RFC 9237

An Authorization Information Format (AIF) for Authentication and Authorization for Constrained Environments (ACE)

📅 published August 2022, from ietf

RFC 9237 🎀 Part 1 of 3, more coming bestie 💅

Title: An Authorization Information Format (AIF) for Authentication and Authorization for Constrained Environments (ACE) 🦋 Author: C. Bormann, Universität Bremen TZI 🧚 Category: Standards Track ✨ Date: August 2022 📅 Series: IETF, ISSN 2070-1721 🌈 Obsoletes/Updates: the title block doesn't list anything this one obsoletes or updates 🙈

Abstract ✨

okay so knowing who is allowed to do what to which parts of which things is literally the backbone of a secure system 🔐 and it gets even more important when you've got a huge pile of automated devices, like the Internet of Things 🌸

this spec gives you a generic information model and format for writing that authorization info down 📝 It also has two flavours of a specific version built for REST resources that are identified by URI path 🍓

Status of This Memo 💜

this is an Internet Standards Track document 🔥

it's a product of the Internet Engineering Task Force (IETF) and it reflects the consensus of the IETF community 🫶 It got public review and was approved for publication by the Internet Engineering Steering Group (IESG) 👑 If you want more on Internet Standards, check out Section 2 of RFC 7841 🎀

for the current status, any errata, or to send feedback, go to https://www.rfc-editor.org/info/rfc9237 ✨

Copyright (c) 2022 IETF Trust and the persons identified as the document authors 💅 All rights reserved 🦋

this doc is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents, which you can find at https://trustee.ietf.org/license-info as in effect on the publication date ⭐ Please actually read these, bestie, because they spell out your rights and restrictions for this doc 🙈 Code Components pulled out of this document must include Revised BSD License text as described in Section 4.e of the Trust Legal Provisions, and they come without warranty, as described in the Revised BSD License 💀

Table of Contents 🧚

1.  Introduction
  1.1.  Terminology
2.  Information Model
  2.1.  REST-Specific Model
  2.2.  Limitations
  2.3.  REST-Specific Model with Dynamic Resource Creation
3.  Data Model
4.  Media Types
5.  IANA Considerations
  5.1.  Media Types
    5.1.1.  application/aif+cbor
    5.1.2.  application/aif+json
  5.2.  Registries
  5.3.  Content-Format
6.  Security Considerations
7.  References
  7.1.  Normative References
  7.2.  Informative References
Acknowledgements
Author's Address

1. Introduction 💖

constrained devices, like the ones in the Internet of Things, need security to work properly and to stop people misusing them 🔐 A big part of that is that devices need to be able to decide which requested operations count as authorized 🎀 They also need to confirm that the authorization for a request really applies to the requester who was authenticated 🫶 And they need to make sure the other devices they send requests to are the ones they meant to talk to 👑

so you need to move detailed authorization info from an authorization manager (like an ACE-OAuth authorization server [RFC9200]) over to a device 🦋 That calls for a compact representation format, and this document defines one: the Authorization Information Format (AIF) 🌸 AIF is written as a general structure that works for lots of different applications, and it also comes as a specific version tailored to REST resources and the permissions on them 💅 That specific version even has a bit of support for dynamically created resources ✨

1.1. Terminology 📖

this memo uses terms from the Constrained Application Protocol (CoAP) [RFC7252] and the Internet Security Glossary [RFC4949] 🧚 CoAP shows up in the examples because it's a great fit for constrained devices 💜

the shape of data is specified in Concise Data Definition Language (CDDL) [RFC8610] [RFC9165] 🌈 Terminology for constrained devices comes from [RFC7228] 🍓

the term "byte", abbreviated as "B", is used in its now customary sense as a synonym for "octet" 🫶

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here. 🔥

2. Information Model 🎀

authorizations usually come wrapped in data structures that are cryptographically secured (or sent over a secure channel) 🔐 This section is all about the information model behind the payload of that data, as opposed to the cryptographic armor around it 🛡️

the semantics of the authorization info in this document are those of an allow-list: everything is denied until it is explicitly allowed 🚫 Anything not on the list is a no-go, bestie 💀

