Re: [docs] [PATCH] Document shared state signing

["Ulrich Ölmann" <u.oelmann@pengutronix.de>]

Hi Antonin,

didn't know that we can sign the sstate - thanks for writing things down!
Just a few typos.

On Fri, Apr 17 2026 at 15:30 +0200, "Antonin Godard via lists.yoctoproject.org" <antonin.godard=bootlin.com@lists.yoctoproject.org> wrote:
> Document the shared state signing feature. Add a new document in the
> Security manual, and definitions for the variables involved in this
> process in the variable glossary.
>
> [YOCTO #15217]
>
> Signed-off-by: Antonin Godard <antonin.godard@bootlin.com>
> ---
>  documentation/overview-manual/concepts.rst       |   6 +
>  documentation/ref-manual/variables.rst           |  50 +++++
>  documentation/security-manual/index.rst          |   1 +
>  documentation/security-manual/sstate-signing.rst | 272 +++++++++++++++++++++++
>  4 files changed, 329 insertions(+)
>
> diff --git a/documentation/overview-manual/concepts.rst b/documentation/overview-manual/concepts.rst
> index ab723d7c3..f0b336226 100644
> --- a/documentation/overview-manual/concepts.rst
> +++ b/documentation/overview-manual/concepts.rst
> @@ -1240,6 +1240,12 @@ variable is the function that determines whether a given dependency
>  needs to be followed, and whether for any given relationship the
>  function needs to be passed. The function returns a True or False value.
>
> +.. note::
> +
> +   Is is possible to sign these artifacts with :wikipedia:`GPG
> +   <GNU_Privacy_Guard>`. See :doc:`/security-manual/sstate-signing` in the Yocto
> +   Project Security Manual for more information.
> +
>  Images
>  ------
>
> diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst
> index 317b75913..7387a5d25 100644
> --- a/documentation/ref-manual/variables.rst
> +++ b/documentation/ref-manual/variables.rst
> @@ -10097,6 +10097,25 @@ system and gives an overview of their function and contents.
>
>        For details on the process, see the :ref:`ref-classes-staging` class.

[...]

> +   :term:`SSTATE_VERIFY_SIG`
> +      The :term:`SSTATE_VERIFY_SIG` variable controls whether to enable of
> +      disable the :ref:`shared state <overview-manual/concepts:setscene tasks

s/whether to enable of disable/whether to enable or disable/

> +      and shared state>` artifacts signing feature.

[...]

> diff --git a/documentation/security-manual/sstate-signing.rst b/documentation/security-manual/sstate-signing.rst
> new file mode 100644
> index 000000000..1845b890f
> --- /dev/null
> +++ b/documentation/security-manual/sstate-signing.rst
> @@ -0,0 +1,272 @@
> +.. SPDX-License-Identifier: CC-BY-SA-2.0-UK
> +
> +Shared State Signing
> +********************
> +
> +The :term:`OpenEmbedded Build System` build system has a built-in mechanism
> +allowing to save execution time by re-using pre-built artifacts: the
> +:ref:`shared state cache (sstate cache) <overview-manual/concepts:shared state
> +cache>`. These artifacts are stored in a directory (:term:`SSTATE_DIR`) are not
> +signed by default.

The last sentence probably misses a conjunction, what about

s/are not signed by default/and are not signed by default/ ?

> +
> +This document goes through the steps to enable shared state signing.
> +This feature is fully dependent on :wikipedia:`GPG <GNU_Privacy_Guard>`, meaning
> +examples shown in this document will use the ``gpg`` command-line tool.

[...]

> +Shared State Location
> +---------------------
> +
> +Our build system needs to be configured to sign new sstate artifacts when they
> +are generated. The generation of new artifacts is done once a task has finished
> +being executed.
> +
> +For the following sections let's assume that our build system has the shared
> +state directory location (:term:`SSTATE_DIR`) defined as follows::
> +
> +   SSTATE_DIR = "${TOPDIR}/sstate-cache"
> +
> +Assuming this directory and our temporary directory (:term:`TMPDIR`) is empty,

s/is empty/are empty/

> +as an example throughout this document, let's run the ``create_recipe_spdx``
> +task of the ``gettext-minimal-native`` recipe:
> +
> +.. code-block:: console
> +
> +   $ bitbake gettext-minimal-native -c create_recipe_spdx
> +
> +After execution, our shared state directory should be populated with new files:
> +
> +.. code-block:: console
> +
> +   $ find $BUILDDIR/sstate-cache/ -name "*gettext-minimal-native*create_recipe_spdx*"
> +   sstate-cache/universal/a3/6e/sstate:gettext-minimal-native:x86_64-linux:1.0:r0:x86_64:14:a36ef66df6b8c0cb5a849bc70a99dcfd61e4bacd11cefe6bbaf4978b2b3b617a_create_recipe_spdx.tar.zst
> +   sstate-cache/universal/a3/6e/sstate:gettext-minimal-native:x86_64-linux:1.0:r0:x86_64:14:a36ef66df6b8c0cb5a849bc70a99dcfd61e4bacd11cefe6bbaf4978b2b3b617a_create_recipe_spdx.tar.zst.siginfo

[...]

> +Verifying Signed Shared State Artifacts
> +=======================================
> +
> +Now that we have setup our build to sign shared state artifacts,
> let's see how

s/we have setup our build/we have set up our build/

> +we can verify them with the public key counterpart of the private key.
> +
> +.. note::
> +
> +   Signature of shared state and its verification can happen on two different
> +   hosts, meaning one host can be in charge of the signature while another only
> +   verifies the artifacts. This is preferred as the private key should not be
> +   shared spread on multiple hosts.

[...]

> +   As you can see, this does not prevent :term:`BitBake` from continuing, but
> +   the the real task is executed instead of re-using the shared state.

s/but the the real task/but the real task/

Best regards,
Ulrich


>
> ---
> base-commit: 2c12ec7bf29aedeacf82970a9d2eb262fde4670e
> change-id: 20260417-sstate-signing-f96c75ce1917
>
>
> -=-=-=-=-=-=-=-=-=-=-=-
> Links: You receive all messages sent to this group.
> View/Reply Online (#9276): https://lists.yoctoproject.org/g/docs/message/9276
> Mute This Topic: https://lists.yoctoproject.org/mt/118875161/3618626
> Group Owner: docs+owner@lists.yoctoproject.org
> Unsubscribe: https://lists.yoctoproject.org/g/docs/unsub [u.oelmann@pengutronix.de]
> -=-=-=-=-=-=-=-=-=-=-=-
-- 
Pengutronix e.K.                           | Ulrich Ölmann               |
Industrial Linux Solutions                 | http://www.pengutronix.de/  |
Peiner Str. 6-8, 31137 Hildesheim, Germany | Phone: +49-5121-206917-0    |
Amtsgericht Hildesheim, HRA 2686           | Fax:   +49-5121-206917-5555 |