idnits 2.17.1 draft-tiloca-ace-revoked-token-notification-04.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (February 22, 2021) is 1158 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Outdated reference: A later version (-46) exists of draft-ietf-ace-oauth-authz-37 Summary: 0 errors (**), 0 flaws (~~), 2 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 ACE Working Group M. Tiloca 3 Internet-Draft RISE AB 4 Intended status: Standards Track L. Seitz 5 Expires: August 26, 2021 Combitech 6 F. Palombini 7 Ericsson AB 8 S. Echeverria 9 G. Lewis 10 CMU SEI 11 February 22, 2021 13 Notification of Revoked Access Tokens in the Authentication and 14 Authorization for Constrained Environments (ACE) Framework 15 draft-tiloca-ace-revoked-token-notification-04 17 Abstract 19 This document specifies a method of the Authentication and 20 Authorization for Constrained Environments (ACE) framework, which 21 allows an Authorization Server to notify Clients and Resource Servers 22 (i.e., registered devices) about revoked Access Tokens. The method 23 relies on resource observation for the Constrained Application 24 Protocol (CoAP), with Clients and Resource Servers observing a Token 25 Revocation List on the Authorization Server. Resulting unsolicited 26 notifications of revoked Access Tokens complement alternative 27 approaches such as token introspection, while not requiring 28 additional endpoints on Clients and Resource Servers. 30 Status of This Memo 32 This Internet-Draft is submitted in full conformance with the 33 provisions of BCP 78 and BCP 79. 35 Internet-Drafts are working documents of the Internet Engineering 36 Task Force (IETF). Note that other groups may also distribute 37 working documents as Internet-Drafts. The list of current Internet- 38 Drafts is at https://datatracker.ietf.org/drafts/current/. 40 Internet-Drafts are draft documents valid for a maximum of six months 41 and may be updated, replaced, or obsoleted by other documents at any 42 time. It is inappropriate to use Internet-Drafts as reference 43 material or to cite them other than as "work in progress." 45 This Internet-Draft will expire on August 26, 2021. 47 Copyright Notice 49 Copyright (c) 2021 IETF Trust and the persons identified as the 50 document authors. All rights reserved. 52 This document is subject to BCP 78 and the IETF Trust's Legal 53 Provisions Relating to IETF Documents 54 (https://trustee.ietf.org/license-info) in effect on the date of 55 publication of this document. Please review these documents 56 carefully, as they describe your rights and restrictions with respect 57 to this document. Code Components extracted from this document must 58 include Simplified BSD License text as described in Section 4.e of 59 the Trust Legal Provisions and are provided without warranty as 60 described in the Simplified BSD License. 62 Table of Contents 64 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 65 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 4 66 2. Protocol Overview . . . . . . . . . . . . . . . . . . . . . . 5 67 3. Token Hash . . . . . . . . . . . . . . . . . . . . . . . . . 7 68 4. The TRL Resource . . . . . . . . . . . . . . . . . . . . . . 9 69 4.1. Update of the TRL Resource . . . . . . . . . . . . . . . 9 70 5. The TRL Endpoint . . . . . . . . . . . . . . . . . . . . . . 9 71 5.1. Full Query of the TRL . . . . . . . . . . . . . . . . . . 10 72 5.2. Diff Query of the TRL . . . . . . . . . . . . . . . . . . 11 73 6. Upon Registration . . . . . . . . . . . . . . . . . . . . . . 13 74 7. Notification of Revoked Tokens . . . . . . . . . . . . . . . 14 75 8. Interaction Examples . . . . . . . . . . . . . . . . . . . . 14 76 8.1. Full Query with Observation . . . . . . . . . . . . . . . 15 77 8.2. Diff Query with Observation . . . . . . . . . . . . . . . 16 78 8.3. Full Query with Observation and Additional Diff Query . . 18 79 9. Security Considerations . . . . . . . . . . . . . . . . . . . 21 80 10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 22 81 10.1. Media Type Registrations . . . . . . . . . . . . . . . . 22 82 10.2. CoAP Content-Formats Registry . . . . . . . . . . . . . 23 83 10.3. Token Revocation List Registry . . . . . . . . . . . . . 23 84 10.4. Expert Review Instructions . . . . . . . . . . . . . . . 24 85 11. References . . . . . . . . . . . . . . . . . . . . . . . . . 24 86 11.1. Normative References . . . . . . . . . . . . . . . . . . 24 87 11.2. Informative References . . . . . . . . . . . . . . . . . 26 88 Appendix A. Usage of the Series Transfer Pattern . . . . . . . . 26 89 Appendix B. Usage of the "Cursor" Pattern . . . . . . . . . . . 28 90 B.1. Full Query Request . . . . . . . . . . . . . . . . . . . 28 91 B.2. Full Query Response . . . . . . . . . . . . . . . . . . . 28 92 B.3. Diff Query Request . . . . . . . . . . . . . . . . . . . 29 93 B.4. Diff Query Response . . . . . . . . . . . . . . . . . . . 29 94 B.4.1. Empty Collection . . . . . . . . . . . . . . . . . . 29 95 B.4.2. Cursor Not Specified in the Diff Query Request . . . 29 96 B.4.3. Cursor Specified in the Diff Query Request . . . . . 30 97 B.4.4. TRL Parameters . . . . . . . . . . . . . . . . . . . 32 98 Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . 33 99 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 33 101 1. Introduction 103 Authentication and Authorization for Constrained Environments (ACE) 104 [I-D.ietf-ace-oauth-authz] is a framework that enforces access 105 control on IoT devices acting as Resource Servers. In order to use 106 ACE, both Clients and Resource Servers have to register with an 107 Authorization Server and become a registered device. Once 108 registered, a Client can send a request to the Authorization Server, 109 to obtain an Access Token for a Resource Server. For a Client to 110 access the Resource Server, the Client must present the issued Access 111 Token at the Resource Server, which then validates and stores it. 113 Even though Access Tokens have expiration times, there are 114 circumstances by which an Access Token may need to be revoked before 115 its expiration time, such as: (1) a registered device has been 116 compromised, or is suspected of being compromised; (2) a registered 117 device is decommissioned; (3) there has been a change in the ACE 118 profile for a registered device; (4) there has been a change in 119 access policies for a registered device; and (5) there has been a 120 change in the outcome of policy evaluation for a registered device 121 (e.g., if policy assessment depends on dynamic conditions in the 122 execution environment, the user context, or the resource 123 utilization). 125 As discussed in Section 6.1 of [I-D.ietf-ace-oauth-authz], only 126 client-initiated revocation is currently specified [RFC7009] for 127 OAuth 2.0 [RFC6749], based on the assumption that Access Tokens in 128 OAuth are issued with a relatively short lifetime. However, this may 129 not be the case for constrained, intermittently connected devices, 130 that need Access Tokens with relatively long lifetimes. 132 This document specifies a method for allowing registered devices to 133 access and observe a Token Revocation List (TRL) resource on the 134 Authorization Server, in order to get an updated list of revoked, but 135 yet not expired, pertaining Access Tokens. In particular, registered 136 devices rely on resource observation [RFC7641] for the Constrained 137 Application Protocol (CoAP) [RFC7252]. The benefits of this method 138 are that it complements token introspection and does not require any 139 additional endpoints on the registered devices. 141 1.1. Terminology 143 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 144 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 145 "OPTIONAL" in this document are to be interpreted as described in BCP 146 14 [RFC2119] [RFC8174] when, and only when, they appear in all 147 capitals, as shown here. 149 Readers are expected to be familiar with the terms and concepts 150 described in the ACE framework for Authentication and Authorization 151 [I-D.ietf-ace-oauth-authz], as well as with terms and concepts 152 related to CBOR Web Tokens (CWTs) [RFC8392], and JSON Web Tokens 153 (JWTs) [RFC7519]. The terminology for entities in the considered 154 architecture is defined in OAuth 2.0 [RFC6749]. In particular, this 155 includes Client, Resource Server, and Authorization Server. 157 Readers are also expected to be familiar with the terms and concepts 158 related to CBOR [RFC8949], JSON [RFC8259], the CoAP protocol 159 [RFC7252], CoAP Observe [RFC7641], and the use of hash functions to 160 name objects as defined in [RFC6920]. 162 Note that, unless otherwise indicated, the term "endpoint" is used 163 here following its OAuth definition, aimed at denoting resources such 164 as /token and /introspect at the Authorization Server, and /authz- 165 info at the Resource Server. This document does not use the CoAP 166 definition of "endpoint", which is "An entity participating in the 167 CoAP protocol." 169 This specification also refers to the following terminology. 171 o Token hash: identifier of an Access Token, in binary format 172 encoding. The token hash has no relation to other possibly used 173 token identifiers, such as the "cti" (CWT ID) claim of CBOR Web 174 Tokens (CWTs) [RFC8392]. 176 o Token Revocation List (TRL): a collection of token hashes, in 177 which the corresponding Access Tokens have been revoked but are 178 not expired yet. 180 o TRL resource: a resource on the Authorization Server, with a TRL 181 as its representation. 183 o TRL endpoint: an endpoint at the Authorization Server associated 184 to the TRL resource. The default name of the TRL endpoint in a 185 url-path is '/revoke/trl'. Implementations are not required to 186 use this name, and can define their own instead. 188 o Registered device: a device registered at the Authorization 189 Server, i.e. as a Client, or a Resource Server, or both. A 190 registered device acts as caller of the TRL endpoint. 192 o Administrator: entity authorized to get full access to the TRL at 193 the Authorization Server, and acting as caller of the TRL 194 endpoint. An administrator is not necessarily a registered device 195 as defined above, i.e. a Client requesting Access Tokens or a 196 Resource Server consuming Access Tokens. How the administrator 197 authorization is established and verified is out of the scope of 198 this specification. 200 o Pertaining Access Token: 202 * With reference to an administrator, an Access Token issued by 203 the Authorization Server. 205 * With reference to a registered device, an Access Token intended 206 to be owned by that device. An Access Token pertains to a 207 Client if the Authorization Server has issued the Access Token 208 and provided it to that Client. An Access Token pertains to a 209 Resource Server if the Authorization Server has issued the 210 Access Token to be consumed by that Resource Server. 212 2. Protocol Overview 214 This protocol defines how a CoAP-based Authorization Server informs 215 Clients and Resource Servers, i.e. registered devices, about revoked 216 Access Tokens. How the relationship between the registered device 217 and the Authorization Server is established is out of the scope of 218 this specification. 220 At a high level, the steps of this protocol are as follows. 222 o Upon startup, the Authorization Server creates a TRL resource. At 223 any point in time, the TRL resource represents the list of all 224 revoked Access Tokens issued by the Authorization Server that are 225 yet not expired. 227 o When a device registers at the Authorization Server, it receives 228 the url-path to the TRL resource. 230 After the registration procedure is finished, the registered 231 device sends an Observation Request to that TRL resource as 232 described in [RFC7641], i.e. a GET request with an Observe option 233 set to 0 (register). Upon receiving the request, the 234 Authorization Server adds the registered device to the list of 235 observers of the TRL resource. 237 At any time, the registered device can send a GET request to the 238 TRL endpoint. When doing so, it can request for: the current list 239 of pertaining revoked Access Tokens (see Section 5.1); or the most 240 recent TRL updates occurred over the list of pertaining revoked 241 Access Tokens (see Section 5.2). In either case, the registered 242 devices may especially rely on an Observation Request. 244 o When an Access Token is revoked, the Authorization Server adds the 245 corresponding token hash to the TRL. Also, when a revoked Access 246 Token eventually expires, the Authorization Server removes the 247 corresponding token hash from the TRL. 249 In either case, after updating the TRL, the Authorization Server 250 sends Observe Notifications as per [RFC7641]. That is, one 251 Observe Notification is sent to each registered device the Access 252 Token pertains to, and specifies the current updated list of token 253 hashes in the portion of the TRL pertaining to that device. 255 Further Observe Notifications may be sent, consistently with 256 ongoing additional observations of the TRL resource. 258 o An administrator can observe and access the TRL like a registered 259 device, while getting the full updated representation of the TRL. 261 Figure 1 shows a high-level overview of the service provided by this 262 protocol. In particular, it shows the Observe Notifications sent by 263 the Authorization Server to one administrator and four registered 264 devices, upon revocation of the issued Access Tokens t1, t2 and t3, 265 with token hash th1, th2 and th3, respectively. Each dotted line 266 associated to a pair of registered devices indicates the Access Token 267 that they both own. 269 +----------------------+ 270 | Authorization Server | 271 +-----------o----------+ 272 revoke/trl | TRL: {th1,th2,th3} 273 | 274 +-----------------+------------+------------+------------+ 275 | | | | | 276 | th1,th2,th3 | th1,th2 | th1 | th3 | th2,th3 277 v v v v v 278 +---------------+ +----------+ +----------+ +----------+ +----------+ 279 | Administrator | | Client 1 | | Resource | | Client 2 | | Resource | 280 | | | | | Server 1 | | | | Server 2 | 281 +---------------+ +----------+ +----------+ +----------+ +----------+ 282 : : : : : : 283 : : t1 : : t3 : : 284 : :........: :............: : 285 : t2 : 286 :...........................................: 288 Figure 1: Protocol Overview 290 Section 8 provides examples of the protocol flow and message exchange 291 between the Authorization Server and a registered device. 293 3. Token Hash 295 The token hash of an Access Token is computed as follows. 297 1. The Authorization Server defines ENCODED_TOKEN, as the content of 298 the 'access_token' parameter in the Authorization Server response 299 (see Section 5.8.2 of [I-D.ietf-ace-oauth-authz]), where the 300 Access Token was included and returned to the requesting Client. 302 Note that the content of the 'access_token' parameter is either: 304 * A CBOR byte string, if the Access Token was transported using 305 CBOR. With reference to the example in Figure 2, and assuming 306 the string's length in bytes to be 119 (i.e., 0x77 in 307 hexadecimal), then ENCODED_TOKEN takes the bytes {0x58 0x77 308 0xd0 0x83 0x44 0xa1 ...}, i.e. the raw content of the 309 parameter 'access_token'. 311 * A text string, if the Access Token was transported using JSON. 312 With reference to the example in Figure 3, ENCODED_TOKEN takes 313 "2YotnFZFEjr1zCsicMWpAA", i.e. the raw content of the 314 parameter 'access_token'. 316 2. The Authorization Server defines HASH_INPUT as follows. 318 * If CBOR was used to transport the Access Token (as a CWT or 319 JWT), HASH_INPUT takes the same value of ENCODED_TOKEN. 321 * If JSON was used to transport the Access Token (as a CWT or 322 JWT), HASH_INPUT takes the serialization of ENCODED_TOKEN. 324 In either case, HASH_INPUT results in the binary 325 representation of the content of the 'access_token' parameter 326 from the Authorization Server response. 328 3. The Authorization Server generates a hash value of HASH_INPUT as 329 per Section 6 of [RFC6920]. The resulting output in binary 330 format is used as the token hash. Note that the used binary 331 format embeds the identifier of the used hash function, in the 332 first byte of the computed token hash. 334 The specifically used hash function MUST be collision-resistant 335 on byte-strings, and MUST be selected from the "Named Information 336 Hash Algorithm" Registry [Named.Information.Hash.Algorithm]. 338 The Authorization Server specifies the used hash function to 339 registered devices during their registration procedure (see 340 Section 6). 342 2.01 Created 343 Content-Format: application/ace+cbor 344 Max-Age: 85800 345 Payload: 346 { 347 access_token : h'd08344a1...' 348 (remainder of the Access Token omitted for brevity) 349 token_type : pop, 350 expires_in : 86400, 351 profile : coap_dtls, 352 (remainder of the response omitted for brevity) 353 } 355 Figure 2: Example of Authorization Server response using CBOR 357 HTTP/1.1 200 OK 358 Content-Type: application/json 359 Cache-Control: no-store 360 Pragma: no-cache 361 Payload: 362 { 363 "access_token" : "2YotnFZFEjr1zCsicMWpAA" 364 (remainder of the Access Token omitted for brevity) 365 "token_type" : "pop", 366 "expires_in" : 86400, 367 "profile" : "coap_dtls", 368 (remainder of the response omitted for brevity) 369 } 371 Figure 3: Example of Authorization Server response using JSON 373 4. The TRL Resource 375 Upon startup, the Authorization Server creates a single TRL resource, 376 encoded as a CBOR array. 378 Each element of the array is a CBOR byte string, with value the token 379 hash of an Access Token. The order of the token hashes in the CBOR 380 array is irrelevant, and the CBOR array MUST be treated as a set in 381 which the order has no significant meaning. 383 The TRL is initialized as empty, i.e. the initial content of the TRL 384 resource representation MUST be an empty CBOR array. 386 4.1. Update of the TRL Resource 388 The Authorization Server updates the TRL in the following two cases. 390 o When a non-expired Access Token is revoked, the token hash of the 391 Access Token is added to the TRL resource representation. That 392 is, a CBOR byte string with the token hash as its value is added 393 to the CBOR array used as TRL resource representation. 395 o When a revoked Access Token expires, the token hash of the Access 396 Token is removed from the TRL resource representation. That is, 397 the CBOR byte string with the token hash as its value is removed 398 from the CBOR array used as TRL resource representation. 400 5. The TRL Endpoint 402 Consistent with Section 6.5 of [I-D.ietf-ace-oauth-authz], all 403 communications between a caller of the TRL endpoint and the 404 Authorization Server MUST be encrypted, as well as integrity and 405 replay protected. Furthermore, responses from the Authorization 406 Server to the caller MUST be bound to the caller's request. 408 The Authorization Server MUST implement measures to prevent access to 409 the TRL endpoint by entities other than registered devices and 410 authorized administrators. 412 The TRL endpoint supports only the GET method, and allows two types 413 of query of the TRL. 415 o Full query: the Authorization Server returns the token hashes of 416 the revoked Access Tokens currently in the TRL and pertaining to 417 the requester. The Authorization Server MUST support this type of 418 query. The processing of a full query and the related response 419 format are defined in Section 5.1. 421 o Diff query: the Authorization Server returns a list of diff 422 entries. Each diff entry is related to one of the most recent 423 updates, in the portion of the TRL pertaining to the requester. 424 The Authorization Server MAY support this type of query. 426 The entry associated to one of such updates contains a list of 427 token hashes, such that: i) the corresponding revoked Access 428 Tokens pertain to the requester; and ii) they were added to or 429 removed from the TRL at that update. The processing of a diff 430 query and the related response format are defined in Section 5.2. 432 The TRL endpoint allows the following query parameter in a GET 433 request. 435 o 'diff': if included, it indicates to perform a diff query of the 436 TRL. Its value MUST be either: 438 * the integer 0, indicating that a (notification) response should 439 include as many diff entries as the Authorization Server can 440 provide in the response; or 442 * a positive integer greater than 0, indicating the maximum 443 number of diff entries that a (notification) response should 444 include. 446 5.1. Full Query of the TRL 448 In order to produce a (notification) response to a GET request asking 449 for a full query of the TRL, the Authorization Server performs the 450 following actions. 452 1. From the current TRL resource representation, the Authorization 453 Server builds a set HASHES, such that: 455 * If the requester is a registered device, HASHES specifies the 456 token hashes of the Access Tokens pertaining to that 457 registered device. The Authorization Server can use the 458 authenticated identity of the registered device to perform the 459 necessary filtering on the TRL resource representation. 461 * If the requester is an administrator, HASHES specifies all the 462 token hashes in the current TRL resource representation. 464 2. The Authorization Server sends a 2.05 (Content) Response to the 465 requester, with a CBOR array as payload. Each element of the 466 array specifies one of the token hashes from the set HASHES, 467 encoded as a CBOR byte string. 469 The order of the token hashes in the CBOR array is irrelevant, 470 i.e. the CBOR array MUST be treated as a set in which the order 471 has no significant meaning. 473 5.2. Diff Query of the TRL 475 In order to produce a (notification) response to a GET request asking 476 for a diff query of the TRL, the Authorization Server performs the 477 following actions. 479 1. The Authorization Server defines the positive integer NUM. If 480 the value N specified in the query parameter 'diff' of the GET 481 request is equal to 0 or greater than a pre-defined positive 482 integer N_MAX, then NUM takes the value of N_MAX. Otherwise, NUM 483 takes N. 485 2. The Authorization Server prepares U = min(NUM, SIZE) diff 486 entries, where SIZE <= N_MAX is the number of TRL updates 487 pertaining to the requester and currently stored at the 488 Authorization Server. That is, the diff entries are related to 489 the U most recent TRL updates pertaining to the requester. In 490 particular, the first entry refers to the most recent of such 491 updates, the second entry refers to the second from last of such 492 updates, and so on. 494 Each diff entry is a CBOR array 'diff-entry', which includes the 495 following two elements. 497 * The first element is a CBOR array 'removed'. Each element of 498 the array is a CBOR byte string, with value the token hash of 499 an Access Token such that: it pertained to the requester; and 500 it was removed from the TRL during the update associated to 501 the diff entry. 503 * The second element is a CBOR array 'added'. Each element of 504 the array is a CBOR byte string, with value the token hash of 505 an Access Token such that: it pertains to the requester; and 506 it was added to the TRL during the update associated to the 507 diff entry. 509 The order of the token hashes in the CBOR arrays 'removed' and 510 'added' is irrelevant. That is, the CBOR arrays 'removed' and 511 'added' MUST be treated as a set in which the order of elements 512 has no significant meaning. 514 3. The Authorization Server prepares a 2.05 (Content) Response for 515 the requester, with a CBOR array 'diff' of U elements as payload. 516 Each element of the CBOR array 'diff' specifies one of the CBOR 517 arrays 'diff-entry' prepared at point 2 as diff entries. 519 Within the CBOR array 'diff', the CBOR arrays 'diff-entry' MUST 520 be sorted to reflect the corresponding updates to the TRL in 521 reverse chronological order. That is, the first 'diff-entry' 522 element of 'diff' relates to the most recent update to the 523 portion of the TRL pertaining to the requester. 525 The CDDL definition [RFC8610] of the CBOR array 'diff' formatted as 526 in the response from the Authorization Server is provided below. 528 token-hash = bytes 529 trl-patch = [* token-hash] 530 diff-entry = [removed: trl-patch, added: trl-patch] 531 diff = [* diff-entry] 533 Figure 4: CDDL definition of the response payload following a Diff 534 Query request to the TRL endpoint 536 If the Authorization Server supports diff queries: 538 o The Authorization Server MUST return a 4.00 (Bad Request) response 539 in case the 'diff' parameter specifies a value other than 0 or 540 than a positive integer. 542 o The Authorization Server MUST keep track of N_MAX most recent 543 updates to the portion of the TRL that pertains to each caller of 544 the TRL endpoint. The particular method to achieve this is 545 implementation-specific. 547 o When SIZE is equal to N_MAX, and a new TRL update occurs as 548 pertaining to a registered device, the Authorization Server MUST 549 first delete the oldest stored update for that device, before 550 storing this latest update as the most recent one for that device. 552 o The Authorization Server SHOULD provide registered devices and 553 administrators with the value of N_MAX, upon their registration 554 (see Section 6). 556 If the Authorization Server does not support diff queries, it 557 proceeds as when processing a full query (see Section 5.1). 559 Appendix A discusses how the diff query of the TRL is in fact a usage 560 example of the Series Transfer Pattern defined in 561 [I-D.bormann-t2trg-stp]. 563 Appendix B discusses how the diff query of the TRL can be further 564 improved by using the "Cursor" pattern defined in Section 3.3 of 565 [I-D.bormann-t2trg-stp]. 567 6. Upon Registration 569 During the registration process at the Authorization Server, an 570 administrator or a registered device receives the following 571 information as part of the registration response. 573 o The url-path to the TRL endpoint at the Authorization Server. 575 o The hash function used to compute token hashes. This is specified 576 as an integer or a text string, taking value from the "ID" or 577 "Hash Name String" column of the "Named Information Hash 578 Algorithm" Registry [Named.Information.Hash.Algorithm], 579 respectively. 581 o Optionally, a positive integer N_MAX, if the Authorization Server 582 supports diff queries of the TRL resource (see Section 5.2). 584 After the registration procedure is finished, the administrator or 585 registered device performs a GET request to the TRL resource, 586 including the CoAP Observe option set to 0 (register), in order to 587 start an observation of the TRL resource at the Authorization Server, 588 as per Section 3.1 of [RFC7641]. The GET request can express the 589 wish for a full query (see Section 5.1) or a diff query (see 590 Section 5.2) of the TRL. 592 In case the request is successfully processed, The Authorization 593 Server replies using the CoAP response code 2.05 (Content) and 594 including the CoAP Observe option in the response. The payload of 595 the response is formatted as defined in Section 5.1 or in 596 Section 5.2, in case the GET request was for a full query or a diff 597 query of the TRL, respectively. 599 Further details about the registration process at the Authorization 600 Server are out of scope for this specification. Note that the 601 registration process is also out of the scope of the ACE framework 602 for Authentication and Authorization (see Section 5.5 of 603 [I-D.ietf-ace-oauth-authz]). 605 7. Notification of Revoked Tokens 607 When the TRL is updated (see Section 4.1), the Authorization Server 608 sends Observe Notifications to every observer of the TRL resource. 609 Observe Notifications are sent as per Section 4.2 of [RFC7641]. 611 The payload of each Observe Notification is formatted as defined in 612 Section 5.1 or in Section 5.2, in case the original Observation 613 Request was for a full query or a diff query of the TRL, 614 respectively. 616 Furthermore, an administrator or a registered device can send 617 additional GET requests to the TRL endpoint at any time, in order to 618 retrieve the token hashes of the pertaining revoked Access Tokens. 619 When doing so, the caller of the TRL endpoint can perform a full 620 query (see Section 5.1) or a diff query (see Section 5.2). 622 8. Interaction Examples 624 This section provides examples of interactions between a Resource 625 Server RS as registered device and an Authorization Server AS. The 626 Authorization Server supports both full query and diff query of the 627 TRL, as defined in Section 5.1 and Section 5.2, respectively. 629 The details of the registration process are omitted, but it is 630 assumed that the Resource Server sends an unspecified payload to the 631 Authorization Server, which replies with a 2.01 (Created) response. 633 The payload of the registration response is a CBOR map, which 634 includes the following entries: 636 o a "trl" parameter, specifying the path of the TRL resource; 638 o a "trl_hash" parameter, specifying the hash function used to 639 computed token hashes as defined in Section 3; 641 o an "n_max" parameter, specifying the value of N_MAX, i.e. the 642 maximum number of TRL updates pertaining to each registered device 643 that the Authorization Server retains for that device (see 644 Section 5.2); 646 o possible further parameters related to the registration process. 648 Furthermore, 'h(x)' refers to the hash function used to compute the 649 token hashes, as defined in Section 3 of this specification and 650 according to [RFC6920]. Assuming the usage of CWTs transported in 651 CBOR, 'bstr.h(t1)' and 'bstr.h(t2)' denote the byte-string 652 representations of the token hashes for the Access Tokens t1 and t2, 653 respectively. 655 8.1. Full Query with Observation 657 Figure 5 shows an example interaction considering a CoAP observation 658 and a full query of the TRL. 660 RS AS 661 | | 662 | Registration: POST | 663 +-------------------------------------->| 664 | | 665 |<--------------------------------------+ 666 | 2.01 CREATED | 667 | Payload: { | 668 | ... | 669 | "trl" = "revoke/trl", | 670 | "trl_hash" = "sha-256", | 671 | "n_max" = 10 | 672 | } | 673 | | 674 | GET Observe: 0 | 675 | coap://example.as.com/revoke/trl/ | 676 +-------------------------------------->| 677 | | 678 |<--------------------------------------+ 679 | 2.05 CONTENT Observe: 42 | 680 | Payload: [] | 681 | . | 682 | . | 683 | . | 684 | | 685 | (Access Tokens t1 and t2 issued | 686 | and successfully submitted to RS) | 687 | . | 688 | . | 689 | . | 690 | | 691 | | 692 | (Access Token t1 is revoked) | 693 | | 694 |<--------------------------------------+ 695 | 2.05 CONTENT Observe: 53 | 696 | Payload: [bstr.h(t1)] | 697 | . | 698 | . | 699 | . | 700 | | 701 | (Access Token t2 is revoked) | 702 | | 703 |<--------------------------------------+ 704 | 2.05 CONTENT Observe: 64 | 705 | Payload: [bstr.h(t1), | 706 | bstr.h(t2)] | 707 | . | 708 | . | 709 | . | 710 | | 711 | (Access Token t1 expires) | 712 | | 713 |<--------------------------------------+ 714 | 2.05 CONTENT Observe: 75 | 715 | Payload: [bstr.h(t2)] | 716 | . | 717 | . | 718 | . | 719 | | 720 | (Access Token t2 expires) | 721 | | 722 |<--------------------------------------+ 723 | 2.05 CONTENT Observe: 86 | 724 | Payload: [] | 725 | | 727 Figure 5: Interaction for Full Query with Observation 729 8.2. Diff Query with Observation 731 Figure 6 shows an example interaction considering a CoAP observation 732 and a diff query of the TRL. 734 The Resource Server indicates N=3 as value of the query parameter 735 "diff", i.e. as the maximum number of diff entries to be specified in 736 a response from the Authorization Server. 738 RS AS 739 | | 740 | Registration: POST | 741 +--------------------------------------------->| 742 | | 743 |<---------------------------------------------+ 744 | 2.01 CREATED | 745 | Payload: { | 746 | ... | 747 | "trl" = "revoke/trl", | 748 | "trl_hash" = "sha-256", | 749 | "n_max" = 10 | 750 | } | 751 | | 752 | GET Observe: 0 | 753 | coap://example.as.com/revoke/trl?diff=3 | 754 +--------------------------------------------->| 755 | | 756 |<---------------------------------------------+ 757 | 2.05 CONTENT Observe: 42 | 758 | Payload: [] | 759 | . | 760 | . | 761 | . | 762 | | 763 | (Access Tokens t1 and t2 issued | 764 | and successfully submitted to RS) | 765 | . | 766 | . | 767 | . | 768 | | 769 | (Access Token t1 is revoked) | 770 | | 771 |<---------------------------------------------+ 772 | 2.05 CONTENT Observe: 53 | 773 | Payload: [ | 774 | [ [], [bstr.h(t1)] ] | 775 | ] | 776 | . | 777 | . | 778 | . | 779 | | 780 | (Access Token t2 is revoked) | 781 | | 782 | | 783 |<---------------------------------------------+ 784 | 2.05 CONTENT Observe: 64 | 785 | Payload: [ | 786 | [ [], [bstr.h(t2)] ], | 787 | [ [], [bstr.h(t1)] ] | 788 | ] | 789 | . | 790 | . | 791 | . | 792 | | 793 | (Access Token t1 expires) | 794 | | 795 |<---------------------------------------------+ 796 | 2.05 CONTENT Observe: 75 | 797 | Payload: [ | 798 | [ [bstr.h(t1)], [] ], | 799 | [ [], [bstr.h(t2)] ], | 800 | [ [], [bstr.h(t1)] ] | 801 | ] | 802 | . | 803 | . | 804 | . | 805 | | 806 | (Access Token t2 expires) | 807 | | 808 |<---------------------------------------------+ 809 | 2.05 CONTENT Observe: 86 | 810 | Payload: [ | 811 | [ [bstr.h(t2)], [] ], | 812 | [ [bstr.h(t1)], [] ], | 813 | [ [], [bstr.h(t2)] ] | 814 | ] | 815 | | 817 Figure 6: Interaction for Diff Query with Observation 819 8.3. Full Query with Observation and Additional Diff Query 821 Figure 7 shows an example interaction considering a CoAP observation 822 and a full query of the TRL. 824 The example also considers one of the notifications from the 825 Authorization Server to get lost in transmission, and thus not 826 reaching the Resource Server. 828 When this happens, and after a waiting time defined by the 829 application has elapsed, the Resource Server sends a GET request with 830 no observation to the Authorization Server, to perform a diff query 831 of the TRL. The Resource Server indicates N=8 as value of the query 832 parameter "diff", i.e. as the maximum number of diff entries to be 833 specified in a response from the Authorization Server. 835 RS AS 836 | | 837 | Registration: POST | 838 +--------------------------------------------->| 839 | | 840 |<---------------------------------------------+ 841 | 2.01 CREATED | 842 | Payload: { | 843 | ... | 844 | "trl" = "revoke/trl", | 845 | "trl_hash" = "sha-256", | 846 | "n_max" = 10 | 847 | } | 848 | | 849 | GET Observe: 0 | 850 | coap://example.as.com/revoke/trl/ | 851 +--------------------------------------------->| 852 | | 853 |<---------------------------------------------+ 854 | 2.05 CONTENT Observe: 42 | 855 | Payload: [] | 856 | . | 857 | . | 858 | . | 859 | | 860 | (Access Tokens t1 and t2 issued | 861 | and successfully submitted to RS) | 862 | . | 863 | . | 864 | . | 865 | | 866 | (Access Token t1 is revoked) | 867 | | 868 |<---------------------------------------------+ 869 | 2.05 CONTENT Observe: 53 | 870 | Payload: [bstr.h(t1)] | 871 | | 872 | . | 873 | . | 874 | . | 875 | | 876 | (Access Token t2 is revoked) | 877 | | 878 | | 879 |<---------------------------------------------+ 880 | 2.05 CONTENT Observe: 64 | 881 | Payload: [bstr.h(t1), | 882 | bstr.h(t2)] | 883 | . | 884 | . | 885 | . | 886 | | 887 | (Access Token t1 expires) | 888 | | 889 |<---------------------------------------------+ 890 | 2.05 CONTENT Observe: 75 | 891 | Payload: [bstr.h(t2)] | 892 | . | 893 | . | 894 | . | 895 | | 896 | (Access Token t2 expires) | 897 | | 898 | X<-------------------------------------+ 899 | 2.05 CONTENT Observe: 86 | 900 | Payload: [] | 901 | . | 902 | . | 903 | . | 904 | (Enough time has passed since | 905 | the latest received notification) | 906 | | 907 | GET | 908 | coap://example.as.com/revoke/trl?diff=8 | 909 +--------------------------------------------->| 910 | | 911 |<---------------------------------------------+ 912 | 2.05 CONTENT | 913 | Payload: [ | 914 | [ [bstr.h(t2)], [] ], | 915 | [ [bstr.h(t1)], [] ], | 916 | [ [], [bstr.h(t2)] ], | 917 | [ [], [bstr.h(t1)] ] | 918 | ] | 919 | | 921 Figure 7: Interaction for Full Query with Observation and Diff Query 923 9. Security Considerations 925 Security considerations are inherited from the ACE framework for 926 Authentication and Authorization [I-D.ietf-ace-oauth-authz], from 927 [RFC8392] as to the usage of CWTs, from [RFC7519] as to the usage of 928 JWTs, from [RFC7641] as to the usage of CoAP Observe, and from 929 [RFC6920] with regards to resource naming through hashes. The 930 following considerations also apply. 932 The Authorization Server MUST ensure that each registered device can 933 access and retrieve only its pertaining portion of the TRL. To this 934 end, the Authorization Server can perform the required filtering 935 based on the authenticated identity of the registered device, i.e., a 936 (non-public) identifier that the Authorization Server can securely 937 relate to the registered device and the secure association they use 938 to communicate. 940 Disclosing any information about revoked Access Tokens to entities 941 other than the intended registered devices may result in privacy 942 concerns. Therefore, the Authorization Server MUST ensure that, 943 other than registered devices accessing their own pertaining portion 944 of the TRL, only authorized and authenticated administrators can 945 retrieve the full TRL. To this end, the Authorization Server may 946 rely on an access control list or similar. 948 If a registered device has many non-expired Access Tokens associated 949 to itself that are revoked, the pertaining portion of the TRL could 950 grow to a size bigger than what the registered device is prepared to 951 handle upon reception, especially if relying on a full query of the 952 TRL resource (see Section 5.1). This could be exploited by attackers 953 to negatively affect the behavior of a registered device. Short 954 expiration times could help reduce the size of a TRL, but an 955 Authorization Server SHOULD take measures to limit this size. 957 Most of the communication about revoked Access Tokens presented in 958 this specification relies on CoAP Observe Notifications sent from the 959 Authorization Server to a registered device. The suppression of 960 those notifications by an external attacker that has access to the 961 network would prevent registered devices from ever knowing that their 962 pertaining Access Tokens have been revoked. To avoid this, a 963 registered device SHOULD NOT rely solely on the CoAP Observe 964 notifications. In particular, a registered device SHOULD also 965 regularly poll the Authorization Server for the most current 966 information about revoked Access Tokens, by sending GET requests to 967 the TRL endpoint according to an application policy. 969 10. IANA Considerations 971 This document has the following actions for IANA. 973 10.1. Media Type Registrations 975 This specification registers the 'application/ace-trl+cbor' media 976 type for messages of the protocols defined in this document encoded 977 in CBOR. This registration follows the procedures specified in 978 [RFC6838]. 980 Type name: application 982 Subtype name: ace-trl+cbor 984 Required parameters: N/A 986 Optional parameters: N/A 988 Encoding considerations: Must be encoded as CBOR map containing the 989 protocol parameters defined in [this document]. 991 Security considerations: See Section 9 of this document. 993 Interoperability considerations: N/A 995 Published specification: [this document] 997 Applications that use this media type: The type is used by 998 Authorization Servers, Clients and Resource Servers that support the 999 notification of revoked Access Tokens, according to a Token 1000 Revocation List maintained by the Authorization Server as specified 1001 in [this document]. 1003 Fragment identifier considerations: N/A 1005 Additional information: N/A 1007 Person & email address to contact for further information: 1008 1010 Intended usage: COMMON 1012 Restrictions on usage: None 1014 Author: Marco Tiloca 1016 Change controller: IESG 1018 10.2. CoAP Content-Formats Registry 1020 This specification registers the following entry to the "CoAP 1021 Content-Formats" registry, within the "CoRE Parameters" registry: 1023 Media Type: application/ace-trl+cbor 1025 Encoding: - 1027 ID: TBD 1029 Reference: [this document] 1031 10.3. Token Revocation List Registry 1033 This specification establishes the "Token Revocation List" IANA 1034 Registry. The Registry has been created to use the "Expert Review" 1035 registration procedure [RFC8126]. Expert review guidelines are 1036 provided in Section 10.4. It should be noted that, in addition to 1037 the expert review, some portions of the Registry require a 1038 specification, potentially a Standards Track RFC, to be supplied as 1039 well. 1041 The columns of this Registry are: 1043 o Name: This is a descriptive name that enables easier reference to 1044 the item. The name MUST be unique. It is not used in the 1045 encoding. 1047 o CBOR Key: This is the value used as CBOR key of the item. These 1048 values MUST be unique. The value can be a positive integer or a 1049 negative integer. Different ranges of values use different 1050 registration policies [RFC8126]. Integer values from -256 to 255 1051 are designated as Standards Action. Integer values from -65536 to 1052 -257 and from 256 to 65535 are designated as Specification 1053 Required. Integer values greater than 65535 are designated as 1054 Expert Review. Integer values less than -65536 are marked as 1055 Private Use. 1057 o CBOR Type: This contains the CBOR type of the item, or a pointer 1058 to the registry that defines its type, when that depends on 1059 another item. 1061 o Reference: This contains a pointer to the public specification for 1062 the item. 1064 This Registry has been initially populated by the values in 1065 Appendix B.4.4. The Reference column for all of these entries refers 1066 to this document. 1068 10.4. Expert Review Instructions 1070 The IANA registry established in this document is defined as expert 1071 review. This section gives some general guidelines for what the 1072 experts should be looking for, but they are being designated as 1073 experts for a reason so they should be given substantial latitude. 1075 Expert reviewers should take into consideration the following points: 1077 o Point squatting should be discouraged. Reviewers are encouraged 1078 to get sufficient information for registration requests to ensure 1079 that the usage is not going to duplicate one that is already 1080 registered and that the point is likely to be used in deployments. 1081 The zones tagged as private use are intended for testing purposes 1082 and closed environments, code points in other ranges should not be 1083 assigned for testing. 1085 o Specifications are required for the standards track range of point 1086 assignment. Specifications should exist for specification 1087 required ranges, but early assignment before a specification is 1088 available is considered to be permissible. Specifications are 1089 needed for the first-come, first-serve range if they are expected 1090 to be used outside of closed environments in an interoperable way. 1091 When specifications are not provided, the description provided 1092 needs to have sufficient information to identify what the point is 1093 being used for. 1095 o Experts should take into account the expected usage of fields when 1096 approving point assignment. The fact that there is a range for 1097 standards track documents does not mean that a standards track 1098 document cannot have points assigned outside of that range. The 1099 length of the encoded value should be weighed against how many 1100 code points of that length are left, the size of device it will be 1101 used on, and the number of code points left that encode to that 1102 size. 1104 11. References 1106 11.1. Normative References 1108 [I-D.ietf-ace-oauth-authz] 1109 Seitz, L., Selander, G., Wahlstroem, E., Erdtman, S., and 1110 H. Tschofenig, "Authentication and Authorization for 1111 Constrained Environments (ACE) using the OAuth 2.0 1112 Framework (ACE-OAuth)", draft-ietf-ace-oauth-authz-37 1113 (work in progress), February 2021. 1115 [Named.Information.Hash.Algorithm] 1116 IANA, "Named Information Hash Algorithm", 1117 . 1120 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1121 Requirement Levels", BCP 14, RFC 2119, 1122 DOI 10.17487/RFC2119, March 1997, 1123 . 1125 [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", 1126 RFC 6749, DOI 10.17487/RFC6749, October 2012, 1127 . 1129 [RFC6838] Freed, N., Klensin, J., and T. Hansen, "Media Type 1130 Specifications and Registration Procedures", BCP 13, 1131 RFC 6838, DOI 10.17487/RFC6838, January 2013, 1132 . 1134 [RFC6920] Farrell, S., Kutscher, D., Dannewitz, C., Ohlman, B., 1135 Keranen, A., and P. Hallam-Baker, "Naming Things with 1136 Hashes", RFC 6920, DOI 10.17487/RFC6920, April 2013, 1137 . 1139 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 1140 Application Protocol (CoAP)", RFC 7252, 1141 DOI 10.17487/RFC7252, June 2014, 1142 . 1144 [RFC7519] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token 1145 (JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015, 1146 . 1148 [RFC7641] Hartke, K., "Observing Resources in the Constrained 1149 Application Protocol (CoAP)", RFC 7641, 1150 DOI 10.17487/RFC7641, September 2015, 1151 . 1153 [RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for 1154 Writing an IANA Considerations Section in RFCs", BCP 26, 1155 RFC 8126, DOI 10.17487/RFC8126, June 2017, 1156 . 1158 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 1159 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 1160 May 2017, . 1162 [RFC8259] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 1163 Interchange Format", STD 90, RFC 8259, 1164 DOI 10.17487/RFC8259, December 2017, 1165 . 1167 [RFC8392] Jones, M., Wahlstroem, E., Erdtman, S., and H. Tschofenig, 1168 "CBOR Web Token (CWT)", RFC 8392, DOI 10.17487/RFC8392, 1169 May 2018, . 1171 [RFC8610] Birkholz, H., Vigano, C., and C. Bormann, "Concise Data 1172 Definition Language (CDDL): A Notational Convention to 1173 Express Concise Binary Object Representation (CBOR) and 1174 JSON Data Structures", RFC 8610, DOI 10.17487/RFC8610, 1175 June 2019, . 1177 [RFC8949] Bormann, C. and P. Hoffman, "Concise Binary Object 1178 Representation (CBOR)", STD 94, RFC 8949, 1179 DOI 10.17487/RFC8949, December 2020, 1180 . 1182 11.2. Informative References 1184 [I-D.bormann-t2trg-stp] 1185 Bormann, C. and K. Hartke, "The Series Transfer Pattern 1186 (STP)", draft-bormann-t2trg-stp-03 (work in progress), 1187 April 2020. 1189 [RFC7009] Lodderstedt, T., Ed., Dronia, S., and M. Scurtescu, "OAuth 1190 2.0 Token Revocation", RFC 7009, DOI 10.17487/RFC7009, 1191 August 2013, . 1193 Appendix A. Usage of the Series Transfer Pattern 1195 This section discusses how the diff query of the TRL defined in 1196 Section 5.2 is a usage example of the Series Transfer Pattern defined 1197 in [I-D.bormann-t2trg-stp]. 1199 A diff query enables the transfer of a series of TRL updates, with 1200 the Authorization Server specifying U <= N_MAX diff entries as the U 1201 most recent updates to the portion of the TRL pertaining to a 1202 registered device. 1204 For each registered device, the Authorization Server maintains an 1205 update collection of maximum N_MAX items. Each time the TRL changes, 1206 the Authorization Server performs the following operations for each 1207 registered device. 1209 1. The Authorization Server considers the portion of the TRL 1210 pertaining to that registered device. If the TRL portion is not 1211 affected by this TRL update, the Authorization Server stops the 1212 processing for that registered device. 1214 2. Otherwise, the Authorization Server creates two sets 'trl_patch' 1215 of token hashes, i.e. one "removed" set and one "added" set, as 1216 related to this TRL update. 1218 3. The Authorization Server fills the two sets with the token hashes 1219 of the removed and added Access Tokens, respectively, from/to the 1220 TRL portion from step 1. 1222 4. The Authorization Server creates a new series item including the 1223 two sets from step 3, and adds the series item to the update 1224 collection associated to the registered device. 1226 When responding to a diff query request from a registered device (see 1227 Section 5.2), 'diff' is a subset of the collection associated to the 1228 requester, where each 'diff_entry' record is a series item from that 1229 collection. Note that 'diff' specifies the whole current collection 1230 when the value of U is equal to SIZE, i.e. the current number of 1231 series items in the collection. 1233 The value N of the 'diff' query parameter in the diff query request 1234 allows the requester and the Authorization Server to trade the amount 1235 of provided information with the latency of the information transfer. 1237 Since the collection associated to each registered device includes up 1238 to N_MAX series item, the Authorization Server deletes the oldest 1239 series item when a new one is generated and added to the end of the 1240 collection, due to a new TRL update pertaining to that registered 1241 device. This addresses the question "When can the server decide to 1242 no longer retain older items?" in Section 3.2 of 1243 [I-D.bormann-t2trg-stp]. 1245 Appendix B. Usage of the "Cursor" Pattern 1247 Building on Appendix A, this section describes how the diff query of 1248 the TRL defined in Section 5.2 can be further improved by using the 1249 "Cursor" pattern of the Series Transfer Pattern (see Section 3.3 of 1250 [I-D.bormann-t2trg-stp]). 1252 This has two benefits. First, the Authorization Server can avoid 1253 excessively big latencies when several diff entries have to be 1254 transferred, by delivering one adjacent subset at the time, in 1255 different diff query responses. Second, a requester can retrieve 1256 diff entries associated to TRL updates that, even if not the most 1257 recent ones, occurred after a TRL update indicated as checkpoint. 1259 To this end, each series item in an update collection is also 1260 associated with an unsigned integer 'index', with value the absolute 1261 counter of series items added to that collection minus 1. That is, 1262 the first series item added to a collection has 'index' with value 0. 1263 Then, the values of 'index' are used as cursor information. 1265 Furthermore, the Authorization Server defines an unsigned integer 1266 MAX_DIFF_BATCH <= N_MAX, specifying the maximum number of diff 1267 entries to be included in a single diff query response. If 1268 supporting diff queries, the Authorization Server SHOULD provide 1269 registered devices and administrators with the value of 1270 MAX_DIFF_BATCH, upon their registration (see Section 6). 1272 Finally, the full query and diff query exchanges defined in 1273 Section 5.1 and Section 5.2 are extended as follows. 1275 In particular, successul responses from the TRL endpoint MUST use the 1276 Content-Format "application/ace-trl+cbor" defined in Section 10.2 of 1277 this specification. 1279 B.1. Full Query Request 1281 No changes apply to what defined in Section 5.1. 1283 B.2. Full Query Response 1285 When sending a 2.05 (Content) response to a full query request (see 1286 Appendix B.1), the response payload includes a CBOR map with the 1287 following fields, whose CBOR labels are defined in Appendix B.4.4. 1289 o 'trl': this field MUST include a CBOR array of token hashes. The 1290 CBOR array is populated and formatted as defined in Section 5.1. 1292 o 'cursor': this field MUST include either the CBOR simple value 1293 Null or a CBOR unsigned integer. 1295 The CBOR simple value Null MUST be used to indicate that there are 1296 currently no TRL updates pertinent to the requester, i.e. the 1297 update collection for that requester is empty. This is the case 1298 from when the requester registers at the Authorization Server 1299 until a first update pertaining that requester occurs to the TRL. 1301 Otherwise, the field MUST include a CBOR unsigned integer, 1302 encoding the 'index' value of the last series item in the 1303 collection, as corresponding to the most recent update pertaining 1304 to the requester occurred to the TRL. 1306 B.3. Diff Query Request 1308 In addition to the query parameter 'diff' (see Section 5.2), the 1309 requester can specify a query parameter 'cursor', with value an 1310 unsigned integer. 1312 B.4. Diff Query Response 1314 The Authorization Server composes a response to a diff query request 1315 (see Appendix B.3) as follows, depending on the parameters specified 1316 in the request and on the current status of the update collection for 1317 the requester. 1319 B.4.1. Empty Collection 1321 If the collection associated to the requester has no elements, the 1322 Authorization Server returns a 2.05 (Content) diff query response. 1324 The response payload includes a CBOR map with the following fields, 1325 whose CBOR labels are defined in Appendix B.4.4. 1327 o 'diff': this field MUST include an empty CBOR array. 1329 o 'cursor': this field MUST include the CBOR simple value Null. 1331 o 'more': this fields MUST include the CBOR simple value False. 1333 B.4.2. Cursor Not Specified in the Diff Query Request 1335 If the update collection associated to the requester is not empty and 1336 the diff query request does not include the query parameter 'cursor', 1337 the Authorization Server returns a 2.05 (Content) diff query 1338 response. 1340 The response payload includes a CBOR map with the following fields, 1341 whose CBOR labels are defined in Appendix B.4.4. 1343 o 'diff': this field MUST include a CBOR array, containing L = 1344 min(U, MAX_DIFF_BATCH) diff entries. In particular, the CBOR 1345 array is populated as follows. 1347 * If U <= MAX_DIFF_BATCH, these diff entries are the last series 1348 items in the collection associated to the requester, 1349 corresponding to the L most recent TRL updates pertaining to 1350 the requester. 1352 * If U > MAX_DIFF_BATCH, these diff entries are the eldest of the 1353 last L series items in the collection associated to the 1354 requester, as corresponding to the first L of the U most recent 1355 TRL updates pertaining to the requester. 1357 The 'diff' CBOR array as well as the individual diff entries have 1358 the same format specified in Figure 4 and used for the reponse 1359 payload defined in Section 5.2. 1361 o 'cursor': this field MUST include a CBOR unsigned integer. This 1362 takes the 'index' value of the series element of the collection 1363 included as first diff entry in the 'diff' CBOR array. That is, 1364 it takes the 'index' value of the series item in the collection 1365 corresponding to the most recent update pertaining to the 1366 requester and returned in this diff query response. 1368 Note that 'cursor' takes the same 'index' value of the last series 1369 item in the collection when U <= MAX_DIFF_BATCH. 1371 o 'more': this field MUST include the CBOR simple value False if U 1372 <= MAX_DIFF_BATCH, or the CBOR simple value True otherwise. 1374 If 'more' has value True, the requester can send a follow-up diff 1375 query request including the query parameter 'cursor', with the 1376 same value of the 'cursor' field included in this diff query 1377 response. This would result in the Authorization Server 1378 transfering the following subset of series items as diff entries, 1379 i.e. resuming from where interrupted in the previous transfer. 1381 B.4.3. Cursor Specified in the Diff Query Request 1383 If the update collection associated to the requester is not empty and 1384 the diff query request includes the query parameter 'cursor' with 1385 value P, the Authorization Server proceeds as follows. 1387 o The Authorization Server MUST return a 4.00 (Bad Request) response 1388 in case the 'cursor' parameter specifies a value other than 0 or 1389 than a positive integer. 1391 o If no series item X with 'index' having value P is found in the 1392 collection associated to the requester, then that item has been 1393 previously removed from the history of updates for that requester 1394 (see Appendix A). In this case, the Authorization Server returns 1395 a 2.05 (Content) diff query response. 1397 The response payload includes a CBOR map with the following 1398 fields, whose CBOR labels are defined in Appendix B.4.4. 1400 * 'diff': this field MUST include an empty CBOR array. 1402 * 'cursor': this field MUST include the CBOR simple value Null. 1404 * 'more': this field MUST include the CBOR simple value True. 1406 With the combination ('cursor', 'more') = (Null, True), the 1407 Authorization Server is signaling that the update collection is in 1408 fact not empty, but that some series items have been lost due to 1409 their removal, including the item with 'index' value P that the 1410 requester wished to use as checkpoint. 1412 When receiving this diff query response, the requester should send 1413 a new full query request to the Authorization Server, in order to 1414 fully retrieve the current pertaining portion of the TRL. 1416 o If the series item X with 'index' having value P is found in the 1417 collection associated to the requester, the Authorization Server 1418 returns a 2.05 (Content) diff query response. 1420 The response payload includes a CBOR map with the following 1421 fields, whose CBOR labels are defined in Appendix B.4.4. 1423 * 'diff': this field MUST include a CBOR array, containing L = 1424 min(SUB_U, MAX_DIFF_BATCH) diff entries, where SUB_U = min(NUM, 1425 SUB_SIZE), and SUB_SIZE is the number of series items in the 1426 collection following the series item X. 1428 That is, these are the L updates pertaining to the requester 1429 that immediately follow the series item X indicated as 1430 checkpoint. In particular, the CBOR array is populated as 1431 follows. 1433 + If SUB_U <= MAX_DIFF_BATCH, these diff entries are the last 1434 series items in the collection associated to the requester, 1435 corresponding to the L most recent TRL updates pertaining to 1436 the requester. 1438 + If SUB_U > MAX_DIFF_BATCH, these diff entries are the eldest 1439 of the last L series items in the collection associated to 1440 the requester, corresponding to the first L of the SUB_U 1441 most recent TRL updates pertaining to the requester. 1443 The 'diff' CBOR array as well as the individual diff entries 1444 have the same format specified in Figure 4 and used for the 1445 reponse payload defined in Section 5.2. 1447 * 'cursor': this field MUST include a CBOR unsigned integer. In 1448 particular: 1450 + If L is equal to 0, i.e. the series item X is the last one 1451 in the collection, 'cursor' takes the same 'index' value of 1452 the last series item in the collection. 1454 + If L is different than 0, 'cursor' takes the 'index' value 1455 of the series element of the collection included as first 1456 diff entry in the 'diff' CBOR array. That is, it takes the 1457 'index' value of the series item in the collection 1458 corresponding to the most recent update pertaining to the 1459 requester and returned in this diff query response. 1461 Note that 'cursor' takes the same 'index' value of the last 1462 series item in the collection when SUB_U <= MAX_DIFF_BATCH. 1464 * 'more': this field MUST include the CBOR simple value False if 1465 SUB_U <= MAX_DIFF_BATCH, or the CBOR simple value True 1466 otherwise. 1468 If 'more' has value True, the requester can send a follow-up 1469 diff query request including the query parameter 'cursor', with 1470 the same value of the 'cursor' field specified in this diff 1471 query response. This would result in the Authorization Server 1472 transfering the following subset of series items as diff 1473 entries, i.e. resuming from where interrupted in the previous 1474 transfer. 1476 B.4.4. TRL Parameters 1478 This specification defines a number of fields used in the response to 1479 a diff query request to the TRL endpoint relying on the "Cursor" 1480 pattern, as defined in Appendix B. 1482 The table below summarizes them, and specifies the CBOR key to use 1483 instead of the full descriptive name. Note that the Content-Format 1484 "application/ace-trl+cbor" defined in Section 10.2 of this 1485 specification MUST be used when these fields are transported. 1487 +--------+----------+---------------------+-----------+ 1488 | Name | CBOR Key | CBOR Type | Reference | 1489 +--------+----------+---------------------+-----------+ 1490 | trl | TBD | array | [This | 1491 | | | | Document] | 1492 +--------+----------+---------------------+-----------+ 1493 | cursor | TBD | simple value null / | [This | 1494 | | | unsigned integer | Document] | 1495 +--------+----------+---------------------+-----------+ 1496 | diff | TBD | array | [This | 1497 | | | | Document] | 1498 +--------+----------+---------------------+-----------+ 1499 | more | TBD | simple value True | [This | 1500 | | | or False | Document] | 1501 +--------+----------+---------------------+-----------+ 1503 Acknowledgments 1505 The authors sincerely thank Carsten Bormann, Benjamin Kaduk, Jim 1506 Schaad, Goeran Selander and Travis Spencer for their comments and 1507 feedback. 1509 The work on this document has been partly supported by VINNOVA and 1510 the Celtic-Next project CRITISEC; and by the H2020 project SIFIS-Home 1511 (Grant agreement 952652). 1513 Authors' Addresses 1515 Marco Tiloca 1516 RISE AB 1517 Isafjordsgatan 22 1518 Kista SE-16440 Stockholm 1519 Sweden 1521 Email: marco.tiloca@ri.se 1522 Ludwig Seitz 1523 Combitech 1524 Djaeknegatan 31 1525 Malmoe SE-21135 Malmoe 1526 Sweden 1528 Email: ludwig.seitz@combitech.se 1530 Francesca Palombini 1531 Ericsson AB 1532 Torshamnsgatan 23 1533 Kista SE-16440 Stockholm 1534 Sweden 1536 Email: francesca.palombini@ericsson.com 1538 Sebastian Echeverria 1539 CMU SEI 1540 4500 Fifth Avenue 1541 Pittsburgh, PA 15213-2612 1542 United States of America 1544 Email: secheverria@sei.cmu.edu 1546 Grace Lewis 1547 CMU SEI 1548 4500 Fifth Avenue 1549 Pittsburgh, PA 15213-2612 1550 United States of America 1552 Email: glewis@sei.cmu.edu