|
1 | 1 | Installation |
2 | 2 | ============ |
3 | 3 |
|
4 | | -*pip* is the recommended installer for installing and managing Python packages. |
5 | | -The project can be installed either locally or from the Python Package Index. |
6 | | -All `TUF releases |
7 | | -<https://github.com/theupdateframework/python-tuf/releases>`_ are cryptographically |
8 | | -signed, with GPG signatures available on both GitHub and `PyPI |
9 | | -<https://pypi.python.org/pypi/tuf/>`_. PGP key information for our maintainers |
10 | | -is available on our `website |
11 | | -<https://theupdateframework.github.io/people.html>`_, on major keyservers, |
12 | | -and on the `maintainers page |
13 | | -<https://github.com/theupdateframework/python-tuf/blob/develop/docs/MAINTAINERS.txt>`_. |
| 4 | +All versions of ``python-tuf`` can be installed from |
| 5 | +`PyPI <https://pypi.org/project/tuf/>`_ with |
| 6 | +`pip <https://pip.pypa.io/en/stable/>`_. |
14 | 7 |
|
| 8 | +:: |
15 | 9 |
|
16 | | -Release Verification |
17 | | --------------------- |
| 10 | + python3 -m pip install tuf |
18 | 11 |
|
19 | | -Assuming you trust `the maintainer's PGP key |
20 | | -<https://github.com/theupdateframework/python-tuf/blob/develop/docs/MAINTAINERS.txt>`_, |
21 | | -the detached ASC signature can be downloaded and verified. For example:: |
| 12 | +By default tuf is installed as pure python package with limited cryptographic |
| 13 | +abilities. See `Install with full cryptographic abilities`_ for more options. |
22 | 14 |
|
23 | | - $ gpg --verify securesystemslib-0.10.8.tar.gz.asc |
24 | | - gpg: assuming signed data in 'securesystemslib-0.10.8.tar.gz' |
25 | | - gpg: Signature made Wed Nov 8 15:21:47 2017 EST |
26 | | - gpg: using RSA key 3E87BB339378BC7B3DD0E5B25DEE9B97B0E2289A |
27 | | - gpg: Good signature from "Vladimir Diaz (Vlad) <[email protected]>" [ultimate] |
28 | 15 |
|
| 16 | +Install with full cryptographic abilities |
| 17 | +----------------------------------------- |
29 | 18 |
|
| 19 | +Default installation supports signature verification only, using a pure Python |
| 20 | +*ed25519* implementation. While this allows to operate a *basic client* on |
| 21 | +almost any computing device, you will need additional cryptographic abilities |
| 22 | +for *repository* code, i.e. key and signature generation, additional |
| 23 | +algorithms, and more performant backends. Opt-in is available via |
| 24 | +``securesystemslib``. |
30 | 25 |
|
31 | | -Simple Installation |
32 | | -------------------- |
| 26 | +.. note:: |
33 | 27 |
|
34 | | -If you are only using ed25519-based cryptography, you can employ a pure-Python |
35 | | -installation, done simply with one of the following commands: |
| 28 | + Please consult with underlying crypto backend installation docs -- |
| 29 | + `cryptography <https://cryptography.io/en/latest/installation/>`_ and |
| 30 | + `pynacl <https://pynacl.readthedocs.io/en/latest/install/>`_ -- |
| 31 | + for possible system dependencies. |
36 | 32 |
|
37 | | -Installing from Python Package Index (https://pypi.python.org/pypi). |
38 | | -(Note: Please use "python3 -m pip install --no-use-wheel tuf" if your version |
39 | | -of pip <= 1.5.6):: |
| 33 | +:: |
40 | 34 |
|
41 | | - $ python3 -m pip install tuf |
| 35 | + python3 -m pip securesystemslib[crypto,pynacl] tuf |
42 | 36 |
|
43 | 37 |
|
44 | | -**Alternatively**, if you wish to install from a GitHub release you've already |
45 | | -downloaded, or a package you obtained in another way, you can instead: |
46 | | - |
47 | | -Install from a local source archive:: |
48 | | - |
49 | | - $ python3 -m pip install <path to archive> |
50 | | - |
51 | | -Or install from the root directory of the unpacked archive:: |
52 | | - |
53 | | - $ python3 -m pip install . |
54 | | - |
55 | | - |
56 | | - |
57 | | -Install with More Cryptographic Flexibility |
58 | | -------------------------------------------- |
| 38 | +Install for development |
| 39 | +----------------------- |
59 | 40 |
|
60 | | -By default, C extensions are not installed and only Ed25519 signatures can |
61 | | -be verified, in pure Python. To fully support RSA, Ed25519, ECDSA, and |
62 | | -other crypto, you must install the extra dependencies declared by |
63 | | -securesystemslib. **Note**: that may require non-Python dependencies, so if |
64 | | -you encounter an error attempting this pip command, see |
65 | | -`more instructions below <#non-python-dependencies>`_). :: |
| 41 | +To install tuf in editable mode together with development dependencies, |
| 42 | +`clone <https://docs.github.com/en/repositories/creating-and-managing-repositories/cloning-a-repository>`_ the |
| 43 | +`python-tuf repository <https://github.com/theupdateframework/python-tuf>`_ |
| 44 | +from GitHub, change into the project root directory, and install with pip |
| 45 | +(using `venv <https://docs.python.org/3/library/venv.html>`_ is recommended). |
66 | 46 |
|
67 | | - $ python3 -m pip install securesystemslib[crypto,pynacl] tuf |
| 47 | +.. note:: |
68 | 48 |
|
| 49 | + Development installation will `Install with full cryptographic abilities`_. |
| 50 | + Please check above for possible system dependencies. |
69 | 51 |
|
| 52 | +:: |
70 | 53 |
|
71 | | -Non-Python Dependencies |
72 | | ------------------------ |
| 54 | + python3 -m pip install -r requirements-dev.txt |
73 | 55 |
|
74 | | -If you encounter errors during installation, you may be missing |
75 | | -certain system libraries. |
76 | 56 |
|
77 | | -For example, PyNaCl and Cryptography -- two libraries used in the full |
78 | | -installation to support certain cryptographic functions -- may require FFI |
79 | | -(Foreign Function Interface) development header files. |
| 57 | +Verify release signatures |
| 58 | +------------------------- |
80 | 59 |
|
81 | | -Debian-based distributions can install the necessary header libraries with apt:: |
| 60 | +Releases on PyPI are signed with a maintainer key using |
| 61 | +`gpg <https://gnupg.org/>`_ (see |
| 62 | +`MAINTAINERS.txt <https://github.com/theupdateframework/python-tuf/blob/develop/docs/MAINTAINERS.txt>`_ |
| 63 | +for key fingerprints). Signatures can be downloaded from the |
| 64 | +`GitHub release <https://github.com/theupdateframework/python-tuf/releases>`_ |
| 65 | +page (look for *\*.asc* files in the *Assets* section). |
82 | 66 |
|
83 | | - $ apt-get install build-essential libssl-dev libffi-dev python-dev |
| 67 | +Below code shows how to verify the signature of a |
| 68 | +`built <https://packaging.python.org/en/latest/glossary/#term-Built-Distribution>`_ distribution, |
| 69 | +signed by the maintainer *Lukas Pühringer*. It works |
| 70 | +alike for `source <https://packaging.python.org/en/latest/glossary/#term-Source-Distribution-or-sdist>`_ distributions. |
84 | 71 |
|
85 | | -Fedora-based distributions can instead install these libraries with dnf:: |
| 72 | +:: |
86 | 73 |
|
87 | | - $ dnf install libffi-devel redhat-rpm-config openssl-devel |
| 74 | + # Get wheel from PyPI and signature from GitHub |
| 75 | + python3 -m pip download --no-deps tuf==0.20.0 |
| 76 | + wget https://github.com/theupdateframework/python-tuf/releases/download/v0.20.0/tuf-0.20.0-py3-none-any.whl.asc |
88 | 77 |
|
89 | | -OS X users can install these header libraries with the `Homebrew <https://brew.sh/>`_ |
90 | | -package manager, among other options:: |
| 78 | + # Get public key, compare fingerprint in MAINTAINERS.txt, and verify with gpg |
| 79 | + gpg --recv-keys 89A2AD3C07D962E8 |
| 80 | + gpg --verify tuf-0.20.0-py3-none-any.whl.asc |
91 | 81 |
|
92 | | - $ brew install python3 |
93 | | - $ brew install libffi |
| 82 | + # Output: |
| 83 | + # gpg: assuming signed data in 'tuf-0.20.0-py3-none-any.whl' |
| 84 | + # gpg: Signature made Thu Dec 16 09:21:38 2021 CET |
| 85 | + # gpg: using RSA key 8BA69B87D43BE294F23E812089A2AD3C07D962E8 |
| 86 | + # gpg: Good signature from "Lukas Pühringer <[email protected]>" [ultimate] |
0 commit comments