On 6/8/20 12:16 PM, Roland Hieber wrote:
> On Mon, Jun 08, 2020 at 10:53:04AM +0200, Bastian Krause wrote:
>> Signed-off-by: Bastian Krause <[email protected]>
>> ---
>> 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 ;)
"For each role a PKCS#11 URI must be known by PTXdist." is a perfectly
valid sentence. "known to" as well as "known by" are applicable. I would
leave it this way, unless some grammar guru explains the difference in
this very sentence and argues Roland's variant fits better.
Regards,
Bastian
>
> - 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
>>
>>
>
--
Pengutronix e.K. | |
Steuerwalder Str. 21 | http://www.pengutronix.de/ |
31137 Hildesheim, Germany | Phone: +49-5121-206917-0 |
Amtsgericht Hildesheim, HRA 2686 | Fax: +49-5121-206917-5555 |
_______________________________________________
ptxdist mailing list
[email protected]
To unsubscribe, send a mail with subject "unsubscribe" to
[email protected]
