9. Add encryption to bundles

RAUC encrypted bundles protect the confidentiality of an update while it is stored or transferred. Encryption is separate from bundle signing:

  • The signing key proves who created the bundle and protects its integrity.

  • The bundle payload key encrypts the payload.

  • The recipient key pair controls which displays can recover the payload key and install the bundle.

For the RAUC crypt format, rauc bundle encrypts the payload using a randomly generated AES-256 key and stores that key in the signed manifest. rauc encrypt then encrypts the signed CMS manifest using the public key for one or more recipient certificates. Because the manifest contains the payload AES key, only a recipient holding a matching private key can recover it. On the CCpilot display, the recipient RSA private key is held by an OP-TEE PKCS#11 token backed by secure storage.

Build host                                         CCpilot display
+-----------------------------------+              +--------------------------------+
| 1. Generate AES-256 payload key   |              | 1. Load PKCS#11 PIN            |
| 2. Encrypt payload                | .raucb file  | 2. Decrypt CMS using OP-TEE    |
| 3. Store AES key in signed        | -----------> | recipient private key          |
| CMS manifest                      |              | 3. Recover AES-256 payload key |
| 4. Encrypt signed CMS manifest    |              | 4. Verify and install bundle   |
| for recipient public key(s)       |              |                                |
+-----------------------------------+              +--------------------------------+

The keys and credentials have separate purposes:

Type

Key or credential

Purpose

Bundle payload key

Symmetric AES-256

Encrypts the payload. RAUC randomly generates a new key for each bundle.

Recipient key pair

Asymmetric RSA-4096

The recipient certificate contains the public key used to encrypt the signed CMS manifest. The matching OP-TEE private key decrypts it.

Developer signing key

Asymmetric RSA

Signs the manifest. It does not encrypt the payload.

Root and intermediate CA keys

Asymmetric RSA

Issue and validate the signing certificates.

SSH login key

Asymmetric RSA-4096

Authenticates SSH access only. It is not used by RAUC bundle encryption.

PKCS#11 user PIN

Credential

Authorizes RAUC to use the recipient private key stored in the OP-TEE PKCS#11 token. Generated per display during provisioning.

PKCS#11 SO PIN

Credential

Security Officer PIN used only to initialize the token during provisioning. Set as PKCS11_SO_PIN in conf.sh.

The procedure in this section follows Example 3 in the RAUC Package Generation Tools for CrossControl Displays repository, the same repository used in 8.1. Generate customer signing keys. The repository contains all scripts, configuration files, manifests, and example content referenced below. Run all host commands from the root of the cloned repository.

Important

The example signs bundles with the keys in openssl-ca/, generated in 8.1. Generate customer signing keys. The encrypted initialization bundle removes all CA certificates in /data/rauc/certs/ and installs the root CA from openssl-ca/.

The encrypted initialization bundle is signed with the CrossControl demo key, so it is intended for a display that still uses the demo CA. A display that has already been switched to customer keys, see 8. Switch to customer keys, rejects it. In that case, build it with ./build-all-encrypted.sh --init --customer-keys, see 9.5. Build the bundles.

9.1. Prerequisites and scope

The example requires:

  • CCpilot display running a CCLinux 5.1 or newer with OP-TEE PKCS#11 support.

  • SSH access to the display.

  • A Linux development computer with OpenSSL, ssh-keygen, mkfs.ext4, debugfs, and a compatible CCLinux SDK. mkfs.ext4 and debugfs are included in e2fsprogs.

Use the example repository set up in 5.2. Set up the example repository.

Warning

The example scripts demonstrate the complete workflow, but their default credentials and provisioning behavior must be reviewed before production use. In particular, provision-device-optee.sh initializes the selected PKCS#11 token and deletes all objects already stored in that token.

9.2. Configure the example

Open conf.sh and set at least the following values:

SDK_INSTALL_PATH=/opt/<cclinux-sdk-directory>
CA_ORG="<company-name>"
DEVICE_HOST="ccs@<display-hostname-or-address>"
PKCS11_SO_PIN="<secret-so-pin>"

SDK_INSTALL_PATH is the installed CCLinux SDK for the selected display. CA_ORG is the company name written to the signing certificates, see 8.1. Generate customer signing keys. DEVICE_HOST is the default SSH destination used by the provisioning script. PKCS11_SO_PIN is the Security Officer PIN used by provision-device-optee.sh to initialize the PKCS#11 token.

