Data Structures
struct	apr_ldap_err_t
struct	apr_ldap_opt_tls_cert_t
struct	apr_ldap_url_desc_t
Defines
#define	APR_HAS_LDAP 1
#define	APR_HAS_NETSCAPE_LDAPSDK 0
#define	APR_HAS_SOLARIS_LDAPSDK 0
#define	APR_HAS_NOVELL_LDAPSDK 0
#define	APR_HAS_MOZILLA_LDAPSDK 0
#define	APR_HAS_OPENLDAP_LDAPSDK 1
#define	APR_HAS_MICROSOFT_LDAPSDK 0
#define	APR_HAS_TIVOLI_LDAPSDK 0
#define	APR_HAS_ZOS_LDAPSDK 0
#define	APR_HAS_OTHER_LDAPSDK 0
#define	APR_HAS_LDAP_SSL 1
#define	APR_HAS_LDAP_URL_PARSE 0
#define	LDAP_DEPRECATED 1
#define	APR_HAS_LDAPSSL_CLIENT_INIT 0
#define	APR_HAS_LDAPSSL_CLIENT_DEINIT 0
#define	APR_HAS_LDAPSSL_ADD_TRUSTED_CERT 0
#define	APR_HAS_LDAP_START_TLS_S 1
#define	APR_HAS_LDAP_SSLINIT 0
#define	APR_HAS_LDAPSSL_INIT 0
#define	APR_HAS_LDAPSSL_INSTALL_ROUTINES 0
#define	LDAPS_PORT 636
#define	APR_LDAP_SIZELIMIT 0
#define	LDAP_VERSION_MAX LDAP_VERSION
#define	APR_LDAP_IS_SERVER_DOWN(s) ((s) == LDAP_SERVER_DOWN)
#define	APU_DECLARE_LDAP(type) APU_DECLARE(type)
#define	APU_LDAP_SECURITY_ERROR(n)
#define	APR_LDAP_OPT_TLS 0x6fff
#define	APR_LDAP_OPT_TLS_CERT 0x6ffe
#define	APR_LDAP_OPT_VERIFY_CERT 0x6ffd
#define	APR_LDAP_OPT_REFERRALS 0x6ffc
#define	APR_LDAP_OPT_REFHOPLIMIT 0x6ffb
#define	APR_LDAP_CA_TYPE_UNKNOWN 0
#define	APR_LDAP_CA_TYPE_DER 1
#define	APR_LDAP_CA_TYPE_BASE64 2
#define	APR_LDAP_CA_TYPE_CERT7_DB 3
#define	APR_LDAP_CA_TYPE_SECMOD 4
#define	APR_LDAP_CERT_TYPE_UNKNOWN 5
#define	APR_LDAP_CERT_TYPE_DER 6
#define	APR_LDAP_CERT_TYPE_BASE64 7
#define	APR_LDAP_CERT_TYPE_KEY3_DB 8
#define	APR_LDAP_CERT_TYPE_NICKNAME 9
#define	APR_LDAP_KEY_TYPE_UNKNOWN 10
#define	APR_LDAP_KEY_TYPE_DER 11
#define	APR_LDAP_KEY_TYPE_BASE64 12
#define	APR_LDAP_CERT_TYPE_PFX 13
#define	APR_LDAP_KEY_TYPE_PFX 14
#define	APR_LDAP_CA_TYPE_CACERTDIR_BASE64 15
#define	APR_LDAP_NONE 0
#define	APR_LDAP_SSL 1
#define	APR_LDAP_STARTTLS 2
#define	APR_LDAP_STOPTLS 3
#define	APR_LDAP_URL_SUCCESS 0x00
#define	APR_LDAP_URL_ERR_MEM 0x01
#define	APR_LDAP_URL_ERR_PARAM 0x02
#define	APR_LDAP_URL_ERR_BADSCHEME 0x03
#define	APR_LDAP_URL_ERR_BADENCLOSURE 0x04
#define	APR_LDAP_URL_ERR_BADURL 0x05
#define	APR_LDAP_URL_ERR_BADHOST 0x06
#define	APR_LDAP_URL_ERR_BADATTRS 0x07
#define	APR_LDAP_URL_ERR_BADSCOPE 0x08
#define	APR_LDAP_URL_ERR_BADFILTER 0x09
#define	APR_LDAP_URL_ERR_BADEXTS 0x0a
Typedefs
typedef struct apr_ldap_err_t	apr_ldap_err_t
typedef struct apr_ldap_opt_tls_cert_t	apr_ldap_opt_tls_cert_t
typedef struct apr_ldap_url_desc_t	apr_ldap_url_desc_t
Functions
int	apr_ldap_ssl_init (apr_pool_t pool, const char cert_auth_file, int cert_file_type, apr_ldap_err_t **result_err)
int	apr_ldap_ssl_deinit (void)
int	apr_ldap_init (apr_pool_t pool, LDAP ldap, const char hostname, int portno, int secure, apr_ldap_err_t **result_err)
int	apr_ldap_info (apr_pool_t pool, apr_ldap_err_t *result_err)
int	apr_ldap_get_option (apr_pool_t pool, LDAP ldap, int option, void outvalue, apr_ldap_err_t *result_err)
int	apr_ldap_set_option (apr_pool_t pool, LDAP ldap, int option, const void invalue, apr_ldap_err_t *result_err)
apr_status_t	apr_ldap_rebind_init (apr_pool_t *pool)
apr_status_t	apr_ldap_rebind_add (apr_pool_t pool, LDAP ld, const char bindDN, const char bindPW)
apr_status_t	apr_ldap_rebind_remove (LDAP *ld)
int	apr_ldap_is_ldap_url (const char *url)
int	apr_ldap_is_ldaps_url (const char *url)
int	apr_ldap_is_ldapi_url (const char *url)
int	apr_ldap_url_parse_ext (apr_pool_t pool, const char url_in, apr_ldap_url_desc_t ludpp, apr_ldap_err_t result_err)
int	apr_ldap_url_parse (apr_pool_t pool, const char url_in, apr_ldap_url_desc_t ludpp, apr_ldap_err_t result_err)

Define Documentation

#define APR_LDAP_CA_TYPE_BASE64 2

PEM encoded CA certificate

#define APR_LDAP_CA_TYPE_CACERTDIR_BASE64 15

Openldap directory full of base64-encoded cert authorities with hashes in corresponding .0 directory

#define APR_LDAP_CA_TYPE_CERT7_DB 3

Netscape/Mozilla cert7.db CA certificate database

#define APR_LDAP_CA_TYPE_DER 1

binary DER encoded CA certificate

#define APR_LDAP_CA_TYPE_SECMOD 4

Netscape/Mozilla secmod file

#define APR_LDAP_CA_TYPE_UNKNOWN 0

Structures for the apr_set_option() cases APR_LDAP_OPT_TLS_CERT

This structure includes possible options to set certificates on system initialisation. Different SDKs have different certificate requirements, and to achieve this multiple certificates must be specified at once passed as an (apr_array_header_t *).

Netscape: Needs the CA cert database (cert7.db), the client cert database (key3.db) and the security module file (secmod.db) set at the system initialisation time. Three types are supported: APR_LDAP_CERT7_DB, APR_LDAP_KEY3_DB and APR_LDAP_SECMOD.

To specify a client cert connection, a certificate nickname needs to be provided with a type of APR_LDAP_CERT. int ldapssl_enable_clientauth( LDAP *ld, char *keynickname, char *keypasswd, char *certnickname ); keynickname is currently not used, and should be set to ""

Novell: Needs CA certificates and client certificates set at system initialisation time. Three types are supported: APR_LDAP_CA*, APR_LDAP_CERT* and APR_LDAP_KEY*.

Certificates cannot be specified per connection.

The functions used are: ldapssl_add_trusted_cert(serverTrustedRoot, serverTrustedRootEncoding); Clients certs and keys are set at system initialisation time with int ldapssl_set_client_cert ( void *cert, int type void *password); type can be LDAPSSL_CERT_FILETYPE_B64 or LDAPSSL_CERT_FILETYPE_DER ldapssl_set_client_private_key(clientPrivateKey, clientPrivateKeyEncoding, clientPrivateKeyPassword);

OpenSSL: Needs one or more CA certificates to be set at system initialisation time with a type of APR_LDAP_CA*.

May have one or more client certificates set per connection with a type of APR_LDAP_CERT*, and keys with APR_LDAP_KEY*. CA certificate type unknown

#define APR_LDAP_CERT_TYPE_BASE64 7

PEM encoded client certificate

#define APR_LDAP_CERT_TYPE_DER 6

binary DER encoded client certificate

#define APR_LDAP_CERT_TYPE_KEY3_DB 8

Netscape/Mozilla key3.db client certificate database

#define APR_LDAP_CERT_TYPE_NICKNAME 9

Netscape/Mozilla client certificate nickname

#define APR_LDAP_CERT_TYPE_PFX 13

PKCS#12 encoded client certificate

#define APR_LDAP_CERT_TYPE_UNKNOWN 5

Client certificate type unknown

#define APR_LDAP_KEY_TYPE_BASE64 12

PEM encoded private key

#define APR_LDAP_KEY_TYPE_DER 11

binary DER encoded private key

#define APR_LDAP_KEY_TYPE_PFX 14

PKCS#12 encoded private key

#define APR_LDAP_KEY_TYPE_UNKNOWN 10

Private key type unknown

#define APR_LDAP_NONE 0

APR_LDAP_OPT_TLS

