Go to main content

Managing Kerberos and Other Authentication Services in Oracle® Solaris 11.3

Exit Print View

Updated: May 2019
 
 

Configuring PAM for Smart Cards

The pam_pkcs11 login module enables X.509 certificate-based user authentication, the certificate that resides on the CACKey and Coolkey smart cards. The module uses the name service switch (NSS) to manage and validate PKCS #11 smart cards either from locally accessible certificate revocation lists (CRLs) or from the Online Certificate Status Protocol (OCSP).

All Oracle Solaris logins go through PAM. To enable smart card authentication for a user, you add information from the user's smart card to PAM files.

    In the /etc/security/pam_pkcs11 directory, you create or modify the following files:

  • pam_pkcs11.conf – Identifies the CACKey or Coolkey cryptographic module, contains some information from the smart card, and points to mapping files

  • subject_mapping – Maps the subject on a smart card's X.509 certificate to the card's login user or to an additional role that the user can assume, such as root

  • cn_map – Maps the smart card's X.509 certificate name (CN) to the login user's CN or to the CN of an additional role that the login user can assume, such as root

Then, the auth PAM stack for all logins is modified to require a second authentication step. This second step uses the PKCS #11 library to verify the X.509 certificate on the smart card and requires the user to supply the smart card PIN.

How to Display a Smart Card's X.509 Certificate

In this procedure, you configure pam_pkcs11 to recognize a smart card that uses either CACKey or Coolkey as its cryptographic module. This configuration includes support for smart card authentication to Secure Shell.

After this preparation, you use this information to configure the user's smart card access in.

Before You Begin

You must assume the root role. For more information, see Using Your Assigned Administrative Rights in Securing Users and Processes in Oracle Solaris 11.3.

You have completed How to Use the OpenSSH Implementation of Secure Shell in Managing Secure Shell Access in Oracle Solaris 11.3 and are running the OpenSSH version of Secure Shell. A smart card reader with a user's smart card in it is attached to your Oracle Solaris system. The system has the pcsclite and ccid packages installed.

  1. If you have not yet enabled the pcsc service, enable it.
    # svcadm enable pcsc

    This service starts the pcscd daemon, which the pam_pkcs11 module uses to communicate with the smart card.

  2. Copy the pam_pkcs11.conf file to pam_pkcs11.conf.orig.
    # cd /etc/security/pam_pkcs11
    # cp pam_pkcs11.conf pam_pkcs11.conf.orig
  3. Configure PAM to use the CACKey or Coolkey cryptographic module for the smart card.

    Add the appropriate module to the pam_pkcs11.conf file.

    • In the pam_pkcs11.conf file, find and change the use_pkcs11_module definition to CACKey.
      # pfedit /etc/security/pam_pkcs11/pam_pkcs11.conf
      use_pkcs11_module = cackey;

      Following that line, add support for CACKey.

      # CACKey support
      pkcs11_module cackey {
           module = /usr/lib/$ISA/libcackey.so;
           description = "CACKey";	
           slot_num = 0;
           support_threads = false;
           ca_dir =/etc/security/pam_pkcs11/cacerts;
           crl_dir =/etc/security/pam_pkcs11/crls;
           cert_policy = none;
           crl_policy = none;
        }
    • In the pam_pkcs11.conf file, find and change the use_pkcs11_module definition to Coolkey.
      # pfedit /etc/security/pam_pkcs11/pam_pkcs11.conf
      use_pkcs11_module = coolkey;

      Following that line, add support for Coolkey.

      # Coolkey support
      pkcs11_module coolkey {
           module = /usr/lib/$ISA/libcoolkeypk11.so;
           description = "Coolkey";	
           slot_num = 0;
           support_threads = false;
           ca_dir =/etc/security/pam_pkcs11/cacerts;
           crl_dir =/etc/security/pam_pkcs11/crls;
           cert_policy = none;
           crl_policy = none;
        }
  4. Still in the pam_pkcs11.conf file, find and change the use_mappers definition.

    This entry indicates the certificate parameters that can verify the certificate.

    use_mappers = cn, subject, openssh, null;

    A full list of supported mappers is in the pam_pkcs11.conf file.

  5. Find and change the mapper subject definition.
      # Certificate Subject to login based mapper
      # provided file stores one or more "Subject -> login" lines
      mapper subject {
           debug = false;
           module = internal;
           ignorecase = false;
           mapfile = file:///etc/security/pam_pkcs11/subject_mapping;
      }

    You will create the subject_mapping mapfile in How to Configure PAM for 2FA With Smart Cards.

  6. Find and change the mapper cn definition.
    mapper cn {
           debug = true;
           module = internal;
           ignorecase = true;
           mapfile = file:///etc/security/pam_pkcs11/cn_map;
      }

    You will create the cn_map mapfile in How to Configure PAM for 2FA With Smart Cards.

  7. Find and change the mapper openssh definition.
      # Search public keys from user's $HOME/.ssh/authorized_keys for match
      mapper openssh {
           debug = false;
           module = /usr/lib/pam_pkcs11/$ISA/openssh_mapper.so;
      }
  8. Exit the pam_pkcs11.conf file.
  9. Set restrictive permissions on the pam_pkcs11.conf file.
    # chmod 644 pam_pkcs11.conf
  10. Verify that you can view the information on the user's smart card.
    1. In a terminal window, run the pkcs11_inspect command.
      # /usr/lib/pam_pkcs11/pkcs11_inspect
    2. Type the user's smart card PIN at the prompt.

      After you type the PIN, X.509 certificate information from the user's smart card should appear. For sample output, see Step 1 in How to Configure PAM for 2FA With Smart Cards.

