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 (T) – Actual metadata payload, i.e. one of Targets, Snapshot, Timestamp or Root.

  • signatures (Dict[str, Signature] | None) – Ordered dictionary of keyids to Signature objects, each signing the canonical serialized representation of signed. Default is an empty dictionary.

  • unrecognized_fields (Dict[str, Any] | None) – 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)

Load TUF metadata from raw data.

Parameters:
  • data (bytes) – Metadata content.

  • deserializer (MetadataDeserializer | None) – MetadataDeserializer implementation to use. Default is JSONDeserializer.

Raises:

DeserializationError – The file cannot be deserialized.

Returns:

TUF Metadata object.

Return type:

Metadata[T]

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

Load TUF metadata from file storage.

Parameters:
  • filename (str) – Path to read the file from.

  • deserializer (MetadataDeserializer | None) – MetadataDeserializer subclass instance that implements the desired wireline format deserialization. Per default a JSONDeserializer is used.

  • storage_backend (StorageBackendInterface | None) – Object that implements securesystemslib.storage.StorageBackendInterface. Default is FilesystemBackend (i.e. a local file).

Raises:
  • 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)

Create signature over signed and assigns it to signatures.

Parameters:
  • signer (Signer) – A securesystemslib.signer.Signer object that provides a private key and signing implementation to generate the signature. A standard implementation is available in securesystemslib.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 (SignedSerializer | None) – SignedSerializer that implements the desired serialization format. Default is CanonicalJSONSerializer.

Raises:
  • SerializationErrorsigned cannot be serialized.

  • UnsignedMetadataError – Signing errors.

Returns:

securesystemslib.signer.Signature object that was added into signatures.

Return type:

Signature

property signed_bytes: bytes

Default canonical json byte representation of self.signed.

to_bytes(serializer=None)

Return the serialized TUF file format as bytes.

Note that if bytes are first deserialized into Metadata and then serialized with to_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 (MetadataSerializer | None) – 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)

Write TUF metadata to file storage.

Note that if a file is first deserialized into Metadata and then serialized with to_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 (MetadataSerializer | None) – MetadataSerializer instance that implements the desired serialization format. Default is JSONSerializer.

  • storage_backend (StorageBackendInterface | None) – StorageBackendInterface implementation. Default is FilesystemBackend (i.e. a local file).

Raises:
  • SerializationError – The metadata object cannot be serialized.

  • StorageError – The file cannot be written.

Return type:

None

verify_delegate(delegated_role, delegated_metadata, signed_serializer=None)

Verify that delegated_metadata is signed with the required threshold of keys for delegated_role.

Deprecated since version 3.1.0: Please use Root.verify_delegate() or Targets.verify_delegate().

Parameters:
Return type:

None