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       void ldap_dnfree( LDAPDN dn )
20
21       int ldap_dn2str( LDAPDN dn, char **str, unsigned flags )
22
23       char **ldap_explode_dn( const char *dn, int notypes )
24
25       char **ldap_explode_rdn( const char *rdn, int notypes )
26
27       char *ldap_dn2ufn( const char * dn )
28
29       char *ldap_dn2dcedn( const char * dn )
30
31       char *ldap_dcedn2dn( const char * dn )
32
33       char *ldap_dn2ad_canonical( const char * dn )
34

DESCRIPTION

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

ERRORS

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

NOTES

149       These routines dynamically allocate memory that the caller must free.
150

SEE ALSO

152       ldap(3),    ldap_error(3),    ldap_first_entry(3),     ldap_memfree(3),
153       ldap_value_free(3)
154

ACKNOWLEDGEMENTS

156       OpenLDAP  Software  is developed and maintained by The OpenLDAP Project
157       <http://www.openldap.org/>.  OpenLDAP Software is derived from the Uni‐
158       versity of Michigan LDAP 3.3 Release.
159
160
161
162OpenLDAP 2.4.46                   2018/03/22                    LDAP_GET_DN(3)
Impressum