fix: Presentation of SD-JWT are not enveloped anymore in a VP JWT (#251)

* fix!: alignments according to breaking changes introduced by openid4vci I-D * fix: Presentation of SD-JWT are not encapsulated anymore in a VP JWT * Apply suggestions from code review Co-authored-by: fmarino-ipzs <[email protected]> * Apply suggestions from code review * Apply suggestions from code review * Update common_definitions.rst * Update common_definitions.rst * Update common_definitions.rst * Update standards.rst * Update pid-eaa-data-model.rst * Update common_definitions.rst * Update standards.rst * Update pid-eaa-data-model.rst --------- Co-authored-by: fmarino-ipzs <[email protected]> Co-authored-by: m-basili <[email protected]>
italia · Jul 30, 2024 · 42a9d4f · 42a9d4f
1 parent 8c18d15
commit 42a9d4f
Show file tree

Hide file tree

Showing 5 changed files with 66 additions and 47 deletions.
diff --git a/docs/common/common_definitions.rst b/docs/common/common_definitions.rst
@@ -50,13 +50,13 @@
 .. _SD-JWT: https://www.ietf.org/archive/id/draft-fett-oauth-selective-disclosure-jwt-02.html
 .. _OpenID4VP: https://openid.net/specs/openid-4-verifiable-presentations-1_0.html
 .. _SIOPv2: https://openid.net/specs/openid-connect-self-issued-v2-1_0.html
-.. _SD-JWT-VC: https://www.ietf.org/id/draft-terbu-sd-jwt-vc-02.html
+.. _SD-JWT-VC: https://datatracker.ietf.org/doc/draft-ietf-oauth-sd-jwt-vc/04/
 .. _PresentationExch: https://identity.foundation/presentation-exchange/spec/v2.0.0
 .. _JARM: https://openid.net/specs/oauth-v2-jarm-final.html
 .. _RFC 9449: https://datatracker.ietf.org/doc/html/draft-ietf-oauth-dpop
 .. _RFC 7519: https://www.rfc-editor.org/rfc/rfc7519
 .. _OAUTH2: https://www.rfc-editor.org/rfc/rfc6749
 .. _OPENID4VC-HAIP: https://openid.net/specs/openid4vc-high-assurance-interoperability-profile-sd-jwt-vc-1_0.html
+.. _SELECTIVE-DISCLOSURE-JWT: https://datatracker.ietf.org/doc/html/draft-ietf-oauth-selective-disclosure-jwt-10
 .. _OAUTH-ATTESTATION-CLIENT-AUTH: https://datatracker.ietf.org/doc/draft-ietf-oauth-attestation-based-client-auth/03/
 
-
diff --git a/docs/common/standards.rst b/docs/common/standards.rst
@@ -12,7 +12,7 @@ Technical References
     * - `OPENID4VCI`_
       - T. Lodderstedt, K. Yasuda, T. Looker, "OpenID for Verifiable Credential Issuance", February 2023.
     * - `SD-JWT-VC`_
-      - O. Terbu, D.Fett, "SD-JWT-based Verifiable Credentials (SD-JWT VC)".
+      - O. Terbu, D.Fett, B. Campbell, "SD-JWT-based Verifiable Credentials (SD-JWT VC)".
     * - `EIDAS-ARF`_
       - EUDI Wallet - Architecture and Reference Framework.
     * - `OPENID4VP`_
@@ -55,5 +55,7 @@ Technical References
       - D. Fett, B. Campbell, J. Bradley, T. Lodderstedt, M. Jones, D. Waite, "OAuth 2.0 Demonstrating Proof-of-Possession at the Application Layer (DPoP)".
     * - `OPENID4VC-HAIP`_
       - Lodderstedt, T., K. Yasuda, "OpenID4VC High Assurance Interoperability Profile with SD-JWT VC".
+    * - `SELECTIVE-DISCLOSURE-JWT`_
+      - Fett, D., Yasuda, K., Campbell, B., "Selective Disclosure for JWTs (SD-JWT)".
     * - `OAUTH-ATTESTATION-CLIENT-AUTH`_
-      - Looker, T., Bastian, P., "OAuth 2.0 Attestation-Based Client Authentication".    
+      - Looker, T., Bastian, P., "OAuth 2.0 Attestation-Based Client Authentication".
diff --git a/docs/en/algorithms.rst b/docs/en/algorithms.rst
@@ -2,7 +2,7 @@
 
 .. _supported_algs:
 
-Cryptographic algorithms
+Cryptographic Algorithms
 ++++++++++++++++++++++++
 
 The following algorithms MUST be supported:

diff --git a/docs/en/pid-eaa-data-model.rst b/docs/en/pid-eaa-data-model.rst
@@ -22,9 +22,9 @@ The PID/(Q)EAA data format and the mechanism through which a digital credential
 SD-JWT
 ======
 
-The PID/(Q)EAA is issued in the form of a Digital Credential. The Digital Credential format is `Selective Disclosure JWT format <https://datatracker.ietf.org/doc/html/draft-ietf-oauth-selective-disclosure-jwt-04>`_ as specified in `[SD-JWT-based Verifiable Credentials 02] <https://www.ietf.org/archive/id/draft-ietf-oauth-sd-jwt-vc-02.html>`__.
+The PID/(Q)EAA is issued in the form of a Digital Credential. The Digital Credential format is `SELECTIVE-DISCLOSURE-JWT`_ as specified in `SD-JWT-VC`_.
 
-An SD-JWT is a JWT that MUST be signed using the Issuer's private key. The SD-JWT payload of the MUST contain the **_sd_alg** claim described in `[SD-JWT]. Section 5.1.2. <https://datatracker.ietf.org/doc/html/draft-ietf-oauth-selective-disclosure-jwt-04>`_ and other claims specified in this section, some of them may be selectively disclosable claims. 
+An SD-JWT is a JWT that MUST be signed using the Issuer's private key. The SD-JWT payload of the MUST contain the **_sd_alg** claim described in the Section 5.1.1 `SELECTIVE-DISCLOSURE-JWT`_ and other claims specified in this section, some of them may be selectively disclosable claims. 
 
 The claim **_sd_alg** indicates the hash algorithm used by the Issuer to generate the digests over the salts and the claim values. The **_sd_alg** claim MUST be set to one of the specified algorithms in Section :ref:`Cryptographic Algorithms <supported_algs>`.
 
@@ -36,13 +36,13 @@ Each digest value ensures the integrity of, and maps to, the respective Disclosu
   - the claim name (only when the claim is an object property), 
   - the claim value. 
 
-The Disclosures are sent to the Holder together with the SD-JWT in the *Combined Format for Issuance* that MUST be an ordered series of base64url-encoded values, each separated from the next by a single tilde ('~') character as follows:
+The Disclosures are provided to the Holder together with the SD-JWT in the *Combined Format for Issuance* that MUST be an ordered series of base64url-encoded values, each separated from the next by a single tilde ('~') character as follows:
 
 .. code-block::
 
   <Issuer-Signed-JWT>~<Disclosure 1>~<Disclosure 2>~...~<Disclosure N>
 
-See `[SD-JWT VC] <https://www.ietf.org/archive/id/draft-ietf-oauth-sd-jwt-vc-02.html>`_ and `[SD-JWT] <https://datatracker.ietf.org/doc/html/draft-ietf-oauth-selective-disclosure-jwt-04>`__ for more details. 
+See `SD-JWT-VC`_ and `SELECTIVE-DISCLOSURE-JWT`_ for additional details. 
 
 
 PID/(Q)EAA SD-JWT parameters
@@ -60,17 +60,17 @@ The JOSE header contains the following mandatory parameters:
     - **Description**
     - **Reference**
   * - **typ**
-    - MUST be set to ``vc+sd-jwt`` as defined in `[draft-terbu-sd-jwt-vc-latest] <https://www.ietf.org/archive/id/draft-terbu-sd-jwt-vc-02.html>`__. 
+    - REQUIRED. It MUST be set to ``vc+sd-jwt`` as defined in `[draft-terbu-sd-jwt-vc-latest] <https://www.ietf.org/archive/id/draft-terbu-sd-jwt-vc-02.html>`__. 
     - `[RFC7515, Section 4.1.9] <https://datatracker.ietf.org/doc/html/rfc7515#section-4.1.9>`_.
   * - **alg**
-    - Signature Algorithm. 
+    - REQUIRED. Signature Algorithm. 
     - `[RFC7515, Section 4.1.1] <https://datatracker.ietf.org/doc/html/rfc7515#section-4.1.1>`_.
   * - **kid**
-    - Unique identifier of the public key. 
+    - REQUIRED. Unique identifier of the public key. 
     - `[RFC7515, Section 4.1.8] <https://datatracker.ietf.org/doc/html/rfc7516.html#section-4.1.8>`_.
   * - **trust_chain**
-    - JSON array containing the trust chain that proves the reliability of the issuer of the JWT. 
-    - `[OIDC-FED, Section 3.2.1] <https://openid.net/specs/openid-connect-federation-1_0.html#name-trust-chain-header-paramete>`_.
+    - OPTIONAL. JSON array containing the trust chain that proves the reliability of the issuer of the JWT. 
+    - `[OIDC-FED, Section 3.2.1] <https://openid.net/specs/openid-federation-1_0.html#name-trust-chain-header-paramete>`_.
 
 The following claims MUST be in the JWT payload. Some of these claims can be disclosed, these are listed in the following tables that specify whether a claim is selectively disclosable [SD] or not [NSD].
 
@@ -95,13 +95,13 @@ The following claims MUST be in the JWT payload. Some of these claims can be dis
       - `[RFC7519, Section 4.1.4] <https://www.iana.org/go/rfc7519>`_.
     * - **status**
       - [NSD].it MUST be a valid JSON object containing the information on how to read the status of the Verifiable Credential. It MUST contain the JSON member *status_attestation* set to a JSON Object containing the *credential_hash_alg* claim indicating the Algorithm used for hashing the Digital Credential to which the Status Attestation is bound. It is RECOMMENDED to use *sha-256*. 
-      - `[SD-JWT-VC. Section 3.2.2.2] <https://www.ietf.org/archive/id/draft-ietf-oauth-sd-jwt-vc-02.html#section-3.2.2.2>`_ and `[OAuth Status Attestations Draft 01] <https://www.ietf.org/archive/id/draft-demarco-status-attestations-01.html#section-9>`_.
+      - Section 3.2.2.2 `SD-JWT-VC`_ and `[OAuth Status Attestations Draft 01] <https://www.ietf.org/archive/id/draft-demarco-status-attestations-01.html#section-9>`_.
     * - **cnf**
       - [NSD].JSON object containing the proof-of-possession key materials. By including a **cnf** (confirmation) claim in a JWT, the issuer of the JWT declares that the Holder is in control of the private key related to the public one defined in the **cnf** parameter. The recipient MUST cryptographically verify that the Holder is in control of that key.
-      - `[RFC7800, Section 3.1] <https://www.iana.org/go/rfc7800>`_ and `[SD-JWT-VC. Section 3.2.2.2] <https://www.ietf.org/archive/id/draft-ietf-oauth-sd-jwt-vc-02.html#section-3.2.2.2>`_.
+      - `[RFC7800, Section 3.1] <https://www.iana.org/go/rfc7800>`_ and Section 3.2.2.2 `SD-JWT-VC`_.
     * - **vct**
       - [NSD].Credential type as a string, MUST be set in accordance to the type obtained from the PID/(Q)EAA Issuer metadata. For example, in the case of the PID, it MUST be set to ``PersonIdentificationData``.
-      - `[SD-JWT-VC. Section 3.2.2.2] <https://www.ietf.org/archive/id/draft-ietf-oauth-sd-jwt-vc-02.html#section-3.2.2.2>`_.
+      - Section 3.2.2.2 `SD-JWT-VC`_.
 
 
 .. _sec-pid-user-claims:   
@@ -140,7 +140,7 @@ The PID attribute schema, which encompasses all potential User data, is defined
 PID Non-Normative Examples
 --------------------------
 
-In the following, the non-normative example of a PID in JSON format.
+In the following, the non-normative example of the payload of a PID represented in JSON format.
 
 .. code-block:: JSON
 

diff --git a/docs/en/remote-flow.rst b/docs/en/remote-flow.rst
@@ -201,9 +201,9 @@ Cross Device Flow Status Checks and Security
 
 When the flow is Cross Device, the user-agent needs to check the session status to the endpoint made available by Relying Party (status endpoint). This check MAY be implemented in the form of JavaScript code, within the page that shows the QRCode, then the user-agent checks the status with a polling strategy in seconds or a push strategy (eg: web socket).
 
-Since the QRcode page and the status endpoint are implemented by the Relying Party, it is under the Relying Party responsability the implementation details of this solution, since it is related to the Relying Party's internal API. However, the text below offers an implementation solution.
+Since the QRcode page and the status endpoint are implemented by the Relying Party, it is under the Relying Party responsability the implementation details of this solution, since it is related to the Relying Party's internal API. However, the text below describes an implementation example.
 
-The Relying Party MUST bind the request of the user-agent, with a session cookie marked as ``Secure`` and ``HttpOnly`` , with the issued request. The request url SHOULD include a parameter with a random value. The HTTP response returned by this specialized endpoint MAY contain the HTTP status codes listed below:
+The Relying Party binds the request of the user-agent, with a session cookie marked as ``Secure`` and ``HttpOnly``, with the issued request. The request url SHOULD include a parameter with a random value. The HTTP response returned by this specialized endpoint MAY contain the HTTP status codes listed below:
 
 * **201 Created**. The signed Request Object was issued by the Relying Party that waits to be downloaded by the Wallet Instance at the **request_uri** endpoint.
 * **202 Accepted**. This response is given when the signed Request Object was obtained by the Wallet Instance.
@@ -444,45 +444,62 @@ Where the following parameters are used:
     - Unique identifier provided by the Relying Party within the Authorization Request.
 
 
-Below is a non-normative example of the ``vp_token`` decoded content, represented in the form of JWS header and payload, separated by a period:
+The items contained in the ``vp_token`` array are Verifiable Presentations of Credentials.
+Both SD-JWT and mdoc CBOR provide indications for the presentation, according to their specifications.
 
-.. code-block:: text
+SD-JWT Presentation
+-------------------
 
-   {
-     "alg": "ES256",
-     "typ": "JWT"
-   }
-   .
-   {
-     "iss": "vbeXJksM45xphtANnCiG6mCyuU4jfGNzopGuKvogg9c",
-     "jti": "3978344f-8596-4c3a-a978-8fcaba3903c5",
-     "aud": "https://relying-party.example.org/response_uri",
-     "iat": 1541493724,
-     "exp": 1573029723,
-     "nonce": "2c128e4d-fc91-4cd3-86b8-18bdea0988cb",
-     "vp": "<Issuer-Signed-JWT>~<Disclosure 1>~<Disclosure 2>~...~<Disclosure N>"
-   }
+SD-JWT defines how an Holder can present a Credential to a Verifier proving the legitimate possession
+of the Credential. For doing this the Holder MUST include the ``KB-JWT`` in the SD-JWT,
+by appending the ``KB-JWT`` at the end of the of the SD-JWT, as represented in the example below:
 
-Where the following parameters are used:
+.. code-block::
+
+  <Issuer-Signed-JWT>~<Disclosure 1>~<Disclosure 2>~...~<Disclosure N>~<KB-JWT>
+
+To validate the signature on the Key Binding JWT, the Verifier MUST use the key material included in the Issuer-Signed-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 parameter ``kid``.
+
+When an SD-JWT is presented, its KB-JWT MUST contain the following parameters in the JWS header:
 
 .. list-table::
   :widths: 25 50
   :header-rows: 1
 
-  * - **Name**
+  * - **Claim**
+    - **Description**
+  * - **typ**
+    - REQUIRED. MUST be ``kb+jwt``, which explicitly types the Key Binding JWT as recommended in Section 3.11 of [RFC8725].
+  * - **alg**
+    - REQUIRED. Signature Algorithm using one of the specified in the section Cryptographic Algorithms. 
+  * - **kid**
+    - REQUIRED. Unique identifier of the public key to be used to verify the signature.
+
+
+When an SD-JWT is presented, its KB-JWT MUST contain the following parameters in the JWS payload:
+
+.. list-table::
+  :widths: 25 50
+  :header-rows: 1
+
+  * - **Claim**
     - **Description**
-  * - **vp**
-    - The Digital Credential in its original state. The public key contained in the Digital Credential MUST be used to verify the entire VP JWS as Proof of Possession of the private key which the public key is included in the Digital Credential. Eg: for SD-JWT VC the public key is provided within the ``cnf.jwk`` claim.
-  * - **jti**
-    - JWS unique identifier.
   * - **iat**
-    - Unix timestamp of the time of issuance of this presentation.
-  * - **exp**
-    - Unix timestamp beyond which this presentation will no longer be considered valid.
+    - 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**
-    - Audience of the VP, corresponding to the ``response_uri`` within the Authorization request issued by the Relying Party.
+    - 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**
-    - The nonce value provided by the Relying Party within the Authorization Request.
+    - 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.
+
+
+MDOC-CBOR Presentation
+----------------------
+
+TBD.
 
 
 Authorization Response Errors