Root class

class Root(version=None, spec_version=None, expires=None, keys=None, roles=None, consistent_snapshot=True, unrecognized_fields=None)

A container for the signed part of root metadata.

Parameters listed below are also instance attributes.

Parameters:

  • version (int | None) – Metadata version number. Default is 1.

  • spec_version (str | None) – Supported TUF specification version. Default is the version currently supported by the library.

  • expires (datetime | None) – Metadata expiry date. Default is current date and time.

  • keys (Dict[str, Key] | None) – Dictionary of keyids to Keys. Defines the keys used in roles. Default is empty dictionary.

  • roles (Dict[str, Role] | None) – Dictionary of role names to Roles. Defines which keys are required to sign the metadata for a specific role. Default is a dictionary of top level roles without keys and threshold of 1.

  • consistent_snapshot (bool | None) – True if repository supports consistent snapshots. Default is True.

  • unrecognized_fields (Dict[str, Any] | None) – Dictionary of all attributes that are not managed by TUF Metadata API

Raises:

ValueError – Invalid arguments.

add_key(key, role)

Add new signing key for delegated role role.

Parameters:

  • key (Key) – Signing key to be added for role.

  • role (str) – Name of the role, for which key is added.

Raises:

ValueError – If the argument order is wrong or if role doesn’t exist.

Return type:

None

property expires: datetime

Get the metadata expiry date.

# Use ‘datetime’ module to e.g. expire in seven days from now obj.expires = utcnow() + timedelta(days=7)

get_delegated_role(delegated_role)

Return the role object for the given delegated role.

Raises ValueError if delegated_role is not actually delegated.

Parameters:

delegated_role (str) –

Return type:

Role

get_key(keyid)

Return the key object for the given keyid.

Raises ValueError if key is not found.

Parameters:

keyid (str) –

Return type:

Key

get_verification_result(delegated_role, payload, signatures)

Return signature threshold verification result for delegated role.

NOTE: Unlike verify_delegate() this method does not raise, if the role metadata is not fully verified.

Parameters:

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

  • payload (bytes) – Signed payload bytes for the delegated role

  • signatures (Dict[str, Signature]) – Signatures over payload bytes

Raises:

ValueError – no delegation was found for delegated_role.

Return type:

VerificationResult

is_expired(reference_time=None)

Check metadata expiration against a reference time.

Parameters:

reference_time (datetime | None) – Time to check expiration date against. A naive datetime in UTC expected. Default is current UTC date and time.

Returns:

True if expiration time is less than the reference time.

Return type:

bool

revoke_key(keyid, role)

Revoke key from role and updates the key store.

Parameters:

  • keyid (str) – Identifier of the key to be removed for role.

  • role (str) – Name of the role, for which a signing key is removed.

Raises:

ValueError – If role doesn’t exist or if role doesn’t include the key.

Return type:

None

verify_delegate(delegated_role, payload, signatures)

Verify signature threshold for delegated role.

Verify that there are enough valid signatures over payload, to meet the threshold of keys for delegated_role, as defined by the delegator (self).

Parameters:

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

  • payload (bytes) – Signed payload bytes for the delegated role

  • signatures (Dict[str, Signature]) – Signatures over payload bytes

Raises:

  • UnsignedMetadataError – delegated_role was not signed with required threshold of keys for role_name.

  • ValueError – no delegation was found for delegated_role.

Return type:

None