| Internet-Draft | ACE AIF | June 2020 |
| Bormann | Expires 30 December 2020 | [Page] |
Constrained Devices as they are used in the "Internet of Things" need security. 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, and need to ascertain that other devices they place requests on are the ones they intended.¶
To transfer detailed authorization information from an authorization manager (such as an ACE-OAuth Authorization Server) to a device, a representation format is needed. This document provides a suggestion for 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 refinement that describes REST resources and the permissions on them.¶
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 30 December 2020.¶
Copyright (c) 2020 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 Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License.¶
(See Abstract.)¶
This memo uses terms from [RFC7252] and [RFC4949].¶
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. These words may also appear in this document in lower case as plain English words, absent their normative meanings.¶
(Note that this document is itself informational, but it is discussing normative statements that MUST be put into concrete terms in each specification that makes use of this document.)¶
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).¶
For the purposes of this strawman, 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 do not concern the AIF format with the subject for which the AIF object is issued, focusing the AIF object on a single row in the access matrix (such a row traditionally is also called a capability list). 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 a such a capability list is a list of pairs of object identifiers and the permissions the subject has on the object(s) identified.¶
AIF-Generic<Toid, Tperm> = [* [Toid, Tperm]]
In a specific data model, 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 simply
use the URI of a resource on a CoAP server. More specifically, the
parts of the URI that identify the server ("authority" in
[RFC3986]) are considered the realm of the authentication mechanism
(which are handled in the cryptographic armor); we therefore focus on
the "path-absolute" 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
unambiguous who is the target (enforcement point) of these
authorizations.¶
For the permissions (Tperm), we simplify the model permissions to
giving the subset of the CoAP methods permitted. This model is
summarized in Table 1.¶
| local-part | Permission Set |
|---|---|
| /s/light | GET |
| /a/led | PUT, GET |
| /dtls | POST |
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], however, that requires some considerations of the ease and unambiguity of matching a given URI against a set of templates in an AIF object.¶
This simple information model also doesn't allow further conditionalizing access based on state outside the identification of objects (e.g., "opening a door is allowed if that isn't 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 that were specifically created for the subject by others.¶
The extended REST-specific model 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 result or using the Location header field in HTTP [RFC7231] (the Location-indicating mechanisms). (The concept is somewhat comparable to "ACL inheritance" in NFSv4 [rfc5661], 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.)¶
| 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 by a Location-indicating mechanism to a request that the
subject made to the resource listed (/a/make-coffee in the example,
which might return the location of a resource that allows GET to find
out about the status 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 extended model; 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 basic REST authorization. As discussed, the object identifier is specialized as a text string giving a relative URI (local-part as absolute path on the server serving as enforcement point). The permission set is specialized to a single number by the following steps:¶
This data model could be interchanged in the JSON [RFC8259] representation given in Figure 3.¶
[["/s/light", 1], ["/a/led", 5], ["/dtls", 2]]
In CDDL [RFC8610], 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:¶
AIF-REST = AIF-Generic<path, permissions> path = tstr ; URI relative to enforcement point permissions = 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 )
A representation of this information in CBOR [RFC7049] is given in Figure 5; again, several optimizations/improvements are possible.¶
83 # array(3)
82 # array(2)
68 # text(8)
2f732f6c69676874 # "/s/light"
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 "local-uri" for Toid and "REST-method-set" for Tperm.¶
[Insert lots of boilerplate here]¶
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).¶
IANA is requested to create a registry for AIF with two sub-registries for Toid and Tperm,
populated with:¶
| Subregistry | name | Description/Specification |
|---|---|---|
| Toid | local-part | local-part of URI as specified in [RFCthis] |
| Tperm | REST-method-set | set of REST methods represented as specified in [RFCthis] |
The registration policy is Specification required [RFC8126]. The designated expert will engage with the submitter to ascertain the requirements of this document are addressed.¶
IANA is requested to register Content-Format numbers in the CoRE Parameters Registry [IANA.core-parameters], as follows:¶
(TBD. Some issues are already discussed in the security considerations of [RFC7252] and in [RFC8576].)¶
Jim Schaad and Francesca Palombini provided comments that shaped the direction of this document.¶