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

Metadata

class in_toto.models.metadata.Metadata

A Metadata abstraction between DSSE Envelope and Metablock.

create_signature(signer: Signer) → Signature

Creates and adds signature over signable representation of self.

The passed signer is used for signing. Applications can implement their own signer or use one from securesystemslib.

Parameters:: signer – A Signer implementation.
Returns:: The Signature object returned from Signer.

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.

classmethod from_dict(data): Loads DSSE or Traditional Metadata from its JSON/dict representation.

get_payload(): Returns Link or Layout.

classmethod load(path)

Loads the JSON string representation of metadata from disk.

Parameters:

path – The path to read the file from.

Raises:

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

Returns:

A Metadata containing a Link or Layout object.

to_dict(): Returns the JSON-serializable dictionary representation of self.

verify_signature(verification_key)

Verifies a signature over signable in signatures with verification_key.

Parameters:

verification_key – A verification key.

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.

DSSE Envelope

class in_toto.models.metadata.Envelope(payload: bytes, payload_type: str, signatures: List[Signature])

DSSE Envelope for in-toto payloads.

create_signature(signer: Signer) → Signature

Creates and adds signature over signable representation of self.

The passed signer is used for signing. Applications can implement their own signer or use one from securesystemslib.

Parameters:: signer – A Signer implementation.
Returns:: The Signature object returned from Signer.

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.

classmethod from_dict(data: dict) → Envelope

Creates a DSSE Envelope from its JSON/dict representation.

Parameters:

data – A dict containing a valid payload, payloadType and signatures

Raises:

KeyError – If any of the “payload”, “payloadType” and “signatures” fields are missing from the “data”.
FormatError – If signature in “signatures” is incorrect.

Returns:

A “Envelope” instance.

classmethod from_signable(signable: Signable) → Envelope: Creates DSSE envelope with signable bytes as payload.

get_payload() → Link | Layout

Parse DSSE payload into Link or Layout object.

Raises:: InvalidMetadata – If type in payload is not link or layout.
Returns:: Link or Layout.

classmethod load(path)

Loads the JSON string representation of metadata from disk.

Parameters:

path – The path to read the file from.

Raises:

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

Returns:

A Metadata containing a Link or Layout object.

pae() → bytes: Pre-Auth-Encoding byte sequence of self.

sign(signer: Signer) → Signature

Sign the payload and create the signature.

Parameters:: signer – A “Signer” class instance.
Returns:: A “Signature” instance.

to_dict() → dict: Returns the JSON-serializable dictionary representation of self.

verify(keys: List[Key], threshold: int) → Dict[str, Key]

Verify the payload with the provided Keys.

NOTE: This API is experimental and might change (see secure-systems-lab/dsse#55)

Parameters:

keys – A list of public keys to verify the signatures.
threshold – Number of signatures needed to pass the verification.

Raises:

ValueError – If “threshold” is not valid.
VerificationError – If the enclosed signatures do not pass the verification.

Note

Mandating keyid in signatures and matching them with keyid of Key in order to consider them for verification, is not DSSE spec compliant (Issue #416).

Returns:: A dict of the threshold of unique public keys that verified a signature.

verify_signature(verification_key)

Verifies a signature over signable in signatures with verification_key.

Parameters:

verification_key – A verification key.

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.

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.

create_signature(signer: Signer)

Creates and adds signature over signable representation of self.

The passed signer is used for signing. Applications can implement their own signer or use one from securesystemslib.

Parameters:: signer – A Signer implementation.
Returns:: The Signature object returned from Signer.

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.

classmethod from_dict(data): Creates a Metablock object from its JSON/dict representation.

get_payload(): Returns signed of the Metablock.

classmethod load(path)

Loads the JSON string representation of metadata from disk.

Parameters:

path – The path to read the file from.

Raises:

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

Returns:

A Metadata containing a Link or 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.

Raises:

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

Returns:

The signature.

Deprecated since version 2.2.0: Please use Metablock.create_signature() instead.

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.

to_dict(): Returns the JSON-serializable dictionary representation of self.

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 is a gpg key, subkey keyids are considered too.

Parameters:

verification_key – A verification key.

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.
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 public key in PEM/subjectPublicKeyInfo format. Supported key types are rsa, ecdsa (nistp256) and ed25519.
Raises:: securesystemslib.exceptions.FormatError – Argument is malformed.
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 public keys in PEM/subjectPublicKeyInfo format. Supported key types are rsa, ecdsa (nistp256), ed25519.
Raises:: securesystemslib.exceptions.FormatError – Argument is malformed.
Returns:: The added functionary public key.

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.