theupdateframework · jku · Feb 14, 2022 · Feb 9, 2022 · Feb 9, 2022 · Feb 9, 2022
@@ -1,4 +1,4 @@
-Instructions for Contributors
+Instructions for contributors
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Contribute to python-tuf by submitting pull requests against the "develop"
@@ -9,37 +9,14 @@ All submitted code should follow our `style guidelines
 <https://github.com/secure-systems-lab/code-style-guidelines/blob/master/python.md>`_
 and must be `unit tested <#unit-tests>`_.
 
-Development Installation
-========================
-
-To work on the TUF project, it's best to perform a development install.
-
-To facilitate development and installation of edited version of the code base,
-developers are encouraged to use `venv <https://docs.python.org/3/library/venv.html>`_.
-
-1. First, `install non-Python dependencies
-<https://theupdateframework.readthedocs.io/en/latest/INSTALLATION.html#non-python-dependencies>`_.
-
-2. Then clone this repository:
-
-::
-
- $ git clone https://github.com/theupdateframework/python-tuf
-
-3. Then perform a full, editable/development install. This will include all
- optional cryptographic support, the testing/linting dependencies, etc.
- With a development installation, modifications to the code in the current
- directory will affect the installed version of TUF.
-
-::
-
- $ python3 -m pip install -r requirements-dev.txt
+.. note::
 
+ Also see `development installation instructions <https://theupdateframework.readthedocs.io/en/latest/INSTALLATION.html#install-for-development>`_.
 
 Testing
 =======
 
-With `tox <https://testrun.org/tox/>`_ the whole test suite can be executed in
+With `tox <https:///tox.wiki>`_ the whole test suite can be executed in
 a separate *virtual environment* for each supported Python version available on
 the system. ``tuf`` and its dependencies are installed automatically for each
 tox run.

@@ -1,93 +1,86 @@
 Installation
 ============
 
-*pip* is the recommended installer for installing and managing Python packages.
-The project can be installed either locally or from the Python Package Index.
-All `TUF releases
-<https://github.com/theupdateframework/python-tuf/releases>`_ are cryptographically
-signed, with GPG signatures available on both GitHub and `PyPI
-<https://pypi.python.org/pypi/tuf/>`_. PGP key information for our maintainers
-is available on our `website
-<https://theupdateframework.github.io/people.html>`_, on major keyservers,
-and on the `maintainers page
-<https://github.com/theupdateframework/python-tuf/blob/develop/docs/MAINTAINERS.txt>`_.
+All versions of ``python-tuf`` can be installed from
+`PyPI <https://pypi.org/project/tuf/>`_ with
+`pip <https://pip.pypa.io/en/stable/>`_.
 
+::
 
-Release Verification
---------------------
+ python3 -m pip install tuf
 
-Assuming you trust `the maintainer's PGP key
-<https://github.com/theupdateframework/python-tuf/blob/develop/docs/MAINTAINERS.txt>`_,
-the detached ASC signature can be downloaded and verified. For example::
+By default tuf is installed as pure python package with limited cryptographic
+abilities. See `Install with full cryptographic abilities`_ for more options.
 
- $ gpg --verify securesystemslib-0.10.8.tar.gz.asc
- gpg: assuming signed data in 'securesystemslib-0.10.8.tar.gz'
- gpg: Signature made Wed Nov 8 15:21:47 2017 EST
- gpg: using RSA key 3E87BB339378BC7B3DD0E5B25DEE9B97B0E2289A
- gpg: Good signature from "Vladimir Diaz (Vlad) <vladimir.v.diaz@gmail.com>" [ultimate]
 
+Install with full cryptographic abilities
+-----------------------------------------
 
+Default installation supports signature verification only, using a pure Python
+*ed25519* implementation. While this allows to operate a *basic client* on
+almost any computing device, you will need additional cryptographic abilities
+for *repository* code, i.e. key and signature generation, additional
+algorithms, and more performant backends. Opt-in is available via
+``securesystemslib``.
 
-Simple Installation
--------------------
+.. note::
 
-If you are only using ed25519-based cryptography, you can employ a pure-Python
-installation, done simply with one of the following commands:
+ Please consult with underlying crypto backend installation docs --
+ `cryptography <https://cryptography.io/en/latest/installation/>`_ and
+ `pynacl <https://pynacl.readthedocs.io/en/latest/install/>`_ --
+ for possible system dependencies.
 
-Installing from Python Package Index (https://pypi.python.org/pypi).
-(Note: Please use "python3 -m pip install --no-use-wheel tuf" if your version
-of pip <= 1.5.6)::
+::
 
-  $ python3 -m pip install tuf
+ python3 -m pip securesystemslib[crypto,pynacl] tuf
 
 
-**Alternatively**, if you wish to install from a GitHub release you've already
-downloaded, or a package you obtained in another way, you can instead:
-
-Install from a local source archive::
-
- $ python3 -m pip install <path to archive>
-
-Or install from the root directory of the unpacked archive::
-
- $ python3 -m pip install .
-
-
-
-Install with More Cryptographic Flexibility
--------------------------------------------
+Install for development
+-----------------------
 
-By default, C extensions are not installed and only Ed25519 signatures can
-be verified, in pure Python. To fully support RSA, Ed25519, ECDSA, and
-other crypto, you must install the extra dependencies declared by
-securesystemslib. **Note**: that may require non-Python dependencies, so if
-you encounter an error attempting this pip command, see
-`more instructions below <#non-python-dependencies>`_). ::
+To install tuf in editable mode together with development dependencies,
+`clone <https://docs.github.com/en/repositories/creating-and-managing-repositories/cloning-a-repository>`_ the
+`python-tuf repository <https://github.com/theupdateframework/python-tuf>`_
+from GitHub, change into the project root directory, and install with pip
+(using `venv <https://docs.python.org/3/library/venv.html>`_ is recommended).
 
- $ python3 -m pip install securesystemslib[crypto,pynacl] tuf
+.. note::
 
+ Development installation will `Install with full cryptographic abilities`_.
+ Please check above for possible system dependencies.
 
+::
 
-Non-Python Dependencies
------------------------
+ python3 -m pip install -r requirements-dev.txt
 
-If you encounter errors during installation, you may be missing
-certain system libraries.
 
-For example, PyNaCl and Cryptography -- two libraries used in the full
-installation to support certain cryptographic functions -- may require FFI
-(Foreign Function Interface) development header files.
+Verify release signatures
+-------------------------
 
-Debian-based distributions can install the necessary header libraries with apt::
+Releases on PyPI are signed with a maintainer key using
+`gpg <https://gnupg.org/>`_ (see
+`MAINTAINERS.txt <https://github.com/theupdateframework/python-tuf/blob/develop/docs/MAINTAINERS.txt>`_
+for key fingerprints). Signatures can be downloaded from the
+`GitHub release <https://github.com/theupdateframework/python-tuf/releases>`_
+page (look for *\*.asc* files in the *Assets* section).
 
- $ apt-get install build-essential libssl-dev libffi-dev python-dev
+Below code shows how to verify the signature of a
+`built <https://packaging.python.org/en/latest/glossary/#term-Built-Distribution>`_ distribution,
+signed by the maintainer *Lukas Pühringer*. It works
+alike for `source <https://packaging.python.org/en/latest/glossary/#term-Source-Distribution-or-sdist>`_ distributions.
 
-Fedora-based distributions can instead install these libraries with dnf::
+::
 
- $ dnf install libffi-devel redhat-rpm-config openssl-devel
+ # Get wheel from PyPI and signature from GitHub
+ python3 -m pip download --no-deps tuf==0.20.0
+ wget https://github.com/theupdateframework/python-tuf/releases/download/v0.20.0/tuf-0.20.0-py3-none-any.whl.asc
 
-OS X users can install these header libraries with the `Homebrew <https://brew.sh/>`_
-package manager, among other options::
+ # Get public key, compare fingerprint in MAINTAINERS.txt, and verify with gpg
+ gpg --recv-keys 89A2AD3C07D962E8
+ gpg --verify tuf-0.20.0-py3-none-any.whl.asc
 
- $ brew install python3
- $ brew install libffi
+ # Output:
+ # gpg: assuming signed data in 'tuf-0.20.0-py3-none-any.whl'
+ # gpg: Signature made Thu Dec 16 09:21:38 2021 CET
+ # gpg: using RSA key 8BA69B87D43BE294F23E812089A2AD3C07D962E8
+ # gpg: Good signature from "Lukas Pühringer <lukas.puehringer@nyu.edu>" [ultimate]
@@ -35,6 +35,8 @@
  'sphinx.ext.autosectionlabel'
 ]
 
+autosectionlabel_prefix_document = True
+
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
 

@@ -17,4 +17,4 @@ systems.
  api/api-reference
  INSTALLATION
  Usage examples <https://github.com/theupdateframework/python-tuf/tree/develop/examples>
- CONTRIBUTING
+ Contribute <CONTRIBUTING>