From 7e942712cce87dcc87f0505f6d39a0310c02f2c0 Mon Sep 17 00:00:00 2001 From: Paul Bastian Date: Mon, 14 Aug 2023 09:07:14 +0200 Subject: [PATCH 01/12] restructure document --- draft-looker-oauth-jwt-cwt-status-list.md | 210 +++++++++++----------- 1 file changed, 106 insertions(+), 104 deletions(-) diff --git a/draft-looker-oauth-jwt-cwt-status-list.md b/draft-looker-oauth-jwt-cwt-status-list.md index d312b2f..6f8947a 100644 --- a/draft-looker-oauth-jwt-cwt-status-list.md +++ b/draft-looker-oauth-jwt-cwt-status-list.md @@ -39,7 +39,7 @@ The status list data structures themselves are also represented as JWTs or CWTs. 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. +This document defines Status List representations in JSON or CBOR formats and a Status List Token representation in JWT or 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. @@ -68,7 +68,7 @@ This specification seeks to find a balance between scalability, security, and pr # Terminology Status List: -: A bit array that lists the statuses of many Referenced Tokens. +: An object in JSON or CBOR representation containing 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. @@ -76,59 +76,11 @@ Status List Token: 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. -# JSON Web Token Representation +# Status List -## Status List JWT Format and Processing Requirements {#jwt-status-list-format-and-processing} +## Status List Encoding {#status-list-base-encoding} -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. - -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 [](#jwt-status-list-claim-format). - -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}}. - -~~~ ascii-art - -{ - "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" - } -} -~~~ - -### Status List Claim Format {#jwt-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 [](#jwt-status-list-claim-encoding). - -### Status List Encoding {#jwt-status-list-claim-encoding} +The following rules apply to the Status List: 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. @@ -136,62 +88,15 @@ Each status of a Referenced Token MUST be represented with a bit size of 1,2,4, 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}}. +## Status List in JSON Format and Processing Requirements {#jwt-status-list-claim-format} -## Referenced Token Format and Processing Requirements {#jwt-referenced-token} - -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. - -2. The JWT MUST contain an "status" (status) claim conforming to the rules outlined in [](#jwt-referenced-token-status) - -The following example is the decoded header and payload of a JWT meeting the processing rules as defined above. - -~~~ ascii-art - -{ - "alg": "ES256", - "kid": "11" -} -. -{ - "iss": "https://example.com", - "status": { - "idx": 0, - "uri": "https://example.com/statuslists/1" - } -} -~~~ - -### Status Claim Format {#jwt-referenced-token-status} - -The following rules apply to validating the "status" (status) claim +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 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}}. - -# Status Types {#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. - -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. - -## 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. +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. -# Example JWT Status Lists +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 as the base64url-encoded result of the algorithm described in [](#status-list-base-encoding). ## Example Status List with 1-Bit Status Values @@ -307,6 +212,103 @@ After compression and base64url encoding, the generated Status List is: } ~~~ +# Status List Token + +## Status List Token in JWT Format and Processing Requirements {#jwt-status-list-format-and-processing} + +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. + +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 [](#jwt-status-list-claim-format). + +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}}. + +~~~ ascii-art + +{ + "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" + } +} +~~~ + +# Referenced Token + +## Referenced Token in JWT Format and Processing Requirements {#jwt-referenced-token} + +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. + +2. The JWT MUST contain an "status" (status) claim conforming to the rules outlined in [](#jwt-referenced-token-status) + +The following example is the decoded header and payload of a JWT meeting the processing rules as defined above. + +~~~ ascii-art + +{ + "alg": "ES256", + "kid": "11" +} +. +{ + "iss": "https://example.com", + "status": { + "idx": 0, + "uri": "https://example.com/statuslists/1" + } +} +~~~ + +### Status Claim Format {#jwt-referenced-token-status} + +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}}. + +# Status Types {#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. + +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. + +## 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. + # CWT Representations TBD Define parallel CWT representations for Status Lists and Referenced Tokens. From 43030d8358965d03d2ab8056a69c631b41899da3 Mon Sep 17 00:00:00 2001 From: Paul Bastian Date: Mon, 14 Aug 2023 15:16:39 +0200 Subject: [PATCH 02/12] split referenced token section, renaming and add protocol section --- draft-looker-oauth-jwt-cwt-status-list.md | 50 +++++++++++++++++++---- 1 file changed, 42 insertions(+), 8 deletions(-) diff --git a/draft-looker-oauth-jwt-cwt-status-list.md b/draft-looker-oauth-jwt-cwt-status-list.md index e3235f8..2c49a56 100644 --- a/draft-looker-oauth-jwt-cwt-status-list.md +++ b/draft-looker-oauth-jwt-cwt-status-list.md @@ -61,6 +61,10 @@ Revocation mechanisms are an essential part for most identity ecosystems. In the 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. +## Design Considerations + +TBD + # Conventions and Definitions {::boilerplate bcp14-tagged} @@ -216,15 +220,34 @@ The following rules apply to validating a JWT-based Status List Token. Applicati {::include ./examples/status_list_jwt} ~~~~~~~~~~ -# Referenced Token +# Status Reference + +## Status Reference in JSON Format{#status-reference-json} + +The following rules apply to validating the "status" (status) claim that references a Status List: + +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. -## Referenced Token in JWT Format and Processing Requirements {#jwt-referenced-token} +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}}. + +~~~ ascii-art +{ + "idx": 0, + "uri": "https://example.com/statuslists/1" +} +~~~ + +# Status Referencing Token + +## Status Referencing Token in JWT Format and Processing Requirements {#status-referencing-token-jwt} 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. -2. The JWT MUST contain an "status" (status) claim conforming to the rules outlined in [](#jwt-referenced-token-status) +2. The JWT MUST contain an "status" (status) claim conforming to the rules outlined in [](#status-reference-json) The following example is the decoded header and payload of a JWT meeting the processing rules as defined above. @@ -244,15 +267,26 @@ The following example is the decoded header and payload of a JWT meeting the pro } ~~~ -### Status Claim Format {#jwt-referenced-token-status} +# Verification and Processing -The following rules apply to validating the "status" (status) claim +## Status List Request -1. The claim value MUST be a valid JSON object. +To obtain the Status List or Status List Token, the Verifier MUST send a HTTP GET request to the Status List Endpoint. Communication with the Status List Endpoint MUST utilize TLS. -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. +The Verifier SHOULD send the following Accept-Header to indicate the requested response type: +- "application/statuslist+json" for Status Lists +- "application/statuslist+jwt" for Status List JWTs -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}}. +If the Verifier does not send an Accept Header, the reponse type is assumed to be known implicit or out-of-band. + +## Status List Response + +In the successful response, the Status List Provider MUST use the following content-type: +- "application/statuslist+json" for Status Lists +- "application/statuslist+jwt" for Status List JWTs + + +## Validation Rules # Status Types {#status-types} From d3a7923adccd38d681f3e173642ba1ae2e0e811e Mon Sep 17 00:00:00 2001 From: Paul Bastian Date: Mon, 14 Aug 2023 15:23:28 +0200 Subject: [PATCH 03/12] add caching section to HTTP --- draft-looker-oauth-jwt-cwt-status-list.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/draft-looker-oauth-jwt-cwt-status-list.md b/draft-looker-oauth-jwt-cwt-status-list.md index 2c49a56..1cd5b21 100644 --- a/draft-looker-oauth-jwt-cwt-status-list.md +++ b/draft-looker-oauth-jwt-cwt-status-list.md @@ -285,6 +285,9 @@ In the successful response, the Status List Provider MUST use the following cont - "application/statuslist+json" for Status Lists - "application/statuslist+jwt" for Status List JWTs +## Caching + +TDB use HTTP chaching mechanisms ## Validation Rules From 62c506f2fcce93e7c7bcc1090b7484a42e3fa018 Mon Sep 17 00:00:00 2001 From: Paul Bastian Date: Mon, 14 Aug 2023 17:15:35 +0200 Subject: [PATCH 04/12] fix refs --- draft-looker-oauth-jwt-cwt-status-list.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/draft-looker-oauth-jwt-cwt-status-list.md b/draft-looker-oauth-jwt-cwt-status-list.md index 1cd5b21..dd69862 100644 --- a/draft-looker-oauth-jwt-cwt-status-list.md +++ b/draft-looker-oauth-jwt-cwt-status-list.md @@ -222,7 +222,7 @@ The following rules apply to validating a JWT-based Status List Token. Applicati # Status Reference -## Status Reference in JSON Format{#status-reference-json} +## Status Reference in JSON Format {#status-reference-json} The following rules apply to validating the "status" (status) claim that references a Status List: From 73c05226a942377ec654de3c57c131b4b1d1d0fc Mon Sep 17 00:00:00 2001 From: Christian Bormann <8774236+c2bo@users.noreply.github.com> Date: Mon, 14 Aug 2023 22:36:34 +0200 Subject: [PATCH 05/12] initial text on endpoint; change encoding example to include the required members --- draft-looker-oauth-jwt-cwt-status-list.md | 13 +++++++++++-- src/main.py | 14 ++++++++------ src/status_list.py | 10 ++++++++++ src/util.py | 5 +++++ 4 files changed, 34 insertions(+), 8 deletions(-) diff --git a/draft-looker-oauth-jwt-cwt-status-list.md b/draft-looker-oauth-jwt-cwt-status-list.md index dd69862..03ecd47 100644 --- a/draft-looker-oauth-jwt-cwt-status-list.md +++ b/draft-looker-oauth-jwt-cwt-status-list.md @@ -26,6 +26,9 @@ normative: RFC3986: RFC3986 RFC1952: RFC1952 RFC7515: RFC7515 + RFC6125: RFC6125 + RFC9111: RFC9111 + RFC9110: RFC9110 informative: --- abstract @@ -271,7 +274,7 @@ The following example is the decoded header and payload of a JWT meeting the pro ## Status List Request -To obtain the Status List or Status List Token, the Verifier MUST send a HTTP GET request to the Status List Endpoint. Communication with the Status List Endpoint MUST utilize TLS. +To obtain the Status List or Status List Token, the Verifier MUST send a HTTP GET request to the Status List Endpoint. Communication with the Status List Endpoint MUST utilize TLS. Which version(s) should be implemented will vary over time. A TLS server certificate check MUST be performed as defined in Section 5 and 6 of {{RFC6125}}. The Verifier SHOULD send the following Accept-Header to indicate the requested response type: - "application/statuslist+json" for Status Lists @@ -285,9 +288,15 @@ In the successful response, the Status List Provider MUST use the following cont - "application/statuslist+json" for Status Lists - "application/statuslist+jwt" for Status List JWTs +In the case of "application/statuslist+json", the response MUST be of type JSON and follow the rules of [](#jwt-status-list-claim-format). + +In the case of "application/statuslist+jwt", the response MUST be of type JWT and follow the rules of [](#jwt-status-list-format-and-processing). + +The response SHOULD use gzip Contente-Encoding as defined in {{RFC9110}}. + ## Caching -TDB use HTTP chaching mechanisms +If caching is required (e.g., to enable the use of alternative mechanisms for hosting, like Content Delivery Networks), the control of the caching mechanism SHOULD be implemented using the standard HTTP Cache-Control as defined in {{RFC9111}}. ## Validation Rules diff --git a/src/main.py b/src/main.py index a403733..a8174ef 100644 --- a/src/main.py +++ b/src/main.py @@ -29,9 +29,11 @@ def statusListEncoding1Bit(): status_list.set(13, 1) status_list.set(14, 0) status_list.set(15, 1) - encoded = status_list.encode(mtime=gzip_time) - text = 'byte_array = [{}, {}] \nencoded = "{}"'.format( - hex(status_list.list[0]), hex(status_list.list[1]), encoded + encoded = status_list.encodeObject(mtime=gzip_time) + text = "byte_array = [{}, {}] \nencoded:\n{}".format( + hex(status_list.list[0]), + hex(status_list.list[1]), + util.printObject(encoded) ) util.outputFile(folder + "status_list_encoding", text) @@ -55,12 +57,12 @@ def exampleStatusList() -> StatusList: def statusListEncoding2Bit(): status_list = exampleStatusList() - encoded = status_list.encode(mtime=gzip_time) - text = 'byte_array = [{}, {}, {}] \nencoded = "{}"'.format( + encoded = status_list.encodeObject(mtime=gzip_time) + text = "byte_array = [{}, {}, {}] \nencoded:\n{}".format( hex(status_list.list[0]), hex(status_list.list[1]), hex(status_list.list[2]), - encoded, + util.printObject(encoded), ) util.outputFile(folder + "status_list_encoding2", text) diff --git a/src/status_list.py b/src/status_list.py index e7a9fba..f024015 100644 --- a/src/status_list.py +++ b/src/status_list.py @@ -1,4 +1,5 @@ from base64 import urlsafe_b64decode, urlsafe_b64encode +from typing import Dict import gzip @@ -44,6 +45,15 @@ def get(self, pos: int) -> int: return ( self.list[floored] & (((1 << self.bits) - 1) << shift) ) >> shift + + def encodeObject(self, mtime=None) -> Dict: + claims = {} + encoded_list = self.encode(mtime=mtime) + claims["status_list"] = { + "bits": self.bits, + "lst": encoded_list, + } + return claims def __str__(self): val = "" diff --git a/src/util.py b/src/util.py index 7178066..f9c3234 100644 --- a/src/util.py +++ b/src/util.py @@ -1,5 +1,6 @@ from jwcrypto import jwk, jwt from textwrap import fill +from typing import Dict import json example = { @@ -26,6 +27,10 @@ def formatToken(input: str, key: jwk.JWK) -> str: {claims}""" +def printObject(input: Dict) -> str: + return printJson(json.dumps(input)) + + def printJson(input: str) -> str: text = json.dumps( json.loads(input), sort_keys=True, indent=2, ensure_ascii=False From 17339912b2f2d45505eff20f4d5b71ad794eab86 Mon Sep 17 00:00:00 2001 From: Paul Bastian Date: Tue, 15 Aug 2023 11:33:43 +0200 Subject: [PATCH 06/12] draft for drawing --- draft-looker-oauth-jwt-cwt-status-list.md | 24 +++++++++++++++-------- 1 file changed, 16 insertions(+), 8 deletions(-) diff --git a/draft-looker-oauth-jwt-cwt-status-list.md b/draft-looker-oauth-jwt-cwt-status-list.md index 03ecd47..74e547b 100644 --- a/draft-looker-oauth-jwt-cwt-status-list.md +++ b/draft-looker-oauth-jwt-cwt-status-list.md @@ -48,14 +48,22 @@ The following diagram depicts the basic conceptual relationship. ~~~ ascii-art -+------------------+ +-------------------+ -| | References | | -| |------------------->| | -| Referenced Token | | Status List Token | -| (JWT or CWT) | | (JWT or CWT) | -| | Describes Status | | -| |<-------------------| | -+------------------+ +-------------------+ ++-------------------+ +------------------+ +| | describes status | | +| Status List +------------------> Status Reference | +| (JSON or CBOR) <------------------+ (JSON or CBOR) | +| | references | | ++-------+-----------+ +--------+---------+ + | | + |embedded | embedded + v v ++-------------------+ +--------------------------+ +| | | | +| Status List Token | | Status Referencing Token | +| (JWT or CWT) | | (JWT or CWT) | +| | | | ++-------------------+ +--------------------------+ + ~~~ ## Rationale From ce34aa17a24fa6625bc191a00ec3814516e79f7a Mon Sep 17 00:00:00 2001 From: Christian Bormann <8774236+c2bo@users.noreply.github.com> Date: Wed, 16 Aug 2023 08:29:26 +0200 Subject: [PATCH 07/12] fix lists in markdown; remove outer object of list encoding example --- draft-looker-oauth-jwt-cwt-status-list.md | 9 ++++++--- src/status_list.py | 7 +++---- 2 files changed, 9 insertions(+), 7 deletions(-) diff --git a/draft-looker-oauth-jwt-cwt-status-list.md b/draft-looker-oauth-jwt-cwt-status-list.md index 74e547b..da66977 100644 --- a/draft-looker-oauth-jwt-cwt-status-list.md +++ b/draft-looker-oauth-jwt-cwt-status-list.md @@ -285,6 +285,7 @@ The following example is the decoded header and payload of a JWT meeting the pro To obtain the Status List or Status List Token, the Verifier MUST send a HTTP GET request to the Status List Endpoint. Communication with the Status List Endpoint MUST utilize TLS. Which version(s) should be implemented will vary over time. A TLS server certificate check MUST be performed as defined in Section 5 and 6 of {{RFC6125}}. The Verifier SHOULD send the following Accept-Header to indicate the requested response type: + - "application/statuslist+json" for Status Lists - "application/statuslist+jwt" for Status List JWTs @@ -293,6 +294,7 @@ If the Verifier does not send an Accept Header, the reponse type is assumed to b ## Status List Response In the successful response, the Status List Provider MUST use the following content-type: + - "application/statuslist+json" for Status Lists - "application/statuslist+jwt" for Status List JWTs @@ -319,9 +321,10 @@ Additional values may defined for particular use cases. 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. + +- 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. diff --git a/src/status_list.py b/src/status_list.py index f024015..3531370 100644 --- a/src/status_list.py +++ b/src/status_list.py @@ -45,15 +45,14 @@ def get(self, pos: int) -> int: return ( self.list[floored] & (((1 << self.bits) - 1) << shift) ) >> shift - + def encodeObject(self, mtime=None) -> Dict: - claims = {} encoded_list = self.encode(mtime=mtime) - claims["status_list"] = { + object = { "bits": self.bits, "lst": encoded_list, } - return claims + return object def __str__(self): val = "" From eda20a1028d0595318d652d68ae9ad792718a60a Mon Sep 17 00:00:00 2001 From: Paul Bastian Date: Wed, 16 Aug 2023 17:24:46 +0200 Subject: [PATCH 08/12] some more reording --- draft-looker-oauth-jwt-cwt-status-list.md | 80 +++++++++++++---------- 1 file changed, 46 insertions(+), 34 deletions(-) diff --git a/draft-looker-oauth-jwt-cwt-status-list.md b/draft-looker-oauth-jwt-cwt-status-list.md index da66977..e5df3d8 100644 --- a/draft-looker-oauth-jwt-cwt-status-list.md +++ b/draft-looker-oauth-jwt-cwt-status-list.md @@ -48,21 +48,21 @@ The following diagram depicts the basic conceptual relationship. ~~~ ascii-art -+-------------------+ +------------------+ -| | describes status | | -| Status List +------------------> Status Reference | -| (JSON or CBOR) <------------------+ (JSON or CBOR) | -| | references | | -+-------+-----------+ +--------+---------+ - | | - |embedded | embedded - v v -+-------------------+ +--------------------------+ -| | | | -| Status List Token | | Status Referencing Token | -| (JWT or CWT) | | (JWT or CWT) | -| | | | -+-------------------+ +--------------------------+ ++-------------------+ +------------------------+ +| | describes status | | +| Status List +------------------> Status Reference Token | +| (JSON or CBOR) <------------------+ (JWT or CWT) | +| | references | | ++-------+-----------+ +--------+---------------+ + | + |embedded + v ++-------------------+ +| | +| Status List Token | +| (JWT or CWT) | +| | ++-------------------+ ~~~ @@ -103,17 +103,9 @@ Each status of a Referenced Token MUST be represented with a bit size of 1,2,4, 2. The complete byte array is compressed using gZIP {{RFC1952}}. -## Status List in JSON Format and Processing Requirements {#jwt-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. +3. The result of the gZIP compression is then base64url-encoded, as defined in Section 2 of {{RFC7515}}. -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 as the base64url-encoded result of the algorithm described in [](#status-list-base-encoding). - -## Example Status List with 1-Bit Status Values +### 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. @@ -156,13 +148,15 @@ index 7 6 5 4 3 2 1 0 15 ... 10 9 8 23 Resulting in the byte array and compressed/base64url encoded status list: -~~~~~~~~~~ -{::include ./examples/status_list_encoding} -~~~~~~~~~~ +~~~ ascii-art -## Example Status List with 2-Bit Status Values +H4sIAOpbjGQC_9u5GABc9QE7AgAAAA + +~~~ -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. +### Example Status List with 2-Bit Status Values + +In this example, 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. @@ -201,11 +195,31 @@ index 3 2 1 0 7 6 5 4 11 10 9 8 Resulting in the byte array and compressed/base64url encoded status list: +~~~ ascii-art + +H4sIAOpbjGQC_zvp8hMAZLRLMQMAAAA + +~~~ + +## Status List in JSON Format and Processing Requirements {#jwt-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 as the base64url-encoded result of the algorithm described in [](#status-list-base-encoding). + +The examples from [](#status-list-base-encoding) represented in a Status List JSON format result in: + ~~~~~~~~~~ -{::include ./examples/status_list_encoding2} +{::include ./examples/status_list_encoding} ~~~~~~~~~~ -# Status List Token +~~~~~~~~~~ +{::include ./examples/status_list_encoding2} +~~~~~~~~~~ ## Status List Token in JWT Format and Processing Requirements {#jwt-status-list-format-and-processing} @@ -250,8 +264,6 @@ The following rules apply to validating the "status" (status) claim that referen } ~~~ -# Status Referencing Token - ## Status Referencing Token in JWT Format and Processing Requirements {#status-referencing-token-jwt} 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. From b925fecfe00e7651fc4d354f62c76ded213bdab7 Mon Sep 17 00:00:00 2001 From: Paul Bastian Date: Wed, 16 Aug 2023 17:26:53 +0200 Subject: [PATCH 09/12] fix lint --- draft-looker-oauth-jwt-cwt-status-list.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/draft-looker-oauth-jwt-cwt-status-list.md b/draft-looker-oauth-jwt-cwt-status-list.md index e5df3d8..71fb035 100644 --- a/draft-looker-oauth-jwt-cwt-status-list.md +++ b/draft-looker-oauth-jwt-cwt-status-list.md @@ -54,15 +54,15 @@ The following diagram depicts the basic conceptual relationship. | (JSON or CBOR) <------------------+ (JWT or CWT) | | | references | | +-------+-----------+ +--------+---------------+ - | - |embedded - v -+-------------------+ -| | -| Status List Token | -| (JWT or CWT) | -| | -+-------------------+ + | + |embedded + v ++-------------------+ +| | +| Status List Token | +| (JWT or CWT) | +| | ++-------------------+ ~~~ From bb0cb8ef386fb8f48b56b168d85ed9ad48b5dade Mon Sep 17 00:00:00 2001 From: Paul Bastian Date: Fri, 20 Oct 2023 10:55:45 +0200 Subject: [PATCH 10/12] Update draft-looker-oauth-jwt-cwt-status-list.md Co-authored-by: Brian Campbell <71398439+bc-pi@users.noreply.github.com> --- draft-looker-oauth-jwt-cwt-status-list.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/draft-looker-oauth-jwt-cwt-status-list.md b/draft-looker-oauth-jwt-cwt-status-list.md index 71fb035..6fa37ff 100644 --- a/draft-looker-oauth-jwt-cwt-status-list.md +++ b/draft-looker-oauth-jwt-cwt-status-list.md @@ -50,7 +50,7 @@ The following diagram depicts the basic conceptual relationship. +-------------------+ +------------------------+ | | describes status | | -| Status List +------------------> Status Reference Token | +| Status List +------------------> Referenced Token | | (JSON or CBOR) <------------------+ (JWT or CWT) | | | references | | +-------+-----------+ +--------+---------------+ From 6fbe5dd70f7448ab2c798061bdabf0a9f2ead1ca Mon Sep 17 00:00:00 2001 From: Paul Bastian Date: Fri, 20 Oct 2023 10:56:37 +0200 Subject: [PATCH 11/12] Update draft-looker-oauth-jwt-cwt-status-list.md --- draft-looker-oauth-jwt-cwt-status-list.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/draft-looker-oauth-jwt-cwt-status-list.md b/draft-looker-oauth-jwt-cwt-status-list.md index 6fa37ff..6af3bda 100644 --- a/draft-looker-oauth-jwt-cwt-status-list.md +++ b/draft-looker-oauth-jwt-cwt-status-list.md @@ -50,7 +50,7 @@ The following diagram depicts the basic conceptual relationship. +-------------------+ +------------------------+ | | describes status | | -| Status List +------------------> Referenced Token | +| Status List +------------------>| Referenced Token | | (JSON or CBOR) <------------------+ (JWT or CWT) | | | references | | +-------+-----------+ +--------+---------------+ From 387c6ee9ca905fc7565f031f661db4b5fcdc958c Mon Sep 17 00:00:00 2001 From: Paul Bastian Date: Fri, 20 Oct 2023 10:56:54 +0200 Subject: [PATCH 12/12] Update draft-looker-oauth-jwt-cwt-status-list.md --- draft-looker-oauth-jwt-cwt-status-list.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/draft-looker-oauth-jwt-cwt-status-list.md b/draft-looker-oauth-jwt-cwt-status-list.md index 6af3bda..7fa8e8b 100644 --- a/draft-looker-oauth-jwt-cwt-status-list.md +++ b/draft-looker-oauth-jwt-cwt-status-list.md @@ -50,7 +50,7 @@ The following diagram depicts the basic conceptual relationship. +-------------------+ +------------------------+ | | describes status | | -| Status List +------------------>| Referenced Token | +| Status List +----------------->| Referenced Token | | (JSON or CBOR) <------------------+ (JWT or CWT) | | | references | | +-------+-----------+ +--------+---------------+