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.

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.