prop289: Rewrite the Deployment Plan section

Split it into subsection for clarity. Add a new subsection describing the
addition of a new protover value.

This patch removes a paragraph that states the obvious with "We'll need to
do a bunch of testing". It is nice but also huge part of our development
work flow so no need for it in the proposal.

Signed-off-by: David Goulet <dgoulet@torproject.org>

1 files changed, 111 insertions, 18 deletions

diff --git a/proposals/289-authenticated-sendmes.txt b/proposals/289-authenticated-sendmes.txt
index 07258ef..df5226b 100644
--- a/proposals/289-authenticated-sendmes.txt
+++ b/proposals/289-authenticated-sendmes.txt
@@ -302,21 +302,61 @@ Status: Open
 
 4. Deployment Plan
 
-   In phase one, both sides begin remembering their expected digests,
-   and they learn how to parse sendme payloads. When they receive a
-   sendme with payload version 1, they verify its digest and tear down
-   the circuit if it's wrong. But they continue to send and accept
-   payload version 0 sendmes.
+   This section describes how we will be able to deploy this new mechanism on
+   the network.
 
-   In phase two, we flip a switch in the consensus, and everybody starts
-   sending payload version 1 sendmes. Payload version 0 sendmes are still
-   accepted. The newly proposed consensus parameter to achieve this is:
+   Alas, this deployment plan leaves a pretty large window until relays are
+   protected from attack. It's not all bad news though, since we could flip
+   the switches earlier than intended if we encounter a network-wide attack.
+
+   There are 5 phases to this plan and detailed in the subsections.
+
+4.1. Phase One - Remembering Digests
+
+   Both sides begin remembering their expected digests, and they learn how to
+   parse sendme version 1 payloads. When they receive a version 1 SENDME, they
+   verify its digest and tear down the circuit if it's wrong. But they
+   continue to send and accept payload version 0 sendmes.
+
+4.2. Phase Two - Sending Version 1
+
+   We flip a switch in the consensus, and everybody starts sending payload
+   version 1 sendmes. Payload version 0 sendmes are still accepted. The newly
+   proposed consensus parameter to achieve this is:
 
       "sendme_emit_min_version" - Minimum SENDME version that can be sent.
 
-   In phase three, we flip a different switch in the consensus, and
-   everybody starts refusing payload version 0 sendmes. The newly proposed
-   consensus parameter to achieve this is:
+4.3. Phase Three - Protover
+
+   On phase four (section 4.4), the new consensus parameter that tells us
+   which minimum version to accept, once flipped to version 1, has the
+   consequence of making every tor not supporting that version to fail to
+   operate on the network. It goes as far as unable to download a consensus.
+
+   It is essentially a "false-kill" switch because tor will still run but will
+   simply not work. It will retry over and over to download a consensus. In
+   order to help us transition before only accepting v1 on the network, a new
+   protover value is proposed (see section 9 of tor-spec.txt for protover
+   details).
+
+   Tor clients and relays that don't support this protover version from the
+   consensus "required-client-protocols" or "required-relay-protocols" lines
+   will exit and thus not try to join the network. Here is the proposed value:
+
+     "FlowCtrl"
+
+     Describes the flow control protocol at the circuit and stream level. If
+     there is no FlowCtrl protocol version, tor supports the unauthenticated
+     flow control features from its supported Relay protocols.
+
+       "1" -- supports authenticated circuit level SENDMEs as of proposal
+              289 in Tor 0.4.1.1-alpha.
+
+4.4. Phase Four - Accepting Version 1
+
+   We flip a different switch in the consensus, and everybody starts refusing
+   payload version 0 sendmes. The newly proposed consensus parameter to
+   achieve this is:
 
       "sendme_accept_min_version" - Minimum SENDME version that is accepted.
 
@@ -324,14 +364,66 @@ Status: Open
    otherwise we'd have a race where relays learn about the update before
    clients know to start the new behavior.)
 
-   We'll want to do a bunch of testing in chutney before flipping the
-   switches in the real network: I've long suspected we still have bugs
-   in our sendme timing, and this proposal might expose some of them.
+   Phase three will shutdown every clients that understand protover. However,
+   one important case remains which is when a client not supporting verison 1
+   boots up for the first time (no consensus).
+
+   It won't be able to download a consensus and thus know that it can't join
+   the network making it re-try over and over again. To avoid that, we propose
+   to still allow v0 SENDMEs on one-hop directory circuits meaning the new
+   parameter above affects everything except these specific circuits.
+
+   It will allow us to extend the period of time between Phase Four and too
+   old clients to bootstrap and fail properly. The last phase will then turn
+   this behavior off and we will be done once and for all with version 0.
+
+4.5. Phase Five - Turning Off v0
+
+   The last consensus switch to flip is the one refusing SENDME v0 on one-hop
+   directory circuit as described in previous phase.
+
+   The newly proposed consensus parameter to achieve this is:
+
+      "sendme_onehop_dir_min_version" - Minimum SENDME version that is
+                                        accepted on one-hop directory circuits.
+
+   After this phase, any tor still not supporting v0 will retry over and over
+   again to bootstrap. We can't avoid that but at least we can give enough
+   time to minimize the amount of old clients unable to boostrap with the
+   proposed timeline below.
+
+4.6. Timeline
+
+   The proposed timeline for the deployment phases:
+
+      Phase 1 and 2:
+
+         Once this proposal is merged into tor (expected: 0.4.1.1-alpha).
+
+         Those two phases will start roughly at the same time. The reason we
+         can do that is because SENDME payloads are ignored for version 0 thus
+         sending v1 right now will not affect Tor current behavior.
+
+      Phase 3:
+
+         This phase will effectively exit() all tor not supporting
+         "FlowCtrl=1". The earliest date we can do that is when all versions
+         not supporting v1 are EOL.
+
+         According to our release schedule[4], this can happen when our latest
+         LTS (0.3.5) goes EOL that is on Feb 1st, 2022.
+
+      Phase 4:
+
+         We recommend to pass at least one version after Phase 3 so we can
+         take the time to see the effect that it had on the network.
+         Considering 6 months release time frame we expect to do this phase
+         around July 2022.
+
+      Phase 5:
 
-   Alas, this deployment plan leaves a pretty large window until relays
-   are protected from attack. It's not all bad news though, since we
-   could flip the switches earlier than intended if we encounter a
-   network-wide attack.
+         Depends on how Phase 4 goes. It could be we'll do that very quickly
+         or not depending on our users and also Tor situation/health in 2022.
 
 5. Security Discussion
 
@@ -420,6 +512,7 @@ Status: Open
    [1] https://www.freehaven.net/anonbib/#sniper14
    [2] https://www.freehaven.net/anonbib/#torta05
    [3] https://www.freehaven.net/anonbib/#congestion-longpaths
+   [4] https://trac.torproject.org/projects/tor/wiki/org/teams/NetworkTeam/CoreTorReleases
 
 8. Acknowledgements