Asynchronous connection management functions for LDAP. More...

#include <freeradius-devel/ldap/base.h>
#include <freeradius-devel/util/debug.h>

Include dependency graph for connection.c:

Macros
#define	do_ldap_option(_option, _name, _value)

#define	maybe_ldap_option(_option, _name, _value) if (_value) do_ldap_option(_option, _name, _value)

#define	POPULATE_LDAP_CONTROLS(_dest, _src)

Functions
static void	_ldap_connection_close_watch (connection_t conn, UNUSED connection_state_t prev, UNUSED connection_state_t state, void uctx)
	Watcher for LDAP connections being closed.

static int	_ldap_connection_free (fr_ldap_connection_t *c)
	Close and delete a connection.

static void	_ldap_trunk_idle_timeout (fr_timer_list_t tl, UNUSED fr_time_t now, void uctx)
	Callback for closing idle LDAP trunk.

static int	_thread_ldap_trunk_free (fr_ldap_thread_trunk_t *ttrunk)

fr_ldap_connection_t *	fr_ldap_connection_alloc (TALLOC_CTX *ctx)
	Allocate our ldap connection handle layer.

void	fr_ldap_connection_close (fr_event_list_t el, void h, UNUSED void *uctx)
	Free the handle, closing the connection to ldap.

int	fr_ldap_connection_configure (fr_ldap_connection_t c, fr_ldap_config_t const config)
	Allocate and configure a new connection.

connection_state_t	fr_ldap_connection_init (void *h, connection_t conn, void *uctx)
	Initialise a standalone LDAP connection.

int	fr_ldap_connection_timeout_reset (fr_ldap_connection_t const *c)

int	fr_ldap_connection_timeout_set (fr_ldap_connection_t const *c, fr_time_delta_t timeout)

connection_state_t	fr_ldap_trunk_connection_init (void *h, connection_t conn, void *uctx)
	Initialise an LDAP trunk connection.

fr_ldap_thread_trunk_t *	fr_thread_ldap_bind_trunk_get (fr_ldap_thread_t *thread)
	Find the thread specific trunk to use for LDAP bind auths.

fr_ldap_thread_trunk_t *	fr_thread_ldap_trunk_get (fr_ldap_thread_t thread, char const uri, char const bind_dn, char const bind_password, request_t request, fr_ldap_config_t const config)
	Find a thread specific LDAP connection for a specific URI / bind DN.

trunk_state_t	fr_thread_ldap_trunk_state (fr_ldap_thread_t thread, char const uri, char const *bind_dn)
	Lookup the state of a thread specific LDAP connection trunk for a specific URI / bind DN.

static void	ldap_bind_auth_cancel_mux (UNUSED fr_event_list_t el, trunk_connection_t tconn, connection_t conn, UNUSED void uctx)
	Callback to cancel LDAP bind auth.

static connection_state_t	ldap_connection_init (void *h, connection_t conn, fr_ldap_config_t const config, fr_ldap_directory_t directory)
	(Re-)Initialises the libldap side of the connection handle

static void	ldap_request_cancel (UNUSED connection_t conn, void preq, UNUSED trunk_cancel_reason_t reason, UNUSED void *uctx)
	Callback when an LDAP trunk request is cancelled.

static void	ldap_request_cancel_mux (UNUSED fr_event_list_t el, trunk_connection_t tconn, connection_t conn, UNUSED void uctx)
	Callback to cancel LDAP queries.

static void	ldap_request_fail (request_t request, void preq, UNUSED void rctx, UNUSED trunk_request_state_t state, UNUSED void uctx)
	Callback to tidy up when a trunk request fails.

static void	ldap_trunk_bind_auth_demux (UNUSED fr_event_list_t el, UNUSED trunk_connection_t tconn, connection_t conn, void uctx)
	Read LDAP bind auth responses.

static void	ldap_trunk_bind_auth_fail (request_t request, void preq, UNUSED void rctx, UNUSED trunk_request_state_t state, UNUSED void uctx)
	Callback to tidy up when a bind auth trunk request fails.

static void	ldap_trunk_bind_auth_mux (UNUSED fr_event_list_t el, trunk_connection_t tconn, connection_t conn, void uctx)
	Take pending LDAP bind auths from the queue and send them.

static connection_t *	ldap_trunk_connection_alloc (trunk_connection_t tconn, fr_event_list_t el, UNUSED connection_conf_t const conn_conf, char const log_prefix, void *uctx)
	Allocate an LDAP trunk connection.

static void	ldap_trunk_request_demux (fr_event_list_t el, trunk_connection_t tconn, connection_t conn, void uctx)
	Read LDAP responses.

static void	ldap_trunk_request_mux (UNUSED fr_event_list_t el, trunk_connection_t tconn, connection_t conn, UNUSED void uctx)
	Take LDAP pending queries from the queue and send them.

Variables
static USES_APPLE_DEPRECATED_API char const *	ldap_msg_types [UINT8_MAX+1]

Detailed Description

Asynchronous connection management functions for LDAP.

Id: 42018db7faf19e2db5cdd93df92c12f895e34166

Copyright: 2017 Arran Cudbard-Bell (a.cud.nosp@m.bard.nosp@m.b@fre.nosp@m.erad.nosp@m.ius.o.nosp@m.rg)

Definition in file connection.c.

Macro Definition Documentation

◆ do_ldap_option

#define do_ldap_option	(	_option,
		_name,
		_value
	)

Value:

        if (ldap_set_option(c->handle, _option, _value) != LDAP_OPT_SUCCESS) do { \
                ldap_get_option(c->handle, LDAP_OPT_ERROR_NUMBER, &ldap_errno); \
                ERROR("Failed setting connection option %s: %s", _name, \
                      (ldap_errno != LDAP_SUCCESS) ? ldap_err2string(ldap_errno) : "Unknown error"); \
                goto error;\
        } while (0)

◆ maybe_ldap_option

#define maybe_ldap_option	(	_option,
		_name,
		_value
	)	if (_value) do_ldap_option(_option, _name, _value)

◆ POPULATE_LDAP_CONTROLS

#define POPULATE_LDAP_CONTROLS	(	_dest,
		_src
	)

Value:

        do { \
        int i; \
        for (i = 0; (i < LDAP_MAX_CONTROLS) && (_src[i].control); i++) { \
                _dest[i] = _src[i].control; \
        } \
        _dest[i] = NULL; \
} while (0)

Definition at line 574 of file connection.c.

Function Documentation

◆ _ldap_connection_close_watch()

static void _ldap_connection_close_watch	(	connection_t *	conn,
		UNUSED connection_state_t	prev,
		UNUSED connection_state_t	state,
		void *	uctx
	)

static

Watcher for LDAP connections being closed.

If there are any outstanding queries on the connection then re-parent the connection to the NULL ctx so that it remains until all the queries have been dealt with.

Definition at line 286 of file connection.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ _ldap_connection_free()

static int _ldap_connection_free ( fr_ldap_connection_t * c )

static

Close and delete a connection.

Unbinds the LDAP connection, informing the server and freeing any memory, then releases the memory used by the connection handle.

Parameters

[in] c to destroy.

Returns: always indicates success.

Definition at line 221 of file connection.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ _ldap_trunk_idle_timeout()

static void _ldap_trunk_idle_timeout	(	fr_timer_list_t *	tl,
		UNUSED fr_time_t	now,
		void *	uctx
	)

static

Callback for closing idle LDAP trunk.

Definition at line 462 of file connection.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ _thread_ldap_trunk_free()

static int _thread_ldap_trunk_free ( fr_ldap_thread_trunk_t * ttrunk )

static

Definition at line 919 of file connection.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ fr_ldap_connection_alloc()

fr_ldap_connection_t * fr_ldap_connection_alloc ( TALLOC_CTX * ctx )

Allocate our ldap connection handle layer.

This is using handles outside of the connection state machine.

Parameters

[in] ctx to allocate connection handle in.

Returns

A new unbound/unconfigured connection handle on success. Call f::r_ldap_connection_configure next.
NULL on OOM.

Definition at line 258 of file connection.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ fr_ldap_connection_close()

void fr_ldap_connection_close	(	fr_event_list_t *	el,
		void *	h,
		UNUSED void *	uctx
	)

Free the handle, closing the connection to ldap.

Parameters

[in]	el	UNUSED.
[in]	h	to close.
[in]	uctx	Connection config and handle.

Definition at line 195 of file connection.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ fr_ldap_connection_configure()

int fr_ldap_connection_configure	(	fr_ldap_connection_t *	c,
		fr_ldap_config_t const *	config
	)

Allocate and configure a new connection.

Configures both our ldap handle, and libldap's handle.

This can be used by async code and async code as no attempt is made to connect to the LDAP server. An attempt will only be made if ldap_start_tls* or ldap_bind* functions are called.

If called on an fr_ldap_connection_t which has already been initialised, will clear any memory allocated to the connection, unbind the ldap handle, and reinitialise everything.

