OTA Connect Developer Guide

Garage-sign commands and options

You can use the garage-sign tool if you need to sign metadata about your software, as well as manage your software signing keys and root of trust. When you start using OTA Connect, we generate a root of trust and a signing key for you, and automatically sign software you upload. Later on, you can use garage-sign to rotate those keys, taking them completely offline to increase security.

In the reference below, find a list of commands and options that you can use.

Garage-sign reference

Global options

--help

Prints all available garage-sign commands and options.

--version

Prints the current binary version.

--verbose

Prints the verbose information for the execution.

-h, --home-dir

The directory that you want to work with. By default, it is your current working directory.

user-keys [gen|id]: Manages keys stored outside of a specific repository’s directory.

user-keys gen: Creates a key pair and stores it in a configurable location.

-t, --type

The type of key that you want to create: Ed25519 or RSA.

--keysize

The length of the key that you want to create, in bits. RSA 2048/4096 and Ed25519 are supported.

-k, --key-name

The base filename for your keys. Generated files will be named `<key-name>.sec` and `<key-name>.pub`.

user-keys id: Calculates the Uptane key ID for a given public key.

-i, --input

The path to the file with your public key.

-p, --keys-path

The path where this executable will look for keys. By default, it is the `user-keys` directory in the directory that you specified with the `--home-dir` command.

delegations [init|sign|push|pull|add-target] Beta: Manages delegation metadata.

delegations init: Creates an empty .json file with delegation metadata that you can edit and sign.

delegations sign: Signs delegation metadata.

-k, --key-name

The base name of the key to use for signing.

-p, --keys-path

The path where this executable will look for keys. By default, it is the `user-keys` directory in the directory that you specified with the `--home-dir` command.

-i, --input

The path to the delegated targets metadata file that you want to sign.

-e, --inplace

Modifies the input .json file directly. If this option is not specified, it outputs the signed metadata to stdout.

delegations push: Pushes delegation metadata to the server. Requires an initialized tuf repository.

-r, --repo

The name of your local repository. This repository should be a directory in your tuf repository. You can create the repository with the init command.

-n, --name

The name of the delegation.

-i, --input

The path to the signed .json file with delegations.

delegations pull: Pulls a delegated targets metadata file from the server. Requires an initialized tuf repository.

-r, --repo

The name of your local repository. This repository should be a directory in your tuf repository. You can create the repository with the init command.

-n, --name

The name of the delegation.

-o, --output

The name of the file to which you want to save the delegation.

delegations add-target: Adds a new target to a delegated targets metadata file.

--length

The length of the target, in bytes.

--name

The name of the target.

--version

The version string of the target.

--format

The format of the target: [`ostree`\|`binary`]

--sha256

The hash of the binary. For OSTree images, it is the root hash of the target commit.

--hardwareids

The types of hardware with which this image is compatible.

--url

(Optional) An external URL where the binary can be downloaded.

-i, --input

The path to the delegated targets metadata file that you want to modify.

-e, --inplace

Modifies the input .json file directly. If this option is not specified, it outputs the signed metadata to stdout.

init: Creates an empty local repository.

-r, --repo

The name of the local repository that you want to create. This repository should be a directory in your tuf repository.

--reposerver

The repo server URL. By default, reads the URL from the .zip file with your provisioning credentials.

-c, --credentials

The path to the .zip file with your provisioning credentials.

-t, --servertype

The repo server type: reposerver (default) or director.

key [generate]: Manages keys stored in a specific local repository’s directory.
key generate: Generates a new key and saves it in a specific repository.

-r, --repo

The name of the local repository where you want to save your new key. This repository should be a directory in your tuf repository. You can create the repository with the init command.

-n, --name

The base filename for your keys. Generated files will be named `<key-name>.sec` and `<key-name>.pub`.

-t, --type

The type of key that you want to create: Ed25519 or RSA.

--keysize

The length of the key that you want to create, in bits. RSA 2048/4096 and Ed25519 are supported.

move-offline: Removes online keys from OTA Connect, and updates the environment to use locally stored offline keys.

-r, --repo

The name of the local repository where you want to rotate keys. This repository should be a directory in your tuf repository. You can create the repository with the init command.

--new-root

The new root key that you want to add to the root.json file (should already exist).

--new-targets

(Only for the repo server) The new targets key that you want to add to the root.json file (should already exist).

--old-root-alias

The alias of the old root key. The old root key will be saved under this name.

--old-keyid

