1 /* tls.c - Handle tls/ssl. */
3 /* This work is part of OpenLDAP Software <http://www.openldap.org/>.
5 * Copyright 1998-2017 The OpenLDAP Foundation.
8 * Redistribution and use in source and binary forms, with or without
9 * modification, are permitted only as authorized by the OpenLDAP
12 * A copy of this license is available in the file LICENSE in the
13 * top-level directory of the distribution or, alternatively, at
14 * <http://www.OpenLDAP.org/license.html>.
16 /* ACKNOWLEDGEMENTS: restructured by Howard Chu.
20 #include "ldap_config.h"
24 #include <ac/stdlib.h>
26 #include <ac/socket.h>
27 #include <ac/string.h>
30 #include <ac/unistd.h>
32 #include <ac/dirent.h>
40 static tls_impl *tls_imp = &ldap_int_tls_impl;
41 #define HAS_TLS( sb ) ber_sockbuf_ctrl( sb, LBER_SB_OPT_HAS_IO, \
42 (void *)tls_imp->ti_sbio )
46 #define LDAP_USE_NON_BLOCKING_TLS
48 /* RFC2459 minimum required set of supported attribute types
51 typedef struct oid_name {
56 static oid_name oids[] = {
57 { BER_BVC("2.5.4.3"), BER_BVC("cn") },
58 { BER_BVC("2.5.4.4"), BER_BVC("sn") },
59 { BER_BVC("2.5.4.6"), BER_BVC("c") },
60 { BER_BVC("2.5.4.7"), BER_BVC("l") },
61 { BER_BVC("2.5.4.8"), BER_BVC("st") },
62 { BER_BVC("2.5.4.10"), BER_BVC("o") },
63 { BER_BVC("2.5.4.11"), BER_BVC("ou") },
64 { BER_BVC("2.5.4.12"), BER_BVC("title") },
65 { BER_BVC("2.5.4.41"), BER_BVC("name") },
66 { BER_BVC("2.5.4.42"), BER_BVC("givenName") },
67 { BER_BVC("2.5.4.43"), BER_BVC("initials") },
68 { BER_BVC("2.5.4.44"), BER_BVC("generationQualifier") },
69 { BER_BVC("2.5.4.46"), BER_BVC("dnQualifier") },
70 { BER_BVC("1.2.840.113549.1.9.1"), BER_BVC("email") },
71 { BER_BVC("0.9.2342.19200300.100.1.25"), BER_BVC("dc") },
72 { BER_BVNULL, BER_BVNULL }
78 ldap_pvt_tls_ctx_free ( void *c )
81 tls_imp->ti_ctx_free( c );
85 tls_ctx_ref( tls_ctx *ctx )
89 tls_imp->ti_ctx_ref( ctx );
94 * an extra mutex for the default ctx.
96 static ldap_pvt_thread_mutex_t tls_def_ctx_mutex;
100 ldap_int_tls_destroy( struct ldapoptions *lo )
102 if ( lo->ldo_tls_ctx ) {
103 ldap_pvt_tls_ctx_free( lo->ldo_tls_ctx );
104 lo->ldo_tls_ctx = NULL;
107 if ( lo->ldo_tls_certfile ) {
108 LDAP_FREE( lo->ldo_tls_certfile );
109 lo->ldo_tls_certfile = NULL;
111 if ( lo->ldo_tls_keyfile ) {
112 LDAP_FREE( lo->ldo_tls_keyfile );
113 lo->ldo_tls_keyfile = NULL;
115 if ( lo->ldo_tls_dhfile ) {
116 LDAP_FREE( lo->ldo_tls_dhfile );
117 lo->ldo_tls_dhfile = NULL;
119 if ( lo->ldo_tls_ecname ) {
120 LDAP_FREE( lo->ldo_tls_ecname );
121 lo->ldo_tls_ecname = NULL;
123 if ( lo->ldo_tls_cacertfile ) {
124 LDAP_FREE( lo->ldo_tls_cacertfile );
125 lo->ldo_tls_cacertfile = NULL;
127 if ( lo->ldo_tls_cacertdir ) {
128 LDAP_FREE( lo->ldo_tls_cacertdir );
129 lo->ldo_tls_cacertdir = NULL;
131 if ( lo->ldo_tls_ciphersuite ) {
132 LDAP_FREE( lo->ldo_tls_ciphersuite );
133 lo->ldo_tls_ciphersuite = NULL;
135 if ( lo->ldo_tls_crlfile ) {
136 LDAP_FREE( lo->ldo_tls_crlfile );
137 lo->ldo_tls_crlfile = NULL;
142 * Tear down the TLS subsystem. Should only be called once.
145 ldap_pvt_tls_destroy( void )
147 struct ldapoptions *lo = LDAP_INT_GLOBAL_OPT();
149 ldap_int_tls_destroy( lo );
151 tls_imp->ti_tls_destroy();
155 * Initialize a particular TLS implementation.
156 * Called once per implementation.
159 tls_init(tls_impl *impl )
161 static int tls_initialized = 0;
163 if ( !tls_initialized++ ) {
164 #ifdef LDAP_R_COMPILE
165 ldap_pvt_thread_mutex_init( &tls_def_ctx_mutex );
169 if ( impl->ti_inited++ ) return 0;
171 #ifdef LDAP_R_COMPILE
174 return impl->ti_tls_init();
178 * Initialize TLS subsystem. Called once per implementation.
181 ldap_pvt_tls_init( void )
183 return tls_init( tls_imp );
187 * initialize a new TLS context
190 ldap_int_tls_init_ctx( struct ldapoptions *lo, int is_server )
193 tls_impl *ti = tls_imp;
194 struct ldaptls lts = lo->ldo_tls_info;
196 if ( lo->ldo_tls_ctx )
201 if ( is_server && !lts.lt_certfile && !lts.lt_keyfile &&
202 !lts.lt_cacertfile && !lts.lt_cacertdir &&
203 !lts.lt_cacert.bv_val && !lts.lt_cert.bv_val &&
204 !lts.lt_key.bv_val ) {
205 /* minimum configuration not provided */
206 return LDAP_NOT_SUPPORTED;
210 /* This ASCII/EBCDIC handling is a real pain! */
211 if ( lts.lt_ciphersuite ) {
212 lts.lt_ciphersuite = LDAP_STRDUP( lts.lt_ciphersuite );
213 __atoe( lts.lt_ciphersuite );
215 if ( lts.lt_cacertfile ) {
216 lts.lt_cacertfile = LDAP_STRDUP( lts.lt_cacertfile );
217 __atoe( lts.lt_cacertfile );
219 if ( lts.lt_certfile ) {
220 lts.lt_certfile = LDAP_STRDUP( lts.lt_certfile );
221 __atoe( lts.lt_certfile );
223 if ( lts.lt_keyfile ) {
224 lts.lt_keyfile = LDAP_STRDUP( lts.lt_keyfile );
225 __atoe( lts.lt_keyfile );
227 if ( lts.lt_crlfile ) {
228 lts.lt_crlfile = LDAP_STRDUP( lts.lt_crlfile );
229 __atoe( lts.lt_crlfile );
231 if ( lts.lt_cacertdir ) {
232 lts.lt_cacertdir = LDAP_STRDUP( lts.lt_cacertdir );
233 __atoe( lts.lt_cacertdir );
235 if ( lts.lt_dhfile ) {
236 lts.lt_dhfile = LDAP_STRDUP( lts.lt_dhfile );
237 __atoe( lts.lt_dhfile );
239 if ( lts.lt_ecname ) {
240 lts.lt_ecname = LDAP_STRDUP( lts.lt_ecname );
241 __atoe( lts.lt_ecname );
244 lo->ldo_tls_ctx = ti->ti_ctx_new( lo );
245 if ( lo->ldo_tls_ctx == NULL ) {
246 Debug( LDAP_DEBUG_ANY,
247 "TLS: could not allocate default ctx.\n",
253 rc = ti->ti_ctx_init( lo, <s, is_server );
256 if ( rc < 0 && lo->ldo_tls_ctx != NULL ) {
257 ldap_pvt_tls_ctx_free( lo->ldo_tls_ctx );
258 lo->ldo_tls_ctx = NULL;
261 LDAP_FREE( lts.lt_ciphersuite );
262 LDAP_FREE( lts.lt_cacertfile );
263 LDAP_FREE( lts.lt_certfile );
264 LDAP_FREE( lts.lt_keyfile );
265 LDAP_FREE( lts.lt_crlfile );
266 LDAP_FREE( lts.lt_cacertdir );
267 LDAP_FREE( lts.lt_dhfile );
268 LDAP_FREE( lts.lt_ecname );
274 * initialize the default context
277 ldap_pvt_tls_init_def_ctx( int is_server )
279 struct ldapoptions *lo = LDAP_INT_GLOBAL_OPT();
281 LDAP_MUTEX_LOCK( &tls_def_ctx_mutex );
282 rc = ldap_int_tls_init_ctx( lo, is_server );
283 LDAP_MUTEX_UNLOCK( &tls_def_ctx_mutex );
288 alloc_handle( void *ctx_arg, int is_server )
296 struct ldapoptions *lo = LDAP_INT_GLOBAL_OPT();
297 if ( ldap_pvt_tls_init_def_ctx( is_server ) < 0 ) return NULL;
298 ctx = lo->ldo_tls_ctx;
301 ssl = tls_imp->ti_session_new( ctx, is_server );
303 Debug( LDAP_DEBUG_ANY,"TLS: can't create ssl handle.\n",0,0,0);
310 update_flags( Sockbuf *sb, tls_session * ssl, int rc )
312 sb->sb_trans_needs_read = 0;
313 sb->sb_trans_needs_write = 0;
315 return tls_imp->ti_session_upflags( sb, ssl, rc );
319 * Call this to do a TLS connect on a sockbuf. ctx_arg can be
320 * a SSL_CTX * or NULL, in which case the default ctx is used.
324 * 0 - Success. Connection is ready for communication.
325 * <0 - Error. Can't create a TLS stream.
326 * >0 - Partial success.
327 * Do a select (using information from lber_pvt_sb_needs_{read,write}
332 ldap_int_tls_connect( LDAP *ld, LDAPConn *conn )
334 Sockbuf *sb = conn->lconn_sb;
336 tls_session *ssl = NULL;
338 if ( HAS_TLS( sb )) {
339 ber_sockbuf_ctrl( sb, LBER_SB_OPT_GET_SSL, (void *)&ssl );
341 struct ldapoptions *lo;
344 ctx = ld->ld_options.ldo_tls_ctx;
346 ssl = alloc_handle( ctx, 0 );
348 if ( ssl == NULL ) return -1;
351 ber_sockbuf_add_io( sb, &ber_sockbuf_io_debug,
352 LBER_SBIOD_LEVEL_TRANSPORT, (void *)"tls_" );
354 ber_sockbuf_add_io( sb, tls_imp->ti_sbio,
355 LBER_SBIOD_LEVEL_TRANSPORT, (void *)ssl );
357 lo = LDAP_INT_GLOBAL_OPT();
359 ctx = lo->ldo_tls_ctx;
360 ld->ld_options.ldo_tls_ctx = ctx;
363 if ( ld->ld_options.ldo_tls_connect_cb )
364 ld->ld_options.ldo_tls_connect_cb( ld, ssl, ctx,
365 ld->ld_options.ldo_tls_connect_arg );
366 if ( lo && lo->ldo_tls_connect_cb && lo->ldo_tls_connect_cb !=
367 ld->ld_options.ldo_tls_connect_cb )
368 lo->ldo_tls_connect_cb( ld, ssl, ctx, lo->ldo_tls_connect_arg );
371 err = tls_imp->ti_session_connect( ld, ssl );
374 errno = WSAGetLastError();
380 if ( update_flags( sb, ssl, err )) {
384 msg = tls_imp->ti_session_errmsg( ssl, err, buf, sizeof(buf) );
386 if ( ld->ld_error ) {
387 LDAP_FREE( ld->ld_error );
389 ld->ld_error = LDAP_STRDUP( msg );
391 if ( ld->ld_error ) __etoa(ld->ld_error);
395 Debug( LDAP_DEBUG_ANY,"TLS: can't connect: %s.\n",
396 ld->ld_error ? ld->ld_error : "" ,0,0);
398 ber_sockbuf_remove_io( sb, tls_imp->ti_sbio,
399 LBER_SBIOD_LEVEL_TRANSPORT );
401 ber_sockbuf_remove_io( sb, &ber_sockbuf_io_debug,
402 LBER_SBIOD_LEVEL_TRANSPORT );
411 * Call this to do a TLS accept on a sockbuf.
412 * Everything else is the same as with tls_connect.
415 ldap_pvt_tls_accept( Sockbuf *sb, void *ctx_arg )
418 tls_session *ssl = NULL;
420 if ( HAS_TLS( sb )) {
421 ber_sockbuf_ctrl( sb, LBER_SB_OPT_GET_SSL, (void *)&ssl );
423 ssl = alloc_handle( ctx_arg, 1 );
424 if ( ssl == NULL ) return -1;
427 ber_sockbuf_add_io( sb, &ber_sockbuf_io_debug,
428 LBER_SBIOD_LEVEL_TRANSPORT, (void *)"tls_" );
430 ber_sockbuf_add_io( sb, tls_imp->ti_sbio,
431 LBER_SBIOD_LEVEL_TRANSPORT, (void *)ssl );
434 err = tls_imp->ti_session_accept( ssl );
437 errno = WSAGetLastError();
442 if ( update_flags( sb, ssl, err )) return 1;
444 if ( DebugTest( LDAP_DEBUG_ANY ) ) {
446 msg = tls_imp->ti_session_errmsg( ssl, err, buf, sizeof(buf) );
447 Debug( LDAP_DEBUG_ANY,"TLS: can't accept: %s.\n",
448 msg ? msg : "(unknown)", 0, 0 );
451 ber_sockbuf_remove_io( sb, tls_imp->ti_sbio,
452 LBER_SBIOD_LEVEL_TRANSPORT );
454 ber_sockbuf_remove_io( sb, &ber_sockbuf_io_debug,
455 LBER_SBIOD_LEVEL_TRANSPORT );
463 ldap_pvt_tls_inplace ( Sockbuf *sb )
465 return HAS_TLS( sb ) ? 1 : 0;
469 ldap_tls_inplace( LDAP *ld )
473 if ( ld->ld_defconn && ld->ld_defconn->lconn_sb ) {
474 sb = ld->ld_defconn->lconn_sb;
476 } else if ( ld->ld_sb ) {
483 return ldap_pvt_tls_inplace( sb );
487 ldap_pvt_tls_get_peer_dn( void *s, struct berval *dn,
488 LDAPDN_rewrite_dummy *func, unsigned flags )
490 tls_session *session = s;
494 rc = tls_imp->ti_session_peer_dn( session, &bvdn );
497 rc = ldap_X509dn2bv( &bvdn, dn,
498 (LDAPDN_rewrite_func *)func, flags);
503 ldap_pvt_tls_check_hostname( LDAP *ld, void *s, const char *name_in )
505 tls_session *session = s;
507 return tls_imp->ti_session_chkhost( ld, session, name_in );
511 ldap_pvt_tls_config( LDAP *ld, int option, const char *arg )
516 case LDAP_OPT_X_TLS_CACERTFILE:
517 case LDAP_OPT_X_TLS_CACERTDIR:
518 case LDAP_OPT_X_TLS_CERTFILE:
519 case LDAP_OPT_X_TLS_KEYFILE:
520 case LDAP_OPT_X_TLS_RANDOM_FILE:
521 case LDAP_OPT_X_TLS_CIPHER_SUITE:
522 case LDAP_OPT_X_TLS_DHFILE:
523 case LDAP_OPT_X_TLS_CRLFILE: /* GnuTLS only */
524 return ldap_pvt_tls_set_option( ld, option, (void *) arg );
526 case LDAP_OPT_X_TLS_REQUIRE_CERT:
529 if ( strcasecmp( arg, "never" ) == 0 ) {
530 i = LDAP_OPT_X_TLS_NEVER ;
532 } else if ( strcasecmp( arg, "demand" ) == 0 ) {
533 i = LDAP_OPT_X_TLS_DEMAND ;
535 } else if ( strcasecmp( arg, "allow" ) == 0 ) {
536 i = LDAP_OPT_X_TLS_ALLOW ;
538 } else if ( strcasecmp( arg, "try" ) == 0 ) {
539 i = LDAP_OPT_X_TLS_TRY ;
541 } else if ( ( strcasecmp( arg, "hard" ) == 0 ) ||
542 ( strcasecmp( arg, "on" ) == 0 ) ||
543 ( strcasecmp( arg, "yes" ) == 0) ||
544 ( strcasecmp( arg, "true" ) == 0 ) )
546 i = LDAP_OPT_X_TLS_HARD ;
550 return ldap_pvt_tls_set_option( ld, option, &i );
553 case LDAP_OPT_X_TLS_PROTOCOL_MIN: {
556 l = strtol( arg, &next, 10 );
557 if ( l < 0 || l > 0xff || next == arg ||
558 ( *next != '\0' && *next != '.' ) )
563 l = strtol( arg, &next, 10 );
564 if ( l < 0 || l > 0xff || next == arg || *next != '\0' )
568 return ldap_pvt_tls_set_option( ld, option, &i );
570 #ifdef HAVE_OPENSSL_CRL
571 case LDAP_OPT_X_TLS_CRLCHECK: /* OpenSSL only */
573 if ( strcasecmp( arg, "none" ) == 0 ) {
574 i = LDAP_OPT_X_TLS_CRL_NONE ;
575 } else if ( strcasecmp( arg, "peer" ) == 0 ) {
576 i = LDAP_OPT_X_TLS_CRL_PEER ;
577 } else if ( strcasecmp( arg, "all" ) == 0 ) {
578 i = LDAP_OPT_X_TLS_CRL_ALL ;
581 return ldap_pvt_tls_set_option( ld, option, &i );
590 ldap_pvt_tls_get_option( LDAP *ld, int option, void *arg )
592 struct ldapoptions *lo;
594 if( option == LDAP_OPT_X_TLS_PACKAGE ) {
595 *(char **)arg = LDAP_STRDUP( tls_imp->ti_name );
600 assert( LDAP_VALID( ld ) );
602 if( !LDAP_VALID( ld ) ) {
603 return LDAP_OPT_ERROR;
606 lo = &ld->ld_options;
609 /* Get pointer to global option structure */
610 lo = LDAP_INT_GLOBAL_OPT();
612 return LDAP_NO_MEMORY;
618 *(int *)arg = lo->ldo_tls_mode;
620 case LDAP_OPT_X_TLS_CTX:
621 *(void **)arg = lo->ldo_tls_ctx;
622 if ( lo->ldo_tls_ctx ) {
623 tls_ctx_ref( lo->ldo_tls_ctx );
626 case LDAP_OPT_X_TLS_CACERTFILE:
627 *(char **)arg = lo->ldo_tls_cacertfile ?
628 LDAP_STRDUP( lo->ldo_tls_cacertfile ) : NULL;
630 case LDAP_OPT_X_TLS_CACERTDIR:
631 *(char **)arg = lo->ldo_tls_cacertdir ?
632 LDAP_STRDUP( lo->ldo_tls_cacertdir ) : NULL;
634 case LDAP_OPT_X_TLS_CERTFILE:
635 *(char **)arg = lo->ldo_tls_certfile ?
636 LDAP_STRDUP( lo->ldo_tls_certfile ) : NULL;
638 case LDAP_OPT_X_TLS_KEYFILE:
639 *(char **)arg = lo->ldo_tls_keyfile ?
640 LDAP_STRDUP( lo->ldo_tls_keyfile ) : NULL;
642 case LDAP_OPT_X_TLS_DHFILE:
643 *(char **)arg = lo->ldo_tls_dhfile ?
644 LDAP_STRDUP( lo->ldo_tls_dhfile ) : NULL;
646 case LDAP_OPT_X_TLS_ECNAME:
647 *(char **)arg = lo->ldo_tls_ecname ?
648 LDAP_STRDUP( lo->ldo_tls_ecname ) : NULL;
650 case LDAP_OPT_X_TLS_CRLFILE: /* GnuTLS only */
651 *(char **)arg = lo->ldo_tls_crlfile ?
652 LDAP_STRDUP( lo->ldo_tls_crlfile ) : NULL;
654 case LDAP_OPT_X_TLS_REQUIRE_CERT:
655 *(int *)arg = lo->ldo_tls_require_cert;
657 #ifdef HAVE_OPENSSL_CRL
658 case LDAP_OPT_X_TLS_CRLCHECK: /* OpenSSL only */
659 *(int *)arg = lo->ldo_tls_crlcheck;
662 case LDAP_OPT_X_TLS_CIPHER_SUITE:
663 *(char **)arg = lo->ldo_tls_ciphersuite ?
664 LDAP_STRDUP( lo->ldo_tls_ciphersuite ) : NULL;
666 case LDAP_OPT_X_TLS_PROTOCOL_MIN:
667 *(int *)arg = lo->ldo_tls_protocol_min;
669 case LDAP_OPT_X_TLS_RANDOM_FILE:
670 *(char **)arg = lo->ldo_tls_randfile ?
671 LDAP_STRDUP( lo->ldo_tls_randfile ) : NULL;
673 case LDAP_OPT_X_TLS_SSL_CTX: {
676 LDAPConn *conn = ld->ld_defconn;
677 if ( conn != NULL ) {
678 Sockbuf *sb = conn->lconn_sb;
679 retval = ldap_pvt_tls_sb_ctx( sb );
682 *(void **)arg = retval;
685 case LDAP_OPT_X_TLS_CONNECT_CB:
686 *(LDAP_TLS_CONNECT_CB **)arg = lo->ldo_tls_connect_cb;
688 case LDAP_OPT_X_TLS_CONNECT_ARG:
689 *(void **)arg = lo->ldo_tls_connect_arg;
691 case LDAP_OPT_X_TLS_VERSION: {
693 const char *retval = NULL;
695 LDAPConn *conn = ld->ld_defconn;
696 if ( conn != NULL ) {
697 Sockbuf *sb = conn->lconn_sb;
698 sess = ldap_pvt_tls_sb_ctx( sb );
700 retval = ldap_pvt_tls_get_version( sess );
703 *(char **)arg = retval ? LDAP_STRDUP( retval ) : NULL;
706 case LDAP_OPT_X_TLS_CIPHER: {
708 const char *retval = NULL;
710 LDAPConn *conn = ld->ld_defconn;
711 if ( conn != NULL ) {
712 Sockbuf *sb = conn->lconn_sb;
713 sess = ldap_pvt_tls_sb_ctx( sb );
715 retval = ldap_pvt_tls_get_cipher( sess );
718 *(char **)arg = retval ? LDAP_STRDUP( retval ) : NULL;
721 case LDAP_OPT_X_TLS_PEERCERT: {
723 struct berval *bv = arg;
727 LDAPConn *conn = ld->ld_defconn;
728 if ( conn != NULL ) {
729 Sockbuf *sb = conn->lconn_sb;
730 sess = ldap_pvt_tls_sb_ctx( sb );
732 return ldap_pvt_tls_get_peercert( sess, bv );
737 case LDAP_OPT_X_TLS_CACERT: {
738 struct berval *bv = arg;
739 if ( lo->ldo_tls_cacert.bv_val ) {
740 ber_dupbv( bv, &lo->ldo_tls_cacert );
746 case LDAP_OPT_X_TLS_CERT: {
747 struct berval *bv = arg;
748 if ( lo->ldo_tls_cert.bv_val ) {
749 ber_dupbv( bv, &lo->ldo_tls_cert );
755 case LDAP_OPT_X_TLS_KEY: {
756 struct berval *bv = arg;
757 if ( lo->ldo_tls_key.bv_val ) {
758 ber_dupbv( bv, &lo->ldo_tls_key );
772 ldap_pvt_tls_set_option( LDAP *ld, int option, void *arg )
774 struct ldapoptions *lo;
777 assert( LDAP_VALID( ld ) );
779 if( !LDAP_VALID( ld ) ) {
780 return LDAP_OPT_ERROR;
783 lo = &ld->ld_options;
786 /* Get pointer to global option structure */
787 lo = LDAP_INT_GLOBAL_OPT();
789 return LDAP_NO_MEMORY;
795 if ( !arg ) return -1;
797 switch( *(int *) arg ) {
798 case LDAP_OPT_X_TLS_NEVER:
799 case LDAP_OPT_X_TLS_DEMAND:
800 case LDAP_OPT_X_TLS_ALLOW:
801 case LDAP_OPT_X_TLS_TRY:
802 case LDAP_OPT_X_TLS_HARD:
804 lo->ldo_tls_mode = *(int *)arg;
811 case LDAP_OPT_X_TLS_CTX:
812 if ( lo->ldo_tls_ctx )
813 ldap_pvt_tls_ctx_free( lo->ldo_tls_ctx );
814 lo->ldo_tls_ctx = arg;
815 tls_ctx_ref( lo->ldo_tls_ctx );
817 case LDAP_OPT_X_TLS_CONNECT_CB:
818 lo->ldo_tls_connect_cb = (LDAP_TLS_CONNECT_CB *)arg;
820 case LDAP_OPT_X_TLS_CONNECT_ARG:
821 lo->ldo_tls_connect_arg = arg;
823 case LDAP_OPT_X_TLS_CACERTFILE:
824 if ( lo->ldo_tls_cacertfile ) LDAP_FREE( lo->ldo_tls_cacertfile );
825 lo->ldo_tls_cacertfile = arg ? LDAP_STRDUP( (char *) arg ) : NULL;
827 case LDAP_OPT_X_TLS_CACERTDIR:
828 if ( lo->ldo_tls_cacertdir ) LDAP_FREE( lo->ldo_tls_cacertdir );
829 lo->ldo_tls_cacertdir = arg ? LDAP_STRDUP( (char *) arg ) : NULL;
831 case LDAP_OPT_X_TLS_CERTFILE:
832 if ( lo->ldo_tls_certfile ) LDAP_FREE( lo->ldo_tls_certfile );
833 lo->ldo_tls_certfile = arg ? LDAP_STRDUP( (char *) arg ) : NULL;
835 case LDAP_OPT_X_TLS_KEYFILE:
836 if ( lo->ldo_tls_keyfile ) LDAP_FREE( lo->ldo_tls_keyfile );
837 lo->ldo_tls_keyfile = arg ? LDAP_STRDUP( (char *) arg ) : NULL;
839 case LDAP_OPT_X_TLS_DHFILE:
840 if ( lo->ldo_tls_dhfile ) LDAP_FREE( lo->ldo_tls_dhfile );
841 lo->ldo_tls_dhfile = arg ? LDAP_STRDUP( (char *) arg ) : NULL;
843 case LDAP_OPT_X_TLS_ECNAME:
844 if ( lo->ldo_tls_ecname ) LDAP_FREE( lo->ldo_tls_ecname );
845 lo->ldo_tls_ecname = arg ? LDAP_STRDUP( (char *) arg ) : NULL;
847 case LDAP_OPT_X_TLS_CRLFILE: /* GnuTLS only */
848 if ( lo->ldo_tls_crlfile ) LDAP_FREE( lo->ldo_tls_crlfile );
849 lo->ldo_tls_crlfile = arg ? LDAP_STRDUP( (char *) arg ) : NULL;
851 case LDAP_OPT_X_TLS_REQUIRE_CERT:
852 if ( !arg ) return -1;
853 switch( *(int *) arg ) {
854 case LDAP_OPT_X_TLS_NEVER:
855 case LDAP_OPT_X_TLS_DEMAND:
856 case LDAP_OPT_X_TLS_ALLOW:
857 case LDAP_OPT_X_TLS_TRY:
858 case LDAP_OPT_X_TLS_HARD:
859 lo->ldo_tls_require_cert = * (int *) arg;
863 #ifdef HAVE_OPENSSL_CRL
864 case LDAP_OPT_X_TLS_CRLCHECK: /* OpenSSL only */
865 if ( !arg ) return -1;
866 switch( *(int *) arg ) {
867 case LDAP_OPT_X_TLS_CRL_NONE:
868 case LDAP_OPT_X_TLS_CRL_PEER:
869 case LDAP_OPT_X_TLS_CRL_ALL:
870 lo->ldo_tls_crlcheck = * (int *) arg;
875 case LDAP_OPT_X_TLS_CIPHER_SUITE:
876 if ( lo->ldo_tls_ciphersuite ) LDAP_FREE( lo->ldo_tls_ciphersuite );
877 lo->ldo_tls_ciphersuite = arg ? LDAP_STRDUP( (char *) arg ) : NULL;
880 case LDAP_OPT_X_TLS_PROTOCOL_MIN:
881 if ( !arg ) return -1;
882 lo->ldo_tls_protocol_min = *(int *)arg;
884 case LDAP_OPT_X_TLS_RANDOM_FILE:
887 if ( lo->ldo_tls_randfile ) LDAP_FREE (lo->ldo_tls_randfile );
888 lo->ldo_tls_randfile = arg ? LDAP_STRDUP( (char *) arg ) : NULL;
890 case LDAP_OPT_X_TLS_NEWCTX:
891 if ( !arg ) return -1;
892 if ( lo->ldo_tls_ctx )
893 ldap_pvt_tls_ctx_free( lo->ldo_tls_ctx );
894 lo->ldo_tls_ctx = NULL;
895 return ldap_int_tls_init_ctx( lo, *(int *)arg );
896 case LDAP_OPT_X_TLS_CACERT:
897 if ( lo->ldo_tls_cacert.bv_val )
898 LDAP_FREE( lo->ldo_tls_cacert.bv_val );
900 lo->ldo_tls_cacert.bv_len = ((struct berval *)arg)->bv_len;
901 lo->ldo_tls_cacert.bv_val = LDAP_MALLOC( lo->ldo_tls_cacert.bv_len );
902 if ( !lo->ldo_tls_cacert.bv_val )
904 AC_MEMCPY( lo->ldo_tls_cacert.bv_val, ((struct berval *)arg)->bv_val, lo->ldo_tls_cacert.bv_len );
906 BER_BVZERO( &lo->ldo_tls_cacert );
909 case LDAP_OPT_X_TLS_CERT:
910 if ( lo->ldo_tls_cert.bv_val )
911 LDAP_FREE( lo->ldo_tls_cert.bv_val );
913 lo->ldo_tls_cert.bv_len = ((struct berval *)arg)->bv_len;
914 lo->ldo_tls_cert.bv_val = LDAP_MALLOC( lo->ldo_tls_cert.bv_len );
915 if ( !lo->ldo_tls_cert.bv_val )
917 AC_MEMCPY( lo->ldo_tls_cert.bv_val, ((struct berval *)arg)->bv_val, lo->ldo_tls_cert.bv_len );
919 BER_BVZERO( &lo->ldo_tls_cert );
922 case LDAP_OPT_X_TLS_KEY:
923 if ( lo->ldo_tls_key.bv_val )
924 LDAP_FREE( lo->ldo_tls_key.bv_val );
926 lo->ldo_tls_key.bv_len = ((struct berval *)arg)->bv_len;
927 lo->ldo_tls_key.bv_val = LDAP_MALLOC( lo->ldo_tls_key.bv_len );
928 if ( !lo->ldo_tls_key.bv_val )
930 AC_MEMCPY( lo->ldo_tls_key.bv_val, ((struct berval *)arg)->bv_val, lo->ldo_tls_key.bv_len );
932 BER_BVZERO( &lo->ldo_tls_key );
942 ldap_int_tls_start ( LDAP *ld, LDAPConn *conn, LDAPURLDesc *srv )
948 #ifdef LDAP_USE_NON_BLOCKING_TLS
949 struct timeval start_time_tv, tv, tv0;
950 ber_socket_t sd = AC_SOCKET_ERROR;
951 #endif /* LDAP_USE_NON_BLOCKING_TLS */
954 return LDAP_PARAM_ERROR;
958 host = srv->lud_host;
960 host = conn->lconn_server->lud_host;
963 /* avoid NULL host */
968 (void) tls_init( tls_imp );
970 #ifdef LDAP_USE_NON_BLOCKING_TLS
972 * Use non-blocking io during SSL Handshake when a timeout is configured
974 if ( ld->ld_options.ldo_tm_net.tv_sec >= 0 ) {
975 ber_sockbuf_ctrl( ld->ld_sb, LBER_SB_OPT_SET_NONBLOCK, sb );
976 ber_sockbuf_ctrl( sb, LBER_SB_OPT_GET_FD, &sd );
977 tv = ld->ld_options.ldo_tm_net;
979 #ifdef HAVE_GETTIMEOFDAY
980 gettimeofday( &start_time_tv, NULL );
981 #else /* ! HAVE_GETTIMEOFDAY */
982 time( &start_time_tv.tv_sec );
983 start_time_tv.tv_usec = 0;
984 #endif /* ! HAVE_GETTIMEOFDAY */
987 #endif /* LDAP_USE_NON_BLOCKING_TLS */
989 ld->ld_errno = LDAP_SUCCESS;
990 ret = ldap_int_tls_connect( ld, conn );
992 #ifdef LDAP_USE_NON_BLOCKING_TLS
993 while ( ret > 0 ) { /* this should only happen for non-blocking io */
996 if ( sb->sb_trans_needs_read ) {
998 } else if ( sb->sb_trans_needs_write ) {
1001 Debug( LDAP_DEBUG_TRACE, "ldap_int_tls_start: ldap_int_tls_connect needs %s\n",
1002 wr ? "write": "read", 0, 0);
1004 ret = ldap_int_poll( ld, sd, &tv, wr);
1006 ld->ld_errno = LDAP_TIMEOUT;
1009 /* ldap_int_poll called ldap_pvt_ndelay_off */
1010 ber_sockbuf_ctrl( ld->ld_sb, LBER_SB_OPT_SET_NONBLOCK, sb );
1011 ret = ldap_int_tls_connect( ld, conn );
1012 if ( ret > 0 ) { /* need to call tls_connect once more */
1013 struct timeval curr_time_tv, delta_tv;
1015 /* This is mostly copied from result.c:wait4msg(), should
1016 * probably be moved into a separate function */
1017 #ifdef HAVE_GETTIMEOFDAY
1018 gettimeofday( &curr_time_tv, NULL );
1019 #else /* ! HAVE_GETTIMEOFDAY */
1020 time( &curr_time_tv.tv_sec );
1021 curr_time_tv.tv_usec = 0;
1022 #endif /* ! HAVE_GETTIMEOFDAY */
1024 /* delta = curr - start */
1025 delta_tv.tv_sec = curr_time_tv.tv_sec - start_time_tv.tv_sec;
1026 delta_tv.tv_usec = curr_time_tv.tv_usec - start_time_tv.tv_usec;
1027 if ( delta_tv.tv_usec < 0 ) {
1029 delta_tv.tv_usec += 1000000;
1033 if ( ( tv0.tv_sec < delta_tv.tv_sec ) ||
1034 ( ( tv0.tv_sec == delta_tv.tv_sec ) &&
1035 ( tv0.tv_usec < delta_tv.tv_usec ) ) )
1038 ld->ld_errno = LDAP_TIMEOUT;
1041 /* timeout -= delta_time */
1042 tv0.tv_sec -= delta_tv.tv_sec;
1043 tv0.tv_usec -= delta_tv.tv_usec;
1044 if ( tv0.tv_usec < 0 ) {
1046 tv0.tv_usec += 1000000;
1048 start_time_tv.tv_sec = curr_time_tv.tv_sec;
1049 start_time_tv.tv_usec = curr_time_tv.tv_usec;
1052 Debug( LDAP_DEBUG_TRACE, "ldap_int_tls_start: ld %p %ld s %ld us to go\n",
1053 (void *)ld, (long) tv.tv_sec, (long) tv.tv_usec );
1057 if ( ld->ld_options.ldo_tm_net.tv_sec >= 0 ) {
1058 ber_sockbuf_ctrl( ld->ld_sb, LBER_SB_OPT_SET_NONBLOCK, NULL );
1060 #endif /* LDAP_USE_NON_BLOCKING_TLS */
1063 if ( ld->ld_errno == LDAP_SUCCESS )
1064 ld->ld_errno = LDAP_CONNECT_ERROR;
1065 return (ld->ld_errno);
1068 ssl = ldap_pvt_tls_sb_ctx( sb );
1069 assert( ssl != NULL );
1072 * compare host with name(s) in certificate
1074 if (ld->ld_options.ldo_tls_require_cert != LDAP_OPT_X_TLS_NEVER &&
1075 ld->ld_options.ldo_tls_require_cert != LDAP_OPT_X_TLS_ALLOW) {
1076 ld->ld_errno = ldap_pvt_tls_check_hostname( ld, ssl, host );
1077 if (ld->ld_errno != LDAP_SUCCESS) {
1078 return ld->ld_errno;
1082 return LDAP_SUCCESS;
1086 ldap_pvt_tls_sb_ctx( Sockbuf *sb )
1090 ber_sockbuf_ctrl( sb, LBER_SB_OPT_GET_SSL, (void *)&p );
1095 ldap_pvt_tls_get_strength( void *s )
1097 tls_session *session = s;
1099 return tls_imp->ti_session_strength( session );
1103 ldap_pvt_tls_get_my_dn( void *s, struct berval *dn, LDAPDN_rewrite_dummy *func, unsigned flags )
1105 tls_session *session = s;
1106 struct berval der_dn;
1109 rc = tls_imp->ti_session_my_dn( session, &der_dn );
1110 if ( rc == LDAP_SUCCESS )
1111 rc = ldap_X509dn2bv(&der_dn, dn, (LDAPDN_rewrite_func *)func, flags );
1116 ldap_pvt_tls_get_unique( void *s, struct berval *buf, int is_server )
1118 tls_session *session = s;
1119 return tls_imp->ti_session_unique( session, buf, is_server );
1123 ldap_pvt_tls_get_version( void *s )
1125 tls_session *session = s;
1126 return tls_imp->ti_session_version( session );
1130 ldap_pvt_tls_get_cipher( void *s )
1132 tls_session *session = s;
1133 return tls_imp->ti_session_cipher( session );
1137 ldap_pvt_tls_get_peercert( void *s, struct berval *der )
1139 tls_session *session = s;
1140 return tls_imp->ti_session_peercert( session, der );
1142 #endif /* HAVE_TLS */
1145 ldap_start_tls( LDAP *ld,
1146 LDAPControl **serverctrls,
1147 LDAPControl **clientctrls,
1150 return ldap_extended_operation( ld, LDAP_EXOP_START_TLS,
1151 NULL, serverctrls, clientctrls, msgidp );
1155 ldap_install_tls( LDAP *ld )
1158 return LDAP_NOT_SUPPORTED;
1160 if ( ldap_tls_inplace( ld ) ) {
1161 return LDAP_LOCAL_ERROR;
1164 return ldap_int_tls_start( ld, ld->ld_defconn, NULL );
1169 ldap_start_tls_s ( LDAP *ld,
1170 LDAPControl **serverctrls,
1171 LDAPControl **clientctrls )
1174 return LDAP_NOT_SUPPORTED;
1177 char *rspoid = NULL;
1178 struct berval *rspdata = NULL;
1180 /* XXYYZ: this initiates operation only on default connection! */
1182 if ( ldap_tls_inplace( ld ) ) {
1183 return LDAP_LOCAL_ERROR;
1186 rc = ldap_extended_operation_s( ld, LDAP_EXOP_START_TLS,
1187 NULL, serverctrls, clientctrls, &rspoid, &rspdata );
1189 if ( rspoid != NULL ) {
1193 if ( rspdata != NULL ) {
1194 ber_bvfree( rspdata );
1197 if ( rc == LDAP_SUCCESS ) {
1198 rc = ldap_int_tls_start( ld, ld->ld_defconn, NULL );
1205 /* These tags probably all belong in lber.h, but they're
1206 * not normally encountered when processing LDAP, so maybe
1207 * they belong somewhere else instead.
1210 #define LBER_TAG_OID ((ber_tag_t) 0x06UL)
1212 /* Tags for string types used in a DirectoryString.
1214 * Note that IA5string is not one of the defined choices for
1215 * DirectoryString in X.520, but it gets used for email AVAs.
1217 #define LBER_TAG_UTF8 ((ber_tag_t) 0x0cUL)
1218 #define LBER_TAG_PRINTABLE ((ber_tag_t) 0x13UL)
1219 #define LBER_TAG_TELETEX ((ber_tag_t) 0x14UL)
1220 #define LBER_TAG_IA5 ((ber_tag_t) 0x16UL)
1221 #define LBER_TAG_UNIVERSAL ((ber_tag_t) 0x1cUL)
1222 #define LBER_TAG_BMP ((ber_tag_t) 0x1eUL)
1225 find_oid( struct berval *oid )
1229 for ( i=0; !BER_BVISNULL( &oids[i].oid ); i++ ) {
1230 if ( oids[i].oid.bv_len != oid->bv_len ) continue;
1231 if ( !strcmp( oids[i].oid.bv_val, oid->bv_val ))
1237 /* Converts BER Bitstring value to LDAP BitString value (RFC4517)
1242 * berValue and ldapValue should not be NULL
1245 #define BITS_PER_BYTE 8
1246 #define SQUOTE_LENGTH 1
1247 #define B_CHAR_LENGTH 1
1248 #define STR_OVERHEAD (2*SQUOTE_LENGTH + B_CHAR_LENGTH)
1251 der_to_ldap_BitString (struct berval *berValue,
1252 struct berval *ldapValue)
1254 ber_len_t bitPadding=0;
1255 ber_len_t bits, maxBits;
1258 ber_len_t bitLength;
1260 unsigned char* valPtr;
1262 ldapValue->bv_len=0;
1263 ldapValue->bv_val=NULL;
1265 /* Gets padding and points to binary data */
1266 valLen=berValue->bv_len;
1267 valPtr=(unsigned char*)berValue->bv_val;
1269 bitPadding=(ber_len_t)(valPtr[0]);
1273 /* If Block is non DER encoding fixes to DER encoding */
1274 if (bitPadding >= BITS_PER_BYTE) {
1275 if (valLen*BITS_PER_BYTE > bitPadding ) {
1276 valLen-=(bitPadding/BITS_PER_BYTE);
1277 bitPadding%=BITS_PER_BYTE;
1283 /* Just in case bad encoding */
1284 if (valLen*BITS_PER_BYTE < bitPadding ) {
1289 /* Gets buffer to hold RFC4517 Bit String format */
1290 bitLength=valLen*BITS_PER_BYTE-bitPadding;
1291 tmpStr=LDAP_MALLOC(bitLength + STR_OVERHEAD + 1);
1294 return LDAP_NO_MEMORY;
1296 ldapValue->bv_val=tmpStr;
1297 ldapValue->bv_len=bitLength + STR_OVERHEAD;
1299 /* Formatting in '*binary-digit'B format */
1300 maxBits=BITS_PER_BYTE;
1305 maxBits-=bitPadding;
1306 for (bits=0; bits<maxBits; bits++) {
1321 return LDAP_SUCCESS;
1324 /* Convert a structured DN from an X.509 certificate into an LDAPV3 DN.
1325 * x509_name must be raw DER. If func is non-NULL, the
1326 * constructed DN will use numeric OIDs to identify attributeTypes,
1327 * and the func() will be invoked to rewrite the DN with the given
1330 * Otherwise the DN will use shortNames from a hardcoded table.
1333 ldap_X509dn2bv( void *x509_name, struct berval *bv, LDAPDN_rewrite_func *func,
1338 LDAPAVA *newAVA, *baseAVA;
1339 BerElementBuffer berbuf;
1340 BerElement *ber = (BerElement *)&berbuf;
1341 char oids[8192], *oidptr = oids, *oidbuf = NULL;
1343 char *dn_end, *rdn_end;
1344 int i, navas, nrdns, rc = LDAP_SUCCESS;
1345 size_t dnsize, oidrem = sizeof(oids), oidsize = 0;
1351 struct berval Oid, Val, oid2, *in = x509_name;
1353 assert( bv != NULL );
1361 /* A DN is a SEQUENCE of RDNs. An RDN is a SET of AVAs.
1362 * An AVA is a SEQUENCE of attr and value.
1363 * Count the number of AVAs and RDNs
1365 ber_init2( ber, in, LBER_USE_DER );
1366 tag = ber_peek_tag( ber, &len );
1367 if ( tag != LBER_SEQUENCE )
1368 return LDAP_DECODING_ERROR;
1370 for ( tag = ber_first_element( ber, &len, &dn_end );
1372 tag = ber_next_element( ber, &len, dn_end )) {
1374 for ( tag = ber_first_element( ber, &len, &rdn_end );
1375 tag == LBER_SEQUENCE;
1376 tag = ber_next_element( ber, &len, rdn_end )) {
1377 tag = ber_skip_tag( ber, &len );
1378 ber_skip_data( ber, len );
1383 /* Allocate the DN/RDN/AVA stuff as a single block */
1384 dnsize = sizeof(LDAPRDN) * (nrdns+1);
1385 dnsize += sizeof(LDAPAVA *) * (navas+nrdns);
1386 dnsize += sizeof(LDAPAVA) * navas;
1387 if (dnsize > sizeof(ptrs)) {
1388 newDN = (LDAPDN)LDAP_MALLOC( dnsize );
1389 if ( newDN == NULL )
1390 return LDAP_NO_MEMORY;
1392 newDN = (LDAPDN)(char *)ptrs;
1395 newDN[nrdns] = NULL;
1396 newRDN = (LDAPRDN)(newDN + nrdns+1);
1397 newAVA = (LDAPAVA *)(newRDN + navas + nrdns);
1400 /* Rewind and start extracting */
1403 tag = ber_first_element( ber, &len, &dn_end );
1404 for ( i = nrdns - 1; i >= 0; i-- ) {
1407 for ( tag = ber_first_element( ber, &len, &rdn_end );
1408 tag == LBER_SEQUENCE;
1409 tag = ber_next_element( ber, &len, rdn_end )) {
1412 tag = ber_skip_tag( ber, &len );
1413 tag = ber_get_stringbv( ber, &Oid, LBER_BV_NOTERM );
1414 if ( tag != LBER_TAG_OID ) {
1415 rc = LDAP_DECODING_ERROR;
1419 oid2.bv_val = oidptr;
1420 oid2.bv_len = oidrem;
1421 if ( ber_decode_oid( &Oid, &oid2 ) < 0 ) {
1422 rc = LDAP_DECODING_ERROR;
1425 oidname = find_oid( &oid2 );
1427 newAVA->la_attr = oid2;
1428 oidptr += oid2.bv_len + 1;
1429 oidrem -= oid2.bv_len + 1;
1431 /* Running out of OID buffer space? */
1433 if ( oidsize == 0 ) {
1434 oidsize = sizeof(oids) * 2;
1436 oidbuf = LDAP_MALLOC( oidsize );
1437 if ( oidbuf == NULL ) goto nomem;
1441 oidbuf = LDAP_REALLOC( oidbuf, oidsize*2 );
1442 if ( oidbuf == NULL ) goto nomem;
1443 /* Buffer moved! Fix AVA pointers */
1444 if ( old != oidbuf ) {
1446 long dif = oidbuf - old;
1448 for (a=baseAVA; a<=newAVA; a++){
1449 if (a->la_attr.bv_val >= old &&
1450 a->la_attr.bv_val <= (old + oidsize))
1451 a->la_attr.bv_val += dif;
1454 oidptr = oidbuf + oidsize - oidrem;
1461 newAVA->la_attr = oidname->oid;
1463 newAVA->la_attr = oidname->name;
1466 newAVA->la_private = NULL;
1467 newAVA->la_flags = LDAP_AVA_STRING;
1468 tag = ber_get_stringbv( ber, &Val, LBER_BV_NOTERM );
1470 case LBER_TAG_UNIVERSAL:
1471 /* This uses 32-bit ISO 10646-1 */
1472 csize = 4; goto to_utf8;
1474 /* This uses 16-bit ISO 10646-1 */
1475 csize = 2; goto to_utf8;
1476 case LBER_TAG_TELETEX:
1477 /* This uses 8-bit, assume ISO 8859-1 */
1479 to_utf8: rc = ldap_ucs_to_utf8s( &Val, csize, &newAVA->la_value );
1480 newAVA->la_flags |= LDAP_AVA_NONPRINTABLE;
1482 newAVA->la_flags |= LDAP_AVA_FREE_VALUE;
1483 if (rc != LDAP_SUCCESS) goto nomem;
1486 newAVA->la_flags |= LDAP_AVA_NONPRINTABLE;
1487 /* This is already in UTF-8 encoding */
1489 case LBER_TAG_PRINTABLE:
1490 /* These are always 7-bit strings */
1491 newAVA->la_value = Val;
1493 case LBER_BITSTRING:
1494 /* X.690 bitString value converted to RFC4517 Bit String */
1495 rc = der_to_ldap_BitString( &Val, &newAVA->la_value );
1498 /* Not a string type at all */
1499 newAVA->la_flags = 0;
1500 newAVA->la_value = Val;
1506 tag = ber_next_element( ber, &len, dn_end );
1510 rc = func( newDN, flags, NULL );
1511 if ( rc != LDAP_SUCCESS )
1515 rc = ldap_dn2bv_x( newDN, bv, LDAP_DN_FORMAT_LDAPV3, NULL );
1518 for (;baseAVA < newAVA; baseAVA++) {
1519 if (baseAVA->la_flags & LDAP_AVA_FREE_ATTR)
1520 LDAP_FREE( baseAVA->la_attr.bv_val );
1521 if (baseAVA->la_flags & LDAP_AVA_FREE_VALUE)
1522 LDAP_FREE( baseAVA->la_value.bv_val );
1526 LDAP_FREE( oidbuf );
1527 if ( newDN != (LDAPDN)(char *) ptrs )