Chapter 6   Publisher Plug-in Modules


You can configure a Certificate Manager to publish certificates to an LDAP directory or flat file, and to publish CRLs to a directory, online validation authority, or flat file. If you configure the Certificate Manager to publish to any of these repositories, when the Certificate Manager is requested to issue a certificate or to update certificate information, it automatically updates the corresponding entry in the configured repository with relevant information. Similarly, when a certificate is revoked, the Certificate Manager automatically updates the configured repositoty with relevant CRL information. To locate the correct entry in the repository, the Certificate Manager relies on object-mapping rules and to update the located entry with relevant information, the Certificate Manager relies on object-publishing rules.

To enable you to construct object-publishing rules, the Certificate Manager provides a set of publisher plug-in modules. These modules are implemented as Java classes and are registered with the Certificate Manager's publishing framework.

This chapter explains the publisher modules that are installed with a Certificate Manager—it lists and briefly describes the modules and then explains each one in detail. Before reading this chapter, you should have read the previous chapter, Chapter 5 "Mapper Plug-in Modules."

The chapter has the following sections:

• Overview of Publisher Modules

• FileBasedPublisher Plug-in Module

• LdapCaCertPublisher Plug-in Module

• LdapUserCertPublisher Plug-in Module

• LdapCrlPublisher Plug-in Module

• OCSPPublisher Plug-in Module

Overview of Publisher Modules

---

Publisher modules help you configure the Certificate Manager to publish a CA certificate, end-entity certificates, or CRLs to the following:

