1 files changed, 103 insertions, 0 deletions
diff --git a/spec/rend-spec/revision-counter-mgt.md b/spec/rend-spec/revision-counter-mgt.md
new file mode 100644
index 0000000..f5c9a9c
--- /dev/null
+++ b/spec/rend-spec/revision-counter-mgt.md
@@ -0,0 +1,103 @@
+<a id="rend-spec-v3.txt-F"></a>
+
+# Appendix F: Two methods for managing revision counters
+
+Implementations MAY generate revision counters in any way they please,
+so long as they are monotonically increasing over the lifetime of each
+blinded public key.  But to avoid fingerprinting, implementors SHOULD
+choose a strategy also used by other Tor implementations. Here we
+describe two, and additionally list some strategies that implementors
+should NOT use.
+
+## F.1. Increment-on-generation {#increment-on-generation}
+
+This is the simplest strategy, and the one used by Tor through at
+least version 0.3.4.0-alpha.
+
+Whenever using a new blinded key, the service records the
+highest revision counter it has used with that key.  When generating
+a descriptor, the service uses the smallest non-negative number
+higher than any number it has already used.
+
+In other words, the revision counters under this system start fresh
+with each blinded key as 0, 1, 2, 3, and so on.
+
+## F.2. Encrypted time in period {#encrypted-time}
+
+This scheme is what we recommend for situations when multiple
+service instances need to
+[coordinate their revision counters](#use-case),
+without an actual coordination mechanism.
+
+Let T be the number of seconds that have elapsed
+since the start time of the SRV protocol run
+that corresponds to this descriptor,
+plus 1.  (T must be at least 1.)
+
+Let S be a per-time-period secret that all the service providers share.
+(C tor and arti use `S = KS_hs_blind_id`;
+when `KS_hs_blind_id` is not available,
+implementations may use `S = KS_hs_desc_sign`.)
+
+Let K be an AES-256 key, generated as
+```
+K = H("rev-counter-generation" | S)
+```
+
+Use `K`, and AES in counter mode with IV=0, to generate a stream of
+`T * 2` bytes.  Consider these bytes as a sequence of T 16-bit
+little-endian words.  Add these words.
+
+Let the sum of these words, plus T, be the revision counter.
+
+> (We include T in the sum so that every increment in T adds at least
+> one to the output.)
+
+Cryptowiki attributes roughly this scheme to G. Bebek in:
+
+> G. Bebek. Anti-tamper database research: Inference control
+> techniques. Technical Report EECS 433 Final Report, Case
+> Western Reserve University, November 2002.
+
+Although we believe it is suitable for use in this application, it
+is not a perfect order-preserving encryption algorithm (and all
+order-preserving encryption has weaknesses).  Please think twice
+before using it for anything else.
+
+(This scheme can be optimized pretty easily by caching the encryption of
+`X*1`, `X*2`, `X*3`, etc for some well chosen `X`.)
+
+For a slow reference implementation
+that can generate test vectors,
+see `src/test/ope_ref.py` in the
+Tor source repository.
+
+> <h6 id="use-case">Note:</h6>
+>
+> Some onion service operators have historically relied upon
+> the behavior of this OPE scheme to provide
+> a kind of ersatz load-balancing:
+> they run multiple onion services,
+> each with the the same `KP_hs_id`.
+> The onion services choose different introduction points,
+> and race each other to publish their HSDescs.
+>
+> It's probably better to use
+> [Onionbalance](https://onionbalance.readthedocs.io/en/latest/)
+> or a similar tool for this purpose.
+> Nonetheless, onion services implemenentations
+> MAY choose to implement this particular OPE scheme exactly
+> in order to provide interoperability with C tor
+> in this use case.
+
+## F.X. Some revision-counter strategies to avoid {#avoid}
+
+Though it might be tempting, implementations SHOULD NOT use the
+current time or the current time within the period directly as their
+revision counter -- doing so leaks their view of the current time,
+which can be used to link the onion service to other services run on
+the same host.
+
+Similarly, implementations SHOULD NOT let the revision counter
+increase forever without resetting it -- doing so links the service
+across changes in the blinded public key.