meta-swupdate/README

meta-swupdate, Yocto layer for deploy tool
==========================================

This layer's purpose is to add support for a deployment
mechanism of Yocto's images based on swupdate project.

Layer dependencies
------------------

This layer depends on:

URI: git://github.com/openembedded/meta-openembedded.git
subdirectory: meta-oe

Recovery GUI in Rust (swupdategui-rs)
-------------------------------------

swupdategui-rs needs more than scarthgap provides:

* Rust >= 1.77 (scarthgap ships 1.75), for example from
  URI: https://git.yoctoproject.org/meta-lts-mixins
  branch: scarthgap/rust
* clang-native, from
  URI: https://github.com/kraj/meta-clang
  branch: scarthgap
* LVGL >= 9.2: this layer provides LVGL 9.2.2

Without meta-clang or meta-lts-mixins the recipe is skipped, so builds that
do not use the GUI need neither of them.

Documentation for the layer
---------------------------

Documentation for meta-swupdate is part of SWUpdate's docs.

Check for http://sbabic.github.io/swupdate/building-with-yocto.html.

BitBake variable expansion
--------------------------

To insert the values of BitBake variables into the update file, pre- and postfix
the names with "@@". For example, to automatically set the version tag, use the
line `version = "@@DISTRO_VERSION@@";` in your sw-description file.

Image hashing
-------------

During creation of the update file, to get the sha256 hash of the image,
pass $swupdate_get_sha256(IMAGE) (where IMAGE is an image filename).

BitBake auto versions
---------------------

By setting the version tag in the update file to `$swupdate_get_pkgvar(<package-name>)` it is
automatically replaced with `PV` from BitBake's package-data-file for the package
matching the name of the provided <package-name> tag.

To insert the value of a variable from BitBake's package-data-file different to
`PV` (e.g. `PKGV`) you can append the variable name to the tag:
`$swupdate_get_pkgvar(<package-name>@<package-data-variable>)`

SWU image signing
-----------------

There are 3 signing mechanisms supported by meta-swupdate at the moment:

1. RSA signing:

  * Set variable: `SWUPDATE_SIGNING = "RSA"`

  * Set `SWUPDATE_PRIVATE_KEY` to the full path of private key file

2. CMS signing:

  * Set variable: `SWUPDATE_SIGNING = "CMS"`

  * Set `SWUPDATE_CMS_CERT` to the full path of certificate file. A space
    delimited list of certificates may be given to produce a CMS with multiple
    signers (e.g. hybrid classic + post-quantum signing). SWUpdate verifies the
    signers as an AND, so every certificate must be present in the target trust
    store.

  * Set `SWUPDATE_CMS_KEY ` to the full path of private key file. When several
    certificates are listed in `SWUPDATE_CMS_CERT`, list the matching private
    keys here in the same order; the two lists must have the same length.

  * (Optional) Set `SWUPDATE_CMS_EXTRA_CERTS` to a space delimited list of intermediate certificate files

  * (Optional) Set `SWUPDATE_CMS_MD` to the message digest algorithm passed to
    `openssl cms -sign` via `-md` (e.g. `sha256`, `sha512`). When unset, openssl
    picks the signing key's default digest. This is required for signing keys
    that have no default digest such as ML-DSA where openssl otherwise fails
    with "no default digest". `openssl cms` uses a single digest for all
    signers, so with multiple certificates choose one strong enough for the
    strongest key (e.g. `sha512` when any of ML-DSA-65/87 is used).

3. Custom signing tool:

  * Set variable: `SWUPDATE_SIGNING = "CUSTOM"`

  * Set variable `SWUPDATE_SIGN_TOOL' to custom string that needs to be
    executed in order to perform the signing

sw-description is signed and the signature is written to sw-description.sig
which is included in the SWU file.

Encrypted private keys are not currently supported since a secure
mechanism must exist to provide the passphrase.

Maintainer
----------

Stefano Babic <stefano.babic@swupdate.org>

Submitting patches
------------------

You can submit your patches (or post questions regarding
this layer to the swupdate Mailing List:

	swupdate@googlegroups.com

When creating patches, please use something like:

    git format-patch -s --subject-prefix='meta-swupdate][PATCH' <revision range>

Please use 'git send-email' to send the generated patches to the ML
to bypass changes from your mailer.