[Previous] [Next]

Changing the Way to Find the Subject's Entry

To find the directory entry for the subject of a certificate, a Netscape server does the following:

  1. Generates a base DN and a search filter, based on the certificate subject's DN and the DNComps and FilterComps preferences specified in the certmap.conf file.

  2. Performs the following searches:

  3. Narrows down the list of search results to a single entry by verifying that the user's certificate is stored in the userCertificate;binary attribute for that entry.
The following diagram illustrates this process.

A default set of API functions defines how these three steps work. To change the way this works by doing the following:

  1. Write your own functions for finding the certificate subject's entry in the directory. Compile a shared object or dynamic link library containing your functions.

  2. Set up the certmap.conf file to load your library and use your functions instead of the default API functions.

Writing Your Own Functions

In a Netscape server, the main API function that finds directory entries for certificate subjects is ldapu_cert_to_ldap_entry(). This function calls three other API functions, which correspond to the steps listed in "Changing the Way to Find the Subject's Entry".

These three functions define the process of finding a certificate subject's entry in the directory. You can write your own version of these three functions if you want to change the way in which they work:

Note that if you choose to write your own version of the functions, you do not need to completely redefine the functions from scratch. If you want to define an additional step in the process before or after the function is invoked, you can call the ldapu_get_cert_mapfn(), ldapu_get_cert_searchfn(), and ldapu_get_cert_verifyfn() to get and invoke the default functions.

For example, the following section of code logs the number of matching entries found after invoking the certificate search function.

static int my_cert_search_fn( void *cert, LDAP *ld, void *certmap_info, 
   const char *basedn, const char *dn, const char *filter,
   const char **attrs, LDAPMessage **res)
{
   int count, rv;
   CertSearchFn_t searchfn;
...
/* Get the default certificate search function. */
   searchfn = ldapu_get_cert_searchfn(NULL); 
/* Call the default certificate search function. */
   rv = (*searchfn)(cert, ld, certmap_info, basedn, dn, filter, 
      certmap_attrs, res);
/* Count the number of matching entries found. */
   if (rv == LDAPU_SUCCESS) {
      count = ldap_count_entries(ld, res);
   }
...
   return rv;
}
...
The following diagram summarizes how the certificate mapping, search, and verification functions should interact with each other.

When you write your functions, make sure that your functions comply with the corresponding type definitions. Also, make sure to do the following:

Configuring the Server to Use Your Functions

In order to specify that you want your functions used instead of the default set of functions, you need to define an initialization function and specify in the certmap.conf file that you want this function loaded.

Writing the Initialization Function

To set up ldapu_cert_to_ldap_entry() to use your functions instead of the default API functions, define an initialization function that calls the following functions:

The initialization function has the following type definition:

typedef int (*CertMapInitFn_t)(void *certmap_info, 
      const char *issuerName, const char *issuerDN,
      const char *libname);
For details of this type definition, see "CertMapInitFn_t (Init Function)".

For example, the following initialization function specifies that the functions plugin_mapping_fn and plugin_verify_fn should be used instead of the default Certificate Map Function and Certificate Verification Function.

int plugin_init_fn (void *certmap_info, const char *issuerName, 
      const char *issuerDN, const char *libname)
{ 
   fprintf(stderr, "plugin_init_fn called.\n"); 
   ldapu_set_cert_mapfn(issuerDN, (CertMapFn_t)plugin_mapping_fn); 
   ldapu_set_cert_verifyfn(issuerDN, (CertVerifyFn_t)plugin_verify_fn); 
   return LDAPU_SUCCESS; 
} 
On Windows NT, you need to call the CertmapDLLInit() function once to initialize the table of functions used to find the LDAP entry for a certificate.

NSAPI_PUBLIC int plugin_init_fn (void *certmap_info, 
   const char *issuerName, const char *issuerDN, const char *libname)
{
   static int initialized = 0;
   int rv;
   /* Make sure CertmapDLLInit is initialized only once */
   if (!initialized) {
#ifdef WIN32
   CertmapDLLInit(rv, libname);
   if (rv != LDAPU_SUCCESS) {
      /* Log an error here, if you want to. */
      return rv;
   }
#endif
      initialized = 1;
   }
...

Configuring the certmap.conf File

After writing your functions, you should compile them into a shared library (a DLL on Windows NT, a .so file on Solaris and IRIX, a .sl file on HP-UX).

In the certmap.conf file, you need to add the following statements:

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

certmap default1 o=Netscape Communications, c=US 
default1:library /usr/netscape/suitespot/userdb/plugin.so 
default1:InitFn plugin_init_fn 
default1:DNComps  ou, o, c 
default1:FilterComps l 
default1:verifycert 
In addition to using the library property to specify the library to load, each server that supports client authentication loads any shared libraries that exist in the following directories:

<server_type> identifies a type of server. The names of server types are the same names as the names of the directories in the <server_type> directory (for example, https for the Enterprise Server and news for the Collabra Server).

<server_id> is the ID of the server instance. Typically, this is the server type concatenated with the server name (for example, https-myhost). If a library is placed in the <server_id> directory, only that server instance will load the library.

Tips and Troubleshooting

As you test your custom functions, check the error log for information about potential problems. Some possible problems that might occur include:


[Previous] [Next]


Copyright ⌐ 1997 Netscape Communications Corporation