API

The in-toto API provides various functions and classes that you can use to generate, consume, modify and verify in-toto metadata, as a more feature-rich, programmable alternative to the command line tools.

Evidence Generation

in_toto.runlib.in_toto_run(name, material_list, product_list, link_cmd_args, record_streams=False, signing_key=None, gpg_keyid=None, gpg_use_default=False, gpg_home=None, exclude_patterns=None, base_path=None, compact_json=False, record_environment=False, normalize_line_endings=False, lstrip_paths=None, metadata_directory=None, use_dsse=False, timeout=10, signer=None)

Performs a supply chain step or inspection generating link metadata.

Executes link_cmd_args, recording paths and hashes of files before and after command execution (aka. artifacts) in a link metadata file. The metadata is signed with the passed signer, signing_key, a gpg key identified by its ID, or the default gpg key. If multiple key arguments are passed, only one key is used in above order of precedence. The resulting link file is written to STEP-NAME.KEYID-PREFIX.link. If no key argument is passed the link metadata is neither signed nor written to disk.

Parameters:
  • name – A unique name to associate link metadata with a step or inspection.

  • material_list – A list of artifact paths to be recorded before command execution. Directories are traversed recursively.

  • product_list – A list of artifact paths to be recorded after command execution. Directories are traversed recursively.

  • link_cmd_args – A list where the first element is a command and the remaining elements are arguments passed to that command.

  • record_streams (optional) – A boolean indicating if standard output and standard error of the link command should be recorded in the link metadata in addition to being displayed while the command is executed.

  • signing_key (optional) –

    A key used to sign the resulting link metadata.

    Deprecated since version 2.2.0: Please pass a signer instead.

  • gpg_keyid (optional) – A keyid used to identify a local gpg key used to sign the resulting link metadata.

  • gpg_use_default (optional) – A boolean indicating if the default gpg key should be used to sign the resulting link metadata.

  • gpg_home (optional) – A path to the gpg home directory. If not set the default gpg home directory is used.

  • exclude_patterns (optional) – A list of filename patterns to exclude certain files from being recorded as artifacts. See Config docs for details.

  • base_path (optional) – A path relative to which artifacts are recorded. Default is the current working directory.

  • compact_json (optional) – A boolean indicating if the resulting link metadata should be written in the most compact JSON representation.

  • record_environment (optional) – A boolean indicating if information about the environment should be added in the resulting link metadata.

  • normalize_line_endings (optional) – A boolean indicating if line endings of artifacts should be normalized before hashing for cross-platform support.

  • lstrip_paths (optional) – A list of path prefixes used to left-strip artifact paths before storing them in the resulting link metadata.

  • metadata_directory (optional) – A directory path to write the resulting link metadata file to. Default destination is the current working directory.

  • use_dsse (optional) – A boolean indicating if DSSE should be used to generate metadata.

  • timeout (optional) – An integer indicating the max timeout in seconds for this command. Default is 10 seconds.

  • signer (optional) – A securesystemslib Signer instance used to sign the resulting link metadata.

Raises:
  • securesystemslib.exceptions.FormatError – Passed arguments are malformed.

  • OSError – Cannot change to base path directory.

  • securesystemslib.exceptions.StorageError – Cannot hash artifacts.

  • PrefixError – Left-stripping artifact paths results in non-unique dict keys.

  • subprocess.TimeoutExpired – Link command times out.

  • IOError, FileNotFoundError, NotADirectoryError, PermissionError – Cannot write link metadata.

  • securesystemslib.exceptions.CryptoError, securesystemslib.exceptions.UnsupportedAlgorithmError – Signing errors.

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

Side Effects:

Reads artifact files from disk. Runs link command in subprocess. Calls system gpg in a subprocess, if a gpg key argument is passed. Writes link metadata file to disk, if any key argument is passed.

Returns:

A Metadata object that contains the resulting link object.

in_toto.runlib.in_toto_record_start(step_name, material_list, signing_key=None, gpg_keyid=None, gpg_use_default=False, gpg_home=None, exclude_patterns=None, base_path=None, record_environment=False, normalize_line_endings=False, lstrip_paths=None, use_dsse=False, signer=None)

Generates preliminary link metadata.

Records paths and hashes of materials in a preliminary link metadata file. The metadata is signed with the passed signer, signing_key, a gpg key identified by its ID, or the default gpg key. If multiple key arguments are passed, only one key is used in above order of precedence. At least one key argument must be passed. The resulting link file is written to .STEP-NAME.KEYID-PREFIX.link-unfinished.

Use this function together with in_toto_record_stop as an alternative to in_toto_run, in order to provide evidence for supply chain steps that cannot be carried out by a single command.

Parameters:
  • step_name – A unique name to associate link metadata with a step.

  • material_list – A list of artifact paths to be recorded as materials. Directories are traversed recursively.

  • signing_key (optional) –

    A key used to sign the resulting link metadata.

    Deprecated since version 2.2.0: Please pass a signer instead.

  • gpg_keyid (optional) – A keyid used to identify a local gpg key used to sign the resulting link metadata.

  • gpg_use_default (optional) – A boolean indicating if the default gpg key should be used to sign the resulting link metadata.

  • gpg_home (optional) – A path to the gpg home directory. If not set the default gpg home directory is used.

  • exclude_patterns (optional) – A list of filename patterns to exclude certain files from being recorded as artifacts. See Config docs for details.

  • base_path (optional) – A path relative to which artifacts are recorded. Default is the current working directory.

  • record_environment (optional) – A boolean indicating if information about the environment should be added in the resulting link metadata.

  • normalize_line_endings (optional) – A boolean indicating if line endings of artifacts should be normalized before hashing for cross-platform support.

  • lstrip_paths (optional) – A list of path prefixes used to left-strip artifact paths before storing them in the resulting link metadata.

  • use_dsse (optional) – A boolean indicating if DSSE should be used to generate metadata.

  • signer (optional) – A securesystemslib Signer instance used to sign the resulting link metadata.

Raises:
  • securesystemslib.exceptions.FormatError – Passed arguments are malformed.

  • ValueError – None of signing_key, gpg_keyid or gpg_use_default=True is passed.

  • securesystemslib.exceptions.StorageError – Cannot hash artifacts.

  • PrefixError – Left-stripping artifact paths results in non-unique dict keys.

  • subprocess.TimeoutExpired – Link command times out.

  • IOError, PermissionError – Cannot write link metadata.

  • securesystemslib.exceptions.CryptoError, securesystemslib.exceptions.UnsupportedAlgorithmError – Signing errors.

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

Side Effects:

Reads artifact files from disk. Calls system gpg in a subprocess, if a gpg key argument is passed. Writes preliminary link metadata file to disk.

in_toto.runlib.in_toto_record_stop(step_name, product_list, signing_key=None, gpg_keyid=None, gpg_use_default=False, gpg_home=None, exclude_patterns=None, base_path=None, normalize_line_endings=False, lstrip_paths=None, metadata_directory=None, command=None, byproducts=None, environment=None, signer=None)

Finalizes preliminary link metadata generated with in_toto_record_start.

Loads preliminary link metadata file, verifies its signature, and records paths and hashes as products, thus finalizing the link metadata. The metadata is signed with the passed signer, signing_key, a gpg key identified by its ID, or the default gpg key. If multiple key arguments are passed, only one key is used in above order of precedence. At least one key argument must be passed and it must be the same as the one used to sign the preliminary link metadata file. The resulting link file is written to STEP-NAME.KEYID-PREFIX.link.

Use this function together with in_toto_record_start as an alternative to in_toto_run, in order to provide evidence for supply chain steps that cannot be carried out by a single command.

Parameters:
  • step_name – A unique name to associate link metadata with a step.

  • product_list – A list of artifact paths to be recorded as products. Directories are traversed recursively.

  • signing_key (optional) –

    A key used to sign the resulting link metadata.

    Deprecated since version 2.2.0: Please pass a signer instead.

  • gpg_keyid (optional) – A keyid used to identify a local gpg key used to sign the resulting link metadata.

  • gpg_use_default (optional) – A boolean indicating if the default gpg key should be used to sign the resulting link metadata.

  • gpg_home (optional) – A path to the gpg home directory. If not set the default gpg home directory is used.

  • exclude_patterns (optional) – A list of filename patterns to exclude certain files from being recorded as artifacts.

  • base_path (optional) – A path relative to which artifacts are recorded. Default is the current working directory.

  • normalize_line_endings (optional) – A boolean indicating if line endings of artifacts should be normalized before hashing for cross-platform support.

  • lstrip_paths (optional) – A list of path prefixes used to left-strip artifact paths before storing them in the resulting link metadata.

  • metadata_directory (optional) – A directory path to write the resulting link metadata file to. Default destination is the current working directory.

  • command (optional) – A list consisting of a command and arguments executed between in_toto_record_start() and in_toto_record_stop() to capture the command ran in the resulting link metadata.

  • byproducts (optional) – A 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 (optional) –

    A dictionary to capture information about the environment to be added in the resulting link metadata eg.:

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

  • signer (optional) – A securesystemslib Signer instance used to sign the resulting link metadata.

Raises:
  • securesystemslib.exceptions.FormatError – Passed arguments are malformed.

  • ValueError – None of signing_key, gpg_keyid or gpg_use_default=True is passed.

  • LinkNotFoundError – No preliminary link metadata file found.

  • securesystemslib.exceptions.StorageError – Cannot hash artifacts.

  • PrefixError – Left-stripping artifact paths results in non-unique dict keys.

  • subprocess.TimeoutExpired – Link command times out.

  • IOError, FileNotFoundError, NotADirectoryError, PermissionError – Cannot write link metadata.

  • securesystemslib.exceptions.CryptoError, securesystemslib.exceptions.UnsupportedAlgorithmError – Signing errors.

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

Side Effects:

Reads preliminary link metadata file from disk. Reads artifact files from disk. Calls system gpg in a subprocess, if a gpg key argument is passed. Writes resulting link metadata file to disk. Removes preliminary link metadata file from disk.

in_toto.runlib.in_toto_match_products(link, paths=None, exclude_patterns=None, lstrip_paths=None)

Check if local artifacts match products in passed link.

NOTE: Does not check integrity or authenticity of passed link!

Parameters:

link – The Link object to match.

See in_toto_run for details about arguments, and exceptions that may occur while recording artifact hashes.

Returns:

A 3-tuple with artifact names that are - only in products, - not in products, - have different hashes.

Supply Chain Verification

in_toto.verifylib.in_toto_verify(metadata, layout_key_dict, link_dir_path='.', substitution_parameters=None, step_name='', persist_inspection_links=True, inspect_timeout=10)

Performs complete in-toto supply chain verification for a final product.

The verification procedure consists of the following activities, performed in the given order:

  1. Verify layout signatures

  2. Verify layout expiration date

  3. Substitute placeholders in the layout

  4. Load link metadata

  5. Verify link signatures with keys in layout

  6. Recurse into sublayout verification

  7. Soft-verify alignment of reported and expected commands. Note: verification does not fail if commands don’t match, instead a warning is logged as per the in-toto specification – https://github.com/in-toto/docs/blob/master/in-toto-spec.md#431-steps

  8. Verify threshold artifact constraints

  9. Process step product and material rules

  10. Execute inspection commands and generate inspection links

  11. Process inspection product and material rules

Note: in-toto’s verification workflow directly uses the key for verifying signatures. It does not communicate with external sources of information for specific attributes about keys. This ensures that verification can be performed in isolation. It is the supply chain owner’s responsibility to consider such attributes before using the key to sign the layout or adding it to the layout. For example, in-toto does not rely on the creation time, revocation status, and usage flags for PGP keys. To revoke or otherwise affect the usage of a key, the supply chain owner must sign a new layout with the corresponding changes.

Parameters:
  • metadata – A Metadata object that contains a Layout object to be verified.

  • layout_key_dict – A public key dictionary. The verification routine requires at least one key, and a valid signature on the layout for each key.

  • link_dir_path (optional) – A directory path to link metadata files. The expected filename format for link metadata files is STEP-NAME.KEYID-PREFIX.link. Link metadata files for a sublayout are loaded from a subdirectory relative to the link_dir_path of the superlayout. The expected directory name format is SUBLAYOUT-STEP-NAME.KEYID-PREFIX.

  • substitution_parameters (optional) – A dictionary with substitution values for artifact rules (steps and inspections), the expected command attribute (steps), and the run attribute (inspections) in the layout.

  • step_name (optional) – A name assigned to the returned link. This is mostly useful during recursive sublayout verification.

  • persist_inspection_links (optional) – A boolean that determines whether or not link metadata files for inspection are written to cwd.

  • inspect_timeout (optional) – An integer value that defaults to in_toto.settings.LINK_CMD_EXEC_TIMEOUT in seconds which ends up timing out the run command subprocess if it runs over.

Raises:
  • securesystemslib.exceptions.FormatError – Passed parameters are malformed.

  • SignatureVerificationError – No layout verification key is passed, or any of the passed keys fails to verify a signature.

  • LayoutExpiredError – The layout is expired.

  • LinkNotFoundError – Fewer than threshold link metadata files can be found for a step of the layout.

  • ThresholdVerificationError – Fewer than threshold links, validly signed by different authorized functionaries, who agree on the recorded materials and products, can be found for a step of the layout. (Links with invalid signatures or signatures by unauthorized functionaries are ignored.)

  • RuleVerificationError – A DISALLOW rule matches disallowed artifacts, or a REQUIRE rule does not find a required artifact.

  • BadReturnValueError – An inspection command returns a non-zero value.

Side Effects:

Reads link metadata files from disk. Runs inspection commands in subprocess.

Returns:

A Link object, which summarizes the materials and products of the overall software supply chain. This is mostly useful during recursive sublayout verification.

Key Utilities

in-toto uses the in-house crypto library securesystemslib to generate and verify cryptographic signatures. Useful securesystemslib API functions, e.g. to generate asymmetric key pairs and import them into a format that aligns with the in-toto metadata specification, are documented below.

Generate Key Pairs

securesystemslib.interface.generate_and_write_rsa_keypair(password, filepath=None, bits=3072)

Generates RSA key pair and writes PEM-encoded keys to disk.

The private key is encrypted using the best available encryption algorithm chosen by ‘pyca/cryptography’, which may change over time. The private key is written in PKCS#1 and the public key in X.509 SubjectPublicKeyInfo format.

NOTE: A signing scheme can be assigned on key import (see import functions).

Parameters:
  • password – An encryption password.

  • filepath (optional) – The path to write the private key to. If not passed, the key is written to CWD using the keyid as filename. The public key is written to the same path as the private key using the suffix ‘.pub’.

  • bits (optional) – The number of bits of the generated RSA key.

Raises:
  • UnsupportedLibraryError – pyca/cryptography is not available.

  • FormatError – Arguments are malformed.

  • ValueError – An empty string is passed as ‘password’.

  • StorageError – Key files cannot be written.

Side Effects:

Writes key files to disk. Overwrites files if they already exist.

Returns:

The private key filepath.

securesystemslib.interface.generate_and_write_rsa_keypair_with_prompt(filepath=None, bits=3072)

Generates RSA key pair and writes PEM-encoded keys to disk.

The private key is encrypted with a password entered on the prompt, using the best available encryption algorithm chosen by ‘pyca/cryptography’, which may change over time. The private key is written in PKCS#1 and the public key in X.509 SubjectPublicKeyInfo format.

NOTE: A signing scheme can be assigned on key import (see import functions).

Parameters:
  • filepath (optional) – The path to write the private key to. If not passed, the key is written to CWD using the keyid as filename. The public key is written to the same path as the private key using the suffix ‘.pub’.

  • bits (optional) – The number of bits of the generated RSA key.

Raises:
  • UnsupportedLibraryError – pyca/cryptography is not available.

  • FormatError – Arguments are malformed.

  • StorageError – Key files cannot be written.

Side Effects:

Prompts user for a password. Writes key files to disk. Overwrites files if they already exist.

Returns:

The private key filepath.

securesystemslib.interface.generate_and_write_unencrypted_rsa_keypair(filepath=None, bits=3072)

Generates RSA key pair and writes PEM-encoded keys to disk.

The private key is written in PKCS#1 and the public key in X.509 SubjectPublicKeyInfo format.

NOTE: A signing scheme can be assigned on key import (see import functions).

Parameters:
  • filepath (optional) – The path to write the private key to. If not passed, the key is written to CWD using the keyid as filename. The public key is written to the same path as the private key using the suffix ‘.pub’.

  • bits (optional) – The number of bits of the generated RSA key.

Raises:
  • UnsupportedLibraryError – pyca/cryptography is not available.

  • FormatError – Arguments are malformed.

  • StorageError – Key files cannot be written.

Side Effects:

Writes unencrypted key files to disk. Overwrites files if they already exist.

Returns:

The private key filepath.

securesystemslib.interface.generate_and_write_ed25519_keypair(password, filepath=None)

Generates ed25519 key pair and writes custom JSON-formatted keys to disk.

The private key is encrypted using AES-256 in CTR mode, with the passed password strengthened in PBKDF2-HMAC-SHA256.

NOTE: The custom key format includes ‘ed25519’ as signing scheme.

Parameters:
  • password – An encryption password.

  • filepath (optional) – The path to write the private key to. If not passed, the key is written to CWD using the keyid as filename. The public key is written to the same path as the private key using the suffix ‘.pub’.

Raises:
  • UnsupportedLibraryError – pyca/pynacl or pyca/cryptography is not available.

  • FormatError – Arguments are malformed.

  • ValueError – An empty string is passed as ‘password’.

  • StorageError – Key files cannot be written.

Side Effects:

Writes key files to disk. Overwrites files if they already exist.

Returns:

The private key filepath.

securesystemslib.interface.generate_and_write_ed25519_keypair_with_prompt(filepath=None)

Generates ed25519 key pair and writes custom JSON-formatted keys to disk.

The private key is encrypted using AES-256 in CTR mode, with the password entered on the prompt strengthened in PBKDF2-HMAC-SHA256.

NOTE: The custom key format includes ‘ed25519’ as signing scheme.

Parameters:

filepath (optional) – The path to write the private key to. If not passed, the key is written to CWD using the keyid as filename. The public key is written to the same path as the private key using the suffix ‘.pub’.

Raises:
  • UnsupportedLibraryError – pyca/pynacl or pyca/cryptography is not available.

  • FormatError – Arguments are malformed.

  • StorageError – Key files cannot be written.

Side Effects:

Prompts user for a password. Writes key files to disk. Overwrites files if they already exist.

Returns:

The private key filepath.

securesystemslib.interface.generate_and_write_unencrypted_ed25519_keypair(filepath=None)

Generates ed25519 key pair and writes custom JSON-formatted keys to disk.

NOTE: The custom key format includes ‘ed25519’ as signing scheme.

Parameters:

filepath (optional) – The path to write the private key to. If not passed, the key is written to CWD using the keyid as filename. The public key is written to the same path as the private key using the suffix ‘.pub’.

Raises:
  • UnsupportedLibraryError – pyca/pynacl or pyca/cryptography is not available.

  • FormatError – Arguments are malformed.

  • StorageError – Key files cannot be written.

Side Effects:

Writes unencrypted key files to disk. Overwrites files if they already exist.

Returns:

The private key filepath.

Note

securesystemslib does not provide functions to generate OpenPGP key pairs. You can use GnuPG for that.

Load Signing Keys

securesystemslib.interface.import_privatekey_from_file(filepath, key_type=None, password=None, prompt=False)

Imports private key from file.

If a password is passed or entered on the prompt, the private key is decrypted, otherwise it is treated as unencrypted.

NOTE: The default signing scheme ‘rsassa-pss-sha256’ is assigned to RSA keys. Use ‘import_rsa_privatekey_from_file’ to specify any other than the default signing scheme for an RSA key. ed25519 and ecdsa keys have the signing scheme included in the custom key format (see generate functions).

Parameters:
  • filepath – The path to read the file from.

  • key_type (optional) – One of KEY_TYPE_RSA, KEY_TYPE_ED25519 or KEY_TYPE_ECDSA. Default is KEY_TYPE_RSA.

  • password (optional) – A password to decrypt the key.

  • prompt (optional) – A boolean indicating if the user should be prompted for a decryption password. If the user enters an empty password, the key is not decrypted.

Raises:
  • FormatError – Arguments are malformed or ‘key_type’ is not supported.

  • ValueError – Both a ‘password’ is passed and ‘prompt’ is true.

  • UnsupportedLibraryError – pyca/cryptography is not available.

  • StorageError – Key file cannot be read.

  • Error, CryptoError – Key cannot be parsed.

Returns:

A private key object conformant with one of ‘ED25519KEY_SCHEMA’, ‘RSAKEY_SCHEMA’ or ‘ECDSAKEY_SCHEMA’.

securesystemslib.interface.import_rsa_privatekey_from_file(filepath, password=None, scheme='rsassa-pss-sha256', prompt=False, storage_backend=None)

Imports PEM-encoded RSA private key from file storage.

The expected key format is PKCS#1. If a password is passed or entered on the prompt, the private key is decrypted, otherwise it is treated as unencrypted.

Parameters:
  • filepath – The path to read the file from.

  • password (optional) – A password to decrypt the key.

  • scheme (optional) – The signing scheme assigned to the returned key object. See RSA_SCHEME_SCHEMA for available signing schemes.

  • prompt (optional) – A boolean indicating if the user should be prompted for a decryption password. If the user enters an empty password, the key is not decrypted.

  • storage_backend (optional) – An object implementing StorageBackendInterface. If not passed a default FilesystemBackend will be used.

Raises:
  • UnsupportedLibraryError – pyca/cryptography is not available.

  • FormatError – Arguments are malformed.

  • ValueError – Both a ‘password’ is passed and ‘prompt’ is true.

  • StorageError – Key file cannot be read.

  • CryptoError – Key cannot be parsed.

Returns:

An RSA private key object conformant with ‘RSAKEY_SCHEMA’.

securesystemslib.interface.import_ed25519_privatekey_from_file(filepath, password=None, prompt=False, storage_backend=None)

Imports custom JSON-formatted ed25519 private key from file storage.

If a password is passed or entered on the prompt, the private key is decrypted, otherwise it is treated as unencrypted.

NOTE: The signing scheme is set at key generation (see generate function).

Parameters:
  • filepath – The path to read the file from.

  • password (optional) – A password to decrypt the key.

  • prompt (optional) – A boolean indicating if the user should be prompted for a decryption password. If the user enters an empty password, the key is not decrypted.

  • storage_backend (optional) – An object implementing StorageBackendInterface. If not passed a default FilesystemBackend will be used.

Raises:
  • UnsupportedLibraryError – pyca/cryptography is not available.

  • FormatError – Arguments are malformed.

  • ValueError – Both a ‘password’ is passed and ‘prompt’ is true.

  • StorageError – Key file cannot be read.

  • Error, CryptoError – Key cannot be parsed.

Returns:

An ed25519 private key object conformant with ‘ED25519KEY_SCHEMA’.

Note

OpenPGP private keys do not need to be imported for signing. They remain in the GnuPG keyring and can be addressed by keyid (see the in_toto.models.metadata.Metablock.sign_gpg() method).

Load Verification Keys

securesystemslib.interface.import_publickeys_from_file(filepaths, key_types=None)

Imports multiple public keys from files.

NOTE: The default signing scheme ‘rsassa-pss-sha256’ is assigned to RSA keys. Use ‘import_rsa_publickey_from_file’ to specify any other than the default signing scheme for an RSA key. ed25519 and ecdsa keys have the signing scheme included in the custom key format (see generate functions).

Parameters:
  • filepaths – A list of paths to public key files.

  • key_types (optional) – A list of types of keys to be imported associated with filepaths by index. Must be one of KEY_TYPE_RSA, KEY_TYPE_ED25519 or KEY_TYPE_ECDSA. If not specified, all keys are assumed to be KEY_TYPE_RSA.

Raises:
  • TypeError – filepaths or ‘key_types’ (if passed) is not iterable.

  • FormatError – Argument are malformed, or ‘key_types’ is passed and does not have the same length as ‘filepaths’ or contains an unsupported type.

  • UnsupportedLibraryError – pyca/cryptography is not available.

  • StorageError – Key file cannot be read.

  • Error – Public key is malformed.

Returns:

A dict of public keys in KEYDICT_SCHEMA format.

securesystemslib.interface.import_ed25519_publickey_from_file(filepath)

Imports custom JSON-formatted ed25519 public key from disk.

NOTE: The signing scheme is set at key generation (see generate function).

Parameters:

filepath – The path to read the file from.

Raises:
  • FormatError – Argument is malformed.

  • StorageError – Key file cannot be read.

  • Error – Public key is malformed.

Returns:

An ed25519 public key object conformant with ‘ED25519KEY_SCHEMA’.

securesystemslib.interface.import_rsa_publickey_from_file(filepath, scheme='rsassa-pss-sha256', storage_backend=None)

Imports PEM-encoded RSA public key from file storage.

The expected key format is X.509 SubjectPublicKeyInfo.

Parameters:
  • filepath – The path to read the file from.

  • scheme (optional) – The signing scheme assigned to the returned key object. See RSA_SCHEME_SCHEMA for available signing schemes.

  • storage_backend (optional) – An object implementing StorageBackendInterface. If not passed a default FilesystemBackend will be used.

Raises:
  • UnsupportedLibraryError – pyca/cryptography is not available.

  • FormatError – Arguments are malformed.

  • StorageError – Key file cannot be read.

  • Error – Public key is malformed.

Returns:

An RSA public key object conformant with ‘RSAKEY_SCHEMA’.

securesystemslib.gpg.functions.export_pubkey(keyid, homedir=None, timeout=10)

Exports a public key from a GnuPG keyring.

Parameters:
  • keyid – An OpenPGP keyid in KEYID_SCHEMA format.

  • homedir (optional) – A path to the GnuPG home directory. If not set the default GnuPG home directory is used.

  • timeout (optional) – gpg command timeout in seconds. Default is 10.

Raises:
  • ValueError – Keyid is not a string.

  • UnsupportedLibraryError – The gpg command or pyca/cryptography are not available.

  • KeyNotFoundError – No key or subkey was found for that keyid.

Side Effects:

Calls system gpg command in a subprocess.

Returns:

An OpenPGP public key object in GPG_PUBKEY_SCHEMA format.

securesystemslib.gpg.functions.export_pubkeys(keyids, homedir=None, timeout=10)

Exports multiple public keys from a GnuPG keyring.

Parameters:
  • keyids – A list of OpenPGP keyids in KEYID_SCHEMA format.

  • homedir (optional) – A path to the GnuPG home directory. If not set the default GnuPG home directory is used.

  • timeout (optional) – gpg command timeout in seconds. Default is 10.

Raises:
  • TypeError – Keyids is not iterable.

  • ValueError – A Keyid is not a string.

  • UnsupportedLibraryError – The gpg command or pyca/cryptography are not available.

  • KeyNotFoundError – No key or subkey was found for that keyid.

Side Effects:

Calls system gpg command in a subprocess.

Returns:

A dict of OpenPGP public key objects in GPG_PUBKEY_SCHEMA format as values, and their keyids as dict keys.

See also

The in_toto.models.layout.Layout() class also provides shortcuts to load public functionary keys and directly assign them to an in-toto layout (see add_functionary_key* methods).