Re: [ptxdist] [PATCH 4/5] doc: dev_code_signing: rework and extend code signing section

[Roland Hieber <rhi@pengutronix.de>]

On Mon, Jun 08, 2020 at 10:53:04AM +0200, Bastian Krause wrote:
> Signed-off-by: Bastian Krause <bst@pengutronix.de>
> ---
>  doc/dev_code_signing.rst | 139 ++++++++++++++++++++++++++++++++-------
>  1 file changed, 116 insertions(+), 23 deletions(-)
> 
> diff --git a/doc/dev_code_signing.rst b/doc/dev_code_signing.rst
> index de0087f8b..c5b5786f9 100644
> --- a/doc/dev_code_signing.rst
> +++ b/doc/dev_code_signing.rst
> @@ -3,34 +3,127 @@
>  Code Signing
>  ------------
>  
> -This is an overview over the ptxdist signing infrastructure.
> -ptxdist uses PKCS#11 internally for providing access to keys and certificates.
> -Packages that wish to sign something should implement a PKCS#11 interface.
> +In order to make sure an artifact was created by a known authority and was not
> +altered later, digital signatures play a key role when building firmware
> +images.
> +This is also essential when a verified boot chain is established, e.g. via
> +*High Assurance Boot* (HAB), signed FIT images, and a verified root file
> +system.
> +
> +PTXdist uses `PKCS#11 <pkcs11-doc_>`_ internally to provide access to keys and
> +certificates, therefore code signing consumers should implement a PKCS#11
> +interface to make use of PTXdist's code signing infrastructure.
>  
>  As PKCS#11 URIs usually differ between different usecases (release vs.
> -development) the URIs normally are not hardcoded in the package configuration.
> -Instead, ptxdist has the idea of "roles" which are string identifiers used to
> +development) the URIs are usually not hardcoded in the package configuration.
> +Instead, PTXdist has the idea of **roles** which are string identifiers used to
>  access a single private/public key pair and a certificate.
>  
> -ptxdist supports Hardware Security Modules (HSM).
> -In case a HSM is not present or shall not be used SoftHSM is used internally to
> -transparently provide the same API internally.
> +Finally, one or several **code signing providers** supply the mapping from
> +roles to the respective key material or even provide it themselves for
> +development.
> +
> +PTXdist supports *Hardware Security Modules* (HSM).
> +In case an HSM is not present or shall not be used, PTXdist can emulate it
> +using `SoftHSM <softhsm_>`_, while still transparently providing the same API
> +to code signing consumers.
> +
> +.. _pkcs11-doc: https://www.cryptsoft.com/pkcs11doc/
> +.. _softhsm: https://www.opendnssec.org/softhsm/
>  
> -For each role a PKCS#11 URI must be known by ptxdist.
> -In case of a HSM the keys and certificates are stored in the HSM, but ptxdist
> +.. _code_signing_providers:
> +
> +Code Signing Providers
> +~~~~~~~~~~~~~~~~~~~~~~
> +
> +For each role a PKCS#11 URI must be known by PTXdist.

"known to PTXdist" sounds more natural to me here, but that's only a
small nitpick in case someone finds any more issues that justify a full
v2 ;)

 - Roland