Warning

The repository default PKCS11_SO_PIN="12345678" is public. Replace it with a secret value before provisioning production displays, and do not commit the changed value to source control.

The initialization bundle installs customer-initialization-encrypted-1.0.0/system.conf on the display. build-all-encrypted.sh generates this file from /etc/rauc/system.conf in the rootfs of the OS update bundle and adds the [encryption] section, see 9.5. Build the bundles. token and id are taken from PKCS11_TOKEN_LABEL and PKCS11_ENC_KEY_ID in conf.sh:

[encryption]
key=pkcs11:token=rauc-token;id=%02;type=private
cert=pkcs11:token=rauc-token;id=%02;type=cert

The script also sets compatible in both manifests to the value in the OS update bundle.

9.3. Generate the signing, encryption, and SSH login keys

Generate the customer signing PKI, the RSA encryption key pair, and the SSH login key on the development computer.

If openssl-ca/ does not exist yet, generate the signing PKI first. Skip this step if the keys were already generated in 8.1. Generate customer signing keys. The script stops with an error if openssl-ca/ already exists:

$ ./generate-ca.sh

Then generate the encryption key pair and the SSH login key:

$ ./generate-enc-key.sh
$ ./generate-login-key.sh

generate-ca.sh creates the root, development, and release signing hierarchy in openssl-ca/, as described in 8.1. Generate customer signing keys. The encrypted bundle script uses the developer-1 signing key and certificate.

generate-enc-key.sh creates:

  • bundle-enc-key/rauc-enc.key.pem: RSA-4096 private key imported into each display.

  • bundle-enc-key/rauc-enc.cert.pem: recipient certificate containing the RSA public key used by rauc encrypt.

Both files are generated locally and excluded from source control by the repository .gitignore. The script refuses to overwrite an existing pair. Deleting and regenerating these files is a key rotation: displays must be provisioned with the new private key before they can install bundles whose CMS manifest is encrypted for the public key in the new recipient certificate.

generate-login-key.sh creates the SSH key pair openssl-login/ccpilot-login-key and openssl-login/ccpilot-login-key.pub. The initialization bundle installs the public key on the display and disables password authentication.

Warning

Keep the signing keys, rauc-enc.key.pem, and ccpilot-login-key confidential and backed up. Do not commit private keys to source control. The example uses one shared encryption key for all provisioned devices, so disclosure of that key affects every device in the group.

9.4. Provision the OP-TEE PKCS#11 token

Provision each display once, before installing the encrypted initialization bundle. The encrypted initialization bundle enables the [encryption] section in system.conf and configures rauc.service to read the PKCS#11 PIN file. Provisioning first ensures that the token, the encryption key, and the PIN file already exist when RAUC starts with this configuration.

How the key is stored on the display

OP-TEE PKCS#11 works like a smart card reader built into the display. It has slots, and each slot can hold one token, similar to a smart card. A token stores objects, such as keys and certificates, each identified by an ID and a label. The provisioning script uses slot 0, names its token rauc-token, and stores the encryption key and its certificate with ID 02:

OP-TEE PKCS#11
+-- Slot 0: token "rauc-token"
|     +-- ID 02  private key   "rauc-enc-key"
|     +-- ID 02  certificate   "rauc-enc-cert"
+-- Other slots: not used by this example

RAUC finds the key through the token label and object ID in the pkcs11: URIs in system.conf. Using the private key requires the user PIN, which the script generates for each display. The token content is kept in OP-TEE secure storage, isolated from Linux. Because the key is imported from the build host, the copy in bundle-enc-key/ must still be protected.

Use the host configured in conf.sh or supply it on the command line:

$ ./provision-device-optee.sh
$ ./provision-device-optee.sh ccs@<display-hostname-or-address>

The script performs the following operations:

  1. Copies the RSA private key and certificate to /tmp over SSH.

  2. Stops rauc.service so it does not hold an open PKCS#11 session.

  3. Registers the OP-TEE PKCS#11 module and prepares its persistent data directories.

  4. Generates a random, device-specific PKCS#11 user PIN.

  5. Stores the PIN in /data/rauc/pkcs11-pin.env with mode 0600.

  6. Initializes the token, imports the private key and certificate as object ID 02, and removes the plaintext copies from /tmp.

  7. Restarts rauc.service.

Re-running the script reinitializes the token, removes its existing objects, and generates a new user PIN. Do not run it if the token contains keys needed by another service.

