Using the Certificate Mapping API

CertVerifyFn_t (Verification Function)

Type definition for the certificate verification function, which takes a set of search results and finds the entry corresponding to the certificate subject. The verification function verifies that the certificate presented to the server matches the user's certificate in the directory.

Syntax

typedef int (*CertVerifyFn_t)(void *cert, LDAP *ld, 
      void *certmap_info, LDAPMessage *res, 
      LDAPMessage **entry);

Parameters

Functions with this type definition have the following parameters:


Name	Description
cert	Certificate whose subject you want to find. The certificate verification function attempts to narrow down multiple results from the certificate search function. 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.
res	Result of the search, passed in from CertSearchFn_t (Search Function). Note that you can use both `ld` and `res` here in subsequent LDAP API calls.
entry	Pointer to the entry in the results (`res`) that is the correct entry, as determined by the verification function.

Returns

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

LDAPU_SUCCESS upon successful completion.

LDAPU_FAILED there is no unexpected error but cert could not be verified (probably because it was revoked).

LDAPU_CERT_VERIFY_FUNCTION_FAILED in all other cases.

Description

The verification function is called by the function ldapu_cert_to_ldap_entry() after the search function finds one or more entries matching the certificate subject and if the value of the verifycert property in the certmap.conf file is on.

If the search function returns multiple entries, the verification function should determine which is the correct entry that corresponds to the certificate subject. The function must pass back a pointer to that matching entry in the entry parameter.

The verification function should also make sure that the certificate presented to the server matches the user's certificate in the directory.

Example

The following function is an example of a certificate verification function. This example also demonstrates how you can call LDAP API functions from within your own function.

static int plugin_verify_fn (void *cert, LDAP *ld, void *certmap_info, 
   LDAPMessage *res, LDAPMessage **entry_out)

   LDAPMessage *entry;

   struct berval **bvals;

   char *cert_attr = "userCertificate;binary";

   int i, count = 0;

   int rv;

   *entry_out = 0;

/* Count and print the number of entries found (just to see how well the search function worked) */

   count = ldap_count_entries( ld, res );

... /* Call a function to print out the count here. */ ...

/* Loop through the entries in the search results */

   for (entry = ldap_first_entry(ld, res); entry != NULL; 
      entry = ldap_next_entry(ld, entry))

/* Get the values of the userCertificate;binary attribute, which should contain the user's certificate. */

      if ((bvals = ldap_get_values_len(ld, entry, cert_attr)) == NULL) {

         rv = LDAPU_CERT_VERIFY_FUNCTION_FAILED;

         continue;

/* Compare the user's certificate against the certificate received by the server (plugin_cmp_certs is a function you define for comparing two certificates) */

      for ( i = 0; bvals[i] != NULL; i++ ) {

         rv = plugin_cmp_certs (cert, bvals[i]->bv_val, 
            bvals[i]->bv_len);

         if (rv == LDAPU_SUCCESS) {

...

            /* Log a message that you've found the entry. */

...

            break;

/* Free the memory that you've allocated to get the certificate values */

      ldap_value_free_len(bvals);

      if (rv == LDAPU_SUCCESS) {

         *entry_out = entry;

         break;