> +In case of an HSM the keys and certificates are stored in the HSM, but PTXdist
>  needs to know the PKCS#11 URI to access the keys.
> -This is done in ptxdist rule files calling cs_set_uri <role> <uri>.
> -For SoftHSM the URI is generated internally by ptxdist, but instead the
> -keys/certificates for each role have have to be imported.
> -This is done with the cs_import_* functions below.
> -
> -During each invocation of ptxdist exactly one key provider is active.
> -The code signing provider can be chosen with the PTXCONF_CODE_SIGNING_PROVIDER
> -variable.
> -A code signing provider is a package resposible for providing the role <->
> -PKCS#11 URI relationships in case a HSM is used or for providing the key
> +For SoftHSM the URI is generated internally by PTXdist, but instead the
> +keys/certificates for each role have to be imported by the code signing
> +provider into the SoftHSM.
> +
> +A code signing provider is a package responsible for providing the role ↔
> +PKCS#11 URI relationships in case an HSM is used, or for providing the key
>  material in case SoftHSM is used.
>  
> -A package which wants to sign something or which needs access to keys has to
> -select CODE_SIGNING.
> -This makes sure the keys are ready when the package is being built.
> +When ``PTXCONF_CODE_SIGNING`` is enabled exactly one code signing provider is
> +active during each invocation of PTXdist.
> +
> +PTXdist comes equipped with a development code signing provider "devel"
> +implemented via the package ``host-ptx-code-signing-dev``.
> +It imports publicly available development keys for each role into the SoftHSM.
> +
> +.. important:: The ``host-ptx-code-signing-dev`` code signing provider can be
> +  used to sign artifacts for development purposes, but **must not** be used for
> +  production.
> +
> +Creating Custom Code Signing Providers
> +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> +
> +When a set of release keys or project-specific development keys should be
> +used (e.g. to achieve backward compatibility) a new code signing provider
> +must be introduced.
> +
> +Use ``ptxdist newpackage code-signing-provider`` to generate such a new code
> +signing provider.
> +The generated files must now be adjusted to the use case, depending on whether
> +a specific HSM or SoftHSM should be used.
> +The generated shell script in ``local_src/<name>-code-signing/`` contains
> +examples for both use cases.
> +See :ref:`code_signing_helper_functions` for an explanation of the available
> +code signing helpers.
> +It is the code signing provider's responsibility to select the host
> +tools required by the code signing helper functions it uses.
> +In case of SoftHSM use cases the keys should also be placed inside
> +``local_src/<name>-code-signing/``
> +
> +In case an HSM is used it is required to extend the ``CODE_SIGNING_ENV`` with
> +additional environment variables via a pre rule in
> +``$(PTXDIST_PLATFORMCONFIGDIR)/rules/pre/``.
> +For example, for Nitrokey HSMs which use *OpenSC* the pre rule could look like
> +this:
> +
> +.. code-block:: make
> +
> +    ifdef PTXCONF_CODE_SIGNING_PROVIDER_<NAME>
> +    CODE_SIGNING_ENV += \
> +    	PKCS11_MODULE_PATH="${PTXDIST_SYSROOT_HOST}/lib/pkcs11/opensc-pkcs11.so"
> +    endif
> +
> +Note that the module is built in the BSP in this case (via
> +``select HOST_OPENSC_PCSC`` in the code signing provider's menu file).
> +This is not strictly required, it is also possible to use an otherwise
> +distributed module, e.g. by the HSM manufacturer.
> +
> +Switching the code signing provider is now possible with
> +``ptxdist platformconfig``, then navigate to *Code signing* → *Code signing
> +provider*.
> +
> +Code Signing Consumers
> +~~~~~~~~~~~~~~~~~~~~~~
> +
> +A package has to select ``CODE_SIGNING`` if it wants to sign something, or if
> +it needs access to keys and/or certificates.
> +The config symbol is available in ptxconfig as well as in platformconfig.
> +Selecting this symbol makes sure the keys and certificates are ready when the
> +package is being built.
> +
> +By adding ``CODE_SIGNING_ENV`` to the package's make/conf/image environment a
> +tool implementing a PKCS#11 interface can access the HSM or SoftHSM.
> +The PKCS#11 URI can be retrieved via :ref:`cs_get_uri` and passed on, usually
> +also via an environment variable.
> +
> +:ref:`cs_get_ca` can be used to install a keyring to the root file system, e.g.:
> +
> +.. code-block:: none
> +
> +    $(call install_copy, rauc, 0, 0, 0644, \
> +      $(shell cs_get_ca update), \
> +      /etc/rauc/ca.cert.pem)
> +
> +.. note:: When code signing helper functions are used in make variables (e.g.
> +  for environment definitions) recursively expanded variables must be used
> +  (``=``, not ``:=``).
> +  Otherwise the variable is expanded before a code signing provider can perform
> +  its setup.
> -- 
> 2.27.0
> 
> 

-- 
Roland Hieber, Pengutronix e.K.          | r.hieber@pengutronix.de     |
Steuerwalder Str. 21                     | https://www.pengutronix.de/ |
31137 Hildesheim, Germany                | Phone: +49-5121-206917-0    |
Amtsgericht Hildesheim, HRA 2686         | Fax:   +49-5121-206917-5555 |

_______________________________________________
ptxdist mailing list
ptxdist@pengutronix.de
To unsubscribe, send a mail with subject "unsubscribe" to ptxdist-request@pengutronix.de