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. |
|
A container 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. |
- 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 (Optional[List[str]]) – Path patterns. See note above.
path_hash_prefixes (Optional[List[str]]) – Hash prefixes. See note above.
unrecognized_fields (Optional[Dict[str, Any]]) – Dictionary of all attributes that are not managed by TUF Metadata API
- Raises
ValueError – Invalid arguments.
- is_delegated_path(target_filepath)
Determines 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, 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]) – 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.
unrecognized_fields (Optional[Dict[str, Any]]) – Dictionary of all attributes that are not managed by TUF Metadata API
- Raises
ValueError – Invalid arguments.
- class Key(keyid, keytype, scheme, keyval, unrecognized_fields=None)
A container class representing the public portion of a Key.
Supported key content (type, scheme and keyval) is defined in `` Securesystemslib``.
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, str]) – Opaque key content
unrecognized_fields (Optional[Dict[str, Any]]) – Dictionary of all attributes that are not managed by TUF Metadata API
- Raises
TypeError – Invalid type for an argument.
- classmethod from_securesystemslib_key(key_dict)
Creates a
Key
object from a securesystemlib key json/dict representation removing the private key from keyval.- Parameters
key_dict (Dict[str, Any]) – Key in securesystemlib dict representation.
- Raises
ValueError –
key_dict
value is not following the securesystemslib format.- Return type
- to_securesystemslib_key()
Returns a
Securesystemslib
compatible representation of self.- Return type
Dict[str, Any]
- verify_signature(metadata, signed_serializer=None)
Verifies that the
metadata.signatures
contains a signature made with this key, correctly signingmetadata.signed
.- Parameters
metadata (Metadata) – Metadata to verify
signed_serializer (Optional[SignedSerializer]) –
SignedSerializer
to serializemetadata.signed
with. Default isCanonicalJSONSerializer
.
- Raises
UnsignedMetadataError – The signature could not be verified for a variety of possible reasons: see error message.
- Return type
None
- class MetaFile(version, 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 (Optional[int]) – Length of the metadata file in bytes.
hashes (Optional[Dict[str, str]]) – Dictionary of hash algorithm names to hashes of the metadata file content.
unrecognized_fields (Optional[Dict[str, Any]]) – Dictionary of all attributes that are not managed by TUF Metadata API
- Raises
ValueError, TypeError – Invalid arguments.
- verify_length_and_hashes(data)
Verifies that the length and hashes of
data
match expected values.- Parameters
data (Union[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 (Optional[Dict[str, Any]]) – 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 (Optional[Dict[str, Any]]) – Dictionary of all attributes that are not managed by TUF Metadata API
- Raises
ValueError, TypeError – Invalid arguments.
- property custom: Any
Can be used to provide 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)
Creates
TargetFile
object from bytes.- Parameters
target_file_path (str) – URL path to a target file, relative to a base targets URL.
data (Union[bytes, IO[bytes]]) – Target file content.
hash_algorithms (Optional[List[str]]) – 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)
Creates
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 (Optional[List[str]]) – 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
- verify_length_and_hashes(data)
Verifies that length and hashes of
data
match expected values.- Parameters
data (Union[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