PKCS#11 / Smart-Card Support Guidelines

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 or %{_datadir}/p11-kit/modules/. The dropped file should have the .module suffix and should contain something similar to the contents below (which is the opensc example).

The provider module, as mentioned in the example below should be installed at %{_libdir}/pkcs11/.

Once a module is registered the tokens/HSMs provided by it should be listed in the p11tool output using the following command:

The packages SHOULD NOT provide the package config *.pc files for the PKCS#11 modules, since the applications are not supposed to link directly against these libraries. The PKCS#11 module shared object SHOULD NOT be in the -devel subpackage either.

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 registered modules.

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. Note that an application must not require the '''module-name''' and '''module-path''' URI elements. Compliant with this policy applications should resolve URIs which do not contain these elements based [[#Registered|on the registered provider modules]]. Applications must not require the "slot" attribute, nor print it, since it is an esoteric PKCS#11 module implementation information that has no meaning for the end-user, and in several modules its value is not guaranteed to be unique (and may change for example after system reboot).

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'.