Previous     Contents     Index     Next     
iPlanet Certificate Management System Plug-ins Guide



Appendix A       Distinguished Names


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

The appendix has the following sections:

For the most part, the information presented in this appendix is specific to Netscape 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 Netscape Directory Server. In Certificate Management 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 Management 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 A-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 Management System by default recognizes components that are listed in Table A-2.


Table A-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.siroe.com

 

E
(deprecated)  

Email address  

Identifies the email address of the entry. For example: jdoe@siroe.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 "SubjectAltNameExt Plug-in Module". 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=Siroe 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 siroe.com, the domain components would be:

  • DC=siroe, 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 Netscape 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=Siroe 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=siroe.com for a client, the LDAP search operation initiated by the client examines only the OU=people subtree in the O=siroe.com directory tree.

Typically, an LDAP search consists of the following components:

  • The base DN—for example, O=Siroe, 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=Siroe, 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 Management System is configured for LDAP publishing, the search point and search criteria are determined by the configuration parameter values; for details, see information about the mapper or publisher classes in Chapter 5 "Mapper Plug-in Modules" and Chapter 6 "Publisher Plug-in Modules." In the absence of a base DN value, Certificate Management 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 Management 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 CMS Installation and Setup Guide.



DNs in Certificate Management System


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

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


Table A-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 A-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 Management 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:

Siroe Corp. \, Ltd.

"Siroe Corp. , Ltd"

"Siroe 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 Management System supports attribute identified in Table A-2. 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 netscape.security.x509.AVAValueConverter interface.

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

  • netscape.security.x509.PrintableConverter—converts a string to a Printable String value. The string must have only printable characters.

  • netscape.security.x509.IA5StringConverter—converts a string to a IA5String value. The string must have only IA5String characters.

  • netscape.security.x509.DirStrConverter—converts a string to a Directory (v3) String. The string is expected to be in DirectoryString format according to RFC 2253.

  • netscape.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=netscape.security.x509.DirStrConverter


Adding New or Proprietary Attributes

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

  1. Stop the Certificate Manager.

  2. Go to this directory: <server_root>/cert-<instance_id>/config

  3. Open the configuration file, CMS.cfg, in a text editor.

  4. 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=netscape.security.x509.
       DirStrConverter
    X500Name.attr.MYATTR2.oid=11.22.33.44.55.66
    X500Name.attr.MYATTR2.class=netscape.security.x509.
       IA5StringConverter
    X500Name.attr.MYATTR3.oid=111.222.333.444.555.666
    X500Name.attr.MYATTR3.class=netscape.security.x509.
       PrintableConverter

  5. Save your changes and close the file.

  6. 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".

  7. Restart the Certificate Manager.

  8. Reload the enrollment page and verify your changes; the new attributes that you added should now show up in the form.

  9. 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: Siroe Corp

  10. Go to the agent interface and approve your request.

  11. 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:

  1. Go to this directory: <server_root>/cert-<instance_id>/web/ee

  2. Open the ManUserEnroll.html file in a text editor.

  3. 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 (the lines you need to add are shown in bold):

       <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>

  4. Save your changes and close the file.

  5. Go to this directory: <server_root>/cert-<instance_id>/web/ee

  6. Open the cms-funcs.js file in a text editor.

  7. 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);
          }
       }

  8. Save your changes and close the file.

  9. Reload the Manual enrollment form in the browser and verify your changes.

  10. 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:

  1. Stop the Certificate Manager.

  2. Go to this directory: <server_root>/cert-<instance_id>/config

  3. Open the configuration file, CMS.cfg, in a text editor.

  4. 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

  5. Save your changes and close the file.

  6. To verify that the encoding order are in effect, enroll for a certificate using the manual enrollment form. Use "John_Doe" for CN.

  7. Go to the agent interface and approve your request.

  8. When you receive the certificate, use the dumpasn1 tool to examine the encoding of the certificate. For details about the dumpasn1 tool, see CMS Command-Line Tools Guide.

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

  9. 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 Management System, DNs are used to identify the entity that owns the certificate. In all cases, if you are using Certificate Management 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. For more information, see Chapter 5 "Mapper Plug-in Modules."


DNs in End-Entity Certificates

In end-entity certificates issued by Certificate Management 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=Siroe 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.siroe.com, OU=Human Resources, O=Siroe 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.siroe.com and receives a certificate from the server, it expects the CN component of the certificate's subject to be corpDirectory.siroe.com. If the CN component has a different value (for example, corpDir.siroe.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 Management 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=Siroe Certificate Authority, O=Siroe Corporation, C=US


Selecting DNs for Certificates

Figure A-1 illustrates the structure of distinguished names you might select for CA certificates, server certificates, and personal certificates.

Figure A-1    Sample directory hierarchy


DN Patterns and Certificate Subject Names

You can configure Certificate Management 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, such as UidPwdDirAuth and UidPwdPinDirAuth, described in Chapter 1 "Authentication Plug-in Modulesenable 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 Management 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=siroe.org
LDAP attributes: cn: Jane Doe
LDAP attributes: mail: jdoe@siroe.org

The subject name formulated will be as follows:

E=jdoe@siroe.org, CN=Jane Doe, OU=people, O=siroe.org, 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=siroe.org
LDAP attributes: cn: Jane Doe
LDAP attributes: mail: jdoe@siroe.org

The subject name formulated will be as follows:

E=jdoe@siroe.org, CN=Jane Doe, OU=people, O=siroe.org, 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=siroe.org
LDAP attributes: cn: Jane Doe
LDAP attributes: mail: jdoe@siroe.org

The subject name formulated will be as follows:

CN=Jane Doe, OU=IS+OU=people, O=siroe.org, 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=siroe, org
LDAP attributes: cn: Jane Doe
LDAP attributes: mail: jdoe@siroe.org

The subject name formulated will be as follows:

CN=Jane Doe, OU=people+OU=IS, O="siroe \, 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.


Previous     Contents     Index     Next     
Copyright © 2001 Sun Microsystems, Inc. Some preexisting portions Copyright © 2001 Netscape Communications Corp. All rights reserved.

Last Updated April 02, 2001