Skip to content

Commit f80b63b

Browse files
c2boc2bo
authored
Merge pull request #269 from oauth-wg/status_list_def
Clarify Status List definition
2 parents 233f2ca + 8b3c09b commit f80b63b

File tree

1 file changed

+39
-33
lines changed

1 file changed

+39
-33
lines changed

‎draft-ietf-oauth-status-list.md

Lines changed: 39 additions & 33 deletions
Original file line numberDiff line numberDiff line change
@@ -231,7 +231,7 @@ Relying Party:
231231
: 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.
232232

233233
Status List:
234-
: An object in JSON or CBOR representation containing a bit array that lists the statuses of many Referenced Tokens.
234+
: An object in JSON or CBOR representation containing a compressed byte array that represents the statuses of many Referenced Tokens.
235235

236236
Status List Token:
237237
: A token in JWT (as defined in {{RFC7519}}) or CWT (as defined in {{RFC8392}}) representation that contains a cryptographically secured Status List.
@@ -244,15 +244,21 @@ base64url:
244244

245245
# Status List {#status-list}
246246

247-
A Status List is a byte array that contains the statuses of many Referenced Tokens represented by one or multiple bits. A common representation of a Status List is composed by the following algorithm:
247+
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.
248248

249-
1. 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.
249+
## Compressed Byte Array {#status-list-byte-array}
250250

251-
2. The overall Status List is encoded as a byte array. Depending on the bit-size, each byte corresponds to 8/(#bit-size) statuses (8,4,2 or 1). The status of each Referenced Token is identified using the index that maps to one or more specific bits within the byte array. The index starts counting at 0 and ends with "size" - 1 (being the last valid entry). The bits within an array are counted from 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.
251+
A compressed byte array containing the status information of the Referenced Token is composed by the following algorithm:
252252

253-
3. The byte array is compressed using DEFLATE {{RFC1951}} with the ZLIB {{RFC1950}} data format. Implementations are RECOMMENDED to use the highest compression level available.
253+
1. The Status Issuer MUST define a number of bits (`bits`) of either 1,2,4 or 8, that represents the amount of bits used to describe the status of each Referenced Token within this Status List. 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.
254254

255-
The following example illustrates a Status List that represents the statuses of 16 Referenced Tokens, requiring 16 bits (2 bytes) for the uncompressed byte array (1 bit status):
255+
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).
256+
257+
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.
258+
259+
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.
260+
261+
The following example illustrates the byte array of a Status List that represents the statuses of 16 Referenced Tokens with a `bits` of 1, requiring 2 bytes (16 bits) for the uncompressed byte array:
256262

257263
~~~ ascii-art
258264

@@ -278,20 +284,18 @@ These bits are concatenated:
278284

279285
~~~ ascii-art
280286

281-
byte 0 1 2
282-
bit 7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0 7
283-
+-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+ +-+...
284-
values |1|0|1|1|1|0|0|1| |1|0|1|0|0|0|1|1| |0|...
285-
+-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+ +-+...
286-
index 7 6 5 4 3 2 1 0 15 ... 10 9 8 23
287-
\_______________/ \_______________/
288-
0xB9 0xA3
287+
byte no 0 1 2
288+
bit no 7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0 7
289+
+-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+ +-+...
290+
values |1|0|1|1|1|0|0|1| |1|0|1|0|0|0|1|1| |0|...
291+
+-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+ +-+...
292+
index 7 6 5 4 3 2 1 0 15 ... 10 9 8 23
293+
\_______________/ \_______________/
294+
byte value 0xB9 0xA3
289295

290296
~~~
291297

292-
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.
293-
294-
This example Status List represents the status of 12 Referenced Tokens, requiring 24 bits (3 bytes) of status (2 bit status):
298+
In the following 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 illustrates the byte array of a Status List that represents the statuses of 12 Referenced Tokens with a `bits` of 2, requiring 3 bytes (24 bits) for the uncompressed byte array:
295299

296300
~~~ ascii-art
297301

@@ -313,16 +317,16 @@ These bits are concatenated:
313317

314318
~~~ ascii-art
315319

316-
byte 0 1 2
317-
bit 7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0
318-
+-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+
319-
values |1|1|0|0|1|0|0|1| |0|1|0|0|0|1|0|0| |1|1|1|1|1|0|0|1|
320-
+-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+
321-
\ / \ / \ / \ / \ / \ / \ / \ / \ / \ / \ / \ /
322-
status 3 0 2 1 1 0 1 0 3 3 2 1
323-
index 3 2 1 0 7 6 5 4 11 10 9 8
324-
\___________/ \___________/ \___________/
325-
0xC9 0x44 0xF9
320+
byte no 0 1 2
321+
bit no 7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0
322+
+-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+
323+
values |1|1|0|0|1|0|0|1| |0|1|0|0|0|1|0|0| |1|1|1|1|1|0|0|1|
324+
+-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+
325+
\ / \ / \ / \ / \ / \ / \ / \ / \ / \ / \ / \ /
326+
status 3 0 2 1 1 0 1 0 3 3 2 1
327+
index 3 2 1 0 7 6 5 4 11 10 9 8
328+
\___________/ \___________/ \___________/
329+
byte value 0xC9 0x44 0xF9
326330

327331
~~~
328332

@@ -331,17 +335,17 @@ index 3 2 1 0 7 6 5 4 11 10 9 8
331335
This section defines the data structure for a JSON-encoded Status List:
332336

333337
* `status_list`: REQUIRED. JSON Object that contains a Status List. It MUST contain at least the following claims:
334-
* `bits`: REQUIRED. JSON Integer specifying the number of bits per Referenced Token in the Status List (`lst`). The allowed values for `bits` are 1,2,4 and 8.
335-
* `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 Status List as specified in [](#status-list).
338+
* `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.
339+
* `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).
336340
* `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.
337341

338-
The following example illustrates the JSON representation of the Status List with bit-size 1 from the example above:
342+
The following example illustrates the JSON representation of the Status List with `bits` 1 from the example above:
339343

340344
~~~~~~~~~~
341345
{::include ./examples/status_list_encoding_json}
342346
~~~~~~~~~~
343347

344-
The following example illustrates the JSON representation of the Status List with bit-size 2 from the example above:
348+
The following example illustrates the JSON representation of the Status List with `bits` 2 from the example above:
345349

346350
~~~~~~~~~~
347351
{::include ./examples/status_list_encoding2_json}
@@ -354,8 +358,8 @@ See section [](#test-vectors) for more test vectors.
354358
This section defines the data structure for a CBOR-encoded Status List:
355359

356360
* The `StatusList` structure is a map (Major Type 5) and defines the following entries:
357-
* `bits`: REQUIRED. Unsigned integer (Major Type 0) that contains the number of bits per Referenced Token in the Status List. The allowed values for `bits` are 1, 2, 4 and 8.
358-
* `lst`: REQUIRED. Byte string (Major Type 2) that contains the Status List as specified in [](#status-list).
361+
* `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.
362+
* `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).
359363
* `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.
360364

361365
The following is the CDDL definition of the StatusList structure:
@@ -1830,6 +1834,8 @@ CBOR encoding:
18301834

18311835
-09
18321836

1837+
* introduce dedicated section for compressed byte array of the Status List
1838+
* fix Status List definitions
18331839
* Add CDDL for CBOR StatusList encoding
18341840
* add diagram for Status List Aggregation for further explanation
18351841
* rename "chunking" of Status List Tokens (for scalability reasons) into "divide .. up"

0 commit comments

Comments
 (0)