<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>PAM-PKCS11 Mappers API</title><link rel="stylesheet" href="pam_pkcs11.css" type="text/css" /><meta name="generator" content="DocBook XSL Stylesheets V1.75.2" /></head><body><div class="book" title="PAM-PKCS11 Mappers API"><div class="titlepage"><div><div><h1 class="title"><a id="mapper-api"></a>PAM-PKCS11 Mappers API</h1></div><div><div class="author"><h3 class="author"><span class="firstname">Juan Antonio</span> <span class="surname">Martinez</span></h3><code class="email"><<a class="email" href="mailto:jonsito@teleline.es">jonsito@teleline.es</a>></code></div></div><div><p class="releaseinfo">Release 0.5.3 30 Ago 2005</p></div></div><hr /></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="chapter"><a href="#copyright">1. Copyright. License</a></span></dt><dt><span class="chapter"><a href="#introduction">2. What is a <span class="application">pam_pkcs11</span> mapper?</a></span></dt><dd><dl><dt><span class="sect1"><a href="#id382346">2.1. Definition</a></span></dt><dt><span class="sect1"><a href="#id385902">2.2. Runtime options</a></span></dt><dt><span class="sect1"><a href="#id385938">2.3. Multiple mapping support</a></span></dt><dt><span class="sect1"><a href="#id385950">2.4. Mapfile support</a></span></dt><dt><span class="sect1"><a href="#id385962">2.5. Mapper tools and libraries</a></span></dt><dt><span class="sect1"><a href="#id382664">2.6. Configuration support</a></span></dt></dl></dd><dt><span class="chapter"><a href="#writting">3. Writting a mapper</a></span></dt><dd><dl><dt><span class="sect1"><a href="#id382691">3.1. Before starting</a></span></dt><dt><span class="sect1"><a href="#id382943">3.2. Sample mapper configuration entry</a></span></dt><dt><span class="sect1"><a href="#id383005">3.3. Sample mapper include file</a></span></dt><dt><span class="sect1"><a href="#id383054">3.4. Skeleton code for mapper C file.</a></span></dt><dt><span class="sect1"><a href="#id421803">3.5. Insert mapper into tables</a></span></dt><dt><span class="sect1"><a href="#id421838">3.6. Adding mapper to Makefile.am to be compiled</a></span></dt><dt><span class="sect1"><a href="#id421912">3.7. Compilation</a></span></dt></dl></dd><dt><span class="chapter"><a href="#deeper">4. A Detailed look on mappers</a></span></dt><dd><dl><dt><span class="sect1"><a href="#id421936">4.1. The mapper chain</a></span></dt><dt><span class="sect1"><a href="#id422042">4.2. Exported data and structures</a></span></dt><dt><span class="sect1"><a href="#id422151">4.3. Comodity macros</a></span></dt><dt><span class="sect1"><a href="#id422231">4.4. Multifield mappers</a></span></dt><dt><span class="sect1"><a href="#id422303">4.5. Configuration entries on static mappers </a></span></dt></dl></dd><dt><span class="chapter"><a href="#api">5. The Mapper API</a></span></dt><dd><dl><dt><span class="sect1"><a href="#id422388">5.1. Debugging macros and functions</a></span></dt><dt><span class="sect1"><a href="#id422469">5.2. The mapfile API</a></span></dt><dt><span class="sect1"><a href="#id422592">5.3. Configuration parsing API</a></span></dt><dt><span class="sect1"><a href="#id422699">5.4. String tools API</a></span></dt><dt><span class="sect1"><a href="#id422843">5.5. BASE64 Encoding functions </a></span></dt><dt><span class="sect1"><a href="#id422877">5.6. X509 Cert Tools API</a></span></dt></dl></dd><dt><span class="chapter"><a href="#more">6. Going further</a></span></dt><dd><dl><dt><span class="sect1"><a href="#id423055">6.1. Hints</a></span></dt><dt><span class="sect1"><a href="#id423093">6.2. Getting help</a></span></dt></dl></dd></dl></div><div class="abstract" title="Abstract"><p class="title"><b>Abstract</b></p><p>
<span class="application">PAM-PKCS#11</span> 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.
</p><p>
This manual describes how to create, compile and install
<span class="application">pam_pkcs11</span> mappers. It also describes their API and related functions,
and provide sample code
</p></div><div class="chapter" title="Chapter 1. Copyright. License"><div class="titlepage"><div><div><h2 class="title"><a id="copyright"></a>Chapter 1. Copyright. License</h2></div></div></div><p>
Copyright (C) 2005 Juan Antonio Martinez <code class="email"><<a class="email" href="mailto:jonsito@teleline.es">jonsito@teleline.es</a>></code>
</p><p>
Copyright (C) 2003-2004 of Mario Strasser <code class="email"><<a class="email" href="mailto:mstt@gmx.net">mstt@gmx.net</a>></code>
</p><p>
ScConf library Copyright (C) Antti Tapaninen <code class="email"><<a class="email" href="mailto:aet@cc.hut.fi">aet@cc.hut.fi</a>></code> and Timo Sirainen <code class="email"><<a class="email" href="mailto:tss@iki.fi">tss@iki.fi</a>></code>
</p><p>
Release 0.5beta1. 30 Mar 2005
</p><p>
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.
</p><p>
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.
</p><p>
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
</p></div><div class="chapter" title="Chapter 2. What is a pam_pkcs11 mapper?"><div class="titlepage"><div><div><h2 class="title"><a id="introduction"></a>Chapter 2. What is a <span class="application">pam_pkcs11</span> mapper?</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="sect1"><a href="#id382346">2.1. Definition</a></span></dt><dt><span class="sect1"><a href="#id385902">2.2. Runtime options</a></span></dt><dt><span class="sect1"><a href="#id385938">2.3. Multiple mapping support</a></span></dt><dt><span class="sect1"><a href="#id385950">2.4. Mapfile support</a></span></dt><dt><span class="sect1"><a href="#id385962">2.5. Mapper tools and libraries</a></span></dt><dt><span class="sect1"><a href="#id382664">2.6. Configuration support</a></span></dt></dl></div><div class="sect1" title="2.1. Definition"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="id382346"></a>2.1. Definition</h2></div></div></div><p>
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.
</p><p>
So we need a configurable, stackable, and definable way to specify
cert-to-user mapping.
</p><p>
pam-pkcs11 cert mappers should provide these functions:
</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem">Extract a item (cn, digest, or so) from provided certificate</li><li class="listitem">Deduce a login from the extracted item</li><li class="listitem">Test if a provided login matches with the previously deduced login</li><li class="listitem">(de)initialization routines</li><li class="listitem">A structure to access all internal methods</li></ol></div><p>
</p></div><div class="sect1" title="2.2. Runtime options"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="id385902"></a>2.2. Runtime options</h2></div></div></div><p>
A mapper can be dinamycally or statically compiled against <span class="application">pam_pkcs11</span>
</p><p>
</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem">An static mapper is one that is statically linked with <span class="application">pam_pkcs11</span>.</li><li class="listitem">A dynamic mapper needs to be loaded at runtime, and the path to
the dynamic module must be provided</li></ul></div><p>
</p></div><div class="sect1" title="2.3. Multiple mapping support"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="id385938"></a>2.3. Multiple mapping support</h2></div></div></div><p>
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
</p></div><div class="sect1" title="2.4. Mapfile support"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="id385950"></a>2.4. Mapfile support</h2></div></div></div><p>
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
</p></div><div class="sect1" title="2.5. Mapper tools and libraries"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="id385962"></a>2.5. Mapper tools and libraries</h2></div></div></div><p>
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:
</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem">Mapfile functions</li><li class="listitem">String tools</li><li class="listitem">Debugging macros</li><li class="listitem">URL handling functions</li><li class="listitem">Configuration file tools</li><li class="listitem">Etc...</li></ul></div><p>
</p></div><div class="sect1" title="2.6. Configuration support"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="id382664"></a>2.6. Configuration support</h2></div></div></div><p>
Althought all mappers have default values, most of then have
configuration options. The file <code class="filename">/etc/pam_pkcs11/pam_pkcs11.conf</code>
stores them.
</p></div></div><div class="chapter" title="Chapter 3. Writting a mapper"><div class="titlepage"><div><div><h2 class="title"><a id="writting"></a>Chapter 3. Writting a mapper</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="sect1"><a href="#id382691">3.1. Before starting</a></span></dt><dt><span class="sect1"><a href="#id382943">3.2. Sample mapper configuration entry</a></span></dt><dt><span class="sect1"><a href="#id383005">3.3. Sample mapper include file</a></span></dt><dt><span class="sect1"><a href="#id383054">3.4. Skeleton code for mapper C file.</a></span></dt><dt><span class="sect1"><a href="#id421803">3.5. Insert mapper into tables</a></span></dt><dt><span class="sect1"><a href="#id421838">3.6. Adding mapper to Makefile.am to be compiled</a></span></dt><dt><span class="sect1"><a href="#id421912">3.7. Compilation</a></span></dt></dl></div><div class="sect1" title="3.1. Before starting"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="id382691"></a>3.1. Before starting</h2></div></div></div><p>
</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem">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</li><li class="listitem">Decide on single or multiple items mapper</li><li class="listitem">Choose a name and configuration options</li><li class="listitem">Study provided mappers and <span class="application">libcommon</span> / <span class="application">libmapper</span> code</li></ul></div><p>
</p><p>
The best way to start is by mean of these skeleton files:
</p></div><div class="sect1" title="3.2. Sample mapper configuration entry"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="id382943"></a>3.2. Sample mapper configuration entry</h2></div></div></div><p>
All mappers should have a configuration entry in <code class="filename">/etc/pam_pkcs11/pam_pkcs11.conf</code>. These entry should at least define:
</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"> The name of the mapper</li><li class="listitem"> The dynamic library to be runtime loaded, or the keyword <code class="option">internal</code> if the mapper is statically linked </li></ul></div><p>
</p><pre class="screen">
# 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";
}
</pre><p>
</p><p>
Note the <code class="option">module</code> option. It says <span class="application">pam_pkcs11</span> if the mapper is static or must be dynloaded in runtime. If so, it must include the full path to the mapper dynamic library
</p><p>
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
</p><p>
See bellow on how to set up code to include multiple fields mappers to be
statically compiled
</p></div><div class="sect1" title="3.3. Sample mapper include file"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="id383005"></a>3.3. Sample mapper include file</h2></div></div></div><p>
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
</p><pre class="screen">
/*
* 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
</pre><p>
</p></div><div class="sect1" title="3.4.  Skeleton code for mapper C file."><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="id383054"></a>3.4. Skeleton code for mapper C file.</h2></div></div></div><p>
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.
</p><p>
They only need to export one symbol: the entry point of the init routine
</p><p>
If the mapper is to be dynamically loaded, this symbol has a fixed name:
<code class="function">mapper_module_init</code>
</p><p>
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
</p><p>
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
</p><pre class="screen">
/*
* 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_
</pre><p>
</p><p>
See bellow on what's each function is intended to do, comodity macros,
and some examples on how to code them
</p></div><div class="sect1" title="3.5. Insert mapper into tables"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="id421803"></a>3.5. Insert mapper into tables</h2></div></div></div><p>
Next task is insert mapper into mappers list, by adding it to mapperlist.c
</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem">Add "foo_mapper.h" to #include list</li><li class="listitem">Add exported entries to static mapper entries table:</li></ul></div><p>
</p><p>
</p><pre class="screen">
#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 }
};
</pre><p>
</p><p>
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
</p></div><div class="sect1" title="3.6. Adding mapper to Makefile.am to be compiled"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="id421838"></a>3.6. Adding mapper to Makefile.am to be compiled</h2></div></div></div><p>
Finally add entry to <code class="filename">src/mappers/Makefile.am</code> file and recompile.
Note that with the current <span class="application">pam_pkcs11</span> version you cannot compile
a dynamically loaded mapper in a separate way. This is a job in progress
</p><p>
To compile as static mapper
</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem">Add <code class="option">"-DFOO_MAPPER_STATIC"</code> to <code class="option">AM_CFLAGS</code> options</li><li class="listitem">Add <code class="filename">"foo_mapper.c"</code> and <code class="filename">"foo_mapper.h"</code> to <code class="option">libmappers_la_SOURCES</code> entry</li></ul></div><p>
</p><p>
To compile as dynamic mapper:
</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem">Add "foo_mapper.la" to lib_LTLIBRARIES entry</li><li class="listitem">Add compile options for "foo_mapper.la" , for instance:
<pre class="screen">
.....
foo_mapper_la_SOURCES = foo_mapper.c foo_mapper.h
foo_mapper_la_LDFLAGS = -module -avoid-version
foo_mapper_la_LIBADD = libmappers.la
.....
</pre></li></ul></div><p>
</p></div><div class="sect1" title="3.7. Compilation"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="id421912"></a>3.7. Compilation</h2></div></div></div><p>
That's all: recompile and install
</p><pre class="screen">
root# cd /base/directory
root# make maintainer-clean
root# ./bootstrap
root# ./configure --your-configure-options
root# make
root# make install
</pre><p>
</p></div></div><div class="chapter" title="Chapter 4. A Detailed look on mappers"><div class="titlepage"><div><div><h2 class="title"><a id="deeper"></a>Chapter 4. A Detailed look on mappers</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="sect1"><a href="#id421936">4.1. The mapper chain</a></span></dt><dt><span class="sect1"><a href="#id422042">4.2. Exported data and structures</a></span></dt><dt><span class="sect1"><a href="#id422151">4.3. Comodity macros</a></span></dt><dt><span class="sect1"><a href="#id422231">4.4. Multifield mappers</a></span></dt><dt><span class="sect1"><a href="#id422303">4.5. Configuration entries on static mappers </a></span></dt></dl></div><div class="sect1" title="4.1. The mapper chain"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="id421936"></a>4.1. The mapper chain</h2></div></div></div><p>
Take a look at <code class="filename">src/pam_pkcs11/mapper_mgr.h</code>. This file contains the data structures used to load a mapper and create a mapper chain
</p><p>
Mapper instance entry declaration:
</p><pre class="screen">
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 */
};
</pre><p>
On statically compiled mappers, <code class="option">module_handler</code> and <code class="option">module_path</code> equals to <code class="option">NULL</code>
</p><p>
Mapper chain entry declaration:
</p><pre class="screen">
struct mapper_listitem {
struct mapper_instance *module; /* pointer to module instance */
struct mapper_listitem *next; /* pointer to next item in chain */
};
</pre><p>
</p><p>
The list of mappers to be loaded are declared by mean of <code class="option">use_mappers</code> entry in <code class="filename">/etc/pam_pkcs11/pam_pksc11.conf</code> configuration file. Each declared mapper is loaded in turn. The first in the list will be the first one in the mapper chain
</p><p>
On each mapper entry, <span class="application">pam_pkcs11</span> search for the <code class="option">module</code> keyword. If not found, or equals to "<code class="option">internal</code>", the code assumes that reffers to an statically linked mapper, and search it in the list of mappers declared at <code class="filename">src/mappers/mapperlist.c</code>. Otherwise assume that we provide the full pathname to a dynamic library, and try to load by mean of <code class="function">dlopen()</code> function
</p><p>
When module is found or loaded, the <code class="function">module_load()</code> calls to the <code class="function">mapper_module_init()</code> 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
</p><p>
If, for any reason, the mapper loading process, a warn is sent, and the mapper entry module is skipped
</p></div><div class="sect1" title="4.2. Exported data and structures"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="id422042"></a>4.2. Exported data and structures</h2></div></div></div><p>
The <code class="function">mapper_module_init()</code> should return a pointer to the following structure (declared in <code class="filename">src/mappers/mapper.h</code>
</p><pre class="screen">
/**
* 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;
</pre><p>
</p><p>
Here comes the meaning of each entry:
</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><code class="option">name</code> is the name of the mapper module, as provided in the init() call</li><li class="listitem"><code class="option">block</code> is a pointer to the mapper configuration entry as defined in <code class="filename">/etc/pam_pkcs11/pam_pkcs11.conf</code>, as provided int the init() call</li><li class="listitem"><code class="option">context</code> 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</li><li class="listitem"><code class="function">entries()</code> is the entry point to the mapper listing method</li><li class="listitem"><code class="function">finder()</code> is the entry point to the mapper login finder method</li><li class="listitem"><code class="function">matcher()</code> is the entry point to the mapper login matcher method </li><li class="listitem"><code class="function">entries()</code> is called when the mapper module is to be removed from mapper chain</li><li class="listitem"><code class="option">dbg_level</code> 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</li></ul></div><p>
Note that <code class="option">context</code> pointer is passed as <code class="function">void *</code> as there are no way to know how the programmer will use it
</p></div><div class="sect1" title="4.3. Comodity macros"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="id422151"></a>4.3. Comodity macros</h2></div></div></div><p>
Many of the mapper functions are repetitive. Many others are nonsense in some mappers. So the API provide several comodity macros, defined in <code class="filename">src/mappers/mapper.h</code>
</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><code class="option">_DEFAULT_MAPPER_FIND_ENTRIES</code> to serve as a replacement for <code class="function">entries()</code> listing method</li><li class="listitem"><code class="option">_DEFAULT_MAPPER_FIND_USER</code> to serve as a replacement for <code class="function">finder()</code> login mapper method</li><li class="listitem"><code class="option">_DEFAULT_MAPPER_MATCH_USER</code> to serve as a replacement for <code class="function">matcher()</code> login matching method</li><li class="listitem"><code class="option">_DEFAULT_MAPPER_END</code> to serve as a replacement for <code class="function">deinit()</code> de-initialization method</li><li class="listitem"><code class="option">_DEFAULT_MAPPER_INIT</code> to serve as a replacement for <code class="function">init()</code> initialization method</li></ul></div><p>
</p><p>
The only usefull one is _DEFAULT_MAPPER_END, but the other ones are provided for compile work-in-progress mappers
</p><p>
See the code, to provide you an idea of how to code real functions
</p></div><div class="sect1" title="4.4. Multifield mappers"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="id422231"></a>4.4. Multifield mappers</h2></div></div></div><p>
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:
</p><p>
</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem">You should provided one mapper entry for each mapper personality in the configuration file</li><li class="listitem">If the mapper is to be statically linked, you should also declare one entry for each personality in the <code class="filename">src/mappers/mapperlist.c</code> mapper list declaration file</li><li class="listitem"> The mapper loader will make as many calls to <code class="function">mapper_module_init()</code> 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</li><li class="listitem"> 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</li><li class="listitem"> If the above case is yours one, then you must define and create by mean of <code class="function">malloc()</code> an internal environment structure, and store it in the <code class="option">context</code> field of the returned <code class="function">mapper_module</code> structure. <span class="application">pam_pkcs11</span> will include this data in every calls to your entry points, to get sure you can retrieve correct internal data</li></ul></div><p>
</p></div><div class="sect1" title="4.5.  Configuration entries on static mappers"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="id422303"></a>4.5. Configuration entries on static mappers </h2></div></div></div><p>
As stated above, to specify that a mapper is not to be dynamically linked, we should remove the keyword "<code class="option">module</code>", or set it to "<code class="option">module = internal ;</code>"
</p><p>
Most of statically linked mappers share common configuration options:
</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><code class="option">module</code> Must be set to <code class="option">internal</code></li><li class="listitem"><code class="option">debug</code> The debug level. Defaults to <code class="option">false</code></li><li class="listitem"><code class="option">ignorecase</code> Ignore letter case on matching functions. Defaults to <code class="option">false</code></li><li class="listitem"><code class="option">mapfile</code> Mapping file to be used. Defaults to <code class="option">"none"</code></li></ul></div><p>
</p><p>
So if up to the system administrator, if agreed with default values, to ommit in the configuration file <code class="filename">/etc/pam_pkcs11/pam_pkcs11.conf</code> 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
</p><p>
Above note does not apply, of course, to dynamically loaded mappers, as they allways need at least the "<code class="option">module</code>" entry to be specified
</p><p>
See PAM-PKCS#11 Manual to see specific notes on provided mappers
</p></div></div><div class="chapter" title="Chapter 5. The Mapper API"><div class="titlepage"><div><div><h2 class="title"><a id="api"></a>Chapter 5. The Mapper API</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="sect1"><a href="#id422388">5.1. Debugging macros and functions</a></span></dt><dt><span class="sect1"><a href="#id422469">5.2. The mapfile API</a></span></dt><dt><span class="sect1"><a href="#id422592">5.3. Configuration parsing API</a></span></dt><dt><span class="sect1"><a href="#id422699">5.4. String tools API</a></span></dt><dt><span class="sect1"><a href="#id422843">5.5. BASE64 Encoding functions </a></span></dt><dt><span class="sect1"><a href="#id422877">5.6. X509 Cert Tools API</a></span></dt></dl></div><div class="sect1" title="5.1. Debugging macros and functions"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="id422388"></a>5.1. Debugging macros and functions</h2></div></div></div><p>
Several functions and macros are provided to generate and display debug and error messages. See files <code class="filename">src/common/debug.[ch]</code> and <code class="filename">src/common/error.[ch]</code>
</p><p>
</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><code class="function">void set_debug_level(int level);</code> Sets the debug level</li><li class="listitem"><code class="function">int get_debug_level(void);</code> Gets the debug level</li><li class="listitem"><code class="function">void debug_print(int level, char *file, int line, char *format, ...);</code> Prints a message if <code class="option">level</code> is greater than current debug level</li><li class="listitem"><code class="function">DBG(), DBG1(), ... DBG5()</code> Are shortcut macros to <code class="function">debug_print()</code> function</li><li class="listitem"><code class="function">void set_error(char *format, ...);</code> Sets the "last error" message entry</li><li class="listitem"><code class="function">const char *get_error();</code> Gets the last error message</li></ul></div><p>
</p></div><div class="sect1" title="5.2. The mapfile API"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="id422469"></a>5.2. The mapfile API</h2></div></div></div><p>
The mapper API provides several functions to manage mapfiles. They are declared in <code class="filename">src/mappers/mapper.h</code>
</p><p>
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 <code class="function">setpwent(), getpwent() and endpwent()</code> functions works in walking throught a password file
</p><p>
The mapfile structure is defined as:
</p><pre class="screen">
/*
* 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 */
};
</pre><p>
</p><p>
The API defines following functions:
</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><code class="function">struct mapfile *set_mapent(const char *uri);</code> Initializes mapfile data structure</li><li class="listitem"><code class="function">int get_mapent(struct mapfile *mfile);</code> Iterative calls returns next key/value pairs in mapfile</li><li class="listitem"><code class="function">void end_mapent(struct mapfile *mfile);</code> Closes and releases mapfile</li><li class="listitem"><code class="function">char *mapfile_find(const char *file,char *key,int ignorecase);</code> To find a given key/value pair in a mapfile</li><li class="listitem"><code class="function">int mapfile_match(const char *file,char *key,const char *value,int ignorecase);</code> To test if any entry on mapfile matches key/value pair</li></ul></div><p>
</p><p>
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 <code class="filename">/etc/pam_pkcs11/subject_mapping</code> or <code class="filename">file:///etc/pam_pkcs11/subject_mapping</code>. Our recommentation is to use second format as is not restricted to local files
</p><p>
<em class="lineannotation"><span class="lineannotation">NOTE:</span></em>
The returned "<code class="option">key</code>" and "<code class="option">value</code>" entries should be used as <code class="function">const char *</code>, that is, contents cannot be modified nor free()'d. If the programmer needs to modify these values, please make a copy with the <code class="function">clone_str()</code> API provided function
</p></div><div class="sect1" title="5.3.  Configuration parsing API"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="id422592"></a>5.3. Configuration parsing API</h2></div></div></div><p>
<span class="application">PAM-PKCS#11</span> configuration files are based in the SCConf library of the <span class="application">OpenSC</span> Project. See the file <code class="filename">src/scconf/README.scconf</code> for a detailed description of the <span class="application">scconf</span>
</p><p>
As a resume, bellow are shown the most relevants scconf API functions for the mapper programmer:
</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><code class="function">const char *scconf_get_str(const scconf_block * block, const char *option, const char *default); </code> To retrieve the string value assigned to keyword <code class="option">option</code> or return <code class="option">default</code> if keyword not found</li><li class="listitem"><code class="function">int scconf_get_int(const scconf_block * block, const char *option, int default); </code> To retrieve the integer value assigned to keyword <code class="option">option</code> or return <code class="option">default</code> if keyword not found</li><li class="listitem"><code class="function">int scconf_get_bool(const scconf_block * block, const char *option, int default); </code> To retrieve the boolean value assigned to keyword <code class="option">option</code> or return <code class="option">default</code> if keyword not found</li></ul></div><p>
</p><p>
With these functions, we can easily parse all "<code class="option">key = value;</code>" entries on the mapper configuration block of the configuration file
</p><p>
<em class="lineannotation"><span class="lineannotation">NOTE:</span></em>
The user should not modify nor free() values returned from <code class="function">scconf_get_str()</code>. Instead, call <code class="function">clone_str()</code> API method to get a working copy
</p></div><div class="sect1" title="5.4.  String tools API"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="id422699"></a>5.4. String tools API</h2></div></div></div><p>
The <code class="filename">string.h</code> standard library is so powerfull. But lacks on some usefull routines. The file <code class="filename">src/common/strings.c</code> contains some of them, as declared at <code class="filename">src/common/strings.h</code>
</p><p>
</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><code class="function"> int is_empty_str(const char *str);</code> Returns true if <code class="option">str</code> is null, empty, or has only spaces</li><li class="listitem"><code class="function"> char *clone_str(const char *str);</code> Returns a duplicate of provided string </li><li class="listitem"><code class="function"> char *toupper_str(const char *str);</code> Same as above, but string is upper-case'd</li><li class="listitem"><code class="function"> char *tolower_str(const char *str);</code> Same as above, but string is lower-case'd</li><li class="listitem"><code class="function"> char *bin2hex(const unsigned char *binstr,const int len);</code> Return a string that contains the hexadecimal representation of the provided binary array of given length. Returned format is :XX:YY:ZZ:...:</li><li class="listitem"><code class="function"> unsigned char *hex2bin(const char *hexstr);</code> Convert a colon-separated hexadecimal string into a binary array</li><li class="listitem"><code class="function"> unsigned char *hex2bin_static(const char *hexstr,unsigned char **res,int *size);</code> Same as above, but programmer supplies pre-allocated memory space for conversion</li><li class="listitem"><code class="function"> char **split(const char *str,char sep, int nelems);</code> Splits provided string in an string array of nelems elements, using sep as character separator</li><li class="listitem"><code class="function"> char **split_static(const char *str,char sep, int nelems,char *dst);</code> Same as above, but user provides pre-allocated buffer for storeing result</li><li class="listitem"><code class="function"> char *trim(const char *str);</code> Return an string that has all superfluous spaces trimmed. Also converts any space char ( newline, tabs, etc ) in normal " " space character</li></ul></div><p>
</p><p>
A note on <code class="function">split(), and split_static()</code> functions. To free allocated resources, is enought to call <code class="function">free()</code> on the first element of the array
</p><p>
Note that <code class="function">trim()</code> 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
</p><p>
See the code for further reference :-)
</p></div><div class="sect1" title="5.5.  BASE64 Encoding functions"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="id422843"></a>5.5. BASE64 Encoding functions </h2></div></div></div><p>
In order to read/write public SSH keys, two funtions are provided to manage base64 encoding:
</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><code class="function">int base64_encode(const unsigned char *in, size_t len, unsigned char *out, size_t outlen)</code> To encode a byte array into a base64 string</li><li class="listitem"><code class="function">int base64_decode(const char *in, unsigned char *out, size_t outlen)</code> To decode a base64 data into a byte array</li></ul></div><p>
</p><p>
See doxygen documentation and source code for more info
</p></div><div class="sect1" title="5.6.  X509 Cert Tools API"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="id422877"></a>5.6. X509 Cert Tools API</h2></div></div></div><p>
The mapper API provides several adittional tools to inspect the contents of a certificate. They are described in <code class="filename">src/common/cert_info.h</code>
</p><p>
The basic library call is:
</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><code class="function">char **cert_info(X509 *x509, int type, const char *algorithm);</code></li></ul></div><p>
</p><p>
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 <code class="option">algorithm</code> parameters. When not used should be set to NULL
</p><p>
The mapper API defines following macros:
</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><code class="option"> CERT_CN</code> Certificate Common Name</li><li class="listitem"><code class="option"> CERT_SUBJECT</code> Certificate subject</li><li class="listitem"><code class="option"> CERT_KPN</code> Kerberos principal name</li><li class="listitem"><code class="option"> CERT_EMAIL</code> Certificate e-mail</li><li class="listitem"><code class="option"> CERT_UPN</code> Microsoft's Universal Principal Name</li><li class="listitem"><code class="option"> CERT_UID</code> Certificate Unique Identifier</li><li class="listitem"><code class="option"> CERT_PUK</code> Certificate Public Key (PEM Format)</li><li class="listitem"><code class="option"> CERT_DIGEST</code> Certificate Digest</li><li class="listitem"><code class="option"> CERT_SSHPUK</code> Certificate Public key in OpenSSH format</li><li class="listitem"><code class="option"> CERT_PEM</code> Certificate in PEM format</li></ul></div><p>
</p><p>
Aditionally, when requesting <code class="option">CERT_DIGEST</code> you must provide a valid digest algorithm: "<code class="option">null</code>", "<code class="option">md2</code>", "<code class="option">md4</code>", "<code class="option">md5</code>", "<code class="option">sha</code>", "<code class="option">sha1</code>", "<code class="option">dss</code>", "<code class="option">dss1</code>" or "<code class="option">ripemd160</code>"
</p><p>
<code class="function">cert_info()</code> 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;
</p><p>
If some error ocurrs, or the certificate does not contain any entry, return NULL
</p><p>
There are two additional methods to check certificate/signatures:
</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><code class="function">int verify_certificate(X509 * x509, char *ca_dir, char *crl_dir, crl_policy_t policy);</code> To check a certificate</li><li class="listitem"><code class="function">int verify_signature(X509 * x509, unsigned char *data, int data_length, unsigned char *signature, int signature_length);</code> To verify a signature</li></ul></div><p>
</p></div></div><div class="chapter" title="Chapter 6. Going further"><div class="titlepage"><div><div><h2 class="title"><a id="more"></a>Chapter 6. Going further</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="sect1"><a href="#id423055">6.1. Hints</a></span></dt><dt><span class="sect1"><a href="#id423093">6.2. Getting help</a></span></dt></dl></div><div class="sect1" title="6.1. Hints"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="id423055"></a>6.1. Hints</h2></div></div></div><p>
It's really recommended the study of provided mappers, and the comodity macros
</p><p>
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
</p><p>
Don't hessitate in use of debugging functions. They are really usefull
</p><p>
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
</p><p>
Avoid write access to any global variable from the mapper code. Use comodity functions
</p><p>
Don't make assumptions on the code. Allways add checks.
</p><p>
Use Universal Resource Locators -and the curl library- instead of hardcoded pathnames to specify files
</p></div><div class="sect1" title="6.2. Getting help"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="id423093"></a>6.2. Getting help</h2></div></div></div><p>
Send questions, patches, suggestions and so to OpenSC Mailing list: <code class="email"><<a class="email" href="mailto:opensc-devel at opensc-project.org">opensc-devel at opensc-project.org</a>></code>
</p><p>
For additional specific info, contact with the authors:
</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem">
Juan Antonio Martinez <code class="email"><<a class="email" href="mailto:jonsito at teleline.es">jonsito at teleline.es</a>></code></li><li class="listitem">
Mario Strasser <code class="email"><<a class="email" href="mailto:mast at gmx.net">mast at gmx.net</a>></code></li><li class="listitem">
Ludovic Rousseau <code class="email"><<a class="email" href="mailto:ludovic.rousseau at free.fr ">ludovic.rousseau at free.fr </a>></code></li></ul></div><p>
</p></div></div></div></body></html>
