Metadata Model

The in-toto metadata model classes are used internally and may be required as arguments to or returned by in-toto API functions (see in_toto.runlib.in_toto_run() and in_toto.verifylib.in_toto_verify()).

They provide containers and convenience methods to generate, sign, serialize and read or write in-toto conformant metadata (see Layout Creation Example).

Metablock

class in_toto.models.metadata.Metablock(**kwargs)

A container for signed in-toto metadata.

Provides methods for metadata JSON (de-)serialization, reading from and writing to disk, creating and verifying signatures, and self-validation.

signed: A subclass of Signable which has the actual metadata payload, usually a Link or Layout object.

signatures: A list of signatures over the canonical JSON representation of the value of the signed attribute.

compact_json: A boolean indicating if the dump method should write a compact JSON string representation of the metadata.

dump(path)

Writes the JSON string representation of the instance to disk.

Parameters: path – The path to write the file to.
Raises: IOError – File cannot be written.

static load(path)

Loads the JSON string representation of in-toto metadata from disk.

Parameters

path – The path to read the file from.

Raises

IOError – The file cannot be read.
securesystemslib.exceptions.FormatError – Metadata format is invalid.

Returns

A Metablock object whose signable attribute is either a Link or a Layout object.

sign(key)

Creates signature over signable with key and adds it to signatures.

Uses the UTF-8 encoded canonical JSON byte representation of the signable attribute to create signatures deterministically.

key: A signing key. The format is securesystemslib.formats.KEY_SCHEMA.

Raises

securesystemslib.exceptions.FormatError – Key argument is malformed.
securesystemslib.exceptions.CryptoError, securesystemslib.exceptions.UnsupportedAlgorithmError – Signing errors.

Returns

The signature. Format is securesystemslib.formats.SIGNATURE_SCHEMA.

sign_gpg(gpg_keyid=None, gpg_home=None)

Creates signature over signable with gpg and adds it to signatures.

Uses the UTF-8 encoded canonical JSON byte representation of the signable attribute to create signatures deterministically.

Parameters

gpg_keyid (optional) – A keyid used to identify a local gpg signing key. If omitted the default signing key is used.
gpg_home (optional) – A path to the gpg home directory. If not set the default gpg home directory is used.

Raises

ValueError, OSError, securesystemslib.gpg.exceptions.CommandError, securesystemslib.gpg.exceptions.KeyNotFoundError – gpg signing errors.

Side Effects

Calls system gpg command in a subprocess.

Returns

The signature. Format is securesystemslib.formats.GPG_SIGNATURE_SCHEMA.

property type_: A shortcut to the type_ attribute of the object on the signable attribute (should be one of “link” or “layout”).

validate()

Validates attributes of the instance.

Raises: securesystemslib.formats.FormatError – An attribute value is invalid.

verify_signature(verification_key)

Verifies a signature over signable in signatures with verification_key.

Uses the UTF-8 encoded canonical JSON byte representation of the signable attribute to verify the signature deterministically.

NOTE: Only the first signature in the signatures attribute, whose keyid matches the verification_key keyid, is verified. If the verification_key format is securesystemslib.formats.GPG_PUBKEY_SCHEMA, subkey keyids are considered too.

Parameters

verification_key – A verification key. The format is securesystemslib.formats.ANY_VERIFICATION_KEY_SCHEMA.

Raises

securesystemslib.exceptions.FormatError – The passed key is malformed.
SignatureVerificationError – No signature keyid matches the verification key keyid, or the matching signature is malformed, or the matching signature is invalid.
securesystemslib.gpg.exceptions.KeyExpirationError – Passed verification key is an expired gpg key.

Link

class in_toto.models.link.Link(**kwargs)

Evidence for a performed step or inspection of the supply chain.

A Link object is usually contained in a generic Metablock object for signing, serialization and I/O capabilities.

name: A unique name used to identify the related step or inspection in an in-toto layout.

command: A list of command and command arguments that report how the corresponding step is performed.

materials

A dictionary of the artifacts used by the step, i.e:

{
  "<material path>": {
    "<hash algorithm name>": "<hash digest of material>",
    ...
  },
  ...
}

products

A dictionary of the artifacts produced by the step, i.e:

{
  "<product path>": {
    "<hash algorithm name>": "<hash digest of product>",
    ...
  },
  ...
}

byproducts: An opaque dictionary that lists byproducts of the link command execution. It should have at least the following entries “stdout” (str), “stderr” (str) and “return-value” (int).

