idnits 2.17.1 draft-gerdes-ace-dcaf-authorize-02.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 (March 09, 2015) is 3326 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 1706, 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-01 == Outdated reference: A later version (-05) exists of draft-gerdes-ace-actors-02 == Outdated reference: A later version (-21) exists of draft-ietf-core-block-16 == Outdated reference: A later version (-28) exists of draft-ietf-core-resource-directory-02 -- Obsolete informational reference (is this intentional?): RFC 5988 (Obsoleted by RFC 8288) Summary: 3 errors (**), 0 flaws (~~), 6 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: September 10, 2015 Universitaet Bremen TZI 6 March 09, 2015 8 Delegated CoAP Authentication and Authorization Framework (DCAF) 9 draft-gerdes-ace-dcaf-authorize-02 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 September 10, 2015. 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 1.1. Features . . . . . . . . . . . . . . . . . . . . . . . . 4 60 1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 4 61 1.2.1. Actors . . . . . . . . . . . . . . . . . . . . . . . 4 62 1.2.2. Other Terms . . . . . . . . . . . . . . . . . . . . . 5 63 2. System Overview . . . . . . . . . . . . . . . . . . . . . . . 6 64 3. Protocol . . . . . . . . . . . . . . . . . . . . . . . . . . 6 65 3.1. Overview . . . . . . . . . . . . . . . . . . . . . . . . 7 66 3.2. Unauthorized Resource Request Message . . . . . . . . . . 8 67 3.3. SAM Information Message . . . . . . . . . . . . . . . . . 9 68 3.4. Access Request . . . . . . . . . . . . . . . . . . . . . 10 69 3.5. Ticket Request Message . . . . . . . . . . . . . . . . . 11 70 3.6. Ticket Grant Message . . . . . . . . . . . . . . . . . . 12 71 3.7. Ticket Transfer Message . . . . . . . . . . . . . . . . . 13 72 3.8. DTLS Channel Setup Between C and S . . . . . . . . . . . 14 73 3.9. Authorized Resource Request Message . . . . . . . . . . . 15 74 3.10. Dynamic Update of Authorization Information . . . . . . . 16 75 3.10.1. Handling of Ticket Transfer Messages . . . . . . . . 17 76 4. Ticket . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 77 4.1. Face . . . . . . . . . . . . . . . . . . . . . . . . . . 18 78 4.2. CI . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 79 4.3. Revocation . . . . . . . . . . . . . . . . . . . . . . . 19 80 4.3.1. Lifetime . . . . . . . . . . . . . . . . . . . . . . 19 81 4.3.2. Revocation Messages . . . . . . . . . . . . . . . . . 20 82 5. Payload Format and Encoding (application/dcaf+cbor) . . . . . 20 83 5.1. Examples . . . . . . . . . . . . . . . . . . . . . . . . 23 84 6. DTLS PSK Generation Methods . . . . . . . . . . . . . . . . . 25 85 6.1. DTLS PSK Transfer . . . . . . . . . . . . . . . . . . . . 25 86 6.2. Distributed Key Derivation . . . . . . . . . . . . . . . 25 87 7. Authorization Configuration . . . . . . . . . . . . . . . . . 26 88 8. Trust Relationships . . . . . . . . . . . . . . . . . . . . . 26 89 9. Listing Authorization Manager Information in a Resource 90 Directory . . . . . . . . . . . . . . . . . . . . . . . . . . 27 91 9.1. The "auth-request" Link Relation . . . . . . . . . . . . 27 92 10. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 28 93 10.1. Access Granted . . . . . . . . . . . . . . . . . . . . . 28 94 10.2. Access Denied . . . . . . . . . . . . . . . . . . . . . 30 95 10.3. Access Restricted . . . . . . . . . . . . . . . . . . . 31 96 10.4. Implicit Authorization . . . . . . . . . . . . . . . . . 32 98 11. Specific Usage Scenarios . . . . . . . . . . . . . . . . . . 33 99 11.1. Combined Authorization Manager and Client . . . . . . . 33 100 11.1.1. Creating the Ticket Request Message . . . . . . . . 33 101 11.1.2. Processing the Ticket Grant Message . . . . . . . . 34 102 11.2. Combined Client Authorization Manager and Server 103 Authorization Manager . . . . . . . . . . . . . . . . . 34 104 11.2.1. Processing the Access Request Message . . . . . . . 35 105 11.2.2. Creating the Ticket Transfer Message . . . . . . . . 35 106 11.3. Combined Server Authorization Manager and Server . . . . 35 107 12. Security Considerations . . . . . . . . . . . . . . . . . . . 36 108 13. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 36 109 13.1. DTLS PSK Key Generation Methods . . . . . . . . . . . . 37 110 13.2. dcaf+cbor Media Type Registration . . . . . . . . . . . 37 111 13.3. CoAP Content Format Registration . . . . . . . . . . . . 38 112 14. References . . . . . . . . . . . . . . . . . . . . . . . . . 38 113 14.1. Normative References . . . . . . . . . . . . . . . . . . 39 114 14.2. Informative References . . . . . . . . . . . . . . . . . 39 115 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 40 117 1. Introduction 119 The Constrained Application Protocol (CoAP) [RFC7252] is a transfer 120 protocol similar to HTTP which is designed for the special 121 requirements of constrained environments. A serious problem with 122 constrained devices is the realization of secure communication. The 123 devices only have limited system resources such as memory, stable 124 storage (such as disk space) and transmission capacity and often lack 125 input/output devices such as keyboards or displays. Therefore, they 126 are not readily capable of using common protocols. Especially 127 authentication mechanisms are difficult to realize, because the lack 128 of stable storage severely limits the number of keys the system can 129 store. Moreover, CoAP has no mechanism for authorization. 131 [I-D.gerdes-ace-actors] describes an architecture that is designed to 132 help constrained nodes with authorization-related tasks by 133 introducing less-constrained nodes. These Authorization Managers 134 perform complex security tasks for their nodes such as managing keys 135 for numerous devices, and enable the constrained nodes to enforce the 136 authorization policies of their principals. 138 DCAF uses access tokens to implement this architecture. A device 139 that wants to access an item of interest on a constrained node first 140 has to gain permission in the form of a token from the node's 141 Authorization Manager. 143 As fine-grained authorization is not always needed on constrained 144 devices, DCAF supports an implicit authorization mode where no 145 authorization information is exchanged. 147 The main goals of DCAF are the setup of a Datagram Transport Layer 148 Security (DTLS) [RFC6347] channel with symmetric pre-shared keys 149 (PSK) [RFC4279] between two nodes and to securely transmit 150 authorization tickets. 152 1.1. Features 154 o Utilize DTLS communication with pre-shared keys. 156 o Authenticated exchange of authorization information. 158 o Simplified authentication on constrained nodes by handing the more 159 sophisticated authentication over to less-constrained devices. 161 o Support of secure constrained device to constrained device 162 communication. 164 o Authorization policies of the principals of both participating 165 parties are ensured. 167 o Simplified authorization mechanism for cases where implicit 168 authorization is sufficient. 170 o Using only symmetric encryption on constrained nodes. 172 1.2. Terminology 174 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 175 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 176 document are to be interpreted as described in RFC 2119 [RFC2119]. 178 Readers are expected to be familiar with the terms and concepts 179 defined in [I-D.gerdes-ace-actors]. 181 1.2.1. Actors 183 Server (S): An endpoint that hosts and represents a CoAP resource. 185 Client (C): An endpoint that attempts to access a CoAP resource on 186 the Server. 188 Server Authorization Manager (SAM): An entity that prepares and 189 endorses authentication and authorization data for a Server. 191 Client Authorization Manager (CAM): An entity that prepares and 192 endorses authentication and authorization data for a Client. 194 Authorization Manager (AM): An entity that is either a SAM or a CAM. 196 Client Overseeing Principal (COP): The principal that is in charge 197 of the Client and controls permissions concerning authorized 198 representations of a CoAP resource. 200 Resource Overseeing Principal (ROP): The principal that is in charge 201 of the CoAP resource and controls its access permissions. 203 1.2.2. Other Terms 205 Resource: A CoAP resource. 207 Authorization information: Contains all information needed by S to 208 decide if C is privileged to access a resource in a specific way. 210 Authentication information: Contains all information needed by S to 211 decide if the entity in possession of a certain key is verified by 212 SAM. 214 Access information: Contains authentication information and, if 215 necessary, authorization information. 217 Access ticket: Contains the authentication and, if necessary, the 218 authorization information needed to access a resource. A Ticket 219 consists of the Ticket Face and the Client Information. The 220 access ticket is a representation of the access information. 222 Ticket Face: The part of the ticket which is generated for the 223 Server. It contains the authorization information and all 224 information needed by the Server to verify that it was granted by 225 SAM. 227 Client Information (CI): The part of the ticket which is generated 228 for the Client. It contains the Verifier and optionally may 229 contain authorization information that represent COP's 230 authorization policies for C. 232 Verifier: It enables the client to verify that it is communicating 233 with an appropriate S. 235 Explicit authorization: SAM informs the S in detail which privileges 236 are granted to the Client. 238 Implicit authorization: SAM authenticates the Client for the Server 239 without specifying the privileges in detail. This can be used for 240 binary or unrestricted authorization (cf section 4 of 241 [I-D.gerdes-ace-actors]). 243 2. System Overview 245 Within the DCAF Architecture each Server (S) has a Server 246 Authorization Manger (SAM) which conducts the authentication and 247 authorization for S. S and SAM share a symmetric key which has to be 248 exchanged initially to provide for a secure channel. The mechanism 249 used for this is not in the scope of this document. 251 To gain access to a specific resource on a S, a Client (C) has to 252 request an access ticket from the SAM serving S either directly or, 253 if it is a constrained device, using its Client Authorization Manager 254 (CAM). In the following, we always discuss the CAM role separately, 255 even if that is co-located within a (more powerful) C (see section 256 Section 11 for details about co-located actors). 258 CAM decides if S is an authorized source for R according to the 259 policies set by COP and in this case transmits the request to SAM. 260 If SAM decides that C is allowed to access the resource according to 261 the policies set by ROP, it generates a DTLS pre-shared key (PSK) for 262 the communication between C and S and wraps it into an access ticket. 263 For explicit access control, SAM adds the detailed access permissions 264 to the ticket in a way that CAM and S can interpret. CAM checks if 265 the permissions in the access ticket comply with COP's authorization 266 policies for C, and if this is the case sends it to C. After C 267 presented the ticket to S, C and S can communicate securely. 269 To be able to provide for the authentication and authorization 270 services, an Authorization Manager has to fulfill several 271 requirements: 273 o AM must have enough stable storage (such as disk space) to store 274 the necessary number of credentials (matching the number of 275 Clients and Servers). 277 o AM must possess means for user interaction, for example directly 278 or indirectly connected input/output devices such as keyboard and 279 display, to allow for configuration of authorization information 280 by the respective Principal. 282 o AM must have enough processing power to handle the authorization 283 requests for all constrained devices it is responsible for. 285 3. Protocol 287 The DCAF protocol comprises three parts: 289 1. transfer of authentication and, if necessary, authorization 290 information between C and S; 292 2. transfer of access requests and the respective ticket grants 293 between C and CAM; and 295 3. transfer of access requests and the respective ticket grants 296 between SAM and CAM. 298 3.1. Overview 300 In Figure 1, a DCAF protocol flow is depicted (messages in square 301 brackets are optional): 303 CAM C S SAM 304 | <== DTLS chan. ==> | | <== DTLS chan. ==> | 305 | | [Resource Req.-->] | | 306 | | | | 307 | | [<-- SAM Info.] | | 308 | | | | 309 | <-- Access Req. | | | 310 | | | | 311 | <==== TLS/DTLS channel (CAM/SAM Mutual Authentication) ====> | 312 | | | | 313 | Ticket Request ------------------------------------------> | 314 | | | | 315 | <------------------------------------------ Ticket Grant | 316 | | | | 317 | Ticket Transf. --> | | | 318 | | | | 319 | | <== DTLS chan. ==> | | 320 | | Auth. Res. Req. -> | | 322 Figure 1: Protocol Overview 324 To determine the SAM in charge of a resource hosted at the S, C MAY 325 send an initial Unauthorized Resource Request message to S. S then 326 denies the request and sends the address of its SAM back to C. 328 Instead of the initial Unauthorized Resource Request message, C MAY 329 look up the desired resource in a resource directory (cf. 330 [I-D.ietf-core-resource-directory]) that lists S's resources as 331 discussed in Section 9. 333 Once C knows SAM's address, it can send a request for authorization 334 to SAM using its own CAM. CAM and SAM authenticate each other and 335 each determine if the request is to be authorized. If it is, SAM 336 generates an access ticket for C. The ticket contains keying 337 material for the establishment of a secure channel and, if necessary, 338 a representation of the permissions C has for the resource. C keeps 339 one part of the access ticket and presents the other part to S to 340 prove its right to access. With their respective parts of the 341 ticket, C and S are able to establish a secure channel. 343 The following sections specify how CoAP is used to interchange 344 access-related data between S and SAM so that SAM can provide C and S 345 with sufficient information to establish a secure channel, and 346 simultaneously convey authorization information specific for this 347 communication relationship to S. 349 Note: Special implementation considerations apply when one single 350 entity takes the role of more than one actors. Section 11 gives 351 additional advice on some of these usage scenarios. 353 This document uses Concise Binary Object Representation (CBOR, 354 [RFC7049]) to express authorization information as set of attributes 355 passed in CoAP payloads. Notation and encoding options are discussed 356 in Section 5. 358 3.2. Unauthorized Resource Request Message 360 The optional Unauthorized Resource Request message is a request for a 361 resource hosted by S for which no proper authorization is granted. S 362 MUST treat any CoAP request as Unauthorized Resource Request message 363 when any of the following holds: 365 o The request has been received on an insecure channel. 367 o S has no valid access ticket for the sender of the request 368 regarding the requested action on that resource. 370 o S has a valid access ticket for the sender of the request, but 371 this does not allow the requested action on the requested 372 resource. 374 Note: These conditions ensure that S can handle requests autonomously 375 once access was granted and a secure channel has been established 376 between C and S. 378 Unauthorized Resource Request messages MUST be denied with a client 379 error response. In this response, the Server MUST provide proper SAM 380 Information to enable the Client to request an access ticket from S's 381 SAM as described in Section 3.3. 383 The response code MUST be 4.01 (Unauthorized) in case the sender of 384 the Unauthorized Resource Request message is not authenticated, or if 385 S has no valid access ticket for C. If S has an access ticket for C 386 but not for the resource that C has requested, S MUST reject the 387 request with a 4.03 (Forbidden). If S has an access ticket for C but 388 it does not cover the action C requested on the resource, S MUST 389 reject the request with a 4.05 (Method Not Allowed). 391 Note: The use of the response codes 4.03 and 4.05 is intended to 392 prevent infinite loops where a dumb Client optimistically tries to 393 access a requested resource with any access token received from 394 the SAM. As malicious clients could pretend to be C to determine 395 C's privileges, these detailed response codes must be used only 396 when a certain level of security is already available which can be 397 achieved only when the Client is authenticated. 399 3.3. SAM Information Message 401 The SAM Information Message is sent by S as a response to an 402 Unauthorized Resource Request message (see Section 3.2) to point the 403 sender of the Unauthorized Resource Request message to S's SAM. The 404 SAM information is a set of attributes containing an absolute URI 405 (see Section 4.3 of [RFC3986]) that specifies the SAM in charge of S. 407 The message MAY also contain a timestamp generated by S. 409 Figure 2 shows an example for an SAM Information message payload 410 using CBOR diagnostic notation. (Refer to Section 5 for a detailed 411 description of the available attributes and their semantics.) 413 4.01 Unauthorized 414 Content-Format: application/dcaf+cbor 415 {SAM: "coaps://sam.example.com/authorize", TS: 168537} 417 Figure 2: SAM Information Payload Example 419 In this example, the attribute SAM points the receiver of this 420 message to the URI "coaps://sam.example.com/authorize" to request 421 access permissions. The originator of the SAM Information payload 422 (i.e. S) uses a local clock that is loosely synchronized with a time 423 scale common between S and SAM (e.g., wall clock time). Therefore, 424 it has included a time stamp on its own time scale that is used as a 425 nonce for replay attack prevention. Refer to Section 4.1 for more 426 details concerning the usage of time stamps to ensure freshness of 427 access tickets. 429 The examples in this document are written in CBOR diagnostic notation 430 to improve readability. Figure 3 illustrates the binary encoding of 431 the message payload shown in Figure 2. 433 a2 # map(2) 434 00 # unsigned(0) (=SAM) 435 78 21 # text(33) 436 636f6170733a2f2f73616d2e6578 437 616d706c652e636f6d2f617574686f72 438 697a65 # "coaps://sam.example.com/authorize" 439 05 # unsigned(5) (=TS) 440 1a 00029259 # unsigned(168537) 442 Figure 3: SAM Information Payload Example encoded in CBOR 444 3.4. Access Request 446 To retrieve an access ticket for the resource that C wants to access, 447 C sends an Access Request to its CAM. The Access Request is 448 constructed as follows: 450 1. The request method is POST. 452 2. The request URI is set as described below. 454 3. The message payload contains a data structure that describes the 455 action and resource for which C requests an access ticket. 457 The request URI identifies a resource at CAM for handling 458 authorization requests from C. The URI SHOULD be announced by CAM in 459 its resource directory as described in Section 9. 461 Note: Where capacity limitations of C do not allow for resource 462 directory lookups, the request URI in Access Requests could be 463 hard-coded during provisioning or set in a specific device 464 configuration profile. 466 The message payload is constructed from the SAM information that S 467 has returned in its SAM Information message (see Section 3.3) and 468 information that C provides to describe its intended request(s). The 469 Access Request MUST contain the following attributes: 471 1. Contact information for the SAM to use. 473 2. An absolute URI of the resource that C wants to access. 475 3. The actions that C wants to perform on the resource. 477 4. Any time stamp generated by S. 479 An example Access Request from C to CAM is depicted in Figure 4. 480 (Refer to Section 5 for a detailed description of the available 481 attributes and their semantics.) 483 POST client-authorize 484 Content-Format: application/dcaf+cbor 485 { 486 SAM: "coaps://sam.example.com/authorize", 487 SAI: ["coaps://temp451.example.com/s/tempC", 5], 488 TS: 168537 489 } 491 Figure 4: Access Request Message Example 493 The example shows an Access Request message payload for the resource 494 "/s/tempC" on the Server "temp451.example.com". Requested operations 495 in attribute SAI are GET and PUT. 497 The attributes SAM (that denotes the Server Authorization Manager to 498 use) and TS (a nonce generated by S) are taken from the SAM 499 Information message from S. 501 The response to an Authorization Request is delivered by CAM back to 502 C in a Ticket Transfer message. 504 3.5. Ticket Request Message 506 When CAM receives an Access Request message from C and COP specified 507 authorization policies for C, CAM MUST check if the requested actions 508 are allowed according to these policies. If this is not the case, 509 CAM MUST send a 4.03 response. 511 If no authorization policies were specified or the requested action 512 is allowed according to the authorization policies, CAM either 513 returns a cached response or attempts to create a Ticket Request 514 message. 516 CAM MAY return a cached response if it is known to be fresh according 517 to Max-Age. CAM SHOULD NOT return a cached response if it expires in 518 less than a minute. 520 If CAM does not send a cached response, it checks whether the request 521 payload is of type "application/dcaf+cbor and contains at least the 522 fields SAM and SAI. CAM MUST respond with 4.00 (Bad Request) if the 523 type is "application/dcaf+cbor and any of these fields is missing or 524 does not conform to the format described in Section 5. Content 525 formats other than application/dcaf+cbor are out of scope of this 526 specification. 528 If the payload is correct, CAM creates a Ticket Request message from 529 the Access Request received from C as follows: 531 1. The destination of the Ticket Request message is derived from the 532 authority information in the URI contained in field "SAM" of the 533 Access Request message payload. 535 2. The request method is POST. 537 3. The request URI is constructed from the SAM field received in the 538 Access Request message payload. 540 4. The payload is copied from the Access Request sent by C. 542 5. A label that describes the Client is added to the payload 544 To send the Ticket Request message to SAM a secure channel between 545 CAM and SAM MUST be used. Depending on the URI scheme used in the 546 SAM field of the Access Request message payload (the less-constrained 547 devices CAM and SAM do not necessarily use CoAP to communicate with 548 each other), this could be, e.g., a DTLS channel (for "coaps") or a 549 TLS connection (for "https"). CAM and SAM MUST be able to mutually 550 authenticate each other, e.g. based on a public key infrastructure. 551 (Refer to Section 8 for a detailed discussion of the trust 552 relationship between Client Authorization Managers and Server 553 Authorization Managers.) 555 3.6. Ticket Grant Message 557 When SAM has received a Ticket Request message it has to evaluate the 558 access request information contained therein. First, it checks 559 whether the request payload is of type "application/dcaf+cbor" and 560 contains at least the fields SAM and SAI. SAM MUST respond with 4.00 561 (Bad Request) for CoAP (or 400 for HTTP) if the type is "application/ 562 dcaf+cbor" and any of these fields is missing or does not conform to 563 the format described in Section 5. 565 SAM decides whether or not access is granted to the requested 566 resource and then creates a Ticket Grant message that reflects the 567 result. To grant access to the requested resource, SAM creates an 568 access ticket comprised of a Face and the Client Information as 569 described in Section 4.1. 571 The Ticket Grant message then is constructed as a success response 572 indicating attached content, i.e. 2.05 for CoAP, or 200 for HTTP, 573 respectively. The payload of the Ticket Grant message is a data 574 structure that contains the result of the access request. When 575 access is granted, the data structure contains the Ticket Face, the 576 Client Information, which at this point only consists of the Verifier 577 and the Session Key Generation Method. 579 The Ticket Grant message MAY provide cache-control options to enable 580 intermediaries to cache the response. The message MAY be cached 581 according to the rules defined in [RFC7252] to facilitate ticket 582 retrieval when C has crashed and wants to recover the DTLS session 583 with S. 585 SAM SHOULD set Max-Age according to the ticket lifetime in its 586 response (Ticket Grant Message). 588 Figure 5 shows an example Ticket Grant message using CoAP. The Face/ 589 Verifier information is transferred as a CBOR data structure as 590 specified in Section 5. The Max-Age option tells the receiving CAM 591 how long this ticket will be valid. 593 2.05 Content 594 Content-Format: application/dcaf+cbor 595 Max-Age: 86400 596 { F: { 597 SAI: [ "/s/tempC", 7 ], 598 TS: 0("2013-07-10T10:04:12.391"), 599 L: 86400, 600 G: hmac_sha256 601 }, 602 V: h'f89947160c73601c7a65cb5e08812026 603 6d0f0565160e3ff7d3907441cdf44cc9' 604 } 606 Figure 5: Example Ticket Grant Message 608 A Ticket Grant message that declines any operation on the requested 609 resource is illustrated in Figure 6. As no ticket needs to be 610 issued, an empty payload is included with the response. 612 2.05 Content 613 Content-Format: application/dcaf+cbor 615 Figure 6: Example Ticket Grant Message With Reject 617 3.7. Ticket Transfer Message 619 A Ticket Transfer message delivers the access information sent by SAM 620 in a Ticket Grant message to the requesting client C. The Ticket 621 Transfer message is the response to the Access Request message sent 622 from C to CAM and includes any access information from SAM contained 623 in the Ticket Grant message. 625 The Authorization Information provided by SAM in the Ticket Grant 626 Message may grant more permissions than C has requested. The 627 authorization policies of COP and ROP may differ: COP might want 628 restrict the resources C is allowed to access, and the actions that C 629 is allowed to perform on the resource. 631 If CAM must ensure authorization policies COP configured , CAM MUST 632 add Authorization Information for C (CAI) to the CI. Since C and CAM 633 use a DTLS channel for communication, the autorization information 634 does not need to be encrypted. 636 CAM includes the Face and Verifier sent by SAM in the Ticket Transfer 637 message. CAM MUST NOT include any other information SAM provided. 638 In particular, CAM MUST NOT include any CAI information provided by 639 SAM. 641 Figure 7 shows an example Ticket Transfer message that conveys the 642 permissions for actions GET, POST, PUT (but not DELETE) on the 643 resource "/s/tempC" in field SAI. As CAM only wants to permit 644 outbound GET requests, it restricts C's permissions in the field CAI 645 accordingly. 647 2.05 Content 648 Content-Format: application/dcaf+cbor 649 Max-Age: 86400 650 { F: { 651 SAI: [ "/s/tempC", 7 ], 652 TS: 0("2013-07-10T10:04:12.391"), 653 L: 86400, 654 G: hmac_sha256 655 }, 656 V: h'f89947160c73601c7a65cb5e08812026 657 6d0f0565160e3ff7d3907441cdf44cc9' 658 CAI: [ "/s/tempC", 1 ], 659 TS: 0("2013-07-10T10:04:12.855"), 660 L: 86400 661 } 663 Figure 7: Example Ticket Transfer Message 665 3.8. DTLS Channel Setup Between C and S 667 Using the information contained in a positive response to its Access 668 Request (i.e. a Ticket Transfer message that contains a Face and a 669 Client Information), C can initiate establishment of a new DTLS 670 channel with S. To use DTLS with pre-shared keys, C follows the PSK 671 key exchange algorithm specified in Section 2 of [RFC4279], with the 672 following additional requirements: 674 1. C sets the psk_identity field of the ClientKeyExchange message to 675 the ticket Face received in the Ticket Transfer message. 677 2. C uses the ticket Verifier as PSK when constructing the premaster 678 secret. 680 Note1: As S cannot provide C with a meaningful PSK identity hint in 681 response to C's ClientHello message, S SHOULD NOT send a 682 ServerKeyExchange message. 684 Note2: According to [RFC7252], CoAP implementations MUST support the 685 ciphersuite TLS_PSK_WITH_AES_128_CCM_8 [RFC6655]. C is therefore 686 expected to offer at least this ciphersuite to S. 688 Note3: The ticket is constructed by SAM such that S can derive the 689 authorization information as well as the PSK (refer to Section 6 for 690 details). 692 3.9. Authorized Resource Request Message 694 If the Client Information in the Ticket Transfer message contains 695 CAI, C MUST ensure that it only sends requests that according to them 696 are allowed. C therefore MUST check CAI, L and T before every 697 request. If CAI is no longer valid according to L, C MUST terminate 698 the DTLS connection with S and re-request the CAI from CAM using an 699 Access Request Message. 701 On the Server side, successful establishment of the DTLS channel 702 between C and S ties the SAM authorization information contained in 703 the psk_identity field to this channel. Any request that S receives 704 on this channel is checked against these authorization rules. 705 Incoming CoAP requests that are not Authorized Resource Requests MUST 706 be rejected by S with 4.01 response as described in Section 3.2. 708 S SHOULD treat an incoming CoAP request as Authorized Resource 709 Request if the following holds: 711 1. The message was received on a secure channel that has been 712 established using the procedure defined in Section 3.8. 714 2. The authorization information tied to the secure channel is 715 valid. 717 3. The request is destined for S. 719 4. The resource URI specified in the request is covered by the 720 authorization information. 722 5. The request method is an authorized action on the resource with 723 respect to the authorization information. 725 Note that the authorization information is not restricted to a single 726 resource URI. For example, role-based authorization can be used to 727 authorize a collection of semantically connected resources 728 simultaneously. Implicit authorization also provides access rights 729 to authenticated clients for all actions on all resources that S 730 offers. As a result, C can use the same DTLS channel not only for 731 subsequent requests for the same resource (e.g. for block-wise 732 transfer as defined in [I-D.ietf-core-block] or refreshing observe- 733 relationships [I-D.ietf-core-observe]) but also for requests to 734 distinct resources. 736 Incoming CoAP requests received on a secure channel according to the 737 procedure defined in Section 3.8 MUST be rejected 739 1. with response code 4.03 (Forbidden) when the resource URI 740 specified in the request is not covered by the authorization 741 information, and 743 2. with response code 4.05 (Method Not Allowed) when the resource 744 URI specified in the request covered by the authorization 745 information but not the requested action. 747 Since SAM may limit the set of requested actions in its Ticket Grant 748 message, C cannot know a priori if an Authorized Resource Request 749 will succeed. 751 3.10. Dynamic Update of Authorization Information 753 Once a security association exists between a Client and a Resource 754 Server, the Client can update the Authorization Information stored at 755 the Server at any time. To do so, the Client creates a new Access 756 Request for the intended action on the respective resource and sends 757 this request to its CAM which checks and relays this request to the 758 Server's SAM as described in Section 3.4. 760 Note: Requesting a new Access Ticket also can be a Client's reaction 761 on a 4.03 or 4.05 error that it has received in response to an 762 Authorized Resource Request. 764 Figure 8 depicts the message flow where C requests a new Access 765 Tickets after a security association between C and S has been 766 established using this protocol. 768 CAM C S SAM 769 | <== DTLS chan. ==> | <== DTLS chan. ==> | <== DTLS chan. ==> | 770 | | | | 771 | | [Unauth. R. Req->] | | 772 | |[<- 4.0x+SAM Info.] | | 773 | | | | 774 | <-- Access Req. | | | 775 | | | | 776 | <==== TLS/DTLS channel (CAM/SAM Mutual Authentication) ====> | 777 | | | | 778 | Ticket Request ------------------------------------------> | 779 | | | | 780 | <------------------------------------------ Ticket Grant | 781 | | | | 782 | Ticket Transf. --> | | | 783 | | | | 784 | | <== Update SAI ==> | | 786 Figure 8: Overview of Dynamic Update Operation 788 Processing the Ticket Request is done at the SAM as specified in 789 Section 3.6, i.e. the SAM checks whether or not the requested 790 operation is permitted by the Resource Principal's policy, and then 791 return a Ticket Grant message with the result of this check. If 792 access is granted, the Ticket Grant message contains an Access Ticket 793 comprised of a public Ticket Face and a private Ticket Verifier. 794 This authorization payload is relayed by CAM to the Client in a 795 Ticket Transfer Message as defined in Section 3.7. 797 The major difference between dynamic update of Authorization 798 Information and the initial handshake is the handling of a Ticket 799 Transfer message by the Client that is described in Section 3.10.1. 801 3.10.1. Handling of Ticket Transfer Messages 803 If the security association with S still exists and S has indicated 804 support for session renegotiation according to [RFC5746], the ticket 805 Face SHOULD be used to renegotiate the existing DTLS session. In 806 this case, the ticket Face is used as psk_identity as defined in 807 Section 3.8. Otherwise, the Client MUST perform a new DTLS handshake 808 according to Section 3.8 that replaces the existing DTLS session. 810 After successful completion of the DTLS handshake S updates the 811 existing SAM Authorization Information for C according to the 812 contents of the ticket Face. 814 Note: No mutual authentication between C and S is required for 815 dynamic updates when a DTLS channel exists that has been 816 established as defined in Section 3.8. S only needs to verify the 817 authenticity and integrity of the ticket Face issued by SAM which 818 is achieved by having performed a successful DTLS handshake with 819 the ticket Face as psk_identity. This could even be done within 820 the existing DTLS session by tunneling a CoDTLS 821 [I-D.schmertmann-dice-codtls] handshake. 823 4. Ticket 825 Access tokens in DCAF are tickets that consist of two parts, namely 826 the Face and the Client Information. The Face goes to S, the CI goes 827 to the Client. The Face and the CI are parts of the same ticket. 829 S only needs the information contained in the Ticket Face to 830 authorize the client and make sure that SAM generated the Ticket Face 831 (S cannot make authorization decisions by itself and hence needs SAM 832 to do it). No additional information about the Client is needed. S 833 keeps the Ticket Face as long as it is valid. 835 4.1. Face 837 Face is the part of the ticket generated for S. Face MUST contain 838 all information needed for authorized access to a resource: 840 o SAM Authorization Information 842 o A timestamp generated by SAM 844 Optionally, Face MAY also contain: 846 o A lifetime (optional) 848 o A DTLS pre-shared key (optional) 850 S MUST verify the integrity of Face, i.e. the information contained 851 in Face stems from SAM and was not manipulated by anyone else. 853 Face MUST contain a timestamp to verify that the contained 854 information is fresh. As constrained devices may not have a clock, 855 timestamps MAY be generated using the clock ticks since the last 856 reboot. To circumvent synchronization problems the timestamp MAY be 857 generated by S and included in the first SAM Information message. 858 Alternatively, SAM MAY generate the timestamp. In this case, SAM and 859 S MUST use a time synchronization mechanism to make sure that S 860 interprets the timestamp correctly. 862 Face MAY be encrypted. If Face contains a DTLS PSK, the whole 863 content of Face MUST be encrypted. 865 The integrity of Face can be ensured by various means. Face may be 866 encrypted by SAM with a key it shares with S. Alternatively, S can 867 use a mechanism to generate the DTLS PSK which includes Face. S 868 generates the key from the Face it received. The correct key can 869 only be calculated with the correct Face (refer to Section 6 for 870 details). 872 4.2. CI 874 The CI part of the ticket is generated for C. It contains the 875 Verifier, i.e. the DTLS PSK for C and MAY contain Client 876 Authorization Information generated by CAM to provide the COP's 877 authorization policies to C. The Verifier MUST NOT be transmitted 878 over insecure channels. 880 4.3. Revocation 882 The existence of access tickets SHOULD be limited in time to avoid 883 stale tickets that waste resources on S and C. This can be achieved 884 either by explicit Revocation Messages to invalidate a ticket or 885 implicitly by attaching a lifetime to the ticket. 887 4.3.1. Lifetime 889 Tickets MAY have a lifetime. SAM is responsible for defining the 890 ticket lifetime. If SAM sets a lifetime for a ticket, SAM and S MUST 891 use a time synchronization method to ensure that S is able to 892 interpret the lifetime correctly. S SHOULD end the DTLS connection 893 to C if the lifetime of a ticket has run out and it MUST NOT accept 894 new requests. S MUST NOT accept tickets with an invalid lifetime. 896 If CAM provides CAI in the CI part of the ticket, CAM MAY add a 897 lifetime for this CAI. If CI contains a lifetime, CAM and C MUST use 898 a time synchronization method to ensure that C is able to interpret 899 the lifetime correctly. C SHOULD end the DTLS connection to S and 900 MUST NOT send new requests if the CAI in the ticket is no longer 901 valid. C MUST NOT accept tickets with an invalid lifetime. 903 Note: Defining reasonable ticket lifetimes is difficult to 904 accomplish. How long a client needs to access a resource depends 905 heavily on the application scenario and may be difficult to decide 906 for SAM. 908 4.3.2. Revocation Messages 910 SAM MAY revoke tickets by sending a ticket revocation message to S. 911 If S receives a ticket revocation message, it MUST end the DTLS 912 connection to C and MUST NOT accept any further requests from C. 914 If ticket revocation messages are used, S MUST check regularly if SAM 915 is still available. If S cannot contact SAM, it MUST end all DTLS 916 connections and reject any further requests from C. 918 Note: The loss of the connection between S and SAM prevents all 919 access to S. This might especially be a severe problem if SAM is 920 responsible for several Servers or even a whole network. 922 5. Payload Format and Encoding (application/dcaf+cbor) 924 Various messages types of the DCAF protocol carry payloads to express 925 authorization information and parameters for generating the DTLS PSK 926 to be used by C and S. In this section, a representation in Concise 927 Binary Object Representation (CBOR, [RFC7049]) is defined. 929 DCAF data structures are defined as CBOR maps that contain key value 930 pairs. For efficient encoding, the keys defined in this document are 931 represented as unsigned integers in CBOR, i. e. major type 0. For 932 improved reading, we use symbolic identifiers to represent the 933 corresponding encoded values as defined in Table 1. 935 +---------------+-----+ 936 | Encoded Value | Key | 937 +---------------+-----+ 938 | 0b000_00000 | SAM | 939 | | | 940 | 0b000_00001 | SAI | 941 | | | 942 | 0b000_00010 | CAI | 943 | | | 944 | 0b000_00011 | E | 945 | | | 946 | 0b000_00100 | K | 947 | | | 948 | 0b000_00101 | TS | 949 | | | 950 | 0b000_00110 | L | 951 | | | 952 | 0b000_00111 | G | 953 | | | 954 | 0b000_01000 | F | 955 | | | 956 | 0b000_01001 | V | 957 +---------------+-----+ 959 Table 1: DCAF field identifiers encoded in CBOR 961 The following list describes the semantics of the keys defined in 962 DCAF. 964 SAM: Server Authorization Manager. This attribute denotes the 965 Server Authorization Manager that is in charge of the resource 966 specified in attribute R. The attribute's value is a string that 967 contains an absolute URI according to Section 4.3 of [RFC3986]. 969 SAI: SAM Authorization Information. A data structure used to convey 970 authorization information from SAM to S. It describes C's 971 permissions for S according to SAM, e.g., which actions C is 972 allowed to perform on an R of S. The SAI attribute contains an 973 AIF object as defined in [I-D.bormann-core-ace-aif]. C uses SAI 974 for its Access Request messages. 976 CAI: CAM Authorization Information. A data structure used to convey 977 authorization information from CAM to C. It describes the C's 978 permissions for S according to CAM, e.g., which actions C is 979 allowed to perform on an R of S. The CAI attribute contains an 980 AIF object as defined in [I-D.bormann-core-ace-aif]. 982 E: Encrypted Ticket Face. A binary string containing an encrypted 983 ticket Face. 985 K: Key. A string that identifies the shared key between S and SAM 986 that can be used to decrypt the contents of E. If the attribute E 987 is present and no attribute K has been specified, the default is 988 to use the current session key for the secured channel between S 989 and SAM. 991 TS: Time Stamp. An optional time stamp that indicates the instant 992 when the access ticket request was formed. This attribute can be 993 used by the Server in an SAM Information message to convey a time 994 stamp in its local time scale (e.g. when it does not have a real 995 time clock with synchronized global time). When the attribute's 996 value is encoded as a string, it MUST contain a valid UTC 997 timestamp without time zone information. When encoded as integer, 998 TS contains a system timestamp relative to the local time scale of 999 its generator, usually S. 1001 L: Lifetime. A lifetime of the ticket. When encoded as a string, L 1002 MUST denote the ticket's expiry time as a valid UTC timestamp 1003 without time zone information. When encoded as an integer, L MUST 1004 denote the ticket's validity period in seconds relative to TS. 1006 G: DTLS PSK Generation Method. A numeric identifier for the method 1007 that S MUST use to derive the DTLS PSK from the ticket Face. This 1008 attribute MUST NOT be used when attribute V is present within the 1009 contents of F. This specification uses symbolic identifiers for 1010 improved readability. The corresponding numeric values encoded in 1011 CBOR are defined in Table 2. A registry for these codes is 1012 defined in Section 13.1. 1014 F: Ticket Face. An object containing the fields SAI, TS, and 1015 optionally G, L and V. 1017 V: Ticket Verifier. A binary string containing the shared secret 1018 between C and S. 1020 +---------------+-------------+-----------+ 1021 | Encoded Value | Mnemonic | Support | 1022 +---------------+-------------+-----------+ 1023 | 0b000_00000 | hmac_sha256 | mandatory | 1024 | | | | 1025 | 0b000_00001 | hmac_sha384 | optional | 1026 | | | | 1027 | 0b000_00010 | hmac_sha512 | optional | 1028 +---------------+-------------+-----------+ 1030 Table 2: CBOR encoding for DTLS PSK Key Generation Methods 1032 5.1. Examples 1034 The following example specifies a SAM that will be accessed using 1035 HTTP over TLS. The request URI is set to 1036 "/a?ep=%5B2001:DB8::dcaf:1234%5D" (hence denoting the endpoint 1037 address to authorize). TS denotes a local timestamp in UTC. 1039 POST /a?ep=%5B2001:DB8::dcaf:1234%5D HTTP/1.1 1040 Host: sam.example.com 1041 Content-Type: application/dcaf+cbor 1042 {SAM: "https://sam.example.com/a?ep=%5B2001:DB8::dcaf:1234%5D", 1043 SAI: ["coaps://temp451.example.com/s/tempC", 1], 1044 TS: 0("2013-07-14T11:58:22.923")} 1046 The following example shows a ticket for the distributed key 1047 generation method (cf. Section 6.2), comprised of a Face (F) and a 1048 Verifier (V). The Face data structure contains authorization 1049 information SAI, a client descriptor, a timestamp using the local 1050 time scale of S, and a lifetime relative to S's time scale. 1052 The DTLS PSK Generation Method is set to hmac_sha256 denoting that 1053 the distributed key derivation is used as defined in Section 6.2 with 1054 SHA-256 as HMAC function. 1056 The Verifier V contains a shared secret to be used as DTLS PSK 1057 between C and S. 1059 HTTP/1.1 200 OK 1060 Content-Type: application/dcaf+cbor 1061 { 1062 F: { 1063 SAI: [ "/s/tempC", 1 ], 1064 TS: 2938749, 1065 L: 3600, 1066 G: hmac_sha256 1067 }, 1068 V: h'48ae5a81b87241d81618f56cab0b65ec 1069 441202f81faabbe10075b20cb57fa939' 1070 } 1072 The Face may be encrypted as illustrated in the following example. 1073 Here, the field E carries an encrypted Face data structure that 1074 contains the same information as the previous example, and an 1075 additional Verifier. Encryption was done with a secret shared by SAM 1076 and S. (This example uses AES128_CCM with the secret { 0x00, 0x01, 1077 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08, 0x09, 0x0a, 0x0b, 0x0c, 1078 0x0d, 0x0e, 0x0f } and S's timestamp { 0x00, 0x2C, 0xD7, 0x7D } as 1079 nonce.) Line breaks have been inserted to improve readability. 1081 The attribute K describes the identity of the key to be used by S to 1082 decrypt the contents of attribute E. Here, The value "key0" in this 1083 example is used to indicate that the shared session key between S and 1084 SAM was used for encrypting E. 1086 { 1087 E: h'2e75eeae01b831e0b65c2976e06d90f4 1088 82135bec5efef3be3d31520b2fa8c6fb 1089 f572f817203bf7a0940bb6183697567c 1090 e291b03e9fca5e9cbdfa7e560322d4ed 1091 3a659f44a542e55331a1a9f43d7f', 1092 K: "key0", 1093 V: h'48ae5a81b87241d81618f56cab0b65ec 1094 441202f81faabbe10075b20cb57fa939' 1095 } 1097 The decrypted contents of E are depicted below (whitespace has been 1098 added to improve readability). The presence of the attribute V 1099 indicates that the DTLS PSK Transfer is used to convey the session 1100 key (cf. Section 6.1). 1102 { 1103 F: { 1104 SAI: [ "/s/tempC", 1 ], 1105 TS: 2938749, 1106 L: 3600, 1107 G: hmac_sha256 1108 }, 1109 V: h'48ae5a81b87241d81618f56cab0b65ec 1110 441202f81faabbe10075b20cb57fa939' 1111 } 1113 6. DTLS PSK Generation Methods 1115 One goal of the DCAF protocol is to provide for a DTLS PSK shared 1116 between C and S. SAM and S MUST negotiate the method for the DTLS 1117 PSK generation. 1119 6.1. DTLS PSK Transfer 1121 The DTLS PSK is generated by AS and transmitted to C and S using a 1122 secure channel. 1124 The DTLS PSK transfer method is defined as follows: 1126 o SAM generates the DTLS PSK using an algorithm of its choice 1128 o SAM MUST include a representation of the DTLS PSK in Face and 1129 encrypt it together with all other information in Face with a key 1130 K(SAM,S) it shares with S. How SAM and S exchange K(SAM,S) is not 1131 in the scope of this document. SAM and S MAY use their preshared 1132 key as K(SAM,S). 1134 o SAM MUST include a representation of the DTLS PSK in the Verifier. 1136 o As SAM and C do not have a shared secret, the Verifier MUST be 1137 transmitted to C using encrypted channels. 1139 o S MUST decrypt Face using K(SAM,S) 1141 6.2. Distributed Key Derivation 1143 SAM generates a DTLS PSK for C which is transmitted using a secure 1144 channel. S generates its own version of the DTLS PSK using the 1145 information contained in Face (see also Section 4.1). 1147 The distributed key derivation method is defined as follows: 1149 o SAM and S both generate the DTLS PSK using the information 1150 included in Face. They use an HMAC algorithm on Face with a 1151 shared key K(SAM,S). The result serves as the DTLS PSK. How SAM 1152 and S exchange K(SAM,S) is not in the scope of this document. 1153 They MAY use their preshared key as K(SAM,S). How SAM and S 1154 negotiate the used HMAC algorithm is also not in the scope of this 1155 document. They MAY however use the HMAC algorithm they use for 1156 their DTLS connection. 1158 o SAM MUST include a representation of the DTLS PSK in the Verifier. 1160 o As SAM and C do not have a shared secret, the Verifier MUST be 1161 transmitted to C using encrypted channels. 1163 o SAM MUST NOT include a representation of the DTLS PSK in Face. 1165 o SAM MUST NOT encrypt Face. 1167 7. Authorization Configuration 1169 For the protocol defined in this document, proper configuration of 1170 CAM and SAM is crucial. The principals that are in charge of the 1171 resource, S and SAM, and the principals that are in charge of C and 1172 CAM need to define the respective permissions. The data 1173 representation of these permissions are not in the scope of this 1174 document. 1176 8. Trust Relationships 1178 C has a trust relationship with CAM: C trusts CAM to act in behalf of 1179 C's principal. S has a trust relationship with SAM: S trusts SAM to 1180 act in behalf of S's principal. 1182 Obviously, CAM trusts C with the specific permissions it hands over 1183 to it. How this trust is established, is not in the scope of this 1184 document. It may be achieved by using a bootstrapping mechanism 1185 similar to [bergmann12]. 1187 Additionally, SAM and CAM need to have a trust relationship 1188 established. Its establishment is also not in the scope of this 1189 document. It fulfills the following conditions: 1191 1. SAM has means to authenticate CAM (e.g. it has a certificate of 1192 CAM or a PKI in which CAM is included) and vice versa 1194 2. As far as SAM needs to rely on the different clients of CAM to 1195 receive different permissions, it can be sure that CAM correctly 1196 identifies these clients towards SAM and does not leak tickets 1197 that have been generated for a specific client C to another 1198 client. 1200 SAM trusts C indirectly because it trusts CAM and CAM vouches for C. 1201 The DCAF Protocol does not provide any means for SAM to validate that 1202 a resource request stems from C. 1204 C indirectly trusts SAM with some potentially confidential 1205 information, and that SAM correctly represents S, because CAM trusts 1206 SAM. 1208 CAM trusts S indirectly because it trusts SAM and SAM vouches for S. 1210 C implicitly trusts S with some potentially confidential information 1211 because it trusts CAM and because S can prove that it shares a key 1212 with SAM. 1214 CAM <------------------> SAM 1216 /|\ /|\ 1217 | | 1218 \|/ \|/ 1220 C ..................... S 1222 9. Listing Authorization Manager Information in a Resource Directory 1224 CoAP utilizes the Web Linking format [RFC5988] to facilitate 1225 discovery of services in an M2M environment. [RFC6690] defines 1226 specific link parameters that can be used to describe resources to be 1227 listed in a resource directory [I-D.ietf-core-resource-directory]. 1229 9.1. The "auth-request" Link Relation 1231 This section defines a resource type "auth-request" that can be used 1232 by clients to retrieve the request URI for a server's authorization 1233 service. When used with the parameter rt in a web link, "auth- 1234 request" indicates that the corresponding target URI can be used in a 1235 POST message to request authorization for the resource and action 1236 that are described in the request payload. 1238 The Content-Format "application/dcaf+cbor with numeric identifier 1239 TBD1 defined in this specification MAY be used to express access 1240 requests and their responses. 1242 The following example shows the web link used by CAM in this document 1243 to relay incoming Authorization Request messages to SAM. (Whitespace 1244 is included only for readability.) 1246 ;rt="auth-request";ct=TBD1 1247 ;title="Contact Remote Authorization Manager" 1249 The resource directory that hosts the resource descriptions of S 1250 could list the following description. In this example, the URI 1251 "ep/node138/a/switch2941" is relative to the resource context 1252 "coaps://sam.example.com/", i.e. the Server Authorization Manager 1253 SAM. 1255 ;rt="auth-request";ct=TBD1;ep="node138" 1256 ;title="Request Client Authorization" 1257 ;anchor="coaps://sam.example.com/" 1259 10. Examples 1261 This section gives a number of short examples with message flows for 1262 the initial Unauthorized Resource Request and the subsequent 1263 retrieval of a ticket from SAM. The notation here follows the actors 1264 conventions defined in Section 1.2.1. The payload format is encoded 1265 as proposed in Section 5. The IP address of SAM is 2001:DB8::1, the 1266 IP address of S is 2001:DB8::dcaf:1234, and C's IP address is 1267 2001:DB8::c. 1269 10.1. Access Granted 1271 This example shows an Unauthorized PUT request from C to S that is 1272 answered with a SAM Information message. C then sends a POST request 1273 to CAM with a description of its intended request. CAM forwards this 1274 request to SAM using CoAP over a DTLS-secured channel. The response 1275 from SAM contains an access ticket that is relayed back to CAM. 1277 C --> S 1278 PUT a/switch2941 [Mid=1234] 1279 Content-Format: application/senml+json 1280 {"e": [{"bv": "1"}]} 1282 C <-- S 1283 4.01 Unauthorized [Mid=1234] 1284 Content-Format: application/dcaf+cbor 1285 {SAM: "coaps://[2001:DB8::1]/ep/node138/a/switch2941"} 1287 C --> CAM 1288 POST client-authorize [Mid=1235,Token="tok"] 1289 Content-Format: application/dcaf+cbor 1290 { 1291 SAM: "coaps://[2001:DB8::1]/ep/node138/a/switch2941", 1292 SAI: ["coaps://[2001:DB8::dcaf:1234]/a/switch2941", 4] 1293 } 1295 CAM --> SAM [Mid=23146] 1296 POST ep/node138/a/switch2941 1297 Content-Format: application/dcaf+cbor 1298 { 1299 SAM: "coaps://[2001:DB8::1]/ep/node138/a/switch2941", 1300 SAI: ["coaps://[2001:DB8::dcaf:1234]/a/switch2941", 4] 1301 } 1303 CAM <-- SAM 1304 2.05 Content [Mid=23146] 1305 Content-Format: application/dcaf+cbor 1306 { F: { 1307 SAI: ["a/switch2941", 5], 1308 TS: 0("2013-07-04T20:17:38.002"), 1309 G: hmac_sha256 1310 }, 1311 V: h'7ba4d9e287c8b69dd52fd3498fb8d26d 1312 9503611917b014ee6ec2a570d857987a' 1313 } 1315 C <-- CAM 1316 2.05 Content [Mid=1235,Token="tok"] 1317 Content-Format: application/dcaf+cbor 1318 { F: { 1319 SAI: ["a/switch2941", 5], 1320 TS: 0("2013-07-04T20:17:38.002"), 1321 G: hmac_sha256 1322 }, 1323 V: h'7ba4d9e287c8b69dd52fd3498fb8d26d 1324 9503611917b014ee6ec2a570d857987a' 1325 } 1327 C --> S 1328 ClientHello (TLS_PSK_WITH_AES_128_CCM_8) 1330 C <-- S 1331 ServerHello (TLS_PSK_WITH_AES_128_CCM_8) 1332 ServerHelloDone 1334 C --> S 1335 ClientKeyExchange 1336 psk_identity=0xa301826c612f73776974636832393431 1337 0x0505c077323031332d30372d30345432 1338 0x303a31373a33382e3030320700 1340 (C decodes the contents of V and uses the result as PSK) 1341 ChangeCipherSpec 1342 Finished 1344 (S calculates PSK from SAI, TS and its session key 1345 HMAC_sha256(0xa301826c612f73776974636832393431 1346 0x0505c077323031332d30372d30345432 1347 0x303a31373a33382e3030320700, 1348 0x736563726574) 1349 = 0x7ba4d9e287c8... 1350 ) 1352 C <-- S 1353 ChangeCipherSpec 1354 Finished 1356 10.2. Access Denied 1358 This example shows a denied Authorization request for the DELETE 1359 operation. 1361 C --> S 1362 DELETE a/switch2941 1364 C <-- S 1365 4.01 Unauthorized 1366 Content-Format: application/dcaf+cbor 1367 {SAM: "coaps://[2001:DB8::1]/ep/node138/a/switch2941"} 1369 C --> CAM 1370 POST client-authorize 1371 Content-Format: application/dcaf+cbor 1372 { 1373 SAM: "coaps://[2001:DB8::1]/ep/node138/a/switch2941", 1374 SAI: ["coaps://[2001:DB8::dcaf:1234]/a/switch2941", 8] 1375 } 1377 CAM --> SAM 1378 POST ep/node138/a/switch2941 1379 Content-Format: application/dcaf+cbor 1380 { 1381 SAM: "coaps://[2001:DB8::1]/ep/node138/a/switch2941", 1382 SAI: ["coaps://[2001:DB8::dcaf:1234]/a/switch2941", 8] 1383 } 1385 CAM <-- SAM 1386 2.05 Content 1387 Content-Format: application/dcaf+cbor 1389 C <-- CAM 1390 2.05 Content 1391 Content-Format: application/dcaf+cbor 1393 10.3. Access Restricted 1395 This example shows a denied Authorization request for the operations 1396 GET, PUT, and DELETE. SAM grants access for PUT only. 1398 CAM --> SAM 1399 POST ep/node138/a/switch2941 1400 Content-Format: application/dcaf+cbor 1401 { 1402 SAM: "coaps://[2001:DB8::1]/ep/node138/a/switch2941", 1403 SAI: ["coaps://[2001:DB8::dcaf:1234]/a/switch2941", 13] 1404 } 1406 CAM <-- SAM 1407 2.05 Content 1408 Content-Format: application/dcaf+cbor 1409 { F: { 1410 SAI: ["a/switch2941", 5], 1411 TS: 0("2013-07-04T21:33:11.930"), 1412 G: hmac_sha256 1413 }, 1414 V: h'c7b5774f2ddcbd548f4ad74b30a1b2e5 1415 b6b04e66a9995edd2545e5a06216c53d' 1416 } 1418 10.4. Implicit Authorization 1420 This example shows an Authorization request using implicit 1421 authorization. CAM initially requests the actions GET and POST on 1422 the resource "coaps://[2001:DB8::dcaf:1234]/a/switch2941". SAM 1423 returns a ticket that has no SAI field in its ticket Face, hence 1424 implicitly authorizing C. 1426 CAM --> SAM 1427 POST ep/node138/a/switch2941 1428 Content-Format: application/dcaf+cbor 1429 { 1430 SAM: "coaps://[2001:DB8::1]/ep/node138/a/switch2941", 1431 SAI: ["coaps://[2001:DB8::dcaf:1234]/a/switch2941", 3] 1432 } 1434 CAM <-- SAM 1435 2.05 Content 1436 Content-Format: application/dcaf+cbor 1437 { F: { 1438 TS: 0("2013-07-16T10:15:43.663"), 1439 G: hmac_sha256 1440 }, 1441 V: h'4f7b0e7fdcc498fb2ece648bf6bdf736 1442 61a6067e51278a0078e5b8217147ea06' 1443 } 1445 11. Specific Usage Scenarios 1447 The general DCAF architure outlined in Section 3.1 illustrates the 1448 various actors who participate in the message exchange for 1449 authenticated authorization. The message types defined in this 1450 document cover the most general case where all four actors are 1451 separate entities that may or may not reside on the same device. 1453 Special implementation considerations apply when one single entity 1454 takes the role of more than one actor. This section gives advice on 1455 the most common usage scenarios where the Client Authorization 1456 Manager and Client, the Server Authorization Manager and Server or 1457 both Authorization Managers reside on the same (less-constrained) 1458 device and have a means of secure communication outside the scope of 1459 this document. 1461 11.1. Combined Authorization Manager and Client 1463 When CAM and C reside on the same (less-constrained) device, the 1464 Access Request and Ticket Transfer messages can be substituted by 1465 other means of secure communication. Figure 9 shows a simplified 1466 message exchange for a combined CAM+C device. 1468 CAM+C S SAM 1469 | | <== DTLS chan. ==> | 1470 | [Resource Req.-->] | | 1471 | | | 1472 | [<-- SAM Info.] | | 1473 | | | 1474 | <==== TLS/DTLS chan. (Mutual Auth) ===> | 1475 | | | 1476 | Ticket Request ---------------------> | 1477 | | | 1478 | <--------------------- Ticket Grant | 1479 | | | 1480 | <== DTLS chan. ==> | | 1481 | Auth. Res. Req. -> | | 1483 Figure 9: Combined Client Authorization Manager and Client 1485 11.1.1. Creating the Ticket Request Message 1487 When CAM+C receives an SAM Information message as a reaction to an 1488 Unauthorized Request message, it creates a Ticket Request message as 1489 follows: 1491 1. The destination of the Ticket Request message is derived from the 1492 authority information in the URI contained in field "SAM" of the 1493 SAM Information message payload. 1495 2. The request method is POST. 1497 3. The request URI is constructed from the SAM field received in the 1498 SAM Information message payload. 1500 4. The payload contains the SAM field from the SAM Information 1501 message, an absolute URI of the resource that CAM+C wants to 1502 access, the actions that CAM+C wants to perform on the resource, 1503 and any time stamp generated by S that was transferred with the 1504 SAM Information message. 1506 5. A label that describes CAM+C is added to the payload. 1508 11.1.2. Processing the Ticket Grant Message 1510 Based on the Ticket Grant message, CAM+C is able to establish a DTLS 1511 channel with S. To do so, CAM+C sets the psk_identity field of the 1512 DTLS ClientKeyExchange message to the ticket Face received in the 1513 Ticket Grant message and uses the ticket Verifier as PSK when 1514 constructing the premaster secret. 1516 11.2. Combined Client Authorization Manager and Server Authorization 1517 Manager 1519 In certain scenarios, CAM and SAM may be combined to a single entity 1520 that knows both, C and S, and decides if their actions are 1521 authorized. Therefore, no explicit communication between CAM and SAM 1522 is necessary, resulting in omission of the Ticket Request and Ticket 1523 Grant messages. Figure 10 depicts the resulting message sequence in 1524 this simplified architecture. 1526 C CAM+SAM S 1527 | <== DTLS chan. ==> | <== DTLS chan. ==> | 1528 | | | 1529 | [Resource Req.----------------------->] | 1530 | | | 1531 | [<-------------------- SAM Information] | 1532 | | | 1533 | Access Request --> | | 1534 | | | 1535 | <-- Ticket Transf. | | 1536 | | | 1537 | <=========== DTLS channel ===========> | 1538 | | | 1539 | Authorized Resource Request ----------> | 1541 Figure 10: Combined Client Authorization Manager and Server 1542 Authorization Manager 1544 11.2.1. Processing the Access Request Message 1546 When receiving an Access Request message, CAM+SAM performs the checks 1547 specified in Section 3.5 and returns a 4.00 (Bad Request) response in 1548 case of failure. Otherwise, if the checks have succeeded, CAM+SAM 1549 evaluates the contents of Access Request message as described in 1550 Section 3.6. 1552 The decision on the access request is performed by CAM+SAM with 1553 respect to the stored policies. When the requested action is 1554 permitted on the respective resource, CAM+SAM generates an access 1555 ticket as outlined in Section 4.1 and creates a Ticket Transfer 1556 message to convey the access ticket to the Client. 1558 11.2.2. Creating the Ticket Transfer Message 1560 A Ticket Transfer message is constructed as a 2.05 response with the 1561 access ticket contained in its payload. The response MAY contain a 1562 Max-Age option to indicate the ticket's lifetime to the receiving 1563 Client. 1565 This specification defines a CBOR data representation for the access 1566 ticket as illustrated in Section 3.6. 1568 11.3. Combined Server Authorization Manager and Server 1570 If SAM and S are colocated in one entity (SAM+S), the main objective 1571 is to allow CAM to delegate access to C. Accordingly, the 1572 authorization information could be replaced by a nonce internal to 1573 SAM+S. (TBD.) 1574 CAM C SAM+S 1575 | <== DTLS chan. ==> | | 1576 | | [Resource Req.-->] | 1577 | | | 1578 | | [<-- SAM Info.] | 1579 | | | 1580 | <-- Access Req. | | 1581 | | | 1582 | <========= TLS/DTLS channel =========> | 1583 | | | 1584 | Ticket Request ---------------------> | 1585 | | | 1586 | <--------------------- Ticket Grant | 1587 | | | 1588 | Ticket Transf. --> | | 1589 | | | 1590 | | <== DTLS chan. ==> | 1591 | | Auth. Res. Req. -> | 1593 Figure 11: Combined Server Authorization Manager and Server 1595 12. Security Considerations 1597 As this protocol builds on transitive trust between Authorization 1598 Managers as mentioned in Section 8, SAM has no direct means to 1599 validate that a resource request originates from C. It has to trust 1600 CAM that it correctly vouches for C and that it does not give 1601 authorization tickets meant for C to another client nor disclose the 1602 contained session key. 1604 The Authorization Managers also could constitute a single point of 1605 failure. If the Server Authorization Manager fails, the resources on 1606 all Servers it is responsible for cannot be accessed any more. If a 1607 Client Authorization Manager fails, all clients it is responsible are 1608 not able to access resources on a Server. Thus, it is crucial for 1609 large networks to use Authorization Managers in a redundant setup. 1611 13. IANA Considerations 1613 The following registrations are done following the procedure 1614 specified in [RFC6838]. 1616 Note to RFC Editor: Please replace all occurrences of "[RFC-XXXX]" 1617 with the RFC number of this specification. 1619 13.1. DTLS PSK Key Generation Methods 1621 A sub-registry for the values indicating the PSK key generation 1622 method as contents of the field G in a payload of type application/ 1623 dcaf+cbor is defined. Values in this sub-registry are numeric 1624 integers encoded in Concise Binary Object Notation (CBOR, [RFC7049]). 1625 This document follows the notation of [RFC7049] for binary values, 1626 i.e. a number starts with the prefix "0b". The major type is 1627 separated from the actual numeric value by an underscore to emphasize 1628 the value's internal structure. 1630 Initial entries in this sub-registry are as follows: 1632 +---------------+-------------+------------+ 1633 | Encoded Value | Name | Reference | 1634 +---------------+-------------+------------+ 1635 | 0b000_00000 | hmac_sha256 | [RFC-XXXX] | 1636 | | | | 1637 | 0b000_00001 | hmac_sha384 | [RFC-XXXX] | 1638 | | | | 1639 | 0b000_00010 | hmac_sha512 | [RFC-XXXX] | 1640 +---------------+-------------+------------+ 1642 Table 3: DTLS PSK Key Generation Methods 1644 New methods can be added to this registry based on designated expert 1645 review according to [RFC5226]. 1647 (TBD: criteria for expert review.) 1649 13.2. dcaf+cbor Media Type Registration 1651 Type name: application 1653 Subtype name: dcaf+cbor 1655 Required parameters: none 1657 Optional parameters: none 1659 Encoding considerations: Must be encoded as using a subset of the 1660 encoding allowed in [RFC7049]. Specifically, only the primitive data 1661 types String and Number are allowed. The type Number is restricted 1662 to unsigned integers (i.e., no negative numbers, fractions or 1663 exponents are allowed). Encoding MUST be UTF-8. These restrictions 1664 simplify implementations on devices that have very limited memory 1665 capacity. 1667 Security considerations: TBD 1669 Interoperability considerations: TBD 1671 Published specification: [RFC-XXXX] 1673 Applications that use this media type: TBD 1675 Additional information: 1677 Magic number(s): none 1679 File extension(s): dcaf 1681 Macintosh file type code(s): none 1683 Person & email address to contact for further information: TBD 1685 Intended usage: COMMON 1687 Restrictions on usage: None 1689 Author: TBD 1691 Change controller: IESG 1693 13.3. CoAP Content Format Registration 1695 This document specifies a new media type application/dcaf+cbor (cf. 1696 Section 13.2). For use with CoAP, a numeric Content-Format 1697 identifier is to be registered in the "CoAP Content-Formats" sub- 1698 registry within the "CoRE Parameters" registry. 1700 Note to RFC Editor: Please replace all occurrences of "RFC-XXXX" with 1701 the RFC number of this specification. 1703 +-----------------------+----------+------+------------+ 1704 | Media type | Encoding | Id. | Reference | 1705 +-----------------------+----------+------+------------+ 1706 | application/dcaf+cbor | - | TBD1 | [RFC-XXXX] | 1707 +-----------------------+----------+------+------------+ 1709 14. References 1710 14.1. Normative References 1712 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1713 Requirement Levels", BCP 14, RFC 2119, March 1997. 1715 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 1716 Resource Identifier (URI): Generic Syntax", STD 66, RFC 1717 3986, January 2005. 1719 [RFC4279] Eronen, P. and H. Tschofenig, "Pre-Shared Key Ciphersuites 1720 for Transport Layer Security (TLS)", RFC 4279, December 1721 2005. 1723 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 1724 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 1725 May 2008. 1727 [RFC5746] Rescorla, E., Ray, M., Dispensa, S., and N. Oskov, 1728 "Transport Layer Security (TLS) Renegotiation Indication 1729 Extension", RFC 5746, February 2010. 1731 [RFC6347] Rescorla, E. and N. Modadugu, "Datagram Transport Layer 1732 Security Version 1.2", RFC 6347, January 2012. 1734 [RFC6838] Freed, N., Klensin, J., and T. Hansen, "Media Type 1735 Specifications and Registration Procedures", BCP 13, RFC 1736 6838, January 2013. 1738 [RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object 1739 Representation (CBOR)", RFC 7049, October 2013. 1741 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 1742 Application Protocol (CoAP)", RFC 7252, June 2014. 1744 14.2. Informative References 1746 [I-D.bormann-core-ace-aif] 1747 Bormann, C., "An Authorization Information Format (AIF) 1748 for ACE", draft-bormann-core-ace-aif-01 (work in 1749 progress), July 2014. 1751 [I-D.gerdes-ace-actors] 1752 Gerdes, S., "Actors in the ACE Architecture", draft- 1753 gerdes-ace-actors-02 (work in progress), October 2014. 1755 [I-D.ietf-core-block] 1756 Bormann, C. and Z. Shelby, "Blockwise transfers in CoAP", 1757 draft-ietf-core-block-16 (work in progress), October 2014. 1759 [I-D.ietf-core-observe] 1760 Hartke, K., "Observing Resources in CoAP", draft-ietf- 1761 core-observe-16 (work in progress), December 2014. 1763 [I-D.ietf-core-resource-directory] 1764 Shelby, Z. and C. Bormann, "CoRE Resource Directory", 1765 draft-ietf-core-resource-directory-02 (work in progress), 1766 November 2014. 1768 [I-D.schmertmann-dice-codtls] 1769 Schmertmann, L., Hartke, K., and C. Bormann, "CoDTLS: DTLS 1770 handshakes over CoAP", draft-schmertmann-dice-codtls-01 1771 (work in progress), August 2014. 1773 [RFC5988] Nottingham, M., "Web Linking", RFC 5988, October 2010. 1775 [RFC6655] McGrew, D. and D. Bailey, "AES-CCM Cipher Suites for 1776 Transport Layer Security (TLS)", RFC 6655, July 2012. 1778 [RFC6690] Shelby, Z., "Constrained RESTful Environments (CoRE) Link 1779 Format", RFC 6690, August 2012. 1781 [bergmann12] 1782 Bergmann, O., Gerdes, S., Schaefer, S., Junge, F., and C. 1783 Bormann, "Secure Bootstrapping of Nodes in a CoAP 1784 Network", IEEE Wireless Communications and Networking 1785 Conference Workshops (WCNCW), April 2012. 1787 Authors' Addresses 1789 Stefanie Gerdes 1790 Universitaet Bremen TZI 1791 Postfach 330440 1792 Bremen D-28359 1793 Germany 1795 Phone: +49-421-218-63906 1796 Email: gerdes@tzi.org 1798 Olaf Bergmann 1799 Universitaet Bremen TZI 1800 Postfach 330440 1801 Bremen D-28359 1802 Germany 1804 Phone: +49-421-218-63904 1805 Email: bergmann@tzi.org 1806 Carsten Bormann 1807 Universitaet Bremen TZI 1808 Postfach 330440 1809 Bremen D-28359 1810 Germany 1812 Phone: +49-421-218-63921 1813 Email: cabo@tzi.org