Chapter 21 Modules for Publishing Certificates and CRLs

When a Certificate Manager is requested to issue a certificate or to update certificate information, it can automatically update the corresponding entry in the configured LDAP directory or the flat file with relevant information. Similarly, when a certificate is revoked, the Certificate Manager can automatically update the configured LDAP directory, the online-validation authority, or the flat file with relevant CRL information. To locate the correct entry and update it with relevant information, the Certificate Manager relies on object-mapping and publishing rules.

• Mapper Modules
• Publisher Modules
• CRL Extension Modules

By default, the Certificate Manager provides a set of mapper plug-in modules for mapping the CA certificate, end-entity certificates, and CRLs to appropriate entries in an LDAP directory; because it's not required to map entries in a flat file and online validation authority, no mapper modules are provided for mapping objects in a flat file or an online validation authority. Plug-in modules are implemented as Java classes and are registered in the CMS publishing framework. The Mapper Plugin Registration tab of the CMS window (Figure 21.1) lists all the modules and the corresponding classes that are registered by default with a Certificate Manager.

The LdapCaSimpleMap plug-in module implements the CA certificate mapper. This mapper enables you to configure a Certificate Manager to automatically create an entry for the CA in an LDAP directory and then map the CA's certificate to the directory entry by formulating the entry's DN from components specified in the certificate's subject name and attribute variable assertion (AVA) constants. For more information on AVAs, check the directory documentation.

The CA certificate mapper allows you to specify whether to create an entry for the CA or to just map the certificate to an existing entry, or to do both; for example, you can choose to manually create an entry for the CA in the directory and then configure the CA certificate mapper to just locate the entry by using attributes from the issuer name in the CA's signing certificate and AVA constants.

During installation, the Certificate Manager automatically creates two instances (called mappers) of the CA certificate mapper module (see Figure 21.2). The mappers are named as follows:

• LdapCrlMap for CRLs (see "LdapCrlMap Mapper")
• LdapCaCertMap for CA certificates (see "LdapCaCertMap Mapper")

Figure 21.2 Default mappers created during installation

The Java class that implements the CA certificate mapper is as follows:

• In the CMS configuration file, the plug-in module is identified as follows: ca.publish.mapper.impl.LdapCaSimpleMap.class=com.netscape.
  certsrv.ldap.LdapCaSimpleMap
• In the CMS window, the module is identified as follows: LdapCaSimpleMap

The mapper named LdapCaCertMap is an instance of the LdapCaSimpleMap module. The Certificate Manager automatically creates this mapper during installation.

The mapper named LdapCrlMap is an instance of the LdapSimpleMap module. The Certificate Manager automatically creates this mapper during installation.

The LdapDNCompsMap plug-in module implements the DN components mapper. This mapper enables you to configure a Certificate Manager to map a certificate to an LDAP directory entry by constructing the entry's distinguished name from components (such as CN, OU, O, and C) specified in the certificate subject name, and then using it as the search DN to locate the entry in the directory. You can use this mapper to locate the following:

• The CA's entry in the directory for publishing the CA certificate and the CRL.
• End-entity entries in the directory for publishing end-entity certificates.

• UID, which represents the user ID of a user in the directory
• CN, which represents the common name of a user in the directory
• OU, which represents an organizational unit in the directory
• O, which represents an organization in the directory
• L, which represents a locality in the directory
• ST, which represents a state in the directory
• C, which represents a country in the directory

• A subject name does not need to have all of the components that you specify for the dnComps parameter. The server ignores any components that are not part of the subject name (such as L, ST, and E in this example).
• Unspecified components are not used to build the DN. In the example, if you did not include the OU component, the server would use this DN as the base for searching the directory:

CN=Jane Doe, O=Siroe Corporation, C=US

LdapDNCompsMap Module

The Java class that implements the DN components mapper is identified as follows:

• In the configuration file, the plug-in module is identified as follows: ca.publish.mapper.impl.LdapDNCompsMap.class=com.netscape.
  certsrv.ldap.LdapCertCompsMap
• In the CMS window, the module is identified as follows: LdapDNCompsMap

• If the formed DN is null, the server uses the baseDN value for the subtree. If both the formed DN and base DN are null, the server logs an error.
• If the filter is null, the server uses the baseDN value for the search. If both the filter and base DN are null, the server logs an error.

The LdapDNExactMap plug-in module implements the subject name mapper. This mapper enables you to configure a Certificate Manager to map a certificate to an LDAP directory entry by searching for the LDAP entry DN that matches the certificate subject name. Note that to be able to use this mapper, each certificate subject name must exactly match a DN in a directory entry. For example, assume the certificate subject name is this:

The Java class that implements the subject name mapper is identified as follows:

• In the configuration file, the plug-in module is identified as follows: ca.publish.mapper.impl.LdapDNExactMap.class=com.netscape.
  certsrv.ldap.LdapCertExactMap
• In the CMS window, the module is identified as follows: LdapDNExactMap

The LdapSimpleMap plug-in module implements the simple mapper. This mapper enables you to configure a Certificate Manager to map a certificate to an LDAP directory entry by formulating the entry's DN from components specified in the certificate's subject name and attribute variable assertion (AVA) constants. For more information on AVAs, see the directory documentation.

The simple mapper requires you to specify just one parameter, which is named dnPattern. The value of dnPattern can be a list of AVA s separated by commas. An AVA can be a variable, such as UID=$subj.UID, or a constant, such as O=Siroe Corporation. By default, the Certificate Manager uses mapper rules that are based on the simple mapper.

During installation, the Certificate Manager automatically creates an instance (called a mapper) of the simple mapper module. The mapper is named LdapUserCertMap (see Figure 21.2). You can use the default mapper to map various types of end-entity certificates the server will issue to their corresponding directory entries. For details, see "LdapUserCertMap Mapper".

The Java class that implements the simple mapper is as follows:

• In the CMS configuration file, the plug-in module is identified as follows: ca.publish.mapper.impl.LdapSimpleMap.class=com.netscape.
  certsrv.ldap.LdapSimpleMap
• In the CMS window, the module is identified as follows: LdapSimpleMap

The rule named LdapUserCertMap is an instance of the LdapSimpleMap module. The Certificate Manager automatically creates this mapper during installation.

The LdapSubjAttrMap plug-in module implements the subject attribute mapper. This mapper enables you to configure a Certificate Manager to map a certificate to an LDAP directory entry by using the LDAP attribute named certSubjectDN. Note that for you to be able to use this mapper, your directory entries must include the certSubjectDN attribute.

The Java class that implements the subject attribute mapper is identified as follows:

• In the configuration file, the plug-in module is identified as follows: ca.publish.mapper.impl.LdapSubjAttrMap.class=com.netscape.
  certsrv.ldap.LdapCertSubjMap
• In the CMS window, the module is identified as follows: LdapSubjAttrMap

• A mapped entry in the directory (entries are mapped by one of the mapper modules explained in "Mapper Modules")
• A particular file
• An online validation authority

By default, the Certificate Manager provides publisher modules for publishing the CA certificate, end-entity certificates, and CRLs. Plug-in modules are implemented as Java classes and are registered in the CMS publishing framework. The Publisher Plugin Registration tab of the CMS window (see Figure 21.8) lists all the modules and the corresponding classes that are currently registered with a Certificate Manager.

The FileBasedPublisher plug-in module implements the flat file publisher. This module enables you to configure a Certificate Manager to publish certificates and CRLs to files, which then can be used for importing the certificates and CRLs into any other repository.

The Java class that implements the flat file publisher is as follows:

• In the CMS configuration file, the plug-in module is identified as follows: ca.publish.publisher.impl.FileBasedPublisher.class=com.
  netscape.certsrv.ldap.FileBasedPublisher
• In the CMS window, the module is identified as follows: FileBasedPublisher

The LdapCaCertPublisher plug-in module implements the CA certificate publisher. This module enables you to configure a Certificate Manager to publish or unpublish a certificate to the caCertificate;binary attribute of the mapped directory entry; the mapper must locate the correct entry so the publisher can publish the certificate to the specified attribute. The certificate is published as a DER encoded binary blob.

The Java class that implements the CA certificate publisher is as follows:

• In the CMS configuration file, the plug-in module is identified as follows: ca.publish.publisher.impl.LdapCaCertPublisher.class=com.
  netscape.certsrv.ldap.LdapCaCertPublisher
• In the CMS window, the module is identified as follows: LdapCaCertPublisher

The publisher named LdapCaCertPublisher is an instance of the LdapCaCertPublisher module. The Certificate Manager automatically creates this publisher during installation.

