PEP 458: add hash algorithm transition plan (#1253)

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

@@ -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,
+changes without disrupting existing clients. For general guidance on how to do
-see the ongoing discussion in the TAP repository__.
+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
 ===============================================