Distinguished Names

Overview #

Distinguished Names is a Distinguished Name (often referred to as a DN or FDN) is a string that uniquely identifies an entry in the DIT.

A Distinguished Names is comprised of zero or more Relative Distinguished Name components that identify the location of the entry in the DIT.

An LDAP Entry's Distinguished Names can be thought of as a kind of an analog to an absolute path in a File System in that it specifies both the name and hierarchical location.

Distinguished Names are composed of Naming Attributes (Relative Distinguished Names or RDNs) and should therefore follow Best Practices For LDAP Naming Attributes

Attribute Definition #

The Distinguished Names AttributeTypes is defined as:

The RDN components for a Distinguished Names are separated by commas and are ordered from right to left. The rightmost components of a DN are closest to the server's Naming Context, and the leftmost components are closest to the leaf entries. That is, if you think of a directory hierarchy as a kind of pyramid with the Naming Context at the top and the branches descending downward, then the order of RDN components in a DN are listed from bottom to top.

Even though a DN is comprised of a series of RDN components, when one refers to an LDAP Entry's RDN, then it is a reference to the leftmost RDN component (Naming Attribute). The attribute values contained in an LDAP Entry's DN must also be contained in that LDAP Entry.

Consider the following Example DIT:

DIT Example

In this case, the top entry is the naming context and its DN is "dc=example,dc=com". To conserve space, only the RDNs of the subordinate entries are displayed, but the full DNs can be obtained by appending the RDN components from bottom to top. For example, the DN of the leftmost entry on the bottom row would be "uid=ann,ou=People,dc=example,dc=com".

Additional Information on Distinguished Names#

Distinguished Names and Certificates[1]#

The X.509 Style Guide describes Distinguished Names and Certificates. We put a summary below.
Name ::= SEQUENCE OF RelativeDistinguishedName

RelativeDistinguishedName ::= SET OF AttributeValueAssertion

