Metadata class
- class Metadata(signed, signatures=None, unrecognized_fields=None)
A container for signed TUF metadata.
Provides methods to convert to and from dictionary, read and write to and from file and to create and verify metadata signatures.
Metadata[T]
is a generic container type where T can be any one type of [Root
,Timestamp
,Snapshot
,Targets
]. The purpose of this is to allow static type checking of the signed attribute in code using Metadata:root_md = Metadata[Root].from_file("root.json") # root_md type is now Metadata[Root]. This means signed and its # attributes like consistent_snapshot are now statically typed and the # types can be verified by static type checkers and shown by IDEs print(root_md.signed.consistent_snapshot)
Using a type constraint is not required but not doing so means T is not a specific type so static typing cannot happen. Note that the type constraint
[Root]
is not validated at runtime (as pure annotations are not available then).New Metadata instances can be created from scratch with:
one_day = datetime.utcnow() + timedelta(days=1) timestamp = Metadata(Timestamp(expires=one_day))
Apart from
expires
all of the arguments to the inner constructors have reasonable default values for new metadata.All parameters named below are not just constructor arguments but also instance attributes.
- Parameters
signed – Actual metadata payload, i.e. one of
Targets
,Snapshot
,Timestamp
orRoot
.signatures – Ordered dictionary of keyids to
Signature
objects, each signing the canonical serialized representation ofsigned
. Default is an empty dictionary.unrecognized_fields – Dictionary of all attributes that are not managed by TUF Metadata API. These fields are NOT signed and it’s preferable if unrecognized fields are added to the Signed derivative classes.
- classmethod from_bytes(data, deserializer=None)
Loads TUF metadata from raw data.
- Parameters
data (bytes) – Metadata content.
deserializer (Optional[MetadataDeserializer]) –
MetadataDeserializer
implementation to use. Default isJSONDeserializer
.
- Raises
DeserializationError – The file cannot be deserialized.
- Returns
TUF
Metadata
object.- Return type
Metadata[T]
- classmethod from_file(filename, deserializer=None, storage_backend=None)
Loads TUF metadata from file storage.
- Parameters
filename (str) – Path to read the file from.
deserializer (Optional[MetadataDeserializer]) –
MetadataDeserializer
subclass instance that implements the desired wireline format deserialization. Per default aJSONDeserializer
is used.storage_backend (Optional[securesystemslib.storage.StorageBackendInterface]) – Object that implements
securesystemslib.storage.StorageBackendInterface
. Default isFilesystemBackend
(i.e. a local file).
- Raises
exceptions.StorageError – The file cannot be read.
DeserializationError – The file cannot be deserialized.
- Returns
TUF
Metadata
object.- Return type
Metadata[T]
- sign(signer, append=False, signed_serializer=None)
Creates signature over
signed
and assigns it tosignatures
.- Parameters
signer (securesystemslib.signer.Signer) – A
securesystemslib.signer.Signer
object that provides a private key and signing implementation to generate the signature. A standard implementation is available insecuresystemslib.signer.SSlibSigner
.append (bool) –
True
if the signature should be appended to the list of signatures or replace any existing signatures. The default behavior is to replace signatures.signed_serializer (Optional[SignedSerializer]) –
SignedSerializer
that implements the desired serialization format. Default isCanonicalJSONSerializer
.
- Raises
SerializationError –
signed
cannot be serialized.exceptions.UnsignedMetadataError – Signing errors.
- Returns
securesystemslib.signer.Signature
object that was added into signatures.- Return type
securesystemslib.signer.Signature
- to_bytes(serializer=None)
Return the serialized TUF file format as bytes.
Note that if bytes are first deserialized into
Metadata
and then serialized withto_bytes()
, the two are not required to be identical even though the signatures are guaranteed to stay valid. If byte-for-byte equivalence is required (which is the case when content hashes are used in other metadata), the original content should be used instead of re-serializing.- Parameters
serializer (Optional[MetadataSerializer]) –
MetadataSerializer
instance that implements the desired serialization format. Default isJSONSerializer
.- Raises
SerializationError – The metadata object cannot be serialized.
- Return type
bytes
- to_file(filename, serializer=None, storage_backend=None)
Writes TUF metadata to file storage.
Note that if a file is first deserialized into
Metadata
and then serialized withto_file()
, the two files are not required to be identical even though the signatures are guaranteed to stay valid. If byte-for-byte equivalence is required (which is the case when file hashes are used in other metadata), the original file should be used instead of re-serializing.- Parameters
filename (str) – Path to write the file to.
serializer (Optional[MetadataSerializer]) –
MetadataSerializer
instance that implements the desired serialization format. Default isJSONSerializer
.storage_backend (Optional[securesystemslib.storage.StorageBackendInterface]) –
StorageBackendInterface
implementation. Default isFilesystemBackend
(i.e. a local file).
- Raises
SerializationError – The metadata object cannot be serialized.
exceptions.StorageError – The file cannot be written.
- Return type
None
- verify_delegate(delegated_role, delegated_metadata, signed_serializer=None)
Verifies that
delegated_metadata
is signed with the required threshold of keys for the delegated roledelegated_role
.- Parameters
delegated_role (str) – Name of the delegated role to verify
delegated_metadata (Metadata) –
Metadata
object for the delegated rolesigned_serializer (Optional[SignedSerializer]) – Serializer used for delegate serialization. Default is
CanonicalJSONSerializer
.
- Raises
UnsignedMetadataError –
delegated_role
was not signed with required threshold of keys forrole_name
.ValueError – no delegation was found for
delegated_role
.TypeError – called this function on non-delegating metadata class.
- Return type
None