Merge pull request #424 from ietf-wg-privacypass/caw/specify-verifica…

…tion

Clearly specify token verification steps

draft-ietf-privacypass-auth-scheme.md

@@ -384,13 +384,16 @@ done in a future specification.
 key. The value of this field is defined by the token_type and corresponding
 issuance protocol.
 
-- "authenticator" is a Nk-octet authenticator that covers the preceding fields
-in the token. The value of this field is defined by the token_type and
-corresponding issuance protocol. The value of constant Nk depends on
-token_type, as defined in {{token-types}}.
+- "authenticator" is a Nk-octet authenticator that is cryptographically bound
+to the preceding fields in the token; see {{verification}} for more information
+about how this field is used in verifying a token. The token_type and corresponding
+issuance protocol determine the value of the authenticator field and how it is computed.
+The value of constant Nk depends on token_type, as defined in {{token-types}}.
 
 The authenticator value in the Token structure is computed over the token_type,
-nonce, challenge_digest, and token_key_id fields.
+nonce, challenge_digest, and token_key_id fields. A token is considered a valid
+if token verification using succeeds; see {{verification}} for details about
+verifying the token and its authenticator value.
 
 When used for client authorization, the "PrivateToken" authentication
 scheme defines one parameter, "token", which contains the base64url-encoded
@@ -408,22 +411,45 @@ the Authorization header field as follows:
 Authorization: PrivateToken token="abc..."
 ~~~
 
-For token types that support public verifiability, origins verify the token
-authenticator using the public key of the issuer, and validate that the signed
-message matches the concatenation of the client nonce and the hash of a
-valid TokenChallenge. For context-bound tokens, origins store or reconstruct
-the contexts of previous TokenChallenge structures in order to validate the
-token. A TokenChallenge MAY be bound to a specific TLS session with a client,
-but origins can also accept tokens for valid challenges in new sessions.
-Origins SHOULD implement some form of double-spend prevention that prevents
-a token with the same nonce from being redeemed twice. This prevents clients
-from "replaying" tokens for previous challenges. For context-bound tokens,
-this double-spend prevention can require no state or minimal state, since
-the context can be used to verify token uniqueness.
+For context-bound tokens, origins store or reconstruct the contexts of previous
+TokenChallenge structures in order to validate the token. A TokenChallenge can
+be bound to a specific TLS session with a client, but origins can also accept
+tokens for valid challenges in new sessions. Origins SHOULD implement some form
+of double-spend prevention that prevents a token with the same nonce from being
+redeemed twice. Double-spend prevention ensures that clients cannot replay tokens
+for previous challenges. For context-bound tokens, this double-spend prevention
+can require no state or minimal state, since the context can be used to verify
+token uniqueness.
 
 If a client is unable to fetch a token, it MUST react to the challenge as
 if it could not produce a valid Authorization response.
 
+### Token Verification {#verification}
+
+A token consists of some input cryptographically bound to an authenticator
+value, such as a digital signature. Verifying a token consists of checking that
+the authenticator value is correct.
+
+The authenticator value is as computed when running and finalizing the issuance
+protocol corresponding to the token type with the following value as the input:
+
+~~~
+struct {
+    uint16_t token_type;
+    uint8_t nonce[32];
+    uint8_t challenge_digest[32];
+    uint8_t token_key_id[Nid];
+} AuthenticatorInput;
+~~~
+
+The value of these fields are as described in {{redemption}}. The cryptographic
+verification check depends on the token type; see {{Section 5.4 of ISSUANCE}}
+and {{Section 6.4 of ISSUANCE}} for verification instructions for the issuance
+protocols described in {{ISSUANCE}}. As such, the security properties of the
+token, e.g., the probability that one can forge an authenticator value without
+invoking the issuance protocol, depend on the cryptographic algorithm used by
+the issuance protocol as determined by the token type.
+
 # User Interaction {#interaction}
 
 When used in contexts like websites, origins that challenge clients for