Go to main content

man pages section 7: Standards, Environments, Macros, Character Sets, and Miscellany

Exit Print View

Updated: Wednesday, July 27, 2022
 
 

pam_pkcs11 (7)

Name

pam_pkcs11 - PAM Authentication Module for the PKCS#11 token libraries

Synopsis

pam_pkcs11.so [debug] [config_file=filename]

Description

Standards, Environments, and Macros                              pam_pkcs11(7)



NAME
       pam_pkcs11 - PAM Authentication Module for the PKCS#11 token libraries

SYNOPSIS
       pam_pkcs11.so [debug] [config_file=filename]


DESCRIPTION
       The  pam_pkcs11 module implements pam_sm_authenticate(3PAM), which pro-
       vides functionality to the PAM authentication stack. This module allows
       a  user  to login a system, using a X.509 certificate and its dedicated
       private key stored in a PKCS#11 token. This module  currently  supports
       the RSA algorithm only.


       To  verify the dedicated private key is truly associated with the X.509
       certificate, the following verification procedure is performed in  this
       module by default:

           o      Generate 128 random byte data

           o      Sign  the  random data with the private key and get a signa-
                  ture. This step is done in the PKCS#11 token.

           o      Verify the signature using the public key extracted from the
                  certificate.


       For the verification of the users' certificates, locally stored CA cer-
       tificates as well as either online or locally accessible CRLs are used.

   PAM CONFIGURATION
       The pam_pkcs11.so service module can be used in the <auth>  PAM  chain.
       The   program  that  needs  a  PAM  service  should  be  configured  in
       /etc/pam.conf or /etc/pam.d/service. For details on  how  to  configure
       PAM services, see pam.conf(5).


       The following example uses only pam_pkcs11 for authentication:

         login auth requisite pam_pkcs11.so.1
         login autho required pam_unix_cred.so.1



       The  following example uses pam_pkcs11 for authentication with fallback
       to standard UNIX authentication:

         login auth sufficient pam_pkcs11.so.1
         login auth requisite  pam_authtok_get.so.1
         login auth required   pam_dhkeys.so.1
         login auth required   pam_unix_cred.so.1
         login auth required   pam_unix_auth.so.1


   PAM_PKCS11 CONFIGURATION
       To configure the pam_pkcs11 module, you must have the following  infor-
       mation:

           o      Which PKCS #11 token you are going to use

           o      Which  mapper(s)  you need, and if needed, how to create and
                  edit the related mapping files

           o      The root Certificate Authority files, and if  required,  the
                  Certificate Revocation Lists files

           o      The list of authorized users to login, and their correspond-
                  ing certificates


       To  configure  the  pam_pkcs11  module,  you   need   to   modify   the
       pam_pkcs11.conf   configuration   file   which  is  in  the  /etc/secu-
       rity/pam_pkcs11 directory by default. For detailed information  on  how
       to  configure  the  pam_pkcs11  module, see the PAM-PKCS11 User Manual,
       available at the http://www.opensc-project.org/ web site, under the PAM
       PKCS#11 link.


       The  following example illustrates how to configure the pam_pkcs11 mod-
       ule for a user whose certificate and private  key  are  stored  in  the
       Solaris  pkcs11_softtoken  keystore. This example uses the default cer-
       tificate verification policy.

           o      Set up the PKCS#11 module.

                  On  Solaris,  the  PKCS#11   module   should   be   set   to
                  /usr/lib/$ISA/libpkcs11.so.1,   the   PKCS#11  Cryptographic
                  Framework library.

           o      Set up the slot_description entry.

                  Specifies the slot to be used. For example, slot_description
                  =  "Sun  Crypto Softtoken". The default value for this entry
                  is none which means to use the first slot with an  available
                  token.

                  An  administrator  can  use  the cryptoadm list -vcommand to
                  find all the available slots and  their  slot  descriptions.
                  For more information, see libpkcs11(3LIB) and cryptoadm(8).

           o      Install  or  create user certificates and its dedicated pri-
                  vate keys in the specific PKCS#11 token.

           o      Set up the certificate verification policy (cert_policy). If
                  needed, set up CA certificate and CRL files.

                  The certificate verification policy includes:


                  none         Perform no verification


                  ca           Perform CA check


                  signature    Perform  a  signature check to ensure that pri-
                               vate and public key matches


                  crl_xxx      Perform various certificate revocation checking


           As this example uses the default policy,  cert_policy  =  ca,signa-
           ture, an administer needs to set up the CA certificates.

               o      Copy    the    CA    certificate   to   the   /etc/secu-
                      rity/pam_pkcs11/cacerts directory.

                      A certificate that is self-signed is its own CA certifi-
                      cate.  Therefore,  in  this  example, the certificate is
                      placed both in the Softtoken keystore and in the CA cer-
                      tificate directory.

               o      Make hash links for CA certificates

                        $ /etc/security/pam_pkcs11/pkcs11_make_hash_link \
                              /etc/security/pam_pkcs11/cacerts



           o      Set up the mappers and mapfiles.

                  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  the  pam_pkcs11  module,  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 are used sequentially until
                  the certificate is successfully matched with the user.

                  The default mapper list is as follows:

                    use_mappers = digest, cn, pwent, uid, mail, subject, null;


                  Some mappers do not require the specification of a  mapfile,
                  for  example,  the common name mapper. Other mappers require
                  mapfiles, for example, the digest mapper. Some  sample  map-
                  ping  files  can  be  found  in the /etc/security/pam_pkcs11
                  directory.

           All the modules (PKCS#11 module and mapper  modules)  specified  in
           the   /etc/security/pam_pkcs11/pam_pkcs11.conf  configuration  file
           need to be delivered in both 32-bit and 64-bit forms.

           The $ISA (instruction set architecture) token  in  all  the  module
           paths is replaced by an implementation-defined directory name which
           defines the path relative to the calling program's instruction  set
           architecture.  The  $ISA  token  should  be  used in all the module
           paths. This allows the pam_pkcs11 module to support both 32 and  64
           bit  applications  concurrently on the system. For example, for the
           "module  =  /usr/lib/$ISA/libpkcs11.so"  option,   at   run   time,
           /usr/lib/64/libpkcs11.so will be loaded for 64-bit applications and
           /usr/lib/32/libpkcs11.so for 32-bit applications.

OPTIONS
       The following options are supported:

       config_file=filename    Specify the  configuration  file.  The  default
                               value               is               /etc/secu-
                               rity/pam_pkcs11/pam_pkcs11.conf.


       debug                   Enable debugging output.


FILES
       /usr/lib/security/pam_pkcs11.so

           pam_pkcs11 module


       /usr/lib/pam_pkcs11/$ISA/ldap_mapper.so

           Mapper module.


       /usr/lib/pam_pkcs11/$ISA/opensc_mapper.so

           Mapper module.


       /usr/lib/pam_pkcs11/$ISA/openssh_mapper.so

           Mapper module.


       /etc/security/pam_pkcs11/pam_pkcs11.conf

           Configuration file.


       /etc/security/pam_pkcs11/cacerts

           Configuration directory. Stores the CA certificates.


       /etc/security/pam_pkcs11/crls

           Configuration directory. Stores the CRL files.


       /etc/security/pam_pkcs11/digest_mapping.example

           Sample mapfile.


       /etc/security/pam_pkcs11/subject_mapping.example

           Sample mapfile.


       /etc/security/pam_pkcs11/mail_mapping.example

           Sample mapfile.


       /etc/security/pam_pkcs11/make_hash_link.sh

           Sample script.


AUTHORS
       PAM-pkcs11 was originally written by MarioStrasser , mast@gmx.net.


       Newer versions are from Juan Antonio Martinez, jonsito@teleline.es

ATTRIBUTES
       See attributes(7) for a description of the following attributes:




       +-----------------------------+-----------------------------+
       |      ATTRIBUTE TYPE         |      ATTRIBUTE VALUE        |
       +-----------------------------+-----------------------------+
       |Availability                 |library/security/pam/mod-    |
       |                             |ule/pam-pkcs11,   SUNWpamp-  |
       |                             |kcs11r, SUNWpampkcs11-docs   |
       +-----------------------------+-----------------------------+
       |Interface Stability          |Uncommitted                  |
       +-----------------------------+-----------------------------+

SEE ALSO
       card_eventmgr(1), pkcs11_inspect(1),  pklogin_finder(1),  cryptoadm(8),
       libpkcs11(3LIB)libpkcs11(3LIB)pam_sm_authenticate(3PAM),   pam.conf(5),
       attributes(7), pkcs11_softtoken(7)


       PAM-PKCS11         User          Manual,          available          at
       /usr/share/doc/pam_pkcs11/pam_pkcs11.html.



Solaris 11.4                      14 Oct 2016                    pam_pkcs11(7)