Selective incorporation of changes based on feedback received nearly …

…four months after the end of the second working group last call (thread at https://mailarchive.ietf.org/arch/msg/oauth/o9G6ibRuibzHQeoKHG7hLpU-CUM/)

draft-ietf-oauth-selective-disclosure-jwt.md

@@ -55,7 +55,7 @@ A popular application of JWS is JSON Web Token (JWT) [@!RFC7519], a format that
 An ID Token as defined in OpenID Connect [@?OpenID.Core], for example, is a JWT containing the user's claims created by the server for consumption by a relying party.
 In cases where the JWT is sent immediately from the server to the relying party, as in OpenID Connect, the server can select at the time of issuance which user claims to include in the JWT, minimizing the information shared with the relying party who validates the JWT.
 
-A new model is emerging that fully decouples the issuance of a JWT from its presentation.
+Another model is emerging that fully decouples the issuance of a JWT from its presentation.
 In this model, a JWT containing many claims is issued to an intermediate party, who holds the JWT (the Holder).
 The Holder can then present the JWT to different verifying parties (Verifiers), that each may only require a subset of the claims in the JWT.
 For example, the JWT may contain claims representing both an address and a birthdate.
@@ -79,7 +79,7 @@ An SD-JWT with a Key Binding JWT is called SD-JWT+KB in this specification.
 
 This specification defines two primary data formats:
 
-1. SD-JWT is a composite structure enabling selective disclosure of its contents. It comprises the following:
+1. SD-JWT is a composite structure, consisting of a JWS plus optional disclosures, enabling selective disclosure of portions of the JWS payload. It comprises the following:
   - A format for enabling selective disclosure in nested JSON data structures,
     supporting selectively disclosable object properties (name/value pairs) and array elements
   - A format for encoding the selectively disclosable data items
@@ -88,7 +88,7 @@ This specification defines two primary data formats:
   - An alternate format extending the JWS JSON Serialization, also allowing for
     transport of the Issuer-signed JSON data structure and disclosure data
 
-2. SD-JWT+KB is a composite structure enabling cryptographic key binding when presented to the Verifier. It comprises the following:
+2. SD-JWT+KB is a composite structure of an SD-JWT and a cryptographic key binding that can be presented to and verified by the Verifier. It comprises the following:
   - A mechanism for associating an SD-JWT with a key pair
   - A format for a Key Binding JWT (KB-JWT) that allows proof of possession of the private key of
     the associated key pair
@@ -110,7 +110,7 @@ Throughout the document the term "claims" refers generally to both
 object properties (name/value pairs) as well as array elements.
 
 Selective Disclosure:
-:  Process of a Holder disclosing to a Verifier a subset of claims contained in a JWT Claims Set issued by an Issuer.
+:  Process of a Holder disclosing to a Verifier a subset of claims contained in a JWT issued by an Issuer.
 
 Selectively Disclosable JWT (SD-JWT):
 :  A composite structure, consisting of an Issuer-signed JWT (JWS, [@!RFC7515]) and zero or more Disclosures, which
@@ -127,9 +127,8 @@ Key Binding:
 
 Key Binding JWT (KB-JWT):
 :  A Key Binding JWT is said to "be tied to" a particular SD-JWT when its payload
-  is signed using the key included in the SD-JWT payload, and also contains
-  a hash of the SD-JWT in its `sd_hash` claim. A JWT for proving Key Binding
-  as defined in (#kb-jwt).
+  is signed using the key included in the SD-JWT payload, and the KB-JWT contains
+  a hash of the SD-JWT in its `sd_hash` claim. Its format is defined in (#kb-jwt).
 
 Selectively Disclosable JWT with Key Binding (SD-JWT+KB):
 : A composite structure, comprising an SD-JWT and a Key Binding JWT tied to that SD-JWT.
@@ -235,7 +234,7 @@ An SD-JWT+KB is composed of
 The Issuer-signed JWT, Disclosures, and Key Binding JWT are explained in
 (#iss-signed-jwt), (#creating_disclosures), and (#kb-jwt) respectively.
 
-The serialized format for the SD-JWT is the concatenation of each part delineated with a single tilde ('~') character as follows:
+The compact serialized format for the SD-JWT is the concatenation of each part delineated with a single tilde ('~') character as follows:
 
 ```
 <Issuer-signed JWT>~<Disclosure 1>~<Disclosure 2>~...~<Disclosure N>~
@@ -387,9 +386,9 @@ For each claim that is an object property and that is to be made selectively dis
    2. The claim name, or key, as it would be used in a regular JWT payload. It MUST be a string and MUST NOT be `_sd`, `...`, or a claim name existing in the object as a non-selectively disclosable claim.
    3. The claim value, as it would be used in a regular JWT payload. The value MAY be of any type that is allowed in JSON, including numbers, strings, booleans, arrays, null, and objects.
  * JSON-encode the array, producing an UTF-8 string.
- * base64url-encode the byte representation of the UTF-8 string, producing a US-ASCII [@!RFC20] string. This string is the Disclosure.
+ * base64url-encode the byte representation of the UTF-8 string. This string is the Disclosure.
 
-The order is decided based on the readability considerations: salts would have a
+Note: The order was decided based on readability considerations: salts have a
 constant length within the SD-JWT, claim names would be around the same length
 all the time, and claim values would vary in size, potentially being large
 objects.
@@ -401,10 +400,10 @@ The array is created as follows:
 ["_26bc4LT-ac6q2KI6cBW5es", "family_name", "Möbius"]
 ```
 
-The resulting Disclosure would be: `WyJfMjZiYzRMVC1hYzZxMktJNmNCVzVlcyIsICJmYW1pbHlfbmFtZSIsICJNw7ZiaXVzIl0`
+The resulting Disclosure is: `WyJfMjZiYzRMVC1hYzZxMktJNmNCVzVlcyIsICJmYW1pbHlfbmFtZSIsICJNw7ZiaXVzIl0`
 
 Note that variations in whitespace, encoding of Unicode characters, ordering of object properties, etc., are allowed
-in the JSON representation and no canonicalization needs be performed before base64url-encoding.
+in the JSON representation and no canonicalization needs be performed before base64url-encoding because the digest is calculated over the base64url-encoded value itself.
 For example, the following strings are all valid and encode the
 same claim value "Möbius":
 
@@ -418,6 +417,8 @@ same claim value "Möbius":
 `WwoiXzI2YmM0TFQtYWM2cTJLSTZjQlc1ZXMiLAoiZmFtaWx5X25hbWUiLAoiT`\
 `cO2Yml1cyIKXQ`
 
+However, the digest is calculated over the respective base64url-encoded value itself, which effectively signs the variation chosen by the Issuer and makes it immutable in the context of the particular SD-JWT.
+
 See (#disclosure_format_considerations) for some further considerations on the Disclosure format approach.
 
 ### Disclosures for Array Elements {#disclosures_for_array_elements}
@@ -449,7 +450,7 @@ The resulting Disclosure would be: `WyJsa2x4RjVqTVlsR1RQVW92TU5JdkNBIiwgIkZSIl0`
 
 ### Hashing Disclosures {#hashing_disclosures}
 
-For embedding references to the Disclosures in the SD-JWT, each Disclosure is hashed using the hash algorithm specified in the `_sd_alg` claim described in (#hash_function_claim). The resulting digest is then included in the SD-JWT payload instead of the original claim value, as described next.
+For embedding references to the Disclosures in the SD-JWT, each Disclosure is hashed using the hash algorithm specified in the `_sd_alg` claim described in (#hash_function_claim), or SHA-256 if no algorithm is specified. The resulting digest is then included in the SD-JWT payload instead of the original claim value, as described next.
 
 The digest MUST be taken over the US-ASCII bytes of the base64url-encoded value that is the Disclosure. This follows the convention in JWS [@!RFC7515] and JWE [@RFC7516]. The bytes of the digest MUST then be base64url-encoded.
 
@@ -476,6 +477,8 @@ For selectively disclosable claims, the digests of the Disclosures are embedded
 Digests of Disclosures for object properties are added to an array under the new
 key `_sd` in the object. The `_sd` key MUST refer to an array of strings, each
 string being a digest of a Disclosure or a decoy digest as described in (#decoy_digests).
+An `_sd` key can be present at any level of the JSON object hierarchy, including the top-level,
+nested deeper as described in (#nested_data), or in recursive disclosures as described in (#recursive_disclosures).
 
 The array MAY be empty in case the Issuer decided not to selectively disclose
 any of the claims at that level. However, it is RECOMMENDED to omit the `_sd`
@@ -736,7 +739,7 @@ After validation, the Verifier will have the following processed SD-JWT payload
 
 # Considerations on Nested Data in SD-JWTs {#nested_data}
 
-Being JSON, an object in an SD-JWT payload MAY contain name/value pairs where the value is another object or objects MAY be elements in arrays. In SD-JWT, the Issuer decides for each claim individually, on each level of the JSON, whether the claim should be selectively disclosable or not. This choice can be made on each level independent from whether keys higher in the hierarchy are selectively disclosable.
+Being JSON, an object in an SD-JWT payload MAY contain name/value pairs where the value is another object or objects MAY be elements in arrays. In SD-JWT, the Issuer decides for each claim individually, on each level of the JSON, whether the claim should be selectively disclosable or not. This choice can be made on each level independent of whether keys higher in the hierarchy are selectively disclosable.
 
 From this it follows that the `_sd` key containing digests MAY appear multiple
 times in an SD-JWT, and likewise, there MAY be multiple arrays within the
@@ -841,7 +844,7 @@ It is up to the Holder how to maintain the mapping between the Disclosures and t
 
 ## Processing by the Holder  {#holder_verification}
 
-The Issuer MUST provide the Holder an SD-JWT, not an SD-JWT+KB.  If the Holder
+The Issuer provides the Holder an SD-JWT, not an SD-JWT+KB.  If the Holder
 receives an SD-JWT+KB, it MUST be rejected.
 
 When receiving an SD-JWT, the Holder MUST do the following:
@@ -1266,8 +1269,10 @@ mitigate them as much as possible, and/or make the risks transparent to the user
 Contrary to that, Issuer/Verifier unlinkability with an honest Verifier can generally be achieved.
 However, a callback from the Verifier to the Issuer, such as a revocation check, could potentially
 disclose information about the credential's usage to the Issuer.
-Where such callbacks are necessary, they MUST be executed in a manner that
-preserves privacy and does not disclose details about the credential to the Issuer. It is
+Where such callbacks are necessary, they need to be executed in a manner that
+preserves privacy and does not disclose details about the credential to the Issuer
+(the mechanism described in [@?I-D.ietf-oauth-status-list] is an example of an approach
+with minimal information disclosure towards the Issuer). It is
 important to note that the timing of such requests could potentially serve as a side-channel.
 
 Verifier/Verifier unlinkability and presentation unlinkability can be achieved using batch issuance: A batch
@@ -1418,7 +1423,7 @@ Torsten Lodderstedt,
 Vittorio Bertocci,
 Watson Ladd, and
 Yaron Sheffer
-for their contributions (some of which substantial) to this draft and to the initial set of implementations.
+for their contributions (some of which were substantial) to this draft and to the initial set of implementations.
 
 Special appreciation is extended to Martin Thomson, who wielded his considerable intellect and influence to change a single occurrence of the word "to" to "with" in the midst of a significant proposal that would be integrated into this document six months later.
 
@@ -1976,6 +1981,7 @@ data. The original JSON data is then used by the application. See
    -16
 
    * Editorial updates to text introduced in -15
+   * Selective incorporation of changes based on feedback received nearly four months after the end of the second working group last call
 
    -15