Smart card support in RHEL7.4+

Updated -

In Red Hat Enterprise Linux, we strive to support several popular smart cards types, however, as it is not possible to support every smart card available, this document specifies our targeted cards. In addition it provides information on how to investigate a potential incompatibility between the cards and RHEL.

Smart cards are typically handled on multiple layers and by multiple components, and for that we would like to provide a brief background to provide context for the following discussion.

On the lower level, the operating system communicates with the smart card (reader), using the PC/SC protocol, and this communication is performed by the pcsc-lite daemon. The daemon forwards the commands received to the card typically over USB.

The PC/SC low level communication is rarely seen on the application level. The main method in RHEL for applications to access smart cards, is via a higher level API, the OASIS PKCS#11 API, which abstracts the card communication to specific commands that operate on cryptographic objects (private keys etc). Smart card vendors, often provide a shared module (.so file), which follows the PKCS#11 API, and serves as a driver for the card. That shared module can be imported by applications, and be used to communicate with the card directly. In the open source world, we have projects like OpenSC, which wraps several smart card drivers into a single shared module. For example the OpenSC module as shipped by RHEL7.4, provides support for Yubikey, Nitrokey, and the US-government PIV and CAC cards on a single module. We highly recommend smart card vendors to provide support for their cards using the OpenSC libraries.

Which cards are supported

In Red Hat Enterprise Linux 7.4, the following cards are supported:

  • All the cards targeted by Red Hat Certificate System (RHCS), i.e., CAC, PIV and cards with the CoolKey applet.
  • Selected PKCS#15 cards. While several cards of this family are supported, there are many different configurations and options for these cards; as such for special cards that may not be compatible with RHEL please contact your customer representative.
  • Other cards may be supported on Red Hat’s discretion.

Which PKCS#11 drivers are available

In RHEL7.3 smart cards are via the CoolKey PKCS#11 module. In RHEL7.4+ we introduce the OpenSC PKCS#11 module, which will accompany the CoolKey module, as a fully compatible replacement of it. Applications that switch to OpenSC module, in RHEL7.4, will take advantage of the additional features and drivers of OpenSC, as well as its enhanced support of cards of the PKCS#15 family. Note that several cards which are supported in OpenSC’s upstream documentation that do not fall in one of the categories in the supported list above, are supported by Red Hat at best-effort basis. New hardware enablement in RHEL7.4+ will be come through OpenSC.

Migrating from CoolKey to OpenSC

Login in GNOME

Gnome is using pam_pkcs11 tool to provide access to Smart Cards and NSS. To use OpenSC, the /etc/pam_pkcs11/pam_pkcs11.conf needs to be updated to list OpenSC and also the correct NSS DB:

use_pkcs11_module = opensc;
pkcs11_module opensc {
    [...]
nss_dir = /etc/pki/nssdb;

The NSS DB needs to be configured with OpenSC, instead of CoolKey. This can be achieved for example using the provided script:

# pkcs11-switch opensc

Going back is as simple as running pkcs11-switch coolkey.

SSH login

OpenSSH is using directly PKCS#11 interface of the library. To use OpenSC instead of CoolKey, just replace the path to CoolKey (/usr/lib64/pkcs11/libcoolkey.so) with the path to OpenSC (/usr/lib64/pkcs11/opensc-pkcs11.so) in the client configuration files or scripts used in your system.

Using OpenSC in parallel with CoolKey in p11-kit

The CoolKey driver is automatically registered in the p11-kit database, which makes it a default provider for most of the smart cards. OpenSC should not be registered there in parallel, otherwise it would cause each of the supported cards showed twice in the p11-kit-proxy. Before using OpenSC through p11-kit-proxy make sure CoolKey is uninstalled (or the file /usr/share/p11-kit/modules/coolkey.module removed).

The file providing support for OpenSC in p11-kit is automatically installed into /usr/share/p11-kit/modules/opensc.module.

Q&A

I am using PIV card in Thunderbird and I am unable to sign emails with OpenSC. It works fine with CoolKey

This is a known bug in NSS and OpenSC, preventing the enforcement of always authenticate rule when using the card in long-running applications. You can workaround this bug by setting pin_cache_ignore_user_consent = true and use_pin_caching = true in /etc/opensc-*.conf. For more information, see the bug #1518348.

I am using PIV card with OpenSC and I am prompted for a PIN with every signature. It didn’t happen with CoolKey.

Every PIV digial signature key operation requires “explicit user action” as described in the following NIST document to assert reliable level of security. In some cases, this requirement can be weakened by enabling PIN caching for these operation in OpenSC by setting pin_cache_ignore_user_consent in /etc/opensc-*.conf.

We are using only one type of the card and the detection takes too long.

The OpenSC implements support for most of the cards, but if you know that you will be using only one or two, it can be runtime configured in /etc/opensc-x86_64.conf (on x86_64 architecture). In the section app default locate the option card_drivers and set it to appropriate drivers you are interested in. You can list all the supported drivers using opensc-tool --list-drivers. For example to allow only PIV and CAC drivers, use the following configuration:

card_drivers = cac, PIV-II;

The label of the PIV card changed with OpenSC

This is a known issue. OpenSC does not show a cardholder name in the label in PIV driver.

If your card has also CAC endpoint, you can modify the configuration in /etc/opensc-x86_64.conf (on x86_64 architecture) to give the CAC driver a priority over other drivers. In the section app default locate the option card_drivers and set:

card_drivers = cac, internal

It will show you the label in similar format as it was in coolkey.

Was this helpful?

We appreciate your feedback. Leave a comment if you would like to provide more detail.
It looks like we have some work to do. Leave a comment to let us know how we could improve.
Close

Welcome! Check out the Getting Started with Red Hat page for quick tours and guides for common tasks.