Status of This Memo

This is an Internet Standards Track document.¶

This document is a product of the Internet Engineering Task Force (IETF). It represents the consensus of the IETF community. It has received public review and has been approved for publication by the Internet Engineering Steering Group (IESG). Further information on Internet Standards is available in Section 2 of RFC 7841.¶

Information about the current status of this document, any errata, and how to provide feedback on it may be obtained at https://www.rfc-editor.org/info/rfc9237.¶

Copyright Notice

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

This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Revised BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Revised BSD License.¶

Table of Contents

1. Introduction

Constrained devices, as they are used in the Internet of Things, need security in order to operate correctly and prevent misuse. One important element of this security is that devices in the Internet of Things need to be able to decide which operations requested of them should be considered authorized, ascertain that the authorization to request the operation does apply to the actual requester as authenticated, and ascertain that other devices they make requests of are the ones they intended.¶

To transfer detailed authorization information from an authorization manager (such as an ACE-OAuth authorization server [RFC9200]) to a device, a compact representation format is needed. This document defines such a format -- the Authorization Information Format (AIF). AIF is defined both as a general structure that can be used for many different applications and as a specific instantiation tailored to REST resources and the permissions on them, including some provision for dynamically created resources.¶

2. Information Model

Authorizations are generally expressed through some data structures that are cryptographically secured (or transmitted in a secure way). This section discusses the information model underlying the payload of that data (as opposed to the cryptographic armor around it).¶

The semantics of the authorization information defined in this document are that of an allow-list: everything is denied until it is explicitly allowed.¶

For the purposes of this specification, the underlying access control model will be that of an access matrix, which gives a set of permissions for each possible combination of a subject and an object. We are focusing the AIF data item on a single row in the access matrix (such a row has often been called a "capability list") without concern to the subject for which the data item is issued. As a consequence, AIF MUST be used in a way that the subject of the authorizations is unambiguously identified (e.g., as part of the armor around it).¶

The generic model of such a capability list is a list of pairs of object identifiers (of type Toid) and the permissions (of type Tperm) that the subject has on the object(s) identified.¶

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

In a specific data model (such as the one specified in this document), the object identifier (Toid) will often be a text string, and the set of permissions (Tperm) will be represented by a bit set, which in turn is represented as a number (see Section 3).¶

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

3. Data Model

Different data model specializations can be defined for the generic information model given above.¶

In this section, we will give the data model for simple REST authorization as per Sections 2.1 and 2.3. As discussed, in this case the object identifier is specialized as a text string giving a relative URI (URI-local-part as the absolute path on the server serving as the enforcement point). The permission set is specialized to a single number REST-method-set by the following steps:¶

• The entries in the table that specify the same URI-local-part are merged into a single entry that specifies the union of the permission sets.¶
• The (non-dynamic) methods in the permission sets are converted into their CoAP method numbers, minus 1.¶
• Dynamic-X permissions are converted into what the number would have been for X, plus a Dynamic-Offset chosen as 32 (e.g., 35 is the number for Dynamic-DELETE as the number for DELETE is 3).¶
• The set of numbers is converted into a single number REST-method-set by taking two to the power of each (decremented) method number and computing the inclusive OR of the binary representations of all the power values.¶

This data model could be interchanged in the JSON [RFC8259] representation given in Figure 3.¶

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

In Figure 4, a straightforward specification of the data model (including both the methods from [RFC7252] and the new ones from [RFC8132], identified by the method code minus 1) is shown in CDDL [RFC8610] [RFC9165]:¶

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
)

For the information shown in Table 1 and Figure 3, a representation in Concise Binary Object Representation (CBOR) [RFC8949] is given in Figure 5; again, several optimizations and improvements are possible.¶

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)

Note that choosing 32 as Dynamic-Offset means that all future CoAP methods that are registered can be represented both as themselves and in the Dynamic-X variant, but only the dynamic forms of methods 1 to 21 are typically usable in a JSON form [RFC7493].¶

4. Media Types

This specification defines media types for the generic information model, expressed in JSON (application/aif+json) or in CBOR (application/aif+cbor). These media types have parameters for specifying Toid and Tperm; default values are the values "URI-local-part" for Toid and "REST-method-set" for Tperm, as per Section 3 of the present specification.¶

A specification that wants to use generic AIF with different Toid and/or Tperm is expected to request these as media type parameters (Section 5.2) and register a corresponding Content-Format (Section 5.3).¶

5. IANA Considerations

6. Security Considerations

The security considerations of [RFC7252] apply when AIF is used with CoAP, and, if complex formats such as URIs are used for Toid or Tperm, specifically Section 11.1 of [RFC7252]. Some wider issues are discussed in [RFC8576].¶

When applying these formats, the referencing specification needs to be careful to ensure that:¶

• the cryptographic armor employed around this format fulfills the referencing specification's security objectives and that the armor or some additional information included in it with the AIF data item (1) unambiguously identifies the subject to which the authorizations shall apply and (2) provides any context information needed to derive the identity of the object to which authorization is being granted from the object identifiers (such as, for the data models defined in the present specification, the scheme and authority information that is used to construct the full URI), and¶
• the types used for Toid and Tperm provide the appropriate granularity and precision so that application requirements on the precision of the authorization information are fulfilled and that all parties have the same understanding of each Toid/Tperm pair in terms of specified objects (resources) and operations on those.¶

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

A plain implementation of AIF might implement just the basic REST model as per Section 2.1. If it receives authorizations that include permissions that use the REST-Specific Model with Dynamic Resource Creation (Section 2.3), it needs to either reject the AIF data item entirely or act only on the permissions that it does understand. In other words, the semantics underlying an allow-list as discussed above need to hold here as well.¶

An implementation of the REST-Specific Model with Dynamic Resource Creation (Section 2.3) needs to carefully keep track of the dynamically created objects and the subjects to which the Dynamic-X permissions apply -- both on the server side to enforce the permissions and on the client side to know which permissions are available.¶

Acknowledgements

Jim Schaad, Francesca Palombini, Olaf Bergmann, Marco Tiloca, and Christian Amsüss provided comments that shaped the direction of this document. Alexey Melnikov pointed out that there were gaps in the media type specifications, and Loganaden Velvindron provided a shepherd review with further comments. Many thanks also to the IESG reviewers, who provided several small but significant observations. Benjamin Kaduk provided an extensive review as Responsible Area Director and indeed is responsible for much improvement in the document.¶

Author's Address