idnits 2.17.1 draft-gerdes-ace-dcaf-authorize-04.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (October 19, 2015) is 3113 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 1840, 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-03 == Outdated reference: A later version (-11) exists of draft-greevenbosch-appsawg-cbor-cddl-07 == Outdated reference: A later version (-07) exists of draft-ietf-ace-actors-02 == Outdated reference: A later version (-21) exists of draft-ietf-core-block-18 == Outdated reference: A later version (-28) exists of draft-ietf-core-resource-directory-05 == Outdated reference: A later version (-24) exists of draft-ietf-cose-msg-06 -- Obsolete informational reference (is this intentional?): RFC 5988 (Obsoleted by RFC 8288) Summary: 3 errors (**), 0 flaws (~~), 8 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: April 21, 2016 Universitaet Bremen TZI 6 October 19, 2015 8 Delegated CoAP Authentication and Authorization Framework (DCAF) 9 draft-gerdes-ace-dcaf-authorize-04 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 April 21, 2016. 41 Copyright Notice 43 Copyright (c) 2015 IETF Trust and the persons identified as the 44 document authors. All rights reserved. 46 This document is subject to BCP 78 and the IETF Trust's Legal 47 Provisions Relating to IETF Documents 48 (http://trustee.ietf.org/license-info) in effect on the date of 49 publication of this document. Please review these documents 50 carefully, as they describe your rights and restrictions with respect 51 to this document. Code Components extracted from this document must 52 include Simplified BSD License text as described in Section 4.e of 53 the Trust Legal Provisions and are provided without warranty as 54 described in the Simplified BSD License. 56 Table of Contents 58 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 59 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 . . . . . . . . . . . . . . . . . . . . . . . . . . 7 65 3.1. Overview . . . . . . . . . . . . . . . . . . . . . . . . 7 66 3.2. Unauthorized Resource Request Message . . . . . . . . . . 8 67 3.3. SAM Information Message . . . . . . . . . . . . . . . . . 9 68 3.3.1. Piggybacked Protected Content . . . . . . . . . . . . 10 69 3.4. Access Request . . . . . . . . . . . . . . . . . . . . . 11 70 3.5. Ticket Request Message . . . . . . . . . . . . . . . . . 12 71 3.6. Ticket Grant Message . . . . . . . . . . . . . . . . . . 13 72 3.7. Ticket Transfer Message . . . . . . . . . . . . . . . . . 15 73 3.8. DTLS Channel Setup Between C and S . . . . . . . . . . . 16 74 3.9. Authorized Resource Request Message . . . . . . . . . . . 17 75 3.10. Dynamic Update of Authorization Information . . . . . . . 18 76 3.10.1. Handling of Ticket Transfer Messages . . . . . . . . 19 77 4. Ticket . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 78 4.1. Face . . . . . . . . . . . . . . . . . . . . . . . . . . 20 79 4.2. Client Information . . . . . . . . . . . . . . . . . . . 21 80 4.3. Revocation . . . . . . . . . . . . . . . . . . . . . . . 22 81 4.4. Lifetime . . . . . . . . . . . . . . . . . . . . . . . . 22 82 4.4.1. Revocation Messages . . . . . . . . . . . . . . . . . 22 83 5. Payload Format and Encoding (application/dcaf+cbor) . . . . . 23 84 5.1. Examples . . . . . . . . . . . . . . . . . . . . . . . . 26 85 6. DTLS PSK Generation Methods . . . . . . . . . . . . . . . . . 28 86 6.1. DTLS PSK Transfer . . . . . . . . . . . . . . . . . . . . 28 87 6.2. Distributed Key Derivation . . . . . . . . . . . . . . . 28 88 7. Authorization Configuration . . . . . . . . . . . . . . . . . 29 89 8. Trust Relationships . . . . . . . . . . . . . . . . . . . . . 29 90 9. Listing Authorization Manager Information in a Resource 91 Directory . . . . . . . . . . . . . . . . . . . . . . . . . . 30 92 9.1. The "auth-request" Link Relation . . . . . . . . . . . . 31 93 10. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 31 94 10.1. Access Granted . . . . . . . . . . . . . . . . . . . . . 31 95 10.2. Access Denied . . . . . . . . . . . . . . . . . . . . . 33 96 10.3. Access Restricted . . . . . . . . . . . . . . . . . . . 34 97 10.4. Implicit Authorization . . . . . . . . . . . . . . . . . 35 98 11. Specific Usage Scenarios . . . . . . . . . . . . . . . . . . 36 99 11.1. Combined Authorization Manager and Client . . . . . . . 36 100 11.1.1. Creating the Ticket Request Message . . . . . . . . 36 101 11.1.2. Processing the Ticket Grant Message . . . . . . . . 37 102 11.2. Combined Client Authorization Manager and Server 103 Authorization Manager . . . . . . . . . . . . . . . . . 37 104 11.2.1. Processing the Access Request Message . . . . . . . 38 105 11.2.2. Creating the Ticket Transfer Message . . . . . . . . 38 106 11.3. Combined Server Authorization Manager and Server . . . . 38 107 12. Security Considerations . . . . . . . . . . . . . . . . . . . 39 108 13. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 39 109 13.1. DTLS PSK Key Generation Methods . . . . . . . . . . . . 40 110 13.2. dcaf+cbor Media Type Registration . . . . . . . . . . . 40 111 13.3. CoAP Content Format Registration . . . . . . . . . . . . 41 112 14. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 41 113 15. References . . . . . . . . . . . . . . . . . . . . . . . . . 42 114 15.1. Normative References . . . . . . . . . . . . . . . . . . 42 115 15.2. Informative References . . . . . . . . . . . . . . . . . 43 116 Appendix A. CDDL Specification . . . . . . . . . . . . . . . . . 44 117 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 45 119 1. Introduction 121 The Constrained Application Protocol (CoAP) [RFC7252] is a transfer 122 protocol similar to HTTP which is designed for the special 123 requirements of constrained environments. A serious problem with 124 constrained devices is the realization of secure communication. The 125 devices only have limited system resources such as memory, stable 126 storage (such as disk space) and transmission capacity and often lack 127 input/output devices such as keyboards or displays. Therefore, they 128 are not readily capable of using common protocols. Especially 129 authentication mechanisms are difficult to realize, because the lack 130 of stable storage severely limits the number of keys the system can 131 store. Moreover, CoAP has no mechanism for authorization. 133 [I-D.ietf-ace-actors] describes an architecture that is designed to 134 help constrained nodes with authorization-related tasks by 135 introducing less-constrained nodes. These Authorization Managers 136 perform complex security tasks for their nodes such as managing keys 137 for numerous devices, and enable the constrained nodes to enforce the 138 authorization policies of their principals. 140 DCAF uses access tokens to implement this architecture. A device 141 that wants to access an item of interest on a constrained node first 142 has to gain permission in the form of a token from the node's 143 Authorization Manager. 145 As fine-grained authorization is not always needed on constrained 146 devices, DCAF supports an implicit authorization mode where no 147 authorization information is exchanged. 149 The main goals of DCAF are the setup of a Datagram Transport Layer 150 Security (DTLS) [RFC6347] channel with symmetric pre-shared keys 151 (PSK) [RFC4279] between two nodes and to securely transmit 152 authorization tickets. 154 1.1. Features 156 o Utilize DTLS communication with pre-shared keys. 158 o Authenticated exchange of authorization information. 160 o Simplified authentication on constrained nodes by handing the more 161 sophisticated authentication over to less-constrained devices. 163 o Support of secure constrained device to constrained device 164 communication. 166 o Authorization policies of the principals of both participating 167 parties are ensured. 169 o Simplified authorization mechanism for cases where implicit 170 authorization is sufficient. 172 o Using only symmetric encryption on constrained nodes. 174 1.2. Terminology 176 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 177 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 178 document are to be interpreted as described in RFC 2119 [RFC2119]. 180 Readers are expected to be familiar with the terms and concepts 181 defined in [I-D.ietf-ace-actors]. 183 1.2.1. Actors 185 Server (S): An endpoint that hosts and represents a CoAP resource. 187 Client (C): An endpoint that attempts to access a CoAP resource on 188 the Server. 190 Server Authorization Manager (SAM): An entity that prepares and 191 endorses authentication and authorization data for a Server. 193 Client Authorization Manager (CAM): An entity that prepares and 194 endorses authentication and authorization data for a Client. 196 Authorization Manager (AM): An entity that is either a SAM or a CAM. 198 Client Overseeing Principal (COP): The principal that is in charge 199 of the Client and controls permissions concerning authorized 200 representations of a CoAP resource. 202 Resource Overseeing Principal (ROP): The principal that is in charge 203 of the CoAP resource and controls its access permissions. 205 1.2.2. Other Terms 207 Resource (R): A CoAP resource. 209 Authorization information: Contains all information needed by S to 210 decide if C is privileged to access a resource in a specific way. 212 Authentication information: Contains all information needed by S to 213 decide if the entity in possession of a certain key is verified by 214 SAM. 216 Access information: Contains authentication information and, if 217 necessary, authorization information. 219 Access ticket: Contains the authentication and, if necessary, the 220 authorization information needed to access a resource. A Ticket 221 consists of the Ticket Face and the Client Information. The 222 access ticket is a representation of the access information. 224 Ticket Face: The part of the ticket which is generated for the 225 Server. It contains the authorization information and all 226 information needed by the Server to verify that it was granted by 227 SAM. 229 Client Information (CI): The part of the ticket which is generated 230 for the Client. It contains the Verifier and optionally may 231 contain authorization information that represent COP's 232 authorization policies for C. 234 Client Authorization Information (CAI): A data structure that 235 describes the C's permissions for S according to CAM, e.g., which 236 actions C is allowed to perform on an R of S. 238 Server Authorization Information (SAI): A data structure that 239 describes C's permissions for S according to SAM, e.g., which 240 actions C is allowed to perform on an R of S. 242 Verifier: The secret (e.g. a 128-bit PSK) shared between C and S. 243 It enables C to validate that it is communicating with a certain S 244 and vice versa. 246 Explicit authorization: SAM informs the S in detail which privileges 247 are granted to the Client. 249 Implicit authorization: SAM authenticates the Client for the Server 250 without specifying the privileges in detail. This can be used for 251 flat or unrestricted authorization (cf section 4 of 252 [I-D.ietf-ace-actors]). 254 2. System Overview 256 Within the DCAF Architecture each Server (S) has a Server 257 Authorization Manger (SAM) which conducts the authentication and 258 authorization for S. S and SAM share a symmetric key which has to be 259 exchanged initially to provide for a secure channel. The mechanism 260 used for this is not in the scope of this document. 262 To gain access to a specific resource on a S, a Client (C) has to 263 request an access ticket from the SAM serving S either directly or, 264 if it is a constrained device, using its Client Authorization Manager 265 (CAM). In the following, we always discuss the CAM role separately, 266 even if that is co-located within a (more powerful) C (see section 267 Section 11 for details about co-located actors). 269 CAM decides if S is an authorized source for R according to the 270 policies set by COP and in this case transmits the request to SAM. 271 If SAM decides that C is allowed to access the resource according to 272 the policies set by ROP, it generates a DTLS pre-shared key (PSK) for 273 the communication between C and S and wraps it into an access ticket. 274 For explicit access control, SAM adds the detailed access permissions 275 to the ticket in a way that CAM and S can interpret. CAM checks if 276 the permissions in the access ticket comply with COP's authorization 277 policies for C, and if this is the case sends it to C. After C 278 presented the ticket to S, C and S can communicate securely. 280 To be able to provide for the authentication and authorization 281 services, an Authorization Manager has to fulfill several 282 requirements: 284 o AM must have enough stable storage (such as disk space) to store 285 the necessary number of credentials (matching the number of 286 Clients and Servers). 288 o AM must possess means for user interaction, for example directly 289 or indirectly connected input/output devices such as keyboard and 290 display, to allow for configuration of authorization information 291 by the respective Principal. 293 o AM must have enough processing power to handle the authorization 294 requests for all constrained devices it is responsible for. 296 3. Protocol 298 The DCAF protocol comprises three parts: 300 1. transfer of authentication and, if necessary, authorization 301 information between C and S; 303 2. transfer of access requests and the respective ticket transfer 304 between C and CAM; and 306 3. transfer of ticket requests and the respective ticket grants 307 between SAM and CAM. 309 3.1. Overview 311 In Figure 1, a DCAF protocol flow is depicted (messages in square 312 brackets are optional): 314 CAM C S SAM 315 | <== DTLS chan. ==> | | <== DTLS chan. ==> | 316 | | [Resource Req.-->] | | 317 | | | | 318 | | [<-- SAM Info.] | | 319 | | | | 320 | <-- Access Req. | | | 321 | | | | 322 | <==== TLS/DTLS channel (CAM/SAM Mutual Authentication) ====> | 323 | | | | 324 | Ticket Request ------------------------------------------> | 325 | | | | 326 | <------------------------------------------ Ticket Grant | 327 | | | | 328 | Ticket Transf. --> | | | 329 | | | | 330 | | <== DTLS chan. ==> | | 331 | | Auth. Res. Req. -> | | 333 Figure 1: Protocol Overview 335 To determine the SAM in charge of a resource hosted at the S, C MAY 336 send an initial Unauthorized Resource Request message to S. S then 337 denies the request and sends the address of its SAM back to C. 339 Instead of the initial Unauthorized Resource Request message, C MAY 340 look up the desired resource in a resource directory (cf. 341 [I-D.ietf-core-resource-directory]) that lists S's resources as 342 discussed in Section 9. 344 Once C knows SAM's address, it can send a request for authorization 345 to SAM using its own CAM. CAM and SAM authenticate each other and 346 each determine if the request is to be authorized. If it is, SAM 347 generates an access ticket for C. The ticket contains keying 348 material for the establishment of a secure channel and, if necessary, 349 a representation of the permissions C has for the resource. C keeps 350 one part of the access ticket and presents the other part to S to 351 prove its right to access. With their respective parts of the 352 ticket, C and S are able to establish a secure channel. 354 The following sections specify how CoAP is used to interchange 355 access-related data between S and SAM so that SAM can provide C and S 356 with sufficient information to establish a secure channel, and 357 simultaneously convey authorization information specific for this 358 communication relationship to S. 360 Note: Special implementation considerations apply when one single 361 entity takes the role of more than one actors. Section 11 gives 362 additional advice on some of these usage scenarios. 364 This document uses Concise Binary Object Representation (CBOR, 365 [RFC7049]) to express authorization information as set of attributes 366 passed in CoAP payloads. Notation and encoding options are discussed 367 in Section 5. A formal specification of the DCAF message format is 368 given in Appendix A. 370 3.2. Unauthorized Resource Request Message 372 The optional Unauthorized Resource Request message is a request for a 373 resource hosted by S for which no proper authorization is granted. S 374 MUST treat any CoAP request as Unauthorized Resource Request message 375 when any of the following holds: 377 o The request has been received on an unprotected channel. 379 o S has no valid access ticket for the sender of the request 380 regarding the requested action on that resource. 382 o S has a valid access ticket for the sender of the request, but 383 this does not allow the requested action on the requested 384 resource. 386 Note: These conditions ensure that S can handle requests autonomously 387 once access was granted and a secure channel has been established 388 between C and S. 390 Unauthorized Resource Request messages MUST be denied with a client 391 error response. In this response, the Server MUST provide proper SAM 392 Information to enable the Client to request an access ticket from S's 393 SAM as described in Section 3.3. 395 The response code MUST be 4.01 (Unauthorized) in case the sender of 396 the Unauthorized Resource Request message is not authenticated, or if 397 S has no valid access ticket for C. If S has an access ticket for C 398 but not for the resource that C has requested, S MUST reject the 399 request with a 4.03 (Forbidden). If S has an access ticket for C but 400 it does not cover the action C requested on the resource, S MUST 401 reject the request with a 4.05 (Method Not Allowed). 403 Note: The use of the response codes 4.03 and 4.05 is intended to 404 prevent infinite loops where a dumb Client optimistically tries to 405 access a requested resource with any access token received from 406 the SAM. As malicious clients could pretend to be C to determine 407 C's privileges, these detailed response codes must be used only 408 when a certain level of security is already available which can be 409 achieved only when the Client is authenticated. 411 3.3. SAM Information Message 413 The SAM Information Message is sent by S as a response to an 414 Unauthorized Resource Request message (see Section 3.2) to point the 415 sender of the Unauthorized Resource Request message to S's SAM. The 416 SAM information is a set of attributes containing an absolute URI 417 (see Section 4.3 of [RFC3986]) that specifies the SAM in charge of S. 419 An optional field A lists the different content formats that are 420 supported by S. 422 The message MAY also contain a timestamp generated by S. 424 Figure 2 shows an example for an SAM Information message payload 425 using CBOR diagnostic notation. (Refer to Section 5 for a detailed 426 description of the available attributes and their semantics.) 427 4.01 Unauthorized 428 Content-Format: application/dcaf+cbor 429 {SAM: "coaps://sam.example.com/authorize", TS: 168537, 430 A: [ TBD1, ct_cose_msg ] } 432 Figure 2: SAM Information Payload Example 434 In this example, the attribute SAM points the receiver of this 435 message to the URI "coaps://sam.example.com/authorize" to request 436 access permissions. The originator of the SAM Information payload 437 (i.e. S) uses a local clock that is loosely synchronized with a time 438 scale common between S and SAM (e.g., wall clock time). Therefore, 439 it has included a time stamp on its own time scale that is used as a 440 nonce for replay attack prevention. Refer to Section 4.1 for more 441 details concerning the usage of time stamps to ensure freshness of 442 access tickets. 444 The content formats accepted by S are TBD1 (identifying 'application/ 445 dcaf+cbor' as defined in this document), and 'application/cose+cbor' 446 defined in [I-D.ietf-cose-msg]. 448 Editorial note: ct_cose_msg is to be replaced with the numeric value 449 assigned for 'application/cose+cbor'. 451 The examples in this document are written in CBOR diagnostic notation 452 to improve readability. Figure 3 illustrates the binary encoding of 453 the message payload shown in Figure 2. 455 a2 # map(2) 456 00 # unsigned(0) (=SAM) 457 78 21 # text(33) 458 636f6170733a2f2f73616d2e6578 459 616d706c652e636f6d2f617574686f72 460 697a65 # "coaps://sam.example.com/authorize" 461 05 # unsigned(5) (=TS) 462 1a 00029259 # unsigned(168537) 463 0a # unsigned(10) (=A) 464 82 # array(2) 465 19 03e6 # unsigned(998) (=dcaf+cbor) 466 19 03e7 # unsigned(999) (=cose+cbor) 468 Figure 3: SAM Information Payload Example encoded in CBOR 470 3.3.1. Piggybacked Protected Content 472 For some use cases (such as sleepy nodes) it might be necessary to 473 store sensor data on a server that might not belong to the same 474 security domain. A client can retrieve the data from that server. 476 To be able to achieve the security objectives of the principles the 477 data must be protected properly. 479 The server that hosts the stored data may respond to GET requests for 480 this particular resource with a SAM Information message that contains 481 the protected data as piggybacked content. As the server may 482 frequently publish updates to the stored data, the URI of the 483 authorization manager responsible for the protected data MAY be 484 omitted and must be retrieved from a resource directory. 486 Once a requesting client has received the SAM Information Message 487 with piggybacked content, it needs to request authorization for 488 accessing the protected data. To do so, it constructs an Access 489 Request as defined in Section 3.4. If access to the protected data 490 is granted, the requesting client will be provided with cryptographic 491 material to verify the integrity and authenticity of the piggybacked 492 content and decrypt the protected data in case it is encrypted. 494 3.4. Access Request 496 To retrieve an access ticket for the resource that C wants to access, 497 C sends an Access Request to its CAM. The Access Request is 498 constructed as follows: 500 1. The request method is POST. 502 2. The request URI is set as described below. 504 3. The message payload contains a data structure that describes the 505 action and resource for which C requests an access ticket. 507 The request URI identifies a resource at CAM for handling 508 authorization requests from C. The URI SHOULD be announced by CAM in 509 its resource directory as described in Section 9. 511 Note: Where capacity limitations of C do not allow for resource 512 directory lookups, the request URI in Access Requests could be 513 hard-coded during provisioning or set in a specific device 514 configuration profile. 516 The message payload is constructed from the SAM information that S 517 has returned in its SAM Information message (see Section 3.3) and 518 information that C provides to describe its intended request(s). The 519 Access Request MUST contain the following attributes: 521 1. Contact information for the SAM to use. 523 2. An absolute URI of the resource that C wants to access. 525 3. The actions that C wants to perform on the resource. 527 4. Any time stamp generated by S. 529 An example Access Request from C to CAM is depicted in Figure 4. 530 (Refer to Section 5 for a detailed description of the available 531 attributes and their semantics.) 533 POST client-authorize 534 Content-Format: application/dcaf+cbor 535 { 536 SAM: "coaps://sam.example.com/authorize", 537 SAI: ["coaps://temp451.example.com/s/tempC", 5], 538 TS: 168537 539 } 541 Figure 4: Access Request Message Example 543 The example shows an Access Request message payload for the resource 544 "/s/tempC" on the Server "temp451.example.com". Requested operations 545 in attribute SAI are GET and PUT. 547 The attributes SAM (that denotes the Server Authorization Manager to 548 use) and TS (a nonce generated by S) are taken from the SAM 549 Information message from S. 551 The response to an Authorization Request is delivered by CAM back to 552 C in a Ticket Transfer message. 554 3.5. Ticket Request Message 556 When CAM receives an Access Request message from C and COP specified 557 authorization policies for C, CAM MUST check if the requested actions 558 are allowed according to these policies. If all requested actions 559 are forbidden, CAM MUST send a 4.03 response. 561 If no authorization policies were specified or some or all of the 562 requested actions are allowed according to the authorization 563 policies, CAM either returns a cached response or attempts to create 564 a Ticket Request message. The Ticket Request message MAY contain all 565 actions requested by C since CAM will add CAI in the Ticket Transfer 566 Message if COP specified authorization policies (see Section 3.7). 568 CAM MAY return a cached response if it is known to be fresh according 569 to Max-Age. CAM SHOULD NOT return a cached response if it expires in 570 less than a minute. 572 If CAM does not send a cached response, it checks whether the request 573 payload is of type "application/dcaf+cbor" and contains at least the 574 fields SAM and SAI. CAM MUST respond with 4.00 (Bad Request) if the 575 type is "application/dcaf+cbor" and any of these fields is missing or 576 does not conform to the format described in Section 5. 578 If the payload is correct, CAM creates a Ticket Request message from 579 the Access Request received from C as follows: 581 1. The destination of the Ticket Request message is derived from the 582 "SAM" field that is specified in the Access Request message 583 payload (for example, if the Access Request contained 'SAM: 584 "coaps://sam.example.com/authz"', the destination of the Ticket 585 Request message is sam.example.com). 587 2. The request method is POST. 589 3. The request URI is constructed from the SAM field received in the 590 Access Request message payload. 592 4. The payload is copied from the Access Request sent by C. 594 To send the Ticket Request message to SAM a secure channel between 595 CAM and SAM MUST be used. Depending on the URI scheme used in the 596 SAM field of the Access Request message payload (the less-constrained 597 devices CAM and SAM do not necessarily use CoAP to communicate with 598 each other), this could be, e.g., a DTLS channel (for "coaps") or a 599 TLS connection (for "https"). CAM and SAM MUST be able to mutually 600 authenticate each other, e.g. based on a public key infrastructure. 601 (Refer to Section 8 for a detailed discussion of the trust 602 relationship between Client Authorization Managers and Server 603 Authorization Managers.) 605 3.6. Ticket Grant Message 607 When SAM has received a Ticket Request message it has to evaluate the 608 access request information contained therein. First, it checks 609 whether the request payload is of type "application/dcaf+cbor" and 610 contains at least the fields SAM and SAI. SAM MUST respond with 4.00 611 (Bad Request) for CoAP (or 400 for HTTP) if the type is "application/ 612 dcaf+cbor" and any of these fields is missing or does not conform to 613 the format described in Section 5. 615 SAM decides whether or not access is granted to the requested 616 resource and then creates a Ticket Grant message that reflects the 617 result. To grant access to the requested resource, SAM creates an 618 access ticket comprised of a Face and the Client Information as 619 described in Section 4. 621 The Ticket Grant message then is constructed as a success response 622 indicating attached content, i.e. 2.05 for CoAP, or 200 for HTTP, 623 respectively. The payload of the Ticket Grant message is a data 624 structure that contains the result of the access request. When 625 access is granted, the data structure contains the Ticket Face and 626 the Client Information. Face contains the SAI and the Session Key 627 Generation Method. The CI at this point only consists of the 628 Verifier. 630 The Ticket Grant message MAY provide cache-control options to enable 631 intermediaries to cache the response. The message MAY be cached 632 according to the rules defined in [RFC7252] to facilitate ticket 633 retrieval when C has crashed and wants to recover the DTLS session 634 with S. 636 SAM SHOULD set Max-Age according to the ticket lifetime in its 637 response (Ticket Grant Message). 639 Figure 5 shows an example Ticket Grant message using CoAP. The Face/ 640 Verifier information is transferred as a CBOR data structure as 641 specified in Section 5. The Max-Age option tells the receiving CAM 642 how long this ticket will be valid. 644 2.05 Content 645 Content-Format: application/dcaf+cbor 646 Max-Age: 86400 647 { F: { 648 SAI: [ "/s/tempC", 7 ], 649 TS: 0("2013-07-10T10:04:12.391"), 650 L: 86400, 651 G: hmac_sha256 652 }, 653 V: h'f89947160c73601c7a65cb5e08812026 654 6d0f0565160e3ff7d3907441cdf44cc9' 655 } 657 Figure 5: Example Ticket Grant Message 659 A Ticket Grant message that declines any operation on the requested 660 resource is illustrated in Figure 6. As no ticket needs to be 661 issued, an empty payload is included with the response. 663 2.05 Content 664 Content-Format: application/dcaf+cbor 666 Figure 6: Example Ticket Grant Message With Reject 668 3.7. Ticket Transfer Message 670 A Ticket Transfer message delivers the access information sent by SAM 671 in a Ticket Grant message to the requesting client C. The Ticket 672 Transfer message is the response to the Access Request message sent 673 from C to CAM and includes the ticket data from SAM contained in the 674 Ticket Grant message. 676 The Authorization Information provided by SAM in the Ticket Grant 677 Message may grant more permissions than C has requested. The 678 authorization policies of COP and ROP may differ: COP might want 679 restrict the resources C is allowed to access, and the actions that C 680 is allowed to perform on the resource. 682 If COP defined authorization policies that concern the requested 683 actions, CAM MUST add Authorization Information for C (CAI) to the CI 684 that reflect those policies. Since C and CAM use a DTLS channel for 685 communication, the autorization information does not need to be 686 encrypted. 688 CAM includes the Face and the CI containing the verifier sent by SAM 689 in the Ticket Transfer message. However, CAM MUST NOT include 690 additional information SAM provided in CI. In particular, CAM MUST 691 NOT include any CAI information provided by SAM, since CAI represents 692 COP's authorization policies that MUST NOT be provided by SAM. 694 Figure 7 shows an example Ticket Transfer message that conveys the 695 permissions for actions GET, POST, PUT (but not DELETE) on the 696 resource "/s/tempC" in field SAI. As CAM only wants to permit 697 outbound GET requests, it restricts C's permissions in the field CAI 698 accordingly. 700 2.05 Content 701 Content-Format: application/dcaf+cbor 702 Max-Age: 86400 703 { F: { 704 SAI: [ "/s/tempC", 7 ], 705 TS: 0("2013-07-10T10:04:12.391"), 706 L: 86400, 707 G: hmac_sha256 708 }, 709 V: h'f89947160c73601c7a65cb5e08812026 710 6d0f0565160e3ff7d3907441cdf44cc9' 711 CAI: [ "/s/tempC", 1 ], 712 TS: 0("2013-07-10T10:04:12.855"), 713 L: 86400 714 } 716 Figure 7: Example Ticket Transfer Message 718 3.8. DTLS Channel Setup Between C and S 720 When C receives a Ticket Transfer message, it checks if the payload 721 contains a face and a Client Information. With this information C 722 can initiate establishment of a new DTLS channel with S. To use DTLS 723 with pre-shared keys, C follows the PSK key exchange algorithm 724 specified in Section 2 of [RFC4279], with the following additional 725 requirements: 727 1. C sets the psk_identity field of the ClientKeyExchange message to 728 the ticket Face received in the Ticket Transfer message. 730 2. C uses the ticket Verifier as PSK when constructing the premaster 731 secret. 733 Note1: As S cannot provide C with a meaningful PSK identity hint in 734 response to C's ClientHello message, S SHOULD NOT send a 735 ServerKeyExchange message. 737 Note2: According to [RFC7252], CoAP implementations MUST support the 738 ciphersuite TLS_PSK_WITH_AES_128_CCM_8 [RFC6655]. C is therefore 739 expected to offer at least this ciphersuite to S. 741 Note3: The ticket is constructed by SAM such that S can derive the 742 authorization information as well as the PSK (refer to Section 6 for 743 details). 745 3.9. Authorized Resource Request Message 747 If the Client Information in the Ticket Transfer message contains 748 CAI, C MUST ensure that it only sends requests that according to them 749 are allowed. C therefore MUST check CAI, L and TS before every 750 request. If CAI is no longer valid according to L, C MUST terminate 751 the DTLS connection with S and re-request the CAI from CAM using an 752 Access Request Message. 754 On the Server side, successful establishment of the DTLS channel 755 between C and S ties the SAM authorization information contained in 756 the psk_identity field to this channel. Any request that S receives 757 on this channel is checked against these authorization rules. 758 Incoming CoAP requests that are not Authorized Resource Requests MUST 759 be rejected by S with 4.01 response as described in Section 3.2. 761 S SHOULD treat an incoming CoAP request as Authorized Resource 762 Request if the following holds: 764 1. The message was received on a secure channel that has been 765 established using the procedure defined in Section 3.8. 767 2. The authorization information tied to the secure channel is 768 valid. 770 3. The request is destined for S. 772 4. The resource URI specified in the request is covered by the 773 authorization information. 775 5. The request method is an authorized action on the resource with 776 respect to the authorization information. 778 Note that the authorization information is not restricted to a single 779 resource URI. For example, role-based authorization can be used to 780 authorize a collection of semantically connected resources 781 simultaneously. Implicit authorization also provides access rights 782 to authenticated clients for all actions on all resources that S 783 offers. As a result, C can use the same DTLS channel not only for 784 subsequent requests for the same resource (e.g. for block-wise 785 transfer as defined in [I-D.ietf-core-block] or refreshing observe- 786 relationships [RFC7641]) but also for requests to distinct resources. 788 Incoming CoAP requests received on a secure channel according to the 789 procedure defined in Section 3.8 MUST be rejected 790 1. with response code 4.03 (Forbidden) when the resource URI 791 specified in the request is not covered by the authorization 792 information, and 794 2. with response code 4.05 (Method Not Allowed) when the resource 795 URI specified in the request covered by the authorization 796 information but not the requested action. 798 Since SAM may limit the set of requested actions in its Ticket Grant 799 message, C cannot know a priori if an Authorized Resource Request 800 will succeed. If C repeatedly gets SAM Information messages as 801 response to its requests, it SHOULD NOT send new Access Requests to 802 CAM. 804 3.10. Dynamic Update of Authorization Information 806 Once a security association exists between a Client and a Resource 807 Server, the Client can update the Authorization Information stored at 808 the Server at any time. To do so, the Client creates a new Access 809 Request for the intended action on the respective resource and sends 810 this request to its CAM which checks and relays this request to the 811 Server's SAM as described in Section 3.4. 813 Note: Requesting a new Access Ticket also can be a Client's reaction 814 on a 4.03 or 4.05 error that it has received in response to an 815 Authorized Resource Request. 817 Figure 8 depicts the message flow where C requests a new Access 818 Tickets after a security association between C and S has been 819 established using this protocol. 821 CAM C S SAM 822 | <== DTLS chan. ==> | <== DTLS chan. ==> | <== DTLS chan. ==> | 823 | | | | 824 | | [Unauth. R. Req->] | | 825 | |[<- 4.0x+SAM Info.] | | 826 | | | | 827 | <-- Access Req. | | | 828 | | | | 829 | <==== TLS/DTLS channel (CAM/SAM Mutual Authentication) ====> | 830 | | | | 831 | Ticket Request ------------------------------------------> | 832 | | | | 833 | <------------------------------------------ Ticket Grant | 834 | | | | 835 | Ticket Transf. --> | | | 836 | | | | 837 | | <== Update SAI ==> | | 839 Figure 8: Overview of Dynamic Update Operation 841 Processing the Ticket Request is done at the SAM as specified in 842 Section 3.6, i.e. the SAM checks whether or not the requested 843 operation is permitted by the Resource Principal's policy, and then 844 return a Ticket Grant message with the result of this check. If 845 access is granted, the Ticket Grant message contains an Access Ticket 846 comprised of a public Ticket Face and a private Ticket Verifier. 847 This authorization payload is relayed by CAM to the Client in a 848 Ticket Transfer Message as defined in Section 3.7. 850 The major difference between dynamic update of Authorization 851 Information and the initial handshake is the handling of a Ticket 852 Transfer message by the Client that is described in Section 3.10.1. 854 3.10.1. Handling of Ticket Transfer Messages 856 If the security association with S still exists and S has indicated 857 support for session renegotiation according to [RFC5746], the ticket 858 Face SHOULD be used to renegotiate the existing DTLS session. In 859 this case, the ticket Face is used as psk_identity as defined in 860 Section 3.8. Otherwise, the Client MUST perform a new DTLS handshake 861 according to Section 3.8 that replaces the existing DTLS session. 863 After successful completion of the DTLS handshake S updates the 864 existing SAM Authorization Information for C according to the 865 contents of the ticket Face. 867 Note: No mutual authentication between C and S is required for 868 dynamic updates when a DTLS channel exists that has been 869 established as defined in Section 3.8. S only needs to verify the 870 authenticity and integrity of the ticket Face issued by SAM which 871 is achieved by having performed a successful DTLS handshake with 872 the ticket Face as psk_identity. This could even be done within 873 the existing DTLS session by tunneling a CoDTLS 874 [I-D.schmertmann-dice-codtls] handshake. 876 4. Ticket 878 Access tokens in DCAF are tickets that consist of two parts, namely 879 the Face and the Client Information (CI). SAM generates the ticket 880 Face for S and the verifier that corresponds to the ticket Face for 881 C. The verifier is included in the CI. 883 The Ticket is transmitted over CAM to C. C keeps the CI and sends 884 the Face to S. CAM can add Client authorization information (CAI) 885 for C to the CI if necessary. 887 S uses the information in the ticket Face to validate that it was 888 generated by SAM and to authenticate and authorize the client. No 889 additional information about the Client is needed, S keeps the Ticket 890 Face as long as it is valid. 892 C uses the verifier to authenticate S. If CAM specified CAI, the 893 client uses it to authorize the server. 895 The ticket is not required to contain a client or a server 896 identifier. The ticket Face MAY contain an SAI identifier for 897 revocation. The CI MAY contain a CAI identifier for revocation. 899 4.1. Face 901 Face is the part of the ticket that is generated by SAM for S. Face 902 MUST contain all information needed for authorized access to a 903 resource: 905 o SAM Authorization Information (SAI) 907 o A nonce 909 Optionally, Face MAY also contain: 911 o A lifetime (optional) 913 o A DTLS pre-shared key (optional) 914 o A SAI identifier (optional) 916 S MUST verify the integrity of Face, i.e. the information contained 917 in Face stems from SAM and was not manipulated by anyone else. The 918 integrity of Face can be ensured by various means. Face may be 919 encrypted by SAM with a key it shares with S. Alternatively, S can 920 use a mechanism to generate the DTLS PSK which includes Face. S 921 generates the key from the Face it received. The correct key can 922 only be calculated with the correct Face (refer to Section 6 for 923 details). 925 Face MUST contain a nonce to verify that the contained information is 926 fresh. As constrained devices may not have a clock, nonces MAY be 927 generated using the clock ticks since the last reboot. To circumvent 928 synchronization problems the timestamp MAY be generated by S and 929 included in the first SAM Information message. Alternatively, SAM 930 MAY generate the timestamp for the nonce. In this case, SAM and S 931 MUST use a time synchronization mechanism to make sure that S 932 interprets the timestamp correctly. 934 Face MAY contain an SAI identifier that uniquely identifies the SAI 935 for S and SAM and can be used for revocation. 937 Face MAY be encrypted. If Face contains a DTLS PSK, the whole 938 content of Face MUST be encrypted. 940 The ticket Face does not need to contain a client identifier. 942 4.2. Client Information 944 The CI part of the ticket is generated for C. It contains 946 o The Verifier generated by SAM 948 CI MAY additionally contain: 950 o CAI generated by CAM 952 o A nonce generated by CAM 954 o A lifetime generated by CAM 956 o A SAI identifier generated by CAM 958 CI MUST contain the verifier, i.e. the DTLS PSK for C. The Verifier 959 MUST NOT be transmitted over unprotected channels. 961 Additionally, CI MAY contain CAI to provide the COP's authorization 962 policies to C. If the CI contains CAI, CAM MUST add a nonce that 963 enables C to validate that the information is fresh. CAM MAY use a 964 timestamp as the nonce (see Section 4.1). CAM SHOULD add a lifetime 965 to CI to limit the lifetime of the CAI. CAM MAY additionally add a 966 CAI identifier to CI for revocating the CAI. The CAI identifier MUST 967 uniquely identify the CAI for C and CAM. 969 4.3. Revocation 971 The existence of access tickets SHOULD be limited in time to avoid 972 stale tickets that waste resources on S and C. This can be achieved 973 either by explicit Revocation Messages to invalidate a ticket or 974 implicitly by attaching a lifetime to the ticket. 976 The SAI in the ticket Face and the CAI in the CI need to be protected 977 separately. CAM decides about the validity of the CAI while SAM is 978 in charge of the validity of SAI. To be able to revoke the CAI, CAM 979 SHOULD include a CAI identifier in the CI. SAM SHOULD include a SAI 980 identifier in FACE to be able to revocate the SAI. 982 4.4. Lifetime 984 SAI and CAI MAY each have lifetime. SAM is responsible for defining 985 the SAI lifetime, CAM is responsible for the CAI lifetime. If SAM 986 sets a lifetime for SAI, SAM and S MUST use a time synchronization 987 method to ensure that S is able to interpret the lifetime correctly. 988 S SHOULD end the DTLS connection to C if the lifetime of a ticket has 989 run out and it MUST NOT accept new requests. S MUST NOT accept 990 tickets with an invalid lifetime. 992 If CAM provides CAI in the CI part of the ticket, CAM MAY add a 993 lifetime for this CAI. If CI contains a lifetime, CAM and C MUST use 994 a time synchronization method to ensure that C is able to interpret 995 the lifetime correctly. C SHOULD end the DTLS connection to S and 996 MUST NOT send new requests if the CAI in the ticket is no longer 997 valid. C MUST NOT accept tickets with an invalid lifetime. 999 Note: Defining reasonable ticket lifetimes is difficult to 1000 accomplish. How long a client needs to access a resource depends 1001 heavily on the application scenario and may be difficult to decide 1002 for SAM. 1004 4.4.1. Revocation Messages 1006 SAM MAY revoke tickets by sending a ticket revocation message to S. 1007 If S receives a ticket revocation message, it MUST end the DTLS 1008 connection to C and MUST NOT accept any further requests from C. 1010 If ticket revocation messages are used, S MUST check regularly if SAM 1011 is still available. If S cannot contact SAM, it MUST end all DTLS 1012 connections and reject any further requests from C. 1014 Likewise, CAM MAY revoke tickets by sending a ticket revocation 1015 message to C. If C receives a CAI revocation message, it MUST end 1016 the DTLS connection to S and MUST NOT send any further requests to S. 1018 If CAI revocation messages are used, C MUST check regularly if CAM is 1019 still available. If C cannot contact CAM, it MUST end all DTLS 1020 connections and MUST NOT send any more requests to S. 1022 Note: The loss of the connection between S and SAM prevents all 1023 access to S. This might especially be a severe problem if SAM is 1024 responsible for several Servers or even a whole network. 1026 5. Payload Format and Encoding (application/dcaf+cbor) 1028 Various messages types of the DCAF protocol carry payloads to express 1029 authorization information and parameters for generating the DTLS PSK 1030 to be used by C and S. In this section, a representation in Concise 1031 Binary Object Representation (CBOR, [RFC7049]) is defined. 1033 DCAF data structures are defined as CBOR maps that contain key value 1034 pairs. For efficient encoding, the keys defined in this document are 1035 represented as unsigned integers in CBOR, i. e. major type 0. For 1036 improved reading, we use symbolic identifiers to represent the 1037 corresponding encoded values as defined in Table 1. 1039 +---------------+-----+ 1040 | Encoded Value | Key | 1041 +---------------+-----+ 1042 | 0 | SAM | 1043 | | | 1044 | 1 | SAI | 1045 | | | 1046 | 2 | CAI | 1047 | | | 1048 | 3 | E | 1049 | | | 1050 | 4 | K | 1051 | | | 1052 | 5 | TS | 1053 | | | 1054 | 6 | L | 1055 | | | 1056 | 7 | G | 1057 | | | 1058 | 8 | F | 1059 | | | 1060 | 9 | V | 1061 | | | 1062 | 10 | A | 1063 | | | 1064 | 11 | D | 1065 | | | 1066 | 12 | N | 1067 +---------------+-----+ 1069 Table 1: DCAF field identifiers encoded in CBOR 1071 The following list describes the semantics of the keys defined in 1072 DCAF. 1074 SAM: Server Authorization Manager. This attribute denotes the 1075 Server Authorization Manager that is in charge of the resource 1076 specified in attribute R. The attribute's value is a string that 1077 contains an absolute URI according to Section 4.3 of [RFC3986]. 1079 SAI: SAM Authorization Information. A data structure used to convey 1080 authorization information from SAM to S. It describes C's 1081 permissions for S according to SAM, e.g., which actions C is 1082 allowed to perform on an R of S. The SAI attribute contains an 1083 AIF object as defined in [I-D.bormann-core-ace-aif]. C uses SAI 1084 for its Access Request messages. 1086 CAI: CAM Authorization Information. A data structure used to convey 1087 authorization information from CAM to C. It describes the C's 1088 permissions for S according to CAM, e.g., which actions C is 1089 allowed to perform on an R of S. The CAI attribute contains an 1090 AIF object as defined in [I-D.bormann-core-ace-aif]. 1092 A: Accepted content formats. An array of numeric content formats 1093 from the CoAP Content-Formats registry (c.f. Section 12.3 of 1094 [RFC7252]. 1096 D: Protected Data. A binary string containing data that may be 1097 encrypted. 1099 E: Encrypted Ticket Face. A binary string containing an encrypted 1100 ticket Face. 1102 K: Key. A string that identifies the shared key between S and SAM 1103 that can be used to decrypt the contents of E. If the attribute E 1104 is present and no attribute K has been specified, the default is 1105 to use the current session key for the secured channel between S 1106 and SAM. 1108 TS: Time Stamp. A time stamp that indicates the instant when the 1109 access ticket request was formed. This attribute can be used by 1110 the Server in an SAM Information message to convey a time stamp in 1111 its local time scale (e.g. when it does not have a real time clock 1112 with synchronized global time). When the attribute's value is 1113 encoded as a string, it MUST contain a valid UTC timestamp without 1114 time zone information. When encoded as integer, TS contains a 1115 system timestamp relative to the local time scale of its 1116 generator, usually S. 1118 L: Lifetime. When in included in a ticket face, the contents of the 1119 L parameter denote the lifetime of the ticket. In combination 1120 with the protected data field D, this parameter denotes the 1121 lifetime of the protected data. When encoded as a string, L MUST 1122 denote the ticket's expiry time as a valid UTC timestamp without 1123 time zone information. When encoded as an integer, L MUST denote 1124 the ticket's validity period in seconds relative to TS. 1126 N: Nonce. An initialization vector used in combination with 1127 piggybacked protected content. 1129 G: DTLS PSK Generation Method. A numeric identifier for the method 1130 that S MUST use to derive the DTLS PSK from the ticket Face. This 1131 attribute MUST NOT be used when attribute V is present within the 1132 contents of F. This specification uses symbolic identifiers for 1133 improved readability. The corresponding numeric values encoded in 1134 CBOR are defined in Table 2. A registry for these codes is 1135 defined in Section 13.1. 1137 F: Ticket Face. An object containing the fields SAI, TS, and 1138 optionally G, L and V. 1140 V: Ticket Verifier. A binary string containing the shared secret 1141 between C and S. 1143 +---------------+-------------+-----------+ 1144 | Encoded Value | Mnemonic | Support | 1145 +---------------+-------------+-----------+ 1146 | 0 | hmac_sha256 | mandatory | 1147 | | | | 1148 | 1 | hmac_sha384 | optional | 1149 | | | | 1150 | 2 | hmac_sha512 | optional | 1151 +---------------+-------------+-----------+ 1153 Table 2: CBOR encoding for DTLS PSK Key Generation Methods 1155 5.1. Examples 1157 The following example specifies a SAM that will be accessed using 1158 HTTP over TLS. The request URI is set to 1159 "/a?ep=%5B2001:DB8::dcaf:1234%5D" (hence denoting the endpoint 1160 address to authorize). TS denotes a local timestamp in UTC. 1162 POST /a?ep=%5B2001:DB8::dcaf:1234%5D HTTP/1.1 1163 Host: sam.example.com 1164 Content-Type: application/dcaf+cbor 1165 {SAM: "https://sam.example.com/a?ep=%5B2001:DB8::dcaf:1234%5D", 1166 SAI: ["coaps://temp451.example.com/s/tempC", 1], 1167 TS: 0("2013-07-14T11:58:22.923")} 1169 The following example shows a ticket for the distributed key 1170 generation method (cf. Section 6.2), comprised of a Face (F) and a 1171 Verifier (V). The Face data structure contains authorization 1172 information SAI, a client descriptor, a timestamp using the local 1173 time scale of S, and a lifetime relative to S's time scale. 1175 The DTLS PSK Generation Method is set to hmac_sha256 denoting that 1176 the distributed key derivation is used as defined in Section 6.2 with 1177 SHA-256 as HMAC function. 1179 The Verifier V contains a shared secret to be used as DTLS PSK 1180 between C and S. 1182 HTTP/1.1 200 OK 1183 Content-Type: application/dcaf+cbor 1184 { 1185 F: { 1186 SAI: [ "/s/tempC", 1 ], 1187 TS: 2938749, 1188 L: 3600, 1189 G: hmac_sha256 1190 }, 1191 V: h'48ae5a81b87241d81618f56cab0b65ec 1192 441202f81faabbe10075b20cb57fa939' 1193 } 1195 The Face may be encrypted as illustrated in the following example. 1196 Here, the field E carries an encrypted Face data structure that 1197 contains the same information as the previous example, and an 1198 additional Verifier. Encryption was done with a secret shared by SAM 1199 and S. (This example uses AES128_CCM with the secret { 0x00, 0x01, 1200 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08, 0x09, 0x0a, 0x0b, 0x0c, 1201 0x0d, 0x0e, 0x0f } and S's timestamp { 0x00, 0x2C, 0xD7, 0x7D } as 1202 nonce.) Line breaks have been inserted to improve readability. 1204 The attribute K describes the identity of the key to be used by S to 1205 decrypt the contents of attribute E. Here, The value "key0" in this 1206 example is used to indicate that the shared session key between S and 1207 SAM was used for encrypting E. 1209 { 1210 E: h'2e75eeae01b831e0b65c2976e06d90f4 1211 82135bec5efef3be3d31520b2fa8c6fb 1212 f572f817203bf7a0940bb6183697567c 1213 e291b03e9fca5e9cbdfa7e560322d4ed 1214 3a659f44a542e55331a1a9f43d7f', 1215 K: "key0", 1216 V: h'48ae5a81b87241d81618f56cab0b65ec 1217 441202f81faabbe10075b20cb57fa939' 1218 } 1220 The decrypted contents of E are depicted below (whitespace has been 1221 added to improve readability). The presence of the attribute V 1222 indicates that the DTLS PSK Transfer is used to convey the session 1223 key (cf. Section 6.1). 1225 { 1226 F: { 1227 SAI: [ "/s/tempC", 1 ], 1228 TS: 2938749, 1229 L: 3600, 1230 G: hmac_sha256 1231 }, 1232 V: h'48ae5a81b87241d81618f56cab0b65ec 1233 441202f81faabbe10075b20cb57fa939' 1234 } 1236 6. DTLS PSK Generation Methods 1238 One goal of the DCAF protocol is to provide for a DTLS PSK shared 1239 between C and S. SAM and S MUST negotiate the method for the DTLS 1240 PSK generation. 1242 6.1. DTLS PSK Transfer 1244 The DTLS PSK is generated by AS and transmitted to C and S using a 1245 secure channel. 1247 The DTLS PSK transfer method is defined as follows: 1249 o SAM generates the DTLS PSK using an algorithm of its choice 1251 o SAM MUST include a representation of the DTLS PSK in Face and 1252 encrypt it together with all other information in Face with a key 1253 K(SAM,S) it shares with S. How SAM and S exchange K(SAM,S) is not 1254 in the scope of this document. SAM and S MAY use their preshared 1255 key as K(SAM,S). 1257 o SAM MUST include a representation of the DTLS PSK in the Verifier. 1259 o As SAM and C do not have a shared secret, the Verifier MUST be 1260 transmitted to C using encrypted channels. 1262 o S MUST decrypt Face using K(SAM,S) 1264 6.2. Distributed Key Derivation 1266 SAM generates a DTLS PSK for C which is transmitted using a secure 1267 channel. S generates its own version of the DTLS PSK using the 1268 information contained in Face (see also Section 4.1). 1270 The distributed key derivation method is defined as follows: 1272 o SAM and S both generate the DTLS PSK using the information 1273 included in Face. They use an HMAC algorithm on Face with a 1274 shared key K(SAM,S). The result serves as the DTLS PSK. How SAM 1275 and S exchange K(SAM,S) is not in the scope of this document. 1276 They MAY use their preshared key as K(SAM,S). How SAM and S 1277 negotiate the used HMAC algorithm is also not in the scope of this 1278 document. They MAY however use the HMAC algorithm they use for 1279 their DTLS connection. 1281 o SAM MUST include a representation of the DTLS PSK in the Verifier. 1283 o As SAM and C do not have a shared secret, the Verifier MUST be 1284 transmitted to C using encrypted channels. 1286 o SAM MUST NOT include a representation of the DTLS PSK in Face. 1288 o SAM MUST NOT encrypt Face. 1290 7. Authorization Configuration 1292 For the protocol defined in this document, proper configuration of 1293 CAM and SAM is crucial. The principals that are in charge of the 1294 resource, S and SAM, and the principals that are in charge of C and 1295 CAM need to define the respective permissions. The data 1296 representation of these permissions are not in the scope of this 1297 document. 1299 8. Trust Relationships 1301 The constrained devices may be too constrained to manage complex 1302 trust relationships. Thus, DCAF does not require the constrained 1303 devices to perform complex tasks such as identifying a formerly 1304 unknown party. Each constrained device has a trust relationship with 1305 its respective AM. These less constrained devices are able to 1306 perform the more complex security tasks and can establish security 1307 associations with formerly unknown parties. The AMs hand down these 1308 security associations to their respective constrained device. The 1309 constrained devices require the help of their AMs for authentication 1310 and authorization. 1312 C has a trust relationship with CAM: C trusts CAM to act in behalf of 1313 COP. S has a trust relationship with SAM: S trusts SAM to act in 1314 behalf of ROP. CAM trusts C to handle the data according to the CAI. 1315 SAM trusts S to protect resources according to the SAI. How the 1316 trust relationships between AMs and their respective constrained 1317 devices are established, is not in the scope of this document. It 1318 may be achieved by using a bootstrapping mechanism similar to 1319 [bergmann12] or by the means introduced in [I-D.gerdes-ace-a2a]. 1321 Additionally, SAM and CAM need to have established a trust 1322 relationship. Its establishment is not in the scope of this 1323 document. It fulfills the following conditions: 1325 1. SAM and CAM have means to mutually authenticate each other (e.g., 1326 they might have a certificate of the other party or a PKI in 1327 which it is included) 1329 2. If SAM requires information about the client from SAM, e.g. if 1330 SAM only wans to authorize certain types of devices, it can be 1331 sure that CAM correctly identifies these clients towards SAM and 1332 does not leak tickets that have been generated for a specific 1333 client C to another client. 1335 SAM trusts C indirectly because it trusts CAM and CAM vouches for C. 1336 The DCAF Protocol does not provide any means for SAM to validate that 1337 a resource request stems from a specific C. 1339 C indirectly entrusts SAM with some potentially confidential 1340 information, and trusts that SAM correctly represents S, because CAM 1341 trusts SAM. 1343 CAM trusts S indirectly because it trusts SAM and SAM vouches for S. 1345 C implicitly entrusts S with some potentially confidential 1346 information and trusts it to correctly represent R because it trusts 1347 CAM and because S can prove that it shares a key with SAM. 1349 CAM <------------------> SAM 1351 /|\ /|\ 1352 | | 1353 \|/ \|/ 1355 C ..................... S 1357 9. Listing Authorization Manager Information in a Resource Directory 1359 CoAP utilizes the Web Linking format [RFC5988] to facilitate 1360 discovery of services in an M2M environment. [RFC6690] defines 1361 specific link parameters that can be used to describe resources to be 1362 listed in a resource directory [I-D.ietf-core-resource-directory]. 1364 9.1. The "auth-request" Link Relation 1366 This section defines a resource type "auth-request" that can be used 1367 by clients to retrieve the request URI for a server's authorization 1368 service. When used with the parameter rt in a web link, "auth- 1369 request" indicates that the corresponding target URI can be used in a 1370 POST message to request authorization for the resource and action 1371 that are described in the request payload. 1373 The Content-Format "application/dcaf+cbor with numeric identifier 1374 TBD1 defined in this specification MAY be used to express access 1375 requests and their responses. 1377 The following example shows the web link used by CAM in this document 1378 to relay incoming Authorization Request messages to SAM. (Whitespace 1379 is included only for readability.) 1381 ;rt="auth-request";ct=TBD1 1382 ;title="Contact Remote Authorization Manager" 1384 The resource directory that hosts the resource descriptions of S 1385 could list the following description. In this example, the URI 1386 "ep/node138/a/switch2941" is relative to the resource context 1387 "coaps://sam.example.com/", i.e. the Server Authorization Manager 1388 SAM. 1390 ;rt="auth-request";ct=TBD1;ep="node138" 1391 ;title="Request Client Authorization" 1392 ;anchor="coaps://sam.example.com/" 1394 10. Examples 1396 This section gives a number of short examples with message flows for 1397 the initial Unauthorized Resource Request and the subsequent 1398 retrieval of a ticket from SAM. The notation here follows the actors 1399 conventions defined in Section 1.2.1. The payload format is encoded 1400 as proposed in Section 5. The IP address of SAM is 2001:DB8::1, the 1401 IP address of S is 2001:DB8::dcaf:1234, and C's IP address is 1402 2001:DB8::c. 1404 10.1. Access Granted 1406 This example shows an Unauthorized PUT request from C to S that is 1407 answered with a SAM Information message. C then sends a POST request 1408 to CAM with a description of its intended request. CAM forwards this 1409 request to SAM using CoAP over a DTLS-secured channel. The response 1410 from SAM contains an access ticket that is relayed back to CAM. 1412 C --> S 1413 PUT a/switch2941 [Mid=1234] 1414 Content-Format: application/senml+json 1415 {"e": [{"bv": "1"}]} 1417 C <-- S 1418 4.01 Unauthorized [Mid=1234] 1419 Content-Format: application/dcaf+cbor 1420 {SAM: "coaps://[2001:DB8::1]/ep/node138/a/switch2941"} 1422 C --> CAM 1423 POST client-authorize [Mid=1235,Token="tok"] 1424 Content-Format: application/dcaf+cbor 1425 { 1426 SAM: "coaps://[2001:DB8::1]/ep/node138/a/switch2941", 1427 SAI: ["coaps://[2001:DB8::dcaf:1234]/a/switch2941", 4] 1428 } 1430 CAM --> SAM [Mid=23146] 1431 POST ep/node138/a/switch2941 1432 Content-Format: application/dcaf+cbor 1433 { 1434 SAM: "coaps://[2001:DB8::1]/ep/node138/a/switch2941", 1435 SAI: ["coaps://[2001:DB8::dcaf:1234]/a/switch2941", 4] 1436 } 1438 CAM <-- SAM 1439 2.05 Content [Mid=23146] 1440 Content-Format: application/dcaf+cbor 1441 { F: { 1442 SAI: ["a/switch2941", 5], 1443 TS: 0("2013-07-04T20:17:38.002"), 1444 G: hmac_sha256 1445 }, 1446 V: h'7ba4d9e287c8b69dd52fd3498fb8d26d 1447 9503611917b014ee6ec2a570d857987a' 1448 } 1450 C <-- CAM 1451 2.05 Content [Mid=1235,Token="tok"] 1452 Content-Format: application/dcaf+cbor 1453 { F: { 1454 SAI: ["a/switch2941", 5], 1455 TS: 0("2013-07-04T20:17:38.002"), 1456 G: hmac_sha256 1457 }, 1458 V: h'7ba4d9e287c8b69dd52fd3498fb8d26d 1459 9503611917b014ee6ec2a570d857987a' 1461 } 1463 C --> S 1464 ClientHello (TLS_PSK_WITH_AES_128_CCM_8) 1466 C <-- S 1467 ServerHello (TLS_PSK_WITH_AES_128_CCM_8) 1468 ServerHelloDone 1470 C --> S 1471 ClientKeyExchange 1472 psk_identity=0xa301826c612f73776974636832393431 1473 0x0505c077323031332d30372d30345432 1474 0x303a31373a33382e3030320700 1476 (C decodes the contents of V and uses the result as PSK) 1477 ChangeCipherSpec 1478 Finished 1480 (S calculates PSK from SAI, TS and its session key 1481 HMAC_sha256(0xa301826c612f73776974636832393431 1482 0x0505c077323031332d30372d30345432 1483 0x303a31373a33382e3030320700, 1484 0x736563726574) 1485 = 0x7ba4d9e287c8... 1486 ) 1488 C <-- S 1489 ChangeCipherSpec 1490 Finished 1492 10.2. Access Denied 1494 This example shows a denied Authorization request for the DELETE 1495 operation. 1497 C --> S 1498 DELETE a/switch2941 1500 C <-- S 1501 4.01 Unauthorized 1502 Content-Format: application/dcaf+cbor 1503 {SAM: "coaps://[2001:DB8::1]/ep/node138/a/switch2941"} 1505 C --> CAM 1506 POST client-authorize 1507 Content-Format: application/dcaf+cbor 1508 { 1509 SAM: "coaps://[2001:DB8::1]/ep/node138/a/switch2941", 1510 SAI: ["coaps://[2001:DB8::dcaf:1234]/a/switch2941", 8] 1511 } 1513 CAM --> SAM 1514 POST ep/node138/a/switch2941 1515 Content-Format: application/dcaf+cbor 1516 { 1517 SAM: "coaps://[2001:DB8::1]/ep/node138/a/switch2941", 1518 SAI: ["coaps://[2001:DB8::dcaf:1234]/a/switch2941", 8] 1519 } 1521 CAM <-- SAM 1522 2.05 Content 1523 Content-Format: application/dcaf+cbor 1525 C <-- CAM 1526 2.05 Content 1527 Content-Format: application/dcaf+cbor 1529 10.3. Access Restricted 1531 This example shows a denied Authorization request for the operations 1532 GET, PUT, and DELETE. SAM grants access for PUT only. 1534 CAM --> SAM 1535 POST ep/node138/a/switch2941 1536 Content-Format: application/dcaf+cbor 1537 { 1538 SAM: "coaps://[2001:DB8::1]/ep/node138/a/switch2941", 1539 SAI: ["coaps://[2001:DB8::dcaf:1234]/a/switch2941", 13] 1540 } 1542 CAM <-- SAM 1543 2.05 Content 1544 Content-Format: application/dcaf+cbor 1545 { F: { 1546 SAI: ["a/switch2941", 5], 1547 TS: 0("2013-07-04T21:33:11.930"), 1548 G: hmac_sha256 1549 }, 1550 V: h'c7b5774f2ddcbd548f4ad74b30a1b2e5 1551 b6b04e66a9995edd2545e5a06216c53d' 1552 } 1554 10.4. Implicit Authorization 1556 This example shows an Authorization request using implicit 1557 authorization. CAM initially requests the actions GET and POST on 1558 the resource "coaps://[2001:DB8::dcaf:1234]/a/switch2941". SAM 1559 returns a ticket that has no SAI field in its ticket Face, hence 1560 implicitly authorizing C. 1562 CAM --> SAM 1563 POST ep/node138/a/switch2941 1564 Content-Format: application/dcaf+cbor 1565 { 1566 SAM: "coaps://[2001:DB8::1]/ep/node138/a/switch2941", 1567 SAI: ["coaps://[2001:DB8::dcaf:1234]/a/switch2941", 3] 1568 } 1570 CAM <-- SAM 1571 2.05 Content 1572 Content-Format: application/dcaf+cbor 1573 { F: { 1574 TS: 0("2013-07-16T10:15:43.663"), 1575 G: hmac_sha256 1576 }, 1577 V: h'4f7b0e7fdcc498fb2ece648bf6bdf736 1578 61a6067e51278a0078e5b8217147ea06' 1579 } 1581 11. Specific Usage Scenarios 1583 The general DCAF architure outlined in Section 3.1 illustrates the 1584 various actors who participate in the message exchange for 1585 authenticated authorization. The message types defined in this 1586 document cover the most general case where all four actors are 1587 separate entities that may or may not reside on the same device. 1589 Special implementation considerations apply when one single entity 1590 takes the role of more than one actor. This section gives advice on 1591 the most common usage scenarios where the Client Authorization 1592 Manager and Client, the Server Authorization Manager and Server or 1593 both Authorization Managers reside on the same (less-constrained) 1594 device and have a means of secure communication outside the scope of 1595 this document. 1597 11.1. Combined Authorization Manager and Client 1599 When CAM and C reside on the same (less-constrained) device, the 1600 Access Request and Ticket Transfer messages can be substituted by 1601 other means of secure communication. Figure 9 shows a simplified 1602 message exchange for a combined CAM+C device. 1604 CAM+C S SAM 1605 | | <== DTLS chan. ==> | 1606 | [Resource Req.-->] | | 1607 | | | 1608 | [<-- SAM Info.] | | 1609 | | | 1610 | <==== TLS/DTLS chan. (Mutual Auth) ===> | 1611 | | | 1612 | Ticket Request ---------------------> | 1613 | | | 1614 | <--------------------- Ticket Grant | 1615 | | | 1616 | <== DTLS chan. ==> | | 1617 | Auth. Res. Req. -> | | 1619 Figure 9: Combined Client Authorization Manager and Client 1621 11.1.1. Creating the Ticket Request Message 1623 When CAM+C receives an SAM Information message as a reaction to an 1624 Unauthorized Request message, it creates a Ticket Request message as 1625 follows: 1627 1. The destination of the Ticket Request message is derived from the 1628 authority information in the URI contained in field "SAM" of the 1629 SAM Information message payload. 1631 2. The request method is POST. 1633 3. The request URI is constructed from the SAM field received in the 1634 SAM Information message payload. 1636 4. The payload contains the SAM field from the SAM Information 1637 message, an absolute URI of the resource that CAM+C wants to 1638 access, the actions that CAM+C wants to perform on the resource, 1639 and any time stamp generated by S that was transferred with the 1640 SAM Information message. 1642 11.1.2. Processing the Ticket Grant Message 1644 Based on the Ticket Grant message, CAM+C is able to establish a DTLS 1645 channel with S. To do so, CAM+C sets the psk_identity field of the 1646 DTLS ClientKeyExchange message to the ticket Face received in the 1647 Ticket Grant message and uses the ticket Verifier as PSK when 1648 constructing the premaster secret. 1650 11.2. Combined Client Authorization Manager and Server Authorization 1651 Manager 1653 In certain scenarios, CAM and SAM may be combined to a single entity 1654 that knows both, C and S, and decides if their actions are 1655 authorized. Therefore, no explicit communication between CAM and SAM 1656 is necessary, resulting in omission of the Ticket Request and Ticket 1657 Grant messages. Figure 10 depicts the resulting message sequence in 1658 this simplified architecture. 1660 C CAM+SAM S 1661 | <== DTLS chan. ==> | <== DTLS chan. ==> | 1662 | | | 1663 | [Resource Req.----------------------->] | 1664 | | | 1665 | [<-------------------- SAM Information] | 1666 | | | 1667 | Access Request --> | | 1668 | | | 1669 | <-- Ticket Transf. | | 1670 | | | 1671 | <=========== DTLS channel ===========> | 1672 | | | 1673 | Authorized Resource Request ----------> | 1675 Figure 10: Combined Client Authorization Manager and Server 1676 Authorization Manager 1678 11.2.1. Processing the Access Request Message 1680 When receiving an Access Request message, CAM+SAM performs the checks 1681 specified in Section 3.5 and returns a 4.00 (Bad Request) response in 1682 case of failure. Otherwise, if the checks have succeeded, CAM+SAM 1683 evaluates the contents of Access Request message as described in 1684 Section 3.6. 1686 The decision on the access request is performed by CAM+SAM with 1687 respect to the stored policies. When the requested action is 1688 permitted on the respective resource, CAM+SAM generates an access 1689 ticket as outlined in Section 4.1 and creates a Ticket Transfer 1690 message to convey the access ticket to the Client. 1692 11.2.2. Creating the Ticket Transfer Message 1694 A Ticket Transfer message is constructed as a 2.05 response with the 1695 access ticket contained in its payload. The response MAY contain a 1696 Max-Age option to indicate the ticket's lifetime to the receiving 1697 Client. 1699 This specification defines a CBOR data representation for the access 1700 ticket as illustrated in Section 3.6. 1702 11.3. Combined Server Authorization Manager and Server 1704 If SAM and S are colocated in one entity (SAM+S), the main objective 1705 is to allow CAM to delegate access to C. Accordingly, the 1706 authorization information could be replaced by a nonce internal to 1707 SAM+S. (TBD.) 1708 CAM C SAM+S 1709 | <== DTLS chan. ==> | | 1710 | | [Resource Req.-->] | 1711 | | | 1712 | | [<-- SAM Info.] | 1713 | | | 1714 | <-- Access Req. | | 1715 | | | 1716 | <========= TLS/DTLS channel =========> | 1717 | | | 1718 | Ticket Request ---------------------> | 1719 | | | 1720 | <--------------------- Ticket Grant | 1721 | | | 1722 | Ticket Transf. --> | | 1723 | | | 1724 | | <== DTLS chan. ==> | 1725 | | Auth. Res. Req. -> | 1727 Figure 11: Combined Server Authorization Manager and Server 1729 12. Security Considerations 1731 As this protocol builds on transitive trust between Authorization 1732 Managers as mentioned in Section 8, SAM has no direct means to 1733 validate that a resource request originates from C. It has to trust 1734 CAM that it correctly vouches for C and that it does not give 1735 authorization tickets meant for C to another client nor disclose the 1736 contained session key. 1738 The Authorization Managers also could constitute a single point of 1739 failure. If the Server Authorization Manager fails, the resources on 1740 all Servers it is responsible for cannot be accessed any more. If a 1741 Client Authorization Manager fails, all clients it is responsible are 1742 not able to access resources on a Server. Thus, it is crucial for 1743 large networks to use Authorization Managers in a redundant setup. 1745 13. IANA Considerations 1747 The following registrations are done following the procedure 1748 specified in [RFC6838]. 1750 Note to RFC Editor: Please replace all occurrences of "[RFC-XXXX]" 1751 with the RFC number of this specification. 1753 13.1. DTLS PSK Key Generation Methods 1755 A sub-registry for the values indicating the PSK key generation 1756 method as contents of the field G in a payload of type application/ 1757 dcaf+cbor is defined. Values in this sub-registry are numeric 1758 integers encoded in Concise Binary Object Notation (CBOR, [RFC7049]). 1759 This document follows the notation of [RFC7049] for binary values, 1760 i.e. a number starts with the prefix "0b". The major type is 1761 separated from the actual numeric value by an underscore to emphasize 1762 the value's internal structure. 1764 Initial entries in this sub-registry are as follows: 1766 +---------------+-------------+------------+ 1767 | Encoded Value | Name | Reference | 1768 +---------------+-------------+------------+ 1769 | 0b000_00000 | hmac_sha256 | [RFC-XXXX] | 1770 | | | | 1771 | 0b000_00001 | hmac_sha384 | [RFC-XXXX] | 1772 | | | | 1773 | 0b000_00010 | hmac_sha512 | [RFC-XXXX] | 1774 +---------------+-------------+------------+ 1776 Table 3: DTLS PSK Key Generation Methods 1778 New methods can be added to this registry based on designated expert 1779 review according to [RFC5226]. 1781 (TBD: criteria for expert review.) 1783 13.2. dcaf+cbor Media Type Registration 1785 Type name: application 1787 Subtype name: dcaf+cbor 1789 Required parameters: none 1791 Optional parameters: none 1793 Encoding considerations: Must be encoded as using a subset of the 1794 encoding allowed in [RFC7049]. Specifically, only the primitive data 1795 types String and Number are allowed. The type Number is restricted 1796 to unsigned integers (i.e., no negative numbers, fractions or 1797 exponents are allowed). Encoding MUST be UTF-8. These restrictions 1798 simplify implementations on devices that have very limited memory 1799 capacity. 1801 Security considerations: TBD 1803 Interoperability considerations: TBD 1805 Published specification: [RFC-XXXX] 1807 Applications that use this media type: TBD 1809 Additional information: 1811 Magic number(s): none 1813 File extension(s): dcaf 1815 Macintosh file type code(s): none 1817 Person & email address to contact for further information: TBD 1819 Intended usage: COMMON 1821 Restrictions on usage: None 1823 Author: TBD 1825 Change controller: IESG 1827 13.3. CoAP Content Format Registration 1829 This document specifies a new media type application/dcaf+cbor (cf. 1830 Section 13.2). For use with CoAP, a numeric Content-Format 1831 identifier is to be registered in the "CoAP Content-Formats" sub- 1832 registry within the "CoRE Parameters" registry. 1834 Note to RFC Editor: Please replace all occurrences of "RFC-XXXX" with 1835 the RFC number of this specification. 1837 +-----------------------+----------+------+------------+ 1838 | Media type | Encoding | Id. | Reference | 1839 +-----------------------+----------+------+------------+ 1840 | application/dcaf+cbor | - | TBD1 | [RFC-XXXX] | 1841 +-----------------------+----------+------+------------+ 1843 14. Acknowledgements 1845 The authors would like to thank Renzo Navas for his valuable input 1846 and feedback. 1848 15. References 1850 15.1. Normative References 1852 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1853 Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/ 1854 RFC2119, March 1997, 1855 . 1857 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 1858 Resource Identifier (URI): Generic Syntax", STD 66, RFC 1859 3986, DOI 10.17487/RFC3986, January 2005, 1860 . 1862 [RFC4279] Eronen, P., Ed. and H. Tschofenig, Ed., "Pre-Shared Key 1863 Ciphersuites for Transport Layer Security (TLS)", RFC 1864 4279, DOI 10.17487/RFC4279, December 2005, 1865 . 1867 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 1868 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 1869 DOI 10.17487/RFC5226, May 2008, 1870 . 1872 [RFC5746] Rescorla, E., Ray, M., Dispensa, S., and N. Oskov, 1873 "Transport Layer Security (TLS) Renegotiation Indication 1874 Extension", RFC 5746, DOI 10.17487/RFC5746, February 2010, 1875 . 1877 [RFC6347] Rescorla, E. and N. Modadugu, "Datagram Transport Layer 1878 Security Version 1.2", RFC 6347, DOI 10.17487/RFC6347, 1879 January 2012, . 1881 [RFC6838] Freed, N., Klensin, J., and T. Hansen, "Media Type 1882 Specifications and Registration Procedures", BCP 13, RFC 1883 6838, DOI 10.17487/RFC6838, January 2013, 1884 . 1886 [RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object 1887 Representation (CBOR)", RFC 7049, DOI 10.17487/RFC7049, 1888 October 2013, . 1890 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 1891 Application Protocol (CoAP)", RFC 7252, DOI 10.17487/ 1892 RFC7252, June 2014, 1893 . 1895 15.2. Informative References 1897 [I-D.bormann-core-ace-aif] 1898 Bormann, C., "An Authorization Information Format (AIF) 1899 for ACE", draft-bormann-core-ace-aif-03 (work in 1900 progress), July 2015. 1902 [I-D.gerdes-ace-a2a] 1903 Gerdes, S., "Managing the Authorization to Authorize in 1904 the Lifecycle of a Constrained Device", draft-gerdes-ace- 1905 a2a-01 (work in progress), September 2015. 1907 [I-D.greevenbosch-appsawg-cbor-cddl] 1908 Vigano, C. and H. Birkholz, "CBOR data definition language 1909 (CDDL): a notational convention to express CBOR data 1910 structures", draft-greevenbosch-appsawg-cbor-cddl-07 (work 1911 in progress), October 2015. 1913 [I-D.ietf-ace-actors] 1914 Gerdes, S., Seitz, L., Selander, G., and C. Bormann, "An 1915 architecture for authorization in constrained 1916 environments", draft-ietf-ace-actors-02 (work in 1917 progress), October 2015. 1919 [I-D.ietf-core-block] 1920 Bormann, C. and Z. Shelby, "Block-wise transfers in CoAP", 1921 draft-ietf-core-block-18 (work in progress), September 1922 2015. 1924 [I-D.ietf-core-resource-directory] 1925 Shelby, Z., Koster, M., Bormann, C., and P. Stok, "CoRE 1926 Resource Directory", draft-ietf-core-resource-directory-05 1927 (work in progress), October 2015. 1929 [I-D.ietf-cose-msg] 1930 Schaad, J., "CBOR Encoded Message Syntax", draft-ietf- 1931 cose-msg-06 (work in progress), October 2015. 1933 [I-D.schmertmann-dice-codtls] 1934 Schmertmann, L., Hartke, K., and C. Bormann, "CoDTLS: DTLS 1935 handshakes over CoAP", draft-schmertmann-dice-codtls-01 1936 (work in progress), August 2014. 1938 [RFC5988] Nottingham, M., "Web Linking", RFC 5988, DOI 10.17487/ 1939 RFC5988, October 2010, 1940 . 1942 [RFC6655] McGrew, D. and D. Bailey, "AES-CCM Cipher Suites for 1943 Transport Layer Security (TLS)", RFC 6655, DOI 10.17487/ 1944 RFC6655, July 2012, 1945 . 1947 [RFC6690] Shelby, Z., "Constrained RESTful Environments (CoRE) Link 1948 Format", RFC 6690, DOI 10.17487/RFC6690, August 2012, 1949 . 1951 [RFC7641] Hartke, K., "Observing Resources in the Constrained 1952 Application Protocol (CoAP)", RFC 7641, DOI 10.17487/ 1953 RFC7641, September 2015, 1954 . 1956 [bergmann12] 1957 Bergmann, O., Gerdes, S., Schaefer, S., Junge, F., and C. 1958 Bormann, "Secure Bootstrapping of Nodes in a CoAP 1959 Network", IEEE Wireless Communications and Networking 1960 Conference Workshops (WCNCW), April 2012. 1962 Appendix A. CDDL Specification 1964 This appendix shows a formal specification of the DCAF messaging 1965 format using the CBOR data definition language (CDDL) 1966 [I-D.greevenbosch-appsawg-cbor-cddl]: 1968 dcaf-msg = sam-information-msg 1969 / access-request-msg 1970 / ticket-transfer-msg 1971 / ticket-grant-msg 1973 sam-information-msg = { sam, ? full-timestamp, ? accepted-formats, 1974 ? piggybacked } 1976 access-request-msg = { sam, sam-ai, full-timestamp } 1978 ticket-transfer-msg = { face-or-encrypted, verifier } 1979 face-or-encrypted = ( face | encrypted-face ) 1980 face = ( F => { sam-ai, limited-timestamp, lifetime, psk-gen } ) 1981 verifier = ( V => shared-secret ) 1982 shared-secret = bstr 1983 F = 8 1984 V = 9 1986 encrypted-face = ( E => bstr, K => tstr ) 1987 E = 3 1988 K = 4 1989 ticket-grant-msg = { face-or-encrypted, verifier, ? client-info } 1990 client-info = ( cam-ai, full-timestamp, lifetime) 1992 sam = (SAM => abs-uri) 1993 SAM = 0 1994 abs-uri = tstr ; .regexp "______" 1996 sam-ai = ( SAI => [* auth-info]) 1997 SAI = 1 1998 auth-info = ( uri : tstr, mask : 0..15 ) 2000 cam-ai = ( CAI => [* auth-info]) 2001 CAI = 2 2003 full-timestamp = ( TS => date) 2004 TS = 5 2005 date = tdate / localdate 2006 localdate = uint 2007 limited-timestamp = ( TS => localdate) 2009 accepted-formats = ( A => [+ content-format] ) 2010 content-format = uint ; valid entry from CoAP content format registry 2011 A=10 2013 piggybacked = ( data, lifetime, nonce ) 2014 data = ( D => bstr ) 2015 none = ( N => bstr ) 2016 lifetime = ( L => period) 2017 period = uint ; in seconds 2018 L = 6 2019 D = 11 2020 N = 12 2022 psk-gen = ( G => mac-algorithm) 2023 G = 7 2024 mac-algorithm = &( hmac-sha256: 0, hmac-sha384: 1, hmac-sha512: 2 ) 2026 Authors' Addresses 2028 Stefanie Gerdes 2029 Universitaet Bremen TZI 2030 Postfach 330440 2031 Bremen D-28359 2032 Germany 2034 Phone: +49-421-218-63906 2035 Email: gerdes@tzi.org 2036 Olaf Bergmann 2037 Universitaet Bremen TZI 2038 Postfach 330440 2039 Bremen D-28359 2040 Germany 2042 Phone: +49-421-218-63904 2043 Email: bergmann@tzi.org 2045 Carsten Bormann 2046 Universitaet Bremen TZI 2047 Postfach 330440 2048 Bremen D-28359 2049 Germany 2051 Phone: +49-421-218-63921 2052 Email: cabo@tzi.org