Utility functions to escape and parse DNs. More...

#include <freeradius-devel/ldap/base.h>
#include <freeradius-devel/util/base16.h>
#include <freeradius-devel/util/value.h>
#include <stdarg.h>

Include dependency graph for util.c:

Go to the source code of this file.

Functions
static int	_fr_ldap_value_iter_free (fr_ldap_value_iter_t *iter)
	Free the ber held by an allocated value iterator.

int	fr_ldap_attrs_check (char const *attrs, char const attr)
	Check that a particular attribute is included in an attribute list.

uint8_t *	fr_ldap_berval_to_bin (TALLOC_CTX ctx, struct berval const in)
	Convert a berval to a talloced buffer.

char *	fr_ldap_berval_to_string (TALLOC_CTX ctx, struct berval const in)
	Convert a berval to a talloced string.

size_t	fr_ldap_common_dn (char const full, char const part)
	Find the place at which the two DN strings diverge.

int	fr_ldap_dn_box_escape (fr_value_box_t vb, UNUSED void uctx)

size_t	fr_ldap_dn_escape_func (UNUSED request_t request, char out, size_t outlen, char const in, UNUSED void arg)
	Escape a string for use as an RFC 4514 DN attribute value.

void	fr_ldap_entry_dump (LDAPMessage *entry)
	Dump out the contents of an LDAPMessage.

int	fr_ldap_entry_value_find (struct berval out, LDAP handle, LDAPMessage entry, char const attr)
	Find an attribute in an entry, returning its first value referenced in place.

char *	fr_ldap_filter_afrom_dn_list (TALLOC_CTX ctx, char const dn_attr, char const filter, char const const *dn_list)
	Build a filter matching a set of objects by DN.

int	fr_ldap_filter_box_escape (fr_value_box_t vb, UNUSED void uctx)

size_t	fr_ldap_filter_escape_func (UNUSED request_t request, char out, size_t outlen, char const in, UNUSED void arg)
	Escape a string for use as an RFC 4515 filter assertion value.

int	fr_ldap_filter_to_tmpl (TALLOC_CTX ctx, tmpl_rules_t const t_rules, char const sub, size_t sublen, tmpl_t out)
	Combine filters and tokenize to a tmpl.

int	fr_ldap_parse_url_extensions (LDAPControl *sss, size_t sss_len, char extensions[])
	Parse a subset (just server side sort and virtual list view for now) of LDAP URL extensions.

int	fr_ldap_result_values_len (size_t num, size_t strings_len, LDAP handle, LDAPMessage result, char const *attr)
	Sum the lengths of an attribute's values across every entry of a result.

int	fr_ldap_server_config_check (fr_ldap_config_t handle_config, char const server, CONF_SECTION *cs)
	Check an LDAP server config in server:port format is valid.

int	fr_ldap_server_url_check (fr_ldap_config_t handle_config, char const server, CONF_SECTION const *cs)
	Check an LDAP server entry in URL format is valid.

talloc_str_list_t *	fr_ldap_str_list_afrom_result (TALLOC_CTX ctx, LDAP handle, LDAPMessage result, char const attr, size_t extra)
	Copy an attribute's values from every entry of a result into a string list.

size_t	fr_ldap_uri_unescape_func (UNUSED request_t request, char out, size_t outlen, char const in, UNUSED void arg)
	Converts escaped DNs and filter strings into normal.

char const *	fr_ldap_url_err_to_str (int ldap_url_err)
	Translate the error code emitted from ldap_url_parse and friends into something accessible with fr_strerror()

bool	fr_ldap_util_is_dn (char const *in, size_t inlen)
	Check whether a string looks like a DN.

size_t	fr_ldap_util_normalise_dn (char out, char const in)
	Normalise escape sequences in a DN.

struct berval *	fr_ldap_value_iter_alloc (int err, fr_ldap_value_iter_t out, TALLOC_CTX ctx, LDAP handle, LDAPMessage entry, char const *attr)
	Allocate a value iterator, released when the iterator is freed.

void	fr_ldap_value_iter_done (fr_ldap_value_iter_t *iter)
	Release value iteration state.

struct berval *	fr_ldap_value_iter_init (int err, fr_ldap_value_iter_t iter, LDAP handle, LDAPMessage entry, char const *attr)
	Start an in place iteration over an attribute's values in an entry.

