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_offlinein thecert_policyto skip the signature verification of the CRLs; it is still a good idea to check the signatures upon download.