idnits 2.17.1 draft-ietf-ace-revoked-token-notification-01.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 (7 March 2022) is 752 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-02 ** Downref: Normative reference to an Informational draft: draft-ietf-core-conditional-attributes (ref. 'I-D.ietf-core-conditional-attributes') Summary: 1 error (**), 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: 8 September 2022 Combitech 6 F. Palombini 7 Ericsson AB 8 S. Echeverria 9 G. Lewis 10 CMU SEI 11 7 March 2022 13 Notification of Revoked Access Tokens in the Authentication and 14 Authorization for Constrained Environments (ACE) Framework 15 draft-ietf-ace-revoked-token-notification-01 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 allows Clients and Resource Servers to access a Token Revocation List 24 on the Authorization Server, with the possible additional use of 25 resource observation for the Constrained Application Protocol (CoAP). 26 Resulting (unsolicited) notifications of revoked Access Tokens 27 complement alternative approaches such as token introspection, while 28 not requiring 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 Authentication and 35 Authorization for Constrained Environments Working Group mailing list 36 (ace@ietf.org), which is archived at 37 https://mailarchive.ietf.org/arch/browse/ace/. 39 Source for this draft and an issue tracker can be found at 40 https://github.com/ace-wg/ace-revoked-token-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 8 September 2022. 59 Copyright Notice 61 Copyright (c) 2022 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 Revised BSD License text as 70 described in Section 4.e of the Trust Legal Provisions and are 71 provided without warranty as described in the Revised 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 6. Full Query of the TRL . . . . . . . . . . . . . . . . . . . . 11 83 7. Diff Query of the TRL . . . . . . . . . . . . . . . . . . . . 12 84 8. Upon Registration . . . . . . . . . . . . . . . . . . . . . . 14 85 9. Notification of Revoked Tokens . . . . . . . . . . . . . . . 15 86 10. Interaction Examples . . . . . . . . . . . . . . . . . . . . 16 87 10.1. Full Query with Observation . . . . . . . . . . . . . . 17 88 10.2. Diff Query with Observation . . . . . . . . . . . . . . 18 89 10.3. Full Query with Observation and Additional Diff Query . 20 90 11. ACE Token Revocation List Parameters . . . . . . . . . . . . 23 91 12. ACE Token Revocation List Error Identifiers . . . . . . . . . 23 92 13. Security Considerations . . . . . . . . . . . . . . . . . . . 24 93 14. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 25 94 14.1. Media Type Registrations . . . . . . . . . . . . . . . . 25 95 14.2. CoAP Content-Formats Registry . . . . . . . . . . . . . 26 96 14.3. ACE Token Revocation List Parameters Registry . . . . . 26 97 14.4. ACE Token Revocation List Errors . . . . . . . . . . . . 27 98 14.5. Expert Review Instructions . . . . . . . . . . . . . . . 28 99 15. References . . . . . . . . . . . . . . . . . . . . . . . . . 28 100 15.1. Normative References . . . . . . . . . . . . . . . . . . 28 101 15.2. Informative References . . . . . . . . . . . . . . . . . 30 102 Appendix A. On using the Series Transfer Pattern . . . . . . . . 30 103 Appendix B. Usage of the "Cursor" Pattern . . . . . . . . . . . 32 104 B.1. Full Query Request . . . . . . . . . . . . . . . . . . . 33 105 B.2. Full Query Response . . . . . . . . . . . . . . . . . . . 33 106 B.3. Diff Query Request . . . . . . . . . . . . . . . . . . . 33 107 B.4. Diff Query Response . . . . . . . . . . . . . . . . . . . 34 108 B.4.1. Empty Collection . . . . . . . . . . . . . . . . . . 34 109 B.4.2. Cursor Not Specified in the Diff Query Request . . . 34 110 B.4.3. Cursor Specified in the Diff Query Request . . . . . 35 111 Appendix C. Document Updates . . . . . . . . . . . . . . . . . . 38 112 C.1. Version -00 to -01 . . . . . . . . . . . . . . . . . . . 38 113 Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . 38 114 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 38 116 1. Introduction 118 Authentication and Authorization for Constrained Environments (ACE) 119 [I-D.ietf-ace-oauth-authz] is a framework that enforces access 120 control on IoT devices acting as Resource Servers. In order to use 121 ACE, both Clients and Resource Servers have to register with an 122 Authorization Server and become a registered device. Once 123 registered, a Client can send a request to the Authorization Server, 124 to obtain an Access Token for a Resource Server. For a Client to 125 access the Resource Server, the Client must present the issued Access 126 Token at the Resource Server, which then validates it before storing 127 it (see Section 5.10.1.1 of [I-D.ietf-ace-oauth-authz]). 129 Even though Access Tokens have expiration times, there are 130 circumstances by which an Access Token may need to be revoked before 131 its expiration time, such as: (1) a registered device has been 132 compromised, or is suspected of being compromised; (2) a registered 133 device is decommissioned; (3) there has been a change in the ACE 134 profile for a registered device; (4) there has been a change in 135 access policies for a registered device; and (5) there has been a 136 change in the outcome of policy evaluation for a registered device 137 (e.g., if policy assessment depends on dynamic conditions in the 138 execution environment, the user context, or the resource 139 utilization). 141 As discussed in Section 6.1 of [I-D.ietf-ace-oauth-authz], only 142 client-initiated revocation is currently specified [RFC7009] for 143 OAuth 2.0 [RFC6749], based on the assumption that Access Tokens in 144 OAuth are issued with a relatively short lifetime. However, this is 145 not expected to be the case for constrained, intermittently connected 146 devices, that need Access Tokens with relatively long lifetimes. 148 This document specifies a method for allowing registered devices to 149 access and possibly subscribe to a Token Revocation List (TRL) 150 resource on the Authorization Server, in order to obtain an updated 151 list of revoked, but yet not expired, pertaining Access Tokens. In 152 particular, registered devices can subscribe to the TRL at the 153 Authorization Server by using resource observation [RFC7641] for the 154 Constrained Application Protocol (CoAP) [RFC7252]. 156 Unlike in the case of token introspection (see Section 5.9 of 157 [I-D.ietf-ace-oauth-authz]), a registered device does not provide an 158 owned Access Token to the Authorization Server for inquiring about 159 its current state. Instead, registered devices simply obtain an 160 updated list of revoked, but yet not expired, pertaining Access 161 Tokens, as efficiently identified by corresponding hash values. 163 The benefits of this method are that it complements token 164 introspection, and it does not require any additional endpoints on 165 the registered devices. The only additional requirements for 166 registered devices are a request/response interaction with the 167 Authorization Server to access and possibly subscribe to the TRL (see 168 Section 2), and the lightweight computation of hash values to use as 169 Token identifiers (see Section 3). 171 1.1. Terminology 173 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 174 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 175 "OPTIONAL" in this document are to be interpreted as described in BCP 176 14 [RFC2119] [RFC8174] when, and only when, they appear in all 177 capitals, as shown here. 179 Readers are expected to be familiar with the terms and concepts 180 described in the ACE framework for Authentication and Authorization 181 [I-D.ietf-ace-oauth-authz], as well as with terms and concepts 182 related to CBOR Web Tokens (CWTs) [RFC8392], and JSON Web Tokens 183 (JWTs) [RFC7519]. The terminology for entities in the considered 184 architecture is defined in OAuth 2.0 [RFC6749]. In particular, this 185 includes Client, Resource Server, and Authorization Server. 187 Readers are also expected to be familiar with the terms and concepts 188 related to CBOR [RFC8949], JSON [RFC8259], the CoAP protocol 189 [RFC7252], CoAP Observe [RFC7641], and the use of hash functions to 190 name objects as defined in [RFC6920]. 192 Note that, unless otherwise indicated, the term "endpoint" is used 193 here following its OAuth definition, aimed at denoting resources such 194 as /token and /introspect at the Authorization Server, and /authz- 195 info at the Resource Server. This document does not use the CoAP 196 definition of "endpoint", which is "An entity participating in the 197 CoAP protocol." 199 This specification also refers to the following terminology. 201 * Token hash: identifier of an Access Token, in binary format 202 encoding. The token hash has no relation to other possibly used 203 token identifiers, such as the "cti" (CWT ID) claim of CBOR Web 204 Tokens (CWTs) [RFC8392]. 206 * Token Revocation List (TRL): a collection of token hashes such 207 that the corresponding Access Tokens have been revoked but are not 208 expired yet. 210 * TRL resource: a resource on the Authorization Server, with a TRL 211 as its representation. 213 * TRL endpoint: an endpoint at the Authorization Server associated 214 with the TRL resource. The default name of the TRL endpoint in a 215 url-path is '/revoke/trl'. Implementations are not required to 216 use this name, and can define their own instead. 218 * Registered device: a device registered at the Authorization 219 Server, i.e., as a Client, or a Resource Server, or both. A 220 registered device acts as a caller of the TRL endpoint. 222 * Administrator: entity authorized to get full access to the TRL at 223 the Authorization Server, and acting as a caller of the TRL 224 endpoint. An administrator is not necessarily a registered device 225 as defined above, i.e., a Client requesting Access Tokens or a 226 Resource Server consuming Access Tokens. How the administrator 227 authorization is established and verified is out of the scope of 228 this specification. 230 * Pertaining Access Token: 232 - With reference to an administrator, an Access Token issued by 233 the Authorization Server. 235 - With reference to a registered device, an Access Token intended 236 to be owned by that device. An Access Token pertains to a 237 Client if the Authorization Server has issued the Access Token 238 and provided it to that Client. An Access Token pertains to a 239 Resource Server if the Authorization Server has issued the 240 Access Token to be consumed by that Resource Server. 242 2. Protocol Overview 244 This protocol defines how a CoAP-based Authorization Server informs 245 Clients and Resource Servers, i.e., registered devices, about 246 pertaining revoked Access Tokens. How the relationship between a 247 registered device and the Authorization Server is established is out 248 of the scope of this specification. 250 At a high level, the steps of this protocol are as follows. 252 * Upon startup, the Authorization Server creates a single TRL 253 resource. At any point in time, the TRL resource represents the 254 list of all revoked Access Tokens issued by the Authorization 255 Server that are not expired yet. 257 * When a device registers at the Authorization Server, it also 258 receives the url-path to the TRL resource. 260 After the registration procedure is finished, the registered 261 device can send an Observation Request to the TRL resource as 262 described in [RFC7641], i.e., a GET request with an Observe option 263 set to 0 (register). By doing so, the registered device 264 effectively subscribes to the TRL resource, as interested to 265 receive notifications about its update. Upon receiving the 266 request, the Authorization Server adds the registered device to 267 the list of observers of the TRL resource. 269 At any time, the registered device can send a GET request to the 270 TRL endpoint. When doing so, it can request for: the current list 271 of pertaining revoked Access Tokens (see Section 6); or the most 272 recent TRL updates occurred over the list of pertaining revoked 273 Access Tokens (see Section 7). In either case, the registered 274 device may especially rely on an Observation Request for 275 subscribing to the TRL resource as discussed above. 277 * When an Access Token is revoked, the Authorization Server adds the 278 corresponding token hash to the TRL. Also, when a revoked Access 279 Token eventually expires, the Authorization Server removes the 280 corresponding token hash from the TRL. 282 In either case, after updating the TRL, the Authorization Server 283 sends Observe Notifications as per [RFC7641]. That is, an Observe 284 Notification is sent to each registered device subscribed to the 285 TRL resource and to which the Access Token pertains. 287 Depending on the specific subscription established through the 288 observation request, the notification provides the current updated 289 list of revoked Access Tokens in the portion of the TRL pertaining 290 to that device (see Section 6), or rather the most recent TRL 291 updates occurred over that list of pertaining revoked Access 292 Tokens (see Section 7). 294 Further Observe Notifications may be sent, consistently with 295 ongoing additional observations of the TRL resource. 297 * An administrator can access and subscribe to the TRL like a 298 registered device, while getting the full updated representation 299 of the TRL. 301 Figure 1 shows a high-level overview of the service provided by this 302 protocol. In particular, it shows the Observe Notifications sent by 303 the Authorization Server to one administrator and four registered 304 devices, upon revocation of the issued Access Tokens t1, t2 and t3, 305 with token hash th1, th2 and th3, respectively. Each dotted line 306 associated with a pair of registered devices indicates the Access 307 Token that they both own. 309 +----------------------+ 310 | Authorization Server | 311 +-----------o----------+ 312 revoke/trl | TRL: {th1,th2,th3} 313 | 314 +-----------------+------------+------------+------------+ 315 | | | | | 316 | th1,th2,th3 | th1,th2 | th1 | th3 | th2,th3 317 v v v v v 318 +---------------+ +----------+ +----------+ +----------+ +----------+ 319 | Administrator | | Client 1 | | Resource | | Client 2 | | Resource | 320 | | | | | Server 1 | | | | Server 2 | 321 +---------------+ +----------+ +----------+ +----------+ +----------+ 322 : : : : : : 323 : : t1 : : t3 : : 324 : :........: :............: : 325 : t2 : 326 :...........................................: 328 Figure 1: Protocol Overview 330 Section 10 provides examples of the protocol flow and message 331 exchange between the Authorization Server and a registered device. 333 3. Token Hash 335 The token hash of an Access Token is computed as follows. 337 1. The Authorization Server defines ENCODED_TOKEN, as the content of 338 the 'access_token' parameter in the Authorization Server response 339 (see Section 5.8.2 of [I-D.ietf-ace-oauth-authz]), where the 340 Access Token was included and provided to the requesting Client. 342 Note that the content of the 'access_token' parameter is either: 344 * A CBOR byte string, if the Access Token was transported using 345 CBOR. With reference to the example in Figure 2, and assuming 346 the string's length in bytes to be 119 (i.e., 0x77 in 347 hexadecimal), then ENCODED_TOKEN takes the bytes {0x58 0x77 348 0xd0 0x83 0x44 0xa1 ...}, i.e., the raw content of the 349 parameter 'access_token'. 351 * A text string, if the Access Token was transported using JSON. 352 With reference to the example in Figure 3, ENCODED_TOKEN takes 353 "2YotnFZFEjr1zCsicMWpAA", i.e., the raw content of the 354 parameter 'access_token'. 356 2. The Authorization Server defines HASH_INPUT as follows. 358 * If CBOR was used to transport the Access Token (as a CWT or 359 JWT), HASH_INPUT takes the same value of ENCODED_TOKEN. 361 * If JSON was used to transport the Access Token (as a CWT or 362 JWT), HASH_INPUT takes the serialization of ENCODED_TOKEN. 364 In either case, HASH_INPUT results in the binary 365 representation of the content of the 'access_token' parameter 366 from the Authorization Server response. 368 3. The Authorization Server generates a hash value of HASH_INPUT as 369 per Section 6 of [RFC6920]. The resulting output in binary 370 format is used as the token hash. Note that the used binary 371 format embeds the identifier of the used hash function, in the 372 first byte of the computed token hash. 374 The specifically used hash function MUST be collision-resistant 375 on byte-strings, and MUST be selected from the "Named Information 376 Hash Algorithm" Registry [Named.Information.Hash.Algorithm]. 378 The Authorization Server specifies the used hash function to 379 registered devices during their registration procedure (see 380 Section 8). 382 2.01 Created 383 Content-Format: application/ace+cbor 384 Max-Age: 85800 385 Payload: 386 { 387 access_token : h'd08344a1...' 388 (remainder of the Access Token omitted for brevity) 389 token_type : pop, 390 expires_in : 86400, 391 profile : coap_dtls, 392 (remainder of the response omitted for brevity) 393 } 395 Figure 2: Example of Authorization Server response using CBOR 397 HTTP/1.1 200 OK 398 Content-Type: application/json 399 Cache-Control: no-store 400 Pragma: no-cache 401 Payload: 402 { 403 "access_token" : "2YotnFZFEjr1zCsicMWpAA" 404 (remainder of the Access Token omitted for brevity) 405 "token_type" : "pop", 406 "expires_in" : 86400, 407 "profile" : "coap_dtls", 408 (remainder of the response omitted for brevity) 409 } 411 Figure 3: Example of Authorization Server response using JSON 413 4. The TRL Resource 415 Upon startup, the Authorization Server creates a single TRL resource, 416 encoded as a CBOR array. 418 Each element of the array is a CBOR byte string, with value the token 419 hash of an Access Token. The order of the token hashes in the CBOR 420 array is irrelevant, and the CBOR array MUST be treated as a set in 421 which the order has no significant meaning. 423 The TRL is initialized as empty, i.e., the initial content of the TRL 424 resource representation MUST be an empty CBOR array. 426 4.1. Update of the TRL Resource 428 The Authorization Server updates the TRL in the following two cases. 430 * When a non-expired Access Token is revoked, the token hash of the 431 Access Token is added to the TRL resource representation. That 432 is, a CBOR byte string with the token hash as its value is added 433 to the CBOR array used as TRL resource representation. 435 * When a revoked Access Token expires, the token hash of the Access 436 Token is removed from the TRL resource representation. That is, 437 the CBOR byte string with the token hash as its value is removed 438 from the CBOR array used as TRL resource representation. 440 5. The TRL Endpoint 442 Consistent with Section 6.5 of [I-D.ietf-ace-oauth-authz], all 443 communications between a caller of the TRL endpoint and the 444 Authorization Server MUST be encrypted, as well as integrity and 445 replay protected. Furthermore, responses from the Authorization 446 Server to the caller MUST be bound to the caller's request. 448 The Authorization Server MUST implement measures to prevent access to 449 the TRL endpoint by entities other than registered devices and 450 authorized administrators. 452 The TRL endpoint supports only the GET method, and allows two types 453 of query of the TRL. 455 * Full query: the Authorization Server returns the token hashes of 456 the revoked Access Tokens currently in the TRL and pertaining to 457 the requester. The Authorization Server MUST support this type of 458 query. The processing of a full query and the related response 459 format are defined in Section 6. 461 * Diff query: the Authorization Server returns a list of diff 462 entries. Each diff entry is related to one of the most recent 463 updates, in the portion of the TRL pertaining to the requester. 464 The Authorization Server MAY support this type of query. 466 The entry associated with one of such updates contains a list of 467 token hashes, such that: i) the corresponding revoked Access 468 Tokens pertain to the requester; and ii) they were added to or 469 removed from the TRL at that update. The processing of a diff 470 query and the related response format are defined in Section 7. 472 The TRL endpoint allows the following query parameters in a GET 473 request. The Authorization Server MUST silently ignore unknown query 474 parameters. 476 * 'pmax': if included, it follows the semantics defined in 477 Section 3.2.2 of [I-D.ietf-core-conditional-attributes]. This 478 query parameter is relevant only in case the GET request is 479 specifically an Observation Request, i.e., if it includes the CoAP 480 Observe option set to 0 (register). In such a case, this 481 parameter indicates the maximum time, in seconds, between two 482 consecutive notifications for the observation in question, 483 regardless whether the TRL resource has changed or not. 485 If the Observation Request does not include the 'pmax' parameter, 486 the maximum time to consider is up to the Authorization Server. 487 If the Observation Request includes the 'pmax' parameter, its 488 value MUST be greater than zero, otherwise the Authorization 489 Server MUST return a 4.00 (Bad Request) response. 491 If the GET request is not an Observation Request, the 492 Authorization Server MUST ignore the 'pmax' parameter, in case 493 this is included. 495 * 'diff': if included, it indicates to perform a diff query of the 496 TRL (see Section 7). Its value MUST be either: 498 - the integer 0, indicating that a (notification) response should 499 include as many diff entries as the Authorization Server can 500 provide in the response; or 502 - a positive integer greater than 0, indicating the maximum 503 number of diff entries that a (notification) response should 504 include. 506 If the Authorization Server does not support diff queries, it 507 ignores the query parameter 'diff' when present in the GET request 508 and proceeds like when processing a full query of the TRL (see 509 Section 6). 511 6. Full Query of the TRL 513 In order to produce a (notification) response to a GET request asking 514 for a full query of the TRL, the Authorization Server performs the 515 following actions. 517 1. From the current TRL resource representation, the Authorization 518 Server builds a set HASHES, such that: 520 * If the requester is a registered device, HASHES specifies the 521 token hashes of the Access Tokens pertaining to that 522 registered device. The Authorization Server can use the 523 authenticated identity of the registered device to perform the 524 necessary filtering on the TRL resource representation. 526 * If the requester is an administrator, HASHES specifies all the 527 token hashes in the current TRL resource representation. 529 2. The Authorization Server sends a 2.05 (Content) Response to the 530 requester, with a CBOR array 'full-set' as payload. Each element 531 of the array specifies one of the token hashes from the set 532 HASHES, encoded as a CBOR byte string. 534 The order of the token hashes in the CBOR array is irrelevant, 535 i.e., the CBOR array MUST be treated as a set in which the order 536 has no significant meaning. 538 The CDDL definition [RFC8610] of the CBOR array 'full-set' specified 539 as payload in the response from the Authorization Server is provided 540 below. 542 token-hash = bytes 543 full-set = [* token-hash] 545 Figure 4: CDDL definition of the response payload following a 546 Full Query request to the TRL endpoint 548 7. Diff Query of the TRL 550 In order to produce a (notification) response to a GET request asking 551 for a diff query of the TRL, the Authorization Server performs the 552 following actions. 554 1. The Authorization Server defines the positive integer NUM. If 555 the value N specified in the query parameter 'diff' in the GET 556 request is equal to 0 or greater than a pre-defined positive 557 integer N_MAX, then NUM takes the value of N_MAX. Otherwise, NUM 558 takes N. 560 2. The Authorization Server prepares U = min(NUM, SIZE) diff 561 entries, where SIZE <= N_MAX is the number of TRL updates 562 pertaining to the requester and currently stored at the 563 Authorization Server. That is, the diff entries are related to 564 the U most recent TRL updates pertaining to the requester. In 565 particular, the first entry refers to the most recent of such 566 updates, the second entry refers to the second from last of such 567 updates, and so on. 569 Each diff entry is a CBOR array 'diff-entry', which includes the 570 following two elements. 572 * The first element is a CBOR array 'removed'. Each element of 573 the array is a CBOR byte string, with value the token hash of 574 an Access Token such that: it pertained to the requester; and 575 it was removed from the TRL during the update associated with 576 the diff entry. 578 * The second element is a CBOR array 'added'. Each element of 579 the array is a CBOR byte string, with value the token hash of 580 an Access Token such that: it pertains to the requester; and 581 it was added to the TRL during the update associated with the 582 diff entry. 584 The order of the token hashes in the CBOR arrays 'removed' and 585 'added' is irrelevant. That is, the CBOR arrays 'removed' and 586 'added' MUST be treated as a set in which the order of elements 587 has no significant meaning. 589 3. The Authorization Server prepares a 2.05 (Content) Response for 590 the requester, with a CBOR array 'diff-set' of U elements as 591 payload. Each element of the CBOR array 'diff-set' specifies one 592 of the CBOR arrays 'diff-entry' prepared at step 2 as diff 593 entries. 595 Within the CBOR array 'diff-set', the CBOR arrays 'diff-entry' 596 MUST be sorted to reflect the corresponding updates to the TRL in 597 reverse chronological order. That is, the first 'diff-entry' 598 element of 'diff-set' relates to the most recent update to the 599 portion of the TRL pertaining to the requester. The second 600 'diff-entry' element of 'diff-set' relates to the second from 601 last most recent update to that portion, and so on. 603 The CDDL definition [RFC8610] of the CBOR array 'diff-set' specified 604 as payload in the response from the Authorization Server is provided 605 below. 607 token-hash = bytes 608 trl-patch = [* token-hash] 609 diff-entry = [removed: trl-patch, added: trl-patch] 610 diff-set = [* diff-entry] 612 Figure 5: CDDL definition of the response payload following a 613 Diff Query request to the TRL endpoint 615 If the Authorization Server supports diff queries: 617 * The Authorization Server MUST return a 4.00 (Bad Request) response 618 in case the query parameter 'diff' of the GET request specifies a 619 value other than 0 or than a positive integer. 621 The response MUST have Content-Format "application/ace-trl+cbor". 622 The payload of the response is a CBOR map, which MUST include the 623 'error' field with value 0 ("Invalid parameter value") and MAY 624 include the 'error_description' field to provide additional 625 context. 627 * The Authorization Server MUST keep track of N_MAX most recent 628 updates to the portion of the TRL that pertains to each caller of 629 the TRL endpoint. The particular method to achieve this is 630 implementation-specific. 632 * When SIZE is equal to N_MAX, and a new TRL update occurs as 633 pertaining to a registered device, the Authorization Server MUST 634 first delete the oldest stored update for that device, before 635 storing this latest update as the most recent one for that device. 637 * The Authorization Server SHOULD provide registered devices and 638 administrators with the value of N_MAX, upon their registration 639 (see Section 8). 641 Appendix A discusses how performing a diff query of the TRL is in 642 fact a usage example of the Series Transfer Pattern defined in 643 [I-D.bormann-t2trg-stp]. 645 Appendix B discusses how the execution of a diff query of the TRL can 646 be further improved by using the "Cursor" pattern defined in 647 Section 3.3 of [I-D.bormann-t2trg-stp]. 649 8. Upon Registration 651 During the registration process at the Authorization Server, an 652 administrator or a registered device receives the following 653 information as part of the registration response. 655 * The url-path to the TRL endpoint at the Authorization Server. 657 * The hash function used to compute token hashes. This is specified 658 as an integer or a text string, taking value from the "ID" or 659 "Hash Name String" column of the "Named Information Hash 660 Algorithm" Registry [Named.Information.Hash.Algorithm], 661 respectively. 663 * Optionally, a positive integer N_MAX, if the Authorization Server 664 supports diff queries of the TRL resource (see Section 7). 666 After the registration procedure is finished, the administrator or 667 registered device can send a GET request to the TRL resource, 668 including the CoAP Observe option set to 0 (register), in order to 669 start an observation of the TRL resource at the Authorization Server 670 as per Section 3.1 of [RFC7641]. The GET request can express the 671 wish for a full query (see Section 6) or a diff query (see Section 7) 672 of the TRL. 674 In case the request is successfully processed, the Authorization 675 Server replies with a response specifying the CoAP response code 2.05 676 (Content) and including the CoAP Observe option. The payload of the 677 response is formatted as defined in Section 6 or in Section 7, in 678 case the GET yielded the execution of a full query or a diff query of 679 the TRL, respectively. 681 Further details about the registration process at the Authorization 682 Server are out of scope for this specification. Note that the 683 registration process is also out of the scope of the ACE framework 684 for Authentication and Authorization (see Section 5.5 of 685 [I-D.ietf-ace-oauth-authz]). 687 9. Notification of Revoked Tokens 689 When the TRL is updated (see Section 4.1), the Authorization Server 690 sends Observe Notifications to the observers of the TRL resource. 691 Observe Notifications are sent as per Section 4.2 of [RFC7641]. 693 If the 'pmax' query parameter was specified in the Observation 694 Request starting an observation (see Section 5), the Authorization 695 Server might accordingly send additional Observe Notifications to the 696 associated observer. That is, the Authorization Server ensures that 697 no more than pmax seconds elapse between two consecutive 698 notifications sent to that observer, regardless whether the TRL 699 resource has changed or not. If the 'pmax' query parameter was not 700 specified in the Observation Request, a possible maximum time to 701 consider is up to the Authorization Server. 703 The payload of each Observe Notification is formatted as defined in 704 Section 6 or in Section 7, in case the original Observation Request 705 yielded the execution of a full query or a diff query of the TRL, 706 respectively. 708 Furthermore, an administrator or a registered device can send 709 additional GET requests to the TRL endpoint at any time, in order to 710 retrieve the token hashes of the pertaining revoked Access Tokens. 711 When doing so, the caller of the TRL endpoint can perform a full 712 query (see Section 6) or a diff query (see Section 7). 714 When receiving a response from the TRL endpoint, a registered device 715 MUST expunge every stored Access Token associated with a token hash 716 specified in the response. 718 When a Resource Server RS receives a response from the TRL endpoint 719 specifying the token hash H associated with a certain revoked Access 720 Token, the RS might not have received and stored that Access Token 721 yet. This occurs if the Access Token is revoked before it is 722 successfully posted to the Authorization Information Endpoint at the 723 RS (see Section 5.10.1 of [I-D.ietf-ace-oauth-authz]). Such a delay 724 can be due, for example, to messages that get lost in transmission, 725 or rather to the Client experiencing failures in sending or 726 deliberately holding the Access Token back. 728 In such a case, the RS performs the following actions. 730 * The RS MUST store the token hash H, until gaining knowledge that 731 the associated revoked Access Token is also expired. 733 This can happen when receiving a subsequent response from the TRL 734 endpoint (i.e., indicating that the token hash is not in the TRL 735 portion pertaining to the RS anymore), or when the Access Token is 736 posted to the Authorization Information Endpoint and is found to 737 be expired based on its 'exp' claim [RFC7519], if included. 739 * The RS MUST NOT accept as valid and store an Access Token posted 740 to the Authorization Information Endpoint, if the corresponding 741 token hash H is among the stored ones. 743 10. Interaction Examples 745 This section provides examples of interactions between a Resource 746 Server RS as a registered device and an Authorization Server AS. The 747 Authorization Server supports both full query and diff query of the 748 TRL, as defined in Section 6 and Section 7, respectively. 750 The details of the registration process are omitted, but it is 751 assumed that the Resource Server sends an unspecified payload to the 752 Authorization Server, which replies with a 2.01 (Created) response. 754 The payload of the registration response is a CBOR map, which 755 includes the following entries: 757 * a "trl_path" parameter, specifying the path of the TRL resource; 759 * a "trl_hash" parameter, specifying the hash function used to 760 computed token hashes as defined in Section 3; 762 * an "n_max" parameter, specifying the value of N_MAX, i.e., the 763 maximum number of TRL updates pertaining to each registered device 764 that the Authorization Server retains for that device (see 765 Section 7); 767 * possible further parameters related to the registration process. 769 Furthermore, 'h(x)' refers to the hash function used to compute the 770 token hashes, as defined in Section 3 of this specification and 771 according to [RFC6920]. Assuming the usage of CWTs transported in 772 CBOR, 'bstr.h(t1)' and 'bstr.h(t2)' denote the byte-string 773 representations of the token hashes for the Access Tokens t1 and t2, 774 respectively. 776 10.1. Full Query with Observation 778 Figure 6 shows an interaction example considering a CoAP observation 779 and a full query of the TRL. 781 RS AS 782 | | 783 | Registration: POST | 784 +-------------------------------------->| 785 | | 786 |<--------------------------------------+ 787 | 2.01 CREATED | 788 | Payload: { | 789 | ... | 790 | "trl_path" = "revoke/trl", | 791 | "trl_hash" = "sha-256", | 792 | "n_max" = 10 | 793 | } | 794 | | 795 | GET Observe: 0 | 796 | coap://example.as.com/revoke/trl/ | 797 +-------------------------------------->| 798 | | 799 |<--------------------------------------+ 800 | 2.05 CONTENT Observe: 42 | 801 | Payload: [] | 802 | . | 803 | . | 804 | . | 805 | | 806 | (Access Tokens t1 and t2 issued | 807 | and successfully submitted to RS) | 808 | . | 809 | . | 810 | . | 811 | | 812 | | 813 | (Access Token t1 is revoked) | 814 | | 815 |<--------------------------------------+ 816 | 2.05 CONTENT Observe: 53 | 817 | Payload: [bstr.h(t1)] | 818 | . | 819 | . | 820 | . | 821 | | 822 | (Access Token t2 is revoked) | 823 | | 824 |<--------------------------------------+ 825 | 2.05 CONTENT Observe: 64 | 826 | Payload: [bstr.h(t1), | 827 | bstr.h(t2)] | 828 | . | 829 | . | 830 | . | 831 | | 832 | (Access Token t1 expires) | 833 | | 834 |<--------------------------------------+ 835 | 2.05 CONTENT Observe: 75 | 836 | Payload: [bstr.h(t2)] | 837 | . | 838 | . | 839 | . | 840 | | 841 | (Access Token t2 expires) | 842 | | 843 |<--------------------------------------+ 844 | 2.05 CONTENT Observe: 86 | 845 | Payload: [] | 846 | | 848 Figure 6: Interaction for Full Query with Observation 850 10.2. Diff Query with Observation 852 Figure 7 shows an interaction example considering a CoAP observation 853 and a diff query of the TRL. 855 The Resource Server indicates N=3 as value of the query parameter 856 "diff", i.e., as the maximum number of diff entries to be specified 857 in a response from the Authorization Server. 859 RS AS 860 | | 861 | Registration: POST | 862 +--------------------------------------------->| 863 | | 864 |<---------------------------------------------+ 865 | 2.01 CREATED | 866 | Payload: { | 867 | ... | 868 | "trl_path" = "revoke/trl", | 869 | "trl_hash" = "sha-256", | 870 | "n_max" = 10 | 871 | } | 872 | | 873 | GET Observe: 0 | 874 | coap://example.as.com/revoke/trl?diff=3 | 875 +--------------------------------------------->| 876 | | 877 |<---------------------------------------------+ 878 | 2.05 CONTENT Observe: 42 | 879 | Payload: [] | 880 | . | 881 | . | 882 | . | 883 | | 884 | (Access Tokens t1 and t2 issued | 885 | and successfully submitted to RS) | 886 | . | 887 | . | 888 | . | 889 | | 890 | (Access Token t1 is revoked) | 891 | | 892 |<---------------------------------------------+ 893 | 2.05 CONTENT Observe: 53 | 894 | Payload: [ | 895 | [ [], [bstr.h(t1)] ] | 896 | ] | 897 | | 898 | | 899 | . | 900 | . | 901 | . | 902 | | 903 | (Access Token t2 is revoked) | 904 | | 905 |<---------------------------------------------+ 906 | 2.05 CONTENT Observe: 64 | 907 | Payload: [ | 908 | [ [], [bstr.h(t2)] ], | 909 | [ [], [bstr.h(t1)] ] | 910 | ] | 911 | . | 912 | . | 913 | . | 914 | | 915 | (Access Token t1 expires) | 916 | | 917 |<---------------------------------------------+ 918 | 2.05 CONTENT Observe: 75 | 919 | Payload: [ | 920 | [ [bstr.h(t1)], [] ], | 921 | [ [], [bstr.h(t2)] ], | 922 | [ [], [bstr.h(t1)] ] | 923 | ] | 924 | . | 925 | . | 926 | . | 927 | | 928 | (Access Token t2 expires) | 929 | | 930 |<---------------------------------------------+ 931 | 2.05 CONTENT Observe: 86 | 932 | Payload: [ | 933 | [ [bstr.h(t2)], [] ], | 934 | [ [bstr.h(t1)], [] ], | 935 | [ [], [bstr.h(t2)] ] | 936 | ] | 937 | | 939 Figure 7: Interaction for Diff Query with Observation 941 10.3. Full Query with Observation and Additional Diff Query 943 Figure 8 shows an interaction example considering a CoAP observation 944 and a full query of the TRL. 946 The example also considers one of the notifications from the 947 Authorization Server to get lost in transmission, and thus not 948 reaching the Resource Server. 950 When this happens, and after a waiting time defined by the 951 application has elapsed, the Resource Server sends a GET request with 952 no Observe Option to the Authorization Server, to perform a diff 953 query of the TRL. The Resource Server indicates N=8 as value of the 954 query parameter "diff", i.e., as the maximum number of diff entries 955 to be specified in a response from the Authorization Server. 957 RS AS 958 | | 959 | Registration: POST | 960 +--------------------------------------------->| 961 | | 962 |<---------------------------------------------+ 963 | 2.01 CREATED | 964 | Payload: { | 965 | ... | 966 | "trl_path" = "revoke/trl", | 967 | "trl_hash" = "sha-256", | 968 | "n_max" = 10 | 969 | } | 970 | | 971 | GET Observe: 0 | 972 | coap://example.as.com/revoke/trl/ | 973 +--------------------------------------------->| 974 | | 975 |<---------------------------------------------+ 976 | 2.05 CONTENT Observe: 42 | 977 | Payload: [] | 978 | . | 979 | . | 980 | . | 981 | | 982 | (Access Tokens t1 and t2 issued | 983 | and successfully submitted to RS) | 984 | . | 985 | . | 986 | . | 987 | | 988 | (Access Token t1 is revoked) | 989 | | 990 |<---------------------------------------------+ 991 | 2.05 CONTENT Observe: 53 | 992 | Payload: [bstr.h(t1)] | 993 | | 994 | . | 995 | . | 996 | . | 997 | | 998 | (Access Token t2 is revoked) | 999 | | 1000 |<---------------------------------------------+ 1001 | 2.05 CONTENT Observe: 64 | 1002 | Payload: [bstr.h(t1), | 1003 | bstr.h(t2)] | 1004 | . | 1005 | . | 1006 | . | 1007 | | 1008 | (Access Token t1 expires) | 1009 | | 1010 |<---------------------------------------------+ 1011 | 2.05 CONTENT Observe: 75 | 1012 | Payload: [bstr.h(t2)] | 1013 | . | 1014 | . | 1015 | . | 1016 | | 1017 | (Access Token t2 expires) | 1018 | | 1019 | X<-------------------------------------+ 1020 | 2.05 CONTENT Observe: 86 | 1021 | Payload: [] | 1022 | . | 1023 | . | 1024 | . | 1025 | | 1026 | (Enough time has passed since | 1027 | the latest received notification) | 1028 | | 1029 | GET | 1030 | coap://example.as.com/revoke/trl?diff=8 | 1031 +--------------------------------------------->| 1032 | | 1033 |<---------------------------------------------+ 1034 | 2.05 CONTENT | 1035 | Payload: [ | 1036 | [ [bstr.h(t2)], [] ], | 1037 | [ [bstr.h(t1)], [] ], | 1038 | [ [], [bstr.h(t2)] ], | 1039 | [ [], [bstr.h(t1)] ] | 1040 | ] | 1041 | | 1043 Figure 8: Interaction for Full Query with Observation and Diff Query 1045 11. ACE Token Revocation List Parameters 1047 This specification defines a number of parameters that can be 1048 transported in the response from the TRL endpoint, when the response 1049 payload is encoded as a CBOR map. Note that such a response MUST use 1050 the Content-Format "application/ace-trl+cbor" defined in Section 14.2 1051 of this specification. 1053 The table below summarizes them, and specifies the CBOR value to use 1054 as abbreviation instead of the full descriptive name. 1056 +-------------------+------------+-----------------------+ 1057 | Name | CBOR Value | CBOR Type | 1058 +-------------------+------------+-----------------------+ 1059 | full-set | TBD | array | 1060 | | | | 1061 +-------------------+------------+-----------------------+ 1062 | cursor | TBD | simple value "null" / | 1063 | | | unsigned integer | 1064 +-------------------+------------+-----------------------+ 1065 | diff-set | TBD | array | 1066 | | | | 1067 +-------------------+------------+-----------------------+ 1068 | more | TBD | simple value "true" | 1069 | | | or "false" | 1070 +-------------------+------------+-----------------------+ 1071 | error | TBD | int | 1072 | | | | 1073 +-------------------+------------+-----------------------+ 1074 | error_description | TBD | tstr | 1075 | | | | 1076 +-------------------+------------+-----------------------+ 1078 Figure 9: CBOR abbreviations for the ACE Token Revocation List 1079 parameters 1081 12. ACE Token Revocation List Error Identifiers 1083 This specification defines a number of values that the Authorization 1084 Server can include as error identifiers, in the 'error' field of an 1085 error response from the TRL endpoint. This applies to error 1086 responses whose payload is encoded as a CBOR map and whose Content- 1087 Format is "application/ace-trl+cbor". 1089 +-------+---------------------------+ 1090 | Value | Description | 1091 +-------+---------------------------+ 1092 | 0 | Invalid parameter value | 1093 +-------+---------------------------+ 1094 | 1 | Invalid set of parameters | 1095 +-------+---------------------------+ 1096 | 2 | Out of bound cursor value | 1097 +-------+---------------------------+ 1099 Figure 10: ACE Token Revocation List Error Identifiers 1101 13. Security Considerations 1103 Security considerations are inherited from the ACE framework for 1104 Authentication and Authorization [I-D.ietf-ace-oauth-authz], from 1105 [RFC8392] as to the usage of CWTs, from [RFC7519] as to the usage of 1106 JWTs, from [RFC7641] as to the usage of CoAP Observe, and from 1107 [RFC6920] with regard to resource naming through hashes. The 1108 following considerations also apply. 1110 The Authorization Server MUST ensure that each registered device can 1111 access and retrieve only its pertaining portion of the TRL. To this 1112 end, the Authorization Server can perform the required filtering 1113 based on the authenticated identity of the registered device, i.e., a 1114 (non-public) identifier that the Authorization Server can securely 1115 relate to the registered device and the secure association they use 1116 to communicate. 1118 Disclosing any information about revoked Access Tokens to entities 1119 other than the intended registered devices may result in privacy 1120 concerns. Therefore, the Authorization Server MUST ensure that, 1121 other than registered devices accessing their own pertaining portion 1122 of the TRL, only authorized and authenticated administrators can 1123 retrieve the full TRL. To this end, the Authorization Server may 1124 rely on an access control list or similar. 1126 If a registered device has many non-expired Access Tokens associated 1127 with itself that are revoked, the pertaining portion of the TRL could 1128 grow to a size bigger than what the registered device is prepared to 1129 handle upon reception, especially if relying on a full query of the 1130 TRL resource (see Section 6). This could be exploited by attackers 1131 to negatively affect the behavior of a registered device. Issuing 1132 Access Tokens with not too long expiration time could help reduce the 1133 size of a TRL, but an Authorization Server SHOULD take measures to 1134 limit this size. 1136 Most of the communication about revoked Access Tokens presented in 1137 this specification relies on CoAP Observe Notifications sent from the 1138 Authorization Server to a registered device. The suppression of 1139 those notifications by an external attacker that has access to the 1140 network would prevent registered devices from ever knowing that their 1141 pertaining Access Tokens have been revoked. To avoid this, a 1142 registered device SHOULD NOT rely solely on the CoAP Observe 1143 notifications. In particular, a registered device SHOULD also 1144 regularly poll the Authorization Server for the most current 1145 information about revoked Access Tokens, by sending GET requests to 1146 the TRL endpoint according to a related application policy. 1148 14. IANA Considerations 1150 RFC EDITOR: Throughout this section, please replace [this document] 1151 with the RFC number of this specification and remove this note. 1153 This document has the following actions for IANA. 1155 14.1. Media Type Registrations 1157 IANA is asked to register the media type "application/ace-trl+cbor" 1158 for messages of the protocols defined in this document encoded in 1159 CBOR. This registration follows the procedures specified in 1160 [RFC6838]. 1162 Type name: application 1164 Subtype name: ace-trl+cbor 1166 Required parameters: N/A 1168 Optional parameters: N/A 1170 Encoding considerations: Must be encoded as CBOR map containing the 1171 protocol parameters defined in [this document]. 1173 Security considerations: See Section 13 of this document. 1175 Interoperability considerations: N/A 1177 Published specification: [this document] 1179 Applications that use this media type: The type is used by 1180 Authorization Servers, Clients and Resource Servers that support the 1181 notification of revoked Access Tokens, according to a Token 1182 Revocation List maintained by the Authorization Server as specified 1183 in [this document]. 1185 Fragment identifier considerations: N/A 1187 Additional information: N/A 1189 Person & email address to contact for further information: 1190 1192 Intended usage: COMMON 1194 Restrictions on usage: None 1196 Author: Marco Tiloca 1198 Change controller: IESG 1200 14.2. CoAP Content-Formats Registry 1202 IANA is asked to add the following entry to the "CoAP Content- 1203 Formats" registry within the "CoRE Parameters" registry group. 1205 Media Type: application/ace-trl+cbor 1207 Encoding: - 1209 ID: TBD 1211 Reference: [this document] 1213 14.3. ACE Token Revocation List Parameters Registry 1215 This specification establishes the "ACE Token Revocation List 1216 Parameters" IANA registry. The registry has been created to use the 1217 "Expert Review" registration procedure [RFC8126]. Expert review 1218 guidelines are provided in Section 14.5. It should be noted that, in 1219 addition to the expert review, some portions of the registry require 1220 a specification, potentially a Standards Track RFC, to be supplied as 1221 well. 1223 The columns of this registry are: 1225 * Name: This is a descriptive name that enables easier reference to 1226 the item. The name MUST be unique. It is not used in the 1227 encoding. 1229 * CBOR Value: This is the value used as CBOR abbreviation of the 1230 item. These values MUST be unique. The value can be a positive 1231 integer or a negative integer. Different ranges of values use 1232 different registration policies [RFC8126]. Integer values from 1233 -256 to 255 are designated as Standards Action. Integer values 1234 from -65536 to -257 and from 256 to 65535 are designated as 1235 Specification Required. Integer values greater than 65535 are 1236 designated as Expert Review. Integer values less than -65536 are 1237 marked as Private Use. 1239 * CBOR Type: This contains the CBOR type of the item, or a pointer 1240 to the registry that defines its type, when that depends on 1241 another item. 1243 * Reference: This contains a pointer to the public specification for 1244 the item. 1246 This registry has been initially populated by the values in 1247 Section 11. The Reference column for all of these entries refers to 1248 this document. 1250 14.4. ACE Token Revocation List Errors 1252 This specification establishes the "ACE Token Revocation List Errors" 1253 IANA registry. The registry has been created to use the "Expert 1254 Review" registration procedure [RFC8126]. Expert review guidelines 1255 are provided in Section 14.5. It should be noted that, in addition 1256 to the expert review, some portions of the registry require a 1257 specification, potentially a Standards Track RFC, to be supplied as 1258 well. 1260 The columns of this registry are: 1262 * Value: The value to be used to identify the error. The value MUST 1263 be unique. The value can be a positive integer or a negative 1264 integer. Integer values between 0 and 255 are designated as 1265 Standards Track Document required. Integer values from 256 to 1266 65535 are designated as Specification Required. Integer values 1267 greater than 65535 are designated as expert review. Integer 1268 values less than -65536 are marked as private use. 1270 * Description: This field contains a brief description of the error. 1272 * Reference: This field contains a pointer to the public 1273 specification defining the error, if one exists. 1275 This registry has been initially populated by the values in 1276 Section 12. The Reference column for all of these entries refers to 1277 this document. 1279 14.5. Expert Review Instructions 1281 The IANA registries established in this document is defined as expert 1282 review. This section gives some general guidelines for what the 1283 experts should be looking for, but they are being designated as 1284 experts for a reason so they should be given substantial latitude. 1286 Expert reviewers should take into consideration the following points: 1288 * Point squatting should be discouraged. Reviewers are encouraged 1289 to get sufficient information for registration requests to ensure 1290 that the usage is not going to duplicate one that is already 1291 registered and that the point is likely to be used in deployments. 1292 The zones tagged as private use are intended for testing purposes 1293 and closed environments, code points in other ranges should not be 1294 assigned for testing. 1296 * Specifications are required for the standards track range of point 1297 assignment. Specifications should exist for specification 1298 required ranges, but early assignment before a specification is 1299 available is considered to be permissible. Specifications are 1300 needed for the first-come, first-serve range if they are expected 1301 to be used outside of closed environments in an interoperable way. 1302 When specifications are not provided, the description provided 1303 needs to have sufficient information to identify what the point is 1304 being used for. 1306 * Experts should take into account the expected usage of fields when 1307 approving point assignment. The fact that there is a range for 1308 standards track documents does not mean that a standards track 1309 document cannot have points assigned outside of that range. The 1310 length of the encoded value should be weighed against how many 1311 code points of that length are left, the size of device it will be 1312 used on, and the number of code points left that encode to that 1313 size. 1315 15. References 1317 15.1. Normative References 1319 [I-D.ietf-ace-oauth-authz] 1320 Seitz, L., Selander, G., Wahlstroem, E., Erdtman, S., and 1321 H. Tschofenig, "Authentication and Authorization for 1322 Constrained Environments (ACE) using the OAuth 2.0 1323 Framework (ACE-OAuth)", Work in Progress, Internet-Draft, 1324 draft-ietf-ace-oauth-authz-46, 8 November 2021, 1325 . 1328 [I-D.ietf-core-conditional-attributes] 1329 Koster, M., Soloway, A., and B. Silverajan, "Conditional 1330 Attributes for Constrained RESTful Environments", Work in 1331 Progress, Internet-Draft, draft-ietf-core-conditional- 1332 attributes-02, 24 February 2022, 1333 . 1336 [Named.Information.Hash.Algorithm] 1337 IANA, "Named Information Hash Algorithm", 1338 . 1341 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1342 Requirement Levels", BCP 14, RFC 2119, 1343 DOI 10.17487/RFC2119, March 1997, 1344 . 1346 [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", 1347 RFC 6749, DOI 10.17487/RFC6749, October 2012, 1348 . 1350 [RFC6838] Freed, N., Klensin, J., and T. Hansen, "Media Type 1351 Specifications and Registration Procedures", BCP 13, 1352 RFC 6838, DOI 10.17487/RFC6838, January 2013, 1353 . 1355 [RFC6920] Farrell, S., Kutscher, D., Dannewitz, C., Ohlman, B., 1356 Keranen, A., and P. Hallam-Baker, "Naming Things with 1357 Hashes", RFC 6920, DOI 10.17487/RFC6920, April 2013, 1358 . 1360 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 1361 Application Protocol (CoAP)", RFC 7252, 1362 DOI 10.17487/RFC7252, June 2014, 1363 . 1365 [RFC7519] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token 1366 (JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015, 1367 . 1369 [RFC7641] Hartke, K., "Observing Resources in the Constrained 1370 Application Protocol (CoAP)", RFC 7641, 1371 DOI 10.17487/RFC7641, September 2015, 1372 . 1374 [RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for 1375 Writing an IANA Considerations Section in RFCs", BCP 26, 1376 RFC 8126, DOI 10.17487/RFC8126, June 2017, 1377 . 1379 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 1380 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 1381 May 2017, . 1383 [RFC8259] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 1384 Interchange Format", STD 90, RFC 8259, 1385 DOI 10.17487/RFC8259, December 2017, 1386 . 1388 [RFC8392] Jones, M., Wahlstroem, E., Erdtman, S., and H. Tschofenig, 1389 "CBOR Web Token (CWT)", RFC 8392, DOI 10.17487/RFC8392, 1390 May 2018, . 1392 [RFC8610] Birkholz, H., Vigano, C., and C. Bormann, "Concise Data 1393 Definition Language (CDDL): A Notational Convention to 1394 Express Concise Binary Object Representation (CBOR) and 1395 JSON Data Structures", RFC 8610, DOI 10.17487/RFC8610, 1396 June 2019, . 1398 [RFC8949] Bormann, C. and P. Hoffman, "Concise Binary Object 1399 Representation (CBOR)", STD 94, RFC 8949, 1400 DOI 10.17487/RFC8949, December 2020, 1401 . 1403 15.2. Informative References 1405 [I-D.bormann-t2trg-stp] 1406 Bormann, C. and K. Hartke, "The Series Transfer Pattern 1407 (STP)", Work in Progress, Internet-Draft, draft-bormann- 1408 t2trg-stp-03, 7 April 2020, 1409 . 1412 [RFC7009] Lodderstedt, T., Ed., Dronia, S., and M. Scurtescu, "OAuth 1413 2.0 Token Revocation", RFC 7009, DOI 10.17487/RFC7009, 1414 August 2013, . 1416 Appendix A. On using the Series Transfer Pattern 1418 Performing a diff query of the TRL as specified in Section 7 is a 1419 usage example of the Series Transfer Pattern defined in 1420 [I-D.bormann-t2trg-stp]. 1422 That is, a diff query enables the transfer of a series of TRL 1423 updates, with the Authorization Server specifying U <= N_MAX diff 1424 entries as the U most recent updates to the portion of the TRL 1425 pertaining to a registered device. 1427 For each registered device, the Authorization Server maintains an 1428 update collection of maximum N_MAX items. Each time the TRL changes, 1429 the Authorization Server performs the following operations for each 1430 registered device. 1432 1. The Authorization Server considers the portion of the TRL 1433 pertaining to that registered device. If the TRL portion is not 1434 affected by this TRL update, the Authorization Server stops the 1435 processing for that registered device. 1437 2. Otherwise, the Authorization Server creates two sets 'trl_patch' 1438 of token hashes, i.e., one "removed" set and one "added" set, as 1439 related to this TRL update. 1441 3. The Authorization Server fills the two sets with the token hashes 1442 of the removed and added Access Tokens, respectively, from/to the 1443 TRL portion from step 1. 1445 4. The Authorization Server creates a new series item including the 1446 two sets from step 3, and adds the series item to the update 1447 collection associated with the registered device. 1449 When responding to a diff query request from a registered device (see 1450 Section 7), 'diff-set' is a subset of the collection associated with 1451 the requester, where each 'diff_entry' record is a series item from 1452 that collection. Note that 'diff-set' specifies the whole current 1453 collection when the value of U is equal to SIZE, i.e., the current 1454 number of series items in the collection. 1456 The value N of the query parameter 'diff' in the GET request allows 1457 the requester and the Authorization Server to trade the amount of 1458 provided information with the latency of the information transfer. 1460 Since the collection associated with each registered device includes 1461 up to N_MAX series item, the Authorization Server deletes the oldest 1462 series item when a new one is generated and added to the end of the 1463 collection, due to a new TRL update pertaining to that registered 1464 device. This addresses the question "When can the server decide to 1465 no longer retain older items?" in Section 3.2 of 1466 [I-D.bormann-t2trg-stp]. 1468 Appendix B. Usage of the "Cursor" Pattern 1470 This section defines how the execution of a diff query of the TRL 1471 specified in Section 7 can be extended, by using the "Cursor" pattern 1472 of the Series Transfer Pattern (see Section 3.3 of 1473 [I-D.bormann-t2trg-stp]). 1475 [ TODO 1477 Merge what is defined below into the document body. 1479 * What is defined below for "Full Query Response" becomes part of 1480 the full query processing in the document body. The successful 1481 response payload is a CBOR map if the AS supports both the "Diff 1482 Query" mode and the "Cursor" pattern, or just the CBOR array full- 1483 set otherwise. 1485 * The diff-query processing in the document body becomes as defined 1486 below for "Diff Query Request" and "Diff Query Response". The 1487 successful response payload is a CBOR map if the AS supports both 1488 the "Diff Query" mode and the "Cursor" pattern, or just the CBOR 1489 array diff-set otherwise. 1491 * An example using also the "Cursor" pattern can be added in 1492 "Interaction Examples". 1494 ] 1496 This has two benefits. First, the Authorization Server can avoid 1497 excessively big latencies when several diff entries have to be 1498 transferred, by delivering one adjacent subset at the time, in 1499 different diff query responses. Second, a requester can retrieve 1500 diff entries associated with TRL updates that, even if not the most 1501 recent ones, occurred after a TRL update indicated as reference 1502 point. 1504 To this end, each series item X in an update collection is also 1505 associated with an unsigned integer 'index', with value the absolute 1506 counter of series items added to that collection until and including 1507 X, minus 1. That is, the first series item added to a collection has 1508 'index' with value 0. Then, the values of 'index' are used as cursor 1509 information. 1511 Within an update collection, the unsigned integer LAST_INDEX denotes 1512 the value of 'index' associated with the latest added series item, 1513 i.e., the total number of series items added to the collection minus 1514 1. 1516 Furthermore, the Authorization Server defines an unsigned integer 1517 MAX_DIFF_BATCH <= N_MAX, specifying the maximum number of diff 1518 entries to be included in a single diff query response. If 1519 supporting diff queries, the Authorization Server SHOULD provide 1520 registered devices and administrators with the value of 1521 MAX_DIFF_BATCH, upon their registration (see Section 8). 1523 Finally, the full query and diff query exchanges defined in Section 6 1524 and Section 7 are extended as follows. 1526 In particular, successful responses from the TRL endpoint MUST use 1527 the Content-Format "application/ace-trl+cbor" defined in Section 14.2 1528 of this specification. 1530 B.1. Full Query Request 1532 No changes apply to what is defined in Section 6. 1534 B.2. Full Query Response 1536 When sending a 2.05 (Content) response to a full query request (see 1537 Appendix B.1), the response payload includes a CBOR map with the 1538 following fields, whose CBOR labels are defined in Section 11. 1540 * 'full-set': this field MUST include a CBOR array of token hashes. 1541 The CBOR array is populated and formatted as defined for the CBOR 1542 array 'full-set' in Section 6. 1544 * 'cursor': this field MUST include either the CBOR simple value 1545 "null" (0xf6) or a CBOR unsigned integer. 1547 The CBOR simple value "null" MUST be used to indicate that there 1548 are currently no TRL updates pertinent to the requester, i.e., the 1549 update collection for that requester is empty. This is the case 1550 from when the requester registers at the Authorization Server 1551 until a first update pertaining that requester occurs to the TRL. 1553 Otherwise, the field MUST include a CBOR unsigned integer, 1554 encoding the 'index' value of the last series item in the 1555 collection, as corresponding to the most recent update pertaining 1556 to the requester occurred to the TRL. 1558 B.3. Diff Query Request 1560 In addition to the query parameter 'diff' (see Section 7), the 1561 requester can specify a query parameter 'cursor', with value an 1562 unsigned integer. 1564 The Authorization Server MUST return a 4.00 (Bad Request) response in 1565 case the query parameter 'cursor' is present but the query parameter 1566 'diff' is not present. The response MUST have Content-Format 1567 "application/ace-trl+cbor". The payload of the response is a CBOR 1568 map, which MUST include the 'error' field with value 1 ("Invalid set 1569 of parameters") and MAY include the 'error_description' field to 1570 provide additional context. 1572 B.4. Diff Query Response 1574 The Authorization Server composes a response to a diff query request 1575 (see Appendix B.3) as follows, depending on the parameters specified 1576 in the request and on the current status of the update collection for 1577 the requester. 1579 B.4.1. Empty Collection 1581 If the collection associated with the requester has no elements, the 1582 Authorization Server returns a 2.05 (Content) diff query response. 1584 The response payload includes a CBOR map with the following fields, 1585 whose CBOR labels are defined in Section 11. 1587 * 'diff-set': this field MUST include an empty CBOR array. 1589 * 'cursor': this field MUST include the CBOR simple value "null" 1590 (0xf6). 1592 * 'more': this field MUST include the CBOR simple value "false" 1593 (0xf4). 1595 B.4.2. Cursor Not Specified in the Diff Query Request 1597 If the update collection associated with the requester is not empty 1598 and the diff query request does not include the query parameter 1599 'cursor', the Authorization Server returns a 2.05 (Content) diff 1600 query response. 1602 The response payload includes a CBOR map with the following fields, 1603 whose CBOR labels are defined in Section 11. 1605 * 'diff-set': this field MUST include a CBOR array, containing L = 1606 min(U, MAX_DIFF_BATCH) diff entries. In particular, the CBOR 1607 array is populated as follows. 1609 - If U <= MAX_DIFF_BATCH, these diff entries are the last series 1610 items in the collection associated with the requester, 1611 corresponding to the L most recent TRL updates pertaining to 1612 the requester. 1614 - If U > MAX_DIFF_BATCH, these diff entries are the eldest of the 1615 last U series items in the collection associated with the 1616 requester, as corresponding to the first L of the U most recent 1617 TRL updates pertaining to the requester. 1619 The 'diff-set' CBOR array as well as the individual diff entries 1620 have the same format specified in Figure 5 and used for the 1621 response payload defined in Section 7. 1623 * 'cursor': this field MUST include a CBOR unsigned integer. This 1624 takes the 'index' value of the series element of the collection 1625 included as first diff entry in the 'diff-set' CBOR array. That 1626 is, it takes the 'index' value of the series item in the 1627 collection corresponding to the most recent update pertaining to 1628 the requester and returned in this diff query response. 1630 Note that 'cursor' takes the same 'index' value of the last series 1631 item in the collection when U <= MAX_DIFF_BATCH. 1633 * 'more': this field MUST include the CBOR simple value "false" 1634 (0xf4) if U <= MAX_DIFF_BATCH, or the CBOR simple value "true" 1635 (0xf5) otherwise. 1637 If 'more' has value "true", the requester can send a follow-up 1638 diff query request including the query parameter 'cursor', with 1639 the same value of the 'cursor' field included in this diff query 1640 response. As defined in Appendix B.4.3, this would result in the 1641 Authorization Server transferring the following subset of series 1642 items as diff entries, i.e., resuming from where interrupted in 1643 the previous transfer. 1645 B.4.3. Cursor Specified in the Diff Query Request 1647 If the update collection associated with the requester is not empty 1648 and the diff query request includes the query parameter 'cursor' with 1649 value P, the Authorization Server proceeds as follows. 1651 * The Authorization Server MUST return a 4.00 (Bad Request) response 1652 in case the query parameter 'cursor' specifies a value other than 1653 0 or than a positive integer. 1655 The response MUST have Content-Format "application/ace-trl+cbor". 1656 The payload of the response is a CBOR map, which MUST include the 1657 'error' field with value 0 ("Invalid parameter value") and MAY 1658 include the 'error_description' field to provide additional 1659 context. 1661 * The Authorization Server MUST return a 4.00 (Bad Request) response 1662 in case the 'cursor' parameter specifies a value strictly greater 1663 than the current LAST_INDEX for the update collection associated 1664 with the requester. 1666 The response MUST have Content-Format "application/ace-trl+cbor". 1667 The payload of the response is a CBOR map, which MUST include the 1668 'error' field with value 2 ("Out of bound cursor value") and the 1669 'cursor' field with value the current LAST_INDEX for the update 1670 collection associated with the requester. The CBOR map MAY also 1671 include the 'error_description' field to provide additional 1672 context. 1674 * The Authorization Server returns a 2.05 (Content) diff query 1675 response formatted as follows, in case the series item X with 1676 'index' having value P and the series item Y with 'index' having 1677 value P+1 are both not found in the collection associated with the 1678 requester. This occurs when the item Y (and possibly further ones 1679 after it) has been previously removed from the history of updates 1680 for that requester (see Appendix A). 1682 The response payload includes a CBOR map with the following 1683 fields, whose CBOR labels are defined in Section 11. 1685 - 'diff-set': this field MUST include an empty CBOR array. 1687 - 'cursor': this field MUST include the CBOR simple value "null" 1688 (0xf6). 1690 - 'more': this field MUST include the CBOR simple value "true" 1691 (0xf5). 1693 With the combination ('cursor', 'more') = ("null", "true"), the 1694 Authorization Server is signaling that the update collection is in 1695 fact not empty, but that one or more series items have been lost 1696 due to their removal. These include the item with 'index' value 1697 P+1, that the requester wished to obtain as the first one 1698 following the specified reference point with 'index' value P. 1700 When receiving this diff query response, the requester should send 1701 a new full query request to the Authorization Server, in order to 1702 fully retrieve the current pertaining portion of the TRL. 1704 * The Authorization Server returns a 2.05 (Content) diff query 1705 response formatted as follows, in case i) the series item X with 1706 'index' having value P is found in the collection associated with 1707 the requester; or ii) the series item X is not found and the 1708 series item Y with 'index' having value P+1 is found in the 1709 collection associated with the requester. 1711 The response payload includes a CBOR map with the following 1712 fields, whose CBOR labels are defined in Section 11. 1714 - 'diff-set': this field MUST include a CBOR array, containing L 1715 = min(SUB_U, MAX_DIFF_BATCH) diff entries, where SUB_U = 1716 min(NUM, SUB_SIZE), and SUB_SIZE is the number of series items 1717 in the collection following the series item X. 1719 That is, these are the L updates pertaining to the requester 1720 that immediately follow the series item X indicated as 1721 reference point. In particular, the CBOR array is populated as 1722 follows. 1724 o If SUB_U <= MAX_DIFF_BATCH, these diff entries are the last 1725 series items in the collection associated with the 1726 requester, corresponding to the L most recent TRL updates 1727 pertaining to the requester. 1729 o If SUB_U > MAX_DIFF_BATCH, these diff entries are the eldest 1730 of the last SUB_U series items in the collection associated 1731 with the requester, corresponding to the first L of the 1732 SUB_U most recent TRL updates pertaining to the requester. 1734 The 'diff-set' CBOR array as well as the individual diff 1735 entries have the same format specified in Figure 5 and used for 1736 the response payload defined in Section 7. 1738 - 'cursor': this field MUST include a CBOR unsigned integer. In 1739 particular: 1741 o If L is equal to 0, i.e., the series item X is the last one 1742 in the collection, 'cursor' takes the same 'index' value of 1743 the last series item in the collection. 1745 o If L is different than 0, 'cursor' takes the 'index' value 1746 of the series element of the collection included as first 1747 diff entry in the 'diff-set' CBOR array. That is, it takes 1748 the 'index' value of the series item in the collection 1749 corresponding to the most recent update pertaining to the 1750 requester and returned in this diff query response. 1752 Note that 'cursor' takes the same 'index' value of the last 1753 series item in the collection when SUB_U <= MAX_DIFF_BATCH. 1755 - 'more': this field MUST include the CBOR simple value "false" 1756 (0xf4) if SUB_U <= MAX_DIFF_BATCH, or the CBOR simple value 1757 "true" (0xf5) otherwise. 1759 If 'more' has value "true", the requester can send a follow-up 1760 diff query request including the query parameter 'cursor', with 1761 the same value of the 'cursor' field specified in this diff 1762 query response. This would result in the Authorization Server 1763 transferring the following subset of series items as diff 1764 entries, i.e., resuming from where interrupted in the previous 1765 transfer. 1767 Appendix C. Document Updates 1769 RFC EDITOR: Please remove this section. 1771 C.1. Version -00 to -01 1773 * Added actions to perform upon receiving responses from the TRL 1774 endpoint. 1776 * Fixed off-by-one error when using the "Cursor" pattern. 1778 * Improved error handling, with registered error codes. 1780 * Section restructuring (full- and diff-query as self-standing 1781 sections). 1783 * Renamed identifiers and CBOR parameters. 1785 * Clarifications and editorial improvements. 1787 Acknowledgments 1789 The authors sincerely thank Carsten Bormann, Benjamin Kaduk, Marco 1790 Rasori, Michael Richardson, Jim Schaad, Goeran Selander and Travis 1791 Spencer for their comments and feedback. 1793 The work on this document has been partly supported by VINNOVA and 1794 the Celtic-Next project CRITISEC; and by the H2020 project SIFIS-Home 1795 (Grant agreement 952652). 1797 Authors' Addresses 1798 Marco Tiloca 1799 RISE AB 1800 Isafjordsgatan 22 1801 SE-16440 Kista 1802 Sweden 1803 Email: marco.tiloca@ri.se 1805 Ludwig Seitz 1806 Combitech 1807 Djaeknegatan 31 1808 SE-21135 Malmoe 1809 Sweden 1810 Email: ludwig.seitz@combitech.com 1812 Francesca Palombini 1813 Ericsson AB 1814 Torshamnsgatan 23 1815 SE-16440 Kista 1816 Sweden 1817 Email: francesca.palombini@ericsson.com 1819 Sebastian Echeverria 1820 CMU SEI 1821 4500 Fifth Avenue 1822 Pittsburgh, PA, 15213-2612 1823 United States of America 1824 Email: secheverria@sei.cmu.edu 1826 Grace Lewis 1827 CMU SEI 1828 4500 Fifth Avenue 1829 Pittsburgh, PA, 15213-2612 1830 United States of America 1831 Email: glewis@sei.cmu.edu