X.509 certificates are used for authentication in TLS and other protocols. It’s an X.509 certificate which lets you trust, when you connect to https://fedoraproject.org/, that you really are talking to the Fedora server and not an imposter.

The certificate is signed by a trusted "certificate authority", and contains a public key. It lets you know that whoever has the corresponding private key is truly the entity that the certificate claims they are (the 'subject' of the certificate).

As well as authentication for servers, certificates are often used to authenticate clients. For example for VPN connections, and also your 'Fedora certificate' used for koji access is an X.509 certificate.

In this guideline, we are only concerned with your certificates, where you have the corresponding private key and they are used to identify yourself.

These certificates are often stored in files, commonly either a PKCS#12 file (e.g. /usr/share/doc/openvpn/sample/sample-keys/client.p12) or a PKCS#7 or PEM file (e.g. ~/.fedora.cert).

It’s important that a private key remain private; if someone can take a copy of it then they can impersonate you — run a server pretending to be yours, log in to your VPN, abuse Fedora’s koji system in your name, etc.

If a key is stored in a file on the file system, it’s common to use a passphrase to protect it. So the attacker would have to find the passphrase as well as copying the file. But if they can get access to your system, that’s not actually much of an additional barrier.

A much more secure option is to keep the key in a separate hardware 'crypto token'. This will never just give up the key; instead it will perform (sign, encrypt, etc.) operations using the key. So you know the key can never really be stolen.

PKCS#11 is the API standard for cryptographic tokens. It covers hardware crypto devices as mentioned above, and there are also implementations of PKCS#11 "providers" in pure software — for example the NSS (Firefox) certificate store, GNOME keyring, and SoftHSM.

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

In Fedora (as with most other modern Linux and *NIX systems) this question is answered by p11-kit. A Fedora package containing a PKCS#11 provider module, such as the OpenSC one 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.

Applications can either link against libp11-kit and use its functionality for loading and handling PKCS#11 provider libraries, or there is a simpler option: p11-kit-proxy.so is a PKCS#11 provider module in its own right which inspects the system’s configuration and loads the appropriate modules — as the name implies, proxying them as slots of itself.

If you have an application which is already capable of using PKCS#11 but which doesn’t know about p11-kit, it will mostly need a PKCS#11 provider module to be explicitly specified. All you need to do is make it use p11-kit-proxy.so if the user didn’t specify anything else, and it should Do The Right Thing.

In April 2015, RFC7512 defined a 'PKCS#11 URI' as a standard way to identify such objects.

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[+pkcs11:manufacturer=piv_II;id=%01+]+'+`.

Packages providing PKCS#11 module DSO file SHOULD also provide a corresponding module configuration file

To fix OpenVPN, we first fixed it to load p11-kit-proxy.so by default (thus making the correct tokens visible), And then we fixed its "serialisation" format for how it identifies objects. This was actually in the pkcs11-helper library, and is fixed here.

Similar fixes were submitted to engine_pkcs11 (now in F22+) to make it load p11-kit-proxy.so as its default provider if none is specified, and to make it accept the RFC7512 standard object URIs in place of its own legacy format.

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)