ldap_get_dn, ldap_explode_dn, ldap_explode_rdn, ldap_dn2ufn — LDAP DN handling routines
#include <ldap.h>
char *ldap_get_dn( |
LDAP *ld, |
LDAPMessage *entry) ; |
int ldap_str2dn( |
const char *str, |
LDAPDN *dn, | |
unsigned flags) ; |
int ldap_dn2str( |
LDAPDN *dn, |
char **str, | |
unsigned flags) ; |
char **ldap_explode_dn( |
const char *dn, |
int notypes) ; |
char **ldap_explode_rdn( |
const char *rdn, |
int notypes) ; |
char *ldap_dn2ufn( |
const char * dn) ; |
char *ldap_dn2dcedn( |
const char * dn) ; |
char *ldap_dcedn2dn( |
const char * dn) ; |
char *ldap_dn2ad_canonical( |
const char * dn) ; |
These routines allow LDAP entry names (Distinguished Names, or DNs) to be obtained, parsed, converted to a user-friendly form, and tested. A DN has the form described in RFC 4414 "Lightweight Directory Access Protocol (LDAP): String Representation of Distinguished Names".
The ldap_get_dn
() routine
takes an entry
as
returned by ldap_first_entry(3) or
ldap_next_entry(3) and
returns a copy of the entry's DN. Space for the DN will be
obtained dynamically and should be freed by the caller using
ldap_memfree(3).
ldap_str2dn
() parses a
string representation of a distinguished name contained in
str
into its
components, which are stored in dn
as ldap_ava
structures, arranged in LDAPAVA,
LDAPRDN,
and LDAPDN
terms, defined as:
typedef struct ldap_ava { char *la_attr; struct berval *la_value; unsigned la_flags; } LDAPAVA; typedef LDAPAVA** LDAPRDN; typedef LDAPRDN* LDAPDN;
The attribute types and the attribute values are not
normalized. The la_flags
can be
either LDAP_AVA_STRING
or
LDAP_AVA_BINARY,
the latter meaning that the value is BER/DER encoded and thus
must be represented as, quoting from RFC 4514, " ... an
octothorpe character ('#' ASCII 35) followed by the
hexadecimal representation of each of the bytes of the BER
encoding of the X.500 AttributeValue." The flags
parameter to ldap_str2dn
() can be
LDAP_DN_FORMAT_LDAPV3 LDAP_DN_FORMAT_LDAPV2 LDAP_DN_FORMAT_DCE
which defines what DN syntax is expected (according to RFC
4514, RFC 1779 and DCE, respectively). The format can be
OR
ed to the flags
LDAP_DN_P_NO_SPACES LDAP_DN_P_NO_SPACE_AFTER_RDN ... LDAP_DN_PEDANTIC
The latter is a shortcut for all the previous limitations.
LDAP_DN_P_NO_SPACES
does not
allow extra spaces in the dn; the default is to silently
eliminate spaces around AVA separators ('='), RDN component
separators ('+' for LDAPv3/LDAPv2 or ',' for DCE) and RDN
separators (',' LDAPv3/LDAPv2 or '/' for DCE).
LDAP_DN_P_NO_SPACE_AFTER_RDN
does not allow a single space after RDN separators.
ldap_dn2str
() performs the
inverse operation, yielding in str
a string representation of
dn.
It allows the
same values for flags
as ldap_str2dn
(), plus
LDAP_DN_FORMAT_UFN LDAP_DN_FORMAT_AD_CANONICAL
for user-friendly naming (RFC 1781) and AD canonical.
The following routines are viewed as deprecated in favor
of ldap_str2dn
() and
ldap_dn2str
(). They are
provided to support legacy applications.
The ldap_explode_dn
()
routine takes a DN as returned by ldap_get_dn
() and breaks it up into its
component parts. Each part is known as a Relative
Distinguished Name, or RDN. ldap_explode_dn
() returns a NULL-terminated
array, each component of which contains an RDN from the DN.
The notypes
parameter
is used to request that only the RDN values be returned, not
their types. For example, the DN "cn=Bob, c=US" would return
as either { "cn=Bob", "c=US", NULL } or { "Bob", "US", NULL
}, depending on whether notypes was 0 or 1, respectively.
Assertion values in RDN strings may included escaped
characters. The result can be freed by calling ldap_value_free(3).
Similarly, the ldap_explode_rdn
() routine takes an RDN as
returned by ldap_explode_dn(dn,0)
and
breaks it up into its "type=value" component parts (or just
"value", if the notypes
parameter is set). Note
the value is not unescaped. The result can be freed by
calling ldap_value_free(3).
ldap_dn2ufn
() is used to
turn a DN as returned by ldap_get_dn(3) into a more
user-friendly form, stripping off all type names. See "Using
the Directory to Achieve User Friendly Naming" (RFC 1781) for
more details on the UFN format. Due to the ambiguous nature
of the format, it is generally only used for display
purposes. The space for the UFN returned is obtained
dynamically and the user is responsible for freeing it via a
call to ldap_memfree(3).
ldap_dn2dcedn
() is used to
turn a DN as returned by ldap_get_dn(3) into a
DCE-style DN, e.g. a string with most-significant to least
significant rdns separated by slashes ('/'); rdn components
are separated by commas (','). Only printable chars (e.g.
LDAPv2 printable string) are allowed, at least in this
implementation. ldap_dcedn2dn
()
performs the opposite operation. ldap_dn2ad_canonical
() turns a DN into a AD
canonical name, which is basically a DCE dn with attribute
types omitted. The trailing domain, if present, is turned in
a DNS-like domain. The space for the returned value is
obtained dynamically and the user is responsible for freeing
it via a call to ldap_memfree(3).
If an error occurs in ldap_get_dn
(
)
, NULL is
returned and the ld_errno
field
in the ld
parameter
is set to indicate the error. See ldap_error(3) for a
description of possible error codes. ldap_explode_dn
(
)
,
ldap_explode_rdn
(
)
,
ldap_dn2ufn
(), ldap_dn2dcedn
(), ldap_dcedn2dn
(), and ldap_dn2ad_canonical
() will return NULL
with errno(3) set appropriately
in case of trouble.
OpenLDAP Software is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. OpenLDAP Software is derived from University of Michigan LDAP 3.3 Release.