The LdapUserCertPublisher plug-in module implements the end-entity certificate publisher. This module enables you to configure a Certificate Manager to publish or unpublish a certificate to the userCertificate;binary attribute of the mapped directory entry; the mapper must locate the correct entry so the publisher can publish the certificate to the specified attribute. The certificate is published as a DER encoded binary blob.

The Java class that implements the end-entity certificate publisher is as follows:

• In the CMS configuration file, the plug-in module is identified as follows: ca.publish.publisher.impl.LdapUserCertPublisher.class=com.
  netscape.certsrv.ldap.LdapUserCertPublisher
• In the CMS window, the module is identified as follows: LdapUserCertPublisher

The publisher named LdapUserCertPublisher is an instance of the LdapUserCertPublisher module. The Certificate Manager automatically creates this publisher during installation.

The LdapCrlPublisher plug-in module implements the CRL publisher. This module enables you to configure a Certificate Manager to publish or unpublish the CRL to the certificateRevocationList;binary attribute of the mapped directory entry; the configured mapper must locate the CA's entry so that the publisher can publish the CRL to the certificateRevocationList;binary attribute. The CRL is published as a DER-encoded binary blob.

During installation, the Certificate Manager automatically creates an instance (called a publisher) of the LdapCrlPublisher module for publishing CRLs to the directory. See "LdapCrlPublisher Publisher".

The Java class that implements the CRL publisher is as follows:

• In the CMS configuration file, the plug-in module is identified as follows: ca.publish.publisher.impl.LdapCrlPublisher.class=com.
  netscape.certsrv.ldap.LdapCrlPublisher
• In the CMS window, the module is identified as follows: LdapCrlPublisher

The publisher named LdapCrlPublisher is an instance of the LdapCrlPublisher module. The Certificate Manager automatically creates this publisher during installation.

The ValiCertPublisher plug-in module implements the ValiCert publisher. This publisher enables you to configure a Certificate Manager to publish CRLs to ValiCert Certificate VA (Certificate VA), which can function as a local online validation authority for your PKI setup. For details, see "Local OCSP Support".

By default, the Certificate Manager does not create any instance of the ValiCertPublisher module. The instructions covered in "Publishing CRLs to Online Validation Authority" explain how to create an instance of this module and how to configure a Certificate Manager to publish CRLs to Certificate VA.

The Java class that implements the ValiCert publisher is as follows:

• In the CMS configuration file, the plug-in module is identified as follows: ca.publish.publisher.impl.ValiCertPublisher.class=com.
  valicert.publisher.VcPublisher
• In the CMS window, the module is identified as follows: ValiCertPublisher

Structure of CRL Extensions

A CRL extension consists of the following:

• The object identifier (OID) for the extension; see "Object Identifier".

This identifier uniquely identifies the extension. It also determines the ASN.1 type of value in the value field and how the value is interpreted. That is, when an extension appears in a CRL, the OID appears as the extension ID field (extnID) and the corresponding ASN.1 encoded structure appears as the value of the octet string (extnValue); see the examples in "Sample CRL and CRL Entry Extensions".

• A flag or boolean field called critical.

The true or false value assigned to this field indicates whether the extension is critical (true) or noncritical (false) to the CRL.

