Internet DRAFT - draft-looker-oauth-jwt-cwt-status-list
draft-looker-oauth-jwt-cwt-status-list
Network Working Group T. Looker
Internet-Draft MATTR
Intended status: Informational P. Bastian
Expires: 11 January 2024 10 July 2023
JWT and CWT Status List
draft-looker-oauth-jwt-cwt-status-list-01
Abstract
This specification defines status list data structures for
representing the status of JSON Web Tokens (JWTs) [RFC7519] and CBOR
Web Tokens (CWTs) [RFC8392]. The status list data structures
themselves are also represented as JWTs or CWTs.
About This Document
This note is to be removed before publishing as an RFC.
The latest revision of this draft can be found at
https://vcstuff.github.io/draft-looker-oauth-jwt-cwt-status-list/
draft-looker-oauth-jwt-cwt-status-list.html. Status information for
this document may be found at https://datatracker.ietf.org/doc/draft-
looker-oauth-jwt-cwt-status-list/.
Source for this draft and an issue tracker can be found at
https://github.com/vcstuff/draft-looker-oauth-jwt-cwt-status-list.
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 11 January 2024.
Looker & Bastian Expires 11 January 2024 [Page 1]
Internet-Draft JWT and CWT Status List July 2023
Copyright Notice
Copyright (c) 2023 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.
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3
1.1. Rationale . . . . . . . . . . . . . . . . . . . . . . . . 3
2. Conventions and Definitions . . . . . . . . . . . . . . . . . 4
3. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 4
4. JSON Web Token Representation . . . . . . . . . . . . . . . . 4
4.1. Referenced Token Format and Processing Requirements . . . 4
4.1.1. Status Claim Format . . . . . . . . . . . . . . . . . 5
4.2. Status List JWT Format and Processing Requirements . . . 5
4.2.1. Status List Claim Format . . . . . . . . . . . . . . 7
4.2.2. Status List Encoding . . . . . . . . . . . . . . . . 7
5. Status Types . . . . . . . . . . . . . . . . . . . . . . . . 7
5.1. Status Types Values . . . . . . . . . . . . . . . . . . . 8
6. Example JWT Status Lists . . . . . . . . . . . . . . . . . . 8
6.1. Example Status List with 1-Bit Status Values . . . . . . 8
6.2. Example Status List with 2-Bit Status Values . . . . . . 9
7. CWT Representations . . . . . . . . . . . . . . . . . . . . . 10
8. Security Considerations . . . . . . . . . . . . . . . . . . . 10
8.1. Correct decoding and parsing of the encoded status
list . . . . . . . . . . . . . . . . . . . . . . . . . . 10
8.2. Cached and Stale status lists . . . . . . . . . . . . . . 10
8.3. Authorized access to the Status List . . . . . . . . . . 10
8.4. History . . . . . . . . . . . . . . . . . . . . . . . . . 11
9. Privacy Considerations . . . . . . . . . . . . . . . . . . . 11
9.1. Herd Privacy . . . . . . . . . . . . . . . . . . . . . . 11
9.2. Profiling . . . . . . . . . . . . . . . . . . . . . . . . 11
9.3. Correlation Risks and Tracking . . . . . . . . . . . . . 11
9.4. Malicious Issuers . . . . . . . . . . . . . . . . . . . . 11
9.5. Hosting Service (what's a better name here?) . . . . . . 11
10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 11
11. Normative References . . . . . . . . . . . . . . . . . . . . 11
Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . 12
Document History . . . . . . . . . . . . . . . . . . . . . . . . 12
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 12
Looker & Bastian Expires 11 January 2024 [Page 2]
Internet-Draft JWT and CWT Status List July 2023
1. Introduction
JSON Web Tokens (JWTs) [RFC7519] and CBOR Web Tokens (CWTs) [RFC8392]
as secure token formats, have vast possible applications. Some of
these applications can involve issuing a token whereby certain
semantics about the token can change over time, which are important
to be able to communicate to relying parties in an interoperable
manner, such as whether the token is considered invalidated or
suspended by its issuer.
This document defines Status List representations in JWT and CWT
formats that describe the individual statuses of multiple Referenced
Tokens, which themselves are also JWTs or CWTs. The statuses of all
Referenced Tokens are conveyed via a bit array in the Status List.
Each Referenced Token is allocated an index during issuance that
represents its position within this bit array. The value of the
bit(s) at this position correspond to the Referenced Token's status.
The document also defines how an issuer of a Referenced Token
references a Status List Token. Status Lists may be composed for
expressing a range of Status Types. This document defines basic
Status Types for the most common use cases as well as an
extensibility mechanism for custom Status Types. The Status List
Token may be used by an issuer in the Issuer-Holder-Verifier model to
express the status of verifiable credentials (Referenced Tokens)
issued by an issuer.
The following diagram depicts the basic conceptual relationship.
+------------------+ +-------------------+
| | References | |
| |------------------->| |
| Referenced Token | | Status List Token |
| (JWT or CWT) | | (JWT or CWT) |
| | Describes Status | |
| |<-------------------| |
+------------------+ +-------------------+
1.1. Rationale
Revocation mechanisms are an essential part for most identity
ecosystems. In the past, revocation of X.509 TLS certificates has
been proven difficult. Traditional certificate revocation lists
(CRLs) have limited scalability; Online Certificate Status Protocol
(OCSP) has additional privacy risks, since the client is leaking the
requested website to a third party. OCSP stapling is addressing some
of these problems at the cost of less up-to-date data. Modern
approaches use accumulator-based revocation registries and Zero-
Knowledge-Proofs to accommodate for this privacy gap, but face
Looker & Bastian Expires 11 January 2024 [Page 3]
Internet-Draft JWT and CWT Status List July 2023
scalability issues again.
This specification seeks to find a balance between scalability,
security, and privacy by minimizing the status information to mere
bits (often a single bit) and compressing the resulting binary data.
Thereby, a Status List may contain statuses of 100,000 or more
Referenced Tokens, but still remain relatively small. Placing large
amounts of Referenced Tokens into the same list also enables herd
privacy relative to the Issuer.
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
Status List: A bit array that lists the statuses of many Referenced
Tokens.
Status List Token: A token in JWT or CWT representation that
contains a Status List.
Referenced Token: A token in JWT or CWT representation which
contains a reference to a Status List Token. The information from
the contained Status List may give a verifier additional
information about up-to-date status of the Referenced Token.
4. JSON Web Token Representation
4.1. Referenced Token Format and Processing Requirements
The following rules apply to validating a Referenced Token in JWT
representation, which references a Status List Token. Application of
additional restrictions and policy are at the discretion of the
verifying party.
1. The JWT MUST contain an "iss" (issuer) claim that contains a
unique string identifier for the entity that issued the JWT. In
the absence of an application profile specifying otherwise,
compliant applications MUST compare issuer values using the
Simple String Comparison method defined in Section 6.2.1 of
[RFC3986]. The value MUST be equal to that of the "iss" claim
contained within the referenced Status List Token.
Looker & Bastian Expires 11 January 2024 [Page 4]
Internet-Draft JWT and CWT Status List July 2023
2. The JWT MUST contain an "status" (status) claim conforming to the
rules outlined in Section 4.1.1
The following example is the decoded header and payload of a JWT
meeting the processing rules as defined above.
{
"alg": "ES256",
"kid": "11"
}
.
{
"iss": "https://example.com",
"status": {
"idx": 0,
"uri": "https://example.com/statuslists/1"
}
}
4.1.1. Status Claim Format
The following rules apply to validating the "status" (status) claim
1. The claim value MUST be a valid JSON object.
2. The claim value object MUST contain an "idx" (index) member with
a numeric value that represents the index to check for status
information in the Status List for the current JWT. The value of
this member MUST be a non-negative number, containing a value of
zero or greater.
3. The claim value object MUST contain a "uri" member with a string
value that identifies the Status List containing the status
information for the JWT. The value of this member MUST be a uri
conforming to [RFC3986].
4.2. Status List JWT Format and Processing Requirements
The following rules apply to validating a JWT-based Status List
Token. Application of additional restrictions and policy are at the
discretion of the verifying party.
Looker & Bastian Expires 11 January 2024 [Page 5]
Internet-Draft JWT and CWT Status List July 2023
1. The JWT MUST contain an "iss" (issuer) claim that contains a
unique string identifier for the entity that issued the JWT. In
the absence of an application profile specifying otherwise,
compliant applications MUST compare issuer values using the
Simple String Comparison method defined in Section 6.2.1 of
[RFC3986]. The value MUST be equal to that of the "iss" claim
contained within the Referenced Token.
2. The JWT MUST contain a "sub" (subject) claim that contains an
unique string identifier for that Referenced Token. The value
MUST be equal to that of the "uri" claim contained in the
"status" claim of the Referenced Token.
3. The JWT MUST contain an "iat" (issued at) claim that identifies
the time at which it was issued.
4. The JWT MUST contain an "status_list" (status list) claim
conforming to the rules outlined in Section 4.2.1.
5. The JWT MAY contain an "exp" (expiration time) claim that conveys
when it is considered expired by its issuer.
6. The JWT MAY contain other claims.
7. The JWT MUST be digitally signed using an asymmetric
cryptographic algorithm. Relying parties MUST reject the JWT if
it is using a Message Authentication Code (MAC) algorithm.
Relying parties MUST reject JWTs with an invalid signature.
8. Relying parties MUST reject JWTs that are not valid in all other
respects per "JSON Web Token (JWT)" [RFC7519].
{
"typ": "statuslist+jwt",
"alg": "ES256",
"kid": "11"
}
.
{
"iss": "https://example.com",
"sub": "https://example.com/statuslists/1",
"iat": 1683560915,
"exp": 1686232115,
"status_list": {
"bits": 1,
"lst": "H4sIAMo_jGQC_9u5GABc9QE7AgAAAA"
}
}
Looker & Bastian Expires 11 January 2024 [Page 6]
Internet-Draft JWT and CWT Status List July 2023
4.2.1. Status List Claim Format
The following rules apply to validating the "status_list" (status
list) claim
1. The claim value MUST be a valid JSON object.
2. The claim value object MUST contain a "bits" (bit size) member
with an numeric value that represents the number of bits per
Referenced Token in the Status List ("lst") of the Status List
JWT. The allowed values for "bits" are 1,2,4 and 8.
3. The claim value object MUST contain a "lst" (list) member with a
string value that represents the status values for all the tokens
it conveys statuses for. The value MUST be computed using the
algorithm described in Section 4.2.2.
4.2.2. Status List Encoding
Each status of a Referenced Token MUST be represented with a bit size
of 1,2,4, or 8. Therefore up to 2,4,16, or 256 statuses for a
Referenced Token are possible, depending on the bit size. This
limitation is intended to limit bit manipulation necessary to a
single byte for every operation and thus keeping implementations
simpler and less error prone.
1. The overall Status List is encoded as a byte array. Depending on
the bitsize, each byte corresponds to 8/(#bit-size) statuses
(8,4,2, or 1). The status of each Referenced Token is identified
using the index that maps to one or more specific bits within the
byte array. The index starts counting at 0 and ends with "size"
- 1 (being the last valid entry). The bits within an array are
counted from least significant bit "0" to the most significant
bit ("7"). All bits of the byte array at a particular index are
set to a status value.
2. The complete byte array is compressed using gZIP [RFC1952].
3. The result of the gZIP compression is then base64url-encoded, as
defined in Section 2 of [RFC7515].
5. Status Types
This document defines potential statuses of Referenced Tokens as
Status Type values. If the Status List contains more than one bit
per token (as defined by "bits" in the Status List), then the whole
value of bits MUST describe one value. A Status List can not
represent multiple statuses per Referenced Token.
Looker & Bastian Expires 11 January 2024 [Page 7]
Internet-Draft JWT and CWT Status List July 2023
The registry in this document describes the basic Status Type values
required for the most common use cases. Additional values may
defined for particular use cases.
5.1. Status Types Values
A status describes the state, mode, condition or stage of an entity
that is described by the status list. Status Types MUST be numeric
values between 0 and 255. Status types described by this
specification comprise: - 0x00 - "VALID" - The status of the Token is
valid, correct or legal. - 0x01 - "INVALID" - The status of the
Token is revoked, annulled, taken back, recalled or cancelled. This
state is irreversible. - 0x02 - "SUSPENDED" - The status of the
Token is temporarily invalid, hanging, debarred from privilege. This
state is reversible.
The issuer of the Status List Token MUST choose an adequate "bits"
(bit size) to be able to describe the required Status Types for the
application.
6. Example JWT Status Lists
6.1. Example Status List with 1-Bit Status Values
In this example, the Status List is used as a revocation list. It
only requires the Status Types "VALID" and "INVALID"; therefore a
"bits" of 1 is sufficient.
This example Status List represents the statuses of 16 Referenced
Tokens, requiring 16 bits (2 bytes) of status.
status[0] = 1
status[1] = 0
status[2] = 0
status[3] = 1
status[4] = 1
status[5] = 1
status[6] = 0
status[7] = 1
status[8] = 1
status[9] = 1
status[10] = 0
status[11] = 0
status[12] = 0
status[13] = 1
status[14] = 0
status[15] = 1
Looker & Bastian Expires 11 January 2024 [Page 8]
Internet-Draft JWT and CWT Status List July 2023
These bits are concatenated:
byte 0 1 2
bit 7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0 7
+-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+ +-+...
values |1|0|1|1|1|0|0|1| |1|0|1|0|0|0|1|1| |0|...
+-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+ +-+...
index 7 6 5 4 3 2 1 0 15 ... 10 9 8 23
\_______________/ \_______________/
0xB9 0xA3
Resulting in the byte array:
byte_array = [0xB9, 0xA3]
After compression and base64url encoding, the generated Status List
is:
"status_list": {
"bits": 1,
"lst": "H4sIAMo_jGQC_9u5GABc9QE7AgAAAA"
}
6.2. Example Status List with 2-Bit Status Values
In thisexample, the Status List additionally includes the Status Type
"SUSPENDED. As the Status Type value for "SUSPENDED" is 0x02 and
does not fit into 1 bit, the "bits" is required to be 2.
This example Status List represents the status of 12 Referenced
Tokens, requiring 24 bits (3 bytes) of status.
status[0] = 1
status[1] = 2
status[2] = 0
status[3] = 3
status[4] = 0
status[5] = 1
status[6] = 0
status[7] = 1
status[8] = 1
status[9] = 2
status[10] = 3
status[11] = 3
These bits are concatenated:
Looker & Bastian Expires 11 January 2024 [Page 9]
Internet-Draft JWT and CWT Status List July 2023
byte 0 1 2
bit 7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0
+-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+
values |1|1|0|0|1|0|0|1| |0|1|0|0|0|1|0|0| |1|1|1|1|1|0|0|1|
+-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+
\ / \ / \ / \ / \ / \ / \ / \ / \ / \ / \ / \ /
status 3 0 2 1 1 0 1 0 3 3 2 1
index 3 2 1 0 7 6 5 4 11 10 9 8
\___________/ \___________/ \___________/
0xC9 0x44 0xF9
Resulting in the byte array:
byte_array = [0xC9, 0x44, 0xF9]
After compression and base64url encoding, the generated Status List
is:
"status_list": {
"bits": 2,
"lst": "H4sIAMo_jGQC_zvp8hMAZLRLMQMAAAA"
}
7. CWT Representations
TBD Define parallel CWT representations for Status Lists and
Referenced Tokens.
TBD Declare whether JWT and CWT representations can be used
interchangeably by the same issuer. For instance, declare whether a
status list can reference both JWT and CWT tokens.
8. Security Considerations
8.1. Correct decoding and parsing of the encoded status list
TODO elaborate on risks of incorrect parsing/decoding leading to
erroneous status data
8.2. Cached and Stale status lists
TODO consumers/Verifiers of the status list should be aware if they
fetch the up-to-date data
8.3. Authorized access to the Status List
TODO elaborate on authorization mechanisms preventing misuse and
profiling as described in privacy section
Looker & Bastian Expires 11 January 2024 [Page 10]
Internet-Draft JWT and CWT Status List July 2023
8.4. History
TODO elaborate on status list only providing the up-to date/latest
status, no historical data, may be provided by the underlying hosting
architecture
9. Privacy Considerations
9.1. Herd Privacy
TODO elaborate on herd privacy, size of the status list
9.2. Profiling
TODO elaborate on Verifiers regularly fetching the status list to
create a profile, possible countermeasures with authorized access to
the status list
9.3. Correlation Risks and Tracking
TODO elaborate on Issuer-Verifier correlation and Verifier-Verifier
correlation as the status list introduces unique,trackable data TODO
elaborate on issuers avoiding sequential usage of indices and status
lists TODO elaborate that a status list only gives information about
the maximum number of possible statuses that a list conveys, issuers
are recommended to pre-allocate lists, use dead entries that are
never assigned or other obfuscation mechanisms
9.4. Malicious Issuers
TODO elaborate on issuers generating unique status lists per
Referenced Token that do not offer herd privacy
9.5. Hosting Service (what's a better name here?)
TODO elaborate on increased privacy if the status list is hosted by a
third party instead of the issuer reducing tracking possiblities TODO
evaluate deifnition of Status List Provider? An entity that hosts
the Status List as a resource for potential verifiers. The Status
List Provider may be the issuer of the Status List but may also be
outsourced to a trusted third party.
10. IANA Considerations
This document specifies no IANA actions.
11. Normative References
Looker & Bastian Expires 11 January 2024 [Page 11]
Internet-Draft JWT and CWT Status List July 2023
[RFC1952] Deutsch, P., "GZIP file format specification version 4.3",
RFC 1952, DOI 10.17487/RFC1952, May 1996,
<https://www.rfc-editor.org/rfc/rfc1952>.
[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>.
[RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform
Resource Identifier (URI): Generic Syntax", STD 66,
RFC 3986, DOI 10.17487/RFC3986, January 2005,
<https://www.rfc-editor.org/rfc/rfc3986>.
[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>.
[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>.
[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>.
Acknowledgments
We would like to thank Christian Bormann, Michael B. Jones, Torsten
Lodderstedt, and Kristina Yasuda for their valuable contributions to
this specification.
Document History
-01
* Applied editorial improvements suggested by Michael Jones.
-00
* Initial draft
Authors' Addresses
Looker & Bastian Expires 11 January 2024 [Page 12]
Internet-Draft JWT and CWT Status List July 2023
Tobias Looker
MATTR
Email: tobias.looker@mattr.global
Paul Bastian
Email: paul.bastian@posteo.de
Looker & Bastian Expires 11 January 2024 [Page 13]