This sets the SSL level on the LDAP handle.

Netscape/Mozilla: Supports SSL, but not STARTTLS SSL is enabled by calling ldapssl_install_routines().

Novell: Supports SSL and STARTTLS. SSL is enabled by calling ldapssl_install_routines(). Note that calling other ldap functions before ldapssl_install_routines() may cause this function to fail. STARTTLS is enabled by calling ldapssl_start_tls_s() after calling ldapssl_install_routines() (check this).

OpenLDAP: Supports SSL and supports STARTTLS, but none of this is documented: http://www.openldap.org/lists/openldap-software/200409/msg00618.html Documentation for both SSL support and STARTTLS has been deleted from the OpenLDAP documentation and website. No encryption

#define APR_LDAP_OPT_REFERRALS 0x6ffc

Set the LDAP library to indicate if referrals should be chased during LDAP searches.

#define APR_LDAP_OPT_REFHOPLIMIT 0x6ffb

Set the LDAP library to indicate a maximum number of referral hops to chase before giving up on the search.

#define APR_LDAP_OPT_TLS 0x6fff

Set SSL mode to one of APR_LDAP_NONE, APR_LDAP_SSL, APR_LDAP_STARTTLS or APR_LDAP_STOPTLS.

#define APR_LDAP_OPT_TLS_CERT 0x6ffe

Set zero or more CA certificates, client certificates or private keys globally, or per connection (where supported).

#define APR_LDAP_OPT_VERIFY_CERT 0x6ffd

Set the LDAP library to no verify the server certificate. This means all servers are considered trusted.

#define APR_LDAP_SSL 1

