idnits 2.17.1 draft-ietf-ace-revoked-token-notification-00.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 (26 November 2021) is 874 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 (-06) exists of draft-ietf-core-conditional-attributes-00 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: 30 May 2022 Combitech 6 F. Palombini 7 Ericsson AB 8 S. Echeverria 9 G. Lewis 10 CMU SEI 11 26 November 2021 13 Notification of Revoked Access Tokens in the Authentication and 14 Authorization for Constrained Environments (ACE) Framework 15 draft-ietf-ace-revoked-token-notification-00 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 Discussion Venues 32 This note is to be removed before publishing as an RFC. 34 Discussion of this document takes place on the Constrained RESTful 35 Environments Working Group mailing list (ace@ietf.org), which is 36 archived at https://mailarchive.ietf.org/arch/browse/ace/. 38 Source for this draft and an issue tracker can be found at 39 https://gitlab.com/crimson84/draft-tiloca-ace-revoked-token- 40 notification. 42 Status of This Memo 44 This Internet-Draft is submitted in full conformance with the 45 provisions of BCP 78 and BCP 79. 47 Internet-Drafts are working documents of the Internet Engineering 48 Task Force (IETF). Note that other groups may also distribute 49 working documents as Internet-Drafts. The list of current Internet- 50 Drafts is at https://datatracker.ietf.org/drafts/current/. 52 Internet-Drafts are draft documents valid for a maximum of six months 53 and may be updated, replaced, or obsoleted by other documents at any 54 time. It is inappropriate to use Internet-Drafts as reference 55 material or to cite them other than as "work in progress." 57 This Internet-Draft will expire on 30 May 2022. 59 Copyright Notice 61 Copyright (c) 2021 IETF Trust and the persons identified as the 62 document authors. All rights reserved. 64 This document is subject to BCP 78 and the IETF Trust's Legal 65 Provisions Relating to IETF Documents (https://trustee.ietf.org/ 66 license-info) in effect on the date of publication of this document. 67 Please review these documents carefully, as they describe your rights 68 and restrictions with respect to this document. Code Components 69 extracted from this document must include Simplified BSD License text 70 as described in Section 4.e of the Trust Legal Provisions and are 71 provided without warranty as described in the Simplified BSD License. 73 Table of Contents 75 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 76 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 4 77 2. Protocol Overview . . . . . . . . . . . . . . . . . . . . . . 6 78 3. Token Hash . . . . . . . . . . . . . . . . . . . . . . . . . 8 79 4. The TRL Resource . . . . . . . . . . . . . . . . . . . . . . 9 80 4.1. Update of the TRL Resource . . . . . . . . . . . . . . . 10 81 5. The TRL Endpoint . . . . . . . . . . . . . . . . . . . . . . 10 82 5.1. Full Query of the TRL . . . . . . . . . . . . . . . . . . 11 83 5.2. Diff Query of the TRL . . . . . . . . . . . . . . . . . . 12 84 6. Upon Registration . . . . . . . . . . . . . . . . . . . . . . 14 85 7. Notification of Revoked Tokens . . . . . . . . . . . . . . . 15 86 8. Interaction Examples . . . . . . . . . . . . . . . . . . . . 15 87 8.1. Full Query with Observation . . . . . . . . . . . . . . . 16 88 8.2. Diff Query with Observation . . . . . . . . . . . . . . . 18 89 8.3. Full Query with Observation and Additional Diff Query . . 19 90 9. Security Considerations . . . . . . . . . . . . . . . . . . . 22 91 10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 23 92 10.1. Media Type Registrations . . . . . . . . . . . . . . . . 23 93 10.2. CoAP Content-Formats Registry . . . . . . . . . . . . . 24 94 10.3. Token Revocation List Registry . . . . . . . . . . . . . 24 95 10.4. Expert Review Instructions . . . . . . . . . . . . . . . 25 96 11. References . . . . . . . . . . . . . . . . . . . . . . . . . 25 97 11.1. Normative References . . . . . . . . . . . . . . . . . . 25 98 11.2. Informative References . . . . . . . . . . . . . . . . . 27 99 Appendix A. Usage of the Series Transfer Pattern . . . . . . . . 27 100 Appendix B. Usage of the "Cursor" Pattern . . . . . . . . . . . 29 101 B.1. Full Query Request . . . . . . . . . . . . . . . . . . . 29 102 B.2. Full Query Response . . . . . . . . . . . . . . . . . . . 29 103 B.3. Diff Query Request . . . . . . . . . . . . . . . . . . . 30 104 B.4. Diff Query Response . . . . . . . . . . . . . . . . . . . 30 105 B.4.1. Empty Collection . . . . . . . . . . . . . . . . . . 30 106 B.4.2. Cursor Not Specified in the Diff Query Request . . . 30 107 B.4.3. Cursor Specified in the Diff Query Request . . . . . 31 108 B.4.4. TRL Parameters . . . . . . . . . . . . . . . . . . . 33 109 Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . 34 110 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 34 112 1. Introduction 114 Authentication and Authorization for Constrained Environments (ACE) 115 [I-D.ietf-ace-oauth-authz] is a framework that enforces access 116 control on IoT devices acting as Resource Servers. In order to use 117 ACE, both Clients and Resource Servers have to register with an 118 Authorization Server and become a registered device. Once 119 registered, a Client can send a request to the Authorization Server, 120 to obtain an Access Token for a Resource Server. For a Client to 121 access the Resource Server, the Client must present the issued Access 122 Token at the Resource Server, which then validates it before storing 123 it (see Section 5.10.1.1 of [I-D.ietf-ace-oauth-authz]). 125 Even though Access Tokens have expiration times, there are 126 circumstances by which an Access Token may need to be revoked before 127 its expiration time, such as: (1) a registered device has been 128 compromised, or is suspected of being compromised; (2) a registered 129 device is decommissioned; (3) there has been a change in the ACE 130 profile for a registered device; (4) there has been a change in 131 access policies for a registered device; and (5) there has been a 132 change in the outcome of policy evaluation for a registered device 133 (e.g., if policy assessment depends on dynamic conditions in the 134 execution environment, the user context, or the resource 135 utilization). 137 As discussed in Section 6.1 of [I-D.ietf-ace-oauth-authz], only 138 client-initiated revocation is currently specified [RFC7009] for 139 OAuth 2.0 [RFC6749], based on the assumption that Access Tokens in 140 OAuth are issued with a relatively short lifetime. However, this is 141 not expected to be the case for constrained, intermittently connected 142 devices, that need Access Tokens with relatively long lifetimes. 144 This document specifies a method for allowing registered devices to 145 access and possibly subscribe to a Token Revocation List (TRL) 146 resource on the Authorization Server, in order to get an updated list 147 of revoked, but yet not expired, pertaining Access Tokens. In 148 particular, registered devices can subscribe to the TRL at the 149 Authorization Server by using resource observation [RFC7641] for the 150 Constrained Application Protocol (CoAP) [RFC7252]. 152 Unlike in the case of token introspection (see Section 5.9 of 153 [I-D.ietf-ace-oauth-authz]), a registered device does not provide an 154 owned Access Token to the Authorization Server for inquiring about 155 its current state. Instead, registered devices simply obtain an 156 updated list of revoked, but yet not expired, pertaining Access 157 Tokens, as efficiently identified by corresponding hash values. 159 In fact, the benefits of this method are that it complements token 160 introspection, and it does not require any additional endpoints on 161 the registered devices. The only additional requirements for 162 registered devices are a request/response interaction with the 163 Authorization Server to access and possibly subscribe to the TRL (see 164 Section 2), and the lightweight computation of hash values as Token 165 identifiers (see Section 3). 167 1.1. Terminology 169 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 170 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 171 "OPTIONAL" in this document are to be interpreted as described in BCP 172 14 [RFC2119] [RFC8174] when, and only when, they appear in all 173 capitals, as shown here. 175 Readers are expected to be familiar with the terms and concepts 176 described in the ACE framework for Authentication and Authorization 177 [I-D.ietf-ace-oauth-authz], as well as with terms and concepts 178 related to CBOR Web Tokens (CWTs) [RFC8392], and JSON Web Tokens 179 (JWTs) [RFC7519]. The terminology for entities in the considered 180 architecture is defined in OAuth 2.0 [RFC6749]. In particular, this 181 includes Client, Resource Server, and Authorization Server. 183 Readers are also expected to be familiar with the terms and concepts 184 related to CBOR [RFC8949], JSON [RFC8259], the CoAP protocol 185 [RFC7252], CoAP Observe [RFC7641], and the use of hash functions to 186 name objects as defined in [RFC6920]. 188 Note that, unless otherwise indicated, the term "endpoint" is used 189 here following its OAuth definition, aimed at denoting resources such 190 as /token and /introspect at the Authorization Server, and /authz- 191 info at the Resource Server. This document does not use the CoAP 192 definition of "endpoint", which is "An entity participating in the 193 CoAP protocol." 195 This specification also refers to the following terminology. 197 * Token hash: identifier of an Access Token, in binary format 198 encoding. The token hash has no relation to other possibly used 199 token identifiers, such as the "cti" (CWT ID) claim of CBOR Web 200 Tokens (CWTs) [RFC8392]. 202 * Token Revocation List (TRL): a collection of token hashes, in 203 which the corresponding Access Tokens have been revoked but are 204 not expired yet. 206 * TRL resource: a resource on the Authorization Server, with a TRL 207 as its representation. 209 * TRL endpoint: an endpoint at the Authorization Server associated 210 to the TRL resource. The default name of the TRL endpoint in a 211 url-path is '/revoke/trl'. Implementations are not required to 212 use this name, and can define their own instead. 214 * Registered device: a device registered at the Authorization 215 Server, i.e., as a Client, or a Resource Server, or both. A 216 registered device acts as caller of the TRL endpoint. 218 * Administrator: entity authorized to get full access to the TRL at 219 the Authorization Server, and acting as caller of the TRL 220 endpoint. An administrator is not necessarily a registered device 221 as defined above, i.e., a Client requesting Access Tokens or a 222 Resource Server consuming Access Tokens. How the administrator 223 authorization is established and verified is out of the scope of 224 this specification. 226 * Pertaining Access Token: 228 - With reference to an administrator, an Access Token issued by 229 the Authorization Server. 231 - With reference to a registered device, an Access Token intended 232 to be owned by that device. An Access Token pertains to a 233 Client if the Authorization Server has issued the Access Token 234 and provided it to that Client. An Access Token pertains to a 235 Resource Server if the Authorization Server has issued the 236 Access Token to be consumed by that Resource Server. 238 2. Protocol Overview 240 This protocol defines how a CoAP-based Authorization Server informs 241 Clients and Resource Servers, i.e., registered devices, about 242 pertaining revoked Access Tokens. How the relationship between the 243 registered device and the Authorization Server is established is out 244 of the scope of this specification. 246 At a high level, the steps of this protocol are as follows. 248 * Upon startup, the Authorization Server creates a single TRL 249 resource. At any point in time, the TRL resource represents the 250 list of all revoked Access Tokens issued by the Authorization 251 Server that are not expired yet. 253 * When a device registers at the Authorization Server, it receives 254 the url-path to the TRL resource. 256 After the registration procedure is finished, the registered 257 device sends an Observation Request to that TRL resource as 258 described in [RFC7641], i.e., a GET request with an Observe option 259 set to 0 (register). By doing so, the registered device 260 effectively subscribes to the TRL resource, as interested to 261 receive notifications about its update. Upon receiving the 262 request, the Authorization Server adds the registered device to 263 the list of observers of the TRL resource. 265 At any time, the registered device can send a GET request to the 266 TRL endpoint. When doing so, it can request for: the current list 267 of pertaining revoked Access Tokens (see Section 5.1); or the most 268 recent TRL updates occurred over the list of pertaining revoked 269 Access Tokens (see Section 5.2). In either case, the registered 270 device may especially rely on an Observation Request for 271 subscribing to the TRL resource as discussed above. 273 * When an Access Token is revoked, the Authorization Server adds the 274 corresponding token hash to the TRL. Also, when a revoked Access 275 Token eventually expires, the Authorization Server removes the 276 corresponding token hash from the TRL. 278 In either case, after updating the TRL, the Authorization Server 279 sends Observe Notifications as per [RFC7641]. That is, an Observe 280 Notification is sent to each registered device subscribed to the 281 TRL resource and to which the Access Token pertains. 283 Depending on the specific subscription established through the 284 observation request, the notification provides the current updated 285 list of revoked Access Tokens in the portion of the TRL pertaining 286 to that device (see Section 5.1), or rather the most recent TRL 287 updates occurred over that list of pertaining revoked Access 288 Tokens (see Section 5.2). 290 Further Observe Notifications may be sent, consistently with 291 ongoing additional observations of the TRL resource. 293 * An administrator can access and subscribe to the TRL like a 294 registered device, while getting the full updated representation 295 of the TRL. 297 Figure 1 shows a high-level overview of the service provided by this 298 protocol. In particular, it shows the Observe Notifications sent by 299 the Authorization Server to one administrator and four registered 300 devices, upon revocation of the issued Access Tokens t1, t2 and t3, 301 with token hash th1, th2 and th3, respectively. Each dotted line 302 associated to a pair of registered devices indicates the Access Token 303 that they both own. 305 +----------------------+ 306 | Authorization Server | 307 +-----------o----------+ 308 revoke/trl | TRL: {th1,th2,th3} 309 | 310 +-----------------+------------+------------+------------+ 311 | | | | | 312 | th1,th2,th3 | th1,th2 | th1 | th3 | th2,th3 313 v v v v v 314 +---------------+ +----------+ +----------+ +----------+ +----------+ 315 | Administrator | | Client 1 | | Resource | | Client 2 | | Resource | 316 | | | | | Server 1 | | | | Server 2 | 317 +---------------+ +----------+ +----------+ +----------+ +----------+ 318 : : : : : : 319 : : t1 : : t3 : : 320 : :........: :............: : 321 : t2 : 322 :...........................................: 324 Figure 1: Protocol Overview 326 Section 8 provides examples of the protocol flow and message exchange 327 between the Authorization Server and a registered device. 329 3. Token Hash 331 The token hash of an Access Token is computed as follows. 333 1. The Authorization Server defines ENCODED_TOKEN, as the content of 334 the 'access_token' parameter in the Authorization Server response 335 (see Section 5.8.2 of [I-D.ietf-ace-oauth-authz]), where the 336 Access Token was included and provided to the requesting Client. 338 Note that the content of the 'access_token' parameter is either: 340 * A CBOR byte string, if the Access Token was transported using 341 CBOR. With reference to the example in Figure 2, and assuming 342 the string's length in bytes to be 119 (i.e., 0x77 in 343 hexadecimal), then ENCODED_TOKEN takes the bytes {0x58 0x77 344 0xd0 0x83 0x44 0xa1 ...}, i.e., the raw content of the 345 parameter 'access_token'. 347 * A text string, if the Access Token was transported using JSON. 348 With reference to the example in Figure 3, ENCODED_TOKEN takes 349 "2YotnFZFEjr1zCsicMWpAA", i.e., the raw content of the 350 parameter 'access_token'. 352 2. The Authorization Server defines HASH_INPUT as follows. 354 * If CBOR was used to transport the Access Token (as a CWT or 355 JWT), HASH_INPUT takes the same value of ENCODED_TOKEN. 357 * If JSON was used to transport the Access Token (as a CWT or 358 JWT), HASH_INPUT takes the serialization of ENCODED_TOKEN. 360 In either case, HASH_INPUT results in the binary 361 representation of the content of the 'access_token' parameter 362 from the Authorization Server response. 364 3. The Authorization Server generates a hash value of HASH_INPUT as 365 per Section 6 of [RFC6920]. The resulting output in binary 366 format is used as the token hash. Note that the used binary 367 format embeds the identifier of the used hash function, in the 368 first byte of the computed token hash. 370 The specifically used hash function MUST be collision-resistant 371 on byte-strings, and MUST be selected from the "Named Information 372 Hash Algorithm" Registry [Named.Information.Hash.Algorithm]. 374 The Authorization Server specifies the used hash function to 375 registered devices during their registration procedure (see 376 Section 6). 378 2.01 Created 379 Content-Format: application/ace+cbor 380 Max-Age: 85800 381 Payload: 382 { 383 access_token : h'd08344a1...' 384 (remainder of the Access Token omitted for brevity) 385 token_type : pop, 386 expires_in : 86400, 387 profile : coap_dtls, 388 (remainder of the response omitted for brevity) 389 } 391 Figure 2: Example of Authorization Server response using CBOR 393 HTTP/1.1 200 OK 394 Content-Type: application/json 395 Cache-Control: no-store 396 Pragma: no-cache 397 Payload: 398 { 399 "access_token" : "2YotnFZFEjr1zCsicMWpAA" 400 (remainder of the Access Token omitted for brevity) 401 "token_type" : "pop", 402 "expires_in" : 86400, 403 "profile" : "coap_dtls", 404 (remainder of the response omitted for brevity) 405 } 407 Figure 3: Example of Authorization Server response using JSON 409 4. The TRL Resource 411 Upon startup, the Authorization Server creates a single TRL resource, 412 encoded as a CBOR array. 414 Each element of the array is a CBOR byte string, with value the token 415 hash of an Access Token. The order of the token hashes in the CBOR 416 array is irrelevant, and the CBOR array MUST be treated as a set in 417 which the order has no significant meaning. 419 The TRL is initialized as empty, i.e., the initial content of the TRL 420 resource representation MUST be an empty CBOR array. 422 4.1. Update of the TRL Resource 424 The Authorization Server updates the TRL in the following two cases. 426 * When a non-expired Access Token is revoked, the token hash of the 427 Access Token is added to the TRL resource representation. That 428 is, a CBOR byte string with the token hash as its value is added 429 to the CBOR array used as TRL resource representation. 431 * When a revoked Access Token expires, the token hash of the Access 432 Token is removed from the TRL resource representation. That is, 433 the CBOR byte string with the token hash as its value is removed 434 from the CBOR array used as TRL resource representation. 436 5. The TRL Endpoint 438 Consistent with Section 6.5 of [I-D.ietf-ace-oauth-authz], all 439 communications between a caller of the TRL endpoint and the 440 Authorization Server MUST be encrypted, as well as integrity and 441 replay protected. Furthermore, responses from the Authorization 442 Server to the caller MUST be bound to the caller's request. 444 The Authorization Server MUST implement measures to prevent access to 445 the TRL endpoint by entities other than registered devices and 446 authorized administrators. 448 The TRL endpoint supports only the GET method, and allows two types 449 of query of the TRL. 451 * Full query: the Authorization Server returns the token hashes of 452 the revoked Access Tokens currently in the TRL and pertaining to 453 the requester. The Authorization Server MUST support this type of 454 query. The processing of a full query and the related response 455 format are defined in Section 5.1. 457 * Diff query: the Authorization Server returns a list of diff 458 entries. Each diff entry is related to one of the most recent 459 updates, in the portion of the TRL pertaining to the requester. 460 The Authorization Server MAY support this type of query. 462 The entry associated to one of such updates contains a list of 463 token hashes, such that: i) the corresponding revoked Access 464 Tokens pertain to the requester; and ii) they were added to or 465 removed from the TRL at that update. The processing of a diff 466 query and the related response format are defined in Section 5.2. 468 The TRL endpoint allows the following query parameter in a GET 469 request. 471 * 'pmax': if included, it follows the semantics defined in 472 Section 3.2.2 of [I-D.ietf-core-conditional-attributes]. This 473 query parameter is relevant only in case the GET request is 474 specifically an Observation Request, i.e., if it includes the CoAP 475 Observe option set to 0 (register). In such a case, this 476 parameter indicates the maximum time, in seconds, between two 477 consecutive notifications for the observation in question, 478 regardless whether the TRL resource has changed or not. 480 If the Observation Request does not include the 'pmax' parameter, 481 the maximum time to consider is up to the Authorization Server. 482 If the Observation Request includes the 'pmax' parameter, its 483 value MUST be greater than zero, otherwise the Authorization 484 Server MUST return a 4.00 (Bad Request) response. 486 If the GET request is not an Observation Request, the 487 Authorization Server MUST ignore the 'pmax' parameter, in case 488 this is included. 490 * 'diff': if included, it indicates to perform a diff query of the 491 TRL. Its value MUST be either: 493 - the integer 0, indicating that a (notification) response should 494 include as many diff entries as the Authorization Server can 495 provide in the response; or 497 - a positive integer greater than 0, indicating the maximum 498 number of diff entries that a (notification) response should 499 include. 501 5.1. Full Query of the TRL 503 In order to produce a (notification) response to a GET request asking 504 for a full query of the TRL, the Authorization Server performs the 505 following actions. 507 1. From the current TRL resource representation, the Authorization 508 Server builds a set HASHES, such that: 510 * If the requester is a registered device, HASHES specifies the 511 token hashes of the Access Tokens pertaining to that 512 registered device. The Authorization Server can use the 513 authenticated identity of the registered device to perform the 514 necessary filtering on the TRL resource representation. 516 * If the requester is an administrator, HASHES specifies all the 517 token hashes in the current TRL resource representation. 519 2. The Authorization Server sends a 2.05 (Content) Response to the 520 requester, with a CBOR array 'full' as payload. Each element of 521 the array specifies one of the token hashes from the set HASHES, 522 encoded as a CBOR byte string. 524 The order of the token hashes in the CBOR array is irrelevant, 525 i.e., the CBOR array MUST be treated as a set in which the order 526 has no significant meaning. 528 The CDDL definition [RFC8610] of the CBOR array 'full' specified as 529 payload in the response from the Authorization Server is provided 530 below. 532 token-hash = bytes 533 full = [* token-hash] 535 Figure 4: CDDL definition of the response payload following a 536 Full Query request to the TRL endpoint 538 5.2. Diff Query of the TRL 540 In order to produce a (notification) response to a GET request asking 541 for a diff query of the TRL, the Authorization Server performs the 542 following actions. 544 1. The Authorization Server defines the positive integer NUM. If 545 the value N specified in the query parameter 'diff' of the GET 546 request is equal to 0 or greater than a pre-defined positive 547 integer N_MAX, then NUM takes the value of N_MAX. Otherwise, NUM 548 takes N. 550 2. The Authorization Server prepares U = min(NUM, SIZE) diff 551 entries, where SIZE <= N_MAX is the number of TRL updates 552 pertaining to the requester and currently stored at the 553 Authorization Server. That is, the diff entries are related to 554 the U most recent TRL updates pertaining to the requester. In 555 particular, the first entry refers to the most recent of such 556 updates, the second entry refers to the second from last of such 557 updates, and so on. 559 Each diff entry is a CBOR array 'diff-entry', which includes the 560 following two elements. 562 * The first element is a CBOR array 'removed'. Each element of 563 the array is a CBOR byte string, with value the token hash of 564 an Access Token such that: it pertained to the requester; and 565 it was removed from the TRL during the update associated to 566 the diff entry. 568 * The second element is a CBOR array 'added'. Each element of 569 the array is a CBOR byte string, with value the token hash of 570 an Access Token such that: it pertains to the requester; and 571 it was added to the TRL during the update associated to the 572 diff entry. 574 The order of the token hashes in the CBOR arrays 'removed' and 575 'added' is irrelevant. That is, the CBOR arrays 'removed' and 576 'added' MUST be treated as a set in which the order of elements 577 has no significant meaning. 579 3. The Authorization Server prepares a 2.05 (Content) Response for 580 the requester, with a CBOR array 'diff' of U elements as payload. 581 Each element of the CBOR array 'diff' specifies one of the CBOR 582 arrays 'diff-entry' prepared at step 2 as diff entries. 584 Within the CBOR array 'diff', the CBOR arrays 'diff-entry' MUST 585 be sorted to reflect the corresponding updates to the TRL in 586 reverse chronological order. That is, the first 'diff-entry' 587 element of 'diff' relates to the most recent update to the 588 portion of the TRL pertaining to the requester. The second 589 'diff-entry' element of 'diff' relates to the second from last 590 most recent update to that portion, and so on. 592 The CDDL definition [RFC8610] of the CBOR array 'diff' specified as 593 payload in the response from the Authorization Server is provided 594 below. 596 token-hash = bytes 597 trl-patch = [* token-hash] 598 diff-entry = [removed: trl-patch, added: trl-patch] 599 diff = [* diff-entry] 601 Figure 5: CDDL definition of the response payload following a 602 Diff Query request to the TRL endpoint 604 If the Authorization Server supports diff queries: 606 * The Authorization Server MUST return a 4.00 (Bad Request) response 607 in case the 'diff' parameter specifies a value other than 0 or 608 than a positive integer. 610 * The Authorization Server MUST keep track of N_MAX most recent 611 updates to the portion of the TRL that pertains to each caller of 612 the TRL endpoint. The particular method to achieve this is 613 implementation-specific. 615 * When SIZE is equal to N_MAX, and a new TRL update occurs as 616 pertaining to a registered device, the Authorization Server MUST 617 first delete the oldest stored update for that device, before 618 storing this latest update as the most recent one for that device. 620 * The Authorization Server SHOULD provide registered devices and 621 administrators with the value of N_MAX, upon their registration 622 (see Section 6). 624 If the Authorization Server does not support diff queries, it 625 proceeds as when processing a full query (see Section 5.1). 627 Appendix A discusses how the diff query of the TRL is in fact a usage 628 example of the Series Transfer Pattern defined in 629 [I-D.bormann-t2trg-stp]. 631 Appendix B discusses how the diff query of the TRL can be further 632 improved by using the "Cursor" pattern defined in Section 3.3 of 633 [I-D.bormann-t2trg-stp]. 635 6. Upon Registration 637 During the registration process at the Authorization Server, an 638 administrator or a registered device receives the following 639 information as part of the registration response. 641 * The url-path to the TRL endpoint at the Authorization Server. 643 * The hash function used to compute token hashes. This is specified 644 as an integer or a text string, taking value from the "ID" or 645 "Hash Name String" column of the "Named Information Hash 646 Algorithm" Registry [Named.Information.Hash.Algorithm], 647 respectively. 649 * Optionally, a positive integer N_MAX, if the Authorization Server 650 supports diff queries of the TRL resource (see Section 5.2). 652 After the registration procedure is finished, the administrator or 653 registered device performs a GET request to the TRL resource, 654 including the CoAP Observe option set to 0 (register), in order to 655 start an observation of the TRL resource at the Authorization Server, 656 as per Section 3.1 of [RFC7641]. The GET request can express the 657 wish for a full query (see Section 5.1) or a diff query (see 658 Section 5.2) of the TRL. 660 In case the request is successfully processed, The Authorization 661 Server replies using the CoAP response code 2.05 (Content) and 662 including the CoAP Observe option in the response. The payload of 663 the response is formatted as defined in Section 5.1 or in 664 Section 5.2, in case the GET request was for a full query or a diff 665 query of the TRL, respectively. 667 Further details about the registration process at the Authorization 668 Server are out of scope for this specification. Note that the 669 registration process is also out of the scope of the ACE framework 670 for Authentication and Authorization (see Section 5.5 of 671 [I-D.ietf-ace-oauth-authz]). 673 7. Notification of Revoked Tokens 675 When the TRL is updated (see Section 4.1), the Authorization Server 676 sends Observe Notifications to the observers of the TRL resource. 677 Observe Notifications are sent as per Section 4.2 of [RFC7641]. 679 If the 'pmax' query parameter was specified in the Observation 680 Request starting an observation (see Section 5), the Authorization 681 Server might accordingly send additional Observe Notifications to the 682 associated observer. That is, the Authorization Server ensures that 683 no more than pmax seconds elapse between two consecutive 684 notifications sent to that observer, regardless whether the TRL 685 resource has changed or not. If the 'pmax' query parameter was not 686 specified in the Observation Request, a possible maximum time to 687 consider is up to the Authorization Server. 689 The payload of each Observe Notification is formatted as defined in 690 Section 5.1 or in Section 5.2, in case the original Observation 691 Request was for a full query or a diff query of the TRL, 692 respectively. 694 Furthermore, an administrator or a registered device can send 695 additional GET requests to the TRL endpoint at any time, in order to 696 retrieve the token hashes of the pertaining revoked Access Tokens. 697 When doing so, the caller of the TRL endpoint can perform a full 698 query (see Section 5.1) or a diff query (see Section 5.2). 700 8. Interaction Examples 702 This section provides examples of interactions between a Resource 703 Server RS as registered device and an Authorization Server AS. The 704 Authorization Server supports both full query and diff query of the 705 TRL, as defined in Section 5.1 and Section 5.2, respectively. 707 The details of the registration process are omitted, but it is 708 assumed that the Resource Server sends an unspecified payload to the 709 Authorization Server, which replies with a 2.01 (Created) response. 711 The payload of the registration response is a CBOR map, which 712 includes the following entries: 714 * a "trl" parameter, specifying the path of the TRL resource; 716 * a "trl_hash" parameter, specifying the hash function used to 717 computed token hashes as defined in Section 3; 719 * an "n_max" parameter, specifying the value of N_MAX, i.e., the 720 maximum number of TRL updates pertaining to each registered device 721 that the Authorization Server retains for that device (see 722 Section 5.2); 724 * possible further parameters related to the registration process. 726 Furthermore, 'h(x)' refers to the hash function used to compute the 727 token hashes, as defined in Section 3 of this specification and 728 according to [RFC6920]. Assuming the usage of CWTs transported in 729 CBOR, 'bstr.h(t1)' and 'bstr.h(t2)' denote the byte-string 730 representations of the token hashes for the Access Tokens t1 and t2, 731 respectively. 733 8.1. Full Query with Observation 735 Figure 6 shows an interaction example considering a CoAP observation 736 and a full query of the TRL. 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/ | 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 | | 770 | (Access Token t1 is revoked) | 771 | | 772 |<--------------------------------------+ 773 | 2.05 CONTENT Observe: 53 | 774 | Payload: [bstr.h(t1)] | 775 | . | 776 | . | 777 | . | 778 | | 779 | (Access Token t2 is revoked) | 780 | | 781 |<--------------------------------------+ 782 | 2.05 CONTENT Observe: 64 | 783 | Payload: [bstr.h(t1), | 784 | bstr.h(t2)] | 785 | . | 786 | . | 787 | . | 788 | | 789 | (Access Token t1 expires) | 790 | | 791 |<--------------------------------------+ 792 | 2.05 CONTENT Observe: 75 | 793 | Payload: [bstr.h(t2)] | 794 | . | 795 | . | 796 | . | 797 | | 798 | (Access Token t2 expires) | 799 | | 800 |<--------------------------------------+ 801 | 2.05 CONTENT Observe: 86 | 802 | Payload: [] | 803 | | 805 Figure 6: Interaction for Full Query with Observation 807 8.2. Diff Query with Observation 809 Figure 7 shows an interaction example considering a CoAP observation 810 and a diff query of the TRL. 812 The Resource Server indicates N=3 as value of the query parameter 813 "diff", i.e., as the maximum number of diff entries to be specified 814 in a response from the Authorization Server. 816 RS AS 817 | | 818 | Registration: POST | 819 +--------------------------------------------->| 820 | | 821 |<---------------------------------------------+ 822 | 2.01 CREATED | 823 | Payload: { | 824 | ... | 825 | "trl" = "revoke/trl", | 826 | "trl_hash" = "sha-256", | 827 | "n_max" = 10 | 828 | } | 829 | | 830 | GET Observe: 0 | 831 | coap://example.as.com/revoke/trl?diff=3 | 832 +--------------------------------------------->| 833 | | 834 |<---------------------------------------------+ 835 | 2.05 CONTENT Observe: 42 | 836 | Payload: [] | 837 | . | 838 | . | 839 | . | 840 | | 841 | (Access Tokens t1 and t2 issued | 842 | and successfully submitted to RS) | 843 | . | 844 | . | 845 | . | 846 | | 847 | (Access Token t1 is revoked) | 848 | | 849 |<---------------------------------------------+ 850 | 2.05 CONTENT Observe: 53 | 851 | Payload: [ | 852 | [ [], [bstr.h(t1)] ] | 853 | ] | 854 | | 855 | | 856 | . | 857 | . | 858 | . | 859 | | 860 | (Access Token t2 is revoked) | 861 | | 862 |<---------------------------------------------+ 863 | 2.05 CONTENT Observe: 64 | 864 | Payload: [ | 865 | [ [], [bstr.h(t2)] ], | 866 | [ [], [bstr.h(t1)] ] | 867 | ] | 868 | . | 869 | . | 870 | . | 871 | | 872 | (Access Token t1 expires) | 873 | | 874 |<---------------------------------------------+ 875 | 2.05 CONTENT Observe: 75 | 876 | Payload: [ | 877 | [ [bstr.h(t1)], [] ], | 878 | [ [], [bstr.h(t2)] ], | 879 | [ [], [bstr.h(t1)] ] | 880 | ] | 881 | . | 882 | . | 883 | . | 884 | | 885 | (Access Token t2 expires) | 886 | | 887 |<---------------------------------------------+ 888 | 2.05 CONTENT Observe: 86 | 889 | Payload: [ | 890 | [ [bstr.h(t2)], [] ], | 891 | [ [bstr.h(t1)], [] ], | 892 | [ [], [bstr.h(t2)] ] | 893 | ] | 894 | | 896 Figure 7: Interaction for Diff Query with Observation 898 8.3. Full Query with Observation and Additional Diff Query 900 Figure 8 shows an interaction example considering a CoAP observation 901 and a full query of the TRL. 903 The example also considers one of the notifications from the 904 Authorization Server to get lost in transmission, and thus not 905 reaching the Resource Server. 907 When this happens, and after a waiting time defined by the 908 application has elapsed, the Resource Server sends a GET request with 909 no observation to the Authorization Server, to perform a diff query 910 of the TRL. The Resource Server indicates N=8 as value of the query 911 parameter "diff", i.e., as the maximum number of diff entries to be 912 specified in a response from the Authorization Server. 914 RS AS 915 | | 916 | Registration: POST | 917 +--------------------------------------------->| 918 | | 919 |<---------------------------------------------+ 920 | 2.01 CREATED | 921 | Payload: { | 922 | ... | 923 | "trl" = "revoke/trl", | 924 | "trl_hash" = "sha-256", | 925 | "n_max" = 10 | 926 | } | 927 | | 928 | GET Observe: 0 | 929 | coap://example.as.com/revoke/trl/ | 930 +--------------------------------------------->| 931 | | 932 |<---------------------------------------------+ 933 | 2.05 CONTENT Observe: 42 | 934 | Payload: [] | 935 | . | 936 | . | 937 | . | 938 | | 939 | (Access Tokens t1 and t2 issued | 940 | and successfully submitted to RS) | 941 | . | 942 | . | 943 | . | 944 | | 945 | (Access Token t1 is revoked) | 946 | | 947 |<---------------------------------------------+ 948 | 2.05 CONTENT Observe: 53 | 949 | Payload: [bstr.h(t1)] | 950 | | 951 | . | 952 | . | 953 | . | 954 | | 955 | (Access Token t2 is revoked) | 956 | | 957 |<---------------------------------------------+ 958 | 2.05 CONTENT Observe: 64 | 959 | Payload: [bstr.h(t1), | 960 | bstr.h(t2)] | 961 | . | 962 | . | 963 | . | 964 | | 965 | (Access Token t1 expires) | 966 | | 967 |<---------------------------------------------+ 968 | 2.05 CONTENT Observe: 75 | 969 | Payload: [bstr.h(t2)] | 970 | . | 971 | . | 972 | . | 973 | | 974 | (Access Token t2 expires) | 975 | | 976 | X<-------------------------------------+ 977 | 2.05 CONTENT Observe: 86 | 978 | Payload: [] | 979 | . | 980 | . | 981 | . | 982 | | 983 | (Enough time has passed since | 984 | the latest received notification) | 985 | | 986 | GET | 987 | coap://example.as.com/revoke/trl?diff=8 | 988 +--------------------------------------------->| 989 | | 990 |<---------------------------------------------+ 991 | 2.05 CONTENT | 992 | Payload: [ | 993 | [ [bstr.h(t2)], [] ], | 994 | [ [bstr.h(t1)], [] ], | 995 | [ [], [bstr.h(t2)] ], | 996 | [ [], [bstr.h(t1)] ] | 997 | ] | 998 | | 1000 Figure 8: Interaction for Full Query with Observation and Diff Query 1002 9. Security Considerations 1004 Security considerations are inherited from the ACE framework for 1005 Authentication and Authorization [I-D.ietf-ace-oauth-authz], from 1006 [RFC8392] as to the usage of CWTs, from [RFC7519] as to the usage of 1007 JWTs, from [RFC7641] as to the usage of CoAP Observe, and from 1008 [RFC6920] with regard to resource naming through hashes. The 1009 following considerations also apply. 1011 The Authorization Server MUST ensure that each registered device can 1012 access and retrieve only its pertaining portion of the TRL. To this 1013 end, the Authorization Server can perform the required filtering 1014 based on the authenticated identity of the registered device, i.e., a 1015 (non-public) identifier that the Authorization Server can securely 1016 relate to the registered device and the secure association they use 1017 to communicate. 1019 Disclosing any information about revoked Access Tokens to entities 1020 other than the intended registered devices may result in privacy 1021 concerns. Therefore, the Authorization Server MUST ensure that, 1022 other than registered devices accessing their own pertaining portion 1023 of the TRL, only authorized and authenticated administrators can 1024 retrieve the full TRL. To this end, the Authorization Server may 1025 rely on an access control list or similar. 1027 If a registered device has many non-expired Access Tokens associated 1028 to itself that are revoked, the pertaining portion of the TRL could 1029 grow to a size bigger than what the registered device is prepared to 1030 handle upon reception, especially if relying on a full query of the 1031 TRL resource (see Section 5.1). This could be exploited by attackers 1032 to negatively affect the behavior of a registered device. Issuing 1033 Access Tokens with not too long expiration time could help reduce the 1034 size of a TRL, but an Authorization Server SHOULD take measures to 1035 limit this size. 1037 Most of the communication about revoked Access Tokens presented in 1038 this specification relies on CoAP Observe Notifications sent from the 1039 Authorization Server to a registered device. The suppression of 1040 those notifications by an external attacker that has access to the 1041 network would prevent registered devices from ever knowing that their 1042 pertaining Access Tokens have been revoked. To avoid this, a 1043 registered device SHOULD NOT rely solely on the CoAP Observe 1044 notifications. In particular, a registered device SHOULD also 1045 regularly poll the Authorization Server for the most current 1046 information about revoked Access Tokens, by sending GET requests to 1047 the TRL endpoint according to a related application policy. 1049 10. IANA Considerations 1051 This document has the following actions for IANA. 1053 10.1. Media Type Registrations 1055 IANA is asked to register the 'application/ace-trl+cbor' media type 1056 for messages of the protocols defined in this document encoded in 1057 CBOR. This registration follows the procedures specified in 1058 [RFC6838]. 1060 Type name: application 1062 Subtype name: ace-trl+cbor 1064 Required parameters: N/A 1066 Optional parameters: N/A 1068 Encoding considerations: Must be encoded as CBOR map containing the 1069 protocol parameters defined in [this document]. 1071 Security considerations: See Section 9 of this document. 1073 Interoperability considerations: N/A 1075 Published specification: [this document] 1077 Applications that use this media type: The type is used by 1078 Authorization Servers, Clients and Resource Servers that support the 1079 notification of revoked Access Tokens, according to a Token 1080 Revocation List maintained by the Authorization Server as specified 1081 in [this document]. 1083 Fragment identifier considerations: N/A 1085 Additional information: N/A 1087 Person & email address to contact for further information: 1088 1090 Intended usage: COMMON 1092 Restrictions on usage: None 1094 Author: Marco Tiloca 1096 Change controller: IESG 1098 10.2. CoAP Content-Formats Registry 1100 IANA is asked to add the following entry to the "CoAP Content- 1101 Formats" registry within the "CoRE Parameters" registry group. 1103 Media Type: application/ace-trl+cbor 1105 Encoding: - 1107 ID: TBD 1109 Reference: [this document] 1111 10.3. Token Revocation List Registry 1113 This specification establishes the "Token Revocation List" IANA 1114 registry. The registry has been created to use the "Expert Review" 1115 registration procedure [RFC8126]. Expert review guidelines are 1116 provided in Section 10.4. It should be noted that, in addition to 1117 the expert review, some portions of the registry require a 1118 specification, potentially a Standards Track RFC, to be supplied as 1119 well. 1121 The columns of this registry are: 1123 * Name: This is a descriptive name that enables easier reference to 1124 the item. The name MUST be unique. It is not used in the 1125 encoding. 1127 * CBOR Value: This is the value used as CBOR abbreviation of the 1128 item. These values MUST be unique. The value can be a positive 1129 integer or a negative integer. Different ranges of values use 1130 different registration policies [RFC8126]. Integer values from 1131 -256 to 255 are designated as Standards Action. Integer values 1132 from -65536 to -257 and from 256 to 65535 are designated as 1133 Specification Required. Integer values greater than 65535 are 1134 designated as Expert Review. Integer values less than -65536 are 1135 marked as Private Use. 1137 * CBOR Type: This contains the CBOR type of the item, or a pointer 1138 to the registry that defines its type, when that depends on 1139 another item. 1141 * Reference: This contains a pointer to the public specification for 1142 the item. 1144 This registry has been initially populated with the values from 1145 Figure 9 in Appendix B.4.4. 1147 10.4. Expert Review Instructions 1149 The IANA registry established in this document is defined as expert 1150 review. This section gives some general guidelines for what the 1151 experts should be looking for, but they are being designated as 1152 experts for a reason so they should be given substantial latitude. 1154 Expert reviewers should take into consideration the following points: 1156 * Point squatting should be discouraged. Reviewers are encouraged 1157 to get sufficient information for registration requests to ensure 1158 that the usage is not going to duplicate one that is already 1159 registered and that the point is likely to be used in deployments. 1160 The zones tagged as private use are intended for testing purposes 1161 and closed environments, code points in other ranges should not be 1162 assigned for testing. 1164 * Specifications are required for the standards track range of point 1165 assignment. Specifications should exist for specification 1166 required ranges, but early assignment before a specification is 1167 available is considered to be permissible. Specifications are 1168 needed for the first-come, first-serve range if they are expected 1169 to be used outside of closed environments in an interoperable way. 1170 When specifications are not provided, the description provided 1171 needs to have sufficient information to identify what the point is 1172 being used for. 1174 * Experts should take into account the expected usage of fields when 1175 approving point assignment. The fact that there is a range for 1176 standards track documents does not mean that a standards track 1177 document cannot have points assigned outside of that range. The 1178 length of the encoded value should be weighed against how many 1179 code points of that length are left, the size of device it will be 1180 used on, and the number of code points left that encode to that 1181 size. 1183 11. References 1185 11.1. Normative References 1187 [I-D.ietf-ace-oauth-authz] 1188 Seitz, L., Selander, G., Wahlstroem, E., Erdtman, S., and 1189 H. Tschofenig, "Authentication and Authorization for 1190 Constrained Environments (ACE) using the OAuth 2.0 1191 Framework (ACE-OAuth)", Work in Progress, Internet-Draft, 1192 draft-ietf-ace-oauth-authz-46, 8 November 2021, 1193 . 1196 [Named.Information.Hash.Algorithm] 1197 IANA, "Named Information Hash Algorithm", 1198 . 1201 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1202 Requirement Levels", BCP 14, RFC 2119, 1203 DOI 10.17487/RFC2119, March 1997, 1204 . 1206 [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", 1207 RFC 6749, DOI 10.17487/RFC6749, October 2012, 1208 . 1210 [RFC6838] Freed, N., Klensin, J., and T. Hansen, "Media Type 1211 Specifications and Registration Procedures", BCP 13, 1212 RFC 6838, DOI 10.17487/RFC6838, January 2013, 1213 . 1215 [RFC6920] Farrell, S., Kutscher, D., Dannewitz, C., Ohlman, B., 1216 Keranen, A., and P. Hallam-Baker, "Naming Things with 1217 Hashes", RFC 6920, DOI 10.17487/RFC6920, April 2013, 1218 . 1220 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 1221 Application Protocol (CoAP)", RFC 7252, 1222 DOI 10.17487/RFC7252, June 2014, 1223 . 1225 [RFC7519] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token 1226 (JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015, 1227 . 1229 [RFC7641] Hartke, K., "Observing Resources in the Constrained 1230 Application Protocol (CoAP)", RFC 7641, 1231 DOI 10.17487/RFC7641, September 2015, 1232 . 1234 [RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for 1235 Writing an IANA Considerations Section in RFCs", BCP 26, 1236 RFC 8126, DOI 10.17487/RFC8126, June 2017, 1237 . 1239 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 1240 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 1241 May 2017, . 1243 [RFC8259] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 1244 Interchange Format", STD 90, RFC 8259, 1245 DOI 10.17487/RFC8259, December 2017, 1246 . 1248 [RFC8392] Jones, M., Wahlstroem, E., Erdtman, S., and H. Tschofenig, 1249 "CBOR Web Token (CWT)", RFC 8392, DOI 10.17487/RFC8392, 1250 May 2018, . 1252 [RFC8610] Birkholz, H., Vigano, C., and C. Bormann, "Concise Data 1253 Definition Language (CDDL): A Notational Convention to 1254 Express Concise Binary Object Representation (CBOR) and 1255 JSON Data Structures", RFC 8610, DOI 10.17487/RFC8610, 1256 June 2019, . 1258 [RFC8949] Bormann, C. and P. Hoffman, "Concise Binary Object 1259 Representation (CBOR)", STD 94, RFC 8949, 1260 DOI 10.17487/RFC8949, December 2020, 1261 . 1263 11.2. Informative References 1265 [I-D.bormann-t2trg-stp] 1266 Bormann, C. and K. Hartke, "The Series Transfer Pattern 1267 (STP)", Work in Progress, Internet-Draft, draft-bormann- 1268 t2trg-stp-03, 7 April 2020, 1269 . 1272 [I-D.ietf-core-conditional-attributes] 1273 Koster, M. and B. Silverajan, "Conditional Attributes for 1274 Constrained RESTful Environments", Work in Progress, 1275 Internet-Draft, draft-ietf-core-conditional-attributes-00, 1276 12 July 2021, . 1279 [RFC7009] Lodderstedt, T., Ed., Dronia, S., and M. Scurtescu, "OAuth 1280 2.0 Token Revocation", RFC 7009, DOI 10.17487/RFC7009, 1281 August 2013, . 1283 Appendix A. Usage of the Series Transfer Pattern 1285 This section discusses how the diff query of the TRL defined in 1286 Section 5.2 is a usage example of the Series Transfer Pattern defined 1287 in [I-D.bormann-t2trg-stp]. 1289 A diff query enables the transfer of a series of TRL updates, with 1290 the Authorization Server specifying U <= N_MAX diff entries as the U 1291 most recent updates to the portion of the TRL pertaining to a 1292 registered device. 1294 For each registered device, the Authorization Server maintains an 1295 update collection of maximum N_MAX items. Each time the TRL changes, 1296 the Authorization Server performs the following operations for each 1297 registered device. 1299 1. The Authorization Server considers the portion of the TRL 1300 pertaining to that registered device. If the TRL portion is not 1301 affected by this TRL update, the Authorization Server stops the 1302 processing for that registered device. 1304 2. Otherwise, the Authorization Server creates two sets 'trl_patch' 1305 of token hashes, i.e., one "removed" set and one "added" set, as 1306 related to this TRL update. 1308 3. The Authorization Server fills the two sets with the token hashes 1309 of the removed and added Access Tokens, respectively, from/to the 1310 TRL portion from step 1. 1312 4. The Authorization Server creates a new series item including the 1313 two sets from step 3, and adds the series item to the update 1314 collection associated to the registered device. 1316 When responding to a diff query request from a registered device (see 1317 Section 5.2), 'diff' is a subset of the collection associated to the 1318 requester, where each 'diff_entry' record is a series item from that 1319 collection. Note that 'diff' specifies the whole current collection 1320 when the value of U is equal to SIZE, i.e., the current number of 1321 series items in the collection. 1323 The value N of the 'diff' query parameter in the diff query request 1324 allows the requester and the Authorization Server to trade the amount 1325 of provided information with the latency of the information transfer. 1327 Since the collection associated to each registered device includes up 1328 to N_MAX series item, the Authorization Server deletes the oldest 1329 series item when a new one is generated and added to the end of the 1330 collection, due to a new TRL update pertaining to that registered 1331 device. This addresses the question "When can the server decide to 1332 no longer retain older items?" in Section 3.2 of 1333 [I-D.bormann-t2trg-stp]. 1335 Appendix B. Usage of the "Cursor" Pattern 1337 Building on Appendix A, this section describes how the diff query of 1338 the TRL defined in Section 5.2 can be further improved by using the 1339 "Cursor" pattern of the Series Transfer Pattern (see Section 3.3 of 1340 [I-D.bormann-t2trg-stp]). 1342 This has two benefits. First, the Authorization Server can avoid 1343 excessively big latencies when several diff entries have to be 1344 transferred, by delivering one adjacent subset at the time, in 1345 different diff query responses. Second, a requester can retrieve 1346 diff entries associated to TRL updates that, even if not the most 1347 recent ones, occurred after a TRL update indicated as reference 1348 point. 1350 To this end, each series item in an update collection is also 1351 associated to an unsigned integer 'index', with value the absolute 1352 counter of series items added to that collection minus 1. That is, 1353 the first series item added to a collection has 'index' with value 0. 1354 Then, the values of 'index' are used as cursor information. 1356 Furthermore, the Authorization Server defines an unsigned integer 1357 MAX_DIFF_BATCH <= N_MAX, specifying the maximum number of diff 1358 entries to be included in a single diff query response. If 1359 supporting diff queries, the Authorization Server SHOULD provide 1360 registered devices and administrators with the value of 1361 MAX_DIFF_BATCH, upon their registration (see Section 6). 1363 Finally, the full query and diff query exchanges defined in 1364 Section 5.1 and Section 5.2 are extended as follows. 1366 In particular, successul responses from the TRL endpoint MUST use the 1367 Content-Format "application/ace-trl+cbor" defined in Section 10.2 of 1368 this specification. 1370 B.1. Full Query Request 1372 No changes apply to what defined in Section 5.1. 1374 B.2. Full Query Response 1376 When sending a 2.05 (Content) response to a full query request (see 1377 Appendix B.1), the response payload includes a CBOR map with the 1378 following fields, whose CBOR labels are defined in Appendix B.4.4. 1380 * 'trl': this field MUST include a CBOR array of token hashes. The 1381 CBOR array is populated and formatted as defined for the CBOR 1382 array 'full' in Section 5.1. 1384 * 'cursor': this field MUST include either the CBOR simple value 1385 Null or a CBOR unsigned integer. 1387 The CBOR simple value Null MUST be used to indicate that there are 1388 currently no TRL updates pertinent to the requester, i.e., the 1389 update collection for that requester is empty. This is the case 1390 from when the requester registers at the Authorization Server 1391 until a first update pertaining that requester occurs to the TRL. 1393 Otherwise, the field MUST include a CBOR unsigned integer, 1394 encoding the 'index' value of the last series item in the 1395 collection, as corresponding to the most recent update pertaining 1396 to the requester occurred to the TRL. 1398 B.3. Diff Query Request 1400 In addition to the query parameter 'diff' (see Section 5.2), the 1401 requester can specify a query parameter 'cursor', with value an 1402 unsigned integer. 1404 B.4. Diff Query Response 1406 The Authorization Server composes a response to a diff query request 1407 (see Appendix B.3) as follows, depending on the parameters specified 1408 in the request and on the current status of the update collection for 1409 the requester. 1411 B.4.1. Empty Collection 1413 If the collection associated to the requester has no elements, the 1414 Authorization Server returns a 2.05 (Content) diff query response. 1416 The response payload includes a CBOR map with the following fields, 1417 whose CBOR labels are defined in Appendix B.4.4. 1419 * 'diff': this field MUST include an empty CBOR array. 1421 * 'cursor': this field MUST include the CBOR simple value Null. 1423 * 'more': this fields MUST include the CBOR simple value False. 1425 B.4.2. Cursor Not Specified in the Diff Query Request 1427 If the update collection associated to the requester is not empty and 1428 the diff query request does not include the query parameter 'cursor', 1429 the Authorization Server returns a 2.05 (Content) diff query 1430 response. 1432 The response payload includes a CBOR map with the following fields, 1433 whose CBOR labels are defined in Appendix B.4.4. 1435 * 'diff': this field MUST include a CBOR array, containing L = 1436 min(U, MAX_DIFF_BATCH) diff entries. In particular, the CBOR 1437 array is populated as follows. 1439 - If U <= MAX_DIFF_BATCH, these diff entries are the last series 1440 items in the collection associated to the requester, 1441 corresponding to the L most recent TRL updates pertaining to 1442 the requester. 1444 - If U > MAX_DIFF_BATCH, these diff entries are the eldest of the 1445 last U series items in the collection associated to the 1446 requester, as corresponding to the first L of the U most recent 1447 TRL updates pertaining to the requester. 1449 The 'diff' CBOR array as well as the individual diff entries have 1450 the same format specified in Figure 5 and used for the response 1451 payload defined in Section 5.2. 1453 * 'cursor': this field MUST include a CBOR unsigned integer. This 1454 takes the 'index' value of the series element of the collection 1455 included as first diff entry in the 'diff' CBOR array. That is, 1456 it takes the 'index' value of the series item in the collection 1457 corresponding to the most recent update pertaining to the 1458 requester and returned in this diff query response. 1460 Note that 'cursor' takes the same 'index' value of the last series 1461 item in the collection when U <= MAX_DIFF_BATCH. 1463 * 'more': this field MUST include the CBOR simple value False if U 1464 <= MAX_DIFF_BATCH, or the CBOR simple value True otherwise. 1466 If 'more' has value True, the requester can send a follow-up diff 1467 query request including the query parameter 'cursor', with the 1468 same value of the 'cursor' field included in this diff query 1469 response. As defined in Appendix B.4.3, this would result in the 1470 Authorization Server transferring the following subset of series 1471 items as diff entries, i.e., resuming from where interrupted in 1472 the previous transfer. 1474 B.4.3. Cursor Specified in the Diff Query Request 1476 If the update collection associated to the requester is not empty and 1477 the diff query request includes the query parameter 'cursor' with 1478 value P, the Authorization Server proceeds as follows. 1480 * The Authorization Server MUST return a 4.00 (Bad Request) response 1481 in case the 'cursor' parameter specifies a value other than 0 or 1482 than a positive integer. 1484 * If no series item X with 'index' having value P is found in the 1485 collection associated to the requester, then that item has been 1486 previously removed from the history of updates for that requester 1487 (see Appendix A). In this case, the Authorization Server returns 1488 a 2.05 (Content) diff query response. 1490 The response payload includes a CBOR map with the following 1491 fields, whose CBOR labels are defined in Appendix B.4.4. 1493 - 'diff': this field MUST include an empty CBOR array. 1495 - 'cursor': this field MUST include the CBOR simple value Null. 1497 - 'more': this field MUST include the CBOR simple value True. 1499 With the combination ('cursor', 'more') = (Null, True), the 1500 Authorization Server is signaling that the update collection is in 1501 fact not empty, but that some series items have been lost due to 1502 their removal, including the item with 'index' value P that the 1503 requester wished to use as reference point. 1505 When receiving this diff query response, the requester should send 1506 a new full query request to the Authorization Server, in order to 1507 fully retrieve the current pertaining portion of the TRL. 1509 * If the series item X with 'index' having value P is found in the 1510 collection associated to the requester, the Authorization Server 1511 returns a 2.05 (Content) diff query response. 1513 The response payload includes a CBOR map with the following 1514 fields, whose CBOR labels are defined in Appendix B.4.4. 1516 - 'diff': this field MUST include a CBOR array, containing L = 1517 min(SUB_U, MAX_DIFF_BATCH) diff entries, where SUB_U = min(NUM, 1518 SUB_SIZE), and SUB_SIZE is the number of series items in the 1519 collection following the series item X. 1521 That is, these are the L updates pertaining to the requester 1522 that immediately follow the series item X indicated as 1523 reference point. In particular, the CBOR array is populated as 1524 follows. 1526 o If SUB_U <= MAX_DIFF_BATCH, these diff entries are the last 1527 series items in the collection associated to the requester, 1528 corresponding to the L most recent TRL updates pertaining to 1529 the requester. 1531 o If SUB_U > MAX_DIFF_BATCH, these diff entries are the eldest 1532 of the last SUB_U series items in the collection associated 1533 to the requester, corresponding to the first L of the SUB_U 1534 most recent TRL updates pertaining to the requester. 1536 The 'diff' CBOR array as well as the individual diff entries 1537 have the same format specified in Figure 5 and used for the 1538 response payload defined in Section 5.2. 1540 - 'cursor': this field MUST include a CBOR unsigned integer. In 1541 particular: 1543 o If L is equal to 0, i.e., the series item X is the last one 1544 in the collection, 'cursor' takes the same 'index' value of 1545 the last series item in the collection. 1547 o If L is different than 0, 'cursor' takes the 'index' value 1548 of the series element of the collection included as first 1549 diff entry in the 'diff' CBOR array. That is, it takes the 1550 'index' value of the series item in the collection 1551 corresponding to the most recent update pertaining to the 1552 requester and returned in this diff query response. 1554 Note that 'cursor' takes the same 'index' value of the last 1555 series item in the collection when SUB_U <= MAX_DIFF_BATCH. 1557 - 'more': this field MUST include the CBOR simple value False if 1558 SUB_U <= MAX_DIFF_BATCH, or the CBOR simple value True 1559 otherwise. 1561 If 'more' has value True, the requester can send a follow-up 1562 diff query request including the query parameter 'cursor', with 1563 the same value of the 'cursor' field specified in this diff 1564 query response. This would result in the Authorization Server 1565 transferring the following subset of series items as diff 1566 entries, i.e., resuming from where interrupted in the previous 1567 transfer. 1569 B.4.4. TRL Parameters 1571 This specification defines a number of fields used in the response to 1572 a diff query request to the TRL endpoint relying on the "Cursor" 1573 pattern, as defined in Appendix B. 1575 The table below summarizes them, and specifies the CBOR value to use 1576 as abbreviation instead of the full descriptive name. Note that the 1577 Content-Format "application/ace-trl+cbor" defined in Section 10.2 of 1578 this specification MUST be used when these fields are transported. 1580 +--------+------------+---------------------+-----------+ 1581 | Name | CBOR Value | CBOR Type | Reference | 1582 +--------+------------+---------------------+-----------+ 1583 | trl | TBD | array | [this | 1584 | | | | document] | 1585 +--------+------------+---------------------+-----------+ 1586 | cursor | TBD | simple value null / | [this | 1587 | | | unsigned integer | document] | 1588 +--------+------------+---------------------+-----------+ 1589 | diff | TBD | array | [this | 1590 | | | | document] | 1591 +--------+------------+---------------------+-----------+ 1592 | more | TBD | simple value True | [this | 1593 | | | or False | document] | 1594 +--------+------------+---------------------+-----------+ 1596 Figure 9: CBOR abbreviations for TRL parameters 1598 Acknowledgments 1600 The authors sincerely thank Carsten Bormann, Benjamin Kaduk, Michael 1601 Richardson, Jim Schaad, Goeran Selander and Travis Spencer for their 1602 comments and feedback. 1604 The work on this document has been partly supported by VINNOVA and 1605 the Celtic-Next project CRITISEC; and by the H2020 project SIFIS-Home 1606 (Grant agreement 952652). 1608 Authors' Addresses 1610 Marco Tiloca 1611 RISE AB 1612 Isafjordsgatan 22 1613 SE-16440 Kista 1614 Sweden 1616 Email: marco.tiloca@ri.se 1617 Ludwig Seitz 1618 Combitech 1619 Djaeknegatan 31 1620 SE-21135 Malmoe 1621 Sweden 1623 Email: ludwig.seitz@combitech.com 1625 Francesca Palombini 1626 Ericsson AB 1627 Torshamnsgatan 23 1628 SE-16440 Kista 1629 Sweden 1631 Email: francesca.palombini@ericsson.com 1633 Sebastian Echeverria 1634 CMU SEI 1635 4500 Fifth Avenue 1636 Pittsburgh, PA, 15213-2612 1637 United States of America 1639 Email: secheverria@sei.cmu.edu 1641 Grace Lewis 1642 CMU SEI 1643 4500 Fifth Avenue 1644 Pittsburgh, PA, 15213-2612 1645 United States of America 1647 Email: glewis@sei.cmu.edu