Using the Certificate Mapping API

You can configure some parts of this process by editing the file <server_root>/userdb/certmap.conf. This file specifies:

• how the server searches the directory for the user's entry
• whether or not the server goes through an additional step of verifying that the user's certificate matches the certificate presented to the server

You can also configure this "certificate to directory entry" process programmatically. Netscape servers include a set of API functions (referred to here as the Certificate Mapping API functions) that allow you to control this process. You can write your own functions to customize the way in which certificate subject entries are found in the directory.

NOTE: In order to use this API, you need to have a copy of the Directory SDK. You can download a copy of this SDK from the Netscape DevEdge site at http:// developer.netscape.com/.

• Distinguished name (DN). This is a name that uniquely identifies an entry in an LDAP directory. A distinguished name consists of components that help identify the entry. Commonly used components include:
• 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
• c, which represents a country in the directory

For example, the following DN:

cn=Barbara Jensen, ou=Accounting, o=Netscape, c=US

represents the user named Barbara Jensen who works for the Accounting department at Netscape, which is based in the U.S.

• Certificate authority (CA). This is the entity (a person, department, or organization) that has issued the certificate. The name of the CA is included in the certificate. This name is in DN format.

For example, the name of the CA for Netscape might be:

ou=Netscape Certificate Authority, o=Netscape, c=US

• Certificate subject. This is the owner of the certificate. The name of the certificate subject is included in this certificate. The name is also in DN format.

For example, the name of the subject of Barbara Jensen's personal certificate might be:

cn=Barbara Jensen, ou=Accounting, o=Netscape, c=US

• Directory search or LDAP search. In Netscape servers, the directory of users of the server is either a LDAP server or a local database. In either case, the Netscape server can find a specific user in the directory by performing an LDAP search.

Typically, an LDAP search consists of the following components:

• The base DN. The base DN identifies the entry from which the search should begin. For example, if the base DN is o=Ace Industry, c=US, a subtree search (see search type below) searches through all entries under this entry in the directory (in other words, all entries with the suffix o=Ace Industry, c=US).
• The search type. In LDAP, you can perform the following types of searches: base search (which only searches the entry specified by the base DN), one-level search (which only searches entries one level below the base entry), and subtree search (which searches all entries at all levels below the base entry).
• The search filter. The search filter specifies the search criteria applied to each entry within the scope of the search.

The rest of this document describes how to use this API:

• "Changing the Way to Find the Subject's Entry" explains how to use the API functions to define how certificate subjects are found in the directory.
• "Type Definition Reference" summarizes the type definitions that you need to use when writing your own custom functions.
• "Function Reference" lists the functions available in this API.
• "Status Code Reference" summarizes the status codes returned by the functions in this API.