ATS Garage has a security concept that includes signing system images with secure, offline keys. As part of the quickstart, your ATS Garage account creates initial keys and stores them online. Before using ATS Garage in production, however, you should create offline keys that you manage yourself, then rotate out the initial online keys.

1. Install the garage-sign tool

On a debian machine, download the garage-deploy package and install it:

wget https://github.com/advancedtelematic/aktualizr/releases/download/2018.8/garage_deploy.deb
sudo apt install ./garage_deploy.deb

This package contains both the garage-deploy and garage-sign tools, but for rotating keys we will only need garage-sign.

2. Rotate the TUF root and targets keys

2.1. Create a local TUF repository

A TUF repository is just a directory structure containing signed metadata in JSON format. Create a new one called mytufrepo with garage-sign:

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

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

2.2. Generate new TUF keys

There are two roles in the repo, each of which needs a new key.

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

2.3. Rotate the online keys with your new offline keys

This is a four-step process:

  1. Pull the current targets.json from ATS Garage:

    garage-sign targets pull --repo mytufrepo
  2. Perform a complete root key rotation:

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

    This command

    • removes the original root key from ATS Garage,

    • 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 ATS Garage

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

    garage-sign targets sign --repo mytufrepo --key-name mytargets
  4. Upload the newly signed targets.json to ATS Garage:

    garage-sign targets push --repo mytufrepo

You have now successfully taken the TUF keys offline.

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

3. 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 mytufrepo --target-key-name mytargets --to 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 ATS Garage account.