idnits 2.17.1 draft-ietf-ace-oauth-authz-01.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (February 25, 2016) is 2982 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Missing Reference: 'RFC2046' is mentioned on line 1575, but not defined == Outdated reference: A later version (-09) exists of draft-bormann-core-ace-aif-03 ** Downref: Normative reference to an Informational draft: draft-bormann-core-ace-aif (ref. 'I-D.bormann-core-ace-aif') == Outdated reference: A later version (-24) exists of draft-ietf-cose-msg-10 == Outdated reference: A later version (-08) exists of draft-ietf-oauth-pop-architecture-07 ** Downref: Normative reference to an Informational draft: draft-ietf-oauth-pop-architecture (ref. 'I-D.ietf-oauth-pop-architecture') == Outdated reference: A later version (-07) exists of draft-ietf-oauth-pop-key-distribution-02 == Outdated reference: A later version (-06) exists of draft-selander-ace-object-security-03 ** Downref: Normative reference to an Informational draft: draft-wahlstroem-ace-cbor-web-token (ref. 'I-D.wahlstroem-ace-cbor-web-token') ** Downref: Normative reference to an Informational draft: draft-wahlstroem-ace-oauth-introspection (ref. 'I-D.wahlstroem-ace-oauth-introspection') ** Obsolete normative reference: RFC 6347 (Obsoleted by RFC 9147) == Outdated reference: A later version (-07) exists of draft-ietf-ace-actors-02 == Outdated reference: A later version (-21) exists of draft-ietf-core-block-18 == Outdated reference: A later version (-02) exists of draft-somaraju-ace-multicast-01 -- Obsolete informational reference (is this intentional?): RFC 5246 (Obsoleted by RFC 8446) -- Obsolete informational reference (is this intentional?): RFC 7049 (Obsoleted by RFC 8949) -- Obsolete informational reference (is this intentional?): RFC 7159 (Obsoleted by RFC 8259) -- Obsolete informational reference (is this intentional?): RFC 7231 (Obsoleted by RFC 9110) Summary: 5 errors (**), 0 flaws (~~), 10 warnings (==), 5 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 ACE Working Group L. Seitz 3 Internet-Draft SICS 4 Intended status: Standards Track G. Selander 5 Expires: August 28, 2016 Ericsson 6 E. Wahlstroem 7 S. Erdtman 8 Nexus Technology 9 H. Tschofenig 10 ARM Ltd. 11 February 25, 2016 13 Authorization for the Internet of Things using OAuth 2.0 14 draft-ietf-ace-oauth-authz-01 16 Abstract 18 This memo defines how to use OAuth 2.0 as an authorization framework 19 with Internet of Things (IoT) deployments, thus bringing a well-known 20 and widely used security solution to IoT devices. Where possible 21 vanilla OAuth 2.0 is used, but where the limitations of IoT devices 22 require it, profiles and extensions are provided. 24 Status of This Memo 26 This Internet-Draft is submitted in full conformance with the 27 provisions of BCP 78 and BCP 79. 29 Internet-Drafts are working documents of the Internet Engineering 30 Task Force (IETF). Note that other groups may also distribute 31 working documents as Internet-Drafts. The list of current Internet- 32 Drafts is at http://datatracker.ietf.org/drafts/current/. 34 Internet-Drafts are draft documents valid for a maximum of six months 35 and may be updated, replaced, or obsoleted by other documents at any 36 time. It is inappropriate to use Internet-Drafts as reference 37 material or to cite them other than as "work in progress." 39 This Internet-Draft will expire on August 28, 2016. 41 Copyright Notice 43 Copyright (c) 2016 IETF Trust and the persons identified as the 44 document authors. All rights reserved. 46 This document is subject to BCP 78 and the IETF Trust's Legal 47 Provisions Relating to IETF Documents 48 (http://trustee.ietf.org/license-info) in effect on the date of 49 publication of this document. Please review these documents 50 carefully, as they describe your rights and restrictions with respect 51 to this document. Code Components extracted from this document must 52 include Simplified BSD License text as described in Section 4.e of 53 the Trust Legal Provisions and are provided without warranty as 54 described in the Simplified BSD License. 56 Table of Contents 58 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 59 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 4 60 3. Overview . . . . . . . . . . . . . . . . . . . . . . . . . . 4 61 3.1. OAuth 2.0 . . . . . . . . . . . . . . . . . . . . . . . . 5 62 3.2. CoAP . . . . . . . . . . . . . . . . . . . . . . . . . . 7 63 3.3. Object Security . . . . . . . . . . . . . . . . . . . . . 8 64 4. Protocol Interactions . . . . . . . . . . . . . . . . . . . . 9 65 5. OAuth 2.0 Profiling . . . . . . . . . . . . . . . . . . . . . 12 66 5.1. Client Information . . . . . . . . . . . . . . . . . . . 12 67 5.2. CoAP Access-Token Option . . . . . . . . . . . . . . . . 15 68 5.3. Authorization Information Resource at the Resource Server 15 69 5.3.1. Authorization Information Request . . . . . . . . . . 16 70 5.3.2. Authorization Information Response . . . . . . . . . 16 71 5.3.2.1. Success Response . . . . . . . . . . . . . . . . 16 72 5.3.2.2. Error Response . . . . . . . . . . . . . . . . . 16 73 5.4. Authorization Information Format . . . . . . . . . . . . 17 74 5.5. CBOR Data Formats . . . . . . . . . . . . . . . . . . . . 17 75 5.6. Token Expiration . . . . . . . . . . . . . . . . . . . . 17 76 6. Deployment Scenarios . . . . . . . . . . . . . . . . . . . . 18 77 6.1. Client and Resource Server are Offline . . . . . . . . . 19 78 6.2. Resource Server Offline . . . . . . . . . . . . . . . . . 22 79 6.3. Token Introspection with an Offline Client . . . . . . . 26 80 6.4. Always-On Connectivity . . . . . . . . . . . . . . . . . 30 81 6.5. Token-less Authorization . . . . . . . . . . . . . . . . 31 82 6.6. Securing Group Communication . . . . . . . . . . . . . . 34 83 7. Security Considerations . . . . . . . . . . . . . . . . . . . 35 84 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 35 85 8.1. CoAP Option Number Registration . . . . . . . . . . . . . 35 86 9. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 36 87 10. References . . . . . . . . . . . . . . . . . . . . . . . . . 36 88 10.1. Normative References . . . . . . . . . . . . . . . . . . 36 89 10.2. Informative References . . . . . . . . . . . . . . . . . 38 90 Appendix A. Design Justification . . . . . . . . . . . . . . . . 40 91 Appendix B. Roles and Responsibilites -- a Checklist . . . 41 92 Appendix C. Optimizations . . . . . . . . . . . . . . . . . . . 44 93 Appendix D. CoAP and CBOR profiles for OAuth 2.0 . . . . . . . . 45 94 D.1. Profile for Token resource . . . . . . . . . . . . . . . 45 95 D.1.1. Token Request . . . . . . . . . . . . . . . . . . . . 46 96 D.1.2. Token Response . . . . . . . . . . . . . . . . . . . 47 98 D.2. CoAP Profile for OAuth Introspection . . . . . . . . . . 48 99 D.2.1. Introspection Request . . . . . . . . . . . . . . . . 48 100 D.2.2. Introspection Response . . . . . . . . . . . . . . . 49 101 Appendix E. Document Updates . . . . . . . . . . . . . . . . . . 51 102 E.1. Version -00 to -01 . . . . . . . . . . . . . . . . . . . 51 103 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 52 105 1. Introduction 107 Authorization is the process for granting approval to an entity to 108 access a resource [RFC4949]. Managing authorization information for 109 a large number of devices and users is often a complex task where 110 dedicated servers are used. 112 Managing authorization of users, services and their devices with the 113 help of dedicated authorization servers (AS) is a common task, found 114 in enterprise networks as well as on the Web. In its simplest form 115 the authorization task can be described as granting access to a 116 requesting client, for a resource hosted on a device, the resource 117 server (RS). This exchange is mediated by one or multiple 118 authorization servers. 120 We envision that end consumers and enterprises will want to manage 121 access-control and authorization for their Internet of Things (IoT) 122 devices in the same style and this desire will increase with the 123 number of exposed services and capabilities provided by applications 124 hosted on the IoT devices. The IoT devices may be constrained in 125 various ways including processing, memory, code-size, energy, etc., 126 as defined in [RFC7228], and the different IoT deployments present a 127 continuous range of device and network capabilities. Taking energy 128 consumption as an example: At one end there are energy-harvesting or 129 battery powered devices which have a tight power budget, on the other 130 end there are devices connected to a continuous power supply which 131 are not constrained in terms of power, and all levels in between. 132 Thus IoT devices are very different in terms of available processing 133 and message exchange capabilities. 135 This memo describes how to re-use OAuth 2.0 [RFC6749] to extend 136 authorization to Internet of Things devices with different kinds of 137 constraints. At the time of writing, OAuth 2.0 is already used with 138 certain types of IoT devices and this document will provide 139 implementers additional guidance for using it in a secure and 140 privacy-friendly way. Where possible the basic OAuth 2.0 mechanisms 141 are used; in some circumstances profiles are defined, for example to 142 support smaller the over-the-wire message size and smaller code size. 144 2. Terminology 146 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 147 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 148 document are to be interpreted as described in [RFC2119]. 150 Certain security-related terms such as "authentication", 151 "authorization", "confidentiality", "(data) integrity", "message 152 authentication code", and "verify" are taken from [RFC4949]. 154 Since we describe exchanges as RESTful protocol interactions HTTP 155 [RFC7231] offers useful terminology. 157 Terminology for entities in the architecture is defined in OAuth 2.0 158 [RFC6749] and [I-D.ietf-ace-actors], such as client (C), resource 159 server (RS), and authorization server (AS). OAuth 2.0 uses the term 160 "endpoint" to denote HTTP resources such as /token and /authorize at 161 the AS, but we will use the term "resource" in this memo to avoid 162 confusion with the CoAP [RFC7252] term "endpoint". 164 Since this draft focuses on the problem of access control to 165 resources, we simplify the actors by assuming that the client 166 authorization server (CAS) functionality is not stand-alone but 167 subsumed by either the authorization server or the client (see 168 section 2.2 in [I-D.ietf-ace-actors]). 170 3. Overview 172 This specification describes a framework for authorization in the 173 Internet of Things consisting of a set of building blocks. 175 The basic block is the OAuth 2.0 [RFC6749] framework, which enjoys 176 widespread deployment. Many IoT devices can support OAuth 2.0 177 without any additional extensions, but for certain constrained 178 settings additional profiling is needed. 180 Another building block is the lightweight web transfer protocol CoAP 181 [RFC7252] for those communication environments where HTTP is not 182 appropriate. CoAP typically runs on top of UDP which further reduces 183 overhead and message exchanges. Transport layer security can be 184 provided either by DTLS 1.2 [RFC6347] or TLS 1.2 [RFC5246]. 186 A third building block is CBOR [RFC7049] for encodings where JSON 187 [RFC7159] is not sufficiently compact. CBOR is a binary encoding 188 designed for extremely small code size and fairly small message size. 189 OAuth 2.0 allows access tokens to use different encodings and this 190 document defines such an alternative encoding. The COSE message 191 format [I-D.ietf-cose-msg] is also based on CBOR. 193 A fourth building block is application layer security, which is used 194 where transport layer security is insufficient. At the time of 195 writing the preferred approach for securing CoAP at the application 196 layer is via the use of COSE [I-D.ietf-cose-msg], which adds object 197 security to CBOR-encoded data. More details about applying COSE to 198 CoAP can be found in OSCOAP [I-D.selander-ace-object-security]. 200 With the building blocks listed above, solutions satisfying various 201 IoT device and network constraints are possible. A list of 202 constraints is described in detail in RFC 7228 [RFC7228] and a 203 description of how the building blocks mentioned above relate to the 204 various constraints can be found in Appendix A. 206 Luckily, not every IoT device suffers from all constraints. The 207 described framework nevertheless takes all these aspects into account 208 and allows several different deployment variants to co-exist rather 209 than mandating a one-size-fits-all solution. We believe this is 210 important to cover the wide range of possible interworking use cases 211 and the different requirements from a security point of view. Once 212 IoT deployments mature, popular deployment variants will be 213 documented in form of profiles. 215 In the subsections below we provide further details about the 216 different building blocks. 218 3.1. OAuth 2.0 220 The OAuth 2.0 authorization framework enables a client to obtain 221 limited access to a resource with the permission of a resource owner. 222 Authorization related information is passed between the nodes using 223 access tokens. These access tokens are issued to clients by an 224 authorization server with the approval of the resource owner. The 225 client uses the access token to access the protected resources hosted 226 by the resource server. 228 A number of OAuth 2.0 terms are used within this memo: 230 Access Tokens: 232 Access tokens are credentials used to access protected resources. 233 An access token is a data structure representing authorization 234 permissions issued to the client. Access tokens are generated by 235 the authorization server and consumed by the resource server. The 236 access token is opaque to the client. 238 Access tokens can have different formats, and various methods of 239 utilization (e.g., cryptographic properties) based on the security 240 requirements of the given deployment. 242 Proof of Possession Tokens: 244 An access token may be bound to a cryptographic key, which is then 245 used by an RS to authenticate requests from a client. Such tokens 246 are called proof-of-possession tokens (or PoP tokens) 247 [I-D.ietf-oauth-pop-architecture]. 249 The proof-of-possession (PoP) security concept assumes that the AS 250 acts as a trusted third party that binds keys to access tokens. 251 These so called PoP keys are then used by the client to 252 demonstrate the possession of the secret to the RS when accessing 253 the resource. The RS, when receiving an access token, needs to 254 verify that the key used by the client matches the one included in 255 the access token. When this memo uses the term "access token" it 256 is assumed to be a PoP token unless specifically stated otherwise. 258 The key bound to the access token (aka PoP key) may be based on 259 symmetric as well as on asymmetric cryptography. The appropriate 260 choice of security depends on the constraints of the IoT devices 261 as well as on the security requirements of the use case. 263 Symmetric PoP key: 265 The AS generates a random symmetric PoP key, encrypts it for 266 the RS and includes it inside an access token. The PoP key is 267 also encrypted for the client and sent together with the access 268 token to the client. 270 Asymmetric PoP key: 272 An asymmetric key pair is generated on the client and the 273 public key is sent to the AS (if it does not already have 274 knowledge of the client's public key). Information about the 275 public key, which is the PoP key in this case, is then included 276 inside the access token and sent back to the requesting client. 277 The RS can identify the client's public key from the 278 information in the token, which allows the client to use the 279 corresponding private key for the proof of possession. 281 The access token is protected against modifications using a MAC or 282 a digital signature of the AS. The choice of PoP key does not 283 necessarily imply a specific credential type for the integrity 284 protection of the token. More information about PoP tokens can be 285 found in [I-D.ietf-oauth-pop-architecture]. 287 Scopes and Permissions: 289 In OAuth 2.0, the client specifies the type of permissions it is 290 seeking to obtain (via the scope parameter) in the access request. 291 In turn, the AS may use the "scope" response parameter to inform 292 the client of the scope of the access token issued. As the client 293 could be a constrained device as well, this memo uses CBOR encoded 294 messages defined in Appendix D to request scopes and to be 295 informed what scopes the access token was actually authorized for 296 by the AS. 298 The values of the scope parameter are expressed as a list of 299 space- delimited, case-sensitive strings, with a semantic that is 300 well-known to the AS and the RS. More details about the concept 301 of scopes is found under Section 3.3 in [RFC6749]. 303 Claims: 305 The information carried in the access token in the form of type- 306 value pairs is called claims. An access token may for example 307 include a claim about the AS that issued the token (the "iss" 308 claim) and what audience the access token is intended for (the 309 "aud" claim). The audience of an access token can be a specific 310 resource or one or many resource servers. The resource owner 311 policies influence the what claims are put into the access token 312 by the authorization server. 314 While the structure and encoding of the access token varies 315 throughout deployments, a standardized format has been defined 316 with the JSON Web Token (JWT) [RFC7519] where claims are encoded 317 as a JSON object. In [I-D.wahlstroem-ace-cbor-web-token] an 318 equivalent format using CBOR encoding (CWT) has been defined. 320 Introspection: 322 Introspection is a method for a resource server to query the 323 authorization server for the active state and content of a 324 received access token. This is particularly useful in those cases 325 where the authorization decisions are very dynamic and/or where 326 the received access token itself is a reference rather than a 327 self-contained token. More information about introspection in 328 OAuth 2.0 can be found in [I-D.ietf-oauth-introspection]. 330 3.2. CoAP 332 CoAP is an application layer protocol similar to HTTP, but 333 specifically designed for constrained environments. CoAP typically 334 uses datagram-oriented transport, such as UDP, where reordering and 335 loss of packets can occur. A security solution need to take the 336 latter aspects into account. 338 While HTTP uses headers and query-strings to convey additional 339 information about a request, CoAP encodes such information in so- 340 called 'options'. 342 CoAP supports application-layer fragmentation of the CoAP payloads 343 through blockwise transfers [I-D.ietf-core-block]. However, this 344 method does not allow the fragmentation of large CoAP options, 345 therefore data encoded in options has to be kept small. 347 3.3. Object Security 349 Transport layer security is not always sufficient and application 350 layer security has to be provided. COSE [I-D.ietf-cose-msg] defines 351 a message format for cryptographic protection of data using CBOR 352 encoding. There are two main approaches for application layer 353 security: 355 Object Security of CoAP (OSCOAP) 357 OSCOAP [I-D.selander-ace-object-security] is a method for 358 protecting CoAP request/response message exchanges, including CoAP 359 payloads, CoAP header fields as well as CoAP options. OSCOAP 360 provides end-to-end confidentiality, integrity and replay 361 protection, and a secure binding between CoAP request and response 362 messages. 364 A CoAP message protected with OSCOAP contains the CoAP option 365 "Object-Security" which signals that the CoAP message carries a 366 COSE message ([I-D.ietf-cose-msg]). OSCOAP defines a profile of 367 COSE which includes replay protection. 369 Object Security of Content (OSCON) 371 For the case of wrapping of application layer payload data 372 ("content") only, such as resource representations or claims of 373 access tokens, the same COSE profile can be applied to obtain end- 374 to-end confidentiality, integrity and replay protection. 375 [I-D.selander-ace-object-security] defines this functionality as 376 Object Security of Content (OSCON). 378 In this case, the message is not bound to the underlying 379 application layer protocol and can therefore be used with HTTP, 380 CoAP, Bluetooth Smart, etc. While OSCOAP integrity protects 381 specific CoAP message meta-data like request/response code, and 382 binds a response to a specific request, OSCON protects only 383 payload/content, therefore those security features are lost. The 384 advantages are that an OSCON message can be passed across 385 different protocols, from request to response, and used to secure 386 group communications. 388 4. Protocol Interactions 390 This framework is based on the same protocol interactions as OAuth 391 2.0: A client obtains an access token from an AS and presents the 392 token to an RS to gain access to a protected resource. These 393 interactions are shown in Figure 1. An overview of various OAuth 394 concepts is provided in Section 3.1. 396 The consent of the resource owner, for giving a client access to a 397 protected resource, can be pre-configured authorization policies or 398 dynamically at the time when the request is sent. The resource owner 399 and the requesting party (= client owner) are not shown in Figure 1. 401 For the description in this document we assume that the client has 402 been registered to an AS. Registration means that the two share 403 credentials, configuration parameters and that some form of 404 authorization has taken place. These credentials are used to protect 405 the token request by the client and the transport of access tokens 406 and client information from AS to the client. 408 It is also assumed that the RS has been registered with the AS. 409 Established keying material between the AS and the RS allows the AS 410 to apply cryptographic protection to the access token to ensure that 411 the content cannot be modified, and if needed, that the content is 412 confidentiality protected. 414 The keying material necessary for establishing communication security 415 between C and RS is dynamically established as part of the protocol 416 described in this document. 418 At the start of the protocol there is an optional discovery step 419 where the client discovers the resource server and the resources this 420 server hosts. In this step the client might also determine what 421 permissions are needed to access the protected resource. The exact 422 procedure depends on the protocols being used and the specific 423 deployment environment. In Bluetooth Smart, for example, 424 advertisements are broadcasted by a peripheral, including information 425 about the supported services. In CoAP, as a second example, a client 426 can makes a request to "/.well-known/core" to obtain information 427 about available resources, which are returned in a standardized 428 format as described in [RFC6690]. 430 +--------+ +---------------+ 431 | |---(A)-- Token Request ------------->| | 432 | | | Authorization | 433 | |<--(B)-- Access Token ---------------| Server | 434 | | + Client Information | | 435 | | +---------------+ 436 | | ^ | 437 | | Introspection Request & Response (D)| |(E) 438 | Client | | v 439 | | +--------------+ 440 | |---(C)-- Token + Request ----------->| | 441 | | | Resource | 442 | |<--(F)-- Protected Resource ---------| Server | 443 | | | | 444 +--------+ +--------------+ 446 Figure 1: Overview of the basic protocol flow 448 Requesting an Access Token (A): 450 The client makes an access token request to the AS. This memo 451 assumes the use of PoP tokens (see Section 3.1 for a short 452 description) wherein the AS binds a key to an access token. The 453 client may include permissions it seeks to obtain, and information 454 about the type of credentials it wants to use (i.e., symmetric or 455 asymmetric cryptography). 457 Access Token Response (B): 459 If the AS successfully processes the request from the client, it 460 returns an access token. It also includes various parameters, 461 which we call "Client Information". In addition to the response 462 parameters defined by OAuth 2.0 and the PoP token extension, we 463 consider new kinds of response parameters in Section 5, including 464 information on which security protocol the client should use with 465 the resource server(s) that it has just been authorized to access. 466 Communication security between client and RS may be based on pre- 467 provisioned keys/security contexts or dynamically established. 468 The RS authenticates the client via the PoP token; and the client 469 authenticates the RS via the client information as described in 470 Section 5.1. 472 Resource Request (C): 474 The client interacts with the RS to request access to the 475 protected resource and provides the access token. The protocol to 476 use between the client and the RS is not restricted to CoAP; HTTP, 477 HTTP/2, Bluetooth Smart etc., are also possible candidates. 479 Depending on the device limitations and the selected protocol this 480 exchange may be split up into two phases: 482 (1) the client sends the access token to a newly defined 483 authorization endpoint at the RS (see Section 5.3) , which 484 conveys authorization information to the RS that may be used by 485 the client for subsequent resource requests, and 487 (2) the client makes the resource access request, using the 488 communication security protocol and other client information 489 obtained from the AS. 491 The RS verifies that the token is integrity protected by the AS 492 and compares the claims contained in the access token with the 493 resource request. If the RS is online, validation can be handed 494 over to the AS using token introspection (see messages D and E) 495 over HTTP or CoAP, in which case the different parts of step C may 496 be interleaved with introspection. 498 Token Introspection Request (D): 500 A resource server may be configured to use token introspection to 501 interact with the AS to obtain the most recent claims, such as 502 scope, audience, validity etc. associated with a specific access 503 token. Token introspection over CoAP is defined in 504 [I-D.wahlstroem-ace-oauth-introspection] and for HTTP in 505 [I-D.ietf-oauth-introspection]. 507 Note that token introspection is an optional step and can be 508 omitted if the token is self-contained and the resource server is 509 prepared to perform the token validation on its own. 511 Token Introspection Response (E): 513 The AS validates the token and returns the claims associated with 514 it back to the RS. The RS then uses the received claims to 515 process the request to either accept or to deny it. 517 Protected Resource (F): 519 If the request from the client is authorized, the RS fulfills the 520 request and returns a response with the appropriate response code. 521 The RS uses the dynamically established keys to protect the 522 response, according to used communication security protocol. 524 5. OAuth 2.0 Profiling 526 This section describes profiles of OAuth 2.0 adjusting it to 527 constrained environments for use cases where this is necessary. 528 Profiling for JSON Web Tokens (JWT) is provided in 529 [I-D.wahlstroem-ace-cbor-web-token]. 531 5.1. Client Information 533 OAuth 2.0 using bearer tokens, as described in [RFC6749] and in 534 [RFC6750], requires TLS for all communication interactions between 535 client, authorization server, and resource server. This is possible 536 in the scope where OAuth 2.0 was originally developed: web and mobile 537 applications. In these environments resources like computational 538 power and bandwidth are not scarce and operating systems as well as 539 browser platforms are pre-provisioned with trust anchors that enable 540 clients to authenticate servers based on the Web PKI. In a more 541 heterogeneous IoT environment a wider range of use cases needs to be 542 supported. Therefore, this document suggests extensions to OAuth 2.0 543 that enables the AS to inform the client on how to communicate 544 securely with a RS and that allows the client to indicate 545 communication security preferences to the AS. 547 In the OAuth memo defining the key distribution for proof-of- 548 possession (PoP) tokens [I-D.ietf-oauth-pop-key-distribution], the 549 authors suggest to use Uri-query parameters in order to submit the 550 parameters of the client's token request. To avoid large headers if 551 the client uses CoAP to communicate with the AS, this memo specifies 552 the following alternative for submitting client request parameters to 553 the AS: The client encodes the parameters of it's request as a CBOR 554 map and submits that map as the payload of the client request. The 555 Content-format MUST be application/cbor in that case. 557 The OAuth memo further specifies that the AS SHALL use a JSON 558 structure in the payload of the response to encode the response 559 parameters. These parameters include the access token, destined for 560 the RS and additional information for the client, such as e.g. the 561 PoP key. We call this information "client information". If the 562 client is using CoAP to communicate with the AS the AS SHOULD use 563 CBOR instead of JSON for encoding it's response. The client can 564 explicitly request this encoding by using the CoAP Accept option. 566 If the channel between client and AS is not secure, the whole 567 messages from client to AS and vice-versa MUST be wrapped in JWEs 568 [RFC7516] or COSE_Encrypted structures [I-D.ietf-cose-msg]. 570 The client may be a constrained device and could therefore be limited 571 in the communication security protocols it supports. It can 572 therefore signal to the AS which protocols it can support for 573 securing their mutual communication. This is done by using the "csp" 574 parameter defined below in the Token Request message sent to the AS. 576 Note that The OAuth key distribution specification 577 [I-D.ietf-oauth-pop-key-distribution] describes in section 6 how the 578 client can request specific types of keys (symmetric vs. asymmetric) 579 and proof-of-possession algorithms in the PoP token request. 581 The client and the RS might not have any prior knowledge about each 582 other, therefore the AS needs to help them to establish a security 583 context or at least a key. The AS does this by indicating 584 communication security protocol ("csp") and additional key parameters 585 in the client information. 587 The "csp" parameter specifies how client and RS communication is 588 going to be secured based on returned keys. Currently defined values 589 are "TLS", "DTLS", "ObjectSecurity" with the encodings specified in 590 Figure 2. Depending on the value different additional parameters 591 become mandatory. 593 /-----------+--------------+-----------------------\ 594 | Value | Major Type | Key | 595 |-----------+--------------+-----------------------| 596 | 0 | 0 | TLS | 597 | 1 | 0 | DTLS | 598 | 2 | 0 | ObjectSecurity | 599 \-----------+--------------+-----------------------/ 601 Figure 2: Table of 'csp' parameter value encodings for Client 602 Information. 604 CoAP specifies three security modes of DTLS: PreSharedKey, 605 RawPublicKey and Certificate. The same modes may be used with TLS. 606 The client is to infer from the type of key provided, which (D)TLS 607 mode the RS supports as follows. 609 If PreSharedKey mode is used, the AS MUST provide the client with the 610 pre-shared key to be used with the RS. This key MUST be the same as 611 the PoP key (i.e. a symmetric key as in section 4 of 612 [I-D.ietf-oauth-pop-key-distribution]). 614 The client MUST use the PoP key as DTLS pre-shared key. The client 615 MUST furthermore use the "kid" parameter provided as part of the JWK/ 616 COSE_Key as the psk_identity in the DTLS handshake [RFC4279]. 618 If RawPublicKey mode is used, the AS MUST provide the client with the 619 RS's raw public key using the "rpk" parameter defined in the 620 following. This parameter MUST contain a JWK or a COSE_Key. The 621 client MUST provide a raw public key to the AS, and the AS MUST use 622 this key as PoP key in the token. The token MUST thus use asymmetric 623 keys for the proof-of-possession. 625 In order to get the proof-of-possession a RS configured to use this 626 mode together with PoP tokens MUST require client authentication in 627 the DTLS handshake. The client MUST use the raw public key bound to 628 the PoP token for client authentication in DTLS. 630 TLS or DTLS with certificates MAY make use of pre-established trust 631 anchors or MAY be configured more tightly with additional client 632 information parameters, such as x5c, x5t, or x5t#S256. An overview 633 of these parameters is given below. 635 For when communication security is based on certificates this 636 attribute can be used to define the server certificate or CA 637 certificate. Semantics for this attribute is defined by [RFC7517] or 638 COSE_Key [I-D.ietf-cose-msg]. 640 For when communication security is based on certificates this 641 attribute can be used to define the specific server certificate to 642 expect or the CA certificate. Semantics for this attribute is 643 defined by JWK/COSE_Key. 645 To use object security (such as OSCOAP and OSCON) requires security 646 context to be established, which can be provisioned with PoP token 647 and client information, or derived from that information. Object 648 security specifications designed to be used with this protocol MUST 649 specify the parameters that an AS has to provide to the client in 650 order to set up the necessary security context. 652 The RS may support different ways of receiving the access token from 653 the client (see Section 5.3 and Appendix C). The AS MAY signal the 654 required method for access token transfer in the client information 655 by using the "tktr" (token transport) parameter using the values 656 defined in table Figure 3. If no "tktn" parameter is present, the 657 client MUST use the default Authorization Information resource as 658 specified in Section 5.3. 660 /-----------+--------------+-------------------------\ 661 | Value | Major Type | Key | 662 |-----------+--------------+-------------------------| 663 | 0 | 0 | POST to /authz-info | 664 | 1 | 0 | RFC 4680 | 665 | 2 | 0 | CoAP option "Ref-Token" | 666 \-----------+--------------+-------------------------/ 668 Figure 3: Table of 'tktn' parameter value encodings for Client 669 Information. 671 Table Figure 4 summarizes the additional parameters defined here for 672 use by the client or the AS in the PoP token request protocol. 674 /-----------+--------------+----------------------------------\ 675 | Parameter | Used by | Description | 676 |-----------+--------------+----------------------------------| 677 | csp | client or AS | Communication security protocol | 678 | rpk | AS | RS's raw public key | 679 | x5c | AS | RS's X.509 certificate chain | 680 | x5t | AS | RS's SHA-1 cert thumb print | 681 | x5t#S256 | AS | RS's SHA-256 cert thumb print | 682 | tktn | AS | Mode of token transfer C -> RS | 683 \-----------+--------------+----------------------------------/ 685 Figure 4: Table of additional parameters defined for the PoP 686 protocol. 688 5.2. CoAP Access-Token Option 690 OAuth 2.0 access tokens are usually transferred as authorization 691 header. CoAP has no authorization header equivalence. This document 692 therefor register the option Access-Token. The Access-Token option 693 is an alternative for transferring the access token when it is 694 smaller then 255 bytes. If token is larger the 255 bytes lager 695 authorization information resources MUST at the RS be user when CoAP. 697 5.3. Authorization Information Resource at the Resource Server 699 A consequence of allowing the use of CoAP as web transfer protocol is 700 that we cannot rely on HTTP specific mechanisms, such as transferring 701 information elements in HTTP headers since those are not necessarily 702 gracefully mapped to CoAP. In case the access token is larger than 703 255 bytes it should not be sent as a CoAP option. 705 For conveying authorization information to the RS a new resource is 706 introduced to which the PoP tokens can be sent to convey 707 authorization information before the first resource request is made 708 by the client. This specification calls this resource "/authz-info"; 709 the URI may, however, vary in deployments. 711 The RS needs to store the PoP token for when later authorizing 712 requests from the client. The RS is not mandated to be able to 713 manage multiple client at once. how the RS manages clients is out of 714 scope for this specification. 716 5.3.1. Authorization Information Request 718 The client makes a POST request to the authorization information 719 resource by sending its PoP token as request data. 721 Client MUST send the Content-Format option indicate token format 723 5.3.2. Authorization Information Response 725 The RS MUST resonde to a requests to the authorization information 726 resource. The response MUST match CoAP response codes according to 727 success or error response section 729 5.3.2.1. Success Response 731 Successful requests MUST be answered with 2.01 Created to indicate 732 that a "session" for the PoP Token has been created. No location 733 path is required to be returned. 735 Resource 736 Client Server 737 | | 738 | | 739 A: +-------->| Header: POST (Code=0.02) 740 | POST | Uri-Path: "/authz-info" 741 | | Content-Format: "application/cwt" 742 | | Payload: 743 | | 744 B: |<--------+ Header: 2.01 Created 745 | 2.01 | 746 | | 748 Figure 5: Authorization Information Resource Success Response 750 5.3.2.2. Error Response 752 The resource server MUST user appropriate CoAP response code to 753 convey the error to the Client. For request that are not valid, e.g. 754 unknown Content-Format, 4.00 Bad Request MUST be returned. If token 755 is not valid, e.g. wrong audience, the RS MUST return 4.01 756 Unauthorized. 758 Resource 759 Client Server 760 | | 761 | | 762 A: +-------->| Header: POST (Code=0.02) 763 | POST | Uri-Path: "/authz-info" 764 | | Content-Format: "application/cwt" 765 | | Payload: 766 | | 767 B: |<--------+ Header: 4.01 Unauthorized 768 | 2.01 | 769 | | 771 Figure 6: Authorization Information Resource Error Response 773 5.4. Authorization Information Format 775 We introduce a new claim for describing access rights with a specific 776 format, the "aif" claim. In this memo we propose to use the compact 777 format provided by AIF [I-D.bormann-core-ace-aif]. Access rights may 778 be specified as a list of URIs of resources together with allowed 779 actions (GET, POST, PUT, PATCH, or DELETE). Other formats may be 780 mandated by specific applications or requirements (e.g. specifying 781 local conditions on access). 783 5.5. CBOR Data Formats 785 The /token resource (called "endpoint" in OAuth 2.0), defined in 786 Section 3.2 of [RFC6749], is used by the client to obtain an access 787 token. Requests sent to the /token resource use the HTTP POST method 788 and the payload includes a query component, which is formatted as 789 application/x-www-form-urlencoded. CoAP payloads cannot be formatted 790 in the same way which requires the /token resource on the AS to be 791 profiled. Appendix D defines a CBOR-based format for sending 792 parameters to the /token resource. 794 5.6. Token Expiration 796 Depending on the capabilities of the RS, there are various ways in 797 which it can verify the validity of a received access token. We list 798 the possibilities here including what functionality they require of 799 the RS. 801 o The token is a CWT/JWT and includes a 'exp' claim and possibly the 802 'nbf' claim. The RS verifies these by comparing them to values 803 from its internal clock as defined in [RFC7519]. In this case the 804 RS must have a real time chip (RTC) or some other way of reliably 805 measuring time. 807 o The RS verifies the validity of the token by performing an 808 introspection request as specified in Appendix D.2. This requires 809 the RS to have a reliable network connection to the AS and to be 810 able to handle two secure sessions in parallel (C to RS and AS to 811 RS). 813 o The RS and the AS both store a sequence number linked to their 814 common security association. The AS increments this number for 815 each access token it issues and includes it in the access token, 816 which is a CWT/JWT. The RS keeps track of the most recently 817 received sequence number, and only accepts tokens as valid, that 818 are in a certain range around this number. This method does only 819 require the RS to keep track of the sequence number. The method 820 does not provide timely expiration, but it makes sure that older 821 tokens cease to be valid after a specified number of newer ones 822 got issued. For a constrained RS with no network connectivity and 823 no means of reliably measuring time, this is the best that can be 824 achieved. 826 6. Deployment Scenarios 828 There is a large variety of IoT deployments, as is indicated in 829 Appendix A, and this section highlights common variants. This 830 section is not normative but illustrates how the framework can be 831 applied. 833 For each of the deployment variants there are a number of possible 834 security setups between clients, resource servers and authorization 835 servers. The main focus in the following subsections is on how 836 authorization of a client request for a resource hosted by a RS is 837 performed. This requires us to also consider how these requests and 838 responses between the clients and the resource servers are secured. 840 The security protocols between other pairs of nodes in the 841 architecture, namely client-to-AS and RS-to-AS, are not detailed in 842 these examples. Different security protocols may be used on 843 transport or application layer. 845 Note: We use the CBOR diagnostic notation for examples of requests 846 and responses. 848 6.1. Client and Resource Server are Offline 850 In this scenario we consider the case where both the resource server 851 and the client are offline, i.e., they are not connected to the AS at 852 the time of the resource request. This access procedure involves 853 steps A, B, C, and F of Figure 1, but assumes that step A and B have 854 been carried out during a phase when the client had connectivity to 855 AS. 857 Since the resource server must be able to verify the access token 858 locally, self-contained access tokens must be used. 860 This example shows the interactions between a client, the 861 authorization server and a temperature sensor acting as a resource 862 server. Message exchanges A and B are shown in Figure 7. 864 A: The client first generates a public-private key pair used for 865 communication security with the RS. 867 The client sends the POST request to /token at AS. The request 868 contains the public key of the client and the Audience parameter 869 set to "tempSensorInLivingRoom", a value that the temperature 870 sensor identifies itself with. The AS evaluates the request and 871 authorizes the client to access the resource. 873 B: The AS responds with a PoP token and client information. The 874 PoP token contains the public key of the client, while the client 875 information contains the public key of the RS. For communication 876 security this example uses DTLS with raw public keys between the 877 client and the RS. 879 Note: In this example we assume that the client knows what 880 resource it wants to access, and is therefore able to request 881 specific audience and scope claims for the access token. 883 Authorization 884 Client Server 885 | | 886 | | 887 A: +-------->| Header: POST (Code=0.02) 888 | POST | Uri-Path:"token" 889 | | Payload: 890 | | 891 B: |<--------+ Header: 2.05 Content 892 | | Content-Type: application/cbor 893 | 2.05 | Payload: 894 | | 896 Figure 7: Token Request and Response Using Client Credentials. 898 The information contained in the Request-Payload and the Response- 899 Payload is shown in Figure 8. 901 Request-Payload : 902 { 903 "grant_type" : "client_credentials", 904 "aud" : "tempSensorInLivingRoom", 905 "client_id" : "myclient", 906 "client_secret" : "qwerty" 907 } 909 Response-Payload : 910 { 911 "access_token" : b64'SlAV32hkKG ...', 912 "token_type" : "pop", 913 "csp" : "DTLS", 914 "key" : b64'eyJhbGciOiJSU0ExXzUi ...' 915 } 917 Figure 8: Request and Response Payload Details. 919 The content of the "key" parameter and the access token are shown in 920 Figure 9 and Figure 10. 922 { 923 "kid" : b64'c29tZSBwdWJsaWMga2V5IGlk', 924 "kty" : "EC", 925 "crv" : "P-256", 926 "x" : b64'MKBCTNIcKUSDii11ySs3526iDZ8AiTo7Tu6KPAqv7D4', 927 "y" : b64'4Etl6SRW2YiLUrN5vfvVHuhp7x8PxltmWWlbbM4IFyM' 928 } 930 Figure 9: Public Key of the RS. 932 { 933 "aud" : "tempSensorInLivingRoom", 934 "iat" : "1360189224", 935 "cnf" : { 936 "jwk" : { 937 "kid" : b64'1Bg8vub9tLe1gHMzV76e8', 938 "kty" : "EC", 939 "crv" : "P-256", 940 "x" : b64'f83OJ3D2xF1Bg8vub9tLe1gHMzV76e8Tus9uPHvRVEU', 941 "y" : b64'x_FEzRu9m36HLN_tue659LNpXW6pCyStikYjKIWI5a0' 942 } 943 } 944 } 946 Figure 10: Access Token including Public Key of the Client. 948 Messages C and F are shown in Figure 11 - Figure 12. 950 C: The client then sends the PoP token to the /authz-info resource 951 at the RS. This is a plain CoAP request, i.e. no DTLS/OSCOAP 952 between client and RS, since the token is integrity protected 953 between AS and RS. The RS verifies that the PoP token was created 954 by a known and trusted AS, is valid, and responds to the client. 955 The RS caches the security context together with authorization 956 information about this client contained in the PoP token. 958 The client and resource server run the DTLS handshake using the 959 raw public keys established in step B and C. 961 The client sends the CoAP request GET to /temperature on RS over 962 DTLS. The RS verifies that the request is authorized. 964 F: The RS responds with a resource representation over DTLS. 966 Resource 967 Client Server 968 | | 969 C: +-------->| Header: POST (Code=0.02) 970 | POST | Uri-Path:"authz-info" 971 | | Payload: SlAV32hkKG ... 972 | | (access token) 973 | | 974 |<--------+ Header: 2.04 Changed 975 | 2.04 | 976 | | 978 Figure 11: Access Token provisioning to RS 980 Resource 981 Client Server 982 | | 983 |<=======>| DTLS Connection Establishment 984 | | using Raw Public Keys 985 | | 986 | | 987 +-------->| Header: GET (Code=0.01) 988 | GET | Uri-Path: "temperature" 989 | | 990 | | 991 | | 992 F: |<--------+ Header: 2.05 Content 993 | 2.05 | Payload: {"t":"22.7"} 994 | | 996 Figure 12: Resource Request and Response protected by DTLS. 998 6.2. Resource Server Offline 1000 In this deployment scenario we consider the case of an RS that may 1001 not be able to access the AS at the time it receives an access 1002 request from a client. We denote this case "RS offline", it involves 1003 steps A, B, C and F of Figure 1. 1005 If the RS is offline, then it must be possible for the RS to locally 1006 validate the access token. This requires self-contained tokens to be 1007 used. 1009 The validity time for the token should always be chosen as short as 1010 possible to reduce the possibility that a token contains out-of-date 1011 authorization information. Therefore the value for the Expiration 1012 Time claim ("exp") should be set only slightly larger than the value 1013 for the Issuing Time claim ("iss"). A constrained RS with means to 1014 reliably measure time must validate the expiration time of the access 1015 token. 1017 The following example shows interactions between a client (air- 1018 conditioning control unit), an offline resource server (temperature 1019 sensor)and an authorization server. The message exchanges A and B 1020 are shown in Figure 13. 1022 A: The client sends the request POST to /token at AS. The request 1023 contains the Audience parameter set to "tempSensor109797", a value 1024 that the temperature sensor identifies itself with. The scope the 1025 client wants the AS to authorize the access token for is "owner", 1026 which means that the token can be used to both read temperature 1027 data and upgrade the firmware on the RS. The AS evaluates the 1028 request and authorizes the client to access the resource. 1030 B: The AS responds with a PoP token and client information. The 1031 PoP token is wrapped in a COSE message, object secured content 1032 from AS to RS. The client information contains a symmetric key. 1033 In this case communication security between C and RS is OSCOAP 1034 with an authenticated encryption algorithm. The client derives 1035 two unidirectional security contexts to use with the resource 1036 request and response messages. The access token includes the 1037 claim "aif" with the authorized access that an owner of the 1038 temperature device can enjoy. The "aif" claim, issued by the AS, 1039 informs the RS that the owner of the access token, that can prove 1040 the possession of a key is authorized to make a GET request 1041 against the /tempC resource and a POST request on the /firmware 1042 resource. 1044 Authorization 1045 Client Server 1046 | | 1047 | | 1048 A: +-------->| Header: POST (Code=0.02) 1049 | POST | Uri-Path: "token" 1050 | | Payload: 1051 | | 1052 B: |<--------+ Header: 2.05 Content 1053 | | Content-Type: application/cbor 1054 | 2.05 | Payload: 1055 | | 1056 | | 1058 Figure 13: Token Request and Response 1060 The information contained in the Request-Payload and the Response- 1061 Payload is shown in Figure 14. 1063 Request-Payload: 1064 { 1065 "grant_type" : "client_credentials", 1066 "client_id" : "myclient", 1067 "client_secret" : "qwerty", 1068 "aud" : "tempSensor109797", 1069 "scope" : "owner" 1070 } 1072 Response-Payload: 1073 { 1074 "access_token": b64'SlAV32hkKG ...', 1075 "token_type" : "pop", 1076 "csp" : "OSCOAP", 1077 "key" : b64'eyJhbGciOiJSU0ExXzUi ...' 1078 } 1080 Figure 14: Request and Response Payload for RS offline 1082 Figure 15 shows examples of the key and the access_token parameters 1083 of the Response-Payload, decoded to CBOR. 1085 access_token: 1086 { 1087 "aud" : "tempSensor109797", 1088 "exp" : 1311281970, 1089 "iat" : 1311280970, 1090 "aif" : [["/tempC", 0], ["/firmware", 2]], 1091 "cnf" : { 1092 "ck":b64'JDLUhTMjU2IiwiY3R5Ijoi ...' 1093 } 1094 } 1096 key: 1097 { 1098 "alg" : "AES_128_CCM_8", 1099 "kid" : b64'U29tZSBLZXkgSWQ', 1100 "k" : b64'ZoRSOrFzN_FzUA5XKMYoVHyzff5oRJxl-IXRtztJ6uE' 1101 } 1103 Figure 15: Access Token and symmetric key from the Response-Payload 1105 Message exchanges C and F are shown in Figure 16 and Figure 17. 1107 C: The client then sends the PoP token to the /authz-info resource 1108 in the RS. This is a plain CoAP request, i.e. no DTLS/OSCOAP 1109 between client and RS, since the token is integrity protected 1110 between AS and RS. The RS verifies that the PoP token was created 1111 by a known and trusted AS, is valid, and responds to the client. 1112 The RS derives and caches the security contexts together with 1113 authorization information about this client contained in the PoP 1114 token. 1116 The client sends the CoAP requests GET to /tempC on the RS using 1117 OSCOAP. The RS verifies the request and that it is authorized. 1119 F: The RS responds with a protected status code using OSCOAP. The 1120 client verifies the response. 1122 Resource 1123 Client Server 1124 | | 1125 C: +-------->| Header: POST (Code=0.02) 1126 | POST | Uri-Path:"authz-info" 1127 | | Payload: 1128 | | 1129 | | 1130 |<--------+ Header: 2.04 Changed 1131 | 2.04 | 1132 | | 1133 | | 1135 Figure 16: Access Token provisioning to RS 1137 Resource 1138 Client Server 1139 | | 1140 +-------->| Header: GET (Code=0.01) 1141 | GET | Object-Security: 1142 | | (,,[Uri-Path:"tempC"],) 1143 | | 1144 F: |<--------+ Header: 2.05 Content 1145 | 2.05 | Object-Security: 1146 | | (,,[22.7 C],) 1147 | | 1149 Figure 17: Resource request and response protected by OSCOAP 1151 In Figure 17 the GET request contains an Object-Security option and 1152 an indication of the content of the COSE object: a sequence number 1153 ("seq", starting from 0), a context identifier ("cid") indicating the 1154 security context, the ciphertext containing the encrypted CoAP option 1155 identifying the resource, and the Message Authentication Code ("tag") 1156 which also covers the Code in the CoAP header. 1158 The Object-Security ciphertext in the response [22.7 C] represents an 1159 encrypted temperature reading. (The COSE object is actually carried 1160 in the CoAP payload when possible but that is omitted to simplify 1161 notation.) 1163 6.3. Token Introspection with an Offline Client 1165 In this deployment scenario we assume that a client is not be able to 1166 access the AS at the time of the access request. Since the RS is, 1167 however, connected to the back-end infrastructure it can make use of 1168 token introspection. This access procedure involves steps A-F of 1169 Figure 1, but assumes steps A and B have been carried out during a 1170 phase when the client had connectivity to AS. 1172 Since the client is assumed to be offline, at least for a certain 1173 period of time, a pre-provisioned access token has to be long-lived. 1174 The resource server may use its online connectivity to validate the 1175 access token with the authorization server, which is shown in the 1176 example below. 1178 In the example we show the interactions between an offline client 1179 (key fob), a resource server (online lock), and an authorization 1180 server. We assume that there is a provisioning step where the client 1181 has access to the AS. This corresponds to message exchanges A and B 1182 which are shown in Figure 18. 1184 A: The client sends the request using POST to /token at AS. The 1185 request contains the Audience parameter set to "lockOfDoor4711", a 1186 value the that the online door in question identifies itself with. 1187 The AS generates an access token as on opaque string, which it can 1188 match to the specific client, a targeted audience and a symmetric 1189 key security context. 1191 B: The AS responds with the an access token and client 1192 information, the latter containing a symmetric key. Communication 1193 security between C and RS will be OSCOAP with authenticated 1194 encryption. 1196 Authorization 1197 Client Server 1198 | | 1199 | | 1200 A: +-------->| Header: POST (Code=0.02) 1201 | POST | Uri-Path:"token" 1202 | | Payload: 1203 | | 1204 B: |<--------+ Header: 2.05 Content 1205 | | Content-Type: application/cbor 1206 | 2.05 | Payload: 1207 | | 1209 Figure 18: Token Request and Response using Client Credentials. 1211 Authorization consent from the resource owner can be pre-configured, 1212 but it can also be provided via an interactive flow with the resource 1213 owner. An example of this for the key fob case could be that the 1214 resource owner has a connected car, he buys a generic key that he 1215 wants to use with the car. To authorize the key fob he connects it 1216 to his computer that then provides the UI for the device. After that 1217 OAuth 2.0 implicit flow is used to authorize the key for his car at 1218 the the car manufacturers AS. 1220 The information contained in the Request-Payload and the Response- 1221 Payload is shown in Figure 19. 1223 Request-Payload: 1224 { 1225 "grant_type" : "token", 1226 "aud" : "lockOfDoor4711", 1227 "client_id" : "myclient", 1228 } 1230 Response-Payload: 1231 { 1232 "access_token" : b64'SlAV32hkKG ...' 1233 "token_type" : "pop", 1234 "csp" : "OSCOAP", 1235 "key" : b64'eyJhbGciOiJSU0ExXzUi ...' 1236 } 1238 Figure 19: Request and Response Payload for C offline 1240 The access token in this case is just an opaque string referencing 1241 the authorization information at the AS. 1243 C: Next, the client POSTs the access token to the /authz-info 1244 resource in the RS. This is a plain CoAP request, i.e. no DTLS/ 1245 OSCOAP between client and RS. Since the token is an opaque 1246 string, the RS cannot verify it on its own, and thus defers to 1247 respond the client with a status code until step E and only 1248 acknowledges on the CoAP message layer (indicated with a dashed 1249 line). 1251 Resource 1252 Client Server 1253 | | 1254 C: +-------->| Header: POST (T=CON, Code=0.02 1255 | POST | Token 0x2a12) 1256 | | Uri-Path:"authz-info" 1257 | | Payload: SlAV32hkKG ... 1258 | | (access token) 1259 | | 1260 |<- - - - + Header: T=ACK 1261 | | 1263 Figure 20: Access Token provisioning to RS 1265 D: The RS forwards the token to the /introspect resource on the 1266 AS. Introspection assumes a secure connection between the AS and 1267 the RS, e.g. using DTLS or OSCOAP, which is not detailed in this 1268 example. 1270 E: The AS provides the introspection response containing claims 1271 about the token. This includes the confirmation key (cnf) claim 1272 that allows the RS to verify the client's proof of possession in 1273 step F. 1275 After receiving message E, the RS responds to the client's POST in 1276 step C with Code 2.04 (Changed), using CoAP Token 0x2a12. This 1277 step is not shown in the figures. 1279 Resource Authorization 1280 Server Server 1281 | | 1282 D: +--------->| Header: POST (Code=0.02) 1283 | POST | Uri-Path: "introspect" 1284 | | Payload: 1285 | | 1286 E: |<---------+ Header: 2.05 Content 1287 | 2.05 | Content-Type: application/cbor) 1288 | | Payload: 1289 | | 1291 Figure 21: Token Introspection for C offline 1293 The information contained in the Request-Payload and the Response- 1294 Payload is shown in Figure 22. 1296 Request-Payload: 1297 { 1298 "token" : b64'SlAV32hkKG...', 1299 "client_id" : "myRS", 1300 "client_secret" : "ytrewq" 1301 } 1303 Response-Payload: 1304 { 1305 "active" : true, 1306 "aud" : "lockOfDoor4711", 1307 "scope" : "open, close", 1308 "iat" : 1311280970, 1309 "cnf" : { 1310 "ck" : b64'JDLUhTMjU2IiwiY3R5Ijoi ...' 1311 } 1312 } 1314 Figure 22: Request and Response Payload for Introspection 1316 The client sends the CoAP requests PUT 1 (= "close the lock") to 1317 /lock on RS using OSCOAP with a security context derived from the 1318 key supplied in step B. The RS verifies the request with the key 1319 supplied in step E and that it is authorized by the token supplied 1320 in step C. 1322 F: The RS responds with a protected status code using OSCOAP. The 1323 client verifies the response. 1325 Resource 1326 Client Server 1327 | | 1328 +-------->| Header: PUT (Code=0.03) 1329 | PUT | Object-Security: 1330 | | (,,[Uri-Path:"lock", 1],) 1331 | | 1332 F: |<--------+ Header: 2.04 Changed 1333 | 2.04 | Object-Security: 1334 | | (,,,) 1335 | | 1337 Figure 23: Resource request and response protected by OSCOAP 1339 The Object-Security ciphertext [...] of the PUT request contains CoAP 1340 options that are encrypted, as well as the payload value '1' which is 1341 the value of PUT to the door lock. 1343 In this example there is no ciphertext of the PUT response, but "tag" 1344 contains a MAC which covers the request sequence number and context 1345 identifier as well as the Code which allows the Client to verify that 1346 this actuator command was well received (door is locked). 1348 6.4. Always-On Connectivity 1350 A popular deployment scenario for IoT devices is to have them always 1351 be connected to the Internet so that they can be reachable to receive 1352 commands. As a continuation from the previous scenarios we assume 1353 that both the client and the RS are online at the time of the access 1354 request. 1356 If the client and the resource server are online then the AS should 1357 be configured to issue short-lived access tokens for the resource to 1358 the client. The resource server must then validate self-contained 1359 access tokens or otherwise must use token introspection to obtain the 1360 up-to-date claim information. If transmission costs are high or the 1361 channel is lossy, the CWT token format 1362 [I-D.wahlstroem-ace-cbor-web-token] may be used instead of a JWT to 1363 reduce the volume of network traffic. In terms of messaging this 1364 deployment scenario uses the patterns described in the previous sub- 1365 sections. 1367 Note that despite the lack of connectivity constraints there may 1368 still be other restrictions a deployment may face. 1370 6.5. Token-less Authorization 1372 In this deployment scenario we consider the case of an RS which is 1373 severely energy constrained, sleeps most of the time and need to have 1374 a tight messaging budget. It is not only infeasible to access the AS 1375 at the time of the access request, as in the "RS offline" case 1376 Section 6.2, it must be offloaded as much message communication as 1377 possible. 1379 OAuth 2.0 is already an efficient protocol in terms of message 1380 exchanges and can be further optimized by compact encodings of 1381 tokens. The scenario illustrated in this section goes beyond that 1382 and removes the access tokens from the protocol. This may be 1383 considered a degenerate case of OAuth 2.0 but it allows us to do two 1384 things: 1386 1. The common case where authorization is performed by means of 1387 authentication fits into the same protocol framework. 1388 Authentication protocol and key is specified by client 1389 information, and access token is omitted. 1391 2. Authentication, and thereby authorization, may even be implicit, 1392 i.e. anyone with access to the right key is authorized to access 1393 the protected resource. 1395 In case 2., the RS does not need to receive any message from the 1396 client, and therefore enables offloading recurring resource request 1397 and response processing to a third party, such as a Message Broker 1398 (MB) in a publish-subscribe setting. 1400 This scenario involves steps A, B, C and F of Figure 1 and four 1401 parties: a client (subscriber), an offline RS (publisher), a trusted 1402 AS, and a MB, not necessarily trusted with access to the plain text 1403 publications. Message exchange A, B is shown in Figure 24. 1405 A: The client sends the request POST to /token at AS. The request 1406 contains the Audience parameter set to "birchPollenSensor301", a 1407 value that characterizes a certain pollen sensor resource. The AS 1408 evaluates the request and authorizes the client to access the 1409 resource. 1411 B: The AS responds with an empty token and client information with 1412 a security context to be used by the client. The empty token 1413 signifies that authorization is performed by means of 1414 authentication using the communication security protocol indicated 1415 with "csp". In this case it is object security of content (OSCON) 1416 i.e. protection of CoAP payload only. The security context 1417 contains the symmetric decryption key and a public signature 1418 verification key of the RS. 1420 Authorization 1421 Client Server 1422 | | 1423 | | 1424 A: +-------->| Header: POST (Code=0.02) 1425 | POST | Uri-Path:"token" 1426 | | Payload: 1427 | | 1428 B: |<--------+ Header: 2.05 Content 1429 | | Content-Type: application/cbor 1430 | 2.05 | Payload: 1431 | | 1432 | | 1434 Figure 24: Token Request and Response 1436 The information contained in the Request-Payload and the Response- 1437 Payload is shown in Figure 25. 1439 Request-Payload : 1440 { 1441 "grant_type" : "client_credentials", 1442 "aud" : "birchPollenSensor301", 1443 "client_id" : "myclient", 1444 "client_secret" : "qwerty" 1445 } 1447 Response-Payload : 1448 { 1449 "access_token" : NULL, 1450 "token_type" : "none", 1451 "csp" : "OSCON", 1452 "key" : b64'eyJhbGciOiJSU0ExXzUi ...' 1453 } 1455 Figure 25: Request and Response Payload for RS severely constrained 1457 The content of the "key" parameter is shown in Figure 26. 1459 key : 1460 { 1461 "alg" : "AES_128_CTR_ECDSA", 1462 "kid" : b64'c29tZSBvdGhlciBrZXkgaWQ'; 1463 "k" : b64'ZoRSOrFzN_FzUA5XKMYoVHyzff5oRJxl-IXRtztJ6uE', 1464 "crv" : "P-256", 1465 "x" : b64'MKBCTNIcKUSDii11ySs3526iDZ8AiTo7Tu6KPAqv7D4', 1466 "y" : b64'4Etl6SRW2YiLUrN5vfvVHuhp7x8PxltmWWlbbM4IFyM' 1467 } 1469 Figure 26: The 'key' Parameter 1471 The RS, which sleeps most of the time, occasionally wakes up, 1472 measures the number birch pollens per cubic meters, publishes the 1473 measurements to the MB, and then returns to sleep. See Figure 27. 1475 In this case the birch pollen count stopped at 270, which is 1476 encrypted with the symmetric key and signed with the private key of 1477 the RS. The MB verifies that the message originates from RS using 1478 the public key of RS, that it is not a replay of an old measurement 1479 using the sequence number of the OSCON COSE profile, and caches the 1480 object secured content. The MB does not have the secret key so is 1481 unable to read the plain text measurement. 1483 Message exchanges C and F are shown in Figure 27. 1485 C: Since there is no access token, the client does not address the 1486 /authz-info resource in the RS. The client sends the CoAP request 1487 GET to /birchPollen on MB which is a plain CoAP request. 1489 F: The MB responds with the cached object secured content. 1491 Message Resource 1492 Client Broker Server 1493 | | | 1494 | |<--------| Header: PUT (Code=0.02) 1495 | | PUT | Uri-Path: "birchPollen" 1496 | | | Payload: (,,["270"],) 1497 | | | 1498 | |-------->| Header: 2.04 Changed 1499 | | 2.04 | 1500 | | 1501 | | 1502 C: +-------->| Header: GET (Code=0.01) 1503 | GET | Uri-Path: "birchPollen" 1504 | | 1505 | | 1506 F: |<--------+ Header: 2.05 Content 1507 | 2.05 | Payload: (,,["270"],) 1508 | | 1510 Figure 27: Sensor measurement protected by COSE 1512 The payload is a COSE message consisting of sequence number 'seq' 1513 stepped by the RS for each publication, the context identifier 'cid' 1514 in this case coinciding with the key identifier 'kid' of Figure 26, 1515 the encrypted measurement and the signature by the RS. 1517 Note that the same COSE message format may be used as in OSCOAP but 1518 that only CoAP payload is protected in this case. 1520 The authorization step is implicit, so while any client could request 1521 access the COSE object, only authorized clients have access to the 1522 symmetric key needed to decrypt the content. 1524 Note that in this case the order of the message exchanges A,B and C,F 1525 could in principle be interchanged, i.e. the client could first 1526 request and obtain the protected resource in steps C,F; and after 1527 that request client information containing the keys decrypt and 1528 verify the message. 1530 6.6. Securing Group Communication 1532 There are use cases that require securing communication between a 1533 (group of) senders and a group of receivers. One prominent example 1534 is lighting. Often, a set of lighting nodes (e.g., luminaires, wall- 1535 switches, sensors) are grouped together and only authorized members 1536 of the group must be able read and process messages. Additionally, 1537 receivers of group messages must be able to verify the integrity of 1538 received messages as being generated within the group. 1540 The requirements for securely communicating in such group use cases 1541 efficiently is outlined in [I-D.somaraju-ace-multicast] along with an 1542 architectural description that aligns with the content of this 1543 document. The requirements for conveying the necessary identifiers 1544 to reference groups and also the process of commissioning devices can 1545 be accomplished using the protocol described in this document. For 1546 details about the lighting-unique use case aspects, the architecture, 1547 as well as other multicast-specific considerations we refer the 1548 reader to [I-D.somaraju-ace-multicast]. 1550 7. Security Considerations 1552 The entire document is about security. Security considerations 1553 applicable to authentication and authorization in RESTful 1554 environments provided in OAuth 2.0 [RFC6749] apply to this work, as 1555 well as the security considerations from [I-D.ietf-ace-actors]. 1556 Furthermore [RFC6819] provides additional security considerations for 1557 OAuth which apply to IoT deployments as well. Finally 1558 [I-D.ietf-oauth-pop-architecture] discusses security and privacy 1559 threats as well as mitigation measures for Proof-of-Possession 1560 tokens. 1562 8. IANA Considerations 1564 TBD 1566 FIXME: Add registry over 'csp' values from Figure 2 1568 FIXME: Add registry of 'rpk' parameter from section 5.1 1570 FIXME: Add registry of 'tktn' values from Figure 3 1572 8.1. CoAP Option Number Registration 1574 This section registers the "Access-Token" CoAP Option Number 1575 [RFC2046] in "CoRE Parameters" sub-registry "CoAP Option Numbers" in 1576 the manner described in [RFC7252]. 1578 Name 1580 Access-Token 1582 Number 1584 TBD 1586 Reference 1588 [draft-ietf-ace-oauth-authz] 1590 Meaning in Request 1592 Contains an Access Token according to [draft-ietf-ace-oauth-authz] 1593 containing access permissions of the client. 1595 Meaning in Response 1597 Not used in response 1599 Safe-to-Forward 1601 TBD 1603 Format 1605 Based on the observer the format is perseved differently. Opaque 1606 data to the client and CWT or reference token to the RS. 1608 Length 1610 Less then 255 bytes 1612 9. Acknowledgments 1614 We would like to thank Eve Maler for her contributions to the use of 1615 OAuth 2.0 and UMA in IoT scenarios, Robert Taylor for his discussion 1616 input, and Malisa Vucinic for his input on the ACRE proposal 1617 [I-D.seitz-ace-core-authz] which was one source of inspiration for 1618 this work. Finally, we would like to thank the ACE working group in 1619 general for their feedback. 1621 10. References 1623 10.1. Normative References 1625 [I-D.bormann-core-ace-aif] 1626 Bormann, C., "An Authorization Information Format (AIF) 1627 for ACE", draft-bormann-core-ace-aif-03 (work in 1628 progress), July 2015. 1630 [I-D.ietf-cose-msg] 1631 Schaad, J., "CBOR Encoded Message Syntax", draft-ietf- 1632 cose-msg-10 (work in progress), February 2016. 1634 [I-D.ietf-oauth-introspection] 1635 Richer, J., "OAuth 2.0 Token Introspection", draft-ietf- 1636 oauth-introspection-11 (work in progress), July 2015. 1638 [I-D.ietf-oauth-pop-architecture] 1639 Hunt, P., Richer, J., Mills, W., Mishra, P., and H. 1640 Tschofenig, "OAuth 2.0 Proof-of-Possession (PoP) Security 1641 Architecture", draft-ietf-oauth-pop-architecture-07 (work 1642 in progress), December 2015. 1644 [I-D.ietf-oauth-pop-key-distribution] 1645 Bradley, J., Hunt, P., Jones, M., and H. Tschofenig, 1646 "OAuth 2.0 Proof-of-Possession: Authorization Server to 1647 Client Key Distribution", draft-ietf-oauth-pop-key- 1648 distribution-02 (work in progress), October 2015. 1650 [I-D.selander-ace-object-security] 1651 Selander, G., Mattsson, J., Palombini, F., and L. Seitz, 1652 "Object Security of CoAP (OSCOAP)", draft-selander-ace- 1653 object-security-03 (work in progress), October 2015. 1655 [I-D.wahlstroem-ace-cbor-web-token] 1656 Wahlstroem, E., Jones, M., and H. Tschofenig, "CBOR Web 1657 Token (CWT)", draft-wahlstroem-ace-cbor-web-token-00 (work 1658 in progress), December 2015. 1660 [I-D.wahlstroem-ace-oauth-introspection] 1661 Wahlstroem, E., "OAuth 2.0 Introspection over the 1662 Constrained Application Protocol (CoAP)", draft- 1663 wahlstroem-ace-oauth-introspection-01 (work in progress), 1664 March 2015. 1666 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1667 Requirement Levels", BCP 14, RFC 2119, 1668 DOI 10.17487/RFC2119, March 1997, 1669 . 1671 [RFC4279] Eronen, P., Ed. and H. Tschofenig, Ed., "Pre-Shared Key 1672 Ciphersuites for Transport Layer Security (TLS)", 1673 RFC 4279, DOI 10.17487/RFC4279, December 2005, 1674 . 1676 [RFC6347] Rescorla, E. and N. Modadugu, "Datagram Transport Layer 1677 Security Version 1.2", RFC 6347, DOI 10.17487/RFC6347, 1678 January 2012, . 1680 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 1681 Application Protocol (CoAP)", RFC 7252, 1682 DOI 10.17487/RFC7252, June 2014, 1683 . 1685 [RFC7516] Jones, M. and J. Hildebrand, "JSON Web Encryption (JWE)", 1686 RFC 7516, DOI 10.17487/RFC7516, May 2015, 1687 . 1689 [RFC7517] Jones, M., "JSON Web Key (JWK)", RFC 7517, 1690 DOI 10.17487/RFC7517, May 2015, 1691 . 1693 10.2. Informative References 1695 [I-D.ietf-ace-actors] 1696 Gerdes, S., Seitz, L., Selander, G., and C. Bormann, "An 1697 architecture for authorization in constrained 1698 environments", draft-ietf-ace-actors-02 (work in 1699 progress), October 2015. 1701 [I-D.ietf-core-block] 1702 Bormann, C. and Z. Shelby, "Block-wise transfers in CoAP", 1703 draft-ietf-core-block-18 (work in progress), September 1704 2015. 1706 [I-D.seitz-ace-core-authz] 1707 Seitz, L., Selander, G., and M. Vucinic, "Authorization 1708 for Constrained RESTful Environments", draft-seitz-ace- 1709 core-authz-00 (work in progress), June 2015. 1711 [I-D.somaraju-ace-multicast] 1712 Somaraju, A., Kumar, S., Tschofenig, H., and W. Werner, 1713 "Security for Low-Latency Group Communication", draft- 1714 somaraju-ace-multicast-01 (work in progress), January 1715 2016. 1717 [RFC4680] Santesson, S., "TLS Handshake Message for Supplemental 1718 Data", RFC 4680, DOI 10.17487/RFC4680, October 2006, 1719 . 1721 [RFC4949] Shirey, R., "Internet Security Glossary, Version 2", 1722 FYI 36, RFC 4949, DOI 10.17487/RFC4949, August 2007, 1723 . 1725 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 1726 (TLS) Protocol Version 1.2", RFC 5246, 1727 DOI 10.17487/RFC5246, August 2008, 1728 . 1730 [RFC6690] Shelby, Z., "Constrained RESTful Environments (CoRE) Link 1731 Format", RFC 6690, DOI 10.17487/RFC6690, August 2012, 1732 . 1734 [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", 1735 RFC 6749, DOI 10.17487/RFC6749, October 2012, 1736 . 1738 [RFC6750] Jones, M. and D. Hardt, "The OAuth 2.0 Authorization 1739 Framework: Bearer Token Usage", RFC 6750, 1740 DOI 10.17487/RFC6750, October 2012, 1741 . 1743 [RFC6819] Lodderstedt, T., Ed., McGloin, M., and P. Hunt, "OAuth 2.0 1744 Threat Model and Security Considerations", RFC 6819, 1745 DOI 10.17487/RFC6819, January 2013, 1746 . 1748 [RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object 1749 Representation (CBOR)", RFC 7049, DOI 10.17487/RFC7049, 1750 October 2013, . 1752 [RFC7159] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 1753 Interchange Format", RFC 7159, DOI 10.17487/RFC7159, March 1754 2014, . 1756 [RFC7228] Bormann, C., Ersue, M., and A. Keranen, "Terminology for 1757 Constrained-Node Networks", RFC 7228, 1758 DOI 10.17487/RFC7228, May 2014, 1759 . 1761 [RFC7231] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 1762 Protocol (HTTP/1.1): Semantics and Content", RFC 7231, 1763 DOI 10.17487/RFC7231, June 2014, 1764 . 1766 [RFC7519] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token 1767 (JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015, 1768 . 1770 Appendix A. Design Justification 1772 This section provides further insight into the design decisions of 1773 the solution documented in this document. Section 3 lists several 1774 building blocks and briefly summarizes their importance. The 1775 justification for offering some of those building blocks, as opposed 1776 to using OAuth 2.0 as is, is given below. 1778 Common IoT constraints are: 1780 Low Power Radio: 1782 Many IoT devices are equipped with a small battery which needs to 1783 last for a long time. For many constrained wireless devices the 1784 highest energy cost is associated to transmitting or receiving 1785 messages. It is therefore important to keep the total 1786 communication overhead low, including minimizing the number and 1787 size of messages sent and received, which has an impact of choice 1788 on the message format and protocol. By using CoAP over UDP, and 1789 CBOR encoded messages some of these aspects are addressed. 1790 Security protocols contribute to the communication overhead and 1791 can in some cases be optimized. For example authentication and 1792 key establishment may in certain cases where security requirements 1793 so allows be replaced by provisioning of security context by a 1794 trusted third party, using transport or application layer 1795 security. 1797 Low CPU Speed: 1799 Some IoT devices are equipped with processors that are 1800 significantly slower than those found in most current devices on 1801 the Internet. This typically has implications on what timely 1802 cryptographic operations a device is capable to perform, which in 1803 turn impacts e.g. protocol latency. Symmetric key cryptography 1804 may be used instead of the computationally more expensive public 1805 key cryptography where the security requirements so allows, but 1806 this may also require support for trusted third party assisted 1807 secret key establishment using transport or application layer 1808 security. 1810 Small Amount of Memory: 1812 Microcontrollers embedded in IoT devices are often equipped with 1813 small amount of RAM and flash memory, which places limitations 1814 what kind of processing can be performed and how much code can be 1815 put on those devices. To reduce code size fewer and smaller 1816 protocol implementations can be put on the firmware of such a 1817 device. In this case, CoAP may be used instead of HTTP, symmetric 1818 key cryptography instead of public key cryptography, and CBOR 1819 instead of JSON. Authentication and key establishment protocol, 1820 e.g. the DTLS handshake, in comparison with assisted key 1821 establishment also has an impact on memory and code. 1823 User Interface Limitations: 1825 Protecting access to resources is both an important security as 1826 well as privacy feature. End users and enterprise customers do 1827 not want to give access to the data collected by their IoT device 1828 or to functions it may offer to third parties. Since the 1829 classical approach of requesting permissions from end users via a 1830 rich user interface does not work in many IoT deployment scenarios 1831 these functions need to be delegated to user controlled devices 1832 that are better suitable for such tasks, such as smart phones and 1833 tablets. 1835 Communication Constraints: 1837 In certain constrained settings an IoT device may not be able to 1838 communicate with a given device at all times. Devices may be 1839 sleeping, or just disconnected from the Internet because of 1840 general lack of connectivity in the area, for cost reasons, or for 1841 security reasons, e.g. to avoid an entry point for Denial-of- 1842 Service attacks. 1844 The communication interactions this framework builds upon (as 1845 shown graphically in Figure 1) may be accomplished using a variety 1846 of different protocols, and not all parts of the message flow are 1847 used in all applications due to the communication constraints. 1848 While we envision deployments to make use of CoAP we explicitly 1849 want to support HTTP, HTTP/2 or specific protocols, such as 1850 Bluetooth Smart communication, which does not necessarily use IP. 1851 The latter raises the need for application layer security over the 1852 various interfaces. 1854 Appendix B. Roles and Responsibilites -- a Checklist 1856 Resource Owner 1858 * Make sure that the RS is registered at the AS. 1860 * Make sure that clients can discover the AS which is in charge 1861 of the RS. 1863 * Make sure that the AS has the necessary, up-to-date, access 1864 control policies for the RS. 1866 Requesting Party 1868 * Make sure that the client is provisioned the necessary 1869 credentials to authenticate to the AS. 1871 * Make sure that the client is configured to follow the security 1872 requirements of the Requesting Party, when issuing requests 1873 (e.g. minimum communication security requirements, trust 1874 anchors). 1876 * Register the client at the AS. 1878 Authorization Server 1880 * Register RS and manage corresponding security contexts. 1882 * Register clients and including authentication credentials. 1884 * Allow Resource Onwers to configure and update access control 1885 policies related to their registered RS' 1887 * Expose a service that allows clients to request tokens. 1889 * Authenticate clients that wishes to request a token. 1891 * Process a token requests against the authorization policies 1892 configured for the RS. 1894 * Expose a service that allows RS's to submit token introspection 1895 requests. 1897 * Authenticate RS's that wishes to get an introspection response. 1899 * Process token introspection requests. 1901 * Optionally: Handle token revocation. 1903 Client 1905 * Discover the AS in charge of the RS that is to be targeted with 1906 a request. 1908 * Submit the token request (A). 1910 + Authenticate towards the AS. 1912 + Specify which RS, which resource(s), and which action(s) the 1913 request(s) will target. 1915 + Specify preferences for communication security 1917 + If raw public key (rpk) or certificate is used, make sure 1918 the AS has the right rpk or certificate for this client. 1920 * Process the access token and client information (B) 1922 + Check that the token has the right format (e.g. CWT). 1924 + Check that the client information provides the necessary 1925 security parameters (e.g. PoP key, information on 1926 communication security protocols supported by the RS). 1928 * Send the token and request to the RS (C) 1930 + Authenticate towards the RS (this could coincide with the 1931 proof of possession process). 1933 + Transmit the token as specified by the AS (default is to an 1934 authorization information resource, alternative options are 1935 as a CoAP option or in the DTLS handshake). 1937 + Perform the proof-of-possession procedure as specified for 1938 the type of used token (this may already have been taken 1939 care of through the authentication procedure). 1941 * Process the RS response (F) requirements of the Requesting 1942 Party, when issuing requests (e.g. minimum communication 1943 security requirements, trust anchors). 1945 * Register the client at the AS. 1947 Resource Server 1949 * Expose a way to submit access tokens. 1951 * Process an access token. 1953 + Verify the token is from the right AS. 1955 + Verify that the token applies to this RS. 1957 + Check that the token has not expired (if the token provides 1958 expiration information). 1960 + Check the token's integrity. 1962 + Store the token so that it can be retrieved in the context 1963 of a matching request. 1965 * Process a request. 1967 + Set up communication security with the client. 1969 + Authenticate the client. 1971 + Match the client against existing tokens. 1973 + Check that tokens belonging to the client actually authorize 1974 the requested action. 1976 + Optionally: Check that the matching tokens are still valid 1977 (if this is possible. 1979 * Send a response following the agreed upon communication 1980 security. 1982 Appendix C. Optimizations 1984 This section sketches some potential optimizations to the presented 1985 solution. 1987 Access token in DTLS handshake 1989 In the case of CSP=DTLS/TLS, the access token provisioning 1990 exchange in step C of the protocol may be embedded in the security 1991 handshake. Different solutions are possible, where one 1992 standardized method would be the use of the TLS supplemental data 1993 extension [RFC4680] for transferring the access token. 1995 Reference token and introspection 1997 In case of introspection it may be beneficial to utilize access 1998 tokens which are not self-contained (also known as "reference 1999 tokens") that are used to lookup detailed information about the 2000 authorization. The RS uses the introspection message exchange not 2001 only for validating token claims, but also for obtaining claims 2002 that potentially were not known at the time when the access token 2003 was issued. 2005 A reference token can be made much more compact than a self- 2006 contained token, since it does not need to contain any of claims 2007 that it represents. This could be very useful in particular if 2008 the client is constrained and offline most of the time. 2010 Reference token in CoAP option 2012 While large access tokens must be sent in CoAP payload, if the 2013 access token is known to be of a certain limited size, for example 2014 in the case of a reference token, then it would be favorable to 2015 combine the access token provisioning request with the resource 2016 request to the RS. 2018 One way to achieve this is to define a new CoAP option for 2019 carrying reference tokens, called "Ref-Token" as shown in the 2020 example in Figure 28. 2022 Resource 2023 Client Server 2024 | | 2025 C: +-------->| Header: PUT (Code=0.02) 2026 | PUT | Ref-Token:SlAV32hkKG 2027 | | Object-Security: 2028 | | ,,[Uri-Path:"lock", 1],) 2029 | | 2030 . . 2031 . . 2032 . . 2033 | | 2034 F: |<--------+ Header: 2.04 Changed 2035 | 2.04 | Object-Security: 2036 | | (,,,) 2037 | | 2039 Figure 28: Reference Token in CoAP Option 2041 Appendix D. CoAP and CBOR profiles for OAuth 2.0 2043 Many IoT devices can support OAuth 2.0 without any additional 2044 extensions, but for certain constrained settings additional profiling 2045 is needed. In this appendix we define CoAP resources for the HTTP 2046 based token and introspection endpoints used in vanilla OAuth 2.0. 2047 We also define a CBOR alternative to the JSON and form based POST 2048 structures used in HTTP. 2050 D.1. Profile for Token resource 2052 The token resource is used by the client to obtain an access token by 2053 presenting its authorization grant or client credentials to the 2054 /token resource the AS. 2056 D.1.1. Token Request 2058 The client makes a request to the token resource by sending a CBOR 2059 structure with the following attributes. 2061 grant_type: 2063 REQUIRED. The grant type, "code", "client_credentials", 2064 "password" or others. 2066 client_id: 2068 OPTIONAL. The client identifier issued to the holder of the token 2069 (client or RS) during the registration process. 2071 client_secret: 2073 OPTIONAL. The client secret. 2075 scope: 2077 OPTIONAL. The scope of the access request as described by 2078 Section 3.1. 2080 aud: 2082 OPTIONAL. Service-specific string identifier or list of string 2083 identifiers representing the intended audience for this token, as 2084 defined in [I-D.wahlstroem-ace-cbor-web-token]. 2086 alg: 2088 OPTIONAL. The value in the 'alg' parameter together with value 2089 from the 'token_type' parameter allow the client to indicate the 2090 supported algorithms for a given token type. 2092 key: 2094 OPTIONAL. This field contains information about the public key 2095 the client would like to bind to the access token in the COSE Key 2096 Structure format. 2098 The parameters defined above use the following CBOR major types. 2100 /-----------+--------------+-----------------------\ 2101 | Value | Major Type | Key | 2102 |-----------+--------------+-----------------------| 2103 | 0 | 0 | grant_type | 2104 | 1 | 0 | client_id | 2105 | 2 | 0 | client_secret | 2106 | 3 | 0 | scope | 2107 | 4 | 0 | aud | 2108 | 5 | 0 | alg | 2109 | 6 | 0 | key | 2110 \-----------+--------------+-----------------------/ 2112 Figure 29: CBOR mappings used in token requests 2114 D.1.2. Token Response 2116 The AS responds by sending a CBOR structure with the following 2117 attributes. 2119 access_token: 2121 REQUIRED. The access token issued by the authorization server. 2123 token_type: 2125 REQUIRED. The type of the token issued. "pop" is recommended. 2127 key: 2129 REQUIRED, if symmetric key cryptography is used. A COSE Key 2130 Structure containing the symmetric proof of possession key. The 2131 members of the structure can be found in section 7.1 of 2132 [I-D.ietf-cose-msg]. 2134 csp: 2136 REQUIRED. Information on what communication protocol to use in 2137 the communication between the client and the RS. Details on 2138 possible values can be found in Section 5.1. 2140 scope: 2142 OPTIONAL, if identical to the scope requested by the client; 2143 otherwise, REQUIRED. 2145 alg: 2147 OPTIONAL. The 'alg' parameter provides further information about 2148 the algorithm, such as whether a symmetric or an asymmetric 2149 crypto-system is used. 2151 The parameters defined above use the following CBOR major types. 2153 /-----------+--------------+-----------------------\ 2154 | Value | Major Type | Key | 2155 |-----------+--------------+-----------------------| 2156 | 0 | 0 | access_token | 2157 | 1 | 0 | token_type | 2158 | 2 | 0 | key | 2159 | 3 | 0 | csp | 2160 | 4 | 0 | scope | 2161 | 5 | 0 | alg | 2162 \-----------+--------------+-----------------------/ 2164 Figure 30: CBOR mappings used in token responses 2166 D.2. CoAP Profile for OAuth Introspection 2168 This section defines a way for a holder of access tokens, mainly 2169 clients and RS's, to get metadata like validity status, claims and 2170 scopes found in access token. The OAuth Token Introspection 2171 specification [I-D.ietf-oauth-introspection] defines a way to 2172 validate the token using HTTP POST or HTTP GET. This document reuses 2173 the work done in the OAuth Token Introspection and defines a mapping 2174 of the request and response to CoAP [RFC7252] to be used by 2175 constrained devices. 2177 D.2.1. Introspection Request 2179 The token holder makes a request to the Introspection CoAP resource 2180 by sending a CBOR structure with the following attributes. 2182 token: 2184 REQUIRED. The string value of the token. 2186 resource_id: 2188 OPTIONAL. A service-specific string identifying the resource that 2189 the client doing the introspection is asking about. 2191 client_id: 2193 OPTIONAL. The client identifier issued to the holder of the token 2194 (client or RS) during the registration process. 2196 client_secret: 2198 OPTIONAL. The client secret. 2200 The parameters defined above use the following CBOR major types: 2202 /-----------+--------------+-----------------------\ 2203 | Value | Major Type | Key | 2204 |-----------+--------------+-----------------------| 2205 | 0 | 0 | token | 2206 | 1 | 0 | resource_id | 2207 | 2 | 0 | client_id | 2208 | 3 | 0 | client_secret | 2209 \-----------+--------------+-----------------------/ 2211 Figure 31: CBOR Mappings to Token Introspection Request Parameters. 2213 D.2.2. Introspection Response 2215 If the introspection request is valid and authorized, the 2216 authorization server returns a CoAP message with the response encoded 2217 as a CBOR structure in the payload of the message. If the request 2218 failed client authentication or is invalid, the authorization server 2219 returns an error response using the CoAP 4.00 'Bad Request' response 2220 code. 2222 The JSON structure in the payload response includes the top-level 2223 members defined in Section 2.2 in the OAuth Token Introspection 2224 specification [I-D.ietf-oauth-introspection]. It is RECOMMENDED to 2225 only return the 'active' attribute considering constrained nature of 2226 CoAP client and server networks. 2228 Introspection responses in CBOR use the following mappings: 2230 active: 2232 REQUIRED. The active key is an indicator of whether or not the 2233 presented token is currently active. The specifics of a token's 2234 "active" state will vary depending on the implementation of the 2235 authorization server, and the information it keeps about its 2236 tokens, but a "true" value return for the "active" property will 2237 generally indicate that a given token has been issued by this 2238 authorization server, has not been revoked by the resource owner, 2239 and is within its given time window of validity (e.g., after its 2240 issuance time and before its expiration time). 2242 scope: 2244 OPTIONAL. A string containing a space-separated list of scopes 2245 associated with this token, in the format described in Section 3.3 2246 of OAuth 2.0 [RFC6749]. 2248 client_id: 2250 OPTIONAL. Client identifier for the client that requested this 2251 token. 2253 username: 2255 OPTIONAL. Human-readable identifier for the resource owner who 2256 authorized this token. 2258 token_type: 2260 OPTIONAL. Type of the token as defined in Section 5.1 of OAuth 2261 2.0 [RFC6749] or PoP token. 2263 exp: 2265 OPTIONAL. Integer timestamp, measured in the number of seconds 2266 since January 1 1970 UTC, indicating when this token will expire, 2267 as defined in CWT [I-D.wahlstroem-ace-cbor-web-token]. 2269 iat: 2271 OPTIONAL. Integer timestamp, measured in the number of seconds 2272 since January 1 1970 UTC, indicating when this token will expire, 2273 as defined in CWT [I-D.wahlstroem-ace-cbor-web-token]. 2275 nbf: 2277 OPTIONAL. Integer timestamp, measured in the number of seconds 2278 since January 1 1970 UTC, indicating when this token will expire, 2279 as defined in CWT [I-D.wahlstroem-ace-cbor-web-token]. 2281 sub: 2283 OPTIONAL. Subject of the token, as defined in CWT 2284 [I-D.wahlstroem-ace-cbor-web-token]. Usually a machine-readable 2285 identifier of the resource owner who authorized this token. 2287 aud: 2289 OPTIONAL. Service-specific string identifier or list of string 2290 identifiers representing the intended audience for this token, as 2291 defined in CWT [I-D.wahlstroem-ace-cbor-web-token]. 2293 iss: 2295 OPTIONAL. String representing the issuer of this token, as 2296 defined in CWT [I-D.wahlstroem-ace-cbor-web-token]. 2298 cti: 2300 OPTIONAL. String identifier for the token, as defined in CWT 2301 [I-D.wahlstroem-ace-cbor-web-token] 2303 The parameters defined above use the following CBOR major types: 2305 /-----------+--------------+-----------------------\ 2306 | Value | Major Type | Key | 2307 |-----------+--------------+-----------------------| 2308 | 0 | 0 | active | 2309 | 1 | 0 | scopes | 2310 | 2 | 0 | client_id | 2311 | 3 | 0 | username | 2312 | 4 | 0 | token_type | 2313 | 5 | 0 | exp | 2314 | 6 | 0 | iat | 2315 | 7 | 0 | nbf | 2316 | 8 | 0 | sub | 2317 | 9 | 0 | aud | 2318 | 10 | 0 | iss | 2319 | 11 | 0 | cti | 2320 \-----------+--------------+-----------------------/ 2322 Figure 32: CBOR Mappings to Token Introspection Response Parameters. 2324 Appendix E. Document Updates 2326 E.1. Version -00 to -01 2328 o Changed 5.1. from "Communication Security Protocol" to "Client 2329 Information". 2331 o Major rewrite of 5.1 to clarify the information exchanged between 2332 C and AS in the PoP token request profile for IoT. 2334 * Allow the client to indicate preferences for the communication 2335 security protocol. 2337 * Defined the term "Client Information" for the additional 2338 information returned to the client in addition to the access 2339 token. 2341 * Require that the messages between AS and client are secured, 2342 either with (D)TLS or with COSE_Encrypted wrappers. 2344 * Removed dependency on OSCoAP and added generic text about 2345 object security instead. 2347 * Defined the "rpk" parameter in the client information to 2348 transmit the raw public key of the RS from AS to client. 2350 * (D)TLS MUST use the PoP key in the handshake (either as PSK or 2351 as client RPK with client authentication). 2353 * Defined the use of x5c, x5t and x5tS256 parameters when a 2354 client certificate is used for proof of possession. 2356 * Defined "tktn" parameter for signaling for how to tranfer the 2357 access token. 2359 o Added 5.2. the CoAP Access-Token option for transfering access 2360 tokens in messages that do not have payload. 2362 o 5.3.2. Defined success and error responses from the RS when 2363 receiving an access token. 2365 o 5.6.:Added section giving guidance on how to handle token 2366 expiration in the absence of reliable time. 2368 o Appendix B Added list of roles and responsibilities for C, AS and 2369 RS. 2371 Authors' Addresses 2373 Ludwig Seitz 2374 SICS 2375 Scheelevaegen 17 2376 Lund 223 70 2377 SWEDEN 2379 Email: ludwig@sics.se 2381 Goeran Selander 2382 Ericsson 2383 Faroegatan 6 2384 Kista 164 80 2385 SWEDEN 2387 Email: goran.selander@ericsson.com 2388 Erik Wahlstroem 2389 Nexus Technology 2390 Telefonvagen 26 2391 Hagersten 126 26 2392 Sweden 2394 Email: erik.wahlstrom@nexusgroup.com 2396 Samuel Erdtman 2397 Nexus Technology 2398 Telefonvagen 26 2399 Hagersten 126 26 2400 Sweden 2402 Email: samuel.erdtman@nexusgroup.com 2404 Hannes Tschofenig 2405 ARM Ltd. 2406 Hall in Tirol 6060 2407 Austria 2409 Email: Hannes.Tschofenig@arm.com