AttributeValueAssertion ::= SEQUENCE {
    attributeType           OBJECT IDENTIFIER,
    attributeValue          ANY
This is used to encode that wonderful ISO creation, the Distinguished Names (DN), a path through an X.500 Directory Information Tree (DIT) which uniquely identifies everything on earth. Although the Relative Distinguished Name (RDN) is given as a SET OF Attribute Value Assertion (AVA) each set should only contain one element. However you may encounter other people's certificates which could contain more than one AVA per set, there has been a reported sighting of a certificate which contained more than one element in the SET.

When encoding sets with cardinality > 1, you need to take care to follow the DER rules which say that they should be ordered by their encoded values (although ASN.1 says a SET is unordered, the DER adds ordering rules to ensure it can be encoded in an unambiguous manner). What you need to do is encode each value in the set, then sort them by the encoded values, and output them wrapped up in the SET OF encoding, however your software really shouldn't be producing these sorts of RDN entries. (See Best Practices For LDAP Naming Attributes)

First things first, but not necessarily in that order.
                        -- Dr.Who

In theory you don't have to use a Name for the Certificate Subject if you don't want to; there is a subjectAltName extension which allows use of email addresses or URL's. In theory if you want to do this you can make the Name an empty sequence and include a subjectAltName extension and mark it critical, but this will break a lot of implementations. Because it is possible to do this, you SHOULD be prepared to accept a zero-length sequence for the Certificate Subject name in version 3 certificates. Since the DN is supposed to encode the location of the certificate in a DIT, having a null issuer name would mean you couldn't actually locate the certificate, so Certificate Authority will need to use proper DNs.

The S/MIME certificate spec codifies this by requiring that all issuer DNs be non-null (so only an end-user certificate can have a null DN, and even then it's NOT RECOMMENDED, and this requirement was back-ported to the PKIX profile shortly before it was finalized. The reason for requiring issuer DNs is that S/MIME v2 and several related standards identify certificates by issuer and serial number, so all Certificate Authority certificates must contain an issuer DN (S/MIME v3 allows subjectKeyIdentifiers, but they're almost never used).

SET provides an eminently sensible definition for DNs:

  Name ::= SEQUENCE SIZE(1..5) OF RelativeDistinguishedName

  RelativeDistinguishedName ::= SET SIZE(1) OF AttributeTypeAndValue

  AttributeTypeAndValue ::= { OID, C | O | OU | CN }
This means that when you see a SET DN it'll be in a fixed, consistent, and easy-to-process format (note in particular the fixed maximum size, the requirement for a single element per AVA, and the restriction to sensible element types).

Note that the (issuer name, serialNumber (with a possible side order of issuerUniqueID, issuerAltName, and keyUsage extension)) tuple uniquely identifies a certificate and can be used as a key to retrieve certificates from an information store. The Certificate Subject name alone does not uniquely identify a certificate because a Certificate Subject can own multiple certificates.

You would normally expect to find the following types of AVAs in an X.509 certificate, starting from the top:

  • countryName ::= SEQUENCE { { 2 5 4 6 }, StringType( SIZE( 2 ) ) }
  • organization ::= SEQUENCE { { 2 5 4 10 }, StringType( SIZE( 1...64 ) ) }
  • organizationalUnitName ::= SEQUENCE { { 2 5 4 11 }, StringType( SIZE( 1...64 ) ) }
  • commonName ::= SEQUENCE { { 2 5 4 3 }, StringType( SIZE( 1...64 ) ) }

You might also find:

Some profiles require at least some of these AVAs to be present, for example the German profile requires at least a countryName and commonName, and in some cases also an organization name. This is a reasonable requirement, as a minimum you should always include the countryName and commonName.

Finally, you'll frequently also run into:

emailAddress    ::= SEQUENCE { { 1 2 840 113549 1 9 1 }, IA5String }
from PKCS 9, although this shouldn't be there.

I can't afford to make exceptions. Once word leaks out that a pirate has gone soft, people begin to disobey you and it's nothing but work, work, work all the time -- The Dread Pirate Roberts, "The Princess Bride"

The reason why oddball components like the emailAddress have no place in a DN created as per the original X.500 vision is because the whole DN is intended to be a strictly hierarchical construction specifying a path through a DIT. Unfortunately the practice adopted by many Certificate Authoritys of tacking on an emailAddress, an element which has no subordinate relationship to the other components of the DN, creates a meaningless mishmash which doesn't follow this hierarchical model. For this reason the ITU defined the GeneralName, which specifically allows for components such as email addresses, URL's, and other non-DN items. GeneralNames are discussed in "Extensions" below.

Since the GeneralName provides a proper means of specifying information like email addresses, your software shouldn't populate DNs with these components, however for compatibility with legacy implementations you need to be able to accept existing certificates which contain odd things in the DN. Currently all mailers appear to be able to handle an rfc822Name in an altName, so storing it in the correct location shouldn't present any interoperability problems. One problem with email address handling is that many mailers will accept not only 'J.Random Luser <jrandom@aol.com>' as a valid emailAddress/rfc822Name but will be equally happy with 'President William Jefferson Clinton <jrandom@aol.com>'. The former is simply invalid, but the latter can be downright dangerous because it completely bypasses the stated purpose of email certificates, which is to identify the other party in an email exchange. Both PKIX and S/MIME explicitly require that an rfc822Name only contain an RFC 822 addr-spec which is defined as local-part@domain, so the mailbox form 'Personal Name <local-part@domain>' isn't allowed (many S/MIME implementations don't enforce this though).

Unfortunately X.509v3 just requires "an Internet electronic mail address defined in accordance with Internet RFC 822" without tying it down any further, so it could be either an addr-spec or a mailbox.

Okay, I'm going home to drink moderately and then pass out. -- Steve Rhoades, "Married with Children"

The countryName is the ISO 3166 code for the country. No One seems to know how to specify non-country-aligned organisations, it's possible that 'EU' will be used at some point but there isn't any way to encode a non-country code although some organisation's have tried using 'INT'. Actually no one really even knows what a countryName is supposed to refer to (let alone something as ambiguous as "locality"), for example it could be your place of birth, country of citizenship, country of current residence, country of incorporation, country where corporate HQ is located, country of choice for tax and/or jurisdictional issues, or a number of other possibilities (moving from countryName to stateOrProvinceName, people in the US military can choose a state as their official "residence" for tax purposes even if they don't own any property in that state, and politicians are allowed to run for office in one state while their wives claim residence and run for office in another state).