(Optional) The ID of the key that you want to remove from the root.json file. This app will try to use the last key defined in the current root.json file.

root [pull|push|key|sign]: Manages root-of-trust metadata for a repository.

root pull: Pulls the current root.json file from OTA Connect.

root push: Uploads local root.json file to OTA Connect. If the file does not have a valid signature, it will be rejected by the server.

root key [add|remove]: Manages keys that are permitted to sign the root-of-trust metadata.

root key add: Adds a specific key to the list of keys authorized to sign the root-of-trust metadata.

-k, --key-name

The path to the public key that you want to add.

root key remove: Removes a specific key from the list of keys authorized to sign the root-of-trust metadata.

-k, --key-name

The name of the file with the keys that you want to remove. You can use the --key-id command instead.

--key-id

The ID of the public key that you want to remove. You can use the --key-name command instead.

root sign: Signs your root-of-trust metadata with a specific key and sets the expiry.

-k, --key-name

The path to the public key to use for signing.

--expires

The metadata expiry date. It is a UTC instant, such as `2020-01-01T00:01:00Z`.

--expire-after

The expiration delay in years, months, and days (each optional, but in that order), such as `1Y3M5D`.

--force

Skips sanity checking. For example, allows to set a date in the past.

-r, --repo

The name of the local repository where you want to manage the root.json file. This repository should be a directory in your tuf repository. You can create the repository with the init command.

targets [init|add|add-uploaded|delete|sign|pull|push|upload|delegations]: (Only for repositories of type reposerver) Manages targets metadata. Target is a term from Uptane. Each target corresponds to a software version available in your OTA Connect software repository.

targets init: Creates a new top-level (non-delegated) targets.json file.

--version

The version of the targets.json file. Versions are integers, normally starting at 1. They must always increase in each successive targets.json version.

--expires

The metadata expiry date. It is a UTC instant, such as `2020-01-01T00:01:00Z`.

targets add: Adds a target.

--length

The length of the target, in bytes.

--name

The name of the target.

--version

The version string of the target.

--format

The format of the target: [`ostree`\|`binary`]

--sha256

The hash of the binary. For OSTree images, it is the root hash of the target commit.

--hardwareids

The types of hardware with which this image is compatible.

--url

(Optional) An external URL where the binary can be downloaded.

targets delete: Deletes a single target. This target can no longer be installed on devices.

--filename

The exact name of the target to remove. Should be in one of the following forms: <name>_<version> for OSTree images, or <name>-<version> for binary images.

targets sign: Signs your targets.json file with a specific key.

--key-name

The path to the public key to use for signing.

--version

The version number to use for the signed metadata. Overrides the version in the unsigned targets.json.

--expires

The metadata expiry date. It is a UTC instant, such as `2020-01-01T00:01:00Z`.

--expire-after

The expiration delay in years, months, and days (each optional, but in that order), such as `1Y3M5D`.

--force

Skips sanity checking. For example, allows to set a date in the past.

targets pull: Pulls the current targets.json file from OTA Connect.

targets push: Pushes the latest targets.json file to the server. If the targets file is invalid, for example because of a bad signature or a non-increasing version number, this push will fail with exit code 2.

targets upload: Uploads a binary to the repository. Note that this will not make the binary available on its own. After the upload completes successfully, add it to your targets.json file using the targets add-uploaded command.

-i, --input

The path to the file that you want to upload.

--name

The name of the target.

--version

The version string of the target.

--timeout

The timeout for the HTTP request of the upload, in seconds.

targets add-uploaded: Adds a target that you previously uploaded to OTA Connect using the targets upload command.

-i, --input

The path to the binary file.

--name

The name of the target.

--version

The version string of the target.

--hardwareids

The types of hardware with which this image is compatible.

targets delegations: Manages the delegated targets of the repository targets.json file.

targets delegations add: Adds a new delegation to the existing targets.json file.

-n, --name

The name of the target.

-p, --prefix

The path prefix of the image that you want to delegate.

-k, --key

The path to the public key that you want to add as a delegation key.

-r, --repo

The name of your local repository. This repository should be a directory in your tuf repository. You can create the repository with the init command.

export-credentials: Exports settings and keys to the .zip file with your provisioning credentials.

-r, --repo

The name of your local repository. This repository should be a directory in your tuf repository. You can create the repository with the init command.

-k, --key-name

The name of the file with your private and public keys that you want to export.

-o, --output

The name of the file to which you want to export our credentials.