connection.c File Reference

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:

Go to the source code of this file.

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 (fr_event_list_t *el, void *h, UNUSED void *uctx)
	Free the handle, closing the connection to ldap. More...
static void	_ldap_connection_close_watch (fr_connection_t *conn, UNUSED fr_connection_state_t prev, UNUSED fr_connection_state_t state, void *uctx)
	Watcher for LDAP connections being closed. More...
static int	_ldap_connection_free (fr_ldap_connection_t *c)
	Close and delete a connection. More...
static fr_connection_state_t	_ldap_connection_init (void **h, fr_connection_t *conn, void *uctx)
	(Re-)Initialises the libldap side of the connection handle More...
static void	_ldap_trunk_idle_timeout (fr_event_list_t *el, UNUSED fr_time_t now, void *uctx)
	Callback for closing idle LDAP trunk. More...
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. More...
int	fr_ldap_connection_configure (fr_ldap_connection_t *c, fr_ldap_config_t const *config)
	Allocate and configure a new connection. More...
fr_connection_t *	fr_ldap_connection_state_alloc (TALLOC_CTX *ctx, fr_event_list_t *el, fr_ldap_config_t const *config, char const *log_prefix)
	Alloc a self re-establishing connection to an LDAP server. More...
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)
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. More...
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. More...
fr_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. More...
static void	ldap_bind_auth_cancel_mux (UNUSED fr_event_list_t *el, fr_trunk_connection_t *tconn, fr_connection_t *conn, UNUSED void *uctx)
	Callback to cancel LDAP bind auth. More...
static void	ldap_conn_error (UNUSED fr_event_list_t *el, UNUSED int fd, UNUSED int flags, int fd_errno, void *uctx)
	I/O error function. More...
static void	ldap_conn_readable (UNUSED fr_event_list_t *el, UNUSED int fd, UNUSED int flags, void *uctx)
	I/O read function. More...
static void	ldap_conn_writable (UNUSED fr_event_list_t *el, UNUSED int fd, UNUSED int flags, void *uctx)
	I/O write function. More...
static void	ldap_request_cancel (UNUSED fr_connection_t *conn, void *preq, UNUSED fr_trunk_cancel_reason_t reason, UNUSED void *uctx)
	Callback when an LDAP trunk request is cancelled. More...
static void	ldap_request_cancel_mux (UNUSED fr_event_list_t *el, fr_trunk_connection_t *tconn, fr_connection_t *conn, UNUSED void *uctx)
	Callback to cancel LDAP queries. More...
static void	ldap_request_fail (request_t *request, void *preq, UNUSED void *rctx, UNUSED fr_trunk_request_state_t state, UNUSED void *uctx)
	Callback to tidy up when a trunk request fails. More...
static void	ldap_trunk_bind_auth_demux (UNUSED fr_event_list_t *el, UNUSED fr_trunk_connection_t *tconn, fr_connection_t *conn, void *uctx)
	Read LDAP bind auth responses. More...
static void	ldap_trunk_bind_auth_fail (request_t *request, void *preq, UNUSED void *rctx, UNUSED fr_trunk_request_state_t state, UNUSED void *uctx)
	Callback to tidy up when a bind auth trunk request fails. More...
static void	ldap_trunk_bind_auth_mux (UNUSED fr_event_list_t *el, fr_trunk_connection_t *tconn, fr_connection_t *conn, void *uctx)
	Take pending LDAP bind auths from the queue and send them. More...
static fr_connection_t *	ldap_trunk_connection_alloc (fr_trunk_connection_t *tconn, fr_event_list_t *el, UNUSED fr_connection_conf_t const *conn_conf, char const *log_prefix, void *uctx)
	Allocate an LDAP trunk connection. More...
static void	ldap_trunk_connection_notify (fr_trunk_connection_t *tconn, fr_connection_t *conn, fr_event_list_t *el, fr_trunk_connection_event_t notify_on, UNUSED void *uctx)
	Setup callbacks requested by LDAP trunk connections. More...
static void	ldap_trunk_request_demux (fr_event_list_t *el, fr_trunk_connection_t *tconn, fr_connection_t *conn, void *uctx)
	Read LDAP responses. More...
static void	ldap_trunk_request_mux (UNUSED fr_event_list_t *el, fr_trunk_connection_t *tconn, fr_connection_t *conn, UNUSED void *uctx)
	Take LDAP pending queries from the queue and send them. More...

Variables
static USES_APPLE_DEPRECATED_API char const *	ldap_msg_types [UINT8_MAX]

Detailed Description

Asynchronous connection management functions for LDAP.

Id

a64332c312ea253fe014ca336fab6a3c6f5dd2fb

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 640 of file connection.c.

Function Documentation

_ldap_connection_close()

static void _ldap_connection_close ( fr_event_list_t *  el, void *  h, UNUSED void *  uctx  )

static

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 190 of file connection.c.

Here is the call graph for this function:

Here is the caller graph for this function:

_ldap_connection_close_watch()

