#821 SSLCertificateHandling policy update
Closed 10 months ago by tibbs. Opened 11 months ago by nmav.
nmav/packaging-committee tmp-pkcs11  into  master

@@ -46,6 +46,7 @@ 

  * xref:Per-Product_Configuration.adoc[Per-Product_Configuration]

  * xref:PHP.adoc[PHP]

  * xref:PkgConfigBuildRequires.adoc[PkgConfigBuildRequires]

+ * xref:Pkcs11Support.adoc[PKCS#11 / Smart-Card Support Guidelines]

  * xref:PreupgradeAssistant.adoc[Preupgrade Assistant]

  * xref:Python.adoc[Python]

  * xref:Python_Appendix.adoc[Python_Appendix]

@@ -58,7 +59,7 @@ 

  * xref:Rust.adoc[Rust]

  * xref:Scriptlets.adoc[Scriptlets]

  * xref:SourceURL.adoc[SourceURL]

- * xref:SSLCertificateHandling.adoc[SSLCertificateHandling]

+ * xref:SSLCertificateHandling.adoc[SSLCertificate Handling Guidelines]

  * xref:SugarActivityGuidelines.adoc[Sugar activities]

  * xref:Systemd.adoc[Systemd]

  * xref:Tcl.adoc[Tcl/Tk extensions]

@@ -0,0 +1,45 @@ 

+ = PKCS#11 / Smart-Card Support Guidelines

+ :toc:

+ 

+ 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 link: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 link:http://p11-glue.freedesktop.org/[p11-kit]. For example, the link: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: http://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

+  

+ 

+ [#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

+ 

+ link: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

+ 

+ link: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 link: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'`.

@@ -1,119 +1,12 @@ 

- == Background

+ = Certificate Handling Guidelines

+ :toc:

  

- === X.509 / SSL certificates

+ These guidelines are relevant to maintainers of packages which utilize smart cards for loading certificate or private key. Its purpose is to bring a consistency in smart card handling on the OS; for background and motivation see the link:https://fedoraproject.org/wiki/User:Nmav/Pkcs11Status[current status of PKCS#11 in Fedora].

  

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

+ == How to specify a certificate or private key stored in a smart card or HSM

  

- 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)_.

+ In April 2015, link:https://tools.ietf.org/html/rfc7512[RFC7512] defined a 'PKCS#11 URI' as a standard way to identify objects stored in smart cards or HSMs. That form should be understood by programs when specified in place of a certificate file. For non-interactive applications which get information on the command line or configuration file, there should not be a separate configuration option to load keys and certificates stored in smart cards, the same option accepting files, should additionally accept PKCS#11 URIs.

  

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

+ == How to specify a specific PKCS#11 provider module for the certificate or key

  

- 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

- 

- 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

- 

- == Problem statement

- 

- Although the use of PKCS#11 is very desirable, it can be very hard to use because each application does things differently. There has historically been no consistent way to specify which certificate to use, from which PKCS#11 provider.

- 

- With the pesign tool for signing EFI executables, first you need to create a NSS database and use the `+modutil+` tool to add your desired PKCS#11 provider to that environment. Then you can reference that 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"+`. _(You can see this in its full horror in https://bugzilla.redhat.com/show_bug.cgi?id=1217727#1[bug 1217727].)_

- 

- 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

- 

- There are two parts to the problem — there's the question of which PKCS#11 provider module(s) should be loaded, and the question of how to identify the certificate you want to use from it. And there are two parts to the solution...

- 

- == Solution

- 

- === Which provider to load?

- 

- In Fedora _(as with most other modern Linux and *NIX systems)_ this question is answered by http://p11-glue.freedesktop.org/[p11-kit]. A Fedora package containing a PKCS#11 provider module, such as the https://github.com/OpenSC/OpenSC/wiki[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.

- 

- === How to specify a certificate?

- 

- In April 2015, https://tools.ietf.org/html/rfc7512[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+`]`+'+`.

- 

- == Proposal

- 

- === Client and server 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 https://tools.ietf.org/html/rfc7512[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 a PKCS#11 module DSO file SHOULD also provide a corresponding http://p11-glue.freedesktop.org/doc/p11-kit/pkcs11-conf.html#config-module[module configuration 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.

- 

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

- 

- == 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[`+pkcs11:manufacturer=piv_II;id=%01+`] consistently in *all* applications within Fedora and expect it to work.

- 

- == Examples

- 

- === OpenVPN

- 

- To fix OpenVPN, we first https://community.openvpn.net/openvpn/ticket/490[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 https://github.com/OpenSC/pkcs11-helper/pull/4[here].

- 

- === OpenSSL engine_pkcs11

- 

- Similar https://github.com/OpenSC/engine_pkcs11/pull/9[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.

- 

- === wpa_supplicant

- 

- 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:+`'. (http://w1.fi/cgit/hostap/commit/?id=01b0d1d5c1d5598fc92580f2804507d61faf0453[sample commit])

- 

- == Expectations

- 

- Obviously, packagers are not always expected to be proficient coders in the language 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. The `+p11-kit-proxy.so+` module is a simple PKCS#11 provider which will read the system's p11-kit configuration and load all the configured modules for itself, providing a kind of 'proxy'. Again, that's certainly something a packager can do.

- 

- With that in mind, 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. If not, please file an upstream bug.

- 

- * If the package can support PKCS#11, make sure it is either fully integrated with libp11-kit to load the correct modules, or at _least_ that it can be configured to load `+p11-kit-proxy.so+` as its default PKCS#11 provider when the user doesn't explicitly specify one. If not, please file an upstream bug.

- 

- * If the package can support PKCS#11, make sure it can accept RFC7512 PKCS#11 URIs as the way to specify certificates. If not, again please file an upstream bug.

- 

- If there are things which need to be fixed, it's helpful also to file a bug in Fedora bugzilla and make it block the https://bugzilla.redhat.com/showdependencytree.cgi?id=1173546&hide_resolved=1[PKCS#11 Sanity Tracker bug]. Do include a reference to the upstream bug.

- 

- == Help

- 

- There's a lot of confusing terminology here, but really what we're asking for is quite simple: If your application can use a certificate from a file, then we would _also_ like it to be able to use a certificate from PKCS#11.

- 

- Your application should Do The Right Thing for certificates in PKCS#11, without the user having to explicitly specify which PKCS#11 provider to use and without the user having to learn some weird non-standard way of asking for it.

- 

- There is a wiki page at https://fedoraproject.org/wiki/PackageMaintainers/PKCS11 which help you test whether your packages meet these guidelines. If in doubt, file a bug as blocking the https://bugzilla.redhat.com/show_bug.cgi?id=PKCS11[PKCS#11 tracker bug] and ask for assistance.

+ 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. See xref:Pkcs11Support.adoc[the PKCS#11 packaging page] for more information.

I'd like to update the current SSLCertificateHandling packaging guidelines for clarity. The reason is that it covers two different fields, PKCS#11 requirements and Application requirements for certificates/keys. The audience is typically different.

Resolves #665

Signed-off-by: Nikos Mavrogiannopoulos nmav@redhat.com

It would be good if you would use asciidoc syntax instead of dumping wiki one :)

Also please use semantic breaks (sembr.org)

And you need to add your page to navigation bar. You can create submenu for crypto things if you feel that it makes sense

Where are these pages generated?

rebased onto 683393fa5239f620274f40d98157420f3496f43b

11 months ago

btw. the review interface is not ready for semantic spacing.

Where are these pages generated?

Depends what you need. You can read README to find out how to generate website.

btw. the review interface is not ready for semantic spacing.

it is simply text file, so just split it.

Where are these pages generated?
Depends what you need. You can read README to find out how to generate website.

My question is on where to refer people to see that policy. I can see the wiki policies.

Thank you. Any other issues to be addressed?

Yes, please make it actually to use proper syntax for documentation. Like the first title and header should be in = Some Header format. See index.adoc or other documents for example of formatting.

rebased onto da78ce0258914cf588c37eb1fb44e7362bb95f38

11 months ago

rebased onto 5532e4aaae14c5785435b7c2ff9b2da37cbe1b87

11 months ago

Hi, Igor, they seem to be addressed. Anything I may have missed?

The problem is that there isn't a corresponding issue, so this doesn't show up in ticket reports and thus doesn't get on the meeting agenda.

I've clarified that we still need an open issue for discussion in https://fedoraproject.org/wiki/Packaging_Committee

I'm not familiar with the context, but isn't #665 a corresponding open issue?

Guys, what do I need to do to unblock this issue?

We will discuss it today on a meeting.

Metadata Update from @ignatenkobrain:
- Pull-request tagged with: meeting

10 months ago

I think this should say "packagers who maintain packages".

Alternatively, instead of "packagers who maintain packages" just say "maintainers of packages"

Should "p11tool" be on fixed-width font?

rebased onto ac2fd579a9bafaa42285305faedcd28c5f6eea12

10 months ago

Thanks, nice comments. Updated.

rebased onto 8bb2d2d669429b9df24807e58034553bd90d3daa

10 months ago

The same text is still in the other file, SSLCertificateHandling.adoc

rebased onto 2978f57

10 months ago

Looks good to me now, thanks!

Metadata Update from @tibbs:
- Pull-request untagged with: meeting
- Pull-request tagged with: writeup

10 months ago

Metadata Update from @tibbs:
- Pull-request untagged with: writeup

10 months ago

I merged this manually.

Pull-Request has been closed by tibbs

10 months ago