Complete Contents
About This Guide
PART 1: Netscape Certificate Management System
Chapter 1: Introduction to Certificate Management System
Chapter 2: Administration Tasks and Tool
Chapter 3: Configuration
PART 2: Managing Certificate Management System
Chapter 4: Installing and Uninstalling Instances
Chapter 5: Starting and Stopping Instances
PART 3: System-Level Configuration
Chapter 6: Configuring Ports, Database, and SMTP Settings
Chapter 7: Managing Privileged Users and Groups
Chapter 8: Keys and Certificates
PART 4: Authentication
Chapter 9: Introduction to Authentication
Chapter 10: Using the PIN Generator Tool
Chapter 11: Configuring Authentication for End Entities
Chapter 12: Developing Authentication Plug-ins
PART 5: Job Scheduling and Notification
Chapter 13: Introduction to Job Scheduling and Notifications
Chapter 14: Configuring Jobs
PART 6: Policies
Chapter 15: Introduction to Policies
Chapter 16: Configuring Policies
PART 7: LDAP Publishing
Chapter 17: Introduction to LDAP Publishing
Chapter 18: Configuring Subsystems for LDAP Publishing
Chapter 19: Publishing CRLs
PART 8: Agent and End-Entity Interfaces
Chapter 20: Introduction to End-Entity and Agent Interfaces
Chapter 21: Customizing End-Entity and Agent Interfaces
PART 9: Logs
Chapter 22: Introduction to Logs
Chapter 23: Managing Logs
PART 10: Issuance and Management of End-Entity Certificates
Chapter 24: Issuing and Managing End-Entity Certificates
Chapter 25: Recovering Encrypted Data
PART 11: Appendixes
Appendix A: Distinguished Names
Appendix B: Backing Up and Restoring Data
Appendix C: Command-Line Utilities
Appendix D: Certificate Database Tool
Appendix E: Key Database Tool
Appendix F: Netscape Signing Tool
Appendix G: SSL Strength Tool
Appendix H: SSL Debugging Tool
Previous Next Contents Index Bookshelf


Chapter 17 Introduction to LDAP Publishing

Large corporations typically use Lightweight Directory Access Protocol (LDAP) directories, such as Netscape 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 Netscape Certificate Management System (CMS) to automatically publish your end-entity certificate-related information to that directory, called a publishing directory.

If you have configured Certificate Management System to employ directory-based authentication, consider publishing end-entity certificates to the same directory. The advantage of publishing certificates and certificate revocation lists (CRLs) to the directory used for authentication is that you can keep your user's certificate-related information with the rest of the user information (see Figure 17.1).

This chapter explains how Certificate Management System works with the publishing directory and outlines the kind of directory configuration required for publishing certificate-related information.

 The chapter has the following sections:
What Is LDAP Publishing?
In Certificate Management System, LDAP publishing refers to the ability of a Certificate Manager or Registration Manager to publish certificates, CRLs, and other certificate-related objects to a directory using the LDAP protocol. Configuring the Certificate Manager or Registration Manager for LDAP publishing is optional--you can turn this feature off without affecting any of the certificate-management operations handled by the Certificate Manager or Registration Manager.

Figure 17.1 Publishing certificates and CRLs to a directory for distribution

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

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

Figure 17.2 Publishing by a Certificate Manager

Figure 17.3 illustrates a configuration in which both the Registration Manager and Certificate Manager publish to separate directories (both are configured for LDAP publishing). The publishing process is initiated by a certificate issuance operation from a Registration Manager.

Figure 17.3 Publishing by a Registration Manager and Certificate Manager


Timing of Directory Updates
If Directory Server is properly configured to work with Certificate Management System, any changes to certificate information in Certificate Management System are automatically updated in the directory.

 Updates take place at specific times:

 The Certificate Manager and Registration Manager publish specific objects to the directory. For details, see "Objects Published by the Certificate Manager" and "Objects Published by the Registration Manager".

Certificate Management System fails to publish to the directory in the following cases:

 Objects Published by the Certificate Manager

