Merge pull request #331 from martinthomson/fixups

Fixups

.gitignore

@@ -4,13 +4,15 @@
 *.swp
 *.txt
 *.upload
+*.xml
 *~
 .DS_Store
 .refcache
 .targets.mk
 /*-[0-9][0-9].xml
 /node_modules/
 /package-lock.json
+/versioned/
 issues.json
 lib
 pulls.json

draft-ietf-privacypass-architecture.md

@@ -34,7 +34,6 @@ author:
     email: caw@heapingbits.net
 
 normative:
-  RFC2119:
 
 informative:
   PrivacyPassExtension:
@@ -46,7 +45,7 @@ informative:
     author:
       ins: N. Sullivan
       org: Cloudflare
-  Dingledine2004:
+  DMS2004:
     title: "Tor: The Second-Generation Onion Router"
     date: 2004-08
     target: "https://svn.torproject.org/svn/projects/design-paper/tor-design.html"
@@ -99,11 +98,11 @@ authentication mechanisms. Typical approaches for authorizing clients,
 such as through the use of long-term cookies, are not privacy-friendly
 since they allow servers to track clients across sessions and interactions.
 Privacy Pass takes a different approach: instead of presenting linkable
-state carrying information to servers, e.g., a cookie indicating whether
+state-carrying information to servers, e.g., a cookie indicating whether
 or not the client is an authorized user or has completed some prior
 challenge, clients present unlinkable proofs that attest to this information.
 These proofs, or tokens, are private in the sense that a given token cannot
-be linked to the protocol instance in which that token was initially issued.
+be linked to the protocol interaction where that token was initially issued.
 
 At a high level, the Privacy Pass architecture consists of two protocols:
 redemption and issuance. The redemption protocol, described in
@@ -124,13 +123,20 @@ the security of all participating entities.
 
 {::boilerplate bcp14}
 
-The following terms are used throughout this document.
+The following terms are used throughout this document:
 
-- Client: An entity that seeks authorization to an Origin.
-- Origin: An entity that redeems tokens presented by Clients.
-- Issuer: An entity that issues tokens to Clients for properties
+Client:
+: An entity that seeks authorization to an Origin.
+
+Origin:
+: An entity that redeems tokens presented by Clients.
+
+Issuer:
+: An entity that issues tokens to Clients for properties
   attested to by the Attester.
-- Attester: An entity that attests to properties of Client for the
+
+Attester:
+: An entity that attests to properties of Client for the
   purposes of token issuance.
 
 # Architecture
@@ -152,7 +158,8 @@ challenge.
 
 2. If the Client already has a token available that satisfies the token
 challenge, e.g., because the Client has a cache of previously issued tokens,
-it can skip to step 6 and redeem its token. Otherwise, it invokes the issuance
+it can skip to [step 6](#step-redemption){: format="none"} and redeem its
+token. Otherwise, it invokes the issuance
 protocol to request a token from the designated Issuer.
 
 3. The first step in the issuance protocol is attestation. Specifically, the
@@ -180,33 +187,42 @@ The Origin validates that the token was generated by the expected Issuer
 and has not already been redeemed for the corresponding token challenge.
 If the Client does not have a token, perhaps because issuance failed, the
 client does not reply to the Origin's challenge with a new request.
+{: anchor="step-redemption"}
 
 ~~~ aasvg
-    Origin           Client         Attester     Issuer
-
-     Request <------
-
- TokenChallenge --->
-                      <--(Attestation)-->
-                      TokenRequest -------------->
-                              <-------------- TokenResponse
- Request + Token <--
++--------+            +--------+         +----------+ +--------+
+| Origin |            | Client |         | Attester | | Issuer |
++---+----+            +---+----+         +----+-----+ +---+----+
+    |                     |                   |           |
+    |<----- Request ------+                   |           |
+    +-- TokenChallenge -->|                   |           |
+    |                     |<== Attestation ==>|           |
+    |                     |                   |           |
+    |                     +--------- TokenRequest ------->|
+    |                     |<-------- TokenResponse -------+
+    |<-- Request+Token ---+                   |           |
+    |                     |                   |           |
 ~~~
 {: #fig-overview title="Privacy pass redemption and issuance protocol interaction"}
 
 The end-to-end flow for Privacy Pass involves three different types of
 contexts:
 
-- Redemption context: The interactions and set of information shared
+Redemption context:
+: The interactions and set of information shared
 between the Client and Origin. This context includes all information
 associated with redemption, such as the timestamp of the event, Client
 visible information (including the IP address), and the Origin name.
-- Issuance context: The interactions and set of information shared
+
+Issuance context:
+: The interactions and set of information shared
 between the Client, Attester, and Issuer. This context includes all
 information associated with issuance, such as the timestamp of the event,
 any Client visible information (including the IP address), and the
 Origin name (if revealed during issuance).
-- Attestation context: The interactions and set of information shared between
+
+Attestation context:
+: The interactions and set of information shared between
 the Client and Attester only, for the purposes of attesting the vailidity of
 the Client. This context includes all information associated with attestation,
 such as the timestamp of the event and any Client visibile information,
@@ -223,24 +239,25 @@ redemption context is indistinguishable from any other Client that might use
 the same redemption context. The set of Clients that share the same redemption
 context is referred to as a redemption anonymity set.
 2. Issuer-Client unlinkability. This is similar to Origin-Client unlinkability
-in that a Client in an issuer context is indistinguishable from any other
-Client that might use the same issuer context. The set of Clients that share
+in that a Client in an issuance context is indistinguishable from any other
+Client that might use the same issuance context. The set of Clients that share
 the same redemption context is referred to as a redemption anonymity set.
 3. Attester-Origin unlinkability. This is similar to Origin-Client and
 Issuer-Client unlinkability. It means that given two attestation contexts,
 the Attester cannot determine if both contexts correspond to the same Origin
 or two different Origins. The set of Clients that share the same attestation
 context is referred to as an anonymity set.
 
-At a high level, these properties ensure that no single party amongst the
-Attester, Issuer, or Origin can link client identifying information to client
-activity, e.g., the origin being accessed.
+By ensuring that different contexts cannot be linked in this way, only the
+Client is able to correlate information that might be used to identify them with
+activity on the Origin.  The Attester, Issuer, and Origin only receive the
+information necessary to perform their respective functions.
 
 The manner in which Origin-Client, Issuer-Client, and Attester-Origin
 unlinkability are achieved depends on the deployment model, type of
 attestation, and issuance protocol details. For example, as discussed in
 {{deployment}}, failure to use a privacy-enhancing proxy system such as Tor
-{{Dingledine2004}} when interacting with Attesters, Issuers, or Origins allows
+{{DMS2004}} when interacting with Attesters, Issuers, or Origins allows
 the set of possible Clients to be partitioned by the Client's IP address, and
 can therefore lead to unlinkability violations. Similarly, malicious Origins
 may attempt to link two redemption contexts together by using Client-specific
@@ -299,7 +316,7 @@ including:
   example, an empty redemption context always allows tokens to be issued and
   redeemed non-interactively, whereas a fresh and random redemption context
   means that the redeemed token must be issued only after the client receives
-  the challenge. See Section 2.1.1 of {{AUTHSCHEME}} for more details.
+  the challenge. See {{Section 2.1.1 of AUTHSCHEME}} for more details.
 - Per-Origin or cross-Origin. Challenges can be constrained to the Origin for
   which the challenge originated (referred to as per-Origin tokens), or
   can be used across multiple Origins (referred to as cross-Origin tokens).
@@ -313,7 +330,7 @@ state to track redeemed tokens. For example, Origins that accept cross-Origin
 tokens across shared redemption contexts SHOULD track which tokens have been
 redeemed already in those redemption contexts, since these tokens can
 be issued and then spent multiple times in response to any such challenge.
-See Section 2.1.1 of {{AUTHSCHEME}} for discussion.
+See {{Section 2.1.1 of AUTHSCHEME}} for discussion.
 
 ## Issuance Protocol
 
@@ -453,15 +470,15 @@ Issuers maintain one or more configurations, including issuance key pairs, for
 use in the issuance protocol. Issuers can rotate these configurations as needed
 to mitigate risk of compromise; see {{rotation-and-consistency}} for more
 considerations around configuration rotation. The Issuer public key for each
-active configuraton is made available to Origins and Clients for use in the
+active configuration is made available to Origins and Clients for use in the
 issuance and redemption protocols.
 
 ### Issuance Metadata {#metadata}
 
 Certain instantiations of the issuance protocol may permit public or private
 metadata to be cryptographically bound to a token. As an example, one
 trivial way to include public metadata is to assign a unique Issuer
-public key for each value of metadata, such that N keys yields log2(N)
+public key for each value of metadata, such that N keys yields log<sub>2</sub>(N)
 bits of metadata. Metadata may be public or private.
 
 Public metadata is that which clients can observe as part of the token
@@ -497,7 +514,7 @@ and guidelines on how to deploy the protocol to minimize any privacy impacts.
 Any extension to the Privacy Pass protocol MUST adhere to the guidelines
 specified in {{issuer-role}} for managing Issuer public key data.
 
-# Deployment Considerations {#deployment}
+# Deployment Configurations {#deployment}
 
 The Origin, Attester, and Issuer portrayed in {{fig-overview}} can be
 instantiated and deployed in a number of ways. The deployment model directly