1
1
<?xml version="1.0" encoding="UTF-8"?>
2
2
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
3
<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="#id422209">2.1. Definition</a></span></dt><dt><span class="sect1"><a href="#id391384">2.2. Runtime options</a></span></dt><dt><span class="sect1"><a href="#id391419">2.3. Multiple mapping support</a></span></dt><dt><span class="sect1"><a href="#id391480">2.4. Mapfile support</a></span></dt><dt><span class="sect1"><a href="#id391491">2.5. Mapper tools and libraries</a></span></dt><dt><span class="sect1"><a href="#id391527">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="#id391554">3.1. Before starting</a></span></dt><dt><span class="sect1"><a href="#id391598">3.2. Sample mapper configuration entry</a></span></dt><dt><span class="sect1"><a href="#id391660">3.3. Sample mapper include file</a></span></dt><dt><span class="sect1"><a href="#id430726">3.4. Skeleton code for mapper C file.</a></span></dt><dt><span class="sect1"><a href="#id430839">3.5. Insert mapper into tables</a></span></dt><dt><span class="sect1"><a href="#id430876">3.6. Adding mapper to Makefile.am to be compiled</a></span></dt><dt><span class="sect1"><a href="#id430949">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="#id430973">4.1. The mapper chain</a></span></dt><dt><span class="sect1"><a href="#id431079">4.2. Exported data and structures</a></span></dt><dt><span class="sect1"><a href="#id431187">4.3. Comodity macros</a></span></dt><dt><span class="sect1"><a href="#id431267">4.4. Multifield mappers</a></span></dt><dt><span class="sect1"><a href="#id431339">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="#id431425">5.1. Debugging macros and functions</a></span></dt><dt><span class="sect1"><a href="#id431505">5.2. The mapfile API</a></span></dt><dt><span class="sect1"><a href="#id431628">5.3. Configuration parsing API</a></span></dt><dt><span class="sect1"><a href="#id431735">5.4. String tools API</a></span></dt><dt><span class="sect1"><a href="#id431879">5.5. BASE64 Encoding functions </a></span></dt><dt><span class="sect1"><a href="#id431913">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="#id432091">6.1. Hints</a></span></dt><dt><span class="sect1"><a href="#id432129">6.2. Getting help</a></span></dt></dl></dd></dl></div><div class="abstract" title="Abstract"><p class="title"><b>Abstract</b></p><p>
3
<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="#id322532">2.1. Definition</a></span></dt><dt><span class="sect1"><a href="#id291706">2.2. Runtime options</a></span></dt><dt><span class="sect1"><a href="#id291784">2.3. Multiple mapping support</a></span></dt><dt><span class="sect1"><a href="#id291797">2.4. Mapfile support</a></span></dt><dt><span class="sect1"><a href="#id291808">2.5. Mapper tools and libraries</a></span></dt><dt><span class="sect1"><a href="#id291844">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="#id291871">3.1. Before starting</a></span></dt><dt><span class="sect1"><a href="#id291915">3.2. Sample mapper configuration entry</a></span></dt><dt><span class="sect1"><a href="#id291977">3.3. Sample mapper include file</a></span></dt><dt><span class="sect1"><a href="#id331045">3.4. Skeleton code for mapper C file.</a></span></dt><dt><span class="sect1"><a href="#id331159">3.5. Insert mapper into tables</a></span></dt><dt><span class="sect1"><a href="#id331194">3.6. Adding mapper to Makefile.am to be compiled</a></span></dt><dt><span class="sect1"><a href="#id331267">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="#id331292">4.1. The mapper chain</a></span></dt><dt><span class="sect1"><a href="#id331397">4.2. Exported data and structures</a></span></dt><dt><span class="sect1"><a href="#id331506">4.3. Comodity macros</a></span></dt><dt><span class="sect1"><a href="#id331586">4.4. Multifield mappers</a></span></dt><dt><span class="sect1"><a href="#id331658">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="#id331743">5.1. Debugging macros and functions</a></span></dt><dt><span class="sect1"><a href="#id331824">5.2. The mapfile API</a></span></dt><dt><span class="sect1"><a href="#id331947">5.3. Configuration parsing API</a></span></dt><dt><span class="sect1"><a href="#id332054">5.4. String tools API</a></span></dt><dt><span class="sect1"><a href="#id332198">5.5. BASE64 Encoding functions </a></span></dt><dt><span class="sect1"><a href="#id332232">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="#id332410">6.1. Hints</a></span></dt><dt><span class="sect1"><a href="#id332448">6.2. Getting help</a></span></dt></dl></dd></dl></div><div class="abstract" title="Abstract"><p class="title"><b>Abstract</b></p><p>
4
4
<span class="application">PAM-PKCS#11</span> is a PAM (Pluggable
5
5
Authentication Module) library and related tools to perform login into
6
6
Linux/UNIX systems by mean of X509 Certificates through any pkcs#11
31
31
You should have received a copy of the GNU Lesser General Public
32
32
License along with this library; if not, write to the Free Software
33
33
Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
34
</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="#id422209">2.1. Definition</a></span></dt><dt><span class="sect1"><a href="#id391384">2.2. Runtime options</a></span></dt><dt><span class="sect1"><a href="#id391419">2.3. Multiple mapping support</a></span></dt><dt><span class="sect1"><a href="#id391480">2.4. Mapfile support</a></span></dt><dt><span class="sect1"><a href="#id391491">2.5. Mapper tools and libraries</a></span></dt><dt><span class="sect1"><a href="#id391527">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="id422209"></a>2.1. Definition</h2></div></div></div><p>
34
</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="#id322532">2.1. Definition</a></span></dt><dt><span class="sect1"><a href="#id291706">2.2. Runtime options</a></span></dt><dt><span class="sect1"><a href="#id291784">2.3. Multiple mapping support</a></span></dt><dt><span class="sect1"><a href="#id291797">2.4. Mapfile support</a></span></dt><dt><span class="sect1"><a href="#id291808">2.5. Mapper tools and libraries</a></span></dt><dt><span class="sect1"><a href="#id291844">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="id322532"></a>2.1. Definition</h2></div></div></div><p>
35
35
When an X509 Certificate is provided, there are no direct way to map
36
36
a cert to a login. With a certificate we can check validity and
37
37
revocation, but user mapping depends entirely on the certificate content.
42
42
pam-pkcs11 cert mappers should provide these functions:
43
43
</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>
44
</p></div><div class="sect1" title="2.2. Runtime options"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="id391384"></a>2.2. Runtime options</h2></div></div></div><p>
44
</p></div><div class="sect1" title="2.2. Runtime options"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="id291706"></a>2.2. Runtime options</h2></div></div></div><p>
45
45
A mapper can be dinamycally or statically compiled against <span class="application">pam_pkcs11</span>
47
47
</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
48
48
the dynamic module must be provided</li></ul></div><p>
49
</p></div><div class="sect1" title="2.3. Multiple mapping support"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="id391419"></a>2.3. Multiple mapping support</h2></div></div></div><p>
49
</p></div><div class="sect1" title="2.3. Multiple mapping support"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="id291784"></a>2.3. Multiple mapping support</h2></div></div></div><p>
50
50
A mapper can provide several ways to realize mapping functions. As
51
51
the mapper name is provided to initialization routines, the mapper
52
52
cand adjust their internal pointers according name. In this case,
53
53
the same mapper will be instantiated (or dynloaded) as many times
54
54
as different mappings required
55
</p></div><div class="sect1" title="2.4. Mapfile support"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="id391480"></a>2.4. Mapfile support</h2></div></div></div><p>
55
</p></div><div class="sect1" title="2.4. Mapfile support"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="id291797"></a>2.4. Mapfile support</h2></div></div></div><p>
56
56
Most of certificate fields are not valid for login names. We need
57
57
a way to map field to login. This is done by mean of mapfiles.
58
58
The mapper API provides several functions to manage mapfiles
59
</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="id391491"></a>2.5. Mapper tools and libraries</h2></div></div></div><p>
59
</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="id291808"></a>2.5. Mapper tools and libraries</h2></div></div></div><p>
60
60
Pam_pkcs11 provides several utility functions to manage certificate
61
61
contents. Instead of start from scratch these functions may be used
62
62
to ease mapper coding. You'll find:
63
63
</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>
64
</p></div><div class="sect1" title="2.6. Configuration support"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="id391527"></a>2.6. Configuration support</h2></div></div></div><p>
64
</p></div><div class="sect1" title="2.6. Configuration support"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="id291844"></a>2.6. Configuration support</h2></div></div></div><p>
65
65
Althought all mappers have default values, most of then have
66
66
configuration options. The file <code class="filename">/etc/pam_pkcs11/pam_pkcs11.conf</code>
68
</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="#id391554">3.1. Before starting</a></span></dt><dt><span class="sect1"><a href="#id391598">3.2. Sample mapper configuration entry</a></span></dt><dt><span class="sect1"><a href="#id391660">3.3. Sample mapper include file</a></span></dt><dt><span class="sect1"><a href="#id430726">3.4. Skeleton code for mapper C file.</a></span></dt><dt><span class="sect1"><a href="#id430839">3.5. Insert mapper into tables</a></span></dt><dt><span class="sect1"><a href="#id430876">3.6. Adding mapper to Makefile.am to be compiled</a></span></dt><dt><span class="sect1"><a href="#id430949">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="id391554"></a>3.1. Before starting</h2></div></div></div><p>
68
</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="#id291871">3.1. Before starting</a></span></dt><dt><span class="sect1"><a href="#id291915">3.2. Sample mapper configuration entry</a></span></dt><dt><span class="sect1"><a href="#id291977">3.3. Sample mapper include file</a></span></dt><dt><span class="sect1"><a href="#id331045">3.4. Skeleton code for mapper C file.</a></span></dt><dt><span class="sect1"><a href="#id331159">3.5. Insert mapper into tables</a></span></dt><dt><span class="sect1"><a href="#id331194">3.6. Adding mapper to Makefile.am to be compiled</a></span></dt><dt><span class="sect1"><a href="#id331267">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="id291871"></a>3.1. Before starting</h2></div></div></div><p>
69
69
</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem">Decide if the mapper will be statically or dinamically compiled
70
70
The first way is for simple, quick and easy mappers that doesn't need
71
71
aditional/optional libraries, just inspect certificate contents.
74
74
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>
76
76
The best way to start is by mean of these skeleton files:
77
</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="id391598"></a>3.2. Sample mapper configuration entry</h2></div></div></div><p>
77
</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="id291915"></a>3.2. Sample mapper configuration entry</h2></div></div></div><p>
78
78
All mappers should have a configuration entry in <code class="filename">/etc/pam_pkcs11/pam_pkcs11.conf</code>. These entry should at least define:
79
79
</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>
80
80
</p><pre class="screen">
98
98
See bellow on how to set up code to include multiple fields mappers to be
99
99
statically compiled
100
</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="id391660"></a>3.3. Sample mapper include file</h2></div></div></div><p>
100
</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="id291977"></a>3.3. Sample mapper include file</h2></div></div></div><p>
101
101
Here comes a sample mapper include file. Note that their main use is to
102
102
allow export internal data when statically compiled. Unless you need several
103
103
files to define a mapper, no need of more data to be included
159
159
/* End of foo_mapper.h */
162
</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="id430726"></a>3.4. Skeleton code for mapper C file.</h2></div></div></div><p>
162
</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="id331045"></a>3.4. Skeleton code for mapper C file.</h2></div></div></div><p>
163
163
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.
165
165
They only need to export one symbol: the entry point of the init routine
323
323
See bellow on what's each function is intended to do, comodity macros,
324
324
and some examples on how to code them
325
</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="id430839"></a>3.5. Insert mapper into tables</h2></div></div></div><p>
325
</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="id331159"></a>3.5. Insert mapper into tables</h2></div></div></div><p>
326
326
Next task is insert mapper into mappers list, by adding it to mapperlist.c
327
327
</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>
345
345
As you can see, if your module support several mapping schemes, you should
346
346
insert one entry for each one. All the entries will share the same entry
347
347
point, but differs in module name
348
</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="id430876"></a>3.6. Adding mapper to Makefile.am to be compiled</h2></div></div></div><p>
348
</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="id331194"></a>3.6. Adding mapper to Makefile.am to be compiled</h2></div></div></div><p>
349
349
Finally add entry to <code class="filename">src/mappers/Makefile.am</code> file and recompile.
350
350
Note that with the current <span class="application">pam_pkcs11</span> version you cannot compile
351
351
a dynamically loaded mapper in a separate way. This is a job in progress
401
401
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
403
403
If, for any reason, the mapper loading process, a warn is sent, and the mapper entry module is skipped
404
</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="id431079"></a>4.2. Exported data and structures</h2></div></div></div><p>
404
</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="id331397"></a>4.2. Exported data and structures</h2></div></div></div><p>
405
405
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>
406
406
</p><pre class="screen">
422
422
Here comes the meaning of each entry:
423
423
</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>
424
424
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
425
</p></div><div class="sect1" title="4.3. Comodity macros"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="id431187"></a>4.3. Comodity macros</h2></div></div></div><p>
425
</p></div><div class="sect1" title="4.3. Comodity macros"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="id331506"></a>4.3. Comodity macros</h2></div></div></div><p>
426
426
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>
427
427
</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>
429
429
The only usefull one is _DEFAULT_MAPPER_END, but the other ones are provided for compile work-in-progress mappers
431
431
See the code, to provide you an idea of how to code real functions
432
</p></div><div class="sect1" title="4.4. Multifield mappers"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="id431267"></a>4.4. Multifield mappers</h2></div></div></div><p>
432
</p></div><div class="sect1" title="4.4. Multifield mappers"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="id331586"></a>4.4. Multifield mappers</h2></div></div></div><p>
433
433
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:
435
435
</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:
436
436
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>
437
</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="id431339"></a>4.5. Configuration entries on static mappers </h2></div></div></div><p>
437
</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="id331658"></a>4.5. Configuration entries on static mappers </h2></div></div></div><p>
438
438
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>"
440
440
Most of statically linked mappers share common configuration options:
445
445
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
447
447
See PAM-PKCS#11 Manual to see specific notes on provided mappers
448
</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="#id431425">5.1. Debugging macros and functions</a></span></dt><dt><span class="sect1"><a href="#id431505">5.2. The mapfile API</a></span></dt><dt><span class="sect1"><a href="#id431628">5.3. Configuration parsing API</a></span></dt><dt><span class="sect1"><a href="#id431735">5.4. String tools API</a></span></dt><dt><span class="sect1"><a href="#id431879">5.5. BASE64 Encoding functions </a></span></dt><dt><span class="sect1"><a href="#id431913">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="id431425"></a>5.1. Debugging macros and functions</h2></div></div></div><p>
448
</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="#id331743">5.1. Debugging macros and functions</a></span></dt><dt><span class="sect1"><a href="#id331824">5.2. The mapfile API</a></span></dt><dt><span class="sect1"><a href="#id331947">5.3. Configuration parsing API</a></span></dt><dt><span class="sect1"><a href="#id332054">5.4. String tools API</a></span></dt><dt><span class="sect1"><a href="#id332198">5.5. BASE64 Encoding functions </a></span></dt><dt><span class="sect1"><a href="#id332232">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="id331743"></a>5.1. Debugging macros and functions</h2></div></div></div><p>
449
449
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>
451
451
</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>
452
</p></div><div class="sect1" title="5.2. The mapfile API"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="id431505"></a>5.2. The mapfile API</h2></div></div></div><p>
452
</p></div><div class="sect1" title="5.2. The mapfile API"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="id331824"></a>5.2. The mapfile API</h2></div></div></div><p>
453
453
The mapper API provides several functions to manage mapfiles. They are declared in <code class="filename">src/mappers/mapper.h</code>
455
455
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
478
478
<em class="lineannotation"><span class="lineannotation">NOTE:</span></em>
479
479
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
480
</p></div><div class="sect1" title="5.3. Configuration parsing API"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="id431628"></a>5.3. Configuration parsing API</h2></div></div></div><p>
480
</p></div><div class="sect1" title="5.3. Configuration parsing API"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="id331947"></a>5.3. Configuration parsing API</h2></div></div></div><p>
481
481
<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>
483
483
As a resume, bellow are shown the most relevants scconf API functions for the mapper programmer:
488
488
<em class="lineannotation"><span class="lineannotation">NOTE:</span></em>
489
489
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
490
</p></div><div class="sect1" title="5.4. String tools API"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="id431735"></a>5.4. String tools API</h2></div></div></div><p>
490
</p></div><div class="sect1" title="5.4. String tools API"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="id332054"></a>5.4. String tools API</h2></div></div></div><p>
491
491
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>
493
493
</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>
497
497
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
499
499
See the code for further reference :-)
500
</p></div><div class="sect1" title="5.5. BASE64 Encoding functions"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="id431879"></a>5.5. BASE64 Encoding functions </h2></div></div></div><p>
500
</p></div><div class="sect1" title="5.5. BASE64 Encoding functions"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="id332198"></a>5.5. BASE64 Encoding functions </h2></div></div></div><p>
501
501
In order to read/write public SSH keys, two funtions are provided to manage base64 encoding:
502
502
</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>
504
504
See doxygen documentation and source code for more info
505
</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="id431913"></a>5.6. X509 Cert Tools API</h2></div></div></div><p>
505
</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="id332232"></a>5.6. X509 Cert Tools API</h2></div></div></div><p>
506
506
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>
508
508
The basic library call is:
522
522
There are two additional methods to check certificate/signatures:
523
523
</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>
525
</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="#id432091">6.1. Hints</a></span></dt><dt><span class="sect1"><a href="#id432129">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="id432091"></a>6.1. Hints</h2></div></div></div><p>
525
</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="#id332410">6.1. Hints</a></span></dt><dt><span class="sect1"><a href="#id332448">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="id332410"></a>6.1. Hints</h2></div></div></div><p>
526
526
It's really recommended the study of provided mappers, and the comodity macros
528
528
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
537
537
Don't make assumptions on the code. Allways add checks.
539
539
Use Universal Resource Locators -and the curl library- instead of hardcoded pathnames to specify files
540
</p></div><div class="sect1" title="6.2. Getting help"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="id432129"></a>6.2. Getting help</h2></div></div></div><p>
540
</p></div><div class="sect1" title="6.2. Getting help"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="id332448"></a>6.2. Getting help</h2></div></div></div><p>
541
541
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>
543
543
For additional specific info, contact with the authors:
added
removed
doc/mappers_api.html