static void _ldap_connection_close_watch ( fr_connection_t *  conn, UNUSED fr_connection_state_t  prev, UNUSED fr_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 281 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 216 of file connection.c.

Here is the call graph for this function:

Here is the caller graph for this function:

_ldap_connection_init()

static fr_connection_state_t _ldap_connection_init ( void **  h, fr_connection_t *  conn, void *  uctx  )

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]	uctx	Our LDAP connection handle (a fr_ldap_connection_t).

Returns

• FR_CONNECTION_STATE_CONNECTING on success.
• FR_CONNECTION_STATE_FAILED on failure.

Definition at line 336 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_event_list_t *  el, UNUSED fr_time_t  now, void *  uctx  )

static

Callback for closing idle LDAP trunk.

Definition at line 450 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 972 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 253 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_state_alloc()

fr_connection_t* fr_ldap_connection_state_alloc	(	TALLOC_CTX *	ctx,
		fr_event_list_t *	el,
		fr_ldap_config_t const *	config,
		char const *	log_prefix
	)

Alloc a self re-establishing connection to an LDAP server.

Parameters

[in]	ctx	to allocate any memory in, and to bind the lifetime of the connection to.
[in]	el	to insert I/O and timer callbacks into.
[in]	config	to use to bind the connection to an LDAP server.
[in]	log_prefix	to prepend to connection state messages.

Definition at line 380 of file connection.c.

Here is the call graph for this function:

Here is the caller graph for this function:

fr_ldap_connection_timeout_reset()

int fr_ldap_connection_timeout_reset

(

fr_ldap_connection_t const *

c

)

Definition at line 425 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 403 of file connection.c.

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 1367 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 993 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()

fr_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
• FR_TRUNK_STATE_MAX if no matching trunk

Definition at line 1071 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, fr_trunk_connection_t *  tconn, fr_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 fr_trunk_alloc

Definition at line 1309 of file connection.c.

Here is the call graph for this function:

ldap_conn_error()

static void ldap_conn_error ( UNUSED fr_event_list_t *  el, UNUSED int  fd, UNUSED int  flags, int  fd_errno, void *  uctx  )

static

I/O error function.

The event loop signalled that a fatal error occurec on this connection.

Parameters

[in]	el	The event list signalling.
[in]	fd	that errored.
[in]	flags	EL flags.
[in]	fd_errno	The nature of the error.
[in]	uctx	The trunk connection handle

Definition at line 569 of file connection.c.

Here is the call graph for this function:

Here is the caller graph for this function:

ldap_conn_readable()

static void ldap_conn_readable ( UNUSED fr_event_list_t *  el, UNUSED int  fd, UNUSED int  flags, void *  uctx  )

static

I/O read function.

Underlying FD is now readable - call the trunk to read any pending requests.

Parameters

[in]	el	The event list signalling.
[in]	fd	that's now readable.
[in]	flags	describing the read event.
[in]	uctx	The trunk connection handle.

Definition at line 534 of file connection.c.

Here is the call graph for this function:

Here is the caller graph for this function:

ldap_conn_writable()

static void ldap_conn_writable ( UNUSED fr_event_list_t *  el, UNUSED int  fd, UNUSED int  flags, void *  uctx  )

static

I/O write function.

Underlying FD is now writable - call the trunk to write any pending requests.

Parameters

[in]	el	The event list signalling.
[in]	fd	that's now writable.
[in]	flags	describing the write event.
[in]	uctx	The trunk connection handle

Definition at line 551 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 fr_connection_t *  conn, void *  preq, UNUSED fr_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 471 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, fr_trunk_connection_t *  tconn, fr_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 fr_trunk_alloc

Definition at line 490 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 fr_trunk_request_state_t  state, UNUSED void *  uctx  )

static

Callback to tidy up when a trunk request fails.

Definition at line 508 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 fr_trunk_connection_t *  tconn, fr_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 1191 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 fr_trunk_request_state_t  state, UNUSED void *  uctx  )

static

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

Definition at line 1339 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, fr_trunk_connection_t *  tconn, fr_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 fr_trunk_alloc

Definition at line 1087 of file connection.c.

Here is the call graph for this function:

ldap_trunk_connection_alloc()

static fr_connection_t* ldap_trunk_connection_alloc ( fr_trunk_connection_t *  tconn, fr_event_list_t *  el, UNUSED fr_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 fr_trunk_alloc.

Definition at line 631 of file connection.c.

Here is the call graph for this function:

ldap_trunk_connection_notify()

static void ldap_trunk_connection_notify ( fr_trunk_connection_t *  tconn, fr_connection_t *  conn, fr_event_list_t *  el, fr_trunk_connection_event_t  notify_on, UNUSED void *  uctx  )

static

Setup callbacks requested by LDAP trunk connections.

Parameters

[in]	tconn	Trunk handle.
[in]	conn	Individual connection callbacks are to be installed for.
[in]	el	The event list to install events in.
[in]	notify_on	The types of event the trunk wants to be notified on.
[in]	uctx	Context provided to fr_trunk_alloc.

Definition at line 586 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, fr_trunk_connection_t *  tconn, fr_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 764 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, fr_trunk_connection_t *  tconn, fr_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 fr_trunk_alloc

Definition at line 655 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]

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.