When the file set by DEVICE_SSH_KEY in conf.sh exists, the script passes it to SSH. The default is openssl-login/ccpilot-login-key. On a display that is not yet initialized, SSH falls back to password login. After initialization, password login is disabled, so re-provisioning a display, for example during key rotation, requires DEVICE_SSH_KEY to point to the SSH private key installed by the initialization bundle.

The example disables SSH host-key checking while provisioning. Use a trusted, isolated network or update the script to verify the target’s SSH host key before transferring production key material.

To verify the imported objects without printing the PIN, run the following on the display:

$ sudo sh -c '. /data/rauc/pkcs11-pin.env; \
  pkcs11-tool --module /usr/lib/libckteec.so.0 \
  --token-label rauc-token --login --pin "$RAUC_PKCS11_PIN" \
  --list-objects'

The output should contain a private key and a certificate with ID 02.

9.5. Build the bundles

  1. Add your application to appfs/, as described in 6.2. Add the application to the appfs.

  2. Place the CrossControl OS update bundle in cclinux-rauc-bundles/, as described in 6.3. Build the bundle.

  3. Build the bundles:

    $ ./build-all-encrypted.sh --init
    

    The script:

    • Creates appfs.ext4, extracts the rootfs from the OS update bundle, and copies both to release-encrypted-1.0.0/.

    • Sets compatible and the rootfs filename in the manifests to match the OS update bundle.

    • With --init, generates customer-initialization-encrypted-1.0.0/system.conf from the rootfs, with the [encryption] section added, and creates initialization-encrypted-1.0.0.raucb, a verity bundle signed with the demo key.

    • Creates install-package-encrypted-1.0.0.raucb, signed with the customer key and encrypted for the recipient certificate in bundle-enc-key/rauc-enc.cert.pem.

    If the display already trusts the customer CA, see 8.3. Install the customer CA, add --customer-keys to sign the initialization bundle with the customer key instead.

    The appfs image is 800 MB by default. Set another size in MB with --appfs-size. Resigned bundles in cclinux-rauc-bundles/ are ignored. If the folder contains more than one other bundle, select the CrossControl bundle with --bundle. For later releases, omit --init to only build the release bundle. Run ./build-all-encrypted.sh --help for all options.

For the manual steps, see Appendix C. Create encrypted bundles manually.

The release bundle is both signed and encrypted. A display must trust the signing CA and hold the recipient private key matching the public key in the recipient certificate to install it.

9.6. Install the initialization bundle

The initialization bundle has a custom handler that:

  • Replaces the CrossControl demo certificate with the generated customer root CA.

  • Installs the generated SSH public key and disables password login.

  • Installs the generated RAUC system.conf with the [encryption] section.

  • Installs a systemd drop-in that provides RAUC_PKCS11_MODULE and reads RAUC_PKCS11_PIN from the root-only environment file.

Warning

After initialization, the target no longer accepts bundles signed with the public demo key and no longer accepts password-based SSH login. Verify that the customer signing keys and SSH private key are available before installing the initialization bundle.

Install this bundle using the 7.1. USB update procedure, or transfer and install it manually:

$ scp initialization-encrypted-1.0.0.raucb ccs@<display-hostname-or-address>:
$ ssh ccs@<display-hostname-or-address>
[CCpilot]$ rauc install initialization-encrypted-1.0.0.raucb
[CCpilot]$ sudo reboot

After reboot, use the generated private SSH key and verify that RAUC starts successfully:

$ ssh -i openssl-login/ccpilot-login-key ccs@<display-hostname-or-address>
[CCpilot]$ systemctl is-active rauc.service
[CCpilot]$ rauc status

9.7. Verify and install the encrypted bundle

Transfer the bundle to an initialized display:

$ scp -i openssl-login/ccpilot-login-key \
  install-package-encrypted-1.0.0.raucb \
  ccs@<display-hostname-or-address>:

rauc info needs the same PKCS#11 environment as rauc.service. Verify the bundle on the display with:

[CCpilot]$ sudo sh -c '. /data/rauc/pkcs11-pin.env; \
  export RAUC_PKCS11_PIN; \
  RAUC_PKCS11_MODULE=/usr/lib/libckteec.so.0 \
  rauc info /data/home/ccs/install-package-encrypted-1.0.0.raucb'

The output should report Bundle Format: crypt [encrypted CMS] and a valid signing certificate chain.

