idnits 2.17.1 draft-gerdes-ace-dcaf-authorize-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 (July 04, 2014) is 3577 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: 'RFC-XXXX' is mentioned on line 1620, but not defined ** Obsolete normative reference: RFC 5226 (Obsoleted by RFC 8126) ** Obsolete normative reference: RFC 6347 (Obsoleted by RFC 9147) ** Obsolete normative reference: RFC 7049 (Obsoleted by RFC 8949) == Outdated reference: A later version (-09) exists of draft-bormann-core-ace-aif-00 == Outdated reference: A later version (-21) exists of draft-ietf-core-block-15 == Outdated reference: A later version (-16) exists of draft-ietf-core-observe-14 == Outdated reference: A later version (-28) exists of draft-ietf-core-resource-directory-01 == Outdated reference: A later version (-01) exists of draft-schmertmann-dice-codtls-00 -- Obsolete informational reference (is this intentional?): RFC 5988 (Obsoleted by RFC 8288) Summary: 3 errors (**), 0 flaws (~~), 7 warnings (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 ACE Working Group S. Gerdes 3 Internet-Draft O. Bergmann 4 Intended status: Standards Track C. Bormann 5 Expires: January 5, 2015 Universitaet Bremen TZI 6 July 04, 2014 8 Delegated CoAP Authentication and Authorization Framework (DCAF) 9 draft-gerdes-ace-dcaf-authorize-00 11 Abstract 13 This specification defines a protocol for delegating client 14 authentication and authorization in a constrained environment for 15 establishing a Datagram Transport Layer Security (DTLS) channel 16 between resource-constrained nodes. The protocol relies on DTLS to 17 transfer authorization information and shared secrets for symmetric 18 cryptography between entities in a constrained network. A resource- 19 constrained node can use this protocol to delegate authentication of 20 communication peers and management of authorization information to a 21 trusted host with less severe limitations regarding processing power 22 and memory. 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 January 5, 2015. 41 Copyright Notice 43 Copyright (c) 2014 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 1.1. Features . . . . . . . . . . . . . . . . . . . . . . . . 4 60 1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 4 61 1.2.1. Roles . . . . . . . . . . . . . . . . . . . . . . . . 4 62 1.2.2. Other Terms . . . . . . . . . . . . . . . . . . . . . 4 63 2. System Overview . . . . . . . . . . . . . . . . . . . . . . . 5 64 3. Protocol . . . . . . . . . . . . . . . . . . . . . . . . . . 6 65 3.1. Overview . . . . . . . . . . . . . . . . . . . . . . . . 6 66 3.2. Unauthorized Resource Request Message . . . . . . . . . . 7 67 3.3. AS Information Message . . . . . . . . . . . . . . . . . 8 68 3.4. Access Request . . . . . . . . . . . . . . . . . . . . . 9 69 3.5. Ticket Request Message . . . . . . . . . . . . . . . . . 11 70 3.6. Ticket Grant Message . . . . . . . . . . . . . . . . . . 11 71 3.7. Ticket Transfer Message . . . . . . . . . . . . . . . . . 13 72 3.8. DTLS Channel Setup Between C and RS . . . . . . . . . . . 13 73 3.9. Authorized Resource Request Message . . . . . . . . . . . 13 74 3.10. Dynamic Update of Authorization Information . . . . . . . 15 75 3.10.1. Handling of Ticket Transfer Messages . . . . . . . . 16 76 4. Ticket . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 77 4.1. Face . . . . . . . . . . . . . . . . . . . . . . . . . . 16 78 4.2. Verifier . . . . . . . . . . . . . . . . . . . . . . . . 17 79 4.3. Revocation . . . . . . . . . . . . . . . . . . . . . . . 17 80 4.3.1. Lifetime . . . . . . . . . . . . . . . . . . . . . . 17 81 4.3.2. Revocation Messages . . . . . . . . . . . . . . . . . 18 82 5. Payload Format and Encoding (application/dcaf+cbor) . . . . . 18 83 5.1. Examples . . . . . . . . . . . . . . . . . . . . . . . . 20 84 6. DTLS PSK Generation Methods . . . . . . . . . . . . . . . . . 22 85 6.1. DTLS PSK Transfer . . . . . . . . . . . . . . . . . . . . 22 86 6.2. Distributed Key Derivation . . . . . . . . . . . . . . . 23 87 7. Authorization Configuration . . . . . . . . . . . . . . . . . 23 88 8. Trust Relationships . . . . . . . . . . . . . . . . . . . . . 23 89 9. Listing Authorization Server Information in a Resource 90 Directory . . . . . . . . . . . . . . . . . . . . . . . . . . 24 91 9.1. The "auth-request" Link Relation . . . . . . . . . . . . 24 92 10. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 25 93 10.1. Access Granted . . . . . . . . . . . . . . . . . . . . . 25 94 10.2. Access Denied . . . . . . . . . . . . . . . . . . . . . 27 95 10.3. Access Restricted . . . . . . . . . . . . . . . . . . . 28 96 10.4. Implicit Authorization . . . . . . . . . . . . . . . . . 28 98 11. Specific Usage Scenarios . . . . . . . . . . . . . . . . . . 29 99 11.1. Combined Authentication Manager and Client . . . . . . . 30 100 11.1.1. Creating the Ticket Request Message . . . . . . . . 30 101 11.1.2. Processing the Ticket Grant Message . . . . . . . . 31 102 11.2. Combined Authentication Manager and Authorization Server 31 103 11.2.1. Processing the Access Request Message . . . . . . . 31 104 11.2.2. Creating the Ticket Transfer Message . . . . . . . . 32 105 11.3. Combined Authorization Server and Resource Server . . . 32 106 12. Security Considerations . . . . . . . . . . . . . . . . . . . 32 107 13. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 33 108 13.1. DTLS PSK Key Generation Methods . . . . . . . . . . . . 33 109 13.2. dcaf+cbor Media Type Registration . . . . . . . . . . . 33 110 13.3. CoAP Content Format Registration . . . . . . . . . . . . 34 111 14. References . . . . . . . . . . . . . . . . . . . . . . . . . 35 112 14.1. Normative References . . . . . . . . . . . . . . . . . . 35 113 14.2. Informative References . . . . . . . . . . . . . . . . . 35 114 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 36 116 1. Introduction 118 The Constrained Application Protocol (CoAP) [RFC7252] is a transfer 119 protocol similar to HTTP which is designed for the special 120 requirements of constrained environments. A serious problem with 121 constrained devices is the realization of secure communication. The 122 devices only have limited resources such as memory, stable storage 123 (such as disk space) and transmission capacity and often lack input/ 124 output devices such as keyboards or displays. Therefore, they are 125 not readily capable of using common protocols. Especially 126 authentication mechanisms are difficult to realize, because the lack 127 of stable storage severely limits the number of keys the system can 128 store. Moreover, CoAP has no mechanism to distinguish access rights 129 for different clients (authorization). 131 The DCAF architecture is designed to relieve the constrained nodes 132 from managing keys for numerous devices by introducing authorization 133 servers which conduct the authentication and authorization for their 134 nodes. To achieve this, access tokens are used. A device which 135 wants to access a constrained node's resource first has to gain 136 permission in the form of a token from the node's authorization 137 server. 139 As fine-grained authorization is not always needed on constrained 140 devices, DCAF supports an implicit authorization mode where no 141 authorization information is exchanged. 143 The main goals of DCAF are the setup of a Datagram Transport Layer 144 Security (DTLS) [RFC6347] channel with symmetric pre-shared keys 145 (PSK) [RFC4279] and to securely transmit authorization tickets. 147 1.1. Features 149 o Utilize DTLS communication with pre-shared keys. 151 o Authenticated exchange of authorization information. 153 o Simplified authentication on constrained nodes by handing the more 154 sophisticated authentication over to less-constrained devices. 156 o Simplified authorization mechanism for cases where implicit 157 authorization is sufficient. 159 o Using only symmetric encryption on constrained nodes. 161 1.2. Terminology 163 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 164 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 165 document are to be interpreted as described in RFC 2119 [RFC2119]. 167 1.2.1. Roles 169 Resource Server (RS): A constrained device that hosts resources the 170 Client wants to access. 172 Client (C): A device that wants to access resources on the Resource 173 Server. 175 Authorization Server (AS): The node that conducts authentication and 176 authorization for a Resource Server. An Authorization Server can be 177 responsible for a single or multiple devices or even for a whole 178 network. A Resource Server can have multiple Authorization Servers. 180 Authentication Manager (AM): The node that conducts authentication on 181 behalf of the Client. 183 Resource Owner: The principal that owns the resource and controls its 184 access permissions. 186 1.2.2. Other Terms 188 Access ticket: Contains the authentication and, if necessary, the 189 authorization information needed to access a resource. A Ticket 190 consists of the Ticket Face and the Ticket Verifier 192 Authorization information: Contains all information needed by RS to 193 decide if C is privileged to access a resource in a specific way. 195 Authentication information: Contains all information needed by RS to 196 decide if the entity in possession of a certain key is verified by 197 the authorization server. 199 Access information: Contains authentication information and, if 200 necessary, authorization information. 202 Ticket Face: The part of the ticket which is generated for the 203 Resource Server. It contains the authorization information and all 204 information needed by the Resource Server to verify that it was 205 granted by AS. 207 Ticket Verifier: The part of the ticket which is generated for the 208 Client. It enables the client to verify that it is communicating 209 with an appropriate RS. 211 Explicit authorization: The Authorization Server informs the Resource 212 Server in detail which privileges are granted to the Client. 214 Implicit authorization: The Authorization Server informs the Resource 215 Server that the Client is authorized to access any resource on RS in 216 any way, without specifying the privileges in detail. 218 2. System Overview 220 Within the DCAF Architecture each Resource Server (RS) has one or 221 more Authorization Servers (AS) which conduct the authentication and 222 authorization for RS. RS and AS share a symmetric key which has to 223 be exchanged initially to provide for a secure channel. The 224 mechanism used for this is not in the scope of this document. 226 To gain access to a specific resource on a Resource Server, a client 227 (C) has to request an access ticket from one of the Authorization 228 Servers serving RS either directly or, if it is a constrained device, 229 using its Authentication Manager (AM). In the following, we always 230 discuss the AM role separately, even if that is co-located within a 231 (more powerful) C. 233 If AS decides that C is allowed to access the resource, it generates 234 a DTLS pre-shared key (PSK) for the communication between C and RS 235 and wraps it into an access ticket. For explicit access control, AS 236 adds the detailed access permissions to the ticket in a way that RS 237 can interpret. After presenting the ticket to RS, C and RS can 238 communicate securely. 240 To be able to provide for the authentication and authorization 241 services, the Authorization Servers have to fulfill several 242 requirements: 244 o An AS must have enough stable storage (such as disk space) to 245 store the necessary number of credentials (matching the number of 246 clients and Resource Servers). 248 o An AS must possess means for user interaction, for example 249 directly or indirectly connected input/output devices like 250 keyboard and display, to allow for configuration of authorization 251 information by the Resource Owner. 253 o An AS must have enough processing power to handle the 254 authorization requests for all RS devices it is responsible for. 256 3. Protocol 258 The DCAF protocol comprises three parts: 260 1. transfer of authentication and, if necessary, authorization 261 information between C and RS; 263 2. transfer of access requests and the respective ticket grants 264 between C and AM; and 266 3. transfer of access requests and the respective ticket grants 267 between AS and AM. 269 3.1. Overview 271 In Figure 1, a DCAF protocol flow is depicted (messages in square 272 brackets are optional): 274 AM C RS AS 275 | <== DTLS chan. ==> | | <== DTLS chan. ==> | 276 | | [Resource Req.-->] | | 277 | | | | 278 | | [<-- AS Info.] | | 279 | | | | 280 | <-- Access Req. | | | 281 | | | | 282 | <===== TLS/DTLS channel (AM/AS Mutual Authentication) =====> | 283 | | | | 284 | Ticket Request ------------------------------------------> | 285 | | | | 286 | <------------------------------------------ Ticket Grant | 287 | | | | 288 | Ticket Transf. --> | | | 289 | | | | 290 | | <== DTLS chan. ==> | | 291 | | Auth. Res. Req. -> | | 292 Figure 1: Protocol Overview 294 To determine the Authorization Server in charge of a resource hosted 295 at the Resource Server (RS), the Client (C) MAY send an initial 296 Unauthorized Resource Request message to RS. RS then denies the 297 request and sends the address of its Authorization Server (AS) back 298 to the Client. 300 Instead of the initial Unauthorized Resource Request message, C MAY 301 look up the desired resource in a resource directory (cf. 302 [I-D.ietf-core-resource-directory]) that lists RS's resources as 303 discussed in Section 9. 305 Once C knows AS' address, it can send a request for authorization to 306 AS using its own Authentication Manager (AM). AS authenticates AM, 307 who serves as a trusted introducer for C, and decides if C is allowed 308 to communicate with RS and access the requested resource. If it is, 309 AS generates an access ticket for C. The ticket contains keying 310 material for the establishment of a secure channel and, if necessary, 311 a representation of the permissions C has for the resource. C keeps 312 one part of the access ticket and presents the other part to RS to 313 prove its right to access. With their respective parts of the 314 ticket, C and RS are able to establish a secure channel. 316 The following sections specify how CoAP is used to interchange 317 access-related data between RS and AS so that AS can provide C and RS 318 with sufficient information to establish a secure channel, and 319 simultaneously convey authorization information specific for this 320 communication relationship to RS. 322 Note: Special implementation considerations apply when one single 323 entity takes the role of more than one actors. Section 11 gives 324 additional advice on some of these usage scenarios. 326 This document uses Concise Binary Object Representation (CBOR, 327 [RFC7049]) to express authorization information as set of attributes 328 passed in CoAP payloads. Notation and encoding options are discussed 329 in Section 5. 331 3.2. Unauthorized Resource Request Message 333 The optional Unauthorized Resource Request message is a request for a 334 resource hosted by RS for which no proper authorization is granted. 335 RS MUST treat any CoAP request as Unauthorized Resource Request 336 message when any of the following holds: 338 o The request has been received on an insecure channel. 340 o RS has no valid access information for the sender of the request 341 regarding the requested action on that resource. 343 o RS has valid access information for the sender of the request, but 344 this does not allow the requested action on the requested 345 resource. 347 Note: These conditions ensure that RS can handle requests 348 autonomously once access was granted and a secure channel has been 349 established between C and RS. 351 Unauthorized Resource Request messages MUST be denied with a client 352 error response. In this response, the Resource Server MUST provide 353 proper AS Information to enable the Client to request an access 354 ticket from RS's Authorization Server as described in Section 3.3. 356 The response code MUST be 4.01 (Unauthorized) in case the sender of 357 the Unauthorized Resource Request message is not authenticated, or if 358 RS has no valid access ticket for C. If RS has authorization 359 information for C but not for the resource that C has requested, RS 360 MUST reject the request with a 4.03 (Forbidden). If RS has 361 authorization information for C but they do not cover the action C 362 requested on the resource, RS MUST reject the request with a 4.05 363 (Method Not Allowed). 365 Note: The use of the response codes 4.03 and 4.05 is intended to 366 prevent infinite loops where a dumb Client optimistically tries to 367 access a requested resource with any access token received from 368 the AS. As malicious clients could pretend to be C to determine 369 C's privileges, these detailed response codes must be used only 370 when a certain level of security is already available which can be 371 achieved only when the Client is authenticated. 373 3.3. AS Information Message 375 The AS Information Message is sent by RS as a response to an 376 Unauthorized Resource Request message (see Section 3.2) to point the 377 sender of the Unauthorized Resource Request message to RS's 378 Authorization Server. The AS information is a set of attributes 379 containing an absolute URI (see Section 4.3 of [RFC3986]) that 380 specifies the Authorization Server in charge of RS. 382 The message MAY also contain a timestamp generated by RS. 384 Figure 2 shows an example for an AS Information message payload using 385 CBOR diagnostic notation. (Refer to Section 5 for a detailed 386 description of the available attributes and their semantics.) 387 4.01 Unauthorized 388 Content-Format: application/dcaf+cbor 389 {AS: "coaps://as-rs.example.com/authorize", TS: 168537} 391 Figure 2: AS Information Payload Example 393 In this example, the attribute AS points the receiver of this message 394 to the URI "coaps://as-rs.example.com/authorize" to request access 395 permissions. The originator of the AS Information payload (i.e. RS) 396 uses a local clock that is loosely synchronized with a time scale 397 common between RS and AS (e.g., wall clock time). Therefore, it has 398 included a time stamp on its own time scale that is used as a nonce 399 for replay attack prevention. Refer to Section 4.1 for more details 400 concerning the usage of time stamps to ensure freshness of access 401 tickets. 403 The examples in this document are written in CBOR diagnostic notation 404 to improve readability. Figure 3 illustrates the binary encoding of 405 the message payload shown in Figure 2. 407 a2 # map(2) 408 00 # unsigned(0) (=AS) 409 78 23 # text(35) 410 636f6170733a2f2f61732d72732e6578 411 616d706c652e636f6d2f617574686f72 412 697a65 # "coaps://as-rs.example.com/authorize" 413 05 # unsigned(5) (=TS) 414 1a 00029259 # unsigned(168537) 416 Figure 3: AS Information Payload Example encoded in CBOR 418 3.4. Access Request 420 To retrieve an access ticket for the resource that C wants to access, 421 C sends an Access Request to its authentication manager AM. The 422 Access Request is constructed as follows: 424 1. The request method is POST. 426 2. The request URI is set as described below. 428 3. The message payload contains a data structure that describes the 429 action and resource for which C requests an access ticket. 431 The request URI identifies a resource at AM for handling 432 authorization requests from C. The URI SHOULD be announced by AM in 433 its resource directory as described in Section 9. 435 Note: Where capacity limitations of C do not allow for resource 436 directory lookups, the request URI in Access Requests could be 437 hard-coded during provisioning or set in a specific device 438 configuration profile. 440 The message payload is constructed from the AS information that RS 441 has returned in its AS Information message (see Section 3.3) and 442 information that C provides to describe its intended request(s). The 443 Access Request MUST contain the following attributes: 445 1. Contact information for the AS to use. 447 2. An absolute URI of the resource that C wants to access. 449 3. The actions that C wants to perform on the resource. 451 4. Any time stamp generated by RS. 453 An example Access Request from C to AM is depicted in Figure 4. 454 (Refer to Section 5 for a detailed description of the available 455 attributes and their semantics.) 457 POST client-authorize 458 Content-Format: application/dcaf+cbor 459 { 460 AS: "coaps://as-rs.example.com/authorize", 461 AI: ["coaps://temp451.example.com/s/tempC", 5], 462 TS: 168537 463 } 465 Figure 4: Access Request Message Example 467 The example shows an Access Request message payload for the resource 468 "/s/tempC" on the Resource Server "temp451.example.com". Requested 469 operations in attribute AR are GET and PUT. 471 The attributes AS (that denotes the Authorization Server to use) and 472 TS (a nonce generated by RS) are taken from the AS Information 473 message from RS. 475 The response to an Authorization Request is delivered by AM back to C 476 in a Ticket Transfer message. 478 3.5. Ticket Request Message 480 When AM receives an Access Request message from C it MAY return a 481 cached response if it is known to be fresh. Otherwise, it checks 482 whether the request payload is of type "application/dcaf+cbor and 483 contains at least the fields AS and AI. AM MUST respond with 4.00 484 (Bad Request) if the type is "application/dcaf+cbor and any of these 485 fields is missing or does not conform to the format described in 486 Section 5. Content formats other than application/dcaf+cbor are out 487 of scope of this specification. 489 When the payload is correct, AM creates a Ticket Request message from 490 the Access Request received from C as follows: 492 1. The destination of the Ticket Request message is derived from the 493 authority information in the URI contained in field "AS" of the 494 Access Request message payload. 496 2. The request method is POST. 498 3. The request URI is constructed from the AS field received in the 499 Access Request message payload. 501 4. The payload is copied from the Access Request sent by C. 503 5. A label that describes the Client is added to the payload 505 To send the Ticket Request message to AS a secure channel between AM 506 and AS MUST be used. Depending on the URI scheme used in the AS 507 field of the Access Request message payload (the less-constrained 508 devices AM and AS do not necessarily use coap to communicate with 509 each other), this could be, e.g., a DTLS channel (for "coaps") or a 510 TLS connection (for "https"). AM and AS MUST be able to mutually 511 authenticate each other, e.g. based on a public key infrastructure. 512 (Refer to Section 8 for a detailed discussion of the trust 513 relationship between authentication managers and authorization 514 servers.) 516 The descriptive label of C included in the Ticket Request is used to 517 distinguish the clients within AS's namespace and MUST NOT be used 518 for authenticating the client. 520 3.6. Ticket Grant Message 522 When AS has received a Ticket Request message it has to evaluate the 523 access request information contained therein. First, it checks 524 whether the request payload is of type "application/dcaf+cbor" and 525 contains at least the fields AS, D, and AI. AS MUST respond with 526 4.00 (Bad Request) for CoAP (or 400 for HTTP) if the type is 527 "application/dcaf+cbor" and any of these fields is missing or does 528 not conform to the format described in Section 5. 530 AS decides whether or not access is granted to the requested resource 531 and then creates a Ticket Grant message that reflects the result. To 532 grant access to the requested resource, AS creates an access ticket 533 comprised of a Face and a Verifier as described in Section 4.1. 535 The Ticket Grant message then is constructed as a success response 536 indicating attached content, i.e. 2.05 for CoAP, or 200 for HTTP, 537 respectively. The payload of the Ticket Grant message is a data 538 structure that contains the result of the access request. When 539 access is granted, the data structure contains the ticket's Face, the 540 Verifier and the Session Key Generation Method. 542 The Ticket Grant message MAY provide cache-control options to enable 543 intermediaries to cache the response. The message MAY be cached 544 according to the rules defined in [RFC7252] to facilitate ticket 545 retrieval when C has crashed and wants to recover the DTLS session 546 with RS. 548 AS sets Max-Age according to the ticket lifetime in its response 549 (Ticket Grant Message). 551 Figure 5 shows an example Ticket Grant message using CoAP. The Face/ 552 Verifier information is transferred as a CBOR data structure as 553 specified in Section 5. The Max-Age option tells the receiving AM 554 how long this ticket will be valid. 556 2.05 Content 557 Content-Format: application/dcaf+cbor 558 Max-Age: 86400 559 { F: { 560 AI: [ "/s/tempC", 7 ], 561 D: "2001:db8:ab9:1234:7920:3133:ae5f:87", 562 TS: 0("2013-07-10T10:04:12.391"), 563 L: 86400, 564 G: hmac_sha256 565 }, 566 V: h'b2dd4e409c2d36a7423da3c87e571999 567 0b778ebd2c7d3730729a7fcde26c7201' 568 } 570 Figure 5: Example Ticket Grant Message 572 A Ticket Grant message that declines any operation on the requested 573 resource is illustrated in Figure 6. As no ticket needs to be 574 issued, an empty payload is included with the response. 576 2.05 Content 577 Content-Format: application/dcaf+cbor 579 Figure 6: Example Ticket Grant Message With Reject 581 3.7. Ticket Transfer Message 583 A Ticket Transfer message delivers the access information sent by AS 584 in a Ticket Grant message to the requesting client C. The Ticket 585 Transfer message is the response to the Access Request message sent 586 from C to AM and includes any access information from AS contained in 587 the Ticket Grant message. 589 3.8. DTLS Channel Setup Between C and RS 591 Using the information contained in a positive response to its Access 592 Request (i.e. a Ticket Transfer message that contains a Face and a 593 Verifier), C can initiate establishment of a new DTLS channel with 594 RS. To use DTLS with pre-shared keys, C follows the PSK key exchange 595 algorithm specified in Section 2 of [RFC4279], with the following 596 additional requirements: 598 1. C sets the psk_identity field of the ClientKeyExchange message to 599 the ticket Face received in the Ticket Transfer message. 601 2. C uses the ticket Verifier as PSK when constructing the premaster 602 secret. 604 Note1: As RS cannot provide C with a meaningful PSK identity hint in 605 response to C's ClientHello message, RS SHOULD NOT send a 606 ServerKeyExchange message. 608 Note2: According to [RFC7252], CoAP implementations MUST support the 609 ciphersuite TLS_PSK_WITH_AES_128_CCM_8 [RFC6655]. C is therefore 610 expected to offer at least this ciphersuite to RS. 612 Note3: The ticket is constructed by AS such that RS can derive the 613 authorization information as well as the PSK (refer to Section 6 for 614 details). 616 3.9. Authorized Resource Request Message 618 Successful establishment of the DTLS channel between C and RS ties 619 the authorization information contained in the psk_identity field to 620 this channel. Any request that RS receives on this channel is 621 checked against these authorization rules. Incoming CoAP requests 622 that are not Authorized Resource Requests MUST be rejected by RS with 623 4.01 response as described in Section 3.2. 625 RS SHOULD treat an incoming CoAP request as Authorized Resource 626 Request if the following holds: 628 1. The message was received on a secure channel that has been 629 established using the procedure defined in Section 3.8. 631 2. The authorization information tied to the secure channel is 632 valid. 634 3. The request is destined for RS. 636 4. The resource URI specified in the request is covered by the 637 authorization information. 639 5. The request method is an authorized action on the resource with 640 respect to the authorization information. 642 Note that the authorization information is not restricted to a single 643 resource URI. For example, role-based authorization can be used to 644 authorize a collection of semantically connected resources 645 simultaneously. Implicit authorization also provides access rights 646 to authenticated clients for all actions on all resources that RS 647 offers. As a result, C can use the same DTLS channel not only for 648 subsequent requests for the same resource (e.g. for block-wise 649 transfer as defined in [I-D.ietf-core-block] or refreshing observe- 650 relationships [I-D.ietf-core-observe]) but also for requests to 651 distinct resources. 653 Incoming CoAP requests received on a secure channel according to the 654 procedure defined in Section 3.8 MUST be rejected 656 1. with response code 4.03 (Forbidden) when the resource URI 657 specified in the request is not covered by the authorization 658 information, and 660 2. with response code 4.05 (Method Not Allowed) when the resource 661 URI specified in the request covered by the authorization 662 information but not the requested action. 664 Since AS may limit the set of requested actions in its Ticket Grant 665 message, C cannot know a priori if an Authorized Resource Request 666 will succeed. 668 3.10. Dynamic Update of Authorization Information 670 Once a security association exists between a Client and a Resource 671 Server, the Client can update the Authorization Information stored at 672 the Resource Server at any time. To do so, the Client creates a new 673 Access Request for the intended action on the respective resource and 674 sends this request to its Authentication Manager which relays this 675 request to the Resource Server's Authorization Server as described in 676 Section 3.4. 678 Note: Requesting a new Access Ticket also can be a Client's reaction 679 on a 4.03 or 4.05 error that it has received in response to an 680 Authorized Resource Request. 682 Figure 7 depicts the message flow where C requests a new Access 683 Tickets after a security association between C and RS has been 684 established using this protocol. 686 AM C RS AS 687 | <== DTLS chan. ==> | <== DTLS chan. ==> | <== DTLS chan. ==> | 688 | | | | 689 | | [Unauth. R. Req->] | | 690 | | [<- 4.0x+AS Info.] | | 691 | | | | 692 | <-- Access Req. | | | 693 | | | | 694 | <===== TLS/DTLS channel (AM/AS Mutual Authentication) =====> | 695 | | | | 696 | Ticket Request ------------------------------------------> | 697 | | | | 698 | <------------------------------------------ Ticket Grant | 699 | | | | 700 | Ticket Transf. --> | | | 701 | | | | 702 | | <== Update AI ===> | | 704 Figure 7: Overview of Dynamic Update Operation 706 Processing the Ticket Request is done at the Authorization Server as 707 specified in Section 3.6, i.e. the AS checks whether or not the 708 requested operation is permitted by the Resource Owner's policy, and 709 then return a Ticket Grant message with the result of this check. If 710 access is granted, the Ticket Grant message contains an Access Ticket 711 comprised of a public Ticket Face and a private Ticket Verifier. 712 This authorization payload is relayed by the Authorization Manager to 713 the Client in a Ticket Transfer Message as defined in Section 3.7. 715 The major difference between dynamic update of Authorization 716 Information and the initial handshake is the handling of a Ticket 717 Transfer message by the Client that is described in Section 3.10.1. 719 3.10.1. Handling of Ticket Transfer Messages 721 If the security association with RS still exists and RS has indicated 722 support for session renegotiation according to [RFC5746], the ticket 723 Face SHOULD be used to renegotiate the existing DTLS session. In 724 this case, the ticket Face is used as psk_identity as defined in 725 Section 3.8. Otherwise, the Client MUST perform a new DTLS handshake 726 according to Section 3.8 that replaces the existing DTLS session. 728 After successful completion of the DTLS handshake RS updates the 729 existing Authorization Information for C according to the contents of 730 the ticket Face. 732 Note: No mutual authentication between C and RS is required for 733 dynamic updates when a DTLS channel exists that has been 734 established as defined in Section 3.8. RS only needs to verify 735 the authenticity and integrity of the ticket Face issued by AS 736 which is achieved by having performed a successful DTLS handshake 737 with the ticket Face as psk_identity. This could even be done 738 within the existing DTLS session by tunneling a CoDTLS 739 [I-D.schmertmann-dice-codtls] handshake. 741 4. Ticket 743 Access tokens in DCAF are tickets that consist of two parts, namely 744 the Face and the Verifier. The Face goes to RS, the Verifier goes to 745 the Client. The Face and the Verifier are parts of the same ticket. 747 RS only needs the information contained in the Ticket Face to 748 authorize the client and make sure that AS generated the Ticket Face 749 (RS cannot make authorization decisions by itself and hence needs AS 750 to do it). No additional information about the Client is needed. RS 751 keeps the Ticket Face as long as it is valid. 753 4.1. Face 755 Face is the part of the ticket generated for RS. Face MUST contain 756 all information needed for authorized access to a resource: 758 o Authorization Information 760 o Descriptive label 762 o A timestamp generated by AS 763 Optionally, Face MAY also contain: 765 o A lifetime (optional) 767 o A DTLS pre-shared key (optional) 769 RS MUST verify the integrity of Face, i.e. the information contained 770 in Face stems from AS and was not manipulated by anyone else. 772 Face MUST contain a timestamp to verify that the contained 773 information is fresh. As constrained devices may not have a clock, 774 timestamps MAY be generated using the clock ticks since the last 775 reboot. To circumvent synchronization problems the timestamp MAY be 776 generated by RS and included in the first AS Information message. 777 Alternatively, AS MAY generate the timestamp. In this case, AS and 778 RS MUST use a time synchronization mechanism to make sure that RS 779 interprets the timestamp correctly. 781 Face MAY be encrypted. If Face contains a DTLS PSK, the whole 782 content of Face MUST be encrypted. 784 Note: The integrity of Face can be ensured by various means. Face 785 may be encrypted by AS with a key it shares with RS. Alternatively, 786 RS can use a mechanism to generate the DTLS PSK which includes Face 787 and is only able to calculate the correct key with the correct Face 788 (refer to Section 6 for details). 790 4.2. Verifier 792 The Verifier part of the ticket is generated for C. It contains the 793 DTLS PSK for C. The Verifier MUST NOT be transmitted over insecure 794 channels. 796 4.3. Revocation 798 The existence of access tickets SHOULD be limited in time. This can 799 be achieved either by explicit Revocation Messages to invalidate a 800 ticket or implicitly by attaching a lifetime to the ticket. 802 4.3.1. Lifetime 804 Tickets MAY have a lifetime. AS is responsible for defining the 805 ticket lifetime. If AS sets a lifetime for a ticket, AS and RS MUST 806 use a time synchronization method to ensure that RS is able to 807 interpret the lifetime correctly. RS SHOULD end the DTLS connection 808 to C if the lifetime of a ticket has run out and it MUST NOT accept 809 new requests. RS MUST NOT accept tickets with an invalid lifetime. 811 Note: Defining reasonable ticket lifetimes is difficult to 812 accomplish. How long a client needs to access a resource depends 813 heavily on the application scenario and may be difficult to decide 814 for AS. 816 4.3.2. Revocation Messages 818 AS MAY revoke tickets by sending a ticket revocation message to RS. 819 If RS receives a ticket revocation message, it MUST end the DTLS 820 connection to C and MUST NOT accept any further requests from C. 822 If ticket revocation messages are used, RS MUST check regularly if AS 823 is still available. If RS cannot contact AS, it MUST end all DTLS 824 connections and reject any further requests from C. 826 Note: The loss of the connection between RS and AS prevents all 827 access to RS. This might especially be a severe problem if AS is 828 responsible for several Resource Servers or even a whole network. 830 5. Payload Format and Encoding (application/dcaf+cbor) 832 Various messages types of the DCAF protocol carry payloads to express 833 authorization information and parameters for generating the DTLS PSK 834 to be used by C and RS. In this section, a representation in Concise 835 Binary Object Representation (CBOR, [RFC7049]) is defined. 837 DCAF data structures are defined as CBOR maps that contain key value 838 pairs. For efficient encoding, the keys defined in this document are 839 represented as unsigned integers in CBOR, i. e. major type 0. For 840 improved reading, we use symbolic identifiers to represent the 841 corresponding encoded values as defined in Table 1. 843 +---------------+-----+ 844 | Encoded Value | Key | 845 +---------------+-----+ 846 | 0b000_00000 | AS | 847 | | | 848 | 0b000_00001 | AI | 849 | | | 850 | 0b000_00010 | D | 851 | | | 852 | 0b000_00011 | E | 853 | | | 854 | 0b000_00100 | K | 855 | | | 856 | 0b000_00101 | TS | 857 | | | 858 | 0b000_00110 | L | 859 | | | 860 | 0b000_00111 | G | 861 | | | 862 | 0b000_01000 | F | 863 | | | 864 | 0b000_01001 | V | 865 +---------------+-----+ 867 Table 1: DCAF field identifiers encoded in CBOR 869 The following list describes the semantics of the keys defined in 870 DCAF. 872 AS: Authorization Server. This attribute denotes the authorization 873 server that is in charge of the resource specified in attribute R. 874 The attribute's value is a string that contains an absolute URI 875 according to Section 4.3 of [RFC3986]. 877 AI: Authorization Information. A data structure used to convey 878 authorization information from AS to RS and to describe the 879 permissions requested from AS in a Ticket Request. The AI 880 attribute contains an AIF object as defined in 881 [I-D.bormann-core-ace-aif]. 883 D: Description. A descriptive label of the initiator of the 884 authorization request. This label MAY be a fully qualified domain 885 name, an IP address, or any other character literal that is used 886 by the Authorization Server to decide whether or not access is 887 granted to the requesting entity. 889 E: Encrypted Ticket Face. A binary string containing an encrypted 890 ticket Face. 892 K: Key. A string that identifies the shared key between RS and AS 893 that can be used to decrypt the contents of E. If the attribute E 894 is present and no attribute K has been specified, the default is 895 to use the current session key for the secured channel between RS 896 and AS. 898 TS: Time Stamp. An optional time stamp that indicates the instant 899 when the access ticket request was formed. This attribute can be 900 used by the resource server in an AS Information message to convey 901 a time stamp in its local time scale (e.g. when it does not have a 902 real time clock with synchronized global time). When the 903 attribute's value is encoded as a string, it MUST contain a valid 904 UTC timestamp without time zone information. When encoded as 905 integer, TS contains a system timestamp relative to the local time 906 scale of its generator, usually RS. 908 L: Lifetime. A lifetime of the ticket. When encoded as a string, L 909 MUST denote the ticket's expiry time as a valid UTC timestamp 910 without time zone information. When encoded as an integer, L MUST 911 denote the ticket's validity period in seconds relative to TS. 913 G: DTLS PSK Generation Method. A numeric identifier for the method 914 that RS MUST use to derive the DTLS PSK from the ticket Face. 915 This attribute MUST NOT be used when attribute V is present within 916 the contents of F. This specification uses symbolic identifiers 917 for improved readability. The corresponding numeric values 918 encoded in CBOR are defined in Table 2. A registry for these 919 codes is defined in Section 13.1. 921 F: Ticket Face. An object containing the fields AI, D, TS, and 922 optionally G, L and V. 924 V: Ticket Verifier. A binary string containing the shared secret 925 between C and RS. 927 +---------------+-------------+-----------+ 928 | Encoded Value | Mnemonic | Support | 929 +---------------+-------------+-----------+ 930 | 0b000_00000 | hmac_sha256 | mandatory | 931 | | | | 932 | 0b000_00001 | hmac_sha384 | optional | 933 | | | | 934 | 0b000_00010 | hmac_sha512 | optional | 935 +---------------+-------------+-----------+ 937 Table 2: CBOR encoding for DTLS PSK Key Generation Methods 939 5.1. Examples 941 The following example specifies an Authorization Server that will be 942 accessed using HTTP over TLS. The request URI is set to "/ 943 a?ep=%5B2001:DB8::dcaf:1234%5D" (hence denoting the endpoint address 944 to authorize). TS denotes a local timestamp in UTC. 946 POST /a?ep=%5B2001:DB8::dcaf:1234%5D HTTP/1.1 947 Host: as-rs.example.com 948 Content-Type: application/dcaf+cbor 949 {AS: "https://as-rs.example.com/a?ep=%5B2001:DB8::dcaf:1234%5D", 950 D: "2001:DB8::dcaf:1234", 951 AI: ["coaps://temp451.example.com/s/tempC", 1], 952 TS: 0("2013-07-14T11:58:22.923")} 954 The following example shows a ticket for the distributed key 955 generation method (cf. Section 6.2), comprised of a Face (F) and a 956 Verifier (V). The Face data structure contains authorization 957 information AI, a client descriptor, a timestamp using the local time 958 scale of RS, and a lifetime relative to RS's time scale. 960 The DTLS PSK Generation Method is set to hmac_sha256 denoting that 961 the distributed key derivation is used as defined in Section 6.2 with 962 SHA-256 as HMAC function. 964 The Verifier V contains a shared secret to be used as DTLS PSK 965 between C and RS. 967 HTTP/1.1 200 OK 968 Content-Type: application/dcaf+cbor 969 { 970 F: { 971 AI: [ "/s/tempC", 1 ], 972 D: "2001:db8:ab9:1234:7920:3133:ae5f:87", 973 TS: 2938749, 974 L: 3600, 975 G: hmac_sha256 976 }, 977 V: h'93b9448d4380304d5a574fc50b944958 978 55bbd5ba1422cc09fde61665aa519cf9' 979 } 981 The Face may be encrypted as illustrated in the following example. 982 Here, the field E carries an encrypted Face data structure that 983 contains the same information as the previous example, and an 984 additional Verifier. Encryption was done with a secret shared by AS 985 and RS. (This example uses AES128_CCM with the secret { 0x00, 0x01, 986 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08, 0x09, 0x0a, 0x0b, 0x0c, 987 0x0d, 0x0e, 0x0f } and RS's timestamp { 0x00, 0x2C, 0xD7, 0x7D } as 988 nonce.) Line breaks have been inserted to improve readability. 990 The attribute K describes the identity of the key to be used by RS to 991 decrypt the contents of attribute E. Here, The value "key0" in this 992 example is used to indicate that the shared session key between RS 993 and AS was used for encrypting E. 995 { 996 E: h'2e1c0c0ae1915711f1073f34e44bfc81 997 12167f5bdbd8801d07686615b0b434 998 cdca7a5453d0d582565e2f236948235d 999 d353cef1114d64d138949f7ab01b92f0 1000 b6f2caccce3a43cb0a32f270a82cde0a 1001 98250e6ac2b79a26fb47c09ef4cb366f 1002 1aa38017cd8b891a6d796fa684294a60 1003 64f3665527c5890b65a33af73a5c66ef 1004 66cbb9e28ea30c89', 1005 K: "key0", 1006 V: h'93b9448d4380304d5a574fc50b944958 1007 55bbd5ba1422cc09fde61665aa519cf9' 1008 } 1010 The decrypted contents of E are depicted below (whitespace has been 1011 added to improve readability). The presence of the attribute V 1012 indicates that the DTLS PSK Transfer is used to convey the session 1013 key (cf. Section 6.1). 1015 { 1016 F: { 1017 AI: [ "/s/tempC", 1 ], 1018 D: "2001:db8:ab9:1234:7920:3133:ae5f:87", 1019 TS: 2938749, 1020 L: 3600, 1021 G: hmac_sha256 1022 }, 1023 V: h'93b9448d4380304d5a574fc50b944958 1024 55bbd5ba1422cc09fde61665aa519cf9' 1025 } 1027 6. DTLS PSK Generation Methods 1029 One goal of the DCAF protocol is to provide for a DTLS PSK shared 1030 between C and RS. AS and RS MUST negotiate the method for the DTLS 1031 PSK generation. 1033 6.1. DTLS PSK Transfer 1035 The DTLS PSK is generated by AS and transmitted to C and RS using a 1036 secure channel. 1038 The DTLS PSK transfer method is defined as follows: 1040 o AS generates the DTLS PSK using an algorithm of its choice 1042 o AS MUST include a representation of the DTLS PSK in Face and 1043 encrypt it together with all other information in Face with a key 1044 K(AS,RS) it shares with RS. How AS and RS exchange K(AS,RS) is 1045 not in the scope of this document. AS and RS MAY use their 1046 preshared key as K(AS,RS). 1048 o AS MUST include a representation of the DTLS PSK in the Verifier. 1050 o As AS and C do not have a shared secret, the Verifier MUST be 1051 transmitted to C using encrypted channels. 1053 o RS MUST decrypt Face using K(AS,RS) 1055 6.2. Distributed Key Derivation 1057 AS generates a DTLS PSK for C which is transmitted using a secure 1058 channel. RS generates its own version of the DTLS PSK using the 1059 information contained in Face (see also Section 4.1). 1061 The distributed key derivation method is defined as follows: 1063 o AS and RS both generate the DTLS PSK using the information. 1064 included in Face. They use an HMAC algorithm on Face with a 1065 shared key. The result serves as the DTLS PSK. How AS and RS 1066 negotiate the used HMAC algorithm is not in the scope of this 1067 document. They MAY however use the HMAC algorithm they use for 1068 their DTLS connection. 1070 o AS MUST include a representation of the DTLS PSK in the Verifier. 1072 o As AS and C do not have a shared secret, the Verifier MUST be 1073 transmitted to C using encrypted channels. 1075 o AS MUST NOT include a representation of the DTLS PSK in Face. 1077 o AS MUST NOT encrypt Face. 1079 7. Authorization Configuration 1081 For the protocol defined in this document, proper configuration of AS 1082 is crucial. The principal who owns the resources hosted by RS (i.e. 1083 the Resource Owner) needs to define permissions for the resources. 1084 The data representation of these permissions are not in the scope of 1085 this document. 1087 8. Trust Relationships 1089 C trusts AM, and RS trusts AS. Obviously, AM trusts C with the 1090 specific permissions it hands over to it. How this trust is 1091 established, is not in the scope of this document. It may be 1092 achieved by using a bootstrapping mechanism similar to [bergmann12]. 1094 Additionally, AS and AM need to have a trust relationship 1095 established. Its establishment is also not in the scope of this 1096 document. It fulfills the following conditions: 1098 1. AS has means to authenticate AM (e.g. it has a certificate of AM 1099 or a PKI in which AM is included) and vice versa 1101 2. As far as AS needs to rely on the different clients of AM to 1102 receive different permissions, it can be sure that AM correctly 1103 identifies these clients towards AS and does not leak tickets 1104 that have been generated for a specific client C to another 1105 client. 1107 AS trusts C indirectly because it trusts AM and AM vouches for C. The 1108 DCAF Protocol does not provide any means for AS to validate that a 1109 resource requests stems from C. 1111 C indirectly trusts AS with some potentially confidential 1112 information, and that AS correctly represents RS, because AM trusts 1113 AS. 1115 AM trusts RS indirectly because it trusts AS and AS vouches for RS. 1117 C implicitly trusts RS with some potentially confidential information 1118 because it trusts AM and because RS can prove that it shares a key 1119 with AS. 1121 AM <--------------------> AS 1123 /|\ /|\ 1124 | | 1125 \|/ \|/ 1127 C ..................... RS 1129 9. Listing Authorization Server Information in a Resource Directory 1131 CoAP utilizes the Web Linking format [RFC5988] to facilitate 1132 discovery of services in an M2M environment. [RFC6690] defines 1133 specific link parameters that can be used to describe resources to be 1134 listed in a resource directory [I-D.ietf-core-resource-directory]. 1136 9.1. The "auth-request" Link Relation 1138 This section defines a resource type "auth-request" that can be used 1139 by clients to retrieve the request URI for a server's authorization 1140 service. When used with the parameter rt in a web link, "auth- 1141 request" indicates that the corresponding target URI can be used in a 1142 POST message to request authorization for the resource and action 1143 that are described in the request payload. 1145 The Content-Format "application/dcaf+cbor with numeric identifier 1146 TBD1 defined in this specification MAY be used to express access 1147 requests and their responses. 1149 The following example shows the web link used by AM in this document 1150 to relay incoming Authorization Request messages to AS. (Whitespace 1151 is included only for readability.) 1153 ;rt="auth-request";ct=TBD1 1154 ;title="Contact Remote Authorization Server" 1156 The resource directory that hosts the resource descriptions of RS 1157 could list the following description. In this example, the URI "ep/ 1158 node138/a/switch2941" is relative to the resource context "coaps 1159 ://as-rs.example.com/", i.e. the authorization server AS. 1161 ;rt="auth-request";ct=TBD1;ep="node138" 1162 ;title="Request Client Authorization" 1163 ;anchor="coaps://as-rs.example.com/" 1165 10. Examples 1167 This section gives a number of short examples with message flows for 1168 the initial Unauthorized Resource Request and the subsequent 1169 retrieval of a ticket from AS. The notation here follows the role 1170 conventions defined in Section 1.2.1. The payload format is encoded 1171 as proposed in Section 5. The IP address of AS is 2001:DB8::1, the 1172 IP address of RS is 2001:DB8::dcaf:1234, and C's IP address is 1173 2001:DB8::c. 1175 10.1. Access Granted 1177 This example shows an Unauthorized PUT request from C to RS that is 1178 answered with an AS Information message. C then sends a POST request 1179 to AM with a description of its intended request. AM forwards this 1180 request to AS using CoAP over a DTLS-secured channel. The response 1181 from AS contains an access ticket that is relayed back to AM. 1183 C --> RS 1184 PUT a/switch2941 [Mid=1234] 1185 Content-Format: application/senml+json 1186 {"e": [{"bv": "1"}]} 1188 C <-- RS 1189 4.01 Unauthorized [Mid=1234] 1190 Content-Format: application/dcaf+cbor 1191 {AS: "coaps://[2001:DB8::1]/ep/node138/a/switch2941"} 1193 C --> AM 1194 POST client-authorize [Mid=1235,Token="tok"] 1195 Content-Format: application/dcaf+cbor 1196 { 1197 AS: "coaps://[2001:DB8::1]/ep/node138/a/switch2941", 1198 AI: ["coaps://[2001:DB8::dcaf:1234]/a/switch2941", 4] 1199 } 1201 AM --> AS [Mid=23146] 1202 POST ep/node138/a/switch2941 1203 Content-Format: application/dcaf+cbor 1204 { 1205 AS: "coaps://[2001:DB8::1]/ep/node138/a/switch2941", 1206 D: "2001:DB8::c", 1207 AI: ["coaps://[2001:DB8::dcaf:1234]/a/switch2941", 4] 1208 } 1210 AM <-- AS 1211 2.05 Content [Mid=23146] 1212 Content-Format: application/dcaf+cbor 1213 { F: { 1214 AI: ["a/switch2941", 5], 1215 D: "2001:DB8::c", 1216 TS: 0("2013-07-04T20:17:38.002"), 1217 G: hmac_sha256 1218 }, 1219 V: h'50f18bf1d6f084eb0fd9d2ee6ec882d8 1220 a87ef66a332c86a45bff8f67fe19bc47' 1221 } 1223 C <-- AM 1224 2.05 Content [Mid=1235,Token="tok"] 1225 Content-Format: application/dcaf+cbor 1226 { F: { 1227 AI: ["a/switch2941", 5], 1228 D: "2001:DB8::c", 1229 TS: 0("2013-07-04T20:17:38.002"), 1230 G: hmac_sha256 1231 }, 1232 V: h'50f18bf1d6f084eb0fd9d2ee6ec882d8 1233 a87ef66a332c86a45bff8f67fe19bc47' 1234 } 1236 C --> RS 1237 ClientHello (TLS_PSK_WITH_AES_128_CCM_8) 1239 C <-- RS 1240 ServerHello (TLS_PSK_WITH_AES_128_CCM_8) 1241 ServerHelloDone 1243 C --> RS 1244 ClientKeyExchange 1245 psk_identity=0x6146a4624149826c612f737769746368 1246 0x323934310561446b323030313a444238 1247 0x3a3a63625453c077323031332d30372d 1248 0x30345432303a31373a33382e30303261 1249 0x476b686d61635f736861323536 1251 (C decodes the contents of V and uses the result as PSK) 1252 ChangeCipherSpec 1253 Finished 1255 (RS calculates PSK from AI, D, TS and its session key 1256 HMAC_sha256(0x6146a4624149826c612f737769746368 1257 0x323934310561446b323030313a444238 1258 0x3a3a63625453c077323031332d30372d 1259 0x30345432303a31373a33382e30303261 1260 0x476b686d61635f736861323536, 1261 0x66736563726574) 1262 = 0x0e70158e... 1263 ) 1265 C <-- RS 1266 ChangeCipherSpec 1267 Finished 1269 10.2. Access Denied 1271 This example shows a denied Authorization request for the DELETE 1272 operation. 1274 C --> RS 1275 DELETE a/switch2941 1277 C <-- RS 1278 4.01 Unauthorized 1279 Content-Format: application/dcaf+cbor 1280 {AS: "coaps://[2001:DB8::1]/ep/node138/a/switch2941"} 1282 C --> AM 1283 POST client-authorize 1284 Content-Format: application/dcaf+cbor 1285 { 1286 AS: "coaps://[2001:DB8::1]/ep/node138/a/switch2941", 1287 AI: ["coaps://[2001:DB8::dcaf:1234]/a/switch2941", 8] 1288 } 1290 AM --> AS 1291 POST ep/node138/a/switch2941 1292 Content-Format: application/dcaf+cbor 1293 { 1294 AS: "coaps://[2001:DB8::1]/ep/node138/a/switch2941", 1295 D: "2001:DB8::c", 1296 AI: ["coaps://[2001:DB8::dcaf:1234]/a/switch2941", 8] 1297 } 1299 AM <-- AS 1300 2.05 Content 1301 Content-Format: application/dcaf+cbor 1303 C <-- AM 1304 2.05 Content 1305 Content-Format: application/dcaf+cbor 1307 10.3. Access Restricted 1309 This example shows a denied Authorization request for the operations 1310 GET, PUT, and DELETE. AS grants access for PUT only. 1312 AM --> AS 1313 POST ep/node138/a/switch2941 1314 Content-Format: application/dcaf+cbor 1315 { 1316 AS: "coaps://[2001:DB8::1]/ep/node138/a/switch2941", 1317 D: "2001:DB8::c", 1318 AI: ["coaps://[2001:DB8::dcaf:1234]/a/switch2941", 13] 1319 } 1321 AM <-- AS 1322 2.05 Content 1323 Content-Format: application/dcaf+cbor 1324 { F: { 1325 AI: ["a/switch2941", 5], 1326 D: "2001:DB8::c", 1327 TS: 0("2013-07-04T21:33:11.930"), 1328 G: hmac_sha256 1329 }, 1330 V: h'f5628265ec99349d2b1f3a1020223793 1331 7098512d555f085a775f1ae6a9c66950' 1332 } 1334 10.4. Implicit Authorization 1335 This example shows an Authorization request using implicit 1336 authorization. AM initially requests the actions GET and POST on the 1337 resource "coaps://[2001:DB8::dcaf:1234]/a/switch2941". AS returns a 1338 ticket that has no AI field in its ticket Face, hence implicitly 1339 authorizing C. 1341 AM --> AS 1342 POST ep/node138/a/switch2941 1343 Content-Format: application/dcaf+cbor 1344 { 1345 AS: "coaps://[2001:DB8::1]/ep/node138/a/switch2941", 1346 D: "2001:DB8::c", 1347 AI: ["coaps://[2001:DB8::dcaf:1234]/a/switch2941", 3] 1348 } 1350 AM <-- AS 1351 2.05 Content 1352 Content-Format: application/dcaf+cbor 1353 { F: { 1354 D: "2001:DB8::c", 1355 TS: 0("2013-07-16T10:15:43.663"), 1356 G: hmac_sha256 1357 }, 1358 V: h'6d30f6162b54cd50c8b7421674d46150 1359 1baba2a34c0a86a7aacc0cfe3c2f2643' 1360 } 1362 11. Specific Usage Scenarios 1364 The general DCAF architure outlined in Section 3.1 illustrates the 1365 various actors who participate in the message exchange for 1366 authenticated authorization. The message types defined in this 1367 document cover the most general case where all four actors are 1368 separate entities that may or may not reside on the same device. 1370 Special implementation considerations apply when one single entity 1371 takes the role of more than one actor. This section gives advice on 1372 the most common usage scenarios where the Authentication Manager and 1373 Client, the Authorization Server and Resource Server or the 1374 Authentication Manager and Authorization Server reside on the same 1375 (less-constrained) device and have a means of secure communication 1376 outside the scope of this document. 1378 11.1. Combined Authentication Manager and Client 1380 When AM and C reside on the same (less-constrained) device, the 1381 Access Request and Ticket Transfer messages can be substituted by 1382 other means of secure communication. Figure 8 shows a simplified 1383 message exchange for a combined AM+C device. 1385 AM+C RS AS 1386 | | <== DTLS chan. ==> | 1387 | [Resource Req.-->] | | 1388 | | | 1389 | [<-- AS Info.] | | 1390 | | | 1391 | <==== TLS/DTLS chan. (Mutual Auth) ===> | 1392 | | | 1393 | Ticket Request ---------------------> | 1394 | | | 1395 | <--------------------- Ticket Grant | 1396 | | | 1397 | <== DTLS chan. ==> | | 1398 | Auth. Res. Req. -> | | 1400 Figure 8: Combined Authentication Manager and Client 1402 11.1.1. Creating the Ticket Request Message 1404 When AM+C receives an AS Information message as a reaction to an 1405 Unauthorized Request message, it creates a Ticket Request message as 1406 follows: 1408 1. The destination of the Ticket Request message is derived from the 1409 authority information in the URI contained in field "AS" of the 1410 AS Information message payload. 1412 2. The request method is POST. 1414 3. The request URI is constructed from the AS field received in the 1415 AS Information message payload. 1417 4. The payload contains the AS field from the AS Information 1418 message, an absolute URI of the resource that AM+C wants to 1419 access, the the actions that AM+C wants to perform on the 1420 resource, and any time stamp generated by RS that was transferred 1421 with the AS Information message. 1423 5. A label that describes AM+C is added to the payload. 1425 11.1.2. Processing the Ticket Grant Message 1427 Based on the Ticket Grant message, AM+C is able to establish a DTLS 1428 channel with RS. To do so, AM+C sets the psk_identity field of the 1429 DTLS ClientKeyExchange message to the ticket Face received in the 1430 Ticket Grant message and uses the ticket Verifier as PSK when 1431 constructing the premaster secret. 1433 11.2. Combined Authentication Manager and Authorization Server 1435 In certain scenarios, AM and AS may be combined to a single entity 1436 that knows both, C and RS, and decides if their actions are 1437 authorized. Therefore, no explicit communication between AM and AS 1438 is necessary, resulting in omission of the Ticket Request and Ticket 1439 Grant messages. Figure 9 depicts the resulting message sequence in 1440 this simplified architecture. 1442 C AM+AS RS 1443 | <== DTLS chan. ==> | <== DTLS chan. ==> | 1444 | | | 1445 | [Resource Req.----------------------->] | 1446 | | | 1447 | [<--------------------- AS Information] | 1448 | | | 1449 | Access Request --> | | 1450 | | | 1451 | <-- Ticket Transf. | | 1452 | | | 1453 | <=========== DTLS channel ===========> | 1454 | | | 1455 | Authorized Resource Request ----------> | 1457 Figure 9: Combined Authentication Manager and Authorization Server 1459 11.2.1. Processing the Access Request Message 1461 When receiving an Access Request message, AM+AS performs the checks 1462 specified in Section 3.5 and returns a 4.00 (Bad Request) response in 1463 case of failure. Otherwise, if the checks have succeeded, AM+AS 1464 evaluates the contents of Access Request message as described in 1465 Section 3.6. 1467 The decision on the access request is performed by AM+AS with respect 1468 to the stored policies. When the requested action is permitted on 1469 the respective resource, AM+AS generates an access ticket as outlined 1470 in Section 4.1 and creates a Ticket Transfer message to convey the 1471 access ticket to the Client. 1473 11.2.2. Creating the Ticket Transfer Message 1475 A Ticket Transfer message is constructed as a 2.05 response with the 1476 access ticket contained in its payload. The response MAY contain a 1477 Max-Age option to indicate the ticket's lifetime to the receiving 1478 Client. 1480 This specification defines a CBOR data representation for the access 1481 ticket as illustrated in Section 3.6. 1483 11.3. Combined Authorization Server and Resource Server 1485 If AS and RS are colocated in one entity (AS+RS), the main objective 1486 is to allow AM to delegate access to C. Accordingly, the 1487 authorization information could be replaced by a nonce internal to 1488 AS+RS. (TBD.) 1490 AM C AS+RS 1491 | <== DTLS chan. ==> | | 1492 | | [Resource Req.-->] | 1493 | | | 1494 | | [<-- AS Info.] | 1495 | | | 1496 | <-- Access Req. | | 1497 | | | 1498 | <========= TLS/DTLS channel =========> | 1499 | | | 1500 | Ticket Request ---------------------> | 1501 | | | 1502 | <--------------------- Ticket Grant | 1503 | | | 1504 | Ticket Transf. --> | | 1505 | | | 1506 | | <== DTLS chan. ==> | 1507 | | Auth. Res. Req. -> | 1509 Figure 10: Combined Authorization Server and Resource Server 1511 12. Security Considerations 1513 As this protocol builds on transitive trust between authorization 1514 servers as mentioned in Section 8, AS has no direct means to validate 1515 that a resource request originates from C. It has to trust AM that it 1516 correctly vouches for C and that it does not give authorization 1517 tickets meant for C to another client nor disclose the contained 1518 session key. 1520 The Authorization Server also could constitute a single point of 1521 failure. If the Authorization Server fails, the resources on all 1522 Resource Servers it is responsible for cannot be accessed any more. 1523 Thus, it is crucial for large networks to use Authorization Servers 1524 in a redundant setup. 1526 13. IANA Considerations 1528 The following registrations are done following the procedure 1529 specified in [RFC6838]. 1531 Note to RFC Editor: Please replace all occurrences of "[RFC-XXXX]" 1532 with the RFC number of this specification. 1534 13.1. DTLS PSK Key Generation Methods 1536 A sub-registry for the values indicating the PSK key generation 1537 method as contents of the field G in a payload of type application/ 1538 dcaf+cbor is defined. Values in this sub-registry are numeric 1539 integers encoded in Concise Binary Object Notation (CBOR, [RFC7049]). 1540 This document follows the notation of [RFC7049] for binary values, 1541 i.e. a number starts with the prefix "0b". The major type is 1542 separated from the actual numeric value by an underscore to emphasize 1543 the value's internal structure. 1545 Initial entries in this sub-registry are as follows: 1547 +---------------+-------------+------------+ 1548 | Encoded Value | Name | Reference | 1549 +---------------+-------------+------------+ 1550 | 0b000_00000 | hmac_sha256 | [RFC-XXXX] | 1551 | | | | 1552 | 0b000_00001 | hmac_sha384 | [RFC-XXXX] | 1553 | | | | 1554 | 0b000_00010 | hmac_sha512 | [RFC-XXXX] | 1555 +---------------+-------------+------------+ 1557 Table 3: DTLS PSK Key Generation Methods 1559 New methods can be added to this registry based on designated expert 1560 review according to [RFC5226]. 1562 (TBD: criteria for expert review.) 1564 13.2. dcaf+cbor Media Type Registration 1566 Type name: application 1567 Subtype name: dcaf+cbor 1569 Required parameters: none 1571 Optional parameters: none 1573 Encoding considerations: Must be encoded as using a subset of the 1574 encoding allowed in [RFC7049]. Specifically, only the primitive data 1575 types String and Number are allowed. The type Number is restricted 1576 to unsigned integers (i.e., no negative numbers, fractions or 1577 exponents are allowed). Encoding MUST be UTF-8. These restrictions 1578 simplify implementations on devices that have very limited memory 1579 capacity. 1581 Security considerations: TBD 1583 Interoperability considerations: TBD 1585 Published specification: [RFC-XXXX] 1587 Applications that use this media type: TBD 1589 Additional information: 1591 Magic number(s): none 1593 File extension(s): dcaf 1595 Macintosh file type code(s): none 1597 Person & email address to contact for further information: TBD 1599 Intended usage: COMMON 1601 Restrictions on usage: None 1603 Author: TBD 1605 Change controller: IESG 1607 13.3. CoAP Content Format Registration 1609 This document specifies a new media type application/dcaf+cbor (cf. 1610 Section 13.2). For use with CoAP, a numeric Content-Format 1611 identifier is to be registered in the "CoAP Content-Formats" sub- 1612 registry within the "CoRE Parameters" registry. 1614 Note to RFC Editor: Please replace all occurrences of "RFC-XXXX" with 1615 the RFC number of this specification. 1617 +-----------------------+----------+------+------------+ 1618 | Media type | Encoding | Id. | Reference | 1619 +-----------------------+----------+------+------------+ 1620 | application/dcaf+cbor | - | TBD1 | [RFC-XXXX] | 1621 +-----------------------+----------+------+------------+ 1623 14. References 1625 14.1. Normative References 1627 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1628 Requirement Levels", BCP 14, RFC 2119, March 1997. 1630 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 1631 Resource Identifier (URI): Generic Syntax", STD 66, RFC 1632 3986, January 2005. 1634 [RFC4279] Eronen, P. and H. Tschofenig, "Pre-Shared Key Ciphersuites 1635 for Transport Layer Security (TLS)", RFC 4279, December 1636 2005. 1638 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 1639 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 1640 May 2008. 1642 [RFC5746] Rescorla, E., Ray, M., Dispensa, S., and N. Oskov, 1643 "Transport Layer Security (TLS) Renegotiation Indication 1644 Extension", RFC 5746, February 2010. 1646 [RFC6347] Rescorla, E. and N. Modadugu, "Datagram Transport Layer 1647 Security Version 1.2", RFC 6347, January 2012. 1649 [RFC6838] Freed, N., Klensin, J., and T. Hansen, "Media Type 1650 Specifications and Registration Procedures", BCP 13, RFC 1651 6838, January 2013. 1653 [RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object 1654 Representation (CBOR)", RFC 7049, October 2013. 1656 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 1657 Application Protocol (CoAP)", RFC 7252, June 2014. 1659 14.2. Informative References 1661 [I-D.bormann-core-ace-aif] 1662 Bormann, C., "An Authorization Information Format (AIF) 1663 for ACE", draft-bormann-core-ace-aif-00 (work in 1664 progress), January 2014. 1666 [I-D.ietf-core-block] 1667 Bormann, C. and Z. Shelby, "Blockwise transfers in CoAP", 1668 draft-ietf-core-block-15 (work in progress), July 2014. 1670 [I-D.ietf-core-observe] 1671 Hartke, K., "Observing Resources in CoAP", draft-ietf- 1672 core-observe-14 (work in progress), June 2014. 1674 [I-D.ietf-core-resource-directory] 1675 Shelby, Z., Bormann, C., and S. Krco, "CoRE Resource 1676 Directory", draft-ietf-core-resource-directory-01 (work in 1677 progress), December 2013. 1679 [I-D.schmertmann-dice-codtls] 1680 Schmertmann, L., Hartke, K., and C. Bormann, "CoDTLS: DTLS 1681 handshakes over CoAP", draft-schmertmann-dice-codtls-00 1682 (work in progress), February 2014. 1684 [RFC5988] Nottingham, M., "Web Linking", RFC 5988, October 2010. 1686 [RFC6655] McGrew, D. and D. Bailey, "AES-CCM Cipher Suites for 1687 Transport Layer Security (TLS)", RFC 6655, July 2012. 1689 [RFC6690] Shelby, Z., "Constrained RESTful Environments (CoRE) Link 1690 Format", RFC 6690, August 2012. 1692 [bergmann12] 1693 Bergmann, O., Gerdes, S., Schaefer, S., Junge, F., and C. 1694 Bormann, "Secure Bootstrapping of Nodes in a CoAP 1695 Network", IEEE Wireless Communications and Networking 1696 Conference Workshops (WCNCW), April 2012. 1698 Authors' Addresses 1700 Stefanie Gerdes 1701 Universitaet Bremen TZI 1702 Postfach 330440 1703 Bremen D-28359 1704 Germany 1706 Phone: +49-421-218-63906 1707 Email: gerdes@tzi.org 1708 Olaf Bergmann 1709 Universitaet Bremen TZI 1710 Postfach 330440 1711 Bremen D-28359 1712 Germany 1714 Phone: +49-421-218-63904 1715 Email: bergmann@tzi.org 1717 Carsten Bormann 1718 Universitaet Bremen TZI 1719 Postfach 330440 1720 Bremen D-28359 1721 Germany 1723 Phone: +49-421-218-63921 1724 Email: cabo@tzi.org