Apache Portable Runtime
Loading...
Searching...
No Matches
Data Structures | Macros | Typedefs | Enumerations | Functions

Data Structures

struct  apr_ldap_url_desc_t
 
struct  apr_ldap_apiinfo_t
 
struct  apr_ldap_apifeature_info_t
 
struct  apr_ldap_opt_tls_cert_t
 
union  apr_ldap_opt_t
 
struct  apr_ldap_bind_interact_t
 

Macros

#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
 
#define APU_DECLARE_LDAP(type)   APR_DECLARE(type)
 
#define APR_LDAP_PORT   389
 
#define APR_LDAPS_PORT   636
 
#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_OPT_HANDLE   0x6ffa
 
#define APR_LDAP_OPT_PROTOCOL_VERSION   0x6ff9
 
#define APR_LDAP_OPT_API_INFO   0x6ff8
 
#define APR_LDAP_OPT_API_FEATURE_INFO   0x6ff7
 
#define APR_LDAP_OPT_DEREF   0x6ff6
 
#define APR_LDAP_OPT_RESULT_CODE   0x6ff5
 
#define APR_LDAP_OPT_DESC   0x6ff4
 
#define APR_LDAP_OPT_URI   0x5006
 
#define APR_LDAP_OPT_NETWORK_TIMEOUT   0x5005
 
#define APR_LDAP_OPT_TIMEOUT   0x5002
 
#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_CACERTDIR_BASE64   15
 
#define APR_LDAP_CA_TYPE_URI   18
 
#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_PFX   13
 
#define APR_LDAP_CERT_TYPE_URI   16
 
#define APR_LDAP_KEY_TYPE_UNKNOWN   10
 
#define APR_LDAP_KEY_TYPE_DER   11
 
#define APR_LDAP_KEY_TYPE_BASE64   12
 
#define APR_LDAP_KEY_TYPE_PFX   14
 
#define APR_LDAP_KEY_TYPE_URI   17
 

Typedefs

typedef struct apr_ldap_url_desc_t apr_ldap_url_desc_t
 
typedef struct apr_ldap_driver_t apr_ldap_driver_t
 
typedef struct apr_ldap_t apr_ldap_t
 
typedef struct apr_ldap_apiinfo_t apr_ldap_apiinfo_t
 
typedef struct apr_ldap_apifeature_info_t apr_ldap_apifeature_info_t
 
typedef struct apr_ldap_opt_tls_cert_t apr_ldap_opt_tls_cert_t
 
typedef union apr_ldap_opt_t apr_ldap_opt_t
 
typedef struct apr_ldap_bind_interact_t apr_ldap_bind_interact_t
 
typedef apr_status_t apr_ldap_bind_interact_cb(apr_ldap_t *ld, unsigned int flags, apr_ldap_bind_interact_t *interact, void *ctx)
 
typedef struct apr_ldap_control_t apr_ldap_control_t
 
typedef apr_status_t(* apr_ldap_prepare_cb) (apr_ldap_t *ldap, apr_status_t status, void *ctx, apu_err_t *err)
 
typedef apr_status_t(* apr_ldap_bind_cb) (apr_ldap_t *ldap, apr_status_t status, const char *matcheddn, apr_ldap_control_t **serverctrls, void *ctx, apu_err_t *err)
 
typedef apr_status_t(* apr_ldap_compare_cb) (apr_ldap_t *ldap, apr_status_t status, const char *matcheddn, apr_ldap_control_t **serverctrls, void *ctx, apu_err_t *err)
 
typedef apr_status_t(* apr_ldap_search_result_cb) (apr_ldap_t *ldap, apr_status_t status, apr_size_t count, const char *matcheddn, apr_ldap_control_t **serverctrls, void *ctx, apu_err_t *err)
 
typedef apr_status_t(* apr_ldap_search_entry_cb) (apr_ldap_t *ldap, const char *dn, int eidx, int nattrs, int aidx, const char *attr, int nvals, int vidx, apr_buffer_t *val, int binary, void *ctx, apu_err_t *err)
 

Enumerations

enum  apr_ldap_protocol_version_e { APR_LDAP_VERSION1 = 1 , APR_LDAP_VERSION2 = 2 , APR_LDAP_VERSION3 = 3 }
 
enum  apr_ldap_deref_e { APR_LDAP_DEREF_NEVER = 0 , APR_LDAP_DEREF_SEARCHING = 1 , APR_LDAP_DEREF_FINDING = 2 , APR_LDAP_DEREF_ALWAYS = 3 }
 
enum  apr_ldap_switch_e { APR_LDAP_OPT_OFF = 0 , APR_LDAP_OPT_ON = 1 }
 
enum  apr_ldap_tls_e { APR_LDAP_TLS_NONE = 0 , APR_LDAP_TLS_SSL = 1 , APR_LDAP_TLS_STARTTLS = 2 , APR_LDAP_TLS_STOPTLS = 3 }
 
enum  apr_ldap_verify_e { APR_LDAP_VERIFY_OFF = 0 , APR_LDAP_VERIFY_ON = 1 }
 
enum  apr_ldap_bind_interact_e {
  APR_LDAP_INTERACT_DN = 0 , APR_LDAP_INTERACT_GETREALM = 0x4008 , APR_LDAP_INTERACT_AUTHNAME = 0x4002 , APR_LDAP_INTERACT_USER = 0x4001 ,
  APR_LDAP_INTERACT_PASS = 0x4004 , APR_LDAP_INTERACT_NOECHOPROMPT = 0x4006 , APR_LDAP_INTERACT_ECHOPROMPT = 0x4005
}
 
enum  apr_ldap_search_scope_e { APR_LDAP_SCOPE_BASE = 0x0000 , APR_LDAP_SCOPE_ONELEVEL = 0x0001 , APR_LDAP_SCOPE_SUBTREE = 0x0002 , APR_LDAP_SCOPE_SUBORDINATE = 0x0003 }
 

Functions

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, apu_err_t **result_err)
 
int apr_ldap_url_parse (apr_pool_t *pool, const char *url_in, apr_ldap_url_desc_t **ludpp, apu_err_t **result_err)
 
apr_status_t apr_ldap_get_driver (apr_pool_t *pool, const apr_ldap_driver_t **driver, apu_err_t *err)
 
apr_status_t apr_ldap_info (apr_pool_t *pool, apu_err_t **result_err)
 
apr_status_t apr_ldap_initialise (apr_pool_t *pool, apr_ldap_t **ldap, apu_err_t *err)
 
apr_status_t apr_ldap_option_get (apr_pool_t *pool, apr_ldap_t *ldap, int option, apr_ldap_opt_t *outvalue, apu_err_t *result_err)
 
apr_status_t apr_ldap_option_set (apr_pool_t *pool, apr_ldap_t *ldap, int option, const apr_ldap_opt_t *invalue, apu_err_t *result_err)
 
apr_status_t apr_ldap_connect (apr_pool_t *pool, apr_ldap_t *ldap, apr_interval_time_t timeout, apu_err_t *result_err)
 
apr_status_t apr_ldap_prepare (apr_pool_t *pool, apr_ldap_t *ldap, apr_ldap_prepare_cb prepare_cb, void *prepare_ctx)
 
apr_status_t apr_ldap_process (apr_pool_t *pool, apr_ldap_t *ldap, apr_interval_time_t timeout, apu_err_t *err)
 
apr_status_t apr_ldap_result (apr_pool_t *pool, apr_ldap_t *ldap, apr_interval_time_t timeout, apu_err_t *err)
 
apr_status_t apr_ldap_poll (apr_pool_t *pool, apr_ldap_t *ldap, apr_pollcb_t *poll, apr_interval_time_t timeout, apu_err_t *err)
 
apr_status_t apr_ldap_bind (apr_pool_t *pool, apr_ldap_t *ldap, const char *mech, apr_ldap_bind_interact_cb *interact_cb, void *interact_ctx, apr_interval_time_t timeout, apr_ldap_bind_cb bind_cb, void *bind_ctx, apu_err_t *err)
 
apr_status_t apr_ldap_compare (apr_pool_t *pool, apr_ldap_t *ldap, const char *dn, const char *attr, const apr_buffer_t *val, apr_ldap_control_t **serverctrls, apr_ldap_control_t **clientctrls, apr_interval_time_t timeout, apr_ldap_compare_cb compare_cb, void *ctx, apu_err_t *err)
 
apr_status_t apr_ldap_search (apr_pool_t *pool, apr_ldap_t *ldap, const char *dn, apr_ldap_search_scope_e scope, const char *filter, const char **attrs, apr_ldap_switch_e attrsonly, apr_ldap_control_t **serverctrls, apr_ldap_control_t **clientctrls, apr_interval_time_t timeout, apr_ssize_t sizelimit, apr_ldap_search_result_cb search_result_cb, apr_ldap_search_entry_cb search_entry_cb, void *ctx, apu_err_t *err)
 
apr_status_t apr_ldap_unbind (apr_ldap_t *ldap, apr_ldap_control_t **serverctrls, apr_ldap_control_t **clientctrls, apu_err_t *err)
 

Detailed Description

The APR LDAP routines provide a common, cross platform, ability to connect to and search an LDAP server.

The goals of the API are:

In typical use, the following calls are used:

Enter the event loop, where we do the following until the connection is closed.

Respond appropriately to callbacks, lining up calls to apr_ldap_compare() and apr_ldap_search() as needed.

Macro Definition Documentation

◆ APR_LDAP_CA_TYPE_BASE64

#define APR_LDAP_CA_TYPE_BASE64   2

PEM encoded CA certificate

See also
APR_LDAP_OPT_TLS_CERT
apr_ldap_opt_tls_cert_t

◆ APR_LDAP_CA_TYPE_CACERTDIR_BASE64

#define APR_LDAP_CA_TYPE_CACERTDIR_BASE64   15

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

See also
APR_LDAP_OPT_TLS_CERT
apr_ldap_opt_tls_cert_t

◆ APR_LDAP_CA_TYPE_DER

#define APR_LDAP_CA_TYPE_DER   1

Binary DER encoded CA certificate

See also
APR_LDAP_OPT_TLS_CERT
apr_ldap_opt_tls_cert_t

◆ APR_LDAP_CA_TYPE_UNKNOWN

#define APR_LDAP_CA_TYPE_UNKNOWN   0

CA certificate type unknown

See also
APR_LDAP_OPT_TLS_CERT
apr_ldap_opt_tls_cert_t

◆ APR_LDAP_CA_TYPE_URI

#define APR_LDAP_CA_TYPE_URI   18

CA Certificate at the given URI

See also
APR_LDAP_OPT_TLS_CERT
apr_ldap_opt_tls_cert_t

◆ APR_LDAP_CERT_TYPE_BASE64

#define APR_LDAP_CERT_TYPE_BASE64   7

PEM encoded client certificate

See also
APR_LDAP_OPT_TLS_CERT
apr_ldap_opt_tls_cert_t

◆ APR_LDAP_CERT_TYPE_DER

#define APR_LDAP_CERT_TYPE_DER   6

Binary DER encoded client certificate

See also
APR_LDAP_OPT_TLS_CERT
apr_ldap_opt_tls_cert_t

◆ APR_LDAP_CERT_TYPE_PFX

#define APR_LDAP_CERT_TYPE_PFX   13

PKCS#12 encoded client certificate

See also
APR_LDAP_OPT_TLS_CERT
apr_ldap_opt_tls_cert_t

◆ APR_LDAP_CERT_TYPE_UNKNOWN

#define APR_LDAP_CERT_TYPE_UNKNOWN   5

Client certificate type unknown

See also
APR_LDAP_OPT_TLS_CERT
apr_ldap_opt_tls_cert_t

◆ APR_LDAP_CERT_TYPE_URI

#define APR_LDAP_CERT_TYPE_URI   16

Certificate at the given URI

See also
APR_LDAP_OPT_TLS_CERT
apr_ldap_opt_tls_cert_t

◆ APR_LDAP_KEY_TYPE_BASE64

#define APR_LDAP_KEY_TYPE_BASE64   12

PEM encoded private key

See also
APR_LDAP_OPT_TLS_CERT
apr_ldap_opt_tls_cert_t

◆ APR_LDAP_KEY_TYPE_DER

#define APR_LDAP_KEY_TYPE_DER   11

Binary DER encoded private key

See also
APR_LDAP_OPT_TLS_CERT
apr_ldap_opt_tls_cert_t

◆ APR_LDAP_KEY_TYPE_PFX

#define APR_LDAP_KEY_TYPE_PFX   14

PKCS#12 encoded private key

See also
APR_LDAP_OPT_TLS_CERT
apr_ldap_opt_tls_cert_t

◆ APR_LDAP_KEY_TYPE_UNKNOWN

#define APR_LDAP_KEY_TYPE_UNKNOWN   10

Private key type unknown

See also
APR_LDAP_OPT_TLS_CERT
apr_ldap_opt_tls_cert_t

◆ APR_LDAP_KEY_TYPE_URI

#define APR_LDAP_KEY_TYPE_URI   17

Private key at the given URI

See also
APR_LDAP_OPT_TLS_CERT
apr_ldap_opt_tls_cert_t

◆ APR_LDAP_OPT_API_FEATURE_INFO

#define APR_LDAP_OPT_API_FEATURE_INFO   0x6ff7

Get the LDAP API feature info.

See also
apr_ldap_option_get
apr_ldap_apifeature_info_t

◆ APR_LDAP_OPT_API_INFO

#define APR_LDAP_OPT_API_INFO   0x6ff8

Get the LDAP API info.

See also
apr_ldap_option_get
apr_ldap_apiinfo_t

◆ APR_LDAP_OPT_DEREF

#define APR_LDAP_OPT_DEREF   0x6ff6

Get the dereference setting.

See also
apr_ldap_option_get
apr_ldap_option_set
apr_ldap_deref_e

◆ APR_LDAP_OPT_DESC

#define APR_LDAP_OPT_DESC   0x6ff4

Get or set the underlying socket.

Use this to get the underlying socket so as to perform select/poll before attempting to read or write.

Note that LDAP libraries like OpenLDAP will successfully return an invalid socket if a previous attempt to connect failed. In this case, you will obtain an error the next time you use the socket.

This option can also be used to set the underlying socket, as an alternative to specifying a URI. This is typically done to perform non blocking DNS lookups, or non blocking TLS negotiation, neither of which is supported natively by LDAP APIs.

Warning
Either APR_LDAP_OPT_DESC or APR_LDAP_OPT_URI must be set before any other options are set, for the LDAP handle to be initialised internally.
See also
apr_ldap_option_get
apr_ldap_option_set
apr_socket_t

◆ APR_LDAP_OPT_HANDLE

#define APR_LDAP_OPT_HANDLE   0x6ffa

Get the underlying native LDAP handle.

See also
apr_ldap_option_get

◆ APR_LDAP_OPT_NETWORK_TIMEOUT

#define APR_LDAP_OPT_NETWORK_TIMEOUT   0x5005

Get/set the network timeout.

See also
apr_ldap_option_get
apr_ldap_option_set

◆ APR_LDAP_OPT_PROTOCOL_VERSION

#define APR_LDAP_OPT_PROTOCOL_VERSION   0x6ff9

Get/Set the LDAP protocol version.

See also
apr_ldap_option_get
apr_ldap_option_set
apr_ldap_protocol_version_e

◆ APR_LDAP_OPT_REFERRALS

#define APR_LDAP_OPT_REFERRALS   0x6ffc

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

See also
apr_ldap_option_get
apr_ldap_option_set
apr_ldap_switch_e

◆ APR_LDAP_OPT_REFHOPLIMIT

#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.

See also
apr_ldap_option_get
apr_ldap_option_set

◆ APR_LDAP_OPT_RESULT_CODE

#define APR_LDAP_OPT_RESULT_CODE   0x6ff5

Get the most recent result code.

See also
apr_ldap_option_get

◆ APR_LDAP_OPT_TIMEOUT

#define APR_LDAP_OPT_TIMEOUT   0x5002

Get/set the timeout.

See also
apr_ldap_option_get
apr_ldap_option_set

◆ APR_LDAP_OPT_TLS

#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.

See also
apr_ldap_option_set
apr_ldap_option_get
apr_ldap_tls_e

◆ APR_LDAP_OPT_TLS_CERT

#define APR_LDAP_OPT_TLS_CERT   0x6ffe

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

See also
apr_ldap_option_set
apr_ldap_opt_tls_cert_t

◆ APR_LDAP_OPT_URI

#define APR_LDAP_OPT_URI   0x5006

Set the URI to connect to.

Warning
This option (or APR_LDAP_OPT_DESC) must be set before other options, as this initialises the underlying LDAP API.
See also
apr_ldap_option_set

◆ APR_LDAP_OPT_VERIFY_CERT

#define APR_LDAP_OPT_VERIFY_CERT   0x6ffd

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

See also
apr_ldap_option_set
apr_ldap_verify_e

◆ APR_LDAP_PORT

#define APR_LDAP_PORT   389

Ports used by LDAP. ldap:/// default LDAP port

◆ APR_LDAP_URL_ERR_BADATTRS

#define APR_LDAP_URL_ERR_BADATTRS   0x07

Bad (or missing) attributes

See also
apr_ldap_url_parse()

◆ APR_LDAP_URL_ERR_BADENCLOSURE

#define APR_LDAP_URL_ERR_BADENCLOSURE   0x04

URL is missing trailing ">"

See also
apr_ldap_url_parse()

◆ APR_LDAP_URL_ERR_BADEXTS

#define APR_LDAP_URL_ERR_BADEXTS   0x0a

Bad or missing extensions

See also
apr_ldap_url_parse()

◆ APR_LDAP_URL_ERR_BADFILTER

#define APR_LDAP_URL_ERR_BADFILTER   0x09

Bad or missing filter

See also
apr_ldap_url_parse()

◆ APR_LDAP_URL_ERR_BADHOST

#define APR_LDAP_URL_ERR_BADHOST   0x06

Host port is bad

See also
apr_ldap_url_parse()

◆ APR_LDAP_URL_ERR_BADSCHEME

#define APR_LDAP_URL_ERR_BADSCHEME   0x03

URL doesn't begin with "ldap[si]://"

See also
apr_ldap_url_parse()

◆ APR_LDAP_URL_ERR_BADSCOPE

#define APR_LDAP_URL_ERR_BADSCOPE   0x08

Scope string is invalid (or missing)

See also
apr_ldap_url_parse()

◆ APR_LDAP_URL_ERR_BADURL

#define APR_LDAP_URL_ERR_BADURL   0x05

URL is bad

See also
apr_ldap_url_parse()

◆ APR_LDAP_URL_ERR_MEM

#define APR_LDAP_URL_ERR_MEM   0x01

Can't allocate memory space

See also
apr_ldap_url_parse()

◆ APR_LDAP_URL_ERR_PARAM

#define APR_LDAP_URL_ERR_PARAM   0x02

Parameter is bad

See also
apr_ldap_url_parse()

◆ APR_LDAP_URL_SUCCESS

#define APR_LDAP_URL_SUCCESS   0x00

URL was successfully parsed.

See also
apr_ldap_url_parse()

◆ APR_LDAPS_PORT

#define APR_LDAPS_PORT   636

ldaps:/// default LDAP over TLS port

◆ APU_DECLARE_LDAP

#define APU_DECLARE_LDAP ( type)    APR_DECLARE(type)
See also
APR_DECLARE

Typedef Documentation

◆ apr_ldap_apifeature_info_t

typedef struct apr_ldap_apifeature_info_t apr_ldap_apifeature_info_t

Structure returned by passing APR_LDAP_OPT_API_FEATURE_INFO to apr_ldap_option_get().

Use to return details of extensions supported by the underlying API.

See also
apr_ldap_option_get
APR_LDAP_OPT_API_FEATURE_INFO

◆ apr_ldap_apiinfo_t

typedef struct apr_ldap_apiinfo_t apr_ldap_apiinfo_t

Structure returned by passing APR_LDAP_OPT_API_INFO to apr_ldap_option_get().

Use to return information about the underlying LDAP API.

See also
apr_ldap_option_get
APR_LDAP_OPT_API_INFO

◆ apr_ldap_bind_cb

typedef apr_status_t(* apr_ldap_bind_cb) (apr_ldap_t *ldap, apr_status_t status, const char *matcheddn, apr_ldap_control_t **serverctrls, void *ctx, apu_err_t *err)

Callback to receive the results of a bind operation.

When a bind is successful, this function is called with a status of APR_SUCCESS.

Bind success is returned from within apr_ldap_process(), and therefore it can be safely assumed that the underlying socket is writable ready for exactly one further LDAP operation like apr_ldap_search() or apr_ldap_compare().

If the bind fails, status will carry the error code, and err will return the human readable details.

If the underlying LDAP connection has failed, status will return details of the error, allowing an opportunity to clean up.

When complete, return APR_SUCCESS to indicate you want to continue, or a different code if you want the event loop to give up. This code will be returned from apr_ldap_process().

If this callback was called during a pool cleanup, the return value is ignored.

See also
apr_ldap_bind
apr_ldap_process
apr_ldap_result

◆ apr_ldap_bind_interact_cb

typedef apr_status_t apr_ldap_bind_interact_cb(apr_ldap_t *ld, unsigned int flags, apr_ldap_bind_interact_t *interact, void *ctx)

Bind SASL interact callback.

Depending on the type of SASL mechanism chosen, this callback is called to request details needed for each bind.

See also
apr_ldap_bind_interact_t
apr_ldap_bind

◆ apr_ldap_bind_interact_t

typedef struct apr_ldap_bind_interact_t apr_ldap_bind_interact_t

During apr_ldap_bind(), a callback is passed this structure requesting authentication and authorisation details. The callback is expected to fill the buffer with the information requested.

This is used to obtain the information needed for SASL binds.

See also
apr_ldap_bind_interact_e
apr_ldap_bind

◆ apr_ldap_compare_cb

typedef apr_status_t(* apr_ldap_compare_cb) (apr_ldap_t *ldap, apr_status_t status, const char *matcheddn, apr_ldap_control_t **serverctrls, void *ctx, apu_err_t *err)

Callback to receive the results of a compare operation.

When a compare is successful, this function is called with a status of APR_COMPARE_TRUE or APR_COMPARE_FALSE.

If the compare fails, status will carry the error code, and err will return the human readable details.

If the underlying LDAP connection has failed, status will return details of the error, allowing an opportunity to clean up.

When complete, return APR_SUCCESS to indicate you want to continue, or a different code if you want the event loop to give up. This code will be returned from apr_ldap_result().

If this callback was called during a pool cleanup, the return value is ignored.

