OAuth Status Assertions

Status of This Memo

This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79.¶

Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet-Drafts is at https://datatracker.ietf.org/drafts/current/.¶

Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress."¶

This Internet-Draft will expire on 18 November 2024.¶

Copyright Notice

Copyright (c) 2024 IETF Trust and the persons identified as the document authors. All rights reserved.¶

This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Revised BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Revised BSD License.¶

Table of Contents

1. Introduction

Status Assertions ensure the integrity and trustworthiness of digital credentials, whether in JSON Web Tokens (JWT) or CBOR Web Tokens (CWT) format, certifying their validity and non-revocation status. They function similarly to OCSP Stapling, allowing wallet instances to present time-stamped assertions from the Credential Issuer. The approach defined in this specification allows the verification of credentials against any revocation, without direct queries to the issuer, enhancing privacy, reducing latency, and enabling offline verification. Essential for offline scenarios, Status Assertions validate digital credentials' validity, balancing scalability, security, and privacy without internet connectivity.¶

The figure below illustrates the process by which a Wallet Instance requests a Status Assertion from the credential issuer and subsequently receives it.¶

+-----------------+                             +-------------------+
|                 | Requests Status Assertion   |                   |
|                 |---------------------------->|                   |
| Wallet Instance |                             | Credential Issuer |
|                 | Status Assertion            |                   |
|                 |<----------------------------|                   |
+-----------------+                             +-------------------+

Figure 1: Status Assertion Issuance Flow¶

the figure below illustrates the process by which a Wallet Instance presents the Status Assertion along with the corresponding digital credential, to prove the non-revocation status of the digital credential to a verifier.¶

+-- ----------------+                             +----------+
|                   | Presents Digital Credential |          |
|  Wallet Instance  | and Status Assertion        | Verifier |
|                   |---------------------------->|          |
+-------------------+                             +----------+

Figure 2: Status Assertion Presentation Flow¶

2. Conventions and Definitions

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.¶

3. Terminology

This specification uses the terms "End-User", "Entity" as defined by OpenID Connect Core [@OpenID.Core], the term "JSON Web Token (JWT)" defined by JSON Web Token (JWT) [RFC7519].¶

Digital Credential:

A set of one or more claims about a subject made by a Credential Issuer. Alternative names are "Verifiable Credential" or "Credential".¶

Credential Issuer:

Entity that is responsible for the issuance of the Digital Credentials. The Issuer is responsible for the lifecycle of their issued Digital Credentials and their validity status.¶

Holder:

An entity that receives Verifiable Credentials and has control over them to present them to the Verifiers as Verifiable Presentations.¶

Verifier:

Entity that relies on the validity of the Digital Credentials presented to it. This Entity, also known as a Relying Party, verifies the authenticity and validity of the Digital Credentials, including their revocation status, before accepting them.¶

Wallet Instance:

The digital Wallet in control of a User, also known as Wallet or Holder. It securely stores the User's Digital Credentials. It can present Digital Credentials to Verifiers and request Status Assertions from Issuers under the control of the User.¶

4. Rationale

OAuth Status Lists [@!I-D.looker-oauth-jwt-cwt-status-list] are suitable for specific scenarios, especially when the Verifier needs to verify the status of a Digital Credential at a later time after the User has presented the Digital Credential.¶

However, there are cases where the Verifier only needs to check the revocation status of a Digital Credential at the time of presentation, or situations where the Verifier should not be allowed to check the status of a Digital Credential over time due to some privacy constraints, in compliance with national privacy regulations.¶

For instance, consider a scenario where a Verifier's repeated access to a Status List to check the revocation status of a Digital Credential could be deemed as excessive monitoring of the End-User's activities. This could potentially infringe upon the End-User's right to privacy, as outlined in [Article 8 of the European Convention on Human Rights] (https://www.echr.coe.int/documents/convention_eng.pdf) and in the the European Union's General Data Protection Regulation (GDPR), by creating a detailed profile of the End-User's interactions and credential usage without explicit consent for such continuous surveillance.¶

In scenarios where the Verifier, Credential Issuer, and OAuth Status List Provider are all part of the same domain or operate within a context where a high level of trust exists between them and the End-User, the OAuth Status List is the optimal solution; while there might be other cases where the OAuth Status List facilitates the exposure to the following privacy risks:¶

• An OAuth Status List Provider might know the association between a specific status list and a Credential Issuer, especially if the latter issues a single type of Digital Credential. This could inadvertently reveal the OAusth Status List Provider information about how a Digital Credential corresponds to a status list.¶

• A Verifier retrieves an OAuth Status List by establishing a TCP/IP connection with an OAuth Status List Provider. This allows the OAuth Status List Provider to obtain the IP address of the Verifier and potentially link it to a specific Digital Credential type and Credential Issuer associated with that OAuth Status List. A malicious OAuth Status List Provider could use internet diagnostic tools, such as Whois or GeoIP lookup, to gather additional information about the Verifier. This could inadvertently disclose to the OAuth Status List Provider which Digital Credential the requester is using and from which Credential Issuer, information that should remain confidential.¶

Status Assertions differ significantly from OAuth Status Lists in several ways:¶

1. Privacy: Status Assertions are designed to be privacy-preserving. Verifier exchanges the Status Assertions directly with the Holder, not requiring the Verifier to gather any additional information from third-party entities. Once a Status Assertion is issued, it can be verified without any further communication with the Credential Issuer or any other party, thus preventing potential privacy leaks.¶

2. Static Verification: Status Assertions are designed to be statically provided to Verifiers by Wallet Instance.¶

3. Digital Credentials Formats: Status Assertions are agnostic from the Digital Credential format to which they are bound.¶

4. Trust Model: Status Assertions operate under a model where the Verifier trusts the Credential Issuer to provide accurate status information, while the OAuth Status Lists operate under a model where the Verifier trusts the Status List Provider to maintain an accurate and up-to-date list of statuses.¶

5. Offline flow: OAuth Status List can be accessed by a Verifier when an internet connection is present. At the same time, OAuth Status List defines how to provide a static Status List Token, to be included within a Digital Credential. This requires the Wallet Instance to acquire a new Digital Credential for a specific presentation. Even if similar to the OAuth Status List Token, the Status Assertions enable the User to persistently use their preexistent Digital Credentials, as long as the linked Status Assertion is available and presented to the Verifier, and not expired.¶

6. Real-time validation: OAuth Status Lists provide the possibility to do real-time validation of the Digital Credential status. To support the real-time status validation use cases, a Wallet MAY implement strategy to request a new Status Assertion before sending it to the Verifier.¶

5. Requirements

The general requirements for the implementation of Status Assertion are listed in this section. The Status Assertion:¶

• MUST be presented in conjunction with the Digital Credential. The Status Assertion MUST be timestamped with its issuance datetime, using a timestamp which is later then the time of presentation issuance;¶

• MUST contain the expiration datetime after which the Digital Credential MUST NOT be considered valid anymore. The expiration datetime MUST be superior to the Status Assertion issuance datetime and it MUST end before the expiration of the Credential;¶

• MUST enable the offline use cases by employing validation using a cryptographic signature and the cryptographic public key of the Credential Issuer.¶

Please note: in this specification the examples and the normative properties of Assertions are reported in accordance with the JWT standard, while for the purposes of this specification any Digital Credential or Assertion format may be used, as long as all attributes and requirements defined in this specification are satisfied, even using equivalent names or values.¶

6. Proof of Possession of a Credential

The concept of Proof of Possession (PoP) of a Credential within the framework of the Status Assertion specification encompasses a broader perspective than merely possessing the digital bytes of the Credential. It involves demonstrating rightful control or ownership over the Credential, which can manifest in various forms depending on the technology employed and the nature of the digital Credential itself. For instance, a Credential could be presented visually (de-visu) with a personal portrait serving as a binding element.¶

While this specification does not prescribe any additional methods for the proof of possession of the Credential, it aims to offer guidance for concrete implementations utilizing common proof of possession mechanisms. This includes, but is not limited to:¶

1. Having the digital representation of the credential (the bytes).¶

2. Controlling a private key that corresponds to a public key associated with the Credential, often indicated within the Credential's cnf (confirmation) claim or through a similar mechanism.¶

The essence of requiring control over the private key and its demonstration through a cryptographic operation (e.g., signing a challenge or a token) is to ensure that the entity in possession of the Credential can execute actions exclusively reserved for the legitimate subject. The dual-layered approach of requiring both possession of the Credential and control over the corresponding private key indeed reinforces the security and integrity of the status assertion process. It also ensures that the entity requesting a Status Attestation is indeed the same entity to which the Credential was originally issued, affirming the authenticity and rightful possession of the Credential.¶

7. Status Assertion Request

The Credential Issuer provides the Wallet Instance with a Status Assertion, which is bound to a Digital Credential. This allows the Wallet Instance to present it, along with the Digital Credential itself, to a Verifier as proof of the Digital Credential's non-revocation status.¶

The following diagram shows the Wallet Instance requesting a Status Assertion to a Credential Issuer, related to a specific Credential issued by the same Credential Issuer.¶

+-------------------+                                  +--------------------+
|                   |                                  |                    |
|  Wallet Instance  |                                  | Credential Issuer  |
|                   |                                  |                    |
+--------+----------+                                  +----------+---------+
         |                                                        |
         | HTTP POST /status                                      |
         |  status_assertion_requests = [$StatusAssertionRequest] |
         +-------------------------------------------------------->
         |                                                        |
         |  Status Assertion Responses [...]                      |
         <--------------------------------------------------------+
         |                                                        |
+--------+----------+                                  +----------+---------+
|                   |                                  |                    |
|  Wallet Instance  |                                  | Credential Issuer  |
|                   |                                  |                    |
+-------------------+                                  +--------------------+

The Wallet Instance sends the Status Assertion request to the Credential Issuer, where: - The request MUST contain the base64url hash value of the Digital Credential, for which the Status Assertion is requested, and enveloped in a signed object as proof of possession. - The proof of possession MUST be signed with the private key corresponding to the confirmation claim assigned by the issuer and contained within the Digital Credential.¶

Below a non-normative example representing a Status Assertion Request array with a single JWT in it.¶

POST /status HTTP/1.1
Host: issuer.example.org
Content-Type: application/json

"status_assertion_requests" : ["${base64url(json({typ: (some pop for status-assertion)+jwt, ...}))}.payload.signature", ... ]

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

The status_assertion_requests MUST be set with an array of strings, where each string within the array represents a Digital Credential Status Assertion Request.¶

The Credential Issuer that receives the Status Assertion Request MUST validate that the Wallet Instance making the request is authorized to request Status Assertions. Therefore the following requirements MUST be satisfied:¶

• The Credential Issuer MUST verify the signature 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;¶

• The Credential Issuer MUST verify that it is the legitimate Issuer of the Digital Credential to which each Status Assertion Request object refers.¶

The technical and details about the status_assertion_requests object are defined in the next section.¶

  HTTP/1.1 400 Bad Request
  Content-Type: application/json;charset=UTF-8

  {
    "error": "invalid_request"
    "error_description": "The signature of the status assertion request is not valid"
  }

{
    "alg": "ES256",
    "typ": "status-assertion-request+jwt",
    "kid": $CREDENTIAL-CNF-JWKID
}
.
{
    "iss": "0b434530-e151-4c40-98b7-74c75a5ef760",
    "aud": "https://issuer.example.org/status-assertion-endpoint",
    "iat": 1698744039,
    "exp": 1698830439,
    "jti": "6f204f7e-e453-4dfd-814e-9d155319408c",
    "credential_hash": $Issuer-Signed-JWT-Hash
    "credential_hash_alg": "sha-256",
}

8. Status Assertion

When a Status Assertion is requested to a Credential Issuer, the Issuer checks the status of the Digital Credential and creates a Status Assertion bound to it.¶

If the Digital Credential is valid, the Credential Issuer creates a new Status Assertion, which a non-normative example is given below.¶

{
    "alg": "ES256",
    "typ": "status-assertion+jwt",
    "kid": $ISSUER-JWKID
}
.
{
    "iss": "https://issuer.example.org",
    "iat": 1504699136,
    "exp": 1504785536,
    "credential_hash": $CREDENTIAL-HASH,
    "credential_hash_alg": "sha-256",
    "cnf": {
        "jwk": {...}
    }
}

The Status Assertion MUST contain the following claims when the JWT format is used.¶

9. Status Assertion Response

If the Status Assertion is requested for a non-existent, expired, revoked or invalid Digital Credential, the Credential Issuer MUST respond with an HTTP Response with the status code set to 404.¶

If the Digital Credential is valid, the Credential Issuer MUST return an HTTP status code of 201 (Created), with the content type set to application/json. The response MUST include a JSON object with a member named status_assertion_responses, which contains the Status Assertions and or the Status Assertion Errors related to the request made by the Wallet Instance. In the non-normative example below is represented an HTTP Response with the status_assertion_responses JSON member:¶

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

{
    "status_assertion_responses": ["${base64url(json({typ: status-assertion+jwt, ...}))}.payload.signature", ... ]
}

The member status_assertion_responses MUST be an array of strings, where each of them represent a Status Assertion Response object or a Status Assertion Error object. For each entry in the status_assertion_responses array, the following requirements are met: - Each element in the array MUST match the corresponding element in the request array at the same index to which it is related. - Each element MUST contain the error or the status of the assertion using the typ member. set to "status-assertion-error+{jwt,cwt}" or "status-assertion+{jwt,cwt}", depending by the object type. - The corresponding entry in the response MUST be of the same type as requested. For example, if the entry in the request is "jwt", then the entry at the same position in the response must also be "jwt".¶

