From Fedora Project Wiki
Line 43: Line 43:
 
Historically, there have been numerous different ways of specifying this.
 
Historically, there have been numerous different ways of specifying this.
  
For example, with OpenVPN might look something like: <code>--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</code>
+
With the pesign tool for signing EFI executables, you specify a token by its description and a certificate by its "nickname", which may not even be unique. For example, <code>-t "PIV_II (PIV Card Holder pin)" -c "Certificate for PIV
 +
Authentication"</code>
 +
 
 +
Referencing the same certificate with OpenVPN might look something like: <code>--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</code>
  
 
With wpa_supplicant it's different again, as shown at http://w1.fi/cgit/hostap/plain/wpa_supplicant/examples/openCryptoki.conf
 
With wpa_supplicant it's different again, as shown at http://w1.fi/cgit/hostap/plain/wpa_supplicant/examples/openCryptoki.conf

Revision as of 13:21, 7 May 2015

Background

X.509 / SSL certificates

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 draft, 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 — and 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

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.

Put rather simplistically, 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

Although the use of PKCS#11 is very desirable, it can be very hard to use for two main reasons:

Which PKCS#11 provider to use?

As stated above, there are many potential PKCS#11 provider libraries in the system. Which ones should be loaded into any given application?

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.

How to specific the certificate / key to use?

Once that's solved, there's also the issue of how the user should specific which certificate/key should be used. When it was in a file, you just gave the filename — simple! But now there are a whole bunch of PKCS#11 providers loaded, and they each have multiple certificates and keys in them. Which one do we want?

Historically, there have been numerous different ways of specifying this.

With the pesign tool for signing EFI executables, you specify a 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"

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

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

All of the above examples should just (be fixed to) take a simple PKCS#11 URI and Just Work™.

Rationale

By consistently using p11-kit for token configuration, and PKCS#11 URIs for specifying objects, we make things a lot simpler for Fedora users. If I want to use a certain certificate from my Yubikey, I should be able to use the URI pkcs11:manufacturer=piv_II;id=%01 consistently in *all* applications within Fedora and expect it to work.

Expectations

Obviously, packagers are not always expected to be proficient coders in the langage their packages are written in. We don't necessarily expect packagers to fix software for themselves, although it's great when they can.

However, it is certainly within the purview of a packager to work with the upstream developers and ensure that the appropriate features are requested and given due consideration.

Most importantly, it is often the case that software can be built with more than one crypto library, and the feature set available will depend on that choice. For example the OpenConnect VPN client will comply with all of the above requirements when built with GnuTLS, but not when built with OpenSSL. This much certainly is within the direct control of the packager. Likewise, sometimes all that is required is to configure a piece of software to use p11-kit-proxy.so as its PKCS#11 provider module by default. Again, that's certainly something a packager can do.

Packagers

What we ask of packagers is this:

  • Check if your package can use SSL client certificates (e.g. ~/.fedora.cert) for authentication. If it can't, you have nothing to do.
  • If it can use SSL client certificates, check and see if it can use PKCS#11. (See the help section below).
  • If the package can support PKCS#11, please make sure you build it with that support enabled, and configure it to use p11-kit-proxy.so as its default PKCS#11 provider when none is specified/overridden by the user.
  • If the package can't support PKCS#11, please file a feature request with the upstream developers to fix that.

Help

There's a lot of confusing terminology here, but really what we're asking for is quite simple: If you application can certificate from a file, then we would *also* like it to be able to use a certificate from PKCS#11, if the user provides a pkcs11:… URI instead of a filename. That's all.

There is a wiki page at https://fedoraproject.org/wiki/PackageMaintainers/PKCS11 which (will) help you test whether your packages meet these guidelines. If in doubt, file a bug as blocking bug #1173546 and ask for assistance.

Various applications might support PKCS#11 tokens differently, and it might even differ according to which crypto library you choose to build against.

If you use GnuTLS, it's quite likely that it'll automatically just Do The Right Thing, and happily take a PKCS#11 URI in place of a filename for certificates and keys. GnuTLS is probably the best choice if your package supports it, unless your package has specific requirements.

If you use OpenSSL, it has no native PKCS#11 support. But your package might support being built with the additional pkcs11-helper or libp11 libraries, or using engine_pkcs11. If not, please talk to the upstream developers about supporting the ENGINE. It's relatively simple to add. Ask dwmw2 and he may be able to provide patches for you.

If you use NSS, it might not accept URIs but if it's a graphical program that might not matter. You can probably just rely on NSS to be fixed (bug 1173577). Until that bug is fixed, it's probably best not to choose NSS. If your package can build against another crypto library, do that.

Guidelines Summary

Client applications

  • Packages which use SSL certificates/keys from a file or elsewhere SHOULD also support using certs/keys from PKCS#11 tokens.
  • Where 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.
  • Packages which can 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.

PKCS#11 Providers

  • Packages providing PKCS#11 modules SHOULD also provide a corresponding module file in the directory specified by pkg-config p11-kit-1 --variable p11_module_configs (currently /usr/share/p11-kit/modules) so that the new module is automatically visible in well-behaved applications.

Rationale