Parameters

[in]	c	to configure.
[in]	config	to apply.

Returns

0 on success.
-1 on error.

Definition at line 67 of file connection.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ fr_ldap_connection_init()

connection_state_t fr_ldap_connection_init	(	void **	h,
		connection_t *	conn,
		void *	uctx
	)

Initialise a standalone LDAP connection.

Parameters

[out]	h	Underlying file descriptor from libldap handle.
[in]	conn	Being initialised.
[in]	uctx	Connection configuration (a fr_ldap_config_t).

Returns

CONNECTION_STATE_CONNECTING on success.
CONNECTION_STATE_FAILED on failure.

Definition at line 391 of file connection.c.

Here is the call graph for this function:

◆ fr_ldap_connection_timeout_reset()

int fr_ldap_connection_timeout_reset ( fr_ldap_connection_t const * c )

Definition at line 437 of file connection.c.

Here is the caller graph for this function:

◆ fr_ldap_connection_timeout_set()

int fr_ldap_connection_timeout_set	(	fr_ldap_connection_t const *	c,
		fr_time_delta_t	timeout
	)

Definition at line 415 of file connection.c.

Here is the caller graph for this function:

◆ fr_ldap_trunk_connection_init()

connection_state_t fr_ldap_trunk_connection_init	(	void **	h,
		connection_t *	conn,
		void *	uctx
	)

Initialise an LDAP trunk connection.

Parameters

[out]	h	Underlying file descriptor from libldap handle.
[in]	conn	Being initialised.
[in]	uctx	Trunk the connection belongs to (a fr_ldap_thread_trunk_t).

Returns

CONNECTION_STATE_CONNECTING on success.
CONNECTION_STATE_FAILED on failure.

Definition at line 408 of file connection.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ fr_thread_ldap_bind_trunk_get()

fr_ldap_thread_trunk_t * fr_thread_ldap_bind_trunk_get ( fr_ldap_thread_t * thread )

Find the thread specific trunk to use for LDAP bind auths.

If there is no current trunk then a new one is created.

Parameters

[in] thread to which the connection belongs

Returns

an existing or new trunk.
NULL on failure

Definition at line 1331 of file connection.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ fr_thread_ldap_trunk_get()

fr_ldap_thread_trunk_t * fr_thread_ldap_trunk_get	(	fr_ldap_thread_t *	thread,
		char const *	uri,
		char const *	bind_dn,
		char const *	bind_password,
		request_t *	request,
		fr_ldap_config_t const *	config
	)

Find a thread specific LDAP connection for a specific URI / bind DN.

If no existing connection exists for that combination then create a new one

Parameters

[in]	thread	to which the connection belongs
[in]	uri	of the host to find / create a connection to
[in]	bind_dn	to make the connection as
[in]	bind_password	for making connection
[in]	request	currently being processed (only for debug messages)
[in]	config	LDAP config of the module requesting the connection.

Returns

an existing or new connection matching the URI and bind DN
NULL on failure

Definition at line 940 of file connection.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ fr_thread_ldap_trunk_state()

trunk_state_t fr_thread_ldap_trunk_state	(	fr_ldap_thread_t *	thread,
		char const *	uri,
		char const *	bind_dn
	)

Lookup the state of a thread specific LDAP connection trunk for a specific URI / bind DN.

Parameters

[in]	thread	to which the connection belongs
[in]	uri	of the host to find / create a connection to
[in]	bind_dn	to make the connection as

Returns

State of a trunk matching the URI and bind DN
TRUNK_STATE_MAX if no matching trunk

Definition at line 1032 of file connection.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ ldap_bind_auth_cancel_mux()

static void ldap_bind_auth_cancel_mux	(	UNUSED fr_event_list_t *	el,
		trunk_connection_t *	tconn,
		connection_t *	conn,
		UNUSED void *	uctx
	)

static

Callback to cancel LDAP bind auth.

Inform the remote LDAP server that we no longer want responses to specific bind.

Parameters

[in]	el	For timer management.
[in]	tconn	The trunk connection handle
[in]	conn	The specific connection binds will be cancelled on
[in]	uctx	Context provided to trunk_alloc

Definition at line 1273 of file connection.c.

Here is the call graph for this function:

◆ ldap_connection_init()

static connection_state_t ldap_connection_init	(	void **	h,
		connection_t *	conn,
		fr_ldap_config_t const *	config,
		fr_ldap_directory_t *	directory
	)

static

(Re-)Initialises the libldap side of the connection handle

The first ldap state transition is either:

