Digital Credential Lifecycle¶
The Credential Issuer is responsible for creating and issuing Digital Credentials, as well as managing their lifecycle and validity status.
The Authentic Source is the entity responsible for the management and provisioning of User's attributes to Credential Issuers. There is a relationship between the lifecycle of the attributes managed by the Authentic Source and the Digital Credential lifecycle managed by the Credential Issuer. Indeed, one of the reasons for revocation or suspension of Digital Credentials is the update/revocation or suspension of the attributes contained in the Digital Credential. In IT Wallet, the provisioning of User's attributes and the notification of updates or changes in the state of the attributes are exchanged using the PDND infrastructure (see relative sections for more details).
Fig. 10 shows the states and transitions for Digital Credentials. It includes four distinct states: Issued, Valid, Expired, and Revoked. While, in case of (Q)EAAs there is an additional state: Suspended. A Digital Credential in all states can be deleted (PID/(Q)EAA DEL) and this ends its lifecycle.
Fig. 10 Digital Credential Lifecycle.¶
Note
Users MAY present a Digital Credential in any state, it is up to the Relying Party's policy to accept a not Valid Digital Credential. An example of this scenario is when a Relying Party needs to verify that the User is not a minor. In this case, even if the User presents an Issued/Expired/Revoked or Suspended Digital Credential, the age claim is still reliable.
Note
While Issued, Valid, Expired, Revoked are explicitly mentioned in the ARF (see Figure 5 of ARF v1.4), Suspended is implicitly present in EIDAS-ARF. This specification explicitly considers it.
Credential Transition to Issued¶
For the state machine to start, the Wallet Instance MUST be in either the Operational or Valid state, enabling Digital Credentials to be issued to it. The state machine begins with the Issued state, when an issuance process is triggered and, as a result, a Digital Credential is issued to the Wallet Instance (PID/(Q)EAA ISS). Please refer to PID/(Q)EAA Issuance.
Credential Transition to Valid¶
A Digital Credential changes to Valid state when:
it reaches its start date of validity;
an unsuspension process is triggered if the (Q)EAA has been suspended.
Credential Transition to Expired¶
A Digital Credential naturally transitions to the Expired state when it automatically expires upon reaching its end date of validity (PID/(Q)EAA EXP), indicating they are no longer valid for use.
If a Digital Credential is Expired the Wallet Instance SHOULD notify the User the Digital Credential has expired and the User MAY delete it (PID/(Q)EAA DEL). This ends its lifecycle.
Credential Transition to Revoked¶
A Digital Credential changes from Issued, Valid or Suspended states to Revoked state when it is actively revoked by the Credential Issuer by a revocation process (PID/(Q)EAA REV). The Relying Parties SHOULD no longer consider usable a particular Digital Credential when it is Revoked, even though it is still valid temporally and contains a valid Credential Issuer signature. Revocation can occur in the following cases:
for technical security reasons relating to the compromise of cryptographic material;
in case of explicit User requests;
as a consequence of an attribute update by Authentic Sources;
in case of a revocation of the attributes contained in the Digital Credential notified by the Authentic Source;
death of the User;
revocation of Wallet Instance to which the Digital Credential was issued;
illegal activities of the User reported by Judicial or Supervisory Bodies.
In the case of PID only, the following cases are in addition to those listed above:
detection of a breach of the digital identity issued by an Identity Provider and used to authenticate the User during the PID Issuance;
as a result of obtaining a new PID on a new Wallet Instance from the same Wallet Provider that has provided the Wallet Instance containing a PID previously issued.
Note
A (Q)EAA Provider MAY revoke a (Q)EAA in case of PID revocation.
When a Digital Credential is Revoked it cannot transition back to Valid, the Wallet Instance SHOULD notify the User the Digital Credential has been revoked and the User MAY delete it (PID/(Q)EAA DEL). This ends its lifecycle.
Credential Transition to Suspended¶
A (Q)EAA changes from Issued or Valid states to Suspended state when it is suspended by the Credential Issuer ((Q)EAA SUSP). The (Q)EAA remains Suspended until it is restored to the Issued or Valid state ((Q)EAA UNSUSP) depending on the previous state, i.e. the conditions leading to its suspension are resolved, or it changes in Revoked, Expired or it is deleted. The suspension of a (Q)EAA MAY be:
Use case driven, based on the validity status of the attributes contained in the (Q)EAA. In this case, an Authentic Source MUST notify the Credential Issuer of any changes in the state of the attributes attested by the (Q)EAA.
Explicitly requested by the User.
Credential Lifecycle Management¶
While Fig. 10 shows the different states a Digital Credential may acquire during its lifecycle, Fig. 11 shows the point of view of Wallet Instances and Credential Issuers in managing the Digital Credential lifecycle and the effect on their local storage.
Fig. 11 Digital Credential Lifecycle Management.¶
A User, through the Wallet Instance, is able to acquire a new Digital Credential (Credential Acquisition) performing the PID/(Q)EAA ISS process. This MUST result in the storage of a Digital Credential in the Issued/Valid state, and delete it when it is not needed anymore or it is Expired/Revoked (Credential Deletion). Until the Credential Deletion, a Digital Credential can be presented to Relying Parties, this operation will not affect its lifecycle.
A Credential Issuer instead is responsible for:
Digital Credential Generation: the Digital Credential is generated as a consequence of an issuance request and MUST be added to the local storage of the Credential Issuer after the successful issuance.
Digital Credential Revocation/Suspension/Unsuspension (PID/(Q)EAA REV and (Q)EAA SUSP/UNSUSP): for technical security reasons or triggered by external entities (e.g., Users and Authentic Sources) the Digital Credential state MUST be locally updated.
Data Purging: after reaching the Expired state, and based on the Credential Issuer retention policies, Digital Credentials MUST be removed from the local storage of the Credential Issuer.
Digital Credential Revocation and Suspension¶
This section describes the flows to request a Digital Credential status update (i.e. revocation or suspension), involved entities, and validation mechanisms for Digital Credentials in the IT-Wallet system.
As highlighted in Section Digital Credential Lifecycle, a Digital Credential's lifecycle is affected by:
The lifecycle of its storing Wallet Instance
The validity of Attributes managed by Authentic Sources
For PIDs only, the status of the Digital Identity used for User authentication
External user-related factors can also influence a Digital Credential's lifecycle, such as:
Explicit request from the Digital Credential holder
User's death
Illegal activities
Entities Involved¶
While the Credential Issuer MUST directly manage the validity status of Digital Credentials it has issued, other actors MAY trigger the Digital Credential revocation/suspension process:
- Users, through:
Their Wallet Instance
Web service provided by the Issuer
The Authentic Source when Credential attributes are updated or change validity status
The Wallet Provider when revoking a Wallet Instance
The Identity Provider if the Digital Identity used for PID issuance is stolen or compromised
Legal authorities or the Supervisory Body in cases of proven illegal activities
The following figure shows an entity relationships diagram relating to the Update Flow status.
Fig. 12 Entities involved in Credential Revocation Flow¶
Status Update Flows¶
This section describes the main flows for managing Digital Credential Status Updates by the Issuer, in particular Status Update:
related to the User;
triggered by a Wallet Instance;
triggered by a Wallet Provider;
triggered by an Authentic Source.
Note
Detailed Status Update Flows for Identity Providers, legal authorities, and the Supervisory Body will be covered in future versions of the technical specification.
Status Update by Wallet Instance¶
When the User deletes a Digital Credential from the Wallet Instance, the Wallet Instance MUST notify this event to the Credential Issuer and the Credential Issuer MUST revoke the Digital Credential. To notify this event, the Wallet Instance MUST use the Notification Endpoint described in Section Notification Endpoint using the parameter event
set with the value credential_deleted
.
When the revoked Credential is the PID, the Credential Issuer MUST send a notification of this event to the User within 24 hours. For any other Credential different from the PID, the Credential Issuer SHOULD send a notification of this event to the User. The notification to the User might be implemented in several ways, such as using a User's email address, telephone number, or any other verified and secure communication channel, and MUST include all the information about the Credential revocation status. The method used for the notification to the User is out of scope of the current technical implementation profile. When the revocation occurs, the Credential Issuer MUST update the status of the Digital Credential accordingly. When the Notification Response sent by the Credential Issuer is succesfully received by the Wallet Instance, the Wallet Instance MUST delete the Digital Credential.
Status Update by Wallet Providers¶
In addition to what already defined in Digital Credential Lifecycle, the Credential Issuer MUST provide a web service (Wallet Instance Revocation endpoint) defined using PDND, as specified in the Section e-Service PDND Catalogue. The Wallet Provider that for any reason revokes a Wallet Instance MUST send a notification to Issuers using this endpoint.
Status Update by Authentic Sources¶
Authentic Sources manage attributes separately from Digital Credentials, which verify authenticity like physical documents. Losing a physical document doesn't mean losing the privileges it represents; it just means the User can't prove them. However, if a User loses privileges due to a serious infraction, the Authentic Source will revoke the related attributes. In such cases, when a User's attributes are updated, Authentic Sources MUST notify Credential Issuers to update the validity status of any Digital Credential containing those attributes.
Credential Issuers MUST provide a web service available via PDND for Credential update notification and validity status as defined in Section e-Service PDND Catalogue. For the protocol flow, please refer to the Section e-Service PDND. Authentic Sources MUST use this notification service in the following cases:
The value of one or more Attributes contained in the Authentic Source's database has changed.
The validity status of the Attributes is updated (revocation or suspension).
Validity Verification Mechanisms¶
The verification of the validity of a Digital Credential is based on the OAuth Status Assertions Specification (OAUTH-STATUS-ASSERTION) with slight modifications [1].
A Status Assertion is a signed document serving as proof of a Digital Credential's current validity status. The Credential Issuer provides these assertions to Holders who can present them to Verifiers together with the corresponding Digital Credentials.
The Status Assertions have the following features:
automated issuance, as the User authentication is not required for the provisioning of the Status Assertion;
verification of the Digital Credential validity status in both online and offline scenarios;
privacy-preserving, according to the following evidences:
the Verifier can check the validity of the Credential during the presentation phase. It is not able to check the validity of a given Digital Credential related to the User over time and out of the scope of the User authentication;
the Credential Issuers is not able to know to which Verifier the Digital Credential or the Status Assertion will be presented;
it doesn't reveal any information about the Users or the content of their Digital Credentials.
MUST have a validity period not greater than 24 hours.
Note
The following sections describe how the Digital Credential validation mechanism works through its key phases.
Credential Issuers Handling Credential Status¶
Credential Issuers, once a Digital Credential has been generated and successfully issued, MUST:
Store it locally with minimum set of data required to manage its lifecycle, including the validity status of that Digital Credential;
Include a specified hash algorithm in the Digital Credential using the
credential_hash_alg
claim within thestatus_assertion
JSON member of the status claim
Moreover, Credential Issuers MUST add the following parameters within their Metadata:
status_assertion_endpoint
credential_hash_alg_supported
Wallet Instance Checking Credentials Statuses¶
A Wallet Instance MUST check periodically the validity status of the Digital Credential that is stored in it, requesting a Status Assertion for each Digital Credential. In this case, the Wallet Instance MUST send a Status Assertion Request to the Credential Issuer according to "OAuth Status Assertion Specification" (see OAUTH-STATUS-ASSERTION for more details) and it is depicted in the following diagram.
Fig. 13 Status Assertion Flow¶
Step 1 (Status Assertion Request): The Wallet Instance sends the Status Assertion Request to the Credential Issuer, where:
The request MUST contain the base64url encoded hash value of the Digital Credential, for which the Status Assertion is requested, and enveloped in a signed Status Assertion Request object.
The Status Assertion Request object MUST be signed with the private key corresponding to the confirmation claim assigned by the Issuer and contained within the Digital Credential.
The Status Assertion HTTP request can be sent to a single Credential Issuer regarding multiple Digital Credentials, and MUST contain a JSON object with the member status_assertion_requests as described in Section HTTP Status Assertion Request.
The Credential Issuer that receives the Status Assertion Request object MUST:
validate that the Wallet Instance making the request is authorized to request Status Assertions. If errors occur during this check, the Credential Issuer MUST provide a Status Assertion Error Response according to Section HTTP Status Assertion Response;
verify the compliance of all elements in the status_assertion_requests object using the confirmation method contained within the Digital Credential where the Status Assertion Request object is referred to. In case of errors, a Status Assertion Error Response MUST be provided (see Section HTTP Status Assertion Response);
verify that it is the legitimate Issuer of the Digital Credential to which each Status Assertion Request object refers;
check the validity status for the requested Credentials;
creates the corresponding Status Assertion.
Step 2 (Status Assertion Response): The status_assertion_responses MUST be a JSON Array containing the StatusAssertionResponse and/or the StatusAssertionErrors JSON Objects related to the request made by the Wallet Instance.
The Wallet Instance MUST:
validate the HTTP Status Assertion Response;
extract and validate the signatures of each JSON Object within the status_assertion_responses JSON Array;
present a valid Status Assertion to a Verifier which request it for the status verification of a Digital Credential (see Section below for more details);
inform the User in case of a validity state update of a Digital Credential.
Note
Status Assertion Errors JSON Object MAY have the alg header parameter set to none. If the Credential Issuer signs the Status Assertion Errors the Wallet Instance MUST validate the signature. Moreover, Status Assertion Errors MUST not be presented to Verifiers.
Technical details about the HTTP Status Assertion Response is provided in the Section HTTP Status Assertion Response.
HTTP Status Assertion Request¶
The Status Assertion endpoint MUST be provided by the Credential Issuer within its Metadata.
The requests to the Status Assertion 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/json
format.
Claim |
Description |
Reference |
---|---|---|
status_assertion_requests |
It MUST be an array of strings, where each represents a Status Assertion Request object. Each element MUST contain a signed JWT, encoded as a series of base64url-encoded values (some of which may be the empty string) separated by period ('.') characters, as a cryptographic proof of possession of the Digital Credential for which the Status Assertion is being requested, according with the Status Assertion Request described in Section 7 of OAUTH-STATUS-ASSERTION. See the Table below for more details. |
This Specification. |
Below a non-normative example representing a Status Assertion Request array with Status Assertion Request objects in JWT format.
POST /status HTTP/1.1
Host: issuer.example.org
Content-Type: application/json
{
"status_assertion_requests" : [
$status_assertion_request,
$status_assertion_request, ...
]
}
The Status Assertion Request object MUST be a JWT that MUST contain the parameters (Header and Payload) in the following table.
Header |
Description |
Reference |
---|---|---|
typ |
It MUST be set to |
|
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 |
Payload |
Description |
Reference |
---|---|---|
iss |
Thumbprint of the JWK in the |
|
aud |
It MUST be set to the URL string of Credential Issuer Status Assertion endpoint. |
|
exp |
UNIX Timestamp with the expiry time of the JWT. It MUST be greater than the value set for iat. |
|
iat |
UNIX Timestamp with the time of JWT issuance. |
|
jti |
Unique identifier for the proof of possession JWT. The value SHOULD be set using a UUID v4 value according to [RFC 4122]. |
|
credential_hash |
It MUST contain the hash value of the Digital Credential's Issuer signed part the Status Assertion is bound to. |
|
credential_hash_alg |
It MUST contain the Algorithm used for hashing the Digital Credential. The value SHOULD be set to sha-256. |
Below, is given a non-normative example of a single Status Assertion Request object with decoded JWT headers and payload and without signature for better readability:
{
"alg": "ES256",
"typ": "status-assertion-request+jwt",
}
.
{
"iss": "0b434530-e151-4c40-98b7-74c75a5ef760",
"aud": "https://pid-provider.example.org/status",
"iat": 1698744039,
"exp": 1698744139,
"jti": "6f204f7e-e453-4dfd-814e-9d155319408c",
"credential_hash": $Issuer-Signed-JWT-Hash,
"credential_hash_alg": "sha-256"
}
HTTP Status Assertion Response¶
In case of succesfully Status Assertion Request validation, the Credential Issuer MUST return an HTTP response with the status code set to 200 OK. If the Credential Issuer is able to provide a valid Status Assertion for a requested Credential, the response MUST contain a Status Assertion object within a JSON Array. Otherwise, a Status Assertion Errors related to that Credential MUST be included in the Response JSON Array as an entry.
If the HTTP Status Assertion Request fails (e.g. invalid request, server unavailability, etc.), an HTTP Error Status Code MUST be provided within the Status Assertion Response.
In the following table are listed HTTP Status Codes that MUST be supported:
Status Code |
Body |
Description |
---|---|---|
200 Ok |
Revocation Response |
The Revocation Response has been successfully created. |
400 Bad Request |
Error code and description |
The Credential Issuer cannot fulfill the request because of invalid parameters. |
500 Internal Server Error |
The Credential Issuer encountered an internal problem. (RFC 6749#section-5.2). |
|
503 Service Unavailable |
The Credential Issuer is temporary unavailable. (RFC 6749#section-5.2). |
The HTTP response MUST:
include a JSON object with a member named status_assertion_responses. It MUST be an array of strings, where each represents a Status Assertion Response object. Each element MUST contain a signed JWT, encoded as a series of base64url-encoded values (some of which may be the empty string) separated by period ('.') characters. The Status Assertion Response object MUST contain a Status Assertion Response and Status Assertion Error in analogy with Sections 8 and 9 of OAUTH-STATUS-ASSERTION for more details.
be encoded in
application/json
format.
A non-normative example of a HTTP Status Assertion Response is given below.
HTTP/1.1 200 Ok
Content-Type: application/json
{
"status_assertion_responses": [
$status_assertion_response,
$status_assertion_response, ...
]
}
The Status Assertion MUST contain the parameters and claims defined below
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 Cryptographic Algorithms and MUST NOT be set to |
|
typ |
It MUST be set to status-assertion+jwt. |
Payload |
Description |
Reference |
---|---|---|
iss |
It MUST be set to the identifier of the Credential Issuer. |
|
iat |
UNIX Timestamp with the time of JWT issuance. |
|
exp |
UNIX Timestamp with the expiry time of the JWT. It MUST be greater than the value set for iat. |
|
credential_hash |
Hash value of the Credential the Status Assertion is bound to. |
|
credential_hash_alg |
The Algorithm used for hashing the Credential to which the Status Assertion is bound. The value SHOULD be set to |
|
credential_status_type [2] |
Numerical value indicating the validity of the Credential linked to the Status Assertion describing its state, mode, condition or stage. All values taken from IANA "OAuth Status Types" registry for Status List values (see Section 7 of TOKEN-STATUS-LIST) MAY be supported. Values from
|
This Specification, TOKEN-STATUS-LIST . |
credential_status_detail |
REQUIRED only if credential_status_type is not set to 0x00. Object containing detailed information about the status of the Credential. It contains:
|
|
cnf |
JSON object containing confirmation methods. The sub-member contained within cnf member, such as jwk for JWT, MUST match with the one provided within the related Digital Credential. Other confirmation methods can be utilized when the referenced Digital Credential supports them, in accordance with the relevant standards. |
Warning
This specification uses credential_status_type
instead of credential_status_validity
currently supported in OAUTH-STATUS-ASSERTION as the value is semantically a status type and not a boolean.
Below a non-normative example of a Status Assertion Response object in JWT format, with the headers and payload represented in JSON and without applying the signature.
{
"alg": "ES256",
"typ": "status-assertion+jwt",
"kid": "Issuer-JWK-KID"
}
.
{
"iss": "https://issuer.example.org",
"jti": "6f204f7e-e453-4dfd-814e-9d155319408c"
"credential_hash": $CREDENTIAL-HASH,
"credential_hash_alg": "sha-256",
"credential_status_type": 0x01,
"credential_status_detail": {
"state": "revoked",
"description": "The Credential is no longer usable as it has been revoked. This state is irreversible"
},
"cnf": {
"jwk": {
"kty": "EC",
"crv": "P-256",
"x": "_2ySUmWFjwmraNlo15r6dIBXerVdy_NpJuwAKJMFdoc",
"y": "MV3C88MhhEMba6oyMBWuGeB3dKHP4YADJmGyJwwILsk"
}
}
}
The Status Assertion Error object MUST contain the following claims:
error. The error code, as registered in the table below;
error_description. Text in human-readable form providing further details to clarify the nature of the error encountered.
Errors are meant to provide additional information about the failure so that the User can be informed and take the appropriate action. The error claim for the Status Assertion Error object MUST be set with one of the values defined in the table below, in addition to the values specified in RFC 6749#section-5.2:
Error Code |
Description |
---|---|
|
The request is not valid due to the lack or incorrectness of one or more parameters. (RFC 6749#section-5.2). |
|
The Revocation Assertion Request signature validation has failed. This error type is used when the proof of possession of the Digital Credential is found not valid within the Revocation Assertion Request. |
|
The credential_hash value provided in the Revocation Assertion Request doesn't match with any active Digital Credential. |
|
The hash algorithm set in credential_hash_alg is not supported. |
Below a non-normative example of a Revocation Assertion Error object in JWT format, with the headers and payload represented in JSON and without applying the signature.
{
"alg": "ES256",
"typ": "revocation-assertion-error+jwt",
"kid": "Issuer-JWK-KID"
}
.
{
"iss": "https://issuer.example.org",
"jti": "6f204f7e-e453-4dfd-814e-9d155319408c"
"credential_hash": $CREDENTIAL-HASH,
"credential_hash_alg": "sha-256",
"error": "unsupported_hash_alg",
"error_description": "The hash algorithm is not supported"
}
Relying Party Checking Credential Status¶
During the presentation flow, if a Status Assertion related to a Digital Credential is available, the Wallet Instance MUST include it along with the related Digital Credential in the vp_token
JSON Array.
The Verifier who wants to rely on the mechanism provided by Status Assertion MUST extract the Status Assertion from the vp_token
Array, and, in addition to the checks required in the Presentation Flow described in the Section Remote Flow, the Verifier MUST check the presence of status.status_assertion
claim in the Digital Credential. If true, the Verifiers MUST:
validate the signature of the Status Assertion;
decode the Status Assertion provided in the presentation, by matching the JWS Header parameter typ set to
status-assertion+jwt
and looking for thecredential_hash
value that matches with the hash of the Digital Credential's Issuer signed part using the hashing algorithm configured instatus.status_assertion.credential_hash_alg
;evaluate the Status Assertion by checking the following items:
the
iss
claim value MUST match the one in the Digital Credential;the
iat
claim value MUST be equal to or later than theiat
claim value in the Digital Credential;the
exp
value MUST be later than the current time;the
nbf
claim value, if present, MUST be less than or equal to the current time;the
cnf
JSON Object MUST match the one included in the related Digital Credential;the
credential_status_type
andcredential_status_detail
values.