for this spec, the underlying access control model is an access matrix, which gives a set of permissions for every possible pairing of a subject and an object 🦋 The AIF data item focuses on a single row of that matrix (people often call that row a "capability list") and doesn't care which subject it's issued for 🧚 Because of that, AIF MUST be used in a way that the subject of the authorizations is unambiguously identified (for example, as part of the armor around it) 👑

the generic model of a capability list is a list of pairs, each holding an object identifier (of type Toid) and the permissions (of type Tperm) that the subject has on the object or objects identified 🌸

AIF-Generic<Toid, Tperm> = [* [Toid, Tperm]]

                 Figure 1: Definition of Generic AIF

in a specific data model (like the one in this document), the object identifier (Toid) is usually a text string, and the set of permissions (Tperm) is a bit set, which is represented as a number (see Section 3) 💜

AIF-Specific = AIF-Generic<tstr, uint>

           Figure 2: Commonly Used Shape of a Specific AIF

2.1. REST-Specific Model 🍓

for the specific version covering REST resources and the permissions on them, the object identifier (Toid) is the URI of a resource on a CoAP server ✨ More precisely, the parts of the URI that identify the server ("authority" in [RFC3986]) are authenticated during REST resource access (Section 4.2.2 of [RFC9110] and Section 6.2 of [RFC7252]), so they naturally belong to the cryptographic armor 🛡️ That means we focus on the "path" ("path-abempty") and "query" parts of the URI (URI-local-part in this spec, which maps onto the Uri-Path and Uri-Query options in CoAP) 🫶 As a result, AIF MUST be used in a way that makes it clear who the target (enforcement point) of these authorizations is. There may be more than one target that the same authorization applies to, for example in a situation with homogeneous devices 🌈

for the permissions (Tperm), we use a simple model that lists the subset of REST (CoAP or HTTP) methods that are permitted 💅 Table 1 sums it up 🦋

+================+================+
| URI-local-part | Permission Set |
+================+================+
| /s/temp        | GET            |
+----------------+----------------+
| /a/led         | PUT, GET       |
+----------------+----------------+
| /dtls          | POST           |
+----------------+----------------+

     Table 1: An Authorization Instance in the REST-Specific
                     AIF Information Model

in this example, a device offers a temperature sensor at /s/temp for read-only access, an LED actuator at /a/led for read/write, and a /dtls resource for POST access 🌸

as shown in the data model (Section 3), the REST method representations are limited to those that have a CoAP method number assigned 🔢 Representing permissions for exotic HTTP methods might need an extension to the model 🧚

2.2. Limitations 🙈

this simple information model only lets you grant permissions for statically identifiable objects, like URIs in the REST-specific version 💖 You might be tempted to extend it toward URI templates [RFC6570] (for instance, to open up an authorization for many parameter values, as in /s/temp{?any*}) 👀 But that needs some thought about how easily and unambiguously a given URI can be matched against a set of templates in an AIF data item 🤔

this model also can't express conditional access based on state outside the identification of objects, like "opening a door is allowed if it is not locked" 🚪🔒

finally, the model doesn't give any special access to a set of resources specific to a subject, like resources the subject created itself through previous operations (PUT, POST, or PATCH/iPATCH [RFC8132]) or resources that others specifically created for the subject 💀

2.3. REST-Specific Model with Dynamic Resource Creation 🦋

