Welma Secure Update¶

Welma Secure Update provides authentication of software update packages before they are installed on the device. It ensures that only update packages signed with an authorized signing key can be accepted for installation.

Package authentication is based on asymmetric cryptography. Update packages are signed using a private key, while the corresponding public key is provisioned on the device and used to verify the package signature before installation.

Secure Update complements Secure Boot: Secure Update authenticates software before it is installed, while Secure Boot authenticates software before it is executed during the boot process.

Overview¶

When Secure Update is enabled, each software update package must contain a valid cryptographic signature.

The authentication principle can be summarized as follows:

                        +---------------------+
update package ----->   | Signing environment | <----- Private signing key
                        +----------+----------+
                                   |
                                   v
                          Signed update package
                                   │
                          +--------v--------+
                          | Embedded device | <----- Public verification key
                          +--------+--------+
                                   │
                                   v
                         Authenticate signature
                                   |
                           +-------+-------+
                           │               │
                    Valid signature  Invalid signature
                           |               |
                           v               v
                        Install         Reject

Two elements are therefore required:

• The embedded software must be provisioned with a public key used to authenticate update packages.
• Update packages must be signed with the corresponding private key.

Welma supports using either SWK1 or SWK2 for update package authentication.

Authentication keys¶

Secure Update uses the same Software Signing Key infrastructure as Welma Secure Boot.

SWK1¶

SWK1 is the primary Software Signing Key. Its public key is anchored in the boot chain and can also be made available to userspace for update package authentication.

When SWK1 is selected for Secure Update, packages are signed using the SWK1 private key and authenticated on the target using its public key.

SWK2¶

SWK2 provides key delegation and can be used instead of SWK1 for userspace authentication, including Secure Update.

Using SWK2 makes it possible to separate the key used to authenticate update packages from the primary SWK1 key anchored in the secure boot chain.

When SWK2 is configured, its certificate is embedded in the boot software and authenticated through the secure boot chain. The corresponding public key is then made available to userspace and used to authenticate update packages.

If both SWK1 and SWK2 are configured, SWK2 takes precedence for userspace authentication.

For more information about SWK1, SWK2 and key delegation, see:

• Authentication with SWK1
• Key delegation with SWK2

Yocto configuration¶

Secure Update is controlled through the WELMA_SECURE_UPDATE Yocto variable:

WELMA_SECURE_UPDATE = "1"

Secure Update is enabled by default.

The signing and verification keys are configured using either the SWK1 variables:

WELMA_KEY_SWK1_PUB = "<path/to/SWK1.crt>"
WELMA_KEY_SWK1_PRIV = "<path/to/SWK1.key>"

or the SWK2 variables:

WELMA_KEY_SWK2_PUB = "<path/to/SWK2.crt>"
WELMA_KEY_SWK2_PRIV = "<path/to/SWK2.key>"

Either SWK1 or SWK2 can be used for Secure Update. If both are configured, SWK2 is used for package authentication.

During development, these variables allow Yocto to provision the software with the appropriate public key and generate signed update packages.

For production systems, private production keys should not need to be part of the Yocto build environment. Welma provides signing tools to provision the appropriate public key and sign the generated artifacts outside of the Yocto build.

Using production keys¶

Welma provides welma-signing-tools to replace development keys with production keys and sign update packages outside of the Yocto build environment.

The production workflow consists of two operations:

1. Provision the embedded software with the production public key.
2. Sign update packages with the corresponding production private key.

How the public key is provisioned depends on whether SWK1 or SWK2 is used and on the boot architecture.

Inject SWK1 in the bootloader¶

When SWK1 is used, its public key is provisioned as part of the secure boot chain in the bootloader.

The exact procedure is platform-specific. Refer to the corresponding Welma Secure Boot documentation for instructions on provisioning SWK1: Secure Boot on IMX with HABv4, Secure Boot on IMX with AHAB or Secure Boot on STM32MP25x

Inject SWK2 in the kernel FIT image¶

On systems using a kernel FIT image, the SWK2 certificate is stored in the ramdisk at /etc/swk/swk2.crt

To replace it with a production certificate:

1. Extract fitImage from the BOOT package, (eg: using mcopy)
2. Inject the production SWK2 certificate into the ramdisk at path /etc/swk/swk2.crt:

welma-signing-tools/common/inject-file-fitimage-ramdisk \
    fitImage \
    CERTIFICATE \
    /etc/swk/swk2.crt

1. Rebuild the BOOT package with the updated fitImage (eg: using mcopy).

The resulting BOOT software contains the production SWK2 certificate that will be used to establish the userspace verification key.

Inject SWK2 in the UEFI Comboapp¶

On UEFI systems, the Comboapp is located in the BOOT package as an EFI executable (eg: bootx86.efi)

To provision a production SWK2 certificate:

1. Extract the Comboapp from the BOOT package.
2. Inject the production certificate into its ramdisk:

welma-signing-tools/common/inject-file-comboapp-ramdisk \
    bootx86.efi \
    CERTIFICATE \
    /etc/swk/swk2.crt

1. Rebuild the BOOT package with the updated Comboapp.

Signing update packages¶

Once the target software has been provisioned with the appropriate production public key, update packages must be signed using the corresponding private key.

The signing procedure depends on the software update backend.

SWUpdate¶

For the SWUpdate backend, an existing SWU package can be signed using welma-signing-tools:

welma-signing-tools/swupdate/sign-swu SWU-FILE PRIV-KEY

SWU-FILE is the update artifact to sign and PRIV-KEY is the private key corresponding to the public key provisioned on the target.

The resulting signed SWU can then be distributed to devices configured to authenticate updates with that key.

Mender¶

For the mender and mender-connected backends, Mender artifacts can be signed using mender-artifact.

See also¶

• Welma Delta Update