Install the bundle and reboot:

[CCpilot]$ rauc install install-package-encrypted-1.0.0.raucb
[CCpilot]$ sudo reboot

The standard USB update procedure also supports the encrypted bundle after the display has been initialized and provisioned. Keep only one .raucb file in the root of the USB drive.

After reboot, use rauc status to confirm the active slots. Installation details are written to /data/rauc/install.log.

9.8. Key strategies and rotation

The example provisions the same RSA private key to every display. This is simple for evaluation, but all displays can decrypt the same bundles and compromise of the shared key affects the complete fleet.

For production, choose a recipient strategy that matches the deployment:

  • Fleet key: One recipient key for all displays. Simple bundle distribution, largest impact if the key is disclosed.

  • Batch key: One recipient key per production batch or customer group. Limits the affected population while keeping bundle management practical.

  • Per-display key: One recipient key per display. Best isolation, but requires a display registry and either per-display bundles or bundles encrypted for multiple recipients.

RAUC can encrypt the signed CMS manifest for multiple recipients. Concatenate the recipient certificates and set CRYPT_CERT in build-all-encrypted.sh to the resulting PEM file. Each certificate contains an RSA public key for one recipient:

$ cat batch-A.cert.pem batch-B.cert.pem > recipients.pem

For rotation, provision the new private key before distributing bundles whose CMS manifest is encrypted for the public key in the new certificate. Replacing the token key also prevents the display from decrypting bundles that only include the old recipient. Initialized displays only accept SSH key login, so re-provisioning requires DEVICE_SSH_KEY as described in 9.4. Provision the OP-TEE PKCS#11 token.

9.9. Troubleshooting

The provisioning script reports a PKCS#11 session error

Confirm that rauc.service is stopped and that no other process is using the token. The script normally stops RAUC before initializing the token.

The OP-TEE module or token cannot be found

Check that /dev/tee0 exists, that PKCS11_MODULE points to the installed libckteec.so.0, and that the display’s CCLinux image supports OP-TEE PKCS#11.

rauc.service fails after initialization

Check systemctl status rauc.service, the permissions of /data/rauc/pkcs11-pin.env, and that the token contains both objects with ID 02. The PIN file must contain RAUC_PKCS11_PIN=<value> and have mode 0600.

The bundle signature is rejected

Confirm that the initialization bundle installed the same customer root CA that signed the release bundle. Encryption does not replace signature verification.

The bundle cannot be decrypted

Confirm that the signed CMS manifest was encrypted for a recipient certificate whose public key matches the display’s PKCS#11 private key. Also confirm that the token label and object IDs in system.conf match conf.sh.

SSH login fails after initialization

Password authentication is disabled by the initialization bundle. Use openssl-login/ccpilot-login-key with the -i option.

More information is available in the RAUC bundle encryption documentation.

10. Additional security measures

Signed bundles with customer keys, see 8. Switch to customer keys, and optionally encrypted bundles, see 9. Add encryption to bundles, protect the update path. The rest of the system also needs to be hardened before production. Which measures are needed depends on the use case.

The recommended procedures are described in CC Linux – Security Manual.

11. Special-purpose bundles and development

11.1. Bundle that only runs a script

A bundle does not have to contain any images. With a full custom handler, RAUC runs a script from the bundle instead of writing images to the slots. This can be used to change the configuration of a display, for example to update files in /etc or /data, without changing the rootfs or appfs.

The initialization bundle in 9. Add encryption to bundles uses the same method.

The example creates a bundle for a CCpilot V700 that copies the configuration file my-app.conf to /etc on the display. It uses the example repository from 6. Update bundle creation, with a separate script-bundle folder:

rauc-simple-pki-example/
+-- cc-demo-keys/          Demo signing key and certificates
+-- script-bundle/         Bundle content: manifest, script, and files used by it
|   +-- manifest.raucm
|   +-- handler.sh
|   +-- my-app.conf
|   +-- padding.bin
+-- script-demo.raucb      Created bundle

