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.
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.
# svcadm enable pcsc
This service starts the pcscd daemon, which the pam_pkcs11 module uses to communicate with the smart card.
# cd /etc/security/pam_pkcs11 # cp pam_pkcs11.conf pam_pkcs11.conf.orig
Add the appropriate module to the pam_pkcs11.conf file.
# 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; }
# 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; }
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.
# 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.
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.
# 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; }
# chmod 644 pam_pkcs11.conf
# /usr/lib/pam_pkcs11/pkcs11_inspect
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.
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.
# /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 ...
Copy the file from /etc/security/pam_pkcs11/subject_mapping.example.
# cd /etc/security/pam_pkcs11 # cp subject_mapping.example subject_mapping
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.
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.
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 -> login … many user entries ## Certificate name mapped to the root account DOD CA-3 -> root
# chmod 644 cn_map subject_mapping
# 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 ...
# 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 ...
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.