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> ...]] [-p]
                    [-g [<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.

Options

-k, --key

paths to key files, used to sign the passed link or layout metadata or to verify its signatures. Verification keys are expected in PEM/subjectPublicKeyInfo and signing keys in PEM/PKCS8 format. Pass ‘–prompt’ to enter a signing key decryption password.

-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