<?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>