idnits 2.17.1 draft-seitz-ace-oauth-authz-00.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 (October 19, 2015) is 3112 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) == Unused Reference: 'I-D.ietf-oauth-pop-key-distribution' is defined on line 1376, but no explicit reference was found in the text == Outdated reference: A later version (-09) exists of draft-bormann-core-ace-aif-02 ** 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-05 == Outdated reference: A later version (-11) exists of draft-ietf-oauth-introspection-09 == Outdated reference: A later version (-08) exists of draft-ietf-oauth-pop-architecture-02 ** 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-01 == Outdated reference: A later version (-06) exists of draft-selander-ace-object-security-01 ** 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-00 == 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-00 -- 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: 4 errors (**), 0 flaws (~~), 11 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: April 21, 2016 Ericsson 6 E. Wahlstroem 7 S. Erdtman 8 Nexus Technology 9 H. Tschofenig 10 ARM Ltd. 11 October 19, 2015 13 Authorization for the Internet of Things using OAuth 2.0 14 draft-seitz-ace-oauth-authz-00 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 April 21, 2016. 41 Copyright Notice 43 Copyright (c) 2015 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 . . . . . . . . . . . . . . . . . . . . . 11 66 5.1. Communication Security Protocol . . . . . . . . . . . . . 12 67 5.2. Authorization Information Resource at the Resource Server 12 68 5.3. Authorization Information Format . . . . . . . . . . . . 13 69 5.4. CBOR Data Formats . . . . . . . . . . . . . . . . . . . . 13 70 5.5. CBOR Web Token . . . . . . . . . . . . . . . . . . . . . 13 71 6. Deployment Scenarios . . . . . . . . . . . . . . . . . . . . 13 72 6.1. Client and Resource Server are Offline . . . . . . . . . 14 73 6.2. Resource Server Offline . . . . . . . . . . . . . . . . . 17 74 6.3. Token Introspection with an Offline Client . . . . . . . 21 75 6.4. Always-On Connectivity . . . . . . . . . . . . . . . . . 25 76 6.5. Token-less Authorization . . . . . . . . . . . . . . . . 25 77 6.6. Securing Group Communication . . . . . . . . . . . . . . 28 78 7. Security Considerations . . . . . . . . . . . . . . . . . . . 29 79 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 29 80 9. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 29 81 10. References . . . . . . . . . . . . . . . . . . . . . . . . . 30 82 10.1. Normative References . . . . . . . . . . . . . . . . . . 30 83 10.2. Informative References . . . . . . . . . . . . . . . . . 31 84 Appendix A. Design Justification . . . . . . . . . . . . . . . . 32 85 Appendix B. Optimizations . . . . . . . . . . . . . . . . . . . 34 86 Appendix C. CoAP and CBOR profiles for OAuth 2.0 . . . . . . . . 35 87 C.1. Profile for Token resource . . . . . . . . . . . . . . . 35 88 C.1.1. Token Request . . . . . . . . . . . . . . . . . . . . 35 89 C.1.2. Token Response . . . . . . . . . . . . . . . . . . . 37 90 C.2. CoAP Profile for OAuth Introspection . . . . . . . . . . 38 91 C.2.1. Introspection Request . . . . . . . . . . . . . . . . 38 92 C.2.2. Introspection Response . . . . . . . . . . . . . . . 39 93 Appendix D. CBOR Web Token (CWT) . . . . . . . . . . . . . . . . 41 94 D.1. Claim Names . . . . . . . . . . . . . . . . . . . . . . . 41 95 D.1.1. iss (Issuer) Claim . . . . . . . . . . . . . . . . . 41 96 D.1.2. sub (Subject) Claim . . . . . . . . . . . . . . . . . 42 97 D.1.3. aud (Audience) Claim . . . . . . . . . . . . . . . . 42 98 D.1.4. exp (Expiration Time) Claim . . . . . . . . . . . . . 42 99 D.1.5. nbf (Not Before) Claim . . . . . . . . . . . . . . . 42 100 D.1.6. iat (Issued At) Claim . . . . . . . . . . . . . . . . 43 101 D.1.7. cti (CWT ID) Claim . . . . . . . . . . . . . . . . . 43 102 D.1.8. cnf (Confirmation) Claim . . . . . . . . . . . . . . 43 103 D.1.9. cks (COSE Key Structure) Claim . . . . . . . . . . . 43 104 D.1.10. aif (Authorization Information Format) Claim . . . . 43 105 D.2. CBOR major types for Claims . . . . . . . . . . . . . . . 43 106 D.3. CBOR Web Token Example . . . . . . . . . . . . . . . . . 44 107 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 44 109 1. Introduction 111 Authorization is the process of deciding what an entity ought to be 112 allowed to do. Managing authorization information for a large number 113 of devices and users is often a complex task where dedicated servers 114 are used. 116 Managing authorization of users, services and their devices with the 117 help of dedicated authorization servers (AS) is a common task, found 118 in enterprise networks as well as on the Web. In its simplest form 119 the authorization task can be described as granting access to a 120 resource hosted on a device, the resource server (RS). This exchange 121 is mediated by one or multiple authorization servers. 123 We envision that end consumers and enterprises will want to manage 124 their Internet of Things (IoT) devices in the same style and this 125 desire will increase with the number of devices that need to be 126 managed and controlled. The IoT devices may be constrained in 127 various ways including processing, memory, code, energy, etc., as 128 defined in [RFC7228], and the different IoT deployments present a 129 continuous range of device and network capabilities. Taking energy 130 consumption as an example: At one end there are energy-harvesting or 131 battery powered devices which have a tight power budget, on the other 132 end there are mains-connected devices which are not constrained in 133 terms of power, and all levels in between. Thus IoT devices are very 134 different in terms of available processing and message exchange 135 capabilities. 137 This memo describes how to re-use OAuth 2.0 [RFC6749] to extend 138 authorization to Internet of Things devices with different kinds of 139 constrainedness. At the time of writing OAuth 2.0 is already used 140 with certain types of IoT devices and this document will provide 141 implementers additional guidance for using it in a secure and 142 privacy-friendly way. Where possible the basic OAuth 2.0 mechanisms 143 are used; in some circumstances profiles are defined, for example to 144 support lower the over-the-wire message size and smaller code size. 146 2. Terminology 148 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 149 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 150 document are to be interpreted as described in [RFC2119]. 152 Certain security-related terms such as "authentication", 153 "authorization", "confidentiality", "(data) integrity", "message 154 authentication code", and "verify" are taken from [RFC4949]. 156 Since we describe exchanges as RESTful protocol interactions HTTP 157 [RFC7231] offers useful terminology. 159 Terminology for entities in the architecture is defined in OAuth 2.0 160 [RFC6749] and [I-D.ietf-ace-actors], such as client (C), resource 161 server (RS), and authorization server (AS). OAuth 2.0 uses the term 162 "endpoint" to denote HTTP resources such as /token and /authorize at 163 the AS, but we will use the term "resource" in this memo to avoid 164 confusion with the CoAP [RFC7252] term "endpoint". 166 Since this draft focuses on the problem of access control to 167 resources, we simplify the actors by assuming that the client 168 authorization server (CAS) functionality is not stand-alone but 169 subsumed by either the authorization server or the client (see 170 section 2.2 in [I-D.ietf-ace-actors]). 172 3. Overview 174 This specification describes a framework for authorization in the 175 Internet of Things consisting of a set of building blocks. 177 The basic block is the OAuth 2.0 [RFC6749] framework, which enjoys 178 widespread deployment. Many IoT devices can support OAuth 2.0 179 without any additional extensions, but for certain constrained 180 settings additional profiling is needed. 182 Another building block is the lightweight web transfer protocol CoAP 183 [RFC7252] for those communication environments where HTTP is not 184 appropriate. CoAP typically runs on top of UDP which further reduces 185 overhead and message exchanges. When CoAP is used over UDP, 186 transport layer security is provided by DTLS 1.2 [RFC6347] instead of 187 TLS 1.2 [RFC5246]. 189 A third building block is CBOR [RFC7049] for encodings where JSON 190 [RFC7159] is not sufficiently compact. CBOR is a binary encoding 191 designed for extremely small code size and fairly small message size. 192 OAuth 2.0 allows access tokens to use different encodings and this 193 document defines such an alternative encoding. The COSE message 194 format [I-D.ietf-cose-msg] is also based on CBOR. 196 A fourth building block is application layer security, which is used 197 where transport layer security is insufficient. At the time of 198 writing the preferred approach for securing CoAP at the application 199 layer is via the use of COSE [I-D.ietf-cose-msg], which adds object 200 security to CBOR-encoded data. More details about applying COSE to 201 CoAP can be found in OSCOAP [I-D.selander-ace-object-security]. 203 With the building blocks listed above, solutions satisfying various 204 IoT device and network constraints are possible. A list of 205 constraints is described in detail in RFC 7228 [RFC7228] and a 206 description of how the building blocks mentioned above relate to the 207 various constraints can be found in Appendix A. 209 Luckily, not every IoT device suffers from all constraints. The 210 described framework does, however, takes all these aspects into 211 account and allows several different deployment variants to co-exist 212 rather than mandating a one-size-fits-all solution. We believe this 213 is important to cover the wide range of possible interworking use 214 cases and the different requirements from a security point of view. 215 Once IoT deployments mature, popular deployment variants will be 216 documented in form of profiles. 218 In the subsections below we provide further details about the 219 different building blocks. 221 3.1. OAuth 2.0 223 The OAuth 2.0 authorization framework enables a client to obtain 224 limited access to a resource with the permission of a resource owner. 225 Authorization related information is passed between the nodes using 226 access tokens. These access tokens are issued to clients by an 227 authorization server with the approval of the resource owner. The 228 client uses the access token to access the protected resources hosted 229 by the resource server. 231 A number of OAuth 2.0 terms are used within this memo: 233 Access Tokens: 235 Access tokens are credentials used to access protected resources. 236 An access token is a data structure representing authorization 237 permissions issued to the client. Access tokens are generated by 238 the authorization server and consumed by the resource server. The 239 access token is opaque to the client. 241 Access tokens can have different formats, and various methods of 242 utilization (e.g., cryptographic properties) based on the security 243 requirements of the given deployment. 245 Proof of Possession Tokens: 247 An access token may be bound to a cryptographic key, which is then 248 used by an RS to authenticate requests from a client. Such tokens 249 are called proof-of-possession tokens (or PoP tokens) 250 [I-D.ietf-oauth-pop-architecture]. 252 The proof-of-possession (PoP) security concept assumes that the AS 253 acts as a trusted third party that binds keys to access tokens. 254 These so called PoP keys are then used by the client to 255 demonstrate the possession of the secret to the RS when accessing 256 the resource. The RS, when receiving an access token, needs to 257 verify that the key used by the client matches the one included in 258 the access token. When this memo uses the term "access token" it 259 is assumed to be a PoP token unless specifically stated otherwise. 261 The key bound to the access token (aka PoP key) may be based on 262 symmetric as well as on asymmetrical cryptography. The 263 appropriate choice of security depends on the constraints of the 264 IoT devices as well as on the security requirements of the use 265 case. 267 Symmetric PoP key: 269 The AS generates a random symmetric PoP key, encrypts it for 270 the RS and includes it inside an access token. The PoP key 271 is also encrypted for the client and sent together with the 272 access token to the client. 274 Asymmetric PoP key: 276 An asymmetric key pair is generated on the client and the 277 public key is sent to the AS (if it does not already have 278 knowledge of the client's public key). Information about 279 the public key, which is the PoP key in this case, is then 280 included inside the access token and sent back to the 281 requesting client. 283 The access token is protected against modifications using a MAC or 284 a digital signature of the AS. The choice of PoP key does not 285 necessarily imply a specific credential type for the integrity 286 protection of the token. More information about PoP tokens can be 287 found in [I-D.ietf-oauth-pop-architecture]. 289 Scopes and Permissions: 291 In OAuth 2.0, the client specifies the type of permissions it is 292 seeking to obtain (via the scope parameter) in the access request. 293 In turn, the AS may use the "scope" response parameter to inform 294 the client of the scope of the access token issued. This memo 295 uses CBOR encoded messages defined in Appendix C to request scopes 296 and to be informed what scopes the access token was actually 297 authorized for by the AS. 299 The values of the scope parameter are expressed as a list of 300 space- delimited, case-sensitive strings, with a semantic that is 301 well-known to the AS and the RS. More details about the concept 302 of scopes is found under Section 3.3 in [RFC6749]. 304 Claims: 306 The information carried in the access token in the form of type- 307 value pairs is called claims. An access token may for example 308 include a claim about the AS that issued the token (the "iss" 309 claim) and what audience the access token is intended for (the 310 "aud" claim). The audience of an access token can be a specific 311 resource or one or many resource servers. The resource owner 312 policies influence the what claims are put into the access token 313 by the authorization server. 315 While the structure and encoding of the access token varies 316 throughout deployments, a standardized format has been defined 317 with the JSON Web Token (JWT) [RFC7519] where claims are encoded 318 as a JSON object. In Appendix D we define a CBOR version of JWT 319 that we call CBOR Web Token (CWT). 321 Introspection: 323 Introspection is a method for a resource server to query the 324 authorization server for the active state and content of a 325 received access token. This is particularly useful in those cases 326 where the authorization decisions are very dynamic and/or where 327 the received access token itself is a reference rather than a 328 self-contained token. More information about introspection in 329 OAuth 2.0 can be found in [I-D.ietf-oauth-introspection]. 331 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. 336 Where HTTP uses headers and query-strings to convey additional 337 information about a request, CoAP encodes such information in so- 338 called 'options'. 340 CoAP supports application-layer fragmentation of the CoAP payloads 341 through blockwise transfers [I-D.ietf-core-block]. However, this 342 method does not allow the fragmentation of large CoAP options, 343 therefore data encoded in options has to be kept small. 345 3.3. Object Security 347 Transport layer security is not always sufficient and application 348 layer security has to be provided. COSE [I-D.ietf-cose-msg] defines 349 a message format for cryptographic protection of data using CBOR 350 encoding. There are two main approaches for application layer 351 security: 353 Object Security of CoAP (OSCOAP) 355 OSCOAP [I-D.selander-ace-object-security] is a method for 356 protecting CoAP request/response message exchanges, including CoAP 357 payloads, CoAP header fields as well as CoAP options. OSCOAP 358 provides end-to-end confidentiality, integrity and replay 359 protection, and a secure binding between CoAP request and response 360 messages. 362 A CoAP message protected with OSCOAP contains the CoAP option 363 "Object-Security" which signals that the CoAP message carries a 364 COSE message ([I-D.ietf-cose-msg]). OSCOAP defines a profile of 365 COSE which includes replay protection. 367 Object Security of Content (OSCON) 369 For the case of wrapping of application layer payload data 370 ("content") only, such as resource representations or claims of 371 access tokens, the same COSE profile can be applied to obtain end- 372 to-end confidentiality, integrity and replay protection. 373 [I-D.selander-ace-object-security] defines this functionality as 374 Object Security of Content (OSCON). 376 In this case, the message is not bound to the underlying 377 application layer protocol and can therefore be used with HTTP, 378 CoAP, Bluetooth Smart, etc. Whereas OSCOAP integrity protects 379 specific CoAP message meta-data like request/response code, and 380 binds a response to a specific request, since OSCON protects only 381 payload/content, those security features are lost. The advantages 382 are that an OSCON message can be passed across different 383 protocols, from request to response, and used to secure group 384 communications. 386 4. Protocol Interactions 388 This framework is based on the same protocol interactions as OAuth 389 2.0: A client obtains an access token from an AS and presents the 390 token to an RS to gain access to a protected resource. These 391 interactions are shown in Figure 1. An overview of various OAuth 392 concepts is provided in Section 3.1. 394 The consent of the resource owner, for giving a client access to a 395 protected resource, can be pre-configured authorization policies or 396 dynamically at the time when the request is sent. The resource owner 397 and the requesting party (= client owner) are not shown in Figure 1. 399 For the description in this document we assume that the client has 400 been registered to an AS. Registration means that the two share 401 credentials, configuration parameters and that some form of 402 authorization has taken place. These credentials are used to protect 403 the token request by the client and the transport of access tokens 404 and client information from AS to the client. 406 It is also assumed that the RS has been registered with the AS. 407 Established keying material between the AS and the RS allows the AS 408 to apply cryptographic protection to the access token to ensure that 409 the content cannot be modified, and if needed, that the content is 410 confidentiality protected. 412 The keying material necessary for establishing communication security 413 between C and RS is dynamically established as part of the protocol 414 described in this document. 416 At the start of the protocol there is an optional discovery step 417 where the client discovers the resource server and the resources this 418 server hosts. In this step the client might also determine what 419 permissions are needed to access the protected resource. The exact 420 procedure depends on the protocols being used and the specific 421 deployment environment. In Bluetooth Smart, for example, 422 advertisements are broadcasted by a peripheral, including information 423 about the supported services. In CoAP, as a second example, a client 424 can makes a request to "/.well-known/core" to obtain information 425 about available resources, which are returned in a standardized 426 format as described in [RFC6690]. 428 +--------+ +---------------+ 429 | |---(A)-- Token Request ------------->| | 430 | | | Authorization | 431 | |<--(B)-- Access Token ---------------| Server | 432 | | + Client Information | | 433 | | +---------------+ 434 | | ^ | 435 | | Introspection Request & Response (D)| |(E) 436 | Client | | v 437 | | +--------------+ 438 | |---(C)-- Token + Request ----------->| | 439 | | | Resource | 440 | |<--(F)-- Protected Resource ---------| Server | 441 | | | | 442 +--------+ +--------------+ 444 Figure 1: Overview of the basic protocol flow 446 Requesting an Access Token (A): 448 The client makes an access token request to the AS. This memo 449 assumes the use of PoP tokens (see Section 3.1 for a short 450 description) wherein the AS binds a key to an access token. The 451 client may include permissions it seeks to obtain, and information 452 about the type of credentials it wants to use (i.e., symmetric or 453 asymmetric cryptography). 455 Access Token Response (B): 457 If the AS successfully processes the request from the client, it 458 returns an access token. It also includes various parameters, 459 which we call "Client Information". In addition to the response 460 parameters defined by OAuth 2.0 and the PoP token extension, we 461 consider new kinds of response parameters in Section 5, including 462 information on which security protocol the client should use with 463 the resource server(s) that it has just been authorized to access. 464 Communication security between client and RS may be based on pre- 465 provisioned keys/security contexts or dynamically established to 466 the RS via the PoP token; and to the client via the client 467 information as described in Section 5.1. 469 Resource Request (C): 471 The client interacts with the RS to request access to the 472 protected resource and provides the access token. The protocol to 473 use between the client and the RS is not restricted to CoAP; HTTP, 474 HTTP/2, Bluetooth Smart etc., are also possible candidates. 476 Depending on the device limitations and the selected protocol this 477 exchange may be split up into two phases: 479 (1) the client sends the access token to a newly defined 480 authorization endpoint at the RS (see Section 5.2) , which 481 conveys authorization information to the RS that may be used 482 for subsequent resource requests, and 484 (2) the client makes the resource access request, using the 485 communication security protocol and other client information 486 obtained from the AS. 488 The RS verifies that the token is integrity protected by the AS 489 and compares the claims contained in the access token with the 490 resource request. If the RS is online, validation can be handed 491 over to the AS using token introspection (see messages D and E) 492 over HTTP or CoAP, in which case the different parts of step C may 493 be interleaved with introspection. 495 Token Introspection Request (D): 497 A resource server may be configured to use token introspection to 498 interact with the AS to obtain the most recent claims, such as 499 scope, audience, validity etc. associated with a specific access 500 token. Token introspection over CoAP is defined in 501 [I-D.wahlstroem-ace-oauth-introspection] and for HTTP in 502 [I-D.ietf-oauth-introspection]. 504 Note that token introspection is an optional step and can be 505 omitted if the token is self-contained and the resource server is 506 prepared to perform the token validation on its own. 508 Token Introspection Response (E): 510 The AS validates the token and returns the claims associated with 511 it back to the RS. The RS then uses the received claims to 512 process the request to either accept or to deny it. 514 Protected Resource (F): 516 If the request from the client is authorized, the RS fulfills the 517 request and returns a response with the appropriate response code. 518 The RS uses the dynamically established keys to protect the 519 response, according to used communication security protocol. 521 5. OAuth 2.0 Profiling 522 This section describes profiles of OAuth 2.0 adjusting it to 523 constrained environments for use cases where this is necessary. 525 5.1. Communication Security Protocol 527 OAuth 2.0 using bearer tokens, as described in RFC 6749 and in RFC 528 6750, requires TLS for all communication interactions between client, 529 authorization server, and resource server. This is possible in the 530 scope where OAuth 2.0 was originally developed, web and mobile 531 applications. In these environments resources like computational 532 power and bandwidth are not scarce and operating systems as well as 533 browser platforms are pre-provisioned with trust anchors that enable 534 clients to authenticate servers based on the Web PKI. In a more 535 heterogeneous IoT environment a wider range of use cases needs to be 536 supported. Therefore, this document suggests extensions to OAuth 2.0 537 that enable the AS to inform the client on how to communicate 538 securely with a RS. 540 The client and the RS might not have any prior knowledge about each 541 other, therefore the AS needs to help them to establish a security 542 context or at least a key. The AS does this by indicating 543 communication security protocol ("csp") and additional key parameters 544 in the client information. 546 The "csp" parameter specifies how client and RS communication is 547 going to be secured based on returned keys. Currently defined values 548 are "TLS", "DTLS", "OSCOAP" and "OSCON". Depending on the value 549 different additional parameters become mandatory. 551 TLS with certificates may make use of pre-established trust anchors 552 or configured more tightly with additional client information 553 parameters, like x5c, x5t or x5t#S256. 555 CoAP specifies three security "modes" of DTLS: PreSharedKey, 556 RawPublicKey and Certificate. In case of PreSharedKey and 557 RawPublicKey DTLS is based on the use keys distributed in the PoP 558 token and via the client information. Additional certificate 559 information may also be added, for example using the parameter x5c, 560 x5t or x5t#S256. 562 To use OSCOAP and OSCON requires security context to be established, 563 which can be provisioned with PoP token and client information, or 564 derived from keys provisioned in this way. 566 5.2. Authorization Information Resource at the Resource Server 568 A consequence of allowing the use of CoAP as web transfer protocol is 569 that we cannot rely on HTTP specific mechanisms, such as transferring 570 information elements in HTTP headers since those are not necessarily 571 gracefully mapped to CoAP. In case the access token is larger then 572 255 bytes it should not be sent as a CoAP option. 574 For conveying authorization information to the RS we therefore 575 introduce a new resource to which the PoP tokens can be sent to 576 convey authorization information before the first resource request is 577 made by the client. This specification calls this resource "/authz- 578 info"; the URI may, however, vary in deployments. 580 5.3. Authorization Information Format 582 We introduce a new claim for describing access rights with a specific 583 format, the "aif" claim. In this memo we propose to use the compact 584 format provided by AIF [I-D.bormann-core-ace-aif]. Access rights may 585 be specified as a list of URIs of resources together with allowed 586 actions (GET, POST, PUT, PATCH, or DELETE). 588 5.4. CBOR Data Formats 590 The /token resource (called "endpoint" in OAuth 2.0), defined in 591 Section 3.2 of [RFC6749], is used by the client to obtain an access 592 token. Requests sent to the /token resource use the HTTP POST method 593 and the payload includes a query component, which is formatted as 594 application/x-www-form-urlencoded. CoAP payloads cannot be formatted 595 in the same way which requires the /token resource on the AS to be 596 profiled. Appendix C defines a CBOR-based format for sending 597 parameters to the /token resource. 599 5.5. CBOR Web Token 601 CBOR Web Tokens (CWT) are defined in Appendix D as compact analogs of 602 JSON Web Tokens (JWT) [RFC7519]. CWTs uses COSE [I-D.ietf-cose-msg] 603 to offer similar, but more compact security services. CWT supports 604 PoP token functionality. 606 6. Deployment Scenarios 608 There is a large variety of IoT deployments, as is indicated in 609 Appendix A, and this section highlights common variants. This 610 section is not normative but illustrates how the framework can be 611 applied. 613 For each of the deployment variants there are a number of possible 614 security setups between clients, resource servers and authorization 615 servers. The main focus in the following subsections is on how 616 authorization of a client request for a resource hosted by a RS is 617 performed. This requires us to also consider how these requests and 618 responses between the clients and the resource servers are secured. 620 The security protocols between other pairs of nodes in the 621 architecture, namely client-to-AS and RS-to-AS, are not detailed in 622 these examples. Different security protocols may be used on 623 transport or application layer. 625 Note: We use the CBOR diagnostic notation for examples of requests 626 and responses. 628 6.1. Client and Resource Server are Offline 630 In this scenario we consider the case where both the resource server 631 and the client are offline, i.e., they are not connected to the AS at 632 the time of the resource request. This access procedure involves 633 steps A, B, C, and F of Figure 1, but assumes that step A and B have 634 been carried out during a phase when the client had connectivity to 635 AS. 637 Since the resource server must be able to verify the access token 638 locally, self-contained access tokens must be used. 640 This example shows the interactions between a client, the 641 authorization server and a temperature sensor acting as a resource 642 server. Message exchanges A and B are shown in Figure 2. 644 A: The client first generates a public-private key pair used for 645 communication security with the RS. 647 The client sends the POST request to /token at AS. The request 648 contains the public key of the client and the Audience parameter 649 set to "tempSensorInLivingRoom", a value the that the temperature 650 sensor identifies itself with. The AS evaluates the request and 651 authorizes the client to access the resource. 653 B: The AS responds with a PoP token and client information. The 654 PoP token contains the public key of the client, while the client 655 information contains the public key of the RS. For communication 656 security this example uses DTLS with raw public keys between the 657 client and the RS. 659 Note: In this example we assume that the client knows what 660 resource it wants to access, and is therefore able to request 661 specific audience and scope claims for the access token. 663 Authorization 664 Client Server 665 | | 666 | | 667 A: +-------->| Header: POST (Code=0.02) 668 | POST | Uri-Path:"token" 669 | | Payload: 670 | | 671 B: |<--------+ Header: 2.05 Content 672 | | Content-Type: application/cbor 673 | 2.05 | Payload: 674 | | 676 Figure 2: Token Request and Response Using Client Credentials. 678 The information contained in the Request-Payload and the Response- 679 Payload is shown in Figure 3. 681 Request-Payload : 682 { 683 "grant_type" : "client_credentials", 684 "aud" : "tempSensorInLivingRoom", 685 "client_id" : "myclient", 686 "client_secret" : "qwerty" 687 } 689 Response-Payload : 690 { 691 "access_token" : b64'SlAV32hkKG ...', 692 "token_type" : "pop", 693 "csp" : "DTLS", 694 "key" : b64'eyJhbGciOiJSU0ExXzUi ...' 695 } 697 Figure 3: Request and Response Payload Details. 699 The content of the "key" parameter and the access token are shown in 700 Figure 4 and Figure 5. 702 { 703 "kid" : b64'c29tZSBwdWJsaWMga2V5IGlk', 704 "kty" : "EC", 705 "crv" : "P-256", 706 "x" : b64'MKBCTNIcKUSDii11ySs3526iDZ8AiTo7Tu6KPAqv7D4', 707 "y" : b64'4Etl6SRW2YiLUrN5vfvVHuhp7x8PxltmWWlbbM4IFyM' 708 } 710 Figure 4: Public Key of the RS. 712 { 713 "aud" : "tempSensorInLivingRoom", 714 "iat" : "1360189224", 715 "cnf" : { 716 "jwk" : { 717 "kid" : b64'1Bg8vub9tLe1gHMzV76e8', 718 "kty" : "EC", 719 "crv" : "P-256", 720 "x" : b64'f83OJ3D2xF1Bg8vub9tLe1gHMzV76e8Tus9uPHvRVEU', 721 "y" : b64'x_FEzRu9m36HLN_tue659LNpXW6pCyStikYjKIWI5a0' 722 } 723 } 724 } 726 Figure 5: Access Token including Public Key of the Client. 728 Messages C and F are shown in Figure 6 - Figure 7. 730 C: The client then sends the PoP token to the /authz-info resource 731 at the RS. This is a plain CoAP request, i.e. no DTLS/OSCOAP 732 between client and RS, since the token is integrity protected 733 between AS and RS. The RS verifies that the PoP token was created 734 by a known and trusted AS, is valid, and responds to the client. 735 The RS caches the security context together with authorization 736 information about this client contained in the PoP token. 738 The client and resource server run the DTLS handshake using the 739 raw public keys established in step B and C. 741 The client sends the CoAP request GET to /temperature on RS over 742 DTLS. The RS verifies that the request is authorized. 744 F: The RS responds with a resource representation over DTLS. 746 Resource 747 Client Server 748 | | 749 C: +-------->| Header: POST (Code=0.02) 750 | POST | Uri-Path:"authz-info" 751 | | Payload: SlAV32hkKG ... 752 | | (access token) 753 | | 754 |<--------+ Header: 2.04 Changed 755 | 2.04 | 756 | | 758 Figure 6: Access Token provisioning to RS 760 Resource 761 Client Server 762 | | 763 |<=======>| DTLS Connection Establishment 764 | | using Raw Public Keys 765 | | 766 | | 767 +-------->| Header: GET (Code=0.01) 768 | GET | Uri-Path: "temperature" 769 | | 770 | | 771 | | 772 F: |<--------+ Header: 2.05 Content 773 | 2.05 | Payload: {"t":"22.7"} 774 | | 776 Figure 7: Resource Request and Response protected by DTLS. 778 6.2. Resource Server Offline 780 In this deployment scenario we consider the case of an RS that may 781 not be able to access the AS at the time it receives an access 782 request from a client. We denote this case "RS offline", it involves 783 steps A, B, C and F of Figure 1. 785 If the RS is offline, then it must be possible for the RS to locally 786 validate the access token. This requires self-contained tokens to be 787 used. 789 The validity time for the token should always be chosen as short as 790 possible to reduce the possibility that a token contains out-of-date 791 authorization information. Therefore the value for the Expiration 792 Time claim ("exp") should be set only slightly larger than the value 793 for the Issuing Time claim ("iss"). A constrained RS with means to 794 reliably measure time must validate the expiration time of the access 795 token. 797 The following example shows interactions between a client (AC control 798 unit), an offline resource server (temperature sensor) and an 799 authorization server. The message exchanges A and B are shown in 800 Figure 8. 802 A: The client sends the request POST to /token at AS. The request 803 contains the Audience parameter set to "tempSensor109797", a value 804 that the temperature sensor identifies itself with. The scope the 805 client want's the AS to authorize the access token for is "owner", 806 which means that the token can be used to both read temperature 807 data and upgrade the firmware on the RS. The AS evaluates the 808 request and authorizes the client to access the resource. 810 B: The AS responds with a PoP token and client information. The 811 PoP token is wrapped in a COSE message, object secured content 812 from AS to RS. The client information contains a symmetric key. 813 In this case communication security between C and RS is OSCOAP 814 with an authenticated encryption algorithm. The client derives 815 two unidirectional security contexts to use with the resource 816 request and response messages. The access token includes the 817 claim "aif" with the authorized access that an owner of the 818 temperature device can enjoy. The "aif" claim, issued by the AS, 819 informs the RS that the owner of the access token, that can prove 820 the possession of a key is authorized to make a GET request 821 against the /tempC resource and a POST request on the /firmware 822 resource. 824 Authorization 825 Client Server 826 | | 827 | | 828 A: +-------->| Header: POST (Code=0.02) 829 | POST | Uri-Path: "token" 830 | | Payload: 831 | | 832 B: |<--------+ Header: 2.05 Content 833 | | Content-Type: application/cbor 834 | 2.05 | Payload: 835 | | 836 | | 838 Figure 8: Token Request and Response 840 The information contained in the Request-Payload and the Response- 841 Payload is shown in Figure 9. 843 Request-Payload: 844 { 845 "grant_type" : "client_credentials", 846 "client_id" : "myclient", 847 "client_secret" : "qwerty", 848 "aud" : "tempSensor109797", 849 "scope" : "owner" 850 } 852 Response-Payload: 853 { 854 "access_token": b64'SlAV32hkKG ...', 855 "token_type" : "pop", 856 "csp" : "OSCOAP", 857 "key" : b64'eyJhbGciOiJSU0ExXzUi ...' 858 } 860 Figure 9: Request and Response Payload for RS offline 862 Figure 10 shows examples of the key and the access_token parameters 863 of the Response-Payload, decoded to CBOR. 865 access_token: 866 { 867 "aud" : "tempSensor109797", 868 "exp" : 1311281970, 869 "iat" : 1311280970, 870 "aif" : [["/tempC", 0], ["/firmware", 2]], 871 "cnf" : { 872 "ck":b64'JDLUhTMjU2IiwiY3R5Ijoi ...' 873 } 874 } 876 key: 877 { 878 "alg" : "AES_128_CCM_8", 879 "kid" : b64'U29tZSBLZXkgSWQ', 880 "k" : b64'ZoRSOrFzN_FzUA5XKMYoVHyzff5oRJxl-IXRtztJ6uE' 881 } 883 Figure 10: Access Token and symmetric key from the Response-Payload 885 Message exchanges C and F are shown in Figure 11 and Figure 12. 887 C: The client then sends the PoP token to the /authz-info resource 888 in the RS. This is a plain CoAP request, i.e. no DTLS/OSCOAP 889 between client and RS, since the token is integrity protected 890 between AS and RS. The RS verifies that the PoP token was created 891 by a known and trusted AS, is valid, and responds to the client. 892 The RS derives and caches the security contexts together with 893 authorization information about this client contained in the PoP 894 token. 896 The client sends the CoAP requests GET to /tempC on the RS using 897 OSCOAP. The RS verifies the request and that it is authorized. 899 F: The RS responds with a protected status code using OSCOAP. The 900 client verifies the response. 902 Resource 903 Client Server 904 | | 905 C: +-------->| Header: POST (Code=0.02) 906 | POST | Uri-Path:"authz-info" 907 | | Payload: 908 | | 909 | | 910 |<--------+ Header: 2.04 Changed 911 | 2.04 | 912 | | 913 | | 915 Figure 11: Access Token provisioning to RS 917 Resource 918 Client Server 919 | | 920 +-------->| Header: GET (Code=0.01) 921 | GET | Object-Security: 922 | | (,,[Uri-Path:"tempC"],) 923 | | 924 F: |<--------+ Header: 2.05 Content 925 | 2.05 | Object-Security: 926 | | (,,[22.7 C],) 927 | | 929 Figure 12: Resource request and response protected by OSCOAP 931 In Figure 12 the GET request contains an Object-Security option and 932 an indication of the content of the COSE object: a sequence number 933 ("seq", starting from 0), a context identifier ("cid") indicating the 934 security context, the ciphertext containing the encrypted CoAP option 935 identifying the resource, and the Message Authentication Code ("tag") 936 which also covers the Code in the CoAP header. 938 The Object-Security ciphertext in the response [22.7 C] represents an 939 encrypted temperature reading. (The COSE object is actually carried 940 in the CoAP payload when possible but that is omitted to simplify 941 notation.) 943 6.3. Token Introspection with an Offline Client 945 In this deployment scenario we assume that a client is not be able to 946 access the AS at the time of the access request. Since the RS is, 947 however, connected to the back-end infrastructure it can make use of 948 token introspection. This access procedure involves steps A-F of 949 Figure 1, but assumes steps A and B have been carried out during a 950 phase when the client had connectivity to AS. 952 Since the client is assumed to be offline, at least for a certain 953 period of time, a pre-provisioned access token has to be long-lived. 954 The resource server may use its online connectivity to validate the 955 access token with the authorization server, which is shown in the 956 example below. 958 In the example we show the interactions between an offline client 959 (key fob), a resource server (online lock), and an authorization 960 server. We assume that there is a provisioning step where the client 961 has access to the AS. This corresponds to message exchanges A and B 962 which are shown in Figure 13. 964 A: The client sends the request using POST to /token at AS. The 965 request contains the Audience parameter set to "lockOfDoor4711", a 966 value the that the online door in question identifies itself with. 967 The AS generates an access token as on opaque string, which it can 968 match to the specific client, a targeted audience and a symmetric 969 key security context. 971 B: The AS responds with the an access token and client 972 information, the latter containing a symmetric key. Communication 973 security between C and RS will be OSCOAP with authenticated 974 encryption. 976 Authorization 977 Client Server 978 | | 979 | | 980 A: +-------->| Header: POST (Code=0.02) 981 | POST | Uri-Path:"token" 982 | | Payload: 983 | | 984 B: |<--------+ Header: 2.05 Content 985 | | Content-Type: application/cbor 986 | 2.05 | Payload: 987 | | 989 Figure 13: Token Request and Response using Client Credentials. 991 Authorization consent from the resource owner can be pre-configured, 992 but it can also be provided via an interactive flow with the resource 993 owner. An example of this for the key fob case could be that the 994 resource owner has a connected car, he buys a generic key that he 995 wants to use with the car. To authorize the key fob he connects it 996 to his computer that then provides the UI for the device. After that 997 OAuth 2.0 implicit flow is used to authorize the key for his car at 998 the the car manufacturers AS. 1000 The information contained in the Request-Payload and the Response- 1001 Payload is shown in Figure 14. 1003 Request-Payload: 1004 { 1005 "grant_type" : "token", 1006 "aud" : "lockOfDoor4711", 1007 "client_id" : "myclient", 1008 } 1010 Response-Payload: 1011 { 1012 "access_token" : b64'SlAV32hkKG ...' 1013 "token_type" : "pop", 1014 "csp" : "OSCOAP", 1015 "key" : b64'eyJhbGciOiJSU0ExXzUi ...' 1016 } 1018 Figure 14: Request and Response Payload for C offline 1020 The access token in this case is just an opaque string referencing 1021 the authorization information at the AS. 1023 C: Next, the client POSTs the access token to the /authz-info 1024 resource in the RS. This is a plain CoAP request, i.e. no DTLS/ 1025 OSCOAP between client and RS. Since the token is an opaque 1026 string, the RS cannot verify it on its own, and thus defers to 1027 respond the client with a status code until step E and only 1028 acknowledges on the CoAP message layer (indicated with a dashed 1029 line). 1031 Resource 1032 Client Server 1033 | | 1034 C: +-------->| Header: POST (T=CON, Code=0.02 1035 | POST | Token 0x2a12) 1036 | | Uri-Path:"authz-info" 1037 | | Payload: SlAV32hkKG ... 1038 | | (access token) 1039 | | 1040 |<- - - - + Header: T=ACK 1041 | | 1043 Figure 15: Access Token provisioning to RS 1045 D: The RS forwards the token to the /introspect resource on the 1046 AS. Introspection assumes a secure connection between the AS and 1047 the RS, e.g. using DTLS or OSCOAP, which is not detailed in this 1048 example. 1050 E: The AS provides the introspection response containing claims 1051 about the token. This includes the confirmation key (cnf) claim 1052 that allows the RS to verify the client's proof of possession in 1053 step F. 1055 After receiving message E, the RS responds to the client's POST in 1056 step C with Code 2.04 (Changed), using CoAP Token 0x2a12. This 1057 step is not shown in the figures. 1059 Resource Authorization 1060 Server Server 1061 | | 1062 D: +--------->| Header: POST (Code=0.02) 1063 | POST | Uri-Path: "introspect" 1064 | | Payload: 1065 | | 1066 E: |<---------+ Header: 2.05 Content 1067 | 2.05 | Content-Type: application/cbor) 1068 | | Payload: 1069 | | 1071 Figure 16: Token Introspection for C offline 1073 The information contained in the Request-Payload and the Response- 1074 Payload is shown in Figure 17. 1076 Request-Payload: 1077 { 1078 "token" : b64'SlAV32hkKG...', 1079 "client_id" : "myRS", 1080 "client_secret" : "ytrewq" 1081 } 1083 Response-Payload: 1084 { 1085 "active" : true, 1086 "aud" : "lockOfDoor4711", 1087 "scope" : "open, close", 1088 "iat" : 1311280970, 1089 "cnf" : { 1090 "ck" : b64'JDLUhTMjU2IiwiY3R5Ijoi ...' 1091 } 1092 } 1094 Figure 17: Request and Response Payload for Introspection 1096 The client sends the CoAP requests PUT 1 (= "close the lock") to / 1097 lock on RS using OSCOAP with a security context derived from the 1098 key supplied in step B. The RS verifies the request with the key 1099 supplied in step E and that it is authorized by the token supplied 1100 in step C. 1102 F: The RS responds with a protected status code using OSCOAP. The 1103 client verifies the response. 1105 Resource 1106 Client Server 1107 | | 1108 +-------->| Header: PUT (Code=0.03) 1109 | PUT | Object-Security: 1110 | | (,,[Uri-Path:"lock", 1],) 1111 | | 1112 F: |<--------+ Header: 2.04 Changed 1113 | 2.04 | Object-Security: 1114 | | (,,,) 1115 | | 1117 Figure 18: Resource request and response protected by OSCOAP 1119 The Object-Security ciphertext [...] of the PUT request contains CoAP 1120 options that are encrypted, as well as the payload value '1' which is 1121 the value of PUT to the door lock. 1123 In this example there is no ciphertext of the PUT response, but "tag" 1124 contains a MAC which covers the request sequence number and context 1125 identifier as well as the Code which allows the Client to verify that 1126 this actuator command was well received (door is locked). 1128 6.4. Always-On Connectivity 1130 A popular deployment scenario for IoT devices is to have them always 1131 be connected to the Internet so that they can be reachable to receive 1132 commands. As a continuation from the previous scenarios we assume 1133 that both the client and the RS are online at the time of the access 1134 request. 1136 If the client and the resource server are online then the AS should 1137 be configured to issue short-lived access tokens for the resource to 1138 the client. The resource server must then validate self-contained 1139 access tokens or otherwise must use token introspection to obtain the 1140 up-to-date claim information. If transmission costs are high or the 1141 channel is lossy, the CWT token format may be used instead of a JWT 1142 to reduce the volume of network traffic. In terms of messaging this 1143 deployment scenario uses the patterns described in the previous sub- 1144 sections. 1146 Note that despite the lack of connectivity constraints there may 1147 still be other restrictions a deployment may face. 1149 6.5. Token-less Authorization 1151 In this deployment scenario we consider the case of an RS which is 1152 severely energy constrained, sleeps most of the time and need to have 1153 a tight messaging budget. It is not only infeasible to access the AS 1154 at the time of the access request, as in the "RS offline" case 1155 Section 6.2, it must be offloaded as much message communication as 1156 possible. 1158 OAuth 2.0 is already an efficient protocol in terms of message 1159 exchanges and can be further optimized by compact encodings of 1160 tokens. The scenario illustrated in this section goes beyond that 1161 and removes the access tokens from the protocol. This may be 1162 considered a degenerate case of OAuth 2.0 but it allows us to do two 1163 things: 1165 1. The common case where authorization is performed by means of 1166 authentication fits into the same protocol framework. 1167 Authentication protocol and key is specified by client 1168 information, and access token is omitted. 1170 2. Authentication, and thereby authorization, may even be implicit, 1171 i.e. anyone with access to the right key is authorized to access 1172 the protected resource. 1174 In case 2., the RS does not need to receive any message from the 1175 client, and therefore enables offloading recurring resource request 1176 and response processing to a third party, such as a Message Broker 1177 (MB) in a publish-subscribe setting. 1179 This scenario involves steps A, B, C and F of Figure 1 and four 1180 parties: a client (subscriber), an offline RS (publisher), a trusted 1181 AS, and a MB, not necessarily trusted with access to the plain text 1182 publications. Message exchange A, B is shown in Figure 19. 1184 A: The client sends the request POST to /token at AS. The request 1185 contains the Audience parameter set to "birchPollenSensor301", a 1186 value that characterizes a certain pollen sensor resource. The AS 1187 evaluates the request and authorizes the client to access the 1188 resource. 1190 B: The AS responds with an empty token and client information with 1191 a security context to be used by the client. The empty token 1192 signifies that authorization is performed by means of 1193 authentication using the communication security protocol indicated 1194 with "csp". In this case it is object security of content (OSCON) 1195 i.e. protection of CoAP payload only. The security context 1196 contains the symmetric decryption key and a public signature 1197 verification key of the RS. 1199 Authorization 1200 Client Server 1201 | | 1202 | | 1203 A: +-------->| Header: POST (Code=0.02) 1204 | POST | Uri-Path:"token" 1205 | | Payload: 1206 | | 1207 B: |<--------+ Header: 2.05 Content 1208 | | Content-Type: application/cbor 1209 | 2.05 | Payload: 1210 | | 1211 | | 1213 Figure 19: Token Request and Response 1215 The information contained in the Request-Payload and the Response- 1216 Payload is shown in Figure 20. 1218 Request-Payload : 1219 { 1220 "grant_type" : "client_credentials", 1221 "aud" : "birchPollenSensor301", 1222 "client_id" : "myclient", 1223 "client_secret" : "qwerty" 1224 } 1226 Response-Payload : 1227 { 1228 "access_token" : NULL, 1229 "token_type" : "none", 1230 "csp" : "OSCON", 1231 "key" : b64'eyJhbGciOiJSU0ExXzUi ...' 1232 } 1234 Figure 20: Request and Response Payload for RS severely constrained 1236 The content of the "key" parameter is shown in Figure 21. 1238 key : 1239 { 1240 "alg" : "AES_128_CTR_ECDSA", 1241 "kid" : b64'c29tZSBvdGhlciBrZXkgaWQ'; 1242 "k" : b64'ZoRSOrFzN_FzUA5XKMYoVHyzff5oRJxl-IXRtztJ6uE', 1243 "crv" : "P-256", 1244 "x" : b64'MKBCTNIcKUSDii11ySs3526iDZ8AiTo7Tu6KPAqv7D4', 1245 "y" : b64'4Etl6SRW2YiLUrN5vfvVHuhp7x8PxltmWWlbbM4IFyM' 1246 } 1248 Figure 21: The 'key' Parameter 1250 The RS, which sleeps most of the time, occasionally wakes up, 1251 measures the number birch pollens per cubic meters, publishes the 1252 measurements to the MB, and then returns to sleep. See Figure 22. 1254 In this case the birch pollen count stopped at 270, which is 1255 encrypted with the symmetric key and signed with the private key of 1256 the RS. The MB verifies that the message originates from RS using 1257 the public key of RS, that it is not a replay of an old measurement 1258 using the sequence number of the OSCON COSE profile, and caches the 1259 object secured content. The MB does not have the secret key so is 1260 unable to read the plain text measurement. 1262 Message exchanges C and F are shown in Figure 22. 1264 C: Since there is no access token, the client does not address the 1265 /authz-info resource in the RS. The client sends the CoAP request 1266 GET to /birchPollen on MB which is a plain CoAP request. 1268 F: The MB responds with the cached object secured content. 1270 Message Resource 1271 Client Broker Server 1272 | | | 1273 | |<--------| Header: PUT (Code=0.02) 1274 | | PUT | Uri-Path: "birchPollen" 1275 | | | Payload: (,,["270"],) 1276 | | | 1277 | |-------->| Header: 2.04 Changed 1278 | | 2.04 | 1279 | | 1280 | | 1281 C: +-------->| Header: GET (Code=0.01) 1282 | GET | Uri-Path: "birchPollen" 1283 | | 1284 | | 1285 F: |<--------+ Header: 2.05 Content 1286 | 2.05 | Payload: (,,["270"],) 1287 | | 1289 Figure 22: Sensor measurement protected by COSE 1291 The payload is a COSE message consisting of sequence number 'seq' 1292 stepped by the RS for each publication, the context identifier 'cid' 1293 in this case coinciding with the key identifier 'kid' of Figure 21, 1294 the encrypted measurement and the signature by the RS. 1296 Note that the same COSE message format may be used as in OSCOAP but 1297 that only CoAP payload is protected in this case. 1299 The authorization step is implicit, so while any client could request 1300 access the COSE object, only authorized clients have access to the 1301 symmetric key needed to decrypt the content. 1303 Note that in this case the order of the message exchanges A,B and C,F 1304 could in principle be interchanged, i.e. the client could first 1305 request and obtain the protected resource in steps C,F; and after 1306 that request client information containing the keys decrypt and 1307 verify the message. 1309 6.6. Securing Group Communication 1310 There are use cases that require securing communication between a 1311 (group of) senders and a group of receivers. One prominent example 1312 is lighting. Often, a set of lighting nodes (e.g., luminaires, wall- 1313 switches, sensors) are grouped together and only authorized members 1314 of the group must be able read and process messages. Additionally, 1315 receivers of group messages must be able to verify the integrity of 1316 received messages as being generated within the group. 1318 The requirements for securely communicating in such group use cases 1319 efficiently is outlined in [I-D.somaraju-ace-multicast] along with an 1320 architectural description that aligns with the content of this 1321 document. The requirements for conveying the necessary identifiers 1322 to reference groups and also the process of commissioning devices can 1323 be accomplished using the protocol described in this document. For 1324 details about the lighting-unique use case aspects, the architecture, 1325 as well as other multicast-specific considerations we refer the 1326 reader to [I-D.somaraju-ace-multicast]. 1328 7. Security Considerations 1330 The entire document is about security. Security considerations 1331 applicable to authentication and authorization in RESTful 1332 environments provided in OAuth 2.0 [RFC6749] apply to this work, as 1333 well as the security considerations from [I-D.ietf-ace-actors]. 1334 Furthermore [RFC6819] provides additional security considerations for 1335 OAuth which apply to IoT deployments as well. Finally 1336 [I-D.ietf-oauth-pop-architecture] discusses security and privacy 1337 threats as well as mitigation measures for Proof-of-Possession 1338 tokens. 1340 8. IANA Considerations 1342 TBD 1344 9. Acknowledgments 1346 We would like to thank Eve Maler for her contributions to the use of 1347 OAuth 2.0 and UMA in IoT scenarios, Robert Taylor for his discussion 1348 input, and Malisa Vucinic for his input on the ACRE proposal 1349 FIXME:REF which was one source of inspiration for this work. 1350 Finally, we would like to thank the ACE working group in general for 1351 their feedback. 1353 10. References 1355 10.1. Normative References 1357 [I-D.bormann-core-ace-aif] 1358 Bormann, C., "An Authorization Information Format (AIF) 1359 for ACE", draft-bormann-core-ace-aif-02 (work in 1360 progress), March 2015. 1362 [I-D.ietf-cose-msg] 1363 Schaad, J. and B. Campbell, "CBOR Encoded Message Syntax", 1364 draft-ietf-cose-msg-05 (work in progress), September 2015. 1366 [I-D.ietf-oauth-introspection] 1367 Richer, J., "OAuth 2.0 Token Introspection", draft-ietf- 1368 oauth-introspection-09 (work in progress), May 2015. 1370 [I-D.ietf-oauth-pop-architecture] 1371 Hunt, P., Richer, J., Mills, W., Mishra, P., and H. 1372 Tschofenig, "OAuth 2.0 Proof-of-Possession (PoP) Security 1373 Architecture", draft-ietf-oauth-pop-architecture-02 (work 1374 in progress), July 2015. 1376 [I-D.ietf-oauth-pop-key-distribution] 1377 Bradley, J., Hunt, P., Jones, M., and H. Tschofenig, 1378 "OAuth 2.0 Proof-of-Possession: Authorization Server to 1379 Client Key Distribution", draft-ietf-oauth-pop-key- 1380 distribution-01 (work in progress), March 2015. 1382 [I-D.selander-ace-object-security] 1383 Selander, G., Mattsson, J., and L. Seitz, "March 9, 2015", 1384 draft-selander-ace-object-security-01 (work in progress), 1385 March 2015. 1387 [I-D.wahlstroem-ace-oauth-introspection] 1388 Wahlstroem, E., "OAuth 2.0 Introspection over the 1389 Constrained Application Protocol (CoAP)", draft- 1390 wahlstroem-ace-oauth-introspection-01 (work in progress), 1391 March 2015. 1393 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1394 Requirement Levels", BCP 14, RFC 2119, March 1997. 1396 [RFC6347] Rescorla, E. and N. Modadugu, "Datagram Transport Layer 1397 Security Version 1.2", RFC 6347, January 2012. 1399 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 1400 Application Protocol (CoAP)", RFC 7252, June 2014. 1402 10.2. Informative References 1404 [I-D.ietf-ace-actors] 1405 Gerdes, S., Seitz, L., Selander, G., and C. Bormann, "An 1406 architecture for authorization in constrained 1407 environments", draft-ietf-ace-actors-00 (work in 1408 progress), August 2015. 1410 [I-D.ietf-core-block] 1411 Bormann, C. and Z. Shelby, "Block-wise transfers in CoAP", 1412 draft-ietf-core-block-18 (work in progress), September 1413 2015. 1415 [I-D.somaraju-ace-multicast] 1416 Somaraju, A., Kumar, S., and H. Tschofenig, "Multicast 1417 Security for the Lighting Domain", draft-somaraju-ace- 1418 multicast-00 (work in progress), July 2015. 1420 [RFC4680] Santesson, S., "TLS Handshake Message for Supplemental 1421 Data", RFC 4680, October 2006. 1423 [RFC4949] Shirey, R., "Internet Security Glossary, Version 2", RFC 1424 4949, August 2007. 1426 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 1427 (TLS) Protocol Version 1.2", RFC 5246, DOI 10.17487/ 1428 RFC5246, August 2008, 1429 . 1431 [RFC6690] Shelby, Z., "Constrained RESTful Environments (CoRE) Link 1432 Format", RFC 6690, DOI 10.17487/RFC6690, August 2012, 1433 . 1435 [RFC6749] Hardt, D., "The OAuth 2.0 Authorization Framework", RFC 1436 6749, October 2012. 1438 [RFC6819] Lodderstedt, T., Ed., McGloin, M., and P. Hunt, "OAuth 2.0 1439 Threat Model and Security Considerations", RFC 6819, DOI 1440 10.17487/RFC6819, January 2013, 1441 . 1443 [RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object 1444 Representation (CBOR)", RFC 7049, October 2013. 1446 [RFC7159] Bray, T., "The JavaScript Object Notation (JSON) Data 1447 Interchange Format", RFC 7159, March 2014. 1449 [RFC7228] Bormann, C., Ersue, M., and A. Keranen, "Terminology for 1450 Constrained-Node Networks", RFC 7228, May 2014. 1452 [RFC7231] Fielding, R. and J. Reschke, "Hypertext Transfer Protocol 1453 (HTTP/1.1): Semantics and Content", RFC 7231, June 2014. 1455 [RFC7519] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token 1456 (JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015, 1457 . 1459 Appendix A. Design Justification 1461 This section provides further insight into the design decisions of 1462 the solution documented in this document. Section 3 lists several 1463 building blocks and briefly summarizes their importance. The 1464 justification for offering some of those building blocks, as opposed 1465 to using OAuth 2.0 as is, is given below. 1467 Common IoT constraints are: 1469 Low Power Radio: 1471 Many IoT devices are equipped with a small battery which needs to 1472 last for a long time. For many constrained wireless devices the 1473 highest energy cost is associated to transmitting or receiving 1474 messages. It is therefore important to keep the total 1475 communication overhead low, including minimizing the number and 1476 size of messages sent and received, which has an impact of choice 1477 of message format and protocol. By using CoAP over UDP, and CBOR 1478 encoded messages some of these aspects are addressed. Security 1479 protocols contribute to the communication overhead and can in some 1480 cases can be optimized. For example authentication and key 1481 establishment may in certain cases where security requirements so 1482 allows be replaced by provisioning of security context by a 1483 trusted third party, using transport or application layer 1484 security. 1486 Low CPU Speed: 1488 Some IoT devices are equipped with processors that are 1489 significantly slower than those found in most current devices on 1490 the Internet. This typically has implications on what timely 1491 cryptographic operations a device is capable to perform, which in 1492 turn impacts e.g. protocol latency. Symmetric key cryptography 1493 may be used instead of the computationally more expensive public 1494 key cryptography where the security requirements so allows, but 1495 this may also require support for trusted third party assisted 1496 secret key establishment using transport or application layer 1497 security. 1499 Small Amount of Memory: 1501 Microcontrollers embedded in IoT devices are often equipped with 1502 small amount of RAM and flash memory, which places limitations 1503 what kind of processing can be performed and how much code can be 1504 put on those devices. To reduce code size fewer and smaller 1505 protocol implementations can be put on the firmware of such a 1506 device. In this case, CoAP may be used instead of HTTP, symmetric 1507 key cryptography instead of public key cryptography, and CBOR 1508 instead of JSON. Authentication and key establishment protocol, 1509 e.g. the DTLS handshake, in comparison with assisted key 1510 establishment also has an impact on memory and code. 1512 User Interface Limitations: 1514 Protecting access to resources is both an important security as 1515 well as privacy feature. End users and enterprise customers do 1516 not want to give access to the data collected by their IoT device 1517 or to functions it may offer to third parties. Since the 1518 classical approach of requesting permissions from end users via a 1519 rich user interface does not work in many IoT deployment scenarios 1520 these functions need to be delegated to user controlled devices 1521 that are better suitable for such tasks, such as smart phones and 1522 tablets. 1524 Communication Constraints: 1526 In certain constrained settings an IoT device may not be able to 1527 communicate with a given device at all times. Devices may be 1528 sleeping, or just disconnected from the Internet because of 1529 general lack of connectivity in the area, for cost reasons, or for 1530 security reasons, e.g. to avoid an entry point for Denial-of- 1531 Service attacks. 1533 The communication interactions this framework builds upon (as 1534 shown graphically in Figure 1) may be accomplished using a variety 1535 of different protocols, and not all parts of the message flow are 1536 used in all applications due to the communication constraints. 1537 While we envision deployments to make use of CoAP we explicitly 1538 want to support HTTP, HTTP/2 or specific protocols, such as 1539 Bluetooth Smart communication, which does not necessarily use IP. 1540 The latter raises the need for application layer security over the 1541 various interfaces. 1543 Appendix B. Optimizations 1545 This section sketches some potential optimizations to the presented 1546 solution. 1548 Access token in DTLS handshake 1550 In the case of CSP=DTLS/TLS, the access token provisoning exchange 1551 in step C of the protocol may be embedded in the security 1552 handshake. Different solutions are possible, where one 1553 standardized method would be the use of the TLS supplemental data 1554 extension [RFC4680] for transferring the access token. 1556 Reference token and introspection 1558 In case of introspection it may be useful with access tokens which 1559 are not self-contained (also known as "reference tokens") that are 1560 used to lookup detailed information about the authorization. The 1561 RS uses the introspection message exchange not only for validating 1562 token claims, but also for obtaining claims that potentially were 1563 not known at the time when the access token was issued. 1565 A reference token can be made much more compact than a CWT, since 1566 it does not need to contain any of claims that it represents. 1567 This could be very useful in particular if the client is 1568 constrained and offline most of the time. 1570 Reference token in CoAP option 1572 While large access tokens must be sent in CoAP payload, if the 1573 access token is known to be of a certain limited size, for example 1574 in the case of a reference token, then it would be favorable to 1575 combine the access token provisioning request with the resource 1576 request to the RS. 1578 One way to achieve this is to define a new CoAP option for 1579 carrying reference tokens, called "Ref-Token" as shown in the 1580 example in Figure 23. 1582 Resource 1583 Client Server 1584 | | 1585 C: +-------->| Header: PUT (Code=0.02) 1586 | PUT | Ref-Token:SlAV32hkKG 1587 | | Object-Security: 1588 | | ,,[Uri-Path:"lock", 1],) 1589 | | 1590 . . 1591 . . 1592 . . 1593 | | 1594 F: |<--------+ Header: 2.04 Changed 1595 | 2.04 | Object-Security: 1596 | | (,,,) 1597 | | 1599 Figure 23: Reference Token in CoAP Option 1601 Appendix C. CoAP and CBOR profiles for OAuth 2.0 1603 Many IoT devices can support OAuth 2.0 without any additional 1604 extensions, but for certain constrained settings additional profiling 1605 is needed. In this appendix we define CoAP resources for the HTTP 1606 based token and introspection endpoints used in vanilla OAuth 2.0. 1607 We also define a CBOR alternative to the JSON and form based POST 1608 structures used in HTTP. 1610 C.1. Profile for Token resource 1612 The token resource is used by the client to obtain an access token by 1613 presenting its authorization grant or client credentials to the / 1614 token resource the AS. 1616 C.1.1. Token Request 1618 The client makes a request to the token resource by sending a CBOR 1619 structure with the following attributes. 1621 grant_type: 1623 REQUIRED. The grant type, "code", "client_credentials", 1624 "password" or others. 1626 client_id: 1628 OPTIONAL. The client identifier issued to the holder of the token 1629 (client or RS) during the registration process. 1631 client_secret: 1633 OPTIONAL. The client secret. 1635 scope: 1637 OPTIONAL. The scope of the access request as described by 1638 Section 3.1. 1640 aud: 1642 OPTIONAL. Service-specific string identifier or list of string 1643 identifiers representing the intended audience for this token, as 1644 defined in CWT Appendix D. 1646 alg: 1648 OPTIONAL. The value in the 'alg' parameter together with value 1649 from the 'token_type' parameter allow the client to indicate the 1650 supported algorithms for a given token type. 1652 key: 1654 OPTIONAL. This field contains information about the public key 1655 the client would like to bind to the access token in the COSE Key 1656 Structure format. 1658 The parameters defined above use the following CBOR major types. 1660 /-----------+--------------+-----------------------\ 1661 | Value | Major Type | Key | 1662 |-----------+--------------+-----------------------| 1663 | 0 | 0 | grant_type | 1664 | 1 | 0 | client_id | 1665 | 2 | 0 | client_secret | 1666 | 3 | 0 | scope | 1667 | 4 | 0 | aud | 1668 | 5 | 0 | alg | 1669 | 6 | 0 | key | 1670 \-----------+--------------+-----------------------/ 1672 Figure 24: CBOR mappings used in token requests 1674 C.1.2. Token Response 1676 The AS responds by sending a CBOR structure with the following 1677 attributes. 1679 access_token: 1681 REQUIRED. The access token issued by the authorization server. 1683 token_type: 1685 REQUIRED. The type of the token issued. "pop" is recommended. 1687 key: 1689 REQUIRED, if symmetric key cryptography is used. A COSE Key 1690 Structure containing the symmetric proof of possession key. The 1691 members of the structure can be found in section 7.1 of 1692 [I-D.ietf-cose-msg]. 1694 csp: 1696 REQUIRED. Information on what communication protocol to use in 1697 the communication between the client and the RS. Details on 1698 possible values can be found in Section 5.1. 1700 scope: 1702 OPTIONAL, if identical to the scope requested by the client; 1703 otherwise, REQUIRED. 1705 alg: 1707 OPTIONAL. The 'alg' parameter provides further information about 1708 the algorithm, such as whether a symmetric or an asymmetric 1709 crypto-system is used. 1711 The parameters defined above use the following CBOR major types. 1713 /-----------+--------------+-----------------------\ 1714 | Value | Major Type | Key | 1715 |-----------+--------------+-----------------------| 1716 | 0 | 0 | access_token | 1717 | 1 | 0 | token_type | 1718 | 2 | 0 | key | 1719 | 3 | 0 | csp | 1720 | 4 | 0 | scope | 1721 | 5 | 0 | alg | 1722 \-----------+--------------+-----------------------/ 1724 Figure 25: CBOR mappings used in token responses 1726 C.2. CoAP Profile for OAuth Introspection 1728 This section defines a way for a holder of access tokens, mainly 1729 clients and RS's, to get metadata like validity status, claims and 1730 scopes found in access token. The OAuth Token Introspection 1731 specification [I-D.ietf-oauth-introspection] defines a way to 1732 validate the token using HTTP POST or HTTP GET. This document reuses 1733 the work done in the OAuth Token Introspection and defines a mapping 1734 of the request and response to CoAP [RFC7252] to be used by 1735 constrained devices. 1737 C.2.1. Introspection Request 1739 The token holder makes a request to the Introspection CoAP resource 1740 by sending a CBOR structure with the following attributes. 1742 token: 1744 REQUIRED. The string value of the token. 1746 resource_id: 1748 OPTIONAL. A service-specific string identifying the resource that 1749 the client doing the introspection is asking about. 1751 client_id: 1753 OPTIONAL. The client identifier issued to the holder of the token 1754 (client or RS) during the registration process. 1756 client_secret: 1758 OPTIONAL. The client secret. 1760 The parameters defined above use the following CBOR major types: 1762 /-----------+--------------+-----------------------\ 1763 | Value | Major Type | Key | 1764 |-----------+--------------+-----------------------| 1765 | 0 | 0 | token | 1766 | 1 | 0 | resource_id | 1767 | 2 | 0 | client_id | 1768 | 3 | 0 | client_secret | 1769 \-----------+--------------+-----------------------/ 1771 Figure 26: CBOR Mappings to Token Introspection Request Parameters. 1773 C.2.2. Introspection Response 1775 If the introspection request is valid and authorized, the 1776 authorization server returns a CoAP message with the response encoded 1777 as a CBOR structure in the payload of the message. If the request 1778 failed client authentication or is invalid, the authorization server 1779 returns an error response using the CoAP 4.00 'Bad Request' response 1780 code. 1782 The JSON structure in the payload response includes the top-level 1783 members defined in Section 2.2 in the OAuth Token Introspection 1784 specification [I-D.ietf-oauth-introspection]. It is RECOMMENDED to 1785 only return the 'active' attribute considering constrained nature of 1786 CoAP client and server networks. 1788 Introspection responses in CBOR use the following mappings: 1790 active: 1792 REQUIRED. The active key is an indicator of whether or not the 1793 presented token is currently active. The specifics of a token's 1794 "active" state will vary depending on the implementation of the 1795 authorization server, and the information it keeps about its 1796 tokens, but a "true" value return for the "active" property will 1797 generally indicate that a given token has been issued by this 1798 authorization server, has not been revoked by the resource owner, 1799 and is within its given time window of validity (e.g., after its 1800 issuance time and before its expiration time). 1802 scope: 1804 OPTIONAL. A string containing a space-separated list of scopes 1805 associated with this token, in the format described in Section 3.3 1806 of OAuth 2.0 [RFC6749]. 1808 client_id: 1810 OPTIONAL. Client identifier for the client that requested this 1811 token. 1813 username: 1815 OPTIONAL. Human-readable identifier for the resource owner who 1816 authorized this token. 1818 token_type: 1820 OPTIONAL. Type of the token as defined in Section 5.1 of OAuth 1821 2.0 [RFC6749] or PoP token. 1823 exp: 1825 OPTIONAL. Integer timestamp, measured in the number of seconds 1826 since January 1 1970 UTC, indicating when this token will expire, 1827 as defined in CWT Appendix D. 1829 iat: 1831 OPTIONAL. Integer timestamp, measured in the number of seconds 1832 since January 1 1970 UTC, indicating when this token will expire, 1833 as defined in CWT Appendix D. 1835 nbf: 1837 OPTIONAL. Integer timestamp, measured in the number of seconds 1838 since January 1 1970 UTC, indicating when this token will expire, 1839 as defined in CWT Appendix D. 1841 sub: 1843 OPTIONAL. Subject of the token, as defined in CWT Appendix D. 1844 Usually a machine-readable identifier of the resource owner who 1845 authorized this token. 1847 aud: 1849 OPTIONAL. Service-specific string identifier or list of string 1850 identifiers representing the intended audience for this token, as 1851 defined in CWT Appendix D. 1853 iss: 1855 OPTIONAL. String representing the issuer of this token, as 1856 defined in CWT Appendix D. 1858 cti: 1860 OPTIONAL. String identifier for the token, as defined in CWT 1861 Appendix D 1863 The parameters defined above use the following CBOR major types: 1865 /-----------+--------------+-----------------------\ 1866 | Value | Major Type | Key | 1867 |-----------+--------------+-----------------------| 1868 | 0 | 0 | active | 1869 | 1 | 0 | scopes | 1870 | 2 | 0 | client_id | 1871 | 3 | 0 | username | 1872 | 4 | 0 | token_type | 1873 | 5 | 0 | exp | 1874 | 6 | 0 | iat | 1875 | 7 | 0 | nbf | 1876 | 8 | 0 | sub | 1877 | 9 | 0 | aud | 1878 | 10 | 0 | iss | 1879 | 11 | 0 | cti | 1880 \-----------+--------------+-----------------------/ 1882 Figure 27: CBOR Mappings to Token Introspection Response Parameters. 1884 Appendix D. CBOR Web Token (CWT) 1886 CBOR Web Token (CWT) is a compact means of representing claims to be 1887 transferred between two parties. CWT is a profile of JSON Web Tokens 1888 that is optimized for constrained devices. The claims in a CWT are 1889 encoded in CBOR and COSE is used for signature and encryption. A 1890 claim is a piece of information asserted about a subject. A claim is 1891 represented as a name/value pair consisting of a Claim Name and a 1892 Claim Value. 1894 The suggested pronunciation of CWT is the same as the English word 1895 "cot". 1897 The set of claims that a CWT must contain to be considered valid is 1898 context dependent and is outside the scope of this specification. 1899 Specific applications of CWTs will require implementations to 1900 understand and process some claims in particular ways. However, in 1901 the absence of such requirements, all claims that are not understood 1902 by implementations MUST be ignored. 1904 D.1. Claim Names 1906 The following Claim Names are asserted by the AS and interpreted by 1907 the RS. None of the claims defined below are intended to be 1908 mandatory to use or implement in all cases, but rather they provide a 1909 starting point for a set of useful, interoperable claims. 1910 Applications using CWTs should define which specific claims they use 1911 and when they are required or optional. 1913 D.1.1. iss (Issuer) Claim 1914 The "iss" (issuer) claim identifies the principal that issued the 1915 CWT. The processing of this claim is generally application specific. 1916 The "iss" value is a case-sensitive string containing a StringOrURI 1917 value. Use of this claim is OPTIONAL. 1919 D.1.2. sub (Subject) Claim 1921 The "sub" (subject) claim identifies the principal that is the 1922 subject of the CWT. The claims in a CWT are normally statements 1923 about the subject. The subject value MUST either be scoped to be 1924 locally unique in the context of the issuer or be globally unique. 1925 The processing of this claim is generally application specific. The 1926 "sub" value is a case-sensitive string containing a StringOrURI 1927 value. Use of this claim is OPTIONAL. 1929 D.1.3. aud (Audience) Claim 1931 The "aud" (audience) claim identifies the recipients that the CWT is 1932 intended for. Each principal intended to process the CWT MUST 1933 identify itself with a value in the audience claim. If the principal 1934 processing the claim does not identify itself with a value in the 1935 "aud" claim when this claim is present, then the CWT MUST be 1936 rejected. In the general case, the "aud" value is an array of case- 1937 sensitive strings, each containing a StringOrURI value. In the 1938 special case when the CWT has one audience, the "aud" value MAY be a 1939 single case-sensitive string containing a StringOrURI value. The 1940 interpretation of audience values is generally application specific. 1941 Use of this claim is OPTIONAL. 1943 D.1.4. exp (Expiration Time) Claim 1945 The "exp" (expiration time) claim identifies the expiration time on 1946 or after which the CWT MUST NOT be accepted for processing. The 1947 processing of the "exp" claim requires that the current date/time 1948 MUST be before the expiration date/time listed in the "exp" claim. 1949 Implementers MAY provide for some small leeway, usually no more than 1950 a few minutes, to account for clock skew. Its value MUST be a number 1951 containing a NumericDate value. Use of this claim is OPTIONAL. 1953 D.1.5. nbf (Not Before) Claim 1955 The "nbf" (not before) claim identifies the time before which the CWT 1956 MUST NOT be accepted for processing. The processing of the "nbf" 1957 claim requires that the current date/time MUST be after or equal to 1958 the not-before date/time listed in the "nbf" claim. Implementers MAY 1959 provide for some small leeway, usually no more than a few minutes, to 1960 account for clock skew. Its value MUST be a number containing a 1961 NumericDate value. Use of this claim is OPTIONAL. 1963 D.1.6. iat (Issued At) Claim 1965 The "iat" (issued at) claim identifies the time at which the CWT was 1966 issued. This claim can be used to determine the age of the CWT. Its 1967 value MUST be a number containing a NumericDate value. Use of this 1968 claim is OPTIONAL. 1970 D.1.7. cti (CWT ID) Claim 1972 The "cti" (CWT ID) claim provides a unique identifier for the CWT. 1973 The identifier value MUST be assigned in a manner that ensures that 1974 there is a negligible probability that the same value will be 1975 accidentally assigned to a different data object; if the application 1976 uses multiple issuers, collisions MUST be prevented among values 1977 produced by different issuers as well. The "cti" claim can be used 1978 to prevent the CWT from being replayed. The "cti" value is a case- 1979 sensitive string. Use of this claim is OPTIONAL. 1981 D.1.8. cnf (Confirmation) Claim 1983 The "cnf" (confirmation) claim is used in the CWT to contain members 1984 used to identify a proof-of-possession key. The "cnf" claim is used 1985 to express a declaration in a CWT that a Client of the CWT possesses 1986 a particular key and that the recipient can cryptographically confirm 1987 proof-of-possession of the key by the client. 1989 D.1.9. cks (COSE Key Structure) Claim 1991 The "cks" (COSE Key Structure) claim holds members representing a 1992 COSE Key Structure. The members of the structure can be found in 1993 Section 7.1 of [I-D.ietf-cose-msg]. 1995 D.1.10. aif (Authorization Information Format) Claim 1997 The "aif" (Authorization Information Format) claim uses the AIF 1998 format defined in [I-D.bormann-core-ace-aif] to transfer information 1999 about the authorization from the AS to the RS. 2001 D.2. CBOR major types for Claims 2003 /-----------+--------------+-----------------------\ 2004 | Value | Major Type | Key | 2005 |-----------+--------------+-----------------------| 2006 | 0 | 0 | iss | 2007 | 1 | 0 | sub | 2008 | 2 | 0 | aud | 2009 | 3 | 0 | nonce | 2010 | 4 | 0 | exp | 2011 | 5 | 0 | iat | 2012 | 6 | 4 | cnf | 2013 | 7 | 0 | ck | 2014 | 8 | 4 | aif | 2015 \-----------+--------------+-----------------------/ 2017 Figure 28: CBOR Mappings used in CWT Access Tokens. 2019 Note: Claims defined by the OpenID Foundation have not yet been 2020 included in the table above. 2022 D.3. CBOR Web Token Example 2024 This section illustrates a CWT in the CBOR diagnostic notation. This 2025 example CWT was issued by the AS identified as "coap:// 2026 as.example.com" in the "iss" (issuer) claim. The CWT is only valid 2027 at a resource server at "coap://light.example.com". It's validity is 2028 2 minutes and it includes a symmetric key that will be used to secure 2029 the communication, either using object security, or transport 2030 security, between the client and the resource server. The "aif" 2031 claim includes AIF objects that assert that subject is authorized to 2032 make a PUT request against the "/s/light" resource, a PUT and a GET 2033 against the "/a/led" resource and a POST against the "/dlts" 2034 resource. 2036 { 2037 "iss" : "coap://as.example.com", 2038 "aud" : "coap://light.example.com", 2039 "exp" : 1444064944, 2040 "iat" : 1443944944, 2041 "aif" : [["/s/light", 1], ["/a/led", 5], ["/dtls", 2]], 2042 "cnf" : { 2043 "jwk" : b64'JDLUhTMjU2IiwiY3R5Ijoi ...' 2044 } 2045 } 2047 Figure 29: CWT Example in the CBOR Diagnostic Notation. 2049 Authors' Addresses 2051 Ludwig Seitz 2052 SICS 2053 Scheelevaegen 17 2054 Lund 223 70 2055 SWEDEN 2057 Email: ludwig@sics.se 2058 Goeran Selander 2059 Ericsson 2060 Faroegatan 6 2061 Kista 164 80 2062 SWEDEN 2064 Email: goran.selander@ericsson.com 2066 Erik Wahlstroem 2067 Nexus Technology 2068 Telefonvagen 26 2069 Hagersten 126 26 2070 Sweden 2072 Email: erik.wahlstrom@nexusgroup.com 2074 Samuel Erdtman 2075 Nexus Technology 2076 Telefonvagen 26 2077 Hagersten 126 26 2078 Sweden 2080 Email: samuel.erdtman@nexusgroup.com 2082 Hannes Tschofenig 2083 ARM Ltd. 2084 Hall in Tirol 6060 2085 Austria 2087 Email: Hannes.Tschofenig@arm.com