The details of the StringType are discussed further down. It's a good idea to actually limit the string lengths to 64 characters as required by X.520 because, although many implementations will accept longer encoded strings in certs, some can't manipulate them once they've been decoded by the software, and you'll run into problems with LDAP as well. This means residents of places like Taumatawhakatangihangakoauotamateaturipukakapikimaungahoronukupokai- whenuakitanataha are out of luck when it comes to getting X.509 certs.

Comparing two DNs has its own special problems, and is dealt with in the rather lengthy "Comparing DNs".

There appears to be some confusion about what format a Name in a certificate should take. Insufficient facts always invite danger -- Spock, "Space Seed"

In theory it should be a full, proper DN, which traces a path through the X.500 DIT, eg:

  C=US, L=Area 51, O=Hanger 18, OU=X.500 Standards Designers, CN=John Doe
but since the DIT's usually don't exist, exactly what format the DN should take seems open to debate. A good guideline to follow is to organize the namespace around the C, O, OU, and CN attribute types, but this is directed primarily at corporate structures. You may also need to use ST(ate) and L(ocality) RDNs.

Some implementations seem to let you stuff anything with an OID into a DN, which is not good.

There is nothing in any of these standards that would prevent me from including a 1 gigabit MPEG movie of me playing with my cat as one of the RDN components of the DN in my certificate. -- Bob Jueneman
on IETF-PKIX (There is a certificate of this form available from http://www.cs.auckland.ac.nz/~pgut001/pubs/ {dave_ca|dave}.der, although the MPEG is limited to just over 1MB)

With a number of organisation's moving towards the use of LDAP-based directory services, it may be that we'll actually see X.500 directories in our lifetime, which means you should make an attempt to have a valid DN in the certificate. LDAP uses the RFC 1779 form of DN, which is the opposite endianness to the ISO 9594 form used above:

  CN=John Doe, OU=X.500 Standards Designers, O=Hanger 18, L=Area 51, C=US
In order to work with LDAP implementations, you should ensure you only have a single AVA per RDN (which also avoids the above mentioned DER-encoding hassle).

As the above text has probably indicated, DNs don't really work - there's no clear idea of what they should look like, most users don't know about (and don't want to know about) X.500 and its naming conventions, and as a consequence of this the DN can end up containing just about anything. At the moment they seem to be heading in two main directions: Public CAs typically set C=CA country, O=CA name, OU=certificate type,

CN=user name - A small subset of CAs in Europe which issue certs in accordance with various signature laws and profiles with their own peculiar requirements can have all sorts of oddities in the DN. You won't run into many of these in the wild.

A small subsets of CAs will modify the DN by adding a unique ID value to the CN to make it a truly Distinguished Name. See the Bugs and Peculiarities sections for more information on this.

Private CAs (mostly people or organizations signing their own certs) typically set any DN fields supported by their software to whatever makes sense for them (some software requires all fields in the set {C,O,OU,SP,L,CN} to be filled in, leading to strange or meaningless entries as people try and guess what a Locality is supposed to be).

Generally you'll only run into certs from public CAs, for which the general rule is that the cert is identified by the CN and/or email address. Some CAs issue certs with identical CN's and use the email address to disambiguate them, others modify the CN to make it unique. The accepted user interface seems to be to let users search on the CN and/or email address (and sometimes also the serial number, which doesn't seem terribly useful), display a list of matches, and let the user pick the cert they want. Probably the best strategy for a user interface which handles certs is:

  if( email address known )
    get a cert which matches the email address (any one should do);
  elseif( name known )
    search for all certs with CN=name;
    if( multiple matches )
      display email addresses for matched certs to user, let them choose;
If you need something unique to use as an identifier (for example for a database key) and you know your own software (or more generally software which can do something useful with the identifier) will be used, use an X.500 serialNumber in a subjectAltName directoryName or use a subjectAltName otherName (which was explicitly created to allow user-defined identifiers).

For internal cert lookups, encode the cert issuer and serial number as a PKCS7 issuerAndSerialNumber, hash it down to a fixed size with SHA-1 (you can either use the full 20 bytes or some convenient truncated form like 64 bits), and use that to identify the cert. This works because the internal structure of the DN is irrelevant anyway, and having a fixed-size unique value makes it very easy to perform a lookup in various data structures (for example the random hash value generated leads to probabilistically balanced search trees without requiring any extra effort).

More Information #

There might be more information for this subject on one of the following: