Distinguished Names

Administrator's Guide
Red Hat Certificate System

Index

Appendix I

Distinguished Names

This appendix explains what a distinguished name is and how Red Hat Certificate System (CS) uses distinguished names to automatically update certificate information in your corporate LDAP directory.

This appendix contains the following sections:

"What Is a Distinguished Name?," on page 753
"DNs in Certificate System," on page 756
"Role of Distinguished Names in Certificates," on page 763

For the most part, the information presented in this appendix is specific to Red Hat Directory Server, an LDAP-compliant directory.

What Is a Distinguished Name?

Distinguished names (DNs) are string representations that uniquely identify users, systems, and organizations. In general, DNs are used in LDAP-compliant directories, such as Red Hat Directory Server. In Certificate System, you use DNs to identify the owner of a certificate and the authority that issued a certificate.

Note

If you are using an LDAP directory in conjunction with Certificate System, the DNs in your certificates should match the DNs in your directory.

Distinguished Name Components

A DN identifies an entry in an LDAP directory. Because directories are hierarchical, DNs identify the entry by its location as a path in a hierarchical tree (much as a path in a file system identifies a file). Generally, a DN begins with a specific common name, and proceeds with increasingly broader areas of identification until the country name is specified. DNs are typically made up of the following components (which are defined in the X.520 standard):

CN=common name, OU=organizational unit, O=organization, L=locality,
ST=state or province, C=country name

These components are described in Table I-1. For more information on distinguished names, see RFC 2253 (which replaces RFC 1779). You can find RFC 2253 at this URL: http://www.ietf.org/rfc/rfc2253.txt

Note that if used in conjunction with an LDAP-compliant directory, Certificate System by default recognizes components that are listed in Table I-2.

Table I-1 Definitions of standard DN components

Component

Name

Definition

CN

Common name

A required component that identifies the person or object defined by the entry. For example:

CN=Jane Doe
CN=corpDirectory.example.com

E
(deprecated)

Email address

Identifies the email address of the entry. For example: jdoe@example.com

The use of this component is discouraged by the PKIX standard; instead, it recommends the use of Subject Alternative Name Extension to associate an email address with a certificate; see "subjectAltName" on page 740. The reason for this is because it is usually too hard to have a E in a directory structure; email addresses change too frequently.

OU

Organizational unit

Identifies a unit within the organization. For example:

OU=Sales
OU=Manufacturing

O

Organization

Identifies the organization in which the entry resides. For example:

O=Example Corporation
O=Public Power & Gas

L

Locality

Identifies the place where the entry resides. The locality can be a city, county, township, or other geographic region. For example:

L=Mountain View
L=Pacific Northwest
L=Anoka County

ST

State or province name

Identifies the state or province in which the entry resides. For example:

ST=California
ST=British Columbia

C

Country

Identifies the name of the country under which the entry resides. For example:

C=US
C=GB

DC

Domain component

Identifies the domain components of a domain. For example, if the domain is example.com, the domain components would be:

dc=example, dc=com

Root Distinguished Name

The root distinguished name, or root DN, is the first, or top-most, entry in an LDAP directory tree. In Red Hat Directory Server, the root DN is commonly referred to as the directory manager. By default, the root DN uses no suffix; it is simply a common name attribute-data pair: CN=Directory Manager. For example, the root entry's DN could look like this: CN=Directory Manager, O=Example Corporation, C=US.

Base Distinguished Name

The base distinguished name, or base DN, identifies the entry in the directory from which searches initiated by LDAP clients occur; the base DN is often referred to as the search base. For example, if you specify a base DN of OU=people, O=example.com for a client, the LDAP search operation initiated by the client examines only the OU=people subtree in the O=example.com directory tree.

Typically, an LDAP search consists of the following components:

