Metadata-Version: 2.0
Name: python-dtuf
Version: 1.0.0
Summary: Docker registry bindings for The Update Framework
Home-page: https://github.com/davedoesdev/dtuf
Author: David Halls
Author-email: dave@davedoesdev.com
License: MIT
Keywords: docker registry tuf update framework
Platform: UNKNOWN
Requires-Dist: cryptography (>=1.1.2)
Requires-Dist: decorator (>=4.0.6)
Requires-Dist: fasteners (>=0.14.1)
Requires-Dist: iso8601 (>=0.1.11)
Requires-Dist: pycrypto (>=2.6.1)
Requires-Dist: python-dxf (>=3.0.0)
Requires-Dist: pytimeparse (>=1.1.5)
Requires-Dist: tqdm (>=3.1.4)
Requires-Dist: tuf (>=0.10.0)

\ |Build Status| |Coverage Status| |PyPI version|

Docker registry bindings for `The Update
Framework <http://theupdateframework.com/>`__ in Python. Uses
`dxf <https://github.com/davedoesdev/dxf>`__ to 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 of `The
   Update Framework <http://theupdateframework.com/>`__.
-  Backed by the scalability and flexbility of a `Docker
   registry <https://github.com/docker/distribution>`__.
-  No extra moving parts: just Python client-side and Docker registry
   server-side.

   -  Docker client and daemon not required.
   -  `Notary <https://github.com/docker/notary>`__ not required. See
      `this issue <https://github.com/docker/notary/issues/261>`__ for
      discussion.

-  Supports Docker registry version 2.3.0 upwards (schema v2)
-  Works on Python 2.7 and 3.4.

Examples
--------

Command-line example
~~~~~~~~~~~~~~~~~~~~

This assumes at least ``DTUF_HOST`` has been set to the hostname of a
Docker registry (see `Usage <#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``).

If you want to run your own, see this `example
script <test/cli_example.sh>`__ or the `unit
tests <test/conftest.py>`__. There are also full instructions available
`here <https://github.com/docker/distribution/blob/master/docs/deploying.md>`__.

.. code:: shell

    # 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!

Module example
~~~~~~~~~~~~~~

This example uses the Docker Hub. Change the username, password and
repository name to suit.

Publish on the master machine:

.. code:: python

    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:

.. code:: python

    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'

Usage
-----

The module API is described
`here <http://rawgit.davedoesdev.com/davedoesdev/dtuf/master/docs/_build/html/index.html>`__.

Environment variables
~~~~~~~~~~~~~~~~~~~~~

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.

-  ``DTUF_HOST`` - Host where Docker registry is running
-  ``DTUF_INSECURE`` - Set this to ``1`` if you want to connect to the
   registry using ``http`` rather than ``https`` (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 to ``dtuf_repos`` in 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 to ``1``, a progress bar is
   displayed (on standard error) during ``dtuf push-target``,
   ``dtuf push-metadata``, ``dtuf pull-metadata`` and
   ``dtuf pull-target``. If this is set to ``0``, 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 to ``1`` if you want
   ``dtuf pull-target`` to 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 by ``dtuf create-root-key``,
   ``dtuf create-metadata`` and ``dtuf reset-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 by ``dtuf create-metadata-keys``,
   ``dtuf create-metadata``, ``dtuf reset-keys`` and
   ``dtuf push-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 by ``dtuf create-metadata-keys``,
   ``dtuf create-metadata``, ``dtuf reset-keys`` and
   ``dtuf push-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 by ``dtuf create-metadata-keys``,
   ``dtuf create-metadata``, ``dtuf reset-keys`` and
   ``dtuf push-metadata``. If unset then you'll be prompted for the
   password.
-  ``DTUF_ROOT_LIFETIME`` - Lifetime of the TUF `root
   metadata <https://github.com/theupdateframework/tuf/blob/develop/docs/tuf-spec.txt#L235>`__.
   After this time expires, you'll need to use ``dtuf reset-keys`` and
   ``dtuf push-metadata`` to re-sign the metadata. Defaults to 1 year.
-  ``DTUF_TARGETS_LIFETIME`` - Lifetime of the TUF `targets
   metadata <https://github.com/theupdateframework/tuf/blob/develop/docs/tuf-spec.txt#L246>`__.
   After this time expires, you'll need to use ``dtuf push-metadata`` to
   re-sign the metadata. Defaults to 3 months.
-  ``DTUF_SNAPSHOT_LIFETIME`` - Lifetime of the TUF `snapshot
   metadata <https://github.com/theupdateframework/tuf/blob/develop/docs/tuf-spec.txt#L268>`__.
   After this time expires, you'll need to use ``dtuf push-metadata`` to
   re-sign the metadata. Defaults to 1 week.
-  ``DTUF_TIMESTAMP_LIFETIME`` - Lifetime of the TUF `timestamp
   metadata <https://github.com/theupdateframework/tuf/blob/develop/docs/tuf-spec.txt#L276>`__.
   After this time expires, you'll need to use ``dtuf push-metadata`` to
   re-sign the metadata. Defaults to 1 day.
-  ``DTUF_LOG_FILE`` - Name of file to write log messages into. Defaults
   to ``dtuf.log`` in the current working directory. Set it to an empty
   string to disable logging to a file.
-  ``DTUF_FILE_LOG_LEVEL`` - Name of the Python `logging
   level <https://docs.python.org/2/library/logging.html#logging-levels>`__
   to use when deciding which messages to write to the log file.
   Defaults to ``WARNING``.
-  ``DTUF_CONSOLE_LOG_LEVEL`` - Name of the Python logging level to use
   when deciding which messages to write to the console. Defaults to
   ``WARNING``.

Command line options
~~~~~~~~~~~~~~~~~~~~

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.

Creating, updating and uploading data
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

-  ``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.

Downloading data
^^^^^^^^^^^^^^^^

-  ``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.

-  ``dtuf list-repos``

       Print the names of all the repositories in the registry.

Authentication tokens
---------------------

``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``.

Installation
------------

.. code:: shell

    pip install python-dtuf

Licence
-------

`MIT <https://raw.github.com/davedoesdev/dtuf/master/LICENCE>`__

Tests
-----

.. code:: shell

    make test

Lint
----

.. code:: shell

    make lint

Code Coverage
-------------

.. code:: shell

    make coverage

`coverage.py <http://nedbatchelder.com/code/coverage/>`__ results are
available
`here <http://rawgit.davedoesdev.com/davedoesdev/dtuf/master/htmlcov/index.html>`__.

Coveralls page is `here <https://coveralls.io/r/davedoesdev/dtuf>`__.

.. |Build Status| image:: https://travis-ci.org/davedoesdev/dtuf.png
   :target: https://travis-ci.org/davedoesdev/dtuf
.. |Coverage Status| image:: https://coveralls.io/repos/davedoesdev/dtuf/badge.png?branch=master
   :target: https://coveralls.io/r/davedoesdev/dtuf?branch=master
.. |PyPI version| image:: https://badge.fury.io/py/python_dtuf.png
   :target: http://badge.fury.io/py/python_dtuf