SSL encryption (ldaps://)

#define APR_LDAP_STARTTLS 2

TLS encryption (STARTTLS)

#define APR_LDAP_STOPTLS 3

end TLS encryption (STOPTLS)

#define APU_LDAP_SECURITY_ERROR ( n )

Value:

(LDAP_INAPPROPRIATE_AUTH == n) ? 1 \
    : (LDAP_INVALID_CREDENTIALS == n) ? 1 \
    : (APU_LDAP_INSUFFICIENT_ACCESS == n) ? 1 \
    : 0

Macro to detect security related return values.

Typedef Documentation

typedef struct apr_ldap_err_t apr_ldap_err_t

This structure allows the C LDAP API error codes to be returned along with plain text error messages that explain to us mere mortals what really happened.

typedef struct apr_ldap_opt_tls_cert_t apr_ldap_opt_tls_cert_t

Certificate structure.

This structure is used to store certificate details. An array of these structures is passed to apr_ldap_set_option() to set CA and client certificates.

Parameters:

type	Type of certificate APR_LDAP__TYPE_
path	Path, file or nickname of the certificate
password	Optional password, can be NULL

typedef struct apr_ldap_url_desc_t apr_ldap_url_desc_t

Structure to access an exploded LDAP URL

Function Documentation

int apr_ldap_get_option	(	apr_pool_t *	pool,
		LDAP *	ldap,
		int	option,
		void *	outvalue,
		apr_ldap_err_t **	result_err
	)

APR LDAP get option function

This function gets option values from a given LDAP session if one was specified. It maps to the native ldap_get_option() function.

Parameters:

pool	The pool to use
ldap	The LDAP handle
option	The LDAP_OPT_* option to return
outvalue	The value returned (if any)
result_err	The apr_ldap_err_t structure contained detailed results of the operation.

int apr_ldap_info	(	apr_pool_t *	pool,
		apr_ldap_err_t **	result_err
	)

APR LDAP info function

This function returns a string describing the LDAP toolkit currently in use. The string is placed inside result_err->reason.

Parameters:

pool	The pool to use
result_err	The returned result

int apr_ldap_init	(	apr_pool_t *	pool,
		LDAP **	ldap,
		const char *	hostname,
		int	portno,
		int	secure,
		apr_ldap_err_t **	result_err
	)

APR LDAP initialise function

This function is responsible for initialising an LDAP connection in a toolkit independant way. It does the job of ldap_init() from the C api.

It handles both the SSL and non-SSL case, and attempts to hide the complexity setup from the user. This function assumes that any certificate setup necessary has already been done.

If SSL or STARTTLS needs to be enabled, and the underlying toolkit supports it, the following values are accepted for secure:

APR_LDAP_NONE: No encryption APR_LDAP_SSL: SSL encryption (ldaps://) APR_LDAP_STARTTLS: Force STARTTLS on ldap://

Remarks:: The Novell toolkit is only able to set the SSL mode via this function. To work around this limitation, set the SSL mode here if no per connection client certificates are present, otherwise set secure APR_LDAP_NONE here, then set the per connection client certificates, followed by setting the SSL mode via apr_ldap_set_option(). As Novell does not support per connection client certificates, this problem is worked around while still being compatible with other LDAP toolkits.

Parameters:

pool	The pool to use
ldap	The LDAP handle
hostname	The name of the host to connect to. This can be either a DNS name, or an IP address.
portno	The port to connect to
secure	The security mode to set
result_err	The returned result

int apr_ldap_is_ldap_url ( const char * url )

Is this URL an ldap url? ldap://

Parameters:

url	The url to test

int apr_ldap_is_ldapi_url ( const char * url )

Is this URL an ldap socket url? ldapi://

Parameters:

url	The url to test

int apr_ldap_is_ldaps_url ( const char * url )

Is this URL an SSL ldap url? ldaps://

Parameters:

url	The url to test

apr_status_t apr_ldap_rebind_add	(	apr_pool_t *	pool,
		LDAP *	ld,
		const char *	bindDN,
		const char *	bindPW
	)

APR LDAP rebind_add function

This function creates a cross reference entry for the specified ldap connection. The rebind callback function will look up this ldap connection so it can retrieve the bindDN and bindPW for use in any binds while referrals are being chased.

This function will add the callback to the LDAP handle passed in.

A cleanup is registered within the pool provided to remove this entry when the pool is removed. Alternatively apr_ldap_rebind_remove() can be called to explicitly remove the entry at will.

Parameters:

pool	The pool to use
ld	The LDAP connectionhandle
bindDN	The bind DN to be used for any binds while chasing referrals on this ldap connection.
bindPW	The bind Password to be used for any binds while chasing referrals on this ldap connection.

apr_status_t apr_ldap_rebind_init ( apr_pool_t * pool )

APR LDAP initialize rebind lock

This function creates the lock for controlling access to the xref list..

Parameters:

pool	Pool to use when creating the xref_lock.

apr_status_t apr_ldap_rebind_remove ( LDAP * ld )

APR LDAP rebind_remove function

This function removes the rebind cross reference entry for the specified ldap connection.

If not explicitly removed, this function will be called automatically when the pool is cleaned up.

Parameters:

ld	The LDAP connectionhandle

int apr_ldap_set_option	(	apr_pool_t *	pool,
		LDAP *	ldap,
		int	option,
		const void *	invalue,
		apr_ldap_err_t **	result_err
	)

APR LDAP set option function

This function sets option values to a given LDAP session if one was specified. It maps to the native ldap_set_option() function.

Where an option is not supported by an LDAP toolkit, this function will try and apply legacy functions to achieve the same effect, depending on the platform.

Parameters:

pool	The pool to use
ldap	The LDAP handle
option	The LDAP_OPT_* option to set
invalue	The value to set
result_err	The apr_ldap_err_t structure contained detailed results of the operation.

int apr_ldap_ssl_deinit ( void )

APR LDAP SSL De-Initialise function

This function tears down any SSL certificate setup previously set using apr_ldap_ssl_init(). It should be called to clean up if a graceful restart of a service is attempted.

Todo:: currently we do not check whether apr_ldap_ssl_init() has been called first - we probably should.

int apr_ldap_ssl_init	(	apr_pool_t *	pool,
		const char *	cert_auth_file,
		int	cert_file_type,
		apr_ldap_err_t **	result_err
	)

APR LDAP SSL Initialise function

This function initialises SSL on the underlying LDAP toolkit if this is necessary.

If a CA certificate is provided, this is set, however the setting of certificates via this method has been deprecated and will be removed in APR v2.0.

The apr_ldap_set_option() function with the APR_LDAP_OPT_TLS_CERT option should be used instead to set certificates.

If SSL support is not available on this platform, or a problem was encountered while trying to set the certificate, the function will return APR_EGENERAL. Further LDAP specific error information can be found in result_err.

Parameters:

pool	The pool to use
cert_auth_file	The name of the certificate to use, can be NULL
cert_file_type	The type of certificate specified. See the apr_ldap_set_option() APR_LDAP_OPT_TLS_CERT option for details.
result_err	The returned result

int apr_ldap_url_parse	(	apr_pool_t *	pool,
		const char *	url_in,
		apr_ldap_url_desc_t **	ludpp,
		apr_ldap_err_t **	result_err
	)

Parse an LDAP URL.

Parameters:

pool	The pool to use
url_in	The URL to parse
ludpp	The structure to return the exploded URL
result_err	The result structure of the operation

int apr_ldap_url_parse_ext	(	apr_pool_t *	pool,
		const char *	url_in,
		apr_ldap_url_desc_t **	ludpp,
		apr_ldap_err_t **	result_err
	)

Parse an LDAP URL.

Parameters:

pool	The pool to use
url_in	The URL to parse
ludpp	The structure to return the exploded URL
result_err	The result structure of the operation

Data Structures

Defines

Typedefs

Functions

Define Documentation

Typedef Documentation

Function Documentation