PAM-PKCS11 Mappers API

When an X509 Certificate is provided, there are no direct way to map a cert to a login. With a certificate we can check validity and revocation, but user mapping depends entirely on the certificate content.

So we need a configurable, stackable, and definable way to specify cert-to-user mapping.

pam-pkcs11 cert mappers should provide these functions:

A mapper can be dinamycally or statically compiled against pam_pkcs11

A mapper can provide several ways to realize mapping functions. As the mapper name is provided to initialization routines, the mapper cand adjust their internal pointers according name. In this case, the same mapper will be instantiated (or dynloaded) as many times as different mappings required

Most of certificate fields are not valid for login names. We need a way to map field to login. This is done by mean of mapfiles. The mapper API provides several functions to manage mapfiles

Pam_pkcs11 provides several utility functions to manage certificate contents. Instead of start from scratch these functions may be used to ease mapper coding. You'll find:

Althought all mappers have default values, most of then have configuration options. The file /etc/pam_pkcs11/pam_pkcs11.conf stores them.

The best way to start is by mean of these skeleton files:

All mappers should have a configuration entry in /etc/pam_pkcs11/pam_pkcs11.conf. These entry should at least define:

  # foo  - Maps FOO certificate field (if exist) to login
  mapper foo {
        debug = false;
        # For dinamycally loaded mappers
	# module = /usr/lib/pam_pkcs11/foo_mapper.so;
	# For statically linked mappers
	module = internal;
        ignorecase = false;
        mapfile = "none";
  }

Note the module option. It says pam_pkcs11 if the mapper is static or must be dynloaded in runtime. If so, it must include the full path to the mapper dynamic library

When the mapper is used to map more than one field, you should add one entry for each mapped field. Each entry must have an unique mapper name, and (if the mapper is to be dynamically loaded) the same library name path

See bellow on how to set up code to include multiple fields mappers to be statically compiled

Here comes a sample mapper include file. Note that their main use is to allow export internal data when statically compiled. Unless you need several files to define a mapper, no need of more data to be included

/*
 * PAM-PKCS11 mapping modules
 * ------------- YOUR COPYRIGHT CREDITS HERE --------------------
 * Copyright (C) 2005 Juan Antonio Martinez <jonsito@teleline.es>
 * pam-pkcs11 is copyright (C) 2003-2004 of Mario Strasser <mast@gmx.net>
 *
 * This library is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Lesser General Public
 * License as published by the Free Software Foundation; either
 * version 2.1 of the License, or (at your option) any later version.
 *
 * This library is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 * Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public
 * License along with this library; if not, write to the Free Software
 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
 *
 * $Id: mappers_api.xml 233 2007-04-04 09:52:54Z ludovic.rousseau $
 */

#ifndef __FOO_MAPPER_H_
#define __FOO_MAPPER_H_

#ifdef HAVE_CONFIG_H
#include <config.h>
#endif

#include "../scconf/scconf.h"
#include "mapper.h"

/* include here container declaration if you intend to 
declare and use several instances of this mapper */

typedef struct myContext_st {
	/* local declarations here */
} myContext;

#ifdef FOO_MAPPER_STATIC

#ifndef __FOO_MAPPER_C_
#define FOO_EXTERN extern
#else
#define FOO_EXTERN
#endif
FOO_EXTERN mapper_module * foo_mapper_module_init(scconf_block *blk,const char *mapper_name);
#undef FOO_EXTERN

/* end of static (if any) declarations */
#endif

/* End of foo_mapper.h */
#endif

This is a sample skeleton file for single field mappers. It provides all the methods and data required by the API. Is up to you to include aditional functions as required.

They only need to export one symbol: the entry point of the init routine

If the mapper is to be dynamically loaded, this symbol has a fixed name: mapper_module_init

If the mapper is to be statically linked, is up to you to decide the exported symbol name, but it's suggested for comodity, just prepend the mapper name as prefix, to avoid collisions. Remember that these names will be added into the static mapper table list

Note that this skeleton file provides support for either static or dynamic linking. Our suggestion is follow this convention, making your mapper as versatile as possible

