This 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.

Detailed information about the Linux-PAM system can be found in The Linux-PAM System Administrators' Guide, The Linux-PAM Module Writers' Guide and The Linux-PAM Application Developers' Guide The specification of the Cryptographic Token Interface Standard (PKCS#11) is available at PKCS#11 - Cryptographic Token Interface Standard.

PAM-PKCS#11 package provides:

• A PAM module able to:
  • Use certificates to get user credentials
  • Deduce a login based on provided certificate
• Several tools:
  • Standalone cert-to-login finder tool
  • Certificate contents viewer
  • Card Event status monitor, to trigger actions on card insert/removal

You can read the online PAM-PKCS#11 User Manual to know how to install, configure and use this software.

The PKCS#11 modules must fulfill the requirements given by the RSA Asymmetric Client Signing Profile, which has been specified in the PKCS#11: Conformance Profile Specification by RSA Laboratories.

To map the ownership of a certificate into a user login, pam-pkcs11 uses the concept of mapper that is, a list of configurable, stackable list of dynamic modules, each one trying to do a specific cert-to-login mapping. Several mappers are provided:

• the common name of the subject matches the login name
• the unique identifier of the subject matches the login name
• the user part of an e-mail subject alternative name extension matches the login name
• the Microsoft universal principal name extension matches the login name
• etc...(see documentation on provided mappers)

Many mappers may use also a mapfile to translate Certificate contents to a login name.

• pam_pkcs11-x.y.z.tar.gz

Packages for various Linux distributions are available through the their standard package management system.

Unpack the archive, configure, compile and install it:

tar xvzf pkcs11_login-X.Y.Z.tar.gz
cd pkcs11_login-X.Y.Z
./configure
make
sudo make install

If you want to use cURL instead of our native URI-functions for downloading CRLs, use ./configure --with-curl

However, up to now cURL is not able to handle binary LDAP replies and thus CRL download might not work for all LDAP URIs.

Next, you have to create the needed openssl-hash-links.

make_hash_link.sh ${path to the directory with the CA certificates}
make_hash_link.sh ${path to the directory with the CRLs}

See PAM-PKCS#11 User Manual to configure and set up pam_pkcs11.

See PAM-PKCS#11 Mappers API to get advanced information on mappers (mainly for developers).

• Online Manuals
• PAM-PKCS#11 User Manual
• PAM-PKCS#11 Mappers API Reference
• TODO file (outdated)
• Man pages
  • pam_pkcs11(8)
  • card_eventmgr(1)
  • pkcs11_eventmgr(1)
  • pklogin_finder(1)
  • pkcs11_inspect(1)

Get involved in development! All comments, suggestions and bug reports are welcome.