For background and motivation please see the current status of PKCS#11 in Fedora.
This guideline updates the previous SSLCertificateHandling.
Proposal
Registering the modules system-wide
Any package in Fedora containing a PKCS#11 provider module, intended to be used outside this package, 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'.