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.

--verification-keys

paths to public key files used to verify the passed root layout’s signatures. Supported keytypes are rsa, ed25519, ecdsa (nistp256) in a standard subjectPublicKeyInfo/PEM format. Passing at least one key using ‘–verification-keys’ and/or ‘–gpg’ is required. For each passed key the layout must carry a valid signature.

-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 ‘–verification-keys’ and/or ‘–gpg’ is required. For each passed key the layout must carry a valid signature.

Options

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

--inspection-timeout

integer that represents the max timeout in seconds for the in-toto-verify command for inspect subprocess. Default is ‘10’ seconds.

Default: 10

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