environment

An opaque dictionary that lists information about the execution environment of the link command. eg.:

{
  "variables": "<list of env var KEY=value pairs>",
  "filesystem": "<filesystem info>",
  "workdir": "<CWD when executing link command>"
}

static read(data)

Creates a Link object from its dictionary representation.

Parameters: data – A dictionary with link metadata fields.
Raises: securesystemslib.exceptions.FormatError – Passed data is invalid.
Returns: The created Link object.

property signable_bytes: The UTF-8 encoded canonical JSON byte representation of the dictionary representation of the instance.

property type_: The string “link” to indentify the in-toto metadata type.

validate()

Validates attributes of the instance.

Raises: securesystemslib.formats.FormatError – An attribute value is invalid.

Layout

class in_toto.models.layout.Layout(**kwargs)

A definition for a software supply chain.

A layout lists the sequence of steps of the software supply chain in the order they are expected to be performed, the functionaries authorized and required to perform them, and inspections to be performed by the client upon final product verification.

A Layout object is usually contained in a generic Metablock object for signing, serialization and I/O capabilities.

steps: A list of Step objects.

inspect: A list of Inspection objects.

keys: A dictionary of functionary public keys, with keyids as dict keys and keys as values.

expires: The layout expiration.

readme: A human readable description of the software supply chain.

add_functionary_key(key)

Adds key as functionary key to layout.

Parameters: key – A public key. Format is securesystemslib.formats.ANY_PUBKEY_SCHEMA.
Raises: securesystemslib.exceptions.FormatError – Argument is malformed.
Returns: The added key.

add_functionary_key_from_gpg_keyid(gpg_keyid, gpg_home=None)

Loads key from gpg keychain and adds as functionary key to layout.

Parameters

gpg_keyid – A keyid used to identify a local gpg public key.
gpg_home (optional) – A path to the gpg home directory. If not set the default gpg home directory is used.

Raises

securesystemslib.exceptions.FormatError – Arguments are malformed.
securesystemslib.gpg.execeptions.KeyNotFoundError – Key cannot be found.

Side Effects

Calls system gpg command in a subprocess.

Returns

The added key.

add_functionary_key_from_path(key_path)

Loads key from disk and adds as functionary key to layout.

Parameters

key_path – A path to a PEM-formatted RSA public key. Format is securesystemslib.formats.PATH_SCHEMA.

Raises

securesystemslib.exceptions.FormatError – Argument is malformed.
securesystemslib.exceptions.Error – Key cannot be imported.

Returns

The added functionary public key.

add_functionary_keys_from_gpg_keyids(gpg_keyid_list, gpg_home=None)

Loads keys from gpg keychain and adds as functionary keys to layout.

Parameters

gpg_keyid_list – A list of keyids used to identify local gpg public keys.
gpg_home (optional) – A path to the gpg home directory. If not set the default gpg home directory is used.

Raises

securesystemslib.exceptions.FormatError – Arguments are malformed.
securesystemslib.gpg.execeptions.KeyNotFoundError – A key cannot be found.

Side Effects

Calls system gpg command in a subprocess.

Returns

A dictionary of the added functionary keys, with keyids as dictionary keys and keys as values.

add_functionary_keys_from_paths(key_path_list)

Loads keys from disk and adds as functionary keys to layout.

Parameters

key_path_list – A list of paths to PEM-formatted RSA public keys. Format of each path is securesystemslib.formats.PATH_SCHEMA.

Raises

securesystemslib.exceptions.FormatError – Argument is malformed.
securesystemslib.exceptions.Error – A key cannot be imported.

Returns

A dictionary of the added functionary keys, with keyids as dictionary keys and keys as values.

get_functionary_key_id_list()

Returns list of functionary keyids from the layout.

Returns: A list of keyids.

get_inspection_by_name(inspection_name)

Returns inspection identified by inspection_names from the layout.

NOTE: Returns the first inspection identified only, which should be the only inspection for a given name of a valid layout.

Parameters: inspection_name – An inspection name.
Raises: securesystemslib.exceptions.FormatError – Argument is not a string.
Returns: An Inspection object.

get_inspection_name_list()

Returns ordered list of inspection names as they appear in the layout.

Returns: A list of inspection names.

get_step_by_name(step_name)

Returns step identified by step_name from the layout.

NOTE: Returns the first step identified only, which should be the only step for a given name of a valid layout.

