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 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.

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 than the one contained in the Digital Credential which it refers to;

• have a validity period not greater than 24 hours;

• 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.

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 the following circumstances occur:

  • 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

  • request a revocation of that Digital Credential;

  • obtain a related Status Attestation;

• 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 MUST:

• 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.

The Authentic Sources MUST:

• 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.

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.

• 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).

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.

• 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 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 to a Verifier as a proof of validity of a corresponding Digital Credential.

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 Issuers and other Entities is out-of-scope of this technical implementation profile.

Revocation Request by Wallet Instance¶

A Wallet Instance MUST request the revocation of a Digital Credential as defined below.

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.

POST /revoke HTTP/1.1
Host: pid-provider.example.org
Content-Type: application/x-www-form-urlencoded

credential_pop=$CredentialPoPJWT

Below, is given a non-normative example of a Credential PoP with decoded JWT headers and payload and without signature for better readability:

{
  "alg": "ES256",
  "typ": "status-attestation-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",
  "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 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, 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.

.. 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.

Claim	Description	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 Credential Proof of Possession for more details.	[OAuth Status Attestation draft 01]

The Revocation Endpoint MUST be provided by the Issuer within its Metadata.

Credential Revocation HTTP Response¶

In case of successful revocation, the Issuer MUST return an HTTP Response with status code 204 No Content. Otherwise, an HTTP error response MUST be provided by the Issuer using status codes according to the table below.

The following HTTP Status Codes MUST be supported:

Status Code	Body	Description
204 No Content		The Digital Credential has been successfully revoked.
400 Bad Request	Error code and description	The issuer cannot fulfill the request because of invalid parameters.
404 Not Found		The Digital Credential to be revoked can not be found by the Issuer.
500 Internal Server Error		The Issuer encountered an internal problem. (RFC 6749#section-5.2).
503 Service Unavailable		The Issuer is temporary unavailable. (RFC 6749#section-5.2).

For HTTP error responses that involve a body, the body MUST be encoded in application/json format and MUST contain the following parameters:

• error. The error code, as registerd in the table below.

• error_description. Text in human-readable form providing further details to clarify the nature of the error encountered.

Error codes are meant to provide additional information about the failure so that the User can be informed and take the appropriate action. The following Error Codes MUST be supported:

Error Code	Description
invalid_request	The request is not valid due to the lack or incorrectness of one or more parameters. (RFC 6749#section-5.2).

Below a non-normative example of an HTTP Response with an error.

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"
}

Status Attestation Flows¶

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.

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 proof of non-revocation status of the Credential.

The following diagram shows how the Wallet Instance requests a Status Attestation to the Issuer.

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.

POST /status HTTP/1.1
Host: pid-provider.example.org
Content-Type: application/x-www-form-urlencoded

credential_pop=$CredentialPoPJWT

A non-normative example of Credential Proof of Possession is 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 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 4 (Status Attestation Creation): The Issuer creates the corresponding Status Attestation. A non-normative example of a Status Attestation is given below.

{
    "alg": "ES256",
    "typ": "status-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": $CREDENTIAL-CNF-JWK
        }
}

Step 4 (Status Attestation Response): The Issuer then returns the Status Attestation to the Wallet Instance, as in the following non-normative example.

HTTP/1.1 201 Created
Content-Type: application/json

{
    "status_attestation": "eyJhbGciOiJFUzI1NiIsInR5cCI6IndhbGxldC1...",
}

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 Table of Credential Request parameters. These MUST be encoded in application/x-www-form-urlencoded format.

Claim	Description	Reference
credential_pop	It MUST contain a signed JWT as a cryptographic proof of possession of the Digital Credential. See Section Credential Proof of Possession for more details.	[OAuth Status Attestation draft 01]

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, the value sha-256 is RECOMMENDED .

Status Attestation HTTP Response¶

The Credential status endpoint MUST return a HTTP response with status code 201 Created 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.

Claim	Description	Reference
status_attestation	It MUST contain the Status Attestation as a signed JWT.	[OAuth Status Attestation draft 01].

The following HTTP Status Codes MUST be supported:

Status Code	Body	Description
201 Created	Status Attestation response	The Status Attestation has been successfully created and it has been returned.
400 Bad Request	Error code and description	The issuer cannot fulfill the request because of invalid parameters.
404 Not Found		The Digital Credential can not be found by the Issuer.
500 Internal Server Error		The Issuer encountered an internal problem. (RFC 6749#section-5.2).
503 Service Unavailable		The Issuer is temporary unavailable. (RFC 6749#section-5.2).

For HTTP error responses that involve a body, the body MUST be encoded in application/json format and MUST contain the following parameters:

• error. The error code, as registerd in the table below.

• error_description. Text in human-readable form providing further details to clarify the nature of the error encountered.

Error codes are meant to provide additional information about the failure so that the User can be informed and take the appropriate action. The following Error Codes MUST be supported:

Error Code	Description
invalid_request	The request is not valid due to the lack or incorrectness of one or more parameters. (RFC 6749#section-5.2).
credential_revoked	The Digital Credential is revoked. The reason of revocation MUST be provided in the error_description field.
credential_updated	One or more attributes contained in the Digital Credential are changed. The error_description field MUST contain a list of updated attributes.

Below a non-normative example of an HTTP Response with an error.

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"
}

Credential Proof of Possession¶

The Credential Proof of Possession (credential_pop) MUST be a JWT that MUST contain the parameters (JOSE Header and claims) in the following table.

Status Attestation¶

The Status Attestation MUST contain the following claims.