The base DN-for example, O=example.com, C=US, which initiates a subtree search through all entries below this entry in the directory (in other words, all entries with the suffix O=example.com, C=US).
The search type, which can be a base search (only the entry specified by the base DN is searched), a one-level search (only entries one level below the base entry are searched), or a subtree search (all entries at all levels below the base entry are searched).
The search filter, which specifies the search criteria applied to each entry within the scope of the search.

When Certificate System is configured for LDAP publishing, the search point and search criteria are determined by the configuration parameter values. In the absence of a base DN value, Certificate System uses DN components in the certificate's subject name to construct the base DN so that it can search the directory in order to publish to or update the appropriate directory entry.

Typically, when you configure Certificate System for LDAP publishing, you set the base DN value to Directory Manager, so that it can use the publishing directory's root entry to start searching; see section "Configuring a Certificate Manager to Publish Certificates and CRLs" in Chapter 19, "Setting Up LDAP Publishing" of CS Administrator's Guide.

DNs in Certificate System

In Certificate System, the characters allowed in a DN are based on the components (attributes) as defined in the X.509 standard.

Table I-2 lists the attributes supported by default and their character sets. Explanation of the character sets are in Table I-3. The set of attributes is extensible.

Table I-2 Allowed characters for value types

Attribute

Value type

Object identifier

CN

Directory String

2.5.4.3

OU

Directory String

2.5.4.11

O

Directory String

2.5.4.10

C

Printable String of length 2

2.5.4.6

L

Directory String

2.5.4.7

ST

Directory String

2.5.4.8

STREET

Directory String

2.5.4.9

TITLE

Directory String

2.5.4.12

UID

Directory String

0.9.2342.19200300.100.1.1

MAIL

IA5String

0.9.2342.19200300.100.1.3

E

IA5String

1.2.840.113549.1.9.1

DC

IA5String

0.9.2342.19200300.100.1.2.25

SERIALNUMBER (for CEP support)

Printable String

2.5.4.5

UNSTRUCTUREDNAME (for CEP support)

IA5String

1.2.840.113549.1.9.2

UNSTRUCTUREDADDRESS (for CEP support)

Printable String

1.2.840.113549.1.9.8

Table I-3 Explanation of character sets for DNs

Value type

Character set allowed

Printable String

A-Z, a-z, 0-9, space
\
(
)
+
,
-
.
/
:
=
?

IA5String

Any 7-bit US ASCII character.

Directory String