Do not add the script to release-full-1.0.0/. A custom handler replaces the image installation, so the images in that folder would not be written.

  1. Create the folder. As in 6. Update bundle creation, every file in script-bundle is included in the bundle, and subfolders are not allowed:

    $ cd rauc-simple-pki-example
    $ mkdir script-bundle
    
  2. Create script-bundle/manifest.raucm:

    $ cat > script-bundle/manifest.raucm << 'EOF'
    [update]
    compatible=CrossControl V700
    version=1.0.0
    description=Configuration update
    
    [bundle]
    format=verity
    
    [handler]
    filename=handler.sh
    EOF
    

    compatible must exactly match the value in the display’s /etc/rauc/system.conf, as described in 6. Update bundle creation. Change it if you use another display.

  3. Create the script script-bundle/handler.sh. The bundle content is available on the display in the directory set by RAUC_BUNDLE_MOUNT_POINT:

    $ cat > script-bundle/handler.sh << 'EOF'
    #!/bin/sh
    set -e
    cp "$RAUC_BUNDLE_MOUNT_POINT"/my-app.conf /etc/my-app.conf
    EOF
    
  4. Make the script executable. RAUC cannot run it otherwise, and the installation fails:

    $ chmod +x script-bundle/handler.sh
    
  5. Add the files used by the script. This example creates a small configuration file. Replace it with your own file:

    $ echo "setting=1" > script-bundle/my-app.conf
    
  6. Add a padding file. A verity bundle must be larger than 4096 bytes after compression, and a bundle with only small text files is not. Without the padding file, rauc bundle fails with squashfs size (4096) must be larger than 4096 byte. Random data is used because it does not compress:

    $ head -c 8192 /dev/urandom > script-bundle/padding.bin
    
  7. Set up the SDK environment, as described in 5.1. Set up the SDK:

    $ source <sdk-install-dir>/environment-setup-<XXXX>
    
  8. Create and sign the bundle with the demo key in cc-demo-keys/:

    [SDK]$ rauc bundle \
           --conf=rauc-host.conf \
           --keyring=cc-demo-keys/ca.cert.pem \
           --key=cc-demo-keys/development-1.key.pem \
           --cert=cc-demo-keys/development-1.cert.pem \
           script-bundle script-demo.raucb
    

    If the display has been switched to customer keys, use the files generated in 8.1. Generate customer signing keys with --key, --cert, --keyring, and --intermediate.

The bundle script-demo.raucb can now be installed on the display, as described in 7. Install a bundle.

The script runs as root on the display. If it exits with a non-zero code, RAUC reports the installation as failed. No images are written. When the bundle is installed with the USB update or cc-update, the display still reboots after a successful installation, unless DO_UPDATE_AUTO_REBOOT=0 is set, see 7.1. USB update.

Note

To run a script together with a normal image installation, use hooks instead of a custom handler, see 3.1. Hooks. The [hooks] section names the hook script, and each image section lists the hooks to run for that slot. The script is called with the hook name, for example slot-post-install:

[hooks]
filename=hook.sh

[image.appfs]
filename=appfs.ext4
hooks=post-install

A custom handler replaces the image installation completely, so images listed in the same manifest are not written.

See Full Custom Update in the RAUC documentation for the variables available to the script.

11.2. Write to /appfs during development

During application development, it can be faster to copy files directly to the display than to create a bundle for every change. The appfs is mounted read-only, see 2.1. Read-only rootfs and appfs, but it can be remounted as writable:

[CCpilot]$ sudo mount -o remount,rw /appfs
# Copy or change files in /appfs
[CCpilot]$ sudo mount -o remount,ro /appfs

Warning

Only use this during development. Changes made this way are not signed, and RAUC does not track them.

Important

RAUC skips writing a slot if the image in the bundle has the same hash as the image it last installed in that slot, see 3.2. Rootfs and appfs in one bundle. RAUC does not detect manual changes, so installing the same appfs image again may not restore the slot. Before testing the production update, install an appfs image with changed content, or reflash the display with uuu.

12. Using the RAUC D-Bus API

The RAUC service on the display provides a D-Bus API on the system bus. Applications can use it to install bundles and to read the update progress and slot status, for example to show the update in the user interface. The rauc command line tool uses the same API.

Item

Value

Bus name

de.pengutronix.rauc

Object path

/

Interface

de.pengutronix.rauc.Installer

The most commonly used members:

Member

Description

InstallBundle()

Starts the installation of a bundle from a local path or an HTTP(S) address. The call returns immediately.

Progress property

Installation progress as percentage, message, and nesting depth.

Completed signal

Emitted when the installation has finished. The result is 0 on success.

LastError property

The last error message.

InspectBundle()

Returns the manifest information of a bundle, the same as rauc info.

GetSlotStatus()

Returns the status of all slots, the same as rauc status.

