idnits 2.17.1 draft-tiloca-ace-revoked-token-notification-02.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 (July 13, 2020) is 1377 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-35 ** Obsolete normative reference: RFC 7049 (Obsoleted by RFC 8949) 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: January 14, 2021 Combitech 6 F. Palombini 7 Ericsson AB 8 S. Echeverria 9 G. Lewis 10 CMU SEI 11 July 13, 2020 13 Notification of Revoked Access Tokens in the Authentication and 14 Authorization for Constrained Environments (ACE) Framework 15 draft-tiloca-ace-revoked-token-notification-02 17 Abstract 19 This document specifies a method of the Authentication and 20 Authorization for Constrained Environments (ACE) framework, which 21 allows an Authorization Server to notify Clients and Resource Servers 22 (i.e., registered devices) about revoked Access Tokens. The method 23 relies on resource observation for the Constrained Application 24 Protocol (CoAP), with Clients and Resource Servers observing a Token 25 Revocation List on the Authorization Server. Resulting unsolicited 26 notifications of revoked Access Tokens complement alternative 27 approaches such as token introspection, while not requiring 28 additional endpoints on Clients and Resource Servers. 30 Status of This Memo 32 This Internet-Draft is submitted in full conformance with the 33 provisions of BCP 78 and BCP 79. 35 Internet-Drafts are working documents of the Internet Engineering 36 Task Force (IETF). Note that other groups may also distribute 37 working documents as Internet-Drafts. The list of current Internet- 38 Drafts is at https://datatracker.ietf.org/drafts/current/. 40 Internet-Drafts are draft documents valid for a maximum of six months 41 and may be updated, replaced, or obsoleted by other documents at any 42 time. It is inappropriate to use Internet-Drafts as reference 43 material or to cite them other than as "work in progress." 45 This Internet-Draft will expire on January 14, 2021. 47 Copyright Notice 49 Copyright (c) 2020 IETF Trust and the persons identified as the 50 document authors. All rights reserved. 52 This document is subject to BCP 78 and the IETF Trust's Legal 53 Provisions Relating to IETF Documents 54 (https://trustee.ietf.org/license-info) in effect on the date of 55 publication of this document. Please review these documents 56 carefully, as they describe your rights and restrictions with respect 57 to this document. Code Components extracted from this document must 58 include Simplified BSD License text as described in Section 4.e of 59 the Trust Legal Provisions and are provided without warranty as 60 described in the Simplified BSD License. 62 Table of Contents 64 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 65 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3 66 2. Protocol Overview . . . . . . . . . . . . . . . . . . . . . . 5 67 3. Token Hash . . . . . . . . . . . . . . . . . . . . . . . . . 6 68 4. The TRL Resource . . . . . . . . . . . . . . . . . . . . . . 8 69 4.1. Update of the TRL Resource . . . . . . . . . . . . . . . 8 70 5. The TRL Endpoint . . . . . . . . . . . . . . . . . . . . . . 9 71 5.1. Full Query of the TRL . . . . . . . . . . . . . . . . . . 10 72 5.2. Diff Query of the TRL . . . . . . . . . . . . . . . . . . 10 73 6. Upon Registration . . . . . . . . . . . . . . . . . . . . . . 12 74 7. Notification of Revoked Tokens . . . . . . . . . . . . . . . 13 75 8. Example . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 76 9. Security Considerations . . . . . . . . . . . . . . . . . . . 15 77 10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 16 78 11. References . . . . . . . . . . . . . . . . . . . . . . . . . 16 79 11.1. Normative References . . . . . . . . . . . . . . . . . . 16 80 11.2. Informative References . . . . . . . . . . . . . . . . . 17 81 Appendix A. Usage of the Series Transfer Pattern . . . . . . . . 18 82 Appendix B. Usage of the "Cursor" Pattern . . . . . . . . . . . 19 83 B.1. Full Query Request . . . . . . . . . . . . . . . . . . . 19 84 B.2. Full Query Response . . . . . . . . . . . . . . . . . . . 19 85 B.3. Diff Query Request . . . . . . . . . . . . . . . . . . . 20 86 B.4. Diff Query Response . . . . . . . . . . . . . . . . . . . 20 87 B.4.1. Empty Collection . . . . . . . . . . . . . . . . . . 20 88 B.4.2. Cursor Not Specified in the Diff Query Request . . . 20 89 B.4.3. Cursor Specified in the Diff Query Request . . . . . 21 90 Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . 23 91 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 23 93 1. Introduction 95 Authentication and Authorization for Constrained Environments (ACE) 96 [I-D.ietf-ace-oauth-authz] is a framework that enforces access 97 control on IoT devices acting as Resource Servers. In order to use 98 ACE, both Clients and Resource Servers have to register with an 99 Authorization Server and become a registered device. Once 100 registered, a Client can send a request to the Authorization Server 101 for an Access Token for a Resource Server. For a Client to access 102 the Resource Server, the Client must present the issued Access Token 103 at the Resource Server, which then validates and stores it. 105 Even though Access Tokens have expiration times, there are 106 circumstances by which an Access Token may need to be revoked before 107 its expiration time, such as: (1) a registered device has been 108 compromised, or is suspected of being compromised; (2) a registered 109 device is decommissioned; (3) there has been a change in access 110 policies for a registered device; and (4) there has been a change in 111 the ACE profile for a registered device. 113 As discussed in Section 6.1 of [I-D.ietf-ace-oauth-authz], only 114 client-initiated revocation is currently specified [RFC7009] for 115 OAuth 2.0, based on the assumption that Access Tokens in OAuth are 116 issued with a relatively short lifetime. However, this may not be 117 the case for constrained, intermittently connected devices, that need 118 Access Tokens with relatively long lifetimes. 120 This document specifies a method for allowing registered devices to 121 access and observe a Token Revocation List (TRL) resource on the 122 Authorization Server, in order to get an updated list of revoked, but 123 yet not expired, pertaining Access Tokens. In particular, registered 124 devices rely on resource observation for the Constrained Application 125 Protocol (CoAP) [RFC7641]. The benefits of this method are that it 126 complements token introspection and does not require any additional 127 endpoints on the registered devices. 129 1.1. Terminology 131 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 132 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 133 "OPTIONAL" in this document are to be interpreted as described in BCP 134 14 [RFC2119] [RFC8174] when, and only when, they appear in all 135 capitals, as shown here. 137 Readers are expected to be familiar with the terms and concepts 138 described in the ACE framework for Authentication and Authorization 139 [I-D.ietf-ace-oauth-authz], as well as with terms and concepts 140 related to CBOR Web Tokens (CWTs) [RFC8392], and JSON Web Tokens 141 (JWTs) [RFC7519]. The terminology for entities in the considered 142 architecture is defined in OAuth 2.0 [RFC6749]. In particular, this 143 includes Client, Resource Server, and Authorization Server. 145 Readers are also expected to be familiar with the terms and concepts 146 related to CBOR [RFC7049], JSON [RFC8259], the CoAP protocol 147 [RFC7252], CoAP Observe [RFC7641], and the use of hash functions to 148 name objects as defined in [RFC6920]. 150 Note that, unless otherwise indicated, the term "endpoint" is used 151 here following its OAuth definition, aimed at denoting resources such 152 as /token and /introspect at the Authorization Server, and /authz- 153 info at the Resource Server. This document does not use the CoAP 154 definition of "endpoint", which is "An entity participating in the 155 CoAP protocol." 157 This specification also refers to the following terminology. 159 o Token hash: identifier of an Access Token, in binary format 160 encoding. The token hash has no relation to other possibly used 161 token identifiers, such as the "cti" (CWT ID) claim of CBOR Web 162 Tokens (CWTs) [RFC8392]. 164 o Token Revocation List (TRL): a collection of token hashes, in 165 which the corresponding Access Tokens have been revoked but are 166 not expired yet. 168 o TRL resource: a resource on the Authorization Server, with a TRL 169 as its representation. 171 o TRL endpoint: an endpoint at the Authorization Server associated 172 to the TRL resource. The default name of the TRL endpoint in a 173 url-path is '/revoke/trl'. Implementations are not required to 174 use this name, and can define their own instead. 176 o Registered device: a device registered at the Authorization 177 Server, as a Client, a Resource Server, or both. A registered 178 device acts as caller of the TRL endpoint. 180 o Administrator: entity authorized to get full access to the TRL at 181 the Authorization Server, and acting as caller of the TRL 182 endpoint. An administrator is not necessarily a registered device 183 as defined above, i.e. a Client requesting Access Tokens or a 184 Resource Server consuming Access Tokens. How the administrator 185 authorization is established and verified is out of the scope of 186 this specification. 188 o Pertaining Access Token: 190 * With reference to an administrator, an Access Token issued by 191 the Authorization Server. 193 * With reference to a registered device, an Access Token intended 194 to be owned by that device. An Access Token pertains to a 195 Client if the Authorization Server has issued the Access Token 196 and provided it to that Client. An Access Token pertains to a 197 Resource Server if the Authorization Server has issued the 198 Access Token to be consumed by that Resource Server. 200 2. Protocol Overview 202 This protocol defines how a CoAP-based Authorization Server informs 203 Clients and Resource Servers, i.e. registered devices, about revoked 204 Access Tokens. How the relationship between the registered device 205 and the Authorization Server is established is out of the scope of 206 this specification. 208 At a high level, the steps of this protocol are as follows. 210 o Upon startup, the Authorization Server creates a TRL resource. At 211 any point in time, the TRL resource represents the list of all 212 revoked Access Tokens issued by the Authorization Server that are 213 yet not expired. 215 o When a device registers at the Authorization Server, it receives 216 the url-path to the TRL resource. After the registration 217 procedure is finished, the registered device sends an Observation 218 Request to that TRL resource as described in [RFC7641], i.e. a GET 219 request with an Observe option set to 0 (register). Upon 220 receiving the request, the Authorization Server adds the 221 registered device to the list of observers of the TRL resource. 222 At any time, the registered device can send a GET request to the 223 TRL endpoint, in order to get the current list of pertaining 224 revoked Access Tokens. 226 o When an Access Token is revoked, the Authorization Server adds the 227 corresponding token hash to the TRL. Also, when a revoked Access 228 Token eventually expires, the Authorization Server removes the 229 corresponding token hash from the TRL. In either case, after 230 updating the TRL, the Authorization Server sends Observe 231 Notifications as described in [RFC7641]. That is, one Observe 232 Notification is sent to each registered device the Access Token 233 pertains to, and specifies the current updated list of token 234 hashes in the portion of the TRL pertaining to that device. 236 o An administrator can observe and access the TRL like a registered 237 device, while getting the full updated representation of the TRL. 239 Figure 1 provides a high-level overview of the service provided by 240 this protocol. Each dotted line associated to a pair of registered 241 devices indicates the Access Token that they both own. In 242 particular, Figure 1 shows the Observe Notifications sent by the 243 Authorization Server to four registered devices and one 244 administrator, upon revocation of the issued Access Tokens t1, t2 and 245 t3, with token hash th1, th2 and th3, respectively. 247 +---------------+ 248 | | 249 | Authorization | 250 | Server | 251 | | 252 +-------o-------+ 253 revoke/trl | TRL: {th1,th2,th3} 254 | 255 | 256 +-----------------+------------+------------+------------+ 257 | | | | | 258 | | | | | 259 | th1,th2,th3 | th1,th2 | th1 | th3 | th2,th3 260 v v v v v 261 +---------------+ +----------+ +----------+ +----------+ +----------+ 262 | | | | | | | | | | 263 | Administrator | | Client 1 | | Resource | | Client 2 | | Resource | 264 | | | | | Server 1 | | | | Server 2 | 265 +---------------+ +----------+ +----------+ +----------+ +----------+ 266 : : : : : : 267 : : t1 : : t3 : : 268 : :........: :............: : 269 : : 270 : t2 : 271 :...........................................: 273 Figure 1: Protocol Overview 275 A more detailed example describing the protocol flow and message 276 exchange between the Authorization Server and a registered device is 277 provided in Section 8. 279 3. Token Hash 281 The token hash of an Access Token is generated as follows. 283 1. The Authorization Server defines ENCODED_TOKEN, as the value of 284 the 'access_token' parameter in the Authorization Server response 285 (see Section 5.6.2 of [I-D.ietf-ace-oauth-authz]), where the 286 Access Token was included and returned to the requesting Client. 288 Note that the value of the 'access_token' parameter assigned to 289 ENCODED_TOKEN is either: 291 * A byte string, if the Access Token was transported using CBOR. 292 With reference to the example in Figure 2, ENCODED_TOKEN takes 293 the raw bytes {d0 83 43 a1 ...}, as value of the byte string 294 'access_token'. 296 * A text string, if the Access Token was transported using JSON. 297 With reference to the example in Figure 3, ENCODED_TOKEN takes 298 "2YotnFZFEjr1zCsicMWpAA...", as value of the text string 299 'access_token'. 301 2. The Authorization Server defines HASH_INPUT as follows. 303 * If CBOR was used to transport the Access Token (as a CWT or 304 JWT), HASH_INPUT takes the same value of ENCODED_TOKEN. 306 * If JSON was used to transport the Access Token (as a CWT or 307 JWT), HASH_INPUT takes the binary representation of 308 ENCODED_TOKEN. 310 In either case, HASH_INPUT results in the binary 311 representation of the value of the 'access_token' parameter 312 from the Authorization Server response. 314 3. The Authorization Server generates a hash value of HASH_INPUT as 315 per Section 6 of [RFC6920]. The resulting output in binary 316 format is used as the token hash. Note that the used binary 317 format embeds the identifier of the used hash function, in the 318 first byte of the computed token hash. 320 The specifically used hash function MUST be collision-resistant 321 on byte-strings, and MUST be selected from the "Named Information 322 Hash Algorithm" Registry [Named.Information.Hash.Algorithm]. 324 The Authorization Server specifies the used hash function to 325 registered devices during their registration procedure (see 326 Section 6). 328 2.01 Created 329 Content-Format: application/ace+cbor 330 Max-Age: 85800 331 Payload: 332 { 333 access_token : h'd08343a1...' 334 (remainder of the Access Token omitted for brevity) 335 token_type : pop, 336 expires_in : 86400, 337 profile : coap_dtls, 338 (remainder of the response omitted for brevity) 339 } 341 Figure 2: Example of Authorization Server response using CBOR 343 HTTP/1.1 200 OK 344 Content-Type: application/json 345 Cache-Control: no-store 346 Pragma: no-cache 347 Payload: 348 { 349 "access_token" : "2YotnFZFEjr1zCsicMWpAA..." 350 (remainder of the Access Token omitted for brevity) 351 "token_type" : "pop", 352 "expires_in" : 86400, 353 "profile" : "coap_dtls", 354 (remainder of the response omitted for brevity) 355 } 357 Figure 3: Example of Authorization Server response using JSON 359 4. The TRL Resource 361 Upon startup, the Authorization Server creates a single TRL resource. 363 The initial content of the TRL resource representation MUST be an 364 empty CBOR array, i.e. the TRL is initialized as empty. 366 The order of the token hashes in the CBOR array is irrelevant, and 367 the CBOR array MUST be treated as a set in which the order has no 368 significant meaning. 370 4.1. Update of the TRL Resource 372 The Authorization Server updates the TRL in the following two cases. 374 o When a non-expired Access Token is revoked, the token hash of the 375 Access Token is added to the TRL resource representation. That 376 is, the token hash is added to the CBOR array used as TRL resource 377 representation. 379 o When a revoked Access Token expires, the token hash of the Access 380 Token is removed from the TRL resource representation. That is, 381 the token hash is removed from the CBOR array used as TRL resource 382 representation. 384 5. The TRL Endpoint 386 Consistent with Section 6.5 of [I-D.ietf-ace-oauth-authz], all 387 communications between a caller of the TRL endpoint and the 388 Authorization Server MUST be encrypted, integrity and replay 389 protected. Furthermore, responses from the Authorization Server to 390 the caller MUST be bound to the caller's request. 392 The Authorization Server MUST implement measures to prevent access to 393 the TRL endpoint by entities other than registered devices and 394 authorized administrators. 396 The TRL endpoint supports only the GET method, and provides two types 397 of query of the TRL. 399 o Full query: the Authorization Server returns the token hashes of 400 the revoked Access Tokens currently in the TRL and pertaining to 401 the requester. The processing of a full query and the related 402 response format are defined in Section 5.1. 404 o Diff query: the Authorization Server returns a set of diff 405 entries. Each entry is related to one of the most recent updates, 406 in the portion of the TRL pertaining to the requester. In 407 particular, the entry associated to one of such updates contains a 408 list of token hashes, such that i) the corresponding revoked 409 Access Tokens pertain to the requester; and ii) they were added to 410 or removed from the TRL at that update. The processing of a diff 411 query and the related response format are defined in Section 5.2. 413 The TRL endpoint allows the following query parameter in a GET 414 request. 416 o 'diff': if included, it indicates to perform a diff query of the 417 TRL. Its value MUST be either: i) 0, indicating that a 418 (notification) response should include as many diff entries as the 419 Authorization Server can provide; or ii) a positive integer 420 greater than 0, indicating the maximum number of diff entries that 421 a (notification) response should include. 423 5.1. Full Query of the TRL 425 In order to produce a (notification) response to a GET request asking 426 for a full query of the TRL, the Authorization Server performs the 427 following actions. 429 1. The Authorization Server builds from the current TRL resource 430 representation a set HASHES of token hashes, such that: 432 * If the requester is a registered device, HASHES includes the 433 token hashes of the Access Tokens pertaining to that 434 registered device. The Authorization Server can use the 435 authenticated identity of the registered device to perform the 436 necessary filtering on the TRL resource representation. 438 * If the requester is an administrator, HASHES includes all the 439 token hashes in the current TRL resource representation. 441 2. The Authorization Server sends a 2.05 (Content) Response to the 442 requester, with a CBOR Array as payload. Each element of the 443 array specifies one of the token hashes from the set HASHES. 445 The order of the token hashes in the CBOR array is irrelevant, 446 i.e. the CBOR array MUST be treated as a set in which the order 447 has no significant meaning. 449 5.2. Diff Query of the TRL 451 In order to produce a (notification) response to a GET request asking 452 for a diff query of the TRL, the Authorization Server performs the 453 following actions. 455 1. The Authorization Server defines the positive integer NUM. If 456 the value N specified in the query parameter 'diff' of the GET 457 request is equal to 0 or greater than a pre-defined positive 458 integer N_MAX, then NUM takes the value of N_MAX. Otherwise, NUM 459 takes N. 461 2. The Authorization Server prepares U = min(NUM, SIZE) diff 462 entries, where SIZE <= N_MAX is the number of TRL updates 463 pertaining to the requester and currently stored at the 464 Authorization Server. That is, the diff entries are related to 465 the U most recent TRL updates pertaining to the requester. In 466 particular, the first entry refers to the most recent of such 467 updates, the second entry refers to the second from last of such 468 updates, and so on. 470 Each diff entry is a CBOR Array 'diff-entry', which includes the 471 following two elements. 473 * The first element is a CBOR Array 'removed'. Each element of 474 the array is the token hash of an Access Token, that pertained 475 to the requester and that was removed from the TRL during the 476 update associated to the diff entry. 478 * The second element is a CBOR Array 'added'. Each element of 479 the array is the token hash of an Access Token, that pertains 480 to the requester and that was added to the TRL during the 481 update associated to the diff entry. 483 The order of the token hashes in the CBOR arrays 'removed' and 484 'added' is irrelevant. That is, the CBOR arrays 'removed' and 485 'added' MUST be treated as a set in which the order of elements 486 has no significant meaning. 488 3. The Authorization Server prepares a 2.05 (Content) Response for 489 the requester, with a CBOR Array 'diff' of U elements as payload. 490 Each element of the array specifies one of the CBOR Arrays 'diff- 491 entry' prepared at point 2 as diff entries. 493 Within the CBOR Array 'diff', the CBOR Arrays 'diff-entry' MUST 494 be sorted to reflect the corresponding updates to the TRL in 495 reverse chronological order. That is, the first 'diff-entry' 496 element of 'diff' relates to the most recent update to the 497 portion of the TRL pertaining to the requester. 499 The CDDL definition [RFC8610] of the CBOR Array 'diff' formatted as 500 in the response from the Authorization Server is provided below. 502 token-hash = bytes 503 trl-patch = [* token-hash] 504 diff-entry = [removed: trl-patch, added: trl-patch] 505 diff = [* diff-entry] 507 Figure 4: CDDL definition of the response payload following a Diff 508 Query request to the TRL endpoint 510 If the Authorization Server supports diff queries: 512 o The Authorization Server MUST keep track of N_MAX most recent 513 updates to the portion of the TRL that pertains to each caller of 514 the TRL endpoint. The particular method to achieve this is 515 implementation-specific. 517 o When SIZE is equal to N_MAX, and a new TRL update occurs as 518 pertaining to a registered device, the Authorization Server MUST 519 first delete the oldest stored update for that device, before 520 storing this latest update as the most recent one for that device. 522 o The Authorization Server SHOULD provide registered devices and 523 administrators with the value of N_MAX, upon their registration 524 (see Section 6). 526 If the Authorization Server does not support diff queries, it 527 proceeds as when processing a full query (see Section 5.1). 529 Appendix A discusses how the diff query of the TRL is a usage example 530 of the Series Transfer Pattern defined in [I-D.bormann-t2trg-stp]. 532 Appendix B discusses how the diff query of the TRL can be further 533 improved by using the "Cursor" pattern defined in Section 3.3 of 534 [I-D.bormann-t2trg-stp]. 536 6. Upon Registration 538 During the registration process at the Authorization Server, an 539 administrator or a registered device receives the following 540 information as part of the registration response. 542 o The url-path to the TRL endpoint at the Authorization Server. 544 o The hash function used to compute token hashes. This is specified 545 as an integer or a text string, taking value from the "ID" or 546 "Hash Name String" column of the "Named Information Hash 547 Algorithm" Registry [Named.Information.Hash.Algorithm], 548 respectively. 550 o Optionally, a positive integer N_MAX, if the Authorization Server 551 supports diff queries of the TRL resource (see Section 5.2). 553 After the registration procedure is finished, the administrator or 554 registered device performs a GET request to the TRL resource, 555 including the CoAP Observe option set to 0 (register), in order to 556 start an observation of the TRL resource at the Authorization Server, 557 as per Section 3.1 of [RFC7641]. The GET request can express the 558 wish for a full query (see Section 5.1) or a diff query (see 559 Section 5.2). 561 The Authorization Server MUST reply using the CoAP response code 2.05 562 (Content) and the CoAP Observe option with value 1. The response 563 payload is formatted as defined in Section 5.1 or in Section 5.2, in 564 case the GET request was for a full query or a diff query of the TRL, 565 respectively. 567 7. Notification of Revoked Tokens 569 In the case the TRL is updated (see Section 4.1), the Authorization 570 Server sends Observe Notifications to every observer of the TRL 571 resource. Observe Notifications are sent as per Section 4.2 of 572 [RFC7641]. 574 The content of each Observe Notification is formatted as defined in 575 Section 5.1 or in Section 5.2, in case the original Observation 576 Request was for a full query or a diff query of the TRL, 577 respectively. 579 Furthermore, an administrator or a registered device can send 580 additional GET requests to the TRL endpoint at any time, in order to 581 retrieve the token hashes of the pertaining revoked Access Tokens. 582 When doing so, the caller of the TRL endpoint can perform a full 583 query (see Section 5.1) or a diff query (see Section 5.2). 585 8. Example 587 Figure 5 shows an example interaction between a Resource Server RS 588 and an Authorization Server AS, considering a CoAP observation and a 589 full query of the TRL. 591 The details of the registration process are omitted, but it is 592 assumed that the Resource Server sends an unspecified payload to the 593 Authorization Server, and then the Authorization Server replies with 594 a 2.01 (Created) response. 596 In particular, the registration response contains a CBOR map, which 597 includes a "trl" parameter specifying the path of the TRL resource, 598 and a "trl-hash" parameter specifying the hash function used to 599 computed token hashes. 601 The function 'h(x)' refers to the hash function used to compute the 602 token hashes, as defined in Section 3 of this specifications and 603 according to [RFC6920]. Assuming the usage of CWTs transported in 604 CBOR, 'bstr.t1' and 'bstr.t2' denote the byte-string representations 605 of the token hashes for the Access Tokens t1 and t2, respectively. 607 RS AS 608 | | 609 | Registration: POST | 610 +------------------------------------->| 611 | | 612 |<-------------------------------------+ 613 | 2.01 CREATED | 614 | Payload: { | 615 | ... | 616 | "trl" = "revoke/trl" | 617 | "trl-hash" = "sha-256" | 618 | } | 619 | | 620 | GET Observe: 0 | 621 | coap://example.as.com/revoke/trl/ | 622 +------------------------------------->| 623 | | 624 |<-------------------------------------+ 625 | 2.05 CONTENT Observe: 1 | 626 | Payload: [] | 627 | . | 628 | . | 629 | . | 630 | | 631 | (Access Tokens t1 and t2 issued | 632 | and successfully submitted to RS) | 633 | . | 634 | . | 635 | . | 636 | | 637 | (Access Token t1 is revoked) | 638 | | 639 |<-------------------------------------+ 640 | 2.05 CONTENT Observe: 2 | 641 | Payload: [h(bstr.t1)] | 642 | . | 643 | . | 644 | . | 645 | | 646 | (Access Token t2 is revoked) | 647 | | 648 |<-------------------------------------+ 649 | 2.05 CONTENT Observe: 3 | 650 | Payload: [h(bstr.t1), | 651 | h(bstr.t2)] | 652 | . | 653 | . | 654 | . | 655 | | 656 | (Access Token t1 expires) | 657 | | 658 |<-------------------------------------+ 659 | 2.05 CONTENT Observe: 4 | 660 | Payload:[h(bstr.t2)] | 661 | | 663 Figure 5: Communication example 665 9. Security Considerations 667 Security considerations are inherited from the ACE framework for 668 Authentication and Authorization [I-D.ietf-ace-oauth-authz], from 669 [RFC8392] as to the usage of CWTs, from [RFC7519] as to the usage of 670 JWTs, from [RFC7641] as to the usage of CoAP Observe, and from 671 [RFC6920] with regards to resource naming through hashes. The 672 following considerations also apply. 674 The Authorization Server MUST ensure that each registered device can 675 access and retrieve only its pertaining portion of the TRL. To this 676 end, the Authorization Server can perform the required filtering 677 based on the authenticated identity of the registered device, i.e., a 678 (non-public) identifier that the Authorization Server can securely 679 relate to the registered device and the secure session they use to 680 communicate. 682 Disclosing any information about revoked Access Tokens to entities 683 other than the intended registered devices may result in privacy 684 concerns. Therefore, the Authorization Server MUST ensure that, 685 other than registered devices accessing their own pertaining portion 686 of the TRL, only authorized and authenticated administrators can 687 retrieve the full TRL. To this end, the Authorization Server may 688 rely on an access control list or similar. 690 If a registered device has many non-expired Access Tokens associated 691 to it that are revoked, the pertaining portion of the TRL could grow 692 to a size bigger than what the registered device is prepared to 693 handle upon reception, especially if relying on a full query of the 694 TRL resource (see Section 5.1). This could be exploited by attackers 695 to negatively affect the behaviour of a registered device. Short 696 expiration times could help reduce the size of a TRL, but an 697 Authorization Server SHOULD take measures to limit this size. 699 Most of the communication about revoked Access Tokens presented in 700 this specification relies on CoAP Observe Notifications sent from the 701 Authorization Server to a registered device. The suppression of 702 those notifications by an external attacker that has access to the 703 network would prevent registered devices from ever knowing that their 704 pertaining Access Tokens have been revoked. To avoid this, a 705 registered device SHOULD NOT rely solely on the CoAP Observe 706 notifications. In particular, a registered device SHOULD also 707 regularly poll the Authorization Server for the most current 708 information about revoked Access Tokens, by sending GET requests to 709 the TRL endpoint according to an application policy. 711 10. IANA Considerations 713 This document has no actions for IANA. 715 11. References 717 11.1. Normative References 719 [I-D.ietf-ace-oauth-authz] 720 Seitz, L., Selander, G., Wahlstroem, E., Erdtman, S., and 721 H. Tschofenig, "Authentication and Authorization for 722 Constrained Environments (ACE) using the OAuth 2.0 723 Framework (ACE-OAuth)", draft-ietf-ace-oauth-authz-35 724 (work in progress), June 2020. 726 [Named.Information.Hash.Algorithm] 727 IANA, "Named Information Hash Algorithm", 728 . 731 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 732 Requirement Levels", BCP 14, RFC 2119, 733 DOI 10.17487/RFC2119, March 1997, 734 . 736 [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", 737 RFC 6749, DOI 10.17487/RFC6749, October 2012, 738 . 740 [RFC6920] Farrell, S., Kutscher, D., Dannewitz, C., Ohlman, B., 741 Keranen, A., and P. Hallam-Baker, "Naming Things with 742 Hashes", RFC 6920, DOI 10.17487/RFC6920, April 2013, 743 . 745 [RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object 746 Representation (CBOR)", RFC 7049, DOI 10.17487/RFC7049, 747 October 2013, . 749 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 750 Application Protocol (CoAP)", RFC 7252, 751 DOI 10.17487/RFC7252, June 2014, 752 . 754 [RFC7519] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token 755 (JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015, 756 . 758 [RFC7641] Hartke, K., "Observing Resources in the Constrained 759 Application Protocol (CoAP)", RFC 7641, 760 DOI 10.17487/RFC7641, September 2015, 761 . 763 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 764 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 765 May 2017, . 767 [RFC8259] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 768 Interchange Format", STD 90, RFC 8259, 769 DOI 10.17487/RFC8259, December 2017, 770 . 772 [RFC8392] Jones, M., Wahlstroem, E., Erdtman, S., and H. Tschofenig, 773 "CBOR Web Token (CWT)", RFC 8392, DOI 10.17487/RFC8392, 774 May 2018, . 776 11.2. Informative References 778 [I-D.bormann-t2trg-stp] 779 Bormann, C. and K. Hartke, "The Series Transfer Pattern 780 (STP)", draft-bormann-t2trg-stp-03 (work in progress), 781 April 2020. 783 [RFC7009] Lodderstedt, T., Ed., Dronia, S., and M. Scurtescu, "OAuth 784 2.0 Token Revocation", RFC 7009, DOI 10.17487/RFC7009, 785 August 2013, . 787 [RFC8610] Birkholz, H., Vigano, C., and C. Bormann, "Concise Data 788 Definition Language (CDDL): A Notational Convention to 789 Express Concise Binary Object Representation (CBOR) and 790 JSON Data Structures", RFC 8610, DOI 10.17487/RFC8610, 791 June 2019, . 793 Appendix A. Usage of the Series Transfer Pattern 795 This section discusses how the diff query of the TRL defined in 796 Section 5.2 is a usage example of the Series Transfer Pattern defined 797 in [I-D.bormann-t2trg-stp]. 799 A diff query enables the transfer of a series of TRL updates, with 800 the Authorization Server specifying U <= N_MAX diff entries as the U 801 most recent updates to the portion of the TRL pertaining to a 802 registered device. 804 For each registered device, the Authorization Server maintains an 805 update collection of maximum N_MAX items. Each time the TRL changes, 806 the Authorization Server performs the following operations for each 807 registered device. 809 1. The Authorization Server considers the portion of the TRL 810 pertaining to that registered device. If the TRL portion is not 811 affected by this TRL update, the Authorization Server stops the 812 processing for that registered device. 814 2. Otherwise, the Authorization Server creates two sets 'trl_patch' 815 of token hashes, i.e. one "removed" set and one "added" set, as 816 related to this TRL update. 818 3. The Authorization Server fills the two sets with the token hashes 819 of the removed and added Access Tokens, respectively, from/to the 820 TRL portion from step 1. 822 4. The Authorization Server creates a new series item including the 823 two sets from step 3, and adds the series item to the update 824 collection associated to the registered device. 826 When responding to a diff query request from a registered device (see 827 Section 5.2), 'diff' is a subset of the collection associated to the 828 requester, where each 'diff_entry' record is a series item from that 829 collection. Note that 'diff' specifies the whole current collection 830 when the value of U is equal to SIZE, i.e. the current number of 831 series items in the collection. 833 The value N of the 'diff' query parameter in the diff query request 834 allows the requester and the Authorization Server to trade the amount 835 of provided information with the latency of the information transfer. 837 Since the collection associated to each registered device includes up 838 to N_MAX series item, the Authorization Server deletes the oldest 839 series item when a new one is generated and added to the end of the 840 collection, due to a new TRL update pertaining to that registered 841 device. This addresses the question "When can the server decide to 842 no longer retain older items?" in Section 3.2 of 843 [I-D.bormann-t2trg-stp]. 845 Appendix B. Usage of the "Cursor" Pattern 847 Building on Appendix A, this section describes how the diff query of 848 the TRL defined in Section 5.2 can be further improved by using the 849 "Cursor" pattern of the Series Transfer Pattern (see Section 3.3 of 850 [I-D.bormann-t2trg-stp]). 852 This has two benefits. First, the Authorization Server can avoid 853 excessively big latencies when several diff entries have to be 854 transferred, by delivering one adjacent subset at the time, in 855 different diff query responses. Second, a requester can retrieve 856 diff entries associated to TRL updates that, even if not the most 857 recent ones, occurred after a TRL update indicated as checkpoint. 859 To this end, each series item in an update collection is also 860 associated with an unsigned integer 'index', with value the absolute 861 counter of series items added to that collection minus 1. That is, 862 the first series item added to a collection has 'index' with value 0. 863 Then, the values of 'index' are used as cursor information. 865 Furthermore, the Authorization Server defines an unsigned integer 866 MAX_DIFF_BATCH <= N_MAX, specifying the maximum number of diff 867 entries to be included in a single diff query response. If 868 supporting diff queries, the Authorization Server should provide 869 registered devices and administrators with the value of 870 MAX_DIFF_BATCH, upon their registration. 872 Finally, the full query and diff query exchanges defined in 873 Section 5.1 and Section 5.2 are extended as follows. 875 B.1. Full Query Request 877 No changes apply to what defined in Section 5.1. 879 B.2. Full Query Response 881 The response to a full query request (see Section 5.1) includes the 882 CBOR array of token hashes as well as a parameter 'cursor', encoded 883 either as a CBOR unsigned integer or the CBOR simple value Null. 885 The 'cursor' parameter specifies the value Null if there are 886 currently no updates pertinent to the requester, i.e. the update 887 collection for that requester is empty. This is the case from when 888 the requester registers at the Authorization Server until a first 889 update pertaining that requester occurs to the TRL. 891 Otherwise, the 'cursor' parameter takes the value of 'index' for the 892 last series item in the collection, as corresponding to the most 893 recent update pertaining to the requester occurred to the TRL. 895 B.3. Diff Query Request 897 In addition to the query parameter 'diff' (see Section 5.2), the 898 requester can specify a query parameter 'cursor', with value an 899 unsigned integer. 901 B.4. Diff Query Response 903 When receiving the diff query request, the Authorization Server 904 proceeds as follows. 906 B.4.1. Empty Collection 908 If the collection associated to the requester has no elements, the 909 Authorization Server returns a diff query response that contains: 911 o The 'diff' parameter, encoding an empty CBOR array. 913 o A 'cursor' parameter, encoding the CBOR simple value Null. 915 o A 'more' parameter, encoding the CBOR simple value False. 917 B.4.2. Cursor Not Specified in the Diff Query Request 919 If the update collection associated to the requester is not empty and 920 the diff query request does not include the query parameter 'cursor', 921 the Authorization Server returns a diff query response that contains: 923 o The 'diff' CBOR array, including L = min(U, MAX_DIFF_BATCH) diff 924 entries. In particular: 926 * If U <= MAX_DIFF_BATCH, these diff entries are the last series 927 items in the collection associated to the requester, 928 corresponding to the L most recent TRL updates pertaining to 929 the requester. 931 * If U > MAX_DIFF_BATCH, these diff entries are the eldest of the 932 last L series items in the collection associated to the 933 requester, as corresponding to the first L of the U most recent 934 TRL updates pertaining to the requester. 936 o A 'cursor' parameter, encoded as a CBOR unsigned integer. This 937 takes the 'index' value of the series element of the collection 938 included as first diff entry in the 'diff' CBOR array. That is, 939 it takes the 'index' value of the series item in the collection 940 corresponding to the most recent update pertaining to the 941 requester and returned in this diff query response. 943 Note that 'cursor' takes the same 'index' value of the last series 944 item in the collection when U <= MAX_DIFF_BATCH. 946 o A 'more' parameter, encoded as the CBOR simple value False if U <= 947 MAX_DIFF_BATCH, or as the CBOR simple value True otherwise. 949 If 'more' has value True, the requester can send a follow-up diff 950 query request including the query parameter 'cursor', with the 951 same value of the 'cursor' parameter included in this response. 952 This would result in the Authorization Server transfering the 953 following subset of series items as diff entries, i.e. resuming 954 from where interrupted in the previous transfer. 956 B.4.3. Cursor Specified in the Diff Query Request 958 If the update collection associated to the requester is not empty and 959 the diff query request includes the query parameter 'cursor' with 960 value P, the Authorization Server proceeds as follows. 962 o If no series item X with 'index' having value P is found in the 963 collection associated to the requester, then that item has been 964 previously removed from the history of updates for that requester 965 (see Appendix A). In this case, the Authorization Server returns 966 a diff query response that contains: 968 * The 'diff' parameter, encoding an empty CBOR array. 970 * A 'cursor' parameter, encoding the CBOR simple value Null. 972 * A 'more' parameter, encoding the CBOR simple value True. 974 With the combination ('cursor', 'more') = (Null, True), the 975 Authorization Server is signaling that the update collection is in 976 fact not empty, but that some series items have been lost due to 977 their removal, including the item with 'index' value P that the 978 requester wished to use as checkpoint. 980 When receiving this diff query response, the requester should send 981 a new full query request to the Authorization Server, in order to 982 fully retrieve the current pertaining portion of the TRL. 984 o If the series item X with 'index' having value P is found in the 985 collection associated to the requester, the Authorization Server 986 returns a diff query response that contains: 988 * The 'diff' CBOR array, including L = min(SUB_U, MAX_DIFF_BATCH) 989 diff entries, where SUB_U = min(NUM, SUB_SIZE), and SUB_SIZE is 990 the number of series items in the collection following the 991 series item X. 993 That is, these are the L updates pertaining to the requester 994 that immediately follow the series item X indicated as 995 checkpoint. In particular: 997 + If SUB_U <= MAX_DIFF_BATCH, these diff entries are the last 998 series items in the collection associated to the requester, 999 corresponding to the L most recent TRL updates pertaining to 1000 the requester. 1002 + If SUB_U > MAX_DIFF_BATCH, these diff entries are the eldest 1003 of the last L series items in the collection associated to 1004 the requester, corresponding to the first L of the SUB_U 1005 most recent TRL updates pertaining to the requester. 1007 * A 'cursor' parameter, encoded as a CBOR unsigned integer. If L 1008 is equal to 0, i.e. the series item X is the last one in the 1009 collection, 'cursor' takes the same 'index' value of the last 1010 series item in the collection. Otherwise, 'cursor' takes the 1011 'index' value of the series element of the collection included 1012 as first diff entry in the 'diff' CBOR array. That is, it 1013 takes the 'index' value of the series item in the collection 1014 corresponding to the most recent update pertaining to the 1015 requester and returned in this diff query response. 1017 Note that 'cursor' takes the same 'index' value of the last 1018 series item in the collection when SUB_U <= MAX_DIFF_BATCH. 1020 * A 'more' parameter, encoded as the CBOR simple value False if 1021 SUB_U <= MAX_DIFF_BATCH, or as the CBOR simple value True 1022 otherwise. 1024 If 'more' has value True, the requester can send a follow-up 1025 diff query request including the query parameter 'cursor', with 1026 the same value of the 'cursor' parameter specified in this diff 1027 query response. This would result in the Authorization Server 1028 transfering the following subset of series items as diff 1029 entries, i.e. resuming from where interrupted in the previous 1030 transfer. 1032 Acknowledgments 1034 The authors sincerely thank Carsten Bormann, Benjamin Kaduk, Jim 1035 Schaad, Goeran Selander and Travis Spencer for their comments and 1036 feedback. 1038 The work on this document has been partly supported by VINNOVA and 1039 the Celtic-Next project CRITISEC. 1041 Authors' Addresses 1043 Marco Tiloca 1044 RISE AB 1045 Isafjordsgatan 22 1046 Kista SE-16440 Stockholm 1047 Sweden 1049 Email: marco.tiloca@ri.se 1051 Ludwig Seitz 1052 Combitech 1053 Djaeknegatan 31 1054 Malmoe SE-21135 Malmoe 1055 Sweden 1057 Email: ludwig.seitz@combitech.se 1059 Francesca Palombini 1060 Ericsson AB 1061 Torshamnsgatan 23 1062 Kista SE-16440 Stockholm 1063 Sweden 1065 Email: francesca.palombini@ericsson.com 1067 Sebastian Echeverria 1068 CMU SEI 1069 4500 Fifth Avenue 1070 Pittsburgh, PA 15213-2612 1071 United States of America 1073 Email: secheverria@sei.cmu.edu 1074 Grace Lewis 1075 CMU SEI 1076 4500 Fifth Avenue 1077 Pittsburgh, PA 15213-2612 1078 United States of America 1080 Email: glewis@sei.cmu.edu