From c4251db635c8c6e0ffe58ed2c7589b2a6b92e365 Mon Sep 17 00:00:00 2001 From: Lukas Puehringer Date: Thu, 28 Nov 2019 12:31:01 +0100 Subject: [PATCH] PEP 458: add hash algorithm transition plan Add subsection to section "Managing Future Changes to the Update Process" that explains how to transition from an old (e.g. because it has become weak) to a new (e.g. stronger) hashing algorithm without disrupting client workflows. --- pep-0458.txt | 45 +++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 43 insertions(+), 2 deletions(-) diff --git a/pep-0458.txt b/pep-0458.txt index 85707d7628c..d83e18359ce 100644 --- a/pep-0458.txt +++ b/pep-0458.txt @@ -1171,8 +1171,8 @@ Managing Future Changes to the Update Process ============================================= If breaking changes are made to the update process, PyPI should implement these -changes without disrupting existing clients. For guidance on how to do so, -see the ongoing discussion in the TAP repository__. +changes without disrupting existing clients. For general guidance on how to do +so, see the ongoing discussion in the TAP repository__. __ https://github.com/theupdateframework/taps/pull/107 @@ -1183,6 +1183,47 @@ This PEP adds the ability for clients to use TUF metadata to improve the security of the update process. +Hash Algorithm Transition Plan +------------------------------ + +If the algorithm used to hash target and metadata files becomes vulnerable, it +SHOULD be replaced by a stronger hash algorithm. + +The TUF metadata format allows to list digests from different hash algorithms +alongside each other, together with an algorithm identifier, so that clients +can seamlessly switch between algorithms. + +However, once support for an old algorithm is turned off, clients that don't +support the new algorithm will only be able to install or update packages, +including the client itself, by disabling TUF verification. To allow clients to +transition without temporarily losing TUF security guarantees, we recommend +the following procedure. + +1. Implement new algorithm in Warehouse. + +2. Regenerate existing, unexpired TUF metadata to include hashes using both the + old and new algorithms. All new metadata going forward shall list both hash + algorithms. + Note, only TUF metadata that lists hash digests for target files or other + metadata needs to be renewed, that is *bin-n*, *snapshot* and *timestamp*. + Thus, only online keys are required to sign renewed metadata. + +3. Announce transition on high-visibility channels, such as `packaging on + Python Discourse`__ and the `PyPI changes mailing list`__. + +4. Give popular clients such as pip and bandersnatch the chance to adopt new + hash algorithm. + +5. Give end-users the chance to update clients. + +6. Get rough consensus to remove old hash algorithm from PyPI maintainers. + +7. Remove Warehouse support for old algorithm and only support new algorithm. + +__ https://discuss.python.org/c/packaging +__ https://mail.python.org/mailman3/lists/pypi-announce.python.org/ + + Appendix A: Repository Attacks Prevented by TUF ===============================================