# The following was performed on Debian Stretch
# Adapted from:
#    https://ubuntuforums.org/showthread.php?t=1557180&p=9743605
#    http://blog.fkraiem.org/2013/03/13/linux-smart-card-authentication-pam/
#
# Note: A X.509 certificate stored on the card is required. See:
#    https://pastebin.com/dCypTy09
# =====================================================================
#
# Install the PKCS11 module for PAM
# Note: /etc/pam_pkcs11/cacerts and /etc/pam_pkcs11/crls are automatically
#    created here.
# ---------------------------------------------------------------------
$ sudo apt-get install libpam-pkcs11

# Extract the pam_pkcs11.conf example file
# ---------------------------------------------------------------------
$ zcat /usr/share/doc/libpam-pkcs11/examples/pam_pkcs11.conf.example.gz | sudo tee /etc/pam_pkcs11/pam_pkcs11.conf

# Edit /etc/pam_pkcs11/pam_pkcs11.conf and change the 'module' line
#    to the correct path of opensc-pkcs11.so.
# ---------------------------------------------------------------------
module = /usr/lib/x86_64-linux-gnu/opensc-pkcs11.so

# Extract the certificate from the card and store as the PAM PKCS11 CA
#
# Note: certificate is self-signed and its own CA
# ---------------------------------------------------------------------
$ pkcs15-tool --read-certificate 707db33cfbd0712e0d5cfc4238fa85be44da990d | sudo tee /etc/pam_pkcs11/cacerts/jdoe-smartcard.pem

# Rehash the certs stored in /etc/pam_pkcs11/cacerts
# ---------------------------------------------------------------------
$ sudo pkcs11_make_hash_link /etc/pam_pkcs11/cacerts

# Basic Test with sudo
# ---------------------------------------------------------------------
#
# Modify /etc/pam.d/sudo from:
# vvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvv
%PAM-1.0

@include common-auth
@include common-account
@include common-session-noninteractive

# To:
# vvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvv
#%PAM-1.0

auth sufficient pam_pkcs11.so

@include common-auth
@include common-account
@include common-session-noninteractive

# Confirm that sudo works
# ---------------------------------------------------------------------
#
# flush any cached passphrase
$ sudo --reset-timestamp

# gain root using PKCS11
$ sudo --login
Smartcard authentication starts
Smart card found.
Welcome OpenSC Card (John Doe)!
Smart card PIN: 
verifying certificate
Checking signature

# Revert changes to /etc/pam.d/sudo
# ---------------------------------------------------------------------
# Remove the "auth sufficient pam_pkcs11.so" line

# Edit /etc/pam.d/common-auth to apply smartcard auth globally
#
# Note: It is important to add pam_pkcs11.so *BEFORE* the comment
#    about the "Primary" block. Otherwise, it will be overwritten by
#    pam-auth-update(8)
# ---------------------------------------------------------------------
#
# Original:
# vvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvv
# /etc/pam.d/common-auth - authentication settings common to all services
#
# This file is included from other service-specific PAM config files,
# and should contain a list of the authentication modules that define
# the central authentication scheme for use on the system
# (e.g., /etc/shadow, LDAP, Kerberos, etc.).  The default is to use the
# traditional Unix authentication mechanisms.
#
# As of pam 1.0.1-6, this file is managed by pam-auth-update by default.
# To take advantage of this, it is recommended that you configure any
# local modules either before or after the default block, and use
# pam-auth-update to manage selection of other modules.  See
# pam-auth-update(8) for details.

# here are the per-package modules (the "Primary" block)
auth	[success=1 default=ignore]	pam_unix.so nullok_secure
# here's the fallback if no module succeeds
auth	requisite			pam_deny.so
# prime the stack with a positive return value if there isn't one already;
# this avoids us returning an error just because nothing sets a success code
# since the modules above will each just jump around
auth	required			pam_permit.so
# and here are more per-package modules (the "Additional" block)
# end of pam-auth-update config

# Updated:
# vvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvv
# /etc/pam.d/common-auth - authentication settings common to all services
#
# This file is included from other service-specific PAM config files,
# and should contain a list of the authentication modules that define
# the central authentication scheme for use on the system
# (e.g., /etc/shadow, LDAP, Kerberos, etc.).  The default is to use the
# traditional Unix authentication mechanisms.
#
# As of pam 1.0.1-6, this file is managed by pam-auth-update by default.
# To take advantage of this, it is recommended that you configure any
# local modules either before or after the default block, and use
# pam-auth-update to manage selection of other modules.  See
# pam-auth-update(8) for details.

auth	[success=2 default=ignore]	pam_pkcs11.so

# here are the per-package modules (the "Primary" block)
auth	[success=1 default=ignore]	pam_unix.so nullok_secure
# here's the fallback if no module succeeds
auth	requisite			pam_deny.so
# prime the stack with a positive return value if there isn't one already;
# this avoids us returning an error just because nothing sets a success code
# since the modules above will each just jump around
auth	required			pam_permit.so
# and here are more per-package modules (the "Additional" block)
# end of pam-auth-update config

# Disable password authentication for the current user
# Note: Verify smartcard auth works before locking account!
# ---------------------------------------------------------------------
$ sudo passwd --lock `whoami`
Smartcard authentication starts
Smart card found.
Welcome OpenSC Card (John Doe)!
Smart card PIN: 
verifying certificate
Checking signature
passwd: password expiry information changed.