PAM-PKCS11 Mappers API

Juan Antonio Martinez

Release 0.5.3 30 Ago 2005


Table of Contents

1. Copyright. License
2. What is a pam_pkcs11 mapper?
2.1. Definition
2.2. Runtime options
2.3. Multiple mapping support
2.4. Mapfile support
2.5. Mapper tools and libraries
2.6. Configuration support
3. Writting a mapper
3.1. Before starting
3.2. Sample mapper configuration entry
3.3. Sample mapper include file
3.4. Skeleton code for mapper C file.
3.5. Insert mapper into tables
3.6. Adding mapper to Makefile.am to be compiled
3.7. Compilation
4. A Detailed look on mappers
4.1. The mapper chain
4.2. Exported data and structures
4.3. Comodity macros
4.4. Multifield mappers
4.5. Configuration entries on static mappers
5. The Mapper API
5.1. Debugging macros and functions
5.2. The mapfile API
5.3. Configuration parsing API
5.4. String tools API
5.5. BASE64 Encoding functions
5.6. X509 Cert Tools API
6. Going further
6.1. Hints
6.2. Getting help

PAM-PKCS#11 is a PAM (Pluggable Authentication Module) library and related tools to perform login into Linux/UNIX systems by mean of X509 Certificates through any pkcs#11 compliant library.

This manual describes how to create, compile and install pam_pkcs11 mappers. It also describes their API and related functions, and provide sample code

Chapter 1. Copyright. License

Copyright (C) 2005 Juan Antonio Martinez

Copyright (C) 2003-2004 of Mario Strasser

ScConf library Copyright (C) Antti Tapaninen and Timo Sirainen

Release 0.5beta1. 30 Mar 2005

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

Chapter 2. What is a pam_pkcs11 mapper?

2.1. Definition

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:

  1. Extract a item (cn, digest, or so) from provided certificate
  2. Deduce a login from the extracted item
  3. Test if a provided login matches with the previously deduced login
  4. (de)initialization routines
  5. A structure to access all internal methods

2.2. Runtime options

A mapper can be dinamycally or statically compiled against pam_pkcs11

  • An static mapper is one that is statically linked with pam_pkcs11.
  • A dynamic mapper needs to be loaded at runtime, and the path to the dynamic module must be provided

2.3. Multiple mapping support

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

2.4. Mapfile support

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

2.5. Mapper tools and libraries

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:

  • Mapfile functions
  • String tools
  • Debugging macros
  • URL handling functions
  • Configuration file tools
  • Etc...

2.6. Configuration support

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

Chapter 3. Writting a mapper

3.1. Before starting

  • Decide if the mapper will be statically or dinamically compiled The first way is for simple, quick and easy mappers that doesn't need aditional/optional libraries, just inspect certificate contents. The second way is for those mappers that need some optional libraries, such as ldap, kerberos, openssh or so
  • Decide on single or multiple items mapper
  • Choose a name and configuration options
  • Study provided mappers and libcommon / libmapper code

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

3.2. Sample mapper configuration entry

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

  • The name of the mapper
  • The dynamic library to be runtime loaded, or the keyword internal if the mapper is statically linked

  # 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

3.3. Sample mapper include file

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$
 */

#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

3.4.  Skeleton code for mapper C file.

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$
 */

#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

3.5. Insert mapper into tables

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

  • Add "foo_mapper.h" to #include list
  • Add exported entries to static mapper entries table:

#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

3.6. Adding mapper to Makefile.am to be compiled

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

  • Add "-DFOO_MAPPER_STATIC" to AM_CFLAGS options
  • Add "foo_mapper.c" and "foo_mapper.h" to libmappers_la_SOURCES entry

To compile as dynamic mapper:

  • Add "foo_mapper.la" to lib_LTLIBRARIES entry
  • Add compile options for "foo_mapper.la" , for instance:
    .....
    foo_mapper_la_SOURCES = foo_mapper.c foo_mapper.h
    foo_mapper_la_LDFLAGS = -module -avoid-version
    foo_mapper_la_LIBADD = libmappers.la
    .....
    

3.7. Compilation

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

Chapter 4. A Detailed look on mappers

4.1. The mapper chain

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

4.2. Exported data and structures

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:

  • name is the name of the mapper module, as provided in the init() call
  • block is a pointer to the mapper configuration entry as defined in /etc/pam_pkcs11/pam_pkcs11.conf, as provided int the init() call
  • context is a pointer to a user-defined local declarations internals to the mapper. If not used it's safe to set to NULL. See below about how to use this entry in multiple instances of same static compiled mapper
  • entries() is the entry point to the mapper listing method
  • finder() is the entry point to the mapper login finder method
  • matcher() is the entry point to the mapper login matcher method
  • entries() is called when the mapper module is to be removed from mapper chain
  • dbg_level stores the debugging level to be used when calling any function inside the mapper. Note that the programmer doesn't need to take care on this field: when mapper_module_init() successfully returns, the module loader assumes that returning debug level is the one selected for the mapper, and store it in this field

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

4.3. Comodity macros

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

  • _DEFAULT_MAPPER_FIND_ENTRIES to serve as a replacement for entries() listing method
  • _DEFAULT_MAPPER_FIND_USER to serve as a replacement for finder() login mapper method
  • _DEFAULT_MAPPER_MATCH_USER to serve as a replacement for matcher() login matching method
  • _DEFAULT_MAPPER_END to serve as a replacement for deinit() de-initialization method
  • _DEFAULT_MAPPER_INIT to serve as a replacement for init() initialization method

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