struct berval *	fr_ldap_value_iter_next (int err, fr_ldap_value_iter_t iter)
	Return the next value of the iterated attribute.

Variables
static USES_APPLE_DEPRECATED_API const char	dn_specials [] = ",+\"\<>;*=()"

static const bool	escapes [SBUFF_CHAR_CLASS]

static const char	filter_specials [] = "*()\\"

static const char	hextab [] = "0123456789abcdef"

Detailed Description

Utility functions to escape and parse DNs.

Id: 8af3eee0cb170260d3d86aaf26cd31c273896411

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

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

Definition in file util.c.

Function Documentation

◆ _fr_ldap_value_iter_free()

static int _fr_ldap_value_iter_free ( fr_ldap_value_iter_t * iter )

static

Free the ber held by an allocated value iterator.

Definition at line 598 of file util.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ fr_ldap_attrs_check()

int fr_ldap_attrs_check	(	char const **	attrs,
		char const *	attr
	)

Check that a particular attribute is included in an attribute list.

Parameters

[in]	attrs	list to check
[in]	attr	to look for

Returns

1 if attr is in list
0 if attr is missing
-1 if checks not possible

Definition at line 1010 of file util.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ fr_ldap_berval_to_bin()

uint8_t * fr_ldap_berval_to_bin	(	TALLOC_CTX *	ctx,
		struct berval const *	in
	)

Convert a berval to a talloced buffer.

Parameters

ctx	to allocate in.
in	Berval to copy.

Returns: buffer containing in->bv_val.

Definition at line 797 of file util.c.

Here is the caller graph for this function:

◆ fr_ldap_berval_to_string()

char * fr_ldap_berval_to_string	(	TALLOC_CTX *	ctx,
		struct berval const *	in
	)

Convert a berval to a talloced string.

The ldap_get_values function is deprecated, and ldap_get_values_len does not guarantee the berval buffers it returns are \0 terminated.

For some cases this is fine, for others we require a \0 terminated buffer (feeding DNs back into libldap for example).

Parameters

ctx	to allocate in.
in	Berval to copy.

Returns: \0 terminated buffer containing in->bv_val.

Definition at line 778 of file util.c.

Here is the caller graph for this function:

◆ fr_ldap_common_dn()

size_t fr_ldap_common_dn	(	char const *	full,
		char const *	part
	)

Find the place at which the two DN strings diverge.

Returns the length of the non matching string in full.

Parameters

full	DN.
part	Partial DN as returned by ldap_parse_result.

Returns

Length of the portion of full which wasn't matched
-1 on failure.

Definition at line 877 of file util.c.

Here is the caller graph for this function:

◆ fr_ldap_dn_box_escape()

int fr_ldap_dn_box_escape	(	fr_value_box_t *	vb,
		UNUSED void *	uctx
	)

Definition at line 109 of file util.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ fr_ldap_dn_escape_func()

size_t fr_ldap_dn_escape_func	(	UNUSED request_t *	request,
		char *	out,
		size_t	outlen,
		char const *	in,
		UNUSED void *	arg
	)

Escape a string for use as an RFC 4514 DN attribute value.

Escapes characters that have special meaning in DNs. Leading space and '#' are also escaped as required by RFC 4514. Escape sequence is

\<hex><hex>

.

Parameters

request	The current request.
out	Pointer to output buffer.
outlen	Size of the output buffer.
in	Raw unescaped string.
arg	Any additional arguments (unused).

Definition at line 69 of file util.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ fr_ldap_entry_dump()

void fr_ldap_entry_dump ( LDAPMessage * entry )

Dump out the contents of an LDAPMessage.

Intended to be called from a debugger.

Parameters

[in] entry LDAPMessage to dump.

Definition at line 1221 of file util.c.

Here is the call graph for this function:

◆ fr_ldap_entry_value_find()

int fr_ldap_entry_value_find	(	struct berval *	out,
		LDAP *	handle,
		LDAPMessage *	entry,
		char const *	attr
	)

Find an attribute in an entry, returning its first value referenced in place.

The value points into the result message the entry belongs to, nothing is allocated and nothing needs freeing. The value remains valid until the result message is freed with ldap_msgfree.

Parameters

[out]	out	First value of the attribute. Untouched when the attribute is not found.
[in]	handle	the entry was received on.
[in]	entry	to search.
[in]	attr	to find.

Returns

The number of values the attribute has.
0 if the entry does not contain the attribute.
-1 if the entry could not be parsed.

Definition at line 748 of file util.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ fr_ldap_filter_afrom_dn_list()

char * fr_ldap_filter_afrom_dn_list	(	TALLOC_CTX *	ctx,
		char const *	dn_attr,
		char const *	filter,
		char const const	dn_list
	)

Build a filter matching a set of objects by DN.

Produces (|(<dn_attr>=<dn>)...), ANDed with filter if one is given. DN values are escaped.

Parameters

[in]	ctx	to allocate the filter string in.
[in]	dn_attr	Attribute which matches an object's own DN, e.g. entryDN or distinguishedName.
[in]	filter	Optional filter to AND with the DN set, may be NULL.
[in]	dn_list	NULL terminated list of DNs to match, no empty strings.

Returns: The filter string.

Definition at line 909 of file util.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ fr_ldap_filter_box_escape()

int fr_ldap_filter_box_escape	(	fr_value_box_t *	vb,
		UNUSED void *	uctx
	)

Definition at line 183 of file util.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ fr_ldap_filter_escape_func()

size_t fr_ldap_filter_escape_func	(	UNUSED request_t *	request,
		char *	out,
		size_t	outlen,
		char const *	in,
		UNUSED void *	arg
	)

Escape a string for use as an RFC 4515 filter assertion value.

Escapes only the characters that MUST be escaped in filter assertion values per RFC 4515: '*', '(', ')', '\'. Other characters (including ',', '+', '=') must NOT be escaped – some LDAP implementations do not decode non-required \HH sequences in assertion values and will fail to match. Escape sequence is

\<hex><hex>

.

Parameters

request	The current request.
out	Pointer to output buffer.
outlen	Size of the output buffer.
in	Raw unescaped string.
arg	Any additional arguments (unused).

Definition at line 155 of file util.c.

Here is the caller graph for this function:

◆ fr_ldap_filter_to_tmpl()

int fr_ldap_filter_to_tmpl	(	TALLOC_CTX *	ctx,
		tmpl_rules_t const *	t_rules,
		char const **	sub,
		size_t	sublen,
		tmpl_t **	out
	)

Combine filters and tokenize to a tmpl.

Parameters

ctx	To allocate combined filter in
t_rules	Rules for parsing combined filter.
sub	Array of subfilters (may contain NULLs).
sublen	Number of potential subfilters in array.
out	Where to write a pointer to the resulting tmpl.

Returns: length of combined data.

Definition at line 948 of file util.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ fr_ldap_parse_url_extensions()

int fr_ldap_parse_url_extensions	(	LDAPControl **	sss,
		size_t	sss_len,
		char *	extensions[]
	)

Parse a subset (just server side sort and virtual list view for now) of LDAP URL extensions.

Parameters

[out]	sss	Array of LDAPControl * pointers to add controls to.
[in]	sss_len	How many elements remain in the sss array.
[in]	extensions	A NULL terminated array of extensions.

Returns

>0 the number of controls added.
0 if no controls added.
-1 on failure.

Definition at line 373 of file util.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ fr_ldap_result_values_len()

int fr_ldap_result_values_len	(	size_t *	num,
		size_t *	strings_len,
		LDAP *	handle,
		LDAPMessage *	result,
		char const *	attr
	)

Sum the lengths of an attribute's values across every entry of a result.

The values are read in place from the result message, no arrays are allocated and no values are copied.

Parameters

[out]	num	Number of values found.
[out]	strings_len	Total length of the values, including a NUL byte for each.
[in]	handle	the result was received on.
[in]	result	Head of the result message chain.
[in]	attr	whose values to measure.

Returns

0 on success.
-1 if an entry could not be parsed.

Definition at line 653 of file util.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ fr_ldap_server_config_check()

int fr_ldap_server_config_check	(	fr_ldap_config_t *	handle_config,
		char const *	server,
		CONF_SECTION *	cs
	)

Check an LDAP server config in server:port format is valid.

Parameters

[in,out]	handle_config	LDAP handle config being built
[in]	server	string to parse
[in]	cs	in which the server is defined

Returns

0 for valid server definition
-1 for invalid server definition

Definition at line 1133 of file util.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ fr_ldap_server_url_check()

int fr_ldap_server_url_check	(	fr_ldap_config_t *	handle_config,
		char const *	server,
		CONF_SECTION const *	cs
	)

Check an LDAP server entry in URL format is valid.

Parameters

[in,out]	handle_config	LDAP handle config being built
[in]	server	string to parse
[in]	cs	in which the server is defined

Returns

0 for valid server definition
-1 for invalid server definition

Definition at line 1036 of file util.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ fr_ldap_str_list_afrom_result()

talloc_str_list_t * fr_ldap_str_list_afrom_result	(	TALLOC_CTX *	ctx,
		LDAP *	handle,
		LDAPMessage *	result,
		char const *	attr,
		size_t	extra
	)

Copy an attribute's values from every entry of a result into a string list.

The list, its pointer array and every string come from a single talloc pool. The values are read in place from the result message, the only copies made are the strings in the list.

Parameters

[in]	ctx	to allocate the list in.
[in]	handle	the result was received on.
[in]	result	Head of the result message chain.
[in]	attr	whose values to copy. May be NULL, in which case only the extra slots are allocated.
[in]	extra	Leading pointer array slots to leave NULL, for the caller to fill with strings not copied into the pool.

Returns

List of the attribute's values. Empty if the result holds no values for the attribute.
NULL if an entry could not be parsed.

Definition at line 696 of file util.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ fr_ldap_uri_unescape_func()

size_t fr_ldap_uri_unescape_func	(	UNUSED request_t *	request,
		char *	out,
		size_t	outlen,
		char const *	in,
		UNUSED void *	arg
	)

Converts escaped DNs and filter strings into normal.

Note

RFC 4515 says filter strings can only use the

\<hex><hex>

format, whereas RFC 4514 indicates that some chars in DNs, may be escaped simply with a backslash..

Will unescape any special characters in strings, or

\<hex><hex>

sequences.

Parameters

request	The current request.
out	Pointer to output buffer.
outlen	Size of the output buffer.
in	Escaped string string.
arg	Any additional arguments (unused).

Definition at line 227 of file util.c.

Here is the caller graph for this function:

◆ fr_ldap_url_err_to_str()

char const * fr_ldap_url_err_to_str ( int ldap_url_err )

Translate the error code emitted from ldap_url_parse and friends into something accessible with fr_strerror()

Parameters

[in] ldap_url_err The error code returned

Definition at line 1174 of file util.c.

Here is the caller graph for this function:

◆ fr_ldap_util_is_dn()

bool fr_ldap_util_is_dn	(	char const *	in,
		size_t	inlen
	)

Check whether a string looks like a DN.

Parameters

[in]	in	Str to check.
[in]	inlen	Length of string to check.

Returns

true if string looks like a DN.
false if string does not look like DN.

Definition at line 275 of file util.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ fr_ldap_util_normalise_dn()

size_t fr_ldap_util_normalise_dn	(	char *	out,
		char const *	in
	)

Normalise escape sequences in a DN.

Characters in a DN can either be escaped as

\<hex><hex>

or

\<special>

The LDAP directory chooses how characters are escaped, which can make local comparisons of DNs difficult.

Here we search for hex sequences that match special chars, and convert them to the

\<special>

form.

Note: the resulting output string will only ever be shorter than the input, so it's fine to use the same buffer for both out and in.

Parameters

out	Where to write the normalised DN.
in	The input DN.

Returns: The number of bytes written to out.

Definition at line 827 of file util.c.

Here is the caller graph for this function:

◆ fr_ldap_value_iter_alloc()

struct berval * fr_ldap_value_iter_alloc	(	int *	err,
		fr_ldap_value_iter_t **	out,
		TALLOC_CTX *	ctx,
		LDAP *	handle,
		LDAPMessage *	entry,
		char const *	attr
	)

Allocate a value iterator, released when the iterator is freed.

Behaves as fr_ldap_value_iter_init, with the ber memory freed by a talloc destructor, so the iteration state is released when the iterator or any of its talloc ancestors are freed.

Parameters

