Using the Certificate Mapping API

CertSearchFn_t (Search Function)

Type definition for the certificate search function, which uses the base DN and search filter to find the certificate subject's corresponding entry in the directory.

Syntax

typedef int (*CertSearchFn_t)(void *cert, LDAP *ld, 
      void *certmap_info, const char *basedn, 
      const char *dn, const char *filter, 
      const char **attrs, LDAPMessage **res);

Parameters

Functions with this type definition have the following parameters:


Name	Description
cert	Certificate whose subject you want to find. The certificate search function attempts to find the certificate subject's entry in the directory. If you need to get information about this certificate, you can pass the `cert` argument to the `ldapu_get_cert_*()` functions.
ld	Handle to the connection to the directory server. If you need to access the directory and perform LDAP operations, you can pass this handle as an argument to the `ldap_*()` functions
certmap_info	Structure containing information about the configuration parameters for the certificate authority (CA) who issued the certificate. If you need to get the value for a particular configuration attribute (or a property), pass the structure to the `ldapu_get_cert_ava_val()` function.
basedn	Base DN to use in the search, if no DN is specified in the `dn` argument. (The DN of the root object will be passed here.) You can use this to specify the default base DN to use in cases where the certificate mapping function does not provide a base DN. (For example, you might set this to `o=My Company,c=US`.)
dn	Base DN to use in the search. This is the value returned by CertMapFn_t (Mapping Function).
filter	Search filter to use in the search. This is the value returned by CertMapFn_t (Mapping Function).
attrs	List of attributes to return from the search. If this is NULL, all attributes are returned. This list can be passed to subsequent `ldap_search()` and `ldap_search_s()` function calls.
res	Results of the search, which are passed to CertVerifyFn_t (Verification Function).

Returns

Functions with this type definition return one of the following values:

LDAPU_SUCCESS upon successful completion.

LDAPU_FAILED if no unexpected error occurs but the search finds no matching entries.

LDAPU_CERT_SEARCH_FUNCTION_FAILED in all other cases.

Description

The certificate search function is called by the function ldapu_cert_to_ldap_entry() after calling the mapping function. The base DN and filter returned by the mapping function are passed to this function, which uses these values to search the directory for the certificate subject.

The default search function works as follows:

If issuer's entry in the certmap.conf file contains the CmapLdapAttr property, the server uses the following filter and searches all entries under the base DN:
```
   (<value_of_CmapLdapAttr>=<subjectDN>)
```
For example, suppose your schema specifies that entries for users have the attribute certSubjectDN, which contains the subject name of the user's certificate.

In the certmap.conf file, you add the following statement:
```
   issuerName:CmapLdapAttr certSubjectDN
```
When evaluating a certificate with the subject DN cn=Barbara Jensen,o=Ace Industry,c=US, the default search function uses the following search filter to search for a matching entry:
```
   (certSubjectDN=cn=Barbara Jensen, o=Ace Industry, c=US)
```
If the search results in no matching entry (or if no value was specified for CmapLdapAttr in the certmap.conf file), the server uses the dn and filter arguments to search the directory:
Return the results of the last search.

Example

The following example is a certificate search function that logs the number of entries found after the search function completes.

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 search function. */

searchfn = ldapu_get_cert_searchfn(NULL);

/* Call the default search function. */

rv = (*searchfn)(cert, ld, certmap_info, basedn, dn, filter, 
   certmap_attrs, res);

/* Determine the number of matching entries found. */

if (rv == LDAPU_SUCCESS ) {

   count = ldap_count_entries(ld, res);

...

/* Log the count of matching entries. */

...