==========================================
The pam_pkcs11 module overview
==========================================
The pam_pkcs11 module is a PAM authentication module for PKCS#11 token
libraries.  This module allows a user to login a system that supports PAM,
using a certificate and its dedicated private key stored in a PKCS#11 token.

This pam_pkcs11 module supports any PKCS#11 token library, however, it
is typically used by a Smart-card PKCS#11 token. 

The original source of this module is provided by opensc-project.org.
The latest version is 0.6.0 which supports only the authentication service.
It does not support pam_setcred, pam_acct_mgmt, or other services.

For more information, see http://www.opensc-project.org/pam_pkcs11

=========================================================
The pam_pkcs11 authentication/verification procedure
=========================================================
The authentication and verification procedure is as following:

Step 1: Find all certificate/private_key pair in the PKCS#11 token

Step 2: Find the certificate/private_key pair that matches the user

    For each pair of the certificate and its associated private key

        Validate the certificate by using the CA certificate and CRL files.
           
        If the certificate is valid, then check if it matches the user
        by using the mappers based on the pam_pkcs11 configuration.

	If a good pair is found, we are done

Step 3: Verification procedure

    To verify the private key on the token is truly associated with the
    certificate, this module performs the following verification procedure.

    - Generates 128 random byte data.

    - Use the private key to  sign the data and get a signature.
      (This will be done in the PKCS11 token).
      
   - Extract the public key from the certificate and verify the signature. 

==========================================
Deliverables:
==========================================
Pam_pkcs11 module:

  /usr/lib/security/pam_pkcs11.so

  (Note: will support both 32bit and 64 bit versions.)

Non-built-in Mapper modules:

  /usr/lib/pam_pkcs11/ldap_mapper.so
  /usr/lib/pam_pkcs11/opensc_mapper.so
  /usr/lib/pam_pkcs11/openssh_mapper.so

  (Note: will support both 32bit and 64 bit versions.)

Configuration directories and files:

  /etc/security/pam_pkcs11/pam_pkcs11.conf
  /etc/security/pam_pkcs11/pkcs11_eventmgr.conf
  /etc/security/pam_pkcs11/cacerts (The directory to store the CA certificates)
  /etc/security/pam_pkcs11/crls (The directory to store the CRL files)

Sample Mapfiles and script:

  /etc/security/pam_pkcs11/digest_mapping.example
  /etc/security/pam_pkcs11/subject_mapping.example
  /etc/security/pam_pkcs11/mail_mapping.example
  /etc/security/pam_pkcs11/make_hash_link.sh
     
Utility commands:

  /usr/lib/pam_pkcs11/pkcs11_inspect
  /usr/lib/pam_pkcs11/pklogin_finder
  /usr/lib/pam_pkcs11/pkcs11_eventmgr

  (Note: will support both 32bit and 64bit versions.)

man pages:

  /usr/share/man/man5/pam_pkcs11.5.sunman
  /usr/share/man/man1/pklogin_finder.1
  /usr/share/man/man1/pkcs11_eventmgr.1
  /usr/share/man/man1/pkcs11_inspect.1


==================================================
A usage example:
==================================================
Setup:

- Add the pam_pkcs11.so module to the /etc/pam.conf file as below:

  login   auth sufficient         pam_pkcs11.so

- Create a self-signed certificate in the Solaris Softtoken keystore, using
  the "pktool gencert" command.

- Export the certificate file from the Solaris Softtoken keystore, using
  the "pktool export" command.

- Copy the CA certificate to the /etc/security/pam_pkcs11/cacerts directory
  and make a hash link with the make_hash_link.sh script.
  
  Note: A certificate that is self-signed is its own CA certificate. Therefore,
        in this example, the certificate is placed both in the keystore and 
        in the CA certificate directory.

- Set up the map files in the /etc/security/pam_pkc11 directory.

  Note: When a X509 certificate is provided, there are no direct ways to map a 
        certificate to a login.  The pam_pkcs11 module provides a configurable
        way with  mappers to specify cert-to-user mapping.   Many mappers are
        provided  by Pam_pkcs11, for example, the common name (CN) mapper,
        the digest mapper, the Email mapper, or the LDAP mapper.

        A user can configure a mapper list in the pam_pkcs11.conf file.  The 
        mappers in the list will be used sequentially until the certificate 
        is successfully matched with the user.

        Some mappers do not require a mapfile to be specified (eg. the CN
        mapper), while some other mappers do require a mapfile (eg. the digest
        mapper) in the /etc/pam_pkcs11 directory.  


Run:
------------------------------------------------------------------------
hylee@bula$exec login
Please insert your smart card or enter your username.
login: hylee
Smart card inserted.
Welcome Sun Metaslot!
Smart card password: XXXXXX
Last login: Wed Sep 12 15:10:29 from comforter
Sun Microsystems Inc.   SunOS 5.11      snv_65  October 2007
------------------------------------------------------------------------

Note that the "Smart card password" is the Solaris softtoken keystore
password.