Mark()

Marks a slot as good, bad, or active, the same as rauc status mark-*.

The API can be tested from the command line with busctl. For example, to read the slot status:

[CCpilot]$ busctl call de.pengutronix.rauc / de.pengutronix.rauc.Installer GetSlotStatus

After a successful installation, the application must reboot the display to start the updated slot. The USB update, see 7.1. USB update, also installs bundles through RAUC. If the application handles updates itself, consider setting DO_USB_UPDATE=0.

A Qt based example application for handling USB or OTA updates is available on request from CrossControl.

The complete API is described in D-Bus API in the RAUC documentation.

13. BSP integration

This chapter is intended for customers who build their own CCLinux image from the CrossControl BSP with Yocto. It describes how RAUC is integrated in the BSP, and how to use customer keys when building bundles. Yocto support for RAUC is provided by the meta-rauc layer.

13.1. Bundle recipe

Bundles are built by recipes that inherit the bundle class from meta-rauc. The recipe variables correspond to the manifest settings described in 6. Update bundle creation. Example recipe for a V700 system update bundle:

DESCRIPTION = "V700 system update bundle generator"

inherit bundle

RAUC_BUNDLE_COMPATIBLE = "CrossControl V700"
RAUC_BUNDLE_SLOTS = "bootloader rootfs appfs"
RAUC_BUNDLE_FORMAT = "verity"

# Slot bootloader
RAUC_SLOT_bootloader = "imx-boot"
RAUC_SLOT_bootloader[file] = "imx-boot.img"
RAUC_SLOT_bootloader[depends] = "imx-boot:do_deploy"

# Slot rootfs
RAUC_SLOT_rootfs = "ccpilot-v700-release"
RAUC_SLOT_rootfs[fstype] = "ext4"
RAUC_SLOT_rootfs[adaptive] = "block-hash-index"

# Slot appfs
RAUC_SLOT_appfs = "ccpilot-v700-appfs"
RAUC_SLOT_appfs[fstype] = "ext4"
RAUC_SLOT_appfs[adaptive] = "block-hash-index"

RAUC_KEY_FILE = "${OEROOT}/../meta-cc/meta-bsp-v700/recipes-core/rauc/files/development-1.key.pem"
RAUC_CERT_FILE = "${OEROOT}/../meta-cc/meta-bsp-v700/recipes-core/rauc/files/development-1.cert.pem"
  • RAUC_BUNDLE_SLOTS lists the slot classes to include. Each slot is defined by the RAUC_SLOT_<class> variables: the image recipe, the image file, and options such as fstype and adaptive, see 7. Install a bundle.

  • RAUC_KEY_FILE and RAUC_CERT_FILE select the signing key and certificate, see 13.4. Customer keys in the BSP.

13.2. RAUC system configuration

RAUC on the display is configured by /etc/rauc/system.conf in the rootfs. It defines the compatible value, the bootloader, the slots, and the keyring used to verify bundles. Each display type has its own configuration that matches its partition layout.

Example for the V700:

[system]
compatible=CrossControl V700
bootloader=uboot
data-directory=/data/rauc
bundle-formats=-plain

[keyring]
directory=/data/rauc/certs/
check-purpose=codesign

[log.install-log]
filename=install.log
events=install
format=readable
max-size=100K
max-files=5

[slot.bootloader.0]
device=/dev/mmcblk1
type=boot-emmc
install-same=false

[slot.rootfs.0]
device=/dev/mmcblk1p2
type=ext4
bootname=A
install-same=false

[slot.rootfs.1]
device=/dev/mmcblk1p3
type=ext4
bootname=B
install-same=false

[slot.appfs.0]
device=/dev/mmcblk1p4
type=ext4
parent=rootfs.0
install-same=false

[slot.appfs.1]
device=/dev/mmcblk1p5
type=ext4
parent=rootfs.1
install-same=false

Setting

Description

compatible

Must match the compatible value in the bundle manifest.

bootloader

Bootloader used to switch slots, see 13.3. Bootloader integration.

data-directory

RAUC status, logs, and block hash indexes, see 2.2. The /data partition.

bundle-formats=-plain

Rejects bundles in the plain format, see 3. Update bundles.

[keyring]

CA certificates used to verify bundles, see 8. Switch to customer keys.

[log.install-log]

Writes the installation log to /data/rauc/install.log.

[slot.*]

