PackagingDrafts/Pkcs11Support

Background

PKCS#11

PKCS#11 is the API standard for cryptographic tokens. It covers hardware crypto devices such as Hardware Security Modules, and smart cards. There are also implementations of PKCS#11 "providers" in pure software — for example the NSS (Firefox) certificate store, GNOME keyring, and SoftHSM; these are referred to as Software Security Modules.

For our purposes, PKCS#11 mostly just provides an object store for keys and certificates — and for keys it can perform crypto operations for you using the key instead of just handing out the private key data willy-nilly.

For security reasons as described above, it's very useful to be able to import keys into a PKCS#11 token and use them from there — even if it's just a software token like the one provided by gnome-keyring — instead of just having them stored in a file in a user's home directory. That's exactly what you're doing when you import a certificate into something like Firefox, Thunderbird or Evolution. There are plans to make NetworkManager always behave this way too: https://wiki.gnome.org/Projects/NetworkManager/PKCS11

Problem statement

Differences in object reference

Although the use of PKCS#11 is very desirable, it can be very hard to use because each application does things differently. There has historically been no consistent way to specify which certificate to use, from which PKCS#11 provider.

With the pesign tool for signing EFI executables, first you need to create a NSS database and use the modutil tool to add your desired PKCS#11 provider to that environment. Then you can reference that token by its description and a certificate by its "nickname", which may not even be unique. For example, -t "PIV_II (PIV Card Holder pin)" -c "Certificate for PIV Authentication". (You can see this in its full horror in bug 1217727.)

Referencing the same certificate with OpenVPN might look something like: --pkcs11-providers=/usr/lib64/pkcs11/opensc-pkcs11.so --pkcs11-id=piv_II/PKCS\x2315\x20emulated/108421384210c3f5/PIV_II\x20\x28PIV\x20Card\x20Holder\x20pin\x29/01

With wpa_supplicant it's different again, as shown at http://w1.fi/cgit/hostap/plain/wpa_supplicant/examples/openCryptoki.conf

There are two parts to the problem — there's the question of which PKCS#11 provider module(s) should be loaded, and the question of how to identify the certificate you want to use from it. And there are two parts to the solution...

No central registry of modules

In addition to the object references, there is no way for a Fedora application to determine the available PKCS#11 modules system-wide. Typically applications request for the user to specify a module in the form of a shared object (.so file), either in configuration file or on every command instance. See for example the pkcs11-tool or browser applications like firefox. Instead of presenting a list of available smart cards or HSMs, they ask instead the user to specify a shared object.

Proposal

Registering the modules system-wide

Any package in Fedora containing a PKCS#11 provider module must be registered with p11-kit. For example, the OpenSC module which supports most major hardware smart cards, will automatically drop a config file into the appropriate place and then its module will automatically appear in well-behaved software which is integrated with the platform and uses p11-kit properly. The appropriate place in Fedora can be obtained with pkg-config p11-kit-1 --variable p11_module_configs. The dropped file should contain something similar to the contents below (which is the opensc example).

# This file describes how to load the opensc module
# See: http://p11-glue.freedesktop.org/doc/p11-kit/config.html

# This is a relative path, which means it will be loaded from
# the p11-kit default path which is usually $(libdir)/pkcs11.
# Doing it this way allows for packagers to package opensc for
# 32-bit and 64-bit and make them parallel installable
module: opensc-pkcs11.so

How applications take advantage of registered provider modules

Packages which can potentially use PKCS#11 tokens SHOULD automatically use the tokens which are present in the system's p11-kit configuration, rather than needing to have a PKCS#11 provider explicitly specified. That can be done by applications using the p11-kit library to get the list of modules, or by applications defaulting to the p11-kit proxy module (%{_libdir}/p11-kit-proxy.so), if no PKCS#11 provider module was specified by the user. The proxy module, is a single module wrapping all available registred modules.

How to specify a specific smart card/HSM

RFC7512 defines a 'PKCS#11 URI' as a standard way to identify tokens and objects. Fedora follows this standard and applications which refer to tokens such as smart cards or HSMs, must use RFC7512 to refer to them.

How to specify an object stored in a smart card/HSM

RFC7512 defines a 'PKCS#11 URI' as a standard way to identify tokens and objects. Fedora follows this standard and applications which refer to objects stored in smart cards or HSMs, must use RFC7512 to refer to certificates and private keys.

In particular when PKCS#11 objects are specified in a textual form which is visible to the user (e.g. on the command line or in a config file), objects SHOULD be specified in the form of a PKCS#11 URI as as described in RFC7512.

This form is already accepted by some programs such as the OpenConnect VPN client. The certificate used in the above examples can be simply used as a client authentication certificate by adding the command-line option -c 'pkcs11:manufacturer=piv_II;id=%01'.

OpenConnect VPN client

It has exemplary PKCS#11 support following all the above guidelines. Instructions on how to use it, are available on this manual page.

wpa_supplicant

Since wpa_supplicant uses engine_pkcs11, much of the work was already done. All that remained was to make it automatically use the PKCS#11 engine when it detected a "filename" starting with 'pkcs11:'. (sample commit)

OpenSSL engine_pkcs11

OpenSSL's engine_pkcs11 will load p11-kit-proxy.so as its default provider if none is specified, and will accept the RFC7512 standard object URIs in place of its own legacy format.

Applications using GnuTLS

Applications linked with GnuTLS that utilize the high level APIs, can load PKCS#11 URLs in place of certificate or key files.

Applications using NSS

Applications linked with NSS, can specify PKCS#11 URLs to identify an object. They will however not load p11-kit-proxy module by default.