OTA Connect Developer Guide

Manage keys for software metadata

OTA Connect has a security concept that includes signing metadata files with secure, offline keys. For more information about these files, see the Uptane metadata overview.

How metadata is signed by default

When you initially create an account on the HERE OTA Connect Portal, all of your Uptane keys and metadata files are managed by OTA Connect. The keys are generated by our crypto service when the account is created and stored in a Vault instance. When you build software images and upload them to your account on the OTA Connect Portal, we generate the metadata and sign it for you.

How metadata should be signed in production

However, if you choose, you can rotate that software signing key and take it offline, replacing it with a key held only by you. Because only you have the key in this scenario, the OTA Connect server can no longer sign software for you. Instead of being signed on the server, these metadata files will now be signed locally or on your build machine. The signing happens automatically whenever you push a new disk image to OTA Connect during the build process. (If you are using non-OSTree software images, you’ll have to use garage-sign to manage your metadata.)

Taking this step is recommended for all production deployments, because a person who gained access to your OTA Connect account would be able to send arbitrary malicious software to your vehicles; that single set of credentials would be a single point of failure. Once you have rotated your keys offline, the maximal impact of an account compromise would be to send an already-signed image—​i.e., one that used to be valid.

Before using OTA Connect in production, however, you should create offline keys that you manage yourself, then rotate out the default keys that were automatically created for your account on the OTA Connect server. If you don’t do this, you expose yourself to risks that we describe the in the key management topic.

Instead of being signed on the server, these metadata files will now be signed locally or on your build machine. The signing happens automatically whenever you push a new disk image to OTA Connect. However, you need to update your build cofiguration first. The following procedures show you how to do this.

Before you start, make sure that you’ve installed the garage-sign tool.

garage-sign is also packaged with the garage-deploy packaged releases, so if you’re on a Debian-based Linux distro, you can install it that way.

Rotate the keys for root and targets metadata

Create a local image repository

An image repository is just a directory structure containing signed metadata in JSON format. Create a new one called myimagerepo with garage-sign:

garage-sign init --repo myimagerepo --credentials /path/to/credentials.zip

This command creates a ./tuf/myimagerepo/ directory tree in the current directory. This directory should be secured on an encrypted filesystem.

Generate new keys

There are two metadata files in the repo and each file needs a new key to sign it.

garage-sign key generate --repo myimagerepo --name myroot --type rsa
garage-sign key generate --repo myimagerepo --name mytargets --type rsa
It is critical to keep these keys offline on secure hardware. Do not lose these keys.

Rotate the online keys with your new offline keys

This is a four-step process:

  1. Pull the current targets.json from OTA Connect:

    garage-sign targets pull --repo myimagerepo

  2. Perform a complete root key rotation:

    garage-sign move-offline --repo myimagerepo --old-root-alias origroot \
    --new-root myroot --new-targets mytargets

    This command

    • removes the original root key from OTA Connect,

    • generates a new root.json with the keys generated in the previous step (myroot and mytargets),

    • signs the new root.json with both the old and new root keys, and

    • uploads the newly signed root.json to OTA Connect

  3. Sign the current targets.json with the new targets key:

    garage-sign targets sign --repo myimagerepo --key-name mytargets

    This metadata eventually expires after a predefined period. If you’d like to define your own metadata expiry period, you can add the --expires or --expire-after option. For more information about these options, see our guide to managing metadata expiry dates.

  4. Upload the newly signed targets.json to OTA Connect:

    garage-sign targets push --repo myimagerepo

You have now successfully taken the keys for software metadata offline.

After rotating keys, you will no longer be able to upload packages through the OTA Connect web UI—​only the usual way, through bitbake.

Push new images with bitbake

Export the new offline targets into a new credentials file that you can use with bitbake:

garage-sign export-credentials --repo myimagerepo --key-name mytargets --output offline-credentials.zip

Update your local.conf to use the new offline-credentials.zip file and run bitbake as before.

As part of the bitbake process, the image’s metadata inside targets.json is signed with your offline TUF keys. The signed targets.json is then uploaded to your OTA Connect account.