Rework JSON Serialization section (#414)

* Rework JSON Serialization section

* Switch to new branch, update examples

* Add new example, describe signature handling

* Clarification proposed by Brian

Co-authored-by: Brian Campbell <71398439+bc-pi@users.noreply.github.com>

* Add changelog entry

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

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

* Switch back to master

---------

Co-authored-by: Brian Campbell <71398439+bc-pi@users.noreply.github.com>

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

@@ -765,35 +765,65 @@ Otherwise, the processed SD-JWT payload can be passed to the application to be u
 
 # JWS JSON Serialization {#json_serialization}
 
-This section describes an optional alternate format for SD-JWT using the JWS JSON Serialization from [@!RFC7515].
+This section describes an alternative format for SD-JWT using the JWS JSON
+Serialization from [@!RFC7515]. Supporting this format is OPTIONAL.
 
-For both the General and Flattened JSON Serialization, the SD-JWT is represented as a JSON object according
-to Section 7.2 of [@!RFC7515]. The Disclosures (both for issuance and presentation) SHOULD be included in the
-serialized JWS using the member name `disclosures` at the top-level of the JSON object (the same level as the `payload` member). The
-value of the `disclosures` member is an array of strings where each element is an individual Disclosure
-as described in (#creating_disclosures). The Issuer includes a Disclosure for each selectively
-disclosable claim of the SD-JWT payload, whereas the Holder includes only the Disclosures
-selected for the given presentation.
+## New Unprotected Header Parameters {#json_serialization_unprotected_headers}
 
-Alternative methods for conveying the Disclosures MAY be used (such as including them in a `disclosures`
-member of an outer JSON structure also containing the JSON Serialized SD-JWT) as dictated by a specific
-application or transport protocol. However, the details of such approaches fall outside the scope of this
-specification.
+For both the General and Flattened JSON Serialization, the SD-JWT is represented
+as a JSON object according to Section 7.2 of [@!RFC7515]. The following new
+unprotected header parameters are defined:
 
-Verification of the JWS JSON serialized SD-JWT follows the same rules defined in (#verification),
-except that the SD-JWT does not need to be split into component parts and the Disclosures
-can be found in the respective member of the JSON object (or elsewhere).
+ * `disclosures`: An array of strings where each element is an individual
+   Disclosure as described in (#creating_disclosures).
+ * `kb_jwt`: A Key Binding JWT as described in (#kb-jwt).
 
-Using a payload similar to that from the example in (#main-example), the following is a non-normative example of
-a JWS JSON serialized SD-JWT from an Issuer with all the respective Disclosures.
 
-<{{examples/json_serialization/sd_jwt_issuance.json}}
+If a Key Binding JWT is present, the digest in the `sd_hash` claim MUST be taken
+over a string built as described in (#integrity-protection-of-the-presentation).
+The "Issuer-signed JWT" part is built by concatenating the protected header, the
+payload, and the signature of the JWS JSON serialized SD-JWT using a `.`
+character as a separator, and using the Disclosures from the `disclosures`
+member of the unprotected header. In case of multiple signatures, only the first
+one is used for the Disclosures and Key Binding JWT.
 
-Below is a non-normative example of a presentation of the JWS JSON serialized SD-JWT, where the Holder
-has selected to disclose `given_name`, `family_name`, and `address`.
+## Flattened JSON Serialization
 
-<{{examples/json_serialization/sd_jwt_presentation.json}}
+In case of the Flattened JSON Serialization, there is only one unprotected
+header.
 
+The following is a non-normative example of a JWS JSON serialized SD-JWT as
+issued using the Flattened JSON Serialization:
+
+<{{examples/json_serialization_flattened/sd_jwt_issuance.json}}
+
+The following is a presentation including a Key Binding JWT and two Disclosures:
+
+<{{examples/json_serialization_flattened/sd_jwt_presentation.json}}
+
+## General JSON Serialization
+
+In case of the General JSON Serialization, there are multiple unprotected
+headers (one per signature). If present, `disclosures` and `kb_jwt`, MUST be
+included in the first unprotected header and MUST NOT be present in any
+following unprotected headers.
+
+The following is a non-normative example of a presentation of a JWS JSON
+serialized SD-JWT including a Key Binding JWT using the General JSON
+Serialization:
+
+<{{examples/json_serialization_general/sd_jwt_presentation.json}}
+
+## Verification of the JWS JSON Serialized SD-JWT
+
+Verification of the JWS JSON serialized SD-JWT follows the rules defined in
+(#verification), except for the following aspects:
+
+ * The SD-JWT does not need to be split into component parts and the Disclosures
+   can be found in the `disclosures` member of the unprotected header.
+ * To verify the digest in `sd_hash` in the Key Binding JWT, the Verifier MUST
+   assemble the string to be hashed as described in
+   (#json_serialization_unprotected_headers).
 
 # Security Considerations {#security_considerations}
 
@@ -1716,6 +1746,7 @@ data. The original JSON data is then used by the application. See
 
    -09
 
+   * New structure for JSON-serialized SD-JWTs/KB-JWTs to better align with JAdES.
    * Attempt to better explain how salt in the Disclosure makes guessing the preimage of the digest infeasible
    * Consolidate salt entropy and length security consideration subsections
    * Unnumbered most of the examples for improved clarity

examples/json_serialization_flattened/specification.yml

@@ -0,0 +1,13 @@
+user_claims:
+  !sd sub: john_doe_42
+  !sd given_name: John
+  !sd family_name: Doe
+  !sd birthdate: "1940-01-01"
+
+holder_disclosed_claims:
+  given_name: true
+  family_name: true
+
+key_binding: True
+
+serialization_format: "json"

examples/json_serialization_general/specification.yml

@@ -0,0 +1,38 @@
+user_claims:
+  !sd sub: john_doe_42
+  !sd given_name: John
+  !sd family_name: Doe
+  !sd birthdate: "1940-01-01"
+
+holder_disclosed_claims:
+  given_name: true
+  family_name: true
+
+key_binding: True
+
+serialization_format: "json"
+
+settings_override:
+  key_settings:
+    key_size: 256
+    kty: EC
+    issuer_keys:
+      - kty: EC
+        d: Ur2bNKuBPOrAaxsRnbSH6hIhmNTxSGXshDSUD1a1y7g
+        crv: P-256
+        x: b28d4MwZMjw8-00CG4xfnn9SLMVMM19SlqZpVb_uNtQ
+        y: Xv5zWwuoaTgdS6hV43yI6gBwTnjukmFQQnJ_kCxzqk8
+        kid: issuer-key-1
+      - kty: EC
+        crv: P-256
+        d: WsGosxrp0XK7VEviPL9xBm3fBb7Xys2vLhPGhESNoXY
+        x: bN-hp3IN0GZB3OlaQnHDPhY4nZsZbQyo4wY-y1NWCvA
+        y: vaSsH5jt9zt3aQvTvrSaFYLyjPG9Ug-2vntoNXlCbVU
+        kid: issuer-key-2
+
+    holder_key:
+      kty: EC
+      d: 5K5SCos8zf9zRemGGUl6yfok-_NiiryNZsvANWMhF-I
+      crv: P-256
+      x: TCAER19Zvu3OHF4j4W4vfSVoHIP1ILilDls7vCeGemc
+      y: ZxjiWWbZMQGHVWKVQ4hbSIirsVfuecCE6t4jT9F2HZQ

examples/settings.yml

@@ -7,12 +7,12 @@ key_settings:
 
     kty: EC
 
-    issuer_key:
-        kty: EC
-        d: Ur2bNKuBPOrAaxsRnbSH6hIhmNTxSGXshDSUD1a1y7g
-        crv: P-256
-        x: b28d4MwZMjw8-00CG4xfnn9SLMVMM19SlqZpVb_uNtQ
-        y: Xv5zWwuoaTgdS6hV43yI6gBwTnjukmFQQnJ_kCxzqk8
+    issuer_keys:
+        - kty: EC
+          d: Ur2bNKuBPOrAaxsRnbSH6hIhmNTxSGXshDSUD1a1y7g
+          crv: P-256
+          x: b28d4MwZMjw8-00CG4xfnn9SLMVMM19SlqZpVb_uNtQ
+          y: Xv5zWwuoaTgdS6hV43yI6gBwTnjukmFQQnJ_kCxzqk8
 
     holder_key:
         kty: EC
@@ -23,9 +23,9 @@ key_settings:
 
 key_binding_nonce: "1234567890"
 
-expiry_seconds: 86400000  # 1000 days
+expiry_seconds: 86400000 # 1000 days
 
 random_seed: 0
 
-iat: 1683000000  # Tue May 02 2023 04:00:00 GMT+0000
-exp: 1883000000  # Sat Sep 01 2029 23:33:20 GMT+0000
+iat: 1683000000 # Tue May 02 2023 04:00:00 GMT+0000
+exp: 1883000000 # Sat Sep 01 2029 23:33:20 GMT+0000