document all options, including TLS and (not yet complete) SASL. Needs expert review

This commit is contained in:
Pierangelo Masarati 2009-08-19 19:00:48 +00:00
parent 4b6f2de8ab
commit d36829a1ab

View File

@ -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 "char *" ;
the library duplicates the corresponding string.
.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 .
.BR outvalue
must be a
.BR "Sockbuf **" .
This is a read-only, handler-specific option.
.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 "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_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 "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.
.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
.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_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_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.
.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.
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
.B LDAP_OPT_X_TLS_CTX
Sets/gets the OpenSSL CTX.
.TP
.B LDAP_OPT_X_TLS_CACERTFILE
Sets/gets the full-path CA certificate file.
.TP
.B LDAP_OPT_X_TLS_CACERTDIR
Sets/gets the path of the directory containing CA certificates.
.TP
.B LDAP_OPT_X_TLS_CERTFILE
Sets/gets the full-path certificate file.
.TP
.B LDAP_OPT_X_TLS_KEYFILE
Sets/gets the full-path certificate key file.
.TP
.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
.BR invalue
must be a
.BR "int *" .
.I /dev/urandom
are not available.
Ignored by GNUtls.
.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_SSL_CTX
Sets/gets the OpenSSL SSL CTX.
.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_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_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_CONNECT_CB
Sets/gets the connection callback.
Currently not implemented.
.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_CONNECT_ARG
Sets/gets the connection callback argument.
Currently not implemented.
.TP
.B LDAP_OPT_DEBUG_LEVEL
Sets/gets the debug level of the client library.
Both
.BR outvalue
and
.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),