From 37e70de190c9d223b4a75c113c7cf0e4ca4a9231 Mon Sep 17 00:00:00 2001 From: Lukas Puehringer Date: Fri, 14 Jan 2022 12:24:11 +0100 Subject: [PATCH] PEP 458: update references to python-tuf repo In preparation for the 1.0.0** release of the TUF reference implementation `python-tuf` documentation referenced in this PEP is being moved. This patch updates the corresponding links in the PEP. ** See https://github.com/theupdateframework/python-tuf/blob/059bfda391893a7e502ed3da5a185ab174e977dc/docs/1.0.0-ANNOUNCEMENT.md More specifically, the following link changes are performed: - METADATA.md to: metadata format section in TUF spec Note: alternatively this could link to the new location of METADATA.md (see theupdateframework/python-tuf#1769), but the spec seems like a better resource - TUTORIAL.md#repo-management to: new metadata API doc on readthedocs and new repo example/tutorial - TUTORIAL.md#lazy-bin-walk to: new hashed bin delegation example/tutorial - client implementation to: new client doc on readthedocs Signed-off-by: Lukas Puehringer --- pep-0458.txt | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/pep-0458.txt b/pep-0458.txt index 6e6a274f9a1..e89f7b1c824 100644 --- a/pep-0458.txt +++ b/pep-0458.txt @@ -85,8 +85,7 @@ to install or update projects from PyPI with TUF metadata. Package managers interested in adopting TUF on the client side may consult its `library documentation`__, which was created for this purpose. -__ https://github.com/theupdateframework/tuf/tree/v0.11.1/tuf/client#updaterpy - +__ https://theupdateframework.readthedocs.io/en/stable/api/tuf.ngclient.html Non-goals ========= @@ -373,11 +372,11 @@ from PyPI. TUF downloads them and checks them against the TUF metadata that it also downloads from the repository. If the downloaded target files are trustworthy, TUF then hands them over to the package manager. -The `Metadata`__ document provides information about each type of required -metadata and its expected content. The next section covers the different -kinds of metadata RECOMMENDED for PyPI. +The `Document formats`__ section of the TUF specification provides information +about each type of required metadata and its expected content. The next +section covers the different kinds of metadata RECOMMENDED for PyPI. -__ https://github.com/theupdateframework/tuf/blob/v0.11.1/docs/METADATA.md +__ https://theupdateframework.github.io/specification/latest/#document-formats In addition, all target files SHOULD be available on disk at least two times. Once under their original filename, to provide backwards compatibility, and @@ -509,11 +508,12 @@ that PyPI uses to produce snapshots that can safely coexist and be deleted independent of other snapshots [18]_. Every year, PyPI administrators SHOULD sign for *root* and *targets* role keys. -Automation will continuously sign for a timestamped snapshot of all projects. -A `repository management`__ tool is available that can sign metadata files, -generate cryptographic keys, and manage a TUF repository. +Automation will continuously sign for a timestamped snapshot of all projects. A +repository `Metadata API`__ is available that can be used to `manage a TUF +repository`__. -__ https://github.com/theupdateframework/tuf/blob/v0.11.1/docs/TUTORIAL.md#how-to-create-and-modify-a-tuf-repository +__ https://theupdateframework.readthedocs.io/en/stable/api/tuf.api.html +__ https://github.com/theupdateframework/python-tuf/blob/v0.20.0/examples/repo_example/basic_repo.py In standard operation, the *bin-n* metadata will be updated and signed as new distributions are uploaded to PyPI. However, there will also need to be a @@ -611,14 +611,14 @@ grow correspondingly. For example, consider the *bins* role. In August 2013, it was found that the size of the *bins* metadata was about 42MB if the *bins* role itself signed for about 220K PyPI targets (which are simple indices and distributions). This PEP does not delve into the details, but TUF features a -so-called "`lazy bin walk`__" scheme that splits a large targets metadata file +so-called `"hashed bin delegation"`__ scheme that splits a large targets metadata file into many small ones. This allows a TUF client updater to intelligently download only a small number of TUF metadata files in order to update any project signed for by the *bins* role. For example, applying this scheme to the previous repository resulted in pip downloading between 1.3KB and 111KB to install or upgrade a PyPI project via TUF. -__ https://github.com/theupdateframework/tuf/blob/v0.11.1/docs/TUTORIAL.md#delegate-to-hashed-bins +__ https://github.com/theupdateframework/python-tuf/blob/v0.20.0/examples/repo_example/hashed_bin_delegation.py Based on our findings as of the time this document was updated for implementation (Nov 7 2019), summarized in Tables 2-3, PyPI SHOULD