Metadata class

class Metadata(signed, signatures)

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

All parameters named below are not just constructor arguments but also instance attributes.

Parameters

  • signed – The actual metadata payload, i.e. one of Targets, Snapshot, Timestamp or Root.

  • signatures – An ordered dictionary of keyids to Signature objects, each signing the canonical serialized representation of ‘signed’.

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 is JSONDeserializer.

Raises

DeserializationError – The file cannot be deserialized.

Returns

A TUF Metadata object.

Return type

Metadata[tuf.api.metadata.T]

classmethod from_file(filename, deserializer=None, storage_backend=None)

Loads TUF metadata from file storage.

Parameters

  • filename (str) – The path to read the file from.

  • deserializer (Optional[MetadataDeserializer]) – A MetadataDeserializer subclass instance that implements the desired wireline format deserialization. Per default a JSONDeserializer is used.

  • storage_backend (Optional[securesystemslib.storage.StorageBackendInterface]) – An object that implements securesystemslib.storage.StorageBackendInterface. Per default a (local) FilesystemBackend is used.

Raises

  • securesystemslib.exceptions.StorageError – The file cannot be read.

  • DeserializationError – The file cannot be deserialized.

Returns

A TUF Metadata object.

Return type

Metadata[tuf.api.metadata.T]

sign(signer, append=False, signed_serializer=None)

Creates signature over ‘signed’ and assigns it to ‘signatures’.

Parameters

  • signer (securesystemslib.signer.Signer) – A securesystemslib.signer.Signer implementation.

  • append (bool) – A boolean indicating 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]) – A SignedSerializer that implements the desired serialization format. Default is CanonicalJSONSerializer.

Raises

  • SerializationError – ‘signed’ cannot be serialized.

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

Returns

Securesystemslib Signature object that was added into signatures.

Return type

securesystemslib.signer.Signature

to_bytes(serializer=None)

Return the serialized TUF file format as bytes.

Parameters

serializer (Optional[MetadataSerializer]) – A MetadataSerializer instance that implements the desired serialization format. Default is JSONSerializer.

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.

Parameters

  • filename (str) – The path to write the file to.

  • serializer (Optional[MetadataSerializer]) – A MetadataSerializer instance that implements the desired serialization format. Default is JSONSerializer.

  • storage_backend (Optional[securesystemslib.storage.StorageBackendInterface]) – A StorageBackendInterface implementation. Default is FilesystemBackend (i.e. a local file).

Raises

  • SerializationError – The metadata object cannot be serialized.

  • securesystemslib.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 role ‘delegated_role’.

Parameters

  • delegated_role (str) – Name of the delegated role to verify

  • delegated_metadata (Metadata) – The Metadata object for the delegated role

  • signed_serializer (Optional[SignedSerializer]) – serializer used for delegate serialization. Default is CanonicalJSONSerializer.

Raises

UnsignedMetadataError – ‘delegate’ was not signed with required threshold of keys for ‘role_name’

Return type

None