Thanks, applied as e1209bf1f06d2518b7e24f62eca5d64052f94d21. Michael
[sent from post-receive hook] On Sat, 20 Jun 2020 00:04:08 +0200, Bastian Krause <[email protected]> wrote: > Signed-off-by: Bastian Krause <[email protected]> > Reviewed-by: Roland Hieber <[email protected]> > Tested-by: Ladislav Michl <[email protected]> > Message-Id: <[email protected]> > Signed-off-by: Michael Olbrich <[email protected]> > > diff --git a/doc/dev_code_signing.rst b/doc/dev_code_signing.rst > index de0087f8b36a..fbebb6b524e1 100644 > --- a/doc/dev_code_signing.rst > +++ b/doc/dev_code_signing.rst > @@ -3,34 +3,136 @@ > 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/ > + > +.. _code_signing_providers: > > -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 > +~~~~~~~~~~~~~~~~~~~~~~ > + > +For each role a PKCS#11 URI must be known by PTXdist. > +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. > +PTXdist distinguishes between "SoftHSM", "HSMs with OpenSC support" and > "other > +HSMs". > +The generated shell script in ``local_src/<name>-code-signing/`` contains > +an examples for the selected HSM use case. > +See :ref:`code_signing_helper_functions` for an explanation of the available > +code signing helpers. > +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 SoftHSM such a pre rule exists already in upstream PTXdist in > +``rules/pre/020-code-signing-softhsm.make``. > +For HSMs with *OpenSC* support a pre rule is generated in > +``$(PTXDIST_PLATFORMCONFIGDIR)/rules/pre/020-<name>-code-signing-hsm.make``. > +For other HSMs a skeleton pre make file is generated and must be adjusted. > + > +For example, for Nitrokey HSMs which use OpenSC the generated pre rule looks > +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. > +This is not strictly required, it is also possible to use an otherwise > +distributed module, e.g. by the HSM manufacturer. > +For HSMs supported by OpenSC the required OpenSC selects are generated. > +If an HSM without OpenSC support is used the ``select FIXME`` should either > be > +replaced with an appropriate host tool that provides the PKCS#11 module or > +removed altogether if an external PKCS#11 module is used. > + > +Switching the code signing provider is now finally possible with > +``ptxdist platformconfig``, then navigate to *Code signing* → *Code signing > +provider*. > + > +.. _code_signing_consumers: > + > +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. _______________________________________________ ptxdist mailing list [email protected] To unsubscribe, send a mail with subject "unsubscribe" to [email protected]