Parameters: step_name – A step name.
Raises: securesystemslib.exceptions.FormatError – Argument is not a string.
Returns: A Step object.

get_step_name_list()

Returns ordered list of step names as they appear in the layout.

Returns: A list of step names.

static read(data)

Creates a Layout object from its dictionary representation.

Parameters: data – A dictionary with layout metadata fields.
Raises: securesystemslib.exceptions.FormatError – Passed data is invalid.
Returns: The created Layout object.

remove_inspection_by_name(inspection_name)

Removes inspections identified by inspection_name from the layout.

NOTE: Removes all inspections identified, which should be only one inspection for a given name of a valid layout.

Parameters: inspection_name – An inspection name.
Raises: securesystemslib.exceptions.FormatError – Argument is not a string.

remove_step_by_name(step_name)

Removes steps identified by step_name from the layout.

NOTE: Removes all steps identified, which should be only one step for a given name of a valid layout.

Parameters: step_name – A step name.
Raises: securesystemslib.exceptions.FormatError – Argument is not a string.

set_relative_expiration(days=0, months=0, years=0)

Sets layout expiration relative to today.

If not argument is passed the set exipration date is now.

Parameters

days (optional) – Days from today.
months (optional) – Months from today.
years (optional) – Years from today.

Raises

securesystemslib.exceptions.FormatError – Arguments are not ints.

property signable_bytes: The UTF-8 encoded canonical JSON byte representation of the dictionary representation of the instance.

property type_: The string “layout” to indentify the in-toto metadata type.

validate()

Validates attributes of the instance.

Raises: securesystemslib.formats.FormatError – An attribute value is invalid.

Step

class in_toto.models.layout.Step(**kwargs)

A step of a software supply chain.

A Step object is usually contained in a Layout object and encodes the expectations for a step of the software supply chain such as, who is authorized to perform the step, what command is executed, and which artifacts are used and produced. Evidence about a performed step is provided by link metadata.

pubkeys: A list of functionary keyids authorized to perform the step.

threshold: A minimum number of distinct functionaries required to provide evidence for a step.

expected_command: A list of command and command arguments, expected to perform the step.

add_material_rule_from_string(rule_string)

Parse artifact rule string as list and add to expected_materials.

Parameters: rule_string – An artifact rule string (see rulelib for formats).
Raises: securesystemslib.exceptions.FormatError – Argument is malformed.

add_product_rule_from_string(rule_string)

Parse artifact rule string as list and add to expected_products.

Parameters: rule_string – An artifact rule string (see rulelib for formats).
Raises: securesystemslib.exceptions.FormatError – Argument is malformed.

static read(data)

Creates a Step object from its dictionary representation.

Parameters: data – A dictionary with step metadata fields.
Raises: securesystemslib.exceptions.FormatError – Passed data is invalid.
Returns: The created Step object.

set_expected_command_from_string(command_string)

Parse command string as list and assign to expected_command.

Parameters: command_string – A command and command arguments string.
Raises: securesystemslib.exceptions.FormatError – Argument is malformed.

validate()

Validates attributes of the instance.

Raises: securesystemslib.formats.FormatError – An attribute value is invalid.

Inspection

class in_toto.models.layout.Inspection(**kwargs)

An inspection for a software supply chain.

An Inspection object is usually contained in a Layout object and encodes a command to be executed by an in-toto client during final product verification. Akin to steps, inspections can define artifact rules.

run: A list of command and command arguments to be executed upon final product verification.

add_material_rule_from_string(rule_string)

Parse artifact rule string as list and add to expected_materials.

Parameters: rule_string – An artifact rule string (see rulelib for formats).
Raises: securesystemslib.exceptions.FormatError – Argument is malformed.

add_product_rule_from_string(rule_string)

Parse artifact rule string as list and add to expected_products.

Parameters: rule_string – An artifact rule string (see rulelib for formats).
Raises: securesystemslib.exceptions.FormatError – Argument is malformed.

static read(data)

Creates an Inspection object from its dictionary representation.

Parameters: data – A dictionary with inspection metadata fields.
Raises: securesystemslib.exceptions.FormatError – Passed data is invalid.
Returns: The created Inspection object.

set_run_from_string(command_string)

Parse command string as list and assign to run attribute.

Parameters: command_string – A command and command arguments string.
Raises: securesystemslib.exceptions.FormatError – Argument is malformed.

validate()

Validates attributes of the instance.

Raises: securesystemslib.formats.FormatError – An attribute value is invalid.