Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
LDAP_GET_OPTION(3)	   Library Functions Manual	    LDAP_GET_OPTION(3)

NAME
       ldap_get_option,	ldap_set_option	- LDAP option handling routines

LIBRARY
       OpenLDAP	LDAP (libldap, -lldap)

SYNOPSIS
       #include	<ldap.h>

       int ldap_get_option(LDAP	*ld, int option, void *outvalue);

       int ldap_set_option(LDAP	*ld, int option, const void *invalue);

DESCRIPTION
       These routines provide access to	options	stored either in a LDAP	handle
       or as global options, where applicable.	They make use of a neutral in-
       terface,	 where	the type of the	value either retrieved by ldap_get_op-
       tion(3) or set by ldap_set_option(3) is cast to	void  *.   The	actual
       type  is	 determined based on the value of the option argument.	Global
       options are set/retrieved by passing a NULL LDAP	handle.	 LDAP  handles
       inherit their default settings from the global options in effect	at the
       time the	handle is created.

       LDAP_OPT_API_FEATURE_INFO
	      Fills-in a LDAPAPIFeatureInfo; outvalue must  be	a  LDAPAPIFea-
	      tureInfo	*,  pointing to	an already allocated struct.  The lda-
	      paif_info_version	field of the struct  must  be  initialized  to
	      LDAP_FEATURE_INFO_VERSION	 before	 making	 the  call.  The  lda-
	      paif_name	field must be set to the name of a feature  to	query.
	      This is a	read-only option.

       LDAP_OPT_API_INFO
	      Fills-in a LDAPAPIInfo; outvalue must be a LDAPAPIInfo *,	point-
	      ing to an	 already  allocated  struct.  The  ldapai_info_version
	      field of the struct must be initialized to LDAP_API_INFO_VERSION
	      before making the	call.  If the version passed in	does not match
	      the current library version, the expected	version	number will be
	      stored in	the struct and the call	will fail.  The	caller is  re-
	      sponsible	 for freeing the elements of the ldapai_extensions ar-
	      ray and the array	itself using ldap_memfree(3).  The caller must
	      also free	the ldapi_vendor_name.	This is	a read-only option.

       LDAP_OPT_CLIENT_CONTROLS
	      Sets/gets	 the  client-side  controls  to	be used	for all	opera-
	      tions.  This is now deprecated as	modern LDAP C API provides re-
	      placements  for  all  main  operations which accepts client-side
	      controls	 as    explicit	   arguments;	 see	for    example
	      ldap_search_ext(3),  ldap_add_ext(3),  ldap_modify_ext(3)	and so
	      on.  outvalue must be LDAPControl	***, and the caller is respon-
	      sible  of	 freeing  the  returned	 controls,  if any, by calling
	      ldap_controls_free(3), while invalue must	be LDAPControl	*const
	      *; the library duplicates	the controls passed via	invalue.

       LDAP_OPT_CONNECT_ASYNC
	      Sets/gets	 the status of the asynchronous	connect	flag.  invalue
	      should either be LDAP_OPT_OFF or LDAP_OPT_ON; outvalue  must  be
	      int  *.	When set, the library will call	connect(2) and return,
	      without waiting for response.  This leaves the handle in a  con-
	      necting  state.	Subsequent calls to library routines will poll
	      for completion of	the connect before performing  further	opera-
	      tions.  As a consequence,	library	calls that need	to establish a
	      connection with a	DSA do not block even for the network  timeout
	      (option LDAP_OPT_NETWORK_TIMEOUT).  This option is OpenLDAP spe-
	      cific.

       LDAP_OPT_CONNECT_CB
	      This option allows to set	a connect callback.  invalue must be a
	      const  struct ldap_conncb	*.  Callbacks are executed in last in-
	      first served  order.   Handle-specific  callbacks	 are  executed
	      first,  followed by global ones.	Right before freeing the call-
	      back structure, the lc_del callback handler  is  passed  a  NULL
	      Sockbuf.	Calling	ldap_get_option(3) for this option removes the
	      callback whose pointer matches outvalue.	This option is	OpenL-
	      DAP specific.

       LDAP_OPT_DEBUG_LEVEL
	      Sets/gets	 the  debug level of the client	library.  invalue must
	      be a const int *;	outvalue must be a int *.  Valid debug	levels
	      are  LDAP_DEBUG_ANY,  LDAP_DEBUG_ARGS,  LDAP_DEBUG_BER, LDAP_DE-
	      BUG_CONNS,   LDAP_DEBUG_NONE,    LDAP_DEBUG_PACKETS,    LDAP_DE-
	      BUG_PARSE,  and  LDAP_DEBUG_TRACE.  This option is OpenLDAP spe-
	      cific.

       LDAP_OPT_DEFBASE
	      Sets/gets	a string containing the	DN to be used as default  base
	      for  search  operations.	 outvalue  must	 be a char **, and the
	      caller is	responsible of freeing the returned string by  calling
	      ldap_memfree(3),	while  invalue must be a const char *; the li-
	      brary duplicates	the  corresponding  string.   This  option  is
	      OpenLDAP specific.

       LDAP_OPT_DEREF
	      Sets/gets	 the  value that defines when alias dereferencing must
	      occur.  invalue must be const int	*; outvalue  must  be  int  *.
	      They  cannot  be	NULL.	The value of *invalue should be	one of
	      LDAP_DEREF_NEVER	  (the	   default),	 LDAP_DEREF_SEARCHING,
	      LDAP_DEREF_FINDING,  or  LDAP_DEREF_ALWAYS.   Note that this has
	      ever been	the only means to determine alias dereferencing	within
	      search operations.

       LDAP_OPT_DESC
	      Returns  the  file descriptor associated to the socket buffer of
	      the LDAP handle passed in	as ld; outvalue	must be	a int *.  This
	      is a read-only, handle-specific option.

       LDAP_OPT_DIAGNOSTIC_MESSAGE
	      Sets/gets	a string containing the	error string associated	to the
	      LDAP handle.  This option	was  formerly  known  as  LDAP_OPT_ER-
	      ROR_STRING.   outvalue  must be a	char **, and the caller	is re-
	      sponsible	of freeing the returned	string	by  calling  ldap_mem-
	      free(3),	while invalue must be a	char *;	the library duplicates
	      the corresponding	string.

       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 dep-
	      recated in favor of LDAP_OPT_URI.	 outvalue must be a  char  **,
	      and the caller is	responsible of freeing the resulting string by
	      calling ldap_memfree(3), while invalue must be a const  char  *;
	      the library duplicates the corresponding string.

       LDAP_OPT_MATCHED_DN
	      Sets/gets	 a  string containing the matched DN associated	to the
	      LDAP handle.  outvalue must be a char **,	and the	caller is  re-
	      sponsible	 of  freeing  the returned string by calling ldap_mem-
	      free(3), while invalue must be a const char *; the  library  du-
	      plicates the corresponding string.

       LDAP_OPT_NETWORK_TIMEOUT
	      Sets/gets	 the  network  timeout	value  after which poll(2)/se-
	      lect(2) following	a connect(2) returns in	case of	 no  activity.
	      outvalue	must  be  a  struct timeval ** (the caller has to free
	      *outvalue), and invalue must be a	const struct timeval *.	  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.

       LDAP_OPT_PROTOCOL_VERSION
	      Sets/gets	 the  protocol	version.  outvalue and invalue must be
	      int *.

       LDAP_OPT_REFERRAL_URLS
	      Sets/gets	an array containing the	referral  URIs	associated  to
	      the LDAP handle.	outvalue must be a char	***, and the caller is
	      responsible  of  freeing	the   returned	 string	  by   calling
	      ldap_memvfree(3),	 while	invalue	must be	a NULL-terminated char
	      *const *;	the library duplicates the corresponding string.  This
	      option is	OpenLDAP specific.

       LDAP_OPT_REFERRALS
	      Determines whether the library should implicitly chase referrals
	      or not.  invalue must be const int *; its	value should either be
	      LDAP_OPT_OFF or LDAP_OPT_ON.  outvalue must be int *.

       LDAP_OPT_RESTART
	      Determines whether the library should implicitly restart connec-
	      tions (FIXME).  invalue must be const int	*;  its	 value	should
	      either be	LDAP_OPT_OFF or	LDAP_OPT_ON.  outvalue must be int *.

       LDAP_OPT_RESULT_CODE
	      Sets/gets	 the  LDAP result code associated to the handle.  This
	      option was formerly  known  as  LDAP_OPT_ERROR_NUMBER.   invalue
	      must be a	const int *.  outvalue must be a int *.

       LDAP_OPT_SERVER_CONTROLS
	      Sets/gets	 the  server-side  controls  to	be used	for all	opera-
	      tions.  This is now deprecated as	modern LDAP C API provides re-
	      placements  for  all  main  operations which accepts server-side
	      controls	 as    explicit	   arguments;	 see	for    example
	      ldap_search_ext(3),  ldap_add_ext(3),  ldap_modify_ext(3)	and so
	      on.  outvalue must be LDAPControl	***, and the caller is respon-
	      sible  of	 freeing  the  returned	 controls,  if any, by calling
	      ldap_controls_free(3), while invalue must	be LDAPControl	*const
	      *; the library duplicates	the controls passed via	invalue.

       LDAP_OPT_SESSION_REFCNT
	      Returns  the  reference  count  associated  with the LDAP	handle
	      passed in	as ld; outvalue	must be	a int *.  This is a read-only,
	      handle-specific option.  This option is OpenLDAP specific.

       LDAP_OPT_SIZELIMIT
	      Sets/gets	 the  value that defines the maximum number of entries
	      to be returned by	a search operation.  invalue must be const int
	      *, while outvalue	must be	int *; They cannot be NULL.

       LDAP_OPT_SOCKBUF
	      Returns a	pointer	to the socket buffer of	the LDAP handle	passed
	      in as ld;	outvalue must be a Sockbuf **.	This is	 a  read-only,
	      handle-specific option.  This option is OpenLDAP specific.

       LDAP_OPT_TIMELIMIT
	      Sets/gets	 the  value  that defines the time limit after which a
	      search operation should be terminated by	the  server.   invalue
	      must be const int	*, while outvalue must be int *, and they can-
	      not be NULL.

       LDAP_OPT_TIMEOUT
	      Sets/gets	a timeout value	for the	synchronous API	 calls.	  out-
	      value  must be a struct timeval ** (the caller has to free *out-
	      value), and invalue must be a struct timeval *, and they	cannot
	      be NULL. Using a struct with seconds set to -1 results in	an in-
	      finite timeout, which is the default.  This option  is  OpenLDAP
	      specific.

       LDAP_OPT_URI
	      Sets/gets	 a  comma-  or space-separated list of URIs to be con-
	      tacted by	the library when trying	 to  establish	a  connection.
	      outvalue	must  be  a  char **, and the caller is	responsible of
	      freeing the resulting string by calling  ldap_memfree(3),	 while
	      invalue  must  be	 a const char *; the library parses the	string
	      into a list of LDAPURLDesc  structures,  so  the	invocation  of
	      ldap_set_option(3) may fail if URL parsing fails.	 URIs may only
	      contain the schema, the host, and	the port fields.  This	option
	      is OpenLDAP specific.

