<?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 User Manual</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 User Manual"><div class="titlepage"><div><div><h1 class="title"><a id="pam-pkcs11"></a>PAM-PKCS11 User Manual</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><div class="author"><h3 class="author"><span class="firstname">Mario</span> <span class="surname">Strasser</span></h3><code class="email"><<a class="email" href="mailto:mstt@gmx.net">mstt@gmx.net</a>></code></div></div><div><div class="author"><h3 class="author"><span class="firstname">Antti</span> <span class="surname">Tapaninen</span></h3><code class="email"><<a class="email" href="mailto:aet@cc.hut.fi">aet@cc.hut.fi</a>></code></div></div><div><div class="author"><h3 class="author"><span class="firstname">Timo</span> <span class="surname">Sirainen</span></h3><code class="email"><<a class="email" href="mailto:tss@iki.fi">tss@iki.fi</a>></code></div></div><div><div class="author"><h3 class="author"><span class="firstname">Ludovic</span> <span class="surname">Rousseau</span></h3><code class="email"><<a class="email" href="mailto:ludovic.rousseau@free.fr">ludovic.rousseau@free.fr</a>></code></div></div><div><p class="releaseinfo">Release 0.5beta2, 27 Sep 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. Introduction</a></span></dt><dt><span class="chapter"><a href="#basics">3. Fundamentals</a></span></dt><dd><dl><dt><span class="sect1"><a href="#id333600">3.1. PKCS #11 Module Requirements</a></span></dt><dt><span class="sect1"><a href="#id333616">3.2. User Matching</a></span></dt></dl></dd><dt><span class="chapter"><a href="#install">4. Installation</a></span></dt><dt><span class="chapter"><a href="#configfile">5. Configuring pam-pkcs11</a></span></dt><dd><dl><dt><span class="sect1"><a href="#id372910">5.1. Setting up Configuration file</a></span></dt><dt><span class="sect1"><a href="#id372962">5.2. Setting up CRL's and CA's lists</a></span></dt><dt><span class="sect1"><a href="#id373042">5.3. Create map files</a></span></dt></dl></dd><dt><span class="chapter"><a href="#pamconfig">6. PAM Configuration</a></span></dt><dd><dl><dt><span class="sect1"><a href="#id373086">6.1. Configuring pam.d files</a></span></dt><dt><span class="sect1"><a href="#id373371">6.2. Sample pam.d/ entries</a></span></dt></dl></dd><dt><span class="chapter"><a href="#autologin">7. Using Login auto-detect features</a></span></dt><dt><span class="chapter"><a href="#eventmgr">8. Using the Event Manager Tools</a></span></dt><dd><dl><dt><span class="sect1"><a href="#id373654">8.1. Using the Card Event Manager</a></span></dt><dd><dl><dt><span class="sect2"><a href="#id373710">8.1.1. Structure of configuration file</a></span></dt></dl></dd><dt><span class="sect1"><a href="#id373733">8.2. Using the PKCS#11 Event Manager</a></span></dt><dt><span class="sect1"><a href="#id373847">8.3. Security issues</a></span></dt><dt><span class="sect1"><a href="#id373873">8.4. Example: use xscreensaver to lock screen on card removal</a></span></dt></dl></dd><dt><span class="chapter"><a href="#loginfinder">9. Using the Login Finder Tool</a></span></dt><dt><span class="chapter"><a href="#pkcs11_inspect">10. Using the PKCS#11 CertInspect tool</a></span></dt><dt><span class="chapter"><a href="#HOWTO">11. HOWTO install pam_pkcs11</a></span></dt><dd><dl><dt><span class="sect1"><a href="#id374146">11.1. Install the software </a></span></dt><dt><span class="sect1"><a href="#id374166">11.2. Configure pam_pkcs11 </a></span></dt><dd><dl><dt><span class="sect2"><a href="#id374171">11.2.1. Create the needed directories </a></span></dt><dt><span class="sect2"><a href="#id374192">11.2.2. Copy and install the root CA certificate </a></span></dt><dt><span class="sect2"><a href="#id374226">11.2.3. Configure pam_pkcs11 </a></span></dt><dt><span class="sect2"><a href="#id374257">11.2.4. Configure the subject mapper </a></span></dt></dl></dd><dt><span class="sect1"><a href="#id374314">11.3. Install and test your PAM configuration </a></span></dt><dt><span class="sect1"><a href="#id374420">11.4. Secure your PAM configuration </a></span></dt><dt><span class="sect1"><a href="#id374448">11.5. Using card_eventmgr </a></span></dt><dd><dl><dt><span class="sect2"><a href="#id374464">11.5.1. Configuring and testing card_eventmgr </a></span></dt><dt><span class="sect2"><a href="#id374506">11.5.2. Starting card_eventmgr </a></span></dt></dl></dd></dl></dd><dt><span class="chapter"><a href="#mappers">12. What is a cert mapper?</a></span></dt><dd><dl><dt><span class="sect1"><a href="#fundamentals">12.1. Fundamentals </a></span></dt><dt><span class="sect1"><a href="#mapper_impl">12.2. Implementation of cert mappers in pam-pkcs11</a></span></dt><dt><span class="sect1"><a href="#mapfiles">12.3. How to use mapfiles</a></span></dt><dt><span class="sect1"><a href="#mapperlist">12.4. Mappers provided by Pam-pkcs11</a></span></dt><dd><dl><dt><span class="sect2"><a href="#id374780">12.4.1. Common Name (CN) mapper</a></span></dt><dt><span class="sect2"><a href="#id374822">12.4.2. Subject mapper</a></span></dt><dt><span class="sect2"><a href="#id374879">12.4.3. Getpwent() CN to login mapper</a></span></dt><dt><span class="sect2"><a href="#id374966">12.4.4. LDAP (lightweight directory access protocol) mapper</a></span></dt><dt><span class="sect2"><a href="#id375241">12.4.5. OpenSC library mapper</a></span></dt><dt><span class="sect2"><a href="#id375261">12.4.6. OpenSSH library mapper</a></span></dt><dt><span class="sect2"><a href="#id375335">12.4.7. Email Cert to login mapper</a></span></dt><dt><span class="sect2"><a href="#id375426">12.4.8. Microsoft Universal Principal Name mapper</a></span></dt><dt><span class="sect2"><a href="#id375478">12.4.9. Kerberos mapper</a></span></dt><dt><span class="sect2"><a href="#id375540">12.4.10. Unique ID to login mapper</a></span></dt><dt><span class="sect2"><a href="#id375572">12.4.11. Certificate Digest to login mapper</a></span></dt><dt><span class="sect2"><a href="#id375613">12.4.12. Generic mapper</a></span></dt><dt><span class="sect2"><a href="#id375750">12.4.13. Null mapper</a></span></dt></dl></dd><dt><span class="sect1"><a href="#id375830">12.5. Adding new mappers</a></span></dt></dl></dd><dt><span class="chapter"><a href="#todo">13. Wish list</a></span></dt><dt><span class="chapter"><a href="#contact">14. Contact</a></span></dt></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 compile, install, configure and use
<span class="application">pam-pkcs11</span> PAM module and related tools.
</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>
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. Introduction"><div class="titlepage"><div><div><h2 class="title"><a id="introduction"></a>Chapter 2. Introduction</h2></div></div></div><p>
<span class="application">pam_pkcs11</span> is a set of libraries and tools
to controls the login process using a PKCS#11 token.
</p><p>
The Linux-PAM login module allows a X.509 certificate based user
login. The certificate and its dedicated private key are thereby
accessed by means of an appropriate PKCS #11 module. For the
verification of the users' certificates, locally stored CA
certificates as well as either online or locally accessible CRLs are
used.
</p><p>
<span class="application">pkcs11_eventmgr</span> is a tool to execute commands
at insert or removal of a smart card from the reader. Alternatively, you can
use the <a class="ulink" href="http://pcsclite.alioth.debian.org/" target="_top">pcsc-lite</a>'s
based version: <span class="application">card_eventmgr</span>.
</p><p>
<span class="application">pkcs11_inspect</span> tool allows you to look at the
content of a certificate, in order to help you in the process of
Certificate-to-User mapping configuration.
</p><p>
<span class="application">pklogin_finder</span> tool can be used to check the
PAM module without need to do the entire login process, just verifying
that login names are properly found and matched.
</p><p>
Detailed information about the Linux-PAM system can be found in <a class="ulink" href="http://www.kernel.org/pub/linux/libs/pam/Linux-PAM-html/pam.html" target="_top">The
Linux-PAM System Administrators' Guide</a>, <a class="ulink" href="http://www.kernel.org/pub/linux/libs/pam/Linux-PAM-html/pam_modules.html" target="_top">The
Linux-PAM Module Writers' Guide</a> and <a class="ulink" href="http://www.kernel.org/pub/linux/libs/pam/Linux-PAM-html/pam_appl.html" target="_top">The
Linux-PAM Application Developers' Guide</a>.
</p><p>
The specification of the Cryptographic Token Interface Standard (PKCS
#11) is available at <a class="ulink" href="http://www.rsasecurity.com/rsalabs/pkcs/pkcs-11/" target="_top">PKCS #11 -
Cryptographic Token Interface Standard</a>.
</p></div><div class="chapter" title="Chapter 3. Fundamentals"><div class="titlepage"><div><div><h2 class="title"><a id="basics"></a>Chapter 3. Fundamentals</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="sect1"><a href="#id333600">3.1. PKCS #11 Module Requirements</a></span></dt><dt><span class="sect1"><a href="#id333616">3.2. User Matching</a></span></dt></dl></div><p>
<span class="application">Pam-pkcs11</span> is a PAM (Pluggable Authentication
Module) pluggin to allow logging into a UNIX/Linux System that supports
PAM by mean of use Digital Certificates stored in a smart card.
</p><p>
To do this, a PKCS #11 library is needed to access the Cards. Details
on how certificates are stored/retrieved, etc are hidden to pam-pkcs11
and handled by PKCS #11 library. This allows independence of the module
from a specific card.
</p><div class="sect1" title="3.1. PKCS #11 Module Requirements"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="id333600"></a>3.1. PKCS #11 Module Requirements</h2></div></div></div><p>
The PKCS #11 modules must full-fit the requirements given by the RSA
Asymmetric Client Signing Profile, which has been specified in the
<a class="ulink" href="http://www.rsasecurity.com/rsalabs/pkcs/pkcs-11/" target="_top">PKCS #11:
Conformance Profile Specification</a> by RSA Laboratories.
</p></div><div class="sect1" title="3.2. User Matching"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="id333616"></a>3.2. User Matching</h2></div></div></div><p>
To approve the ownership of a certificate, that is, to allow the owner
of a certificate to login as a particular user, pam-pkcs11 uses several
modules called <code class="systemitem">mappers</code> that perform
cert-to-login mapping. See <a class="xref" href="#mappers" title="Chapter 12. What is a cert mapper?">Chapter 12, <i>What is a cert mapper?</i></a>
section.
</p><p>
[Note: This is still a work in progress, any suggestions for
improvements or alternative matching algorithms are welcome.]
</p></div></div><div class="chapter" title="Chapter 4. Installation"><div class="titlepage"><div><div><h2 class="title"><a id="install"></a>Chapter 4. Installation</h2></div></div></div><p>
</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem">Download source code from the <a class="ulink" href="http://www.opensc-project.org/pam_pkcs11/" target="_top">official
site</a>.
</li><li class="listitem">Unpack source tarball:
<pre class="screen">
<strong class="userinput"><code>tar xvzf pam_pkcs11-X.Y.Z.tar.gz
cd pam_pkcs11-X.Y.Z</code></strong>
</pre></li><li class="listitem">If using SVN tree, re-create environment:
<pre class="screen">
<strong class="userinput"><code>./bootstrap</code></strong>
</pre></li><li class="listitem">Execute the "standard" install sequence :-)
<pre class="screen">
<strong class="userinput"><code>./configure
make
make install</code></strong>
</pre></li><li class="listitem"> Alternatively, on RedHat Linux systems, you can use
rpmbuild tools and the provided <code class="filename">.spec</code> file to
create and install RPM packages:
<pre class="screen">
<strong class="userinput"><code>rpmbuild -ta /path/to/pam_pkcs11.X.Y.tar.gz
rpm -v -i /usr/src/redhat/RPMS/i386/pam_pkcs11-X.Y-Z.i386.rpm
rpm -v -i /usr/src/redhat/RPMS/i386/pam_pkcs11-tools-X.Y-Z.i386.rpm</code></strong>
</pre></li><li class="listitem"> Configure package:
<div class="orderedlist"><ol class="orderedlist" type="a"><li class="listitem"> Create the base configuration directory: <code class="filename">/etc/pam_pkcs11/</code></li><li class="listitem"> Copy
<code class="filename">${base}/etc/pam_pkcs11.conf.example</code> to
<code class="filename">/etc/pam_pkcs11/</code>, rename it
to <code class="filename">/etc/pam_pkcs11/pam_pkcs11.conf</code> and
personalize it</li><li class="listitem"> Create <code class="filename">/etc/pam_pkcs11/crls/</code> and <code class="filename">/etc/pam_pkcs11/cacerts/</code> directories
corresponding to the configuration file, and fill them with proper
data. The <code class="filename">tools/</code> directory
provides a tool <span class="application">make_hash_link</span> that can
be used to create hash files on every valid Cert and CRL
file.</li><li class="listitem"> Choose one or more mappers to install, set up
configuration file, and if needed configure mappers. File
<code class="filename">/etc/pam_pkcs11.conf</code> is documented to
allow an easy editing </li><li class="listitem"> Edit and configure <code class="filename">/etc/pam.d/xxx</code>
entries. See instructions bellow</li><li class="listitem">Use <span class="application">pkcs11_inspect</span> and
<span class="application">pklogin_finder</span> provided tools to see if
you can read certificate data and perform correct user
mapping</li><li class="listitem">Try to log in. For instance, switch to a new tty
console</li></ol></div></li><li class="listitem">If things go wrong:
<div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"> Ensure that the PKCS #11 library works properly. You can,
for instance, try to use the PKCS #11 module as an engine for
<span class="application">OpenSSL</span> or
<span class="application">Mozilla/Firefox</span></li><li class="listitem"> Re-check the configuration</li><li class="listitem"> If a mapping file is used, check it. There are some known
problems on some certificates that uses obscure character encodings
(non utf-8), that makes CN mappings fail</li></ul></div></li></ol></div><p>
</p><p>
<em class="lineannotation"><span class="lineannotation">NOTES</span></em>
</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem">To avoid locking the computer, it is recommended to try to
configure only one non-critical service the first time (e.g.
<code class="filename">/etc/pam.d/xscreensaver</code>), and allow normal
login on the other services
(<code class="filename">/etc/pam.d/gdm</code>).</li><li class="listitem">PAM modules used for remote authentication (e.g.
<code class="filename">/etc/pam.d/sshd</code>) cannot be used with
pam-pkcs11 since there is no local smart card on the server. To do
remote logging, you should use a kind of Single Sign On (SSO)
service (Kerberos, winbind, etc.) and authenticate against a local
(client) smart card. This is a job in progress.</li></ul></div><p>
</p></div><div class="chapter" title="Chapter 5.  Configuring pam-pkcs11"><div class="titlepage"><div><div><h2 class="title"><a id="configfile"></a>Chapter 5. Configuring pam-pkcs11</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="sect1"><a href="#id372910">5.1. Setting up Configuration file</a></span></dt><dt><span class="sect1"><a href="#id372962">5.2. Setting up CRL's and CA's lists</a></span></dt><dt><span class="sect1"><a href="#id373042">5.3. Create map files</a></span></dt></dl></div><p>
Configuration of <span class="application">pam-pkcs11</span> involves two steps:
</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem">Configure pam-pkcs11</li><li class="listitem">Configure global PAM options</li></ol></div><p>
</p><p>
This chapter explains pam-pkcs11 configuration-related issues. Next
chapter deals with generic PAM options. You should read this manual and
study the provided configuration sample files before doing any change.
</p><p>
You must know:
</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem">Which PKCS #11 module you are going to use, and its
filename</li><li class="listitem">Which mapper(s) module(s) you need, and if needed, how to
create and edit related mapping files</li><li class="listitem">You'll also need the root Certificate Authority files, and if
required, the Certificate Revocation Lists ones</li><li class="listitem">Of course, the list of authorized users to login, and their
corresponding certificates. When a remote certificate authentication is
performed (e.g., via LDAP, ADS or NSS), this information must reside on, or
be accessible by the server</li></ul></div><p>
</p><div class="sect1" title="5.1. Setting up Configuration file"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="id372910"></a>5.1. Setting up Configuration file</h2></div></div></div><p>
The configuration file uses the <span class="application">scconf</span> library.
</p><p>
Parameters and data are grouped into blocks. Blocks can be nested in a
tree.
</p><p>
A pam-pkcs11 configuration file looks like:
</p><pre class="screen">
pam-pkcs11 {
global options
...
use_pkcs11_module = pkcs11 module to be used
pkcs11_module module1 {
module1 specific options
}
pkcs11_module module2 {
module2 specific options
}
[...]
use_mappers = mapper1, mapper2,... ;
mapper mapper1 {
mapper1 specific options
}
mapper mapper2 {
mapper2 specific options
}
[...]
mapper mapperN {
mapperN specific options
}
}
</pre><p>
</p><p>
For detailed description see the
<a class="ulink" href="http://www.opensc-project.org/pam_pkcs11/file/trunk/etc/pam_pkcs11.conf.example" target="_top">pam_pkcs11.conf.example</a> file.
</p><p>
Details on scconf syntax and API are provided in the
<a class="ulink" href="http://www.opensc-project.org/pam_pkcs11/file/trunk/src/scconf/README.scconf" target="_top">src/scconf/README.scconf</a>
file.
</p></div><div class="sect1" title="5.2. Setting up CRL's and CA's lists"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="id372962"></a>5.2. Setting up CRL's and CA's lists</h2></div></div></div><p>
<span class="application">pam-pkcs11</span> needs a list of recognized
Certificate Authorities, to properly validate user certificates. The same
applies to Certificate Revocation Lists (if configured to be used).
</p><p>
So the process to setup ca and crl entries is:
</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"> Create ca_dir and crl_dir directory entries, according to
configuration file</li><li class="listitem"> Copy CA Certificates (either DER or PEM format) to
the ca_dir directory</li><li class="listitem"> Create hash links to CA certificates with provided
<span class="application">make_hash_link.sh</span>. Note that
<span class="application">OpenSSL</span> must be installed
<pre class="screen">
<strong class="userinput"><code>cd /etc/pam_pkcs11/cacerts
/usr/bin/make_hash_link.sh</code></strong>
</pre></li><li class="listitem"> Repeat above procedure for CRL entries (if used)</li><li class="listitem"> Select your Certificate verification policy ("<code class="option">cert_policy</code>" option in "<code class="option">module</code>" entry) </li></ol></div><p>
</p><p>
<em class="lineannotation"><span class="lineannotation">NOTE:</span></em>
Due to OpenSSL library limitations, CA entries must reside in the local
file system, and cannot be accessed from a remote server. So although
user auth can be done in a remote way, certificate validation must be
done locally.
</p></div><div class="sect1" title="5.3. Create map files"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="id373042"></a>5.3. Create map files</h2></div></div></div><p>
If your selected mapper module(s) use(s) login mapping, you'll need to
create and setup mapping files. Some examples are provided with the source
code.
</p><p>
As a general rule, a mapping file has a new line terminated list of
certificate contents -> login entries:
</p><pre class="screen">
Certificate1 data -> login1
Certificate2 data -> login2
Certificate2 data -> login3
</pre><p>
</p><p>Remember that this file is parsed from the first line to the end,
and returns on the first match.</p><p>
As you can see bellow, mapfile specification doesn't need to be
a regular file: you can retrieve data from any legal URL. Anyway, data
format must be preserved. See <a class="xref" href="#mapfiles" title="12.3. How to use mapfiles">Section 12.3, “How to use mapfiles”</a>
for additional info.
</p></div></div><div class="chapter" title="Chapter 6. PAM Configuration"><div class="titlepage"><div><div><h2 class="title"><a id="pamconfig"></a>Chapter 6. PAM Configuration</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="sect1"><a href="#id373086">6.1. Configuring pam.d files</a></span></dt><dt><span class="sect1"><a href="#id373371">6.2. Sample pam.d/ entries</a></span></dt></dl></div><div class="sect1" title="6.1. Configuring pam.d files"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="id373086"></a>6.1. Configuring pam.d files</h2></div></div></div><p>
To make use of the PKCS #11 login module add the line
</p><pre class="screen">
auth sufficient pam_pkcs11.so ...
</pre><p>
in the <code class="filename">/etc/pam.d/serviceXXX</code> configuration file.
</p><p>
Some mappers doesn't map to an existing user. To allow correct login,
you may need to install also pam-mkhomedir in session PAM stack
See <a class="ulink" href="http://www.kernel.org/pub/linux/libs/pam" target="_top">http://www.kernel.org/pub/linux/libs/pam</a> for
details.
</p><p>
The following options are recognized by
<code class="filename">pam-pkcs11.so</code>:
<dt><span class="term"><span class="token">debug</span></span></dt><dd>Enable debugging support.</dd>
<dt><span class="term"><span class="token">config_file</span></span></dt><dd>To specify up configuration file (default
<code class="filename">/etc/pam_pkcs11/pam_pkcs11.conf</code>)
</dd>
</p><p>
The next options should be taken from the configuration file (default
<code class="filename">/etc/pam_pkcs11/pam_pkcs11.conf</code>), but is up to the
user to specify them in the command line. If so, it takes precedence
over the configuration file.
<dt><span class="term"><span class="token">nullok</span></span></dt><dd>Allow empty passwords.</dd>
<dt><span class="term"><span class="token">use_first_pass</span></span></dt><dd>
Do not prompt the user for the passwords but take them from the
PAM_ items instead.
</dd>
<dt><span class="term"><span class="token">try_first_pass </span></span></dt><dd>Do not prompt the user for the passwords unless PAM_(OLD)AUTHTOK
is unset.
</dd>
<dt><span class="term"><span class="token">use_authtok</span></span></dt><dd>Like <span class="token">try_first_pass</span>, but fail if the new
PAM_AUTHTOK has not been previously set (intended for stacking password
modules only).
</dd>
</p><p>
Next options are PKCS #11 module specific:
</p><dt><span class="term"><span class="token">pkcs11_module=<file></span></span></dt><dd><p>
Filename of the PKCS #11 module. The default value is
<code class="filename">/etc/pam_pkcs11/pkcs11_module.so</code>
</p><p>
Note that this option takes precedence over "module" entry
in proper pkcs11_module section, but this section is still needed
</p></dd><dt><span class="term"><span class="token">slot_num=<nr></span></span></dt><dd><p>
Slot-number to use: 1 for the first, 2 for the second and so
on. The default value is 0, which means to use the first slot
with an available token.
</p></dd><dt><span class="term"><span class="token">ca_dir=<path></span></span></dt><dd><p>
Path to the directory where the CA certificates are stored. The
directory must contain an OpenSSL hash-link to each certificate.
The default value is <code class="filename">/etc/pam_pkcs11/cacerts/</code>.
</p><p>
<span class="application">Pam-pkcs11</span> provides a utility:
<code class="filename">make_hash_link.sh</code> that can be used to create hash
links to certificate files. Hashes are used to check certification
validity and revocation.
</p></dd><dt><span class="term"><span class="token">crl_dir=<path></span></span></dt><dd><p>
Path to the directory where the CRLs are stored. The directory
must contain an openssl hash-link to each CRL. The default value
is <code class="filename">/etc/pam_pkcs11/crls/</code>.
</p></dd><dt><span class="term"><span class="token">cert_policy={none, ca, signature, crl_online, crl_offline, crl_auto}</span></span></dt><dd><p>
Sets the Certificate verification policy:
</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><span class="token">none</span>: Performs no verification at all
</li><li class="listitem"><span class="token">ca</span>: Checks that Certificate has a recognized CA from ca_dir
</li><li class="listitem"><span class="token">signature></span>: Does a signature check to ensure that private and public key matches
</li><li class="listitem"><span class="token">crl_online</span>: Downloads the CRL from the location
given by the CRL distribution point extension of the
certificate</li><li class="listitem"><span class="token">crl_offline</span>: Uses the locally stored CRLs.
</li><li class="listitem"><span class="token">crl_auto</span>: Is a combination of online and
offline: it first tries to download the CRL from a possibly given
CRL distribution point and if this fails it uses the local CRLs.
</li></ul></div><p>
You can use a comma-separated list to specify all desired options, eg <code class="option">ca,crl_offline,signature</code>. The default setting is <code class="option">none</code>.
</p></dd></div><div class="sect1" title="6.2. Sample pam.d/ entries"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="id373371"></a>6.2. Sample pam.d/ entries</h2></div></div></div><p>
Here is the normal way to use pam-pkcs11 into the PAM stack. Only the
first auth line is added. You configuration may be different depending
on your Unix system.
</p><pre class="screen">
#%PAM-1.0
auth sufficient pam_pkcs11.so
auth required pam_securetty.so
auth required pam_stack.so service=system-auth
auth required pam_nologin.so
account required pam_stack.so service=system-auth
password required pam_stack.so service=system-auth
session required pam_stack.so service=system-auth
session optional pam_console.so
</pre><p>
</p><p>
An alternate way is to use explicit options. This is not recommended,
but still possible:
</p><pre class="screen">
#%PAM-1.0
auth sufficient pam_pkcs11.so nullok debug try_first_pass \
config_file=/etc/pam_pkcs11/pam_pkcs11.conf \
pkcs11_module=/usr/lib/pkcs11/pkcs11_module.so \
ca_dir=/etc/cacerts/ crl_dir=/etc/cacerts/ cert_policy=none
auth required pam_securetty.so
auth required pam_stack.so service=system-auth
auth required pam_nologin.so
account required pam_stack.so service=system-auth
password required pam_stack.so service=system-auth
session required pam_stack.so service=system-auth
session optional pam_console.so
</pre><p>
In this second example the configuration file is still needed to get
the mapper module options and flags.
</p></div></div><div class="chapter" title="Chapter 7. Using Login auto-detect features"><div class="titlepage"><div><div><h2 class="title"><a id="autologin"></a>Chapter 7. Using Login auto-detect features</h2></div></div></div><p>
Starting at pam_pkcs11-0.4.2 a new feature is provided: pam-pkcs11 can
deduce the username from the user certificate without using the login prompt.
</p><p>
This is done when <code class="function">pam_get_user()</code> call returns null
or an empty string. In this case, pam-pcks11 uses the module mapper "find"
feature instead of normal "match".
</p><p>
If the finder returns with success, the found username is set to PAM
using <code class="function">pam_set_item(PAM_USER)</code> call, and
<span class="emphasis"><em>PAM_AUTH_OK</em></span> is returned.
</p><p>
So it is no longer needed to enter the login name if a certificate is
provided and can be mapped to a user.
</p><p>
There are to ways for using this feature:
</p><div class="orderedlist"><ol class="orderedlist" type="a"><li class="listitem"> Patch "gdm" and "login" programs to detect card presence
and return null as user name, without prompt for a user login.
This is a work to be done :-(</li><li class="listitem"> Use unpatched versions, and do the following procedures:
<div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem">When login from console, just enter " " (space) +
Enter. </li><li class="listitem">When login from gdm, just key Enter at login prompt.
</li></ol></div></li></ol></div><p>
</p><p>
In both cases the procedure follows as:
</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem">If a card is not present, "login" will ask for a password and
then fail; "gdm" will prompt again for a user login</li><li class="listitem">If a card is present, pam-pkcs11 will ask for the PIN, and then
invoke finder in module mapper list. When a user is found, this user
become the logged user</li></ol></div><p>
</p><p>
This feature can be used with pam-mkhomedir.so PAM session module.
In this case, you can create on-the-fly accounts. This scenario is
ideal for centralized auth services (Winbind, LDAP, Kerberos, RDBMS
auth...).
</p><p>
As example, here comes my tested <code class="filename">/etc/pam.d/gdm</code> file:
</p><pre class="screen">
#%PAM-1.0
auth sufficient pam_pkcs11.so debug config_file=/etc/pam_pkcs11/pam_pkcs11.conf
auth required pam_env.so
auth required pam_stack.so service=system-auth
auth required pam_nologin.so
account required pam_stack.so service=system-auth
password required pam_stack.so service=system-auth
session required pam_stack.so service=system-auth
session optional pam_mkhomedir.so skel=/etc/skel umask=0022
session optional pam_console.so
</pre><p>
</p><p>
<em class="lineannotation"><span class="lineannotation">IMPORTANT NOTES:</span></em>
For <code class="function">pam_set_item(PAM_USER)</code> to succeed,
the application using PAM must have enough permission. If this condition
is not met, setting user process will fail and proper log message registered.
So this feature is mainly provided for logging processes running as
<span class="keysym">root</span>.
</p><p>
Improper mapper chain' configurations with unauthorized certificates can
lead to the creation of fake accounts in the system if pam_mkhomedir.so
module is used. So be really careful when authenticate users directly
from certificates.
</p></div><div class="chapter" title="Chapter 8. Using the Event Manager Tools"><div class="titlepage"><div><div><h2 class="title"><a id="eventmgr"></a>Chapter 8. Using the Event Manager Tools</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="sect1"><a href="#id373654">8.1. Using the Card Event Manager</a></span></dt><dd><dl><dt><span class="sect2"><a href="#id373710">8.1.1. Structure of configuration file</a></span></dt></dl></dd><dt><span class="sect1"><a href="#id373733">8.2. Using the PKCS#11 Event Manager</a></span></dt><dt><span class="sect1"><a href="#id373847">8.3. Security issues</a></span></dt><dt><span class="sect1"><a href="#id373873">8.4. Example: use xscreensaver to lock screen on card removal</a></span></dt></dl></div><p>
<span class="application">PAM-PKCS11</span> includes several tools:
<span class="application">card_eventmgr</span> and
<span class="application">pkcs11_eventmgr</span> that can be used to monitor
the status of the card reader and dispatch actions on several events.
These programs can be used to several actions, like lock screen on card
removal.
</p><p>
Note that these programs have no direct interaction with pam-pkcs11 module:
they are just card status monitors. It is the system administrator job
to define and configure actions to take on events.
</p><div class="sect1" title="8.1. Using the Card Event Manager"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="id373654"></a>8.1. Using the Card Event Manager</h2></div></div></div><p>
<span class="application">card_eventmgr</span> is a card status monitor based
on the PCSC-Lite library.
</p><p>
To invoke the program, just type <strong class="userinput"><code>card_eventmgr</code></strong>.
Several command lines options are recognized:
</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><code class="option">debug</code> to enable debugging. Default is no
debug</li><li class="listitem"><code class="option">daemon</code> to run as a daemon in the background.
If <code class="option">debug</code> is unset, also detach from the tty. Default is to
run in the foreground</li><li class="listitem"><code class="option">timeout=<msecs></code> time in milliseconds
between two consecutive status poll. Defaults is 1000 (1
second)</li><li class="listitem"><code class="option">config_file=<file></code> configuration file
to use. Default is
<code class="filename">/etc/pam_pkcs11/card_eventmgr.conf</code></li></ul></div><p>
</p><div class="sect2" title="8.1.1. Structure of configuration file"><div class="titlepage"><div><div><h3 class="title"><a id="id373710"></a>8.1.1. Structure of configuration file</h3></div></div></div><p>
Here is an example of configuration file. It is auto-descriptive:
</p><pre class="screen">
card_eventmgr {
# Run in background? Implies debug=false if set to true
daemon = false;
# show debug messages?
debug = false;
# polling time in milliseconds
timeout = 1000;
#
# list of events and actions
# Card inserted
event card_insert {
# what to do if an action fail?
# ignore : continue to next action
# return : end action sequence
# quit : end program
on_error = ignore ;
# You can enter several, comma-separated action entries
# they will be executed in turn
action = "/usr/bin/play /usr/share/sounds/warning.wav",
"/usr/X11R6/bin/xscreensaver-command -deactivate";
}
# Card has been removed
event card_remove {
on_error = ignore;
action = "/usr/bin/play /usr/share/sounds/error.wav",
"/usr/X11R6/bin/xscreensaver-command -lock";
}
}
</pre><p>
</p></div></div><div class="sect1" title="8.2. Using the PKCS#11 Event Manager"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="id373733"></a>8.2. Using the PKCS#11 Event Manager</h2></div></div></div><p>
pkcs11_eventmgr is very similar to
<span class="application">card_eventmgr</span>, with some improvements:
</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"> It uses the PKCS#11 library, instead the low-level PCSC-Lite
API</li><li class="listitem"> Polling time, and expire time unit is the second, not
the millisecond</li><li class="listitem"> New command line options:
<div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><code class="option">[no]debug</code> to enable/disable debugging.
Defaults to "<code class="option">nodebug</code>"</li><li class="listitem"><code class="option">[no]daemon</code> to run as daemon or
foreground. If debug is unset, daemon mode also detaches from tty.
Default to "<code class="option">nodaemon</code>"</li><li class="listitem"><code class="option">polling_time=<secs></code> time in
seconds between two consecutive status poll. Defaults to 1
second</li><li class="listitem"><code class="option">expire_time=<secs></code> time in
second on card removed to trigger "expire_time" event. Default to
0 (no expire)</li><li class="listitem"><code class="option">config_file=<file> </code>configuration
file to use. Defaults to
<code class="filename">/etc/pam_pkcs11/card_eventmgr.conf</code></li><li class="listitem"><code class="option">pkcs11_module=<file> </code>PKCS #11
dynamic library to use. Defaults to
<code class="filename">/usr/lib/pkcs11/opensc-pkcs11.so</code></li></ul></div></li><li class="listitem"> Expire time on card removal is now supported</li><li class="listitem"> Configuration file is slightly different. See provided
example</li></ol></div><p>
</p><p>
Here is a pkcs11_cardmgr sample file, with defaults
</p><pre class="screen">
# Sample pkcs11_eventmgr configuration file
#
pkcs11_eventmgr {
# Run in background? Implies debug=false if true
daemon = true;
# show debug messages?
debug = false;
# polling time in seconds
polling_time = 1;
# expire time in seconds
# default = 0 (no expire)
expire_time = 0;
# pkcs11 module to use
pkcs11_module = /usr/lib/opensc-pkcs11.so;
#
# list of events and actions
# Card inserted
event card_insert {
# what to do if an action fail?
# ignore : continue to next action
# return : end action sequence
# quit : end program
on_error = ignore ;
# You can enter several, comma-separated action entries
# they will be executed in turn
action = "/usr/bin/play /usr/share/sounds/warning.wav",
"/usr/X11R6/bin/xscreensaver-command -deactivate";
}
# Card has been removed
event card_remove {
on_error = ignore;
action = "/usr/bin/play /usr/share/sounds/error.wav",
"/usr/X11R6/bin/xscreensaver-command -lock";
}
# Too much time card removed
event expire_time {
on_error = ignore;
action = "/bin/false";
}
}
</pre><p>
</p><p>
As you can see, on each event you can define a list of actions, and what to
do if an action fails.
</p></div><div class="sect1" title="8.3.  Security issues"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="id373847"></a>8.3. Security issues</h2></div></div></div><p>
The best way to start card monitoring is at user login.
If so, note that all event commands will be executed with user privileges.
So it is up to the user to take care that he has permissions to execute
the desired actions.
</p><p>
Special checks should be done when invoking setuid/segid programs: these
commands usually ignore the user environment and set up their own. So
these applications may not work as expected.
</p><p>
Command actions are executed via
<code class="function">execve("/bin/sh","-c","provided
command",null,environ)</code> in order to avoid security risks if
using system() library call.
</p></div><div class="sect1" title="8.4.  Example: use xscreensaver to lock screen on card removal"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="id373873"></a>8.4. Example: use xscreensaver to lock screen on card removal</h2></div></div></div><p>
Just add to your <code class="filename">~/.xsession</code> or KDE/GNOME Autostart
directory an invocation to <span class="application">card_eventmgr</span> in
daemon mode. Your <code class="filename">~/.xsession</code> should look like:
FIXME
</p><p>
Additionally you can add this line to
<code class="filename">/etc/pam.d/xscreensaver</code> configuration file:
</p><pre class="screen">
auth sufficient pam_pkcs11.so
</pre><p>
</p><p>
In this case, when card is removed the X screen will lock. When card
is re-inserted, screen will prompt for the card PIN, check it and if
access granted the screen will unlock
</p><p>
<em class="lineannotation"><span class="lineannotation">NOTES:</span></em>
</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem">Starting pam_pkcs11-0.4.4, <span class="application">card_eventmgr</span> tool is no longer supported by pam-pkcs11, and may be removed in newer versions on the package. Users are encouraged to upgrade to<span class="application"> pkcs11_eventmgr</span>. This is done to avoid dependencies on low level card management routines</li><li class="listitem">
Some PKCS#11 implementations do not properly support <code class="function">
C_WaitForSlotEvent()</code> function as defined in PKCS #11 v2.1 API. So current <span class="application">pkcs11_eventmgr</span> doesn't use it at all, just sleep+rescan tokens. This is a time-consuming behavior, and may change in future versions of the tool
</li></ol></div><p>
</p></div></div><div class="chapter" title="Chapter 9. Using the Login Finder Tool"><div class="titlepage"><div><div><h2 class="title"><a id="loginfinder"></a>Chapter 9. Using the Login Finder Tool</h2></div></div></div><p>
<span class="application">PAM-PKCS#11</span> provides another tool: <span class="application">pklogin-finder</span> that can be used to
find Cert-to-login maps, outside the PAM environment.
This tool can be used to create and test map files, or to check environment
and configuration files, without need to use PAM related tools.
</p><p>
<span class="application">pklogin_finder</span> uses the same structure and configuration than pam-pkcs11
module. It reads certificate, and try all specified mappers to find a
user match. When found, login name is displayed on stdout.
</p><p>
To invoke, just type from console:
</p><pre class="screen">
<strong class="userinput"><code>pklogin_finder [[no]debug] [config_file=<file>]</code></strong>
</pre><p>
By default, debug is set to <code class="filename">false</code>, and config_file to <code class="filename">/etc/pam_pkcs11/pam-pkcs11.conf</code>. All PAM related options (<code class="option">nullok</code>, <code class="option">try_first_pass</code>, and so) in configuration file are ignored
</p><p>
Return values are:
</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"> 0 0n success, and login name displayed on stdout</li><li class="listitem"> 1 On no login match found</li><li class="listitem"> 2 On process error</li></ul></div><p>
</p></div><div class="chapter" title="Chapter 10. Using the PKCS#11 CertInspect tool"><div class="titlepage"><div><div><h2 class="title"><a id="pkcs11_inspect"></a>Chapter 10. Using the PKCS#11 CertInspect tool</h2></div></div></div><p>
Starting at version 0.5 a new tool
<span class="application">pkcs11_inspect</span> is provided.
</p><p>
<span class="application">pkcs11_inspect</span> is a PKCS #11 based tool to
explore certificate contents. It's similar to
<span class="application">pklogin_finder</span>, but no mapping is done at
all: just load mappers' chains, and in turn, try to get proper data from
certificate (i.e.: cn_mapper looks for CN entries, and so).
</p><p>
When desired info is found, <span class="application">pkcs11_inspect</span>
print found data to stdout, <span class="emphasis"><em>without doing any
mapping</em></span>, that is, mapfile entries in configuration file are
ignored.
</p><p>
The reason to exist for this tool is to ease the making of mapping files:
</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem">Insert your smart card</li><li class="listitem">Invoke <span class="application">pkcs11_inspect</span></li><li class="listitem">Store result as "left side" of mapfile</li><li class="listitem">Edit mapfile and assign contents to a login</li></ul></div><p>
</p><p>
Same command line options and configuration file than
<span class="application">pklogin_finder</span> applies to
<span class="application">pkcs11_inspect</span> command, but note that
<code class="option">mapping</code> and <code class="option">ignorecase</code> options will be
ignored. See the manual page for details.
</p></div><div class="chapter" title="Chapter 11. HOWTO install pam_pkcs11"><div class="titlepage"><div><div><h2 class="title"><a id="HOWTO"></a>Chapter 11. HOWTO install pam_pkcs11</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="sect1"><a href="#id374146">11.1. Install the software </a></span></dt><dt><span class="sect1"><a href="#id374166">11.2. Configure pam_pkcs11 </a></span></dt><dd><dl><dt><span class="sect2"><a href="#id374171">11.2.1. Create the needed directories </a></span></dt><dt><span class="sect2"><a href="#id374192">11.2.2. Copy and install the root CA certificate </a></span></dt><dt><span class="sect2"><a href="#id374226">11.2.3. Configure pam_pkcs11 </a></span></dt><dt><span class="sect2"><a href="#id374257">11.2.4. Configure the subject mapper </a></span></dt></dl></dd><dt><span class="sect1"><a href="#id374314">11.3. Install and test your PAM configuration </a></span></dt><dt><span class="sect1"><a href="#id374420">11.4. Secure your PAM configuration </a></span></dt><dt><span class="sect1"><a href="#id374448">11.5. Using card_eventmgr </a></span></dt><dd><dl><dt><span class="sect2"><a href="#id374464">11.5.1. Configuring and testing card_eventmgr </a></span></dt><dt><span class="sect2"><a href="#id374506">11.5.2. Starting card_eventmgr </a></span></dt></dl></dd></dl></div><p>
We will now describe a complete installation of pam_pkcs11 as an example
case. This configuration will use a local root CA certificate and the
subject mapper. Many other configurations are also possible.
</p><div class="sect1" title="11.1.  Install the software"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="id374146"></a>11.1. Install the software </h2></div></div></div><p>
You should install pre-compiled binaries since that is the easiest way
to install a software. See the documentation of your distribution to
know how to install RPM, DEB or whatever packages.
</p><p>
If you want to recompile from source read <a class="xref" href="#install" title="Chapter 4. Installation">Chapter 4, <i>Installation</i></a>.
</p></div><div class="sect1" title="11.2.  Configure pam_pkcs11"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="id374166"></a>11.2. Configure pam_pkcs11 </h2></div></div></div><div class="sect2" title="11.2.1.  Create the needed directories"><div class="titlepage"><div><div><h3 class="title"><a id="id374171"></a>11.2.1. Create the needed directories </h3></div></div></div><p>
</p><pre class="screen">
<strong class="userinput"><code>mkdir /etc/pam_pkcs11
mkdir /etc/pam_pkcs11/cacerts
mkdir /etc/pam_pkcs11/crls</code></strong>
</pre><p>
</p></div><div class="sect2" title="11.2.2.  Copy and install the root CA certificate"><div class="titlepage"><div><div><h3 class="title"><a id="id374192"></a>11.2.2. Copy and install the root CA certificate </h3></div></div></div><p>
I used <a class="ulink" href="http://tinyca.sm-zone.net/" target="_top">tinyCA</a> to
generate the root CA and the user certificates. Your root CA certificate
name may be different. Make sure that all the files in <code class="filename">/etc/pam_pkcs11/cacerts/</code> can be read by
any user.
</p><pre class="screen">
<strong class="userinput"><code>cp testCA-cacert.der /etc/pam_pkcs11/cacerts/
cd /etc/pam_pkcs11/cacerts
chmod a+r *
make_hash_link.sh</code></strong>
</pre><p>
</p></div><div class="sect2" title="11.2.3.  Configure pam_pkcs11"><div class="titlepage"><div><div><h3 class="title"><a id="id374226"></a>11.2.3. Configure pam_pkcs11 </h3></div></div></div><p>
Copy the sample file:
</p><pre class="screen">
<strong class="userinput"><code>cp /usr/share/doc/pam-pkcs11/examples/pam_pkcs11.conf.example.gz /etc/pam_pkcs11/
cd /etc/pam_pkcs11/
gunzip pam_pkcs11.conf.example.gz
mv pam_pkcs11.conf.example pam_pkcs11.conf</code></strong>
</pre><p>
</p><p>
The sample file uses the OpenSC PKCS#11 library. You may need to edit
<code class="filename">/etc/pam_pkcs11/pam_pkcs11.conf</code> if you want to use
another PKCS#11 library.
</p></div><div class="sect2" title="11.2.4.  Configure the subject mapper"><div class="titlepage"><div><div><h3 class="title"><a id="id374257"></a>11.2.4. Configure the subject mapper </h3></div></div></div><p>
Copy the sample file:
</p><pre class="screen">
<strong class="userinput"><code>cp /usr/share/doc/pam-pkcs11/examples/subject_mapping.example /etc/pam_pkcs11/subject_mapping</code></strong>
</pre><p>
Then use <span class="application">pkcs11_inspect</span> to get the
information you need for the mapper. In our case you are looking for
something like:
</p><pre class="screen">
Printing data for mapper subject: /C=ES/O=FNMT/OU=FNMT Clase 2
CA/OU=500051483/CN=NOMBRE MARTINEZ CASTA\xF1O JUAN ANTONIO
- NIF 50431138G
</pre><p>
Note that this is one line but it is wrapped to be displayed here in the
form of three lines.
</p><p>
Then edit <code class="filename">/etc/pam_pkcs11/subject_mapping</code> to add
the strings above followed by <strong class="userinput"><code>-> login name</code></strong>. The
file should then contain something like:
</p><pre class="screen">
# Mapping file for Certificate Subject
# format: Certificate Subject -> login
#
/C=ES/O=FNMT/OU=FNMT Clase 2 CA/OU=500051483/CN=NOMBRE MARTINEZ
CASTA\xF1O JUAN ANTONIO - NIF 50431138G -> jantonio
</pre><p>
Again note that the two last lines displayed should be only one.
</p></div></div><div class="sect1" title="11.3.  Install and test your PAM configuration"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="id374314"></a>11.3. Install and test your PAM configuration </h2></div></div></div><p>
You will now configure your PAM system to use
<span class="application">pam_pkcs11</span>. We recommend you to start with an
easy-to-debug application like <span class="application">login</span>. The
advantage of <span class="application">login</span> is that you can see the
debug messages from <span class="application">pam_pkcs11</span>.
</p><p>
Edit <code class="filename">/etc/pam.d/login</code> and add, at the beginning of
the file, the lines:
</p><pre class="screen">
# pam_pkcs11: smart card login
auth sufficient pam_pkcs11.so
</pre><p>
Since <code class="filename">/etc/pam_pkcs11/pam_pkcs11.conf</code> has "<code class="code">debug =
true</code>" you should see lots of debug on the console you use to log in. You
should also see any error that would occur. If everything works
correctly you can change the configuration file and use "<code class="code">debug =
false</code>".
</p><p>
Once your PAM configuration is tested and working you can configure all
the PAM applications you want to use with a smart card. A possible list
is:
</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><span class="application">gdm</span> (Gnome Display Manager)</li><li class="listitem"><span class="application">kdm</span> (KDE Display Manager)</li><li class="listitem"><span class="application">xdm</span> (X11 display manager)</li><li class="listitem"><span class="application">login</span> (text console login)</li><li class="listitem"><span class="application">xscreensaver</span> (X11 screen saver)</li><li class="listitem">etc.</li></ul></div><p>
</p></div><div class="sect1" title="11.4.  Secure your PAM configuration"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="id374420"></a>11.4. Secure your PAM configuration </h2></div></div></div><p>
We used "<span class="token">sufficient</span>" in the PAM configuration file. If
the pam_pkcs11 module fails to authenticate the user the PAM system will
go on with the next PAM module, the next PAM module should ask for a
password. If you want to use the smart card only and not the password
any more just replace "<span class="token">sufficient</span>" by
"<span class="token">required</span>". The authentication process will then fail if
pam_pkcs11 fails.
</p><p>
Note: with the "required" option, if there is a bug in any smart card
related software you will not be able to log in even as root. It should
be safer to keep the possibility to log in using a password but at the
same time disable password login for normal users. So you will still be
able to login as root with the root password.
</p></div><div class="sect1" title="11.5.  Using card_eventmgr"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="id374448"></a>11.5. Using card_eventmgr </h2></div></div></div><p>
<span class="application">card_eventmgr</span> is a helper tool to
automatically launch an application to lock or unlock the screen when the
card is removed or inserted. A natural application is to lock the X11
screen when the card is removed.
</p><div class="sect2" title="11.5.1.  Configuring and testing card_eventmgr"><div class="titlepage"><div><div><h3 class="title"><a id="id374464"></a>11.5.1. Configuring and testing card_eventmgr </h3></div></div></div></div><p>
Copy the sample file:
</p><pre class="screen">
<strong class="userinput"><code>cp /usr/share/doc/pam-pkcs11/examples/card_eventmgr.conf.example /etc/pam_pkcs11/card_eventmgr.conf</code></strong>
</pre><p>
Edit the configuration file to set the actions to be processes when the
card is removed and inserted. You may have to change the command to play
a sound.
</p><p>
You can now test your <span class="application">card_eventmgr</span>
configuration file by executing
</p><pre class="screen">
<strong class="userinput"><code>card_eventmgr debug nodaemon</code></strong>
</pre><p>
You will see some debug messages and, possibly, why the command you
configured as action does not work properly.
</p><div class="sect2" title="11.5.2.  Starting card_eventmgr"><div class="titlepage"><div><div><h3 class="title"><a id="id374506"></a>11.5.2. Starting card_eventmgr </h3></div></div></div></div><p>
After debugging your <span class="application">card_eventmgr</span>
configuration file you can start it automatically. One solution is to
create a <code class="filename">~/.xsession</code> file containing:
</p><pre class="screen">
# start the card autolock
card_eventmgr pidfile=$HOME/.card_eventmgr.pid
# start Gnome or something else
/usr/bin/x-session-manager
# kill the card autolock
card_eventmgr kill pidfile=$HOME/.card_eventmgr.pid
</pre><p>
</p></div></div><div class="chapter" title="Chapter 12. What is a cert mapper?"><div class="titlepage"><div><div><h2 class="title"><a id="mappers"></a>Chapter 12. What is a cert mapper?</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="sect1"><a href="#fundamentals">12.1. Fundamentals </a></span></dt><dt><span class="sect1"><a href="#mapper_impl">12.2. Implementation of cert mappers in pam-pkcs11</a></span></dt><dt><span class="sect1"><a href="#mapfiles">12.3. How to use mapfiles</a></span></dt><dt><span class="sect1"><a href="#mapperlist">12.4. Mappers provided by Pam-pkcs11</a></span></dt><dd><dl><dt><span class="sect2"><a href="#id374780">12.4.1. Common Name (CN) mapper</a></span></dt><dt><span class="sect2"><a href="#id374822">12.4.2. Subject mapper</a></span></dt><dt><span class="sect2"><a href="#id374879">12.4.3. Getpwent() CN to login mapper</a></span></dt><dt><span class="sect2"><a href="#id374966">12.4.4. LDAP (lightweight directory access protocol) mapper</a></span></dt><dt><span class="sect2"><a href="#id375241">12.4.5. OpenSC library mapper</a></span></dt><dt><span class="sect2"><a href="#id375261">12.4.6. OpenSSH library mapper</a></span></dt><dt><span class="sect2"><a href="#id375335">12.4.7. Email Cert to login mapper</a></span></dt><dt><span class="sect2"><a href="#id375426">12.4.8. Microsoft Universal Principal Name mapper</a></span></dt><dt><span class="sect2"><a href="#id375478">12.4.9. Kerberos mapper</a></span></dt><dt><span class="sect2"><a href="#id375540">12.4.10. Unique ID to login mapper</a></span></dt><dt><span class="sect2"><a href="#id375572">12.4.11. Certificate Digest to login mapper</a></span></dt><dt><span class="sect2"><a href="#id375613">12.4.12. Generic mapper</a></span></dt><dt><span class="sect2"><a href="#id375750">12.4.13. Null mapper</a></span></dt></dl></dd><dt><span class="sect1"><a href="#id375830">12.5. Adding new mappers</a></span></dt></dl></div><div class="sect1" title="12.1.  Fundamentals"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="fundamentals"></a>12.1. Fundamentals </h2></div></div></div><p>
When a X509 Certificate is provided, there are no direct ways to map
a cert to a login. With a certificate we can check validity and
revocation, but user mapping depends entirely on certificate contents.
</p><p>
So we need a configurable, stackable, and definable way to specify
cert-to-user mapping.
</p><p>
pam-pkcs11 cert mappers provides several functions to:
</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"> Search an specific item in certificate</li><li class="listitem"> Deduce a login from certificate</li><li class="listitem"> Test if a login and a certificate matches</li></ol></div><p>
</p><p>
Normal pam-pkcs11 login process involves following procedures:
</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"> Enter login</li><li class="listitem"> Ask for PIN</li><li class="listitem"> Open and validate certificate</li><li class="listitem"> Map certificate into an user (*)</li><li class="listitem"> Check if login and user matches (**)</li></ol></div><p>
</p><p>
An alternate way of working is by mean of not providing user name:
</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"> Detect if a card is inserted</li><li class="listitem"> Ask for PIN</li><li class="listitem"> Open and validate certificate</li><li class="listitem"> Map certificate into an user (*)</li><li class="listitem"> Open session for deduced login</li></ol></div><p>
Last way needs an additional pam-mkhomedir.so PAM module, which can
dynamically create an account.
</p><p>
Operations (*) and (**) are the reason for cert-mappers to exist.
</p></div><div class="sect1" title="12.2. Implementation of cert mappers in pam-pkcs11"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="mapper_impl"></a>12.2. Implementation of cert mappers in pam-pkcs11</h2></div></div></div><p>
<span class="application">pam-pkcs11</span> implements cert mapper in form of
dynamic loaded modules. Additionally, most of simplest mappers doesn't
need to be dynamically loaded, as they are already statically linked with
<span class="application">pam-pkcs11</span>. You can add as many modules as
desired, and the system will try all of them in turn, until match is
done, or end of list get reached.
</p><p>
The mapper list is defined in the configuration file:
</p><pre class="screen">
pam-pkcs11 {
....
use_mappers = mapper1 [ [[,] mapper2 ] ... ] ;
....
mapper mapper1 {
debug = false;
# When the mapper module is to be dynamically loaded, specify path
module = /path/to/module.so;
# When the mapper module is statically linked set to "internal"
# module = internal;
[ additional mapper dependent options ]
}
....
}
</pre><p>
"<span class="token">module</span>" option is mandatory: says pam_pkcs11 where to find dynamic library.
Additional entries can be defined but are module dependent
</p></div><div class="sect1" title="12.3. How to use mapfiles"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="mapfiles"></a>12.3. How to use mapfiles</h2></div></div></div><p>
Most of mappers supports the concept of <span class="property">mapfile</span>, that is,
a system to convert a given certificate data item to a user login.
The reasons are simple:
</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem">Most certificate contents are no valid for use
as login name, and need some way to manage it</li><li class="listitem">We can store and manage a list of authorized certificates in
a centralized way</li></ul></div><p>
</p><p>
The mapfile scheme used in pam-pkcs11 is powerful: it's not only
restricted to files, so we can specify HTTP, LDAP, FTP and so connections,
to retrieve mapfile. So this scheme is ideal for centralized accounting
systems.
</p><p>
The common structure of all mapfiles is:
</p><pre class="screen">
Certificate 1 entry data -> login1
Cert 2 data -> login2
string from -> string to
</pre><p>
That is: a string, the sequence " -> " (space, dash, greater, space) and a login
</p><p>
<em class="lineannotation"><span class="lineannotation">NOTE:</span></em>
It's syntactically correct to specify more than one word in the right side
of a map entry. But be aware that most mappers expect to be returned a single
word that provides a user login. Otherwise a strange behavior may occur.
See specific notes on mappers.
</p><p>
When a mapper module uses mapfiles, has a structure like:
</p><pre class="screen">
...
mapper my_mapper {
...
mapfile = URL;
}
...
</pre><p>
</p><p>
URL is a Universal Resource Locator as defined in corresponding RFC:
</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"> ftp://user:password@my.host.com/file</li><li class="listitem"> file:///path/to/local/file</li><li class="listitem"> https://www.weirdserver.com:8000/</li><li class="listitem"> ldap://ldap.frontec.se/o=frontec??sub?mail=*sth.frontec.se</li></ul></div><p>
Note that depending on compile time options pam-pkcs11 may not support
all URL syntax. See Install section and use of --use-curl configure option
</p><p>
Provided source code includes several example mapping files
</p></div><div class="sect1" title="12.4. Mappers provided by Pam-pkcs11"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="mapperlist"></a>12.4. Mappers provided by Pam-pkcs11</h2></div></div></div><p>
The standard pam-pkcs11 provides following mapper modules:
</p><div class="sect2" title="12.4.1. Common Name (CN) mapper"><div class="titlepage"><div><div><h3 class="title"><a id="id374780"></a>12.4.1. Common Name (CN) mapper</h3></div></div></div><p>
Assumes CN field on certificate to be the login name.
</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"> When used as finder, module returns the first CN field found or NULL</li><li class="listitem"> When used as matcher, it parses certificate and compare all CN fields
found against provided login name, returning OK if match found</li></ul></div><p>
In either case, if a mapfile is used, the mapper will try to map CN into
a login and use it.
</p><p>
Configuration entry is as follow:
</p><pre class="screen">
# Common Name (CN) to login mapper
mapper cn {
debug = false;
module = internal;
# module = /usr/lib/pam_pkcs11/cn_mapper.so;
# mapfile = "file:///etc/pam_pkcs11/cn_mapfile;
ignorecase = false;
mapfile = "none"
}
</pre><p>
</p><p>
Starting <span class="application">pam-pkcs11-0.5.3</span> this module is now statically linked, so no need to provide library pathname
</p></div><div class="sect2" title="12.4.2. Subject mapper"><div class="titlepage"><div><div><h3 class="title"><a id="id374822"></a>12.4.2. Subject mapper</h3></div></div></div><p>
Extract Certificate Subject and assume it as login.
</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"> When used as finder, returns mapped login, or assume
login=subject if no map found or provided</li><li class="listitem"> When used as matcher, try to match provided login, with
result obtained by previous find operation</li></ul></div><p>
In either case, if a mapfile is used, the mapper will try to map
subject into a login and use it.
</p><p>
Configuration file is like:
</p><pre class="screen">
# Certificate Subject to login mapper
mapper file {
debug = false;
module = internal;
# module = /usr/lib/pam_pkcs11/subject_mapper.so;
ignorecase = true;
# mapfile = file:///etc/pam_pkcs11/subject_map;
mapfile = "none";
}
</pre><p>
</p><p>
The mapping file must follow this structure:
</p><pre class="screen">
....
Certificate Subject -> login
....
</pre><p>
Note that some certificates handle strange char mappings (non utf-8)
so you must ensure correct byte-to-byte match. You can use provided
<span class="application">pkcs11_inspect</span> tool
to get and store correct data from certificate
</p><p>
Starting <span class="application">pam-pkcs11-0.5.3</span> this module is now statically linked, so no need to provide library pathname
</p></div><div class="sect2" title="12.4.3. Getpwent() CN to login mapper"><div class="titlepage"><div><div><h3 class="title"><a id="id374879"></a>12.4.3. Getpwent() CN to login mapper</h3></div></div></div><p>
Compare CN against <code class="function">getpwent()</code> library call <span class="symbol">login</span> or <span class="symbol">gecos</span> returned values to match user login
</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"> When used as finder use <code class="function">getpwent()</code> system call to retrieve every
users on the system. If <span class="symbol">pw_name</span> or <span class="symbol">pw_gecos</span> fields match with CN,
<span class="symbol">pw_name</span> is returned as login name</li><li class="listitem"> When used as matcher, maps CN to an user with via the finder
and matches result with login name provided by PAM, returning the
result (match or no)</li></ul></div><p>
</p><p>
Note: newer implementations of <code class="function">getpwent()</code> libraries, use an
additional Name Service Swicth (NSS) infrastructure, that
allows administrators to specify how to obtain requested data.
This means you can setup <code class="filename">/etc/nsswitch.conf</code> password entries
to lookup in to <code class="filename">/etc/passwd</code>, or LDAP/Kerberos/NIS+/YP services
</p><p>
pw_mapper configuration file shows like:
</p><pre class="screen">
mapper pw {
debug = true;
ignorecase = false;
module = internal;
# module = /usr/lib/pam_pkcs11/pw_mapper.so;
}
</pre><p>
</p><p>
Starting <span class="application">pam-pkcs11-0.5.3</span> this module is now statically linked, so no need to provide library pathname
</p></div><div class="sect2" title="12.4.4. LDAP (lightweight directory access protocol) mapper"><div class="titlepage"><div><div><h3 class="title"><a id="id374966"></a>12.4.4. LDAP (lightweight directory access protocol) mapper</h3></div></div></div><p>
Uses an LDAP server to retrieve user name. An additional file tells
module the mapping between Cert fields and LDAP entries.
</p><p>
This mapper is still under development.
</p><p>
ldap_mapper configuration file shows like:
</p><pre class="screen">
# Directory ( ldap style ) mapper
mapper ldap {
debug = false;
module = /usr/lib/pam_pkcs11/ldap_mapper.so;
ldaphost = "";
ldapport = ;
URI = "";
scope = 2;
binddn = "cn=pam,o=example,c=com";
passwd = "";
base = "ou=People,o=example,c=com";
attribute = "userCertificate";
filter = "(&(objectClass=posixAccount)(uid=%s))"
# SSL/TLS-Settings
ssl = tls
# tls_randfile = ...
tls_cacertfile = /etc/ssl/cacert.pem
# tls_cacertdir = ...
tls_checkpeer = 0
#tls_ciphers = ...
#tls_cert = ...
#tls_key = ...
}
</pre><p>
The following options are recognized by
<dt><span class="term"><span class="token">ldaphost</span></span></dt><dd>The FQDN (hostname) oder IP-address of the ldap server.</dd>
<dt><span class="term"><span class="token">URI</span></span></dt><dd>A space separated list of LDAP URIs. The URIs are used in the given order.
If a ldaphost is also submitted, it will be appended to the URI list.
</dd>
<dt><span class="term"><span class="token">ldapport</span></span></dt><dd>The LDAP Port on the server (default:
389 for LDAP and LDAP-TLS and 636 for SSL)
</dd>
<dt><span class="term"><span class="token">scope</span></span></dt><dd>Scope of search: 0-2
<div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><code class="option"> 0 </code> "base", search only the basedn
</li><li class="listitem"><code class="option"> 1 </code> "one", only the set of records one
level below the basedn is searched (default)
</li><li class="listitem"><code class="option"> 2 </code> "sub" means the union of entries
at the "base" level and all levels below are searched
</li></ul></div></dd>
<dt><span class="term"><span class="token">binddn</span></span></dt><dd>The bind-DN if needed.
</dd>
<dt><span class="term"><span class="token">passwd</span></span></dt><dd>Password for bind-DN
</dd>
<dt><span class="term"><span class="token">base</span></span></dt><dd>The DN of the searchbase (see scope)
</dd>
<dt><span class="term"><span class="token">attribute</span></span></dt><dd>The user attribute in LDAP entry, which contains
the certificate. This can be an multi-value attribute. That
implies you can store more than one certificate under this
attribute. All certificates are utilized.
</dd>
<dt><span class="term"><span class="token">filter</span></span></dt><dd>LDAP filter string. You can use ist to restrict
the entries returned by the LDAP server, e.g. by checking
other attributes of the user entry.
%s is substituted by the user name.
(&(objectClass=posixAccount)(uid=%s))
means, only that
LDAP entry is returned which has an objectClass
"posixAccount" and the uid with the user name.
<em class="lineannotation"><span class="lineannotation">IMPORTANT NOTE:</span></em> The filter string
must be choosen in such a way that only one entry for the user is
returned. If an user has more certifactes than these should be
collected under the attribute.
</dd>
<dt><span class="term"><span class="token">ssl</span></span></dt><dd>Enable or disable the usage of TLS or SSL
<div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><code class="option"> off </code> TLS/SSL off(default)
</li><li class="listitem"><code class="option"> tls </code> enable TLS
</li><li class="listitem"><code class="option"> on|ssl </code> enable SSL
</li></ul></div></dd>
<dt><span class="term"><span class="token">tls_randfile</span></span></dt><dd>Specifies the path to an entropy source.
</dd>
<dt><span class="term"><span class="token">tls_cacertfile</span></span></dt><dd>Specifies the path to the X.509 certificate for peer authentication.
</dd>
<dt><span class="term"><span class="token">tls_cacertdir</span></span></dt><dd>Specifies the directory containing X.509 certificates for peer authentication.
</dd>
<dt><span class="term"><span class="token">tls_checkpeer</span></span></dt><dd>Specifies whether to require and verify the server certificate or not.
<code class="option"> 1 </code> check the certificate
<code class="option"> 0 </code> off (default)
</dd>
<dt><span class="term"><span class="token">tls_ciphers</span></span></dt><dd>Specifies the ciphers to use.
</dd>
<dt><span class="term"><span class="token">tls_cert</span></span></dt><dd>Specifies the path to the file containing the local certificate for client TLS authentication if required.
</dd>
<dt><span class="term"><span class="token">tls_key</span></span></dt><dd>Specifies the path to the file containing the private key for client TLS authentication.
</dd>
</p></div><div class="sect2" title="12.4.5. OpenSC library mapper"><div class="titlepage"><div><div><h3 class="title"><a id="id375241"></a>12.4.5. OpenSC library mapper</h3></div></div></div><p>
Search certificate in <code class="filename">${HOME}/.eid/autorized_certificates</code>
in a similar way as OpenSC does. When used as login finder,
returns the user that owns ${HOME} directory where certificate
is found.
</p><p>
This mapper is still under development.
</p></div><div class="sect2" title="12.4.6. OpenSSH library mapper"><div class="titlepage"><div><div><h3 class="title"><a id="id375261"></a>12.4.6. OpenSSH library mapper</h3></div></div></div><p>
Search certificate public key in <code class="filename">${HOME}/.ssh/authorized_keys</code> in a similar way as OpenSSH does. The openssh mapper uses Naming Service Switch (<span class="symbol">NSS</span>) via <code class="function">getpwent()</code> to get the list of users and home directories
</p><p>
When used as login finder, returns the user that owns the
<code class="filename">authorized_keys</code> file where the public key is found. If several users share the same public key, returns first found login. On no public key match returns <span class="symbol">NULL</span>
</p><p>
When used as matcher, the module uses <code class="function">getpwnam()</code> to evaluate user home directory, then tries to open <code class="filename">${HOME}/.ssh/authorized_keys</code> file and finally tries to find a public key that matches with public keys found in certificate. Returns <span class="symbol">ok</span> if match found, or <span class="symbol">fail</span> on no match ( or process error )
</p><p>
Configuration file entry looks like:
</p><pre class="screen">
mapper openssh {
debug = false;
module = /usr/lib/pam_pkcs11/openssh_mapper.so;
}
</pre><p>
</p><p>
<em class="lineannotation"><span class="lineannotation">NOTE:</span></em>
This mapper is still under development.
</p></div><div class="sect2" title="12.4.7. Email Cert to login mapper"><div class="titlepage"><div><div><h3 class="title"><a id="id375335"></a>12.4.7. Email Cert to login mapper</h3></div></div></div><p>
Email mapper tries to extract an e-mail from certificate. If found
does following procedures:
</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"> if <code class="option">mapfile</code> option is set and file is provided, the module tries to map email field from the certificate to a user (or an alternate email).
</li><li class="listitem"> if <code class="option">mapfile</code> is not set, just use email
address from certificate to perform find/match
</li></ul></div><p>
</p><p>
Once we have a mapped user, module does:
</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"> When used as finder, just return email or mapped email/user
(see above)</li><li class="listitem"> When used as matcher, compare found email/user against provided
by PAM. </li></ul></div><p>
</p><p>
Additionally you can set <code class="option">ignorecase</code> or <code class="option">ignoredomain</code> flags:
</p><p>
Domain check (if set) is done by testing if provided email domain
part (@ie.this.domain) matches host domain.
</p><p>
E.g. <code class="filename">user@my.company.com</code> email in host <code class="filename">host.in.my.company.com</code>
host matches domain.
</p><p>
Configuration file entry looks like:
</p><pre class="screen">
mapper mail {
debug = false;
module = internal;
# module = /usr/lib/pam_pkcs11/mail_mapper.so;
# MapFile to use
mapfile = file:///etc/pam_pkcs11/mail_mapping;
# Some certs store email in uppercase. Take care on this
ignorecase = true;
# Also check that host matches mx domain
ignoredomain = false;
}
</pre><p>
</p><p>
Starting <span class="application">pam-pkcs11-0.5.3</span> this module is now statically linked, so no need to provide library pathname
</p></div><div class="sect2" title="12.4.8. Microsoft Universal Principal Name mapper"><div class="titlepage"><div><div><h3 class="title"><a id="id375426"></a>12.4.8. Microsoft Universal Principal Name mapper</h3></div></div></div><p>
Try to find and use Microsoft Universal Principal Name (UPN) extension
to evaluate login name.
</p><p>
Microsoft Universal Principal Name is a ASN1-encoded UTF8 string with
the syntax <code class="filename">login@ADS_Domain</code>. When an UPN is found,
the mapper extracts login part as login user. Then, if ignoredomain is unset, try to match domain.
</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"> When used as finder, returns UPN login as login name (or NULL on fail)</li><li class="listitem"> When used as matcher compares UPN login against PAM provided login</li></ul></div><p>
</p><p>
Configuration file entry looks like:
</p><pre class="screen">
mapper ms {
debug = false;
module = internal;
# module = /usr/lib/pam_pkcs11/ms_mapper.so;
ignorecase = false;
ignoredomain = false;
domainname = "domain.com";
}
</pre><p>
</p><p>
Starting <span class="application">pam-pkcs11-0.5.3</span> this module is now statically linked, so no need to provide library pathname
</p></div><div class="sect2" title="12.4.9. Kerberos mapper"><div class="titlepage"><div><div><h3 class="title"><a id="id375478"></a>12.4.9. Kerberos mapper</h3></div></div></div><p>
Try to find and use Kerberos Principal Name as login name. if mapfile is
specified, maps KPN into a login.
</p><p>
<em class="lineannotation"><span class="lineannotation">NOTES:</span></em>
</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem">Kerberos V5 Principal name syntax is assumed: <span class="emphasis"><em>component/component@realm</em></span>. It's supposed to be stored in ASN1String format in the certificate</li><li class="listitem"><p>This mapper does not perform <span class="application">PKINIT</span> Kerberos authentication, just retrieve and use KPN to map login name. (<span class="application">PKINIT</span> auth is still a work in progress)</p></li></ul></div><p>
</p><p>
Configuration entry:
</p><pre class="screen">
mapper krb {
debug = false;
module = internal;
# module = /usr/lib/pam_pkcs11/krb_mapper.so;
ignorecase = false;
mapfile = "none";
}
</pre><p>
</p><p>
Starting <span class="application">pam-pkcs11-0.5.3</span> this module is now statically linked, so no need to provide library pathname
</p></div><div class="sect2" title="12.4.10.  Unique ID to login mapper"><div class="titlepage"><div><div><h3 class="title"><a id="id375540"></a>12.4.10. Unique ID to login mapper</h3></div></div></div><p>
Use Unique ID (UID) field as login name.
</p><p>
Similar to CN mapper, but using UID as field to find/match.
</p><p>
Configuration entry:
</p><pre class="screen">
mapper uid {
debug = false;
module = internal;
# module = /usr/lib/pam_pkcs11/uid_mapper.so;
ignorecase = false;
mapfile = "none";
}
</pre><p>
</p><p>
Starting <span class="application">pam-pkcs11-0.5.3</span> this module is now statically linked, so no need to provide library pathname
</p></div><div class="sect2" title="12.4.11.  Certificate Digest to login mapper"><div class="titlepage"><div><div><h3 class="title"><a id="id375572"></a>12.4.11. Certificate Digest to login mapper</h3></div></div></div><p>
Evaluates a certificate digest, and try to map result into a login
by using a mapfile.
</p><p>
Configuration file should provide the digest algorithm. Depending
on <span class="application">OpenSSL</span> configuration all of listed
bellow may or not be present in your system.
</p><p>
Configuration entry:
</p><pre class="screen">
mapper digest {
debug = false;
module = internal;
# module = /usr/lib/pam_pkcs11/digest_mapper.so;
# Algorithm used to evaluate certificate digest
# Select one of:
# "null","md2","md4","md5","sha","sha1","dss","dss1","ripemd160"
algorithm = "sha1";
mapfile = file:///etc/pam_pkcs11/digest_map;
}
</pre><p>
</p><p>
Starting <span class="application">pam-pkcs11-0.5.3</span> this module is now statically linked, so no need to provide library pathname
</p></div><div class="sect2" title="12.4.12. Generic mapper"><div class="titlepage"><div><div><h3 class="title"><a id="id375613"></a>12.4.12. Generic mapper</h3></div></div></div><p>
This mapper groups several mappers in one. You can select which certificate
content should be used to deduce/match login, optionally perform a file
mapping, and, if desired consult mapped string to NSS services to get
final user login.
</p><p>
Three arguments are needed:
</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem">The certificate field to be used. Allowed values are:
<div class="itemizedlist"><ul class="itemizedlist" type="circle"><li class="listitem">"<span class="symbol">cn</span>" To use Certificate CommonName</li><li class="listitem">"<span class="symbol">subject</span>" To use Certificate Subject</li><li class="listitem">"<span class="symbol">kpn</span>" To use Kerberos PrincipalName</li><li class="listitem">"<span class="symbol">email</span>" To use Certificate Email</li><li class="listitem">"<span class="symbol">upn</span>" To use Microsoft Universal Principal Name</li><li class="listitem">"<span class="symbol">uid</span>" To use Certificate UniqueID</li></ul></div></li><li class="listitem">
A map file name or "none" if no mapping is desired
</li><li class="listitem">
A "use_getpwent" flag, to decide if NSS services are required
</li></ul></div><p>
</p><p>
Note that fields are taken literally: i.e. no post-processing is done,
just take string "as is", and pass it to next step. So if you need some
data processing (i.e. use ADS name field in upn) this mapper is not for
you.
</p><p>
The first step is extract string from certificate. If a mapping file is required, the string is mapped against mapfile, obtaining a new string. If use_pwent is also required, the mapper compare last one against <span class="symbol">pw_login</span> or <span class="symbol">pw_gecos</span>. If a match is done, the <span class="symbol">pw_login</span> is returned as user login.
</p><p>
When module is user as login finder, returns result of above operations. When user as login matcher, compares provided login with above result.
</p><p>
generic_mapper configuration file shows like:
</p><pre class="screen">
mapper generic {
debug = true;
module = internal;
# module = /usr/lib/pam_pkcs11/generic_mapper.so;
# ignore letter case on match/compare
ignorecase = false;
# Use one of "cn" , "subject" , "kpn" , "email" , "upn" or "uid"
cert_item = cn;
# Declare mapfile if needed, else select "none"
mapfile = file:///etc/pam_pkcs11/generic_mapfile
# Decide if use getpwent() to map login
use_getpwent = false;
}
</pre><p>
</p><p>
<em class="lineannotation"><span class="lineannotation">Note:</span></em>
</p><p>
As for every other mappers, <span class="application">pklogin_finder</span> tool, doesn't perform the entire process, just returns certificate contents.
</p><p>
Starting <span class="application">pam-pkcs11-0.5.3</span> this module is now statically linked, so no need to provide library pathname
</p></div><div class="sect2" title="12.4.13. Null mapper"><div class="titlepage"><div><div><h3 class="title"><a id="id375750"></a>12.4.13. Null mapper</h3></div></div></div><p>
Blind access/deny mapper.
</p><p>
If <code class="option">default_match</code> is set to true:
</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"> When used as finder always returns configuration provided <code class="option">default_user</code> (default: "nobody")</li><li class="listitem"> When used as matcher always returns <span class="emphasis"><em>OK</em></span></li></ul></div><p>
</p><p>
If <code class="option">default_match</code> is set to false:
</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"> When used as finder always returns <span class="emphasis"><em>NULL</em></span></li><li class="listitem"> When used as matcher always returns <span class="emphasis"><em>FAIL</em></span></li></ul></div><p>
</p><p>
Configuration entry:
</p><pre class="screen">
mapper null {
debug = false;
module = internal;
# module = /usr/lib/pam_pkcs11/null_mapper.so;
# select behaviour: always match, or always fail
default_match = false;
# on match, select returned user
default_user = nobody;
}
</pre><p>
</p><p>
<em class="lineannotation"><span class="lineannotation">NOTE:</span></em>
This mapper should be the last one in the mapper chain, as it always
return valid -- although meaningless -- data
</p><p>
Starting <span class="application">pam-pkcs11-0.5.3</span> this module is now statically linked, so no need to provide library pathname
</p></div></div><div class="sect1" title="12.5. Adding new mappers"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="id375830"></a>12.5. Adding new mappers</h2></div></div></div><p>
Creating new mappers is easy: just retrieve and study the
<a class="ulink" href="mappers_api.html" target="_top">PAM-PKCS#11 Mapper API reference Manual</a>
</p><p>
You'll find sample code, compiling instructions, and a complete list
of provided library calls
</p></div></div><div class="chapter" title="Chapter 13. Wish list"><div class="titlepage"><div><div><h2 class="title"><a id="todo"></a>Chapter 13. Wish list</h2></div></div></div><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem">
Make all mappers to use an unified library
</li><li class="listitem">
Only ask for PIN only when needed (to extract private key for signature verification or pkinit challenge process)
</li><li class="listitem">
Check that certificate is valid for authentication instead of using first found cert
</li><li class="listitem">
Finish coding all mappers (OpenSSH, OpenSSL, LDAP to be done)
</li><li class="listitem">
Implement pkinit to talk Kerberos server
</li><li class="listitem">
Debug. I cannot test all cases
</li><li class="listitem">
Lots of docs and samples needs to be written
</li><li class="listitem">
Check data types on same certificate contents instead of assume utf8or asn1string
</li><li class="listitem">
Define and document a mapper API. Create pam_pkcs11-devel package
</li></ol></div></div><div class="chapter" title="Chapter 14. Contact"><div class="titlepage"><div><div><h2 class="title"><a id="contact"></a>Chapter 14. Contact</h2></div></div></div><p>
Any comments, suggestions and bug reports are welcome. Please, mention
the keywords 'pkcs' and 'pam' in the subject.
</p><p>
Juan Antonio Martinez <code class="email"><<a class="email" href="mailto:jonsito at teleline.es">jonsito at teleline.es</a>></code>
</p><p>
Mario Strasser <code class="email"><<a class="email" href="mailto:mast at gmx.net">mast at gmx.net</a>></code>
</p></div></div></body></html>