init -> start tls or init -> bind

Either way libldap will try an open the connection so when fr_ldap_state_next returns we should have the file descriptor to pass back.

The complete order of operations is:

Initialise the libldap handle with fr_ldap_connection_configure (calls ldap_init)
Initiate the connection with fr_ldap_state_next, which either binds or calls start_tls.
Either operation calls ldap_send_server_request.
- Which calls ldap_new_connection.
- Which calls ldap_int_open_connection.
- Which calls ldap_connect_to_(host|path) and adds socket buffers, and possibly calls ldap_int_tls_start (for ldaps://).
- When ldap_new_connection returns, because LDAP_OPT_CONNECT_ASYNC is set to LDAP_OPT_ON, lc->lconn_status is set to LDAP_CONNST_CONNECTING.
- ldap_send_server_request checks for lconn_stats == LDAP_CONNST_CONNECTING, and calls ldap_int_poll, which checks the fd for error conditions and immediately returns due to the network timeout value.
- If the socket is not yet connected:
  - As network timeout on the LDAP handle is 0, ld->ld_errno is set to LDAP_X_CONNECTING. ldap_send_server_request returns -1.
  - bind or start_tls errors with LDAP_X_CONNECTING without sending the request.
  - We install a write I/O handler, and wait to be called again, then we retry the operation.
- else
  - the bind or start_tls operation succeeds, our ldap state machine advances, the connection callback is called and our socket state machine transitions to connected.
Continue running the state machine

Parameters

[out]	h	Underlying file descriptor from libldap handle.
[in]	conn	Being initialised.
[in]	config	LDAP connection configuration.
[in]	directory	Where the properties of the directory being connected to are recorded. May be NULL if directory discovery is not being performed.

Returns

CONNECTION_STATE_CONNECTING on success.
CONNECTION_STATE_FAILED on failure.

Definition at line 343 of file connection.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ ldap_request_cancel()

static void ldap_request_cancel	(	UNUSED connection_t *	conn,
		void *	preq,
		UNUSED trunk_cancel_reason_t	reason,
		UNUSED void *	uctx
	)

static

Callback when an LDAP trunk request is cancelled.

Ensure the request is removed from the list of outstanding requests

Definition at line 483 of file connection.c.

Here is the call graph for this function:

◆ ldap_request_cancel_mux()

static void ldap_request_cancel_mux	(	UNUSED fr_event_list_t *	el,
		trunk_connection_t *	tconn,
		connection_t *	conn,
		UNUSED void *	uctx
	)

static

Callback to cancel LDAP queries.

Inform the remote LDAP server that we no longer want responses to specific queries.

Parameters

[in]	el	For timer management.
[in]	tconn	The trunk connection handle
[in]	conn	The specific connection queries will be cancelled on
[in]	uctx	Context provided to trunk_alloc

Definition at line 503 of file connection.c.

Here is the call graph for this function:

◆ ldap_request_fail()

static void ldap_request_fail	(	request_t *	request,
		void *	preq,
		UNUSED void *	rctx,
		UNUSED trunk_request_state_t	state,
		UNUSED void *	uctx
	)

static

Callback to tidy up when a trunk request fails.

Definition at line 521 of file connection.c.

Here is the call graph for this function:

◆ ldap_trunk_bind_auth_demux()

static void ldap_trunk_bind_auth_demux	(	UNUSED fr_event_list_t *	el,
		UNUSED trunk_connection_t *	tconn,
		connection_t *	conn,
		void *	uctx
	)

static

Read LDAP bind auth responses.

Parameters

[in]	el	To insert timers into.
[in]	tconn	Trunk connection associated with these results.
[in]	conn	Connection handle for these results.
[in]	uctx	Thread specific trunk structure - contains tree of pending queries.

Definition at line 1154 of file connection.c.

Here is the call graph for this function:

◆ ldap_trunk_bind_auth_fail()

static void ldap_trunk_bind_auth_fail	(	request_t *	request,
		void *	preq,
		UNUSED void *	rctx,
		UNUSED trunk_request_state_t	state,
		UNUSED void *	uctx
	)

static

Callback to tidy up when a bind auth trunk request fails.

Definition at line 1303 of file connection.c.

Here is the call graph for this function:

◆ ldap_trunk_bind_auth_mux()

static void ldap_trunk_bind_auth_mux	(	UNUSED fr_event_list_t *	el,
		trunk_connection_t *	tconn,
		connection_t *	conn,
		void *	uctx
	)

static

Take pending LDAP bind auths from the queue and send them.

Parameters

[in]	el	Event list for timers.
[in]	tconn	Trunk handle.
[in]	conn	on which to send the queries
[in]	uctx	User context passed to trunk_alloc

Definition at line 1049 of file connection.c.

Here is the call graph for this function:

◆ ldap_trunk_connection_alloc()

static connection_t * ldap_trunk_connection_alloc	(	trunk_connection_t *	tconn,
		fr_event_list_t *	el,
		UNUSED connection_conf_t const *	conn_conf,
		char const *	log_prefix,
		void *	uctx
	)

static

Allocate an LDAP trunk connection.

Parameters

[in]	tconn	Trunk handle.
[in]	el	Event list which will be used for I/O and timer events.
[in]	conn_conf	Configuration of the connection.
[in]	log_prefix	What to prefix log messages with.
[in]	uctx	User context passed to trunk_alloc.

Definition at line 549 of file connection.c.

Here is the call graph for this function:

◆ ldap_trunk_request_demux()

static void ldap_trunk_request_demux	(	fr_event_list_t *	el,
		trunk_connection_t *	tconn,
		connection_t *	conn,
		void *	uctx
	)

static

Read LDAP responses.

Responses from the LDAP server will cause the fd to become readable and trigger this callback. Most LDAP search responses have multiple messages in their response - we only gather those which are complete before either following a referral or passing the head of the resulting chain of messages back.

Parameters

[in]	el	To insert timers into.
[in]	tconn	Trunk connection associated with these results.
[in]	conn	Connection handle for these results.
[in]	uctx	Thread specific trunk structure - contains tree of pending queries.

Definition at line 711 of file connection.c.

Here is the call graph for this function:

◆ ldap_trunk_request_mux()

static void ldap_trunk_request_mux	(	UNUSED fr_event_list_t *	el,
		trunk_connection_t *	tconn,
		connection_t *	conn,
		UNUSED void *	uctx
	)

static

Take LDAP pending queries from the queue and send them.

Parameters

[in]	el	Event list for timers.
[in]	tconn	Trunk handle.
[in]	conn	on which to send the queries
[in]	uctx	User context passed to trunk_alloc

Definition at line 590 of file connection.c.

Here is the call graph for this function:

Variable Documentation

◆ ldap_msg_types

USES_APPLE_DEPRECATED_API char const* ldap_msg_types[UINT8_MAX+1]

static

Initial value:

= {
        [LDAP_RES_BIND]                 = "bind response",
        [LDAP_RES_SEARCH_ENTRY]         = "search entry",
        [LDAP_RES_SEARCH_REFERENCE]     = "search reference",
        [LDAP_RES_SEARCH_RESULT]        = "search result",
        [LDAP_RES_MODIFY]               = "modify response",
        [LDAP_RES_ADD]                  = "add response",
        [LDAP_RES_DELETE]               = "delete response",
        [LDAP_RES_MODDN]                = "modify dn response",
        [LDAP_RES_COMPARE]              = "compare response",
        [LDAP_RES_EXTENDED]             = "extended response",
        [LDAP_RES_INTERMEDIATE]         = "intermediate response"
}

Definition at line 34 of file connection.c.

Macros

Functions

Variables

Detailed Description

Macro Definition Documentation

◆ do_ldap_option

◆ maybe_ldap_option

◆ POPULATE_LDAP_CONTROLS

Function Documentation

◆ _ldap_connection_close_watch()

◆ _ldap_connection_free()

◆ _ldap_trunk_idle_timeout()

◆ _thread_ldap_trunk_free()

◆ fr_ldap_connection_alloc()

◆ fr_ldap_connection_close()

◆ fr_ldap_connection_configure()

◆ fr_ldap_connection_init()

◆ fr_ldap_connection_timeout_reset()

◆ fr_ldap_connection_timeout_set()

◆ fr_ldap_trunk_connection_init()

◆ fr_thread_ldap_bind_trunk_get()

◆ fr_thread_ldap_trunk_get()

◆ fr_thread_ldap_trunk_state()

◆ ldap_bind_auth_cancel_mux()

◆ ldap_connection_init()

◆ ldap_request_cancel()

◆ ldap_request_cancel_mux()

◆ ldap_request_fail()

◆ ldap_trunk_bind_auth_demux()

◆ ldap_trunk_bind_auth_fail()

◆ ldap_trunk_bind_auth_mux()

◆ ldap_trunk_connection_alloc()

◆ ldap_trunk_request_demux()

◆ ldap_trunk_request_mux()

Variable Documentation

◆ ldap_msg_types