/*
 * PAM-PKCS11 FOO mapper module
 * -------------- YOUR COPYRIGHTS CREDITS HERE --------------------
 * Copyright (C) 2005 Juan Antonio Martinez <jonsito@teleline.es>
 * pam-pkcs11 is copyright (C) 2003-2004 of Mario Strasser <mast@gmx.net>
 *
 * This library is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Lesser General Public
 * License as published by the Free Software Foundation; either
 * version 2.1 of the License, or (at your option) any later version.
 *
 * This library is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 * Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public
 * License along with this library; if not, write to the Free Software
 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
 *
 * $Id: mappers_api.xml 233 2007-04-04 09:52:54Z ludovic.rousseau $
 */

#define __FOO_MAPPER_C_

#ifdef HAVE_CONFIG_H
#include <config.h>
#endif

/* required standard headers here */
#include <openssl/x509.h>
/* Pam_pkcs11 API headers here */
#include "../scconf/scconf.h"
#include "../common/debug.h"
#include "../common/error.h"
#include "../common/strings.h"
#include "../common/cert_info.h"

/* mandatory includes */
#include "mapper.h"
#include "foo_mapper.h"

/*
* Summary:
* This mapper uses the FOO entry in the certificate to deduce 
* user name
*/

/* local variables */
/* 
NOTE:
When multiple instances of an static module are declared, it's a
bad idea to use local variables. 
Declare and use a context container instead
*/
static const char *mapfile="none";
static int ignorecase=0;
static int debug=0;

/**
* Return array of found FOO's
*/
static char ** mapper_find_entries(X509 *x509, void *context) {
	/* your code here* */
}

/*
* Parses the certificate and return the first FOO entry found, or NULL
*/
static char * mapper_find_user(X509 *x509, void *context) {
	/* your code here */
}

/*
* parses the certificate and try to macht any FOO entry in the certificate
* with provided user
* returns: 1 on success
*          0 on no match
*         -1 on fail
*/
static int mapper_match_user(X509 *x509,const char *login, void *context) {
	/* your code here */
}

/*
* Closes and frees all resources for this mapper
*/
static void mapper_module_end(void, void *context) {
       /* your code here */
}

/*
* initialize entry points
*/
static mapper_module * init_mapper_st(
	scconf_block *blk, /* pointer to configuration block */
	const char *name   /* mapper name */
	) {
	mapper_module *pt=malloc(sizeof(mapper_module));
	if (!pt) return NULL;
	pt->name = name;
	pt->block = blk;
	pt->context = NULL;
	pt->dbg_level = get_debug_level();
	pt->entries = mapper_find_entries;
	pt->finder = mapper_find_user;
	pt->matcher = mapper_match_user;
	pt->mapper_module_end = mapper_module_end;
	return pt;
}

