From 548dcfdc9b8fc9dea9d9761042aa5a7151654c11 Mon Sep 17 00:00:00 2001 From: Tommy Pauly Date: Thu, 22 Jun 2023 09:28:14 -0700 Subject: [PATCH 1/3] Clarify default structures Closes #382 --- draft-ietf-privacypass-auth-scheme.md | 50 ++++++++++++++++++--------- 1 file changed, 34 insertions(+), 16 deletions(-) diff --git a/draft-ietf-privacypass-auth-scheme.md b/draft-ietf-privacypass-auth-scheme.md index 38fbd648..dc58438c 100644 --- a/draft-ietf-privacypass-auth-scheme.md +++ b/draft-ietf-privacypass-auth-scheme.md @@ -154,7 +154,24 @@ be empty to allow fully cross-origin tokens, a single origin name that matches the origin itself, or a list of origin names containing the origin itself. -The TokenChallenge message has the following structure: +All token challenges MUST begin with a 2-octet integer that defines the +token type, in network byte order. This type indicates the issuance protocol +used to generate the token and determines the structure and semantics of the rest of +the structure. Values are registered in an IANA registry, {{token-types}}. Client MUST +ignore challenges with token_types they do not support. + +This document defines the default challenge structure that can be used across +token types, although future token types MAY extend or modify the structure +of the challenge; see {{token-types}} for the registry information +which establishes and defines the relationship between "token_type" and the +contents of the TokenChallenge message. + +Even when a given token type uses the default challenge, structure, +the requirements on the presence or interpretation of the fields can differ +across token types. For example, some token types might require that "origin_info" +is non-empty, while others allow it to be empty. + +The default TokenChallenge message has the following structure: ~~~ struct { @@ -167,13 +184,8 @@ struct { The structure fields are defined as follows: -- "token_type" is a 2-octet integer, in network byte order. This type indicates -the issuance protocol used to generate the token. Values are registered -in an IANA registry, {{token-types}}. Challenges with unsupported token_type -values MUST be ignored. This value determines the structure and semantics of -the rest of the structure; see {{token-types}} for the registry information -which establishes and defines the relationship between "token_type" and the -contents of the TokenChallenge message. +- "token_type" is a 2-octet integer, in network byte order, as described +above. - "issuer_name" is a string containing the name of the issuer. This is a hostname that is used to identify the issuer that is allowed to issue @@ -238,8 +250,8 @@ WWW-Authenticate: Upon receipt of this challenge, a client validates the TokenChallenge before responding to it. Validation requirements are as follows: -- The TokenChallenge structure is well-formed; -- The token_type is recognized and supported by the client; and +- The token_type is recognized and supported by the client; +- The TokenChallenge structure is well-formed; and - If the origin_info field is non-empty, the name of the origin that issued the authentication challenge is included in the list of origin names. @@ -332,7 +344,16 @@ original context could allow the origin to recognize a client. The output of the issuance protocol is a token that corresponds to the origin's challenge (see {{challenge}}). A token is a structure that begins with a two-octet field that indicates a token type, which MUST match the token_type in -the TokenChallenge structure. +the TokenChallenge structure. This value determines the structure and semantics +of the rest of token structure. + +This document defines the default token structure that can be used across +token types, although future token types MAY extend or modify the structure +of the token; see {{token-types}} for the registry information which +establishes and defines the relationship between "token_type" and the contents +of the Token structure. + +The default Token message has the following structure: ~~~ struct { @@ -346,11 +367,8 @@ struct { The structure fields are defined as follows: -- "token_type" is a 2-octet integer, in network byte order. This value must -match the value in the challenge ({{challenge}}). This value determines the -structure and semantics of the rest of the structure; see {{token-types}} for -the registry information which establishes and defines the relationship between -"token_type" and the contents of the Token structure. +- "token_type" is a 2-octet integer, in network byte order, as described +above. - "nonce" is a 32-octet value containing a client-generated random nonce. From b7a5ec4f63880a14b93e4bbc22b542de248bee2b Mon Sep 17 00:00:00 2001 From: Tommy Pauly Date: Thu, 22 Jun 2023 09:46:24 -0700 Subject: [PATCH 2/3] Update draft-ietf-privacypass-auth-scheme.md --- draft-ietf-privacypass-auth-scheme.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/draft-ietf-privacypass-auth-scheme.md b/draft-ietf-privacypass-auth-scheme.md index dc58438c..b269daa9 100644 --- a/draft-ietf-privacypass-auth-scheme.md +++ b/draft-ietf-privacypass-auth-scheme.md @@ -192,16 +192,16 @@ hostname that is used to identify the issuer that is allowed to issue tokens that can be redeemed by this origin. The string is prefixed with a 2-octet integer indicating the length, in network byte order. -- "redemption_context" is an optional field. If present, it allows the origin -to require that clients fetch tokens bound to a specific context, as opposed -to reusing tokens that were fetched for other contexts. See +- "redemption_context" is an optionally empty field. If non-empty, it allows +the origin to require that clients fetch tokens bound to a specific context, as +opposed to reusing tokens that were fetched for other contexts. See {{context-construction}} for example contexts that might be useful in practice. When present, this value is a 32-byte context generated by the origin. Valid lengths for this field are either 0 or 32 bytes. The field is prefixed with a single octet indicating the length. Challenges with redemption_context values of invalid lengths MUST be ignored. -- "origin_info" is an optional string containing one or more origin names, +- "origin_info" is an optionally empty string containing one or more origin names, which allows a token to be scoped to a specific set of origins. The string is prefixed with a 2-octet integer indicating the length, in network byte order. If empty, any non-origin-specific token can be redeemed. If the string From f8334e65fbb877c1feec25d0d55e00ba3d6d122d Mon Sep 17 00:00:00 2001 From: Tommy Pauly Date: Thu, 22 Jun 2023 13:59:12 -0700 Subject: [PATCH 3/3] Apply suggestions from code review --- draft-ietf-privacypass-auth-scheme.md | 20 +++++++++----------- 1 file changed, 9 insertions(+), 11 deletions(-) diff --git a/draft-ietf-privacypass-auth-scheme.md b/draft-ietf-privacypass-auth-scheme.md index b269daa9..8a301972 100644 --- a/draft-ietf-privacypass-auth-scheme.md +++ b/draft-ietf-privacypass-auth-scheme.md @@ -192,17 +192,15 @@ hostname that is used to identify the issuer that is allowed to issue tokens that can be redeemed by this origin. The string is prefixed with a 2-octet integer indicating the length, in network byte order. -- "redemption_context" is an optionally empty field. If non-empty, it allows -the origin to require that clients fetch tokens bound to a specific context, as -opposed to reusing tokens that were fetched for other contexts. See -{{context-construction}} for example contexts that might be useful in practice. -When present, this value is a 32-byte context generated by the origin. Valid -lengths for this field are either 0 or 32 bytes. The field is prefixed with a -single octet indicating the length. Challenges with redemption_context values -of invalid lengths MUST be ignored. - -- "origin_info" is an optionally empty string containing one or more origin names, -which allows a token to be scoped to a specific set of origins. The string +- "redemption_context" is a field that is either 0 or 32 bytes, prefixed with a single +octet indicating the length (either 0 or 32). If value is non-empty, it is a 32-byte value +generated by the origin that allows the origin to require that clients fetch tokens +bound to a specific context, as opposed to reusing tokens that were fetched for other +contexts. See {{context-construction}} for example contexts that might be useful in +practice. Challenges with redemption_context values of invalid lengths MUST be ignored. + +- "origin_info" is a string that is either empty, or contains one or more origin +names that allow a token to be scoped to a specific set of origins. The string is prefixed with a 2-octet integer indicating the length, in network byte order. If empty, any non-origin-specific token can be redeemed. If the string contains multiple origin names, they are delimited with commas "," without any