The bootloader, rootfs, and appfs slots. bootname links a rootfs slot to the bootloader, parent links an appfs slot to its rootfs, and install-same=false enables slot skipping, see 3.2. Rootfs and appfs in one bundle.

Displays using U-Boot generally have the same configuration, apart from compatible. The Extreme line displays, such as the X1200, use GRUB. Their configuration differs in the [system] section and the bootloader slot:

[system]
compatible=CrossControl X1200
bootloader=grub
grubenv=/efi/EFI/BOOT/grubenv
data-directory=/data/rauc
bundle-formats=-plain

[slot.efi.0]
device=/dev/mmcblk0
type=boot-gpt-switch
region-start=1M
region-size=256M
install-same=false

13.3. Bootloader integration

RAUC does not boot the slots itself. It selects the slot to boot, and marks slots as good or bad, by writing variables in the bootloader environment. A boot script in the bootloader reads these variables, selects the slot, and counts the boot attempts. This is what makes the rollback in 7.6. Rollback on boot errors possible.

V700, V1x00, Vx10, Yukon

Extreme line, for example X1200

Bootloader

U-Boot

GRUB

bootloader in system.conf

uboot

grub

Tool used by RAUC

fw_setenv and fw_printenv, from the libubootenv package

grub-editenv, installed with GRUB

Environment location

Configured in /etc/fw_env.config

/efi/EFI/BOOT/grubenv

Boot script

Patch to the board header file in the U-Boot source

grub.cfg from the grub-bootconf recipe, installed in /efi/EFI/BOOT/

Environment variables

BOOT_ORDER, BOOT_A_LEFT, BOOT_B_LEFT

ORDER, A_OK, A_TRY, B_OK, B_TRY

Important

For U-Boot, make sure that libubootenv is included in the image. Without fw_setenv, RAUC cannot switch slots.

The CCLinux U-Boot boot script allows five boot attempts per slot. If no slot has attempts left, it resets both counters to five and restarts.

The boot scripts follow the RAUC reference implementations. See Integration for example U-Boot and GRUB scripts, and Bootloader Interaction for how RAUC uses the variables.

13.4. Customer keys in the BSP

The BSP uses keys in two places:

  • The rauc recipe installs the CA certificate (keyring) used by the display to verify bundles.

  • The bundle recipes sign bundles with the key and certificate set in RAUC_KEY_FILE and RAUC_CERT_FILE.

To build images and bundles that use your own keys, replace both. Generate the keys as described in 8.1. Generate customer signing keys, or use keys from your own PKI. For a test setup, the openssl-ca-create.sh script in the RAUC sources can also be used.

Warning

Do not store private keys in a public source control repository. Anyone with access to the signing key can create bundles that the display installs.

Use the customer keys

  1. Copy the customer CA certificate as ca.cert.pem to meta-cc/meta-<platform>/recipes-core/rauc/files/.

  2. Create meta-cc/meta-<platform>/recipes-core/rauc/rauc_%.bbappend, which adds the folder to the search path of the rauc recipe:

    FILESEXTRAPATHS:prepend := "${THISDIR}/files:"
    

    Alternatively, set RAUC_KEYRING_FILE in the .bbappend file to the path of the CA certificate.

  3. Copy the signing key and certificate to your meta layer, and set them in the bundle recipe, see 13.1. Bundle recipe:

    RAUC_KEY_FILE = "${OEROOT}/../meta-<layername>/files/<signing-key>.pem"
    RAUC_CERT_FILE = "${OEROOT}/../meta-<layername>/files/<signing-cert>.pem"
    

    If the signing certificate is issued by an intermediate CA, as with the keys from 8.1. Generate customer signing keys, also copy the intermediate CA certificate and add it to the bundle arguments:

    BUNDLE_ARGS += "--intermediate=${OEROOT}/../meta-<layername>/files/<intermediate-cert>.pem"
    

Displays in the field

The rauc recipe installs the CA certificate in /data/rauc/certs/ of the image. It is written to the display only when the display is flashed with uuu. /data is not modified by RAUC updates, so installing a bundle with a new CA certificate in the rootfs does not change which bundles a display accepts:

  • Displays flashed with an image built with the customer CA certificate accept only bundles signed with the customer key.

  • Displays already in the field keep the CA certificates in their /data/rauc/certs/, for example the CrossControl demo CA. They reject bundles signed with the customer key until the customer CA is installed, as described in 8.3. Install the customer CA.