Add text on hash in KB-JWT (#353)

* Improve structure of specification

* Fix references

* serialized format for the SD-JWT figure: adding a newline so (hopefully) the horizontal scrollbar in the HTML output doesn't cover up the contentUpdate draft-ietf-oauth-selective-disclosure-jwt.md

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

Co-authored-by: Kristina <[email protected]>

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

Co-authored-by: Kristina <[email protected]>

* Apply suggestions from code review

* Remove KB-JWT header example

Co-authored-by: Brian Campbell <[email protected]>

* Move three subsections out of 'Data Format Details' and remove that section

* Reformat list of SD-JWT payload requirements and note on line breaks

* Add text on hash in KB-JWT

* Add instructions on checking hash and hash algorithm

* Uppercase Presentation

* Adapt wording in concepts section

* Document history

* Add IANA registration for new claim

* Improve wording in Integrity of Presentation

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

Co-authored-by: Brian Campbell <[email protected]>

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

Co-authored-by: Brian Campbell <[email protected]>

* Remove trailing whitespace

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

Co-authored-by: Orie Steele <[email protected]>

* Apply suggestions from Joseph's code review

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

---------

Co-authored-by: Daniel Fett <[email protected]>
Co-authored-by: Brian Campbell <[email protected]>
Co-authored-by: Kristina <[email protected]>
Co-authored-by: Orie Steele <[email protected]>

.github/workflows/ghpages.yml

@@ -30,7 +30,7 @@ jobs:
     - name: "Install SD-JWT tooling"
       run: |
         python3 -m pip install --upgrade pip
-        python3 -m pip install git+https://github.com/openwallet-foundation-labs/sd-jwt-python.git
+        python3 -m pip install git+https://github.com/openwallet-foundation-labs/sd-jwt-python.git@danielfett/kb-jwt-hash
 
     # Build the local examples
     - name: "Build local examples"

.github/workflows/publish.yml

@@ -25,7 +25,7 @@ jobs:
     - name: "Install SD-JWT tooling"
       run: |
         python3 -m pip install --upgrade pip
-        python3 -m pip install git+https://github.com/openwallet-foundation-labs/sd-jwt-python.git
+        python3 -m pip install git+https://github.com/openwallet-foundation-labs/sd-jwt-python.git@danielfett/kb-jwt-hash
 
     # Build the local examples
     - name: "Build local examples"

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

@@ -224,11 +224,12 @@ Key Binding is an optional feature. When Key Binding is required by the use-case
 
 Note: How the public key is included in SD-JWT is out of scope of this document. It can be passed by value or by reference.
 
-The Holder can then create a signed document, the Key Binding JWT as defined in (#kb-jwt), using its private key. This document contains some
-data provided by the Verifier such as a nonce to ensure the freshness of the signature, and audience to indicate the
-intended audience for the document.
-
-The Key Binding JWT can be included as part of the SD-JWT and sent to the Verifier as described in (#data_formats).
+For presenting an SD-JWT to a Verifier that enforces Key Binding, the Holder
+creates a signed document, the Key Binding JWT as defined in (#kb-jwt), using
+its private key. This document contains a nonce to ensure the freshness of the signature, an audience value to
+indicate the intended audience for the document, and a hash that ensures the
+integrity of the data sent from the Holder to the Verifier. Details of the format of Key Binding JWTs are
+described in (#kb-jwt).
 
 Note that there may be other ways to send a Key Binding JWT to the Verifier or for the Holder to prove possession of the key material included in an SD-JWT. In these cases, inclusion of the Key Binding JWT in the SD-JWT is not required.
 
@@ -521,13 +522,35 @@ The JWT MUST contain the following elements:
     * `iat`: REQUIRED. The value of this claim MUST be the time at which the Key Binding JWT was issued using the syntax defined in [@!RFC7519].
     * `aud`: REQUIRED. The intended receiver of the Key Binding JWT. How the value is represented is up to the protocol used and out of scope of this specification.
     * `nonce`: REQUIRED. Ensures the freshness of the signature. The value type of this claim MUST be a string. How this value is obtained is up to the protocol used and out of scope of this specification.
+    * `_sd_hash`: REQUIRED. The base64url-encoded hash digest over the Issuer-signed JWT and the selected Disclosures as defined below.
+
+### Integrity Protection of the Presentation {#integrity-protection-of-the-presentation}
+
+The hash digest in `_sd_hash` ensures the integrity of the Presentation. It MUST
+be taken over the US-ASCII bytes preceding the KB-JWT in the Presentation, i.e.,
+the Issuer-signed JWT, a tilde character, and zero or more Disclosures selected
+for presentation to the Verifier, each followed by a tilde character:
+
+```
+<Issuer-signed JWT>~<Disclosure 1>~<Disclosure 2>~...~<Disclosure N>~
+```
+
+The bytes of the digest MUST then be base64url-encoded.
+
+The same hash algorithm as for the Disclosures MUST be used (defined by
+the `_sd_alg` element in the Issuer-signed JWT or the default value, as defined
+in (#hash_function_claim)).
+
+### Validating the Key Binding JWT
 
 To validate the signature on the Key Binding JWT, the Verifier MUST use the key material in the SD-JWT. If it is not clear from the SD-JWT, the Key Binding JWT MUST specify which key material the Verifier needs to use to validate the Key Binding JWT signature using JOSE header parameters such as `kid` and `x5c`.
 
 Whether to require Key Binding is up to the Verifier's policy, based on the set
 of trust requirements such as trust frameworks it belongs to. See
 (#key_binding_security) for security considerations.
 
+### Alternatives to a Key Binding JWT
+
 Other ways of proving Key Binding MAY be used when supported by the Verifier,
 e.g., when the presented SD-JWT without a Key Binding JWT is itself embedded in a
 signed JWT. See (#enveloping) for details.
@@ -721,7 +744,8 @@ To this end, Verifiers MUST follow the following steps (or equivalent):
        5. Check that the `typ` of the Key Binding JWT is `kb+jwt`.
        6. Check that the creation time of the Key Binding JWT, as determined by the `iat` claim, is within an acceptable window.
        7. Determine that the Key Binding JWT is bound to the current transaction and was created for this Verifier (replay protection) by validating `nonce` and `aud` claims.
-       8. Check that the Key Binding JWT is valid in all other respects, per [@!RFC7519] and [@!RFC8725].
+       8. Calculate the digest over the Issuer-signed JWT and Disclosures as defined in (#integrity-protection-of-the-presentation) and verify that it matches the value of the `_sd_hash` claim in the Key Binding JWT.
+       9. Check that the Key Binding JWT is valid in all other respects, per [@!RFC7519] and [@!RFC8725].
 
 If any step fails, the Presentation is not valid and processing MUST be aborted.
 
@@ -800,7 +824,7 @@ Key Binding is achieved by the signature on the enclosing JWT.
 }
 ```
 
-Other specifications or profiles of this specification may define alternative formats for transporting an SD-JWT that envelope multiple such SD-JWTs into one object and provide Key Binding using means other than the Key Binding JWT.
+Other specifications or profiles of this specification may define alternative formats for transporting an SD-JWT that envelope multiple such SD-JWTs into one object and provide Key Binding and integrity protection of the presentation using means other than the Key Binding JWT.
 
 
 # Security Considerations {#security_considerations}
@@ -924,10 +948,6 @@ particular use case and the Key Binding is not present, does not fulfill the req
 Key Binding data is present in the SD-JWT, the Verifier will reject the
 presentation, as described in (#verifier_verification).
 
-### Key Binding JWT
-
-Issuer provided integrity protection of the SD-JWT payload and Disclosures is achieved by the signature on the Issuer-signed JWT that covers the SD-JWT payload including the digest values of the Disclosures as described in (#sec-is-jwt) and (#sec-disclosures), respectively. The Key Binding JWT, defined in (#kb-jwt), serves exclusively as a mechanism for the Holder to demonstrate possession of the private key corresponding to the public key in the SD-JWT payload. As such, the signature on the Key Binding JWT does not cover other parts of the SD-JWT. In cases where it's desirable for the Holder's signature to convey more than a proof-of-possession, such as signing over the selected Disclosures to prove those were the Disclosures selected, the SD-JWT to be presented can be embedded in another JWT (as described in [Enveloping SD-JWTs](#enveloping)) or otherwise signed by the Holder via the application protocol delivering it.
-
 ## Blinding Claim Names {#blinding-claim-names}
 
 SD-JWT ensures that names of claims that are selectively disclosable are
@@ -983,6 +1003,13 @@ when presenting to a downstream party.
 In some scenarios this behavior could be desirable,
 but if it is not, Issuers need to support and Verifiers need to enforce Key Binding.
 
+## Integrity of Presentation
+
+In a Presentation, the Issuer-signed JWT is integrity-protected by the Issuer's
+signature, and the Disclosures are integrity-protected by the digests included
+in the Issuer-signed JWT. If used, the KB-JWT, besides proving Key Binding, protects the integrity of the
+set of Disclosures the Holder disclosed.
+
 ## Explicit Typing {#explicit_typing}
 
 Section 3.11 of [@RFC8725] describes the use of explicit typing to prevent confusion attacks
@@ -1156,10 +1183,17 @@ IANA "JSON Web Token Claims" registry [@IANA.JWT] established by [@!RFC7519].
 <br/>
 
 *  Claim Name: `_sd_alg`
-*  Claim Description: Hash algorithm used to generate disclosure digests
+*  Claim Description: Hash algorithm used to generate disclosure digests and digest over presentation
 *  Change Controller: IETF
 *  Specification Document(s):  [[ (#hash_function_claim) of this specification ]]
 
+<br/>
+
+*  Claim Name: `_sd_hash`
+*  Claim Description: Digest of the Issuer-signed JWT and Disclosures in a Presentation
+*  Change Controller: IETF
+*  Specification Document(s):  [[ (#kb-jwt) of this specification ]]
+
 ## Media Type Registration
 
 This section requests registration of the following media types [@RFC2046] in
@@ -1626,6 +1660,7 @@ data. The original JSON data is then used by the application. See
 
    -06
 
+   * Added hash of Issuer-signed part and Disclosures in KB-JWT
    * Fix minor issues in some examples
    * Added IANA media type registration request for the JSON Serialization
    * More precise wording around storing artifacts with sensitive data