OTA Connect Developer Guide

Simulate Uptane metadata transactions

The uptane-generator directory contains a basic tool that generates metadata according to the Uptane spec. It is comprised of three tools:

  1. create_repo.sh is a script to generate a new Uptane metadata repository, an OSTree repository, and all associated credentials and configuration.

  2. serve_repo.py is a script for running a minimalistic Uptane server.

  3. uptane-generator is a low-level tool to generate and control an Uptane repository. It can be used to manipulate the repo created with create_repo.sh, or it can be used entirely independently.

create_repo.sh

create_repo.sh generates the whole Uptane repo together with client and server certificates and OSTree repo that can be used both by meta-updater and by the device. create_repo.sh uses uptane-generator, so make sure it’s in PATH.

Usage

create_repo.sh <repo path> <hostname>

Make sure that the repository path doesn’t already exist and the machine where serve_repo.py will be running is accessible from the device specified by <hostname>.

Integration with bitbake

create_repo.sh can work with bitbake running on the same machine. Copy site.conf from the generated directory to your build/conf or append it to your existing site.conf. bitbake will then commit the built rootfs to the generated OSTree repository and provision devices to automatically connect to serve_repo.py.

serve_repo.py

serve_repo.py serves Uptane metadata and OSTree objects to the devices.

Usage

serve_repo.py <port number> <repo path>

uptane-generator

uptane-generator can generate and control Uptane metadata. It is used by create_repo.sh and many aktualizr tests, but can also be used manually. See uptane-generator --help for basic usage details or the examples below for greater detail.

Basic usage example

  1. Generate a new Uptane repository:

    uptane-generator --path <repo path> --command generate
  2. Add a target to the images metadata:

    uptane-generator --path <repo path> --command image --filename <image name> --targetname <target name> --hwid <hardware ID>

    This step can be repeated as many times as necessary for each target. --targetname is optional. If it is not provided, it is assumed to be the same as the image name provided to --filename.

  3. Prepare director targets metadata for a given device:

    uptane-generator --path <repo path> --command addtarget --targetname <image name> --hwid <hardware ID> --serial <ECU serial>

    This step can be repeated as many times as necessary for each target and ECU.

  4. Sign the director targets metadata and schedule the prepared update:

    uptane-generator --path <repo path> --command signtargets

Advanced usage examples

Delegations

uptane-generator supports first-order delegations. All delegations are therefore marked as terminating. To add a delegated role, use this:

uptane-generator --path <repo path> --command adddelegation --dname <delegated role name> --dpattern <delegated path pattern>

To add a target to a delegated role, add the --dname parameter to the image command. The targetname must match the pattern supplied in --dpattern to the adddelegation command.

uptane-generator --path <repo path> --command image --filename <image name> --targetname <target name> --hwid <hardware ID> --dname <delegated role name>

Generating metadata without a real file

To add a target to the images metadata without providing an actual file, you can supply alternative parameters to the image command:

uptane-generator --path <repo path> --command image --targetname <target name> --targetsha256 <target SHA256 hash> --targetsha512 <target SHA512 hash> --targetlength <target length> --hwid <hardware ID>

Advanced director metadata control

To reset the director targets metadata or to prepare empty targets metadata, use the emptytargets command. If you then sign this metadata with signtargets, it will schedule an empty update.

uptane-generator --path <repo path> --command emptytargets

To populate the director targets metadata with the currently signed metadata (with the previous signature removed), use the oldtargets command. You can then add more targets with addtarget and re-sign with signtargets.

uptane-generator --path <repo path> --command oldtargets

Sign arbitrary metadata

To sign arbitrary metadata with one of the Uptane keys, use the sign command:

uptane-generator --path <repo path> --command sign --repotype <director|image> --keyname <role name of key> < <input data>

Add custom URLs

To add a custom URL to an image in the Targets metadata of the Images repository:

uptane-generator --path <repo path> --command image --filename <image name> --targetname <target name> --hwid <hardware ID> --url <URL>

To add a custom URL to an image in the Targets metadata of the Director:

uptane-generator --path <repo path> --command addtarget --targetname <image name> --hwid <hardware ID> --serial <ECU serial> --url <URL>

If a custom URL is set in both sets of metadata, libaktualizr will use the URL from the Director.