C.2. Mapper Plug-in Modules

This section describes the mapper plug-in modules provided for the Certificate Manager. These modules configure a Certificate Manager to enable and configure specific mapper instances.
The available mapper plug-in modules include the following:

C.2.1. LdapCaSimpleMap

The LdapCaSimpleMap plug-in 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 plug-in 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 plug-in 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 plug-in, 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:

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=$subj.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=$subj.o.
  • Example 1: uid=CertMgr, o=Example Corporation
  • Example 2: cn=$subj.cn,ou=$subj.ou,o=$subj.o,c=US
  • Example 3: uid=$req.HTTP_PARAMS.uid, e=$ext.SubjectAlternativeName.RFC822Name,ou=$subj.ou
In the above examples, $req takes the attribute from the certificate request, $subj takes the attribute from the certificate subject name, and $ext 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: 
uid=$subj.cn,ou=people,o=$subj.o

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: 
uid=$subj.cn,ou=people,o=$subj.o

C.2.2. LdapDNExactMap

The LdapDNExactMap plug-in 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 plug-in 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=$subj.UID, or a constant, such as o=Example Corporation.
  • Example 1: uid=CertMgr, o=Example Corporation
  • Example 2: cn=$subj.cn,ou=$subj.ou,o=$subj.o,c=US
  • Example 3: uid=$req.HTTP_PARAMS.uid, e=$ext.SubjectAlternativeName.RFC822Name,ou=$subj.ou
In the examples, $req takes the attribute from the certificate request, $subj takes the attribute from the certificate subject name, and $ext takes the attribute from the certificate extension.

C.2.4. LdapSubjAttrMap

The LdapSubjAttrMap plug-in 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.
Table C.9, “LdapSubjAttrMap Parameters” 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 plug-in 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: 
cn=Jane Doe, ou=Sales, o=Example Corporation, l=Mountain View, st=California, c=US
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: 
cn=Jane Doe, ou=Sales, o=Example Corporation, c=US
  • 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: 
    cn=Jane Doe, o=Example Corporation, c=US
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.
Table C.10, “LdapDNCompsMap Configuration Parameters” 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.