dtuf module

dtuf.DTufBase(host[, auth, insecure, auth_host])

Class for communicating with a Docker v2 registry.

dtuf.DTufMaster(host, repo[, repos_root, …])

Class for creating, updating and publishing data to repositories in a Docker registry using The Update Framework (TUF).

dtuf.DTufCopy(host, repo[, repos_root, …])

Class for downloading data from repositories in a Docker registry using The Update Framework (TUF).

Docker registry bindings for The Update Framework

class dtuf.DTufBase(host, auth=None, insecure=False, auth_host=None)

Bases: object

Class for communicating with a Docker v2 registry. Contains only operations which aren’t related to pushing and pulling data to repositories in the registry using The Update Framework.

Can act as a context manager. For each context entered, a new requests.Session is obtained. Connections to the same host are shared by the session. When the context exits, all the session’s connections are closed.

If you don’t use DTufBase as a context manager, each request uses an ephemeral session. If you don’t read all the data from an iterator returned by DTufCopy.pull_target() then the underlying connection won’t be closed until Python garbage collects the iterator.

Parameters
  • host (str) – Host name of registry. Can contain port numbers. e.g. registry-1.docker.io, localhost:5000.

  • auth (function(dtuf_obj, response)) – Authentication function to be called whenever authentication to the registry is required. Receives the DTufBase object and a HTTP response object. It should call authenticate() on dtuf_obj with a username, password and response before it returns.

  • insecure (bool) – Use HTTP instead of HTTPS (which is the default) when connecting to the registry.

  • auth_host (str) – Host to use for token authentication. If set, overrides host returned by then registry.

authenticate(username=None, password=None, actions=None, response=None)

Authenticate to the registry, using a username and password if supplied, otherwise as the anonymous user.

Parameters
  • username (str) – User name to authenticate as.

  • password (str) – User’s password.

  • actions (list) – If you know which types of operation you need to make on the registry, specify them here. Valid actions are pull, push and *.

  • response (requests.Response) – When the auth function you passed to DTufBase’s constructor is called, it is passed a HTTP response object. Pass it back to authenticate() to have it automatically detect which actions are required.

Return type

str

Returns

Authentication token, if the registry supports bearer tokens. Otherwise None, and HTTP Basic auth is used.

list_repos()

List all repositories in the registry.

Return type

list

Returns

List of repository names.

property token

str: Authentication token. This will be obtained automatically when you call authenticate(). If you’ve obtained a token previously, you can also set it but be aware tokens expire quickly.

class dtuf.DTufCopy(host, repo, repos_root=None, auth=None, insecure=False, auth_host=None)

Bases: dtuf._DTufCommon

Class for downloading data from repositories in a Docker registry using The Update Framework (TUF).

Parameters
  • host (str) – Host name of registry. Can contain port numbers. e.g. registry-1.docker.io, localhost:5000.

  • repo (str) – Name of the repository to access on the registry. Typically this is of the form username/reponame but for your own registries you don’t actually have to stick to that. The repository is used to retrieve data and TUF metadata describing the data.

  • repos_root (str) – Directory under which to store TUF metadata. Note that the value of repo and the literal string copy are appended to this directory name before storing the metadata. Defaults to dtuf_repos in the current working directory.

  • auth (function(dtuf_obj, response)) – Authentication function to be called whenever authentication to the registry is required. Receives the DTufBase object and a HTTP response object. It should call DTufBase.authenticate() with a username, password and response before it returns.

  • insecure (bool) – Use HTTP instead of HTTPS (which is the default) when connecting to the registry.

  • auth_host (str) – Host to use for token authentication. If set, overrides host returned by then registry.

blob_sizes(target)

Return the sizes of all the blobs which make up a target.

Parameters

target (str) – Name of target

Returns

List of blob sizes

Return type

list

check_target(target, *filenames)

Check whether the hashes of a target’s blobs match the hashes of a given list of filenames.

Raises dxf.exceptions.DXFDigestMismatchError if they don’t.

Parameters
  • target (str) – Name of target to check.

  • filenames (list) – Names of files to check against.

get_expirations()

Return the expiration dates of the local TUF metadata copy.

Returns

A dictionary containing datetime values for the keys root, targets, snapshot and timestamp.

Return type

dict

list_targets()

Return the names of all the targets defined in the local copy of the TUF metadata.

Returns

List of target names

Return type

list

pull_metadata(root_public_key=None, progress=None)

Download TUF metadata from the repository.

The metadata is checked for expiry and verified against the root public key for the repository.

You only need to supply the root public key once, and you should obtain it from the person who uploaded the metadata.

Target data is not downloaded - use pull_target() for that.

Parameters
  • root_public_key (str) – PEM-encoded root public key. Obtain this from the repository’s owner, who generates the key using DTufMaster.create_root_key() on the repository master.

  • progress (function(dgst, chunk, total)) – Optional function to call as the download progresses. The function will be called with the hash of the metadata currently being download, the blob just read from the repository and the total size of the metadata.

Returns

List of targets which have been updated since you last downloaded them (using pull_target()).

Return type

list

pull_target(target, digests_and_sizes=False)

Download a target (data) from the repository.

Target data consists of one or more separate blobs (depending on how many were uploaded). Because this function returns an iterator, download of each blob occurs lazily.

Target information is stored in the TUF metadata, so you should have called pull_metadata() previously.

Parameters
  • target (str) – Name of the target to download.

  • digests_and_sizes (bool) – Whether to return the hash and size of each downloaded blob as well.

Returns

If digests_and_sizes is falsey, an iterator which yields for each blob an iterator over its content. If digests_and_sizes is truthy, an iterator which yields for each blob a tuple containing an iterator over its content, the hash of its content and its size.

Return type

iterator

class dtuf.DTufMaster(host, repo, repos_root=None, auth=None, insecure=False, auth_host=None, root_lifetime=None, targets_lifetime=None, snapshot_lifetime=None, timestamp_lifetime=None)

Bases: dtuf._DTufCommon

Class for creating, updating and publishing data to repositories in a Docker registry using The Update Framework (TUF).

Parameters
  • host (str) – Host name of registry. Can contain port numbers. e.g. registry-1.docker.io, localhost:5000.

  • repo (str) – Name of the repository to access on the registry. Typically this is of the form username/reponame but for your own registries you don’t actually have to stick to that. The repository is used to store data and TUF metadata describing the data.

  • repos_root (str) – Directory under which to store TUF metadata. Note that the value of repo and the literal string master are appended to this directory name before storing the metadata. Defaults to dtuf_repos in the current working directory.

  • auth (function(dtuf_obj, response)) – Authentication function to be called whenever authentication to the registry is required. Receives the DTufBase object and a HTTP response object. It should call DTufBase.authenticate() on dtuf_obj with a username, password and response before it returns.

  • insecure (bool) – Use HTTP instead of HTTPS (which is the default) when connecting to the registry.

  • auth_host (str) – Host to use for token authentication. If set, overrides host returned by then registry.

  • root_lifetime (datetime.timedelta) – Lifetime of the TUF root metadata. After this time expires, you’ll need to call reset_keys() and push_metadata() to re-sign the metadata. Defaults to tuf.repository_tool.ROOT_EXPIRATION (1 year).

  • targets_lifetime (datetime.timedelta) – Lifetime of the TUF targets metadata. After this time expires, you’ll need to call push_metadata() to re-sign the metadata. Defaults to tuf.repository_tool.TARGETS_EXPIRATION (3 months).

  • snapshot_lifetime (datetime.timedelta) – Lifetime of the TUF snapshot metadata. After this time expires, you’ll need to call push_metadata() to re-sign the metadata. Defaults to tuf.repository_tool.SNAPSHOT_EXPIRATION (1 week).

  • timestamp_lifetime (datetime.timedelta) – Lifetime of the TUF timestamp metadata. After this time expires, you’ll need to call push_metadata() to re-sign the metadata. Defaults to tuf.repository_tool.TIMESTAMP_EXPIRATION (1 day).

create_metadata(root_key_password=None, targets_key_password=None, snapshot_key_password=None, timestamp_key_password=None)

Create and sign the TUF metadata for the repository.

You only need to call this once for each repository, and the repository’s root and metadata private keys must be available.

Parameters
  • root_key_password – Password to use for decrypting the TUF root private key. You’ll be prompted for one if you don’t supply it.

  • targets_key_password – Password to use for decrypting the TUF targets private key. You’ll be prompted for one if you don’t supply it.

  • snapshot_key_password – Password to use for decrypting the TUF snapshot private key. You’ll be prompted for one if you don’t supply it.

  • timestamp_key_password – Password to use for decrypting the TUF timestamp private key. You’ll be prompted for one if you don’t supply it.

create_metadata_keys(targets_key_password=None, snapshot_key_password=None, timestamp_key_password=None)

Create TUF metadata keypairs for the repository.

The keys are written to the <repos_root>/<repo>/master/keys directory. The public keys have a .pub extension.

You can move the private keys offline once you’ve called create_metadata() but you’ll need them again when you call push_metadata() to publish the repository.

You don’t need to give out the metadata public keys since they’re published on the repository.

Parameters
  • targets_key_password – Password to use for encrypting the TUF targets private key. You’ll be prompted for one if you don’t supply it.

  • snapshot_key_password – Password to use for encrypting the TUF snapshot private key. You’ll be prompted for one if you don’t supply it.

  • timestamp_key_password – Password to use for encrypting the TUF timestamp private key. You’ll be prompted for one if you don’t supply it.

create_root_key(password=None)

Create root keypair for the repository.

The private key is written to <repos_root>/<repo>/master/keys/root_key and can be moved offline once you’ve called create_metadata(). You’ll need it again if you call reset_keys() when the root metadata expires.

The public key is written to <repos_root>/<repo>/master/keys/root_key.pub and can be given to others for use when retrieving a copy of the repository metadata with DTufCopy.pull_metadata().

Parameters

password (str) – Password to use for encrypting the private key. You’ll be prompted for one if you don’t supply it.

del_target(target)

Delete a target (data) from the repository and update the local TUF metadata.

The metadata isn’t updated on the registry until you call push_metadata().

Note that the registry doesn’t support deletes yet so expect an error.

Parameters

target (str) – The name you gave to the data when it was uploaded using push_target().

get_expirations()

Return the expiration dates of the TUF metadata.

Returns

A dictionary containing datetime values for the keys root, targets, snapshot and timestamp.

Return type

dict

list_targets()

Return the names of all the targets defined in the local TUF metadata.

Returns

List of target names

Return type

list

push_metadata(targets_key_password=None, snapshot_key_password=None, timestamp_key_password=None, progress=None)

Upload local TUF metadata to the repository.

The TUF metadata consists of a list of targets (which were uploaded by push_target()), a snapshot of the state of the metadata (list of hashes), a timestamp and a list of public keys.

This function signs the metadata except for the list of public keys, so you’ll need to supply the password to the respective private keys.

The list of public keys was signed (along with the rest of the metadata) with the root private key when you called create_metadata() (or reset_keys()).

Parameters
  • targets_key_password – Password to use for decrypting the TUF targets private key. You’ll be prompted for one if you don’t supply it.

  • snapshot_key_password – Password to use for decrypting the TUF snapshot private key. You’ll be prompted for one if you don’t supply it.

  • timestamp_key_password – Password to use for decrypting the TUF timestamp private key. You’ll be prompted for one if you don’t supply it.

  • progress (function(dgst, chunk, total)) – Optional function to call as the upload progresses. The function will be called with the hash of the content of the file currently being uploaded, the blob just read from the file and the total size of the file.

push_target(target, *filename_or_target_list, **kwargs)

Upload data to the repository and update the local TUF metadata.

The metadata isn’t uploaded until you call push_metadata().

The data is given a name (known as the target) and can come from a list of files or existing target names.

Parameters
  • target (str) – Name to give the data.

  • filename_or_target_list (list) – List of data to upload. Each item is either a filename or an existing target name. Existing target names should be prepended with @ in order to distinguish them from filenames.

  • kwargs (dict({'progress': function(dgst, chunk, total)})) – Contains an optional progress member which is a function to call as the upload progresses. The function will be called with the hash of the content of the file currently being uploaded, the blob just read from the file and the total size of the file.

reset_keys(root_key_password=None, targets_key_password=None, snapshot_key_password=None, timestamp_key_password=None)

Re-sign the TUF metadata for the repository.

Call this if you’ve generated new root or metadata keys (because one of the keys has been compromised, for example) but you don’t want to delete the repository and start again.

Parameters
  • root_key_password – Password to use for decrypting the TUF root private key. You’ll be prompted for one if you don’t supply it.

  • targets_key_password – Password to use for decrypting the TUF targets private key. You’ll be prompted for one if you don’t supply it.

  • snapshot_key_password – Password to use for decrypting the TUF snapshot private key. You’ll be prompted for one if you don’t supply it.

  • timestamp_key_password – Password to use for decrypting the TUF timestamp private key. You’ll be prompted for one if you don’t supply it.

dtuf.exceptions module

Module containing exceptions thrown by dtuf.

exception dtuf.exceptions.DTufError

Bases: Exception

Base exception class for all dtuf errors

exception dtuf.exceptions.DTufReservedTargetError(target)

Bases: dtuf.exceptions.DTufError

Target name is reserved so can’t be used in dtuf.DTufMaster.push_target().

Parameters

target (str) – Target name

Indices and tables