Appendix C. Publishing modules reference Several publisher, mapper, and rule modules are configured by default with the Certificate Manager. Section C.1, "Publisher plugin modules" Section C.2, "Mapper plugin modules" Section C.3, "Rule instances" C.1. Publisher plugin modules This section describes the publisher modules provided for the Certificate Manager. The modules are used by the Certificate Manager to enable and configure specific publisher instances. Section C.1.1, "FileBasedPublisher" Section C.1.2, "LdapCaCertPublisher" Section C.1.3, "LdapUserCertPublisher" Section C.1.4, "LdapCrlPublisher" Section C.1.5, "LdapDeltaCrlPublisher" Section C.1.6, "LdapCertificatePairPublisher" Section C.1.7, "OCSPPublisher" C.1.1. FileBasedPublisher The FileBasedPublisher plugin module configures a Certificate Manager to publish certificates and CRLs to file. This plugin can publish base-64 encoded files, DER-encoded files, or both, depending on the checkboxes selected when the publisher is configured. The certificate and CRL content can be viewed by converting the files using the PrettyPrintCert and PrettyPrintCRL tools. For details on viewing the content in base-64 and DER-encoded certificates and CRLs, see Section 7.10, "Viewing certificates and CRLs published to file" . By default, the Certificate Manager does not create an instance of the FileBasedPublisher module. Table C.1. FileBasedPublisher configuration parameters Parameter Description Publisher ID Specifies a name for the publisher, an alphanumeric string with no spaces. For example, PublishCertsToFile . directory Specifies the complete path to the directory to which the Certificate Manager creates the files; the path can be an absolute path or can be relative to the Certificate System instance directory. For example, /export/CS/certificates . C.1.2. LdapCaCertPublisher The LdapCaCertPublisher plugin module configures a Certificate Manager to publish or unpublish a CA certificate to the caCertificate;binary attribute of the CA's directory entry. The module converts the object class of the CA's entry to pkiCA or certificationAuthority , if it is not used already. Similarly, it also removes the pkiCA or certificationAuthority object class when unpublishing if the CA has no other certificates. During installation, the Certificate Manager automatically creates an instance of the LdapCaCertPublisher module for publishing the CA certificate to the directory. Table C.2. LdapCaCertPublisher configuration parameters Parameter Description caCertAttr Specifies the LDAP directory attribute to publish the CA certificate. This must be caCertificate;binary . caObjectClass Specifies the object class for the CA's entry in the directory. This must be pkiCA or certificationAuthority . C.1.3. LdapUserCertPublisher The LdapUserCertPublisher plugin module configures a Certificate Manager to publish or unpublish a user certificate to the userCertificate;binary attribute of the user's directory entry. This module is used to publish any end-entity certificate to an LDAP directory. Types of end-entity certificates include SSL client, S/MIME, SSL server, and OCSP responder. During installation, the Certificate Manager automatically creates an instance of the LdapUserCertPublisher module for publishing end-entity certificates to the directory. Table C.3. LdapUserCertPublisher configuration parameters Parameter Description certAttr Specifies the directory attribute of the mapped entry to which the Certificate Manager should publish the certificate. This must be userCertificate;binary . C.1.4. LdapCrlPublisher The LdapCrlPublisher plugin module configures a Certificate Manager to publish or unpublish the CRL to the certificateRevocationList;binary attribute of a directory entry. During installation, the Certificate Manager automatically creates an instance of the LdapCrlPublisher module for publishing CRLs to the directory. Table C.4. LdapCrlPublisher configuration parameters Parameter Description crlAttr Specifies the directory attribute of the mapped entry to which the Certificate Manager should publish the CRL. This must be certificateRevocationList;binary . C.1.5. LdapDeltaCrlPublisher The LdapDeltaCrlPublisher plugin module configures a Certificate Manager to publish or unpublish a delta CRL to the deltaRevocationList attribute of a directory entry. During installation, the Certificate Manager automatically creates an instance of the LdapDeltaCrlPublisher module for publishing CRLs to the directory. Table C.5. LdapDeltaCrlPublisher configuration parameters Parameter Description crlAttr Specifies the directory attribute of the mapped entry to which the Certificate Manager should publish the delta CRL. This must be deltaRevocationList;binary . C.1.6. LdapCertificatePairPublisher The LdapCertificatePairPublisher plugin module configures a Certificate Manager to publish or unpublish a cross-signed certificate to the crossCertPair;binary attribute of the CA's directory entry. The module also converts the object class of the CA's entry to a pkiCA or certificationAuthority , if it is not used already. Similarly, it also removes the pkiCA or certificationAuthority object class when unpublishing if the CA has no other certificates. During installation, the Certificate Manager automatically creates an instance of the LdapCertificatePairPublisher module named LdapCrossCertPairPublisher for publishing the cross-signed certificates to the directory. Table C.6. LdapCertificatePairPublisher Parameters Parameter Description crossCertPairAttr Specifies the LDAP directory attribute to publish the CA certificate. This must be crossCertificatePair;binary . caObjectClass Specifies the object class for the CA's entry in the directory. This must be pkiCA or certificationAuthority . C.1.7. OCSPPublisher The OCSPPublisher plugin module configures a Certificate Manager to publish its CRLs to an Online Certificate Status Manager. The Certificate Manager does not create any instances of the OCSPPublisher module at installation. Table C.7. OCSPPublisher Parameters Parameter Description host Specifies the fully qualified hostname of the Online Certificate Status Manager. port Specifies the port number on which the Online Certificate Status Manager is listening to the Certificate Manager. This is the Online Certificate Status Manager's SSL port number. path Specifies the path for publishing the CRL. This must be the default path, /ocsp/agent/ocsp/addCRL . enableClientAuth Sets whether to use client (certificate-based) authentication to access the OCSP service. nickname Gives the nickname of the certificate in the OCSP service's database to use for client authentication. This is only used if the enableClientAuth option is set to true. C.2. Mapper plugin modules This section describes the mapper plugin modules provided for the Certificate Manager. These modules configure a Certificate Manager to enable and configure specific mapper instances. The available mapper plugin modules include the following: Section C.2.1, "LdapCaSimpleMap" Section C.2.2, "LdapDNExactMap" Section C.2.3, "LdapSimpleMap" Section C.2.4, "LdapSubjAttrMap" Section C.2.5, "LdapDNCompsMap" C.2.1. LdapCaSimpleMap The LdapCaSimpleMap plugin module configures a Certificate Manager to create an entry for the CA in an LDAP directory automatically and then map the CA's certificate to the directory entry by formulating the entry's DN from components specified in the certificate request, certificate subject name, certificate extension, and attribute variable assertion (AVA) constants. For more information on AVAs, check the directory documentation. The CA certificate mapper specifies whether to create an entry for the CA, to map the certificate to an existing entry, or to do both. If a CA entry already exists in the publishing directory and the value assigned to the dnPattern parameter of this mapper is changed, but the uid and o attributes are the same, the mapper fails to create the second CA entry. For example, if the directory already has a CA entry for uid=CA,ou=Marketing,o=example.com and a mapper is configured to create another CA entry with uid=CA,ou=Engineering,o=example.com , the operation fails. The operation may fail because the directory has the UID Uniqueness plugin set to a specific base DN. This setting prevents the directory from having two entries with the same UID under that base DN. In this example, it prevents the directory from having two entries under o=example.com with the same UID, CA . If the mapper fails to create a second CA entry, check the base DN to which the UID Uniqueness plugin is set, and check if an entry with the same UID already exists in the directory. If necessary, adjust the mapper setting, remove the old CA entry, comment out the plugin, or create the entry manually. During installation, the Certificate Manager automatically creates two instances of the CA certificate mapper module. The mappers are named as follows: LdapCrlMap for CRLs (see Section C.2.1.2, "LdapCrlMap" ) LdapCaCertMap for CA certificates (see Section C.2.1.1, "LdapCaCertMap" ). Table C.8. LdapCaSimpleMap configuration parameters Parameter Description createCAEntry Creates a CA's entry, if selected (default). If selected, the Certificate Manager first attempts to create an entry for the CA in the directory. If the Certificate Manager succeeds in creating the entry, it then attempts to publish the CA's certificate to the entry. If this is not selected, the entry must already be present in order to publish to it. dnPattern Specifies the DN pattern the Certificate Manager should use to construct to search for the CA's entry in the publishing directory. The value of dnPattern can be a list of AVAs separated by commas. An AVA can be a variable, such as cn=USDsubj.cn , that the Certificate Manager can derive from the certificate subject name or a constant, such as o=Example Corporation . If the CA certificate does not have the cn component in its subject name, adjust the CA certificate mapping DN pattern to reflect the DN of the entry in the directory where the CA certificate is to be published. For example, if the CA certificate subject DN is o=Example Corporation and the CA's entry in the directory is cn=Certificate Authority, o=Example Corporation , the pattern is cn=Certificate Authority, o=USDsubj.o . Example 1: uid=CertMgr, o=Example Corporation Example 2: cn=USDsubj.cn,ou=USDsubj.ou,o=USDsubj.o,c=US Example 3: uid=USDreq.HTTP_PARAMS.uid, e=USDext.SubjectAlternativeName.RFC822Name,ou=USDsubj.ou In the above examples, USDreq takes the attribute from the certificate request, USDsubj takes the attribute from the certificate subject name, and USDext takes the attribute from the certificate extension. C.2.1.1. LdapCaCertMap The LdapCaCertMap mapper is an instance of the LdapCaSimpleMap module. The Certificate Manager automatically creates this mapper during installation. This mapper creates an entry for the CA in the directory and maps the CA certificate to the CA's entry in the directory. By default, the mapper is configured to create an entry for the CA in the directory, The default DN pattern for locating the CA's entry is as follows: C.2.1.2. LdapCrlMap The LdapCrlMap mapper is an instance of the LdapCaSimpleMap module. The Certificate Manager automatically creates this mapper during installation. This mapper creates an entry for the CA in the directory and maps the CRL to the CA's entry in the directory. By default, the mapper is configured to create an entry for the CA in the directory. The default DN pattern for locating the CA's entry is as follows: C.2.2. LdapDNExactMap The LdapDNExactMap plugin module configures 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. To use this mapper, each certificate subject name must exactly match a DN in a directory entry. For example, if the certificate subject name is uid=jdoe, o=Example Corporation, c=US , when searching the directory for the entry, the Certificate Manager only searches for an entry with the DN uid=jdoe, o=Example Corporation, c=US . If no matching entries are found, the server returns an error and does not publish the certificate. This mapper does not require any values for any parameters because it obtains all values from the certificate. C.2.3. LdapSimpleMap The LdapSimpleMap plugin module configures a Certificate Manager to map a certificate to an LDAP directory entry by deriving the entry's DN from components specified in the certificate request, certificate's subject name, certificate extension, and attribute variable assertion (AVA) constants. For more information on AVAs, see the directory documentation. By default, the Certificate Manager uses mapper rules that are based on the simple mapper. During installation, the Certificate Manager automatically creates an instance of the simple mapper module, named LdapUserCertMap . The default mapper maps various types of end-entity certificates to their corresponding directory entries. The simple mapper requires one parameter, dnPattern . The value of dnPattern can be a list of AVAs separated by commas. An AVA can be a variable, such as uid=USDsubj.UID , or a constant, such as o=Example Corporation . Example 1: uid=CertMgr, o=Example Corporation Example 2: cn=USDsubj.cn,ou=USDsubj.ou,o=USDsubj.o,c=US Example 3: uid= USDreq.HTTP_PARAMS.uid, e=USDext.SubjectAlternativeName.RFC822Name,ou=USDsubj.ou In the examples, USDreq takes the attribute from the certificate request, USDsubj takes the attribute from the certificate subject name, and USDext takes the attribute from the certificate extension. C.2.4. LdapSubjAttrMap The LdapSubjAttrMap plugin module configures a Certificate Manager to map a certificate to an LDAP directory entry using a configurable LDAP attribute. To use this mapper, the directory entries must include the specified LDAP attribute. This mapper requires the exact pattern of the subject DN because the Certificate Manager searches the directory for the attribute with a value that exactly matches the entire subject DN. For example, if the specified LDAP attribute is certSubjectDN and the certificate subject name is uid=jdoe, o=Example Corporation, c=US , the Certificate Manager searches the directory for entries that have the attribute certSubjectDN=uid=jdoe, o=Example Corporation, c=US . If no matching entries are found, the server returns an error and writes it to the log. The following table describes these parameters. Table C.9. LdapSubjAttrMap parameters Parameter Description certSubjNameAttr Specifies the name of the LDAP attribute that contains a certificate subject name as its value. The default is certSubjectName , but this can be configured to any LDAP attribute. searchBase Specifies the base DN for starting the attribute search. The permissible value is a valid DN of an LDAP entry, such as o=example.com, c=US . C.2.5. LdapDNCompsMap The LdapDNCompsMap plugin module implements the DN components mapper. This mapper maps a certificate to an LDAP directory entry by constructing the entry's DN from components, such as cn , ou , o , and c , specified in the certificate subject name, and then uses it as the search DN to locate the entry in the directory. The mapper locates the following entries: 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. The mapper takes DN components to build the search DN. The mapper 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. Both the DNComps and filterComps parameters accept valid DN components or attributes separated by commas. The parameters do not accept multiple entries of an attribute; for example, filterComps can be set to cn,ou but not to cn,ou2,ou1 . To create a filter with multiple instances of the same attribute, such as if directory entries contain multiple ou s, modify the source code for the LdapDNCompsMap module. The following components are commonly used in DNs: uid represents the user ID of a user in the directory. cn represents the common name of a user in the directory. ou represents an organizational unit in the directory. o represents an organization in the directory. l represents a locality (city). st represents a state. c represents a country. For example, the following DN represents the user named Jane Doe who works for the Sales department at Example Corporation, which is located in Mountain View, California, United States: The Certificate Manager can use some or all of these components ( cn , ou , o , l , st , and c ) to build a DN for searching the directory. When creating a mapper rule, these components can be specified for the server to use to build a DN; that is, components to match attributes in the directory. This is set through the dnComps parameter. For example, the components cn , ou , o , and c are set as values for the dnComps parameter. To locate Jane Doe's entry in the directory, the Certificate Manager constructs the following DN by reading the DN attribute values from the certificate, and uses the DN as the base for searching the directory: A subject name does not need to have all of the components specified in the dnComps parameter. The server ignores any components that are not part of the subject name, such as l and st in this example. Unspecified components are not used to build the DN. In the example, if the ou component is not included, the server uses this DN as the base for searching the directory: For the dnComps parameter, enter those DN components that the Certificate Manager 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, the Certificate Manager might not get a single, distinct matching entry from the DN. For example, the subject name cn=Jane Doe, ou=Sales, o=Example Corporation, c=US might match two users with the name Jane Doe in the directory. If that occurs, the Certificate Manager needs additional criteria to determine which entry corresponds to the subject of the certificate. To specify the components the Certificate Manager must use to distinguish between different entries in the directory, use the filterComps parameter; for details, see Table C.10, "LdapDNCompsMap configuration parameters" . For example, if cn , ou , o , and c are 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. If the two Jane Doe entries are distinguished by the value of the uid attribute - one entry's uid is janedoe1 , and the other entry's uid is janedoe2 - the subject names of certificates can be set to include the uid component. NOTE The e , l , and st components are not included in the standard set of certificate request forms provided for end entities. These components can be added to the forms, or the issuing agents can be required to insert these components when editing the subject name in the certificate issuance forms. C.2.5.1. Configuration parameters of LdapDNCompsMap With this configuration, a Certificate 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. 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 following table describes these parameters. Table C.10. LdapDNCompsMap configuration parameters Parameter Description baseDN Specifies the DN to start searching for an entry in the publishing directory. If the dnComps field is blank, the server uses the base DN value to start its search in the directory. dnComps Specifies where in the publishing directory the Certificate Manager should start searching for an LDAP entry that matches the CA's or the end entity's information. For example, if dnComps uses the o and c attributes of the DN, 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 DN in the certificate. If the dnComps field is empty, the server checks the baseDN field and searches the directory tree specified by that DN for entries matching the filter specified by filterComps parameter values. The permissible values are valid DN components or attributes separated by commas. filterComps Specifies components the Certificate Manager should use to filter entries from the search result. 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 certificate subject name; it uses the filter to search for and match entries in the LDAP directory. If the server finds more than one entry in the directory that matches the 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 information gathered from the certificate. The permissible values are 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 . C.3. Rule instances This section discusses the rule instances that have been set. C.3.1. LdapCaCertRule The LdapCaCertRule can be used to publish CA certificates to an LDAP directory. Table C.11. LdapCaCert Rule configuration parameters Parameter Value Description type cacert Specifies the type of certificate that will be published. predicate Specifies a predicate for the publisher. enable yes Enables the rule. mapper LdapCaCertMap Specifies the mapper used with the rule. See Section C.2.1.1, "LdapCaCertMap" for details on the mapper. publisher LdapCaCertPublisher Specifies the publisher used with the rule. See Section C.1.2, "LdapCaCertPublisher" for details on the publisher. C.3.2. LdapXCertRule The LdapXCertRule is used to publish cross-pair certificates to an LDAP directory. Table C.12. LdapXCert rule configuration parameters Parameter Value Description type xcert Specifies the type of certificate that will be published. predicate Specifies a predicate for the publisher. enable yes Enables the rule. mapper LdapCaCertMap Specifies the mapper used with the rule. See Section C.2.1.1, "LdapCaCertMap" for details on the mapper. publisher LdapCrossCertPairPublisher Specifies the publisher used with the rule. See Section C.1.6, "LdapCertificatePairPublisher" for details on this publisher. C.3.3. LdapUserCertRule The LdapUserCertRule is used to publish user certificates to an LDAP directory. Table C.13. LdapUserCert rule configuration parameters Parameter Value Description type certs Specifies the type of certificate that will be published. predicate Specifies a predicate for the publisher. enable yes Enables the rule. mapper LdapUserCertMap Specifies the mapper used with the rule. See Section C.2.3, "LdapSimpleMap" for details on the mapper. publisher LdapUserCertPublisher Specifies the publisher used with the rule. See Section C.1.3, "LdapUserCertPublisher" for details on the publisher. C.3.4. LdapCRLRule The LdapCRLRule is used to publish CRLs to an LDAP directory. Table C.14. LdapCRL rule configuration parameters Parameter Value Description type crl Specifies the type of certificate that will be published. predicate Specifies a predicate for the publisher. enable yes Enables the rule. mapper LdapCrlMap Specifies the mapper used with the rule. See Section C.2.1.2, "LdapCrlMap" for details on the mapper. publisher LdapCrlPublisher Specifies the publisher used with the rule. See Section C.1.4, "LdapCrlPublisher" for details on the publisher.

Commands:
uid=USDsubj.cn,ou=people,o=USDsubj.o
uid=USDsubj.cn,ou=people,o=USDsubj.o
cn=Jane Doe, ou=Sales, o=Example Corporation, l=Mountain View, st=California, c=US
cn=Jane Doe, ou=Sales, o=Example Corporation, c=US
cn=Jane Doe, o=Example Corporation, c=US