SASL OPTIONS
       The SASL	options	are OpenLDAP specific.

       LDAP_OPT_X_SASL_AUTHCID
	      Gets  the	 SASL authentication identity; outvalue	must be	a char
	      **, its content needs to be freed	by the caller using  ldap_mem-
	      free(3).

       LDAP_OPT_X_SASL_AUTHZID
	      Gets  the	 SASL  authorization identity; outvalue	must be	a char
	      **, its content needs to be freed	by the caller using  ldap_mem-
	      free(3).

       LDAP_OPT_X_SASL_MAXBUFSIZE
	      Gets/sets	 SASL  maximum	buffer	size;  invalue	must  be const
	      ber_len_t	*, while outvalue  must	 be  ber_len_t	*.   See  also
	      LDAP_OPT_X_SASL_SECPROPS.

       LDAP_OPT_X_SASL_MECH
	      Gets the SASL mechanism; outvalue	must be	a char **, its content
	      needs to be freed	by the caller using ldap_memfree(3).

       LDAP_OPT_X_SASL_MECHLIST
	      Gets the list of the available mechanisms, in form  of  a	 NULL-
	      terminated  array	 of  strings;  outvalue	must be	char ***.  The
	      caller must not free or otherwise	muck with it.

       LDAP_OPT_X_SASL_NOCANON
	      Sets/gets	the NOCANON flag.  When	unset, the hostname is canoni-
	      calized.	 invalue  must be const	int *; its value should	either
	      be LDAP_OPT_OFF or LDAP_OPT_ON.  outvalue	must be	int *.

       LDAP_OPT_X_SASL_REALM
	      Gets the SASL realm; outvalue must be a  char  **,  its  content
	      needs to be freed	by the caller using ldap_memfree(3).

       LDAP_OPT_X_SASL_SECPROPS
	      Sets  the	 SASL secprops;	invalue	must be	a char *, containing a
	      comma-separated list of properties.  Legal values	are: none, no-
	      dict,  noplain,  noactive,  passcred,  forwardsec,  noanonymous,
	      minssf=<minssf>, maxssf=<maxssf>,	maxbufsize=<maxbufsize>.

       LDAP_OPT_X_SASL_SSF
	      Gets the SASL SSF; outvalue must be a ber_len_t *.

       LDAP_OPT_X_SASL_SSF_EXTERNAL
	      Sets the SASL SSF	value related to an  authentication  performed
	      using  an	 EXTERNAL mechanism; invalue must be a const ber_len_t
	      *.

       LDAP_OPT_X_SASL_SSF_MAX
	      Gets/sets	SASL maximum SSF; invalue must be const	 ber_len_t  *,
	      while    outvalue	   must	   be	 ber_len_t    *.    See	  also
	      LDAP_OPT_X_SASL_SECPROPS.

       LDAP_OPT_X_SASL_SSF_MIN
	      Gets/sets	SASL minimum SSF; invalue must be const	 ber_len_t  *,
	      while    outvalue	   must	   be	 ber_len_t    *.    See	  also
	      LDAP_OPT_X_SASL_SECPROPS.

       LDAP_OPT_X_SASL_USERNAME
	      Gets the SASL username; outvalue must be a char **.  Its content
	      needs to be freed	by the caller using ldap_memfree(3).

TCP OPTIONS
       The  TCP	 options  are OpenLDAP specific.  Mainly intended for use with
       Linux, they may not be portable.

       LDAP_OPT_X_KEEPALIVE_IDLE
	      Sets/gets	the number of seconds a	 connection  needs  to	remain
	      idle  before  TCP	starts sending keepalive probes.  invalue must
	      be const int *; outvalue must be int *.

       LDAP_OPT_X_KEEPALIVE_PROBES
	      Sets/gets	the maximum number of keepalive	probes TCP should send
	      before  dropping	the  connection.  invalue must be const	int *;
	      outvalue must be int *.

       LDAP_OPT_X_KEEPALIVE_INTERVAL
	      Sets/gets	the interval in	seconds	between	 individual  keepalive
	      probes.  invalue must be const int *; outvalue must be int *.

TLS OPTIONS
       The TLS options are OpenLDAP specific.

       LDAP_OPT_X_TLS_CACERTDIR
	      Sets/gets	 the path of the directory containing CA certificates.
	      invalue must be const char *; outvalue must be char **, and  its
	      contents need to be freed	by the caller using ldap_memfree(3).

       LDAP_OPT_X_TLS_CACERTFILE
	      Sets/gets	 the  full-path	 of  the CA certificate	file.  invalue
	      must be const char *; outvalue must be char **, and its contents
	      need to be freed by the caller using ldap_memfree(3).

       LDAP_OPT_X_TLS_CERTFILE
	      Sets/gets	 the  full-path	of the certificate file.  invalue must
	      be const char *; outvalue	must be	char **, and its contents need
	      to be freed by the caller	using ldap_memfree(3).

       LDAP_OPT_X_TLS_CIPHER_SUITE
	      Sets/gets	 the allowed cipher suite.  invalue must be const char
	      *; outvalue must be char **, and its contents need to  be	 freed
	      by the caller using ldap_memfree(3).

       LDAP_OPT_X_TLS_CONNECT_ARG
	      Sets/gets	 the  connection  callback  argument.  invalue must be
	      const void *; outvalue must be void **.

       LDAP_OPT_X_TLS_CONNECT_CB
	      Sets/gets	the connection callback	handle.	 invalue must be const
	      LDAP_TLS_CONNECT_CB *; outvalue must be LDAP_TLS_CONNECT_CB **.

       LDAP_OPT_X_TLS_CRLCHECK
	      Sets/gets	    the	   CRL	  evaluation	strategy,    one    of
	      LDAP_OPT_X_TLS_CRL_NONE,	     LDAP_OPT_X_TLS_CRL_PEER,	    or
	      LDAP_OPT_X_TLS_CRL_ALL.	invalue	 must be const int *; outvalue
	      must be int *.  Requires OpenSSL.

       LDAP_OPT_X_TLS_CRLFILE
	      Sets/gets	the full-path of the CRL file.	invalue	must be	 const
	      char  *;	outvalue  must be char **, and its contents need to be
	      freed by the caller using	ldap_memfree(3).  This option is  only
	      valid for	GnuTLS.

       LDAP_OPT_X_TLS_CTX
	      Sets/gets	the TLS	library	context. New TLS sessions will inherit
	      their default settings from this library context.	 invalue  must
	      be  const	 void  *;  outvalue  must  be void **.	When using the
	      OpenSSL library this is an SSL_CTX*. When	using other crypto li-
	      braries this is a	pointer	to an OpenLDAP private structure.  Ap-
	      plications generally should not use this option  or  attempt  to
	      manipulate this structure.

       LDAP_OPT_X_TLS_DHFILE
	      Gets/sets	 the  full-path	 of the	file containing	the parameters
	      for Diffie-Hellman ephemeral  key	 exchange.   invalue  must  be
	      const char *; outvalue must be char **, and its contents need to
	      be freed by the caller using ldap_memfree(3).  Ignored by	GnuTLS
	      and Mozilla NSS.

       LDAP_OPT_X_TLS_ECNAME
	      Gets/sets	 the  name of the curve(s) used	for elliptic curve key
	      exchanges.  invalue must be const	char *;	outvalue must be  char
	      **,  and	its  contents  need  to	 be  freed by the caller using
	      ldap_memfree(3).	Ignored	by GnuTLS and Mozilla NSS. In GnuTLS a
	      curve may	be selected in the cipher suite	specification.

       LDAP_OPT_X_TLS_KEYFILE
	      Sets/gets	 the  full-path	 of the	certificate key	file.  invalue
	      must be const char *; outvalue must be char **, and its contents
	      need to be freed by the caller using ldap_memfree(3).

       LDAP_OPT_X_TLS_NEWCTX
	      Instructs	 the library to	create a new TLS library context.  in-
	      value must be const int *.  A non-zero value pointed to  by  in-
	      value tells the library to create	a context for a	server.

       LDAP_OPT_X_TLS_PROTOCOL_MIN
	      Sets/gets	 the  minimum protocol version.	 invalue must be const
	      int *; outvalue must be int *.

       LDAP_OPT_X_TLS_RANDOM_FILE
	      Sets/gets	the random file	when /dev/random and /dev/urandom  are
	      not  available.	invalue	must be	const char *; outvalue must be
	      char **, and its contents	need to	be freed by the	 caller	 using
	      ldap_memfree(3).	Ignored	by GnuTLS older	than version 2.2.  Ig-
	      nored by Mozilla NSS.

       LDAP_OPT_X_TLS_REQUIRE_CERT
	      Sets/gets	 the  peer  certificate	 checking  strategy,  one   of
	      LDAP_OPT_X_TLS_NEVER,   LDAP_OPT_X_TLS_HARD,  LDAP_OPT_X_TLS_DE-
	      MAND, LDAP_OPT_X_TLS_ALLOW, LDAP_OPT_X_TLS_TRY.

       LDAP_OPT_X_TLS_REQUIRE_SAN
	      Sets/gets	the peer certificate  subjectAlternativeName  checking
	      strategy,	  one  of  LDAP_OPT_X_TLS_NEVER,  LDAP_OPT_X_TLS_HARD,
	      LDAP_OPT_X_TLS_DEMAND, LDAP_OPT_X_TLS_ALLOW, LDAP_OPT_X_TLS_TRY.

       LDAP_OPT_X_TLS_SSL_CTX
	      Gets the TLS session context associated with this	handle.	  out-
	      value  must  be void **.	When using the OpenSSL library this is
	      an SSL*. When using other	crypto libraries this is a pointer  to
	      an  OpenLDAP  private  structure.	 Applications generally	should
	      not use this option.

