in-toto-sign

in-toto-sign provides a command line interface to sign in-toto link or layout metadata or verify their signatures, with options to:

  • replace (default) or add signatures:
    • layout metadata can be signed by multiple keys at once,
    • link metadata can only be signed by one key at a time.
  • write signed metadata to a specified path. If no output path is specified,
    • layout metadata is written to the path of the input file,
    • link metadata is written to ‘<name>.<keyid prefix>.link’.
  • verify signatures

in-toto-sign is useful to re-sign metadata (e.g. when changing keys), or to sign unsigned links (e.g. generated with ‘in-toto-mock’). For layouts, it is useful to append signatures in case threshold signing of layouts is necessary.

It returns a non-zero value on failure and zero otherwise.

usage: in-toto-sign [-h] -f <path> [-k <path> [<path> ...]]
                    [-t {rsa,ed25519} [{rsa,ed25519} ...]] [-p]
                    [-g [<id> [<id> ...]]] [--gpg-home <path>] [-o <path>]
                    [-a] [--verify] [-v | -q] [--version]

Required Named Arguments

-f, --file path to link or layout file to be signed or verified.

Optional Arguments

-k, --key paths to key files, used to sign the passed link or layout metadata or to verify its signatures. See ‘–key-type’ for available formats.
-t, --key-type

Possible choices: rsa, ed25519

types of keys specified by the ‘–key’ option. ‘rsa’ keys are expected in a ‘PEM’ format and ‘ed25519’ in a custom ‘securesystemslib/json’ format. If multiple keys are passed via ‘–key’ the same amount of key types must be passed. Key types are then associated with keys by index. If ‘–key-type’ is omitted, the default of ‘rsa’ is used for all keys.

-p, --prompt

prompt for signing key decryption password

Default: False

-g, --gpg GPG keyids used to sign the passed link or layout metadata or to verify its signatures. If passed without keyids, the default GPG key is used.
--gpg-home path to a GPG home directory used to load a GPG key identified by ‘–gpg’. If ‘–gpg-home’ is not passed, the default GPG home directory is used.
-o, --output path to location where the metadata file is stored after signing. If not passed, layout metadata is written to the path of the input file and link metadata is written to ‘<name>.<keyid prefix>.link’
-a, --append

add signatures rather than replacing existing signatures. This option is only availabe for layout metdata.

Default: False

--verify

verify signatures of passed link or layout metadata using the public keys passed via ‘–key’ and/or ‘–gpg’ options.

Default: False

-v, --verbose

show more output

Default: False

-q, --quiet

suppress all output

Default: False

--version show program’s version number and exit

Example Usage

Sign ‘unsigned.layout’ with two keys and write it to ‘root.layout’.

in-toto-sign -f unsigned.layout -k priv_key1 priv_key2 -o root.layout

Replace signature in link file and write to default filename, i.e. ‘package.<priv_key keyid prefix>.link’.

in-toto-sign -f package.2f89b927.link -k priv_key

Verify layout signed with 3 keys.

in-toto-sign -f root.layout -k pub_key0 pub_key1 pub_key2 --verify

Sign layout with default gpg key in default gpg keyring.

in-toto-sign -f root.layout --gpg

Verify layout with a gpg key identified by keyid ‘…439F3C2’.

in-toto-sign -f root.layout --verify \
    --gpg 3BF8135765A07E21BD12BF89A5627F6BF439F3C2