By default, the Certificate Manager publishes specific objects to the directory configured for LDAP publishing. These objects and associated details are listed in Table 17.1. To configure the Certificate Manager for LDAP publishing, see "Configuring Subsystems for LDAP Publishing".

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

Table 17.1 Details of objects published by the Certificate Manager

Object
Action
 Timing
LDAP entry
LDAP attribute
Object format
End-entity certificate
Publish
Occurs when a certificate is issued or renewed

End entity's entry
userCertificate;binary
DER encoded binary blob
End-entity certificate
Unpublish (remove)
Occurs when a certificate is revoked or expired

End entity's entry
userCertificate;binary
DER encoded binary blob
CA certificate

Publish
Occurs when the Certificate Manager is started

CA's entry
caCertificate;binary
DER encoded binary blob
CRL (full)
Publish (replace)
Occurs when a new CRL is generated
CA's entry
certificateRevocationList;binary
DER encoded binary blob

Objects Published by the Registration Manager

By default, the Registration Manage publishes specific objects to the directory configured for LDAP publishing. These objects and the associated details are listed in Table 17.2. To configure the Certificate Manager for LDAP publishing, see "Configuring Subsystems for LDAP Publishing".

As in LDAP publishing by the Certificate Manager, the result of any certificate operation is not affected by the Registration Manager's LDAP publishing action.

Table 17.2 Details of objects published by the Registration Manager

Object
Action
Timing
LDAP entry
LDAP attribute
Object format
End-entity certificate
Publish
Occurs when the Certificate Manager returns a signed certificate for the Registration Manager's issuance or renewal request

End entity's entry
userCertificate;binary
DER encoded binary blob
End-entity certificate
Unpublish
(remove)
Occurs when the Certificate Manager responds success to a revocation request
End entity's entry
userCertificate;binary
DER encoded binary blob


Directory Update Process
When Certificate Management System is requested to issue a certificate or to update certificate information, it automatically publishes or updates the certificate information for the corresponding entry in the configured LDAP directory. To locate the correct directory entry and publish certificate information to it, Certificate Management System uses object mapping and publishing rules. For details, see "Object-Mapping Rules" and "Object-Publishing Rules".

Similarly, when you revoke a certificate, Certificate Management System automatically deletes the corresponding certificate from the directory.

 Object-Mapping Rules

Before Certificate Management System can publish or update a certificate in the directory, it must first find the directory entry that needs to be updated. In order to find the correct directory entry to update, Certificate Management System needs to present the directory (Directory Server) with appropriate search criteria so that it can initiate an LDAP search operation; the server considers the search successful only if Directory Server returns a single LDAP entry that exactly matches the search criteria.

A Certificate Manager or Registration Manager uses object-mapping rules to find the directory entry that needs to be updated. The mapping rules help the server to build appropriate LDAP search criteria (that results in locating the exact entry that needs to be updated) and present it to the LDAP directory. Object- mapping rules are implemented as Java classes and registered in the CMS configuration.

 Built-in Mapper Classes

Mapper classes map an object to an entry in the directory. By default, Certificate Management System provides a single mapper class for mapping certificates to entries in the publishing directory. The rule implemented by this class enables a Certificate Manager or Registration Manager to map an X.509 certificate to an LDAP entry in these ways:

In general, the rule takes DN components to build the search DN. The rule also takes an optional root search DN. The server uses the DN components to form an LDAP entry to begin a subtree search and the filter components to form a search filter for the subtree. If none of the DN components are configured, the server uses the base DN for the subtree. If the base DN is null and none of the DN components match, an error is returned. If none of the DN components and filter components match, an error is returned. If the filter components are null, a base search is performed.

 The Java class provided for mapping certificates to directory entries based on DN components is identified as follows:

 com.netscape.certsrv.ldap.LdapCertCompsMap

 You can also write your own mapper classes by implementing the following Java interface:

 com.netscape.certsrv.ldappublish.ILdapMapper

 For more information about this interface, see the SDKs directory on the product CD.

 Configurable Parameters in the LdapCertCompsMap Class

Figure 17.4 shows how the configurable parameters pertaining to the LdapCertCompsMaps mapper class are displayed in the CMS window.