Next Steps

Continue with How to Configure PAM for 2FA With Smart Cards to complete PAM configuration for smart card authentication.

How to Configure PAM for 2FA With Smart Cards

This procedure shows how to complete the configuration of the pam_pkcs11 module to authenticate smart card users. The example in the procedure is of U.S. Government-issued CACKeys. You must follow these steps for every smart card user.

Before You Begin

You have completed How to Display a Smart Card's X.509 Certificate.

You must assume the root role. For more information, see Using Your Assigned Administrative Rights in Securing Users and Processes in Oracle Solaris 11.3.

  1. Display the information on the user's smart card.
    # /usr/lib/pam_pkcs11/pkcs11_inspect

    After you type the PIN, X.509 certificate information from the user's smart card should appear similar to the following:

    PIN for token: 
    Printing data for mapper cn:
    LNAME.FNAME.ID
    Printing data for mapper subject:
    /C=US/O=U.S. Government/OU=DoD/OU=PKI/OU=Division/CN=LNAME.FNAME.ID
    Printing data for mapper openssh:
    ssh-rsa AAAAB3NzaC1yc2EAAAA ...
    ... fname.lname@example.org
    Printing data for mapper cn:
    LNAME.FNAME.ID
    Printing data for mapper subject:
    /C=US/O=U.S. Government/OU=DoD/OU=PKI/OU=Division/CN=LNAME.FNAME.ID
    Printing data for mapper openssh:
    ssh-rsa AAAAB3NzaC1yc2EAAAA ... 
    ... fname.lname@example.org
    ...
    Printing data for mapper cn:
    DoD Root CA ...
    ...
    Printing data for mapper subject:
    /C=US/O=U.S. Government/OU=DoD/OU=PKI/CN=DOD Root CA
    
    Printing data for mapper cn:
    DOD CA-30
    
    Printing data for mapper subject:
    /C=US/O=U.S. Government/OU=DoD/OU=PKI/CN=DOD CA-30
    ...
  2. Create the subject_mapping file.

    Copy the file from /etc/security/pam_pkcs11/subject_mapping.example.

    # cd /etc/security/pam_pkcs11
    # cp subject_mapping.example subject_mapping
  3. In the subject_mapping file, map the user's subject value from their X.509 certificate to their login name.

    The format line describes the mapping format.

    Use the value from the line that follows the first instance of Printing data for mapper subject:, for example:

    /C=US/O=U.S. Government/OU=DoD/OU=PKI/OU=Division/CN=LNAME.FNAME.ID
    # Mapping file for Certificate Subject
    # format: Certificate Subject -> login
    #
    ## User certificates
    /C=US/O=U.S. Government/OU=DoD/OU=PKI/OU=Division/CN=LNAME.FNAME.ID -> login
    ...
    ## Root certificate authority
    ...

    Smart cards that are not issued by the U.S. government have different values for certificate subjects.


    Note -  If the root account has a unique smart card, treat root as a user and map root's certificate name from the X.509 certificate to the root login name.
  4. (Optional) If the smart card user is allowed to assume other roles, such as root, map the correct certificate from the card to the correct identity.
    • In this example, the certificate for the root CA is the certificate for the root role.

      # pfedit subject_mapping
      # Mapping file for Certificate Subject
      # format: Certificate Subject -> login
      #
      ## User certificates
      ...
      ## Certificate name mapped to the root account
      /C=US/O=U.S. Government/OU=DoD/OU=PKI/CN=DOD CA-3 -> root
    • In this example, the certificate for the root role is different from the root CA certificate.

      # pfedit subject_mapping
      # Mapping file for Certificate Subject
      # format: Certificate Subject -> login
      #
      ## User certificates
      ...
      ## Certificate name mapped to the root account
      /C=US/O=U.S. Government/OU=DoD/OU=PKI/CN=DOD CA-30 -> root
    • In this example, the DOD CA-29 certificate subject maps to the sysadmin role.

      # pfedit subject_mapping
      # Mapping file for Certificate Subject
      # format: Certificate Subject -> login
      #
      ## User certificates
      ...
      ## Certificate name mapped to the sysadmin role
      /C=US/O=U.S. Government/OU=DoD/OU=PKI/CN=DOD CA-29 -> sysadmin

    Smart cards that are not issued by the U.S. government have different values for certificate names.

  5. Map CN values in the cn_map file.
    • Create the /etc/security/pam_pkcs11/cn_map file.

    • Map the user's certificate name from the X.509 certificate to the user's login name.

    • If the user can assume a role, map the appropriate certificate name to the role.

    # pfedit cn_map
    # Mapping file for Certificate Name
    # format: Certificate Name -> login
    #
    ## User certificate names
    LNAME.FNAME.ID -> loginmany user entries
    
    ## Certificate name mapped to the root account
    DOD CA-3 -> root
  6. Set restrictive permissions on the mapping files.
    # chmod 644 cn_map subject_mapping
  7. Add pam_pkcs11 as the first module in the auth stack of the login PAM configuration file.
    # cd /etc/pam.d
    # cp login login.orig
    # pfedit login
    # login service (explicit because of pam_dial_auth)
    #
    ## pam_pkcs11 enables smart card logins
    auth sufficient         pam_pkcs11.so
    auth definitive         pam_user_policy.so.1
    ...
  8. Modify the other file similarly.
    # cp other other.orig
    # pfedit other
    # Default definitions for Authentication management
    # Used when service name is not explicitly mentioned for authentication
    #
    ## pam_pkcs11 enables smart card logins
    auth sufficient         pam_pkcs11.so
    auth definitive         pam_user_policy.so.1
    ...
  9. Test the PAM configuration.
    1. Log in to a local desktop.
    2. Log in to a remote desktop.
    3. Log in by using the ssh command.
    4. Log in by using a local console.

    For more information about PAM and testing, see Chapter 1, Using Pluggable Authentication Modules in Managing Kerberos and Other Authentication Services in Oracle Solaris 11.3.