From 79977c92bd76daba3c587c73201b7a013188971e Mon Sep 17 00:00:00 2001 From: Riccardo Iaconelli Date: Sun, 15 Oct 2023 21:30:01 +0200 Subject: [PATCH 01/28] [draft] revocation technical details --- docs/en/revocation-lists.rst | 219 +++++++++++++++++++++++++++++------ 1 file changed, 184 insertions(+), 35 deletions(-) diff --git a/docs/en/revocation-lists.rst b/docs/en/revocation-lists.rst index 49cc7b174..05f2305f4 100644 --- a/docs/en/revocation-lists.rst +++ b/docs/en/revocation-lists.rst @@ -1,57 +1,206 @@ .. include:: ../common/common_definitions.rst -.. _revocation-lists.rst: +.. _revocation-lists: -revocation-lists.rst -+++++++++++++++++++++++++++ +Credential validity and non-revocation attestations ++++++++++++++++++++++++++++++++++++++++++++++++++++ -[What is it] - -[What it is usefull for] - -[Example] - -General Properties ------------------- - -[TODO] +This section outlines the key technical requirements and processes related to the validity and non-revocation of digital credentials. It provides a comprehensive guide on how to manage, verify, and revoke digital credentials in a secure and reliable manner. - -Requirements +The value of verifiable credentials is contingent on their validity. A credential that has been revoked, due to legal requirements, inaccuracy or compromise, is not only valueless but potentially harmful. Therefore, robust mechanisms for managing the validity and revocation of credentials are crucial. + +This section is structured into several subsections, each addressing a different aspect of credential validity and revocation. + +The "Key Technical Requirements" subsection outlines the fundamental requirements for managing credential validity and revocation. These requirements define the roles and responsibilities of the Authentic Source, the Issuer, and the Wallet Instance in ensuring the validity of credentials and managing their revocation. + +The "Presentation" and "Issuance" subsections describe the processes by which a Wallet Instance responds to a presentation request and initiates a request for a digital credential, respectively. These subsections detail how a non-revocation attestation, a proof that the credential has not been revoked, is created, presented, and validated. + +The "Non-Revocation Attestation Renewal Flow" and "Credential Revocation Flow" subsections provide detailed workflows for renewing a non-revocation attestation and revoking a credential, respectively. These workflows include the generation and verification of a Proof of Possession (PoP) JWT, which proves that the Wallet Instance possesses the private key associated with the VC. + + +Key Technical Requirements +--------------------------- + +- The Authentic Source MUST be the only source of truth for credential validity. All revocation requests MUST be communicated to the Authentic Source using appropriate channels. These requests MAY come from: + - The citizen (Holder) via their personal Wallet Instance. + - The citizen via a legal entity (e.g., Police for reporting). + - The citizen directly via the Authentic Source. + - The Authentic Source itself (e.g., for attribute updates). + - A legal entity (e.g., Police for seizure). +- The Authentic Source MUST maintain a record of the issuers who have issued a certain credential. +- The Issuer MUST provide information about a callback hook for revocation. +- The Authentic Source MUST manage the revocation of issued credentials by notifying the respective issuers. +- The Authentic Source MUST maintain a mapping between ID_CREDENTIAL and ID_ISSUER to facilitate credential revocation even in case of Wallet Instance loss. +- The revocation MUST be verifiable via a cryptographic signature. + + +Presentation ------------ - - req 1 - - req 2 +The Wallet Instance responds to a presentation request from the Relying Party. It produces a Verifiable Presentation (VP) token with the digital credential and a non-revocation attestation. This attestation is a proof that the credential has not been revoked. + +It is timestamped with the request date and always refers to a previous period. Importantly, this attestation does not reveal any information about the Relying Party. The Relying Party then evaluates and validates the response, the VP token, and the non-revocation attestation. + +Issuance +-------- + +The Wallet Instance initiates a request for a digital credential from the Credential Issuer. + +Upon successful request, the Wallet Instance receives: +- The digital credential +- A non-revocation attestation + +The non-revocation attestation is presented in conjunction with the credential. The attestation is timestamped with the request date, not the authentication date, and always refers to a previous period. +Relying Parties determine the validity duration of this attestation based on the specific use case. +By default, an attestation is considered valid if issued within the previous 350 hours. This provision supports offline use cases and potential disruptions or incidents in the certification systems. Note that this delay only refers to the non-revocation of the credential, while the validity of the credential itself can always be verified. + +Non-Revocation Attestation Renewal Flow +--------------------------------------- + +.. code-block:: mermaid + + sequenceDiagram + participant WalletInstance as Wallet Instance + participant VCIssuer as VC Issuer + WalletInstance->>VCIssuer: Send Non-Revocation Attestation Renewal Request + VCIssuer->>VCIssuer: Verify credential PoP + VCIssuer->>VCIssuer: Renew Non-Revocation Attestation (if PoP is valid) + VCIssuer->>WalletInstance: Send Response + +1. **Non-Revocation Attestation Renewal Request**: The Wallet Instance initiates the process by creating a Non-Revocation Attestation Renewal Request. This request includes the ID of the VC for which the non-revocation attestation is to be renewed and a PoP JWT. The PoP JWT is signed with the private key associated with the VC, and includes claims such as `iss`, `aud`, `exp`, `iat`, and `jti`. + +2. **Send Request to VC Issuer**: The Wallet Instance sends the Non-Revocation Attestation Renewal Request to the VC Issuer's renewal endpoint. The request is authenticated using the PoP JWT (see [Proof of Possession (PoP) JWT generation process](#proof-of-possession-pop-jwt-generation-process)), which proves that the Wallet Instance possesses the private key associated with the VC. + +3. **Verify PoP**: The VC Issuer verifies the PoP by checking the signature of the PoP JWT using the public key that was used when the VC was issued. If the verification is successful, it means that the Wallet Instance possesses the private key associated with the VC, and therefore has the authority to request its renewal. + +4. **Renew Non-Revocation Attestation**: If the PoP is verified successfully, the VC Issuer renews the non-revocation attestation for the VC identified by the ID in the Non-Revocation Attestation Renewal Request. +5. **Send Response**: The VC Issuer sends a response back to the Wallet Instance indicating the result of the renewal request. If the renewal was successful, the response includes the renewed non-revocation attestation. -Attributes ----------- +.. code-block:: python -[Table with parameters/attributes] + # Step 1: Create Non-Revocation Attestation Renewal Request + attestation_renewal_request = { + "vc_id": "ID of the VC to be renewed", + "pop_jwt": "PoP JWT signed with the private key associated with the VC" + } + + # Step 2: Send Request to VC Issuer + response = send_request_to_vc_issuer(attestation_renewal_request) + + # Step 3: VC Issuer verifies the PoP + is_pop_valid = verify_pop(attestation_renewal_request["pop_jwt"]) + + if is_pop_valid: + # Step 4: Renew Non-Revocation Attestation + renew_attestation(attestation_renewal_request["vc_id"]) + + # Step 5: Send Response + response = { + "status": "success", + "message": "Non-revocation attestation renewed successfully" + } + else: + response = { + "status": "failure", + "message": "PoP verification failed" + } + + +Upon successful request, the Wallet Instance receives: +- The renewed non-revocation attestation + +This process ensures that the Wallet Instance is the legitimate owner of the digital credential and has the authority to request its renewal. It does so by signing the request and having the Issuer verify this signature using the corresponding public key. This ensures that the Wallet Instance is authenticated and has a PID. + +Proof of Possession (PoP) JWT generation process +------------------------------------------------ + +The Wallet Instance generates a Proof of Possession (PoP) JWT as follows: + +1. **Create PKCE code verifier**: The Wallet Instance creates a fresh PKCE code verifier, Wallet Instance Attestation Proof of Possession, and ``state`` parameter for the *Pushed Authorization Request*. + +2. **Send parameters to PID/(Q)EAA Provider**: The Wallet Instance provides these parameters to the PID/(Q)EAA Provider PAR endpoint using the ``request`` parameter to prevent Request URI swapping attack. + +3. **Generate code_verifier**: The Wallet Instance must create the ``code_verifier`` with enough entropy random string using the unreserved characters with a minimum length of 43 characters and a maximum length of 128 characters. This makes it impractical for an attacker to guess its value. The value must be generated following the recommendation in Section 4.1 of :rfc:`7636`. + +4. **Sign the request**: The Wallet Instance signs this request using the private key that was created during the setup phase to obtain the Wallet Instance Attestation. The related public key that is attested by the Wallet Provider is provided within the Wallet Instance Attestation ``cnf`` claim. + +5. **Create PoP**: The Proof of Possession JWT contains a JOSE header with ``alg``, ``kid``, and ``typ`` parameters, and a body with ``iss``, ``aud``, ``exp``, ``iat``, and ``jti`` claims. + + - ``alg``: A digital signature algorithm identifier such as per IANA "JSON Web Signature and Encryption Algorithms" registry. It MUST be one of the supported algorithms listed in the Section `Cryptographic Algorithms `_ and MUST NOT be set to ``none`` or any symmetric algorithm (MAC) identifier. + - ``kid``: Unique identifier of the ``jwk`` inside the ``cnf`` claim of Wallet Instance Attestation as base64url-encoded JWK Thumbprint value. + - ``typ``: It MUST be set to ``jwt-client-attestation-pop`` + - ``iss``: Thumbprint of the JWK in the ``cnf`` parameter. + - ``aud``: It MUST be set to the identifier of the PID/(Q)EAA Provider. + - ``exp``: UNIX Timestamp with the expiry time of the JWT. + - ``iat``: UNIX Timestamp with the time of JWT issuance. + - ``jti``: Unique identifier for the DPoP proof JWT. The value SHOULD be set using a *UUID v4* value according to RFC 4122. + +6. **Set client_assertion parameter**: The ``client_assertion`` parameter in the Token Request is set to a value containing the Wallet Instance Attestation and the Proof of Possession, separated with the ``~`` character. + +7. **Verify PoP**: The PID/(Q)EAA Provider then verifies the Proof of Possession by checking the signature of the request using the public key provided in the Wallet Instance Attestation ``cnf`` claim. -.. list-table:: - :widths: 20 60 - :header-rows: 1 +Credential Revocation Flow +-------------------------- + +.. code-block:: mermaid + + sequenceDiagram + participant WalletInstance as Wallet Instance + participant VCIssuer as Issuer + WalletInstance->>VCIssuer: Send Credential Revocation Request + VCIssuer->>VCIssuer: Verify credential PoP + VCIssuer->>VCIssuer: Revoke VC (if PoP is valid) + VCIssuer->>WalletInstance: Send Response + +1. **Credential Revocation Request**: The Wallet Instance initiates the process by creating a Credential Revocation Request. This request includes the ID of the VC to be revoked and a PoP JWT. The PoP JWT is signed with the private key associated with the VC to be revoked, and includes claims such as `iss`, `aud`, `exp`, `iat`, and `jti`. + +2. **Send Request to VC Issuer**: The Wallet Instance sends the Credential Revocation Request to the VC Issuer's revocation endpoint. The request is authenticated using the PoP JWT, which proves that the Wallet Instance possesses the private key associated with the VC. + +3. **Verify PoP**: The VC Issuer verifies the PoP by checking the signature of the PoP JWT using the public key that was used when the VC was issued. If the verification is successful, it means that the Wallet Instance possesses the private key associated with the VC, and therefore has the authority to request its revocation. + +4. **Revoke VC**: If the PoP is verified successfully, the VC Issuer revokes the VC identified by the ID in the Credential Revocation Request. + +5. **Send Response**: The VC Issuer sends a response back to the Wallet Instance indicating the result of the revocation request. If the revocation was successful, the response includes a confirmation of the revocation. + +Here's a code block that outlines the flow: + +.. code-block:: python - * - **Claim** - - **Description** - * - key - - value + # Step 1: Create Credential Revocation Request + credential_revocation_request = { + "vc_id": "ID of the VC to be revoked", + "pop_jwt": "PoP JWT signed with the private key associated with the VC" + } - -Implementation considerations ------------------------------ + # Step 2: Send Request to VC Issuer + response = send_request_to_vc_issuer(credential_revocation_request) -TODO + # Step 3: VC Issuer verifies the PoP + is_pop_valid = verify_pop(credential_revocation_request["pop_jwt"]) + if is_pop_valid: + # Step 4: Revoke VC + revoke_vc(credential_revocation_request["vc_id"]) + + # Step 5: Send Response + response = { + "status": "success", + "message": "VC revoked successfully" + } + else: + response = { + "status": "failure", + "message": "PoP verification failed" + } -Libraries and code snippets ---------------------------- -TODO External references ------------------- -TODO +- OpenID for Verifiable Presentations - draft 20 _ +- OAuth 2.0 Demonstrating Proof-of-Possession at the Application Layer (DPoP) _ +- Dynamic status lists _ +- JWT and CWT Status List _ From ee0f26167efe6d95a02ff40d0572e5d54516987d Mon Sep 17 00:00:00 2001 From: Giuseppe De Marco Date: Mon, 16 Oct 2023 17:01:21 +0200 Subject: [PATCH 02/28] Non-Revocation Issuance flow and Revocation request flow baseline --- docs/en/revocation-lists.rst | 210 +++++++++++++---------------------- 1 file changed, 76 insertions(+), 134 deletions(-) diff --git a/docs/en/revocation-lists.rst b/docs/en/revocation-lists.rst index 05f2305f4..9893670fc 100644 --- a/docs/en/revocation-lists.rst +++ b/docs/en/revocation-lists.rst @@ -2,130 +2,99 @@ .. _revocation-lists: -Credential validity and non-revocation attestations -+++++++++++++++++++++++++++++++++++++++++++++++++++ +Credential Revocations +++++++++++++++++++++++ -This section outlines the key technical requirements and processes related to the validity and non-revocation of digital credentials. It provides a comprehensive guide on how to manage, verify, and revoke digital credentials in a secure and reliable manner. +The value of digital credentials is contingent on their validity. +A credential that has been revoked, due to legal requirements, inaccuracy or compromise, is not only valueless but potentially harmful. +For these reason a robust mechanism for managing the validity and revocation of digital credentials is required. -The value of verifiable credentials is contingent on their validity. A credential that has been revoked, due to legal requirements, inaccuracy or compromise, is not only valueless but potentially harmful. Therefore, robust mechanisms for managing the validity and revocation of credentials are crucial. +This section outlines the key technical requirements and processes related to the revocation of the digital credentials. +Furthermore, it provides the technical details that the Relying Parties MUST implement to verify, in a secure and reliable manner, +the validity of a digital credential during the presentation phase. -This section is structured into several subsections, each addressing a different aspect of credential validity and revocation. +This section is structured into several subsections, these are listed below. -The "Key Technical Requirements" subsection outlines the fundamental requirements for managing credential validity and revocation. These requirements define the roles and responsibilities of the Authentic Source, the Issuer, and the Wallet Instance in ensuring the validity of credentials and managing their revocation. - -The "Presentation" and "Issuance" subsections describe the processes by which a Wallet Instance responds to a presentation request and initiates a request for a digital credential, respectively. These subsections detail how a non-revocation attestation, a proof that the credential has not been revoked, is created, presented, and validated. - -The "Non-Revocation Attestation Renewal Flow" and "Credential Revocation Flow" subsections provide detailed workflows for renewing a non-revocation attestation and revoking a credential, respectively. These workflows include the generation and verification of a Proof of Possession (PoP) JWT, which proves that the Wallet Instance possesses the private key associated with the VC. +* The "Key Technical Requirements" subsection outlines the fundamental requirements for managing digital credential revocation. These requirements define the roles and responsibilities of the Authentic Source, the Issuer, and the Wallet Instance in ensuring the validity of credentials and managing their revocation. +* The "Presentation" subsection describe the processes by which a Wallet Instance and a Relying Party interacts with each other to demonstrate and verify the non-revocation status of the presented digital credentials. These subsections detail how a Non-Revocation Attestation, in the form of a cryptographic proof that the credential has not been revoked, is created, provided, and validated. +* The "Non-Revocation Attestation Renewal Flow" and "Credential Revocation Flow" subsections provide detailed workflows for renewing a Non-Revocation Attestation and revoking a credential, respectively. These workflows include the generation and verification of a Proof of Possession (PoP) JWT, which proves that the Wallet Instance possesses the private key associated with the digital credential. Key Technical Requirements --------------------------- -- The Authentic Source MUST be the only source of truth for credential validity. All revocation requests MUST be communicated to the Authentic Source using appropriate channels. These requests MAY come from: - - The citizen (Holder) via their personal Wallet Instance. - - The citizen via a legal entity (e.g., Police for reporting). - - The citizen directly via the Authentic Source. - - The Authentic Source itself (e.g., for attribute updates). - - A legal entity (e.g., Police for seizure). -- The Authentic Source MUST maintain a record of the issuers who have issued a certain credential. -- The Issuer MUST provide information about a callback hook for revocation. -- The Authentic Source MUST manage the revocation of issued credentials by notifying the respective issuers. -- The Authentic Source MUST maintain a mapping between ID_CREDENTIAL and ID_ISSUER to facilitate credential revocation even in case of Wallet Instance loss. -- The revocation MUST be verifiable via a cryptographic signature. +- The Authentic Source is the provider of the data necessary for the issuance of a digital credential requested by PID/(Q)EAA Provider. +- The revocation requests MAY be communicated to PID/(Q)EAA Provider by Users using their personal Wallet Instance (Holder). +- The revocation requests MAY be communicated to Authentic Source from the following entities: + - A legal entity (e.g., Police for reporting) on behalf of the User. + - The Authentic Source itself (e.g., for attribute updates) following administrative purposes. + - A legal entity for the performance of their functions and any other judicial reasons (e.g., Police). +- The Authentic Source MUST maintain a record of the PID/(Q)EAA Provider who have requested the User's data for the issuance of the digital credential related to the User. +- The PID/(Q)EAA Provider MUST provide a protected web endpoint where the Authentic Source MAY notify any updates related to the User's data, having the Authentic Source the record of PID/(Q)EAA Providers that have requested Users data for the issuance of the digital credentials. +- The PID/(Q)EAA Provider MUST provide to the Holder the non-revocations attestation related to the digital credential it has issued to the Holder. +- The Non-Revocation Attestation provides the proof about the non-revocation of the digital credential which is related to. +- The Non-Revocation Attestation MUST be verifiable with a cryptographic signature. +- The Non-Revocation Attestation does not reveal any information about the Relying Party or the User's data contained in the digital credential the attestation is related to. -Presentation ------------- +Presentation Phase +------------------ -The Wallet Instance responds to a presentation request from the Relying Party. It produces a Verifiable Presentation (VP) token with the digital credential and a non-revocation attestation. This attestation is a proof that the credential has not been revoked. +The Wallet Instance, according to the presentation request from the Relying Party, +produces a Verifiable Presentation (VP) token with the digital credential +and a Non-Revocation Attestation. This attestation is the proof that the credential has not been revoked. -It is timestamped with the request date and always refers to a previous period. Importantly, this attestation does not reveal any information about the Relying Party. The Relying Party then evaluates and validates the response, the VP token, and the non-revocation attestation. +The Relying Party MUST validate the VP token and the Non-Revocation Attestation to certify the validity of a digital credential. -Issuance --------- +Non-revocation Attestation Issuance +----------------------------------- -The Wallet Instance initiates a request for a digital credential from the Credential Issuer. +The Wallet Instance sends a request for a digital credential to the PID/(Q)EAA Provider. Upon successful request, the Wallet Instance receives: -- The digital credential -- A non-revocation attestation +* The digital credential; +* a Non-Revocation Attestation. -The non-revocation attestation is presented in conjunction with the credential. The attestation is timestamped with the request date, not the authentication date, and always refers to a previous period. -Relying Parties determine the validity duration of this attestation based on the specific use case. -By default, an attestation is considered valid if issued within the previous 350 hours. This provision supports offline use cases and potential disruptions or incidents in the certification systems. Note that this delay only refers to the non-revocation of the credential, while the validity of the credential itself can always be verified. +The Non-Revocation Attestation MUST be presented in conjunction with the digital credential. The Non-Revocation Attestation MUST be timestamped with its issuance datetime, always referring to a previous period. +The Non-Revocation Attestation MUST contain the expiration datetime after which the digital credential MUST NOT be considered valid anymore. +Relying Parties determine the validity duration of the Non-Revocation Attestation based. +The Non-Revocation Attestation enables offline use cases and potential unavailability of the in the non-revocation certification systems. -Non-Revocation Attestation Renewal Flow ---------------------------------------- +Non-Revocation Attestation Flow +------------------------------- .. code-block:: mermaid sequenceDiagram participant WalletInstance as Wallet Instance - participant VCIssuer as VC Issuer - WalletInstance->>VCIssuer: Send Non-Revocation Attestation Renewal Request - VCIssuer->>VCIssuer: Verify credential PoP - VCIssuer->>VCIssuer: Renew Non-Revocation Attestation (if PoP is valid) - VCIssuer->>WalletInstance: Send Response - -1. **Non-Revocation Attestation Renewal Request**: The Wallet Instance initiates the process by creating a Non-Revocation Attestation Renewal Request. This request includes the ID of the VC for which the non-revocation attestation is to be renewed and a PoP JWT. The PoP JWT is signed with the private key associated with the VC, and includes claims such as `iss`, `aud`, `exp`, `iat`, and `jti`. - -2. **Send Request to VC Issuer**: The Wallet Instance sends the Non-Revocation Attestation Renewal Request to the VC Issuer's renewal endpoint. The request is authenticated using the PoP JWT (see [Proof of Possession (PoP) JWT generation process](#proof-of-possession-pop-jwt-generation-process)), which proves that the Wallet Instance possesses the private key associated with the VC. - -3. **Verify PoP**: The VC Issuer verifies the PoP by checking the signature of the PoP JWT using the public key that was used when the VC was issued. If the verification is successful, it means that the Wallet Instance possesses the private key associated with the VC, and therefore has the authority to request its renewal. - -4. **Renew Non-Revocation Attestation**: If the PoP is verified successfully, the VC Issuer renews the non-revocation attestation for the VC identified by the ID in the Non-Revocation Attestation Renewal Request. - -5. **Send Response**: The VC Issuer sends a response back to the Wallet Instance indicating the result of the renewal request. If the renewal was successful, the response includes the renewed non-revocation attestation. - -.. code-block:: python - - # Step 1: Create Non-Revocation Attestation Renewal Request - attestation_renewal_request = { - "vc_id": "ID of the VC to be renewed", - "pop_jwt": "PoP JWT signed with the private key associated with the VC" - } + participant digital credentialIssuer as PID/(Q)EAA Provider + WalletInstance->>digital credentialIssuer: Send Non-Revocation Attestation Request
providing the digital credentials and
the cryptoghraphic proof of possession of it. + digital credentialIssuer->>digital credentialIssuer: Verify digital credential PoP + digital credentialIssuer->>digital credentialIssuer: Creates the Non-Revocation Attestation
(if the previous step is valid) + digital credentialIssuer->>WalletInstance: Send Response containing the Non-Revocation Attestation - # Step 2: Send Request to VC Issuer - response = send_request_to_vc_issuer(attestation_renewal_request) +1. **Non-Revocation Attestation Request**: The Wallet Instance initiates the process by creating a Non-Revocation Attestation Request. This request includes the digital credential for which the Non-Revocation Attestation is related to and a PoP JWT. The PoP JWT is signed with the private key associated with the digital credential, and MUST include claims such as `iss`, `aud`, `exp`, `iat`, and `jti`. - # Step 3: VC Issuer verifies the PoP - is_pop_valid = verify_pop(attestation_renewal_request["pop_jwt"]) +2. **Send Request to PID/(Q)EAA Provider**: The Wallet Instance sends the Non-Revocation Attestation Request to the PID/(Q)EAA Provider Non-Revocation issuance endpoint. The Holder is authenticated using the PoP JWT (see [Proof of Possession (PoP) JWT generation process](#proof-of-possession-pop-jwt-generation-process)), which proves that the Wallet Instance possesses the private key associated with the digital credential. - if is_pop_valid: - # Step 4: Renew Non-Revocation Attestation - renew_attestation(attestation_renewal_request["vc_id"]) - - # Step 5: Send Response - response = { - "status": "success", - "message": "Non-revocation attestation renewed successfully" - } - else: - response = { - "status": "failure", - "message": "PoP verification failed" - } +3. **Verify PoP**: The PID/(Q)EAA Provider verifies the PoP by checking the signature of the PoP JWT using the public key that was used when the digital credential was issued. If the verification is successful, it means that the Wallet Instance possesses the private key associated with the digital credential, and therefore has the authority to request its renewal. +4. **Renew Non-Revocation Attestation**: If the PoP is verified successfully, the PID/(Q)EAA Provider renews the Non-Revocation Attestation with the digital credential included in the Non-Revocation Attestation Renewal Request. -Upon successful request, the Wallet Instance receives: -- The renewed non-revocation attestation - -This process ensures that the Wallet Instance is the legitimate owner of the digital credential and has the authority to request its renewal. It does so by signing the request and having the Issuer verify this signature using the corresponding public key. This ensures that the Wallet Instance is authenticated and has a PID. - -Proof of Possession (PoP) JWT generation process ------------------------------------------------- +5. **Send Response**: The PID/(Q)EAA Provider sends a response back to the Wallet Instance indicating the result of the request. If the renewal is successful, the response includes the renewed Non-Revocation Attestation. If not, the response includes an error message describing the unavailability of the Non-Revocation Attestation and any additional information about the cause of that MAY be included in the `error_description`. -The Wallet Instance generates a Proof of Possession (PoP) JWT as follows: +Upon successful request, the Wallet Instance receives the Non-Revocation Attestation. -1. **Create PKCE code verifier**: The Wallet Instance creates a fresh PKCE code verifier, Wallet Instance Attestation Proof of Possession, and ``state`` parameter for the *Pushed Authorization Request*. +This process ensures that the Wallet Instance is the legitimate owner of the digital credential and has the authority to request its Non-Revocation Attestation. It does so by signing the request and having the Issuer verify this signature using the corresponding public key boun with the related digital credetial. This ensures that the Wallet Instance is authenticated and has the digital credential which is requesting the Non-Revocation Attestation. -2. **Send parameters to PID/(Q)EAA Provider**: The Wallet Instance provides these parameters to the PID/(Q)EAA Provider PAR endpoint using the ``request`` parameter to prevent Request URI swapping attack. +Non-Revocation Attestation Request +---------------------------------- -3. **Generate code_verifier**: The Wallet Instance must create the ``code_verifier`` with enough entropy random string using the unreserved characters with a minimum length of 43 characters and a maximum length of 128 characters. This makes it impractical for an attacker to guess its value. The value must be generated following the recommendation in Section 4.1 of :rfc:`7636`. +The Wallet Instance provides the parameters listed below to the PID/(Q)EAA Provider Non-Revocation Attestation endpoint using the ``request`` parameter to prevent Request URI swapping attack. -4. **Sign the request**: The Wallet Instance signs this request using the private key that was created during the setup phase to obtain the Wallet Instance Attestation. The related public key that is attested by the Wallet Provider is provided within the Wallet Instance Attestation ``cnf`` claim. +The Wallet Instance signs the signed request using the private key that was created to obtain the digital credential, as provided within the digital credential ``cnf.jwk`` claim. -5. **Create PoP**: The Proof of Possession JWT contains a JOSE header with ``alg``, ``kid``, and ``typ`` parameters, and a body with ``iss``, ``aud``, ``exp``, ``iat``, and ``jti`` claims. +The signed request JWT contains a JOSE header with ``alg``, ``kid``, and ``typ`` parameters, and a body with ``iss``, ``aud``, ``exp``, ``iat``, and ``jti`` claims. - ``alg``: A digital signature algorithm identifier such as per IANA "JSON Web Signature and Encryption Algorithms" registry. It MUST be one of the supported algorithms listed in the Section `Cryptographic Algorithms `_ and MUST NOT be set to ``none`` or any symmetric algorithm (MAC) identifier. - ``kid``: Unique identifier of the ``jwk`` inside the ``cnf`` claim of Wallet Instance Attestation as base64url-encoded JWK Thumbprint value. @@ -136,65 +105,38 @@ The Wallet Instance generates a Proof of Possession (PoP) JWT as follows: - ``iat``: UNIX Timestamp with the time of JWT issuance. - ``jti``: Unique identifier for the DPoP proof JWT. The value SHOULD be set using a *UUID v4* value according to RFC 4122. -6. **Set client_assertion parameter**: The ``client_assertion`` parameter in the Token Request is set to a value containing the Wallet Instance Attestation and the Proof of Possession, separated with the ``~`` character. +The PID/(Q)EAA Provider MUST verify the Proof of Possession by checking the signature of the request using the public key provided in the digital credential ``cnf.jwk`` claim. -7. **Verify PoP**: The PID/(Q)EAA Provider then verifies the Proof of Possession by checking the signature of the request using the public key provided in the Wallet Instance Attestation ``cnf`` claim. - -Credential Revocation Flow --------------------------- +TBD: the typ value in the JWT header configuring the content type of the request (Non-Revocation Attestation request). + +Credential Revocation Request Flow +---------------------------------- .. code-block:: mermaid sequenceDiagram participant WalletInstance as Wallet Instance - participant VCIssuer as Issuer - WalletInstance->>VCIssuer: Send Credential Revocation Request - VCIssuer->>VCIssuer: Verify credential PoP - VCIssuer->>VCIssuer: Revoke VC (if PoP is valid) - VCIssuer->>WalletInstance: Send Response - -1. **Credential Revocation Request**: The Wallet Instance initiates the process by creating a Credential Revocation Request. This request includes the ID of the VC to be revoked and a PoP JWT. The PoP JWT is signed with the private key associated with the VC to be revoked, and includes claims such as `iss`, `aud`, `exp`, `iat`, and `jti`. - -2. **Send Request to VC Issuer**: The Wallet Instance sends the Credential Revocation Request to the VC Issuer's revocation endpoint. The request is authenticated using the PoP JWT, which proves that the Wallet Instance possesses the private key associated with the VC. - -3. **Verify PoP**: The VC Issuer verifies the PoP by checking the signature of the PoP JWT using the public key that was used when the VC was issued. If the verification is successful, it means that the Wallet Instance possesses the private key associated with the VC, and therefore has the authority to request its revocation. - -4. **Revoke VC**: If the PoP is verified successfully, the VC Issuer revokes the VC identified by the ID in the Credential Revocation Request. - -5. **Send Response**: The VC Issuer sends a response back to the Wallet Instance indicating the result of the revocation request. If the revocation was successful, the response includes a confirmation of the revocation. + participant digital credentialIssuer as PID/(Q)EAA Provider + WalletInstance->>digital credentialIssuer: Send Non-Revocation Attestation Request + digital credentialIssuer->>digital credentialIssuer: Verify credential PoP + digital credentialIssuer->>digital credentialIssuer: Revoke digital credential (if PoP is valid) + digital credentialIssuer->>WalletInstance: Send Response -Here's a code block that outlines the flow: +1. **Credential Revocation Request**: The Wallet Instance initiates the process by creating a Credential Revocation Request. This request includes the ID of the digital credential to be revoked and a PoP JWT. The PoP JWT is signed with the private key associated with the digital credential to be revoked, and includes claims such as `iss`, `aud`, `exp`, `iat`, and `jti`. -.. code-block:: python +2. **Send Request to PID/(Q)EAA Provider**: The Wallet Instance sends the Credential Revocation Request to the PID/(Q)EAA Provider's revocation endpoint. The request is authenticated using the PoP JWT, which proves that the Wallet Instance possesses the private key associated with the digital credential. - # Step 1: Create Credential Revocation Request - credential_revocation_request = { - "vc_id": "ID of the VC to be revoked", - "pop_jwt": "PoP JWT signed with the private key associated with the VC" - } +3. **Verify PoP**: The PID/(Q)EAA Provider verifies the PoP by checking the signature of the PoP JWT using the public key that was used when the digital credential was issued. If the verification is successful, it means that the Wallet Instance possesses the private key associated with the digital credential, and therefore has the authority to request its revocation. - # Step 2: Send Request to VC Issuer - response = send_request_to_vc_issuer(credential_revocation_request) +4. **Revoke digital credential**: If the PoP is verified successfully, the PID/(Q)EAA Provider revokes the digital credential identified by the ID in the Credential Revocation Request. - # Step 3: VC Issuer verifies the PoP - is_pop_valid = verify_pop(credential_revocation_request["pop_jwt"]) +5. **Send Response**: The PID/(Q)EAA Provider sends a response back to the Wallet Instance indicating the result of the revocation request. If the revocation was successful, the response includes a confirmation of the revocation. - if is_pop_valid: - # Step 4: Revoke VC - revoke_vc(credential_revocation_request["vc_id"]) - - # Step 5: Send Response - response = { - "status": "success", - "message": "VC revoked successfully" - } - else: - response = { - "status": "failure", - "message": "PoP verification failed" - } +Digital Credential Revocation Request +------------------------------------- +TBD. External references From f4bdf25064fa7d74846f76859827d742c64409fe Mon Sep 17 00:00:00 2001 From: Giuseppe De Marco Date: Mon, 16 Oct 2023 17:51:51 +0200 Subject: [PATCH 03/28] fix: Non-Revocation Issuance flow and Revocation request flow baseline - peppelinux and fmarino pair --- docs/en/revocation-lists.rst | 117 ++++++++++++++++++++++++----------- 1 file changed, 81 insertions(+), 36 deletions(-) diff --git a/docs/en/revocation-lists.rst b/docs/en/revocation-lists.rst index 9893670fc..50bcb0467 100644 --- a/docs/en/revocation-lists.rst +++ b/docs/en/revocation-lists.rst @@ -7,7 +7,7 @@ Credential Revocations The value of digital credentials is contingent on their validity. A credential that has been revoked, due to legal requirements, inaccuracy or compromise, is not only valueless but potentially harmful. -For these reason a robust mechanism for managing the validity and revocation of digital credentials is required. +For these reasons a robust mechanism for managing the validity and revocation of digital credentials is required. This section outlines the key technical requirements and processes related to the revocation of the digital credentials. Furthermore, it provides the technical details that the Relying Parties MUST implement to verify, in a secure and reliable manner, @@ -15,13 +15,23 @@ the validity of a digital credential during the presentation phase. This section is structured into several subsections, these are listed below. -* The "Key Technical Requirements" subsection outlines the fundamental requirements for managing digital credential revocation. These requirements define the roles and responsibilities of the Authentic Source, the Issuer, and the Wallet Instance in ensuring the validity of credentials and managing their revocation. -* The "Presentation" subsection describe the processes by which a Wallet Instance and a Relying Party interacts with each other to demonstrate and verify the non-revocation status of the presented digital credentials. These subsections detail how a Non-Revocation Attestation, in the form of a cryptographic proof that the credential has not been revoked, is created, provided, and validated. -* The "Non-Revocation Attestation Renewal Flow" and "Credential Revocation Flow" subsections provide detailed workflows for renewing a Non-Revocation Attestation and revoking a credential, respectively. These workflows include the generation and verification of a Proof of Possession (PoP) JWT, which proves that the Wallet Instance possesses the private key associated with the digital credential. +* The "General Assumptions" subsection outlines ... +* The "Requirements" subsection outlines fundamental requirements for managing digital credential revocation, ...outlining general, privacy and security requirements. +* The "Entities Involved in the Revocation Flows" ... the roles and responsibilities of the Authentic Source, the Issuer, and the Wallet Instance in ensuring the validity of credentials and managing their revocation. +* The "High Level Revocation Flow" subsection outlines ... +* The "Revocation Wallet Instance Request" subsections outlines ... +* The "High Level Non-Revocation Attestations Flows" subsection outlines ... +* The "Non-Non-Revocation Proof during the Presentation Phase" subsection describes the processes by which a Wallet Instance and a Relying Party interacts with each other to demonstrate and verify the Non-Revocation Attestation of the presented digital credentials. These subsections detail how a Non-Revocation Attestation, in the form of a cryptographic proof that the credential has not been revoked, is created, provided, and validated. -Key Technical Requirements ---------------------------- +General Assumptions +------------------- + +TBD. + + +Requirements +------------ - The Authentic Source is the provider of the data necessary for the issuance of a digital credential requested by PID/(Q)EAA Provider. - The revocation requests MAY be communicated to PID/(Q)EAA Provider by Users using their personal Wallet Instance (Holder). @@ -37,17 +47,58 @@ Key Technical Requirements - The Non-Revocation Attestation does not reveal any information about the Relying Party or the User's data contained in the digital credential the attestation is related to. -Presentation Phase ------------------- +Entities Involved in the Revocation Flows +----------------------------------------- -The Wallet Instance, according to the presentation request from the Relying Party, -produces a Verifiable Presentation (VP) token with the digital credential -and a Non-Revocation Attestation. This attestation is the proof that the credential has not been revoked. +TBD. -The Relying Party MUST validate the VP token and the Non-Revocation Attestation to certify the validity of a digital credential. -Non-revocation Attestation Issuance ------------------------------------ +High Level Revocation Flow +-------------------------- + +TBD. + +All the flows and use cases not defind in the subsequent section is considered out of scope for this technical implementation profile. + + +Revocation Wallet Instance Request +---------------------------------- + +.. code-block:: mermaid + + sequenceDiagram + participant WalletInstance as Wallet Instance + participant digital credentialIssuer as PID/(Q)EAA Provider + WalletInstance->>digital credentialIssuer: Send Non-Revocation Attestation Request + digital credentialIssuer->>digital credentialIssuer: Verify credential PoP + digital credentialIssuer->>digital credentialIssuer: Revoke digital credential (if PoP is valid) + digital credentialIssuer->>WalletInstance: Send Response + +1. **Credential Revocation Request**: The Wallet Instance initiates the process by creating a Credential Revocation Request. This request includes the ID of the digital credential to be revoked and a PoP JWT. The PoP JWT is signed with the private key associated with the digital credential to be revoked, and includes claims such as `iss`, `aud`, `exp`, `iat`, and `jti`. + +2. **Send Request to PID/(Q)EAA Provider**: The Wallet Instance sends the Credential Revocation Request to the PID/(Q)EAA Provider's revocation endpoint. The request is authenticated using the PoP JWT, which proves that the Wallet Instance possesses the private key associated with the digital credential. + +3. **Verify PoP**: The PID/(Q)EAA Provider verifies the PoP by checking the signature of the PoP JWT using the public key that was used when the digital credential was issued. If the verification is successful, it means that the Wallet Instance possesses the private key associated with the digital credential, and therefore has the authority to request its revocation. + +4. **Revoke digital credential**: If the PoP is verified successfully, the PID/(Q)EAA Provider revokes the digital credential identified by the ID in the Credential Revocation Request. + +5. **Send Response**: The PID/(Q)EAA Provider sends a response back to the Wallet Instance indicating the result of the revocation request. If the revocation was successful, the response includes a confirmation of the revocation. + + +Credential Revocation Request +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +TBD. + + +Credential Revocation Response +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +TBD. + + +High Level Non-Revocation Attestations Flows +-------------------------------------------- The Wallet Instance sends a request for a digital credential to the PID/(Q)EAA Provider. @@ -60,9 +111,6 @@ The Non-Revocation Attestation MUST contain the expiration datetime after which Relying Parties determine the validity duration of the Non-Revocation Attestation based. The Non-Revocation Attestation enables offline use cases and potential unavailability of the in the non-revocation certification systems. -Non-Revocation Attestation Flow -------------------------------- - .. code-block:: mermaid sequenceDiagram @@ -87,8 +135,11 @@ Upon successful request, the Wallet Instance receives the Non-Revocation Attesta This process ensures that the Wallet Instance is the legitimate owner of the digital credential and has the authority to request its Non-Revocation Attestation. It does so by signing the request and having the Issuer verify this signature using the corresponding public key boun with the related digital credetial. This ensures that the Wallet Instance is authenticated and has the digital credential which is requesting the Non-Revocation Attestation. +TBD. + + Non-Revocation Attestation Request ----------------------------------- +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The Wallet Instance provides the parameters listed below to the PID/(Q)EAA Provider Non-Revocation Attestation endpoint using the ``request`` parameter to prevent Request URI swapping attack. @@ -109,34 +160,28 @@ The PID/(Q)EAA Provider MUST verify the Proof of Possession by checking the sign TBD: the typ value in the JWT header configuring the content type of the request (Non-Revocation Attestation request). -Credential Revocation Request Flow ----------------------------------- -.. code-block:: mermaid +Non-Revocation Attestation Response +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - sequenceDiagram - participant WalletInstance as Wallet Instance - participant digital credentialIssuer as PID/(Q)EAA Provider - WalletInstance->>digital credentialIssuer: Send Non-Revocation Attestation Request - digital credentialIssuer->>digital credentialIssuer: Verify credential PoP - digital credentialIssuer->>digital credentialIssuer: Revoke digital credential (if PoP is valid) - digital credentialIssuer->>WalletInstance: Send Response +TBD. -1. **Credential Revocation Request**: The Wallet Instance initiates the process by creating a Credential Revocation Request. This request includes the ID of the digital credential to be revoked and a PoP JWT. The PoP JWT is signed with the private key associated with the digital credential to be revoked, and includes claims such as `iss`, `aud`, `exp`, `iat`, and `jti`. -2. **Send Request to PID/(Q)EAA Provider**: The Wallet Instance sends the Credential Revocation Request to the PID/(Q)EAA Provider's revocation endpoint. The request is authenticated using the PoP JWT, which proves that the Wallet Instance possesses the private key associated with the digital credential. +Non-Revocation Attestation +^^^^^^^^^^^^^^^^^^^^^^^^^^ -3. **Verify PoP**: The PID/(Q)EAA Provider verifies the PoP by checking the signature of the PoP JWT using the public key that was used when the digital credential was issued. If the verification is successful, it means that the Wallet Instance possesses the private key associated with the digital credential, and therefore has the authority to request its revocation. +TBD. -4. **Revoke digital credential**: If the PoP is verified successfully, the PID/(Q)EAA Provider revokes the digital credential identified by the ID in the Credential Revocation Request. -5. **Send Response**: The PID/(Q)EAA Provider sends a response back to the Wallet Instance indicating the result of the revocation request. If the revocation was successful, the response includes a confirmation of the revocation. +Non-Revocation Proof during the Presentation Phase +-------------------------------------------------- +The Wallet Instance, according to the presentation request from the Relying Party, +produces a Verifiable Presentation (VP) token with the digital credential +and a Non-Revocation Attestation. This attestation is the proof that the credential has not been revoked. -Digital Credential Revocation Request -------------------------------------- +The Relying Party MUST validate the VP token and the Non-Revocation Attestation to certify the validity of a digital credential. -TBD. External references From 86977c6b3e34a053effe75e281c7e85792dc4765 Mon Sep 17 00:00:00 2001 From: fmarino-ipzs Date: Mon, 16 Oct 2023 18:17:20 +0200 Subject: [PATCH 04/28] Update revocation-lists.rst --- docs/en/revocation-lists.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/en/revocation-lists.rst b/docs/en/revocation-lists.rst index 50bcb0467..95f3d264c 100644 --- a/docs/en/revocation-lists.rst +++ b/docs/en/revocation-lists.rst @@ -85,6 +85,8 @@ Revocation Wallet Instance Request 5. **Send Response**: The PID/(Q)EAA Provider sends a response back to the Wallet Instance indicating the result of the revocation request. If the revocation was successful, the response includes a confirmation of the revocation. +https://www.plantuml.com/plantuml/uml/TPB1RXCn48RlynGZYmEeTRffTXCIAQWe1Ib5QYkAoDbTJyFGZMtiIG92l3lsDbH1YDDQytqQ_Vwz5qbCbEscWv2_t78mJb2jJDUHuD9bx5fIQ1Bk-MzdcTAMOeyO0EPp_4WxtnfXx_BnsvQIu7mEi6VKRv1dnpmU-ClLyYqATvRmzkRs52zvpM8wN4Iov8JpyMhrgR1NuBmG-Xr5PFY_1py1KPbkhMQetjsTDsDrMYRo8vH9VCwW3nbElkxbINbaMvGNEPDUNB_NLwiFoqi5y0i6PQlYb0glxkjHtOmgJSDcgEkshlJqzVr4J-fsqfY67YRZgYnKPjll-o8IqkpiBB3L8VeTMue3-cuseQE1Z-lUPIFP7JPLFPvEXwDncJtukEd7QjUU9AiFGLNxVEa-xjD3w3jUEx8wrw1oOY1diJG6yAV-pwPZQuImt2ytzIyuQhFm8cHZdvMRHpolwlo2ANYN2AyzBhoJB0F01JcRVw7V + Credential Revocation Request ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ From f13dc467a935ced1573fa751c771f35b774f5cc2 Mon Sep 17 00:00:00 2001 From: fmarino-ipzs Date: Mon, 16 Oct 2023 18:40:13 +0200 Subject: [PATCH 05/28] Update revocation-lists.rst --- docs/en/revocation-lists.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/en/revocation-lists.rst b/docs/en/revocation-lists.rst index 95f3d264c..fbad1b6c9 100644 --- a/docs/en/revocation-lists.rst +++ b/docs/en/revocation-lists.rst @@ -139,6 +139,7 @@ This process ensures that the Wallet Instance is the legitimate owner of the dig TBD. +https://www.plantuml.com/plantuml/uml/dLDHRzem67pth_XaxM5JwpIC10OIKn4mDTt6AaB7O-Kc7yHjSBBO8Pqc_llia45HHn_wXBcxVBxlJhvKcXUwNASaDxyY4ZcN6kY2fobg2AIXPOGKk89A76i2fKeiQaeGGWO3c6QIpN2JHLoBJC9GQrHwTvxXhzByWS60a4e0-moY_vg-QFJl5y4Gj4XZX9iVD-Sm5YkXUGgZ0cEKMfZZzM9kkGz4PXeXss01WfpMaJy4WF9qHVj09-57lqFFBQ9_vnQHnbEnzyJumHDhF9qzL7htoQE8xIVlZ4SscdvXruklmPWIiYMElOKAfIpltdjjps-x35j-YtcHvxBUf_ikwtfHr-S-BhiTrmwalApd9LhdgdznaOkOvKMs4J4M3ZxnTPwYanMhMYkuDjgMxtgTNg_LxbXicHNh6gQRw4p5h35Aetq8jTrTSImKAuanCx5GuvYWZC4cICY_UdxoLCHS8zZzJ78lYMVfMdulCBYbZxE4PrdQCiXHOMzjvMKRGHZUJcQdodXpkFYKDrZNTGrs7EnTmbLINp-QJSQJwJmOVcDNm_2A_aTtr-of4iwQJMaabmQoAG1zg1xjsN6SBH3OsdRc2OAHWA5WmzCIuVjjE0TJTvH09NG2sYWoYT0i5GEni90rKM3AjS7YvbaS31rwh-ip_LMcm1cgF9CAwz6dtsdJ8o6NPagvJly2 Non-Revocation Attestation Request ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ From 2e8180910a3f79f17a7c7dfeb36c1770a24994c6 Mon Sep 17 00:00:00 2001 From: Giuseppe De Marco Date: Mon, 16 Oct 2023 19:17:50 +0200 Subject: [PATCH 06/28] Revocations: plantuml flows --- docs/en/revocation-lists.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/en/revocation-lists.rst b/docs/en/revocation-lists.rst index fbad1b6c9..e8a315fdb 100644 --- a/docs/en/revocation-lists.rst +++ b/docs/en/revocation-lists.rst @@ -85,7 +85,7 @@ Revocation Wallet Instance Request 5. **Send Response**: The PID/(Q)EAA Provider sends a response back to the Wallet Instance indicating the result of the revocation request. If the revocation was successful, the response includes a confirmation of the revocation. -https://www.plantuml.com/plantuml/uml/TPB1RXCn48RlynGZYmEeTRffTXCIAQWe1Ib5QYkAoDbTJyFGZMtiIG92l3lsDbH1YDDQytqQ_Vwz5qbCbEscWv2_t78mJb2jJDUHuD9bx5fIQ1Bk-MzdcTAMOeyO0EPp_4WxtnfXx_BnsvQIu7mEi6VKRv1dnpmU-ClLyYqATvRmzkRs52zvpM8wN4Iov8JpyMhrgR1NuBmG-Xr5PFY_1py1KPbkhMQetjsTDsDrMYRo8vH9VCwW3nbElkxbINbaMvGNEPDUNB_NLwiFoqi5y0i6PQlYb0glxkjHtOmgJSDcgEkshlJqzVr4J-fsqfY67YRZgYnKPjll-o8IqkpiBB3L8VeTMue3-cuseQE1Z-lUPIFP7JPLFPvEXwDncJtukEd7QjUU9AiFGLNxVEa-xjD3w3jUEx8wrw1oOY1diJG6yAV-pwPZQuImt2ytzIyuQhFm8cHZdvMRHpolwlo2ANYN2AyzBhoJB0F01JcRVw7V +https://www.plantuml.com/plantuml/uml/TP9HRzC-5CNV_IckhF_3firTkYRjlvMAXZgGEiGsqKAVtUIklJIrW-saJ0W-EzT9DuQ0frZtT-npdECh7xGBzRuK5NyffqgR07Abon83p0rZawC4xU50lslctjVeMaH2YEaKFc1ZSnt86bv-gT47c4w5E12eLq2JbzmT-Sbg_lh7_TtzELpJXe8kOUQmG1E8bpUh9J0x5SO61DkWOwT_wyGt0I1rkP4Ja6yMbzbGdiT9UApYn3sxgwFxsUT3w2GxAgBaFqwZPhTlrStgtVnQ2l5TzEAfahoFF5cdWpGR90hxML-bUPgeyV_haHgb-IZJ6JwCXaayKEgwFMyRGkKd5nSL5Qfojg42NG-_wdrLOi-wJQib7LZRpv9qE1xt1yCuUx1ktuvbav_vGXs3olpvqctShWAre8t1WaCl9ISMOhd5ltN17Dv_N2nXZU3RBTnfs49WUUMeqG5XXuyWm66f0-DWErYlIyfRbbiJD3rj9TFoNwdWf8i4NQHeUIe4cW9YXK8ylOHFkgGY-iKVpjNz2LxK6taKiEB0ahiTN2OftyfNrdY4MmipJiLYSSLE_9P_0W00 Credential Revocation Request ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -139,7 +139,7 @@ This process ensures that the Wallet Instance is the legitimate owner of the dig TBD. -https://www.plantuml.com/plantuml/uml/dLDHRzem67pth_XaxM5JwpIC10OIKn4mDTt6AaB7O-Kc7yHjSBBO8Pqc_llia45HHn_wXBcxVBxlJhvKcXUwNASaDxyY4ZcN6kY2fobg2AIXPOGKk89A76i2fKeiQaeGGWO3c6QIpN2JHLoBJC9GQrHwTvxXhzByWS60a4e0-moY_vg-QFJl5y4Gj4XZX9iVD-Sm5YkXUGgZ0cEKMfZZzM9kkGz4PXeXss01WfpMaJy4WF9qHVj09-57lqFFBQ9_vnQHnbEnzyJumHDhF9qzL7htoQE8xIVlZ4SscdvXruklmPWIiYMElOKAfIpltdjjps-x35j-YtcHvxBUf_ikwtfHr-S-BhiTrmwalApd9LhdgdznaOkOvKMs4J4M3ZxnTPwYanMhMYkuDjgMxtgTNg_LxbXicHNh6gQRw4p5h35Aetq8jTrTSImKAuanCx5GuvYWZC4cICY_UdxoLCHS8zZzJ78lYMVfMdulCBYbZxE4PrdQCiXHOMzjvMKRGHZUJcQdodXpkFYKDrZNTGrs7EnTmbLINp-QJSQJwJmOVcDNm_2A_aTtr-of4iwQJMaabmQoAG1zg1xjsN6SBH3OsdRc2OAHWA5WmzCIuVjjE0TJTvH09NG2sYWoYT0i5GEni90rKM3AjS7YvbaS31rwh-ip_LMcm1cgF9CAwz6dtsdJ8o6NPagvJly2 +https://www.plantuml.com/plantuml/uml/dPFHJzim4CRV_LUSh3ri0eTq9Er0waH5En6sCTIKzH6Pv6WCYPFPJWAQ-Dzdfu4MCNZWgUxttLq-tqy-qeOhKnSvgUolI4J5fG6wv7cE1Y9fRPaW1QwX5Szh8grhL9qb227ZCPoLaisnAHDkH2bXOWngipxFyKzj_y1uJ4WhW7q5SVXMlUhhFowZ2HYHfmZdlyvtOIfMml0SZXMcA8smnzFbmdcVY2mDGjcW0a5UhoD_2G3b-OeU0ft5dyCXtNMAkQ-S8cqczPI9yKqcrcVQkMdDkkLMfAxbWyt8Zi--iTFbzsXA2NaWdliA5LextxyAzeDmtsSu20SiI0AV7Nov6h5Ha8n27kBrQEYxWPJNtRpCc4eVxkrL8cMLAXkHelBmZXTLZbwfLbsjuCRM3a8_61uS3FQ7JhikLT79j4bsTChwe3HvMa8NTmsEnM8bCMLsBTGc9eiCmIsRonICFK-ZVc7myo9Um1M2xXe8jC9aNOdc1KAbHCCDmYtU4uAssM4Wv97nRvwBrFbkINRQ2sCRaVKtdLPtzdCWi0N44INRrD-DzYNIA8ulPlDNYBwV4DvLlJRo_LxRqBdCkCwwpn_FPzFPsIAQ_60da_Y4_gVkih-dpZZhRqeJUMqbjmMWD-sjEtkUzm047XuHsnAm5ZGyht6Djk0coJPKIudGNoe5ucGXEqDXpetLqlvjRG9jSNVuBB_M0foZhagfiHlzrcDt78_iYBh8_m40 Non-Revocation Attestation Request ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ From 03c99b53bacbbbfa51571e52837191c09dcf6996 Mon Sep 17 00:00:00 2001 From: fmarino-ipzs Date: Tue, 31 Oct 2023 17:49:21 +0100 Subject: [PATCH 07/28] chore: update revocation section --- docs/en/defined-terms.rst | 4 + docs/en/revocation-lists.rst | 455 ++++++++++++++---- .../Low-Level-Flow-Revocation-Attestation.svg | 1 + images/Low-Level-Flow-Revocation.svg | 1 + images/revocation-entity-relationship.svg | 3 + images/revocation-processes.svg | 3 + 6 files changed, 360 insertions(+), 107 deletions(-) create mode 100644 images/Low-Level-Flow-Revocation-Attestation.svg create mode 100644 images/Low-Level-Flow-Revocation.svg create mode 100644 images/revocation-entity-relationship.svg create mode 100644 images/revocation-processes.svg diff --git a/docs/en/defined-terms.rst b/docs/en/defined-terms.rst index 6f8e1c0e4..bd50efc47 100644 --- a/docs/en/defined-terms.rst +++ b/docs/en/defined-terms.rst @@ -29,6 +29,8 @@ Below are the description of acronyms and definitions which are useful for furth - An entity, recognized and accredited by the State, responsible for identifying citizens for the issuance of an Electronic Identity Certificate. * - Electronic Attestation of Identity - Electronic attestation of attributes referring to master data already present in Italian digital identity systems. + * - Digital Credential + - Electronic Attestation of Identity. * - Federation Authority - A public governance entity that issues guidelines and technical rules, and administers - directly or through its intermediary - Trusted Lists, services, and accreditation processes, the status of participants, and their eligibility evaluation. It also performs oversight functions. * - Wallet Instance @@ -37,6 +39,8 @@ Below are the description of acronyms and definitions which are useful for furth - All public and/or private entities, conforming to a technical profile and accredited by the Federation Authority, that provide citizens with an IT Wallet Instance. * - Wallet Instance Attestation - Verifiable Attestation, issued by the Wallet Provider, that proves the security compliace of the Wallet Instance. + * - Non-Revocation Attestation + - Verifiable Attestation, issued by the Issuer, proving that a related Digital Credential is not revoked. * - App Attestation Service - Device manufacturer service that allows you to certify the authenticity of the mobile app (Wallet Instance). * - Qualified Electronic Attestation of Attributes (QEAA) diff --git a/docs/en/revocation-lists.rst b/docs/en/revocation-lists.rst index e8a315fdb..297021ede 100644 --- a/docs/en/revocation-lists.rst +++ b/docs/en/revocation-lists.rst @@ -1,6 +1,6 @@ .. include:: ../common/common_definitions.rst -.. _revocation-lists: +.. _sec_revocation_intro: Credential Revocations ++++++++++++++++++++++ @@ -15,182 +15,423 @@ the validity of a digital credential during the presentation phase. This section is structured into several subsections, these are listed below. -* The "General Assumptions" subsection outlines ... -* The "Requirements" subsection outlines fundamental requirements for managing digital credential revocation, ...outlining general, privacy and security requirements. -* The "Entities Involved in the Revocation Flows" ... the roles and responsibilities of the Authentic Source, the Issuer, and the Wallet Instance in ensuring the validity of credentials and managing their revocation. -* The "High Level Revocation Flow" subsection outlines ... -* The "Revocation Wallet Instance Request" subsections outlines ... -* The "High Level Non-Revocation Attestations Flows" subsection outlines ... -* The "Non-Non-Revocation Proof during the Presentation Phase" subsection describes the processes by which a Wallet Instance and a Relying Party interacts with each other to demonstrate and verify the Non-Revocation Attestation of the presented digital credentials. These subsections detail how a Non-Revocation Attestation, in the form of a cryptographic proof that the credential has not been revoked, is created, provided, and validated. +* The :ref:`"General Assumptions" ` subsection outlines the main assumptions relevant to the design of a suitable solution for the main revocation scenarios. +* The :ref:`"Requirements" ` subsection outlines basic requirements, particularly regarding security and privacy aspects. +* The :ref:`"Entities Relationship" ` describes the roles and responsibilities of the main entities involved in ensuring the validity of credentials and managing their revocation. +* The :ref:`"High Level Revocation Flow" ` subsection outlines the main revocation scanarios and relevant processes. +* The :ref:`"Wallet Instance Initiated Revocation Flow" ` subsections outline how Wallet Instances request a revocation of a given credential to Issuers. +* The :ref:`"Non-Revocation Attestation Request" ` subsections decribe how the Wallet Instance interacts with the Issuer to obtain a Non-Revocation Attestation related to a credential own by the Holder. +* The :ref:`"Non-Revocation Proof during the Presentation Phase" ` subsection details how a Non-Revocation Attestation, in the form of a cryptographic proof that the credential has not been revoked, is provided by the Wallet Instance to the Verifier requesting a credential. + +.. _sec_revocation_assumption: + General Assumptions ------------------- -TBD. +A Credential Issuer is in charge of the creation and the issuance of credentials, its lifecycle, and ultimately, its validity status. Some credentials may have regulatory value given by national or european laws, therefore also revocations of credentials MUST be non-repudiable. +Some credentials may be a digital representation of a physical document issued, under a well defined national law, by an Authentic Source which, in the Wallet Ecosystem, acts as a repository or system that contains attributes and provides them to the Issuer. For this reason, an exchange of information between the two entities is required not only for the issuing the credential but also for the proper handling of its revocation. +Moreover, due to digital signature of the credentials, any updates on them MUST result in a re-issuance. +Finally, it is assumed that, to facilitate the association between physical document and digital credentials, the identifier of the physical document is always present as an attribute within the digital credentials. + +.. _sec_revocation_requirements: + Requirements ------------ -- The Authentic Source is the provider of the data necessary for the issuance of a digital credential requested by PID/(Q)EAA Provider. -- The revocation requests MAY be communicated to PID/(Q)EAA Provider by Users using their personal Wallet Instance (Holder). -- The revocation requests MAY be communicated to Authentic Source from the following entities: - - A legal entity (e.g., Police for reporting) on behalf of the User. - - The Authentic Source itself (e.g., for attribute updates) following administrative purposes. - - A legal entity for the performance of their functions and any other judicial reasons (e.g., Police). -- The Authentic Source MUST maintain a record of the PID/(Q)EAA Provider who have requested the User's data for the issuance of the digital credential related to the User. -- The PID/(Q)EAA Provider MUST provide a protected web endpoint where the Authentic Source MAY notify any updates related to the User's data, having the Authentic Source the record of PID/(Q)EAA Providers that have requested Users data for the issuance of the digital credentials. -- The PID/(Q)EAA Provider MUST provide to the Holder the non-revocations attestation related to the digital credential it has issued to the Holder. -- The Non-Revocation Attestation provides the proof about the non-revocation of the digital credential which is related to. -- The Non-Revocation Attestation MUST be verifiable with a cryptographic signature. -- The Non-Revocation Attestation does not reveal any information about the Relying Party or the User's data contained in the digital credential the attestation is related to. - - -Entities Involved in the Revocation Flows ------------------------------------------ +General Requirements +^^^^^^^^^^^^^^^^^^^^ + +- The Issuer MUST be the only responsible for the lifecycle of credentials including the revocation status. +- Credentials SHOULD be updates whenever one or more attributes are changed. +- Any credential update MUST result in a new fresh issuance of it, following the principle that the credential SHOULD always have updated data. In this case, the old Credentials of the same type MUST be revoked. +- The revocation of a credential for technical reasons (loss or theft of the device, compromise of cryptographic keys) MAY not have an impact on any other digital credentials issued of the same type and MUST NOT lead to the revocation of a physical document associated with it. +- The revocation of a physical document which one or more Credentials are associated with MUST result in their revocation. +- The revocation requests of a credential MAY be communicated to the Issuer by + + - Holders using their personal Wallet Instance. + - Authentic Sources (e.g., for attribute updates) following administrative purposes. + - Law-Enforcing Bodies for the fulfillment of their functions and any other judicial reasons (e.g., Police). +- The revocation requests of a physical document MAY be communicated to Authentic Source by: + + - A Law-Enforcing Body (e.g., Police) on behalf of the User or directly for the fulfillment of their functions and any other judicial reasons. + - The Holder using any out-of-band procedure in force by national regulations. +- The Authentic Source MUST provide an interface for the data sharing regarding the attributes update and revocation status of a physical document the credential is associated with. +- The Issuer MUST provide an interface handling the revocation flows (Revocation request/response, data access regarding the revocation status of a credential, etc.). +- The Issuer MUST provide the Wallet Instance with a proof of non-revocation of a given Holder's credential (Non-Revocation Attestation). +- The Holders MAY provide the Verifiers with a proof of non-revocation of their Credentials (Non-Revocation Attestations). +- The Verifiers MAY require a proof of non-revocation, even in the future after the credential presentation, for the fulfillment of their functions and for any other regulatory reasons (deferred). + + +Security Requirements +^^^^^^^^^^^^^^^^^^^^^ + +- The proof of non-revocation (Non-Revocation Attestation) MUST be cryptographically verifiable, so that it can be shown to have been issued by the Issuer and not to have been tampered with. +- The Non-Revocation Attestation MUST be non-repudiable even beyond its expiration time and even in the face of any rotations of the cryptographic keys. +- Granting of the proof of non-revocation (Non-Revocation Attestation) MUST be allowed only to authorized entities (e.g. by the Holder or by law). + + +Privacy Requirements +^^^^^^^^^^^^^^^^^^^^ + +- The Authentic Source MUST store in local databases only the minimum information required to notify the Issuer of a change in attributes or a change in the validity status of a physical document associated with one or more credentials. +- Access to credential status information by a Verifier MUST be authorized by the Holder, except for checks carried out by Law-Enforcement Bodies on a regulatory basis. +- The Issuer SHOULD not directly or indirectly have any information related to the Verifier, type of credentials, and Holder such that it is impossible to track the Holder's usage of the Credentials. +- A proof of non-revocation (Non-Revocation Attestation) provided by the Issuer, in whatever format it is, SHOULD NOT reveal any information about the Verifier nor the User's attributes contained in the credential the attestation is related to. -TBD. +.. _sec_revocation_entity_relationship: + +Entities Relationship +--------------------- + +The entities involved in the main revocation processes are depicted in the diagram below. + +.. _fig_revocation_entity_relationship: +.. figure:: ../../images/revocation-entity-relationship.svg + :figwidth: 80% + :align: center + + Entity-Relationship diagram in the revocation scenario + +The revocation scenarios involve two main flows: + + - The Revocation Request flow: this flow describes how an entity requests for a credential revocation to the Issuer of that credential. + - The Non-Revocation Attestation Request flow: this flow defines the technical protocol for requesting and obtaining a Non-Revocation Attestation and how the Wallet Instance will share it with a Verifier as a proof of validity of a credential. + + + +.. _sec_revocation_high_level_flow: + High Level Revocation Flow -------------------------- -TBD. +A Credential Revocation Flow can start under different scenarios: -All the flows and use cases not defind in the subsequent section is considered out of scope for this technical implementation profile. + - The Holders report the loss or theft of their own physical document to the Law-Enforcement Authorities: this implies that the credentials, if any, shall be revoked. + - The Holders notify an Authentic Source that one or more attributes are changed (e.g. the current resident address): in this case the Credentials shall be revoked, as they are no longer valid due to the change in attributes. + - The Holders who no longer have access to their Wallet Instance (e.g. theft or loss of the device), may request the Issuer of the credentials to revoke them. + - The Law-Enforcing Authorities, for the fulfillment of their functions and any other judicial reasons, may request the Authentic Source to revoke entitlements, licences, certificates, identification documents, etc., which in turn leads to the revocation of any linked Credentials. + - The Authentic Sources that for any administrative reasons update one or more attributes of a Holder, shall inform the Issuer of related Credentials. + - The Issuers, for technical security reasons (e.g. in the case of compromised cryptographic keys), can decide to revoke the Credentials. +The Figure below shows the main processes involved in the scenarios described above -Revocation Wallet Instance Request ----------------------------------- +.. _fig_revocation_processes: +.. figure:: ../../images/revocation-processes.svg + :figwidth: 100% + :align: center -.. code-block:: mermaid + High-Level Revocation Processes and main scenarios - sequenceDiagram - participant WalletInstance as Wallet Instance - participant digital credentialIssuer as PID/(Q)EAA Provider - WalletInstance->>digital credentialIssuer: Send Non-Revocation Attestation Request - digital credentialIssuer->>digital credentialIssuer: Verify credential PoP - digital credentialIssuer->>digital credentialIssuer: Revoke digital credential (if PoP is valid) - digital credentialIssuer->>WalletInstance: Send Response +Some of the sub-processes involved in the above scenarios are already well defined by national laws. +The susequent section defines the protocol interface between the Wallet Instance and the Issuer during the revocation request. The communication between the Authenitc Source and the Issuer is out of scope of this technical implementation profile. -1. **Credential Revocation Request**: The Wallet Instance initiates the process by creating a Credential Revocation Request. This request includes the ID of the digital credential to be revoked and a PoP JWT. The PoP JWT is signed with the private key associated with the digital credential to be revoked, and includes claims such as `iss`, `aud`, `exp`, `iat`, and `jti`. -2. **Send Request to PID/(Q)EAA Provider**: The Wallet Instance sends the Credential Revocation Request to the PID/(Q)EAA Provider's revocation endpoint. The request is authenticated using the PoP JWT, which proves that the Wallet Instance possesses the private key associated with the digital credential. -3. **Verify PoP**: The PID/(Q)EAA Provider verifies the PoP by checking the signature of the PoP JWT using the public key that was used when the digital credential was issued. If the verification is successful, it means that the Wallet Instance possesses the private key associated with the digital credential, and therefore has the authority to request its revocation. +.. _sec_revocation_wi_initiated_flow: -4. **Revoke digital credential**: If the PoP is verified successfully, the PID/(Q)EAA Provider revokes the digital credential identified by the ID in the Credential Revocation Request. +Wallet Instance Initiated Revocation Flow +----------------------------------------- -5. **Send Response**: The PID/(Q)EAA Provider sends a response back to the Wallet Instance indicating the result of the revocation request. If the revocation was successful, the response includes a confirmation of the revocation. +A Wallet Instance MUST request the revocation of a credential as defined below. +.. _fig_Low-Level-Flow-Revocation: +.. figure:: ../../images/Low-Level-Flow-Revocation.svg + :figwidth: 100% + :align: center + :target: https://www.plantuml.com/plantuml/svg/PP11ImD134Rlyoj2yQ1WyIvKAfxgPGSjxaLOucw4q6bcd6HSlFZRZHLRnEjx7xoGjHfMQ_iKi5cMjd-X6eeZ7hcW62nwJ8aCDk9B6Ma1g33ptyr6jL4zA0vXPbZU05z3x1wtS5NfFUy8AhqrKZiVAqqanfY6KdD-NPtT7KdCyRxVNiAOsC60gkILB8Dz5FgFL_tczZDsyIBy5fymyOH6u6Rf1fu5PO9J0HmUrmy_bvtijt4r7voMB4hGxSAQPF8NVG40 + + Wallet Instance Initiated Revocation Flow -https://www.plantuml.com/plantuml/uml/TP9HRzC-5CNV_IckhF_3firTkYRjlvMAXZgGEiGsqKAVtUIklJIrW-saJ0W-EzT9DuQ0frZtT-npdECh7xGBzRuK5NyffqgR07Abon83p0rZawC4xU50lslctjVeMaH2YEaKFc1ZSnt86bv-gT47c4w5E12eLq2JbzmT-Sbg_lh7_TtzELpJXe8kOUQmG1E8bpUh9J0x5SO61DkWOwT_wyGt0I1rkP4Ja6yMbzbGdiT9UApYn3sxgwFxsUT3w2GxAgBaFqwZPhTlrStgtVnQ2l5TzEAfahoFF5cdWpGR90hxML-bUPgeyV_haHgb-IZJ6JwCXaayKEgwFMyRGkKd5nSL5Qfojg42NG-_wdrLOi-wJQib7LZRpv9qE1xt1yCuUx1ktuvbav_vGXs3olpvqctShWAre8t1WaCl9ISMOhd5ltN17Dv_N2nXZU3RBTnfs49WUUMeqG5XXuyWm66f0-DWErYlIyfRbbiJD3rj9TFoNwdWf8i4NQHeUIe4cW9YXK8ylOHFkgGY-iKVpjNz2LxK6taKiEB0ahiTN2OftyfNrdY4MmipJiLYSSLE_9P_0W00 +**Step 1 (Credential Revocation Request)**: The Wallet Instance initiates the process by creating a Credential Revocation Request. This request includes the Wallet Instance Attestation with its Proof of Possession and a Credential Proof of Possession as a JWT. It MUST be signed with the private key related to the public key contained within the credential (Issuer Signed JWT). Then, the Wallet Instance sends the request to the Issuer as in the following non-normative example. -Credential Revocation Request -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. _credential_revocation_request_ex: +.. code-block:: + + POST /revoke HTTP/1.1 + Host: pid-provider.example.org + Content-Type: application/x-www-form-urlencoded -TBD. + credential_proof=$CredentialPoPJWT + &client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-client-attestation + &client_assertion=$WIA~WIA-PoP +where a non-normative example of a Credential PoP JWT is given by -Credential Revocation Response -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. _credential_pop_jwt_ex: +.. code-block:: + + { + "alg": "ES256", + "typ": "revocation-request+jwt", + "kid": "$WIA-CNF-JWKID" + + } + . + { + "iss": "0b434530-e151-4c40-98b7-74c75a5ef760", + "aud": "https://pid-provider.example.org", + "iat": 1698744039, + "exp": 1698744139, + "jti": "6f204f7e-e453-4dfd-814e-9d155319408c", + "format": "vc+sd-jwt", + "credential": "$Issuer-Signed-JWT" + } + +**Step 2 (PoP verification)**: The Issuer verifies the signature of the PoP JWTs using the public key that was attested in the Wallet Instance Attestation and the credential. If the verification is successful, it means that the Wallet Instance owns the private keys associated with the Wallet Instance Attestation and credential, and therefore is entitled to request its revocation. + +**Step 3 (Credential Revocation)**: The Issuer revokes the credential provided in the Credential PoP JWT. After the revocation, the Issuer MAY also send a notification to the Holder (e.g. using a Holder contact certified during the issuance phase), with all needed information related to the credential revocation status update. This communication is out of scope of the current technical implemetation profile. + +**Step 4 (Credential Revocation Response)**: The Issuer sends a response back to the Wallet Instance with the result of the revocation request. + +.. code:: + + .. code-block:: http + + HTTP/1.1 204 No Content + + +Credential Revocation HTTP Request +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The requests to the *Issuer Revocation endpoint* MUST be HTTP with method POST, using the mandatory parameters listed below within the HTTP request message body. These MUST be encoded in ``application/x-www-form-urlencoded`` format. + +.. _table_revocation_request_params: +.. list-table:: + :widths: 20 60 20 + :header-rows: 1 + + * - **Claim** + - **Description** + - **Reference** + * - **credential_proof** + - It MUST contain a JWT proof of possession of the cryptographic key the credential to be revoked shall be bound to. + - This specification + * - **client_assertion_type** + - It MUST be set to ``urn:ietf:params:oauth:client-assertion-type:jwt-client-attestation``. + - `oauth-attestation-draft `_. + * - **client_assertion** + - It MUST be set to a value containing the Wallet Instance Attestation JWT and the Proof of Possession, separated with the ``~`` character. + - `oauth-attestation-draft `_. + +The Revocation Endpoint MUST be provided by the Issuer within its Metadata. + +The Credential Proof of Possession MUST be a JWT that MUST contain the paramters (JOSE Header and claims) in the following table. + +.. list-table:: + :widths: 20 60 20 + :header-rows: 1 + + * - **JOSE header** + - **Description** + - **Reference** + * - **typ** + - It MUST be set to ``revocation-request+jwt`` + - :rfc:`7516#section-4.1.1`, the value is defined within this specification + * - **alg** + - A digital signature algorithm identifier such as per IANA "JSON Web Signature and Encryption Algorithms" registry. It MUST be one of the supported algorithms listed in the Section `Cryptographic Algorithms `_ and MUST NOT be set to ``none`` or any symmetric algorithm (MAC) identifier. + - :rfc:`7516#section-4.1.1`. + * - **kid** + - Unique identifier of the ``jwk`` inside the ``cnf`` claim of the credential to be revoked, as base64url-encoded JWK Thumbprint value. + - :rfc:`7638#section_3`. + +.. list-table:: + :widths: 20 60 20 + :header-rows: 1 + + * - **Claim** + - **Description** + - **Reference** + * - **iss** + - Thumbprint of the JWK in the ``cnf`` parameter of the Wallet Instance Attestation. + - :rfc:`9126` and :rfc:`7519`. + * - **aud** + - It MUST be set to the identifier of the Issuer. + - :rfc:`9126` and :rfc:`7519`. + * - **exp** + - UNIX Timestamp with the expiry time of the JWT. + - :rfc:`9126` and :rfc:`7519`. + * - **iat** + - UNIX Timestamp with the time of JWT issuance. + - :rfc:`9126` and :rfc:`7519`. + * - **jti** + - Unique identifier for the PoP proof JWT. The value SHOULD be set using a *UUID v4* value according to [:rfc:`4122`]. + - [:rfc:`7519`. Section 4.1.7]. + * - **credential_format** + - The data format of the credential to be revoked. It MUST be set to ``vc+sd-jwt`` or ``vc+mdoc`` + - This specification. + * - **credential** + - It MUST contain the credential to be revoked encoded according to the data format given in the ``credential_format`` claim. + - [:rfc:`7519`. Section 4.1.7]. + + +Credential Revocation HTTP Response +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ TBD. -High Level Non-Revocation Attestations Flows --------------------------------------------- -The Wallet Instance sends a request for a digital credential to the PID/(Q)EAA Provider. +.. _sec_revocation_nra_request: -Upon successful request, the Wallet Instance receives: -* The digital credential; -* a Non-Revocation Attestation. +Non-Revocation Attestation Request +---------------------------------- + +The presentation of a credential to a Verifier may occur long after it has been issued by the Issuer. During this time interval, the credential can be invalidated for any reason and therefore the Verifier also needs to verify its revocation or suspension status. To address this scenario, the Issuer provides the Wallet Instance with a *Non-Revocation Attestation*. This Attestation is bound to a credential so that the Wallet Instance can share it to a Verifier, along with the credential itself, as a proof of non-revocation status of the credential. The Non-Revocation Attestation MUST be presented in conjunction with the digital credential. The Non-Revocation Attestation MUST be timestamped with its issuance datetime, always referring to a previous period. The Non-Revocation Attestation MUST contain the expiration datetime after which the digital credential MUST NOT be considered valid anymore. -Relying Parties determine the validity duration of the Non-Revocation Attestation based. -The Non-Revocation Attestation enables offline use cases and potential unavailability of the in the non-revocation certification systems. +The Non-Revocation Attestation enables offline use cases as it MUST be statically validated using the cryptographic signature of the Issuer. +Relying Parties MUST reject an expired Non-Revocation Attestation and, in the case of valid Attestations, they MAY still reject them according to their own policies (e.g., if the issue date doesn't meet their security requirements). -.. code-block:: mermaid +The following diagram shows how the Wallet Instance MUST request a Non-Revocation Attestation to the Issuer. - sequenceDiagram - participant WalletInstance as Wallet Instance - participant digital credentialIssuer as PID/(Q)EAA Provider - WalletInstance->>digital credentialIssuer: Send Non-Revocation Attestation Request
providing the digital credentials and
the cryptoghraphic proof of possession of it. - digital credentialIssuer->>digital credentialIssuer: Verify digital credential PoP - digital credentialIssuer->>digital credentialIssuer: Creates the Non-Revocation Attestation
(if the previous step is valid) - digital credentialIssuer->>WalletInstance: Send Response containing the Non-Revocation Attestation +.. _fig_Low-Level-Flow-Revocation-Attestation: +.. figure:: ../../images/Low-Level-Flow-Revocation-Attestation.svg + :figwidth: 100% + :align: center + :target: https://www.plantuml.com/plantuml/svg/PSr1ImCn40NWUtx5K3mek7WNAYsUreDTQd4lmZ9cHmna9p4pSV7YRtTQiANqEE_bork9Oj4wHOTL4zVfdOhB5WKVChB2eiSOIQ5bKMHF2q21EPo_QKKgbKCLd9i3D0yGxg7RlEpWpfnMWK9VbKIlVQ6HM0F68PUKFfPNZyUaIzrJlxi57uC50ugGhIGUz2VJPRpis_Llj-bkdFkVVCKOHbG2gnghtXYGHpXDW6s0ZPo8TNlmdBZPqdVokF_Qt5gLH0_N4PYOZMn9Sc8XE_JpN5ww5V5Of_W7 + + Non-Revocation Attestation Request Flow -1. **Non-Revocation Attestation Request**: The Wallet Instance initiates the process by creating a Non-Revocation Attestation Request. This request includes the digital credential for which the Non-Revocation Attestation is related to and a PoP JWT. The PoP JWT is signed with the private key associated with the digital credential, and MUST include claims such as `iss`, `aud`, `exp`, `iat`, and `jti`. +**Step 1 (Non-Revocation Attestation Request)**: The Wallet Instance sends the Non-Revocation Attestation Request to the Issuer. The request MUST contain the Wallet Instance Attestation with its Proof of Possession and a Credential Proof of Possession JWT, signed with the private key related to the public key contained within the credential. -2. **Send Request to PID/(Q)EAA Provider**: The Wallet Instance sends the Non-Revocation Attestation Request to the PID/(Q)EAA Provider Non-Revocation issuance endpoint. The Holder is authenticated using the PoP JWT (see [Proof of Possession (PoP) JWT generation process](#proof-of-possession-pop-jwt-generation-process)), which proves that the Wallet Instance possesses the private key associated with the digital credential. +.. code:: -3. **Verify PoP**: The PID/(Q)EAA Provider verifies the PoP by checking the signature of the PoP JWT using the public key that was used when the digital credential was issued. If the verification is successful, it means that the Wallet Instance possesses the private key associated with the digital credential, and therefore has the authority to request its renewal. + POST /status HTTP/1.1 + Host: pid-provider.example.org + Content-Type: application/x-www-form-urlencoded -4. **Renew Non-Revocation Attestation**: If the PoP is verified successfully, the PID/(Q)EAA Provider renews the Non-Revocation Attestation with the digital credential included in the Non-Revocation Attestation Renewal Request. + credential_proof=$CredentialPoPJWT + &client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-client-attestation + &client_assertion=$WIA~WIA-PoP -5. **Send Response**: The PID/(Q)EAA Provider sends a response back to the Wallet Instance indicating the result of the request. If the renewal is successful, the response includes the renewed Non-Revocation Attestation. If not, the response includes an error message describing the unavailability of the Non-Revocation Attestation and any additional information about the cause of that MAY be included in the `error_description`. +For a non-normative example of Credential Proof of Possession see :ref:`the one provided in the prevoius section `. -Upon successful request, the Wallet Instance receives the Non-Revocation Attestation. +**Step 2 (PoP verification)**: The Issuer verifies the signature of the PoP JWTs using the public key that was attested in the Wallet Instance Attestation and the credential, which is the proof that the Wallet Instance owns the private keys associated with the Wallet Instance Attestation and credential. Therefore the Wallet Instance is entitled to request its Non-Revocation Attestation. -This process ensures that the Wallet Instance is the legitimate owner of the digital credential and has the authority to request its Non-Revocation Attestation. It does so by signing the request and having the Issuer verify this signature using the corresponding public key boun with the related digital credetial. This ensures that the Wallet Instance is authenticated and has the digital credential which is requesting the Non-Revocation Attestation. +**Step 3 (Non-Revocation Attestation Creation)**: The Issuer checks the status of the credential and creates a Non-Revocation Attestation bound to it. Then it creates a new Non-Revocation Attestation, a non-normative example of which is given below. -TBD. +.. code:: -https://www.plantuml.com/plantuml/uml/dPFHJzim4CRV_LUSh3ri0eTq9Er0waH5En6sCTIKzH6Pv6WCYPFPJWAQ-Dzdfu4MCNZWgUxttLq-tqy-qeOhKnSvgUolI4J5fG6wv7cE1Y9fRPaW1QwX5Szh8grhL9qb227ZCPoLaisnAHDkH2bXOWngipxFyKzj_y1uJ4WhW7q5SVXMlUhhFowZ2HYHfmZdlyvtOIfMml0SZXMcA8smnzFbmdcVY2mDGjcW0a5UhoD_2G3b-OeU0ft5dyCXtNMAkQ-S8cqczPI9yKqcrcVQkMdDkkLMfAxbWyt8Zi--iTFbzsXA2NaWdliA5LextxyAzeDmtsSu20SiI0AV7Nov6h5Ha8n27kBrQEYxWPJNtRpCc4eVxkrL8cMLAXkHelBmZXTLZbwfLbsjuCRM3a8_61uS3FQ7JhikLT79j4bsTChwe3HvMa8NTmsEnM8bCMLsBTGc9eiCmIsRonICFK-ZVc7myo9Um1M2xXe8jC9aNOdc1KAbHCCDmYtU4uAssM4Wv97nRvwBrFbkINRQ2sCRaVKtdLPtzdCWi0N44INRrD-DzYNIA8ulPlDNYBwV4DvLlJRo_LxRqBdCkCwwpn_FPzFPsIAQ_60da_Y4_gVkih-dpZZhRqeJUMqbjmMWD-sjEtkUzm047XuHsnAm5ZGyht6Djk0coJPKIudGNoe5ucGXEqDXpetLqlvjRG9jSNVuBB_M0foZhagfiHlzrcDt78_iYBh8_m40 + { + "alg": "ES256", + "typ": "non-revocation-attestation+jwt", + "kid": "$ISSUER-JWKID" + } + . + { + "iss": "https://pid-provider.example.org", + "iat": 1504699136, + "exp": 1504700136, + "credential_hash": "$CREDENTIAL-HASH", + "credential_hash_alg": "sha-256", + "cnf": { + "jwk": {...} + } + } -Non-Revocation Attestation Request -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +**Step 4 (Non-Revocation Attestation Response)**: The Issuer then returns the Non-Revocation Attestation to the Wallet Instance, as in the following non-normative example. -The Wallet Instance provides the parameters listed below to the PID/(Q)EAA Provider Non-Revocation Attestation endpoint using the ``request`` parameter to prevent Request URI swapping attack. +.. code:: -The Wallet Instance signs the signed request using the private key that was created to obtain the digital credential, as provided within the digital credential ``cnf.jwk`` claim. + HTTP/1.1 201 OK + Content-Type: application/json + + { + "non_revocation_attestation": "eyJhbGciOiJFUzI1NiIsInR5cCI6IndhbGxldC1...", + } -The signed request JWT contains a JOSE header with ``alg``, ``kid``, and ``typ`` parameters, and a body with ``iss``, ``aud``, ``exp``, ``iat``, and ``jti`` claims. - - ``alg``: A digital signature algorithm identifier such as per IANA "JSON Web Signature and Encryption Algorithms" registry. It MUST be one of the supported algorithms listed in the Section `Cryptographic Algorithms `_ and MUST NOT be set to ``none`` or any symmetric algorithm (MAC) identifier. - - ``kid``: Unique identifier of the ``jwk`` inside the ``cnf`` claim of Wallet Instance Attestation as base64url-encoded JWK Thumbprint value. - - ``typ``: It MUST be set to ``jwt-client-attestation-pop`` - - ``iss``: Thumbprint of the JWK in the ``cnf`` parameter. - - ``aud``: It MUST be set to the identifier of the PID/(Q)EAA Provider. - - ``exp``: UNIX Timestamp with the expiry time of the JWT. - - ``iat``: UNIX Timestamp with the time of JWT issuance. - - ``jti``: Unique identifier for the DPoP proof JWT. The value SHOULD be set using a *UUID v4* value according to RFC 4122. +Non-Revocation Attestation HTTP Request +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -The PID/(Q)EAA Provider MUST verify the Proof of Possession by checking the signature of the request using the public key provided in the digital credential ``cnf.jwk`` claim. +The requests to the *Credential status endpoint* of the Issuers MUST be HTTP with method POST, using the same mandatory parameters as in the :ref:`Table of Credential Request parameters `. These MUST be encoded in ``application/x-www-form-urlencoded`` format. -TBD: the typ value in the JWT header configuring the content type of the request (Non-Revocation Attestation request). +The *Credential status endpoint* MUST be provided by the Issuer within its Metadata. -Non-Revocation Attestation Response -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Non-Revocation Attestation HTTP Response +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -TBD. +The *Credential status endpoint* MUST return a response with a *HTTP status code 201 OK* if the credential is valid at the time of the request, otherwise a *HTTP status code 404 Not Found* MUST be given by the Issuer. The responses MUST be encoded in ``application/json`` format. It MUST contain the following mandatory claims. + +.. _table_http_response_claim: +.. list-table:: + :widths: 20 60 20 + :header-rows: 1 + + * - **Claim** + - **Description** + - **Reference** + * - **non_revocation_attestation** + - It MUST contain the Non-Revocation Attestation as a signed JWT. + - This specification. Non-Revocation Attestation ^^^^^^^^^^^^^^^^^^^^^^^^^^ -TBD. - +The Non-Revocation Attestation MUST contain the following claims. + +.. _table_non_revocation_attestation_header: +.. list-table:: + :widths: 20 60 20 + :header-rows: 1 + + * - **JOSE Header** + - **Description** + - **Reference** + * - **alg** + - A digital signature algorithm identifier such as per IANA "JSON Web Signature and Encryption Algorithms" registry. It MUST be one of the supported algorithms in Section :ref:`Cryptographic Algorithms ` and MUST NOT be set to ``none`` or to a symmetric algorithm (MAC) identifier. + - `[OIDC4VCI. Draft 13] `_, [:rfc:`7515`], [:rfc:`7517`]. + * - **typ** + - It MUST be set to `non-revocation-attestation+jwt`. + - [:rfc:`7515`], [:rfc:`7517`], this specification. + * - **kid** + - Unique identifier of the Issuer ``jwk`` as base64url-encoded JWK Thumbprint value. + - :rfc:`7638#section_3`. + +.. _table_non_revocation_attestation_claim: +.. list-table:: + :widths: 20 60 20 + :header-rows: 1 + + * - **Claim** + - **Description** + - **Reference** + * - **iss** + - It MUST be set to the identifier of the Issuer. + - :rfc:`9126` and :rfc:`7519`. + * - **iat** + - UNIX Timestamp with the time of JWT issuance. + - :rfc:`9126` and :rfc:`7519`. + * - **exp** + - UNIX Timestamp with the expiry time of the JWT. + - :rfc:`9126` and :rfc:`7519`. + * - **credential_hash** + - Hash value of the credential the Non-Revocation Attestation is bound to. + - This specification. + * - **credential_hash_alg** + - The Algorithm used of hashing the credential to which the Non-Revocation Attestation is bound. The value MUST be set to ``S256``. + - This specification. + * - **cnf** + - JSON object containing the proof-of-possession key materials. The ``cnf`` jwk value MUST match with the one provided within the related credential. + - `[RFC7800, Section 3.1] `_. + + + +.. _sec_revocation_nra_presentation: Non-Revocation Proof during the Presentation Phase -------------------------------------------------- -The Wallet Instance, according to the presentation request from the Relying Party, -produces a Verifiable Presentation (VP) token with the digital credential -and a Non-Revocation Attestation. This attestation is the proof that the credential has not been revoked. - -The Relying Party MUST validate the VP token and the Non-Revocation Attestation to certify the validity of a digital credential. +During the presentation phase, a Verifier MAY request the Wallet Instance to provide a Non-Revocation Attestation along with the requested credential (e.g. using the ``scope`` parameter). The Wallet Instance MUST provide the Verifier with a most recent Non-Revocation Attestation. If the Attestation is requested by the Verifier and the Wallet Instance is not able to provide it or it is expired the Verifier MUST reject the credential. If the Attestation is issued far back in time, the Verifier MAY decide to accept or reject the credential according to its security policy. +Law-Enforcement Authorities or Third Parties authorized by national law, MAY require deferred non-revocation status verification but the definition of these protocols is currently out-of-scope for this technical implementation profile. - -External references -------------------- - -- OpenID for Verifiable Presentations - draft 20 _ -- OAuth 2.0 Demonstrating Proof-of-Possession at the Application Layer (DPoP) _ -- Dynamic status lists _ -- JWT and CWT Status List _ diff --git a/images/Low-Level-Flow-Revocation-Attestation.svg b/images/Low-Level-Flow-Revocation-Attestation.svg new file mode 100644 index 000000000..13aae6545 --- /dev/null +++ b/images/Low-Level-Flow-Revocation-Attestation.svg @@ -0,0 +1 @@ +Wallet InstanceWallet InstanceIssuerIssuer1POST /status request(credential_proof=$CredentialPoPJWT, client_assertion_type, client_assertion=WIA~POP)2Validate WIA-POPand Credential PoP JWT3Create Non-RevocationAttestation JWT4Response with Non-Revocation Attestation JWT \ No newline at end of file diff --git a/images/Low-Level-Flow-Revocation.svg b/images/Low-Level-Flow-Revocation.svg new file mode 100644 index 000000000..5f5bd4538 --- /dev/null +++ b/images/Low-Level-Flow-Revocation.svg @@ -0,0 +1 @@ +Wallet InstanceWallet InstanceIssuerIssuer1POST /revoke request(credential_proof=$CredentialPoPJWT, client_assertion_type, client_assertion=WIA~POP)2Validate WIA-POPand Credential POP3Revoke Credential4Response Ok \ No newline at end of file diff --git a/images/revocation-entity-relationship.svg b/images/revocation-entity-relationship.svg new file mode 100644 index 000000000..fe1a701ef --- /dev/null +++ b/images/revocation-entity-relationship.svg @@ -0,0 +1,3 @@ + + +
Request for user attributes
Request for user attributes
Notify attributes update 
and revocation of the 
physical document
Notify attributes update...
Authentic Source
Authentic Source
Issuer
Issuer
Check the credential
non-revocation status
Check the credential...
Verifier
Verifier
I
I
Interact with
Interact with
Request for
attributes update
Request for...
Request for revocation
of physical document
Request for revocation...
Check the credential non-revocation status
end request for credential revocation
Check the credential non-revocation status...
Holders
Holders
Wallet Instance
Wallet Instance
Request for credential
revocation
Request for credential...
Request for revocation
of physical document
Request for revocation...
Request for credential
revocation
Request for credential...
Check the credential
non-revocation status
Check the credential...
Law Enforcing Bodies
Law Enforcing Bodies
Check the credential
non-revocation status
Check the credential...
Revoke the
credential
Revoke the...
Provide the non-revocation attestation
Provide the non-revocation attestationText is not SVG - cannot display \ No newline at end of file diff --git a/images/revocation-processes.svg b/images/revocation-processes.svg new file mode 100644 index 000000000..be042c7b5 --- /dev/null +++ b/images/revocation-processes.svg @@ -0,0 +1,3 @@ + + +
High-Level Revocation Processes
High-Level Revocation Processes
Holder
Holder
Requires attributes to be updated
Requires attributes...
Request for revocation of a Credential
Request for revocati...
Start
Start
Request for revocation of a physical document
Request for revocati...
NEW
NEW
Law Enforcing Bodies
Law Enforcing Bodies
Start
(e.g. Police
check)
Start...
Request for revocation of a physical document
Request for revocati...
Authentic Source
Authentic Source
Elaborate the request
Elaborate the request
Update its database with changed document status information or attributes
Update its database...
Start
Start
Send notification on revocation status of physical document or attributes update 
Send notification on...
Local
DB
Local...
NEW
NEW
Issuer
Issuer
Receive notification on revocation status or attributes update
Receive notification...
Elaborate the request
Elaborate the request
Revoke the Credential
Revoke the Credential
Start
(e.g. in the case of
compromised
cryptographic keys)
Start...
Send notification to the Holder
Send notification to...
NEW
NEW
NEW
NEW
NEW
NEW
NEW
NEW
End
EndText is not SVG - cannot display \ No newline at end of file From 49ce2b8d7b5404fa99d1a928405c6b8a932b6ca1 Mon Sep 17 00:00:00 2001 From: fmarino-ipzs <77629526+fmarino-ipzs@users.noreply.github.com> Date: Tue, 7 Nov 2023 17:21:08 +0100 Subject: [PATCH 08/28] Apply suggestions from code review Co-authored-by: Giuseppe De Marco --- docs/en/defined-terms.rst | 2 +- docs/en/revocation-lists.rst | 12 ++++++------ 2 files changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/en/defined-terms.rst b/docs/en/defined-terms.rst index bd50efc47..ff0a13bf5 100644 --- a/docs/en/defined-terms.rst +++ b/docs/en/defined-terms.rst @@ -40,7 +40,7 @@ Below are the description of acronyms and definitions which are useful for furth * - Wallet Instance Attestation - Verifiable Attestation, issued by the Wallet Provider, that proves the security compliace of the Wallet Instance. * - Non-Revocation Attestation - - Verifiable Attestation, issued by the Issuer, proving that a related Digital Credential is not revoked. + - Verifiable Attestation proving that a related Digital Credential is not revoked. * - App Attestation Service - Device manufacturer service that allows you to certify the authenticity of the mobile app (Wallet Instance). * - Qualified Electronic Attestation of Attributes (QEAA) diff --git a/docs/en/revocation-lists.rst b/docs/en/revocation-lists.rst index 297021ede..69b8b3e2e 100644 --- a/docs/en/revocation-lists.rst +++ b/docs/en/revocation-lists.rst @@ -5,13 +5,13 @@ Credential Revocations ++++++++++++++++++++++ -The value of digital credentials is contingent on their validity. +The value of Digital Credentials is contingent on their validity. A credential that has been revoked, due to legal requirements, inaccuracy or compromise, is not only valueless but potentially harmful. -For these reasons a robust mechanism for managing the validity and revocation of digital credentials is required. +For these reasons a robust mechanism for managing the validity and revocation of Digital Credentials is required. -This section outlines the key technical requirements and processes related to the revocation of the digital credentials. +This section outlines the key technical requirements and processes related to the revocation of the Digital Credentials. Furthermore, it provides the technical details that the Relying Parties MUST implement to verify, in a secure and reliable manner, -the validity of a digital credential during the presentation phase. +the validity of a Digital Credential during the presentation phase. This section is structured into several subsections, these are listed below. @@ -46,11 +46,11 @@ General Requirements ^^^^^^^^^^^^^^^^^^^^ - The Issuer MUST be the only responsible for the lifecycle of credentials including the revocation status. -- Credentials SHOULD be updates whenever one or more attributes are changed. +- Credentials SHOULD be updated whenever one or more attributes are changed. - Any credential update MUST result in a new fresh issuance of it, following the principle that the credential SHOULD always have updated data. In this case, the old Credentials of the same type MUST be revoked. - The revocation of a credential for technical reasons (loss or theft of the device, compromise of cryptographic keys) MAY not have an impact on any other digital credentials issued of the same type and MUST NOT lead to the revocation of a physical document associated with it. - The revocation of a physical document which one or more Credentials are associated with MUST result in their revocation. -- The revocation requests of a credential MAY be communicated to the Issuer by +- The revocation requests of a credential MAY be communicated to the Issuer by: - Holders using their personal Wallet Instance. - Authentic Sources (e.g., for attribute updates) following administrative purposes. From e236725a07c40254b89404da921a904257e37b73 Mon Sep 17 00:00:00 2001 From: fmarino-ipzs <77629526+fmarino-ipzs@users.noreply.github.com> Date: Tue, 7 Nov 2023 17:22:29 +0100 Subject: [PATCH 09/28] Apply suggestions from code review Co-authored-by: Giuseppe De Marco --- docs/en/revocation-lists.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/en/revocation-lists.rst b/docs/en/revocation-lists.rst index 69b8b3e2e..1a2fb132a 100644 --- a/docs/en/revocation-lists.rst +++ b/docs/en/revocation-lists.rst @@ -33,7 +33,7 @@ General Assumptions A Credential Issuer is in charge of the creation and the issuance of credentials, its lifecycle, and ultimately, its validity status. Some credentials may have regulatory value given by national or european laws, therefore also revocations of credentials MUST be non-repudiable. Some credentials may be a digital representation of a physical document issued, under a well defined national law, by an Authentic Source which, in the Wallet Ecosystem, acts as a repository or system that contains attributes and provides them to the Issuer. For this reason, an exchange of information between the two entities is required not only for the issuing the credential but also for the proper handling of its revocation. Moreover, due to digital signature of the credentials, any updates on them MUST result in a re-issuance. -Finally, it is assumed that, to facilitate the association between physical document and digital credentials, the identifier of the physical document is always present as an attribute within the digital credentials. +Finally, it is assumed that, to facilitate the association between physical document and digital credentials, the identifier of the physical document is always present as an attribute within the Digital Credentials. @@ -48,7 +48,7 @@ General Requirements - The Issuer MUST be the only responsible for the lifecycle of credentials including the revocation status. - Credentials SHOULD be updated whenever one or more attributes are changed. - Any credential update MUST result in a new fresh issuance of it, following the principle that the credential SHOULD always have updated data. In this case, the old Credentials of the same type MUST be revoked. -- The revocation of a credential for technical reasons (loss or theft of the device, compromise of cryptographic keys) MAY not have an impact on any other digital credentials issued of the same type and MUST NOT lead to the revocation of a physical document associated with it. +- The revocation of a credential for technical reasons (loss or theft of the device, compromise of cryptographic keys) MAY not have an impact on any other Digital Credentials issued of the same type and MUST NOT lead to the revocation of a physical document associated with it. - The revocation of a physical document which one or more Credentials are associated with MUST result in their revocation. - The revocation requests of a credential MAY be communicated to the Issuer by: @@ -59,7 +59,7 @@ General Requirements - A Law-Enforcing Body (e.g., Police) on behalf of the User or directly for the fulfillment of their functions and any other judicial reasons. - The Holder using any out-of-band procedure in force by national regulations. -- The Authentic Source MUST provide an interface for the data sharing regarding the attributes update and revocation status of a physical document the credential is associated with. +- The Authentic Source MUST provide an interface for the data provisioning regarding the attributes update and revocation status of a physical document the credential is associated with. - The Issuer MUST provide an interface handling the revocation flows (Revocation request/response, data access regarding the revocation status of a credential, etc.). - The Issuer MUST provide the Wallet Instance with a proof of non-revocation of a given Holder's credential (Non-Revocation Attestation). - The Holders MAY provide the Verifiers with a proof of non-revocation of their Credentials (Non-Revocation Attestations). From 901a28ab117a51e00e0eef5cc66692715cea7a2e Mon Sep 17 00:00:00 2001 From: Riccardo Iaconelli Date: Fri, 17 Nov 2023 21:35:17 +0100 Subject: [PATCH 10/28] Update docs/en/revocation-lists.rst Co-authored-by: Giuseppe De Marco --- docs/en/revocation-lists.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/en/revocation-lists.rst b/docs/en/revocation-lists.rst index 1a2fb132a..cca840d2e 100644 --- a/docs/en/revocation-lists.rst +++ b/docs/en/revocation-lists.rst @@ -282,7 +282,7 @@ TBD. Non-Revocation Attestation Request ---------------------------------- -The presentation of a credential to a Verifier may occur long after it has been issued by the Issuer. During this time interval, the credential can be invalidated for any reason and therefore the Verifier also needs to verify its revocation or suspension status. To address this scenario, the Issuer provides the Wallet Instance with a *Non-Revocation Attestation*. This Attestation is bound to a credential so that the Wallet Instance can share it to a Verifier, along with the credential itself, as a proof of non-revocation status of the credential. +The presentation of a credential to a Verifier may occur long after it has been issued by the Issuer. During this time interval, the credential can be invalidated for any reason and therefore the Verifier also needs to verify its revocation or suspension status. To address this scenario, the Issuer provides the Wallet Instance with a *Non-Revocation Attestation*. This Attestation is bound to a credential so that the Wallet Instance can present it to a Verifier, along with the credential itself, as a proof of non-revocation status of the credential. The Non-Revocation Attestation MUST be presented in conjunction with the digital credential. The Non-Revocation Attestation MUST be timestamped with its issuance datetime, always referring to a previous period. The Non-Revocation Attestation MUST contain the expiration datetime after which the digital credential MUST NOT be considered valid anymore. From 87cf3e9a154bbc503829c65266937afcbd32c87b Mon Sep 17 00:00:00 2001 From: Giuseppe De Marco Date: Thu, 23 Nov 2023 16:30:49 +0100 Subject: [PATCH 11/28] Apply suggestions from code review --- docs/en/revocation-lists.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/en/revocation-lists.rst b/docs/en/revocation-lists.rst index cca840d2e..09961bb21 100644 --- a/docs/en/revocation-lists.rst +++ b/docs/en/revocation-lists.rst @@ -113,13 +113,13 @@ High Level Revocation Flow A Credential Revocation Flow can start under different scenarios: - The Holders report the loss or theft of their own physical document to the Law-Enforcement Authorities: this implies that the credentials, if any, shall be revoked. - - The Holders notify an Authentic Source that one or more attributes are changed (e.g. the current resident address): in this case the Credentials shall be revoked, as they are no longer valid due to the change in attributes. + - The Holders notify an Authentic Source that one or more attributes are changed (e.g. the current resident address): in this case the Credentials SHALL be revoked, as they are no longer valid due to the change in attributes. - The Holders who no longer have access to their Wallet Instance (e.g. theft or loss of the device), may request the Issuer of the credentials to revoke them. - The Law-Enforcing Authorities, for the fulfillment of their functions and any other judicial reasons, may request the Authentic Source to revoke entitlements, licences, certificates, identification documents, etc., which in turn leads to the revocation of any linked Credentials. - - The Authentic Sources that for any administrative reasons update one or more attributes of a Holder, shall inform the Issuer of related Credentials. + - The Authentic Sources that for any administrative reasons update one or more attributes of a Holder, SHALL inform the Issuer of related Credentials. - The Issuers, for technical security reasons (e.g. in the case of compromised cryptographic keys), can decide to revoke the Credentials. -The Figure below shows the main processes involved in the scenarios described above +The Figure below shows the main processes involved in the scenarios described above. .. _fig_revocation_processes: .. figure:: ../../images/revocation-processes.svg @@ -161,7 +161,7 @@ A Wallet Instance MUST request the revocation of a credential as defined below. &client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-client-attestation &client_assertion=$WIA~WIA-PoP -where a non-normative example of a Credential PoP JWT is given by +where a non-normative example of a Credential PoP is given by the following JWT headers and payload .. _credential_pop_jwt_ex: .. code-block:: From a5fbc76694d543db47924fc734dd13ac9057d611 Mon Sep 17 00:00:00 2001 From: Giuseppe De Marco Date: Sun, 10 Dec 2023 18:16:38 +0100 Subject: [PATCH 12/28] Apply suggestions from code review --- docs/en/revocation-lists.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/en/revocation-lists.rst b/docs/en/revocation-lists.rst index 09961bb21..e681c6509 100644 --- a/docs/en/revocation-lists.rst +++ b/docs/en/revocation-lists.rst @@ -101,7 +101,7 @@ The entities involved in the main revocation processes are depicted in the diagr The revocation scenarios involve two main flows: - The Revocation Request flow: this flow describes how an entity requests for a credential revocation to the Issuer of that credential. - - The Non-Revocation Attestation Request flow: this flow defines the technical protocol for requesting and obtaining a Non-Revocation Attestation and how the Wallet Instance will share it with a Verifier as a proof of validity of a credential. + - The Non-Revocation Attestation Request flow: this flow defines the technical protocol for requesting and obtaining a Non-Revocation Attestation and how the Wallet Instance will provide it with a Verifier as a proof of validity of a credential. From ef1b3a610d5c9b2f69f2fb3bbef0b586e449e7d6 Mon Sep 17 00:00:00 2001 From: Giuseppe De Marco Date: Sun, 10 Dec 2023 20:27:25 +0100 Subject: [PATCH 13/28] NRA revision and revocation response section --- docs/en/revocation-lists.rst | 195 +++++++++++++++++++++-------------- 1 file changed, 119 insertions(+), 76 deletions(-) diff --git a/docs/en/revocation-lists.rst b/docs/en/revocation-lists.rst index e681c6509..c4e6b968b 100644 --- a/docs/en/revocation-lists.rst +++ b/docs/en/revocation-lists.rst @@ -5,65 +5,112 @@ Credential Revocations ++++++++++++++++++++++ -The value of Digital Credentials is contingent on their validity. -A credential that has been revoked, due to legal requirements, inaccuracy or compromise, is not only valueless but potentially harmful. -For these reasons a robust mechanism for managing the validity and revocation of Digital Credentials is required. +The value of a Digital Credential is conditional on its validity. +A Credential that has been revoked, due to legal requirements, inaccuracy or compromise, is valueless and potentially harmful. +For these reasons a robust mechanism for managing the life-cycle and the revocation of a Digital Credential is required. This section outlines the key technical requirements and processes related to the revocation of the Digital Credentials. Furthermore, it provides the technical details that the Relying Parties MUST implement to verify, in a secure and reliable manner, the validity of a Digital Credential during the presentation phase. -This section is structured into several subsections, these are listed below. - -* The :ref:`"General Assumptions" ` subsection outlines the main assumptions relevant to the design of a suitable solution for the main revocation scenarios. -* The :ref:`"Requirements" ` subsection outlines basic requirements, particularly regarding security and privacy aspects. -* The :ref:`"Entities Relationship" ` describes the roles and responsibilities of the main entities involved in ensuring the validity of credentials and managing their revocation. -* The :ref:`"High Level Revocation Flow" ` subsection outlines the main revocation scanarios and relevant processes. -* The :ref:`"Wallet Instance Initiated Revocation Flow" ` subsections outline how Wallet Instances request a revocation of a given credential to Issuers. -* The :ref:`"Non-Revocation Attestation Request" ` subsections decribe how the Wallet Instance interacts with the Issuer to obtain a Non-Revocation Attestation related to a credential own by the Holder. -* The :ref:`"Non-Revocation Proof during the Presentation Phase" ` subsection details how a Non-Revocation Attestation, in the form of a cryptographic proof that the credential has not been revoked, is provided by the Wallet Instance to the Verifier requesting a credential. +It also provides the technical requirements that the Wallet Instance MUST implement to +request and present a status attestation about a Digital Credential, +theirein defined as Non-Revocation Attestation. +Generally, the Non-Revocation Attestation enables: +- the verification of the digital Credential when both the Wallet Instance and the Verifier are offline; +- a better privacy of the User since the Relyign Party cannot check over time the validity of a specific digital Credential related to the User. .. _sec_revocation_assumption: General Assumptions ------------------- -A Credential Issuer is in charge of the creation and the issuance of credentials, its lifecycle, and ultimately, its validity status. Some credentials may have regulatory value given by national or european laws, therefore also revocations of credentials MUST be non-repudiable. -Some credentials may be a digital representation of a physical document issued, under a well defined national law, by an Authentic Source which, in the Wallet Ecosystem, acts as a repository or system that contains attributes and provides them to the Issuer. For this reason, an exchange of information between the two entities is required not only for the issuing the credential but also for the proper handling of its revocation. -Moreover, due to digital signature of the credentials, any updates on them MUST result in a re-issuance. -Finally, it is assumed that, to facilitate the association between physical document and digital credentials, the identifier of the physical document is always present as an attribute within the Digital Credentials. +Similar to the Wallet Instance Attestation, Non-Revocation Attestations do not necessitate the User authentication. +The attestations acquired by the Holder (Wallet Instance) for its proper functioning are procured via assessments +and Holder's authentication with the attestation providers, entirely in an automated fashion. + +All the attestations can only be acquired when the Wallet Instance has an internet connection and is actively executed by the User. + +A Credential Issuer, together with the owner of the Credential (User), +is in charge of the creation and the issuance of Credentials, +its lifecycle and its validity status. + +Digital Credentials may be linked to a physical documents issued by an Authentic Source in a previous period. +The Authentic Sources are National organizations that implements repositories of data containing attributes +related to the Users to be provided to the Issuers duringthe issuance phase. +When one or more Authentic Sources are involved in the issuance of a Digital Credential, +the information exchanged between the Authentic Source and the PID/(Q)EAA Provider is required for the +issuance of the Credential and, in some cases also for the the revocation of the Credential. + +Finally, it is assumed that, to facilitate the association between physical document and a digital Credential, +the identifier of the physical document should be always present as an attribute within the Digital Credential. .. _sec_revocation_requirements: +Revocation Use Cases +-------------------- + +The revocation requests of a Credential MAY be communicated to the Issuer by: + +- Users using their personal Wallet Instance. +- Authentic Sources (e.g., for attribute updates) following administrative purposes. +- Law-Enforcing Bodies for the fulfillment of their functions and any other judicial reasons (e.g., Police). + + +The revocation requests of a physical document MAY be communicated to Authentic Source by: + +- A Law-Enforcing Body (e.g., Police) on behalf of the User or directly for the fulfillment of their functions and any other judicial reasons. +- The User using any out-of-band procedure in force by national regulations. + Requirements ------------ General Requirements ^^^^^^^^^^^^^^^^^^^^ - -- The Issuer MUST be the only responsible for the lifecycle of credentials including the revocation status. -- Credentials SHOULD be updated whenever one or more attributes are changed. -- Any credential update MUST result in a new fresh issuance of it, following the principle that the credential SHOULD always have updated data. In this case, the old Credentials of the same type MUST be revoked. -- The revocation of a credential for technical reasons (loss or theft of the device, compromise of cryptographic keys) MAY not have an impact on any other Digital Credentials issued of the same type and MUST NOT lead to the revocation of a physical document associated with it. -- The revocation of a physical document which one or more Credentials are associated with MUST result in their revocation. -- The revocation requests of a credential MAY be communicated to the Issuer by: - - - Holders using their personal Wallet Instance. - - Authentic Sources (e.g., for attribute updates) following administrative purposes. - - Law-Enforcing Bodies for the fulfillment of their functions and any other judicial reasons (e.g., Police). -- The revocation requests of a physical document MAY be communicated to Authentic Source by: - - - A Law-Enforcing Body (e.g., Police) on behalf of the User or directly for the fulfillment of their functions and any other judicial reasons. - - The Holder using any out-of-band procedure in force by national regulations. -- The Authentic Source MUST provide an interface for the data provisioning regarding the attributes update and revocation status of a physical document the credential is associated with. -- The Issuer MUST provide an interface handling the revocation flows (Revocation request/response, data access regarding the revocation status of a credential, etc.). -- The Issuer MUST provide the Wallet Instance with a proof of non-revocation of a given Holder's credential (Non-Revocation Attestation). -- The Holders MAY provide the Verifiers with a proof of non-revocation of their Credentials (Non-Revocation Attestations). -- The Verifiers MAY require a proof of non-revocation, even in the future after the credential presentation, for the fulfillment of their functions and for any other regulatory reasons (deferred). + +Below the requirements that must be satisfied, the Non-Revocation Attestation: + +- MUST be presented in conjunction with the digital Credential, and it MUST be timestamped with the issuance datetime, always referring to a previous period; +- MUST contain the expiration datetime after which it MUST NOT be considered valid anymore; +- expiration datetime MUST NOT be greater the one contained in the digital Credential which it refers to; +- enables offline use cases as it MUST be statically validated using the cryptographic signature of the Issuer; +- provides the proof about the non-revocation of the digital Credential which is related to; +- MUST be verifiable with a cryptographic signature. +- does not reveal any information about the Relying Party or the User's data contained in the digital Credential the attestation is related to. + + +Below the requirements that must be satisfied by the PID/(Q)EAA Providers, then the Issuer: + +- MUST provide a web service for allowing an authenticated User to ask the revocation using the Wallet Instance; +- MUST provide a web service for allowing a Wallet Instance, with a proof of possession of a specific Digital Credential, to obtain a Non-Revocation Attestation; +- MUST be responsible for the lifecycle of Credentials including the revocation status; +- MUST revoke a Digital Credential when it requires to be updated, whenever one or more attributes are changed; +- in the case of attributes update, the Issuer MUST provide a fresh issuance of the Digital Credential to the User; +- MUST multiple communication channels and services where the User can request the revocation of their Digital Credentials, using a robust procedure for identity proofing and User authentication, in particular when the User is unable to use the personal Wallet for asking the revocations. +- MUST provide a web service where the authorized Authentic Sources MAY notify the updates related to the data of a specific User for which the Issuer has requested the data, in a previous period, for the issuance of a Digital Credential related to that User; +- each time an Authentic Source notify a data update regarding a specific User, the Issuer MUST revoke the already issued Digital Credential. +- MUST provide Non-Revocation Attestation in a non-repudiable manner, using cryptographic mechanisms. + +Below the requirements that must be satisfied by the User: + +- the revocation of a Digital Credential may happen for technical reasons, such as the loss or theft of the device, or the compromission of the cryptographic keys. In these cases the User MUST ask the revocation of its Digital Credentials to their Issuers. + + +Below the requirement that must be satisfied by the Wallet Instance: + +- The Wallet Instance MAY provide the Verifiers and Relying Parties with a proof of non-revocation of their Credentials when the issued Credential contains the status object configuring the status check using a Non-Revocation Attestation. + + +Below the requirements related to the Authentic Sources: + +- The Authentic Source MUST provide web service where the allowed Issuers can be authenticated and authorized in obtaining the data for a specific User for the scope of the issuance of a Digital Credential; +- Each time an Issuer requests data of a specific User to the Authentic Source, the Authentic Source MUST keep track of which Issuer has asked and obtained the data for which User; +- Each time the data of a User is updated, the Authentic Source MUST notify to the Issuers that have requested the data for that specific User in a previous time; +- The revocation of a physical document which one or more Credentials are associated with, MUST result in the revocation of those Credentials. In these cases the Authentic Source MUST notify to the Issuers that the data are changed. Security Requirements @@ -77,11 +124,10 @@ Security Requirements Privacy Requirements ^^^^^^^^^^^^^^^^^^^^ -- The Authentic Source MUST store in local databases only the minimum information required to notify the Issuer of a change in attributes or a change in the validity status of a physical document associated with one or more credentials. -- Access to credential status information by a Verifier MUST be authorized by the Holder, except for checks carried out by Law-Enforcement Bodies on a regulatory basis. -- The Issuer SHOULD not directly or indirectly have any information related to the Verifier, type of credentials, and Holder such that it is impossible to track the Holder's usage of the Credentials. -- A proof of non-revocation (Non-Revocation Attestation) provided by the Issuer, in whatever format it is, SHOULD NOT reveal any information about the Verifier nor the User's attributes contained in the credential the attestation is related to. - +- The Authentic Source MUST store in local databases only the minimum information required to notify the Issuer of a change in attributes or a change in the validity status of a physical document associated with one or more Credentials. +- Access to Credential status information by a Verifier MUST be authorized by the Holder, except for checks carried out by Law-Enforcement Bodies on a regulatory basis. +- The Issuer SHOULD not directly or indirectly have any information related to the Verifier, type of Credentials, and Holder such that it is impossible to track the Holder's usage of the Credentials. +- A proof of non-revocation (Non-Revocation Attestation) provided by the Issuer, in whatever format it is, SHOULD NOT reveal any information about the Verifier nor the User's attributes contained in the Credential the attestation is related to. .. _sec_revocation_entity_relationship: @@ -100,9 +146,8 @@ The entities involved in the main revocation processes are depicted in the diagr The revocation scenarios involve two main flows: - - The Revocation Request flow: this flow describes how an entity requests for a credential revocation to the Issuer of that credential. - - The Non-Revocation Attestation Request flow: this flow defines the technical protocol for requesting and obtaining a Non-Revocation Attestation and how the Wallet Instance will provide it with a Verifier as a proof of validity of a credential. - + - The Revocation Request flow: this flow describes how an entity requests for a Credential revocation to the Issuer of that Credential. + - The Non-Revocation Attestation Request flow: this flow defines the technical protocol for requesting and obtaining a Non-Revocation Attestation and how the Wallet Instance will provide it with a Verifier as a proof of validity of a Credential. .. _sec_revocation_high_level_flow: @@ -112,9 +157,9 @@ High Level Revocation Flow A Credential Revocation Flow can start under different scenarios: - - The Holders report the loss or theft of their own physical document to the Law-Enforcement Authorities: this implies that the credentials, if any, shall be revoked. + - The Holders report the loss or theft of their own physical document to the Law-Enforcement Authorities: this implies that the Credentials, if any, shall be revoked. - The Holders notify an Authentic Source that one or more attributes are changed (e.g. the current resident address): in this case the Credentials SHALL be revoked, as they are no longer valid due to the change in attributes. - - The Holders who no longer have access to their Wallet Instance (e.g. theft or loss of the device), may request the Issuer of the credentials to revoke them. + - The Holders who no longer have access to their Wallet Instance (e.g. theft or loss of the device), may request the Issuer of the Credentials to revoke them. - The Law-Enforcing Authorities, for the fulfillment of their functions and any other judicial reasons, may request the Authentic Source to revoke entitlements, licences, certificates, identification documents, etc., which in turn leads to the revocation of any linked Credentials. - The Authentic Sources that for any administrative reasons update one or more attributes of a Holder, SHALL inform the Issuer of related Credentials. - The Issuers, for technical security reasons (e.g. in the case of compromised cryptographic keys), can decide to revoke the Credentials. @@ -132,13 +177,12 @@ Some of the sub-processes involved in the above scenarios are already well defin The susequent section defines the protocol interface between the Wallet Instance and the Issuer during the revocation request. The communication between the Authenitc Source and the Issuer is out of scope of this technical implementation profile. - .. _sec_revocation_wi_initiated_flow: Wallet Instance Initiated Revocation Flow ----------------------------------------- -A Wallet Instance MUST request the revocation of a credential as defined below. +A Wallet Instance MUST request the revocation of a Credential as defined below. .. _fig_Low-Level-Flow-Revocation: .. figure:: ../../images/Low-Level-Flow-Revocation.svg @@ -148,7 +192,7 @@ A Wallet Instance MUST request the revocation of a credential as defined below. Wallet Instance Initiated Revocation Flow -**Step 1 (Credential Revocation Request)**: The Wallet Instance initiates the process by creating a Credential Revocation Request. This request includes the Wallet Instance Attestation with its Proof of Possession and a Credential Proof of Possession as a JWT. It MUST be signed with the private key related to the public key contained within the credential (Issuer Signed JWT). Then, the Wallet Instance sends the request to the Issuer as in the following non-normative example. +** Step 1 (Credential Revocation Request)**: The Wallet Instance initiates the process by creating a Credential Revocation Request. This request includes the Wallet Instance Attestation with the Proof of Possession and a Credential Proof of Possession as a JWT. It MUST be signed with the private key related to the public key contained within the Credential (such as the Issuer Signed JWT in the case of SD-JWT, or the MSO in the case of Mdoc CBOR). Then, the Wallet Instance sends the request to the Issuer as in the following non-normative example. .. _credential_revocation_request_ex: .. code-block:: @@ -175,7 +219,7 @@ where a non-normative example of a Credential PoP is given by the following JWT . { "iss": "0b434530-e151-4c40-98b7-74c75a5ef760", - "aud": "https://pid-provider.example.org", + "aud": "https://pid-provider.example.org/revoke", "iat": 1698744039, "exp": 1698744139, "jti": "6f204f7e-e453-4dfd-814e-9d155319408c", @@ -183,9 +227,9 @@ where a non-normative example of a Credential PoP is given by the following JWT "credential": "$Issuer-Signed-JWT" } -**Step 2 (PoP verification)**: The Issuer verifies the signature of the PoP JWTs using the public key that was attested in the Wallet Instance Attestation and the credential. If the verification is successful, it means that the Wallet Instance owns the private keys associated with the Wallet Instance Attestation and credential, and therefore is entitled to request its revocation. +**Step 2 (PoP verification)**: The Issuer verifies the signature of the PoP JWTs using the public key that was attested in the Wallet Instance Attestation and the Credential. If the verification is successful, it means that the Wallet Instance owns the private keys associated with the Wallet Instance Attestation and Credential, and therefore is entitled to request its revocation. -**Step 3 (Credential Revocation)**: The Issuer revokes the credential provided in the Credential PoP JWT. After the revocation, the Issuer MAY also send a notification to the Holder (e.g. using a Holder contact certified during the issuance phase), with all needed information related to the credential revocation status update. This communication is out of scope of the current technical implemetation profile. +**Step 3 (Credential Revocation)**: The Issuer revokes the Credential provided in the Credential PoP JWT. After the revocation, the Issuer MAY also send a notification to the User (e.g. using a User's email address, or telephone number or any other verified and secure communication channel), with all needed information related to the Credential revocation status update. This communication is out of scope of the current technical implemetation profile. **Step 4 (Credential Revocation Response)**: The Issuer sends a response back to the Wallet Instance with the result of the revocation request. @@ -209,8 +253,8 @@ The requests to the *Issuer Revocation endpoint* MUST be HTTP with method POST, * - **Claim** - **Description** - **Reference** - * - **credential_proof** - - It MUST contain a JWT proof of possession of the cryptographic key the credential to be revoked shall be bound to. + * - **Credential_proof** + - It MUST contain a JWT proof of possession of the cryptographic key the Credential to be revoked shall be bound to. - This specification * - **client_assertion_type** - It MUST be set to ``urn:ietf:params:oauth:client-assertion-type:jwt-client-attestation``. @@ -237,7 +281,7 @@ The Credential Proof of Possession MUST be a JWT that MUST contain the paramters - A digital signature algorithm identifier such as per IANA "JSON Web Signature and Encryption Algorithms" registry. It MUST be one of the supported algorithms listed in the Section `Cryptographic Algorithms `_ and MUST NOT be set to ``none`` or any symmetric algorithm (MAC) identifier. - :rfc:`7516#section-4.1.1`. * - **kid** - - Unique identifier of the ``jwk`` inside the ``cnf`` claim of the credential to be revoked, as base64url-encoded JWK Thumbprint value. + - Unique identifier of the ``jwk`` inside the ``cnf`` claim of the Credential to be revoked, as base64url-encoded JWK Thumbprint value. - :rfc:`7638#section_3`. .. list-table:: @@ -262,19 +306,18 @@ The Credential Proof of Possession MUST be a JWT that MUST contain the paramters * - **jti** - Unique identifier for the PoP proof JWT. The value SHOULD be set using a *UUID v4* value according to [:rfc:`4122`]. - [:rfc:`7519`. Section 4.1.7]. - * - **credential_format** - - The data format of the credential to be revoked. It MUST be set to ``vc+sd-jwt`` or ``vc+mdoc`` + * - **Credential_format** + - The data format of the Credential to be revoked. It MUST be set to ``vc+sd-jwt`` or ``vc+mdoc`` - This specification. - * - **credential** - - It MUST contain the credential to be revoked encoded according to the data format given in the ``credential_format`` claim. + * - **Credential** + - It MUST contain the Credential to be revoked encoded according to the data format given in the ``Credential_format`` claim. - [:rfc:`7519`. Section 4.1.7]. Credential Revocation HTTP Response ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -TBD. - +The response MUST be an HTTP Response using the status code set to 204 (No-Content). .. _sec_revocation_nra_request: @@ -282,10 +325,10 @@ TBD. Non-Revocation Attestation Request ---------------------------------- -The presentation of a credential to a Verifier may occur long after it has been issued by the Issuer. During this time interval, the credential can be invalidated for any reason and therefore the Verifier also needs to verify its revocation or suspension status. To address this scenario, the Issuer provides the Wallet Instance with a *Non-Revocation Attestation*. This Attestation is bound to a credential so that the Wallet Instance can present it to a Verifier, along with the credential itself, as a proof of non-revocation status of the credential. +The presentation of a Credential to a Verifier may occur long after it has been issued by the Issuer. During this time interval, the Credential can be invalidated for any reason and therefore the Verifier also needs to verify its revocation or suspension status. To address this scenario, the Issuer provides the Wallet Instance with a *Non-Revocation Attestation*. This Attestation is bound to a Credential so that the Wallet Instance can present it to a Verifier, along with the Credential itself, as a proof of non-revocation status of the Credential. -The Non-Revocation Attestation MUST be presented in conjunction with the digital credential. The Non-Revocation Attestation MUST be timestamped with its issuance datetime, always referring to a previous period. -The Non-Revocation Attestation MUST contain the expiration datetime after which the digital credential MUST NOT be considered valid anymore. +The Non-Revocation Attestation MUST be presented in conjunction with the digital Credential. The Non-Revocation Attestation MUST be timestamped with its issuance datetime, always referring to a previous period. +The Non-Revocation Attestation MUST contain the expiration datetime after which the digital Credential MUST NOT be considered valid anymore. The Non-Revocation Attestation enables offline use cases as it MUST be statically validated using the cryptographic signature of the Issuer. Relying Parties MUST reject an expired Non-Revocation Attestation and, in the case of valid Attestations, they MAY still reject them according to their own policies (e.g., if the issue date doesn't meet their security requirements). @@ -299,7 +342,7 @@ The following diagram shows how the Wallet Instance MUST request a Non-Revocatio Non-Revocation Attestation Request Flow -**Step 1 (Non-Revocation Attestation Request)**: The Wallet Instance sends the Non-Revocation Attestation Request to the Issuer. The request MUST contain the Wallet Instance Attestation with its Proof of Possession and a Credential Proof of Possession JWT, signed with the private key related to the public key contained within the credential. +**Step 1 (Non-Revocation Attestation Request)**: The Wallet Instance sends the Non-Revocation Attestation Request to the Issuer. The request MUST contain the Wallet Instance Attestation with its Proof of Possession and a Credential Proof of Possession JWT, signed with the private key related to the public key contained within the Credential. .. code:: @@ -307,29 +350,29 @@ The following diagram shows how the Wallet Instance MUST request a Non-Revocatio Host: pid-provider.example.org Content-Type: application/x-www-form-urlencoded - credential_proof=$CredentialPoPJWT + Credential_proof=$CredentialPoPJWT &client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-client-attestation &client_assertion=$WIA~WIA-PoP -For a non-normative example of Credential Proof of Possession see :ref:`the one provided in the prevoius section `. +For a non-normative example of Credential Proof of Possession see :ref:`the one provided in the prevoius section `. -**Step 2 (PoP verification)**: The Issuer verifies the signature of the PoP JWTs using the public key that was attested in the Wallet Instance Attestation and the credential, which is the proof that the Wallet Instance owns the private keys associated with the Wallet Instance Attestation and credential. Therefore the Wallet Instance is entitled to request its Non-Revocation Attestation. +**Step 2 (PoP verification)**: The Issuer verifies the signature of the PoP JWTs using the public key that was attested in the Wallet Instance Attestation and the Credential, which is the proof that the Wallet Instance owns the private keys associated with the Wallet Instance Attestation and Credential. Therefore the Wallet Instance is entitled to request its Non-Revocation Attestation. -**Step 3 (Non-Revocation Attestation Creation)**: The Issuer checks the status of the credential and creates a Non-Revocation Attestation bound to it. Then it creates a new Non-Revocation Attestation, a non-normative example of which is given below. +**Step 3 (Non-Revocation Attestation Creation)**: The Issuer checks the status of the Credential and creates a Non-Revocation Attestation bound to it. Then it creates a new Non-Revocation Attestation, a non-normative example of which is given below. .. code:: { "alg": "ES256", "typ": "non-revocation-attestation+jwt", - "kid": "$ISSUER-JWKID" + "kid": $ISSUER-JWKID } . { "iss": "https://pid-provider.example.org", "iat": 1504699136, "exp": 1504700136, - "credential_hash": "$CREDENTIAL-HASH", + "credential_hash": $CREDENTIAL-HASH, "credential_hash_alg": "sha-256", "cnf": { "jwk": {...} @@ -359,7 +402,7 @@ The *Credential status endpoint* MUST be provided by the Issuer within its Metad Non-Revocation Attestation HTTP Response ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -The *Credential status endpoint* MUST return a response with a *HTTP status code 201 OK* if the credential is valid at the time of the request, otherwise a *HTTP status code 404 Not Found* MUST be given by the Issuer. The responses MUST be encoded in ``application/json`` format. It MUST contain the following mandatory claims. +The *Credential status endpoint* MUST return a response with a *HTTP status code 201 OK* if the Credential is valid at the time of the request, otherwise a *HTTP status code 404 Not Found* MUST be given by the Issuer. The responses MUST be encoded in ``application/json`` format. It MUST contain the following mandatory claims. .. _table_http_response_claim: .. list-table:: @@ -415,13 +458,13 @@ The Non-Revocation Attestation MUST contain the following claims. - UNIX Timestamp with the expiry time of the JWT. - :rfc:`9126` and :rfc:`7519`. * - **credential_hash** - - Hash value of the credential the Non-Revocation Attestation is bound to. + - Hash value of the Credential the Non-Revocation Attestation is bound to. - This specification. * - **credential_hash_alg** - - The Algorithm used of hashing the credential to which the Non-Revocation Attestation is bound. The value MUST be set to ``S256``. + - The Algorithm used of hashing the Credential to which the Non-Revocation Attestation is bound. The value MUST be set to ``S256``. - This specification. * - **cnf** - - JSON object containing the proof-of-possession key materials. The ``cnf`` jwk value MUST match with the one provided within the related credential. + - JSON object containing the proof-of-possession key materials. The ``cnf`` jwk value MUST match with the one provided within the related Credential. - `[RFC7800, Section 3.1] `_. @@ -431,7 +474,7 @@ The Non-Revocation Attestation MUST contain the following claims. Non-Revocation Proof during the Presentation Phase -------------------------------------------------- -During the presentation phase, a Verifier MAY request the Wallet Instance to provide a Non-Revocation Attestation along with the requested credential (e.g. using the ``scope`` parameter). The Wallet Instance MUST provide the Verifier with a most recent Non-Revocation Attestation. If the Attestation is requested by the Verifier and the Wallet Instance is not able to provide it or it is expired the Verifier MUST reject the credential. If the Attestation is issued far back in time, the Verifier MAY decide to accept or reject the credential according to its security policy. +During the presentation phase, a Verifier MAY request the Wallet Instance to provide a Non-Revocation Attestation along with the requested Credential (e.g. using the ``scope`` parameter). The Wallet Instance MUST provide the Verifier with a most recent Non-Revocation Attestation. If the Attestation is requested by the Verifier and the Wallet Instance is not able to provide it or it is expired the Verifier MUST reject the Credential. If the Attestation is issued far back in time, the Verifier MAY decide to accept or reject the Credential according to its security policy. Law-Enforcement Authorities or Third Parties authorized by national law, MAY require deferred non-revocation status verification but the definition of these protocols is currently out-of-scope for this technical implementation profile. From ae0db0c0285a3bfd86899953aa8c7ffa650cb948 Mon Sep 17 00:00:00 2001 From: Giuseppe De Marco Date: Sun, 10 Dec 2023 20:34:17 +0100 Subject: [PATCH 14/28] added space in NRA --- docs/en/revocation-lists.rst | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) diff --git a/docs/en/revocation-lists.rst b/docs/en/revocation-lists.rst index c4e6b968b..6a46a2372 100644 --- a/docs/en/revocation-lists.rst +++ b/docs/en/revocation-lists.rst @@ -213,7 +213,7 @@ where a non-normative example of a Credential PoP is given by the following JWT { "alg": "ES256", "typ": "revocation-request+jwt", - "kid": "$WIA-CNF-JWKID" + "kid": $WIA-CNF-JWKID } . @@ -224,7 +224,7 @@ where a non-normative example of a Credential PoP is given by the following JWT "exp": 1698744139, "jti": "6f204f7e-e453-4dfd-814e-9d155319408c", "format": "vc+sd-jwt", - "credential": "$Issuer-Signed-JWT" + "credential": $Issuer-Signed-JWT } **Step 2 (PoP verification)**: The Issuer verifies the signature of the PoP JWTs using the public key that was attested in the Wallet Instance Attestation and the Credential. If the verification is successful, it means that the Wallet Instance owns the private keys associated with the Wallet Instance Attestation and Credential, and therefore is entitled to request its revocation. @@ -253,7 +253,7 @@ The requests to the *Issuer Revocation endpoint* MUST be HTTP with method POST, * - **Claim** - **Description** - **Reference** - * - **Credential_proof** + * - **credential_proof** - It MUST contain a JWT proof of possession of the cryptographic key the Credential to be revoked shall be bound to. - This specification * - **client_assertion_type** @@ -265,6 +265,7 @@ The requests to the *Issuer Revocation endpoint* MUST be HTTP with method POST, The Revocation Endpoint MUST be provided by the Issuer within its Metadata. + The Credential Proof of Possession MUST be a JWT that MUST contain the paramters (JOSE Header and claims) in the following table. .. list-table:: @@ -306,11 +307,11 @@ The Credential Proof of Possession MUST be a JWT that MUST contain the paramters * - **jti** - Unique identifier for the PoP proof JWT. The value SHOULD be set using a *UUID v4* value according to [:rfc:`4122`]. - [:rfc:`7519`. Section 4.1.7]. - * - **Credential_format** + * - **credential_format** - The data format of the Credential to be revoked. It MUST be set to ``vc+sd-jwt`` or ``vc+mdoc`` - This specification. - * - **Credential** - - It MUST contain the Credential to be revoked encoded according to the data format given in the ``Credential_format`` claim. + * - **credential** + - It MUST contain the Credential to be revoked encoded according to the data format given in the ``credential_format`` claim. - [:rfc:`7519`. Section 4.1.7]. @@ -350,7 +351,7 @@ The following diagram shows how the Wallet Instance MUST request a Non-Revocatio Host: pid-provider.example.org Content-Type: application/x-www-form-urlencoded - Credential_proof=$CredentialPoPJWT + credential_proof=$CredentialPoPJWT &client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-client-attestation &client_assertion=$WIA~WIA-PoP From 561cbeeaf9ed0d9158e44d7a530d4133b8297efb Mon Sep 17 00:00:00 2001 From: Giuseppe De Marco Date: Sun, 10 Dec 2023 21:00:29 +0100 Subject: [PATCH 15/28] fix: NRA authentic source --- docs/en/revocation-lists.rst | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/docs/en/revocation-lists.rst b/docs/en/revocation-lists.rst index 6a46a2372..0eb3a2205 100644 --- a/docs/en/revocation-lists.rst +++ b/docs/en/revocation-lists.rst @@ -31,19 +31,21 @@ Similar to the Wallet Instance Attestation, Non-Revocation Attestations do not n The attestations acquired by the Holder (Wallet Instance) for its proper functioning are procured via assessments and Holder's authentication with the attestation providers, entirely in an automated fashion. + All the attestations can only be acquired when the Wallet Instance has an internet connection and is actively executed by the User. + A Credential Issuer, together with the owner of the Credential (User), is in charge of the creation and the issuance of Credentials, its lifecycle and its validity status. + Digital Credentials may be linked to a physical documents issued by an Authentic Source in a previous period. -The Authentic Sources are National organizations that implements repositories of data containing attributes -related to the Users to be provided to the Issuers duringthe issuance phase. + When one or more Authentic Sources are involved in the issuance of a Digital Credential, the information exchanged between the Authentic Source and the PID/(Q)EAA Provider is required for the -issuance of the Credential and, in some cases also for the the revocation of the Credential. +issuance of the Credential and, in the cases where the revocation is requested by the Authentic Source, also for the the revocation of the Credential. Finally, it is assumed that, to facilitate the association between physical document and a digital Credential, the identifier of the physical document should be always present as an attribute within the Digital Credential. From 258c1a952a5b9ca6cbe6f67c74a044888f631dc4 Mon Sep 17 00:00:00 2001 From: Giuseppe De Marco Date: Mon, 11 Dec 2023 02:00:04 +0100 Subject: [PATCH 16/28] fix: NRA Holder is User --- docs/en/revocation-lists.rst | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/docs/en/revocation-lists.rst b/docs/en/revocation-lists.rst index 0eb3a2205..8321b5ce6 100644 --- a/docs/en/revocation-lists.rst +++ b/docs/en/revocation-lists.rst @@ -120,16 +120,16 @@ Security Requirements - The proof of non-revocation (Non-Revocation Attestation) MUST be cryptographically verifiable, so that it can be shown to have been issued by the Issuer and not to have been tampered with. - The Non-Revocation Attestation MUST be non-repudiable even beyond its expiration time and even in the face of any rotations of the cryptographic keys. -- Granting of the proof of non-revocation (Non-Revocation Attestation) MUST be allowed only to authorized entities (e.g. by the Holder or by law). +- Granting of the proof of non-revocation (Non-Revocation Attestation) MUST be allowed only to authorized entities (e.g. by the User or by law). Privacy Requirements ^^^^^^^^^^^^^^^^^^^^ - The Authentic Source MUST store in local databases only the minimum information required to notify the Issuer of a change in attributes or a change in the validity status of a physical document associated with one or more Credentials. -- Access to Credential status information by a Verifier MUST be authorized by the Holder, except for checks carried out by Law-Enforcement Bodies on a regulatory basis. -- The Issuer SHOULD not directly or indirectly have any information related to the Verifier, type of Credentials, and Holder such that it is impossible to track the Holder's usage of the Credentials. -- A proof of non-revocation (Non-Revocation Attestation) provided by the Issuer, in whatever format it is, SHOULD NOT reveal any information about the Verifier nor the User's attributes contained in the Credential the attestation is related to. +- Access to Credential status information by a Verifier MUST be authorized by the User, except for checks carried out by Law-Enforcement Bodies on a regulatory basis. +- The Issuer SHOULD not directly or indirectly have any information related to the interation between the Verifier and the User, such that it is impossible to track the usage of the issued Credential. +- A proof of non-revocation (Non-Revocation Attestation) provided by the Issuer, in whatever format it is, SHOULD NOT reveal any information about the Verifier nor the User's attributes contained in the Credential, or the Credential type, the attestation is related to. .. _sec_revocation_entity_relationship: @@ -148,7 +148,7 @@ The entities involved in the main revocation processes are depicted in the diagr The revocation scenarios involve two main flows: - - The Revocation Request flow: this flow describes how an entity requests for a Credential revocation to the Issuer of that Credential. + - The Revocation Request flow: this flow describes how an entity requests for a non-Revocation Attestation to the Issuer of that Credential. - The Non-Revocation Attestation Request flow: this flow defines the technical protocol for requesting and obtaining a Non-Revocation Attestation and how the Wallet Instance will provide it with a Verifier as a proof of validity of a Credential. @@ -159,11 +159,11 @@ High Level Revocation Flow A Credential Revocation Flow can start under different scenarios: - - The Holders report the loss or theft of their own physical document to the Law-Enforcement Authorities: this implies that the Credentials, if any, shall be revoked. - - The Holders notify an Authentic Source that one or more attributes are changed (e.g. the current resident address): in this case the Credentials SHALL be revoked, as they are no longer valid due to the change in attributes. - - The Holders who no longer have access to their Wallet Instance (e.g. theft or loss of the device), may request the Issuer of the Credentials to revoke them. + - The User report the loss or theft of their own physical document to the Law-Enforcement Authorities: this implies that the Credentials, if any, shall be revoked. + - The User notify an Authentic Source that one or more attributes are changed (e.g. the current resident address): in this case the Credentials SHALL be revoked, as they are no longer valid due to the change in attributes. + - The Users who no longer have access to their Wallet Instance (e.g. theft or loss of the device), may request the Issuer of the Credentials to revoke them. - The Law-Enforcing Authorities, for the fulfillment of their functions and any other judicial reasons, may request the Authentic Source to revoke entitlements, licences, certificates, identification documents, etc., which in turn leads to the revocation of any linked Credentials. - - The Authentic Sources that for any administrative reasons update one or more attributes of a Holder, SHALL inform the Issuer of related Credentials. + - The Authentic Sources that for any administrative reasons update one or more attributes of a User, SHALL inform the Issuer of related Credentials. - The Issuers, for technical security reasons (e.g. in the case of compromised cryptographic keys), can decide to revoke the Credentials. The Figure below shows the main processes involved in the scenarios described above. From c2279739880357fe1f12eae9516aae42657c218e Mon Sep 17 00:00:00 2001 From: Giuseppe De Marco Date: Tue, 12 Dec 2023 13:17:57 +0100 Subject: [PATCH 17/28] small editorials on revocations --- docs/en/revocation-lists.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/en/revocation-lists.rst b/docs/en/revocation-lists.rst index 8321b5ce6..598ca9aca 100644 --- a/docs/en/revocation-lists.rst +++ b/docs/en/revocation-lists.rst @@ -335,7 +335,7 @@ The Non-Revocation Attestation MUST contain the expiration datetime after which The Non-Revocation Attestation enables offline use cases as it MUST be statically validated using the cryptographic signature of the Issuer. Relying Parties MUST reject an expired Non-Revocation Attestation and, in the case of valid Attestations, they MAY still reject them according to their own policies (e.g., if the issue date doesn't meet their security requirements). -The following diagram shows how the Wallet Instance MUST request a Non-Revocation Attestation to the Issuer. +The following diagram shows how the Wallet Instance requests a Non-Revocation Attestation to the Issuer. .. _fig_Low-Level-Flow-Revocation-Attestation: .. figure:: ../../images/Low-Level-Flow-Revocation-Attestation.svg @@ -357,7 +357,7 @@ The following diagram shows how the Wallet Instance MUST request a Non-Revocatio &client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-client-attestation &client_assertion=$WIA~WIA-PoP -For a non-normative example of Credential Proof of Possession see :ref:`the one provided in the prevoius section `. +For a non-normative example of Credential Proof of Possession see :ref:`the one provided in the prevoius section `. **Step 2 (PoP verification)**: The Issuer verifies the signature of the PoP JWTs using the public key that was attested in the Wallet Instance Attestation and the Credential, which is the proof that the Wallet Instance owns the private keys associated with the Wallet Instance Attestation and Credential. Therefore the Wallet Instance is entitled to request its Non-Revocation Attestation. From 78bd1e5c74b9e81cec5f98bee9555bfd264b2325 Mon Sep 17 00:00:00 2001 From: fmarino-ipzs Date: Wed, 28 Feb 2024 01:36:15 +0100 Subject: [PATCH 18/28] fix: alignment with Status Attestation draft --- docs/en/revocation-lists.rst | 531 ++++++++++-------- images/High-Level-Flow-Status-Attestation.svg | 3 + .../Low-Level-Flow-Revocation-Attestation.svg | 2 +- images/Low-Level-Flow-Revocation.svg | 2 +- images/revocation-entity-relationship.svg | 3 - images/revocation-processes.svg | 3 - 6 files changed, 289 insertions(+), 255 deletions(-) create mode 100644 images/High-Level-Flow-Status-Attestation.svg delete mode 100644 images/revocation-entity-relationship.svg delete mode 100644 images/revocation-processes.svg diff --git a/docs/en/revocation-lists.rst b/docs/en/revocation-lists.rst index 598ca9aca..b61fdcac7 100644 --- a/docs/en/revocation-lists.rst +++ b/docs/en/revocation-lists.rst @@ -2,199 +2,136 @@ .. _sec_revocation_intro: -Credential Revocations -++++++++++++++++++++++ +Credential Lifecycle +++++++++++++++++++++ -The value of a Digital Credential is conditional on its validity. -A Credential that has been revoked, due to legal requirements, inaccuracy or compromise, is valueless and potentially harmful. +The value of a Digital Credential is conditional on its validity. A Credential that has been revoked, due to legal requirements, inaccuracy or compromise, is valueless and potentially harmful. For these reasons a robust mechanism for managing the life-cycle and the revocation of a Digital Credential is required. This section outlines the key technical requirements and processes related to the revocation of the Digital Credentials. -Furthermore, it provides the technical details that the Relying Parties MUST implement to verify, in a secure and reliable manner, -the validity of a Digital Credential during the presentation phase. +Furthermore, it provides the technical details that the Verifiers MUST implement to verify, in a secure and reliable manner, the validity of a Digital Credential during the presentation phase. -It also provides the technical requirements that the Wallet Instance MUST implement to -request and present a status attestation about a Digital Credential, -theirein defined as Non-Revocation Attestation. +The verification of the validity of a Digital Credential is based on the `[OAuth Status Attestation draft 00] `_ specification. -Generally, the Non-Revocation Attestation enables: +A Status Attestation is a signed object that is evidence of the validity status of a Digital Credential. These attestations are provided by the Issuer to Holders who can present them to Verifiers together with the corresponding Digital Credentials. -- the verification of the digital Credential when both the Wallet Instance and the Verifier are offline; -- a better privacy of the User since the Relyign Party cannot check over time the validity of a specific digital Credential related to the User. +Generally, the Status Attestation enables: + +- an entirely automated issuance flow, as the User authentication is not required; +- the verification of the digital Credential validity status when both the Wallet Instance and the Verifier are offline; +- a better privacy of the User since: + + 1. the Verifier cannot check over time the validity of a given Digital Credential related to the User; + 2. it prevents issuers to track when and where a Digital Credential is verified. + 3. it doesn't reveal any information about the Users or the content of their Digital Credentials. .. _sec_revocation_assumption: General Assumptions ------------------- -Similar to the Wallet Instance Attestation, Non-Revocation Attestations do not necessitate the User authentication. -The attestations acquired by the Holder (Wallet Instance) for its proper functioning are procured via assessments -and Holder's authentication with the attestation providers, entirely in an automated fashion. - - -All the attestations can only be acquired when the Wallet Instance has an internet connection and is actively executed by the User. - - -A Credential Issuer, together with the owner of the Credential (User), -is in charge of the creation and the issuance of Credentials, -its lifecycle and its validity status. - - -Digital Credentials may be linked to a physical documents issued by an Authentic Source in a previous period. - - -When one or more Authentic Sources are involved in the issuance of a Digital Credential, -the information exchanged between the Authentic Source and the PID/(Q)EAA Provider is required for the -issuance of the Credential and, in the cases where the revocation is requested by the Authentic Source, also for the the revocation of the Credential. - -Finally, it is assumed that, to facilitate the association between physical document and a digital Credential, -the identifier of the physical document should be always present as an attribute within the Digital Credential. + - All the Status Attestations can only be acquired when the Wallet Instance has an internet connection and is actively executed by the User. + - A Credential Issuer, is in charge of the creation and the issuance of Credentials, its lifecycle and its validity status. + - When one or more Authentic Sources are involved in the issuance of a Digital Credential, the information exchanged between the Authentic Source and the PID/(Q)EAA Provider is required for the issuance of the Credential and, in the cases where the revocation is requested by the Authentic Source, also for the the revocation of the Credential. .. _sec_revocation_requirements: -Revocation Use Cases --------------------- - -The revocation requests of a Credential MAY be communicated to the Issuer by: - -- Users using their personal Wallet Instance. -- Authentic Sources (e.g., for attribute updates) following administrative purposes. -- Law-Enforcing Bodies for the fulfillment of their functions and any other judicial reasons (e.g., Police). - - -The revocation requests of a physical document MAY be communicated to Authentic Source by: - -- A Law-Enforcing Body (e.g., Police) on behalf of the User or directly for the fulfillment of their functions and any other judicial reasons. -- The User using any out-of-band procedure in force by national regulations. - Requirements ------------ -General Requirements -^^^^^^^^^^^^^^^^^^^^ - -Below the requirements that must be satisfied, the Non-Revocation Attestation: +**The Status Attestation MUST:** -- MUST be presented in conjunction with the digital Credential, and it MUST be timestamped with the issuance datetime, always referring to a previous period; -- MUST contain the expiration datetime after which it MUST NOT be considered valid anymore; -- expiration datetime MUST NOT be greater the one contained in the digital Credential which it refers to; -- enables offline use cases as it MUST be statically validated using the cryptographic signature of the Issuer; -- provides the proof about the non-revocation of the digital Credential which is related to; -- MUST be verifiable with a cryptographic signature. -- does not reveal any information about the Relying Party or the User's data contained in the digital Credential the attestation is related to. +- be presented in conjunction with the Digital Credential; +- be timestamped with the issuance datetime; +- contain the expiration datetime after which it SHOULD NOT be considered valid anymore and it MUST NOT be greater the one contained in the digital Credential which it refers to; +- have a validity period not greater than 24 hours; +- provides the proof about the non-revocation of the digital Credential which is related to and MUST be validated using the cryptographic signature of the Issuer; +- not reveal any information about the Relying Party, the User's device or the User's data contained in the digital Credential the attestation is related to; +- be non-repudiable even beyond its expiration time and even in the case of cryptographic keys rotation. -Below the requirements that must be satisfied by the PID/(Q)EAA Providers, then the Issuer: +**The Issuer MUST:** -- MUST provide a web service for allowing an authenticated User to ask the revocation using the Wallet Instance; -- MUST provide a web service for allowing a Wallet Instance, with a proof of possession of a specific Digital Credential, to obtain a Non-Revocation Attestation; -- MUST be responsible for the lifecycle of Credentials including the revocation status; -- MUST revoke a Digital Credential when it requires to be updated, whenever one or more attributes are changed; -- in the case of attributes update, the Issuer MUST provide a fresh issuance of the Digital Credential to the User; -- MUST multiple communication channels and services where the User can request the revocation of their Digital Credentials, using a robust procedure for identity proofing and User authentication, in particular when the User is unable to use the personal Wallet for asking the revocations. -- MUST provide a web service where the authorized Authentic Sources MAY notify the updates related to the data of a specific User for which the Issuer has requested the data, in a previous period, for the issuance of a Digital Credential related to that User; -- each time an Authentic Source notify a data update regarding a specific User, the Issuer MUST revoke the already issued Digital Credential. -- MUST provide Non-Revocation Attestation in a non-repudiable manner, using cryptographic mechanisms. +- ensure that the data contained in a Digital Credential is kept up to date, including the status of validity of the data from the Authentic Source; +- revoke a Digital Credential when -Below the requirements that must be satisfied by the User: + - it requires to be updated, whenever one or more attributes are changed; in this case the User will request a new issuance for that Digital Credential; + - the Wallet Instance to which it was issued is revoked; + - the User deletes it from the Wallet Instance; -- the revocation of a Digital Credential may happen for technical reasons, such as the loss or theft of the device, or the compromission of the cryptographic keys. In these cases the User MUST ask the revocation of its Digital Credentials to their Issuers. +- provide a web service for allowing a Wallet Instance, with a proof of possession of a specific Digital Credential, to + - request a revocation of that Digital Credential; + - obtain a related Status Attestation; -Below the requirement that must be satisfied by the Wallet Instance: +- provide out-of-band mechanisms through which the User can request the revocation of their Digital Credentials, using a robust procedure for identity proofing and User authentication, in particular when the User is unable to use the personal Wallet Instance. -- The Wallet Instance MAY provide the Verifiers and Relying Parties with a proof of non-revocation of their Credentials when the issued Credential contains the status object configuring the status check using a Non-Revocation Attestation. +**The Wallet Instance MUST:** -Below the requirements related to the Authentic Sources: +- check periodically the validity status of the Digital Credential that are stored in it, requesting a Status Attestation for each Digital Credential; +- be able to present a Status Attestation if required by a Verifier, along with the corresponding Digital Credential; +- request a revocation of a Digital Credential when the Users delete it from the storage. -- The Authentic Source MUST provide web service where the allowed Issuers can be authenticated and authorized in obtaining the data for a specific User for the scope of the issuance of a Digital Credential; -- Each time an Issuer requests data of a specific User to the Authentic Source, the Authentic Source MUST keep track of which Issuer has asked and obtained the data for which User; -- Each time the data of a User is updated, the Authentic Source MUST notify to the Issuers that have requested the data for that specific User in a previous time; -- The revocation of a physical document which one or more Credentials are associated with, MUST result in the revocation of those Credentials. In these cases the Authentic Source MUST notify to the Issuers that the data are changed. +**The Authentic Sources MUST:** -Security Requirements -^^^^^^^^^^^^^^^^^^^^^ +- provide web services for the providing of updated User data and the validity status; +- store in local databases only the minimum information required to provide the Issuer with the User data or a change in the validity status. -- The proof of non-revocation (Non-Revocation Attestation) MUST be cryptographically verifiable, so that it can be shown to have been issued by the Issuer and not to have been tampered with. -- The Non-Revocation Attestation MUST be non-repudiable even beyond its expiration time and even in the face of any rotations of the cryptographic keys. -- Granting of the proof of non-revocation (Non-Revocation Attestation) MUST be allowed only to authorized entities (e.g. by the User or by law). - - -Privacy Requirements -^^^^^^^^^^^^^^^^^^^^ - -- The Authentic Source MUST store in local databases only the minimum information required to notify the Issuer of a change in attributes or a change in the validity status of a physical document associated with one or more Credentials. -- Access to Credential status information by a Verifier MUST be authorized by the User, except for checks carried out by Law-Enforcement Bodies on a regulatory basis. -- The Issuer SHOULD not directly or indirectly have any information related to the interation between the Verifier and the User, such that it is impossible to track the usage of the issued Credential. -- A proof of non-revocation (Non-Revocation Attestation) provided by the Issuer, in whatever format it is, SHOULD NOT reveal any information about the Verifier nor the User's attributes contained in the Credential, or the Credential type, the attestation is related to. +Revocation Use Cases +-------------------- -.. _sec_revocation_entity_relationship: +The revocation of a Digital Credential MAY be triggered by: -Entities Relationship ---------------------- +- Users using their personal Wallet Instance or by some out-of-band touchpoints. +- Revocation of the Wallet Instance +- Authentic Sources (e.g., for attribute updates) following administrative purposes. +- Law-Enforcing Bodies for the fulfillment of their functions and any other judicial reasons (e.g., Police). -The entities involved in the main revocation processes are depicted in the diagram below. +Credential Revocation Flows can start under different scenarios, such as: -.. _fig_revocation_entity_relationship: -.. figure:: ../../images/revocation-entity-relationship.svg - :figwidth: 80% - :align: center + - The User reports the loss or theft of their own physical document to the Law-Enforcement Authorities: this implies that the Credentials, if any, shall be revoked. + - The User notifies an Authentic Source that one or more attributes are changed (e.g. the current resident address): in this case the Credentials SHALL be revoked, as they are no longer valid due to the change in attributes. + - The Users who no longer have access to their Wallet Instance (e.g. theft or loss of the device), may request the Issuer of the Credentials to revoke them or may request the Wallet Provider to revoke the Wallet Instance which in turn implies the revocation of all Digital Credentials stored in the Wallet Instance. + - The Law-Enforcing Authorities, for the fulfillment of their functions and any other judicial reasons, may request the Authentic Source to revoke entitlements, licenses, certificates, identification documents, etc., which in turn leads to the revocation of any linked Credentials. + - The Authentic Sources that for any administrative reasons update one or more attributes of a User, SHALL inform the Issuer of related Credentials. + - The Issuers, for technical security reasons (e.g. in the case of compromised cryptographic keys, death of the User, etc.), can decide to revoke the Credentials. - Entity-Relationship diagram in the revocation scenario The revocation scenarios involve two main flows: - - The Revocation Request flow: this flow describes how an entity requests for a non-Revocation Attestation to the Issuer of that Credential. - - The Non-Revocation Attestation Request flow: this flow defines the technical protocol for requesting and obtaining a Non-Revocation Attestation and how the Wallet Instance will provide it with a Verifier as a proof of validity of a Credential. + - The **Revocation flows**: these flows describe how an Entity requests for a Digital Credential revocation. + - The **Status Attestation flows**: these flows define the technical protocols for requesting and obtaining a Status Attestation and how the Wallet Instance will provide it with a Verifier as a proof of validity of a corresponding Digital Credential. .. _sec_revocation_high_level_flow: -High Level Revocation Flow --------------------------- - -A Credential Revocation Flow can start under different scenarios: - - - The User report the loss or theft of their own physical document to the Law-Enforcement Authorities: this implies that the Credentials, if any, shall be revoked. - - The User notify an Authentic Source that one or more attributes are changed (e.g. the current resident address): in this case the Credentials SHALL be revoked, as they are no longer valid due to the change in attributes. - - The Users who no longer have access to their Wallet Instance (e.g. theft or loss of the device), may request the Issuer of the Credentials to revoke them. - - The Law-Enforcing Authorities, for the fulfillment of their functions and any other judicial reasons, may request the Authentic Source to revoke entitlements, licences, certificates, identification documents, etc., which in turn leads to the revocation of any linked Credentials. - - The Authentic Sources that for any administrative reasons update one or more attributes of a User, SHALL inform the Issuer of related Credentials. - - The Issuers, for technical security reasons (e.g. in the case of compromised cryptographic keys), can decide to revoke the Credentials. - -The Figure below shows the main processes involved in the scenarios described above. - -.. _fig_revocation_processes: -.. figure:: ../../images/revocation-processes.svg - :figwidth: 100% - :align: center - - High-Level Revocation Processes and main scenarios +Revocation Flows +---------------- -Some of the sub-processes involved in the above scenarios are already well defined by national laws. -The susequent section defines the protocol interface between the Wallet Instance and the Issuer during the revocation request. The communication between the Authenitc Source and the Issuer is out of scope of this technical implementation profile. +Depending on the different scenarios that may involve the revocation of a Digital Credential, different processes and technical flows may be implemented, according to national laws or Regulations of specific domains. +The subsequent sections define the protocol interface between the Wallet Instances and the Issuers during the revocation request. The communication between the the Issuers and other Entities are out of scope of this technical implementation profile. .. _sec_revocation_wi_initiated_flow: -Wallet Instance Initiated Revocation Flow ------------------------------------------ +Revocation Request by Wallet Instance +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -A Wallet Instance MUST request the revocation of a Credential as defined below. +A Wallet Instance MUST request the revocation of a Digital Credential as defined below. .. _fig_Low-Level-Flow-Revocation: .. figure:: ../../images/Low-Level-Flow-Revocation.svg :figwidth: 100% :align: center - :target: https://www.plantuml.com/plantuml/svg/PP11ImD134Rlyoj2yQ1WyIvKAfxgPGSjxaLOucw4q6bcd6HSlFZRZHLRnEjx7xoGjHfMQ_iKi5cMjd-X6eeZ7hcW62nwJ8aCDk9B6Ma1g33ptyr6jL4zA0vXPbZU05z3x1wtS5NfFUy8AhqrKZiVAqqanfY6KdD-NPtT7KdCyRxVNiAOsC60gkILB8Dz5FgFL_tczZDsyIBy5fymyOH6u6Rf1fu5PO9J0HmUrmy_bvtijt4r7voMB4hGxSAQPF8NVG40 + :target: https://www.plantuml.com/plantuml/svg/NP31IaD134Nt-OfGNEX2t0jAmLNTTD1YDuB4zoA6JfDnal7zlkE05eMixZqdWQmzg4OxPg0MfktuoXLAZsIIGXgusbFE7BZHJkh4AoJ7HVuo6_V6TLG2i0XUtg9SOze-xl2gygST62j_DFOudohFh26KNqerUxivk_jDagNx_Uu2u6V34sMPAHZZdV74FMlwLh5FCdTs5zEJzJ0k_dD6tVjb05vCdN5x05Ypplq1Nm00 Wallet Instance Initiated Revocation Flow -** Step 1 (Credential Revocation Request)**: The Wallet Instance initiates the process by creating a Credential Revocation Request. This request includes the Wallet Instance Attestation with the Proof of Possession and a Credential Proof of Possession as a JWT. It MUST be signed with the private key related to the public key contained within the Credential (such as the Issuer Signed JWT in the case of SD-JWT, or the MSO in the case of Mdoc CBOR). Then, the Wallet Instance sends the request to the Issuer as in the following non-normative example. +**Step 1 (Credential Revocation Request)**: The Wallet Instance initiates the process by creating a Credential Revocation Request. This request includes a Digital Credential Proof of Possession as a JWT. It MUST be signed with the private key related to the public key contained within the Credential (such as the Issuer Signed JWT in the case of SD-JWT, or the MSO in the case of Mdoc CBOR). Then, the Wallet Instance sends the request to the Issuer as in the following non-normative example. .. _credential_revocation_request_ex: .. code-block:: @@ -204,8 +141,7 @@ A Wallet Instance MUST request the revocation of a Credential as defined below. Content-Type: application/x-www-form-urlencoded credential_proof=$CredentialPoPJWT - &client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-client-attestation - &client_assertion=$WIA~WIA-PoP + where a non-normative example of a Credential PoP is given by the following JWT headers and payload @@ -213,23 +149,22 @@ where a non-normative example of a Credential PoP is given by the following JWT .. code-block:: { - "alg": "ES256", - "typ": "revocation-request+jwt", - "kid": $WIA-CNF-JWKID - + "alg": "ES256", + "typ": "revocation-request+jwt", + "kid": $CREDENTIAL-CNF-JWKID } . { - "iss": "0b434530-e151-4c40-98b7-74c75a5ef760", - "aud": "https://pid-provider.example.org/revoke", - "iat": 1698744039, - "exp": 1698744139, - "jti": "6f204f7e-e453-4dfd-814e-9d155319408c", - "format": "vc+sd-jwt", - "credential": $Issuer-Signed-JWT + "iss": "0b434530-e151-4c40-98b7-74c75a5ef760", + "aud": "https://pid-provider.example.org/revoke", + "iat": 1698744039, + "exp": 1698744139, + "jti": "6f204f7e-e453-4dfd-814e-9d155319408c", + "credential_hash": $Issuer-Signed-JWT-Hash + "credential_hash_alg": "sha-256", } -**Step 2 (PoP verification)**: The Issuer verifies the signature of the PoP JWTs using the public key that was attested in the Wallet Instance Attestation and the Credential. If the verification is successful, it means that the Wallet Instance owns the private keys associated with the Wallet Instance Attestation and Credential, and therefore is entitled to request its revocation. +**Step 2 (PoP verification)**: The Issuer verifies the signature of the PoP JWTs using the public key that was attested in the issued Digital Credential. If the verification is successful, it means that the Wallet Instance owns the private keys associated with the Digital Credential, and therefore is entitled to request its revocation. **Step 3 (Credential Revocation)**: The Issuer revokes the Credential provided in the Credential PoP JWT. After the revocation, the Issuer MAY also send a notification to the User (e.g. using a User's email address, or telephone number or any other verified and secure communication channel), with all needed information related to the Credential revocation status update. This communication is out of scope of the current technical implemetation profile. @@ -243,7 +178,7 @@ where a non-normative example of a Credential PoP is given by the following JWT Credential Revocation HTTP Request -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The requests to the *Issuer Revocation endpoint* MUST be HTTP with method POST, using the mandatory parameters listed below within the HTTP request message body. These MUST be encoded in ``application/x-www-form-urlencoded`` format. @@ -256,96 +191,87 @@ The requests to the *Issuer Revocation endpoint* MUST be HTTP with method POST, - **Description** - **Reference** * - **credential_proof** - - It MUST contain a JWT proof of possession of the cryptographic key the Credential to be revoked shall be bound to. - - This specification - * - **client_assertion_type** - - It MUST be set to ``urn:ietf:params:oauth:client-assertion-type:jwt-client-attestation``. - - `oauth-attestation-draft `_. - * - **client_assertion** - - It MUST be set to a value containing the Wallet Instance Attestation JWT and the Proof of Possession, separated with the ``~`` character. - - `oauth-attestation-draft `_. + - It MUST contain a JWT proof of possession of the cryptographic key the Credential to be revoked shall be bound to. See Section :ref:`Credential Proof of Possession ` for more details. + - `[OAuth Status Attestation draft 00] `_ The Revocation Endpoint MUST be provided by the Issuer within its Metadata. -The Credential Proof of Possession MUST be a JWT that MUST contain the paramters (JOSE Header and claims) in the following table. +Credential Revocation HTTP Response +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -.. list-table:: - :widths: 20 60 20 - :header-rows: 1 +The response MUST be an HTTP Response using the status code set to *204 (No-Content)* in the case of successful revocation. If the Digital Credential could not be found by the Issuer, an HTTP Response with status code *404 (Not Found)* MUST be returned. Otherwise an HTTP error response MUST be provided by the Issuer to the Wallet Instance. This response MUST use *application/json* as the content type, and MUST include the following parameters: - * - **JOSE header** - - **Description** - - **Reference** - * - **typ** - - It MUST be set to ``revocation-request+jwt`` - - :rfc:`7516#section-4.1.1`, the value is defined within this specification - * - **alg** - - A digital signature algorithm identifier such as per IANA "JSON Web Signature and Encryption Algorithms" registry. It MUST be one of the supported algorithms listed in the Section `Cryptographic Algorithms `_ and MUST NOT be set to ``none`` or any symmetric algorithm (MAC) identifier. - - :rfc:`7516#section-4.1.1`. - * - **kid** - - Unique identifier of the ``jwk`` inside the ``cnf`` claim of the Credential to be revoked, as base64url-encoded JWK Thumbprint value. - - :rfc:`7638#section_3`. + - *error*. The error code. + - *error_description*. Text in human-readable form providing further details to clarify the nature of the error encountered. + +Below a non-normative example of an HTTP Response with an error. + +.. code:: + + HTTP/1.1 400 Bad Request + Content-Type: application/json;charset=UTF-8 + + { + "error":"invalid_request" + "error_description": "The signature of credential_pop JWT is not valid" + } + +The following HTTP Status Codes and Error Codes MUST be supported: .. list-table:: - :widths: 20 60 20 + :widths: 20 20 60 :header-rows: 1 - * - **Claim** + * - **Status Code** + - **Error Code** - **Description** - - **Reference** - * - **iss** - - Thumbprint of the JWK in the ``cnf`` parameter of the Wallet Instance Attestation. - - :rfc:`9126` and :rfc:`7519`. - * - **aud** - - It MUST be set to the identifier of the Issuer. - - :rfc:`9126` and :rfc:`7519`. - * - **exp** - - UNIX Timestamp with the expiry time of the JWT. - - :rfc:`9126` and :rfc:`7519`. - * - **iat** - - UNIX Timestamp with the time of JWT issuance. - - :rfc:`9126` and :rfc:`7519`. - * - **jti** - - Unique identifier for the PoP proof JWT. The value SHOULD be set using a *UUID v4* value according to [:rfc:`4122`]. - - [:rfc:`7519`. Section 4.1.7]. - * - **credential_format** - - The data format of the Credential to be revoked. It MUST be set to ``vc+sd-jwt`` or ``vc+mdoc`` - - This specification. - * - **credential** - - It MUST contain the Credential to be revoked encoded according to the data format given in the ``credential_format`` claim. - - [:rfc:`7519`. Section 4.1.7]. + * - *400 Bad Request* + - *invalid_request* + - The request is not valid due to the lack or incorrectness of one or more parameters. (:rfc:`6749#section-5.2`). + * - *500 Internal Server Error* + - *server_error* + - The Issuer encountered an internal problem. (:rfc:`6749#section-5.2`). + * - *503 Service Unavailable* + - *temporarily_unavailable* + - The Issuer is temporary unavailable. (:rfc:`6749#section-5.2`). -Credential Revocation HTTP Response -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -The response MUST be an HTTP Response using the status code set to 204 (No-Content). +Status Attestation Flows +------------------------ + +The Status Attestation flows are made up of two distinct phases in time + 1. The Status Attestation Request by a Wallet Instance: it involves the Wallet Instance and the Issuer. + 2. The Status Attestation Presentation to a Verifier: it involves the Wallet Instance and the Verifier. + + +.. figure:: ../../images/High-Level-Flow-Status-Attestation.svg + :figwidth: 100% + :align: center + + High-Level Status Attestation Flows -.. _sec_revocation_nra_request: -Non-Revocation Attestation Request ----------------------------------- +.. _sec_revocation_status_attestation_request: -The presentation of a Credential to a Verifier may occur long after it has been issued by the Issuer. During this time interval, the Credential can be invalidated for any reason and therefore the Verifier also needs to verify its revocation or suspension status. To address this scenario, the Issuer provides the Wallet Instance with a *Non-Revocation Attestation*. This Attestation is bound to a Credential so that the Wallet Instance can present it to a Verifier, along with the Credential itself, as a proof of non-revocation status of the Credential. +Status Attestation Request by Wallet Instance +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -The Non-Revocation Attestation MUST be presented in conjunction with the digital Credential. The Non-Revocation Attestation MUST be timestamped with its issuance datetime, always referring to a previous period. -The Non-Revocation Attestation MUST contain the expiration datetime after which the digital Credential MUST NOT be considered valid anymore. -The Non-Revocation Attestation enables offline use cases as it MUST be statically validated using the cryptographic signature of the Issuer. -Relying Parties MUST reject an expired Non-Revocation Attestation and, in the case of valid Attestations, they MAY still reject them according to their own policies (e.g., if the issue date doesn't meet their security requirements). +The presentation of a Credential to a Verifier may occur long after it has been issued by the Issuer. During this time interval, the Credential can be invalidated for any reason and therefore the Verifier also needs to verify its revocation or suspension status. To address this scenario, the Issuer provides the Wallet Instance with a *Status Attestation*. This Attestation is bound to a Credential so that the Wallet Instance can present it to a Verifier, along with the Credential itself, as a proof of non-revocation status of the Credential. -The following diagram shows how the Wallet Instance requests a Non-Revocation Attestation to the Issuer. +The following diagram shows how the Wallet Instance requests a Status Attestation to the Issuer. -.. _fig_Low-Level-Flow-Revocation-Attestation: +.. _fig_Low-Level-Flow-Status-Attestation: .. figure:: ../../images/Low-Level-Flow-Revocation-Attestation.svg :figwidth: 100% :align: center - :target: https://www.plantuml.com/plantuml/svg/PSr1ImCn40NWUtx5K3mek7WNAYsUreDTQd4lmZ9cHmna9p4pSV7YRtTQiANqEE_bork9Oj4wHOTL4zVfdOhB5WKVChB2eiSOIQ5bKMHF2q21EPo_QKKgbKCLd9i3D0yGxg7RlEpWpfnMWK9VbKIlVQ6HM0F68PUKFfPNZyUaIzrJlxi57uC50ugGhIGUz2VJPRpis_Llj-bkdFkVVCKOHbG2gnghtXYGHpXDW6s0ZPo8TNlmdBZPqdVokF_Qt5gLH0_N4PYOZMn9Sc8XE_JpN5ww5V5Of_W7 + :target: https://www.plantuml.com/plantuml/svg/NP11wzf04CNl-oaUqeE2shlGekZ57jfGfLw4iaacPccoa-xEAdxxpXAg_eLSPjxlJNx9EeeDalhEs2JiKrzIC8EkNEK6wmMJa-qw4kozahwY2Mp4pNrazZ4c2Zd2Mx99qfBN-UmFdCBOryUOcyFYAzmAnO_34P_rkgI8G7yJHPbMWUhSiztl8J0tNpvj7vk2Ys-duyoO_nT-sSxLLWXF1Wf1AMCyQy1N2d1p6rSujeJH5roATJwY2Tn3FV6mnIYBiy_hDEJhDQn8S6KIYh2-Hewk-TLExXZzjS1D3lAzmEdIAWbEik1cKUPIJrLhlOlzNDafBIzB9JEOMoXsttVO5Fk8U8z2_GpFhzosLFr1m-75u-n7j-ppS7cf1ChX8Rifkn6XxEdOZ_z6EGLlIlwaEB2Ff8Eq60juvzVawzHt_m00 - Non-Revocation Attestation Request Flow + Status Attestation Request Flow -**Step 1 (Non-Revocation Attestation Request)**: The Wallet Instance sends the Non-Revocation Attestation Request to the Issuer. The request MUST contain the Wallet Instance Attestation with its Proof of Possession and a Credential Proof of Possession JWT, signed with the private key related to the public key contained within the Credential. +**Step 1 (Status Attestation Request)**: The Wallet Instance sends the Status Attestation Request to the Issuer. The request MUST contain the Wallet Instance Attestation with its Proof of Possession and a Credential Proof of Possession JWT, signed with the private key related to the public key contained within the Credential. .. code:: @@ -354,14 +280,15 @@ The following diagram shows how the Wallet Instance requests a Non-Revocation At Content-Type: application/x-www-form-urlencoded credential_proof=$CredentialPoPJWT - &client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-client-attestation - &client_assertion=$WIA~WIA-PoP For a non-normative example of Credential Proof of Possession see :ref:`the one provided in the prevoius section `. -**Step 2 (PoP verification)**: The Issuer verifies the signature of the PoP JWTs using the public key that was attested in the Wallet Instance Attestation and the Credential, which is the proof that the Wallet Instance owns the private keys associated with the Wallet Instance Attestation and Credential. Therefore the Wallet Instance is entitled to request its Non-Revocation Attestation. +**Step 2 (PoP verification)**: The Issuer verifies the signature of the PoP JWTs using the public key that was attested in the Digital Credential, which is the proof that the Wallet Instance owns the private keys associated with the Digital Credential. Therefore the Wallet Instance is entitled to request its Status Attestation. -**Step 3 (Non-Revocation Attestation Creation)**: The Issuer checks the status of the Credential and creates a Non-Revocation Attestation bound to it. Then it creates a new Non-Revocation Attestation, a non-normative example of which is given below. +**Step 3 (Check for validity)**: The Issuer checks that the user's attributes are not updated by the Authentic Source or that the latter has not revoked them. The technical mechanisms for obtaining this information are out-of-scope of this technical implementation profile. + + +**Step 4 (Status Attestation Creation)**: The Issuer creates the corresponding Status Attestation. A non-normative example of a Status Attestation is given below. .. code:: @@ -378,11 +305,11 @@ For a non-normative example of Credential Proof of Possession see :ref:`the one "credential_hash": $CREDENTIAL-HASH, "credential_hash_alg": "sha-256", "cnf": { - "jwk": {...} + "jwk": $CREDENTIAL-CNF-JWK } } -**Step 4 (Non-Revocation Attestation Response)**: The Issuer then returns the Non-Revocation Attestation to the Wallet Instance, as in the following non-normative example. +**Step 4 (Status Attestation Response)**: The Issuer then returns the Status Attestation to the Wallet Instance, as in the following non-normative example. .. code:: @@ -390,22 +317,35 @@ For a non-normative example of Credential Proof of Possession see :ref:`the one Content-Type: application/json { - "non_revocation_attestation": "eyJhbGciOiJFUzI1NiIsInR5cCI6IndhbGxldC1...", + "status_attestation": "eyJhbGciOiJFUzI1NiIsInR5cCI6IndhbGxldC1...", } -Non-Revocation Attestation HTTP Request -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Status Attestation HTTP Request +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The requests to the *Credential status endpoint* of the Issuers MUST be HTTP with method POST, using the same mandatory parameters as in the :ref:`Table of Credential Request parameters `. These MUST be encoded in ``application/x-www-form-urlencoded`` format. + +.. list-table:: + :widths: 20 60 20 + :header-rows: 1 + + * - **Claim** + - **Description** + - **Reference** + * - **credential_proof** + - It MUST contain a signed JWT as a cryptographic proof of possession of the Digital Credential. See Section :ref:`Credential Proof of Possession ` for more details. + - `[OAuth Status Attestation draft 00] `_ -The requests to the *Credential status endpoint* of the Issuers MUST be HTTP with method POST, using the same mandatory parameters as in the :ref:`Table of Credential Request parameters `. These MUST be encoded in ``application/x-www-form-urlencoded`` format. +The *typ* value in the *credential_pop* JWT MUST be set to **status-attestation+jwt** -The *Credential status endpoint* MUST be provided by the Issuer within its Metadata. +The *Credential status endpoint* MUST be provided by the Issuers within their Metadata. The Issuers MUST include in the issued Digital Credentials the object *status* with the JSON member *status_attestation* set to a JSON Object containing the *credential_hash_alg* claim. It MUST contain the algorithm used for hashing the Digital Credential. Among the hash algorithms, sha-256 is RECOMMENDED. -Non-Revocation Attestation HTTP Response -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Status Attestation HTTP Response +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The *Credential status endpoint* MUST return a response with a *HTTP status code 201 OK* if the Credential is valid at the time of the request, otherwise a *HTTP status code 404 Not Found* MUST be given by the Issuer. The responses MUST be encoded in ``application/json`` format. It MUST contain the following mandatory claims. +The *Credential status endpoint* MUST return a response with a *HTTP status code 201 OK* if the Credential is valid at the time of the request. The responses MUST be encoded in ``application/json`` format. It MUST contain the following mandatory claims. .. _table_http_response_claim: .. list-table:: @@ -415,15 +355,123 @@ The *Credential status endpoint* MUST return a response with a *HTTP status code * - **Claim** - **Description** - **Reference** - * - **non_revocation_attestation** - - It MUST contain the Non-Revocation Attestation as a signed JWT. - - This specification. + * - **status_attestation** + - It MUST contain the Status Attestation as a signed JWT. + - `[OAuth Status Attestation draft 00] `_. + +If the Digital Credential could not be found by the Issuer, an HTTP Response with status code 404 (Not Found) MUST be returned. In all other cases the Issuer MUST return an HTTP Response Error using *application/json* as the content type, and including the following parameters: + + - *error*. The error code. + - *error_description*. Text in human-readable form that offers more details to clarify the nature of the error encountered (for instance, changes in some attributes, reasons for revocation, other). + +Below a non-normative example of an HTTP Response with an error. + +.. code:: + + HTTP/1.1 400 Bad Request + Content-Type: application/json;charset=UTF-8 + + { + "error":"invalid_request" + "error_description": "The signature of credential_pop JWT is not valid" + } + +The following HTTP Status Codes and Error Codes MUST be supported: + +.. list-table:: + :widths: 20 20 60 + :header-rows: 1 + + * - **Status Code** + - **Error Code** + - **Description** + * - *400 Bad Request* + - *invalid_request* + - The request is not valid due to the lack or incorrectness of one or more parameters. (:rfc:`6749#section-5.2`). + * - *500 Internal Server Error* + - *server_error* + - The Issuer encountered an internal problem. (:rfc:`6749#section-5.2`). + * - *503 Service Unavailable* + - *temporarily_unavailable* + - The Issuer is temporary unavailable. (:rfc:`6749#section-5.2`). + * - *400 Bad Request* + - *credential_revoked* + - The Digital Credential is revoked. The reason of revocation MUST be provided in the *error_description* field. + * - *400 Bad Request* + - *credential_updated* + - One or more attributes contained in the Digital Credential are changed. The *error_description* field MUST contain a list of updated attributes. + + +.. _sec_revocation_nra_presentation: + +Status Attestation Presentation to the Verifiers +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +During the presentation phase, a Verifier MAY request the Wallet Instance to provide a Non-Revocation Attestation along with the requested Credential. If a Verifier requests a Status Attestation for a requested Digital Credential, the Wallet Instance MUST provides the Status Attestations in the *vp_token* JSON array. If the Status Attestation is requested by the Verifier and the Wallet Instance is not able to provide it or it is expired or it is issued far back in time, the Verifier MAY decide to accept or reject the Credential according to its security policy. + +Law-Enforcement Authorities or Third Parties authorized by national law, MAY require deferred non-revocation status verification but the definition of these protocols is currently out-of-scope for this technical implementation profile. + -Non-Revocation Attestation -^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. _sec_revocation_credential_pop: -The Non-Revocation Attestation MUST contain the following claims. +Credential Proof of Possession +------------------------------ + +The Credential Proof of Possession (**credential_proof**) MUST be a JWT that MUST contain the paramters (JOSE Header and claims) in the following table. + +.. list-table:: + :widths: 20 60 20 + :header-rows: 1 + + * - **JOSE header** + - **Description** + - **Reference** + * - **typ** + - In case of revocation request it MUST be set to ``revocation-request+jwt``. In case of Status Attestation request it MUST be set to ``status-attestation-request+jwt``, according to `[OAuth Status Attestation draft 00] `_. + - :rfc:`7516#section-4.1.1`. + * - **alg** + - A digital signature algorithm identifier such as per IANA "JSON Web Signature and Encryption Algorithms" registry. It MUST be one of the supported algorithms listed in the Section `Cryptographic Algorithms `_ and MUST NOT be set to ``none`` or any symmetric algorithm (MAC) identifier. + - :rfc:`7516#section-4.1.1`. + * - **kid** + - Unique identifier of the ``jwk`` inside the ``cnf`` claim of the Credential to be revoked, as base64url-encoded JWK Thumbprint value. + - :rfc:`7638#section_3`. + +.. list-table:: + :widths: 20 60 20 + :header-rows: 1 + + * - **Claim** + - **Description** + - **Reference** + * - **iss** + - Thumbprint of the JWK in the ``cnf`` parameter of the Wallet Instance Attestation. + - :rfc:`9126` and :rfc:`7519`. + * - **aud** + - It MUST be set to the identifier of the Issuer. + - :rfc:`9126` and :rfc:`7519`. + * - **exp** + - UNIX Timestamp with the expiry time of the JWT. + - :rfc:`9126` and :rfc:`7519`. + * - **iat** + - UNIX Timestamp with the time of JWT issuance. + - :rfc:`9126` and :rfc:`7519`. + * - **jti** + - Unique identifier for the PoP proof JWT. The value SHOULD be set using a *UUID v4* value according to [:rfc:`4122`]. + - [:rfc:`7519`. Section 4.1.7]. + * - **credential_hash** + - It MUST contain the hash value of a Digital Credential, derived by computing the base64url encoded hash of the Digital Credential. + - `[OAuth Status Attestation draft 00] `_. + * - **credential_hash_alg** + - It MUST contain the Algorithm used for hashing the Digital Credential. The value SHOULD be set to `S256`. + - `[OAuth Status Attestation draft 00] `_. + + + +Status Attestation +------------------ + +The Status Attestation MUST contain the following claims. .. _table_non_revocation_attestation_header: .. list-table:: @@ -437,8 +485,8 @@ The Non-Revocation Attestation MUST contain the following claims. - A digital signature algorithm identifier such as per IANA "JSON Web Signature and Encryption Algorithms" registry. It MUST be one of the supported algorithms in Section :ref:`Cryptographic Algorithms ` and MUST NOT be set to ``none`` or to a symmetric algorithm (MAC) identifier. - `[OIDC4VCI. Draft 13] `_, [:rfc:`7515`], [:rfc:`7517`]. * - **typ** - - It MUST be set to `non-revocation-attestation+jwt`. - - [:rfc:`7515`], [:rfc:`7517`], this specification. + - It MUST be set to `status-attestation+jwt`. + - [:rfc:`7515`], [:rfc:`7517`], `[OAuth Status Attestation draft 00] `_.. * - **kid** - Unique identifier of the Issuer ``jwk`` as base64url-encoded JWK Thumbprint value. - :rfc:`7638#section_3`. @@ -461,23 +509,12 @@ The Non-Revocation Attestation MUST contain the following claims. - UNIX Timestamp with the expiry time of the JWT. - :rfc:`9126` and :rfc:`7519`. * - **credential_hash** - - Hash value of the Credential the Non-Revocation Attestation is bound to. - - This specification. + - Hash value of the Credential the Status Attestation is bound to. + - `[OAuth Status Attestation draft 00] `_. * - **credential_hash_alg** - - The Algorithm used of hashing the Credential to which the Non-Revocation Attestation is bound. The value MUST be set to ``S256``. - - This specification. + - The Algorithm used of hashing the Credential to which the Status Attestation is bound. The value SHOULD be set to ``S256``. + - `[OAuth Status Attestation draft 00] `_. * - **cnf** - JSON object containing the proof-of-possession key materials. The ``cnf`` jwk value MUST match with the one provided within the related Credential. - `[RFC7800, Section 3.1] `_. - - -.. _sec_revocation_nra_presentation: - -Non-Revocation Proof during the Presentation Phase --------------------------------------------------- - -During the presentation phase, a Verifier MAY request the Wallet Instance to provide a Non-Revocation Attestation along with the requested Credential (e.g. using the ``scope`` parameter). The Wallet Instance MUST provide the Verifier with a most recent Non-Revocation Attestation. If the Attestation is requested by the Verifier and the Wallet Instance is not able to provide it or it is expired the Verifier MUST reject the Credential. If the Attestation is issued far back in time, the Verifier MAY decide to accept or reject the Credential according to its security policy. - -Law-Enforcement Authorities or Third Parties authorized by national law, MAY require deferred non-revocation status verification but the definition of these protocols is currently out-of-scope for this technical implementation profile. - diff --git a/images/High-Level-Flow-Status-Attestation.svg b/images/High-Level-Flow-Status-Attestation.svg new file mode 100644 index 000000000..93bb76594 --- /dev/null +++ b/images/High-Level-Flow-Status-Attestation.svg @@ -0,0 +1,3 @@ + + +
Credential Issuer
Wallet Instance
Verifier
1
Request a Status Attestation for a Digital Credential
Provide a Status Attestation for a Digital Credential
Request a Digital Credential with a corresponding Status Attestation
Present a Digital Credential with a corresponding Status Attestation
2
3
4
At time t0, a Status Attestation is obtained by the Wallet Instance for each stored Digital Credential
At time t1, greater that t0 and less that the expiration time of the Status Attestation, the Wallet Instance present a Digital Credential and the corresponding Status Attestation if requested.

This page contains the following errors:

error on line 3 at column 6: XML declaration allowed only at the start of the document

Below is a rendering of the page up to the first error.

 \ No newline at end of file diff --git a/images/Low-Level-Flow-Revocation-Attestation.svg b/images/Low-Level-Flow-Revocation-Attestation.svg index 13aae6545..5210432c1 100644 --- a/images/Low-Level-Flow-Revocation-Attestation.svg +++ b/images/Low-Level-Flow-Revocation-Attestation.svg @@ -1 +1 @@ -Wallet InstanceWallet InstanceIssuerIssuer1POST /status request(credential_proof=$CredentialPoPJWT, client_assertion_type, client_assertion=WIA~POP)2Validate WIA-POPand Credential PoP JWT3Create Non-RevocationAttestation JWT4Response with Non-Revocation Attestation JWT \ No newline at end of file +Wallet InstanceWallet InstanceIssuerIssuerAuthenticSourceAuthenticSource1POST /status request(credential_proof=$CredentialPoPJWT)2Validate Credential PoP JWTThe Issuer obtains from the Authentic Sourcethe updated attributes and the validity statusof them through an out-of-band mechanism,(e.g. though the PDND APIs system)3Check for attributesupdate and validity4Create StatusAttestation JWT5Response with Status Attestation JWT \ No newline at end of file diff --git a/images/Low-Level-Flow-Revocation.svg b/images/Low-Level-Flow-Revocation.svg index 5f5bd4538..01b0b5f15 100644 --- a/images/Low-Level-Flow-Revocation.svg +++ b/images/Low-Level-Flow-Revocation.svg @@ -1 +1 @@ -Wallet InstanceWallet InstanceIssuerIssuer1POST /revoke request(credential_proof=$CredentialPoPJWT, client_assertion_type, client_assertion=WIA~POP)2Validate WIA-POPand Credential POP3Revoke Credential4Response Ok \ No newline at end of file +Wallet InstanceWallet InstanceIssuerIssuer1POST /revoke request(credential_proof=$CredentialPoPJWT)2Validate the CredentialProof of Possession3Revoke the Credential4Response Ok \ No newline at end of file diff --git a/images/revocation-entity-relationship.svg b/images/revocation-entity-relationship.svg deleted file mode 100644 index fe1a701ef..000000000 --- a/images/revocation-entity-relationship.svg +++ /dev/null @@ -1,3 +0,0 @@ - - -
Request for user attributes
Request for user attributes
Notify attributes update 
and revocation of the 
physical document
Notify attributes update...
Authentic Source
Authentic Source
Issuer
Issuer
Check the credential
non-revocation status
Check the credential...
Verifier
Verifier
I
I
Interact with
Interact with
Request for
attributes update
Request for...
Request for revocation
of physical document
Request for revocation...
Check the credential non-revocation status
end request for credential revocation
Check the credential non-revocation status...
Holders
Holders
Wallet Instance
Wallet Instance
Request for credential
revocation
Request for credential...
Request for revocation
of physical document
Request for revocation...
Request for credential
revocation
Request for credential...
Check the credential
non-revocation status
Check the credential...
Law Enforcing Bodies
Law Enforcing Bodies
Check the credential
non-revocation status
Check the credential...
Revoke the
credential
Revoke the...
Provide the non-revocation attestation
Provide the non-revocation attestationText is not SVG - cannot display \ No newline at end of file diff --git a/images/revocation-processes.svg b/images/revocation-processes.svg deleted file mode 100644 index be042c7b5..000000000 --- a/images/revocation-processes.svg +++ /dev/null @@ -1,3 +0,0 @@ - - -
High-Level Revocation Processes
High-Level Revocation Processes
Holder
Holder
Requires attributes to be updated
Requires attributes...
Request for revocation of a Credential
Request for revocati...
Start
Start
Request for revocation of a physical document
Request for revocati...
NEW
NEW
Law Enforcing Bodies
Law Enforcing Bodies
Start
(e.g. Police
check)
Start...
Request for revocation of a physical document
Request for revocati...
Authentic Source
Authentic Source
Elaborate the request
Elaborate the request
Update its database with changed document status information or attributes
Update its database...
Start
Start
Send notification on revocation status of physical document or attributes update 
Send notification on...
Local
DB
Local...
NEW
NEW
Issuer
Issuer
Receive notification on revocation status or attributes update
Receive notification...
Elaborate the request
Elaborate the request
Revoke the Credential
Revoke the Credential
Start
(e.g. in the case of
compromised
cryptographic keys)
Start...
Send notification to the Holder
Send notification to...
NEW
NEW
NEW
NEW
NEW
NEW
NEW
NEW
End
EndText is not SVG - cannot display \ No newline at end of file From d85ce1418032871253ed2a033292b77895f22529 Mon Sep 17 00:00:00 2001 From: fmarino-ipzs Date: Wed, 28 Feb 2024 09:16:18 +0100 Subject: [PATCH 19/28] chore: fix figure typo --- images/High-Level-Flow-Status-Attestation.svg | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/images/High-Level-Flow-Status-Attestation.svg b/images/High-Level-Flow-Status-Attestation.svg index 93bb76594..fe109258f 100644 --- a/images/High-Level-Flow-Status-Attestation.svg +++ b/images/High-Level-Flow-Status-Attestation.svg @@ -1,3 +1,4 @@ + -
Credential Issuer
Wallet Instance
Verifier
1
Request a Status Attestation for a Digital Credential
Provide a Status Attestation for a Digital Credential
Request a Digital Credential with a corresponding Status Attestation
Present a Digital Credential with a corresponding Status Attestation
2
3
4
At time t0, a Status Attestation is obtained by the Wallet Instance for each stored Digital Credential
At time t1, greater that t0 and less that the expiration time of the Status Attestation, the Wallet Instance present a Digital Credential and the corresponding Status Attestation if requested.

This page contains the following errors:

error on line 3 at column 6: XML declaration allowed only at the start of the document

Below is a rendering of the page up to the first error.

 \ No newline at end of file +
Credential Issuer
Wallet Instance
Verifier
1
Request a Status Attestation for a Digital Credential
Provide a Status Attestation for a Digital Credential
Request a Digital Credential with a corresponding Status Attestation
Present a Digital Credential with a corresponding Status Attestation
2
3
4
At time t0, a Status Attestation is obtained by the Wallet Instance, for each stored Digital Credential
At time t1, greater that t0 and less that the expiration time of the Status Attestation, the Wallet Instance presents a Digital Credential and the corresponding Status Attestation if requested.

This page contains the following errors:

error on line 3 at column 6: XML declaration allowed only at the start of the document

Below is a rendering of the page up to the first error.

 \ No newline at end of file From a85429128b2a739f933078ce6700f24546d0734d Mon Sep 17 00:00:00 2001 From: fmarino-ipzs Date: Wed, 28 Feb 2024 10:24:24 +0100 Subject: [PATCH 20/28] chore: editorial fix typo --- docs/en/revocation-lists.rst | 26 +++++++++++++------------- 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/docs/en/revocation-lists.rst b/docs/en/revocation-lists.rst index b61fdcac7..1c5868dc0 100644 --- a/docs/en/revocation-lists.rst +++ b/docs/en/revocation-lists.rst @@ -8,18 +8,18 @@ Credential Lifecycle The value of a Digital Credential is conditional on its validity. A Credential that has been revoked, due to legal requirements, inaccuracy or compromise, is valueless and potentially harmful. For these reasons a robust mechanism for managing the life-cycle and the revocation of a Digital Credential is required. -This section outlines the key technical requirements and processes related to the revocation of the Digital Credentials. +This section outlines the key technical requirements and processes related to the revocation of Digital Credentials. Furthermore, it provides the technical details that the Verifiers MUST implement to verify, in a secure and reliable manner, the validity of a Digital Credential during the presentation phase. The verification of the validity of a Digital Credential is based on the `[OAuth Status Attestation draft 00] `_ specification. -A Status Attestation is a signed object that is evidence of the validity status of a Digital Credential. These attestations are provided by the Issuer to Holders who can present them to Verifiers together with the corresponding Digital Credentials. +A Status Attestation is a signed object that is evidence of the validity status of a Digital Credential. The Issuer provides these attestations to Holders who can present them to Verifiers together with the corresponding Digital Credentials. Generally, the Status Attestation enables: - an entirely automated issuance flow, as the User authentication is not required; - the verification of the digital Credential validity status when both the Wallet Instance and the Verifier are offline; -- a better privacy of the User since: +- better privacy of the User since: 1. the Verifier cannot check over time the validity of a given Digital Credential related to the User; 2. it prevents issuers to track when and where a Digital Credential is verified. @@ -70,7 +70,7 @@ Requirements **The Wallet Instance MUST:** -- check periodically the validity status of the Digital Credential that are stored in it, requesting a Status Attestation for each Digital Credential; +- check periodically the validity status of the Digital Credential that is stored in it, requesting a Status Attestation for each Digital Credential; - be able to present a Status Attestation if required by a Verifier, along with the corresponding Digital Credential; - request a revocation of a Digital Credential when the Users delete it from the storage. @@ -113,7 +113,7 @@ Revocation Flows ---------------- Depending on the different scenarios that may involve the revocation of a Digital Credential, different processes and technical flows may be implemented, according to national laws or Regulations of specific domains. -The subsequent sections define the protocol interface between the Wallet Instances and the Issuers during the revocation request. The communication between the the Issuers and other Entities are out of scope of this technical implementation profile. +The subsequent sections define the protocol interface between the Wallet Instances and the Issuers during the revocation request. The communication between the the Issuers and other Entities is out-of-scope of this technical implementation profile. .. _sec_revocation_wi_initiated_flow: @@ -166,7 +166,7 @@ where a non-normative example of a Credential PoP is given by the following JWT **Step 2 (PoP verification)**: The Issuer verifies the signature of the PoP JWTs using the public key that was attested in the issued Digital Credential. If the verification is successful, it means that the Wallet Instance owns the private keys associated with the Digital Credential, and therefore is entitled to request its revocation. -**Step 3 (Credential Revocation)**: The Issuer revokes the Credential provided in the Credential PoP JWT. After the revocation, the Issuer MAY also send a notification to the User (e.g. using a User's email address, or telephone number or any other verified and secure communication channel), with all needed information related to the Credential revocation status update. This communication is out of scope of the current technical implemetation profile. +**Step 3 (Credential Revocation)**: The Issuer revokes the Credential provided in the Credential PoP JWT. After the revocation, the Issuer MAY also send a notification to the User (e.g. using a User's email address, telephone number, or any other verified and secure communication channel), with all needed information related to the Credential revocation status update. This communication is out of scope of the current technical implementation profile. **Step 4 (Credential Revocation Response)**: The Issuer sends a response back to the Wallet Instance with the result of the revocation request. @@ -200,7 +200,7 @@ The Revocation Endpoint MUST be provided by the Issuer within its Metadata. Credential Revocation HTTP Response ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The response MUST be an HTTP Response using the status code set to *204 (No-Content)* in the case of successful revocation. If the Digital Credential could not be found by the Issuer, an HTTP Response with status code *404 (Not Found)* MUST be returned. Otherwise an HTTP error response MUST be provided by the Issuer to the Wallet Instance. This response MUST use *application/json* as the content type, and MUST include the following parameters: +The response MUST be an HTTP Response using the status code set to *204 (No-Content)* in the case of successful revocation. If the Digital Credential could not be found by the Issuer, an HTTP Response with status code *404 (Not Found)* MUST be returned. Otherwise an HTTP error response MUST be provided by the Issuer to the Wallet Instance. This response MUST use *application/json* as the content type and MUST include the following parameters: - *error*. The error code. - *error_description*. Text in human-readable form providing further details to clarify the nature of the error encountered. @@ -259,7 +259,7 @@ The Status Attestation flows are made up of two distinct phases in time Status Attestation Request by Wallet Instance ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -The presentation of a Credential to a Verifier may occur long after it has been issued by the Issuer. During this time interval, the Credential can be invalidated for any reason and therefore the Verifier also needs to verify its revocation or suspension status. To address this scenario, the Issuer provides the Wallet Instance with a *Status Attestation*. This Attestation is bound to a Credential so that the Wallet Instance can present it to a Verifier, along with the Credential itself, as a proof of non-revocation status of the Credential. +The presentation of a Credential to a Verifier may occur long after it has been issued by the Issuer. During this time interval, the Credential can be invalidated for any reason and therefore the Verifier also needs to verify its revocation or suspension status. To address this scenario, the Issuer provides the Wallet Instance with a *Status Attestation*. This Attestation is bound to a Credential so that the Wallet Instance can present it to a Verifier, along with the Credential itself, as proof of non-revocation status of the Credential. The following diagram shows how the Wallet Instance requests a Status Attestation to the Issuer. @@ -281,9 +281,9 @@ The following diagram shows how the Wallet Instance requests a Status Attestatio credential_proof=$CredentialPoPJWT -For a non-normative example of Credential Proof of Possession see :ref:`the one provided in the prevoius section `. +For a non-normative example of Credential Proof of Possession see :ref:`the one provided in the previous section `. -**Step 2 (PoP verification)**: The Issuer verifies the signature of the PoP JWTs using the public key that was attested in the Digital Credential, which is the proof that the Wallet Instance owns the private keys associated with the Digital Credential. Therefore the Wallet Instance is entitled to request its Status Attestation. +**Step 2 (PoP verification)**: The Issuer verifies the signature of the PoP JWTs using the public key that was attested in the Digital Credential, which is proof that the Wallet Instance owns the private keys associated with the Digital Credential. Therefore the Wallet Instance is entitled to request its Status Attestation. **Step 3 (Check for validity)**: The Issuer checks that the user's attributes are not updated by the Authentic Source or that the latter has not revoked them. The technical mechanisms for obtaining this information are out-of-scope of this technical implementation profile. @@ -407,7 +407,7 @@ The following HTTP Status Codes and Error Codes MUST be supported: Status Attestation Presentation to the Verifiers ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -During the presentation phase, a Verifier MAY request the Wallet Instance to provide a Non-Revocation Attestation along with the requested Credential. If a Verifier requests a Status Attestation for a requested Digital Credential, the Wallet Instance MUST provides the Status Attestations in the *vp_token* JSON array. If the Status Attestation is requested by the Verifier and the Wallet Instance is not able to provide it or it is expired or it is issued far back in time, the Verifier MAY decide to accept or reject the Credential according to its security policy. +During the presentation phase, a Verifier MAY request the Wallet Instance to provide a Non-Revocation Attestation along with the requested Credential. If a Verifier requests a Status Attestation for a requested Digital Credential, the Wallet Instance MUST provide the Status Attestations in the *vp_token* JSON array. If the Status Attestation is requested by the Verifier and the Wallet Instance is not able to provide it or it is expired or it is issued far back in time, the Verifier MAY decide to accept or reject the Credential according to its security policy. Law-Enforcement Authorities or Third Parties authorized by national law, MAY require deferred non-revocation status verification but the definition of these protocols is currently out-of-scope for this technical implementation profile. @@ -418,7 +418,7 @@ Law-Enforcement Authorities or Third Parties authorized by national law, MAY req Credential Proof of Possession ------------------------------ -The Credential Proof of Possession (**credential_proof**) MUST be a JWT that MUST contain the paramters (JOSE Header and claims) in the following table. +The Credential Proof of Possession (**credential_proof**) MUST be a JWT that MUST contain the parameters (JOSE Header and claims) in the following table. .. list-table:: :widths: 20 60 20 @@ -512,7 +512,7 @@ The Status Attestation MUST contain the following claims. - Hash value of the Credential the Status Attestation is bound to. - `[OAuth Status Attestation draft 00] `_. * - **credential_hash_alg** - - The Algorithm used of hashing the Credential to which the Status Attestation is bound. The value SHOULD be set to ``S256``. + - The Algorithm used for hashing the Credential to which the Status Attestation is bound. The value SHOULD be set to ``S256``. - `[OAuth Status Attestation draft 00] `_. * - **cnf** - JSON object containing the proof-of-possession key materials. The ``cnf`` jwk value MUST match with the one provided within the related Credential. From d5ff33934b4996bff8657c67b7f1bc0928d28dfb Mon Sep 17 00:00:00 2001 From: fmarino-ipzs <77629526+fmarino-ipzs@users.noreply.github.com> Date: Wed, 28 Feb 2024 10:35:29 +0100 Subject: [PATCH 21/28] Apply suggestions from code review Co-authored-by: Giuseppe De Marco --- docs/en/revocation-lists.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/en/revocation-lists.rst b/docs/en/revocation-lists.rst index 1c5868dc0..a6061f55c 100644 --- a/docs/en/revocation-lists.rst +++ b/docs/en/revocation-lists.rst @@ -17,7 +17,7 @@ A Status Attestation is a signed object that is evidence of the validity status Generally, the Status Attestation enables: -- an entirely automated issuance flow, as the User authentication is not required; +- an entirely automated issuance flow, as the User authentication is not required for the provisioning of the Status Attestation; - the verification of the digital Credential validity status when both the Wallet Instance and the Verifier are offline; - better privacy of the User since: From da8a163e11720a812cc9e256e043da2d55b891b7 Mon Sep 17 00:00:00 2001 From: fmarino-ipzs <77629526+fmarino-ipzs@users.noreply.github.com> Date: Wed, 28 Feb 2024 19:15:39 +0100 Subject: [PATCH 22/28] Apply suggestions from code review Co-authored-by: Giuseppe De Marco Co-authored-by: Giada Sciarretta --- docs/en/revocation-lists.rst | 60 ++++++++++++++++++------------------ 1 file changed, 30 insertions(+), 30 deletions(-) diff --git a/docs/en/revocation-lists.rst b/docs/en/revocation-lists.rst index a6061f55c..53878b13d 100644 --- a/docs/en/revocation-lists.rst +++ b/docs/en/revocation-lists.rst @@ -11,18 +11,18 @@ For these reasons a robust mechanism for managing the life-cycle and the revocat This section outlines the key technical requirements and processes related to the revocation of Digital Credentials. Furthermore, it provides the technical details that the Verifiers MUST implement to verify, in a secure and reliable manner, the validity of a Digital Credential during the presentation phase. -The verification of the validity of a Digital Credential is based on the `[OAuth Status Attestation draft 00] `_ specification. +The verification of the validity of a Digital Credential is based on the `[OAuth Status Attestation draft 01] `_ specification. -A Status Attestation is a signed object that is evidence of the validity status of a Digital Credential. The Issuer provides these attestations to Holders who can present them to Verifiers together with the corresponding Digital Credentials. +A Status Attestation is a signed document serving as proof of a Digital Credential's current validity status. The Issuer provides these attestations to Holders who can present them to Verifiers together with the corresponding Digital Credentials. -Generally, the Status Attestation enables: +The Status Attestations have the following features: -- an entirely automated issuance flow, as the User authentication is not required for the provisioning of the Status Attestation; -- the verification of the digital Credential validity status when both the Wallet Instance and the Verifier are offline; -- better privacy of the User since: +- automated issuance, as the User authentication is not required for the provisioning of the Status Attestation; +- verification of the digital Credential validity status when both the Wallet Instance and the Verifier are offline; +- improved privacy, according to the following evidences: 1. the Verifier cannot check over time the validity of a given Digital Credential related to the User; - 2. it prevents issuers to track when and where a Digital Credential is verified. + 2. the Issuers cannot track when and where a Digital Credential is verified. 3. it doesn't reveal any information about the Users or the content of their Digital Credentials. .. _sec_revocation_assumption: @@ -30,9 +30,9 @@ Generally, the Status Attestation enables: General Assumptions ------------------- - - All the Status Attestations can only be acquired when the Wallet Instance has an internet connection and is actively executed by the User. - - A Credential Issuer, is in charge of the creation and the issuance of Credentials, its lifecycle and its validity status. - - When one or more Authentic Sources are involved in the issuance of a Digital Credential, the information exchanged between the Authentic Source and the PID/(Q)EAA Provider is required for the issuance of the Credential and, in the cases where the revocation is requested by the Authentic Source, also for the the revocation of the Credential. +- **Internet Connection for Status Attestations**: Status Attestations can be obtained only when the Wallet Instance is connected to the internet and actively operated by the User. +- **Role of a Credential Issuer**: A Credential Issuer is responsible for creating and issuing Credentials, as well as managing their lifecycle and validity status. +- **Involvement of Authentic Sources**: When one or more Authentic Sources are involved in the issuance of a Digital Credential, the information exchanged between the Authentic Source and the PID/(Q)EAA Provider is crucial for the credential's issuance. Furthermore, in cases where the Authentic Source initiates a revocation or data changes, revoking the Credential becomes necessary. .. _sec_revocation_requirements: @@ -54,11 +54,11 @@ Requirements **The Issuer MUST:** - ensure that the data contained in a Digital Credential is kept up to date, including the status of validity of the data from the Authentic Source; -- revoke a Digital Credential when +- revoke a Digital Credential when the following circumstances occur: - - it requires to be updated, whenever one or more attributes are changed; in this case the User will request a new issuance for that Digital Credential; - - the Wallet Instance to which it was issued is revoked; - - the User deletes it from the Wallet Instance; + - the Digital Credential requires to be updated, whenever one or more attributes are changed; in this case the User will request a new issuance for that Digital Credential; + - the Wallet Instance that holds the Digital Credential was issued is revoked; + - the User deletes the Digital Credential from the Wallet Instance; - provide a web service for allowing a Wallet Instance, with a proof of possession of a specific Digital Credential, to @@ -87,7 +87,7 @@ Revocation Use Cases The revocation of a Digital Credential MAY be triggered by: - Users using their personal Wallet Instance or by some out-of-band touchpoints. -- Revocation of the Wallet Instance +- Revocation of the Wallet Instance. - Authentic Sources (e.g., for attribute updates) following administrative purposes. - Law-Enforcing Bodies for the fulfillment of their functions and any other judicial reasons (e.g., Police). @@ -95,16 +95,16 @@ Credential Revocation Flows can start under different scenarios, such as: - The User reports the loss or theft of their own physical document to the Law-Enforcement Authorities: this implies that the Credentials, if any, shall be revoked. - The User notifies an Authentic Source that one or more attributes are changed (e.g. the current resident address): in this case the Credentials SHALL be revoked, as they are no longer valid due to the change in attributes. - - The Users who no longer have access to their Wallet Instance (e.g. theft or loss of the device), may request the Issuer of the Credentials to revoke them or may request the Wallet Provider to revoke the Wallet Instance which in turn implies the revocation of all Digital Credentials stored in the Wallet Instance. + - Users who lose access to their Wallet Instance (e.g., due to theft or loss of the device) can request the Credential Issuer to revoke their Credentials or ask the Wallet Provider to revoke the Wallet Instance. If the Wallet Provider is authorized by the User and is aware of the types of Credentials and their issuers stored in the Wallet, it can then initiate the revocation of all Digital Credentials contained within the Wallet Instance on behalf of the User. - The Law-Enforcing Authorities, for the fulfillment of their functions and any other judicial reasons, may request the Authentic Source to revoke entitlements, licenses, certificates, identification documents, etc., which in turn leads to the revocation of any linked Credentials. - - The Authentic Sources that for any administrative reasons update one or more attributes of a User, SHALL inform the Issuer of related Credentials. + - The Authentic Sources that for any administrative reasons update one or more attributes of a User, shall inform the Issuer of related Credentials. - The Issuers, for technical security reasons (e.g. in the case of compromised cryptographic keys, death of the User, etc.), can decide to revoke the Credentials. The revocation scenarios involve two main flows: - The **Revocation flows**: these flows describe how an Entity requests for a Digital Credential revocation. - - The **Status Attestation flows**: these flows define the technical protocols for requesting and obtaining a Status Attestation and how the Wallet Instance will provide it with a Verifier as a proof of validity of a corresponding Digital Credential. + - The **Status Attestation flows**: these flows define the technical protocols for requesting and obtaining a Status Attestation and how the Wallet Instance will provide it to a Verifier as a proof of validity of a corresponding Digital Credential. .. _sec_revocation_high_level_flow: @@ -113,7 +113,7 @@ Revocation Flows ---------------- Depending on the different scenarios that may involve the revocation of a Digital Credential, different processes and technical flows may be implemented, according to national laws or Regulations of specific domains. -The subsequent sections define the protocol interface between the Wallet Instances and the Issuers during the revocation request. The communication between the the Issuers and other Entities is out-of-scope of this technical implementation profile. +The subsequent sections define the protocol interface between the Wallet Instances and the Issuers during the revocation request. The communication between the Issuers and other Entities is out-of-scope of this technical implementation profile. .. _sec_revocation_wi_initiated_flow: @@ -140,10 +140,10 @@ A Wallet Instance MUST request the revocation of a Digital Credential as defined Host: pid-provider.example.org Content-Type: application/x-www-form-urlencoded - credential_proof=$CredentialPoPJWT + credential_pop=$CredentialPoPJWT -where a non-normative example of a Credential PoP is given by the following JWT headers and payload +Below, is given a non-normative example of a Credential PoP with decoded JWT headers and payload and without signature for better readability: .. _credential_pop_jwt_ex: .. code-block:: @@ -213,7 +213,7 @@ Below a non-normative example of an HTTP Response with an error. Content-Type: application/json;charset=UTF-8 { - "error":"invalid_request" + "error": "invalid_request" "error_description": "The signature of credential_pop JWT is not valid" } @@ -241,7 +241,7 @@ The following HTTP Status Codes and Error Codes MUST be supported: Status Attestation Flows ------------------------ -The Status Attestation flows are made up of two distinct phases in time +The Status Attestation process is divided into the following phases: 1. The Status Attestation Request by a Wallet Instance: it involves the Wallet Instance and the Issuer. 2. The Status Attestation Presentation to a Verifier: it involves the Wallet Instance and the Verifier. @@ -271,7 +271,7 @@ The following diagram shows how the Wallet Instance requests a Status Attestatio Status Attestation Request Flow -**Step 1 (Status Attestation Request)**: The Wallet Instance sends the Status Attestation Request to the Issuer. The request MUST contain the Wallet Instance Attestation with its Proof of Possession and a Credential Proof of Possession JWT, signed with the private key related to the public key contained within the Credential. +**Step 1 (Status Attestation Request)**: The Wallet Instance sends the Status Attestation Request to the Issuer. The request MUST contain the Credential Proof of Possession JWT, signed with the private key related to the public key contained within the Credential. .. code:: @@ -279,13 +279,13 @@ The following diagram shows how the Wallet Instance requests a Status Attestatio Host: pid-provider.example.org Content-Type: application/x-www-form-urlencoded - credential_proof=$CredentialPoPJWT + credential_pop=$CredentialPoPJWT -For a non-normative example of Credential Proof of Possession see :ref:`the one provided in the previous section `. +A non-normative example of Credential Proof of Possession is provided :ref:`in the previous section `. **Step 2 (PoP verification)**: The Issuer verifies the signature of the PoP JWTs using the public key that was attested in the Digital Credential, which is proof that the Wallet Instance owns the private keys associated with the Digital Credential. Therefore the Wallet Instance is entitled to request its Status Attestation. -**Step 3 (Check for validity)**: The Issuer checks that the user's attributes are not updated by the Authentic Source or that the latter has not revoked them. The technical mechanisms for obtaining this information are out-of-scope of this technical implementation profile. +**Step 3 (Check for validity)**: The Issuer checks that the User's attributes are not updated by the Authentic Source or that the latter has not revoked them. The technical mechanisms for obtaining this information are out-of-scope of this technical implementation profile. **Step 4 (Status Attestation Creation)**: The Issuer creates the corresponding Status Attestation. A non-normative example of a Status Attestation is given below. @@ -294,7 +294,7 @@ For a non-normative example of Credential Proof of Possession see :ref:`the one { "alg": "ES256", - "typ": "non-revocation-attestation+jwt", + "typ": "status-attestation+jwt, "kid": $ISSUER-JWKID } . @@ -339,7 +339,7 @@ The requests to the *Credential status endpoint* of the Issuers MUST be HTTP wit The *typ* value in the *credential_pop* JWT MUST be set to **status-attestation+jwt** -The *Credential status endpoint* MUST be provided by the Issuers within their Metadata. The Issuers MUST include in the issued Digital Credentials the object *status* with the JSON member *status_attestation* set to a JSON Object containing the *credential_hash_alg* claim. It MUST contain the algorithm used for hashing the Digital Credential. Among the hash algorithms, sha-256 is RECOMMENDED. +The *Credential status endpoint* MUST be provided by the Issuers within their Metadata. The Issuers MUST include in the issued Digital Credentials the object *status* with the JSON member *status_attestation* set to a JSON Object containing the *credential_hash_alg* claim. It MUST contain the algorithm used for hashing the Digital Credential. Among the hash algorithms, the value ``sha-256`` is RECOMMENDED . Status Attestation HTTP Response @@ -372,7 +372,7 @@ Below a non-normative example of an HTTP Response with an error. Content-Type: application/json;charset=UTF-8 { - "error":"invalid_request" + "error": "invalid_request" "error_description": "The signature of credential_pop JWT is not valid" } From 1aa65d315bd4b0338d5a97074a608ca15d7bf6ea Mon Sep 17 00:00:00 2001 From: Giuseppe De Marco Date: Thu, 29 Feb 2024 09:30:41 +0100 Subject: [PATCH 23/28] Apply suggestions from code review Co-authored-by: Giada Sciarretta --- docs/en/revocation-lists.rst | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/en/revocation-lists.rst b/docs/en/revocation-lists.rst index 53878b13d..4569ff4a5 100644 --- a/docs/en/revocation-lists.rst +++ b/docs/en/revocation-lists.rst @@ -22,32 +22,32 @@ The Status Attestations have the following features: - improved privacy, according to the following evidences: 1. the Verifier cannot check over time the validity of a given Digital Credential related to the User; - 2. the Issuers cannot track when and where a Digital Credential is verified. + 2. the Issuers cannot track when and where a Digital Credential is verified; 3. it doesn't reveal any information about the Users or the content of their Digital Credentials. .. _sec_revocation_assumption: -General Assumptions +Operational Requirements ------------------- - **Internet Connection for Status Attestations**: Status Attestations can be obtained only when the Wallet Instance is connected to the internet and actively operated by the User. - **Role of a Credential Issuer**: A Credential Issuer is responsible for creating and issuing Credentials, as well as managing their lifecycle and validity status. -- **Involvement of Authentic Sources**: When one or more Authentic Sources are involved in the issuance of a Digital Credential, the information exchanged between the Authentic Source and the PID/(Q)EAA Provider is crucial for the credential's issuance. Furthermore, in cases where the Authentic Source initiates a revocation or data changes, revoking the Credential becomes necessary. +- **Involvement of Authentic Sources**: When one or more Authentic Sources are involved in the issuance of a Digital Credential, the information exchanged between the Authentic Source and the Credential Issuer is crucial for the Digital Credential's issuance. Furthermore, in cases where the Authentic Source initiates a revocation or data changes, revoking the Digital Credential becomes necessary. .. _sec_revocation_requirements: -Requirements +Functional Requirements ------------ **The Status Attestation MUST:** - be presented in conjunction with the Digital Credential; - be timestamped with the issuance datetime; -- contain the expiration datetime after which it SHOULD NOT be considered valid anymore and it MUST NOT be greater the one contained in the digital Credential which it refers to; +- contain the expiration datetime after which it SHOULD NOT be considered valid anymore and it MUST NOT be greater than the one contained in the Digital Credential which it refers to; - have a validity period not greater than 24 hours; -- provides the proof about the non-revocation of the digital Credential which is related to and MUST be validated using the cryptographic signature of the Issuer; -- not reveal any information about the Relying Party, the User's device or the User's data contained in the digital Credential the attestation is related to; +- provide the proof about the non-revocation of the Digital Credential which is related to and MUST be validated using the cryptographic signature of the Issuer; +- not reveal any information about the Relying Party, the User's device or the User's data contained in the Digital Credential the attestation is related to; - be non-repudiable even beyond its expiration time and even in the case of cryptographic keys rotation. @@ -150,7 +150,7 @@ Below, is given a non-normative example of a Credential PoP with decoded JWT hea { "alg": "ES256", - "typ": "revocation-request+jwt", + "typ": "status-attestation-request+jwt", "kid": $CREDENTIAL-CNF-JWKID } . From 10db28db7a58d80d416a06f25fee0cefa6a99f23 Mon Sep 17 00:00:00 2001 From: Giuseppe De Marco Date: Thu, 29 Feb 2024 09:34:12 +0100 Subject: [PATCH 24/28] Apply suggestions from code review Co-authored-by: Giada Sciarretta --- docs/en/revocation-lists.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/en/revocation-lists.rst b/docs/en/revocation-lists.rst index 4569ff4a5..b33a909f5 100644 --- a/docs/en/revocation-lists.rst +++ b/docs/en/revocation-lists.rst @@ -18,8 +18,8 @@ A Status Attestation is a signed document serving as proof of a Digital Credenti The Status Attestations have the following features: - automated issuance, as the User authentication is not required for the provisioning of the Status Attestation; -- verification of the digital Credential validity status when both the Wallet Instance and the Verifier are offline; -- improved privacy, according to the following evidences: +- verification of the Digital Credential validity status in both online and offline scenarios; +- privacy-preserving, according to the following evidences: 1. the Verifier cannot check over time the validity of a given Digital Credential related to the User; 2. the Issuers cannot track when and where a Digital Credential is verified; From 03c08f174e17d2d1be46bbd655da31967786b617 Mon Sep 17 00:00:00 2001 From: fmarino-ipzs Date: Thu, 29 Feb 2024 10:05:53 +0100 Subject: [PATCH 25/28] fix: credential_proof -> credential_pop --- docs/en/revocation-lists.rst | 8 ++++---- images/Low-Level-Flow-Revocation-Attestation.svg | 2 +- images/Low-Level-Flow-Revocation.svg | 2 +- 3 files changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/en/revocation-lists.rst b/docs/en/revocation-lists.rst index b33a909f5..49535db19 100644 --- a/docs/en/revocation-lists.rst +++ b/docs/en/revocation-lists.rst @@ -28,7 +28,7 @@ The Status Attestations have the following features: .. _sec_revocation_assumption: Operational Requirements -------------------- +------------------------ - **Internet Connection for Status Attestations**: Status Attestations can be obtained only when the Wallet Instance is connected to the internet and actively operated by the User. - **Role of a Credential Issuer**: A Credential Issuer is responsible for creating and issuing Credentials, as well as managing their lifecycle and validity status. @@ -38,7 +38,7 @@ Operational Requirements .. _sec_revocation_requirements: Functional Requirements ------------- +----------------------- **The Status Attestation MUST:** @@ -127,7 +127,7 @@ A Wallet Instance MUST request the revocation of a Digital Credential as defined .. figure:: ../../images/Low-Level-Flow-Revocation.svg :figwidth: 100% :align: center - :target: https://www.plantuml.com/plantuml/svg/NP31IaD134Nt-OfGNEX2t0jAmLNTTD1YDuB4zoA6JfDnal7zlkE05eMixZqdWQmzg4OxPg0MfktuoXLAZsIIGXgusbFE7BZHJkh4AoJ7HVuo6_V6TLG2i0XUtg9SOze-xl2gygST62j_DFOudohFh26KNqerUxivk_jDagNx_Uu2u6V34sMPAHZZdV74FMlwLh5FCdTs5zEJzJ0k_dD6tVjb05vCdN5x05Ypplq1Nm00 + :target: https://www.plantuml.com/plantuml/svg/LOz1IyKm383l_HNXuK4FubrG7dXwNbxHuIw2n2rYM9VK9dL_tpBHCUYb-RwFaACv5gzp2bXTfSxlL49k8nuuepWSUao974xIJ1de06YmyDuvcLKgA-8G5eRhU-1RYEVd3cuAVUj4KEYhaldbK6WaSSRqbZNVNJpy_wF6nxwx2k6lVy748pg1Vn9itgl4ele1xKKr8pDMsQgdtttxPiMDBwjWMSK8pbCuaepj-Xy0 Wallet Instance Initiated Revocation Flow @@ -267,7 +267,7 @@ The following diagram shows how the Wallet Instance requests a Status Attestatio .. figure:: ../../images/Low-Level-Flow-Revocation-Attestation.svg :figwidth: 100% :align: center - :target: https://www.plantuml.com/plantuml/svg/NP11wzf04CNl-oaUqeE2shlGekZ57jfGfLw4iaacPccoa-xEAdxxpXAg_eLSPjxlJNx9EeeDalhEs2JiKrzIC8EkNEK6wmMJa-qw4kozahwY2Mp4pNrazZ4c2Zd2Mx99qfBN-UmFdCBOryUOcyFYAzmAnO_34P_rkgI8G7yJHPbMWUhSiztl8J0tNpvj7vk2Ys-duyoO_nT-sSxLLWXF1Wf1AMCyQy1N2d1p6rSujeJH5roATJwY2Tn3FV6mnIYBiy_hDEJhDQn8S6KIYh2-Hewk-TLExXZzjS1D3lAzmEdIAWbEik1cKUPIJrLhlOlzNDafBIzB9JEOMoXsttVO5Fk8U8z2_GpFhzosLFr1m-75u-n7j-ppS7cf1ChX8Rifkn6XxEdOZ_z6EGLlIlwaEB2Ff8Eq60juvzVawzHt_m00 + :target: https://www.plantuml.com/plantuml/svg/NP31Rk9038RlynGMsWD8mDwHTWM22tlOHWML2r8rIHmoQZ9EnnuGRryFeK0vsl_tErzcpcA3nBOnDWhvsEOOJAShLxZEUe71pZOD2gozahx00LY6a_l9h9aZXalqb2oYrEXrXWt5SArRDkRaOF8Nt0oobyqMVkjnYGm1FoEo38k0PQhPvhsZxi-lvMtEAFktsuwC-Uw_sSQLLX3k32W4IXdZIGCwOW0tjZo3ROtGomBbOfrdg0Are9Bmh0fxdzQnIzTBi2B1vL5G_NrvQHpJfvsSeRVN0bKfIFS2nKEj952K2LMJF9LQB6hh7RTZPOSuFKoLJE3bNBRwlu95jcRWCmks8xZ_vRB6uWCg2WyUUz-x9P-RoqCbO0etoKtPXGWcJqU-Vnlb53mf-OhSaMVKGUfh0PxvEVeojiqN Status Attestation Request Flow diff --git a/images/Low-Level-Flow-Revocation-Attestation.svg b/images/Low-Level-Flow-Revocation-Attestation.svg index 5210432c1..e77ec7936 100644 --- a/images/Low-Level-Flow-Revocation-Attestation.svg +++ b/images/Low-Level-Flow-Revocation-Attestation.svg @@ -1 +1 @@ -Wallet InstanceWallet InstanceIssuerIssuerAuthenticSourceAuthenticSource1POST /status request(credential_proof=$CredentialPoPJWT)2Validate Credential PoP JWTThe Issuer obtains from the Authentic Sourcethe updated attributes and the validity statusof them through an out-of-band mechanism,(e.g. though the PDND APIs system)3Check for attributesupdate and validity4Create StatusAttestation JWT5Response with Status Attestation JWT \ No newline at end of file +Wallet InstanceWallet InstanceIssuerIssuerAuthentic SourceAuthentic Source1POST /status request(credential_pop=$CredentialPoPJWT)2Validate Credential PoP JWTThe Issuer obtains from the Authentic Sourcethe updated attributes and the validity statusof them through an out-of-band mechanism,(e.g. though the PDND APIs system)3Check for attributesupdate and validity4Create StatusAttestation JWT5Response with Status Attestation JWT \ No newline at end of file diff --git a/images/Low-Level-Flow-Revocation.svg b/images/Low-Level-Flow-Revocation.svg index 01b0b5f15..ef2f16fce 100644 --- a/images/Low-Level-Flow-Revocation.svg +++ b/images/Low-Level-Flow-Revocation.svg @@ -1 +1 @@ -Wallet InstanceWallet InstanceIssuerIssuer1POST /revoke request(credential_proof=$CredentialPoPJWT)2Validate the CredentialProof of Possession3Revoke the Credential4Response Ok \ No newline at end of file +Wallet InstanceWallet InstanceIssuerIssuer1POST /revoke request(credential_pop=$CredentialPoPJWT)2Validate the CredentialProof of Possession3Revoke the Credential4Response Ok \ No newline at end of file From c7148c78bff18b7f5871e8722fd2c39aa7ee432e Mon Sep 17 00:00:00 2001 From: fmarino-ipzs Date: Thu, 29 Feb 2024 10:07:02 +0100 Subject: [PATCH 26/28] Update revocation-lists.rst --- docs/en/revocation-lists.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/en/revocation-lists.rst b/docs/en/revocation-lists.rst index 49535db19..3870d4612 100644 --- a/docs/en/revocation-lists.rst +++ b/docs/en/revocation-lists.rst @@ -190,7 +190,7 @@ The requests to the *Issuer Revocation endpoint* MUST be HTTP with method POST, * - **Claim** - **Description** - **Reference** - * - **credential_proof** + * - **credential_pop** - It MUST contain a JWT proof of possession of the cryptographic key the Credential to be revoked shall be bound to. See Section :ref:`Credential Proof of Possession ` for more details. - `[OAuth Status Attestation draft 00] `_ @@ -333,7 +333,7 @@ The requests to the *Credential status endpoint* of the Issuers MUST be HTTP wit * - **Claim** - **Description** - **Reference** - * - **credential_proof** + * - **credential_pop** - It MUST contain a signed JWT as a cryptographic proof of possession of the Digital Credential. See Section :ref:`Credential Proof of Possession ` for more details. - `[OAuth Status Attestation draft 00] `_ @@ -418,7 +418,7 @@ Law-Enforcement Authorities or Third Parties authorized by national law, MAY req Credential Proof of Possession ------------------------------ -The Credential Proof of Possession (**credential_proof**) MUST be a JWT that MUST contain the parameters (JOSE Header and claims) in the following table. +The Credential Proof of Possession (**credential_pop**) MUST be a JWT that MUST contain the parameters (JOSE Header and claims) in the following table. .. list-table:: :widths: 20 60 20 From eb4e1da00a1070276e17e7a1c5a8870e866cc9e0 Mon Sep 17 00:00:00 2001 From: fmarino-ipzs Date: Thu, 29 Feb 2024 10:09:45 +0100 Subject: [PATCH 27/28] fix: reference to status attestation draft 01 --- docs/en/revocation-lists.rst | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/docs/en/revocation-lists.rst b/docs/en/revocation-lists.rst index 3870d4612..effc14e69 100644 --- a/docs/en/revocation-lists.rst +++ b/docs/en/revocation-lists.rst @@ -192,7 +192,7 @@ The requests to the *Issuer Revocation endpoint* MUST be HTTP with method POST, - **Reference** * - **credential_pop** - It MUST contain a JWT proof of possession of the cryptographic key the Credential to be revoked shall be bound to. See Section :ref:`Credential Proof of Possession ` for more details. - - `[OAuth Status Attestation draft 00] `_ + - `[OAuth Status Attestation draft 01] `_ The Revocation Endpoint MUST be provided by the Issuer within its Metadata. @@ -335,7 +335,7 @@ The requests to the *Credential status endpoint* of the Issuers MUST be HTTP wit - **Reference** * - **credential_pop** - It MUST contain a signed JWT as a cryptographic proof of possession of the Digital Credential. See Section :ref:`Credential Proof of Possession ` for more details. - - `[OAuth Status Attestation draft 00] `_ + - `[OAuth Status Attestation draft 01] `_ The *typ* value in the *credential_pop* JWT MUST be set to **status-attestation+jwt** @@ -357,7 +357,7 @@ The *Credential status endpoint* MUST return a response with a *HTTP status code - **Reference** * - **status_attestation** - It MUST contain the Status Attestation as a signed JWT. - - `[OAuth Status Attestation draft 00] `_. + - `[OAuth Status Attestation draft 01] `_. If the Digital Credential could not be found by the Issuer, an HTTP Response with status code 404 (Not Found) MUST be returned. In all other cases the Issuer MUST return an HTTP Response Error using *application/json* as the content type, and including the following parameters: @@ -428,7 +428,7 @@ The Credential Proof of Possession (**credential_pop**) MUST be a JWT that MUST - **Description** - **Reference** * - **typ** - - In case of revocation request it MUST be set to ``revocation-request+jwt``. In case of Status Attestation request it MUST be set to ``status-attestation-request+jwt``, according to `[OAuth Status Attestation draft 00] `_. + - In case of revocation request it MUST be set to ``revocation-request+jwt``. In case of Status Attestation request it MUST be set to ``status-attestation-request+jwt``, according to `[OAuth Status Attestation draft 01] `_. - :rfc:`7516#section-4.1.1`. * - **alg** - A digital signature algorithm identifier such as per IANA "JSON Web Signature and Encryption Algorithms" registry. It MUST be one of the supported algorithms listed in the Section `Cryptographic Algorithms `_ and MUST NOT be set to ``none`` or any symmetric algorithm (MAC) identifier. @@ -461,10 +461,10 @@ The Credential Proof of Possession (**credential_pop**) MUST be a JWT that MUST - [:rfc:`7519`. Section 4.1.7]. * - **credential_hash** - It MUST contain the hash value of a Digital Credential, derived by computing the base64url encoded hash of the Digital Credential. - - `[OAuth Status Attestation draft 00] `_. + - `[OAuth Status Attestation draft 01] `_. * - **credential_hash_alg** - It MUST contain the Algorithm used for hashing the Digital Credential. The value SHOULD be set to `S256`. - - `[OAuth Status Attestation draft 00] `_. + - `[OAuth Status Attestation draft 01] `_. @@ -486,7 +486,7 @@ The Status Attestation MUST contain the following claims. - `[OIDC4VCI. Draft 13] `_, [:rfc:`7515`], [:rfc:`7517`]. * - **typ** - It MUST be set to `status-attestation+jwt`. - - [:rfc:`7515`], [:rfc:`7517`], `[OAuth Status Attestation draft 00] `_.. + - [:rfc:`7515`], [:rfc:`7517`], `[OAuth Status Attestation draft 01] `_.. * - **kid** - Unique identifier of the Issuer ``jwk`` as base64url-encoded JWK Thumbprint value. - :rfc:`7638#section_3`. @@ -510,10 +510,10 @@ The Status Attestation MUST contain the following claims. - :rfc:`9126` and :rfc:`7519`. * - **credential_hash** - Hash value of the Credential the Status Attestation is bound to. - - `[OAuth Status Attestation draft 00] `_. + - `[OAuth Status Attestation draft 01] `_. * - **credential_hash_alg** - The Algorithm used for hashing the Credential to which the Status Attestation is bound. The value SHOULD be set to ``S256``. - - `[OAuth Status Attestation draft 00] `_. + - `[OAuth Status Attestation draft 01] `_. * - **cnf** - JSON object containing the proof-of-possession key materials. The ``cnf`` jwk value MUST match with the one provided within the related Credential. - `[RFC7800, Section 3.1] `_. From 85293b09d27fb43d35bd97c3fc091c13e64cbadb Mon Sep 17 00:00:00 2001 From: fmarino-ipzs Date: Thu, 29 Feb 2024 10:14:11 +0100 Subject: [PATCH 28/28] fix: clarification aud param in credential_pop --- docs/en/revocation-lists.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/en/revocation-lists.rst b/docs/en/revocation-lists.rst index effc14e69..4b5da47ac 100644 --- a/docs/en/revocation-lists.rst +++ b/docs/en/revocation-lists.rst @@ -448,7 +448,7 @@ The Credential Proof of Possession (**credential_pop**) MUST be a JWT that MUST - Thumbprint of the JWK in the ``cnf`` parameter of the Wallet Instance Attestation. - :rfc:`9126` and :rfc:`7519`. * - **aud** - - It MUST be set to the identifier of the Issuer. + - It MUST be set to the Issuer endpoint at which the JWT is used. - :rfc:`9126` and :rfc:`7519`. * - **exp** - UNIX Timestamp with the expiry time of the JWT.