idnits 2.17.1 draft-ietf-ace-aif-01.txt: -(3): Line appears to be too long, but this could be caused by non-ascii characters in UTF-8 encoding 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: ---------------------------------------------------------------------------- == There are 2 instances of lines with non-ascii characters in the document. 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 (11 February 2021) is 1141 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- == Missing Reference: 'RFCthis' is mentioned on line 394, but not defined == Outdated reference: A later version (-46) exists of draft-ietf-ace-oauth-authz-36 -- Obsolete informational reference (is this intentional?): RFC 7231 (Obsoleted by RFC 9110) Summary: 0 errors (**), 0 flaws (~~), 4 warnings (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group C. Bormann 3 Internet-Draft Universität Bremen TZI 4 Intended status: Informational 11 February 2021 5 Expires: 15 August 2021 7 An Authorization Information Format (AIF) for ACE 8 draft-ietf-ace-aif-01 10 Abstract 12 Constrained Devices as they are used in the "Internet of Things" need 13 security. One important element of this security is that devices in 14 the Internet of Things need to be able to decide which operations 15 requested of them should be considered authorized, need to ascertain 16 that the authorization to request the operation does apply to the 17 actual requester, and need to ascertain that other devices they place 18 requests on are the ones they intended. 20 To transfer detailed authorization information from an authorization 21 manager (such as an ACE-OAuth Authorization Server) to a device, a 22 representation format is needed. This document provides a suggestion 23 for such a format, the Authorization Information Format (AIF). AIF 24 is defined both as a general structure that can be used for many 25 different applications and as a specific refinement that describes 26 REST resources and the permissions on them. 28 Status of This Memo 30 This Internet-Draft is submitted in full conformance with the 31 provisions of BCP 78 and BCP 79. 33 Internet-Drafts are working documents of the Internet Engineering 34 Task Force (IETF). Note that other groups may also distribute 35 working documents as Internet-Drafts. The list of current Internet- 36 Drafts is at https://datatracker.ietf.org/drafts/current/. 38 Internet-Drafts are draft documents valid for a maximum of six months 39 and may be updated, replaced, or obsoleted by other documents at any 40 time. It is inappropriate to use Internet-Drafts as reference 41 material or to cite them other than as "work in progress." 43 This Internet-Draft will expire on 15 August 2021. 45 Copyright Notice 47 Copyright (c) 2021 IETF Trust and the persons identified as the 48 document authors. All rights reserved. 50 This document is subject to BCP 78 and the IETF Trust's Legal 51 Provisions Relating to IETF Documents (https://trustee.ietf.org/ 52 license-info) in effect on the date of publication of this document. 53 Please review these documents carefully, as they describe your rights 54 and restrictions with respect to this document. Code Components 55 extracted from this document must include Simplified BSD License text 56 as described in Section 4.e of the Trust Legal Provisions and are 57 provided without warranty as described in the Simplified BSD License. 59 Table of Contents 61 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 62 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3 63 2. Information Model . . . . . . . . . . . . . . . . . . . . . . 3 64 2.1. REST-specific model . . . . . . . . . . . . . . . . . . . 4 65 2.2. Limitations . . . . . . . . . . . . . . . . . . . . . . . 4 66 2.3. Extended REST-specific model . . . . . . . . . . . . . . 5 67 3. Data Model . . . . . . . . . . . . . . . . . . . . . . . . . 5 68 4. Media Types . . . . . . . . . . . . . . . . . . . . . . . . . 8 69 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 8 70 5.1. Media Types . . . . . . . . . . . . . . . . . . . . . . . 8 71 5.2. Registries . . . . . . . . . . . . . . . . . . . . . . . 9 72 5.3. Content-Format . . . . . . . . . . . . . . . . . . . . . 9 73 6. Security Considerations . . . . . . . . . . . . . . . . . . . 10 74 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 10 75 7.1. Normative References . . . . . . . . . . . . . . . . . . 10 76 7.2. Informative References . . . . . . . . . . . . . . . . . 11 77 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 12 78 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 12 80 1. Introduction 82 Constrained Devices as they are used in the "Internet of Things" need 83 security. One important element of this security is that devices in 84 the Internet of Things need to be able to decide which operations 85 requested of them should be considered authorized, need to ascertain 86 that the authorization to request the operation does apply to the 87 actual requester, and need to ascertain that other devices they place 88 requests on are the ones they intended. 90 To transfer detailed authorization information from an authorization 91 manager (such as an ACE-OAuth Authorization Server 92 [I-D.ietf-ace-oauth-authz]) to a device, a representation format is 93 needed. This document provides a suggestion for such a format, the 94 Authorization Information Format (AIF). AIF is defined both as a 95 general structure that can be used for many different applications 96 and as a specific refinement that describes REST resources and the 97 permissions on them. 99 1.1. Terminology 101 This memo uses terms from [RFC7252] and [RFC4949]. 103 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 104 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 105 "OPTIONAL" in this document are to be interpreted as described in 106 BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all 107 capitals, as shown here. These words may also appear in this 108 document in lower case as plain English words, absent their normative 109 meanings. 111 (Note that this document is itself informational, but it is 112 discussing normative statements that MUST be put into concrete terms 113 in each specification that makes use of this document.) 115 The term "byte", abbreviated by "B", is used in its now customary 116 sense as a synonym for "octet". 118 2. Information Model 120 Authorizations are generally expressed through some data structures 121 that are cryptographically secured (or transmitted in a secure way). 122 This section discusses the information model underlying the payload 123 of that data (as opposed to the cryptographic armor around it). 125 For the purposes of this specification, the underlying access control 126 model will be that of an access matrix, which gives a set of 127 permissions for each possible combination of a subject and an object. 128 We do not concern the AIF format with the subject for which the AIF 129 object is issued, focusing the AIF object on a single row in the 130 access matrix (such a row traditionally is also called a capability 131 list). As a consequence, AIF MUST be used in a way that the subject 132 of the authorizations is unambiguously identified (e.g., as part of 133 the armor around it). 135 The generic model of a such a capability list is a list of pairs of 136 object identifiers and the permissions the subject has on the 137 object(s) identified. 139 AIF-Generic = [* [Toid, Tperm]] 141 Figure 1: Definition of Generic AIF 143 In a specific data model, the object identifier ("Toid") will often 144 be a text string, and the set of permissions ("Tperm") will be 145 represented by a bitset in turn represented as a number (see 146 Section 3). 148 AIF-Specific = AIF-Generic 150 Figure 2: Likely shape of a specific AIF 152 2.1. REST-specific model 154 In the specific instantiation of the REST resources and the 155 permissions on them, for the object identifiers ("Toid"), we use the 156 URI of a resource on a CoAP server. More specifically, the parts of 157 the URI that identify the server ("authority" in [RFC3986]) are 158 considered the realm of the authentication mechanism (which are 159 handled in the cryptographic armor); we therefore focus on the "path- 160 absolute" and "query" parts of the URI (URI "local-part" in this 161 specification, as expressed by the Uri-Path and Uri-Query options in 162 CoAP). As a consequence, AIF MUST be used in a way that it is 163 unambiguous who is the target (enforcement point) of these 164 authorizations. 166 For the permissions ("Tperm"), we simplify the model permissions to 167 giving the subset of the CoAP methods permitted. This model is 168 summarized in Table 1. 170 +============+================+ 171 | local-part | Permission Set | 172 +============+================+ 173 | /s/light | GET | 174 +------------+----------------+ 175 | /a/led | PUT, GET | 176 +------------+----------------+ 177 | /dtls | POST | 178 +------------+----------------+ 180 Table 1: An authorization 181 instance in the AIF 182 Information Model 184 2.2. Limitations 186 This simple information model only allows granting permissions for 187 statically identifiable objects, e.g. URIs for the REST-specific 188 instantiation. One might be tempted to extend the model towards URI 189 templates [RFC6570], however, that requires some considerations of 190 the ease and unambiguity of matching a given URI against a set of 191 templates in an AIF object. 193 This simple information model also doesn't allow further 194 conditionalizing access based on state outside the identification of 195 objects (e.g., "opening a door is allowed if that isn't locked"). 197 Finally, the model does not provide any special access for a set of 198 resources that are specific to a subject, e.g. that the subject 199 created itself by previous operations (PUT, POST) or that were 200 specifically created for the subject by others. 202 2.3. Extended REST-specific model 204 The extended REST-specific model addresses the need to provide 205 defined access to dynamic resources that were created by the subject 206 itself, specifically, a resource that is made known to the subject by 207 providing Location-* options in a CoAP result or using the Location 208 header field in HTTP [RFC7231] (the Location-indicating mechanisms). 209 (The concept is somewhat comparable to "ACL inheritance" in NFSv4 210 [rfc5661], except that it does not use a containment relationship but 211 the fact that the dynamic resource was created from a resource to 212 which the subject had access.) 214 +================+===================================+ 215 | local-part | Permission Set | 216 +================+===================================+ 217 | /a/make-coffee | POST, Dynamic-GET, Dynamic-DELETE | 218 +----------------+-----------------------------------+ 220 Table 2: An authorization instance in the AIF 221 Information Model 223 For a method X, the presence of a Dynamic-X permission means that the 224 subject holds permission to exercise the method X on resources that 225 have been returned by a Location-indicating mechanism to a request 226 that the subject made to the resource listed ("/a/make-coffee" in the 227 example, which might return the location of a resource that allows 228 GET to find out about the status and DELETE to cancel the coffee- 229 making operation). 231 Since the use of the extension defined in this section can be 232 detected by the mentioning of the Dynamic-X permissions, there is no 233 need for another explicit switch between the basic and the extended 234 model; the extended model is always presumed once a Dynamic-X 235 permission is present. 237 3. Data Model 239 Different data model specializations can be defined for the generic 240 information model given above. 242 In this section, we will give the data model for basic REST 243 authorization. As discussed, the object identifier is specialized as 244 a text string giving a relative URI (local-part as absolute path on 245 the server serving as enforcement point). The permission set is 246 specialized to a single number by the following steps: 248 * The entries in the table that specify the same local-part are 249 merged into a single entry that specifies the union of the 250 permission sets. 252 * The (non-dynamic) methods in the permission sets are converted 253 into their CoAP method numbers, minus 1. 255 * Dynamic-X permissions are converted into what the number would 256 have been for X, plus a Dynamic-Offset chosen as 32 (e.g., 35 for 257 Dynamic-DELETE). 259 * The set of numbers is converted into a single number by taking 260 each number to the power of two and computing the inclusive OR of 261 the binary representations of all the power values. 263 This data model could be interchanged in the JSON [RFC8259] 264 representation given in Figure 3. 266 [["/s/light", 1], ["/a/led", 5], ["/dtls", 2]] 268 Figure 3: An authorization instance encoded in JSON (46 bytes) 270 In CDDL [RFC8610], a straightforward specification of the data model 271 (including both the methods from [RFC7252] and the new ones from 272 [RFC8132], identified by the method code minus 1) is: 274 AIF-REST = AIF-Generic 275 path = tstr ; URI relative to enforcement point 276 permissions = uint .bits methods 277 methods = &( 278 GET: 0 279 POST: 1 280 PUT: 2 281 DELETE: 3 282 FETCH: 4 283 PATCH: 5 284 iPATCH: 6 285 Dynamic-GET: 32; 0 .plus Dynamic-Offset 286 Dynamic-POST: 33; 1 .plus Dynamic-Offset 287 Dynamic-PUT: 34; 2 .plus Dynamic-Offset 288 Dynamic-DELETE: 35; 3 .plus Dynamic-Offset 289 Dynamic-FETCH: 36; 4 .plus Dynamic-Offset 290 Dynamic-PATCH: 37; 5 .plus Dynamic-Offset 291 Dynamic-iPATCH: 38; 6 .plus Dynamic-Offset 292 ) 294 Figure 4: AIF in CDDL 296 A representation of this information in CBOR [RFC8949] is given in 297 Figure 5; again, several optimizations/improvements are possible. 299 83 # array(3) 300 82 # array(2) 301 68 # text(8) 302 2f732f6c69676874 # "/s/light" 303 01 # unsigned(1) 304 82 # array(2) 305 66 # text(6) 306 2f612f6c6564 # "/a/led" 307 05 # unsigned(5) 308 82 # array(2) 309 65 # text(5) 310 2f64746c73 # "/dtls" 311 02 # unsigned(2) 313 Figure 5: An authorization instance encoded in CBOR (29 bytes) 315 Note that choosing 32 as Dynamic-Offset means that all future CoAP 316 methods that can be registered can be represented both as themselves 317 and in the Dynamic-X variant, but only the dynamic forms of methods 1 318 to 21 are typically usable in a JSON form [RFC7493]. 320 4. Media Types 322 This specification defines media types for the generic information 323 model, expressed in JSON ("application/aif+json") or in CBOR 324 ("application/aif+cbor"). These media types have parameters for 325 specifying "Toid" and "Tperm"; default values are the values "local- 326 uri" for "Toid" and "REST-method-set" for "Tperm". 328 [Insert lots of boilerplate here] 330 A specification that wants to use Generic AIF with different "Toid" 331 and/or "Tperm" is expected to request these as media type parameters 332 (Section 5.2) and register a corresponding Content-Format 333 (Section 5.3). 335 5. IANA Considerations 337 5.1. Media Types 339 IANA is requested to add the following Media-Type to the "Media 340 Types" registry. 342 +==========+======================+=====================+ 343 | Name | Template | Reference | 344 +==========+======================+=====================+ 345 | aif+cbor | application/aif+cbor | RFC XXXX, Section 4 | 346 +----------+----------------------+---------------------+ 347 | aif+json | application/aif+json | RFC XXXX, Section 4 | 348 +----------+----------------------+---------------------+ 350 Table 3 352 // RFC Ed.: please replace RFC XXXX with this RFC number and remove 353 this note. 355 Type name: application 356 Subtype name: aif+cbor 357 Required parameters: none 358 Optional parameters: none 359 Encoding considerations: binary (CBOR) 360 Security considerations: Section 6 of RFC XXXX 361 Published specification: Section 4 of RFC XXXX 362 Person & email address to contact for further information: ACE WG 363 mailing list (ace@ietf.org), or IETF Applications and Real-Time 364 Area (art@ietf.org) 365 Intended usage: COMMON 366 Restrictions on usage: none 367 Author/Change controller: IETF 368 Type name: application 369 Subtype name: aif+json 370 Required parameters: none 371 Optional parameters: none 372 Encoding considerations: binary (JSON is UTF-8-encoded text) 373 Security considerations: Section 6 of RFC XXXX 374 Published specification: Section 4 of RFC XXXX 375 Person & email address to contact for further information: ACE WG 376 mailing list (ace@ietf.org), or IETF Applications and Real-Time 377 Area (art@ietf.org) 378 Intended usage: COMMON 379 Restrictions on usage: none 380 Author/Change controller: IETF 382 5.2. Registries 384 IANA is requested to create a registry for AIF with two sub- 385 registries for "Toid" and "Tperm", populated with: 387 +=============+=================+=================================+ 388 | Subregistry | name | Description/Specification | 389 +=============+=================+=================================+ 390 | Toid | local-part | local-part of URI as specified | 391 | | | in [RFCthis] | 392 +-------------+-----------------+---------------------------------+ 393 | Tperm | REST-method-set | set of REST methods represented | 394 | | | as specified in [RFCthis] | 395 +-------------+-----------------+---------------------------------+ 397 Table 4 399 The registration policy is Specification required [RFC8126]. The 400 designated expert will engage with the submitter to ascertain the 401 requirements of this document are addressed. 403 5.3. Content-Format 405 IANA is requested to register Content-Format numbers in the "CoAP 406 Content-Formats" subregistry, within the "Constrained RESTful 407 Environments (CoRE) Parameters" Registry [IANA.core-parameters], as 408 follows: 410 +======================+================+======+===========+ 411 | Media Type | Content Coding | ID | Reference | 412 +======================+================+======+===========+ 413 | application/aif+cbor | - | TBD1 | RFC XXXX | 414 +----------------------+----------------+------+-----------+ 415 | application/aif+json | - | TBD2 | RFC XXXX | 416 +----------------------+----------------+------+-----------+ 418 Table 5 420 // RFC Ed.: please replace TBD1 and TBD2 with assigned IDs and remove 421 this note. // RFC Ed.: please replace RFC XXXX with this RFC number 422 and remove this note. 424 6. Security Considerations 426 The security considerations of [RFC7252] apply. Some wider issues 427 are discussed in [RFC8576]. 429 When applying these formats, the referencing specification must be 430 careful to: 432 * ensure that the cryptographic armor employed around this format 433 fulfills the security objectives, and that the armor or some 434 additional information included in it with the AIF information 435 unambiguously identifies the subject to which the authorizations 436 shall apply, and 438 * ensure that the types used for "Toid" and "Tperm" provide the 439 appropriate granularity so that application requirements on the 440 precision of the authorization information are fulfilled. 442 For the data formats, the security considerations of [RFC8259] and 443 [RFC8949] apply. 445 7. References 447 7.1. Normative References 449 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 450 Requirement Levels", BCP 14, RFC 2119, 451 DOI 10.17487/RFC2119, March 1997, 452 . 454 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 455 Application Protocol (CoAP)", RFC 7252, 456 DOI 10.17487/RFC7252, June 2014, 457 . 459 [RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for 460 Writing an IANA Considerations Section in RFCs", BCP 26, 461 RFC 8126, DOI 10.17487/RFC8126, June 2017, 462 . 464 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 465 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 466 May 2017, . 468 [RFC8610] Birkholz, H., Vigano, C., and C. Bormann, "Concise Data 469 Definition Language (CDDL): A Notational Convention to 470 Express Concise Binary Object Representation (CBOR) and 471 JSON Data Structures", RFC 8610, DOI 10.17487/RFC8610, 472 June 2019, . 474 7.2. Informative References 476 [I-D.ietf-ace-oauth-authz] 477 Seitz, L., Selander, G., Wahlstroem, E., Erdtman, S., and 478 H. Tschofenig, "Authentication and Authorization for 479 Constrained Environments (ACE) using the OAuth 2.0 480 Framework (ACE-OAuth)", Work in Progress, Internet-Draft, 481 draft-ietf-ace-oauth-authz-36, 16 November 2020, 482 . 485 [IANA.core-parameters] 486 IANA, "Constrained RESTful Environments (CoRE) 487 Parameters", 488 . 490 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 491 Resource Identifier (URI): Generic Syntax", STD 66, 492 RFC 3986, DOI 10.17487/RFC3986, January 2005, 493 . 495 [RFC4949] Shirey, R., "Internet Security Glossary, Version 2", 496 FYI 36, RFC 4949, DOI 10.17487/RFC4949, August 2007, 497 . 499 [rfc5661] Shepler, S., Ed., Eisler, M., Ed., and D. Noveck, Ed., 500 "Network File System (NFS) Version 4 Minor Version 1 501 Protocol", RFC 5661, DOI 10.17487/RFC5661, January 2010, 502 . 504 [RFC6570] Gregorio, J., Fielding, R., Hadley, M., Nottingham, M., 505 and D. Orchard, "URI Template", RFC 6570, 506 DOI 10.17487/RFC6570, March 2012, 507 . 509 [RFC7231] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 510 Protocol (HTTP/1.1): Semantics and Content", RFC 7231, 511 DOI 10.17487/RFC7231, June 2014, 512 . 514 [RFC7493] Bray, T., Ed., "The I-JSON Message Format", RFC 7493, 515 DOI 10.17487/RFC7493, March 2015, 516 . 518 [RFC8132] van der Stok, P., Bormann, C., and A. Sehgal, "PATCH and 519 FETCH Methods for the Constrained Application Protocol 520 (CoAP)", RFC 8132, DOI 10.17487/RFC8132, April 2017, 521 . 523 [RFC8259] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 524 Interchange Format", STD 90, RFC 8259, 525 DOI 10.17487/RFC8259, December 2017, 526 . 528 [RFC8576] Garcia-Morchon, O., Kumar, S., and M. Sethi, "Internet of 529 Things (IoT) Security: State of the Art and Challenges", 530 RFC 8576, DOI 10.17487/RFC8576, April 2019, 531 . 533 [RFC8949] Bormann, C. and P. Hoffman, "Concise Binary Object 534 Representation (CBOR)", STD 94, RFC 8949, 535 DOI 10.17487/RFC8949, December 2020, 536 . 538 Acknowledgements 540 Jim Schaad and Francesca Palombini provided comments that shaped the 541 direction of this document. 543 Author's Address 545 Carsten Bormann 546 Universität Bremen TZI 547 Postfach 330440 548 D-28359 Bremen 549 Germany 551 Phone: +49-421-218-63921 552 Email: cabo@tzi.org