Smart-card support in RHEL 7.4+

Updated -

In Red Hat Enterprise Linux, we strive to support several popular smart-card types. However, because 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.

If you search for smart-card support for RHEL 8, see the Smart-card support in RHEL 8 and later article.

If you search for a guide how to configure smart cards authentication from scratch in RHEL 7, see Smart Cards section in system-level Authentication Guide.

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 reader 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 card readers are supported

In Red Hat Enterprise Linux, we follow the pcsc-lite upstream project in regards to smart card reader hardware support. Most CCID compatible readers will work without any issue. Red Hat will periodically update the USB identifiers from the upstream project into our pcsc-lite-ccid driver. Furthermore, additional readers may be supported on Red Hat’s discretion. The following list of smart card readers are tested and verified by Red Hat:

  • SCR331/SCR3310
  • Omnikey 3121

The list of supported hardware in the upstream project.

Which PKCS#11 drivers are available

In RHEL7.3 smart cards are accessed 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 will take in RHEL7.4 the advantage of the additional features and drivers of OpenSC as well as its enhanced support of cards of the PKCS#15 family. Note that for several cards which are supported in OpenSC’s upstream documentation that do not fall in one of the categories in the supported list above, Red Hat will provide ongoing assistance in a commercially reasonable manner. New hardware enablement in RHEL7.4+ will come through OpenSC.

Enabling new cards via OpenSC

Red Hat can enable new cards under the following conditions.

  • Newer cards can be enabled only during the Full Support Phase as documented in https://access.redhat.com/support/policy/updates/errata#Full_Support_Phase.
  • Sample hardware must be provided to Red Hat. One sample for Red hat engineering to enable the hardware and one sample for Red Hat Quality Engineering. This is a hard requirement and the submitted samples must be identical to the cards the customer will be using. If cards require provisioning with special non-generally available tools, then the provided cards must be provisioned.
  • Cards must conform to the support outlined above. That is, CAC, PIV, and cards with the CoolKey applet or PKCS#15 cards.

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.

Debugging smart card issues

As the smart cards go through several layers of abstraction, we need to identify the source of the problem first.

  • USB:
    • Is the card/reader detected in USB layer?
      • lsusb -v
  • PC/SC: pcsc-lite, pcsc-lite-ccid, pcsc-tools
    • Is the reader supported?
    • Is the card detected in PC/SC layer?
      • pcsc_scan
    • Generate PC/SC level trace (APDU messages exchanged)
      • sudo systemctl stop pcscd; sudo LIBCCID_ifdLogLevel=0x000F pcscd --foreground --debug --apdu --color | tee log.txt
  • PKCS#11: opensc
    • Is the card detected in PKCS#11 layer:
      • pkcs11-tool -L
    • Can we list objects:
      • pkcs11-tool -O
    • Can we login to the card?
      • pkcs11-tool --login -O
    • Generate OpenSC debug log:
      • OPENSC_DEBUG=9 pkcs11-tool --login -O
  • Applications: pam_pkcs11
    • List certificates and tests if they are allowed to login:
      • pkcs11_listcerts debug
    • Debug pam module: Change /etc/pam.d/smartcard-auth (add a debug option):
      • auth [success=done ignore=ignore default=die] pam_pkcs11.so debug wait_for_card

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. The issue was resolved via this nss errata https://access.redhat.com/errata/RHEA-2018:1376.

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 a similar format as it was in coolkey.

The OpenSC is not able to handle login with my smart card reader integrated in the keyboard. It worked fine with CoolKey

Some of the smart card readers integrated in keyboards allow to input the PIN on the keyboard without sending it to the computer itself and potentially exposing it to malicious software. This feature is not supported by Coolkey so it always passes the PIN throughout the computer. Unfortunately, not all the keyboards implement this feature correctly in a standard way. If you encounter a problem with these keyboards, try to disable the PIN pad usage by uncommenting the enable_pinpad = false line in /etc/opensc-*.conf.

Comments