From Fedora Project Wiki
Line 1: Line 1:
 
[[Category:Packaging_guidelines_drafts]]
 
[[Category:Packaging_guidelines_drafts]]
 
=== Background ===
 
=== Background ===
 
+
==== PKCS#11 ====
 
PKCS#11 is the API standard for cryptographic tokens. It covers both hardware crypto devices and software storage like the NSS database that remembers which web site certificates you've accepted. It 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.
 
PKCS#11 is the API standard for cryptographic tokens. It covers both hardware crypto devices and software storage like the NSS database that remembers which web site certificates you've accepted. It 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.
  
 
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
 
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
  
=== Summary ===
+
==== Usability ====
  
==== Client applications ====
+
The problem is that in most cases PKCS#11 is much too hard to set up and use. You have to explicitly configure each application to know where to load the PKCS#11 token, and there are numerous different ways of specifying which certificate from the token you want to use.
 
* 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 at http://tools.ietf.org/html/draft-pechanec-pkcs11uri-16 and http://p11-glue.freedesktop.org/pkcs11-uris.html .
+
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 <code>pkcs11:manufacturer=piv_II;id=%01</code> consistently in *all* applications within Fedora and expect it to work.
  
* 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.
+
Currently, there are many different ways to tell each application how to find the certificate. With OpenVPN it's: <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>
  
==== PKCS#11 Providers ====
+
With wpa_supplicant it's different again, as shown at http://w1.fi/cgit/hostap/plain/wpa_supplicant/examples/openCryptoki.conf
  
* Packages providing PKCS#11 modules SHOULD also provide a corresponding module file in the directory specified by  <code>pkg-config p11-kit-1 --variable p11_module_configs</code> ''(currently <code>/usr/share/p11-kit/modules</code>)'' so that the new module is automatically visible in well-behaved applications.
+
All of these should just take a simple PKCS#11 URI and Just Work™.
  
=== Rationale ===
+
==== Expectations ====
  
For the general case, PKCS#11 is much too hard to set up and use. You have to explicitly configure each application to know where to load the PKCS#11 token, and there are numerous different ways of specifying which certificate from the token you want to use.
+
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.
  
By consistently using p11-kit for token configuration, and PKCS#11 URIs for specifying objects, we make things a lot simpler for users. If I want to use a certain certificate from my Yubikey, I should be able to use the URI <code>pkcs11:manufacturer=piv_II;id=%01</code> consistently in *all* applications within Fedora and expect it to work.
+
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.
  
Currently, there are many different ways to tell each application how to find the certificate. With OpenVPN it's: <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>
+
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 <code>p11-kit-proxy.so</code> as its PKCS#11 provider module by default. Again, that's certainly something a packager can do.
  
With wpa_supplicant it's different again, as shown at http://w1.fi/cgit/hostap/plain/wpa_supplicant/examples/openCryptoki.conf
+
=== Summary ===
  
All of these should just take a simple PKCS#11 URI and Just Work™.
+
==== 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 at http://tools.ietf.org/html/draft-pechanec-pkcs11uri-16 and http://p11-glue.freedesktop.org/pkcs11-uris.html .
  
=== Expectations ===
+
* 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.
  
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.
+
==== PKCS#11 Providers ====
  
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.
+
* Packages providing PKCS#11 modules SHOULD also provide a corresponding module file in the directory specified by  <code>pkg-config p11-kit-1 --variable p11_module_configs</code> ''(currently <code>/usr/share/p11-kit/modules</code>)'' so that the new module is automatically visible in well-behaved applications.
  
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 <code>p11-kit-proxy.so</code> as its PKCS#11 provider module by default. Again, that's certainly something a packager can do.
+
=== Rationale ===

Revision as of 11:30, 19 December 2014

Background

PKCS#11

PKCS#11 is the API standard for cryptographic tokens. It covers both hardware crypto devices and software storage like the NSS database that remembers which web site certificates you've accepted. It 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.

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

Usability

The problem is that in most cases PKCS#11 is much too hard to set up and use. You have to explicitly configure each application to know where to load the PKCS#11 token, and there are numerous different ways of specifying which certificate from the token you want to use.

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.

Currently, there are many different ways to tell each application how to find the certificate. With OpenVPN it's: --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

All of these should just take a simple PKCS#11 URI and Just 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.

Summary

Client applications

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