From 14a393c943795ac70adda02d1d70970afe79a60a Mon Sep 17 00:00:00 2001 From: Giuseppe De Marco Date: Sat, 13 Apr 2024 23:00:41 +0200 Subject: [PATCH] fix: Presentation of SD-JWT are not encapsulated anymore in a VP JWT --- docs/en/algorithms.rst | 2 +- docs/en/pid-eaa-data-model.rst | 16 +++---- docs/en/remote-flow.rst | 77 +++++++++++++++++++++------------- 3 files changed, 57 insertions(+), 38 deletions(-) diff --git a/docs/en/algorithms.rst b/docs/en/algorithms.rst index a1698984a..1c9b101a6 100644 --- 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 index 33be9163d..8b196b048 100644 --- a/docs/en/pid-eaa-data-model.rst +++ b/docs/en/pid-eaa-data-model.rst @@ -36,13 +36,15 @@ 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:: ~~~...~ -See `[SD-JWT VC] `_ and `[SD-JWT] `__ for more details. +See `[SD-JWT VC] `_ and +`[SD-JWT] `__ +for additional details. PID/(Q)EAA SD-JWT parameters @@ -60,16 +62,16 @@ 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] `__. + - REQUIRED. It MUST be set to ``vc+sd-jwt`` as defined in `[draft-terbu-sd-jwt-vc-latest] `__. - `[RFC7515, Section 4.1.9] `_. * - **alg** - - Signature Algorithm. + - REQUIRED. Signature Algorithm. - `[RFC7515, Section 4.1.1] `_. * - **kid** - - Unique identifier of the public key. + - REQUIRED. Unique identifier of the public key. - `[RFC7515, Section 4.1.8] `_. * - **trust_chain** - - JSON array containing the trust chain that proves the reliability of the issuer of the JWT. + - Optional. JSON array containing the trust chain that proves the reliability of the issuer of the JWT. - `[OIDC-FED, Section 3.2.1] `_. 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]. @@ -138,7 +140,7 @@ Depending on the Digital Credential type **vct**, additional claims data MAY be 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 index 0ebc6d78f..15148af19 100644 --- 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. @@ -488,46 +488,63 @@ 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", - "kid": "e0bbf2f1-8c3a-4eab-a8ac-2e8f34db8a47" - } - . - { - "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": "~~~...~" - } +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:: + + ~~~...~~ + + +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