| RFC 9237 | ACE AIF | August 2022 |
| Bormann | Standards Track | [Page] |
Information about which entities are authorized to perform whatoperations on which constituents of other entities is a crucialcomponent of producing an overall system that is secure. Conveyingprecise authorization information is especially critical in highlyautomated systems with large numbers of entities, such as theInternet of Things.¶
This specification provides a generic information model and format forrepresenting such authorization information, as well as two variantsof a specific instantiation of that format for use with Representational State Transfer (REST) resourcesidentified by URI path.¶
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 athttps://www.rfc-editor.org/info/rfc9237.¶
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.¶
Constrained devices, as they are used in the Internet of Things, needsecurity in order to operate correctly and prevent misuse.One important element of this security is that devices in the Internetof Things need to be able to decide which operations requested of themshould be considered authorized, ascertain that theauthorization to request the operation does apply to the actualrequester as authenticated,and ascertain that other devices they makerequests 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, acompact representation format is needed.This document defines such a format -- theAuthorization Information Format (AIF).AIF is defined both as a general structure that can be used for manydifferent applications andas a specific instantiation tailored to REST resources and the permissionson them, including some provision for dynamically created resources.¶
This memo uses terms from the Constrained Application Protocol (CoAP)[RFC7252] and the Internet Security Glossary[RFC4949]; CoAP is used forthe explanatory examples as it is a good fit for constrained devices.¶
The shape of data is specified in Concise Data Definition Language (CDDL)[RFC8610][RFC9165].Terminology for constrained devices is defined in[RFC7228].¶
The term "byte", abbreviated by "B", is used in its now customarysense 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 beinterpreted as described in BCP 14[RFC2119][RFC8174] when, and only when, they appear in all capitals, as shownhere.¶
Authorizations are generally expressed through some data structuresthat are cryptographically secured (or transmitted in a secure way).This section discusses the information model underlying the payload ofthat data (as opposed to the cryptographic armor around it).¶
The semantics of the authorization information defined in thisdocument are that of anallow-list:everything is denied until it is explicitly allowed.¶
For the purposes of this specification, the underlying access control modelwill be that of an access matrix, which gives a set of permissions foreach 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") withoutconcern to the subject for which the data item is issued.As a consequence, AIFMUST be used in a way that the subject of theauthorizations is unambiguously identified (e.g., as part of the armoraround it).¶
The generic model of such a capability list is a list of pairs ofobject identifiers (of typeToid) and the permissions (of typeTperm) that the subject has on theobject(s) identified.¶
AIF-Generic<Toid, Tperm> = [* [Toid, Tperm]]
In a specific data model (such as the one specified inthis document), the object identifier (Toid) will often bea text string, and the set of permissions (Tperm) will be representedby a bit set, which in turn is represented as a number (seeSection 3).¶
AIF-Specific = AIF-Generic<tstr, uint>
In the specific instantiation of the REST resources and the permissions on them, we use the URI of a resource on a CoAP server for the object identifier (Toid). More specifically, since the parts of the URI that identify the server ("authority" in[RFC3986]) are authenticated during REST resource access (Section 4.2.2 of [RFC9110] andSection 6.2 of [RFC7252]), they naturally fall into the realm handled by the cryptographic armor; we therefore focus on the "path" ("path-abempty") and "query" parts of the URI (URI-local-part in this specification, as expressed by the Uri-Path and Uri-Query options in CoAP).As a consequence, AIFMUST be used in a way that it is clearwho is the target (enforcement point) of these authorizations(note that there may be more than one target that the sameauthorization applies to, e.g., in a situation with homogeneousdevices).¶
For the permissions (Tperm), we use a simple permissions model thatlists the subset of the REST (CoAP or HTTP) methods permitted.This model is summarized inTable 1.¶
| URI-local-part | Permission Set |
|---|---|
| /s/temp | GET |
| /a/led | PUT, GET |
| /dtls | POST |
In this example, a device offers a temperature sensor/s/temp forread-only access, a LED actuator/a/led for read/write, and a/dtls resource for POST access.¶
As shown in the data model (Section 3), the representationsof REST methods provided are limited to those that have a CoAP methodnumber assigned; an extension to the model may be necessary to representpermissions for exotic HTTP methods.¶
This simple information model only allows granting permissions forstatically identifiable objects, e.g., URIs for the REST-specificinstantiation. One might be tempted to extend the model towards URItemplates[RFC6570] (for instance, to open up anauthorization for many parameter values as in/s/temp{?any*}).However, that requires some considerations ofthe ease and unambiguity of matching a given URI against a set oftemplates in an AIF data item.¶
This simple information model also does not allow expressingconditionalized access based on state outside the identification ofobjects (e.g., "opening a door is allowed if it is not locked").¶
Finally, the model does not provide any special access for a set ofresources that are specific to a subject, e.g., that the subjectcreated itself by previous operations (PUT, POST, or PATCH/iPATCH[RFC8132]) or that werespecifically created for the subject by others.¶
TheREST-specific model with dynamic resource creation addresses the need to provide defined access to dynamic resources that were created by the subject itself, specifically, a resource that is made known to the subject by providing Location-* options in a CoAP response or using the Location header field in HTTP[RFC9110] (the Location-indicating mechanisms). (The concept is somewhat comparable to "Access Control List (ACL) inheritance" in the Network File System version 4 (NFSv4) protocol[RFC8881], except that it does not use a containment relationship but rather the fact that the dynamic resource was created from a resource to which the subject had access.) In other words, it addresses an important subset of the third limitation mentioned inSection 2.2.¶
| URI-local-part | Permission Set |
|---|---|
| /a/make-coffee | POST, Dynamic-GET, Dynamic-DELETE |
For a method X, the presence of a Dynamic-X permission means that the subjectholds permission to exercise the method X on resources that have beenreturned in a 2.01 (201 Created) response by a Location-indicating mechanism to a request that thesubject made to the resource listed.In the example shown inTable 2, POST operations on/a/make-coffee might return the location of a resource dynamicallycreated on the coffee machine that allows GET to findout about the status of, and DELETE to cancel, the coffee-makingoperation.¶
Since the use of the extension defined in this section can be detectedby the mentioning of the Dynamic-X permissions, there is no need foranother explicit switch between the basic and the model extended bydynamic resource creation; theextended model is always presumed once a Dynamic-X permission is present.¶
Different data model specializations can be defined for the genericinformation model given above.¶
In this section, we will give the data model for simple RESTauthorization as per Sections2.1 and2.3.As discussed, in this case the object identifier is specialized as a text stringgiving a relative URI (URI-local-part as the absolute path on the serverserving as the enforcement point).The permission set is specialized to a single numberREST-method-set by the following steps:¶
This data model could be interchanged in the JSON[RFC8259] representation given inFigure 3.¶
[["/s/temp",1],["/a/led",5],["/dtls",2]]
InFigure 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 pointREST-method-set = uint .bits methodsmethods = &( 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
For the information shown inTable 1 andFigure 3, arepresentation in Concise Binary Object Representation (CBOR)[RFC8949] is given inFigure 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 having chosen 32 as Dynamic-Offset means that all future CoAPmethods that are registered can be represented both as themselvesand in the Dynamic-X variant, but that only the dynamic forms of methods 1to 21 are typically usable in a JSON form[RFC7493].¶
This specification defines media types for the generic informationmodel, expressed in JSON (application/aif+json) or in CBOR (application/aif+cbor). These media types haveparameters for specifyingToid andTperm; default values are thevalues "URI-local-part" forToid and "REST-method-set" forTperm, asperSection 3 of the present specification.¶
A specification that wants to use generic AIF with differentToidand/orTperm is expected to request these as media type parameters(Section 5.2) and register a corresponding Content-Format (Section 5.3).¶
IANA has added the following media types to the "Media Types" registry. The registration entries are in the following subsections.¶
| Name | Template | Reference |
|---|---|---|
| aif+cbor | application/aif+cbor | RFC 9237,Section 4 |
| aif+json | application/aif+json | RFC 9237,Section 4 |
application¶
aif+cbor¶
N/A¶
Toid:Toid.Default value: "URI-local-part" (RFC 9237).¶Tperm:Toid.A value from the "Sub-Parameter Registry for application/aif+cbor and application/aif+json" subregistry forTperm.Default value: "REST-method-set" (RFC 9237).¶binary (CBOR)¶
N/A¶
Applications that need to convey structured authorization data foridentified resources, conveying sets of permissions.¶
The syntax and semantics of fragment identifiers is as specified for"application/cbor". (At publication of RFC 9237, there is nofragment identification syntax defined for "application/cbor".)¶
ACE WG mailing list (ace@ietf.org)or IETF Applications and Real-Time Area (art@ietf.org)¶
COMMON¶
N/A¶
IETF¶
no¶
application¶
aif+json¶
N/A¶
Toid:Toid.Default value: "URI-local-part" (RFC 9237).¶Tperm:Toid.A value from the media-type parameter subregistry forTperm.Default value: "REST-method-set" (RFC 9237).¶binary (JSON is UTF-8-encoded text)¶
N/A¶
Applications that need to convey structured authorization data foridentified resources, conveying sets of permissions.¶
The syntax and semantics of fragment identifiers is as specified for"application/json". (At publication of RFC 9237, there is nofragment identification syntax defined for "application/json".)¶
ACE WG mailing list (ace@ietf.org)or IETF Applications and Real-Time Area (art@ietf.org)¶
COMMON¶
N/A¶
IETF¶
no¶
For the media types application/aif+cbor and application/aif+json,IANA has created a subregistry within[IANA.media-type-sub-parameters] for the media-type parametersToid andTperm, populated with the following:¶
| Parameter | name | Description/Specification | Reference |
|---|---|---|---|
| Toid | URI-local-part | local-part of URI | RFC 9237 |
| Tperm | REST-method-set | set of REST methods represented | RFC 9237 |
The registration policy is Specification Required[RFC8126].The designated expert will engage with the submitter to ascertain whether therequirements of this document are addressed:¶
Toid andTperm need to realize thegeneral ideas of unambiguous object identifiers and permission listsin the context where the AIF data item is intended to be used, andtheir structure needs to be usable with the intended media types(application/aif+cbor and application/aif+json) as identified in thespecification.¶The designated experts will develop further criteria and guidelines asneeded.¶
IANA has registered Content-Format numbers in the "CoAPContent-Formats" subregistry, within the "Constrained RESTfulEnvironments (CoRE) Parameters" registry[IANA.core-parameters], asfollows:¶
| Media Type | Encoding | ID | Reference |
|---|---|---|---|
| application/aif+cbor | - | 290 | RFC 9237 |
| application/aif+json | - | 291 | RFC 9237 |
Note that applications that registerToid andTperm values areencouraged to also register Content-Formats for the relevantcombinations.¶
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 forToid orTperm. Some wider issues are discussed in[RFC8576].¶
When applying these formats, the referencing specification needs to becareful to ensure:¶
Toid andTperm provide theappropriate granularity and precision so that application requirements on theprecision of the authorization information are fulfilled and thatall parties have the same understanding of eachToid/Tperm pair interms 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 RESTmodel as perSection 2.1. If it receives authorizations thatinclude permissions that use the REST-specific model with dynamicresource creation (Section 2.3), it needs to eitherreject the AIF data item entirely or act only on thepermissions that it does understand.In other words, the semantics underlying an allow-list as discussedabove need to hold here as well.¶
An implementation of the REST-specific model with dynamic resourcecreation (Section 2.3) needs to carefully keep track of thedynamically created objects and the subjects to which the Dynamic-Xpermissions apply -- both on the server side to enforce the permissionsand on the client side to know which permissions are available.¶
Jim Schaad,Francesca Palombini,Olaf Bergmann,Marco Tiloca,andChristian Amsüssprovided comments that shaped thedirection of this document.Alexey Melnikov pointed out that there were gaps in the mediatype specifications, andLoganaden Velvindron provided a shepherdreview with further comments.Many thanks also to the IESG reviewers, who provided several smallbut significant observations.Benjamin Kaduk provided an extensive review as Responsible AreaDirector and indeed is responsible for much improvement in the document.¶