Using the Certificate Mapping API

CertMapFn_t (Mapping Function)

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

Syntax

typedef int (*CertMapFn_t)(void *cert, LDAP *ld, 
   void *certmap_info, char **ldapDN, char **filter);

Parameters

Functions with this type definition have the following parameters:


Name	Description
cert	Certificate to be mapped. The certificate mapping function generates a base DN and a search filter for finding 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.
ldapDN	Base DN generated by the function. Your mapping function should allocate memory for `ldapDN` using `ldapu_malloc()` and set this variable using `cert` and `certmap_info`. This DN is passed on to CertSearchFn_t (Search Function). The DN serves as the base DN in the search for the certificate subject.
filter	Search filter generated by the function. Your mapping function should allocate memory for `filter` using `ldapu_malloc()` and set this variable using `cert` and `certmap_info`. This filter is passed on to CertSearchFn_t (Search Function). The search filter is used to find the entry for the certificate subject.

Returns

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

LDAPU_SUCCESS upon successful completion (the base DN and filter could be determined from the certificate and the certmap.conf file).

LDAPU_CERT_MAP_FUNCTION_FAILED if an error occurs or if the base DN and filter cannot be determined.

Description

The certificate mapping function is called by ldapu_cert_to_ldap_entry() to generate a base DN and a search filter that can be used to search for the certificate subject's entry in the directory.

The default certificate mapping function does the following:

Builds a base DN from the subject DN and the components specified in the DNComps entry in the certmap.conf file.

The output parameter ldapDN is the base DN constructed by this function call.

Builds a search filter from the subject DN and the components specified in the FilterComps entry if the certmap.conf file.

The output parameter filter is the search filter constructed by this function call.

If you want to customize this, you can define you own certificate mapping function. You can call some of the API functions described in this document to get information from certificates:

To get the values of these entries in the configuration file, call the ldapu_certmap_info_attrval() function.

You can also enter your own name-value pairs in the certmap.conf file and access these values by calling ldapu_certmap_info_attrval().

To get the values of the DN components for the certificate subject's DN, you can do one of the following:

Call the ldapu_get_cert_subject_dn() function to get the subject's DN, then parse the DN yourself.

Call the ldapu_get_cert_ava_val() function to get the values of a specified DN component (for example c, o, ou, cn).

Example

The following example is part of a certificate mapping function that gets the subject DN from the certificate.

#include "certmap.h"

...

/* My function for generating a base DN and filter from a certificate subject DN and the preferences under certmap.conf. */

static int my_cert_mapping_fn( void *cert, LDAP *ld, 
   void *certmap_info, char **ldapDN, char **filter)

char *subjectDN;

int rv;

char *my_val;

CertMapFn_t mapfn;

...

/* You can get the subject DN from the certificate by calling this function. */

rv = ldapu_get_cert_subject_dn( cert, &subjectDN );

/* You can call this function to get any name/value pair from the certmap.conf file (even your own custom pairs). */

ldapu_certmap_info_attrval( certmap_info, my_custom_attr, &my_val );

...

/* If you do not want to completely redefine the certificate mapping function, you can always get and call the default function.

*/

mapfn = ldapu_get_cert_mapfn(NULL);

rv = (*mapfn)(cert, ld, certmap_info, &ldapDN, &filter);

...

if (rv != LDAPU_SUCCESS) {

   /* Must return LDAPU_CERT_MAP_FUNCTION_FAILED on error. */

   return LDAPU_CERT_MAP_FUNCTION_FAILED;

...

CertMapFn_t (Mapping Function)

Syntax

Parameters

Returns

Description

Example

See Also