ERRORS
       On success, the functions return	LDAP_OPT_SUCCESS, while	they  may  re-
       turn LDAP_OPT_ERROR to indicate a generic option	handling error.	 Occa-
       sionally, more specific errors can be returned, like LDAP_NO_MEMORY  to
       indicate	a failure in memory allocation.

NOTES
       The   LDAP   libraries	with  the  LDAP_OPT_REFERRALS  option  set  to
       LDAP_OPT_ON (default value) automatically  follow  referrals  using  an
       anonymous bind.	Application developers are encouraged to either	imple-
       ment consistent referral	chasing	features, or explicitly	disable	refer-
       ral chasing by setting that option to LDAP_OPT_OFF.

       The  protocol  version used by the library defaults to LDAPv2 (now his-
       toric), which corresponds to the	LDAP_VERSION2 macro.  Application  de-
       velopers	 are encouraged	to explicitly set LDAP_OPT_PROTOCOL_VERSION to
       LDAPv3, using the LDAP_VERSION3 macro, or to allow users	to select  the
       protocol	version.

SEE ALSO
       ldap(3),	ldap_error(3), RFC 4422	(http://www.rfc-editor.org),

ACKNOWLEDGEMENTS
       OpenLDAP	 Software  is developed	and maintained by The OpenLDAP Project
       <http://www.openldap.org/>.  OpenLDAP Software is derived from the Uni-
       versity of Michigan LDAP	3.3 Release.

OpenLDAP 2.4.57			  2021/01/18		    LDAP_GET_OPTION(3)

NAME | LIBRARY | SYNOPSIS | DESCRIPTION | SASL OPTIONS | TCP OPTIONS | TLS OPTIONS | ERRORS | NOTES | SEE ALSO | ACKNOWLEDGEMENTS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=ldap_get_option&sektion=3&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help