the REST-specific model with dynamic resource creation gives defined access to dynamic resources that the subject created itself 🎀 Those are resources made known to the subject through Location-* options in a CoAP response, or through the Location header field in HTTP [RFC9110] (the Location-indicating mechanisms) 🧚 (This is kind of like "Access Control List (ACL) inheritance" in the Network File System version 4 (NFSv4) protocol [RFC8881], except it doesn't use a containment relationship. It relies on the fact that the dynamic resource was created from a resource the subject already had access to.) So it covers an important subset of the third limitation from Section 2.2 ✨

+================+===================================+
| URI-local-part | Permission Set                    |
+================+===================================+
| /a/make-coffee | POST, Dynamic-GET, Dynamic-DELETE |
+----------------+-----------------------------------+

   Table 2: An Authorization Instance in the REST-
     Specific AIF Information Model with Dynamic
                  Resource Creation

for a method X, a Dynamic-X permission means the subject holds permission to use method X on resources that were returned in a 2.01 (201 Created) response by a Location-indicating mechanism, to a request the subject made to the listed resource 🌈 In the Table 2 example, POST operations on /a/make-coffee might return the location of a resource dynamically created on the coffee machine, which lets the subject GET the status of the coffee-making operation and DELETE to cancel it ☕💜

since the extension from this section can be detected by spotting Dynamic-X permissions, there's no need for another explicit switch between the basic model and the one extended with dynamic resource creation 🫶 The extended model is always presumed as soon as a Dynamic-X permission is present 💅✨

3. Data Model ✨

Okay bestie, this is where the generic information model gets specialized 💅 You can define different data model specializations on top of it, and this section shows the one for simple REST authorization, which lines up with Sections 2.1 and 2.3. 🦋 Here the object identifier becomes a text string holding a relative URI. It's the URI-local-part, which is the absolute path on the server acting as the enforcement point 🌸 The permission set gets squished down into one single number, REST-method-set, using these steps:

  • Entries in the table that have the same URI-local-part get merged into one entry, and that entry is the union of their permission sets. 🫶
  • The non-dynamic methods in the permission sets get turned into their CoAP method numbers, minus 1.
  • Dynamic-X permissions become whatever the number for X would have been, plus a Dynamic-Offset, which is chosen as 32. For example, 35 is the number for Dynamic-DELETE, since the number for DELETE is 3. 🔥
  • The set of numbers becomes one number, REST-method-set. You take two to the power of each (decremented) method number, then compute the inclusive OR of the binary representations of all those power values. 🧚

This data model can be interchanged in the JSON [RFC8259] representation shown in Figure 3. 🍓

[["/s/temp",1],["/a/led",5],["/dtls",2]]

Figure 3: An Authorization Instance Encoded in JSON (40 Bytes)

In Figure 4, a straightforward specification of the data model (covering both the methods from [RFC7252] and the new ones from [RFC8132], each identified by its method code minus 1) is written in CDDL [RFC8610] [RFC9165]. Iconic energy 👑

AIF-REST = AIF-Generic<local-path, REST-method-set>
local-path = tstr   ; URI relative to enforcement point
REST-method-set = uint .bits methods
methods = &(
  GET: 0
  POST: 1
  PUT: 2
  DELETE: 3
  FETCH: 4
  PATCH: 5
  iPATCH: 6
  Dynamic-GET: 32; 0 .plus Dynamic-Offset
  Dynamic-POST: 33; 1 .plus Dynamic-Offset
  Dynamic-PUT: 34; 2 .plus Dynamic-Offset
  Dynamic-DELETE: 35; 3 .plus Dynamic-Offset
  Dynamic-FETCH: 36; 4 .plus Dynamic-Offset
  Dynamic-PATCH: 37; 5 .plus Dynamic-Offset
  Dynamic-iPATCH: 38; 6 .plus Dynamic-Offset
)
Dynamic-Offset = 32

Figure 4: AIF in CDDL

For the information shown in Table 1 and Figure 3, the Concise Binary Object Representation (CBOR) [RFC8949] version is in Figure 5. Again, there are several optimizations and improvements possible, so this isn't the final word 🦋

83                        # array(3)
   82                     # array(2)
      67                  # text(7)
         2f732f74656d70   # "/s/temp"
      01                  # unsigned(1)
   82                     # array(2)
      66                  # text(6)
         2f612f6c6564     # "/a/led"
      05                  # unsigned(5)
   82                     # array(2)
      65                  # text(5)
         2f64746c73       # "/dtls"
      02                  # unsigned(2)

Figure 5: An Authorization Instance Encoded in CBOR (28 Bytes)

Note that choosing 32 as the Dynamic-Offset means every future CoAP method that gets registered can be represented both as itself and in its Dynamic-X variant. That's giving future-proof ✨ But only the dynamic forms of methods 1 to 21 are typically usable in a JSON form [RFC7493], so keep that in mind 🙈

4. Media Types

Two media types are defined for the generic information model: application/aif+json, which is JSON, and application/aif+cbor, which is CBOR. 💜 Both have parameters for specifying Toid and Tperm. The default values are "URI-local-part" for Toid and "REST-method-set" for Tperm, as described in Section 3 of this specification.

A specification that wants to use generic AIF with a different Toid and/or Tperm is expected to request those as media type parameters (Section 5.2) and register a matching Content-Format (Section 5.3). Main character energy in the registry world 🎀

5. IANA Considerations 🌈

5.1. Media Types

IANA added the following media types to the "Media Types" registry. The registration entries live in the subsections below ⭐

+==========+======================+=====================+
| Name     | Template             | Reference           |
+==========+======================+=====================+
| aif+cbor | application/aif+cbor | RFC 9237, Section 4 |
+----------+----------------------+---------------------+
| aif+json | application/aif+json | RFC 9237, Section 4 |
+----------+----------------------+---------------------+

                 Table 3: New Media Types

5.1.1. application/aif+cbor

  • Type name: application
  • Subtype name: aif+cbor
  • Required parameters: N/A
  • Optional parameters:
    • Toid: the identifier for the object that the permissions are supplied for. It's a value from the "Sub-Parameter Registry for application/aif+cbor and application/aif+json" subregistry for Toid. Default value: "URI-local-part" (RFC 9237).
    • Tperm: the data type of a permission set for the object identified via a Toid. It's a value from the "Sub-Parameter Registry for application/aif+cbor and application/aif+json" subregistry for Tperm. Default value: "REST-method-set" (RFC 9237).
  • Encoding considerations: binary (CBOR)
  • Security considerations: Section 6 of RFC 9237. Security is serious business, so go read it 🔥
  • Interoperability considerations: N/A
  • Published specification: Section 4 of RFC 9237
  • Applications that use this media type: applications that need to convey structured authorization data for identified resources, conveying sets of permissions 💅
  • Fragment identifier considerations: the syntax and semantics of fragment identifiers is as specified for "application/cbor". (At publication of RFC 9237, there is no fragment identification syntax defined for "application/cbor".)
  • Person & email address to contact for further information: ACE WG mailing list (ace@ietf.org) or IETF Applications and Real-Time Area (art@ietf.org) 📬
  • Intended usage: COMMON
  • Restrictions on usage: N/A
  • Author/Change controller: IETF
  • Provisional registration: no

5.1.2. application/aif+json

  • Type name: application
  • Subtype name: aif+json
  • Required parameters: N/A
  • Optional parameters:
    • Toid: the identifier for the object that the permissions are supplied for. It's a value from the media-type parameter subregistry for Toid. Default value: "URI-local-part" (RFC 9237).
    • Tperm: the data type of a permission set for the object identified via a Toid. It's a value from the media-type parameter subregistry for Tperm. Default value: "REST-method-set" (RFC 9237).
  • Encoding considerations: binary (JSON is UTF-8-encoded text)
  • Security considerations: Section 6 of RFC 9237. Yes, it's dramatic, but security stays important 😭
  • Interoperability considerations: N/A
  • Published specification: Section 4 of RFC 9237
  • Applications that use this media type: applications that need to convey structured authorization data for identified resources, conveying sets of permissions ✨
  • Fragment identifier considerations: the syntax and semantics of fragment identifiers is as specified for "application/json". (At publication of RFC 9237, there is no fragment identification syntax defined for "application/json".)
  • Person & email address to contact for further information: ACE WG mailing list (ace@ietf.org) or IETF Applications and Real-Time Area (art@ietf.org) 📬
  • Intended usage: COMMON
  • Restrictions on usage: N/A
  • Author/Change controller: IETF
  • Provisional registration: no

5.2. Registries

For the media types application/aif+cbor and application/aif+json, IANA created a subregistry within [IANA.media-type-sub-parameters] for the media-type parameters Toid and Tperm. It's populated with the following 🌸

+===========+=================+=====================+===========+
| Parameter | name            | Description/        | Reference |
|           |                 | Specification       |           |
+===========+=================+=====================+===========+
| Toid      | URI-local-part  | local-part of URI   | RFC 9237  |
+-----------+-----------------+---------------------+-----------+
| Tperm     | REST-method-set | set of REST methods | RFC 9237  |
|           |                 | represented         |           |
+-----------+-----------------+---------------------+-----------+

                 Table 4: New Media Type Parameters

The registration policy is Specification Required [RFC8126]. The designated expert will work with the submitter to check that the requirements of this document are addressed:

  • The specifications for Toid and Tperm need to get the general ideas right: unambiguous object identifiers and permission lists, in the context where the AIF data item is meant to be used. Their structure also needs to be usable with the intended media types (application/aif+cbor and application/aif+json) named in the specification 🧚
  • The parameter names need to conform to Section 4.3 of [RFC6838]. They're preferably written in [KebabCase], so they can be easily translated into names used in APIs with popular programming languages 💖

The designated experts will develop further criteria and guidelines as needed.

5.3. Content-Format

IANA registered Content-Format numbers in the "CoAP Content-Formats" subregistry, which sits within the "Constrained RESTful Environments (CoRE) Parameters" registry [IANA.core-parameters], like this 🦋

+======================+==========+=====+===========+
| Media Type           | Encoding | ID  | Reference |
+======================+==========+=====+===========+
| application/aif+cbor | -        | 290 | RFC 9237  |
+----------------------+----------+-----+-----------+
| application/aif+json | -        | 291 | RFC 9237  |
+----------------------+----------+-----+-----------+

              Table 5: New Content-Formats

Note that applications that register Toid and Tperm values are encouraged to also register Content-Formats for the relevant combinations. It's giving organized 🎀

6. Security Considerations 🔒✨

Okay bestie, this is the serious part, so listen up 🫶 The security considerations of [RFC7252] apply when AIF is used with CoAP. Section 11.1 of [RFC7252] specifically applies if complex formats such as URIs are used for Toid or Tperm. Some wider issues are discussed in [RFC8576].

When you apply these formats, the referencing specification needs to be careful to make sure of two things 💅

  • (1) The cryptographic armor around this format has to meet the referencing specification's security objectives. The armor, or some extra information included with the AIF data item, needs to unambiguously identify the subject that the authorizations shall apply to. It also needs to give any context needed to work out the identity of the object being authorized from its object identifiers. For the data models defined in this specification, that means the scheme and authority information used to build the full URI. Main character energy 👑
  • (2) The types used for Toid and Tperm need the right granularity and precision. That way the application's precision requirements for authorization information are met, and every party has the same understanding of each Toid/Tperm pair in terms of the specified objects (resources) and the operations on them. No one gets to be confused, periodt 💖

For the data formats, the security considerations of [RFC8259] and [RFC8949] apply 🌸

A plain implementation of AIF might only implement the basic REST model from Section 2.1. If it receives authorizations that include permissions using the REST-specific model with dynamic resource creation (Section 2.3), it needs to do one of two things. It can reject the AIF data item entirely, or it can act only on the permissions it does understand. Basically, the allow-list semantics we talked about above need to hold here too 🦋

An implementation of the REST-specific model with dynamic resource creation (Section 2.3) needs to be super careful about keeping track of the dynamically created objects and the subjects that the Dynamic-X permissions apply to. That goes for the server side, where it enforces the permissions, and the client side, where it needs to know which permissions are available 😭🎀

7. References 📚

7.1. Normative References

7.2. Informative References

Acknowledgements 🙏💜

Huge thanks to Jim Schaad, Francesca Palombini, Olaf Bergmann, Marco Tiloca, and Christian Amsüss, whose comments shaped the direction of this document 🌈 Alexey Melnikov spotted gaps in the media type specifications, and Loganaden Velvindron gave the shepherd review with more comments. Many thanks also to the IESG reviewers, who made several small but significant observations ⭐ And Benjamin Kaduk gave an extensive review as Responsible Area Director, and is honestly responsible for a lot of the improvement in this document 👑

Author's Address 🦋

Carsten Bormann
Universität Bremen TZI
Postfach 330440
D-28359 Bremen
Germany
Phone: +49-421-218-63921
Email: cabo@tzi.org
📦 where this page comes from