Add hash algorithm transition plan

Add subsection to section "Managing Future Changes to the Update
Process" that explains how to transition from an old (weak) to a
new (stronger) hashing algorithm without disrupting client
workflows.

Author: lukpueh

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,45 @@ 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. Re-generate existing TUF metadata to include both old and new algorithm
+   hashes, and include both old and new algorithm hashes in new metadata in
+   Warehouse.
+   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.
+
+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.
+
+
+
+
 Appendix A: Repository Attacks Prevented by TUF
 ===============================================