/opt/chainguard/in-toto/bin/in-toto-sign

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

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.

Required Named Arguments:
  -f <path>, --file <path>
                        path to link or layout file to be signed or verified.

Options:
  -h, --help            show this help message and exit
  -k <path> [<path> ...], --key <path> [<path> ...]
                        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
  -g [<id> ...], --gpg [<id> ...]
                        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>     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 <path>, --output <path>
                        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 available for layout metadata.
  --verify              verify signatures of passed link or layout metadata using the public keys
                        passed via '--key' and/or '--gpg' options.
  -v, --verbose         show more output
  -q, --quiet           suppress all output
  --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