ACE Working Group L. Seitz Internet-Draft SICS Intended status: Standards Track G. Selander Expires: December 31, 2015 Ericsson M. Vucinic STMicroelectronics June 29, 2015 Authorization for Constrained RESTful Environments draft-seitz-ace-core-authz-00 Abstract This memo defines a framework for authorization in constrained-node networks, i.e. networks where some devices have severe constraints on memory, processing, power and communication bandwidth. The main goal is to offload constrained devices by providing them access control support from trusted parties that are less constrained. The approach is based on RESTful requests to dedicated access management resources, supporting different authorization schemes and communication security paradigms. 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 http://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 December 31, 2015. Copyright Notice Copyright (c) 2015 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 (http://trustee.ietf.org/license-info) in effect on the date of Seitz, et al. Expires December 31, 2015 [Page 1] Internet-Draft CoRE Authorization June 2015 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 . . . . . . . . . . . . . . . . . . . . . . . . 3 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3 2. Overview . . . . . . . . . . . . . . . . . . . . . . . . . . 4 2.1. Example A: Access to an Actuator . . . . . . . . . . . . 4 2.2. Example B: Multiple Devices Accessing Sensor Data . . . . 5 2.3. The Authentication and Authorization Problem . . . . . . 5 2.4. Solution Overview . . . . . . . . . . . . . . . . . . . . 6 3. Information Flows . . . . . . . . . . . . . . . . . . . . . . 7 3.1. Message Sequences . . . . . . . . . . . . . . . . . . . . 7 3.2. Access Management Resources . . . . . . . . . . . . . . . 9 4. Communication Security . . . . . . . . . . . . . . . . . . . 11 4.1. AS - RS . . . . . . . . . . . . . . . . . . . . . . . . . 12 4.2. AS - C . . . . . . . . . . . . . . . . . . . . . . . . . 13 4.3. C - RS . . . . . . . . . . . . . . . . . . . . . . . . . 13 4.4. Authorization Information transfer in the DTLS Handshake 13 5. Authorization Request Format . . . . . . . . . . . . . . . . 15 5.1. ARF Information Model . . . . . . . . . . . . . . . . . . 15 5.2. ARF Data Model . . . . . . . . . . . . . . . . . . . . . 15 6. Authorization Information Format . . . . . . . . . . . . . . 16 6.1. AIF Information Model . . . . . . . . . . . . . . . . . . 16 6.2. AIF Data Model . . . . . . . . . . . . . . . . . . . . . 17 7. Client Information Format . . . . . . . . . . . . . . . . . . 18 7.1. CIF for the Push scheme . . . . . . . . . . . . . . . . . 18 7.2. CIF for the Client-Pull scheme . . . . . . . . . . . . . 19 8. Message Processing . . . . . . . . . . . . . . . . . . . . . 20 8.1. Unauthorized Access Attempt . . . . . . . . . . . . . . . 20 8.2. Authorization Request . . . . . . . . . . . . . . . . . . 21 8.3. Receiving Authorization Information . . . . . . . . . . . 22 8.4. Receiving Client Information . . . . . . . . . . . . . . 23 8.5. Resource Request and Response . . . . . . . . . . . . . . 23 9. Security Considerations . . . . . . . . . . . . . . . . . . . 24 10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 24 11. Acknowledmgents . . . . . . . . . . . . . . . . . . . . . . . 24 12. References . . . . . . . . . . . . . . . . . . . . . . . . . 25 12.1. Normative References . . . . . . . . . . . . . . . . . . 25 12.2. Informative References . . . . . . . . . . . . . . . . . 25 Appendix A. Examples . . . . . . . . . . . . . . . . . . . . . . 26 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 28 Seitz, et al. Expires December 31, 2015 [Page 2] Internet-Draft CoRE Authorization June 2015 1. Introduction Authorization is the process of deciding what an entity ought to be allowed to do. Authorization management and processing access control policies in order to reach an authorization decision is often a heavyweight task, involving e.g. database lookups, credential verification and matching large sets of values against each other. Constrained devices are ill-equipped to handle this on their own, therefore the logical approach is to offload authorization management and part of the decision process to a less constrained, trusted third party. This memo describes an approach to authorization in constrained-node networks using dedicated resources for access management. The various entities in the architecture handle authorization information by making RESTful requests (GET/PUT/POST/DELETE) to these resources and thereby establish the necessary security contexts for interactions between endpoints. The approach is based on the use cases from [I-D.ietf-ace-usecases] and on the architecture and problem description from [I-D.gerdes-ace-actors]. It introduces protocols for requesting authorization information from a trusted third party, encodings for such authorization information and protocols for transferring it to the affected device(s). We assume that CoAP [RFC7252] is the preferred application-layer protocol and that constrained devices implementing these mechanisms can be as resource constrained as class 1 according to the definitions in [RFC7228]. An important goal in the design of this framework is to preserve end- to-end security in the presence of untrusted intermediate nodes in the communication of requests, responses and related authorization information. 1.1. Terminology The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC2119]. Certain security-related terms are to be understood in the sense defined in [RFC4949]. These terms include, but are not limited to, "authentication", "authorization", "confidentiality", "(data) integrity", "message authentication code", and "verify". RESTful terms including "resource", "representation", etc. are to be understood as used in HTTP [RFC7231] and CoAP [RFC7252]. Seitz, et al. Expires December 31, 2015 [Page 3] Internet-Draft CoRE Authorization June 2015 Terminology for constrained environments including "constrained device", "constrained-node network", "class 1", etc. is defined in [RFC7228]. Terminology for entities in the architecture is defined in [I-D.gerdes-ace-actors], such as the constrained nodes Client (C) and Resource Server (RS), and the less constrained nodes Client Authorization Server (CAS) and Authorization Server (AS). Since this draft focuses on the problem of access control to resources it is for simplicity assumed that the Client Authorization Server functionality is not stand-alone but subsumed by either the Authorization Server or the Client (see section 2.2 in [I-D.gerdes-ace-actors]). We use the term "authorization token" for authorization information that is protected with object security. 2. Overview This section contains an overview of the authentication and authorization problem and the solution described in this memo. We begin with two generic examples. 2.1. Example A: Access to an Actuator Consider an actuator, e.g. in an industrial control system. Set in the terms of the architecture [I-D.gerdes-ace-actors], the actuator is hosted in one endpoint, acting RS, and another endpoint, acting C, is requesting access to the actuation resource. Security requirements of special importance are: o RS needs to verify that the requesting Client is authorized to access the resource. o Integrity and replay protection of request. Assuming CoAP, integrity protection applies to Payload but also to other fields such as for example the CoAP option Uri-path. o C must be able to verify the integrity of the response, and that the received message is the response to the previously made request, in order for C to verify that the actuation was performed. o It must be possible to confidentiality protect the request and response, e.g. for privacy reasons. Seitz, et al. Expires December 31, 2015 [Page 4] Internet-Draft CoRE Authorization June 2015 2.2. Example B: Multiple Devices Accessing Sensor Data Consider a constrained sensor performing measurements consumed by multiple devices. Since the communication of a duty-cycled sensor with each consuming device would require energy expensive radio receptions and transmissions, it is favorable to minimize the number of devices that directly interact with the sensor. Therefore the sensor publishes (e.g. sends notifications with) measurements to a message broker, which forwards the measurements to subscribing devices. Access control is performed by only giving plaintext access to authorized subscribers. In the terminology of [I-D.gerdes-ace-actors] this means that the sensor acts RS and the subscribing devices are Clients. In this case, the RS may neither be able to verify integrity nor replay of individual client requests, nor authorize individual clients, since it isn't necessarily interacting directly with any clients. For the same reason the client is not able to match a publication against a request. The main relevant security requirements here are: o Access to plaintext publications must be restricted to authorized Clients. o A Client needs to verify the origin of the publication, and that it is not a replay of an old publication. 2.3. The Authentication and Authorization Problem Both examples in the previous subsections are encompassed by the problem statement described in [I-D.gerdes-ace-actors] but their security requirements are quite different. On a high level, the authentication and authorization problem can be broken down into three sub-problems: 1. The policy for resource access as defined by the Resource Owner (RO) and managed by the Authorization Server (AS) needs to be translated into authorization information following an Authorization Information Format (AIF) that the RS can parse and act upon. 2. Similarly, the Client may need to acquire keys/credentials or other information from the AS to securely access the resource. Such client information is encoded following a Client Information Format (CIF). Seitz, et al. Expires December 31, 2015 [Page 5] Internet-Draft CoRE Authorization June 2015 3. In order for Client and RS to authenticate and authorize according to policy, the communication of the various information elements needs to be protected appropriately end-to-end: from AS to C, from AS to RS, and between C and RS. To access an actuator, as in example A, the authorization information could be an authorization decision that C is granted access to a certain resource, or attributes of C that RS can match against internal access policies. The client information could be cryptographic keys which C could use to establish secure communication with RS. In the publish-subscribe scenario of example B, the authorization information (if present) could be cryptographic keys that must be used for protection of published resource representations. The client information could be cryptographic keys/credentials with which publications of certain resource representations can be verified and decrypted. Communication security could be addressed with a session security based protocol such as DTLS [RFC6347], or an object security solution based on e.g. COSE [I-D.schaad-cose-msg] (see Section 4). The other sub-problems listed in this section, AIF and CIF, are further detailed in Section 6 and Section 7, respectively. 2.4. Solution Overview Considering the large variety of use cases, it may be difficult to address the authentication and authorization problem with one single protocol instance. In this section we list some guiding principles for a solution. The remainder of the document provides solution components based on the principles listed in this section. In Section 8 the detailed processing steps are presented. In Appendix A examples of the proposed solution are given. PRINCIPLE 1: Allow different order of information flows The information flows, including AIF, CIF, and Resource Request/ Response (RRR) (Figure 1), may take place in different order see Section 3. Seitz, et al. Expires December 31, 2015 [Page 6] Internet-Draft CoRE Authorization June 2015 +---------------------------------+ | Authorization | | Server | +---------------------------------+ | | CIF AIF | | V V +--------+ +----------+ | Client |<--- RRR --->| Resource | | | | Server | +--------+ +----------+ Figure 1: Information flows PRINCIPLE 2: Build upon REST The information flows should leverage the RESTful architecture. For RRR this is already assumed, but RESTful administrative resources for managing access to e.g. AIF and CIF need to be defined. The support for REST should not preclude optimizations for particular protocols, for example some flows may be embedded within the DTLS handshake. PRINCIPLE 3: Allow security at different layers Leave to the application to decide about session based or object based security for any given information flow. 3. Information Flows This section gives an overview of information flows between the entities in the architecture, and the use of access management resources. 3.1. Message Sequences The information flows in scope between the nodes (constrained to constrained and constrained to less constrained) are described in [I-D.gerdes-ace-actors]. Taking [RFC2904] as a starting point, there are three authorization schemes, defining the message sequences for the flow of request, response, and authorization data: 1. In the Push scheme, C first obtains authorization information from AS and then transmits this data to RS together with its request, and finally RS sends its reply. In this model RS does not communicate with AS directly. Seitz, et al. Expires December 31, 2015 [Page 7] Internet-Draft CoRE Authorization June 2015 2. In the Pull scheme, C sends its request to RS directly, RS then contacts AS in order to obtain authorization information, AS provides authorization information, and finally RS sends back the reply. In this model C does not communicate with AS directly. 3. In the Agent scheme, C sends its request to AS, which evaluates C's access rights and, if authorized, executes the request on C's behalf, transmitting RS's response back to C. In this model C does not communicate with RS directly. Depending on use case, different schemes may be more appropriate than others. From a constrained-node network point of view we note the following: o The Push and Agent scheme requires C to connect to AS. o The Pull and Agent scheme requires RS to connect to AS. o The Pull scheme requires RS to handle two secure connections at the same time (RS - AS and RS - C) in order to perform the real time authorization check. Considering processing and memory requirements of RS, the Push scheme is more favorable than the Pull scheme. The Agent scheme assumes constant connectivity with both C and RS and is therefore not applicable to the constrained setting. However, the publish-subscribe case from Section 2.2 is not covered by any of the schemes so this memo defines a new scheme, called Client-Pull. 4. In the Client-Pull scheme, RS first provides unconditional access to a protected resource representation. C obtains this protected resource representation and then contacts AS to obtain authorization information (in this case cryptographic keys) for access and verification of the resource representation. In this model RS does not communicate with AS directly, and C does not communicate with RS directly. The Client-Pull scheme is only useful for GET access. However, it offloads the RS considerably, since the RS neither receives any requests from clients nor performs any access control verifications. Furthermore it enables use cases, such as caching and publish- subscribe, that can not be covered by the other schemes in a satisfactory manner. Seitz, et al. Expires December 31, 2015 [Page 8] Internet-Draft CoRE Authorization June 2015 3.2. Access Management Resources This section describes an approach for transferring authorization information between the various entities in the architecture by making RESTful requests to dedicated resources for access management. The structure or naming of such "access management resources" is left for a future version of this memo, and for simplicity we denote any such resource "/authorize". In this section we illustrate various message sequences for transferring authorization information by means of requesting access management resources. We assume, as in section 3.2 of [I-D.gerdes-ace-dcaf-authorize], that the need for transferring authorization information may be triggered by a request from C to RS to access a resource. Figure 2 shows C making an access request (GET /PUT/POST/DELETE) which cannot be granted by the RS because of missing authorization information. C RS | | | Request /resource | | ------------------------> | | <------------------------ | | Unauthorized | | | Figure 2: Access request unauthorized. Starting with the Pull scheme, if the RS can access the AS, then any missing authorization information could be requested on the fly, see Figure 3. The RS sends an authorization request in a specific Authorization Request Format (ARF) to the /authorize resource at the AS as detailed in Section 8 and receives authorization information in a specific Authorization Information Format (AIF) in the response. RS updates the stored authorization information based on the new information and executes the client's resource request accordingly. Note that C and RS need be mutually authenticated using pre- established credentials in this scheme. Seitz, et al. Expires December 31, 2015 [Page 9] Internet-Draft CoRE Authorization June 2015 C RS AS | | | | Request /resource | | | ------------------------> | | | | POST /authorize ARF | | | ------------------------> | | | <------------------------ | | | AIF | | | | | <------------------------ | | | Granted | | | | | Figure 3: Pull Scheme In use cases where the RS does not have connectivity with AS, or if the RS cannot handle two secure connections at the same time, the Push scheme provides an alternative, see Figure 4. C receives, in the negative response to its resource request, information about where to request the missing authorization information. In this case it is C that requests the resource /authorize at the AS and receives both authorization information, and client information in a specific Client Information Format (CIF). The latter will be used by C to establish communication security with RS. Next, C pushes the authorization information to the /authorize resource at the RS. RS updates the stored authorization information based on the new data and confirms the change, after which C can repeat the resource request to the RS with the new client information and authorization information in place. AS C RS | | | | | Request /resource | | | ------------------------> | | | <------------------------ | | | Unauthorized | | POST /authorize ARF | | | <------------------------ | | | ------------------------> | | | AIF, CIF | | | | | | | POST /authorize AIF | | | ------------------------> | | | <------------------------ | | | Changed | | | | | | Request /resource | | | ------------------------> | Seitz, et al. Expires December 31, 2015 [Page 10] Internet-Draft CoRE Authorization June 2015 | | <------------------------ | | | Granted | | | | Figure 4: Push Scheme Note that in case there is connectivity between RS and AS, but RS has not implemented the Pull scheme or cannot handle two secure connections at the same time, then AS could POST the authorization information to the /authorize resource of RS directly instead of using C as intermediary node. Also note that the authorization information needs to be integrity protected during the transport between AS and RS. This is because the client has access to it and would otherwise be able to change its permissions. How this is done is described in Section 4. Finally the Client-Pull scheme, which only requires C to request a Protected Resource Representation from the RS, and client information (e.g. cryptographic keys) from the AS. AS C RS | | | | | GET /resource | | | ------------------------> | | | <------------------------ | | | Protected Resource | | | Representation | | | | | POST /authorize ARF | | | <------------------------ | | | ------------------------> | | | CIF | | | | | Figure 5: Client-Pull Scheme Note that the order of the information flows is different for the different authorization schemes. The authorization scheme is defined at design time, so an RS would typically support one specific message sequence suitable for the particular application. 4. Communication Security In this section we address the third sub-problem of Section 2.3, the authentication and communication security problem, based on the assumptions made in [I-D.gerdes-ace-actors]: Seitz, et al. Expires December 31, 2015 [Page 11] Internet-Draft CoRE Authorization June 2015 o AS and RS are assumed to have established security contexts (keys, credentials, security protocols, parameters). How this was established is out of scope for this work. o AS is assumed to have a policy for how C is allowed to access the resources of RS, including information for how to authenticate C, such as a shared secret key, public key or other credential. o Both session based and object based security solutions shall be supported. Since CoAP is the default communication protocol, DTLS [RFC6347] is the default session based security protocol. DTLS MUST NOT be used with untrusted intermediary nodes. For object security in constrained environments, COSE [I-D.schaad-cose-msg] is the main candidate. OSCOAP [I-D.selander-ace-object-security] defines a profile of COSE, suitable for securing individual CoAP messages, and two Modes of operation: o Mode:PAYL for (CoAP) Payload confidentiality, integrity and replay protection. o Mode:COAP for additional protection of CoAP Headers (Code) and Options (Uri-Path, Uri-Query etc.) and for securing request- response pair. 4.1. AS - RS The main purpose of this communication is to provide authorization information from AS to RS. There are three communication patterns: 1. RS: POST /authorize to AS (ARF in request, AIF in response) 2. AS: POST /authorize to RS (AIF in request) 3. C: POST /authorize to AS (ARF in request, AIF in response) followed by C: POST /authorize to RS (AIF in request) Pattern 1. and 2. SHALL be protected by DTLS or COSE Mode:COAP, leveraging the pre-established security context. In pattern 3., since C is an untrusted intermediary node, the authorization information SHALL be protected end-to-end from AS to RS with COSE Mode:PAYL, leveraging the pre-established credentials. Pattern 2. with COSE Mode:COAP includes the case of POST via an intermediary untrusted Forward Proxy, which in particular could be the Client, if the Client supports Forward Proxy functionality. Seitz, et al. Expires December 31, 2015 [Page 12] Internet-Draft CoRE Authorization June 2015 In pattern 3. the use of transport layer security (DTLS) or CoAP message security (Mode:COAP) is optional, since Mode:PAYL protected authorization information is in itself a confidential, integrity and replay protected token. If the subsequent communication between C and RS is going to be protected by DTLS, then an OPTIONAL optimization of the message exchange is to replace "C: POST /authorize to RS (AIF in request)" with a transfer of the protected authorization in the DTLS Handshake, see Section 4.4. 4.2. AS - C The main purpose of this communication is to provide client information from the AS to the C. The communication pattern is: o C: POST /authorize to AS to (ARF in request, CIF in response) This pattern SHALL be protected by DTLS or COSE Mode:COAP, leveraging out of band established credentials. 4.3. C - RS This is the original resource request/response problem. Since there may be no pre-established keys between C and RS, it is the purpose of AIF and CIF to provide information for authentication and communication security. There are two communication patterns: 1. The Client makes a request (GET/PUT/POST/DELETE /resource) to RS and receives a response. 2. The Client makes a GET request to the RS, or a cache, or message broker and unconditionally receives a protected resource representation Pattern 1. SHALL be protected by DTLS or COSE Mode:COAP, leveraging the established keys or credentials in authorization information and client information. Pattern 2. SHALL be protected with COSE Mode:PAYL. 4.4. Authorization Information transfer in the DTLS Handshake In certain situations, a session security protocol like DTLS [RFC6347] can be used directly to send the authorization information to the RS and optimize the message exchange. The authorization information MAY be embedded in the DTLS handshake. In this case the authorization information SHOULD be transferred using the TLS supplemental data extension [RFC4680]. Seitz, et al. Expires December 31, 2015 [Page 13] Internet-Draft CoRE Authorization June 2015 Figure 6 illustrates this approach for a DTLS handshake. The messages marked with * are optional depending on the type of handshake. Client Resource Server ------ --------------- ClientHello (with extensions) -------> <------- HelloVerifyRequest ClientHello (with extensions) --------> ServerHello Certificate* ServerKeyExchange* CertificateRequest* <-------- ServerHelloDone SupplementalData (AIF) Certificate* ClientKeyExchange CertificateVerify* [ChangeCipherSpec] Finished --------> [ChangeCipherSpec] <-------- Finished Application Data <-------> Application Data Figure 6: Authorization information Transfer in Handshake The SupplementalDataType value SHOULD be set to 16386 (authz_data). The Resource Server MUST verify the validity of the received authorization information before accepting any application data from the client. The RS MUST verify that the authorization information transmitted in the SupplementalData message is bound to the same key as the one the Client used in the handshake (see Section 6 for the subject binding in the AIF). Note that this also enables AS-asserted authorization of the DTLS handshake. Seitz, et al. Expires December 31, 2015 [Page 14] Internet-Draft CoRE Authorization June 2015 5. Authorization Request Format Authorization requests are represented in the Authorization Request Format (ARF). They are produced either by the Client (Push, Client- Pull) or the RS (Pull) and consumed by the AS. The ARF allows to specify requests for several actions on several resources in a single message. 5.1. ARF Information Model The general information that needs to be contained in the ARF is the following: o The identifier of the subject of this authorization request (usually the Client). o The identifier of the host that provides the resources that are requested in this authorization request (CoAP option URI-host). Note that the ARF does not allow to specify more than one host. o The requested resources and actions on these resources. The resources can be represented by the "path-absolute" part of the URI (In CoAP this would be the Uri-Path options). 5.2. ARF Data Model For representing the ARF discussed in Section 5.1 the following steps are performed: o The subject identifier is encoded in a map that maps the type of the identifier to its value. The type could e.g. be a raw public key, or the key identifier of a secret key, or a X.509 distinguished name. o The host identifier is encoded as second parameter. o The third parameter is array of resource-actions tuples. The structure of the entries is specified as follows: * Requests that affect the same resource are merged into a single entry that specifies the union of the permitted actions. * The actions GET, POST, PUT, DELETE are represented as integer 0, 1, 2, and 3 respectively. Seitz, et al. Expires December 31, 2015 [Page 15] Internet-Draft CoRE Authorization June 2015 * 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 numbers. * Each entry is an array, containing the resource identifier, and the number representing the actions. This information can then be represented in CBOR [RFC7049] or JSON [RFC7159] as an array of the elements listed above. An example JSON representation of the ARF is given in Figure 7. [{"subjectKeyId":"someKeyId1"}, "rs.example.com", [["sensors/tempC",1], ["conf/sleepInterval", 5], ["conf/sleepDuration", 5]]] Figure 7: Example JSON representation of an access request 6. Authorization Information Format Addressing the first sub-problem of Section 2.3, this section defines an Authorization Information Format (AIF) for encoding authorization information. AIF instances are either consumed directly by an RS (Pull), or packaged into a COSE Mode:PAYL token and sent to the Client, who forwards the token to the RS (Push). This memo defines two different types of AIF that can be used by an AS: o One or more access control decisions, listing one or more tuples of actions and resources similar to a capability list. This is a simple super-set of the ARF. o Group memberships for the Client. This type of AIF is used in a configuration where the RS stores access control lists (ACLs) corresponding to a number of groups. The RS will resolve a specific group to a specific set of ACLs which are then applied to the request. 6.1. AIF Information Model The general information that needs to be contained in the AIF is the following: o The identifier of the subject of this authorization information (usually the Client) Seitz, et al. Expires December 31, 2015 [Page 16] Internet-Draft CoRE Authorization June 2015 o The identifier of the host that provides the resources for which this authorization information applies (CoAP option URI-host). Note that the AIF does not allow to specify more than one host. If the authorization information represents one or more group memberships, the only other information needed is the group names. If the authorization information represents access control decisions, the affected resources and the actions are needed. Authorization decisions can also MAY contain local conditions, that can only be evaluated by the RS at access time (e.g. "NotBefore='09:00', NotAfter='18:00'"). This memo does not define the format of these local conditions, as it is expected that these will be application specific. The RS MUST reject any authorization information that contains local conditions that it does not understand. 6.2. AIF Data Model For representing the AIF discussed in Section 6.1 the following steps are performed: o The subject identifier is encoded in a map that maps the type of the identifier to its value. The type could e.g. be a raw public key, or the key identifier of a secret key, or a X.509 distinguished name. Section 4.3 defines how this is used to bind the authorization information to a specific client. o The host identifier is encoded as second parameter. o The third parameter is either an array of access control decisions, or if group memberships are asserted, a map, mapping the key 'grp' to the array of group names. The structure of the entries in the access control decision array is the same as for the ARF, except that is may also contain local conditions represented as strings. o Each entry is an array, containing the resource identifier, the number representing the actions, and optionally the local conditions. This information can then be represented in CBOR [RFC7049] or JSON [RFC7159] as an array of the elements listed above. An example JSON representation of the AIF with access control decisions is given in Figure 8, while an example of the AIF containing group membership assertions is shown in Figure 9. Seitz, et al. Expires December 31, 2015 [Page 17] Internet-Draft CoRE Authorization June 2015 [{"SubjectKeyId":"someKeyId2"}, "rs.example.com", [["actuators/doorLock", 5, "not-before:'07:00';not-after:'18:00'"]]] Figure 8: Example JSON representation of access control decisions [{"SubjectPublicKey":"MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEJG4m93 ED8tPK2CpkhrrtKNx1vXDbml4Fun1628Qkl1U_aIB5zUfqPwaacznbqoMJ6vQVZ7 4X9HpfynouLK_ujw"}, "rs.example.com", {"grp":["admin","user"]}] Figure 9: Example JSON representation of group memberships Note that different subject identifiers might be used in instances of the ARF and the AIF in the same Push scheme. This is due to the fact that the credential the Client uses towards the AS may not be the same as the one later used towards the RS. 7. Client Information Format This section addresses the second sub-problem of Section 2.3, and describes a format for client information. Two types of client information are defined in this section: 1. Client Information related to the Push scheme, which encodes keys and related parameters, that allow the Client to communicate securely with the RS and prove that it is the legitimate subject of some authorization information. 2. Client Information related to the Client-Pull scheme represent keys and related parameters that allow the Client to access and verify a resource representation protected with object security. For the Push scheme, the CIF must be able to encode instructions to the Client on how secure the connection between Client and RS, and how to transfer the authorization information to the RS. 7.1. CIF for the Push scheme The encoding of the client information in a Push scheme is an array with the following elements: 1. The type of this client information, here the string 'push'. 2. The method to be used for securing the transfer. Either the string 'coaps' (for CoAP over DTLS) or the string 'oscoap' (for CoAP with object security). Seitz, et al. Expires December 31, 2015 [Page 18] Internet-Draft CoRE Authorization June 2015 3. The method of transferring the authorization information. Either the string 'suppl' (for supplemental data) or the URI of the resource on the RS to which the authorization information should be transferred. 4. The type of key to be used for coaps of oscoap. This can either be a raw public key denoted by the string 'rpk', or a pre-shared key denoted by the string 'psk'. 5. If the key type was 'psk', then the next element is the identifier of this key. If the key type was 'rpk' this element is the raw public key of the RS. The encoding here should follow the SubjectPublicKeyInfo defined in RFC 7250 [RFC7250]. 6. If the key type was 'psk', then the next element is the pre- shared key that the Client should use either for DTLS or object security. The encoding of this key depends on the representation format. For CBOR it is raw bytes, for JSON it is Base64 encoded bytes. Figure Figure 10 shows an example representation of the CIF for a Push scheme, using JSON. ["push", "oscoap", "/authorize", "psk", "someKeyId", "Z4LXBNbOeeOJOYglBLb4pg"] Figure 10: CIF example for the Push scheme 7.2. CIF for the Client-Pull scheme The encoding of the CIF for a Client-Pull scheme is an array with the following elements: 1. The type of this client information, here the string 'cpull'. 2. The public key of the RS used to sign the resource representation. The encoding here should follow the SubjectPublicKeyInfo defined in RFC 7250 [RFC7250]. 3. The secret key used to encrypt the resource representation. The encoding of this key depends on the representation format. For CBOR it is raw bytes, for JSON it is Base64 encoded bytes. Note that further parameters are provided in the secure object itself, such as e.g. algorithm identifiers and initialization vectors. Seitz, et al. Expires December 31, 2015 [Page 19] Internet-Draft CoRE Authorization June 2015 Figure Figure 11 shows an example representation of the CIF for a Client-Pull scheme, using JSON. ["cpull", "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEJG4m93 ED8tPK2CpkhrrtKNx1vXDbml4Fun1628Qkl1U_aIB5zUfqPwaaczn bqoMJ6vQVZ74X9HpfynouLK_ujw", "eyJhbGciOiJIUzI1NiIsIm"] Figure 11: CIF example for the Client-Pull scheme 8. Message Processing This section puts together the pieces from previous sections and specifies more in detail the processing steps for the authorization schemes defined in Section 3. 8.1. Unauthorized Access Attempt All schemes can start with the Client requesting access at the RS without any established authorization information. Depending on which authorization scheme (Push, Pull, Client Pull) the RS has implemented, the RS can either: o Query the AS using the Pull scheme. o Instruct the Client to use the Push scheme. o In case the Client-Pull scheme, provide an encrypted representation of the resource that was requested, without performing any access control. If the RS wants the Client to use the Push scheme, the RS MUST respond with an error message using the response code 4.01 (Unauthorized). The error message MUST contain information that allows the Client to locate the AS responsible for the requested resource, and other information needed to make an Authorization Request. For example: 4.01 Unauthorized Content-Format: application/json ["oscoap", "as.example.com/authorize"] The response payload MAY be protected, e.g. signed with the private key of RS, using COSE Mode:PAYL. The response MAY include authentication information of AS, such as the (hash of the) public key of AS. The public key of RS or AS be retrieved in different ways e.g. from a Resource Directory Seitz, et al. Expires December 31, 2015 [Page 20] Internet-Draft CoRE Authorization June 2015 The initial exchange described in this section may be omitted, and the client can start with the Authorization Request to AS as described in Section 8.2 if the Client has obtained information about the relevant AS in some other way, e.g. using a Resource Directory. If the RS has access to authorization information about the Client, but it does not apply to the requested resource, the RS MUST answer with an error message using the response code 4.03 (Forbidden). If the RS has authorization information for the Client that applies to the requested resource, but that does not cover the requested action, the RS MUST reply with an error message using the response code 4.05 (Method Not Allowed). 8.2. Authorization Request Either the Client (Push scheme) or the RS (Pull scheme) can POST an request to the /authorize resource at the AS, specifying the Client's request(s) for authorization using the ARF defined in Section 5. Upon receiving a POST request to /authorize, the AS MUST perform the following steps: o Ensure that the request was received over a secure channel (DTLS) or uses object security. If object security was used the AS MUST perform the necessary verifications. o Ensure that the requesting party is authenticated. This is either the Client (as described in Section 4.2) or the RS (as described in Section 4.1). For DTLS this is supposed to have happened during the handshake, for object security this is accomplished by a signature or MAC over the request, produced by the requesting party. o Control that the requesting party is authorized to submit this kind of authorization request If the integrity verification fails, the AS MUST respond with an error message using the response code 4.00 (Bad Request) If the requesting party is not correctly authenticated, the AS MUST respond with an error message using the response code 4.01 (Unauthorized). If the requesting party is not authorized to perform this request for authorization information, the AS MUST respond with an error message using the response code 4.03 (Forbidden). Seitz, et al. Expires December 31, 2015 [Page 21] Internet-Draft CoRE Authorization June 2015 If the evaluation is successful the AS MUST respond with a 2.05 (Content) message code. The response can contain one of the following payloads: o If any part of the access requested by the Client was not authorized, the payload MUST be empty. o If all parts of the access requested by the Client were authorized, the payload MUST be either in AIF, CIF or both, depending on the authorization scheme: 1. If the Authorization Scheme is Pull, then the payload MUST be in AIF, as defined in Section 6. 2. If the Authorization Scheme is Client-Pull, then the payload MUST be in CIF as defined in Section 7. 3. If the Authorization Scheme is Push, then the payload MUST be an array containing first CIF, then AIF, as defined in Section 7 and Section 6 respectively. 8.3. Receiving Authorization Information The RS may receive authorization information in a response to a POST to an Authorization Request as described in the previous section. As an alternative this section describes how to push this information to the RS. This is done with a POST of the authorization information to the /authorize resource on the RS. This request may come from the Client in the Pull scheme, as defined in Pattern 3 in Section 4.1. The request may also come from the AS directly. Figure 12 illustrates the successful execution of such a request. C/AS RS | | | POST /authorize AIF | | ------------------------> | | <------------------------ | | 2.01 Created | | | Figure 12: POST AIF to /authorize A third OPTIONAL method is to include the authorization information in a DTLS handshake as supplemental data, as described in Section 4.4. Seitz, et al. Expires December 31, 2015 [Page 22] Internet-Draft CoRE Authorization June 2015 Irrespective of how the authorization information is received by the AS, upon receiving it, RS MUST verify that it is valid, by doing the following: o Check that the authorization information comes from a trusted AS o Check that the host in the authorization information corresponds to itself o Check that the authorization information is not expired or revoked, if the object security encapsulation allows this o Verify the integrity of the authorization information If the validation succeeds, RS MUST store the authorization information and use it to determine the authorization of future requests. If the authorization information is invalid, RS MUST respond with an error message using the error code 4.03 (Forbidden). 8.4. Receiving Client Information The Client receives client information in a response to a POST of an authorization request to an AS as described in Section 8.2. The Client MUST make sure that it is communicating with a trusted AS. If the communication is protected with COSE Mode:COAP, the Client MUST verify the authenticity and integrity of the client information, before using it. 8.5. Resource Request and Response The final resource request is handled differently based on which authorization scheme is implemented. In the Pull scheme this is an unauthorized request as described in Section 8.1. For resources configured to use the Client-Pull scheme for GET access, the RS MUST unconditionally provide an encrypted and signed representation of the requested resource to any requesting Client. In the Push scheme the RS MUST perform the following steps: o If the communication is secured with DTLS, verify that the handshake included client authentication. If the communication is protected with Mode:COAP, verify the object security of the request. o Verify the present authorization information to see if it has data that matches the Client, the requested resource, and the actions Seitz, et al. Expires December 31, 2015 [Page 23] Internet-Draft CoRE Authorization June 2015 requested on that resource. Note specifically that the binding between the authorization information and the Client is provided either by comparing with the keys used in the DTLS handshake, or with the keys used for object security of the request. o If some matching authorization information contains local conditions, verify that these are fulfilled. If any of these verifications fail, the RS treat the request as specified in Section 8.1. If all of these verifications succeed, the RS MUST process the request as required by the underlying application. If the request was protected with Mode:COAP, the RS MUST follow the response protecting scheme for this mode. 9. Security Considerations The entire document is about security. Security considerations applicable to authentication and authorization in RESTful environments provided in OAuth 2.0 [RFC6749] apply to this work, as well as the security considerations from [I-D.gerdes-ace-actors]. 10. IANA Considerations This document has no actions for IANA yet. 11. Acknowledmgents Some of the ideas of this document were originally described in a now expired Internet Draft: draft-selander-core-access-control-01. The authors would also like to thank Carsten Bormann, Stefanie Gerdes and Olaf Bergmann for the inspiration drawn from draft-bormann-core-ace- aif [I-D.bormann-core-ace-aif] and [I-D.gerdes-ace-dcaf-authorize]. This work has further drawn inspriation from [OSCAR] which presents another scheme for securing resource request and response using object security and where access key transport is performed by means of RESTful requests to dedicated resources. Seitz, et al. Expires December 31, 2015 [Page 24] Internet-Draft CoRE Authorization June 2015 12. References 12.1. Normative References [I-D.schaad-cose-msg] Schaad, J., "CBOR Encoded Message Syntax", draft-schaad- cose-msg-00 (work in progress), June 2015. [I-D.selander-ace-object-security] Selander, G., Mattsson, J., and L. Seitz, "March 9, 2015", draft-selander-ace-object-security-01 (work in progress), March 2015. [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997. [RFC4680] Santesson, S., "TLS Handshake Message for Supplemental Data", RFC 4680, October 2006. [RFC6347] Rescorla, E. and N. Modadugu, "Datagram Transport Layer Security Version 1.2", RFC 6347, January 2012. [RFC7250] Wouters, P., Tschofenig, H., Gilmore, J., Weiler, S., and T. Kivinen, "Using Raw Public Keys in Transport Layer Security (TLS) and Datagram Transport Layer Security (DTLS)", RFC 7250, June 2014. [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained Application Protocol (CoAP)", RFC 7252, June 2014. 12.2. Informative References [I-D.bormann-core-ace-aif] Bormann, C., "An Authorization Information Format (AIF) for ACE", draft-bormann-core-ace-aif-02 (work in progress), March 2015. [I-D.gerdes-ace-actors] Gerdes, S., Seitz, L., Selander, G., and C. Bormann, "An architecture for authorization in constrained environments", draft-gerdes-ace-actors-05 (work in progress), April 2015. [I-D.gerdes-ace-dcaf-authorize] Gerdes, S., Bergmann, O., and C. Bormann, "Delegated CoAP Authentication and Authorization Framework (DCAF)", draft- gerdes-ace-dcaf-authorize-02 (work in progress), March 2015. Seitz, et al. Expires December 31, 2015 [Page 25] Internet-Draft CoRE Authorization June 2015 [I-D.ietf-ace-usecases] Seitz, L., Gerdes, S., Selander, G., Mani, M., and S. Kumar, "ACE use cases", draft-ietf-ace-usecases-04 (work in progress), June 2015. [OSCAR] Vucinic, M., Tourancheau, B., Rousseau, F., Duda, A., Damon, L., and R. Guizzetti, "OSCAR: Object security architecture for the Internet of Things", Ad Hoc Networks Vol. 32, September 2015. [RFC2904] Vollbrecht, J., Calhoun, P., Farrell, S., Gommans, L., Gross, G., de Bruijn, B., de Laat, C., Holdrege, M., and D. Spence, "AAA Authorization Framework", RFC 2904, August 2000. [RFC4949] Shirey, R., "Internet Security Glossary, Version 2", RFC 4949, August 2007. [RFC6749] Hardt, D., "The OAuth 2.0 Authorization Framework", RFC 6749, October 2012. [RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object Representation (CBOR)", RFC 7049, October 2013. [RFC7159] Bray, T., "The JavaScript Object Notation (JSON) Data Interchange Format", RFC 7159, March 2014. [RFC7228] Bormann, C., Ersue, M., and A. Keranen, "Terminology for Constrained-Node Networks", RFC 7228, May 2014. [RFC7231] Fielding, R. and J. Reschke, "Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content", RFC 7231, June 2014. Appendix A. Examples The following examples show an overview the different authorization schemes presented in Section 3. The notation is as follows: A -> B : POST {blah} (request) \__ __/ \_ _/ \__ __/ \___ ___/ V V V V Communication RESTful Payload Type of partners and method payload direction of communication Messages protected with COSE Mode:COAP are denoted by adding 'CoseC(Key)', where 'Key' is the key used to protect the message. Seitz, et al. Expires December 31, 2015 [Page 26] Internet-Draft CoRE Authorization June 2015 Payload protected with COSE Mode:PAYL is denoted by 'CoseP(Key){payload}', where 'Key' is the key used to protect the payload. Note that we use POST to request authorization information instead of GET, since with the latter, the request would need to be transported in CoAP options (e.g. Uri-Query), and it could potentially become larger than the maximum CoAP packet size. Since CoAP options can not be fragmented this would be extremely problematic. Example A (using the Push scheme) 1. C -> RS : GET /sensors/tempC {} (request) 2. RS -> C : 4.01 Unauthorized {"oscoap", "as.example.com/ authorize"} (response) 3. C -> AS : POST /authorize CoseC(Key_C-AS) { [{"subjectKeyId ":"Key_C-AS"}, "rs.example.com", [['sensors/tempC', 1(= GET)]]] } (ARF) 4. AS -> C : 2.05 CoseC(Key_C-AS) { ["push", "oscoap", "/authorize", "psk", "someKeyId", "Z4LXBNbOeeOJOYglBLb4pg"], CoseP(Key_AS-RS){ [{"SubjectKeyId":"someKeyId"}, "rs.example.com", [["sensors/ tempC", 1(= GET)]]] } } (CIF, AIF) 5. C -> RS : POST /authorize CoseC(someKeyId) { CoseP(Key_AS- RS){[{"SubjectKeyId":"someKeyId"}, "rs.example.com", [["sensors/ tempC", 1(= GET)]]]} } (AIF) 6. C -> RS : GET /sensors/tempC CoseC(someKeyId) {} (request) 7. RS -> C : 2.05 CoseC(someKeyId) {37.5} (response) Example B (using the Pull scheme) 1. C -> RS : POST /actuators/doorLock CoseC(someClientKey) {open} (request) 2. RS -(DTLS)-> AS : POST /authorize { [{"subjectKeyId":"someClientKey"}, "rs.example.com", [['actuators /doorLock', 2(= POST)]]] } (ARF) 3. AS -(DTLS)-> RS : 2.05 { [{"subjectKeyId":"someClientKey"}, "rs.example.com", [['actuators/doorLock', 2(= POST)]]] } (AIF) 4. RS -> C : 2.04 (response) Seitz, et al. Expires December 31, 2015 [Page 27] Internet-Draft CoRE Authorization June 2015 Example C (using the Client-Pull scheme) 1. C -> RS : GET /sensors/tempC {} (request) 2. RS -> C : 2.05 { CoseP(someKey){39.2} } (response) 3. C -> AS : POST /authorize CoseC(Key_C-AS) { [{"subjectKeyId ":"Key_C-AS"}, "rs.example.com", [['sensors/tempC', 1(= GET)]]] } (ARF) 4. AS -> C : 2.05 CoseC(Key_C-AS) { ["cpull", "RS_PublicKey", "someKey] } (CIF) The authorizon schemes defining these flows are introduced in Section 3, and detailed in Section 8. The message structures for ARF, AIF and CIF are introduced in Section 5, Section 6, and Section 7. Authors' Addresses Ludwig Seitz SICS Scheelevaegen 17 Lund 223 70 SWEDEN Email: ludwig@sics.se Goeran Selander Ericsson Faroegatan 6 Kista 164 80 SWEDEN Email: goran.selander@ericsson.com Malisa Vucinic STMicroelectronics 850 Rue Jean Monnet Crolles 38920 FRANCE Email: malisa.vucinic@st.com Seitz, et al. Expires December 31, 2015 [Page 28]