Figure 17.4 Configurable parameters for the LdapCertMapComps mapper class

With this configuration, a Certificate Manager or Registration Manager maps its certificates with the ones in the LDAP directory by using the dnComps values to form a DN and the filterComps values to form a search filter for the subtree.

 Table 17.3 provides details for each of these parameters.

Table 17.3 Configuration parameters for mapping and publishing certificates and CRLs to the directory

Parameter name
Description
filterComps
The server uses the filterComps values to form an LDAP search filter for the subtree. The server constructs the filter by gathering values for these attributes from the user's DN in the certificate; it uses the filter to search for and match entries in the LDAP directory.

If the server finds one or more entries in the LDAP directory that match the user'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 email and user ID attributes (filterComps=e, uid), the server searches the directory for an entry whose values for email and user ID match the end user's information gathered from the client certificate.

Email addresses and user IDs are good filters because they are usually unique entries in the directory. Keep in mind that email is not always included in the certificate subject name. The filter needs to be specific enough to match one and only one entry in the LDAP database.

Example: UID

Permissible values: Valid directory attributes (in the certificate DN) separated by commas.

The attribute names for the filters need to be attribute names from the certificate, not from ones in the LDAP directory. For example, most certificates have an E attribute for the user's email address; LDAP calls that attribute mail.

Object type: String
dnComps
Use this parameter to specify where in the LDAP directory Certificate Management System should start searching for entries that match the end entity's information (that is, the owner of the certificate). The server uses the dnComps values to form an LDAP entry to begin a subtree search.

The server gathers values for these attributes from the certificate subject name and uses the values to form an LDAP DN, which then determines where in the LDAP directory the server starts its search. For example, if you set dnComps to use the o and c attributes of the DN, the server starts the search from the o=<org>, c=<country> entry in the LDAP directory, where <org> and <country> are replaced with values from the DN in the certificate.

If the dnComps entry is present but has no value, the server searches the entire LDAP tree for entries matching the filter specified by filterComps parameter values.

Example: O,C

Permissible values: Valid DN components or attributes separated by commas.

Object type: String

baseDN
Use this parameter to specify the base DN for the publishing directory. If dnComps is not set, the server uses the base DN value to start its search in the directory.

Example: o=airius.com

Permissible values: Alphanumeric string up to 255 characters; see "Base Distinguished Name".

Object type: String

How Mapping by DN Components Works

Subject names in certificates are in distinguished-name format. A distinguished name (DN) uniquely identifies an entry in an LDAP directory; it consists of components that help identify the entry. The following components are commonly used:

For example, the following DN represents the user named Jane Doe who works for the sales department at Netscape, which is located in Mountain View in the state of California, United States:

CN=Jane Doe, E=jdoe@netscape.com, OU=Sales, O=Netscape, L=Mountain View, ST=CA, C=US

Certificate Management System uses the components in subject names to construct a DN that it can use as the base for searching specific directory entries in order to publish the corresponding certificate information.

 For example, suppose the subject name in the certificate is in this form:

CN=Jane Doe, OU=Sales, O=Netscape, L=Mountain View, ST=CA, C=US

Certificate Management System can use some or all of these components (CN, OU, O, L, ST, and C) to build a DN for searching the directory. When configuring the server for LDAP publishing, you can specify which components the server should use to build a DN (that is, components to match attributes in the directory). You do this by configuring the dnComps parameter; for details, see Table 17.3.

For example, assume you entered components CN, E, OU, O, and C as values for the dnComps parameter. For locating Jane Doe's entry in the directory, Certificate Management System constructs the following DN by reading the DN attribute values from the certificate, and uses the DN as the base for searching the directory:

CN=Jane Doe, OU=My Division, O=My Company, C=US

Note the following:

 In general, for the dnComps parameter, you should enter those DN components that Certificate Management System can use to form the LDAP DN exactly. In certain situations, however, the subject name in a certificate may match more than one entry in the directory. Then, Certificate Management System might not get a single, distinct matching entry from the DN. For example, the subject name

CN=Jane Doe, OU=My Division, O=My Company, C=US

might match two Jane Does in the directory. If that occurs, Certificate Management System needs additional criteria to determine which entry corresponds to the subject of the certificate.

 To specify the components Certificate Management System must use to distinguish between different entries in the directory, use the filterComps parameter; for details, see Table 17.3.

For example, if you entered CN, OU, O, and C as values for the dnComps parameter, enter L for the filterComps parameter only if the L attribute can be used to distinguish between entries with identical CN, OU, O, and C values.

 Consider another example that shows how two directory entries with similar distinguished names can be differentiated by the value of the UID attribute: Assume that the two Jane Doe entries are distinguished by the value of the UID attribute. One entry's UID value is janedoe1 and the other entry's UID value is janedoe2. Because the UID attribute corresponds to the UID component in a distinguished name, you can set up the subject names of certificates to include the UID component.

 Note By default, the E, L, and ST components are not included in the standard set of certificate request forms provided for end entities. You can add these components to the forms, or you can have the issuing agents insert these components when editing the subject name in the certificate issuance forms.

Object-Publishing Rules

If you configure Certificate Management System for LDAP publishing, whenever it issues or updates a certificate information, it needs to publish the certificate information in the corresponding directory entry. Object-publishing rules are a set of publishing rules implemented as a Java class and registered in the CMS configuration.

Built-in Publisher Classes

Publisher classes publish an object to an entry in the directory. By default, Certificate Management System provides publisher classes for publishing CA, end-entity, and other certificates and CRLs to entries mapped by the mapper classes. Table 17.4 lists publisher classes provided out of the box.

You can write your own publisher classes by implementing the following Java interface:

com.netscape.certsrv.ldappublish.ILdapPublisher

For more information on this interface, see the directory named SDK on the product CD or check this site for information on CMS SDK:

 http://home.netscape.com/eng/server/cms

Table 17.4 Default publisher classes and their functions

Publisher class name
Description
LdapUserCertPublisher
Publishes or unpublishes a certificate to the userCertificate;binary attribute of the given entry as a DER encoded binary blob.

Both the Certificate Manager and Registration Manager provide this plug-in module.

LdapCaCertPublisher
Publishes or unpublishes a certificate to the caCertificate;binary attribute of the given entry. Also converts the object class to a certificateAuthority if it's not one already, and similarly removes the certificateAuthority object class on unpublish if the CA has no other certificates.

Only the Certificate Manager provides this plug-in module.

LdapCertAndSubjectPublisher
Publishes or unpublishes a certificate to the userCertificate;binary attribute. The subject name on the certificate is published at the same time to the CertSubjectDN attribute.

Only the Certificate Manager provides this plug-in module.

LdapCrlPublisher
Publishes (replaces) a CRL to the certificateRevocationList;binary attribute of the given entry. The entry should be a certificateAuthority object class.

Only the Certificate Manager provides this plug-in module.


Directory Schema Requirements
A directory must be configured with specific attributes and object classes in order to be used for LDAP publishing by Certificate Management System. This section discusses those basic schema requirements.

 Required Schema for Publishing End-Entity Certificates

Certificate Management System 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.

Certificate Management System does not automatically add this object class in the corresponding Directory Server schema table 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 schema table.

 Required Schema for Publishing CA Certificates

Certificate Management System 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 corresponding to the Certificate Manager's issuer name. This is a required attribute of the object class certificationAuthority.

Certificate Management System will add this object class to the directory object for the CA, provided that it finds the CA's directory object.

 Required Schema for Publishing CRLs

Certificate Management System 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 whenever it is generated--which could be when a certificate is revoked or at regular intervals. You can also manually trigger the server to generate a CRL and publish it to the directory. For details, see "Publishing CRLs".

The server publishes the updated CRL to the CA's directory object under the 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.
Directory Synchronization
Certificate Management System 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 or Registration Manager keeps a record of whether a certificate in its internal database has been published to the directory. If Certificate Management System 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 directory synchronization:

 For details, see "Manually Updating Certificate Information in the Directory".
 

© Copyright 1999 Netscape Communications Corp., a subsidiary of America Online, Inc. All rights reserved.