See also
apr_ldap_compare
apr_ldap_result

◆ apr_ldap_control_t

◆ apr_ldap_driver_t

Opaque structure representing the LDAP driver.

See also
apr_ldap_get_driver

◆ apr_ldap_opt_t

typedef union apr_ldap_opt_t apr_ldap_opt_t

Union of all possible options to be passed to apr_ldap_option_get() and apr_ldap_option_set().

See also
apr_ldap_option_set
apr_ldap_option_get

◆ apr_ldap_opt_tls_cert_t

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_option_set() with the option APR_LDAP_OPT_TLS_CERT to set CA and client certificates.

See also
apr_ldap_option_set
APR_LDAP_OPT_TLS_CERT

◆ apr_ldap_prepare_cb

typedef apr_status_t(* apr_ldap_prepare_cb) (apr_ldap_t *ldap, apr_status_t status, void *ctx, apu_err_t *err)

Callback to prepare an LDAP request.

This callback is scheduled to be fired when the LDAP socket is next writable, from within apr_ldap_process().

When complete, return APR_SUCCESS to indicate you want to continue, or a different code if you want the event loop to give up. This code will be returned from apr_ldap_process().

See also
apr_ldap_prepare
apr_ldap_process

◆ apr_ldap_search_entry_cb

typedef apr_status_t(* apr_ldap_search_entry_cb) (apr_ldap_t *ldap, const char *dn, int eidx, int nattrs, int aidx, const char *attr, int nvals, int vidx, apr_buffer_t *val, int binary, void *ctx, apu_err_t *err)

Callback to receive the entries of a search operation.

This callback is fired once for every attribute and value combination, and then once for each entry to indicate the entry is complete.

When complete, return APR_SUCCESS to indicate you want to continue, or a different code if you want the event loop to give up. This code will be returned from apr_ldap_result().

See also
apr_ldap_search
apr_ldap_result

◆ apr_ldap_search_result_cb

typedef apr_status_t(* apr_ldap_search_result_cb) (apr_ldap_t *ldap, apr_status_t status, apr_size_t count, const char *matcheddn, apr_ldap_control_t **serverctrls, void *ctx, apu_err_t *err)

Callback to receive the results of a search operation.

This callback is fired once for every search.

When a search is complete, this function is called with a status of APR_SUCCESS or APR_NO_RESULTS_RETURNED.

If the search fails, status will carry the error code, and err will return the human readable details.

If the underlying LDAP connection has failed, status will return details of the error, allowing an opportunity to clean up.

When complete, return APR_SUCCESS to indicate you want to continue, or a different code if you want the event loop to give up. This code will be returned from apr_ldap_result().

If this callback was called during a pool cleanup, the return value is ignored.

See also
apr_ldap_search
apr_ldap_result

◆ apr_ldap_t

typedef struct apr_ldap_t apr_ldap_t

Opaque structure tracking the state of an LDAP connection.

See also
apr_ldap_initialise

◆ apr_ldap_url_desc_t

typedef struct apr_ldap_url_desc_t apr_ldap_url_desc_t

Individual fields accessible within an LDAP URL.

See also
apr_ldap_url_parse

Enumeration Type Documentation

◆ apr_ldap_bind_interact_e

LDAP interaction identifiers during LDAP binding

See also
apr_ldap_bind_interact_t
apr_ldap_bind
Enumerator
APR_LDAP_INTERACT_DN 

Distinguished name to use for simple bind

APR_LDAP_INTERACT_GETREALM 

SASL realm for the authentication attempt

APR_LDAP_INTERACT_AUTHNAME 

SASL username to authenticate

APR_LDAP_INTERACT_USER 

SASL username to use for proxy authorization

APR_LDAP_INTERACT_PASS 

SASL password for the provided username / Simple password for a simple bind

APR_LDAP_INTERACT_NOECHOPROMPT 

SASL generic prompt for input with input echoing disabled

APR_LDAP_INTERACT_ECHOPROMPT 

SASL generic prompt for input with input echoing enabled

◆ apr_ldap_deref_e

LDAP deref settings

See also
apr_ldap_option_set
APR_LDAP_OPT_DEREF
Enumerator
APR_LDAP_DEREF_NEVER 

Aliases should never be dereferenced

APR_LDAP_DEREF_SEARCHING 

Aliases should be dereferenced during the search, but not when locating the base object of the search.

APR_LDAP_DEREF_FINDING 

Aliases should be dereferenced when locating the base object, but not during the search.

APR_LDAP_DEREF_ALWAYS 

Aliases should always be dereferenced

◆ apr_ldap_protocol_version_e

LDAP Protocol Versions.

See also
apr_ldap_option_set
APR_LDAP_OPT_PROTOCOL_VERSION
Enumerator
APR_LDAP_VERSION1 

LDAP version 1

APR_LDAP_VERSION2 

LDAP version 2

APR_LDAP_VERSION3 

LDAP version 3

◆ apr_ldap_search_scope_e

APR search scopes

See also
apr_ldap_search
Enumerator
APR_LDAP_SCOPE_BASE 

base object search

APR_LDAP_SCOPE_ONELEVEL 

one-level search

APR_LDAP_SCOPE_SUBTREE 

subtree search

APR_LDAP_SCOPE_SUBORDINATE 

subordinate search

◆ apr_ldap_switch_e

LDAP options on or off

See also
apr_ldap_option_set
APR_LDAP_OPT_REFERRALS
Enumerator
APR_LDAP_OPT_OFF 

Option set off

APR_LDAP_OPT_ON 

Option set on

◆ apr_ldap_tls_e

APR_LDAP_OPT_TLS

This sets the SSL level on the LDAP handle.

See also
APR_LDAP_OPT_TLS
apr_ldap_option_set
Enumerator
APR_LDAP_TLS_NONE 

