Specifying Distinguished Names

A distinguished name for an X.509 certificate consists of a sequence of relative distinguished names (RDN) where each RDN is expressed as an attribute type/value pair.

In this Toolkit, an RDN is specified as an attribute type/value pair in the form <type>=<value>, for example, CN=Carol. Multi-valued RDNs are not supported. A distinguished name is specified as a string consisting of a sequence of attribute type/value pairs separated by a semicolon (';' U+003B). The general format is

<type>=<value>(;<type>=<value>)*[;]

At least one attribute must be specified. The RDNs are written to the certificate name in the order they are listed. Attribute pairs may be repeated. Note that the Windows Certificate Manager displays the attributes in LDAP order, which is the reverse order to which they are written.

<type> is either a supported short name in the following table or a dotted-decimal encoding of an ASN.1 object identifier (see Specifying an arbitrary RDN below).

We keep the deprecated emailAddress attribute here because it seems so popular. Note that the emailAddress attribute of the distinguished name is independent of the rfc822Name address in a subjectAltName extension, which can be specified separately in the extensions parameter.

<value> is a string of bytes (octets) to be encoded as an ASN.1 string type. A <value> can be specified in the following ways:

Simple form:

<astring>
where <astring> consists only of printable ASCII characters excluding the equals sign ('=' U+003D) and the semicolon (';' U+003B). Some examples.

"C=US;O=Example Organisation;CN=Test User 1"
"CN=Carol"
"CN=My User;O=My Org;OU=Unit;C=AU;L=My Town;S=NSW;E=myuser@my.org"

All other characters are treated literally, including spaces after the '=' and before the ';'.

General form:

'<quoted-string>'
Enclose <quoted-string> in single quotes (apostrophe "'" U+0027) and use the backslash ('\' U+005C) to escape the special characters "'" and "\". Examples:

"O='e=mc2';OU='roses are red; violets are blue'"
"O='Fred\'s Bar'"      => Fred's Bar
"OU='This=\\E\'asy;'"  => This=\E'asy

[New in v12.0]. To insert a single octet in the code of the character, use an escaped hex sequence consisting of the backslash "\" followed by exactly two hex digits. For example:

"C='M\e9xico'"    => Latin-1-encoded letter é
"C='M\C3\A9xico'"  => UTF-8-encoded letter é

In all other cases the backslash is ignored.

"OU='p\qr'"  => pqr

Note that when using C/C++, you need to double-escape the backslash character:

strDN = "CN=My User;OU='This=\\\\E\\'asy;';C='M\\C3\\A9xico'";

In C#, use a verbatim string literal:

strDN = @"CN=My User;OU='This=\\E\'asy;';C='M\C3\A9xico'";

Hexadecimal form:

#x<hex-digits>
A hex-encoded string of characters preceded by the two characters the hash symbol (number sign '#' U+0023) and a lower-case letter x ('x' U+0078). Examples:

OU=#x616263         => abc
C=#x4de97869636f    => México in Latin-1
C=#x4dc3a97869636f  => México in UTF-8
CN=#xE5A4A7E58DAB   => CJK ideographs, U+5927 (da) and U+536B (wei) in UTF-8

The value must start with the two characters #x and be followed only by hex digits [0-9A-Fa-f]. The lower-case letter "x" is case sensitive. This form is now made redundant by using escaped hex sequences in a quoted string, but it's more compact and, hey, it's there if you want to use it.

Arbitrary RDN:

#<hexstring>
A hex-encoded string prefixed by a pound sign ('#' U+0023), where <hexstring> is the hexadecimal encoding of the octets of the DER-encoding of the ASN.1 value, and only if the <type> is in the form <dotted-oid>. [New in v12.0] - for advanced users only. See Specifying an arbitrary RDN below.

Special case: Empty subjectName:

$
[New in v12.3]. Setting szDistid="$" will create an X.509 document with an empty subject name. At least one field for a subject alternative name extension (altSubjectName) must be specified and the extension will automatically be marked critical. (Note that's a dollar symbol "$", not an empty string, which has a different meaning.)