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|importpub]
: Manages keys stored outside of a specific repository 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.
|
user-keys importpub
: Imports a public key and stores it in a configurable location.
-r, --repo
|
The name of the 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 path to the public key that you want to add.
|
-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
|
(Optional) 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|increment-version|key|targets-key|sign|set-threshold]
: Manages the root-of-trust metadata of 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 increment-version
: Explicitly increments the version of the unsigned root.json
file.
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 targets-key [add|remove]
: Manages keys that are permitted to sign the targets metadata.
root targets-key add
: Adds a specific key to the list of keys authorized to sign the targets metadata.
-k, --key-name
|
The path to the public key that you want to add.
|
root targets-key remove
: Removes a specific key from the list of keys authorized to sign the targets 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.
|
--old-root-alias
|
The path to the old public key to use for signing with external signatures.
|
--signatures
|
Key-value pairs in the keyname=signature form for signing with externally generated signatures. keyname is the name of the key that you used to generate a signature.
|
--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.
|
root set-threshold
: Sets the threshold for the Root role.
-t, --threshold
|
The threshold for the Root role.
|
-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|increment-version|get-unsigned|upload|delegations|set-threshold]
: (Only for repositories of the reposerver
type) Manages the 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.
|
--signatures
|
Key-value pairs in the keyname=signature form for signing with externally generated signatures. keyname is the name of the key that you used to generate a signature.
|
--version
|
The version number to use for the signed metadata. Overrides the version in the unsigned targets.json file.
|
--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 increment-version
: Explicitly increments the version of the unsigned targets.json
file.
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.
|
--force
|
Force upload of a binary file. Skips checking whether the file has already been added to the targets.
|
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.
|
--verifyIntegrity
|
Verifies the integrity of the previously uploaded target before adding it to the metadata.
|
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.
|
targets set-threshold
: Sets the threshold for the Targets role.
-t, --threshold
|
The threshold for the Targets role.
|
-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: