Supporting classes
The Metadata API includes multiple classes that are used by the top-level ones (Root, Timestamp, Snapshot, Targets):
A container with information about a delegated role. |
|
A container object storing information about all delegations. |
|
Abstract class representing the public portion of a key. |
|
A container with information about a particular metadata file. |
|
Container that defines which keys are required to sign roles metadata. |
|
A container with information about a particular target file. |
|
Succinctly defines a hash bin delegation graph. |
- class DelegatedRole(name, keyids, threshold, terminating, paths=None, path_hash_prefixes=None, unrecognized_fields=None)
A container with information about a delegated role.
A delegation can happen in two ways:
paths
is set: delegates targets matching any path pattern inpaths
path_hash_prefixes
is set: delegates targets whose target path hash starts with any of the prefixes inpath_hash_prefixes
paths
andpath_hash_prefixes
are mutually exclusive: both cannot be set, at least one of them must be set.All parameters named below are not just constructor arguments but also instance attributes.
- Parameters:
name (str) – Delegated role name.
keyids (List[str]) – Delegated role signing key identifiers.
threshold (int) – Number of keys required to sign this role’s metadata.
terminating (bool) –
True
if this delegation terminates a target lookup.paths (List[str] | None) – Path patterns. See note above.
path_hash_prefixes (List[str] | None) – Hash prefixes. See note above.
unrecognized_fields (Dict[str, Any] | None) – Dictionary of all attributes that are not managed by TUF Metadata API.
- Raises:
ValueError – Invalid arguments.
- is_delegated_path(target_filepath)
Determine whether the given
target_filepath
is in one of the paths thatDelegatedRole
is trusted to provide.The
target_filepath
and theDelegatedRole
paths are expected to be in their canonical forms, so e.g. “a/b” instead of “a//b” . Only “/” is supported as target path separator. Leading separators are not handled as special cases (see TUF specification on targetpath).- Parameters:
target_filepath (str) – URL path to a target file, relative to a base targets URL.
- Return type:
bool
- class Delegations(keys, roles=None, succinct_roles=None, unrecognized_fields=None)
A container object storing information about all delegations.
All parameters named below are not just constructor arguments but also instance attributes.
- Parameters:
keys (Dict[str, Key]) – Dictionary of keyids to Keys. Defines the keys used in
roles
.roles (Dict[str, DelegatedRole] | None) – Ordered dictionary of role names to DelegatedRoles instances. It defines which keys are required to sign the metadata for a specific role. The roles order also defines the order that role delegations are considered during target searches.
succinct_roles (SuccinctRoles | None) – Contains succinct information about hash bin delegations. Note that succinct roles is not a TUF specification feature yet and setting succinct_roles to a value makes the resulting metadata non-compliant. The metadata will not be accepted as valid by specification compliant clients such as those built with python-tuf <= 1.1.0. For more information see: https://github.com/theupdateframework/taps/blob/master/tap15.md
unrecognized_fields (Dict[str, Any] | None) – Dictionary of all attributes that are not managed by TUF Metadata API
Exactly one of
roles
andsuccinct_roles
must be set.- Raises:
ValueError – Invalid arguments.
- Parameters:
keys (Dict[str, Key]) –
roles (Dict[str, DelegatedRole] | None) –
succinct_roles (SuccinctRoles | None) –
unrecognized_fields (Dict[str, Any] | None) –
- get_roles_for_target(target_filepath)
Given
target_filepath
get names and terminating status of all delegated roles who are responsible for it.- Parameters:
target_filepath (str) – URL path to a target file, relative to a base targets URL.
- Return type:
Iterator[Tuple[str, bool]]
- class Key(keyid, keytype, scheme, keyval, unrecognized_fields=None)
Abstract class representing the public portion of a key.
All parameters named below are not just constructor arguments but also instance attributes.
- Parameters:
keyid (str) – Key identifier that is unique within the metadata it is used in. Keyid is not verified to be the hash of a specific representation of the key.
keytype (str) – Key type, e.g. “rsa”, “ed25519” or “ecdsa-sha2-nistp256”.
scheme (str) – Signature scheme. For example: “rsassa-pss-sha256”, “ed25519”, and “ecdsa-sha2-nistp256”.
keyval (Dict[str, Any]) – Opaque key content
unrecognized_fields (Dict[str, Any] | None) – Dictionary of all attributes that are not managed by Securesystemslib
- Raises:
TypeError – Invalid type for an argument.
- abstract verify_signature(signature, data)
Raises if verification of signature over data fails.
- Parameters:
signature (Signature) – Signature object.
data (bytes) – Payload bytes.
- Raises:
UnverifiedSignatureError – Failed to verify signature.
VerificationError – Signature verification process error. If you are only interested in the verify result, just handle UnverifiedSignatureError: it contains VerificationError as well
- Return type:
None
- class MetaFile(version=1, length=None, hashes=None, unrecognized_fields=None)
A container with information about a particular metadata file.
All parameters named below are not just constructor arguments but also instance attributes.
- Parameters:
version (int) – Version of the metadata file.
length (int | None) – Length of the metadata file in bytes.
hashes (Dict[str, str] | None) – Dictionary of hash algorithm names to hashes of the metadata file content.
unrecognized_fields (Dict[str, Any] | None) – Dictionary of all attributes that are not managed by TUF Metadata API
- Raises:
ValueError, TypeError – Invalid arguments.
- verify_length_and_hashes(data)
Verify that the length and hashes of
data
match expected values.- Parameters:
data (bytes | IO[bytes]) – File object or its content in bytes.
- Raises:
LengthOrHashMismatchError – Calculated length or hashes do not match expected values or hash algorithm is not supported.
- Return type:
None
- class Role(keyids, threshold, unrecognized_fields=None)
Container that defines which keys are required to sign roles metadata.
Role defines how many keys are required to successfully sign the roles metadata, and which keys are accepted.
All parameters named below are not just constructor arguments but also instance attributes.
- Parameters:
keyids (List[str]) – Roles signing key identifiers.
threshold (int) – Number of keys required to sign this role’s metadata.
unrecognized_fields (Dict[str, Any] | None) – Dictionary of all attributes that are not managed by TUF Metadata API
- Raises:
ValueError – Invalid arguments.
- class TargetFile(length, hashes, path, unrecognized_fields=None)
A container with information about a particular target file.
All parameters named below are not just constructor arguments but also instance attributes.
- Parameters:
length (int) – Length of the target file in bytes.
hashes (Dict[str, str]) – Dictionary of hash algorithm names to hashes of the target file content.
path (str) – URL path to a target file, relative to a base targets URL.
unrecognized_fields (Dict[str, Any] | None) – Dictionary of all attributes that are not managed by TUF Metadata API
- Raises:
ValueError, TypeError – Invalid arguments.
- property custom: Any
Get implementation specific data related to the target.
python-tuf does not use or validate this data.
- classmethod from_data(target_file_path, data, hash_algorithms=None)
Create
TargetFile
object from bytes.- Parameters:
target_file_path (str) – URL path to a target file, relative to a base targets URL.
data (bytes | IO[bytes]) – Target file content.
hash_algorithms (List[str] | None) – Hash algorithms to create the hashes with. If not specified the securesystemslib default hash algorithm is used.
- Raises:
ValueError – The hash algorithms list contains an unsupported algorithm.
- Return type:
- classmethod from_file(target_file_path, local_path, hash_algorithms=None)
Create
TargetFile
object from a file.- Parameters:
target_file_path (str) – URL path to a target file, relative to a base targets URL.
local_path (str) – Local path to target file content.
hash_algorithms (List[str] | None) – Hash algorithms to calculate hashes with. If not specified the securesystemslib default hash algorithm is used.
- Raises:
FileNotFoundError – The file doesn’t exist.
ValueError – The hash algorithms list contains an unsupported algorithm.
- Return type:
- get_prefixed_paths()
Return hash-prefixed URL path fragments for the target file path.
- Return type:
List[str]
- verify_length_and_hashes(data)
Verify that length and hashes of
data
match expected values.- Parameters:
data (bytes | IO[bytes]) – Target file object or its content in bytes.
- Raises:
LengthOrHashMismatchError – Calculated length or hashes do not match expected values or hash algorithm is not supported.
- Return type:
None
- class SuccinctRoles(keyids, threshold, bit_length, name_prefix, unrecognized_fields=None)
Succinctly defines a hash bin delegation graph.
A
SuccinctRoles
object describes a delegation graph that covers all targets, distributing them uniformly over the delegated roles (i.e. bins) in the graph.The total number of bins is 2 to the power of the passed
bit_length
.Bin names are the concatenation of the passed
name_prefix
and a zero-padded hex representation of the bin index separated by a hyphen.The passed
keyids
andthreshold
is used for each bin, and each bin is ‘terminating’.For details: https://github.com/theupdateframework/taps/blob/master/tap15.md
- Parameters:
keyids (List[str]) – Signing key identifiers for any bin metadata.
threshold (int) – Number of keys required to sign any bin metadata.
bit_length (int) – Number of bits between 1 and 32.
name_prefix (str) – Prefix of all bin names.
unrecognized_fields (Dict[str, Any] | None) – Dictionary of all attributes that are not managed by TUF Metadata API.
- Raises:
ValueError, TypeError, AttributeError – Invalid arguments.
- get_role_for_target(target_filepath)
Calculate the name of the delegated role responsible for
target_filepath
.The target at path
target_filepath
is assigned to a bin by casting the left-mostbit_length
of bits of the file path hash digest to int, using it as bin index between 0 and2**bit_length - 1
.- Parameters:
target_filepath (str) – URL path to a target file, relative to a base targets URL.
- Return type:
str
- get_roles()
Yield the names of all different delegated roles one by one.
- Return type:
Iterator[str]
- is_delegated_role(role_name)
Determine whether the given
role_name
is in one of the delegated roles thatSuccinctRoles
represents.- Parameters:
role_name (str) – The name of the role to check against.
- Return type:
bool