A distinguished name (usually just shortened to “DN”) uniquely identifies an entry and describes its position in the DIT. A DN is much like an absolute path on a filesystem, except whereas filesystem paths usually start with the root of the filesystem and descend the tree from left to right, LDAP DNs ascend the tree from left to right. For example, the DN “uid=john.doe,ou=People,dc=example,dc=com” represents an entry that is immediately subordinate to “ou=People,dc=example,dc=com” which is itself immediately subordinate to the entry “dc=example,dc=com”.
DNs are comprised of zero or more comma-separated components called relative distinguished names, or RDNs. For example, the DN “uid=john.doe,ou=People,dc=example,dc=com” has four RDNs:
Each RDN is comprised of name-value pairs. Every RDN must contain at least one pair (an attribute name followed by an equal sign and the value for that attribute), but you can include multiple name-value pairs in the same RDN by separating them with plus signs. For example, the RDN “cn=John Doeemail@example.com” has a “cn” value of “John Doe” and a “mail” value of “firstname.lastname@example.org”. RDNs with multiple name-value pairs are called multivalued RDNs, and they are primarily used for cases in which it is not possible to guarantee that an RDN with a single component could be unique among entries at a given level of the hierarchy (e.g., there may be multiple users with a name of “John Doe” but they probably all have different email addresses).
Note that even though each component of a DN is in itself an RDN, it is a common practice to refer to the leftmost component of an entry’s DN as the RDN for that entry, and to refer to the attributes included in that RDN component as naming attributes. So in the DN “uid=john.doe,ou=People,dc=example,dc=com”, the component “uid=john.doe” is often referred to as the RDN for that entry. The attribute name-value pairs in this leftmost component must be present in the entry (so the entry “uid=john.doe,ou=People,dc=example,dc=com” must contain a uid attribute with a value of “john.doe”).
As previously noted, DNs can be comprised of zero or more components, which means that it is legal to have a DN without any components at all. This DN, whose string representation doesn’t have any characters, is often called the zero-length DN or the null DN. The null DN may be used to reference a special entry called the root DSE, which provides a lot of useful information about the directory server (e.g., the features supported by that server, the server software version, etc.). The root DSE will be described in more detail elsewhere.
It’s also worth pointing out that there is no requirement for the topmost entry in an LDAP tree to contain a single component. For example, it is entirely legal for a directory server to be configured such that it has an entry with DN “dc=example,dc=com” but not an entry with DN “dc=com”. The DN of the entry that is at the top of an LDAP tree is called a naming context (or sometimes referred to as a suffix).
Whenever a DN needs to be transferred in LDAP, that is generally done using its string representation. The string representation of a DN is simply the string representations of each of its RDNs, with each RDN separated by a comma. Usually, an RDN consists of an attribute type name (never including attribute options) followed by an equal sign and the string representation of the corresponding attribute value, with the plus sign used to separate the name-value pairs in a multivalued RDN. However, there are special cases in which it is necessary to escape one or more characters in an RDN. Some of those cases include:
- If a value starts or ends with a space, then that space character needs to be escaped. It can be escaped as either “\ ” (i.e., a backslash followed by a space) or “\20” (i.e., a backslash followed by the digits two and zero, which is the hexadecimal representation of the ASCII character code for a space). Note that any space which occurs anywhere except the first or last character of a value does not need to be escaped (but it would be legal to escape it anyway).
- If a value starts with the octothorpe character (#), then that character needs to be escaped as either “\#” or “\23”. Note that any occurrence of the octothorpe character that is not the first character of the value does not need to be escaped (but it would be legal to escape it anyway).
- All occurrences of the double quote character (") must be escaped as either “\"” or “\22”.
- All occurrences of the plus sign character (+) must be escaped as either “\+” or “\2b”.
- All occurrences of the comma character (,) must be escaped as either “\,” or “\2c”.
- All occurrences of the semicolon character (;) must be escaped as either “\;” or “\3b”.
- All occurrences of the less-than character (<) must be escaped as either “\<” or “\3c”.
- All occurrences of the greater-than character (>) must be escaped as either “\>” or “\3e”.
- All occurrences of the backslash character (\) must be escaped as either “\\” or “\5c”.
- Although it is not required, it is common for characters whose UTF-8 representation consists of multiple bytes (i.e., non-ASCII characters) to be escaped by placing a backslash character in front of the hexadecimal representation of each byte in the value. For example, the character “ñ” (a lowercase letter n with a tilde over it) could be escaped as “\c3\b1”.
- Although it is not common, it is entirely legal to escape any ASCII character with a backslash character followed by the two-digit hexadecimal representation for that character. For example, the character “a” could be escaped as “\61”.
The complete specification describing how to properly construct the string representation of an LDAP DN is contained in RFC 4514.
LDAP DNs may actually have multiple string representations. You can have any number of spaces around the commas separating RDN components. You can have any number of spaces around the equal signs separating RDN attributes from their values. You can have any number of spaces around the plus signs separating the elements of a multivalued RDN. The attributes in a multivalued RDN may appear in any order. You can use any kind of capitalization for attribute names. You can use the OID to reference an attribute instead of the attribute name, and some attributes may have multiple names. There may be multiple ways of representing some or all of the values of the RDN components (e.g., differences in capitalization may be considered insignificant). For example, all of the following are valid ways of representing the same DN:
- dc=example, dc=com
- dc = example , dc = com
You must therefore be careful to take all of these things into account when trying to compare DNs, and you should avoid using simple string comparisons. Most LDAP client APIs offer some mechanism for comparing DNs (e.g., to determine whether they are equal, or to determine whether they are hierarchically related) or to generate some kind of “normalized” representation of a DN (e.g., with all extraneous spaces removed, with all case-insensitive characters converted to either all lowercase or all uppercase, etc.) that can be more safely compared using simple string processing. Note, however, that even these methods are not necessarily safe unless the client is able to use schema information retrieved from the server (e.g., so that it can learn all of the names and OIDs for the attribute types, and the syntaxes and matching rules for the attribute values).