!!! Overview [{$pagename}] is a [Distinguished Name] (often referred to as a [DN] or [FDN]) is a string that uniquely identifies an entry in the [DIT]. A [{$pagename}] is comprised of zero or more [Relative Distinguished Name] components that identify the location of the entry in the [DIT]. An [LDAP Entry]'s [{$pagename}] 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. [{$pagename}] are composed of [Naming Attributes] ([Relative Distinguished Names] or RDNs) and should therefore follow [Best Practices For LDAP Naming Attributes] !! Attribute Definition The [{$pagename}] [AttributeTypes] is defined as: * [OID] of [2.5.4.49] * NAME: [{$pagename}] * DESC: * [EQUALITY]: [distinguishedNameMatch] * [ORDERING]: [] * SYNTAX: [1.3.6.1.4.1.1466.115.121.1.12] [DN Syntax] The [RDN] components for a [{$pagename}] 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|Leaf]. 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: [{Image src='DIT/DIT.png' caption='DIT Example' align=left style='font-size: 120%}]\\ 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 [{$pagename}] * [Escaping Distinguished Name]s is described in [RFC 4514] and required for "Special Characters" * [String Representation of Distinguished Names] ([RFC 4514]) describes [LDAP] [{$pagename}]s and the way in which they should be represented as [strings]. * [DistinguishedNameMatch] ([RFC 4517]) describes the [Matching Rule] for [{$pagename}] * [Distinguished Name Case Sensitivity] describes [ Case Sensitivity|Case-sensitive] which is not consistent across [LDAP Server Implementations]!! [{$pagename}] and [Certificates][1] The [X.509 Style Guide] describes [{$pagename}] and [Certificates]. We put a summary below. %%prettify {{{ 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 [{$pagename}] (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|Encoding] 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: %%prettify {{{ 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: * [localityName] ::= SEQUENCE { { 2 5 4 7 }, StringType( SIZE( 1...64 ) ) } * [stateOrProvinceName] ::= SEQUENCE { { 2 5 4 8 }, StringType( SIZE( 1...64 ) ) } 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: %%prettify {{{ 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 Authority]s 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 [DN]s 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|ISO 3166-1 alpha-2] 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|Jurisdiction] 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|Distinguished Name Case Sensitivity]". 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: %%prettify {{{ 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: %%prettify {{{ 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: %%prettify {{{ 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; else error; }}} /% 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: [{ReferringPagesPlugin before='*' after='\n' }] ---- * [#1] - [X.509 Style Guide|https://www.cs.auckland.ac.nz/~pgut001/pubs/x509guide.txt|target='_blank'] - based on information obtained 2015-04-02