| Internet-Draft | ACE AIF | March 2022 |
| Bormann | Expires 16 September 2022 | [Page] |
Information about which entities are authorized to perform what operations on which constituents of other entities is a crucial component of producing an overall system that is secure. Conveying precise authorization information is especially critical in highly automated systems with large numbers of entities, such as the "Internet of Things".¶
This specification provides a generic information model and format for representing such authorization information, as well as two variants of a specific instantiation of that format for use with REST resources identified by URI path.¶
This note is to be removed before publishing as an RFC.¶
Status information for this document may be found at https://datatracker.ietf.org/doc/draft-ietf-ace-aif/.¶
Discussion of this document takes place on the Authentication and Authorization for Constrained Environments (ace) Working Group mailing list (mailto:ace@ietf.org), which is archived at https://mailarchive.ietf.org/arch/browse/ace/.¶
Source for this draft and an issue tracker can be found at https://github.com/cabo/ace-aif.¶
This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79.¶
Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet-Drafts is at https://datatracker.ietf.org/drafts/current/.¶
Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress."¶
This Internet-Draft will expire on 16 September 2022.¶
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" 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, need to ascertain that the authorization to request the operation does apply to the actual requester as authenticated, and need to 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 [I-D.ietf-ace-oauth-authz]) 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.¶
This memo uses terms from CoAP [RFC7252] and the Internet Security Glossary [RFC4949]; CoAP is used for the explanatory examples as it is a good fit for Constrained Devices.¶
The shape of data is specified in CDDL [RFC8610] [RFC9165]. Terminology for Constrained Devices is defined in [RFC7228].¶
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.¶
The term "byte", abbreviated by "B", is used in its now customary sense as a synonym for "octet".¶
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) the subject has on the
object(s) identified.¶
AIF-Generic<Toid, Tperm> = [* [Toid, Tperm]]
In a specific data model (such as the one also 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 bitset in turn represented as a number (see Section 3).¶
AIF-Specific = AIF-Generic<tstr, uint>
In the specific instantiation of the REST resources and the
permissions on them, for the object identifiers (Toid), we
use the URI of a resource on a CoAP server. More specifically, since the
parts of the URI that identify the server ("authority" in
[RFC3986]) are what are authenticated during REST resource access (Section 4.2.2 of [I-D.ietf-httpbis-semantics] and Section 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, AIF MUST be used in a way that it is
clear who is the target (enforcement point) of these authorizations
(note that there may be more than one target that the same
authorization applies to, e.g., in a situation with homogeneous
devices).¶
For the permissions (Tperm), we use a simple permissions model that
lists the subset of the REST (CoAP or HTTP) methods permitted.
This model is summarized in Table 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 for
read-only access, a LED actuator /a/led for read/write, and a
/dtls resource for POST access.¶
As will be seen in the data model (Section 3), the representations of REST methods provided are limited to those that have a CoAP method number assigned; an extension to the model may be necessary to represent permissions for exotic HTTP methods.¶
This simple information model only allows granting permissions for
statically identifiable objects, e.g., URIs for the REST-specific
instantiation. One might be tempted to extend the model towards URI
templates [RFC6570] (for instance, to open up an
authorization for many parameter values as in
/s/temp{?any*}).
However, that requires some considerations of
the ease and unambiguity of matching a given URI against a set of
templates in an AIF data item.¶
This simple information model also does not allow expressing conditionalized access based on state outside the identification of objects (e.g., "opening a door is allowed if that is not locked").¶
Finally, the model does not provide any special access for a set of resources that are specific to a subject, e.g., that the subject created itself by previous operations (PUT, POST, or PATCH/iPATCH [RFC8132]) or that were specifically created for the subject by others.¶
The REST-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 [I-D.ietf-httpbis-semantics] (the Location-indicating mechanisms). (The concept is somewhat comparable to "ACL inheritance" in NFSv4 [RFC8881], except that it does not use a containment relationship but 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 in Section 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 subject
holds permission to exercise the method X on resources that have been
returned in a 2.01 (201 Created) response by a Location-indicating mechanism to a request that the
subject made to the resource listed.
In the example shown in Table 2, POST operations on
/a/make-coffee might return the location of a resource dynamically
created on the coffee machine that allows GET to find
out about the status of, and DELETE to cancel, the coffee-making
operation.¶
Since the use of the extension defined in this section can be detected by the mentioning of the Dynamic-X permissions, there is no need for another explicit switch between the basic and the model extended by dynamic resource creation; the extended model is always presumed once a Dynamic-X permission is present.¶
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 Section 2.1 and Section 2.3.
As discussed, in this case the object identifier is specialized as a text string
giving a relative URI (URI-local-part as absolute path on the server
serving as enforcement point).
The permission set is specialized to a single number REST-method-set by the following steps:¶
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 CBOR [RFC8949] is given in Figure 5; again, several optimizations/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 can be 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].¶
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).¶
RFC Ed.: throughout this section, please replace RFC XXXX with the RFC number of this specification and remove this note.¶
IANA is requested to add the following Media-Types to the "Media Types" registry.¶
| Name | Template | Reference |
|---|---|---|
| aif+cbor | application/aif+cbor | RFC XXXX, Section 4 |
| aif+json | application/aif+json | RFC XXXX, Section 4 |
For application/aif+cbor:¶
application¶
aif+cbor¶
N/A¶
Toid: the identifier for the object for which permissions are
supplied.
A value from the media-type parameter sub-registry for Toid.
Default value: "URI-local-part" (RFC XXXX).¶
Tperm: the data type of a permission set for the object
identified via a Toid.
A value from the media-type parameter sub-registry for Tperm.
Default value: "REST-method-set" (RFC XXXX).¶
binary (CBOR)¶
none¶
Applications that need to convey structured authorization data for identified resources, conveying sets of permissions.¶
The syntax and semantics of fragment identifiers is as specified for "application/cbor". (At publication of RFC XXXX, there is no fragment identification syntax defined for "application/cbor".)¶
ACE WG mailing list (ace@ietf.org), or IETF Applications and Real-Time Area (art@ietf.org)¶
COMMON¶
none¶
IETF¶
no¶
For application/aif+json:¶
application¶
aif+json¶
N/A¶
Toid: the identifier for the object for which permissions are
supplied.
A value from the media-type parameter sub-registry for Toid.
Default value: "URI-local-part" (RFC XXXX).¶
Tperm: the data type of a permission set for the object
identified via a Toid.
A value from the media-type parameter sub-registry for Tperm.
Default value: "REST-method-set" (RFC XXXX).¶
binary (JSON is UTF-8-encoded text)¶
none¶
Applications that need to convey structured authorization data for identified resources, conveying sets of permissions.¶
The syntax and semantics of fragment identifiers is as specified for "application/json". (At publication of RFC XXXX, there is no fragment identification syntax defined for "application/json".)¶
ACE WG mailing list (ace@ietf.org), or IETF Applications and Real-Time Area (art@ietf.org)¶
COMMON¶
none¶
IETF¶
no¶
For the media types application/aif+cbor and application/aif+json,
IANA is requested to create a sub-registry within
[IANA.media-type-sub-parameters] for the two media-type parameters
Toid and Tperm, populated with:¶
| Parameter | name | Description/Specification | Reference |
|---|---|---|---|
| Toid | URI-local-part | local-part of URI | RFC XXXX |
| Tperm | REST-method-set | set of REST methods represented | RFC XXXX |
The registration policy is Specification required [RFC8126]. The designated expert will engage with the submitter to ascertain the requirements of this document are addressed:¶
Toid and Tperm need to realize the
general ideas of unambiguous object identifiers and permission lists
in the context where the AIF data item is intended to be used, and
their structure needs to be usable with the intended media types
(application/aif+cbor and application/aif+json) as identified in the
specification.¶
The designated experts will develop further criteria and guidelines as needed.¶
IANA is requested to register Content-Format numbers in the "CoAP Content-Formats" sub-registry, within the "Constrained RESTful Environments (CoRE) Parameters" Registry [IANA.core-parameters], as follows:¶
| Content-Type | Content Coding | ID | Reference |
|---|---|---|---|
| application/aif+cbor | - | TBD1 | RFC XXXX |
| application/aif+json | - | TBD2 | RFC XXXX |
// RFC Ed.: please replace TBD1 and TBD2 with assigned IDs and remove this note.¶
In the registry as defined by Section 12.3 of [RFC7252] at the time of writing, the column "Content-Type" is called "Media type" and the column "Content Coding" is called "Encoding".¶
Note that applications that register Toid and Tperm values are
encouraged to also register Content-Formats for the relevant
combinations.¶
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:¶
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.¶
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, which 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.¶