4.4. Multifield mappers

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:

  • You should provided one mapper entry for each mapper personality in the configuration file
  • If the mapper is to be statically linked, you should also declare one entry for each personality in the src/mappers/mapperlist.c mapper list declaration file
  • The mapper loader will make as many calls to mapper_module_init() as declared in mapper chain definition. On each call a different name and configuration context will be provided, and a different mapper_module structure should be returned
  • There are an additional problem when use statically linked mappers: They cannot contain any global variable, as consecutive init call will overwrite previous value. This is not the case of dynloaded mappers, as each instance has its own address space
  • If the above case is yours one, then you must define and create by mean of malloc() an internal environment structure, and store it in the context field of the returned mapper_module structure. pam_pkcs11 will include this data in every calls to your entry points, to get sure you can retrieve correct internal data

4.5.  Configuration entries on static mappers

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:

  • module Must be set to internal
  • debug The debug level. Defaults to false
  • ignorecase Ignore letter case on matching functions. Defaults to false
  • mapfile Mapping file to be used. Defaults to "none"

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

Chapter 5. The Mapper API

5.1. Debugging macros and functions

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]

  • void set_debug_level(int level); Sets the debug level
  • int get_debug_level(void); Gets the debug level
  • void debug_print(int level, char *file, int line, char *format, ...); Prints a message if level is greater than current debug level
  • DBG(), DBG1(), ... DBG5() Are shortcut macros to debug_print() function
  • void set_error(char *format, ...); Sets the "last error" message entry
  • const char *get_error(); Gets the last error message

5.2. The mapfile API

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:

  • struct mapfile *set_mapent(const char *uri); Initializes mapfile data structure
  • int get_mapent(struct mapfile *mfile); Iterative calls returns next key/value pairs in mapfile
  • void end_mapent(struct mapfile *mfile); Closes and releases mapfile
  • char *mapfile_find(const char *file,char *key,int ignorecase); To find a given key/value pair in a mapfile
  • int mapfile_match(const char *file,char *key,const char *value,int ignorecase); To test if any entry on mapfile matches key/value pair

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

5.3.  Configuration parsing API

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:

  • const char *scconf_get_str(const scconf_block * block, const char *option, const char *default); To retrieve the string value assigned to keyword option or return default if keyword not found
  • int scconf_get_int(const scconf_block * block, const char *option, int default); To retrieve the integer value assigned to keyword option or return default if keyword not found
  • int scconf_get_bool(const scconf_block * block, const char *option, int default); To retrieve the boolean value assigned to keyword option or return default if keyword not found

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

5.4.  String tools API

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

  • int is_empty_str(const char *str); Returns true if str is null, empty, or has only spaces
  • char *clone_str(const char *str); Returns a duplicate of provided string
  • char *toupper_str(const char *str); Same as above, but string is upper-case'd
  • char *tolower_str(const char *str); Same as above, but string is lower-case'd
  • char *bin2hex(const unsigned char *binstr,const int len); Return a string that contains the hexadecimal representation of the provided binary array of given length. Returned format is :XX:YY:ZZ:...:
  • unsigned char *hex2bin(const char *hexstr); Convert a colon-separated hexadecimal string into a binary array
  • unsigned char *hex2bin_static(const char *hexstr,unsigned char **res,int *size); Same as above, but programmer supplies pre-allocated memory space for conversion
  • char **split(const char *str,char sep, int nelems); Splits provided string in an string array of nelems elements, using sep as character separator
  • char **split_static(const char *str,char sep, int nelems,char *dst); Same as above, but user provides pre-allocated buffer for storeing result
  • char *trim(const char *str); Return an string that has all superfluous spaces trimmed. Also converts any space char ( newline, tabs, etc ) in normal " " space character

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 :-)

5.5.  BASE64 Encoding functions

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

  • int base64_encode(const unsigned char *in, size_t len, unsigned char *out, size_t outlen) To encode a byte array into a base64 string
  • int base64_decode(const char *in, unsigned char *out, size_t outlen) To decode a base64 data into a byte array

See doxygen documentation and source code for more info

5.6.  X509 Cert Tools API

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:

  • char **cert_info(X509 *x509, int type, const char *algorithm);

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:

  • CERT_CN Certificate Common Name
  • CERT_SUBJECT Certificate subject
  • CERT_KPN Kerberos principal name
  • CERT_EMAIL Certificate e-mail
  • CERT_UPN Microsoft's Universal Principal Name
  • CERT_UID Certificate Unique Identifier
  • CERT_PUK Certificate Public Key (PEM Format)
  • CERT_DIGEST Certificate Digest
  • CERT_SSHPUK Certificate Public key in OpenSSH format
  • CERT_PEM Certificate in PEM format

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:

  • int verify_certificate(X509 * x509, char *ca_dir, char *crl_dir, crl_policy_t policy); To check a certificate
  • int verify_signature(X509 * x509, unsigned char *data, int data_length, unsigned char *signature, int signature_length); To verify a signature

Chapter 6. Going further

6.1. Hints

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

6.2. Getting help

Send questions, patches, suggestions and so to OpenSC Mailing list:

For additional specific info, contact with the authors: