fedora-llm-docs/Documents/pages/Pkcs11Support.txt

= PKCS#11 / Smart-Card Support Guidelines

These guidelines are relevant to maintainers of packages with smart cards drivers (PKCS#11 modules), or smart card related tooling. Its purpose is to bring a consistency in smart card handling on the OS; for background and motivation see the https://fedoraproject.org/wiki/User:Nmav/Pkcs11Status[current status of PKCS#11 in Fedora].

== 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 https://p11-glue.github.io/p11-glue/[p11-kit]. For example, the https://github.com/OpenSC/OpenSC/wiki[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).

 # This file describes how to load the opensc module
 # See: https://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

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:


 $ p11tool --list-tokens
 
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.

[#registered]
== 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 registered modules.

[#specify-card]
== How to specify a specific smart card/HSM

https://tools.ietf.org/html/rfc7512[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).

[#specify-object]
== How to specify an object stored in a smart card/HSM

https://tools.ietf.org/html/rfc7512[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 https://tools.ietf.org/html/rfc7512[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'`.