Any character in format as specified in Lightweight Directory Access Protocol (v3): UTF-8 String Representation of Distinguished Names (see http://www.ietf.org/rfc/rfc2253.txt). Certificate System conforms to all of this standard, including support of using hex numbers to escape characters. The special characters are as follows:

,
=
+
<
>
#
;

They can be escaped by either a backslash (\) before the character or by surrounding the value in double quotes (" "). A few examples are shown below:

Example Corp. \, Ltd.

"Example Corp. , Ltd"

"Example Corp. \, Ltd"

Name \, with \= escaped \+ special \< characters \# like \> or \"\\\;

"Name , with = special + characters < surrounded > by # quotes; ,=+<>#;"

Name with escaped characters like return \0D or C with Caron \C4\8D or L\4C

Name with spaces at beginning and end

For additional more examples, check the standards.

Extending Attribute Support

By default, Certificate System supports attribute identified in Table I-2 on page 756. You can extend the list of attributes supported by server. The syntax for adding additional X.500Name attributes (or components) is as follows:

X500Name.<NEW_ATTRNAME>.oid=<n.n.n.n>
X500Name.<NEW_ATTRNAME>.class=<string_to_DER_value_converter_class>

Note the following:

Value converter class converts a string to a ASN.1 value.
It must implement redhat.security.x509.AVAValueConverter interface.

The string-to-value converter class can be one of these:

redhat.security.x509.PrintableConverter-converts a string to a Printable String value. The string must have only printable characters.
redhat.security.x509.IA5StringConverter-converts a string to a IA5String value. The string must have only IA5String characters.
redhat.security.x509.DirStrConverter-converts a string to a Directory (v3) String. The string is expected to be in DirectoryString format according to RFC 2253.
redhat.security.x509.GenericValueConverter-converts a string character by character in the following order, from smaller character sets to broadest character set: Printable, IA5String, BMPString, Universal String.

For example:

X500Name.MY_ATTR.oid=1.2.3.4.5.6
X500Name.MY_ATTR.class=redhat.security.x509.DirStrConverter

Adding New or Proprietary Attributes

To add a new or proprietary attribute that's not supported by Certificate System by default:

Stop the Certificate Manager.
Go to this directory: <server_root>/cert-<instance_id>/config
Open the configuration file, CS.cfg, in a text editor.
Add the new attributes to the configuration file.

For example, if you want to add three proprietary attributes, MYATTR1 that is a directoryString, MYATTR2 that is a IA5String, and MYATTR3 that is PrintableStrings, you would add the following lines at the end of the configuration file:
X500Name.attr.MYATTR1.oid=1.2.3.4.5.6
X500Name.attr.MYATTR1.class=redhat.security.x509.
DirStrConverter
X500Name.attr.MYATTR2.oid=11.22.33.44.55.66
X500Name.attr.MYATTR2.class=redhat.security.x509.
IA5StringConverter
X500Name.attr.MYATTR3.oid=111.222.333.444.555.666
X500Name.attr.MYATTR3.class=redhat.security.x509.
PrintableConverter

Save your changes and close the file.
Next, add each new attribute or component (for example, MYATTR1, MYATTR2 and MYATTR3) to the enrollment form. For instructions, see "Adding Attributes to an Enrollment Form" on page 760.
Restart the Certificate Manager.
Reload the enrollment page and verify your changes; the new attributes that you added should now show up in the form.
To verify that the new attributes are in effect, request a certificate using the manual enrollment form.

Be sure to enter values for the new attributes (so that you can verify whether they appear in certificate subject names). For example, you can enter the following values for the new attributes and look for them in the subject name:
MYATTR1: a_value
MYATTR2: a.Value
MYATTR3: aValue
CN: John Doe
O: Example Corporation

Go to the agent interface and approve your request.
When you receive the certificate, check the subject name. The certificate should show the new attribute values in the subject name.

Adding Attributes to an Enrollment Form

The steps below explain how to add an attribute (or component) to the Manual enrollment form:

Go to this directory: <server_root>/cert-<instance_id>/web-apps/ee
Open the ManUserEnroll.html file in a text editor.
Find the line with the component name that the new component will follow and copy the table row, using the new component name. For the purposes of this instruction, assume that the new component you want to add is DC and that it follows component OU. Here's how you would add a table row for DC:
	<tr>

		<td valign="TOP">

			<div align="RIGHT">

				<font face="PrimaSans BT, Verdana, Arial, Helvetica, 

				 sans-serif" size="-1">Organization unit: </font>

			</div>

		</td>

		<td valign="TOP">

				<input type="TEXT" name="OU" size="30" 

				 onchange="formulateDN(this.form, this.form.subject)">

		</td>

	</tr>
 

 
	<tr>

		<td valign="TOP">

			<div align="RIGHT">

				<font face="PrimaSans BT, Verdana, Arial, Helvetica, 

				 sans-serif" size="-1">Domain component: </font>

			</div>

		</td>

		<td valign="TOP"> 

				<input type="TEXT" name="DC" size="30" 

				 onchange="formulateDN(this.form, this.form.subject)">

		</td>

	</tr> 
 
Save your changes and close the file.
Go to this directory: <server_root>/cert-<instance_id>/web-apps/ee
Open the CS-funcs.js file in a text editor.
Find the line with form.OU != null (or the component that the new component will follow) and add the if block. For example, if the new component is DC and comes after OU, you need to add the lines shown in bold:
	if (form.OU != null) {

		if (OU.value != '') {

			if (doubleQuotes(OU.value) == true) {

					alert('Double quotes are not allowed in Org Unit 

							field');

				OU.value = '';

				OU.focus();

				return;

			}

			if (distinguishedName.value != '') 

				 distinguishedName.value += ', ';

				 distinguishedName.value += 'OU=' + 

				 escapeDNComponent(OU.value);

		}

	}


 
	if (form.DC != null) {

		if (DC.value != '') {

			if (doubleQuotes(DC.value) == true) {

						alert('Double quotes are not allowed in DC 

								field');

				 DC.value = '';

				 DC.focus();

				 return;

			}

			if (distinguishedName.value != '') 

				 distinguishedName.value += ', '; 

				 distinguishedName.value += 'DC=' + 

				 escapeDNComponent(DC.value);

		}

	} 
 
Save your changes and close the file.
Reload the Manual enrollment form in the browser and verify your changes.
To verify that the Enroll for a certificate using the new attribute value.

Changing the DER Encoding Order

You can also change the DER-encoding order of a DirectoryString. (The reason for allowing this to be configurable is that different clients support different encodings for historical reasons.)

The syntax for changing the DER-encoding order of a DirectoryString is as follows:

X500Name.dirStringEncodingOrder=<encoding_list_separated_by_commas>

Possible encoding values are as follows:

Printable
IA5String
UniversalString
BMPString
UTF8String

For example, X500Name.dirEncodingOrder=Printable,BMPString.

To change the DirectoryString encoding:

Stop the Certificate Manager.
Go to this directory: <server_root>/cert-<instance_id>/config
Open the configuration file, CS.cfg, in a text editor.
Add the encoding order to the configuration file.

For example, if you want to specify two encoding values, PrintableString and UniversalString, and the encoding order is PrintableString first and UniversalString next, you would add the following line at the end of the configuration file:
X500Name.directoryStringEncodingOrder=PrintableString,
UniversalString

Save your changes and close the file.
To verify that the encoding order are in effect, enroll for a certificate using the manual enrollment form. Use "John_Doe" for CN.
Go to the agent interface and approve your request.
When you receive the certificate, use the dumpasn1 tool to examine the encoding of the certificate. For details about the dumpasn1 tool, see CS Command-Line Tools Guide.

The CN component of the subject name should be encoded as a UniversalString.

Repeat Steps 6 through 8 above, but use "John Smith for CN this time.

The CN component of the subject name should be encoded as a PrintableString.

Role of Distinguished Names in Certificates

In certificates issued by Certificate System, DNs are used to identify the entity that owns the certificate. In all cases, if you are using Certificate System with a directory, the format of the DNs in your certificates should match the format of the DNs in your directory. It is not necessary that the names match exactly; certificate mapping allows the subject DN in a certificate to be different from the one in the directory.

DNs in End-Entity Certificates

In end-entity certificates issued by Certificate System, DNs are used to identify the end entity that owns the certified key pair. The end entity is one of the following:

The individual who owns the certified key pair (for personal or client certificates-to form this type of DN, use the CN component to specify the user's full name:

CN=<user's_full_name>, OU=<user's_division_name>, O=<company_name>, C=<country_name>
For example:
CN=Jane Doe, OU=Human Resources, O=Example Corporation, C=US

The server that owns the certified key pair (for SSL server certificates)-to form this type of DN, use the CN component to specify the server's fully qualified host name in the form <machine_name>.<your_domain>.<domain>:

CN=<host_name>, OU=<division_name>, O=<company_name>, C=<country_name>
For example:
CN=corpDirectory.example.com, OU=Human Resources, O=Example Corporation, C=US
When clients such as Netscape Navigator receive a server certificate, they expect the CN component of the certificate's subject to match the host name in the URL. If the name in the certificate and the host name of the server do not match, Navigator notifies the user and gives the user the choice of not connecting to the server.
For example, if Navigator goes to the URL https://corpDirectory.example.com and receives a certificate from the server, it expects the CN component of the certificate's subject to be corpDirectory.example.com. If the CN component has a different value (for example, corpDir.example.com), Navigator notifies the user that the certificate's subject name does not match the host name in the URL.

DNs in CA Certificates

In CA certificates issued by Certificate System (for both root and subordinate CAs), DNs are used to identify the authority who owns the certified key pair.

To form this type of distinguished name, use the CN component to specify the name of your CA: CN=<CA_name>, O=<company_name>, C=<country_name>

For example: CN=Example Corporation Certificate Authority, O=Example Corporation, C=US

DN Patterns and Certificate Subject Names

You can configure Certificate System to issue certificates with subject names that are formulated from the directory attributes and entry DN. The dnpattern configuration variable of the automated-enrollment modules enable you to configure the server to issue certificates with required subject names. Note that dnpattern is a string representing a subject name pattern to formulate from the directory attributes and entry DN. If empty or not set, Certificate System uses the LDAP entry DN as the certificate subject name.

The dnpattern configuration variable supports escaped commas and multiple attribute variable assertions (AVAs) in a RDN. Below is the syntax for the DN pattern followed by examples.

Syntax
dnPattern := rdnPattern *[ "," rdnPattern ]

rdnPattern := avaPattern *[ "+" avaPattern ]

avaPattern := name "=" value | name "=" "$attr" "." attrName [ "." 

	attrNumber ] | name "=" 

"$dn" "." attrName [ "." attrNumber ] | "$dn" "." "$rdn" "." number
 
Example 1

If the configured DN pattern is

E=$attr.mail.1, CN=$attr.cn, OU=$dn.ou.2, O=$dn.o, C=US

LDAP entry: dn: UID=jdoe, OU=IS, OU=people, O=example.com
LDAP attributes: cn: Jane Doe
LDAP attributes: mail: jdoe@example.com

The subject name formulated will be as follows:

E=jdoe@example.com, CN=Jane Doe, OU=people, O=example.com, C=US

E= the first `mail' LDAP attribute value in user's entry.
CN= the (first) `cn' LDAP attribute value in the user's entry.
OU= the second `ou' value in the user's entry DN.
O= the (first) `o' value in the user's entry DN.
C= the string `US'

Example 2

If the configured DN pattern is

E=$attr.mail.1, CN=$attr.cn, OU=$dn.ou.2, O=$dn.o, C=US

LDAP entry: dn: UID=jdoe, OU=IS+OU=people, O=example.com
LDAP attributes: cn: Jane Doe
LDAP attributes: mail: jdoe@example.com

The subject name formulated will be as follows:

E=jdoe@example.com, CN=Jane Doe, OU=people, O=example.com, C=US

E= the first `mail' LDAP attribute value in user's entry.
CN= the (first) `cn' LDAP attribute value in the user's entry.
OU= the second `ou' value in the user's entry DN; note the multiple AVAs in a RDN in this example.
O= the (first) `o' value in the user's entry DN.
C= the string `US'

Example 3

If the configured DN pattern is

CN=$attr.cn, $rdn.2, O=$dn.o, C=US

LDAP entry: dn: UID=jdoe, OU=IS+OU=people, O=example.com
LDAP attributes: cn: Jane Doe
LDAP attributes: mail: jdoe@example.com

The subject name formulated will be as follows:

CN=Jane Doe, OU=IS+OU=people, O=example.com, C=US

CN= the (first) `cn' LDAP attribute value in the user's entry followed by the second RDN in the user's entry DN.
O= the (first) `o' value in the user's entry DN.
C= the string `US'

Example 4

If the configured DN pattern is

CN=$attr.cn, OU=$dn.ou.2+OU=$dn.ou.1, O=$dn.o, C=US

LDAP entry: dn: UID=jdoe, OU=IS+OU=people, O=example, org
LDAP attributes: cn: Jane Doe
LDAP attributes: mail: jdoe@example.org

The subject name formulated will be as follows:

CN=Jane Doe, OU=people+OU=IS, O="example \, org", C=US

CN= the (first) `cn' LDAP attribute value in the user's entry.
OU= the second `ou' value in the user's entry DN followed by the first `ou' value in the user's entry; note the multiple AVAs in a RDN in this example.
O= the (first) `o' value in the user's entry DN.
C= the string `US'

If an attribute or subject DN component does not exist, the attribute is skipped.

Note	If you are using an LDAP directory in conjunction with Certificate System, the DNs in your certificates should match the DNs in your directory.

Table I-1 Definitions of standard DN components
Component	Name	Definition
CN	Common name	A required component that identifies the person or object defined by the entry. For example: CN=Jane Doe CN=corpDirectory.example.com
E (deprecated)	Email address	Identifies the email address of the entry. For example: jdoe@example.com The use of this component is discouraged by the PKIX standard; instead, it recommends the use of Subject Alternative Name Extension to associate an email address with a certificate; see "subjectAltName" on page 740. The reason for this is because it is usually too hard to have a E in a directory structure; email addresses change too frequently.
OU	Organizational unit	Identifies a unit within the organization. For example: OU=Sales OU=Manufacturing
O	Organization	Identifies the organization in which the entry resides. For example: O=Example Corporation O=Public Power & Gas
L	Locality	Identifies the place where the entry resides. The locality can be a city, county, township, or other geographic region. For example: L=Mountain View L=Pacific Northwest L=Anoka County
ST	State or province name	Identifies the state or province in which the entry resides. For example: ST=California ST=British Columbia
C	Country	Identifies the name of the country under which the entry resides. For example: C=US C=GB
DC	Domain component	Identifies the domain components of a domain. For example, if the domain is example.com, the domain components would be: dc=example, dc=com

Table I-2 Allowed characters for value types
Attribute	Value type	Object identifier
CN	Directory String	2.5.4.3
OU	Directory String	2.5.4.11
O	Directory String	2.5.4.10
C	Printable String of length 2	2.5.4.6
L	Directory String	2.5.4.7
ST	Directory String	2.5.4.8
STREET	Directory String	2.5.4.9
TITLE	Directory String	2.5.4.12
UID	Directory String	0.9.2342.19200300.100.1.1
MAIL	IA5String	0.9.2342.19200300.100.1.3
E	IA5String	1.2.840.113549.1.9.1
DC	IA5String	0.9.2342.19200300.100.1.2.25
SERIALNUMBER (for CEP support)	Printable String	2.5.4.5
UNSTRUCTUREDNAME (for CEP support)	IA5String	1.2.840.113549.1.9.2
UNSTRUCTUREDADDRESS (for CEP support)	Printable String	1.2.840.113549.1.9.8

Table I-3 Explanation of character sets for DNs
Value type	Character set allowed
Printable String	A-Z, a-z, 0-9, space \ ( ) + , - . / : = ?
IA5String	Any 7-bit US ASCII character.
Directory String	Any character in format as specified in Lightweight Directory Access Protocol (v3): UTF-8 String Representation of Distinguished Names (see http://www.ietf.org/rfc/rfc2253.txt). Certificate System conforms to all of this standard, including support of using hex numbers to escape characters. The special characters are as follows: , = + < > # ; They can be escaped by either a backslash (\) before the character or by surrounding the value in double quotes (" "). A few examples are shown below: Example Corp. \, Ltd. "Example Corp. , Ltd" "Example Corp. \, Ltd" Name \, with \= escaped \+ special \< characters \# like \> or \"\\\; "Name , with = special + characters < surrounded > by # quotes; ,=+<>#;" Name with escaped characters like return \0D or C with Caron \C4\8D or L\4C Name with spaces at beginning and end For additional more examples, check the standards.

Contents

Index