diff --git a/README.md b/README.md index fe9fc5a..cb7cf9b 100644 --- a/README.md +++ b/README.md @@ -28,13 +28,15 @@ $ make Command line usage requires that you have the necessary software installed. See [the instructions](https://github.com/martinthomson/i-d-template/blob/main/doc/SETUP.md). +## Implementations (Open Source) -# Implementations - -| Project | Language | Issuer | Holder | Relying Party | +| Project | Language | Issuer | Holder | Relying Party | |---|---|---|---|---| -| [OWF sd-jwt-js](https://github.com/openwallet-foundation/sd-jwt-js) | TypeScript | yes | yes | yes | +| [OWF sd-jwt-js](https://github.com/openwallet-foundation/sd-jwt-js) | TypeScript | yes | yes | yes | +| [Adorsys status-list-server](https://github.com/adorsys/status-list-server) | Rust | yes | no | no | +| [Bundesdruckerei issuer](https://github.com/Bundesdruckerei-GmbH/pid-issuer/tree/main/status-list-service-0.1.11) | Kotlin | yes | yes | yes | +| [eudi-wallet-it-python](https://github.com/italia/eudi-wallet-it-python/blob/main/pyeudiw/status_list) | Python | no | yes | no | -# Testing +## Testing You may use this [Cyberchef script](https://gchq.github.io/CyberChef/#recipe=JWT_Decode()JPath_expression('status_list.lst','%5C%5Cn')From_Base64('A-Za-z0-9-_',true,false)Zlib_Inflate(0,0,'Adaptive',false,false)To_Binary('Line%20feed',8)Add_line_numbers()) to quickly analyze a Token Status List in JWT format. diff --git a/draft-ietf-oauth-status-list.md b/draft-ietf-oauth-status-list.md index 5d5a503..bc11b4b 100644 --- a/draft-ietf-oauth-status-list.md +++ b/draft-ietf-oauth-status-list.md @@ -1,5 +1,5 @@ --- -title: "Token Status List" +title: "Token Status List (TSL)" category: std lang: en @@ -27,6 +27,7 @@ author: email: tobias.looker@mattr.global - fullname: Paul Bastian + organization: Bundesdruckerei email: paul.bastian@posteo.de - fullname: Christian Bormann @@ -123,7 +124,7 @@ informative: --- abstract -This specification defines a mechanism, data structures and processing rules for representing the status of tokens secured by JSON Object Signing and Encryption (JOSE) or CBOR Object Signing and Encryption (COSE), such as JWT, SD-JWT VC, CBOR Web Token and ISO mdoc. It also defines an extension point and a registry for future status mechanisms. +This specification defines a mechanism called Token Status List (abbreviated TSL), data structures and processing rules for representing the status of tokens secured by JSON Object Signing and Encryption (JOSE) or CBOR Object Signing and Encryption (COSE), such as JWT, SD-JWT VC, CBOR Web Token and ISO mdoc. It also defines an extension point and a registry for future status mechanisms. --- middle @@ -131,7 +132,7 @@ This specification defines a mechanism, data structures and processing rules for Token formats secured by JOSE {{IANA.JOSE}} or COSE {{RFC9052}}, such as JWTs {{RFC7519}}, SD-JWT VCs {{SD-JWT.VC}}, CWTs {{RFC8392}} and ISO mdoc {{ISO.mdoc}}, have vast possible applications. Some of these applications can involve issuing a token whereby certain semantics about the token or its validity may change over time. Communicating these changes to relying parties in an interoperable manner, such as whether the token is considered invalidated or suspended by its issuer is important for many of these applications. -This document defines a Status List data structure that describes the individual statuses of multiple Referenced Tokens. A Referenced Token may be of any format, but is most commonly a data structures secured by JOSE or COSE. The Referenced Token is referenced by the Status List, which describes the status of the Referenced Token. 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 index corresponds to the Referenced Token's status. A Status List is provided within a Status List Token protected by cryptographic signature or MAC and this document defines its representations in JWT and CWT format. +This document defines a Status List data structure that describes the individual statuses of multiple Referenced Tokens. A Referenced Token may be of any format, but is most commonly a data structure secured by JOSE or COSE. The Referenced Token is referenced by the Status List, which describes the status of the Referenced Token. 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 index corresponds to the Referenced Token's status. A Status List is provided within a Status List Token protected by cryptographic signature or MAC and this document defines its representations in JWT and CWT format. The following diagram depicts the relationship between the artifacts: @@ -175,13 +176,13 @@ The following diagram depicts the relationship between the involved roles (Relyi ~~~ -Status Lists may be composed to express 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. +Status Lists can be used to express a variety 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. Furthermore, the document defines an extension point that enables other specifications to describe additional status mechanisms and creates an IANA registry. ## Example Use Cases -An example of the usage of a Status List is to manage the status of issued access tokens as defined in section 1.4 of {{RFC6749}}. Token Introspection {{RFC7662}} defines another way to determine the status of an issued access token, but it requires the party trying to validate the state of access tokens to directly contact the token issuer, whereas the mechanism defined in this specification does not have this limitation. +An example of the usage of a Status List is to manage the statuses of issued access tokens as defined in section 1.4 of {{RFC6749}}. Token Introspection {{RFC7662}} provides a method to determine the status of an issued access token, but it necessitates the party attempting to validate the state of access tokens to directly contact the Issuer of each token for validation. In contrast, the mechanism defined in this specification allows a party to retrieve the statuses for many tokens, reducing interactions with the Issuer substantially. This not only improves scalability but also enhances privacy by preventing the Issuer from gaining knowledge of access tokens being verified (herd anonymity). Another possible use case for the Status List is to express the status of verifiable credentials (Referenced Tokens) issued by an Issuer in the Issuer-Holder-Verifier model {{SD-JWT.VC}}. @@ -189,7 +190,7 @@ Another possible use case for the Status List is to express the status of verifi Revocation mechanisms are an essential part of 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 scalability issues again. Another alternative is short-lived Referenced Tokens with regular re-issuance, but this puts additional burden on the Issuer's infrastructure. -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 many thousands or millions Referenced Tokens while remaining as small as possible. Placing large amounts of Referenced Tokens into the same list also enables herd privacy relative to the Status Provider. +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 many thousands or millions Referenced Tokens while remaining as small as possible. Placing a large number of Referenced Tokens into the same list also offers Holders and Relying Parties herd privacy from the Status Provider. ## Design Considerations @@ -221,7 +222,7 @@ Other status mechanisms may have different tradeoffs regarding security, privacy # Terminology Issuer: -: An entity that issues the Referenced Token. +: An entity that issues the Referenced Token. Also known as a Provider. Status Issuer: : An entity that issues the Status List Token about the status information of the Referenced Token. This role may be fulfilled by the Issuer. @@ -233,7 +234,7 @@ Holder: : An entity that receives Referenced Tokens from the Issuer and presents them to Relying Parties. Relying Party: -: An entity that relies on the Referenced Token and fetches the corresponding Status List Token to validate the status of that Referenced Token. Also known as Verifier. +: An entity that relies on the Referenced Token and fetches the corresponding Status List Token to validate the status of that Referenced Token. Also known as a Verifier. Status List: : An object in JSON or CBOR representation containing a compressed byte array that represents the statuses of many Referenced Tokens. @@ -249,7 +250,7 @@ base64url: # Status List {#status-list} -A Status List is a data structure that contains the statuses of many Referenced Tokens represented by one or multiple bits. The [first section](#status-list-byte-array) describes how to construct a compressed byte array that is the base component for the Status List data structure. The second and third section describe how to encode such a Status List in JSON and CBOR representation. +A Status List is a data structure that contains the statuses of many Referenced Tokens represented by one or multiple bits. The [first section](#status-list-byte-array) describes how to construct a compressed byte array that is the base component for the Status List data structure. The second and third sections describe how to encode such a Status List in JSON and CBOR representations. ## Compressed Byte Array {#status-list-byte-array} @@ -259,7 +260,7 @@ A compressed byte array containing the status information of the Referenced Toke 2. The Status Issuer creates a byte array of size = amount of Referenced Tokens * `bits` / 8 or greater. Depending on the `bits`, each byte in the array corresponds to 8/(`bits`) statuses (8,4,2 or 1). -3. The Status Issuer sets the status values for all Referenced Tokens within the byte array. The status of each Referenced Token is identified using an index that maps to one or more specific bits within the byte array. The index starts counting at 0 and ends with amount of Referenced Tokens - 1 (being the last valid entry). The bits within an array are counted from the 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. +3. The Status Issuer sets the status values for all Referenced Tokens within the byte array. The status of each Referenced Token is identified using an index that maps to one or more specific bits within the byte array. The index starts counting at 0 and ends with amount of Referenced Tokens - 1 (being the last valid entry). The bits within an array are counted from the 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 (see [](#status-types) for more details on the values). 4. The Status Issuer compresses the byte array using DEFLATE {{RFC1951}} with the ZLIB {{RFC1950}} data format. Implementations are RECOMMENDED to use the highest compression level available. @@ -339,7 +340,7 @@ byte value 0xC9 0x44 0xF9 This section defines the data structure for a JSON-encoded Status List: -* `status_list`: REQUIRED. JSON Object that contains a Status List. It MUST contain at least the following claims: +* The `StatusList` structure is a JSON Object and MUST contain at least the following members: * `bits`: REQUIRED. JSON Integer specifying the number of bits per Referenced Token in the compressed byte array (`lst`). The allowed values for `bits` are 1,2,4 and 8. * `lst`: REQUIRED. JSON String that contains the status values for all the Referenced Tokens it conveys statuses for. The value MUST be the base64url-encoded compressed byte array as specified in [](#status-list-byte-array). * `aggregation_uri`: OPTIONAL. JSON String that contains a URI to retrieve the Status List Aggregation for this type of Referenced Token or Issuer. See section [](#aggregation) for further details. @@ -362,10 +363,10 @@ See section [](#test-vectors) for more test vectors. This section defines the data structure for a CBOR-encoded Status List: -* The `StatusList` structure is a map (Major Type 5) and defines the following entries: - * `bits`: REQUIRED. Unsigned integer (Major Type 0) that contains the number of bits per Referenced Token in the compressed byte array (`lst`). The allowed values for `bits` are 1, 2, 4 and 8. - * `lst`: REQUIRED. Byte string (Major Type 2) that contains the status values for all the Referenced Tokens it conveys statuses for. The value MUST be the compressed byte array as specified in [](#status-list-byte-array). - * `aggregation_uri`: OPTIONAL. Text string (Major Type 3) that contains a URI to retrieve the Status List Aggregation for this type of Referenced Token. See section [](#aggregation) for further detail. +* The `StatusList` structure is a CBOR map (Major Type 5) and defines the following entries: + * `bits`: REQUIRED. CBOR Unsigned integer (Major Type 0) that contains the number of bits per Referenced Token in the compressed byte array (`lst`). The allowed values for `bits` are 1, 2, 4 and 8. + * `lst`: REQUIRED. CBOR Byte string (Major Type 2) that contains the status values for all the Referenced Tokens it conveys statuses for. The value MUST be the compressed byte array as specified in [](#status-list-byte-array). + * `aggregation_uri`: OPTIONAL. CBOR Text string (Major Type 3) that contains a URI to retrieve the Status List Aggregation for this type of Referenced Token. See section [](#aggregation) for further detail. The following is the CDDL definition of the StatusList structure: @@ -393,7 +394,7 @@ See section [](#test-vectors) for more test vectors. # Status List Token {#status-list-token} -A Status List Token embeds the Status List into a token that is cryptographically signed and protects the integrity of the Status List. This allows for the Status List Token to be hosted by third parties or be transferred for offline use cases. +A Status List Token embeds a Status List into a token that is cryptographically signed and protects the integrity of the Status List. This allows for the Status List Token to be hosted by third parties or be transferred for offline use cases. This section specifies Status List Tokens in JSON Web Token (JWT) and CBOR Web Token (CWT) format. @@ -411,7 +412,7 @@ The following content applies to the JWT Claims Set: * `iat`: REQUIRED. As generally defined in {{RFC7519}}. The `iat` (issued at) claim MUST specify the time at which the Status List Token was issued. * `exp`: OPTIONAL. As generally defined in {{RFC7519}}. The `exp` (expiration time) claim, if present, MUST specify the time at which the Status List Token is considered expired by the Status Issuer. * `ttl`: OPTIONAL. The `ttl` (time to live) claim, if present, MUST specify the maximum amount of time, in seconds, that the Status List Token can be cached by a consumer before a fresh copy SHOULD be retrieved. The value of the claim MUST be a positive number encoded in JSON as a number. -* `status_list`: REQUIRED. The `status_list` (status list) claim MUST specify the Status List conforming to the rules outlined in [](#status-list-json). +* `status_list`: REQUIRED. The `status_list` (status list) claim MUST specify the Status List conforming to the structure defined in [](#status-list-json). The following additional rules apply: @@ -443,7 +444,7 @@ The following content applies to the CWT Claims Set: * `6` (issued at): REQUIRED. As generally defined in {{RFC8392}}. The issued at claim MUST specify the time at which the Status List Token was issued. * `4` (expiration time): OPTIONAL. As generally defined in {{RFC8392}}. The expiration time claim, if present, MUST specify the time at which the Status List Token is considered expired by its issuer. * `65534` (time to live): OPTIONAL. Unsigned integer (Major Type 0). The time to live claim, if present, MUST specify the maximum amount of time, in seconds, that the Status List Token can be cached by a consumer before a fresh copy SHOULD be retrieved. The value of the claim MUST be a positive number. -* `65533` (status list): REQUIRED. The status list claim MUST specify the Status List conforming to the rules outlined in [](#status-list-cbor). +* `65533` (status list): REQUIRED. The status list claim MUST specify the Status List conforming to the structure defined in [](#status-list-cbor). The following additional rules apply: @@ -471,7 +472,7 @@ The following is the CBOR Annotated Hex output of the example above: ## Status Claim {#status-claim} -By including a "status" claim in a Referenced Token, the Issuer is referencing a mechanism to retrieve status information about this Referenced Token. The claim contains members used to reference to a Status List Token as defined in this specification. Other members of the "status" object may be defined by other specifications. This is analogous to "cnf" claim in Section 3.1 of {{RFC7800}} in which different authenticity confirmation methods can be included. +By including a "status" claim in a Referenced Token, the Issuer is referencing a mechanism to retrieve status information about this Referenced Token. This specification defines one possible member of the "status" object, called "status_list". Other members of the "status" object may be defined by other specifications. This is analogous to "cnf" claim in Section 3.1 of {{RFC7800}} in which different authenticity confirmation methods can be included. ## Referenced Token in JOSE {#referenced-token-jose} @@ -480,8 +481,8 @@ The Referenced Token MAY be encoded as a "JSON Web Token (JWT)" according to {{R The following content applies to the JWT Claims Set: * `status`: REQUIRED. The `status` (status) claim MUST specify a JSON Object that contains at least one reference to a status mechanism. - * `status_list`: REQUIRED when the status mechanism defined in this specification is used. It contains a reference to a Status List Token. It MUST at least contain the following claims: - * `idx`: REQUIRED. The `idx` (index) claim MUST specify an Integer that represents the index to check for status information in the Status List for the current Referenced Token. The value of `idx` MUST be a non-negative number, containing a value of zero or greater. + * `status_list`: REQUIRED when the status mechanism defined in this specification is used. It MUST specify a JSON Object that contains a reference to a Status List Token. It MUST at least contain the following claims: + * `idx`: REQUIRED. The `idx` (index) claim MUST specify a non-negative Integer that represents the index to check for status information in the Status List for the current Referenced Token. * `uri`: REQUIRED. The `uri` (URI) claim MUST specify a String value that identifies the Status List Token containing the status information for the Referenced Token. The value of `uri` MUST be a URI conforming to {{RFC3986}}. Application of additional restrictions and policies are at the discretion of the Relying Party. @@ -505,9 +506,7 @@ The following is a non-normative example of a decoded header and payload of a Re } ~~~ -SD-JWT-based Verifiable Credentials {{SD-JWT.VC}} introduce the usage of a status mechanism in Section 3.2.2.2. The "status" object uses the same encoding as a JWT as defined in {{referenced-token-jose}}. - -The following is a non-normative example of a Referenced Token in SD-JWT-VC serialized form as received from an Issuer: +SD-JWT-based Verifiable Credentials {{SD-JWT.VC}} section 3.2.2.2. introduces the usage of the status mechanism defined in this section. Therefore, an SD-JWT VC can be considered a Referenced Token. The following is a non-normative example of a Referenced Token in SD-JWT VC serialized form as received from an Issuer: ~~~ ascii-art @@ -560,7 +559,7 @@ The following content applies to the CWT Claims Set: * `65535` (status): REQUIRED. The status claim is encoded as a `Status` CBOR structure and MUST include at least one data item that refers to a status mechanism. Each data item in the `Status` CBOR structure comprises a key-value pair, where the key must be a CBOR text string (Major Type 3) specifying the identifier of the status mechanism and the corresponding value defines its contents. This specification defines the following data items: * `status_list` (status list): REQUIRED when the status mechanism defined in this specification is used. It has the same definition as the `status_list` claim in [](#referenced-token-jose) but MUST be encoded as a `StatusListInfo` CBOR structure with the following fields: - * `idx`: REQUIRED. Unsigned integer (Major Type 0) The `idx` (index) claim MUST specify an Integer that represents the index to check for status information in the Status List for the current Referenced Token. The value of `idx` MUST be a non-negative number, containing a value of zero or greater. + * `idx`: REQUIRED. Unsigned integer (Major Type 0) The `idx` (index) claim MUST specify a non-negative Integer that represents the index to check for status information in the Status List for the current Referenced Token. * `uri`: REQUIRED. Text string (Major Type 3). The `uri` (URI) claim MUST specify a String value that identifies the Status List Token containing the status information for the Referenced Token. The value of `uri` MUST be a URI conforming to {{RFC3986}}. Application of additional restrictions and policies are at the discretion of the Relying Party. @@ -727,9 +726,9 @@ This document creates a registry in [](#iana-status-types) that includes the mos - 0x00 - "VALID" - The status of the Referenced Token is valid, correct or legal. - 0x01 - "INVALID" - The status of the Referenced Token is revoked, annulled, taken back, recalled or cancelled. - - 0x02 - "SUSPENDED" - The status of the Referenced Token is temporarily invalid, hanging, debarred from privilege. This state is reversible. + - 0x02 - "SUSPENDED" - The status of the Referenced Token is temporarily invalid, hanging, debarred from privilege. This state is usually temporary. - The Status Type value 0x03 and Status Type values in the range 0x0B until 0x0F are permanently reserved as application specific. Meaning the processing of Status Types using these values is application specific. All other Status Type values are reserved for future registration. + The Status Type value 0x03 and Status Type values in the range 0x0B until 0x0F are permanently reserved as application specific. The processing of Status Types using these values is application specific. All other Status Type values are reserved for future registration. The processing rules for Referenced Tokens (such as JWT or CWT) precede any evaluation of a Referenced Token's status. For example, if a token is evaluated as being expired through the "exp" (Expiration Time) but also has a status of 0x00 ("VALID"), the token is considered expired. @@ -737,15 +736,15 @@ See [](#privacy-status-types) for privacy considerations on status types. # Verification and Processing -The fetching, processing and verifying of a Status List Token may be done by either the Holder or the Relying Party. In the following section is described from the role of the Relying Party, however the same rules would also apply for the Holder. +The fetching, processing and verifying of a Status List Token may be done by either the Holder or the Relying Party. The following section is described from the role of the Relying Party, however the same rules would also apply for the Holder. ## Status List Request {#status-list-request} To obtain the Status List Token, the Relying Party MUST send an HTTP GET request to the URI provided in the Referenced Token. -The HTTP endpoint SHOULD support the use of Cross-Origin Resource Sharing (CORS) {{CORS}} and/or other methods as appropriate to enable Browser-based clients to access it. +The HTTP endpoint SHOULD support the use of Cross-Origin Resource Sharing (CORS) {{CORS}} and/or other methods as appropriate to enable Browser-based clients to access it, unless ecosystems using this specification choose not to support Browser-based clients. -The Relying Party SHOULD send the following Accept-Header to indicate the requested response type: +The Relying Party SHOULD send the following Accept HTTP Header to indicate the requested response type unless the Content-Type of Status List Tokens in the respective ecosystem is known or the Relying Party supports both formats: - "application/statuslist+jwt" for Status List Token in JWT format - "application/statuslist+cwt" for Status List Token in CWT format @@ -784,13 +783,15 @@ In the successful response, the Status Provider MUST use the following content-t In the case of "application/statuslist+jwt", the response MUST be of type JWT and follow the rules of [](#status-list-token-jwt). In the case of "application/statuslist+cwt", the response MUST be of type CWT and follow the rules of [](#status-list-token-cwt). +The body of such an HTTP response contains the raw Status List Token, that means the binary encoding as defined in section 9.2.1 of {{RFC8392}} for a Status List Token in CWT format and the JWS Compact Serialization form for a Status List Token in JWT format. Note that while the examples for Status List Tokens in CWT format in this document are provided in hex encoding, this is done purely for readability and does not mean that hex encoding is expected for HTTP messages. + The HTTP response SHOULD use gzip Content-Encoding as defined in {{RFC9110}}. -If caching-related HTTP headers are present in the HTTP response, Relying Parties SHOULD prioritize the exp and ttl claims within the Status List Token over the HTTP headers for determining caching behavior. +If caching-related HTTP headers are present in the HTTP response, Relying Parties MUST prioritize the exp and ttl claims within the Status List Token over the HTTP headers for determining caching behavior. ## Validation Rules -Upon receiving a Referenced Token, a Relying Party MUST first perform the validation of the Referenced Token - e.g., checking for expected attributes, valid signature and expiration time. The processing rules for Referenced Tokens (such as JWT or CWT) precede any evaluation of a Referenced Token's status. For example, if a token is evaluated as being expired through the "exp" (Expiration Time) but also has a status of 0x00 ("VALID"), the token is considered expired. As this is out of scope for this document, this validation is not described here, but is expected to be done according to the format of the Referenced Token. +Upon receiving a Referenced Token, a Relying Party MUST first perform the validation of the Referenced Token - e.g., checking for expected attributes, valid signature and expiration time. The processing rules for Referenced Tokens (such as JWT or CWT) MUST precede any evaluation of a Referenced Token's status. For example, if a token is evaluated as being expired through the "exp" (Expiration Time) but also has a status of 0x00 ("VALID"), the token is considered expired. As this is out of scope for this document, this validation is not described here, but is expected to be done according to the format of the Referenced Token. If this validation is not successful, the Referenced Token MUST be rejected. If the validation was successful, the Relying Party MUST perform the following validation steps to evaluate the status of the reference token: @@ -839,9 +840,9 @@ Content-Type: application/statuslist+jwt # Status List Aggregation {#aggregation} -Status List Aggregation is an optional mechanism to retrieve a list of URIs to all Status List Tokens, allowing a Relying Party to fetch all relevant Status Lists for a specific type of Referenced Token or Issuer. This mechanism is intended to support fetching and caching mechanisms and allow offline validation of the status of a reference token for a period of time. +Status List Aggregation is an optional mechanism offered by the Issuer to publish a list of one or more Status List Tokens URIs, allowing a Relying Party to fetch Status List Tokens provided by this Issuer. This mechanism is intended to support fetching and caching mechanisms and allow offline validation of the status of a reference token for a period of time. -If a Relying Party encounters an invalid Status List referenced in the response from the Status List Aggregation endpoint, it SHOULD continue processing the other valid Status Lists referenced in the response. +If a Relying Party encounters an error while validating one of the Status List Tokens returned from the Status List Aggregation endpoint, it SHOULD continue processing the other Status List Tokens. There are two options for a Relying Party to retrieve the Status List Aggregation. An Issuer MAY support any of these mechanisms: @@ -870,9 +871,10 @@ An Issuer MAY support any of these mechanisms: ## Issuer Metadata -The Issuer MAY link to the Status List Aggregation URI in metadata that can be provided by different means like .well-known metadata as is used commonly in OAuth and OpenID or via a VICAL extension for ISO mDoc / mDL. If the Issuer is an OAuth Authorization Server according to {{RFC6749}}, it is RECOMMENDED to use `status_list_aggregation_endpoint` for its metadata defined by {{RFC8414}}. +The Issuer MAY link to the Status List Aggregation URI in metadata that can be provided by different means like .well-known metadata as is used commonly in OAuth and OpenID Connect, or within Issuer certificates or trust lists (such as VICAL as defined in Annex C of {{ISO.mdoc}}). If the Issuer is an OAuth Authorization Server according to {{RFC6749}}, it is RECOMMENDED to use `status_list_aggregation_endpoint` for its metadata defined by {{RFC8414}}. The Issuer MAY limit the Status List Tokens listed by a Status List Aggregation to a particular type of Referenced Token. + +The concrete implementation details depend on the specific ecosystem and are out of scope of this specification. -The concrete specification on how this is implemented depends on the specific ecosystem and is out of scope of this specification. ## Status List Parameter @@ -884,7 +886,7 @@ This section defines the structure for a JSON-encoded Status List Aggregation: * `status_lists`: REQUIRED. JSON array of strings that contains URIs linking to Status List Tokens. -The Status List Aggregation URI provides a list of Status List URIs. This aggregation in JSON and the media type return SHOULD be `application/json`. A Relying Party can iterate through this list and fetch all Status List Tokens before encountering the specific URI in a Referenced Token. +The Status List Aggregation URI provides a list of Status List Token URIs. This aggregation in JSON and the media type return MUST be `application/json`. A Relying Party can iterate through this list and fetch all Status List Tokens before encountering the specific URI in a Referenced Token. The following is a non-normative example for media type `application/json`: @@ -899,21 +901,20 @@ The following is a non-normative example for media type `application/json`: } ~~~ -# X.509 Certificate Extensions - -## Extended Key Usage Extension {#eku} +# X.509 Certificate Extended Key Usage Extension {#eku} {{RFC5280}} specifies the Extended Key Usage (EKU) X.509 certificate extension for use on end entity certificates. The extension indicates one or more purposes for which the certified public key is valid. The EKU extension can be used in conjunction with the Key Usage (KU) extension, which indicates the set of basic cryptographic operations for which the certified key may be used. A certificate's issuer explicitly delegates Status List Token signing authority by issuing a X.509 certificate containing the KeyPurposeId defined below in the extended key usage extension. +Other specifications MAY choose to re-use this OID for other status mechanisms under the condition that they are registered in the "JWT Status Mechanisms" or "CWT Status Mechanisms" registries. The following OID is defined for usage in the EKU extension -``` - id-kp OBJECT IDENTIFIER ::= +~~~ + id-kp OBJECT IDENTIFIER ::= { iso(1) identified-organization(3) dod(6) internet(1) security(5) mechanisms(5) pkix(7) 3 } - id-kp-oauthStatusListSigning OBJECT IDENTIFIER ::= { id-kp TBD } -``` + id-kp-oauthStatusSigning OBJECT IDENTIFIER ::= { id-kp TBD } +~~~ # Security Considerations {#Security} @@ -933,13 +934,15 @@ A Status List Token in the CWT format should follow the security considerations ## Key Resolution and Trust Management {#key-management} -This specification does not mandate specific methods for key resolution and trust management, however the following recommendations are made for specifications, profiles, or ecosystems that are planning ot make use of the Status List mechanism: +This specification does not mandate specific methods for key resolution and trust management, however the following recommendations are made for specifications, profiles, or ecosystems that are planning to make use of the Status List mechanism: If the Issuer of the Referenced Token is the same entity as the Status Issuer, then the same key that is embedded into the Referenced Token may be used for the Status List Token. In this case the Status List Token may use: + - the same `x5c` value or an `x5t`, `x5t#S256` or `kid` parameter referencing to the same key as used in the Referenced Token for JOSE. - the same `x5chain` value or an `x5t` or `kid` parameter referencing to the same key as used in the Referenced Token for COSE. Alternatively, the Status Issuer may use the same web-based key resolution that is used for the Referenced Token. In this case the Status List Token may use: + - an `x5u`, `jwks`, `jwks_uri` or `kid` parameter referencing to a key using the same web-based resolution as used in the Referenced Token for JOSE. - an `x5u` or `kid` parameter referencing to a key using the same web-based resolution as used in the Referenced Token for COSE. @@ -956,7 +959,7 @@ Alternatively, the Status Issuer may use the same web-based key resolution that │ Status Provider │ └─────────────────┘ ~~~ -If the Issuer of the Referenced Token is a different entity than the Status Issuer, then the keys used for the Status List Token may be cryptographically linked, e.g. by an Certificate Authority through an x.509 PKI. The certificate of the Issuer for the Referenced Token and the Status Issuer should be issued by the same Certificate Authority and the Status Issuer's certificate should utilize [extended key usage](#eku). +If the Issuer of the Referenced Token is a different entity than the Status Issuer, then the keys used for the Status List Token may be cryptographically linked, e.g. by a Certificate Authority through an x.509 PKI. The certificate of the Issuer for the Referenced Token and the Status Issuer should be issued by the same Certificate Authority and the Status Issuer's certificate should utilize [extended key usage](#eku). ~~~ ascii-art ┌───────────────────────┐ @@ -976,11 +979,11 @@ If the Issuer of the Referenced Token is a different entity than the Status Issu └─────────────────┘ ~~~ -# Privacy Considerations +# Privacy Considerations {#privacy-considerations} ## Observability of Issuers {#privacy-issuer} -The main privacy consideration for a Status List, especially in the context of the Issuer-Holder-Verifier model {{SD-JWT.VC}}, is to prevent the Issuer from tracking the usage of the Referenced Token when the status is being checked. If an Issuer offers status information by referencing a specific token, this would enable him to create a profile for the issued token by correlating the date and identity of Relying Parties, that are requesting the status. +The main privacy consideration for a Status List, especially in the context of the Issuer-Holder-Verifier model {{SD-JWT.VC}}, is to prevent the Issuer from tracking the usage of the Referenced Token when the status is being checked. If an Issuer offers status information by referencing a specific token, this would enable the Issuer to create a profile for the issued token by correlating the date and identity of Relying Parties, that are requesting the status. The Status List approaches these privacy implications by integrating the status information of many Referenced Tokens into the same list. Therefore, the Issuer does not learn for which Referenced Token the Relying Party is requesting the Status List. The privacy of the Holder is protected by the anonymity within the set of Referenced Tokens in the Status List, also called herd privacy. This limits the possibilities of tracking by the Issuer. @@ -993,9 +996,14 @@ This behaviour may be mitigated by: - private relay protocols or other mechanisms hiding the original sender like {{RFC9458}}. - using trusted Third Party Hosting, see [](#third-party-hosting). -## Malicious Issuers +## Issuer Tracking of Reference Tokens + +An Issuer could maliciously or accidentally bypass the privacy benefits of the herd privacy by either: -A malicious Issuer could bypass the privacy benefits of the herd privacy by generating a unique Status List for every Referenced Token. By these means, he could maintain a mapping between Referenced Tokens and Status Lists and thus track the usage of Referenced Tokens by utilizing this mapping for the incoming requests. This malicious behaviour could be detected by Relying Parties that request large amounts of Referenced Tokens by comparing the number of different Status Lists and their sizes. +- Generating a unique Status List for every Referenced Token. By these means, the Issuer could maintain a mapping between Referenced Tokens and Status Lists and thus track the usage of Referenced Tokens by utilizing this mapping for the incoming requests. +- Encoding a unique URI in each Reference Token which points to the underlying Status List. This may involve using URI components such as query parameters, unique path segments, or fragments to make the URI unique. + +This malicious behavior can be detected by Relying Parties that request large amounts of Referenced Tokens by comparing the number of different Status Lists and their sizes with the volume of Reference Tokens being verified. ## Observability of Relying Parties {#privacy-relying-party} @@ -1003,19 +1011,19 @@ Once the Relying Party receives the Referenced Token, this enables them to reque This behaviour could be mitigated by: -- regular re-issuance of the Referenced Token, see [](#implementation-lifecycle). +- regular re-issuance of the Referenced Token, see [](#implementation-linkability). ## Observability of Outsiders {#privacy-outsider} -Outside actors may analyse the publicly available Status Lists to get information on the internal processes of the Issuer and his related business. This data may allow inferences on the total number of issued Reference Tokens and the revocation rate. Additionally, actors may regularly fetch this data or use the historic data functionality to learn how these numbers change over time. +Outside actors may analyse the publicly available Status Lists to get information on the internal processes of the Issuer and its related business, e.g. number of customers or clients. This data may allow inferences on the total number of issued Reference Tokens and the revocation rate. Additionally, actors may regularly fetch this data or use the historic data functionality to learn how these numbers change over time. This behaviour could be mitigated by: -- disable the historical data feature [](#historical-resolution) -- disable the Status List Aggregation [](#aggregation) -- choose non-sequential, pseudo-random or random indices -- use decoy entries to obfuscate the real number of Referenced Tokens within a Status List -- choose to deploy and utilize multiple Status Lists simultaneously +- disabling the historical data feature [](#historical-resolution) +- disabling the Status List Aggregation [](#aggregation) +- choosing non-sequential, pseudo-random or random indices +- using decoy entries to obfuscate the real number of Referenced Tokens within a Status List +- choosing to deploy and utilize multiple Status Lists simultaneously ## Unlinkability @@ -1025,7 +1033,7 @@ The tuple of uri and index inside the Referenced Token are unique and therefore Two or more colluding Relying Parties may link two transactions involving the same Referenced Token by comparing the status claims of received Referenced Tokens and therefore determine that they have interacted with the same Holder. -To avoid privacy risks for colluding Relying Parties, it is RECOMMENDED that Issuers provide the ability to issue batches of one-time-use Referenced Tokens, enabling Holders to use in a single interaction with a Relying Party before discarding. See [](#implementation-lifecycle) to avoid further correlatable information by the values of `uri` and `index`, Status Issuers are RECOMMENDED to: +To avoid privacy risks for colluding Relying Parties, it is RECOMMENDED that Issuers provide the ability to issue batches of one-time-use Referenced Tokens, enabling Holders to use in a single interaction with a Relying Party before discarding. See [](#implementation-linkability) to avoid further correlatable information by the values of `uri` and `index`, Status Issuers are RECOMMENDED to: - choose non-sequential, pseudo-random or random indices - use decoy entries to obfuscate the real number of Referenced Tokens within a Status List @@ -1049,9 +1057,9 @@ There are strong privacy concerns that have to be carefully taken into considera ## Status Types {#privacy-status-types} -As previously explained, there is the potential risk of observability by Relying Parties (see [](#privacy-relying-party)) and Outsiders (see [](#privacy-outsider)). That means that any Status Type that transports special information about a Token can leak information to other parties. This documents defines one additional Status Type with "SUSPENDED" that conveys such additional information. Depending on the use-case, suspended could for example provide information that an authorization in the Token is suspended, but the token itself is still valid. +As previously explained, there is the potential risk of observability by Relying Parties (see [](#privacy-relying-party)) and Outsiders (see [](#privacy-outsider)). That means that any Status Type that transports special information about a Referenced Token can leak information to other parties. This document defines one additional Status Type with "SUSPENDED" that conveys such additional information. -A concrete example would be a driver's license, where the digital driver's license might still be useful to prove other information about its holder, but suspended could signal that it should not be considered valid in the scope of being allowed to drive a car. This case could be solved by either introducing a special status type, or by revoking the Token and re-issuing with changed attributes. For such a case, the status type suspended might be dangerous as it would leak the information of a suspended driver's license even if the driver's license is used as a mean of identification and not in the context of driving a car. This could also allow for the unwanted collection of statistical data on the status of driver's licenses. +A concrete example for "SUSPENDED" would be a driver's license, where the digital driver's license might still be useful to prove other information about its holder, but suspended could signal that it should not be considered valid in the scope of being allowed to drive a car. This case could be solved by either introducing a special status type, or by revoking the Referenced Token and re-issuing with changed attributes. For such a case, the status type suspended might be dangerous as it would leak the information of a suspended driver's license even if the driver's license is used as a mean of identification and not in the context of driving a car. This could also allow for the unwanted collection of statistical data on the status of driver's licenses. Ecosystems that want to use other Status Types than "VALID" and "INVALID" should consider the possible leakage of data and profiling possibilities before doing so and evaluate if revocation and re-issuance might a better fit for their use-case. @@ -1061,19 +1069,25 @@ Ecosystems that want to use other Status Types than "VALID" and "INVALID" should The lifetime of a Status List Token depends on the lifetime of its Referenced Tokens. Once all Referenced Tokens are expired, the Issuer may stop serving the Status List Token. +## Linkability Mitigation {#implementation-linkability} + Referenced Tokens may be regularly re-issued to mitigate the linkability of presentations to Relying Parties. In this case, every re-issued Referenced Token MUST have a fresh Status List entry in order to prevent this from becoming a possible source of correlation. -Referenced Tokens may also be issued in batches and be presented by Holders in a one-time-use policy to avoid linkability. In this case, every Referenced Token MUST have a dedicated Status List entry and MAY be spread across multiple Status Lists. Revoking batch-issued Referenced Tokens might reveal this correlation later on. +Referenced Tokens may also be issued in batches and be presented by Holders in a one-time-use policy to avoid linkability. In this case, every Referenced Token MUST have a dedicated Status List entry and MAY be spread across multiple Status List Tokens. Revoking batch-issued Referenced Tokens might reveal this correlation later on. + +Beware, that this mechanism solves linkability issues between Relying Parties, but does not prevent traceability by Issuers. ## Default Values and Double Allocation -Implementations producing Status Lists are RECOMMENDED to initialize the Status List byte array with a default value and provide this as an initialization parameter to the Issuer. The Issuer is RECOMMENDED to use a default value that represents the most common value for its Referenced Tokens to avoid an update during issuance. +The Status Issuer is RECOMMENDED to initialize the Status List byte array with a default value provided as +an initialization parameter by the Issuer of the Referenced Token. The Issuer is RECOMMENDED to use a default value that represents the most common value for its Referenced Tokens to avoid an update during issuance (usually 0x00, VALID). This preserves the benefits from compression and effectively hides the number of managed Referenced Tokens since an unused index value can not be distinguished from a valid Referenced Token. -Implementations producing Status Lists are RECOMMENDED to prevent double allocation, i.e. re-using the same `uri` and `index` for multiple Referenced Tokens. The Issuer MUST prevent any unintended double allocation by using the Status List. +The Status Issuer is RECOMMENDED to prevent double allocation, i.e. re-using the same `uri` and `index` for multiple Referenced Tokens (since `uri` and `index` form a unique identifier that might be used for tracking, see [](#privacy-considerations) for more details). The Status Issuer MUST prevent any unintended double allocation. ## Status List Size The storage and transmission size of the Status Issuer's Status List Tokens depends on: + - the size of the Status List, i.e. the number of Referenced Tokens - the revocation rate and distribution of the Status List data (due to compression, revocation rates close to 0% or 100% create lowest sizes while revocation rates closer to 50% and random distribution create highest sizes) - the lifetime of Referenced Tokens (shorter lifetimes allows for earlier retirement of Status List Tokens) @@ -1110,7 +1124,7 @@ When fetching a Status List Token, Relying Parties must carefully evaluate how l - After initial fetching, the Relying Party checks for updates at time of `iat` + `ttl`. This method ensures the most up-to-date information for critical use cases. The Relying Party should account a minimal offset due to the signing and distribution process of the Status Issuer. - If no `ttl` is given, then Relying Party SHOULD check for updates latest after time of `exp`. -Ultimately, its the Relying Parties decision how often to check for updates, ecosystems may define there own guidelines and policies for updating the Status List information. +Ultimately, it's the Relying Parties decision how often to check for updates, ecosystems may define their own guidelines and policies for updating the Status List information. The following diagram illustrates the relationship between these claims and how they are designed to influence caching: @@ -1136,10 +1150,10 @@ The following diagram illustrates the relationship between these claims and how ## Relying Parties avoiding correlatable Information -If the Relying Party does not require the Referenced Token and the Status List Token after the presentation, e.g. for subsequent status checks or audit trail, it is RECOMMENDED to delete correlatable information, in particular: +If the Relying Party does not require the Referenced Token or the Status List Token, e.g. for subsequent status checks or audit trail, it is RECOMMENDED to delete correlatable information, in particular: -- the `status` claim in the Referenced Token -- the Status List Token itself +- the `status` claim in the Referenced Token (after the presentation) +- the Status List Token itself (after expiration or update) The Relying Party should instead only keep the relevant payload from the Referenced Token. @@ -1163,14 +1177,14 @@ IANA "JSON Web Token Claims" registry {{IANA.JWT}} established by {{RFC7519}}. ### Registry Contents * Claim Name: `status` -* Claim Description: Reference to a status or validity mechanism containing up-to-date status information on the JWT. +* Claim Description: A JSON object containing a reference to a status mechanism from the JWT Status Mechanisms Registry. * Change Controller: IETF * Specification Document(s): [](#status-claim) of this specification
* Claim Name: `status_list` -* Claim Description: A status list containing up-to-date status information on multiple tokens. +* Claim Description: A JSON object containing up-to-date status information on multiple tokens using the Token Status List mechanism. * Change Controller: IETF * Specification Document(s): [](#status-list-token-jwt) of this specification @@ -1219,7 +1233,7 @@ Specification Document(s): ### Initial Registry Contents * Status Mechanism Value: `status_list` -* Status Mechanism Description: A status list containing up-to-date status information on multiple tokens. +* Status Mechanism Description: A Token Status List containing up-to-date status information on multiple tokens. * Change Controller: IETF * Specification Document(s): [](#referenced-token-jose) of this specification @@ -1233,7 +1247,7 @@ IANA "CBOR Web Token (CWT) Claims" registry {{IANA.CWT}} established by {{RFC839
* Claim Name: `status` -* Claim Description: Reference to a status or validity mechanism containing up-to-date status information on the CWT. +* Claim Description: A CBOR structure containing a reference to a status mechanism from the CWT Status Mechanisms Registry. * JWT Claim Name: `status` * Claim Key: TBD (requested assignment 65535) * Claim Value Type: map @@ -1243,7 +1257,7 @@ IANA "CBOR Web Token (CWT) Claims" registry {{IANA.CWT}} established by {{RFC839
* Claim Name: `status_list` -* Claim Description: A status list containing up-to-date status information on multiple tokens. +* Claim Description: A CBOR structure containing up-to-date status information on multiple tokens using the Token Status List mechanism. * JWT Claim Name: `status_list` * Claim Key: TBD (requested assignment 65533) * Claim Value Type: map @@ -1297,7 +1311,7 @@ Specification Document(s): ### Initial Registry Contents * Status Mechanism Value: `status_list` -* Status Mechanism Description: A status list containing up-to-date status information on multiple tokens. +* Status Mechanism Description: A Token Status List containing up-to-date status information on multiple tokens. * Change Controller: IETF * Specification Document(s): [](#referenced-token-cose) of this specification @@ -1358,7 +1372,7 @@ Specification Document(s):
* Status Type Name: SUSPENDED -* Status Type Description: The status of the Referenced Token is temporarily invalid, hanging or debarred from privilege. This state is reversible. +* Status Type Description: The status of the Referenced Token is temporarily invalid, hanging or debarred from privilege. This state is usually temporary. * Status Type value: `0x02` * Change Controller: IETF * Specification Document(s): [](#status-types) of this specification @@ -1457,7 +1471,10 @@ IANA is also requested to register the following OID "1.3.6.1.5.5.7.3.TBD" in th {:numbered="false"} We would like to thank +Andrii Deinega, Brian Campbell, +Dan Moore, +Denis Pinkas, Filip Skokan, Francesco Marino, Giuseppe De Marco, @@ -1891,6 +1908,29 @@ CBOR encoding: # Document History {:numbered="false"} +-13 + +* add a note that cwt is encoded in raw/binary. +* added further privacy consideration around issuer tracking using unique URIs + +-12 + +* Allow for extended key usage OID to be used for other status mechanisms +* add Paul's affiliation +* add feedback from Dan Moore +* change JSON Status List structure to only contain JSON object +* further nitpicks +* clarifying status and status_list IANA descriptions for JWT/CWT +* clarifying description texts for status and status_list in CBOR +* splitting Linkability Mitigation from Token Lifecycle section in Implementation Consideration +* relax the accept header from must to should + +-11 + +* incorporate feedback from shepherd review +* some nitpicks +* even more nitpicks + -10 * improve caching guidelines and move them to implementaiton considerations