dtuf module¶
|
Class for communicating with a Docker v2 registry. |
|
Class for creating, updating and publishing data to repositories in a Docker registry using The Update Framework (TUF). |
|
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 byDTufCopy.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 callauthenticate()
ondtuf_obj
with a username, password andresponse
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 toDTufBase
’s constructor is called, it is passed a HTTP response object. Pass it back toauthenticate()
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 stringcopy
are appended to this directory name before storing the metadata. Defaults todtuf_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 callDTufBase.authenticate()
with a username, password andresponse
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
andtimestamp
.- 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. Ifdigests_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 stringmaster
are appended to this directory name before storing the metadata. Defaults todtuf_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 callDTufBase.authenticate()
ondtuf_obj
with a username, password andresponse
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()
andpush_metadata()
to re-sign the metadata. Defaults totuf.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 totuf.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 totuf.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 totuf.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 callpush_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 calledcreate_metadata()
. You’ll need it again if you callreset_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 withDTufCopy.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
andtimestamp
.- 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()
(orreset_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