• If the extension is critical and the CRL is sent to an application that does not understand the extension (based on the extension's ID), the application must reject the CRL.
• If the extension is not critical and the CRL is sent to an application that does not understand the extension (based on the extension's ID), the application can ignore the extension and accept the CRL.

• An octet string containing the DER encoding of the value of the extension.

Typically, the application receiving the CRL checks the extension ID to determine if it can recognize the ID. If it can, it uses the extension ID to determine the type of value used.

The following is an example of the section of a CRL containing X.509 v2 extensions. (Certificate Management System can display CRLs in human-readable format, as shown here.) As shown in the example, CRL extensions appear in sequence and only one instance of a particular extension may appear in a particular CRL; for example, a CRL may contain only one authority key identifier extension. However, CRL-entry extensions appear in appropriate entries in the CRL.

Certificate Revocation List:

	Data: 

		Version:  v2

...

Extensions: 

	Identifier: Authority Key Identifier

		Critical: no

		Key Identifier:

		2c:22:c6:ae:4e:4b:91:c7:fb:4c:cc:ae:84:e8:aa:5b:46:6a:a0:ad

Extensions: 

	Identifier: Revocation Reason - 2.5.29.21

		Critical: no 

		Reason: Key_Compromise

		Serial Number: 0x12

		Revocation Date: Tuesday, December 15, 1998 5:20:42 AM

Extensions: 

	Identifier: Revocation Reason - 2.5.29.21

		Critical: no

		Reason: CA_Compromise

		Serial Number: 0x11

		Revocation Date: Wednesday, December 16, 1998 4:51:54 AM

Extensions: 

	Identifier: Revocation Reason - 2.5.29.21

		Critical: no

		Reason: Key_Compromise

		Serial Number: 0x10

		Revocation Date: Thursday, December 17, 1998 2:37:24 AM

Extensions:

	Identifier: Revocation Reason - 2.5.29.21

		Critical: no

		Reason: Affiliation_Changed

		Serial Number: 0xA

		Revocation Date: Wednesday, November 25, 1998 5:11:18 AM

...

Overview of CRL Extension Modules

To enable you issue or publish X.509 v2 CRLs (that is, CRLs with extensions), Certificate Management System provides a set of plug-in modules; each module enables you to configure the Certificate Manager to set a particular CRL or CRL-entry extension in CRLs it issues. Plug-in modules are implemented as Java classes and are registered in the CMS publishing framework. The CRL Extensions Management tab of the CMS window (Figure 21.14) lists all the modules that are registered with a Certificate Manager.

The AuthorityKeyIdentifier rule enables you to configure a Certificate Manager to set the Authority Key Identifier Extension defined in X.509 and PKIX standard RFC 2459 (see http://www.ietf.org/rfc/rfc2459.txt) in CRLs. The extension is used to identify the public key that corresponds to the private key used by a CA to sign CRLs.

The CRLNumber rule enables you to configure a Certificate Manager to set the CRL Number Extension defined in X.509 and PKIX standard RFC 2459 (see http://www.ietf.org/rfc/rfc2459.txt) in CRLs. This extension specifies a monotonically increasing sequence number for each CRL issued by a CA, allowing CRL users to easily determine when a particular CRL supersedes another CRL.

The CRLReason rule enables you to configure a Certificate Manager to set the CRL ReasonCode Extension defined in X.509 and PKIX standard RFC 2459 (see http://www.ietf.org/rfc/rfc2459.txt) in CRL entries. The extension is used to identify the reason for the revocation of a certificate included in the CRL.

The HoldInstruction rule enables you to configure a Certificate Manager to set the CRL Hold Instruction Extension defined in X.509 and PKIX standard RFC 2459 (see http://www.ietf.org/rfc/rfc2459.txt) in CRLs. The extension is a non-critical CRL entry extension that is used to specify a registered instruction identifier--the identifier indicates what action the validating application should take when it encounters a certificate that has been placed on hold.

The InvalidityDate rule enables you to configure a Certificate Manager to set the Invalidity Date Extension defined in X.509 and PKIX standard RFC 2459 (see http://www.ietf.org/rfc/rfc2459.txt) in CRLs. The extension is a non-critical CRL entry extension that is used to specify the date on which it is known or suspected that the private key was compromised or that the certificate otherwise became invalid.

The IssuerAlternativeName rule enables you to configure a Certificate Manager to set the Issuer Alternative Name Extension defined in X.509 and PKIX standard RFC 2459 (see http://www.ietf.org/rfc/rfc2459.txt) in CRLs. This extension enables binding of or associating alternative identities, such as Internet electronic mail address, a DNS name, an IP address, and a uniform resource indicator (URI), with the issuer of the CRL.

• An rfc822Name
• A DNS name
• A directory name
• A uniform resource indicator (URI)
• An IP address
• An object identifier (OID)

The IssuingDistributionPoint rule enables you to configure a Certificate Manager to set the Issuing Distribution Point Extension defined in X.509 and PKIX standard RFC 2459 (see http://www.ietf.org/rfc/rfc2459.txt) in CRLs. The CRL issuing point extension enables you to specify a pointer to a particular CRL and to include additional information about the CRL at that location--whether it covers revocation of end-entity certificates only, CA certificates only, or revoked certificates that have a limited set of reason codes.

• The name of the X.500 directory that stores the CRL
• The URI to the location that contains the CRL