in-toto-verify

in-toto-verify is the main verification tool of the suite, and it is used to verify that the software supply chain of the delivered product was carried out as defined in the passed in-toto supply chain layout. Evidence for supply chain steps must be available in the form of link metadata files named ‘<step name>.<functionary keyid prefix>.link’.

Both ‘in-toto-run’ and ‘in-toto-record’ generate link metadata named in this manner. If you require special handling of the in-toto link metadata files, please take a look at the library api to modify this behavior.

The verification includes the following checks:
  • the layout is signed with the passed keys,

  • the layout has not expired,

  • a threshold of link metadata files exists for each step of the layout,

  • link files are signed by the authorized functionaries,

  • the materials and products for each step, as reported by the corresponding link files, adhere to the artifact rules specified by the step.

Additionally, inspection commands defined in the layout are executed sequentially, followed by processing the inspections’ artifact rules.

If the layout includes sublayouts, the verification routine will recurse into a subdirectory named ‘<step name>.<keyid prefix>’, where all the links relevant to that sublayout must exist. The sublayout itself must be in the same directory as the other links of the superlayout. (i.e. ‘<step name>.<keyid prefix>.link’)

The verification workflow is performed in isolation and does not rely on information about keys that are available through external sources. For example, in-toto does not rely on the creation time, revocation status, and usage flags for PGP keys.

The command returns 2 if it is called with wrong arguments, 1 if in-toto verification fails and 0 if verification passes.

usage: in-toto-verify <named arguments> [options]

Required Named Arguments

-l, --layout

path to root layout specifying the software supply chain to be verified.

-k, --layout-keys

paths to public key files used to verify the passed root layout’s signatures. See ‘–key-types’ for available formats. Passing at least one key using ‘–layout-keys’ and/or ‘–gpg’ is required. For each passed key the layout must carry a valid signature.

--verification-keys

replacement for ‘–layout-keys’ using a standard subjectPublicKeyInfo/PEM format. Key type is detected automatically and need not be specified with ‘–key-type’.

-g, --gpg

GPG keyid, identifying a public key in the GPG keyring used to verify the passed root layout’s signatures. Passing at least one key using ‘–layout-keys’ and/or ‘–gpg’ is required. For each passed key the layout must carry a valid signature.

Options

-t, --key-types

Possible choices: rsa, ed25519, ecdsa

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

--link-dir

path to directory from which link metadata files for steps defined in the root layout should be loaded. If not passed, links are loaded from the current working directory.

Default: “.”

--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.

-v, --verbose

show more output

Default: False

-q, --quiet

suppress all output

Default: False

--version

show program’s version number and exit

Example Usage

Verify supply chain in ‘root.layout’, signed with private part of ‘key_file.pub’.

in-toto-verify --layout root.layout --layout-keys key_file.pub

Verify supply chain as above but load links corresponding to steps of ‘root.layout’ from ‘link_dir’.

in-toto-verify --layout root.layout --layout-keys key_file.pub \
    --link-dir link_dir

Verify supply chain in ‘root.layout’, signed with GPG key ‘…7E0C8A17’, for which the public part can be found in the GPG keyring at ‘~/.gnupg’.

in-toto-verify --layout root.layout \
    --gpg 8465A1E2E0FB2B40ADB2478E18FB3F537E0C8A17 \
    --gpg-home ~/.gnupg