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 12 December 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 non-revocation of digital credentials, whether in JSON Web Tokens (JWT) or CBOR Web Tokens (CWT) format. Status Assertions function similarly to OCSP Stapling, allowing clients to present to the relying parties time-stamped assertions provided by the credential issuer. The approach outlined in this specification enables the verification of credentials against revocation without direct queries to third-party systems, enhancing privacy, reducing latency, and faciliting offline verification.¶

The figure below illustrates the process by which a client, such as a Wallet Instance, requests and obtains a Status Assertion from the credential issuer.¶

+-----------------+                              +-------------------+
|                 | Requests Status Assertions   |                   |
|                 |----------------------------->|                   |
| Client          |                              | Credential Issuer |
|                 | Status Assertions            |                   |
|                 |<-----------------------------|                   |
+-----------------+                              +-------------------+

Figure 1: Status Assertion Issuance Flow.¶

The figure below illustrates the process by which a client 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 |          |
| Client            | 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], the term "CBOR Web Token (CWT)" defined in [RFC8392], "Client" as defined [RFC6749]¶

Holder:

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

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. 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. For the purposes of this specification, the Wallet Instance is considered as a Client.¶

4. Rationale

There are cases where the Verifier only needs to check the revocation status of a Digital Credential at the time of presentation, and therefore it 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, such as the one defined in draft-ietf-oauth-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 and in the the European Union's General Data Protection Regulation (GDPR), by creating a detailed profile of the End-User's Digital Credential status without explicit consent for such continuous surveillance.¶

5. Requirements

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

• SHOULD be presented in conjunction with the Digital Credential.¶

• MUST include information that links it to the referenced Digital Credential;¶

• MUST be timestamped with its issuance datetime, using a timestamp which is at or after the time of Digital Credential issuance which it refers;¶

• MUST contain the expiration datetime after which both the Status Assertion and the Digital Credential it refers 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 datetime of the Digital Credential;¶

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

• MUST NOT contain personal information about the User who owns the Digital Credential to which the Status Assertion refers.¶

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 Digital 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 Digital Credential (the bytes).¶

2. Controlling the confirmation method of the Credential, using the Credential's cnf parameter.¶

The essence of requiring proof of possession over the Credential through the confirmation method, such has proving the control of the cryptographic material related to a Credential, is to ensure that the entity in possession of the Credential can execute actions exclusively reserved to the legitimate Holder. The dual-layered approach of requiring both possession of the Credential and control over it, reinforces the security and integrity of the Status Assertion process. This ensures that the Holder requesting a Status Assertion is indeed the same Holder 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 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.¶

When the JWT or CWT format are used, the JWT/CWT MUST contain the parameters defined in the following table.¶

Below is a non-normative example of a Status Assertion Request with the JWT headers and payload are represented without applying signature and encoding:¶

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

Below is a non-normative example of a Status Assertion Request object in CWT format represented in CBOR diagnostic notation format [RFC8152], where the CWT headers and payload are presented without applying signature and encoding for better readability:¶

   [
       / protected / << {
       / alg / 1: -7 / ES256 /
       / typ / 16: -7 / status-assertion-request+cwt /
       / kid / 4: h'3132' / $CREDENTIAL-CNF-CWKID /
     } >>,
     / unprotected / {
     },
     / payload / << {
       / iss    / 1: 0b434530-e151-4c40-98b7-74c75a5ef760 /,
       / aud    / 3: https://issuer.example.org/status-assertion-endpoint /,
       / iat    / 6: 1698744039 /,
       / exp    / 4: 1698830439 /,
       / cti    / 7: 6f204f7e-e453-4dfd-814e-9d155319408c /,
       / credential_hash / 8: $Issuer-Signed-JWT-Hash /,
       / credential_hash_alg / 9: sha-256 /
     } >>,
   ]

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

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

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. Therefore the following requirements MUST be satisfied:¶

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

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

8. Status Assertion Response

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 200 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, as defined in the section Status Assertion (Section 10) or a Status Assertion Error object, as defined in the section Status Error (Section 9).¶

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 position index to which it is related, eg: [requestAboutA, requestAboutB] produces [responseAboutA, responseErrorAboutB]. - Each element MUST contain the error or the status of the assertion using the typ member. set to "status-assertion+{jwt,cwt}" or "status-assertion-error+{jwt,cwt}", depending by the object type. - The corresponding entry in the response MUST be of the same data format 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". - The corresponding entry in the response MUST NOT contain any information regarding the Verifier to whom it may be presented, such as the Verifier identifier as the intended audience.¶

9. Status Assertion Error

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 200 and the status_assertion_responses array with the related Status Assertion Error object.¶

The Status Assertion Error MUST NOT be presented or provided to a Verifier, the only audience of the Status Assertion Error is the Holder of the Credential that has requested the Status Assertion. Therefore, it is not necessary that the Status Assertion Error contains the parameter aud within its payload.¶

Below a non-normative example of a Status Assertion Error object in JWT format, with the headers and payload represented in JSON and without applying the signature.¶

{
    "alg": "ES256",
    "typ": "status-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": "credential_revoked",
    "error_description": "Credential is revoked."
    }
}

The Status Assertion Error object MUST contain the parameters described in the table below:¶

10. 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 where the format is JWT.¶

{
    "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 parameters defined below.¶

11. 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",
    }
 }
}

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

13. Considerations On Revocation Verification

The recommendation for Verifiers to check the revocation status of Digital Credentials as a 'SHOULD' instead of a 'MUST' acknowledges that the decision to verify revocation is not absolute and may be influenced by various factors. 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.¶

14. Security Considerations

TODO Security¶

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

16. IANA Considerations

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

[RFC6749]

Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", RFC 6749, DOI 10.17487/RFC6749, October 2012, <https://www.rfc-editor.org/rfc/rfc6749>.

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

[RFC8152]

Schaad, J., "CBOR Object Signing and Encryption (COSE)", RFC 8152, DOI 10.17487/RFC8152, July 2017, <https://www.rfc-editor.org/rfc/rfc8152>.

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

[RFC8392]

Jones, M., Wahlstroem, E., Erdtman, S., and H. Tschofenig, "CBOR Web Token (CWT)", RFC 8392, DOI 10.17487/RFC8392, May 2018, <https://www.rfc-editor.org/rfc/rfc8392>.

[RFC8747]

Jones, M., Seitz, L., Selander, G., Erdtman, S., and H. Tschofenig, "Proof-of-Possession Key Semantics for CBOR Web Tokens (CWTs)", RFC 8747, DOI 10.17487/RFC8747, March 2020, <https://www.rfc-editor.org/rfc/rfc8747>.

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

• Sara Casanova¶

• Emanuele De Cupis¶

• Riccardo Iaconelli¶

• Marina Adomeit¶

• Victor Näslund¶

• Giada Sciarretta¶

• Amir Sharif¶

Appendix B. Document History

-00¶

• Removed any comparison with OAuth Status List¶

• Status Assertion Request and Response is now a json array with multiple entries.¶

• Better generalization about the confirmation methods.¶

• Removed any informative comparison with OAuth Status List.¶

• JWT and CWT typ.¶

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

• Extended Status Assertion errors table added in the section Status Error (Section 9).¶

Authors' Addresses