An Authorization Information Format (AIF) for ACE

Status of This Memo

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 15 August 2021.¶

Copyright Notice

Copyright (c) 2021 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.¶

Table of Contents

1. Introduction

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 [I-D.ietf-ace-oauth-authz]) 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.¶

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).¶

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 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>

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 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:¶

• The entries in the table that specify the same 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 for Dynamic-DELETE).¶
• The set of numbers is converted into a single number by taking each number to the power of two 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/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 [RFC8949] 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].¶

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 "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).¶

5. IANA Considerations

6. Security Considerations

The security considerations of [RFC7252] apply. Some wider issues are discussed in [RFC8576].¶

When applying these formats, the referencing specification must be careful to:¶

• ensure that the cryptographic armor employed around this format fulfills the security objectives, and that the armor or some additional information included in it with the AIF information unambiguously identifies the subject to which the authorizations shall apply, and¶
• ensure that the types used for Toid and Tperm provide the appropriate granularity so that application requirements on the precision of the authorization information are fulfilled.¶

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

Acknowledgements

Jim Schaad and Francesca Palombini provided comments that shaped the direction of this document.¶

Author's Address