From d36829a1abbfc98ce39c90c26aaccb6fc500a39e Mon Sep 17 00:00:00 2001 From: Pierangelo Masarati Date: Wed, 19 Aug 2009 19:00:48 +0000 Subject: [PATCH] document all options, including TLS and (not yet complete) SASL. Needs expert review --- doc/man/man3/ldap_get_option.3 | 492 +++++++++++++++++++++++---------- 1 file changed, 341 insertions(+), 151 deletions(-) diff --git a/doc/man/man3/ldap_get_option.3 b/doc/man/man3/ldap_get_option.3 index a9631db4c8..d4da8abafb 100644 --- a/doc/man/man3/ldap_get_option.3 +++ b/doc/man/man3/ldap_get_option.3 @@ -29,6 +29,15 @@ The actual type is determined based on the value of the argument. Global options are set/retrieved by passing a NULL LDAP handle. .TP +.B LDAP_OPT_API_FEATURE_INFO +Fills-in a +.BR "LDAPAPIFeatureInfo" ; +.BR outvalue +must be a +.BR "LDAPAPIFeatureInfo *" , +pointing to an already allocated struct. +This is a read-only option. +.TP .B LDAP_OPT_API_INFO Fills-in a .BR "struct ldapapiinfo" ; @@ -38,6 +47,110 @@ must be a pointing to an already allocated struct. This is a read-only option. .TP +.B LDAP_OPT_CLIENT_CONTROLS +Sets/gets the client-side controls to be used for all operations. +This is now deprecated as modern LDAP C API provides replacements +for all main operations which accepts client-side controls as +explicit arguments; see for example +.BR ldap_search_ext (3), +.BR ldap_add_ext (3), +.BR ldap_modify_ext (3) +and so on. +.BR outvalue +must be +.BR "LDAPControl ***" , +and the caller is responsible of freeing the returned controls, if any, +by calling +.BR ldap_controls_free (3), +while +.BR invalue +must be +.BR "LDAPControl **" ; +the library duplicates the controls passed via +.BR invalue . +.TP +.B LDAP_OPT_CONNECT_ASYNC +Sets/gets the status of the asynchronous connect flag. +The value should either be +.BR LDAP_OPT_OFF +or +.BR LDAP_OPT_ON . +When set, the library will call +.BR connect (2) +and return, without waiting for response. +This leaves the handler in a connecting state. +Subsequent calls to library routines will poll for completion +of the connect before performing further operations. +As a consequence, library calls that need to establish a connection +with a DSA do not block even for the network timeout +(option +.BR LDAP_OPT_NETWORK_TIMEOUT ). +This option is OpenLDAP specific. +.TP +.B LDAP_OPT_CONNECT_CB +This option allows to set a connect callback. +The +.B invalue +must be a pointer to a +.IR "struct ldap_conncb" . +Callbacks are executed in last in-first served order. +Hanlder-specific callbacks are executed first, followed by global ones. +Right before freeing the callback structure, the +.I lc_del +callback handler is passed a +.B NULL +.IR Sockbuf . +Calling +.BR ldap_get_option (3) +for this option removes the callback whose pointer matches +.BR outvalue . +This option is OpenLDAP specific. +.TP +.B LDAP_OPT_DEBUG_LEVEL +Sets/gets the debug level of the client library. +Both +.BR outvalue +and +.BR invalue +must be a +.BR "int *" . +This option is OpenLDAP specific. +.TP +.B LDAP_OPT_DEFBASE +Sets/gets a string containing the DN to be used as default base +for search operations. +.BR outvalue +must be a +.BR "char **" , +and the caller is responsible of freeing the returned string by calling +.BR ldap_memfree (3), +while +.BR invalue +must be a +.BR "char *" ; +the library duplicates the corresponding string. +This option is OpenLDAP specific. +.TP +.B LDAP_OPT_DEREF +Sets/gets the value that defines when alias dereferencing must occur. +.BR outvalue +and +.BR invalue +must be +.BR "int *" , +and they cannot be NULL. +The value of +.BR *invalue +should be one of +.BR LDAP_DEREF_NEVER +(the default), +.BR LDAP_DEREF_SEARCHING , +.BR LDAP_DEREF_FINDING , +or +.BR LDAP_DEREF_ALWAYS . +Note that this has ever been the only means to determine alias dereferencing +within search operations. +.TP .B LDAP_OPT_DESC Returns the file descriptor associated to the socket buffer of the LDAP handle passed in as @@ -47,27 +160,49 @@ must be a .BR "int *" . This is a read-only, handler-specific option. .TP -.B LDAP_OPT_SOCKBUF -Returns a pointer to the socket buffer of the LDAP handle passed in as -.BR ld ; +.B LDAP_OPT_DIAGNOSTIC_MESSAGE +Sets/gets a string containing the error string associated to the LDAP handle. +This option was formerly known as +.BR LDAP_OPT_ERROR_STRING . .BR outvalue +must be a +.BR "char **" , +and the caller is responsible of freeing the returned string by calling +.BR ldap_memfree (3), +while +.BR invalue must be a -.BR "Sockbuf **" . -This is a read-only, handler-specific option. +.BR "char *" ; +the library duplicates the corresponding string. .TP -.B LDAP_OPT_TIMEOUT -Sets/gets a timeout value for the synchronous API calls. -.B outvalue +.B LDAP_OPT_HOST_NAME +Sets/gets a space-separated list of hosts to be contacted by the library +when trying to establish a connection. +This is now deprecated in favor of +.BR LDAP_OPT_URI . +.BR outvalue must be a -.BR "struct timeval **" -(the caller has to free -.BR *outvalue ) , -and -.B invalue +.BR "char **" , +and the caller is responsible of freeing the resulting string by calling +.BR ldap_memfree (3), +while +.BR invalue must be a -.BR "struct timeval *" , -and they cannot be NULL. Using a struct with seconds set to \-1 results -in an infinite timeout, which is the default. +.BR "char *" ; +the library duplicates the corresponding string. +.TP +.B LDAP_OPT_MATCHED_DN +Sets/gets a string containing the matched DN associated to the LDAP handle. +.BR outvalue +must be a +.BR "char **" , +and the caller is responsible of freeing the returned string by calling +.BR ldap_memfree (3), +while +.BR invalue +must be a +.BR "char *" ; +the library duplicates the corresponding string. .TP .B LDAP_OPT_NETWORK_TIMEOUT Sets/gets the network timeout value after which @@ -86,35 +221,29 @@ must be a .BR "struct timeval *" , and they cannot be NULL. Using a struct with seconds set to \-1 results in an infinite timeout, which is the default. +This option is OpenLDAP specific. .TP -.B LDAP_OPT_DEREF -Sets/gets the value that defines when alias dereferencing must occur. -.BR outvalue -and -.BR invalue -must be -.BR "int *" , -and they cannot be NULL. -.TP -.B LDAP_OPT_SIZELIMIT -Sets/gets the value that defines the maximum number of entries -to be returned by a search operation. -.BR outvalue -and +.B LDAP_OPT_PROTOCOL_VERSION +Sets/gets the protocol version. +.BR outvalue +and .BR invalue -must be -.BR "int *" , -and they cannot be NULL. +must be +.BR "int *" . .TP -.B LDAP_OPT_TIMELIMIT -Sets/gets the value that defines the time limit after which -a search operation should be terminated by the server. -.BR outvalue -and +.B LDAP_OPT_REFERRAL_URLS +Sets/gets an array containing the referral URIs associated to the LDAP handle. +.BR outvalue +must be a +.BR "char ***" , +and the caller is responsible of freeing the returned string by calling +.BR ber_memvfree (3), +while .BR invalue -must be -.BR "int *" , -and they cannot be NULL. +must be a NULL-terminated +.BR "char **" ; +the library duplicates the corresponding string. +This option is OpenLDAP specific. .TP .B LDAP_OPT_REFERRALS Determines whether the library should implicitly chase referrals or not. @@ -128,6 +257,10 @@ their value should either be or .BR LDAP_OPT_ON . .TP +.B LDAP_OPT_REFHOPLIMIT +This option is OpenLDAP specific. +It is not currently implemented. +.TP .B LDAP_OPT_RESTART Determines whether the library should implicitly restart connections (FIXME). .BR outvalue @@ -140,12 +273,15 @@ their value should either be or .BR LDAP_OPT_ON . .TP -.B LDAP_OPT_PROTOCOL_VERSION -Sets/gets the protocol version. +.B LDAP_OPT_RESULT_CODE +Sets/gets the LDAP result code associated to the handle. +This option was formerly known as +.BR LDAP_OPT_ERROR_NUMBER . +Both .BR outvalue and .BR invalue -must be +must be a .BR "int *" . .TP .B LDAP_OPT_SERVER_CONTROLS @@ -170,46 +306,52 @@ must be the library duplicates the controls passed via .BR invalue . .TP -.B LDAP_OPT_CLIENT_CONTROLS -Sets/gets the client-side controls to be used for all operations. -This is now deprecated as modern LDAP C API provides replacements -for all main operations which accepts client-side controls as -explicit arguments; see for example -.BR ldap_search_ext (3), -.BR ldap_add_ext (3), -.BR ldap_modify_ext (3) -and so on. -.BR outvalue -must be -.BR "LDAPControl ***" , -and the caller is responsible of freeing the returned controls, if any, -by calling -.BR ldap_controls_free (3), -while +.B LDAP_OPT_SIZELIMIT +Sets/gets the value that defines the maximum number of entries +to be returned by a search operation. +.BR outvalue +and .BR invalue -must be -.BR "LDAPControl **" ; -the library duplicates the controls passed via -.BR invalue . +must be +.BR "int *" , +and they cannot be NULL. .TP -.B LDAP_OPT_HOST_NAME -Sets/gets a space-separated list of hosts to be contacted by the library -when trying to establish a connection. -This is now deprecated in favor of -.BR LDAP_OPT_URI . +.B LDAP_OPT_SOCKBUF +Returns a pointer to the socket buffer of the LDAP handle passed in as +.BR ld ; .BR outvalue must be a -.BR "char **" , -and the caller is responsible of freeing the resulting string by calling -.BR ldap_memfree (3), -while +.BR "Sockbuf **" . +This is a read-only, handler-specific option. +This option is OpenLDAP specific. +.TP +.B LDAP_OPT_TIMELIMIT +Sets/gets the value that defines the time limit after which +a search operation should be terminated by the server. +.BR outvalue +and .BR invalue +must be +.BR "int *" , +and they cannot be NULL. +.TP +.B LDAP_OPT_TIMEOUT +Sets/gets a timeout value for the synchronous API calls. +.B outvalue must be a -.BR "char *" ; -the library duplicates the corresponding string. +.BR "struct timeval **" +(the caller has to free +.BR *outvalue ) , +and +.B invalue +must be a +.BR "struct timeval *" , +and they cannot be NULL. Using a struct with seconds set to \-1 results +in an infinite timeout, which is the default. +This option is OpenLDAP specific. .TP .B LDAP_OPT_URI -Sets/gets a space-separated list of URIs to be contacted by the library +Sets/gets a comma- or space-separated list of URIs to be contacted by the library when trying to establish a connection. .BR outvalue must be a @@ -225,90 +367,128 @@ the library parses the string into a list of structures, so the invocation of .BR ldap_set_option (3) may fail if URL parsing fails. +URIs may only contain the +.BR schema , +the +.BR host , +and the +.BR port +fields. +This option is OpenLDAP specific. +.SH TLS OPTIONS +The TLS options are OpenLDAP specific. .TP -.B LDAP_OPT_DEFBASE -Sets/gets a string containing the DN to be used as default base -for search operations. -.BR outvalue -must be a -.BR "char **" , -and the caller is responsible of freeing the returned string by calling -.BR ldap_memfree (3), -while -.BR invalue -must be a -.BR "char *" ; -the library duplicates the corresponding string. +.B LDAP_OPT_X_TLS +Sets/gets the TLS mode, one of +.BR LDAP_OPT_X_TLS_NEVER , +.BR LDAP_OPT_X_TLS_HARD , +.BR LDAP_OPT_X_TLS_DEMAND , +.BR LDAP_OPT_X_TLS_ALLOW , +.BR LDAP_OPT_X_TLS_TRY . .TP -.B LDAP_OPT_RESULT_CODE -Sets/gets the LDAP result code associated to the handle. -This option was formerly known as -.BR LDAP_OPT_ERROR_NUMBER . -Both -.BR outvalue -and -.BR invalue -must be a -.BR "int *" . +.B LDAP_OPT_X_TLS_CTX +Sets/gets the OpenSSL CTX. .TP -.B LDAP_OPT_DIAGNOSTIC_MESSAGE -Sets/gets a string containing the error string associated to the LDAP handle. -This option was formerly known as -.BR LDAP_OPT_ERROR_STRING . -.BR outvalue -must be a -.BR "char **" , -and the caller is responsible of freeing the returned string by calling -.BR ldap_memfree (3), -while -.BR invalue -must be a -.BR "char *" ; -the library duplicates the corresponding string. +.B LDAP_OPT_X_TLS_CACERTFILE +Sets/gets the full-path CA certificate file. .TP -.B LDAP_OPT_MATCHED_DN -Sets/gets a string containing the matched DN associated to the LDAP handle. -.BR outvalue -must be a -.BR "char **" , -and the caller is responsible of freeing the returned string by calling -.BR ldap_memfree (3), -while -.BR invalue -must be a -.BR "char *" ; -the library duplicates the corresponding string. +.B LDAP_OPT_X_TLS_CACERTDIR +Sets/gets the path of the directory containing CA certificates. .TP -.B LDAP_OPT_REFERRAL_URLS -Sets/gets an array containing the referral URIs associated to the LDAP handle. -.BR outvalue -must be a -.BR "char ***" , -and the caller is responsible of freeing the returned string by calling -.BR ber_memvfree (3), -while -.BR invalue -must be a NULL-terminated -.BR "char **" ; -the library duplicates the corresponding string. +.B LDAP_OPT_X_TLS_CERTFILE +Sets/gets the full-path certificate file. .TP -.B LDAP_OPT_API_FEATURE_INFO -Fills-in a -.BR "LDAPAPIFeatureInfo" ; -.BR outvalue -must be a -.BR "LDAPAPIFeatureInfo *" , -pointing to an already allocated struct. -This is a read-only option. +.B LDAP_OPT_X_TLS_KEYFILE +Sets/gets the full-path certificate key file. .TP -.B LDAP_OPT_DEBUG_LEVEL -Sets/gets the debug level of the client library. -Both -.BR outvalue +.B LDAP_OPT_X_TLS_REQUIRE_CERT +Sets/gets the peer certificate checking strategy, +one of +.BR LDAP_OPT_X_TLS_NEVER , +.BR LDAP_OPT_X_TLS_HARD , +.BR LDAP_OPT_X_TLS_DEMAND , +.BR LDAP_OPT_X_TLS_ALLOW , +.BR LDAP_OPT_X_TLS_TRY . +.TP +.B LDAP_OPT_X_TLS_PROTOCOL_MIN +Sets/gets the minimum protocol version. +.TP +.B LDAP_OPT_X_TLS_CIPHER_SUITE +Sets/gets the allowed cipher suite. +.TP +.B LDAP_OPT_X_TLS_RANDOM_FILE +Sets/gets the random file when +.I /dev/random and +.I /dev/urandom +are not available. +Ignored by GNUtls. +.TP +.B LDAP_OPT_X_TLS_SSL_CTX +Sets/gets the OpenSSL SSL CTX. +.TP +.B LDAP_OPT_X_TLS_CRLCHECK +Sets/gets the CRL evaluation strategy, one of +.BR LDAP_OPT_X_TLS_CRL_NONE , +.BR LDAP_OPT_X_TLS_CRL_PEER , +or +.BR LDAP_OPT_X_TLS_CRL_ALL . +Requires OpenSSL. +.TP +.B LDAP_OPT_X_TLS_CONNECT_CB +Sets/gets the connection callback. +Currently not implemented. +.TP +.B LDAP_OPT_X_TLS_CONNECT_ARG +Sets/gets the connection callback argument. +Currently not implemented. +.TP +.B LDAP_OPT_X_TLS_DHFILE +Gets/sets the full-path of the file containing the parameters +for Diffie-Hellman ephemeral key exchange. +Ignored by GNUtls. +.TP +.B LDAP_OPT_X_TLS_NEWCTX +Instructs the library to create a new TLS CTX. +A non-zero .BR invalue -must be a -.BR "int *" . +tells the library to create a CTX for a server. +.TP +.B LDAP_OPT_X_TLS_CRLFILE +Sets/gets the full-path of the CRL file. +This option is only valid for GNUtls. +.SH SASL OPTIONS +.TP +.B LDAP_OPT_X_SASL_MECH +.TP +.B LDAP_OPT_X_SASL_REALM +.TP +.B LDAP_OPT_X_SASL_AUTHCID +.TP +.B LDAP_OPT_X_SASL_AUTHZID +.TP +.B LDAP_OPT_X_SASL_SSF +read-only +.TP +.B LDAP_OPT_X_SASL_SSF_EXTERNAL +write-only +.TP +.B LDAP_OPT_X_SASL_SECPROPS +write-only +.TP +.B LDAP_OPT_X_SASL_SSF_MIN +.TP +.B LDAP_OPT_X_SASL_SSF_MAX +.TP +.B LDAP_OPT_X_SASL_MAXBUFSIZE +.TP +.B LDAP_OPT_X_SASL_MECHLIST +read-only +.TP +.B LDAP_OPT_X_SASL_NOCANON +.TP +.B LDAP_OPT_X_SASL_USERNAME +read-only .SH ERRORS On success, the functions return .BR LDAP_OPT_SUCCESS , @@ -328,6 +508,16 @@ Application developers are encouraged to either implement consistent referral chasing features, or explicitly disable referral chasing by setting that option to .BR LDAP_OPT_OFF . +.P +The protocol version used by the library defaults to LDAPv2 (now historic), +which corresponds to the +.B LDAP_VERSION2 +macro. +Application developers are encouraged to explicitly set +.B LDAP_OPT_PROTOCOL_VERSION +to LDAPv3, using the +.B LDAP_VERSION3 +macro, or to allow users to select the protocol version. .SH SEE ALSO .BR ldap (3), .BR ldap_error (3), -- 2.39.5