/**
* Initialization entry point
* return mapper_module pointer on success
*        NULL on fail
*/
#ifndef FOO_MAPPER_STATIC
mapper_module * mapper_module_init(scconf_block *blk,const char *mapper_name) {
#else
mapper_module * foo_mapper_module_init(scconf_block *blk,const char *mapper_name) {
#endif
	mapper_module *pt;

	/* Read configuration */
	if(blk) {
	    debug= scconf_get_bool(blk,"debug",0);
	    mapfile= scconf_get_str(blk,"mapfile",mapfile);
	    ignorecase= scconf_get_bool(blk,"ignorecase",ignorecase);
	    set_debug_level(debug);
	} else {
	    set_debug_level(debug);
	    DBG1("No configuration entry for mapper '%s'. Assume defaults",mapper_name);
	}

	/* set up internal variables */


	/* initialize function entry points */
	pt = init_mapper_st(pt,blk,mapper_name);
        return pt;
}

/* end of foo_mapper.c */
#undef __FOO_MAPPER_C_

See bellow on what's each function is intended to do, comodity macros, and some examples on how to code them

Next task is insert mapper into mappers list, by adding it to mapperlist.c

#include "foo_mapper.h"
......
mapper_list static_mapper_list [] = {
....
#ifdef FOO_MAPPER_STATIC
        { "foo", foo_mapper_module_init },
	/* if your mapper manages more than one mapping scheme, add it */
        { "foo2", foo_mapper_module_init },
        { "foo3", foo_mapper_module_init },
#endif
....
    { NULL, NULL }
};

As you can see, if your module support several mapping schemes, you should insert one entry for each one. All the entries will share the same entry point, but differs in module name

Finally add entry to src/mappers/Makefile.am file and recompile. Note that with the current pam_pkcs11 version you cannot compile a dynamically loaded mapper in a separate way. This is a job in progress

To compile as static mapper

To compile as dynamic mapper:

That's all: recompile and install

root# cd /base/directory
root# make maintainer-clean
root# ./bootstrap
root# ./configure --your-configure-options
root# make
root# make install

Take a look at src/pam_pkcs11/mapper_mgr.h. This file contains the data structures used to load a mapper and create a mapper chain

Mapper instance entry declaration:

struct mapper_instance {
    void *module_handler; 	/* dynamic module descriptor */
    const char *module_name;	/* mapper module name */
    const char *module_path;	/* dynamic module path */
    mapper_module *module_data;	/* mapper module entries table */
};

On statically compiled mappers, module_handler and module_path equals to NULL

Mapper chain entry declaration:

struct mapper_listitem {
        struct mapper_instance *module; /* pointer to module instance */
        struct mapper_listitem *next;   /* pointer to next item in chain */
};

The list of mappers to be loaded are declared by mean of use_mappers entry in /etc/pam_pkcs11/pam_pksc11.conf configuration file. Each declared mapper is loaded in turn. The first in the list will be the first one in the mapper chain

On each mapper entry, pam_pkcs11 search for the module keyword. If not found, or equals to "internal", the code assumes that reffers to an statically linked mapper, and search it in the list of mappers declared at src/mappers/mapperlist.c. Otherwise assume that we provide the full pathname to a dynamic library, and try to load by mean of dlopen() function

When module is found or loaded, the module_load() calls to the mapper_module_init() function, and if the result is not null assumes to be returned a pointer to the internal mapper entries table. These entries will be used to call finder, matcher, and deinit functions on the mapper

If, for any reason, the mapper loading process, a warn is sent, and the mapper entry module is skipped

The mapper_module_init() should return a pointer to the following structure (declared in src/mappers/mapper.h

/**
* Structure to be filled on mapper module initialization
*/
typedef struct mapper_module_st {
    const char *name; 
    scconf_block *block;
    void *context;
    int dbg_level;
    char **(*entries)(X509 *x509, void *context);
    char *(*finder)(X509 *x509, void *context);
    int (*matcher)(X509 *x509, const char *login, void *context);
    void (*deinit)( void *context);
} mapper_module;

Here comes the meaning of each entry:

Note that context pointer is passed as void * as there are no way to know how the programmer will use it

Many of the mapper functions are repetitive. Many others are nonsense in some mappers. So the API provide several comodity macros, defined in src/mappers/mapper.h

The only usefull one is _DEFAULT_MAPPER_END, but the other ones are provided for compile work-in-progress mappers

See the code, to provide you an idea of how to code real functions

The sample code provided in first section can be used directly to create single field mappers. When writting multiple fields mappers ( a mapper, that can resolve two or more different certificate contents, ie CN and KPN ), a different approach is needed:

As stated above, to specify that a mapper is not to be dynamically linked, we should remove the keyword "module", or set it to "module = internal ;"

Most of statically linked mappers share common configuration options:

So if up to the system administrator, if agreed with default values, to ommit in the configuration file /etc/pam_pkcs11/pam_pkcs11.conf the mapper entry for this module. The module loader will look for proper mapper entry. If not found, assume that the module is static, and will try to load it and set up with default values. This behaviour is coded in the provided sample skeleton file for coding mappers

Above note does not apply, of course, to dynamically loaded mappers, as they allways need at least the "module" entry to be specified

See PAM-PKCS#11 Manual to see specific notes on provided mappers

Several functions and macros are provided to generate and display debug and error messages. See files src/common/debug.[ch] and src/common/error.[ch]

The mapper API provides several functions to manage mapfiles. They are declared in src/mappers/mapper.h

To use a mapfile, we must create a mapfile entry, then make sucessive calls to retrieve data, and finally destroy the structure. It works in a similar way as setpwent(), getpwent() and endpwent() functions works in walking throught a password file

The mapfile structure is defined as:

/*
* This struct is used in processing map files
* a map file is a list of "key" " -> " "value" text lines
*/
struct mapfile {
        const char *uri;/* URL of mapfile */
        char *buffer;   /* buffer to content of mapfile */
        size_t length;  /* lenght of buffer */
        char *pt;       /* pointer to last readed entry in buffer */
        char *key;      /* key entry in current buffer */
        char *value;    /* value assigned to key */
};

The API defines following functions:

An important note is that mapfiles names can be provided as standard UNIX path names, or Universal Resource Locators. For instance, you can use either /etc/pam_pkcs11/subject_mapping or file:///etc/pam_pkcs11/subject_mapping. Our recommentation is to use second format as is not restricted to local files

NOTE: The returned "key" and "value" entries should be used as const char *, that is, contents cannot be modified nor free()'d. If the programmer needs to modify these values, please make a copy with the clone_str() API provided function

PAM-PKCS#11 configuration files are based in the SCConf library of the OpenSC Project. See the file src/scconf/README.scconf for a detailed description of the scconf

As a resume, bellow are shown the most relevants scconf API functions for the mapper programmer:

With these functions, we can easily parse all "key = value;" entries on the mapper configuration block of the configuration file

NOTE: The user should not modify nor free() values returned from scconf_get_str(). Instead, call clone_str() API method to get a working copy

The string.h standard library is so powerfull. But lacks on some usefull routines. The file src/common/strings.c contains some of them, as declared at src/common/strings.h

A note on split(), and split_static() functions. To free allocated resources, is enought to call free() on the first element of the array

Note that trim() function behaviour is different from Java or PHP counterparts, as remove ALL extra spaces, not only at the begining and at the end of string

See the code for further reference :-)

In order to read/write public SSH keys, two funtions are provided to manage base64 encoding:

See doxygen documentation and source code for more info

The mapper API provides several adittional tools to inspect the contents of a certificate. They are described in src/common/cert_info.h

The basic library call is:

This function takes an argument, the X509 certificate to be inspected, and a macro that shows the certificate content to be searched. Some contents needs an aditional third algorithm parameters. When not used should be set to NULL

The mapper API defines following macros:

Aditionally, when requesting CERT_DIGEST you must provide a valid digest algorithm: "null", "md2", "md4", "md5", "sha", "sha1", "dss", "dss1" or "ripemd160"

cert_info() returns an array of up to 15 string entries, corresponding to as many entry founds in the provided certificate. Last entry in the returned array is set to NULL;

If some error ocurrs, or the certificate does not contain any entry, return NULL

There are two additional methods to check certificate/signatures:

It's really recommended the study of provided mappers, and the comodity macros

Before start writting a new mapper, perhaps you'd better to check if there are already one mapper that performs your desired map. For instance, pwent and generic mapper can use Naming Swictch Service (NSS) to lookup pasword entries, and NSS is capable of perform some LDAP or Kerberos authentication task

Don't hessitate in use of debugging functions. They are really usefull

It's recommended write mappers in a way that they could be statically or dynamically linked without code change, Doing so you'll make maintainer life easier :-) Also, in order to ease debugging, single field mappers is preferred over multifield mappers

Avoid write access to any global variable from the mapper code. Use comodity functions

Don't make assumptions on the code. Allways add checks.

Use Universal Resource Locators -and the curl library- instead of hardcoded pathnames to specify files

Send questions, patches, suggestions and so to OpenSC Mailing list: <opensc-devel at opensc-project.org>

For additional specific info, contact with the authors: