Docker registry bindings for The Update Framework
This assumes at least DTUF_HOST has been set to the hostname of a Docker registry (see Usage below). You may need to set DTUF_USERNAME and DTUF_PASSWORD too depending on the registry you’re using.
You can run your own registry or use a hosted one such as Docker Hub (registry-1.docker.io).
# On the master machine $ echo 'Hello World!' > demo.txt $ dtuf create-root-key fred/demo $ dtuf create-metadata-keys fred/demo $ dtuf create-metadata fred/demo $ dtuf push-target fred/demo demo.txt demo.txt $ dtuf push-metadata fred/demo # pub key is in dtuf_repos/fred/demo/master/keys/root_key.pub # distribute it out-of-band # On some other machine $ dtuf pull-metadata fred/demo root_key.pub demo.txt $ dtuf pull-target fred/demo demo.txt Hello World! # Update on the master machine $ echo 'Update World!' > demo.txt $ echo 'Another World!' > demo2.txt $ dtuf push-target fred/demo demo.txt demo.txt $ dtuf push-target fred/demo demo2.txt demo2.txt $ dtuf push-metadata fred/demo # On the other machine $ dtuf pull-metadata fred/demo demo.txt demo2.txt $ dtuf pull-target fred/demo demo.txt Update World! $ dtuf pull-target fred/demo demo2.txt Another World!
This example uses the Docker Hub. Change the username, password and repository name to suit.
Publish on the master machine:
from dtuf import DTufMaster def auth(dtuf, response): dtuf.authenticate('fred', 'somepassword', response=response) dtuf = DTufMaster('registry-1.docker.io', 'fred/demo', auth=auth) with open('demo.txt', 'w') as f: f.write('Hello World!\n') dtuf.create_root_key() dtuf.create_metadata_keys() dtuf.create_metadata() dtuf.push_target('demo.txt', 'demo.txt') dtuf.push_metadata() # pub key is in dtuf_repos/fred/demo/master/keys/root_key.pub # distribute it out-of-band
Retrieve on some other machine:
from dtuf import DTufCopy def auth(dtuf, response): dtuf.authenticate('barney', 'otherpassword', response=response) dtuf = DTufCopy('registry-1.docker.io', 'fred/demo', auth=auth) with open('root_key.pub', 'r') as f: assert dtuf.pull_metadata(f.read()) == ['demo.txt'] s = '' for download in dtuf.pull_target('demo.txt'): for chunk in download: s += chunk assert s == 'Hello World!\n'
The module API is described here.
The dtuf command-line tool uses the following environment variables. Only DTUF_HOST is strictly required but you may need to set others depending on your set up.
You can use the following options with dtuf. In each case, supply the name of the repository on the registry you wish to work with as the second argument.
dtuf create-root-key <repo>
Create TUF root keypair for the repository.
The private key is written to $DTUF_REPOSITORIES_ROOT/<repo>/master/keys/root_key and can be moved offline once you’ve used dtuf create-metadata. You’ll need it again if you use dtuf reset-keys when the root metadata expires.
The public key is written to $DTUF_REPOSITORIES_ROOT/<repo>/master/keys/root_key.pub and can be given to others for use when retrieving a copy of the repository metadata with dtuf pull-metadata.
dtuf create-metadata-keys <repo>
Create TUF metadata keypairs for the repository.
The keys are written to the $DTUF_REPOSITORIES_ROOT/<repo>/master/keys directory. The public keys have a .pub extension.
You can move the private keys offline once you’ve used dtuf push-metadata to publish the repository.
You don’t need to give out the metadata public keys since they’re published on the repository.
dtuf create-metadata <repo>
Create and sign the TUF metadata for the repository.
You only need to do this once for each repository, and the repository’s root and metadata private keys must be available.
dtuf reset-keys <repo>
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.
dtuf push-target <repo> <target> <file|@target>...
Upload data to the repository and update the local TUF metadata
The metadata isn’t uploaded until you use dtuf push-metadata.
The data is given a name (known as the target) and can come from a list of files or existing target names. Existing target names should be prepended with @ in order to distinguish them from filenames.
dtuf del-target <repo> <target>...
Delete targets (data) from the repository and update the local TUF metadata.
The metadata isn’t updated on the registry until you use dtuf push-metadata.
Note that the registry doesn’t support deletes yet so expect an error.
dtuf push-metadata <repo>
Upload local TUF metadata to the repository.
The TUF metadata consists of a list of targets (which were uploaded by dtuf push-target), a snapshot of the state of the metadata (list of hashes), a timestamp and a list of public keys.
The metadata except for the list of public keys will be signed here. The list of public keys was signed (along with the rest of the metadata) when you used dtuf create-metadata (or dtuf reset-keys).
dtuf list-master-targets <repo>
Print the names of all the targets defined in the local TUF metadata.
dtuf get-master-expirations <repo>
Print the expiration dates of the TUF metadata.
dtuf pull-metadata <repo> [<root-pubkey-file>|-]
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. If you specify - then the key is read from standard input instead of a file.
Target data is not downloaded - use dtuf pull-target for that.
A list of targets which have been updated since you last downloaded them will be printed to standard output, one per line.
dtuf pull-target <repo> <target>...
Download targets (data) from the repository to standard output.
Each target’s data consists of one of more separate blobs (depending on how many > were uploaded). All of them will be downloaded.
dtuf blob-sizes <repo> <target>...
Print the sizes of all the blobs which make up a list of targets.
dtuf check-target <repo> <target> <file>...
Check whether the hashes of a target’s blobs match the hashes of list of files. An error message will be displayed if not and the exit code won’t be 0.
dtuf list-copy-targets <repo>
Print the names of all the targets defined in the local copy of the TUF metadata.
dtuf get-copy-expirations <repo>
Print the expiration dates of the local copy of the TUF metadata.
Print the names of all the repositories in the registry.
dtuf automatically obtains Docker registry authentication tokens using your DTUF_USERNAME and DTUF_PASSWORD environment variables as necessary.
However, if you wish to override this then you can use the following command:
dtuf auth <repo> <action>...
Authenticate to the registry using DTUF_USERNAME and DTUF_PASSWORD, and print the resulting token.
action can be pull, push or *.
If you assign the token to the DTUF_TOKEN environment variable, for example:
DTUF_TOKEN=$(dtuf auth fred/demo pull)
then subsequent dtuf commands will use the token without needing DTUF_USERNAME and DTUF_PASSWORD to be set.
Note however that the token expires after a few minutes, after which dtuf will exit with EACCES.
pip install python-dtuf