[out]	err	Set to -1 if the entry could not be parsed. Untouched otherwise. May be NULL.
[out]	out	The allocated iterator.
[in]	ctx	to allocate the iterator in.
[in]	handle	the entry was received on.
[in]	entry	whose values to iterate.
[in]	attr	to find.

Returns

The attribute's first value.
NULL if the entry does not contain the attribute, or could not be parsed.

Definition at line 623 of file util.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ fr_ldap_value_iter_done()

void fr_ldap_value_iter_done ( fr_ldap_value_iter_t * iter )

Release value iteration state.

Must be called once for every fr_ldap_value_iter_init, whether iteration completed or not.

Parameters

[in] iter to release.

Definition at line 507 of file util.c.

Here is the caller graph for this function:

◆ fr_ldap_value_iter_init()

struct berval * fr_ldap_value_iter_init	(	int *	err,
		fr_ldap_value_iter_t *	iter,
		LDAP *	handle,
		LDAPMessage *	entry,
		char const *	attr
	)

Start an in place iteration over an attribute's values in an entry.

The returned values point into the result message the entry belongs to, nothing is copied, and the values remain valid until the result message is freed with ldap_msgfree.

Parameters

[out]	err	Set to -1 if the entry could not be parsed. Untouched otherwise. May be NULL.
[out]	iter	to initialise. Release with fr_ldap_value_iter_done.
[in]	handle	the entry was received on.
[in]	entry	whose values to iterate.
[in]	attr	to find.

Returns

The attribute's first value.
NULL if the entry does not contain the attribute, or could not be parsed.

Definition at line 556 of file util.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ fr_ldap_value_iter_next()

struct berval * fr_ldap_value_iter_next	(	int *	err,
		fr_ldap_value_iter_t *	iter
	)

Return the next value of the iterated attribute.

Parameters

[out]	err	Set to -1 if the entry could not be parsed. Untouched otherwise. May be NULL.
[in]	iter	to advance.

Returns

The next value.
NULL when the values are exhausted, or the entry could not be parsed.

Definition at line 523 of file util.c.

Here is the caller graph for this function:

Variable Documentation

◆ dn_specials

USES_APPLE_DEPRECATED_API const char dn_specials[] = ",+\"\<>;*=()"

static

Definition at line 38 of file util.c.

◆ escapes

const bool escapes[SBUFF_CHAR_CLASS]

static

Initial value:

= {
        [' '] = true,
        ['#'] = true,
        ['='] = true,
        ['"'] = true,
        ['+'] = true,
        [','] = true,
        [';'] = true,
        ['<'] = true,
        ['>'] = true,
        ['\''] = true
}

Definition at line 40 of file util.c.

◆ filter_specials

const char filter_specials[] = "*()\\"

static

Definition at line 54 of file util.c.

◆ hextab

const char hextab[] = "0123456789abcdef"

static

Definition at line 39 of file util.c.

Functions

Variables

Detailed Description

Function Documentation

◆ _fr_ldap_value_iter_free()

◆ fr_ldap_attrs_check()

◆ fr_ldap_berval_to_bin()

◆ fr_ldap_berval_to_string()

◆ fr_ldap_common_dn()

◆ fr_ldap_dn_box_escape()

◆ fr_ldap_dn_escape_func()

◆ fr_ldap_entry_dump()

◆ fr_ldap_entry_value_find()

◆ fr_ldap_filter_afrom_dn_list()

◆ fr_ldap_filter_box_escape()

◆ fr_ldap_filter_escape_func()

◆ fr_ldap_filter_to_tmpl()

◆ fr_ldap_parse_url_extensions()

◆ fr_ldap_result_values_len()

◆ fr_ldap_server_config_check()

◆ fr_ldap_server_url_check()

◆ fr_ldap_str_list_afrom_result()

◆ fr_ldap_uri_unescape_func()

◆ fr_ldap_url_err_to_str()

◆ fr_ldap_util_is_dn()

◆ fr_ldap_util_normalise_dn()

◆ fr_ldap_value_iter_alloc()

◆ fr_ldap_value_iter_done()

◆ fr_ldap_value_iter_init()

◆ fr_ldap_value_iter_next()

Variable Documentation

◆ dn_specials

◆ escapes

◆ filter_specials

◆ hextab