10. Interoperability of Credential Issuers Supporting Status Assertions

This section outlines how Credential Issuers support Status Assertions, detailing the necessary metadata and practices to integrate into their systems.¶

{
 "vct": "https://credentials.example.com/identity_credential",
 "given_name": "John",
 "family_name": "Doe",
 "email": "johndoe@example.com",
 "phone_number": "+1-202-555-0101",
 "address": {
   "street_address": "123 Main St",
   "locality": "Anytown",
   "region": "Anystate",
   "country": "US"
 },
 "birthdate": "1940-01-01",
 "is_over_18": true,
 "is_over_21": true,
 "is_over_65": true,
 "status": {
    "status_assertion": {
        "credential_hash_alg": "sha-256",
    }
 }
}

11. Presenting Status Assertions

The Wallet Instance that provides the Status Assertions using [@OpenID4VP], SHOULD include in the vp_token JSON array, as defined in [@OpenID4VP], the Status Assertion along with the related Digital Credential.¶

The Verifier that receives a Digital Credential supporting the Status Assertion, SHOULD:¶

• Decode and validate the Digital Credential;¶

• Check the presence of status.status_assertion in the Digital Credential. If true, the Verifier SHOULD:¶

  • produce the hash of the Digital Credential using the hashing algorithm configured in status.status_assertion.credential_hash_alg;¶

  • decode all the Status Assertions provided in the presentation, by matching the JWS Header parameter typ set to status-assertion+jwt and looking for the credential_hash value that matches with the hash produced at the previous point;¶

  • evaluate the validity of the Status Assertion.¶

Please note: The importance of checking the revocation status of Digital Credentials as a 'SHOULD' rather than a 'MUST' for a Verifier who gets Status Assertion for the Digital Credential stems from the fact that the decision of a Verifier to check the revocation status of Digital Credentials is not absolute and can be influenced by numerous variables. Consider as an example the case of age-over x; even if it has expired, it may still perform its intended purpose. As a result, the expiration status alone does not render it invalid. The adaptability recognizes that the need to verify revocation status may not always coincide with the actual usability of a Digital Credential, allowing Verifiers to examine and make educated conclusions based on a variety of scenarios.¶

12. Security Considerations

TODO Security¶

13. Privacy Considerations

In the design and implementation of Status Assertions, particular attention has been paid to privacy considerations to ensure that the system is respectful of user privacy and compliant with relevant regulations.¶

14. IANA Considerations

15. Normative References

[RFC2119]

Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997, <https://www.rfc-editor.org/rfc/rfc2119>.

[RFC7515]

Jones, M., Bradley, J., and N. Sakimura, "JSON Web Signature (JWS)", RFC 7515, DOI 10.17487/RFC7515, May 2015, <https://www.rfc-editor.org/rfc/rfc7515>.

[RFC7516]

Jones, M. and J. Hildebrand, "JSON Web Encryption (JWE)", RFC 7516, DOI 10.17487/RFC7516, May 2015, <https://www.rfc-editor.org/rfc/rfc7516>.

[RFC7517]

Jones, M., "JSON Web Key (JWK)", RFC 7517, DOI 10.17487/RFC7517, May 2015, <https://www.rfc-editor.org/rfc/rfc7517>.

[RFC7519]

Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token (JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015, <https://www.rfc-editor.org/rfc/rfc7519>.

[RFC7800]

Jones, M., Bradley, J., and H. Tschofenig, "Proof-of-Possession Key Semantics for JSON Web Tokens (JWTs)", RFC 7800, DOI 10.17487/RFC7800, April 2016, <https://www.rfc-editor.org/rfc/rfc7800>.

[RFC8174]

Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, May 2017, <https://www.rfc-editor.org/rfc/rfc8174>.

[RFC9126]

Lodderstedt, T., Campbell, B., Sakimura, N., Tonge, D., and F. Skokan, "OAuth 2.0 Pushed Authorization Requests", RFC 9126, DOI 10.17487/RFC9126, September 2021, <https://www.rfc-editor.org/rfc/rfc9126>.

Appendix A. Acknowledgments

We would like to thank:¶

• Paul Bastien¶

• Emanuele De Cupis¶

• Riccardo Iaconelli¶

• Marina Adomeit¶

• Victor Näslund¶

• Giada Sciarretta¶

• Amir Sharif¶

Appendix B. Document History

-02¶

• Name of the draft changed from OAuth Status Attestations to OAuth Status Assertions¶

Authors' Addresses