Sun Java System Web Server 6.1 SP12 Administrator's Guide

Using the certmap.conf File

Certificate mapping determines how a server scans user entry in the LDAP directory. You can use the certmap.conf to configure how a certificate, designated by name, is mapped to an LDAP entry. You edit this file and add entries to match the structure of your LDAP directory and to list the certificates you want your users to have. Users can be authenticated based on userid, email, or any other value used in the subjectDN. Specifically, the mapping file defines the following information:

The certificate mapping file is located in the following location:


The file contains one or more named mappings, each applying to a different CA. A mapping has the following syntax:

certmap <name> <issuerDN>

<name>:<property> [<value>]

The first line specifies a name for the entry and the attributes that form the distinguished name found in the CA certificate. You can select any name for the entry. However, the issuerDN must exactly match the issuer DN of the CA that issued the client certificate. For example, the following two issuerDN lines have different space separating the attributes, but the server treats these as two separate entries

certmap sun1 ou=Sun Certificate Authority,o=Sun, c=US
      certmap sun2 ou=Sun Certificate Authority, o=Sun, c=US 

Note –

If you are using the Sun Java System Directory Server and experiencing problems in matching the issuerDN, check the Directory Server error logs for useful information.

The second and subsequent lines in the named mapping match properties with values. The certmap.conf file has six default properties (you can use the certificate API to customize your own properties):

Table 6–2 Attributes for x509v3 Certificates








Common name 






Organizational unit 


UNIX/Linux userid 


Email address 

The attribute names for the filters need to be attribute names from the certificate, not from the LDAP directory. For example, some certificates have an e attribute for the user’s email address; whereas LDAP calls refers to this attribute as mail.

For more information on these properties, refer to the examples described in Sample Mappings.

Creating Custom Properties

You can use the client certificate API to create your own properties. For information on programming and using the client certificate API, see the Sun Java System Web Server 6.1 SP12 NSAPI Programmer’s Guide.

Once you have a custom mapping, you reference the mapping as follows:

<name>:library <path_to_shared_library>
 <name>:InitFn <name_of_init_function>

For example:

certmap default1 o=Sun Microsystems, c=US default1:library /usr/sun/userdb/plugin.so default1:InitFn plugin_init_fn default1:DNComps ou o c default1:FilterComps l default1:verifycert on

Sample Mappings

The certmap.conf file should have at least one entry. The following examples illustrate the different ways you can use the certmap.conf file.

Example #1

This example represents a certmap.conf file with only one “default” mapping:

certmap default defaultdefault:DNComps ou, o, cdefault:FilterComps e, uiddefault:verifycert on

Using this example, the server starts its search at the LDAP branch point containing the entry ou=<orgunit>, o=<org>, c=<country> where the text within <> is replaced with the values from the subject’s DN in the client certificate.

The server then uses the values for email address and userid from the certificate to search for a match in the LDAP directory. When it finds an entry, the server verifies the certificate by comparing the one the client sent to the one stored in the directory.

Example #2

The following example file has two mappings: one for default and another for the US Postal Service (USPS):

certmap default defaultdefault:DNCompsdefault:FilterComps e, uid

certmap usps ou=United States Postal Service, o=usps, c=USusps:DNComps ou,o,cusps:FilterComps eusps:verifycert on

When the server gets a certificate from someone other than the USPS , it uses the default mapping, which starts at the top of the LDAP tree and searches for an entry matching the client’s userid and email address. If the certificate is from the USPS, the server starts its search at the LDAP branch containing the organizational unit and searches for matching email addresses. Note that if the certificate is from the USPS, the server verifies the certificate; other certificates are not verified.

Caution – Caution –

The issuer DN (that is, the CA’s information) in the certificate must be identical to the issuer DN listed in the first line of the mapping. In the previous example, a certificate from an issuer DN that is o=United States Postal Service,c=US will not match because there is not a space between the o and the c attributes.

Example #3

The following example uses the CmapLdapAttr property to scan the LDAP database for the certSubjectDN attribute whose value exactly matches the entire subject DN taken from the client certificate.

certmap myco ou=My Company Inc, o=myco, c=USmyco:CmapLdapAttr certSubjectDNmyco:DNComps o, c myco:FilterComps mail, uid myco:verifycert on

If the client certificate subject is:

uid=Walt Whitman, o=LeavesOfGrass Inc, c=US

the server first searches for entries that contain the following information:

certSubjectDN=uid=Walt Whitman, o=LeavesOfGrass Inc, c=US

If one or more matching entries are found, the server proceeds to verify the entries. If no matching entries are found, the server will use DNComps and FilterComps to search for matching entries. In this example, the server would search for uid=Walt Whitman in all entries under o=LeavesOfGrass Inc, c=US.

Note –

This example assumes the LDAP directory contains entries with the certSubjectDN attribute.