File: pam_pkcs11.psarc_summary ========================================== 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. The original source of this module is provided by opensc-project.org. The latest version is 0.6.0 which supports only the pam_authenticate() function for the authentication service. For more information, see http://www.opensc-project.org/pam_pkcs11 This pam_pkcs11 module supports any PKCS#11 token library. On Solaris, the PKCS#11 library to be used for this module is /usr/lib/libpkcs11.so.1, the Solaris Cryptographic Framework. A user can configure the pam_pkcs11 module to use a specific slot/token. Note that the original pam_pkcs11 module from OpenSC uses slot number for the slot/token selection which is not always safe because there is no guaranteed ordering of slots returned from the PKCS#11 C_GetSlotList() function. To resolve this, on Solaris, the slot/token selection is changed to use the slot description instead. ========================================================= The pam_pkcs11 authentication/verification procedure ========================================================= The authentication and verification procedure is as following: Step 1: Find all the certificates in the PKCS#11 token Step 2: Find the certificate in the certificate list that matches the user For each certificate in the certificate list Verify the certificate to see if it is really issued by the CA certificate or if it has been revoked, based on the certificate verification policy specified in the configuration. If the certificate is valid, then check if it matches the user by using the certificate-to-user mappers specified in the configuration. If a good certificate is found, we are done Step 3: Signature verification If the "signature" policy is specified in the certificate verification policy in the configuration, then this module will find the private key on the token that is associated with the certificate and verify the public key inside the certificate and the private key are truly a pair with following algorithm: - 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 /usr/share/man/man1/pklogin_finder.1 /usr/share/man/man1/pkcs11_eventmgr.1 /usr/share/man/man1/pkcs11_inspect.1 ================================================== A usage example ================================================== The following example demonstrates how to use the pam_pkcs11 module with the Solaris cryptographic framework and the Solaris PKCS#11 softtoken to authenticate a user to log into a system. Set up a certificate with private key in the Solaris PKCS#11 softtoken: - Initialize the Solaris softtoken keystore with the "pktool setpin" command. - 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. Configure the pam_pkcs11 module: - The /etc/security/pam_pkcs11/pam_pkcs11.conf file is the configuration file for the pam_pkcs11 module. A user should modify this file to configure the pam_pkcs11 module. In this example, we will use default values for all the entries. - 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. Configure the /etc/pam.conf file: The pam_pkcs11.so service module can be used in the PAM chain. In this example, we will use only pam_pkcs11 for authentication. login auth requisite pam_pkcs11.so.1 login auth required pam_unix_cred.so.1 Test: To test result, run "exec login" as below: -------------------------------------------------------------------- hylee@bula$exec login Please insert your smart card or enter your username. login: hylee found the PKCS#11 slot with a token. Welcome Sun Software PKCS#11 softtoken! token password: XXXXXXXX Last login: Tue Feb 26 14:13:41 from comforter Sun Microsystems Inc. SunOS 5.11 snv_80 Dec. 15, 2007 SunOS Internal Development: root 2007-12-15 [onnv_80] bfu'ed from /ws/onnv-gate/archives/sparc/snv_80 on 2007-12-19 Sun Microsystems Inc. SunOS 5.11 snv_76 October 2007 --------------------------------------------------------------------