• A mapped entry in the directory (entries are mapped by one of the mapper modules explained in Chapter 5 "Mapper Plug-in 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 (Figure 6-1) lists all the modules and the corresponding classes that are currently registered with a Certificate Manager.

Figure 6-1    Default publisher modules registered with a Certificate Manager

Table 6-1 describes the publisher modules provided for the Certificate Manager. You can use these modules to configure a Certificate Manager to employ specific publishing rules.

Table 6-1    Default publisher plug-in modules for publishing certificates and CRLs  

Plug-in module name	Function
FileBasedPublisher	Publishes certificates and CRLs to a flat file (for exporting into other repositories). For details, see "FileBasedPublisher Plug-in Module".
LdapCaCertPublisher	Publishes or unpublishes a certificate to the caCertificate;binary attribute of the mapped directory entry as a DER encoded binary blob. Also converts the object class to a certificationAuthority if it's not one already; similarly, removes the certificationAuthority object class on unpublish if the CA has no other certificates. For details, see "LdapCaCertPublisher Plug-in Module".
LdapCrlPublisher	Publishes (replaces) a CRL to the certificateRevocationList;binary attribute of the mapped directory entry as a DER encoded binary blob. The entry should be a certificationAuthority object class. For details, see "LdapCrlPublisher Plug-in Module".
LdapUserCertPublisher	Publishes or unpublishes a certificate to the userCertificate;binary attribute of the mapped directory entry as a DER encoded binary blob. For details, see "LdapUserCertPublisher Plug-in Module".
OCSPPublisher	Publishes CRLs to a Online Certificate Status Manager. For details, see "OCSPPublisher Plug-in Module".

Note that the name of the Java class for a publisher plug-in is in this format:

com.netscape.certsrv.ldap.<plugin_name>

where <plugin_name> is the name of a plug-in module. For example, the Java class for the FileBasedPublisher module would be:

com.netscape.certsrv.ldap.FileBasedPublisher

If you determine that the default publisher modules do not meet your requirements, you can develop a custom publisher class by implementing the following Java interface:

com.netscape.certsrv.ldappublish.ILdapPublisher

For more information on this interface, check the CMS software development kit (SDK) installed at this location: <server_root>/cms_sdk/cms_jdk

Be sure to take a look at the samples available at this location: <server_root>/cms_sdk/cms_jdk/samples/publishers

When developing a custom publisher module, you may want to intercept LDAP error 52 and reword it so that the correct error message gets logged. To give you an example, if the publishing directory has been stopped, the server logs the following message in its error and system logs:

Error publishing CRL MasterCRL: Cannot find a match in the LDAP server for certificate. netscape.ldap.LDAPException: unable to establish connection (52); DSA is unavailable.

Notice that the error message incorrectly says DSA is unavailable instead of Directory Server is unavailable.

For instructions on how to configure a Certificate Manager to use a publisher module, see section "Configuring a Certificate Manager to Publish Certificates and CRLs" in Chapter 19, "Setting Up LDAP Publishing" of CMS Installation and Setup Guide.

FileBasedPublisher Plug-in Module

---

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.

By default, the Certificate Manager does not create an instance of the FileBasedPublisher module. The instructions covered in Chapter 20, "Publishing Certificates and CRLs to a File" of CMS Installation and Setup Guide explain how to create an instance of this module and how to configure a Certificate Manager to publish certificates and CRLs to files.

Configuration Parameters of FileBasedPublisher

In the CMS configuration file, the FileBasedPublisher module is identified as
ca.publish.publisher.impl.FileBasedPublisher.class=com.netscape.
certsrv.ldap.FileBasedPublisher.

In the CMS window, the module is identified as FileBasedPublisher. Figure 6-2 shows how the configurable parameters for the module are displayed in the CMS window.

Figure 6-2    Configuration parameters defined in the FileBasedPublisher module

The configuration shown in Figure 6-2 creates a publisher named PublishCertsToFile, which can publish certificate and CRL files to a directory at C:\certificates.

LdapCaCertPublisher Plug-in Module

---

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 module also converts the object class of the CA's entry to a certificationAuthority if it's not one already. Similarly, it also removes the certificationAuthority object class on unpublish if the CA has no other certificates.

You can use this module for publishing the CA certificate to the LDAP directory only.

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

Configuration Parameters of LdapCaCertPublisher

In the CMS configuration file, the LdapCaCertPublisher module is identified as
ca.publish.publisher.impl.LdapCaCertPublisher.class=com.netscape.
certsrv.ldap.LdapCaCertPublisher.

In the CMS window, the module is identified as LdapCaCertPublisher. Figure 6-3 shows how the configurable parameters for the module are displayed in the CMS window.

Figure 6-3    Parameters defined in the LdapCaCertPublisher module

Table 6-2 describes these parameters.

Table 6-2    Description of parameters defined in the LdapCaCertPublisher module  

Parameter	Description
caCertAttr	Specifies the LDAP directory attribute to publish the CA certificate. Permissible values: Must be caCertificate;binary. Example: caCertificate;binary
caObjectClass	Specifies the object class for the CA's entry in the directory. Permissible values: Must be certificationAuthority. Example: certificationAuthority

LdapCaCertPublisher Publisher

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

You can use this publisher for publishing the CA certificate to caCertificate;binary attribute of the mapped CA's entry in the directory.

LdapUserCertPublisher Plug-in Module

---

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.

You can use this module to publish any end-entity certificate to an LDAP directory. Types of end-entity certificates include SSL client, S/MIME, SSL server, object signing, router, and OCSP responder.

During installation, the Certificate Manager automatically creates an instance (called a publisher) of the LdapUserCertPublisher module for publishing end-entity certificates to the directory. See "LdapUserCertPublisher Publisher".

Configuration Parameters of LdapUserCertPublisher

In the CMS configuration file, the LdapUserCertPublisher module is identified as
ca.publish.publisher.impl.LdapUserCertPublisher.class=com.netscape.
certsrv.ldap.LdapUserCertPublisher.

In the CMS window, the module is identified as LdapUserCertPublisher. Figure 6-4 shows how the configurable parameters for the module are displayed in the CMS window.

Figure 6-4    Parameters defined in the LdapUserCertPublisher module

The configuration shown in Figure 6-4 creates a publisher rule named LdapUserCertPublisher, which publishes user certificates to the userCertificate;binary attribute of the mapped user entries.

Table 6-3 describes the parameters.

Table 6-3    Description of parameters defined in the LdapUserCertPublisher module  

Parameter	Description
certAttr	Specifies the directory attribute of the mapped entry to which the Certificate Manager should publish the certificate. Permissible values: Must be userCertificate;binary. Example: userCertificate;binary

LdapUserCertPublisher Publisher

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

You can use this publisher to publish an end-entity certificate to the userCertificate;binary attribute of the mapped end-entity's entry in the directory.

LdapCrlPublisher Plug-in Module

---

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.

The CRL publisher requires you to specify just one parameter named crlAttr. The value of this parameter must be certificateRevocationList;binary.

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

Configuration Parameters of LdapCrlPublisher

In the CMS configuration file, the LdapCrlPublisher module is identified as
ca.publish.publisher.impl.LdapCrlPublisher.class=com.netscape.
certsrv.ldap.LdapCrlPublisher.

In the CMS window, the module is identified as LdapCrlPublisher. Figure 6-5 shows how the configurable parameters for the module are displayed in the CMS window.

Figure 6-5    Parameters defined in the LdapCrlPublisher module

Table 6-4 describes these parameters.

Table 6-4    Description of parameters defined in the LdapCrlPublisher module  

Parameter	Description
crlAttr	Specifies the directory attribute of the mapped entry to which the Certificate Manager should publish the certificate. Permissible values: Must be certificateRevocationList;binary. Example: certificateRevocationList;binary

LdapCrlPublisher Publisher

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

You can use this publisher for publishing the CRL to certificateRevocationList;binary attribute of the CA's entry in the directory.

OCSPPublisher Plug-in Module

---

The OCSPPublisher plug-in module implements the OCSP publisher. This module enables you to configure a Certificate Manager to publish its CRLs to a Online Certificate Status Manager, the OCSP responder provided by Certificate Management System.

During installation, the Certificate Manager does not create any instancs of the OCSPPublisher module.

Configuration Parameters of OCSPPublisher

In the CMS configuration file, the OCSPPublisher module is identified as
ca.publish.publisher.impl.OCSPPublisher.class=com.netscape.
certsrv.ldap.OCSPPublisher.

In the CMS window, the module is identified as OCSPPublisher. Figure 6-6 shows how the configurable parameters for the module are displayed in the CMS window.

Figure 6-6    Parameters defined in the OCSPPublisher module

Table 6-5 describes these parameters.

Table 6-5    Description of parameters defined in the OCSPPublisher module  

Parameter	Description
host	Specifies the hostname of the Online Certificate Status Manager. Permissible values: Must be the fully-qualified hostname of a Online Certificate Status Manager in this form: <machine)_name>.<your_domain>.com Example: ocspResponder.siroe.com
port	Specifies the port number at which the Online Certificate Status Manager is listening to the Certificate Manager. Permissible values: Must be the Online Certificate Status Manager's agent port number. Example: 8101
path	Specifies the path for publishing the CRL. Permissible values: Must be the default path, /ocsp/addCRL. Example: /ocsp/addCRL