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] 
: 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
|
|
--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|get-unsigned|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 get-unsigned: Generates an unsigned root.json file in a canonical JSON form.
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|get-unsigned|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
|
|
--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 get-unsigned: Generates the unsigned targets.json file in a canonical JSON form.
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
|
|
--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
|
|
--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
|
|
-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.
|
To learn how to use the garage-sign tool, see the following documentation: