1LDAP_GET_DN(3)             Library Functions Manual             LDAP_GET_DN(3)
2
3
4

NAME

6       ldap_get_dn,  ldap_explode_dn,  ldap_explode_rdn, ldap_dn2ufn - LDAP DN
7       handling routines
8

LIBRARY

10       OpenLDAP LDAP (libldap, -lldap)
11

SYNOPSIS

13       #include <ldap.h>
14
15       char *ldap_get_dn( LDAP *ld, LDAPMessage *entry )
16
17       int ldap_str2dn( const char *str, LDAPDN **dn, unsigned flags )
18
19       int ldap_dn2str( LDAPDN *dn, char **str, unsigned flags )
20
21       char **ldap_explode_dn( const char *dn, int notypes )
22
23       char **ldap_explode_rdn( const char *rdn, int notypes )
24
25       char *ldap_dn2ufn( const char * dn )
26
27       char *ldap_dn2dcedn( const char * dn )
28
29       char *ldap_dcedn2dn( const char * dn )
30
31       char *ldap_dn2ad_canonical( const char * dn )
32

DESCRIPTION

34       These routines allow LDAP entry names (Distinguished Names, or DNs)  to
35       be  obtained, parsed, converted to a user-friendly form, and tested.  A
36       DN has the form described in RFC  2253  "Lightweight  Directory  Access
37       Protocol (v3): UTF-8 String Representation of Distinguished Names".
38
39       The   ldap_get_dn()   routine   takes   an   entry   as   returned   by
40       ldap_first_entry(3) or ldap_next_entry(3) and returns  a  copy  of  the
41       entry's  DN.   Space for the DN will be obtained dynamically and should
42       be freed by the caller using ldap_memfree(3).
43
44       ldap_str2dn() parses a string representation of  a  distinguished  name
45       contained  in  str  into  its  components,  which  are  stored in dn as
46       ldap_ava structures, arranged in LDAPAVA, LDAPRDN,  and  LDAPDN  terms,
47       defined as:
48
49       typedef struct ldap_ava {
50           char *la_attr;
51           struct berval *la_value;
52           unsigned la_flags;
53       } LDAPAVA;
54
55       typedef LDAPAVA** LDAPRDN;
56       typedef LDAPRDN** LDAPDN;
57
58       The  attribute  types and the attribute values are not normalized.  The
59       la_flags can be either LDAP_AVA_STRING or LDAP_AVA_BINARY,  the  latter
60       meaning  that the value is BER/DER encoded and thus must be represented
61       as, quoting from RFC 2253, " ... an octothorpe character ('#' ASCII 35)
62       followed  by the hexadecimal representation of each of the bytes of the
63       BER encoding of the X.500  AttributeValue."   The  flags  parameter  to
64       ldap_str2dn() can be
65
66            LDAP_DN_FORMAT_LDAPV3
67            LDAP_DN_FORMAT_LDAPV2
68            LDAP_DN_FORMAT_DCE
69
70       which  defines  what  DN syntax is expected (according to RFC 2253, RFC
71       1779 and DCE, respectively).  The format can be ORed to the flags
72
73            LDAP_DN_P_NO_SPACES
74            LDAP_DN_P_NO_SPACE_AFTER_RDN
75            ...
76            LDAP_DN_PEDANTIC
77
78       The latter is a shortcut for all the previous limitations.
79
80       LDAP_DN_P_NO_SPACES does not allow extra spaces in the dn; the  default
81       is to silently eliminate spaces around AVA separators ('='), RDN compo‐
82       nent separators ('+' for LDAPv3/LDAPv2 or ',' for DCE) and RDN  separa‐
83       tors (',' LDAPv3/LDAPv2 or '/' for DCE).
84
85       LDAP_DN_P_NO_SPACE_AFTER_RDN  does  not  allow a single space after RDN
86       separators.
87
88       ldap_dn2str() performs the inverse operation, yielding in str a  string
89       representation  of  dn.   It  allows  the  same  values  for  flags  as
90       ldap_str2dn(), plus
91
92            LDAP_DN_FORMAT_UFN
93            LDAP_DN_FORMAT_AD_CANONICAL
94
95       for user-friendly naming (RFC 1781) and AD canonical.
96
97       The  following  routines  are  viewed  as  deprecated   in   favor   of
98       ldap_str2dn()  and  ldap_dn2str().  They are provided to support legacy
99       applications.
100
101       The ldap_explode_dn() routine takes a DN as returned  by  ldap_get_dn()
102       and  breaks  it  up  into its component parts.  Each part is known as a
103       Relative Distinguished Name, or RDN.  ldap_explode_dn() returns a NULL-
104       terminated  array, each component of which contains an RDN from the DN.
105       The notypes parameter is used to request that only the  RDN  values  be
106       returned,  not  their  types.  For example, the DN "cn=Bob, c=US" would
107       return as either { "cn=Bob", "c=US", NULL } or { "Bob", "US",  NULL  },
108       depending  on whether notypes was 0 or 1, respectively.  Assertion val‐
109       ues in RDN strings may included escaped characters.  The result can  be
110       freed by calling ldap_value_free(3).
111
112       Similarly,  the  ldap_explode_rdn() routine takes an RDN as returned by
113       ldap_explode_dn(dn,0) and breaks it up into its "type=value"  component
114       parts  (or  just  "value",  if the notypes parameter is set).  Note the
115       value  is  not  unescaped.   The  result  can  be  freed   by   calling
116       ldap_value_free(3).
117
118       ldap_dn2ufn() is used to turn a DN as returned by ldap_get_dn(3) into a
119       more user-friendly form, stripping off all type names.  See "Using  the
120       Directory  to Achieve User Friendly Naming" (RFC 1781) for more details
121       on the UFN format.  Due to the ambiguous nature of the  format,  it  is
122       generally  only  used  for  display  purposes.   The  space for the UFN
123       returned is obtained dynamically and the user is responsible for  free‐
124       ing it via a call to ldap_memfree(3).
125
126       ldap_dn2dcedn() is used to turn a DN as returned by ldap_get_dn(3) into
127       a DCE-style DN, e.g. a string with most-significant to  least  signifi‐
128       cant  rdns  separated by slashes ('/'); rdn components are separated by
129       commas (',').  Only printable chars (e.g. LDAPv2 printable string)  are
130       allowed, at least in this implementation.  ldap_dcedn2dn() performs the
131       opposite operation.  ldap_dn2ad_canonical() turns a DN into a AD canon‐
132       ical  name,  which  is basically a DCE dn with attribute types omitted.
133       The trailing domain, if present, is turned in a DNS-like  domain.   The
134       space  for  the  returned value is obtained dynamically and the user is
135       responsible for freeing it via a call to ldap_memfree(3).
136

ERRORS

138       If an error occurs in ldap_get_dn(), NULL is returned and the  ld_errno
139       field  in  the  ld  parameter  is  set  to  indicate  the  error.   See
140       ldap_error(3)   for   a   description   of   possible   error    codes.
141       ldap_explode_dn(),  ldap_explode_rdn(), ldap_dn2ufn(), ldap_dn2dcedn(),
142       ldap_dcedn2dn(),  and  ldap_dn2ad_canonical()  will  return  NULL  with
143       errno(3) set appropriately in case of trouble.
144

NOTES

146       These routines dynamically allocate memory that the caller must free.
147

SEE ALSO

149       ldap(3),     ldap_error(3),    ldap_first_entry(3),    ldap_memfree(3),
150       ldap_value_free(3)
151

ACKNOWLEDGEMENTS

153       OpenLDAP  is  developed  and  maintained  by   The   OpenLDAP   Project
154       (http://www.openldap.org/).   OpenLDAP  is  derived  from University of
155       Michigan LDAP 3.3 Release.
156
157
158
159OpenLDAP 2.3.34                    2007/2/16                    LDAP_GET_DN(3)
Impressum