No encryption

APR_LDAP_TLS_SSL 

SSL encryption (ldaps://)

APR_LDAP_TLS_STARTTLS 

TLS encryption (STARTTLS)

APR_LDAP_TLS_STOPTLS 

end TLS encryption (STOPTLS)

◆ apr_ldap_verify_e

LDAP TLS verify options

See also
APR_LDAP_OPT_VERIFY_CERT
apr_ldap_option_set
Enumerator
APR_LDAP_VERIFY_OFF 

Disable TLS verification (this is an insecure setting)

APR_LDAP_VERIFY_ON 

Enable TLS verification

Function Documentation

◆ apr_ldap_bind()

apr_status_t apr_ldap_bind ( apr_pool_t * pool,
apr_ldap_t * ldap,
const char * mech,
apr_ldap_bind_interact_cb * interact_cb,
void * interact_ctx,
apr_interval_time_t timeout,
apr_ldap_bind_cb bind_cb,
void * bind_ctx,
apu_err_t * err )

APR LDAP bind function

This function initiates a bind on a previously initialised LDAP connection to the directory.

Pass the required SASL mechanism in mech, or set to NULL for a simple bind.

Unlike the native LDAP APIs, this function muct be called just once. The job of binding is done inside apr_ldap_process() and apr_ldap_result().

Binds are attempted asynchronously. For non blocking behaviour, this function must be called after the underlying socket has indicated that it is ready to write.

In the absence of an error, apr_ldap_bind will return APR_WANT_READ to indicate that the next message in the conversation be retrieved using apr_ldap_result().

The outcome of the bind will be retrieved and handled by the apr_ldap_process() function, and the outcome is passed to the apr_ldap_bind_cb provided.

Parameters
poolThe pool that keeps track of the lifetime of the bind conversation. If this pool is cleaned up, the bind conversation will be gracefully abandoned without affecting other LDAP requests in progress. This pool need not have any relationship with the LDAP connection pool.
ldapThe ldap handle
mechThe SASL mechanism. Pass NULL for simple bind.
interact_cbThe SASL interactive callback function. This function is is called to request credentials for the bind, depending on the mechanism.
interact_ctxContext passed to the interactive callback.
timeoutThe timeout to use for writes.
bind_cbThe bind result callback function. When the bind process has completed the success or failure of the bind is returned here. The callback is triggered from inside apr_ldap_process() so that it is safe to write the next LDAP request.
bind_ctxContext passed to the bind callback.
errError structure for reporting detailed results.
Returns
APR_WANT_READ means that processing has occurred, and the message in reply needs to be fetched using apr_ldap_result(). APR_WANT_WRITE means that processing has occurred, and the conversation needs to be continued with a call to apr_ldap_process(). APR_SUCCESS means that the processing is complete, and the bind has been successful. Other error codes indicate that the bind was not successful.
See also
apr_ldap_bind_interact_cb
apr_ldap_bind_cb
apr_ldap_process
apr_ldap_result

◆ apr_ldap_compare()

apr_status_t apr_ldap_compare ( apr_pool_t * pool,
apr_ldap_t * ldap,
const char * dn,
const char * attr,
const apr_buffer_t * val,
apr_ldap_control_t ** serverctrls,
apr_ldap_control_t ** clientctrls,
apr_interval_time_t timeout,
apr_ldap_compare_cb compare_cb,
void * ctx,
apu_err_t * err )

APR LDAP compare function

This function compares a string or binary value of an attribute within an entry described by the given distinguished name against a previously initialised LDAP connection to the directory.

Compares are attempted asynchronously. For non blocking behaviour, this function must be called after the underlying socket has indicated that it is ready to write.

In the absence of an error, apr_ldap_compare will return APR_WANT_READ to indicate that the next message in the conversation be retrieved using apr_ldap_result().

The outcome of the compare will be retrieved and handled by the apr_ldap_process() function, and the outcome is passed to the apr_ldap_compare_cb provided.

Parameters
poolThe pool that keeps track of the lifetime of the compare conversation. If this pool is cleaned up, the compare conversation will be gracefully abandoned without affecting other LDAP requests in progress. This pool need not have any relationship with the LDAP connection pool.
ldapThe ldap handle
dnThe distinguished named of the object to compare.
attrThe attribute of the object to compare.
valThe value to be compared to the attribute. The value can be zero terminated text, or binary.
serverctrlsNULL terminated array of server controls.
clientctrlsNULL terminated array of client controls.
timeoutThe timeout to use for writes.
compare_cbThe compare result callback function. When the compare process has completed the success or failure of the compare is returned here. The callback is triggered from inside apr_ldap_process() so that it is safe to write the next LDAP request.
ctxContext passed to the compare callback.
errError structure for reporting detailed results.
Returns
APR_WANT_READ means that processing has occurred, and the message in reply needs to be fetched using apr_ldap_result(). APR_SUCCESS means that the processing is complete, and the bind has been successful. Other error codes indicate that the bind was not successful.
See also
apr_ldap_compare_cb
apr_ldap_process
apr_ldap_result

◆ apr_ldap_connect()

apr_status_t apr_ldap_connect ( apr_pool_t * pool,
apr_ldap_t * ldap,
apr_interval_time_t timeout,
apu_err_t * result_err )

APR LDAP connect function.

This function makes an attempt to connect to the server initialised by apr_ldap_initialise().

While other functions will connect if not connected, use this function to explicitly handle errors in the connect case.

This function will synchronously perform DNS lookups and TLS negotiation and will block if needed.

If you need asynchronous handling, perform the DNS and TLS handling yourself, and then pass the socket with APR_LDAP_OPT_DESC.

Returns
APR_SUCCESS means that the connection connected successfully. Other error codes indicate that the connect was not successful.

◆ apr_ldap_get_driver()

apr_status_t apr_ldap_get_driver ( apr_pool_t * pool,
const apr_ldap_driver_t ** driver,
apu_err_t * err )

apr_ldap_get_driver: get the driver struct for a name

The LDAP driver is unique in that LDAP libraries are almost exclusively derived from RFC1823 "The LDAP Application Program Interface".

As a result, unlike other drivers for other subsystems in APR, two different drivers cannot be loaded at once, as the underlying libraries share common symbols with one another.

For this reason we have exactly one driver available at a time.

This function loads the library, and registers a cleanup with the pool provided to unload the library.

This function can be called multiple times by independent code, cleanups are reference counted so the last pool cleanup unloads the library.

Calling this function explicitly is optional, and would be done to have complete control over the lifetime of the driver.

If this function is not called explicitly, this function will be called if needed before the apr_ldap_info(), apr_ldap_initialise(), apr_ldap_option_get(), and apr_ldap_option_set() functions, registering cleanups in the pools provided to those functions if needed.

Parameters
pool(process) pool to register cleanup that will unload the library. Cleanup is reference counted so the driver is unloaded on last access.
driverPointer to driver struct. Can be NULL.
errHuman readable error messages
Returns
APR_SUCCESS for success
APR_ENOTIMPL for no driver (when DSO not enabled)
APR_EDSOOPEN if DSO driver file can't be opened
APR_ESYMNOTFOUND if the driver file doesn't contain a driver

◆ apr_ldap_info()

apr_status_t apr_ldap_info ( apr_pool_t * pool,
apu_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
poolThe pool to use
result_errThe returned result

◆ apr_ldap_initialise()

apr_status_t apr_ldap_initialise ( apr_pool_t * pool,
apr_ldap_t ** ldap,
apu_err_t * 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_initialize() from the C api.

The setting of the LDAP server to connect is made after this function returns, using the apr_ldap_option_set() call with APR_LDAP_OPT_DESC or APR_LDAP_OPT_URI.

A cleanup for the connection is registered in the given pool.

Parameters
poolThe pool to use
ldapThe ldap context returned
errOn error, error details are written to the structure.
See also
apr_ldap_option_set
APR_LDAP_OPT_DESC
APR_LDAP_OPT_URI

◆ apr_ldap_is_ldap_url()

int apr_ldap_is_ldap_url ( const char * url)

Is this URL an ldap url? ldap://

Parameters
urlThe url to test

◆ apr_ldap_is_ldapi_url()

int apr_ldap_is_ldapi_url ( const char * url)

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

Parameters
urlThe url to test

◆ apr_ldap_is_ldaps_url()

int apr_ldap_is_ldaps_url ( const char * url)

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

Parameters
urlThe url to test

◆ apr_ldap_option_get()

apr_status_t apr_ldap_option_get ( apr_pool_t * pool,
apr_ldap_t * ldap,
int option,
apr_ldap_opt_t * outvalue,
apu_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
poolThe pool to use where needed
ldapThe LDAP handle
optionThe LDAP_OPT_* option to return
outvalueThe value returned (if any)
result_errOn error, error details are written to the structure.
See also
APR_LDAP_OPT_API_FEATURE_INFO
APR_LDAP_OPT_API_INFO
APR_LDAP_OPT_DEREF
APR_LDAP_OPT_DESC
APR_LDAP_OPT_HANDLE
APR_LDAP_OPT_NETWORK_TIMEOUT
APR_LDAP_OPT_PROTOCOL_VERSION
APR_LDAP_OPT_REFERRALS
APR_LDAP_OPT_REFHOPLIMIT
APR_LDAP_OPT_RESULT_CODE
APR_LDAP_OPT_TIMEOUT

◆ apr_ldap_option_set()

apr_status_t apr_ldap_option_set ( apr_pool_t * pool,
apr_ldap_t * ldap,
int option,
const apr_ldap_opt_t * invalue,
apu_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
poolThe pool to use where needed
ldapThe LDAP handle
optionThe LDAP_OPT_* option to set
invalueThe value to set
result_errOn error, error details are written to the structure.
See also
APR_LDAP_OPT_DEREF
APR_LDAP_OPT_DESC
APR_LDAP_OPT_NETWORK_TIMEOUT
APR_LDAP_OPT_PROTOCOL_VERSION
APR_LDAP_OPT_REFERRALS
APR_LDAP_OPT_REFHOPLIMIT
APR_LDAP_OPT_TIMEOUT
APR_LDAP_OPT_TLS
APR_LDAP_OPT_TLS_CERT
APR_LDAP_OPT_URI
APR_LDAP_OPT_VERIFY_CERT

◆ apr_ldap_poll()

apr_status_t apr_ldap_poll ( apr_pool_t * pool,
apr_ldap_t * ldap,
apr_pollcb_t * poll,
apr_interval_time_t timeout,
apu_err_t * err )

APR LDAP poll function.

For applications that need simple set of queries, this function provides an event loop that can handle a series of LDAP requests.

This function calls apr_ldap_process() and apr_ldap_result() as needed.

Parameters
poolThe pool to use
ldapThe LDAP handle
timeoutThe timeout to use for reads and writes.
errError structure for reporting detailed results.
Returns
APR_SUCCESS means that no further processing is needed. Other error codes indicate that processing was not successful.

◆ apr_ldap_prepare()

apr_status_t apr_ldap_prepare ( apr_pool_t * pool,
apr_ldap_t * ldap,
apr_ldap_prepare_cb prepare_cb,
void * prepare_ctx )

APR LDAP prepare function

This function schedules a generic callback, fired the next time the LDAP socket is writable.

This callback can be used to prepare the initial LDAP request, or to prepare additional requests as needed without blocking.

Parameters
poolThe pool that keeps track of the lifetime of the callback. If this pool is cleaned up, the callback will be will be gracefully removed without affecting other LDAP requests in progress. This pool need not have any relationship with the LDAP connection pool.
ldapThe ldap handle
prepare_cbThe prepare callback function. When apr_ldap_process() is next called this callback will be triggered in the expectation of the next LDAP request.
prepare_ctxContext passed to the prepare callback.
errError structure for reporting detailed results.
Returns
APR_SUCCESS means the callback was successfully prepared. Other error codes indicate that the attept to send the cancellation was not successful.

◆ apr_ldap_process()

apr_status_t apr_ldap_process ( apr_pool_t * pool,
apr_ldap_t * ldap,
apr_interval_time_t timeout,
apu_err_t * err )

APR process function.

This function performs outstanding processing of any LDAP conversations currently in progress.

When a request tells you that further processing is needed, schedule this call the next time the socket is writable.

Most callbacks are fired from within apr_ldap_process() so that we are ready to write the next LDAP query should that be needed.

Parameters
poolThe pool to use
ldapThe LDAP handle
timeoutThe timeout to use for writes.
errError structure for reporting detailed results.
Returns
APR_WANT_WRITE means that at least one further process is outstanding and a further write callback should be scheduled. APR_WANTS_READ indicates the a request has been sent and we're waiting for the response. APR_SUCCESS means that no further processing is needed. Other error codes indicate that the processing of outstanding conversations was not successful.

◆ apr_ldap_result()

apr_status_t apr_ldap_result ( apr_pool_t * pool,
apr_ldap_t * ldap,
apr_interval_time_t timeout,
apu_err_t * err )

APR result function.

This function returns the result of a previous request, ready for further processing.

Parameters
poolThe pool to use
ldapThe LDAP handle
timeoutThe timeout to use for writes.
errError structure for reporting detailed results.
Returns
APR_WANT_WRITE means that at least one further process is outstanding and a further write callback should be scheduled. APR_WANTS_READ indicates more responses are expected and we're waiting for the response. APR_SUCCESS means that no further processing is needed. Other error codes indicate that the processing of outstanding conversations was not successful.

◆ apr_ldap_search()

apr_status_t apr_ldap_search ( apr_pool_t * pool,
apr_ldap_t * ldap,
const char * dn,
apr_ldap_search_scope_e scope,
const char * filter,
const char ** attrs,
apr_ldap_switch_e attrsonly,
apr_ldap_control_t ** serverctrls,
apr_ldap_control_t ** clientctrls,
apr_interval_time_t timeout,
apr_ssize_t sizelimit,
apr_ldap_search_result_cb search_result_cb,
apr_ldap_search_entry_cb search_entry_cb,
void * ctx,
apu_err_t * err )

APR LDAP search function

This function searches a previously initialised LDAP connection to the directory.

Searches are attempted asynchronously. For non blocking behaviour, this function must be called after the underlying socket has indicated that it is ready to write.

In the absence of an error, apr_ldap_search will return APR_WANT_READ to indicate that the next message in the conversation be retrieved using apr_ldap_result().

The outcome of the search will be retrieved and handled by the apr_ldap_result() function as each result arrives.

If one or more results are returned, the apr_ldap_search_entry_cb callback is called once for each attribute and value combination.

At the end of each entry, apr_ldap_search_entry_cb will be called with no attribute or value, giving code an opportunity to perform any processing only possible after all of the entries have been retrieved.

Once all entries have been processed, apr_ldap_search_result_cb is called to indicate the final result of the search.

If no entries are returned, only apr_ldap_search_result_cb will be called.

Parameters
poolThe pool that keeps track of the lifetime of the search conversation. If this pool is cleaned up, the search conversation will be gracefully abandoned without affecting other LDAP requests in progress. This pool need not have any relationship with the LDAP connection pool.
ldapThe ldap handle
dnThe base distinguished named of the search.
scopeThe scope of the search.
filterThe search filter string.
attrsNULL terminated array of attributes to return.
attrsonlyIf on, attributes will be returned without values.
serverctrlsNULL terminated array of server controls.
clientctrlsNULL terminated array of client controls.
timeoutThe timeout to use for writes.
sizelimitThe maximum number of entries to return in the search.
search_result_cbThe search result callback function. When the search process has completed the success or failure of the search is returned here. The callback is triggered from inside apr_ldap_process() so that it is safe to write the next LDAP request.
search_entry_cbThe search entry callback function. For each value of each attribute of each entry, this callback is called with each value. This callback is then fired off one more time at the end of each entry, giving the chance to handle that entry. The callback is triggered from inside apr_ldap_result().
ctxContext passed to the search result and search entry callbacks.
errError structure for reporting detailed results.
Returns
APR_WANT_READ means that processing has occurred, and the message in reply needs to be fetched using apr_ldap_result(). Other error codes indicate that the search attempt was not successful.
See also
apr_ldap_search_entry_cb
apr_ldap_search_result_cb
apr_ldap_result

◆ apr_ldap_unbind()

apr_status_t apr_ldap_unbind ( apr_ldap_t * ldap,
apr_ldap_control_t ** serverctrls,
apr_ldap_control_t ** clientctrls,
apu_err_t * err )

APR LDAP unbind function

This function unbinds from the LDAP server, and frees the connection handle.

Calling this function is optional, the same effect can be achieved by cleaning up the pool passed to apr_ldap_initialise().

See also
apr_ldap_initialise

◆ apr_ldap_url_parse()

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

Parse an LDAP URL.

Parameters
poolThe pool to use
url_inThe URL to parse
ludppThe structure to return the exploded URL
result_errThe result structure of the operation

◆ apr_ldap_url_parse_ext()

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

Parse an LDAP URL.

Parameters
poolThe pool to use
url_inThe URL to parse
ludppThe structure to return the exploded URL
result_errThe result structure of the operation