Chapter 19   Setting Up LDAP Publishing


iPlanet Certificate Management Server (CMS) provides a customizable publishing framework for the Certificate Manager, enabling it to publish certificates, certificate revocation lists (CRLs), and other certificate-related objects to any of the supported repositories—an LDAP-compliant directory, a flat file, and an online validation authority—using the appropriate protocol.

The ability of a Certificate Manager to publish certificates, CRLs, and other certificate-related objects to a directory using the LDAP or LDAPS protocol is called LDAP publishing and the directory to which it publishes is called the publishing directory.

This chapter explains how to configure the Certificate Manager to publish certificates and CRLs to an LDAP directory. The chapter also tells you how to update the directory manually, if the need arises.

The chapter has the following sections:

• Publishing of Certificates to a Directory

• Publishing of CRLs

• Configuring a Certificate Manager to Publish Certificates and CRLs

• Manually Updating Certificates and CRLs in a Directory

Publishing of Certificates to a Directory

---

Large corporations typically use Lightweight Directory Access Protocol (LDAP) directories, such as iPlanet Directory Server, to store and manage corporatewide data, including user and group information and network resource data. If you have deployed an LDAP-compliant directory, you can configure the Certificate Manager to automatically publish your CA and end-entity certificate-related information to that directory. For example, if you have configured the Certificate Management System to employ directory-based authentication, you should consider publishing the CA and end-entity certificates to the same directory. This way, you can keep your users' security credentials with the rest of the user information (see Figure 19-1).

Figure 19-1    Publishing certificates to a directory for distribution

Note that configuring the Certificate Manager for LDAP publishing is optional—you can turn this feature off without affecting any of the certificate issuance, renewal, and revocation operations handled by the server.

You can configure the Certificate Manager to automatically publish certificates to the directory every time a certificate is issued and at a predetermined interval—for example, every day or once every week. Privileged users (administrators and agents) can also manually initiate the LDAP publishing process.

Figure 19-2 illustrates LDAP publishing by the Certificate Manager when a certificate requested via the manual-enrollment process is issued.

Figure 19-2    Publishing by a Certificate Manager

Figure 19-3 illustrates how certificates requested via a Registration Manager get published to the directory.

Figure 19-3    Publishing of certificates requested via a Registration Manager

Timing of Directory Updates

If the LDAP directory is properly configured to work with the Certificate Manager (and vice versa), any changes to the certificate information in the Certificate Manager are automatically made also in the publishing directory.

The publishing directory is updated at these times:

• When the Certificate Manager starts up, it publishes its CA signing certificate to the directory.

• When the Certificate Manager issues a new certificate (the request may originate from Registration Managers that're connected to the Certificate Manager), it stores a copy of the certificate in its internal database and then publishes the certificate to the configured directory.

• When the Certificate Manager revokes a certificate (the request may originate from Registration Managers that're connected to the Certificate Manager), it marks the copy of the certificate in its internal database as revoked and then unpublishes or removes the revoked certificate from the configured directory.

• When a certificate expires, the Certificate Manager can remove that certificate from the configured directory. Note that the server doesn't do this automatically. You need to configure the server to run the appropriate job. For details, see Configuring a Subsystem to Run Automated Jobs.

• When the certificate revocation list is created or updated (either through the CMS window or through the certificate-revocation feature provided in the agent or end-entity interface), the Certificate Manager publishes that list to the configured directory.

Table 19-1 summarizes the above-listed actions of the Certificate Manager. The table also indicates how the Certificate Manager populates an LDAP directory, if configured for publishing. Note that certificates (and CRLs) are published as DER-encoded binary blobs.

Table 19-1    Details of objects published by the Certificate Manager  

Object	Action and Timing	LDAP entry	LDAP attribute
End-entity certificate	Publishing occurs when a certificate is issued or renewed	End-entity's entry	userCertificate;binary
	Unpublishing (removal) occurs when a certificate is revoked or expired	End-entity's entry	userCertificate;binary
CA certificate	Publishing occurs when the Certificate Manager is started	CA's entry	caCertificate;binary
CRL (full)	Publishing (replacement) occurs when a new CRL is generated	CA's entry	certificateRevocation List;binary

The Certificate Manager cannot update the directory in the following cases:

• If an end-entity entry is not present or if an entry cannot be found to publish the certificate.

• If the directory's schema doesn't include the appropriate attributes. To configure the directory for LDAP publishing, see Step 2. Set Up the Directory for Publishing. Note that the Certificate Manager publishes to the userCertificate;binary attribute, which is an LDAP v3 standard. Unless you are using a non-standards compliant directory, this situation shouldn't arise.

• When the directory is unreachable because maintenance work is being performed, or because of network or system failures.

Note that the Certificate Manager's LDAP publishing action happens as a separate transaction from any certificate operation (such as issuance); the operation of a certificate is not affected by whether it was successfully published or not.

Directory Update Process

As indicated in Table 19-1, when a Certificate Manager is requested to issue a certificate, update certificate information, or publish a CRL, it automatically updates the corresponding entry in the configured directory with relevant information. To locate the correct directory entry, the Certificate Manager relies on object-mapping rules, which can be defined using the mapper modules. Once an entry is located in the directory, to publish the object to the correct attribute of the located entry, the Certificate Manager relies on object-publishing rules, which can be defined with the help of publisher modules. For details about mapper and publisher modules, see Chapter 5, "Mapper Plug-in Modules" and Chapter 6, "Publisher Plug-in Modules" of CMS Plug-Ins Guide.

Similarly, when you revoke a certificate, the Certificate Manager uses the object mapping and publishing rules to locate and delete the corresponding certificate from the directory.

For step-by-step instructions to configure a Certificate Manager to publish to an LDAP directory, see Configuring a Certificate Manager to Publish Certificates and CRLs.

Directory Synchronization

The Certificate Manager and the publishing directory can become out of sync if certificates are issued or revoked while Directory Server is down. Certificates that were issued or revoked need to be published or unpublished manually when Directory Server comes back up.

To help find certificates that are out of sync with the directory—that is, valid certificates that are not in the directory and revoked or expired certificates that are still in the directory—the Certificate Manager keeps a record of whether a certificate in its internal database has been published to the directory. If the Certificate Manager and the publishing directory become out of sync, you can use the Update Directory option in the Certificate Manager Agent Services interface to synchronize the publishing directory with the internal database.

The following choices are available for synchronizing the directory with the internal database:

• Search the internal database for certificates that are out of sync and publish or unpublish accordingly.

• Publish certificates that were issued from time A to time B while Directory Server was down. Similarly, unpublish certificates that were revoked or that expired while Directory Server was down.

• Publish or unpublish a range of certificates based on serial numbers (from serial number xx to serial number yy).

For instructions, see Manually Updating Certificates in the Directory.

Publishing of CRLs

---

This section covers the following topics:

• What's a CRL?

• Reasons for Revoking a Certificate

• Revocation Checking by Netscape Clients

• Revocation Checking by iPlanet Servers

• Publishing of CRLs to an LDAP Directory

• CRL Issuing Points

What's a CRL?

Server and client applications that use public-key certificates as tokens of identification need access to information about the validity of a certificate; because one of the factors that determines the validity of a certificate is its revocation status, these applications need to know whether the certificate being validated has been revoked. In that regard, the CA has a responsibility to do the following:

• Revoke the certificate if any of the certificate assertions becomes false—for example, if the subject's key gets compromised or the status of the subject's role or right changes. (See Reasons for Revoking a Certificate.)

• Make the revoked certificate available to parties or applications that need to verify its validity status.

One of the standard methods for conveying the revocation status of certificates is by publishing a list of revoked certificates. This list is known as the certificate revocation list (CRL). The CRL is a publicly available list of certificates that have been revoked.

A CRL is issued and digitally signed by the certificate authority (CA) that issued the certificates listed in the CRL. The CA may use a single key pair to sign the certificates and CRLs or two separate key pairs, one for signing certificates and another one for signing CRLs. The CA's function includes creating the CRLs periodically and distributing them to other applications. For example, the CA may publish the CRL to a global directory which other applications may use for checking the revocation status of a certificate or from which other applications can retrieve the CRL.

In Certificate Management System, the Certificate Manager can create the CRL, sign it, and publish it to any of the configured repositories, such as an LDAP directory, a file, and an OCSP responder. Configuring a Certificate Manager to publish CRLs is optional. Note that the Registration Manager cannot create or publish the CRL.

By default, the Certificate Manager uses a single key pair for signing the certificates it issues and CRLs it generates. This key pair and the corresponding certificate is explained in CA Signing Key Pair and Certificate. You may choose to create another key pair for the Certificate Manager and use it exclusively for signing the CRLs it generates. For details, see CRL Signing Key Pair and Certificate.

Normally, whenever a certificate is revoked (by administrators, agents, or end users), the Certificate Manager automatically updates the status of the certificate in its internal database—it marks the copy of the certificate in its internal database as revoked and removes the revoked certificate from the directory, if the Certificate Manager is configured to do so. In addition to certificates, the Certificate Manager also maintains a CRL in its internal database. You can configure the Certificate Manager to generate the CRL every time a certificate is revoked and at periodic intervals.

You can also configure the Certificate Manager to generate and publish CRLs conforming to X.509 (either version 1 or version 2) standards by enabling or disabling the CRL extension-specific modules in the server's configuration. Note that the server supports standard CRL extensions that are explained in Chapter 7, "CRL Extension Plug-in Modules" of CMS Plug-Ins Guide.

For instructions on how to configure a Certificate Manager to publish CRLs, see Configuring a Certificate Manager to Publish Certificates and CRLs.

Reasons for Revoking a Certificate

A Certificate Manager can revoke any certificate it has issued. A certificate needs to be revoked if one or more of the following situations occur:

• The owner of the certificate has changed status and no longer has the right to use the certificate.

• The private key of a certificate owner has been compromised.

• The certificate owner doesn't want to use the certificate.

• The private key of the CA that issued the certificate has been compromised.

A certificate can be revoked by administrators, agents, and end entities, such as end users and individual server administrators. Agents and administrators (with agent privileges) can revoke certificates by using the forms provided in the agent interface. Administrators, agents, and end users can revoke certificates by using the forms provided in the Revocation tab of the end-entity interface. Note that end users can revoke only their own certificates, whereas agents and administrators can revoke any certificates issued by the server. End users are also required to authenticate to the server in order to revoke their certificate; see Authentication of End Users During Certificate Revocation.

Whenever a certificate is revoked, the Certificate Manager updates the status of the certificate in its internal database. This way, the server keeps track of all revoked certificates in its internal database and it makes the revoked list of certificates public (by publishing it to a central repository) to notify other users that the certificates in the list are no longer valid.

Revocation Checking by Netscape Clients

At the time of this writing, Netscape Communicator versions 4.7 and later, when used in conjunction with the security module called Netscape Personal Security Manager, enable automatic revocation-status verification of certificates using the OCSP protocol. Chapter 21 "Setting Up an OCSP Responder" explains how the revocation status of a certificate is verified in an OCSP-compliant PKI setup.

Earlier versions of Netscape client products do not have the ability to automatically check to see whether a certificate has been revoked. However, these clients do give the user the ability to check the revocation status of a certificate if it includes the NetscapeRevocationURL extension. For details about this extension, check this site: http://home.netscape.com/eng/security/cert-exts.html

In addition, from the Retrieval tab of the CMS end-entity interface, Netscape client users can manually check the revocation status of a particular certificate and automatically import the latest version of the CRL into their browsers. If your users are not using Netscape clients, they can download the latest CRL in binary form to a local file, and then import this file into their browsers by an appropriate method. Users can also view the header information of the master or full CRL published by the Certificate Manager, which contains the date and time of the latest update, and then compare this information to that in their browser's CRL to see if they have the latest version.

Revocation Checking by iPlanet Servers

Because iPlanet servers currently cannot check the revocation status of a certificate, you should use other forms of access control. For example, you can remove individual users from access groups to prevent them from accessing the server.

Because Certificate Management System can check the revocation status of the certificates that it issues, you do not need to rely on other forms of access control.

Publishing of CRLs to an LDAP Directory

The Certificate Manager can publish the CRL to an LDAP-compliant directory using the LDAP protocol or LDAP over SSL (LDAPS) protocol, and applications can retrieve the CRL over HTTP. Support for retrieving CRLs over HTTP enables some browsers, such as Netscape Communicator, to automatically import the latest CRL from the directory that receives regular updates from the Certificate Manager. The browser can then use the CRL to automatically check all certificates to ensure that they have not been revoked.

For applications that are incapable of retrieving the CRL over HTTP, the Certificate Manager also supports retrieval of the CRL in binary form. For example, if the browser you've deployed doesn't support CRL retrieval over HTTP, your users may download the CRL to a local file and then import the file into their browsers by an appropriate method.

You can configure a Certificate Manager to publish the CRL it maintains to a directory, for example, to the same directory in which end-entity certificates are published. If you configure the Certificate Manager and directory to work properly, any changes to the CRL information in the Certificate Manager are automatically updated in the publishing directory. Note that the server publishes the CRL to the certificateRevocationList;binary attribute of the CA's entry in the directory. To locate the correct directory entry, the Certificate Manager uses object mapping rules; to publish the CRL to the correct attribute of the located entry, the server uses publishing rules. For details about mapper and publisher rules, see Chapter 5, "Mapper Plug-in Modules" and Chapter 6, "Publisher Plug-in Modules" of CMS Plug-Ins Guide.

Directory updates take place depending on how you configure the Certificate Manager—that is, publish the CRL to the directory every time a certificate is revoked or at specific intervals, or both. It's important to understand that when the Certificate Manager revokes a certificate, it marks the copy of the certificate in its internal database as revoked, generates the CRL, and then publishes it to the configured directory. For example, if you configure the server to publish the CRL every time a certificate is revoked, CRL will be generated whenever a certificate is revoked.

For instructions on configuring a Certificate Manager for publishing CRLs to a directory, see Configuring a Certificate Manager to Publish Certificates and CRLs.

If the Certificate Manager and publishing directory become out of sync for some reason, privileged users (administrators and agents) can also manually initiate the publishing process. For instructions, see Manually Updating the CRL in the Directory.

CRL Issuing Points

Because CRLs can grow very large, several methods have been developed to minimize the overhead of retrieving and delivering large CRLs. One of these methods is based on partitioning the entire certificate space and associating a separate CRL with every partition. This partition is called a CRL issuing or distribution point—it is the location where a subset of all the revoked certificates are maintained. Partitioning can be based on revocation reason, on whether the revoked certificate is a CA certificate or end-entity certificate, on end users' names, and so on. Each issuing point is identified by a set of names, which can be in various forms.

Once the issuing points have been defined, they can be included in certificates so that an application that needs to check the revocation status of a certificate can access the CRL issuing points specified in the certificate instead of the master or main CRL—the application would check the CRL maintained at the issuing point, which would be smaller in size compared to the master CRL, and thus speed up the revocation-status-checking process.

CRL distribution points can be associated with certificates by setting the CRLDistributionPoint extension in them.

By default, the Certificate Manager only generates and publishes a single CRL, identified as the master CRL. However, for interoperatability purposes, the server does enable you to add the CRLDistributionPoint extension to the certificates it issues. For details, see section "CRLDistributionPointsExt Plug-in Module" in Chapter 4, "Certificate Extension Plug-in Modules" of CMS Plug-Ins Guide.

Configuring a Certificate Manager to Publish Certificates and CRLs

---

If you are using an LDAP-compliant directory, such as iPlanet Directory Server, to publish and manage your user and group data, you can configure the Certificate Manager to communicate with this directory. The Certificate Manager can then publish end-entity as well as CA certificates and the certificate revocation list (CRL) to the directory. This way, your publishing directory acts as a common distribution point for information about users and other entities on the network, including each entity's current security credentials.

Once the Certificate Manager is configured to publish to the directory, many certificate and CRL-related operations are performed automatically. For details, see Timing of Directory Updates.

To configure a Certificate Manager to publish certificates and CRLs to a directory, follow these steps:

• Step 1. Before You Begin

• Step 2. Set Up the Directory for Publishing

• Step 3. Configure the Certificate Manager to Publish Certificates

• Step 4. Configure the Certificate Manager to Publish CRLs

• Step 5. Identify the Publishing Directory

• Step 6. Test Certificate and CRL Publishing (optional)

Step 1. Before You Begin

Before configuring a Certificate Manager to publish it CA certificate, end-entity certificates, and CRLs to a directory, do this:

• Read Publishing of Certificates to a Directoryand Publishing of CRLs to an LDAP Directory to understand how the Certificate Manager publishes certificates and CRLs to the directory.

• Read Chapter 5, "Mapper Plug-in Modules" and Chapter 6, "Publisher Plug-in Modules" of CMS Plug-Ins Guide. Be sure to take a look at the default mappers and publishers created during CMS installation and determine whether they are suitable for your setup. If they're unsuitable, decide on the mapper and publisher modules you want to use.

• If you decided to not use the default mappers created using the LdapCaSimpleMap module, you will be required to manually create an entry for the CA in the publishing directory. (This document explains how to create an entry for the CA in Netscape Directory Server, version 4.x only.)

• Read Publishing of CRLs. Determine whether you want the Certificate Manager to publish version 1 or version 2 CRLs to the directory. If you decide to publish version 2 CRLs, read Chapter 4, "Certificate Extension Plug-in Modules" of CMS Plug-Ins Guide and determine the CRL extensions you want the Certificate Manager to set; you will be required to configure the server to set these extensions.

• Identify your publishing directory. If you've already configured the Certificate Manager to use an LDAP directory for authenticating users (for example, if you're using the directory-based or directory- and PIN-based authentication), you should consider publishing certificates and CRLs to the same directory. This way, users' security credentials will be kept with the rest of the user information.

• Note the following information for the directory: the host name, the port number, and the port type—whether it's an SSL or nonSSL port.

• Determine how you want the Certificate Manager to authenticate to the directory: whether to publish with basic authentication, publish over SSL without SSL client authentication, or publish over SSL with SSL client authentication. Accordingly, you will need to configure the Directory Server.

• If you want the Certificate Manager to authenticate to the directory using SSL client authentication, determine the certificate the Certificate Manager must use for SSL client authentication; see Certificate Manager's Key Pairs and Certificates. By default, the server uses its SSL server certificate; see SSL Server Key Pair and Certificate.

  Depending on your PKI setup, you may use an external CA for requesting the certificate. For example, if your Certificate Manager is a subordinate CA to an external CA, you can get the Directory Server's certificate signed by the same CA that signed your Certificate Manager's certificate.

• If certificates the Directory Server and Certificate Manager will use during SSL-enabled communication already exist, check the CA that issued these certificates. The CA that issued the Directory Server's SSL server certificate must be trusted by the Certificate Manager. Similarly, the Directory Server must trust the CA that issued the certificate the Certificate Manager will use for client authentication.

• Determine how you want the Certificate Manager to bind to the directory: whether to bind as CN=directory manager or as another user; if it's another user, the entry must have read-write privileges to the directory tree that contains entries for end-entities to whom you intend to issue certificates.

• If you're not the directory administrator, consult the directory administrator about making changes to the schema, if required.

• Keep your directory documentation handy. For an online version of iPlanet Directory Server documentation, check this file: <server_root>/manual/index.html

  You can find documentation for other versions of Directory Server at this site: http://wwws.sun.com/software/products/directory_srvr/home_directory.html

Step 2. Set Up the Directory for Publishing

For a Certificate Manager to publish certificates and CRLs to an LDAP directory, the directory needs to be set up to receive certificate- and CRL-related information from the Certificate Manager.

• Step A. Verify the Directory Schema

• Step B. Add an Entry for the CA

• Step C. Identify an Entry That Has Write Access

• Step D. Verify Entries for End Entities

• Step E. Specify the Directory Authentication Method

• Step F. Modify the Certificate Mapping File

• Step G. Restart Directory Server

Step A. Verify the Directory Schema

For a Certificate Manager to publish certificates and CRLs to a directory, it must be configured with specific attributes and object classes. This section discusses those basic schema requirements. Is it assumed that you're familiar with directory schema and related terminology. If you're not, check the Directory Server documentation.

Required Schema for Publishing End-Entity Certificates
The Certificate Manager publishes an end entity's certificate to the userCertificate;binary attribute within the end entity's or subject's directory object. This attribute is multivalued; each value is a DER encoded binary X.509 certificate. The LDAP object class named inetOrgPerson allows this attribute. This object class is supported by Netscape Directory Server versions 1.0, 3.x, and 4.x. The mix-in object class named strongAuthenticationUser allows this attribute and can be combined with any other object class to allow certificate publication to that object. Note that the Certificate Manager does not automatically add this object class to the schema table of the corresponding Directory Server while publishing or unpublishing end-entity certificates. If the directory object that it finds does not allow the userCertificate;binary attribute, the addition or removal of that specific certificate fails.

If you have created user entries as inetOrgPerson, the userCertificate;binary attribute already exists in the directory. Otherwise, you must add the userCertificate;binary attribute to your directory's schema table. For information on modifying directory schema, check the Directory Server documentation.

Required Schema for Publishing the CA Certificate
The Certificate Manager publishes its own CA certificate in the caCertificate;binary attribute of the CA's directory object when the server is started; this is the object that corresponds to the Certificate Manager's issuer name. This is a required attribute of the certificationAuthority object class. Note that the Certificate Manager will add this object class to the directory entry for the CA, provided that it finds the CA's directory entry.

Required Schema for Publishing CRLs
The Certificate Manager maintains its list of revoked certificates in its internal database; this list is called the certificate revocation list (CRL). You can configure the server to publish the CRL to the directory whenever it is generated, which could be when a certificate is revoked and at regular intervals. You can also manually trigger the server to generate a CRL and publish it to the directory.

The Certificate Manager publishes the updated CRL to the CA's directory object under this attribute: certificateRevocationList;binary.

This attribute is an attribute of the object class certificationAuthority. The value of the attribute is the DER encoded binary X.509 certificate revocation list. The CA's entry must already be a certificate authority.

Step B. Add an Entry for the CA

Complete this step only if you want to manually create an entry for your CA in the directory—that is, you do not want use the automated feature built into the LdapCaSimpleCAMap plug-in module for creating the CA's entry in a directory.

For the Certificate Manager to publish its CA certificate and CRL, the directory must include an entry for the CA. This section explains how to manually add this entry in iPlanet Directory Server using the Directory Server window (which you can launch from within iPlanet Console). To add this entry in Netscape Directory Server 3.x, use its HTML forms-based interface (also called the HTTP gateway).

When adding the CA's entry to the directory, you need to select the entry type based on the distinguished name of your CA:

• If your CA's distinguished name begins with the CN component, create a new person entry for the CA. (If you select a different type of entry, the interface may not allow you to specify a value for the CN component.)

• If your CA's distinguished name begins with the OU component, create a new organizational unit entry for the CA.

After you select the correct entry type, you need to specify the required information to create the entry. Note that the entry you create doesn't have to be in the certificationAuthority object class. The Certificate Manager will convert this entry to the certificationAuthority object class automatically by publishing its CA's signing certificate (as explained in Required Schema for Publishing the CA Certificate).

To create an entry for the Certificate Manager in Netscape Directory Server 4.x:

1. Log in to Console (see Logging In to iPlanet Console).

2. Locate the Directory Server instance you want the Certificate Manager to use for publishing certificates and CRLs.

3. Double-click the instance or select the instance and click Open.

   This opens the Directory Server window.

4. Select the Directory tab.

5. Select the domain name, right click, select New, and then select Other.

   The "New object" window appears.

6. Select "person" and click OK.

   The Property Editor - New window appears.

7. Enter the required information.

   Full name. Enter the common name (the value of the CN component) of the CA exactly as it appears in the issuer DN; this DN shows up in the CA's signing certificate. For example, if your CA's issuer DN is CN=testCA, OU=Research Dept, O=Siroe Corp, ST=California, C=US, you should enter testCA in this field.

   Last name. Enter the name again; it must be the same as the one you entered in the "Full name" field.

8. Keep the default values in the remaining fields, and click OK.

   The new entry appears in the Directory tab.

9. Verify that the entry has been created.
   1. Double-click Directory Administrators, click Members, and then click Add.

   2. Search for the user entry you added earlier.

   3. Click OK and again OK.

Step C. Identify an Entry That Has Write Access

When you configure the Certificate Manager to work with Directory Server, you'll be required to specify a distinguished name in the directory that has read-write permissions to the directory. To publish certificates and CRLs to the directory, the Certificate Manager needs to use a user entry (in the directory) that has write access to the directory. This enables the Certificate Manager to bind to the directory as this user and modify the user entries with certificate-related information and the CA entry with CA's certificate and CRL related information.

To provide the Certificate Manager with a user entry that has read-write permission, you can do either of the following:

• Use the DN of an existing entry that has write access. For example, you can use the entry of the Directory Manager or choose an alternative.

• Give write access to the user entry you created for the Certificate Manager in the previous step. The entry can be identified by the Certificate Manager's DN. For example, it may look like this:

  CN=testCA, OU=Research Dept, O=Siroe Corp, ST=California, C=US

For instructions on giving write access to the Certificate Manager's entry, see your LDAP directory documentation. In either case, note the entry DN and the corresponding password as you will be required to identify this user entry to the Certificate Manager later; see Step 5. Identify the Publishing Directory.

Step D. Verify Entries for End Entities

The publishing directory must contain an entry for each end entity for whom you want a certificate published. If the end entity does not have an entry in the directory, the Certificate Manager will not be able to publish the end entity's certificate.

To add an entry for each end entity, you can use the tools provided with Directory Server. Keep in mind that the end-entity entries must belong to an object class, such as inetOrgPerson, that allows the userCertificate;binary attribute.

---

Note

If you configured the Certificate Manager to use directory-based authentication for end entities and are using the same directory for authentication and publishing, you may not have to deal with this issue. The server will not issue certificates to end entities that do not have entries in the directory. See Authentication of End Entities During Certificate Enrollment.

---

Step E. Specify the Directory Authentication Method

Depending on how you want the Certificate Manager to authenticate to the directory, you must set up Directory Server for one of the following methods of communication:

• Publishing With Basic Authentication

• Publishing Over SSL Without Client Authentication

• Publishing Over SSL With Client Authentication

The instructions that follow explain how to configure Netscape Directory Server 4.x for all of the above methods of communication. If you're using any other directory, refer to the documentation that accompanied that product.

Publishing With Basic Authentication
To configure Directory Server for basic authentication:

1. Go to the Directory Server window.

2. Select the Configuration tab, and then in the right pane, select the Encryption tab.

3. Make sure that the Enable SSL box is unchecked. If it's checked, uncheck it.

4. Click Save.

   You are prompted to restart the server. Don't restart the server yet; you can do this after you've made all the configuration changes.

Publishing Over SSL Without Client Authentication
To configure the Directory Server for SSL-enabled communication:

1. Go to the Directory Server window.

2. Select the Configuration tab, and then in the right pane, select the Encryption tab.

3. Check the Enable SSL box.

4. In the Cipher Family section, check the RSA box.

5. Click the Cipher Preferences button and select the appropriate SSL ciphers.

   For details on individual ciphers, click the Help button.

6. In the Client Authentication section, select the "Allow client authentication" option.

   Be sure not to select the "Require client authentication" option. If you do, Console will not be able to communicate with the directory.

7. Click Save.

   You are be prompted to restart the server. Don't restart the server yet; you can do this after you've made all the configuration changes.

Publishing Over SSL With Client Authentication
For the Certificate Manager to publish to the directory with SSL client authentication, Directory Server must:

• Contain an SSL server certificate in its certificate database

• Trust the CA that issued its SSL server certificate

• Trust the CA that issued the certificate the Certificate Manager will use for SSL client authentication

• Use a valid, secure port number for communication with the Certificate Manager

• Have SSL-enabled communication turned on in its configuration

The steps that follow explain how you can configure Directory Server for all of the above.

1. Check the Directory Server's certificate database.

   Before getting an SSL server certificate, determine whether Directory Server already has an SSL server certificate installed in its certificate database and whether you want Directory Server to use the same certificate during the SSL handshake.

   To check the Directory Server's certificate database:

   1. Go to the Directory Server window.

   2. Select the Tasks tab.

   3. From the Console menu, choose the Manage Certificates option.

      The Certificate Management dialog box appears showing a list of all the certificates installed for Directory Server.

   4. Scroll through the list to see if it contains the SSL server certificate that you want to use.

      If the server has an SSL server certificate, check the CA that has issued the certificate. If this CA is trusted by the Certificate Manager, you can configure Directory Server to use the same certificate. If the CA is untrusted by the Certificate Manager and you want the Certificate Manager to trust it, you need to check the Certificate Manager's certificate database for the CA certificate, add it if it isn't present, and specify that it be trusted. For instructions on manipulating the Certificate Manager's certificate database, see Changing the Trust Settings of a CA Certificate.

      After you've made sure that the CA is trusted by the Certificate Manager, go to Step 10.

      If the server does not have an SSL server certificate, or if you don't want the Certificate Manager to trust the CA that has issued the Directory Server's certificate, you must get an SSL server certificate for the Directory Server from a CA that is trusted by the Certificate Manager. You may get this certificate from the Certificate Manager itself. The instructions that follow (Step 2 through Step 9) explain how to do this.

2. Generate an SSL server certificate request for Directory Server.

   The steps below explain in general how to generate a certificate signing request (CSR) using the Certificate Setup Wizard, which is built into the Directory Server window available within Console. For detailed instructions on each step of the wizard, you should read the on-screen instructions and view the online help by clicking the Help button.

   In the first step of generating the CSR, you will be asked to specify whether the certificate is for a new key pair or an exiting key pair and the method for submitting the CSR to the CA.

   If you want to request the certificate from an external CA, you should click the Show CA button to see whether the CA of your interest is listed there. If it is listed, you can open the SSL server enrollment interface of that CA so that you can paste the CSR the wizard will generate.

   If you want to request the certificate from the Certificate Manager, there are three possible ways in which you can submit the CSR to the Certificate Manager:

   • Submit the CSR directly from the wizard; in this method, you do not need to copy the CSR the wizard generates.

   • Submit the CSR as an email to the CA's administrator; to use this method, you need to know the email address of the person who processes certificate requests for the CA and you need to copy the CSR the wizard generates.

   • Submit the CSR manually by pasting it into the Certificate Manager's SSL server enrollment form; to use this method, you need to copy the CSR the wizard generates.

   To generate a certificate request:

   1. In the Directory Server window, select the Tasks tab, and then click the Certificate Setup Wizard button.

   2. Select the token for generating the key pair (and for storing the certificate). Since you don't have the certificate, select No.

      If you're generating the certificate for the first time, the wizard informs you that it needs to create a trust database (cert7.db and key3.db files) for Directory Server.

   3. When prompted for the password, enter the password.

      Remember this password because you will be required to supply it when starting Directory Server from now on. Once the trust database is generated, the wizard steps for generating the CSR begin.

   4. You are asked to specify whether the certificate is for a new key pair or an existing key pair and the method for submitting the CSR to the CA.
      
      

      The choices for submitting the CSR to the CA include the following:

      To CA's email address. Select this if you want to send the CSR to the CA administrator's email address. Type the administrator's email address (for example, jdoe@siroe.com) in the adjoining field. The administrator will then be required to submit the request to the CA by pasting the CSR in the CA's server enrollment form.

      To CA's URL. Select this if you want to submit the CSR to the Certificate Manager directly. Depending on the end-entity port that's enabled, type either of the following URL:

      http://<CA_hostname>:<end_entity_port>/enrollment or https://<CA_hostname>:<end_entity_SSL_port>/enrollment

      Note that the request submitted to the CA's URL gets queued for approval by the Certificate Manager agent.

   5. When the wizard displays the CSR, if you are running the wizard on a Windows NT system, copy the CSR (displayed in its base-64 encoded format) to a text file. The information you copied should look similar to the sample shown below. Do not make any changes to it. (As indicated in the message, a copy of this information is also saved to the /temp file in the host machine's file system.)

      -----BEGIN NEW CERTIFICATE REQUEST-----

      MMIIBnzCCAQgCAQAwXzELMAkGA1UEBhMCVXMxEzARBgNVBAgTCkNBTElGT1JO
      SUExHTAbBgNVBAopME5ldHNjYXBlIENvbW0uIENvcnAuMRwwGgYDVQQDExNzd
      XByaXlhLW50Lm1jb20uY29tMIGfMA0GCSGSIb3DQEBAQUAA4GNADCBiQKBgQC
      k49jBib3SZQqTt5YtIGugnVOq38Y1CcB9owCsapR+DIow8MUVWGRUT38mcX0l
      fpNT4hzW1aePiHersIMZFLxRgel0kEtJ0ClWfNQKzrnOfpL1H3CjcLjSM5hWa
      Ft0M5hfZEtPk+XBsMbu3dCtbRacxs0M2I0AVkf+kp24ePvqD8QIDAQABoA

      -----END NEW CERTIFICATE REQUEST-----

3. Submit the request to a CA and get the SSL server certificate.

   If you decided to submit the certificate request to an external CA, you need to go to that CA's enrollment area and use the form provided for requesting SSL server certificates. After you submit the request, hold on to the confirmation message until you receive the certificate. When the CA sends the certificate to you, complete the remaining configuration, starting from Step 6.

   The instructions in this step explain how to request the SSL server certificate from the Certificate Manager manually. You should complete this step if you didn't use the auto-submit feature of the wizard to directly send the CSR to the Certificate Manager's URL.

   To submit the request to the Certificate Manager manually:

   1. Open a web browser window.

   2. Go to the end-entity interface of the Certificate Manager (or to the Registration Manager that's connected to the Certificate Manager).

   3. In the left frame, under Server, click SSL Server.

   4. In the server enrollment form that appears, enter the required information:

      PKCS#10 Request. Paste the base-64 encoded blob, including the -----BEGIN NEW CERTIFICATE REQUEST----- and -----END NEW CERTIFICATE REQUEST----- marker lines, you copied to the text file earlier.

      Name. Type your full name.

      Email. Type your business email address, for example, jdoe@siroe.com.

      Phone. Type your business phone number.

      Additional Comments. Type any information that will help you identify this request in the future or will help the person who will process this request.

   5. Click Submit.

4. Approve the request you submitted.

   Skip to the next step if you submitted the CSR to an external CA. Complete this step if you submitted the CSR to the Certificate Manager.

   To access the agent queue and approve the SSL server certificate request you submitted:

   1. In the browser window, go to the Certificate Manager Agent Services interface. (If you submitted the request to a Registration Manager, go its agent interface.)

   2. In the left frame, select List Requests. In the form that appears, select the "Show pending request" option and click Find.

   3. In the request queue, locate the request you submitted and click Details.

   4. Verify the information and click Do It.

      If your request contained all the required information, the server issues a certificate and you should see a message indicating so.

   5. Click Show Certificate.

      The complete details about the certificate appear. Don't close the page; in the next step, you'll need to copy the certificate from this page.

5. Copy the SSL server certificate.

   You must go through this step, irrespective of whether you submitted the CSR to the Certificate Manager or to an external CA.

   To install the certificate in the Directory Server's database, you need to have a copy of the certificate in its base 64-encoded format:

   • If you submitted the CSR to an external CA, wait till you receive the certificate. When you receive the certificate, look for the base 64-encoded blob of the certificate.

   • If you submitted the CSR to the Certificate Manager, check the confirmation page that you received in the previous step; it contains the certificate in its base 64-encoded format.

   The steps below explain how to copy the base 64-encoded blob of the certificate from the confirmation page that you received from the Certificate Manager:

   1. In the page that shows the certificate details, scroll down to the section that says "Installing this certificate in a server".

   2. Copy the base-64 encoded certificate, including the ----BEGIN CERTIFICATE----- and -----END CERTIFICATE----- marker lines, to a text file or to the clipboard; be sure not to make any changes to the text blob. An example of the information you should copy is shown below:

      -----BEGIN CERTIFICATE-----

      MMIICVDCCAf6gAwIBAgIBDDANBgkqhkiG9w0BAQQFADB6MQswCQYDVQQGEwJV
      UzELMAkGA1UECBMQ0M0ExFjAUBgNVBAcTDU1vdW50YWluIFZpZXcxETAPBgNV
      BAoTCE5ldHNjYXBlMRUwEwYDVQQLEwxTZW1cml0eVB1YnMxHDAaBgNVBAMTE0
      NlcnRpZmljYXRlIE1hbmFnZXIwHhcNOTkwNzA5MjIxNjQ5WhcMDAwNzA4MjIx
      NjQ5WjCQYDVQQGEwJVczETMBEGA1UECBMKQ0FMSUZPUk5JQTEdMBsGA1UEChM
      UTm0c2NhcGUgQ29tbS4gQ29ycC4xHDAaBgNVBAMTE3N1cHJpeW

      -----END CERTIFICATE-----

6. Install the certificate in the Directory Server's certificate database.

   You must go through this step, irrespective of whether you requested the certificate from the Certificate Manager or from an external CA.

   To install the SSL server certificate in the Directory Server's certificate database:

   1. Go to the Directory Server window.

   2. Start the Certificate Setup Wizard.

   3. In the first step that the wizard displays, select the "Install Certificate for This Server" option.

   4. In the second step, select the "The certificate is located in the following text field" option and paste the certificate blob, including the -----BEGIN CERTIFICATE----- and -----END CERTIFICATE----- marker lines, you copied earlier.

   5. Follow the prompts and add the certificate to the certificate database.

7. Copy the CA chain.

   You must go through this step, irrespective of whether you requested the certificate from the Certificate Manager or from an external CA.

   The steps in this section explain how to copy the CA chain, if you requested the SSL server certificate from a Certificate Manager. If you got the certificate from an external CA, make sure that the CA's chain exists in certificate database of Directory Server; otherwise, go to the CA site and copy the chain.

   1. Go to the end-entity interface of the Certificate Manager (or to the Registration Manager that's connected to the Certificate Manager).

   2. Click the Retrieval tab.

   3. In the left frame, click Import CA Certificate Chain.

   4. In the form that appears, select the "Display the CA certificate chain in PKCS#7 for importing into a server" option, and click Submit.

      The CA certificate chain appears.

   5. Copy the base-64 encoded certificate blob, including the -----BEGIN CERTIFICATE----- and -----END CERTIFICATE----- marker lines, to a text file or the clipboard.

8. Install the CA chain in the Directory Server as a trusted CA.

   To install the CA chain:

   1. Go to the Directory Server window.

   2. Start the Certificate Setup Wizard.

   3. Select the option to install a certificate for a trusted certificate authority.

   4. Select the "The certificate is located in the following text field" option and paste the certificate blob, including the -----BEGIN CERTIFICATE---- and -----END CERTIFICATE----- marker lines, you copied earlier.

   5. Follow the prompts and add the CA certificate chain to the certificate database of Directory Server.

9. Confirm that the new certificates are installed.

   To verify that the certificates are installed in the certificate database of Directory Server:

   1. In the Directory Server window, select the Tasks tab.

   2. From the Console menu, select Manage Certificates.

      The Certificate Management dialog box appears showing a list of certificates installed for Directory Server.

   3. Scroll through the list. You should find the certificates you installed. If you find the certificates, your server is ready for SSL activation.

10. Verify the port number.

    Before turning on SSL-enabled communication for Directory Server, you must verify that the configured port number can be used for this purpose. If not, you must change the port number to a valid one.

    To modify the port (for a secure port) on which the Directory Server listens for incoming requests:

    1. In the Directory Server window, select the Configuration tab, and then in the navigation tree, select the root (the topmost) item.

    2. Select the Settings tab in the right pane.

       Port. Type the port number you want the server to use for non-SSL communication. The default port number is 389.

       Encrypted Port. Type the port number you want the server to use for SSL-enabled communication. The default secure port number is 636. The encrypted port number that you specify must not be the same as one you specified in the Port field.

    3. Click Save.

       You are be prompted to restart the server. Don't restart the server yet; you can restart it after you've made all the changes.

       Be aware that changing the Directory Server port number requires you to change the corresponding port number in all other servers that communicate with the directory. For example, if you have other servers installed that point to the directory, you need to update those server configurations to use the new port number. For details, see Managing Servers with Console.

11. Turn on SSL-enabled communication.

    To turn on SSL-enabled communication in Directory Server:

    1. In the Directory Server window, select the Configuration tab, and then in the right pane, select the Encryption tab.

    2. Check the Enable SSL box.

    3. In the Cipher Family section, check the RSA box.

    4. Click the Cipher Preferences button and select the appropriate SSL ciphers.

       For details on individual ciphers, click the Help button.

    5. In the Token drop-down list, select the token that contains the key pair for the certificate you installed (or for the certificate you want the server to use).

    6. Select the certificate you want the server to use during SSL-enabled communication with the Certificate Manager.

    7. In the Client Authentication section, select the appropriate option:

       Do not allow client authentication. Select this if you want to configure the directory for basic authentication or for SSL-based communication without client authentication.

       Allow client authentication. Select this if you want to configure the directory for SSL client authenticated communication.

       Require client authentication. Don't select this option. If you do, Console will not be able to communicate with Directory Server. This is because Console does not support client-authenticated communication yet. For example, if you're using the same directory for user data and configuration information of other servers and if you configure Directory Server to require client authentication, you will no longer be able to manage your Netscape servers from Netscape Console; instead, you will be required to use the command-line tools.

    8. Click Save.

       You are prompted to restart the server. Don't restart the server yet; you can restart it after you've made all the required changes.

Step F. Modify the Certificate Mapping File

This step explains how to modify the certmap.conf file to add a certificate mapping rule for the CA's entry you created. You need to go through this step only if you configured the directory for SSL client authenticated communication. Otherwise, skip to Step G. Restart Directory Server.

When the Certificate Manager presents its certificate for SSL client authentication, Directory Server uses the mapping rule specified in the certmap.conf file to locate the corresponding entry in the directory and then determine the access privileges set for the entry. The certificate mapping file is located in the <server_root>/shared/config directory, where <server_root> is the directory in which the Directory Server binaries are installed.

The certmap.conf file specifies the following:

• Where in the directory tree the server should begin its search for locating the entry in the directory

• What certificate attributes the server should use as search criteria when searching for the entry in the directory

• Whether the server needs to go through any additional verification process

The file contains one or more named mappings, each applying to a different CA.. A mapping has the following syntax:

certmap <name> <issuerDN>
<name>:<property1> [<value1>]
<name>:<property2> [<value2]
...
<name>:<propertyn> [<valuen]

The first line specifies a name for the entry and the DN of the issuer of the client certificate—in this case, the issuer of the certificate the Certificate Manager will present during client authentication. (By default, the Certificate Manager uses its SSL server certificate generated during installation.) The name is arbitrary; you can define it to be whatever you want. However, the issuer DN must exactly match the issuer DN of the CA that has issued the certificate the Certificate Manager will use for client authentication. For example, the following two issuer DN lines differ only in the number of spaces separating the attribute value assertions (AVAs), but the Directory Server will treat these two entries as different:

certmap moz CN=myCA,OU=myDept,O=myCompany,C=US
certmap moz CN=myCA,OU=myDept,O=myCompany, C=US

The second and subsequent lines in the named mapping match properties with values. The certmap.conf file has six default properties, but the ones that should be of use to you are explained below. For in depth detail about the certmap.conf file, see Managing Servers with iPlanet Console.

• DNComps—This is a list of comma-separated DN attribute tags used to determine where in the directory the server should start searching for directory entries that match the Certificate Manager's information (that is, the owner of the client certificate). The Directory Server gathers values for these tags from the certificate presented by the Certificate Manager during client authentication and uses the values to form an LDAP DN, which then determines where the server starts its search in the directory. For example, if you set DNComps to use the <O=org> and <C=country> DN attribute tags (DNComps=O,C) the server starts the search from the O=<org>, C=<country> entry in the directory, where <org> and <country> are replaced with values from the values specified in the subject DN of the certificate presented for client authentication.
  • If the DNComps entry is present but has no value, the server searches the entire LDAP tree for entries matching the filter.

  • If there isn't a DNComps entry in the mapping, the server uses either the CmapLdapAttr setting (if present) or the entire subject DN in the Certificate Manager's certificate.

  The following component tags are supported for DNComps: CN, OU, O, C, L, ST, E, and Mail. Case is ignored. You can use E or Mail, but not both.

• FilterComp—This is a list of comma-separated DN attribute tags used to create a filter by gathering information from the subject DN in the certificate presented during client authentication. Directory Server uses the values for these tags to form the search criteria for matching entries in the directory. If Directory Server finds one or more entries in the directory that match the Certificate Manager's information gathered from the certificate, the search is successful and the server optionally performs a verification. For example, if FilterComps is set to use the attribute tags E and UID (FilterComps=E,UID), the server searches the directory for an entry whose values for E and UID match the Certificate Manager's information gathered from the client certificate. Email addresses and user IDs are good filters because they are usually unique entries in the directory.

  Note that the filter needs to be specific enough to match only the Certificate Manager's entry in the LDAP directory. The following component tags are supported for FilterComps: CN, OU, O, C, L, ST, E, and Mail. Case is ignored. You can use E or Mail, but not both.

• verifycert—This tells the server whether it should compare the certificate the Certificate Manager presents during client authentication with the certificate found in the Certificate Manager's entry in the directory. It takes one of the two values: on or off. It is recommended that you set this to on for a complete single sign-on solution. This ensures that Directory Server will authenticate the Certificate Manager unless the certificate presented exactly matches the certificate stored in the directory.

The following two examples illustrate two different ways you can use the certmap.conf file.

certmap default default
default:dnComps
default:filterComps E, UID

certmap MyCA CN=CA,OU=MyGroup,O=MyCompany,C=US
MyCA:dnComps OU,O,C
MyCA:filterComps E
MyCA:verifycert on

This file has two mappings: a default one and another for MyCA. When the Directory Server gets a certificate from anyone other than MyCA, the server uses the default mapping, which starts at the top of the LDAP tree and searches for an entry matching the client's email address and user ID. If the certificate is from MyCA, the server starts its search at the LDAP branch containing the organizational unit and searches for matching email addresses. Also note that if the certificate is from MyCA, the server verifies the certificate with the one stored for the entry in the directory; other certificates are not verified. Note that the issuer DN in the certificate must be identical to the issuer DN listed in the first line of the mapping. Even an extra space after a comma will cause a mismatch.

To modify the certmap.conf file:

1. In the Directory Server host machine, go to this directory: <server_root>/shared/config

2. Open the certmap.conf file in a text editor.

3. Follow the instructions in the file and add the mapping information for the entry you added.
   
   

   The figure above shows the following mapping rule being added to the file:

   certmap myCA CN=rootCA, O=siroe.com
   #myCA:DNComps
   myCA:FilterComps

   This mapping rule specifies that if the name of the CA that signed the certificate used for SSL client authentication by the Certificate Manager is myCA and that the issuer name or DN of the CA is CN=rootCA, O=siroe.com, the server should use the FilterComps attributes to locate the entry.

   If you determine that the certmap.conf file needs an empty DNComps mapping (because your certificate subject name has no overlap with the corresponding directory DN), you may need to modify the default base DN in Directory Server by adding the following to the Directory Server configuration file:

   dn: cn=config
   changetype: modify
   replace: nsslapd-certmap-basedn
   nsslapd-certmap-basedn: dc=siroe, dc=com

4. Save your changes, and close the file.

Step G. Restart Directory Server

For all your changes to take effect, you must restart Directory Server.

• Starting Directory Server

  If you configured the Directory Server for basic authentication or SSL-enabled communication without client authentication, you can start the server from the Directory Server window from within iPlanet Console:

  1. Click the Tasks tab.

  2. Click Restart the Server.

• Starting SSL-Enabled Directory Server

  If you configured the Directory Server for SSL-enabled communication with client authentication, here's how you must start the server:

  • On Windows NT, start the server from the server's host machine and supply the PIN or password that protects the key pair you generated for the Directory Server's certificate. For security reasons, the dialog box that prompts you for this PIN appears only on the server's host machine.

  • On Unix, start the server from the command line.

Step 3. Configure the Certificate Manager to Publish Certificates

This section explains how to specify certificate mapping and publishing rules the Certificate Manager should use to publish certificates to the correct entries in the directory.

• Step A. Modify the Default Mappers, Publishers, and Publishing Rules

• Step B. Add Mappers, Publishers, and Publishing Rules

Step A. Modify the Default Mappers, Publishers, and Publishing Rules

Complete this step if you decided to use any of the default mappers, publishers, and publishing rules created during installation. If you want to create new mappers, publishers, and publishing rules, skip to the next step, Step B. Add Mappers, Publishers, and Publishing Rules.

During installation, the Certificate Manager automatically creates a set of mappers that you would most likely want to use. The names of the default mappers are as follows:

• LdapUserCertMap—for locating the correct attribute of user entries in the directory in order to publish user certificates.

• LdapCrlMap—for locating the correct attribute of the CA's entry in the directory in order to publish the CRL.

• LdapCaCertMap—for locating the correct attribute of the CA's entry in the directory in order to publish the CA certificate.

Similar to mappers, the Certificate Manager also creates a set of publishers for your convenience. The names of the default publishers are as follows:

• LdapCaCertPublisher

• LdapCrlPublisher

• LdapUserCertPublisher

The Certificate Manager also