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

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

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

  * (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".

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.