diff --git a/pep-0458.txt b/pep-0458.txt index fc83adcf2..8bddc03f3 100644 --- a/pep-0458.txt +++ b/pep-0458.txt @@ -1219,8 +1219,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 @@ -1231,6 +1231,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 ===============================================