idnits 2.17.1 draft-tiloca-ace-revoked-token-notification-05.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 (12 July 2021) is 1019 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-43 == Outdated reference: A later version (-06) exists of draft-ietf-core-conditional-attributes-00 Summary: 0 errors (**), 0 flaws (~~), 3 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: 13 January 2022 Combitech 6 F. Palombini 7 Ericsson AB 8 S. Echeverria 9 G. Lewis 10 CMU SEI 11 12 July 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-05 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 13 January 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 . . . . . . . . 28 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 . . . 31 107 B.4.3. Cursor Specified in the Diff Query Request . . . . . 32 108 B.4.4. TRL Parameters . . . . . . . . . . . . . . . . . . . 34 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 regards 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 This specification registers the 'application/ace-trl+cbor' media 1056 type for messages of the protocols defined in this document encoded 1057 in 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 This specification registers the following entry to the "CoAP 1101 Content-Formats" registry, within the "CoRE Parameters" registry: 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 Key: This is the value used as CBOR key of the item. These 1128 values MUST be unique. The value can be a positive integer or a 1129 negative integer. Different ranges of values use different 1130 registration policies [RFC8126]. Integer values from -256 to 255 1131 are designated as Standards Action. Integer values from -65536 to 1132 -257 and from 256 to 65535 are designated as Specification 1133 Required. Integer values greater than 65535 are designated as 1134 Expert Review. Integer values less than -65536 are marked as 1135 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 by the values in 1145 Appendix B.4.4. The Reference column for all of these entries refers 1146 to this document. 1148 10.4. Expert Review Instructions 1150 The IANA registry established in this document is defined as expert 1151 review. This section gives some general guidelines for what the 1152 experts should be looking for, but they are being designated as 1153 experts for a reason so they should be given substantial latitude. 1155 Expert reviewers should take into consideration the following points: 1157 * Point squatting should be discouraged. Reviewers are encouraged 1158 to get sufficient information for registration requests to ensure 1159 that the usage is not going to duplicate one that is already 1160 registered and that the point is likely to be used in deployments. 1161 The zones tagged as private use are intended for testing purposes 1162 and closed environments, code points in other ranges should not be 1163 assigned for testing. 1165 * Specifications are required for the standards track range of point 1166 assignment. Specifications should exist for specification 1167 required ranges, but early assignment before a specification is 1168 available is considered to be permissible. Specifications are 1169 needed for the first-come, first-serve range if they are expected 1170 to be used outside of closed environments in an interoperable way. 1171 When specifications are not provided, the description provided 1172 needs to have sufficient information to identify what the point is 1173 being used for. 1175 * Experts should take into account the expected usage of fields when 1176 approving point assignment. The fact that there is a range for 1177 standards track documents does not mean that a standards track 1178 document cannot have points assigned outside of that range. The 1179 length of the encoded value should be weighed against how many 1180 code points of that length are left, the size of device it will be 1181 used on, and the number of code points left that encode to that 1182 size. 1184 11. References 1186 11.1. Normative References 1188 [I-D.ietf-ace-oauth-authz] 1189 Seitz, L., Selander, G., Wahlstroem, E., Erdtman, S., and 1190 H. Tschofenig, "Authentication and Authorization for 1191 Constrained Environments (ACE) using the OAuth 2.0 1192 Framework (ACE-OAuth)", Work in Progress, Internet-Draft, 1193 draft-ietf-ace-oauth-authz-43, 10 July 2021, 1194 . 1197 [Named.Information.Hash.Algorithm] 1198 IANA, "Named Information Hash Algorithm", 1199 . 1202 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1203 Requirement Levels", BCP 14, RFC 2119, 1204 DOI 10.17487/RFC2119, March 1997, 1205 . 1207 [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", 1208 RFC 6749, DOI 10.17487/RFC6749, October 2012, 1209 . 1211 [RFC6838] Freed, N., Klensin, J., and T. Hansen, "Media Type 1212 Specifications and Registration Procedures", BCP 13, 1213 RFC 6838, DOI 10.17487/RFC6838, January 2013, 1214 . 1216 [RFC6920] Farrell, S., Kutscher, D., Dannewitz, C., Ohlman, B., 1217 Keranen, A., and P. Hallam-Baker, "Naming Things with 1218 Hashes", RFC 6920, DOI 10.17487/RFC6920, April 2013, 1219 . 1221 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 1222 Application Protocol (CoAP)", RFC 7252, 1223 DOI 10.17487/RFC7252, June 2014, 1224 . 1226 [RFC7519] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token 1227 (JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015, 1228 . 1230 [RFC7641] Hartke, K., "Observing Resources in the Constrained 1231 Application Protocol (CoAP)", RFC 7641, 1232 DOI 10.17487/RFC7641, September 2015, 1233 . 1235 [RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for 1236 Writing an IANA Considerations Section in RFCs", BCP 26, 1237 RFC 8126, DOI 10.17487/RFC8126, June 2017, 1238 . 1240 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 1241 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 1242 May 2017, . 1244 [RFC8259] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 1245 Interchange Format", STD 90, RFC 8259, 1246 DOI 10.17487/RFC8259, December 2017, 1247 . 1249 [RFC8392] Jones, M., Wahlstroem, E., Erdtman, S., and H. Tschofenig, 1250 "CBOR Web Token (CWT)", RFC 8392, DOI 10.17487/RFC8392, 1251 May 2018, . 1253 [RFC8610] Birkholz, H., Vigano, C., and C. Bormann, "Concise Data 1254 Definition Language (CDDL): A Notational Convention to 1255 Express Concise Binary Object Representation (CBOR) and 1256 JSON Data Structures", RFC 8610, DOI 10.17487/RFC8610, 1257 June 2019, . 1259 [RFC8949] Bormann, C. and P. Hoffman, "Concise Binary Object 1260 Representation (CBOR)", STD 94, RFC 8949, 1261 DOI 10.17487/RFC8949, December 2020, 1262 . 1264 11.2. Informative References 1266 [I-D.bormann-t2trg-stp] 1267 Bormann, C. and K. Hartke, "The Series Transfer Pattern 1268 (STP)", Work in Progress, Internet-Draft, draft-bormann- 1269 t2trg-stp-03, 7 April 2020, 1270 . 1273 [I-D.ietf-core-conditional-attributes] 1274 Koster, M. and B. Silverajan, "Conditional Attributes for 1275 Constrained RESTful Environments", Work in Progress, 1276 Internet-Draft, draft-ietf-core-conditional-attributes-00, 1277 12 July 2021, . 1280 [RFC7009] Lodderstedt, T., Ed., Dronia, S., and M. Scurtescu, "OAuth 1281 2.0 Token Revocation", RFC 7009, DOI 10.17487/RFC7009, 1282 August 2013, . 1284 Appendix A. Usage of the Series Transfer Pattern 1286 This section discusses how the diff query of the TRL defined in 1287 Section 5.2 is a usage example of the Series Transfer Pattern defined 1288 in [I-D.bormann-t2trg-stp]. 1290 A diff query enables the transfer of a series of TRL updates, with 1291 the Authorization Server specifying U <= N_MAX diff entries as the U 1292 most recent updates to the portion of the TRL pertaining to a 1293 registered device. 1295 For each registered device, the Authorization Server maintains an 1296 update collection of maximum N_MAX items. Each time the TRL changes, 1297 the Authorization Server performs the following operations for each 1298 registered device. 1300 1. The Authorization Server considers the portion of the TRL 1301 pertaining to that registered device. If the TRL portion is not 1302 affected by this TRL update, the Authorization Server stops the 1303 processing for that registered device. 1305 2. Otherwise, the Authorization Server creates two sets 'trl_patch' 1306 of token hashes, i.e., one "removed" set and one "added" set, as 1307 related to this TRL update. 1309 3. The Authorization Server fills the two sets with the token hashes 1310 of the removed and added Access Tokens, respectively, from/to the 1311 TRL portion from step 1. 1313 4. The Authorization Server creates a new series item including the 1314 two sets from step 3, and adds the series item to the update 1315 collection associated to the registered device. 1317 When responding to a diff query request from a registered device (see 1318 Section 5.2), 'diff' is a subset of the collection associated to the 1319 requester, where each 'diff_entry' record is a series item from that 1320 collection. Note that 'diff' specifies the whole current collection 1321 when the value of U is equal to SIZE, i.e., the current number of 1322 series items in the collection. 1324 The value N of the 'diff' query parameter in the diff query request 1325 allows the requester and the Authorization Server to trade the amount 1326 of provided information with the latency of the information transfer. 1328 Since the collection associated to each registered device includes up 1329 to N_MAX series item, the Authorization Server deletes the oldest 1330 series item when a new one is generated and added to the end of the 1331 collection, due to a new TRL update pertaining to that registered 1332 device. This addresses the question "When can the server decide to 1333 no longer retain older items?" in Section 3.2 of 1334 [I-D.bormann-t2trg-stp]. 1336 Appendix B. Usage of the "Cursor" Pattern 1338 Building on Appendix A, this section describes how the diff query of 1339 the TRL defined in Section 5.2 can be further improved by using the 1340 "Cursor" pattern of the Series Transfer Pattern (see Section 3.3 of 1341 [I-D.bormann-t2trg-stp]). 1343 This has two benefits. First, the Authorization Server can avoid 1344 excessively big latencies when several diff entries have to be 1345 transferred, by delivering one adjacent subset at the time, in 1346 different diff query responses. Second, a requester can retrieve 1347 diff entries associated to TRL updates that, even if not the most 1348 recent ones, occurred after a TRL update indicated as reference 1349 point. 1351 To this end, each series item in an update collection is also 1352 associated to an unsigned integer 'index', with value the absolute 1353 counter of series items added to that collection minus 1. That is, 1354 the first series item added to a collection has 'index' with value 0. 1355 Then, the values of 'index' are used as cursor information. 1357 Furthermore, the Authorization Server defines an unsigned integer 1358 MAX_DIFF_BATCH <= N_MAX, specifying the maximum number of diff 1359 entries to be included in a single diff query response. If 1360 supporting diff queries, the Authorization Server SHOULD provide 1361 registered devices and administrators with the value of 1362 MAX_DIFF_BATCH, upon their registration (see Section 6). 1364 Finally, the full query and diff query exchanges defined in 1365 Section 5.1 and Section 5.2 are extended as follows. 1367 In particular, successul responses from the TRL endpoint MUST use the 1368 Content-Format "application/ace-trl+cbor" defined in Section 10.2 of 1369 this specification. 1371 B.1. Full Query Request 1373 No changes apply to what defined in Section 5.1. 1375 B.2. Full Query Response 1377 When sending a 2.05 (Content) response to a full query request (see 1378 Appendix B.1), the response payload includes a CBOR map with the 1379 following fields, whose CBOR labels are defined in Appendix B.4.4. 1381 * 'trl': this field MUST include a CBOR array of token hashes. The 1382 CBOR array is populated and formatted as defined for the CBOR 1383 array 'full' in Section 5.1. 1385 * 'cursor': this field MUST include either the CBOR simple value 1386 Null or a CBOR unsigned integer. 1388 The CBOR simple value Null MUST be used to indicate that there are 1389 currently no TRL updates pertinent to the requester, i.e., the 1390 update collection for that requester is empty. This is the case 1391 from when the requester registers at the Authorization Server 1392 until a first update pertaining that requester occurs to the TRL. 1394 Otherwise, the field MUST include a CBOR unsigned integer, 1395 encoding the 'index' value of the last series item in the 1396 collection, as corresponding to the most recent update pertaining 1397 to the requester occurred to the TRL. 1399 B.3. Diff Query Request 1401 In addition to the query parameter 'diff' (see Section 5.2), the 1402 requester can specify a query parameter 'cursor', with value an 1403 unsigned integer. 1405 B.4. Diff Query Response 1407 The Authorization Server composes a response to a diff query request 1408 (see Appendix B.3) as follows, depending on the parameters specified 1409 in the request and on the current status of the update collection for 1410 the requester. 1412 B.4.1. Empty Collection 1414 If the collection associated to the requester has no elements, the 1415 Authorization Server returns a 2.05 (Content) diff query response. 1417 The response payload includes a CBOR map with the following fields, 1418 whose CBOR labels are defined in Appendix B.4.4. 1420 * 'diff': this field MUST include an empty CBOR array. 1422 * 'cursor': this field MUST include the CBOR simple value Null. 1424 * 'more': this fields MUST include the CBOR simple value False. 1426 B.4.2. Cursor Not Specified in the Diff Query Request 1428 If the update collection associated to the requester is not empty and 1429 the diff query request does not include the query parameter 'cursor', 1430 the Authorization Server returns a 2.05 (Content) diff query 1431 response. 1433 The response payload includes a CBOR map with the following fields, 1434 whose CBOR labels are defined in Appendix B.4.4. 1436 * 'diff': this field MUST include a CBOR array, containing L = 1437 min(U, MAX_DIFF_BATCH) diff entries. In particular, the CBOR 1438 array is populated as follows. 1440 - If U <= MAX_DIFF_BATCH, these diff entries are the last series 1441 items in the collection associated to the requester, 1442 corresponding to the L most recent TRL updates pertaining to 1443 the requester. 1445 - If U > MAX_DIFF_BATCH, these diff entries are the eldest of the 1446 last U series items in the collection associated to the 1447 requester, as corresponding to the first L of the U most recent 1448 TRL updates pertaining to the requester. 1450 The 'diff' CBOR array as well as the individual diff entries have 1451 the same format specified in Figure 5 and used for the reponse 1452 payload defined in Section 5.2. 1454 * 'cursor': this field MUST include a CBOR unsigned integer. This 1455 takes the 'index' value of the series element of the collection 1456 included as first diff entry in the 'diff' CBOR array. That is, 1457 it takes the '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 series 1462 item in the collection when U <= MAX_DIFF_BATCH. 1464 * 'more': this field MUST include the CBOR simple value False if U 1465 <= MAX_DIFF_BATCH, or the CBOR simple value True otherwise. 1467 If 'more' has value True, the requester can send a follow-up diff 1468 query request including the query parameter 'cursor', with the 1469 same value of the 'cursor' field included in this diff query 1470 response. As defined in Appendix B.4.3, this would result in the 1471 Authorization Server transferring the following subset of series 1472 items as diff entries, i.e., resuming from where interrupted in 1473 the previous transfer. 1475 B.4.3. Cursor Specified in the Diff Query Request 1477 If the update collection associated to the requester is not empty and 1478 the diff query request includes the query parameter 'cursor' with 1479 value P, the Authorization Server proceeds as follows. 1481 * The Authorization Server MUST return a 4.00 (Bad Request) response 1482 in case the 'cursor' parameter specifies a value other than 0 or 1483 than a positive integer. 1485 * If no series item X with 'index' having value P is found in the 1486 collection associated to the requester, then that item has been 1487 previously removed from the history of updates for that requester 1488 (see Appendix A). In this case, the Authorization Server returns 1489 a 2.05 (Content) diff query response. 1491 The response payload includes a CBOR map with the following 1492 fields, whose CBOR labels are defined in Appendix B.4.4. 1494 - 'diff': this field MUST include an empty CBOR array. 1496 - 'cursor': this field MUST include the CBOR simple value Null. 1498 - 'more': this field MUST include the CBOR simple value True. 1500 With the combination ('cursor', 'more') = (Null, True), the 1501 Authorization Server is signaling that the update collection is in 1502 fact not empty, but that some series items have been lost due to 1503 their removal, including the item with 'index' value P that the 1504 requester wished to use as reference point. 1506 When receiving this diff query response, the requester should send 1507 a new full query request to the Authorization Server, in order to 1508 fully retrieve the current pertaining portion of the TRL. 1510 * If the series item X with 'index' having value P is found in the 1511 collection associated to the requester, the Authorization Server 1512 returns a 2.05 (Content) diff query response. 1514 The response payload includes a CBOR map with the following 1515 fields, whose CBOR labels are defined in Appendix B.4.4. 1517 - 'diff': this field MUST include a CBOR array, containing L = 1518 min(SUB_U, MAX_DIFF_BATCH) diff entries, where SUB_U = min(NUM, 1519 SUB_SIZE), and SUB_SIZE is the number of series items in the 1520 collection following the series item X. 1522 That is, these are the L updates pertaining to the requester 1523 that immediately follow the series item X indicated as 1524 reference point. In particular, the CBOR array is populated as 1525 follows. 1527 o If SUB_U <= MAX_DIFF_BATCH, these diff entries are the last 1528 series items in the collection associated to the requester, 1529 corresponding to the L most recent TRL updates pertaining to 1530 the requester. 1532 o If SUB_U > MAX_DIFF_BATCH, these diff entries are the eldest 1533 of the last SUB_U series items in the collection associated 1534 to the requester, corresponding to the first L of the SUB_U 1535 most recent TRL updates pertaining to the requester. 1537 The 'diff' CBOR array as well as the individual diff entries 1538 have the same format specified in Figure 5 and used for the 1539 reponse payload defined in Section 5.2. 1541 - 'cursor': this field MUST include a CBOR unsigned integer. In 1542 particular: 1544 o If L is equal to 0, i.e., the series item X is the last one 1545 in the collection, 'cursor' takes the same 'index' value of 1546 the last series item in the collection. 1548 o If L is different than 0, 'cursor' takes the 'index' value 1549 of the series element of the collection included as first 1550 diff entry in the 'diff' CBOR array. That is, it takes the 1551 'index' value of the series item in the collection 1552 corresponding to the most recent update pertaining to the 1553 requester and returned in this diff query response. 1555 Note that 'cursor' takes the same 'index' value of the last 1556 series item in the collection when SUB_U <= MAX_DIFF_BATCH. 1558 - 'more': this field MUST include the CBOR simple value False if 1559 SUB_U <= MAX_DIFF_BATCH, or the CBOR simple value True 1560 otherwise. 1562 If 'more' has value True, the requester can send a follow-up 1563 diff query request including the query parameter 'cursor', with 1564 the same value of the 'cursor' field specified in this diff 1565 query response. This would result in the Authorization Server 1566 transferring the following subset of series items as diff 1567 entries, i.e., resuming from where interrupted in the previous 1568 transfer. 1570 B.4.4. TRL Parameters 1572 This specification defines a number of fields used in the response to 1573 a diff query request to the TRL endpoint relying on the "Cursor" 1574 pattern, as defined in Appendix B. 1576 The table below summarizes them, and specifies the CBOR key to use 1577 instead of the full descriptive name. Note that the Content-Format 1578 "application/ace-trl+cbor" defined in Section 10.2 of this 1579 specification MUST be used when these fields are transported. 1581 +--------+----------+---------------------+-----------+ 1582 | Name | CBOR Key | CBOR Type | Reference | 1583 +--------+----------+---------------------+-----------+ 1584 | trl | TBD | array | [This | 1585 | | | | Document] | 1586 +--------+----------+---------------------+-----------+ 1587 | cursor | TBD | simple value null / | [This | 1588 | | | unsigned integer | Document] | 1589 +--------+----------+---------------------+-----------+ 1590 | diff | TBD | array | [This | 1591 | | | | Document] | 1592 +--------+----------+---------------------+-----------+ 1593 | more | TBD | simple value True | [This | 1594 | | | or False | Document] | 1595 +--------+----------+---------------------+-----------+ 1597 Acknowledgments 1599 The authors sincerely thank Carsten Bormann, Benjamin Kaduk, Michael 1600 Richardson, Jim Schaad, Goeran Selander and Travis Spencer for their 1601 comments and feedback. 1603 The work on this document has been partly supported by VINNOVA and 1604 the Celtic-Next project CRITISEC; and by the H2020 project SIFIS-Home 1605 (Grant agreement 952652). 1607 Authors' Addresses 1609 Marco Tiloca 1610 RISE AB 1611 Isafjordsgatan 22 1612 SE-16440 Kista 1613 Sweden 1615 Email: marco.tiloca@ri.se 1616 Ludwig Seitz 1617 Combitech 1618 Djaeknegatan 31 1619 SE-21135 Malmoe 1620 Sweden 1622 Email: ludwig.seitz@combitech.com 1624 Francesca Palombini 1625 Ericsson AB 1626 Torshamnsgatan 23 1627 SE-16440 Kista 1628 Sweden 1630 Email: francesca.palombini@ericsson.com 1632 Sebastian Echeverria 1633 CMU SEI 1634 4500 Fifth Avenue 1635 Pittsburgh, PA, 15213-2612 1636 United States of America 1638 Email: secheverria@sei.cmu.edu 1640 Grace Lewis 1641 CMU SEI 1642 4500 Fifth Avenue 1643 Pittsburgh, PA, 15213-2612 1644 United States of America 1646 Email: glewis@sei.cmu.edu