From cf30cb9c56f6177d4d1eca5bcc6d4bbf9c0a04c8 Mon Sep 17 00:00:00 2001 From: Igor Gnatenko Date: Dec 11 2018 10:41:07 +0000 Subject: PKCS11Support: fix markup Signed-off-by: Igor Gnatenko --- diff --git a/guidelines/modules/ROOT/pages/Pkcs11Support.adoc b/guidelines/modules/ROOT/pages/Pkcs11Support.adoc index 0ed32d3..428fb8e 100644 --- a/guidelines/modules/ROOT/pages/Pkcs11Support.adoc +++ b/guidelines/modules/ROOT/pages/Pkcs11Support.adoc @@ -1,45 +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]. +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 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). +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: 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/`. +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. +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 +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. +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]. +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'`. diff --git a/guidelines/modules/ROOT/pages/Python.adoc b/guidelines/modules/ROOT/pages/Python.adoc index 84d7ba4..e0a15fa 100644 --- a/guidelines/modules/ROOT/pages/Python.adoc +++ b/guidelines/modules/ROOT/pages/Python.adoc @@ -39,7 +39,7 @@ Packages MUST NOT have dependencies (either build-time or runtime) on packages n === Automatically generated dependencies -Packages MAY use the automatic Python dependency generator. This generator uses upstream egg/dist metadata (such as https://python-packaging.readthedocs.io/en/latest/dependencies.html[setuptool's install_requires]) to determine what the package should depend on. The generator parses the installed metadata from `+/usr/lib(64)?/pythonX.Y/site-packages/[^/]+.(egg|dist)-info/requires.txt+`, so it will not work with software that uses plain https://docs.python.org/3/distutils/[distutils]. +Packages MAY use the automatic Python dependency generator. This generator uses upstream egg/dist metadata (such as https://python-packaging.readthedocs.io/en/latest/dependencies.html[setuptool's install_requires]) to determine what the package should depend on. The generator parses the installed metadata from `+/usr/lib(64)?/pythonX.Y/site-packages/[^/]\+.(egg|dist)-info/requires.txt+`, so it will not work with software that uses plain https://docs.python.org/3/distutils/[distutils]. To enable this feature, add: