This project is a Puppet module to manage pam_pkcs11, a PAM module developed as part of the OpenSC project for advanced authentication with smart cards and other PKCS #11 cryptographic modules.
- Setup - The basics of getting started with pam_pkcs11
- Usage - Configuration options and additional functionality
- Reference - An under-the-hood peek at what the module is doing and how
- Limitations - OS compatibility, etc.
- Development - Guide for contributing to the module
In addition to installing and configuring the core pam_pkcs11(8)
PAM module,
this Puppet module assists in the creation of mapper files to associate users
with their certificates. It can also manage some aspects of the session lock
policy through the configuration of the pkcs11_eventmgr(8)
daemon, part of the
pam_pkcs11 package.
Currently, PAM is only configured on the supported Debian-based platforms
(Debian and Ubuntu) using pam-auth-update
. On other platforms, configure PAM
to use pam_pkcs11(8)
via other means, be that another Puppet module, a Puppet
profile, or something else. In most cases just the following line in the PAM
configuration is all that is required:
auth sufficient pam_pkcs11.so
Please refer to the section on PAM configuration from the official pam_pkcs11 documentation for further details.
By default, this module will install pam_pkcs11 and configure it to use the OpenSC PKCS#11 module, checking user certificates against a certificate authority (CA) trust store, and the certificates contained on a PKCS#11 token to users based on the SHA-1 certificate fingerprints (via the digest mapper). None of this is useful on its own, so we also provide parameters to install user mapping data and CA certificates.
To associate the certificates contained on a smart card or other PKCS#11 token,
use the digest_mappings
parameter like so:
class { 'pam_pkcs11':
digest_mappings => {
'alice' => '79:E7:27:38:59:24:C6:AD:92:E5:AA:FA:20:0F:D6:9A:D5:47:87:DF',
'bob' => 'DD:75:AD:96:0E:CD:BD:25:E7:27:02:8B:34:3D:E4:08:FA:44:A8:31',
},
}
Handling CA certificates is more difficult, because they are stored differently depending on the cryptographic back-end. The most common back-end options are NSS and OpenSSL. Unfortunately, this module does not currently support NSS database storage. See the Limitations section below for more details.
For Debian-based systems, the parameters ca_dir_source
and
ca_dir_sourceselect
provide a way to specify CA file sources for the OpenSSL
hash directory back-end. The parameters are simply passed on to a Puppet file
resource, as source
and sourceselect
with the caveat that ca_source_dir
has to be an array of strings. See the Puppet documentation about the
file resource for more
information.
Extending the example from before, here all the CA certificates are stored in the
ca_dir
sub-directory of a "files" module are installed on the target host:
class { 'pam_pkcs11':
digest_mappings => {
'alice' => '79:E7:27:38:59:24:C6:AD:92:E5:AA:FA:20:0F:D6:9A:D5:47:87:DF',
'bob' => 'DD:75:AD:96:0E:CD:BD:25:E7:27:02:8B:34:3D:E4:08:FA:44:A8:31',
},
ca_dir_source => ['puppet:///modules/files/ca_dir'],
}
With this configuration, Alice and Bob should be able to authenticate, provided the certificates on their smart cards were issued by a trusted CA and have not been revoked.
The base pam_pkcs11
class is the primary point of entry for this module.
This class should be declared with its parameters defined as appropriate to the
deployment environment.
The sub-class pam_pkcs11::pkcs11_eventmgr
provides a supplementary interface
to configure the pkcs11_eventmgr(1)
session lock daemon. It will be enabled
via the pam_pkcs11::manage_pkcs11_eventmgr
parameter.
pam_pkcs11
: The primary point of entry to this module.pam_pkcs11::pkcs11_eventmgr
: Managespkcs11_eventmgr(1)
, the session lock helper daemon.
pam_pkcs11::install
: Manages installation of the pam_pkcs11 package.pam_pkcs11::config
: Manages configuration of the various configuration files.pam_pkcs11::params
: Contains the default configuration parameters.
The package name that provides the pam_pkcs11 software.
Affects the debug
configuration option of the resulting pam_pkcs11
configuration file.
Affects the nullok
configuration option of the resulting pam_pkcs11
configuration file.
Affects the use_first_pass
configuration option of the resulting
pam_pkcs11
configuration file.
Affects the try_first_pass
configuration option of the resulting
pam_pkcs11
configuration file.
Affects the use_authtok
configuration option of the resulting pam_pkcs11
configuration file.
Affects the card_only
configuration option of the resulting pam_pkcs11
configuration file.
Affects the wait_for_card
configuration option of the resulting pam_pkcs11
configuration file.
Affects the pkcs11_module
configuration option of the resulting pam_pkcs11
configuration file.
This parameter overwrites the base settings from
pam_pkcs11::pkcs11_module_base
.
Affects the pkcs11_module
configuration option of the resulting pam_pkcs11
configuration file.
This parameter provides the distribution-dependent base settings. Per default
values from the pam_pkcs11::params
class are used. If some customization on
top of those base settings is necessary, use the pam_pkcs11::pkcs11_module
parameter, otherwise use this parameter to define new base settings.
Affects the use_mappers
configuration option of the resulting pam_pkcs11
configuration file.
Affects the mapper *
configuration entries of the resulting pam_pkcs11
configuration file.
This parameter overwrites the base settings from
pam_pkcs11::mapper_options_base
.
Affects the mapper *
configuration entries of the resulting pam_pkcs11
configuration file.
This parameter provides the distribution-dependent base settings. Per default
values from the pam_pkcs11::params
class are used. If some customization on
top of those base settings is necessary, use the pam_pkcs11::mapper_options
parameter, otherwise use this parameter to define new base settings.
Affects the content of digest_mappings
configuration file.
It contains a hash that maps user logins to certificate fingerprints. The keys are the user logins and the values are the certificate fingerprints.
Affects the content of subject_mappings
configuration file.
It contains a hash that maps user logins to certificate subjects. The keys are the user logins and the values are the certificate subjects.
Affects the content of uid_mappings
configuration file.
It contains a hash that maps user logins to certificate unique identifiers (UIDs). The keys are the user logins and the values are the certificate UIDs.
An array of file source URIs, which should be populated into the trusted CA certificate pool of the target host.
Can either be first
or all
and defines the sourceselect
parameter of the
file resource that copies the CA certificates to the target host.
Defines if the pkcs11_eventmgr
should be configured and managed or not.
Defines which PAM configuration framework is used. Currently, only
pam-auth-update
is supported. Set this to none
to handle PAM configuration
elsewhere or manually.
Affects the debug
configuration option of the resulting pkcs11_eventmgr
configuration file.
Affects the daemonize
configuration option of the resulting
pkcs11_eventmgr
configuration file.
Affects the polling_time
configuration option of the resulting
pkcs11_eventmgr
configuration file.
Affects the expire_time
configuration option of the resulting
pkcs11_eventmgr
configuration file.
Affects the pkcs11_module
configuration option of the resulting
pkcs11_eventmgr
configuration file.
Affects the event *
configuration entries of the resulting pkcs11_eventmgr
configuration file.
This parameter overwrites the base settings from
pam_pkcs11::pkcs11_eventmgr::event_opts_base
(and
pam_pkcs11::pkcs11_eventmgr::event_opts_screen_lock
if
pam_pkcs11::pkcs11_eventmgr::lock_screen_on_card_removal
is enabled).
Affects the event *
configuration entries of the resulting pkcs11_eventmgr
configuration file.
This parameter provides the distribution-dependent base settings. Per default
values from the pam_pkcs11::params
class are used. If some customization on
top of those base settings is necessary, use the
pam_pkcs11::pkcs11_eventmgr::event_opts
parameter, otherwise use this
parameter to define new base settings.
Affects the event *
configuration entries of the resulting pkcs11_eventmgr
configuration file.
When pam_pkcs11::pkcs11_eventmgr::lock_screen_on_card_removal
is enabled,
these settings will be merged into the resulting event *
configuration. It
overwrites settings from pam_pkcs11::pkcs11_eventmgr::event_opts_base
, but
can still be overwritten by any settings in
pam_pkcs11::pkcs11_eventmgr::event_opts
.
This defines how the pkcs11_eventmgr
service is started. Currently only
systemd_service
and xdg_autostart
is supported. Choose none
in case the
auto-start of the daemon is configured elsewhere.
This option defines if the
pam_pkcs11::pkcs11_eventmgr::event_opts_screen_lock
should be merged into the
event *
configuration or not.
Please see the disclaimer of liability in the LICENSE
file.
Although no guarantees can be made, this module is designed to work on the following operating systems:
- Red Hat Enterprise Linux 6 and 7
- CentOS 6 and 7
- Scientific Linux 6 and 7
- Oracle Linux 6 and 7
- Ubuntu 18.04, 20.04, and 22.04
- Debian 10 and 11
- SUSE Linux Enterprise Server 12 and 15
This module is tested with the following software. For complete details see
metadata.json
and the GitHub actions configuration.
- Puppet
- 7
- Ruby
- 2.5
- 2.6
- 2.7
This module cannot currently manage CA certificates stored in an NSS database,
so users of that storage back-end must install them via other means. One option
is Joshua Hoblitt's nsstools module; however, due to limitations in certutil
it cannot currently handle multiple certificates with the same subject, a
scenario commonly used for large-scale intermediate CAs.
On systems using non-NSS CA storage (OpenSSL hash directories), the module
provides the ca_dir_source
and ca_dir_sourceselect
parameters; however,
they are not supported on the RedHat
OS family due to a missing script.
-
If there are multiple trusted CAs with the same subject, online CRL checks may fail during CRL signature verification. The workaround is to use pre-downloaded CRLs and
crl_offline
in thecert_policy
to skip the signature verification of the CRLs; it is still a good idea to check the signatures upon download.