Package: python-dtuf
This module is now DEPRECATED!The Update
Frameworkhas moved to version 2
and I don’t have time to update dtuf to work with it.Docker registry bindings forThe Update
Frameworkin Python. Usesdxfto store TUF metadata and
target files in a Docker registry.Easy-to-use Python module and command-line tool.Distribute your data with the security and trust features ofThe
Update Framework.Backed by the scalability and flexbility of aDocker
registry.No extra moving parts: just Python client-side and Docker registry
server-side.Docker client and daemon not required.Notarynot required. Seethis issuefor
discussion.Supports Docker registry schema v1 and v2.Works on Python 2.7 and 3.4.ExamplesCommand-line exampleThis assumes at leastDTUF_HOSThas been set to the hostname of a
Docker registry (seeUsagebelow). You may need to setDTUF_USERNAMEandDTUF_PASSWORDtoo 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).If you want to run your own, see thisexample
scriptor theunit
tests. There are also full instructions availablehere.# On the master machine$echo'Hello World!'>demo.txt$dtufcreate-root-keyfred/demo$dtufcreate-metadata-keysfred/demo$dtufcreate-metadatafred/demo$dtufpush-targetfred/demodemo.txtdemo.txt$dtufpush-metadatafred/demo# pub key is in dtuf_repos/fred/demo/master/keys/root_key.pub
# distribute it out-of-band# On some other machine$dtufpull-metadatafred/demoroot_key.pubdemo.txt$dtufpull-targetfred/demodemo.txtHelloWorld!# Update on the master machine$echo'Update World!'>demo.txt$echo'Another World!'>demo2.txt$dtufpush-targetfred/demodemo.txtdemo.txt$dtufpush-targetfred/demodemo2.txtdemo2.txt$dtufpush-metadatafred/demo# On the other machine$dtufpull-metadatafred/demodemo.txtdemo2.txt$dtufpull-targetfred/demodemo.txtUpdateWorld!$dtufpull-targetfred/demodemo2.txtAnotherWorld!Module exampleThis example uses the Docker Hub. Change the username, password and
repository name to suit.Publish on the master machine:fromdtufimportDTufMasterdefauth(dtuf,response):dtuf.authenticate('fred','somepassword',response=response)dtuf=DTufMaster('registry-1.docker.io','fred/demo',auth=auth)withopen('demo.txt','w')asf: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-bandRetrieve on some other machine:fromdtufimportDTufCopydefauth(dtuf,response):dtuf.authenticate('barney','otherpassword',response=response)dtuf=DTufCopy('registry-1.docker.io','fred/demo',auth=auth)withopen('root_key.pub','r')asf:assertdtuf.pull_metadata(f.read())==['demo.txt']s=''fordownloadindtuf.pull_target('demo.txt'):forchunkindownload:s+=chunkasserts=='Hello World!\n'UsageThe module API is describedhere.Environment variablesThedtufcommand-line tool uses the following environment variables.
OnlyDTUF_HOSTis strictly required but you may need to set others
depending on your set up.DTUF_HOST- Host where Docker registry is runningDTUF_INSECURE- Set this to1if you want to connect to the
registry usinghttprather thanhttps(which is the default).DTUF_USERNAME- Name of user to authenticate as.DTUF_PASSWORD- User’s password.DTUF_REPOSITORIES_ROOT- Directory under which TUF metadata
should be stored. Note that the repository name is appended to this
before storing the metadata. Defaults todtuf_reposin the
current working directory.DTUF_AUTH_HOST- If set, always perform token authentication to
this host, overriding the value returned by the registry.DTUF_PROGRESS- If this is set to1, a progress bar is
displayed (on standard error) duringdtufpush-target,dtufpush-metadata,dtufpull-metadataanddtufpull-target. If this is set to0, a progress bar is not
displayed. If this is set to any other value, a progress bar is only
displayed if standard error is a terminal.DTUF_BLOB_INFO- Set this to1if you wantdtufpull-targetto prepend each blob with its digest and size
(printed in plain text, separated by a space and followed by a
newline).DTUF_ROOT_KEY_PASSWORD- Password to use for encrypting the TUF
root private key. Used bydtufcreate-root-key,dtufcreate-metadataanddtufreset-keys. If unset then
you’ll be prompted for the password.DTUF_TARGETS_KEY_PASSWORD- Password to use for encrypting the
TUF targets private key. Used bydtufcreate-metadata-keys,dtufcreate-metadata,dtufreset-keysanddtufpush-metadata. If unset then you’ll be prompted for the
password.DTUF_SNAPSHOT_KEY_PASSWORD- Password to use for encrypting the
TUF snapshot private key. Used bydtufcreate-metadata-keys,dtufcreate-metadata,dtufreset-keysanddtufpush-metadata. If unset then you’ll be prompted for the
password.DTUF_TIMESTAMP_KEY_PASSWORD- Password to use for enrypting the
TUF timestamp private key. Used bydtufcreate-metadata-keys,dtufcreate-metadata,dtufreset-keysanddtufpush-metadata. If unset then you’ll be prompted for the
password.DTUF_ROOT_LIFETIME- Lifetime of the TUFroot
metadata.
After this time expires, you’ll need to usedtufreset-keysanddtufpush-metadatato re-sign the metadata. Defaults to 1 year.DTUF_TARGETS_LIFETIME- Lifetime of the TUFtargets
metadata.
After this time expires, you’ll need to usedtufpush-metadatato
re-sign the metadata. Defaults to 3 months.DTUF_SNAPSHOT_LIFETIME- Lifetime of the TUFsnapshot
metadata.
After this time expires, you’ll need to usedtufpush-metadatato
re-sign the metadata. Defaults to 1 week.DTUF_TIMESTAMP_LIFETIME- Lifetime of the TUFtimestamp
metadata.
After this time expires, you’ll need to usedtufpush-metadatato
re-sign the metadata. Defaults to 1 day.DTUF_LOG_FILE- Name of file to write log messages into. Defaults
todtuf.login the current working directory. Set it to an empty
string to disable logging to a file.DTUF_FILE_LOG_LEVEL- Name of the Pythonlogging
levelto use when deciding which messages to write to the log file.
Defaults toWARNING.DTUF_CONSOLE_LOG_LEVEL- Name of the Python logging level to use
when deciding which messages to write to the console. Defaults toWARNING.Command line optionsYou can use the following options withdtuf. In each case, supply
the name of the repository on the registry you wish to work with as the
second argument.Creating, updating and uploading datadtufcreate-root-key<repo>Create TUF root keypair for the repository.The private key is written to$DTUF_REPOSITORIES_ROOT/<repo>/master/keys/root_keyand can be
moved offline once you’ve useddtufcreate-metadata. You’ll
need it again if you usedtufreset-keyswhen the root
metadata expires.The public key is written to$DTUF_REPOSITORIES_ROOT/<repo>/master/keys/root_key.puband
can be given to others for use when retrieving a copy of the
repository metadata withdtufpull-metadata.dtufcreate-metadata-keys<repo>Create TUF metadata keypairs for the repository.The keys are written to the$DTUF_REPOSITORIES_ROOT/<repo>/master/keysdirectory. The
public keys have a.pubextension.You can move the private keys offline once you’ve useddtufpush-metadatato publish the repository.You don’t need to give out the metadata public keys since they’re
published on the repository.dtufcreate-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.dtufreset-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.dtufpush-target<repo> <target><file|@target>...Upload data to the repository and update the local TUF metadataThe metadata isn’t uploaded until you usedtufpush-metadata.The data is given a name (known as thetarget) 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.dtufdel-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 usedtufpush-metadata.Note that the registry doesn’t support deletes yet so expect an
error.dtufpush-metadata<repo>Upload local TUF metadata to the repository.The TUF metadata consists of a list of targets (which were
uploaded bydtufpush-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 useddtufcreate-metadata(ordtufreset-keys).dtuflist-master-targets<repo>Print the names of all the targets defined in the local TUF
metadata.dtufget-master-expirations<repo>Print the expiration dates of the TUF metadata.Downloading datadtufpull-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 - usedtufpull-targetfor that.A list of targets which have been updated since you last
downloaded them will be printed to standard output, one per line.dtufpull-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.dtufblob-sizes<repo><target>...Print the sizes of all the blobs which make up a list of targets.dtufcheck-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.dtuflist-copy-targets<repo>Print the names of all the targets defined in the local copy of
the TUF metadata.dtufget-copy-expirations<repo>Print the expiration dates of the local copy of the TUF metadata.dtuflist-reposPrint the names of all the repositories in the registry.Authentication tokensdtufautomatically obtains Docker registry authentication tokens
using yourDTUF_USERNAMEandDTUF_PASSWORDenvironment 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 usingDTUF_USERNAMEandDTUF_PASSWORD, and print the resulting token.actioncan bepull,pushor*.If you assign the token to theDTUF_TOKENenvironment variable, for
example:DTUF_TOKEN=$(dtufauth fred/demo pull)then subsequentdtufcommands will use the token without needingDTUF_USERNAMEandDTUF_PASSWORDto be set.Note however that the token expires after a few minutes, after whichdtufwill exit withEACCES.Installationpipinstallpython-dtufLicenceMITTestsmaketestLintmakelintCode Coveragemakecoveragecoverage.pyresults are
availablehere.Coveralls page ishere.