idnits 2.17.1 draft-gerdes-ace-dcaf-authorize-03.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 (September 10, 2015) is 3150 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 1762, 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-06 == Outdated reference: A later version (-21) exists of draft-ietf-core-block-17 == Outdated reference: A later version (-28) exists of draft-ietf-core-resource-directory-04 == Outdated reference: A later version (-24) exists of draft-ietf-cose-msg-04 -- Obsolete informational reference (is this intentional?): RFC 5988 (Obsoleted by RFC 8288) Summary: 3 errors (**), 0 flaws (~~), 7 warnings (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 ACE Working Group S. Gerdes 3 Internet-Draft O. Bergmann 4 Intended status: Standards Track C. Bormann 5 Expires: March 13, 2016 Universitaet Bremen TZI 6 September 10, 2015 8 Delegated CoAP Authentication and Authorization Framework (DCAF) 9 draft-gerdes-ace-dcaf-authorize-03 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 March 13, 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 . . . . . . . . . . . . . . . . . 14 73 3.8. DTLS Channel Setup Between C and S . . . . . . . . . . . 15 74 3.9. Authorized Resource Request Message . . . . . . . . . . . 16 75 3.10. Dynamic Update of Authorization Information . . . . . . . 17 76 3.10.1. Handling of Ticket Transfer Messages . . . . . . . . 18 77 4. Ticket . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 78 4.1. Face . . . . . . . . . . . . . . . . . . . . . . . . . . 19 79 4.2. Client Information . . . . . . . . . . . . . . . . . . . 20 80 4.3. Revocation . . . . . . . . . . . . . . . . . . . . . . . 20 81 4.3.1. Lifetime . . . . . . . . . . . . . . . . . . . . . . 20 82 4.3.2. Revocation Messages . . . . . . . . . . . . . . . . . 21 83 5. Payload Format and Encoding (application/dcaf+cbor) . . . . . 21 84 5.1. Examples . . . . . . . . . . . . . . . . . . . . . . . . 24 85 6. DTLS PSK Generation Methods . . . . . . . . . . . . . . . . . 26 86 6.1. DTLS PSK Transfer . . . . . . . . . . . . . . . . . . . . 26 87 6.2. Distributed Key Derivation . . . . . . . . . . . . . . . 26 88 7. Authorization Configuration . . . . . . . . . . . . . . . . . 27 89 8. Trust Relationships . . . . . . . . . . . . . . . . . . . . . 27 90 9. Listing Authorization Manager Information in a Resource 91 Directory . . . . . . . . . . . . . . . . . . . . . . . . . . 28 92 9.1. The "auth-request" Link Relation . . . . . . . . . . . . 28 93 10. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 29 94 10.1. Access Granted . . . . . . . . . . . . . . . . . . . . . 29 95 10.2. Access Denied . . . . . . . . . . . . . . . . . . . . . 31 96 10.3. Access Restricted . . . . . . . . . . . . . . . . . . . 32 97 10.4. Implicit Authorization . . . . . . . . . . . . . . . . . 33 98 11. Specific Usage Scenarios . . . . . . . . . . . . . . . . . . 34 99 11.1. Combined Authorization Manager and Client . . . . . . . 34 100 11.1.1. Creating the Ticket Request Message . . . . . . . . 34 101 11.1.2. Processing the Ticket Grant Message . . . . . . . . 35 102 11.2. Combined Client Authorization Manager and Server 103 Authorization Manager . . . . . . . . . . . . . . . . . 35 104 11.2.1. Processing the Access Request Message . . . . . . . 36 105 11.2.2. Creating the Ticket Transfer Message . . . . . . . . 36 106 11.3. Combined Server Authorization Manager and Server . . . . 36 107 12. Security Considerations . . . . . . . . . . . . . . . . . . . 37 108 13. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 37 109 13.1. DTLS PSK Key Generation Methods . . . . . . . . . . . . 38 110 13.2. dcaf+cbor Media Type Registration . . . . . . . . . . . 38 111 13.3. CoAP Content Format Registration . . . . . . . . . . . . 39 112 14. References . . . . . . . . . . . . . . . . . . . . . . . . . 39 113 14.1. Normative References . . . . . . . . . . . . . . . . . . 40 114 14.2. Informative References . . . . . . . . . . . . . . . . . 41 115 Appendix A. CDDL Specification . . . . . . . . . . . . . . . . . 42 116 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 43 118 1. Introduction 120 The Constrained Application Protocol (CoAP) [RFC7252] is a transfer 121 protocol similar to HTTP which is designed for the special 122 requirements of constrained environments. A serious problem with 123 constrained devices is the realization of secure communication. The 124 devices only have limited system resources such as memory, stable 125 storage (such as disk space) and transmission capacity and often lack 126 input/output devices such as keyboards or displays. Therefore, they 127 are not readily capable of using common protocols. Especially 128 authentication mechanisms are difficult to realize, because the lack 129 of stable storage severely limits the number of keys the system can 130 store. Moreover, CoAP has no mechanism for authorization. 132 [I-D.gerdes-ace-actors] describes an architecture that is designed to 133 help constrained nodes with authorization-related tasks by 134 introducing less-constrained nodes. These Authorization Managers 135 perform complex security tasks for their nodes such as managing keys 136 for numerous devices, and enable the constrained nodes to enforce the 137 authorization policies of their principals. 139 DCAF uses access tokens to implement this architecture. A device 140 that wants to access an item of interest on a constrained node first 141 has to gain permission in the form of a token from the node's 142 Authorization Manager. 144 As fine-grained authorization is not always needed on constrained 145 devices, DCAF supports an implicit authorization mode where no 146 authorization information is exchanged. 148 The main goals of DCAF are the setup of a Datagram Transport Layer 149 Security (DTLS) [RFC6347] channel with symmetric pre-shared keys 150 (PSK) [RFC4279] between two nodes and to securely transmit 151 authorization tickets. 153 1.1. Features 155 o Utilize DTLS communication with pre-shared keys. 157 o Authenticated exchange of authorization information. 159 o Simplified authentication on constrained nodes by handing the more 160 sophisticated authentication over to less-constrained devices. 162 o Support of secure constrained device to constrained device 163 communication. 165 o Authorization policies of the principals of both participating 166 parties are ensured. 168 o Simplified authorization mechanism for cases where implicit 169 authorization is sufficient. 171 o Using only symmetric encryption on constrained nodes. 173 1.2. Terminology 175 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 176 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 177 document are to be interpreted as described in RFC 2119 [RFC2119]. 179 Readers are expected to be familiar with the terms and concepts 180 defined in [I-D.gerdes-ace-actors]. 182 1.2.1. Actors 184 Server (S): An endpoint that hosts and represents a CoAP resource. 186 Client (C): An endpoint that attempts to access a CoAP resource on 187 the Server. 189 Server Authorization Manager (SAM): An entity that prepares and 190 endorses authentication and authorization data for a Server. 192 Client Authorization Manager (CAM): An entity that prepares and 193 endorses authentication and authorization data for a Client. 195 Authorization Manager (AM): An entity that is either a SAM or a CAM. 197 Client Overseeing Principal (COP): The principal that is in charge 198 of the Client and controls permissions concerning authorized 199 representations of a CoAP resource. 201 Resource Overseeing Principal (ROP): The principal that is in charge 202 of the CoAP resource and controls its access permissions. 204 1.2.2. Other Terms 206 Resource: A CoAP resource. 208 Authorization information: Contains all information needed by S to 209 decide if C is privileged to access a resource in a specific way. 211 Authentication information: Contains all information needed by S to 212 decide if the entity in possession of a certain key is verified by 213 SAM. 215 Access information: Contains authentication information and, if 216 necessary, authorization information. 218 Access ticket: Contains the authentication and, if necessary, the 219 authorization information needed to access a resource. A Ticket 220 consists of the Ticket Face and the Client Information. The 221 access ticket is a representation of the access information. 223 Ticket Face: The part of the ticket which is generated for the 224 Server. It contains the authorization information and all 225 information needed by the Server to verify that it was granted by 226 SAM. 228 Client Information (CI): The part of the ticket which is generated 229 for the Client. It contains the Verifier and optionally may 230 contain authorization information that represent COP's 231 authorization policies for C. 233 Verifier: It enables the client to verify that it is communicating 234 with an appropriate S. 236 Explicit authorization: SAM informs the S in detail which privileges 237 are granted to the Client. 239 Implicit authorization: SAM authenticates the Client for the Server 240 without specifying the privileges in detail. This can be used for 241 binary or unrestricted authorization (cf section 4 of 242 [I-D.gerdes-ace-actors]). 244 2. System Overview 246 Within the DCAF Architecture each Server (S) has a Server 247 Authorization Manger (SAM) which conducts the authentication and 248 authorization for S. S and SAM share a symmetric key which has to be 249 exchanged initially to provide for a secure channel. The mechanism 250 used for this is not in the scope of this document. 252 To gain access to a specific resource on a S, a Client (C) has to 253 request an access ticket from the SAM serving S either directly or, 254 if it is a constrained device, using its Client Authorization Manager 255 (CAM). In the following, we always discuss the CAM role separately, 256 even if that is co-located within a (more powerful) C (see section 257 Section 11 for details about co-located actors). 259 CAM decides if S is an authorized source for R according to the 260 policies set by COP and in this case transmits the request to SAM. 261 If SAM decides that C is allowed to access the resource according to 262 the policies set by ROP, it generates a DTLS pre-shared key (PSK) for 263 the communication between C and S and wraps it into an access ticket. 264 For explicit access control, SAM adds the detailed access permissions 265 to the ticket in a way that CAM and S can interpret. CAM checks if 266 the permissions in the access ticket comply with COP's authorization 267 policies for C, and if this is the case sends it to C. After C 268 presented the ticket to S, C and S can communicate securely. 270 To be able to provide for the authentication and authorization 271 services, an Authorization Manager has to fulfill several 272 requirements: 274 o AM must have enough stable storage (such as disk space) to store 275 the necessary number of credentials (matching the number of 276 Clients and Servers). 278 o AM must possess means for user interaction, for example directly 279 or indirectly connected input/output devices such as keyboard and 280 display, to allow for configuration of authorization information 281 by the respective Principal. 283 o AM must have enough processing power to handle the authorization 284 requests for all constrained devices it is responsible for. 286 3. Protocol 288 The DCAF protocol comprises three parts: 290 1. transfer of authentication and, if necessary, authorization 291 information between C and S; 293 2. transfer of access requests and the respective ticket grants 294 between C and CAM; and 296 3. transfer of access requests and the respective ticket grants 297 between SAM and CAM. 299 3.1. Overview 301 In Figure 1, a DCAF protocol flow is depicted (messages in square 302 brackets are optional): 304 CAM C S SAM 305 | <== DTLS chan. ==> | | <== DTLS chan. ==> | 306 | | [Resource Req.-->] | | 307 | | | | 308 | | [<-- SAM Info.] | | 309 | | | | 310 | <-- Access Req. | | | 311 | | | | 312 | <==== TLS/DTLS channel (CAM/SAM Mutual Authentication) ====> | 313 | | | | 314 | Ticket Request ------------------------------------------> | 315 | | | | 316 | <------------------------------------------ Ticket Grant | 317 | | | | 318 | Ticket Transf. --> | | | 319 | | | | 320 | | <== DTLS chan. ==> | | 321 | | Auth. Res. Req. -> | | 323 Figure 1: Protocol Overview 325 To determine the SAM in charge of a resource hosted at the S, C MAY 326 send an initial Unauthorized Resource Request message to S. S then 327 denies the request and sends the address of its SAM back to C. 329 Instead of the initial Unauthorized Resource Request message, C MAY 330 look up the desired resource in a resource directory (cf. 331 [I-D.ietf-core-resource-directory]) that lists S's resources as 332 discussed in Section 9. 334 Once C knows SAM's address, it can send a request for authorization 335 to SAM using its own CAM. CAM and SAM authenticate each other and 336 each determine if the request is to be authorized. If it is, SAM 337 generates an access ticket for C. The ticket contains keying 338 material for the establishment of a secure channel and, if necessary, 339 a representation of the permissions C has for the resource. C keeps 340 one part of the access ticket and presents the other part to S to 341 prove its right to access. With their respective parts of the 342 ticket, C and S are able to establish a secure channel. 344 The following sections specify how CoAP is used to interchange 345 access-related data between S and SAM so that SAM can provide C and S 346 with sufficient information to establish a secure channel, and 347 simultaneously convey authorization information specific for this 348 communication relationship to S. 350 Note: Special implementation considerations apply when one single 351 entity takes the role of more than one actors. Section 11 gives 352 additional advice on some of these usage scenarios. 354 This document uses Concise Binary Object Representation (CBOR, 355 [RFC7049]) to express authorization information as set of attributes 356 passed in CoAP payloads. Notation and encoding options are discussed 357 in Section 5. A formal specification of the DCAF message format is 358 given in Appendix A. 360 3.2. Unauthorized Resource Request Message 362 The optional Unauthorized Resource Request message is a request for a 363 resource hosted by S for which no proper authorization is granted. S 364 MUST treat any CoAP request as Unauthorized Resource Request message 365 when any of the following holds: 367 o The request has been received on an insecure channel. 369 o S has no valid access ticket for the sender of the request 370 regarding the requested action on that resource. 372 o S has a valid access ticket for the sender of the request, but 373 this does not allow the requested action on the requested 374 resource. 376 Note: These conditions ensure that S can handle requests autonomously 377 once access was granted and a secure channel has been established 378 between C and S. 380 Unauthorized Resource Request messages MUST be denied with a client 381 error response. In this response, the Server MUST provide proper SAM 382 Information to enable the Client to request an access ticket from S's 383 SAM as described in Section 3.3. 385 The response code MUST be 4.01 (Unauthorized) in case the sender of 386 the Unauthorized Resource Request message is not authenticated, or if 387 S has no valid access ticket for C. If S has an access ticket for C 388 but not for the resource that C has requested, S MUST reject the 389 request with a 4.03 (Forbidden). If S has an access ticket for C but 390 it does not cover the action C requested on the resource, S MUST 391 reject the request with a 4.05 (Method Not Allowed). 393 Note: The use of the response codes 4.03 and 4.05 is intended to 394 prevent infinite loops where a dumb Client optimistically tries to 395 access a requested resource with any access token received from 396 the SAM. As malicious clients could pretend to be C to determine 397 C's privileges, these detailed response codes must be used only 398 when a certain level of security is already available which can be 399 achieved only when the Client is authenticated. 401 3.3. SAM Information Message 403 The SAM Information Message is sent by S as a response to an 404 Unauthorized Resource Request message (see Section 3.2) to point the 405 sender of the Unauthorized Resource Request message to S's SAM. The 406 SAM information is a set of attributes containing an absolute URI 407 (see Section 4.3 of [RFC3986]) that specifies the SAM in charge of S. 409 An optional field A lists the different content formats that are 410 supported by S. 412 The message MAY also contain a timestamp generated by S. 414 Figure 2 shows an example for an SAM Information message payload 415 using CBOR diagnostic notation. (Refer to Section 5 for a detailed 416 description of the available attributes and their semantics.) 418 4.01 Unauthorized 419 Content-Format: application/dcaf+cbor 420 {SAM: "coaps://sam.example.com/authorize", TS: 168537, 421 A: [ TBD1, ct_cose_msg ] } 423 Figure 2: SAM Information Payload Example 425 In this example, the attribute SAM points the receiver of this 426 message to the URI "coaps://sam.example.com/authorize" to request 427 access permissions. The originator of the SAM Information payload 428 (i.e. S) uses a local clock that is loosely synchronized with a time 429 scale common between S and SAM (e.g., wall clock time). Therefore, 430 it has included a time stamp on its own time scale that is used as a 431 nonce for replay attack prevention. Refer to Section 4.1 for more 432 details concerning the usage of time stamps to ensure freshness of 433 access tickets. 435 The content formats accepted by S are TBD1 (identifying 'application/ 436 dcaf+cbor' as defined in this document), and 'application/cose+cbor' 437 defined in [I-D.ietf-cose-msg]. 439 Editorial note: ct_cose_msg is to be replaced with the numeric value 440 assigned for 'application/cose+cbor'. 442 The examples in this document are written in CBOR diagnostic notation 443 to improve readability. Figure 3 illustrates the binary encoding of 444 the message payload shown in Figure 2. 446 a2 # map(2) 447 00 # unsigned(0) (=SAM) 448 78 21 # text(33) 449 636f6170733a2f2f73616d2e6578 450 616d706c652e636f6d2f617574686f72 451 697a65 # "coaps://sam.example.com/authorize" 452 05 # unsigned(5) (=TS) 453 1a 00029259 # unsigned(168537) 454 0a # unsigned(10) (=A) 455 82 # array(2) 456 19 03e6 # unsigned(998) (=dcaf+cbor) 457 19 03e7 # unsigned(999) (=cose+cbor) 459 Figure 3: SAM Information Payload Example encoded in CBOR 461 3.3.1. Piggybacked Protected Content 463 For some use cases (such as sleepy nodes) it might be necessary to 464 store sensor data on a server that might not belong to the same 465 security domain. A client can retrieve the data from that server. 466 To be able to achieve the security objectives of the principles the 467 data must be protected properly. 469 The server that hosts the stored data may respond to GET requests for 470 this particular resource with a SAM Information message that contains 471 the protected data as piggybacked content in addition to the URI of 472 the authorization manager that is responsible for the protected data. 474 Once a requesting client has received the SAM Information Message 475 with piggybacked content, it needs to request authorization for 476 accessing the protected data. To do so, it constructs an Access 477 Request as defined in Section 3.4. If access to the protected data 478 is granted, the requesting client will be provided with cryptographic 479 material to verify the integrity and authenticity of the piggybacked 480 content and decrypt the protected data in case it is encrypted. 482 3.4. Access Request 484 To retrieve an access ticket for the resource that C wants to access, 485 C sends an Access Request to its CAM. The Access Request is 486 constructed as follows: 488 1. The request method is POST. 490 2. The request URI is set as described below. 492 3. The message payload contains a data structure that describes the 493 action and resource for which C requests an access ticket. 495 The request URI identifies a resource at CAM for handling 496 authorization requests from C. The URI SHOULD be announced by CAM in 497 its resource directory as described in Section 9. 499 Note: Where capacity limitations of C do not allow for resource 500 directory lookups, the request URI in Access Requests could be 501 hard-coded during provisioning or set in a specific device 502 configuration profile. 504 The message payload is constructed from the SAM information that S 505 has returned in its SAM Information message (see Section 3.3) and 506 information that C provides to describe its intended request(s). The 507 Access Request MUST contain the following attributes: 509 1. Contact information for the SAM to use. 511 2. An absolute URI of the resource that C wants to access. 513 3. The actions that C wants to perform on the resource. 515 4. Any time stamp generated by S. 517 An example Access Request from C to CAM is depicted in Figure 4. 518 (Refer to Section 5 for a detailed description of the available 519 attributes and their semantics.) 520 POST client-authorize 521 Content-Format: application/dcaf+cbor 522 { 523 SAM: "coaps://sam.example.com/authorize", 524 SAI: ["coaps://temp451.example.com/s/tempC", 5], 525 TS: 168537 526 } 528 Figure 4: Access Request Message Example 530 The example shows an Access Request message payload for the resource 531 "/s/tempC" on the Server "temp451.example.com". Requested operations 532 in attribute SAI are GET and PUT. 534 The attributes SAM (that denotes the Server Authorization Manager to 535 use) and TS (a nonce generated by S) are taken from the SAM 536 Information message from S. 538 The response to an Authorization Request is delivered by CAM back to 539 C in a Ticket Transfer message. 541 3.5. Ticket Request Message 543 When CAM receives an Access Request message from C and COP specified 544 authorization policies for C, CAM MUST check if the requested actions 545 are allowed according to these policies. If this is not the case, 546 CAM MUST send a 4.03 response. 548 If no authorization policies were specified or the requested action 549 is allowed according to the authorization policies, CAM either 550 returns a cached response or attempts to create a Ticket Request 551 message. 553 CAM MAY return a cached response if it is known to be fresh according 554 to Max-Age. CAM SHOULD NOT return a cached response if it expires in 555 less than a minute. 557 If CAM does not send a cached response, it checks whether the request 558 payload is of type "application/dcaf+cbor and contains at least the 559 fields SAM and SAI. CAM MUST respond with 4.00 (Bad Request) if the 560 type is "application/dcaf+cbor and any of these fields is missing or 561 does not conform to the format described in Section 5. Content 562 formats other than application/dcaf+cbor are out of scope of this 563 specification. 565 If the payload is correct, CAM creates a Ticket Request message from 566 the Access Request received from C as follows: 568 1. The destination of the Ticket Request message is derived from the 569 authority information in the URI contained in field "SAM" of the 570 Access Request message payload. 572 2. The request method is POST. 574 3. The request URI is constructed from the SAM field received in the 575 Access Request message payload. 577 4. The payload is copied from the Access Request sent by C. 579 5. A label that describes the Client is added to the payload 581 To send the Ticket Request message to SAM a secure channel between 582 CAM and SAM MUST be used. Depending on the URI scheme used in the 583 SAM field of the Access Request message payload (the less-constrained 584 devices CAM and SAM do not necessarily use CoAP to communicate with 585 each other), this could be, e.g., a DTLS channel (for "coaps") or a 586 TLS connection (for "https"). CAM and SAM MUST be able to mutually 587 authenticate each other, e.g. based on a public key infrastructure. 588 (Refer to Section 8 for a detailed discussion of the trust 589 relationship between Client Authorization Managers and Server 590 Authorization Managers.) 592 3.6. Ticket Grant Message 594 When SAM has received a Ticket Request message it has to evaluate the 595 access request information contained therein. First, it checks 596 whether the request payload is of type "application/dcaf+cbor" and 597 contains at least the fields SAM and SAI. SAM MUST respond with 4.00 598 (Bad Request) for CoAP (or 400 for HTTP) if the type is "application/ 599 dcaf+cbor" and any of these fields is missing or does not conform to 600 the format described in Section 5. 602 SAM decides whether or not access is granted to the requested 603 resource and then creates a Ticket Grant message that reflects the 604 result. To grant access to the requested resource, SAM creates an 605 access ticket comprised of a Face and the Client Information as 606 described in Section 4.1. 608 The Ticket Grant message then is constructed as a success response 609 indicating attached content, i.e. 2.05 for CoAP, or 200 for HTTP, 610 respectively. The payload of the Ticket Grant message is a data 611 structure that contains the result of the access request. When 612 access is granted, the data structure contains the Ticket Face, the 613 Client Information, which at this point only consists of the Verifier 614 and the Session Key Generation Method. 616 The Ticket Grant message MAY provide cache-control options to enable 617 intermediaries to cache the response. The message MAY be cached 618 according to the rules defined in [RFC7252] to facilitate ticket 619 retrieval when C has crashed and wants to recover the DTLS session 620 with S. 622 SAM SHOULD set Max-Age according to the ticket lifetime in its 623 response (Ticket Grant Message). 625 Figure 5 shows an example Ticket Grant message using CoAP. The Face/ 626 Verifier information is transferred as a CBOR data structure as 627 specified in Section 5. The Max-Age option tells the receiving CAM 628 how long this ticket will be valid. 630 2.05 Content 631 Content-Format: application/dcaf+cbor 632 Max-Age: 86400 633 { F: { 634 SAI: [ "/s/tempC", 7 ], 635 TS: 0("2013-07-10T10:04:12.391"), 636 L: 86400, 637 G: hmac_sha256 638 }, 639 V: h'f89947160c73601c7a65cb5e08812026 640 6d0f0565160e3ff7d3907441cdf44cc9' 641 } 643 Figure 5: Example Ticket Grant Message 645 A Ticket Grant message that declines any operation on the requested 646 resource is illustrated in Figure 6. As no ticket needs to be 647 issued, an empty payload is included with the response. 649 2.05 Content 650 Content-Format: application/dcaf+cbor 652 Figure 6: Example Ticket Grant Message With Reject 654 3.7. Ticket Transfer Message 656 A Ticket Transfer message delivers the access information sent by SAM 657 in a Ticket Grant message to the requesting client C. The Ticket 658 Transfer message is the response to the Access Request message sent 659 from C to CAM and includes any access information from SAM contained 660 in the Ticket Grant message. 662 The Authorization Information provided by SAM in the Ticket Grant 663 Message may grant more permissions than C has requested. The 664 authorization policies of COP and ROP may differ: COP might want 665 restrict the resources C is allowed to access, and the actions that C 666 is allowed to perform on the resource. 668 If CAM must ensure authorization policies COP configured , CAM MUST 669 add Authorization Information for C (CAI) to the CI. Since C and CAM 670 use a DTLS channel for communication, the autorization information 671 does not need to be encrypted. 673 CAM includes the Face and Verifier sent by SAM in the Ticket Transfer 674 message. CAM MUST NOT include any other information SAM provided. 675 In particular, CAM MUST NOT include any CAI information provided by 676 SAM. 678 Figure 7 shows an example Ticket Transfer message that conveys the 679 permissions for actions GET, POST, PUT (but not DELETE) on the 680 resource "/s/tempC" in field SAI. As CAM only wants to permit 681 outbound GET requests, it restricts C's permissions in the field CAI 682 accordingly. 684 2.05 Content 685 Content-Format: application/dcaf+cbor 686 Max-Age: 86400 687 { F: { 688 SAI: [ "/s/tempC", 7 ], 689 TS: 0("2013-07-10T10:04:12.391"), 690 L: 86400, 691 G: hmac_sha256 692 }, 693 V: h'f89947160c73601c7a65cb5e08812026 694 6d0f0565160e3ff7d3907441cdf44cc9' 695 CAI: [ "/s/tempC", 1 ], 696 TS: 0("2013-07-10T10:04:12.855"), 697 L: 86400 698 } 700 Figure 7: Example Ticket Transfer Message 702 3.8. DTLS Channel Setup Between C and S 704 Using the information contained in a positive response to its Access 705 Request (i.e. a Ticket Transfer message that contains a Face and a 706 Client Information), C can initiate establishment of a new DTLS 707 channel with S. To use DTLS with pre-shared keys, C follows the PSK 708 key exchange algorithm specified in Section 2 of [RFC4279], with the 709 following additional requirements: 711 1. C sets the psk_identity field of the ClientKeyExchange message to 712 the ticket Face received in the Ticket Transfer message. 714 2. C uses the ticket Verifier as PSK when constructing the premaster 715 secret. 717 Note1: As S cannot provide C with a meaningful PSK identity hint in 718 response to C's ClientHello message, S SHOULD NOT send a 719 ServerKeyExchange message. 721 Note2: According to [RFC7252], CoAP implementations MUST support the 722 ciphersuite TLS_PSK_WITH_AES_128_CCM_8 [RFC6655]. C is therefore 723 expected to offer at least this ciphersuite to S. 725 Note3: The ticket is constructed by SAM such that S can derive the 726 authorization information as well as the PSK (refer to Section 6 for 727 details). 729 3.9. Authorized Resource Request Message 731 If the Client Information in the Ticket Transfer message contains 732 CAI, C MUST ensure that it only sends requests that according to them 733 are allowed. C therefore MUST check CAI, L and T before every 734 request. If CAI is no longer valid according to L, C MUST terminate 735 the DTLS connection with S and re-request the CAI from CAM using an 736 Access Request Message. 738 On the Server side, successful establishment of the DTLS channel 739 between C and S ties the SAM authorization information contained in 740 the psk_identity field to this channel. Any request that S receives 741 on this channel is checked against these authorization rules. 742 Incoming CoAP requests that are not Authorized Resource Requests MUST 743 be rejected by S with 4.01 response as described in Section 3.2. 745 S SHOULD treat an incoming CoAP request as Authorized Resource 746 Request if the following holds: 748 1. The message was received on a secure channel that has been 749 established using the procedure defined in Section 3.8. 751 2. The authorization information tied to the secure channel is 752 valid. 754 3. The request is destined for S. 756 4. The resource URI specified in the request is covered by the 757 authorization information. 759 5. The request method is an authorized action on the resource with 760 respect to the authorization information. 762 Note that the authorization information is not restricted to a single 763 resource URI. For example, role-based authorization can be used to 764 authorize a collection of semantically connected resources 765 simultaneously. Implicit authorization also provides access rights 766 to authenticated clients for all actions on all resources that S 767 offers. As a result, C can use the same DTLS channel not only for 768 subsequent requests for the same resource (e.g. for block-wise 769 transfer as defined in [I-D.ietf-core-block] or refreshing observe- 770 relationships [I-D.ietf-core-observe]) but also for requests to 771 distinct resources. 773 Incoming CoAP requests received on a secure channel according to the 774 procedure defined in Section 3.8 MUST be rejected 776 1. with response code 4.03 (Forbidden) when the resource URI 777 specified in the request is not covered by the authorization 778 information, and 780 2. with response code 4.05 (Method Not Allowed) when the resource 781 URI specified in the request covered by the authorization 782 information but not the requested action. 784 Since SAM may limit the set of requested actions in its Ticket Grant 785 message, C cannot know a priori if an Authorized Resource Request 786 will succeed. 788 3.10. Dynamic Update of Authorization Information 790 Once a security association exists between a Client and a Resource 791 Server, the Client can update the Authorization Information stored at 792 the Server at any time. To do so, the Client creates a new Access 793 Request for the intended action on the respective resource and sends 794 this request to its CAM which checks and relays this request to the 795 Server's SAM as described in Section 3.4. 797 Note: Requesting a new Access Ticket also can be a Client's reaction 798 on a 4.03 or 4.05 error that it has received in response to an 799 Authorized Resource Request. 801 Figure 8 depicts the message flow where C requests a new Access 802 Tickets after a security association between C and S has been 803 established using this protocol. 805 CAM C S SAM 806 | <== DTLS chan. ==> | <== DTLS chan. ==> | <== DTLS chan. ==> | 807 | | | | 808 | | [Unauth. R. Req->] | | 809 | |[<- 4.0x+SAM Info.] | | 810 | | | | 811 | <-- Access Req. | | | 812 | | | | 813 | <==== TLS/DTLS channel (CAM/SAM Mutual Authentication) ====> | 814 | | | | 815 | Ticket Request ------------------------------------------> | 816 | | | | 817 | <------------------------------------------ Ticket Grant | 818 | | | | 819 | Ticket Transf. --> | | | 820 | | | | 821 | | <== Update SAI ==> | | 823 Figure 8: Overview of Dynamic Update Operation 825 Processing the Ticket Request is done at the SAM as specified in 826 Section 3.6, i.e. the SAM checks whether or not the requested 827 operation is permitted by the Resource Principal's policy, and then 828 return a Ticket Grant message with the result of this check. If 829 access is granted, the Ticket Grant message contains an Access Ticket 830 comprised of a public Ticket Face and a private Ticket Verifier. 831 This authorization payload is relayed by CAM to the Client in a 832 Ticket Transfer Message as defined in Section 3.7. 834 The major difference between dynamic update of Authorization 835 Information and the initial handshake is the handling of a Ticket 836 Transfer message by the Client that is described in Section 3.10.1. 838 3.10.1. Handling of Ticket Transfer Messages 840 If the security association with S still exists and S has indicated 841 support for session renegotiation according to [RFC5746], the ticket 842 Face SHOULD be used to renegotiate the existing DTLS session. In 843 this case, the ticket Face is used as psk_identity as defined in 844 Section 3.8. Otherwise, the Client MUST perform a new DTLS handshake 845 according to Section 3.8 that replaces the existing DTLS session. 847 After successful completion of the DTLS handshake S updates the 848 existing SAM Authorization Information for C according to the 849 contents of the ticket Face. 851 Note: No mutual authentication between C and S is required for 852 dynamic updates when a DTLS channel exists that has been 853 established as defined in Section 3.8. S only needs to verify the 854 authenticity and integrity of the ticket Face issued by SAM which 855 is achieved by having performed a successful DTLS handshake with 856 the ticket Face as psk_identity. This could even be done within 857 the existing DTLS session by tunneling a CoDTLS 858 [I-D.schmertmann-dice-codtls] handshake. 860 4. Ticket 862 Access tokens in DCAF are tickets that consist of two parts, namely 863 the Face and the Client Information. The Face goes to S, the CI goes 864 to the Client. The Face and the CI are parts of the same ticket. 866 S only needs the information contained in the Ticket Face to 867 authorize the client and make sure that SAM generated the Ticket Face 868 (S cannot make authorization decisions by itself and hence needs SAM 869 to do it). No additional information about the Client is needed. S 870 keeps the Ticket Face as long as it is valid. 872 4.1. Face 874 Face is the part of the ticket generated for S. Face MUST contain 875 all information needed for authorized access to a resource: 877 o SAM Authorization Information 879 o A timestamp generated by SAM 881 Optionally, Face MAY also contain: 883 o A lifetime (optional) 885 o A DTLS pre-shared key (optional) 887 S MUST verify the integrity of Face, i.e. the information contained 888 in Face stems from SAM and was not manipulated by anyone else. 890 Face MUST contain a timestamp to verify that the contained 891 information is fresh. As constrained devices may not have a clock, 892 timestamps MAY be generated using the clock ticks since the last 893 reboot. To circumvent synchronization problems the timestamp MAY be 894 generated by S and included in the first SAM Information message. 895 Alternatively, SAM MAY generate the timestamp. In this case, SAM and 896 S MUST use a time synchronization mechanism to make sure that S 897 interprets the timestamp correctly. 899 Face MAY be encrypted. If Face contains a DTLS PSK, the whole 900 content of Face MUST be encrypted. 902 The integrity of Face can be ensured by various means. Face may be 903 encrypted by SAM with a key it shares with S. Alternatively, S can 904 use a mechanism to generate the DTLS PSK which includes Face. S 905 generates the key from the Face it received. The correct key can 906 only be calculated with the correct Face (refer to Section 6 for 907 details). 909 4.2. Client Information 911 The CI part of the ticket is generated for C. It contains the 912 Verifier, i.e. the DTLS PSK for C and MAY contain Client 913 Authorization Information generated by CAM to provide the COP's 914 authorization policies to C. The Verifier MUST NOT be transmitted 915 over insecure channels. 917 4.3. Revocation 919 The existence of access tickets SHOULD be limited in time to avoid 920 stale tickets that waste resources on S and C. This can be achieved 921 either by explicit Revocation Messages to invalidate a ticket or 922 implicitly by attaching a lifetime to the ticket. 924 4.3.1. Lifetime 926 Tickets MAY have a lifetime. SAM is responsible for defining the 927 ticket lifetime. If SAM sets a lifetime for a ticket, SAM and S MUST 928 use a time synchronization method to ensure that S is able to 929 interpret the lifetime correctly. S SHOULD end the DTLS connection 930 to C if the lifetime of a ticket has run out and it MUST NOT accept 931 new requests. S MUST NOT accept tickets with an invalid lifetime. 933 If CAM provides CAI in the CI part of the ticket, CAM MAY add a 934 lifetime for this CAI. If CI contains a lifetime, CAM and C MUST use 935 a time synchronization method to ensure that C is able to interpret 936 the lifetime correctly. C SHOULD end the DTLS connection to S and 937 MUST NOT send new requests if the CAI in the ticket is no longer 938 valid. C MUST NOT accept tickets with an invalid lifetime. 940 Note: Defining reasonable ticket lifetimes is difficult to 941 accomplish. How long a client needs to access a resource depends 942 heavily on the application scenario and may be difficult to decide 943 for SAM. 945 4.3.2. Revocation Messages 947 SAM MAY revoke tickets by sending a ticket revocation message to S. 948 If S receives a ticket revocation message, it MUST end the DTLS 949 connection to C and MUST NOT accept any further requests from C. 951 If ticket revocation messages are used, S MUST check regularly if SAM 952 is still available. If S cannot contact SAM, it MUST end all DTLS 953 connections and reject any further requests from C. 955 Note: The loss of the connection between S and SAM prevents all 956 access to S. This might especially be a severe problem if SAM is 957 responsible for several Servers or even a whole network. 959 5. Payload Format and Encoding (application/dcaf+cbor) 961 Various messages types of the DCAF protocol carry payloads to express 962 authorization information and parameters for generating the DTLS PSK 963 to be used by C and S. In this section, a representation in Concise 964 Binary Object Representation (CBOR, [RFC7049]) is defined. 966 DCAF data structures are defined as CBOR maps that contain key value 967 pairs. For efficient encoding, the keys defined in this document are 968 represented as unsigned integers in CBOR, i. e. major type 0. For 969 improved reading, we use symbolic identifiers to represent the 970 corresponding encoded values as defined in Table 1. 972 +---------------+-----+ 973 | Encoded Value | Key | 974 +---------------+-----+ 975 | 0 | SAM | 976 | | | 977 | 1 | SAI | 978 | | | 979 | 2 | CAI | 980 | | | 981 | 3 | E | 982 | | | 983 | 4 | K | 984 | | | 985 | 5 | TS | 986 | | | 987 | 6 | L | 988 | | | 989 | 7 | G | 990 | | | 991 | 8 | F | 992 | | | 993 | 9 | V | 994 | | | 995 | 10 | A | 996 | | | 997 | 11 | D | 998 | | | 999 | 12 | N | 1000 +---------------+-----+ 1002 Table 1: DCAF field identifiers encoded in CBOR 1004 The following list describes the semantics of the keys defined in 1005 DCAF. 1007 SAM: Server Authorization Manager. This attribute denotes the 1008 Server Authorization Manager that is in charge of the resource 1009 specified in attribute R. The attribute's value is a string that 1010 contains an absolute URI according to Section 4.3 of [RFC3986]. 1012 SAI: SAM Authorization Information. A data structure used to convey 1013 authorization information from SAM to S. It describes C's 1014 permissions for S according to SAM, e.g., which actions C is 1015 allowed to perform on an R of S. The SAI attribute contains an 1016 AIF object as defined in [I-D.bormann-core-ace-aif]. C uses SAI 1017 for its Access Request messages. 1019 CAI: CAM Authorization Information. A data structure used to convey 1020 authorization information from CAM to C. It describes the C's 1021 permissions for S according to CAM, e.g., which actions C is 1022 allowed to perform on an R of S. The CAI attribute contains an 1023 AIF object as defined in [I-D.bormann-core-ace-aif]. 1025 A: Accepted content formats. An array of numeric content formats 1026 from the CoAP Content-Formats registry (c.f. Section 12.3 of 1027 [RFC7252]. 1029 D: Protected Data. A binary string containing data that may be 1030 encrypted. 1032 E: Encrypted Ticket Face. A binary string containing an encrypted 1033 ticket Face. 1035 K: Key. A string that identifies the shared key between S and SAM 1036 that can be used to decrypt the contents of E. If the attribute E 1037 is present and no attribute K has been specified, the default is 1038 to use the current session key for the secured channel between S 1039 and SAM. 1041 TS: Time Stamp. An optional time stamp that indicates the instant 1042 when the access ticket request was formed. This attribute can be 1043 used by the Server in an SAM Information message to convey a time 1044 stamp in its local time scale (e.g. when it does not have a real 1045 time clock with synchronized global time). When the attribute's 1046 value is encoded as a string, it MUST contain a valid UTC 1047 timestamp without time zone information. When encoded as integer, 1048 TS contains a system timestamp relative to the local time scale of 1049 its generator, usually S. 1051 L: Lifetime. When in included in a ticket face, the contents of the 1052 L parameter denote the lifetime of the ticket. In combination 1053 with the protected data field D, this parameter denotes the 1054 lifetime of the protected data. When encoded as a string, L MUST 1055 denote the ticket's expiry time as a valid UTC timestamp without 1056 time zone information. When encoded as an integer, L MUST denote 1057 the ticket's validity period in seconds relative to TS. 1059 N: Nonce. An initialization vector used in combination with 1060 piggybacked protected content. 1062 G: DTLS PSK Generation Method. A numeric identifier for the method 1063 that S MUST use to derive the DTLS PSK from the ticket Face. This 1064 attribute MUST NOT be used when attribute V is present within the 1065 contents of F. This specification uses symbolic identifiers for 1066 improved readability. The corresponding numeric values encoded in 1067 CBOR are defined in Table 2. A registry for these codes is 1068 defined in Section 13.1. 1070 F: Ticket Face. An object containing the fields SAI, TS, and 1071 optionally G, L and V. 1073 V: Ticket Verifier. A binary string containing the shared secret 1074 between C and S. 1076 +---------------+-------------+-----------+ 1077 | Encoded Value | Mnemonic | Support | 1078 +---------------+-------------+-----------+ 1079 | 0 | hmac_sha256 | mandatory | 1080 | | | | 1081 | 1 | hmac_sha384 | optional | 1082 | | | | 1083 | 2 | hmac_sha512 | optional | 1084 +---------------+-------------+-----------+ 1086 Table 2: CBOR encoding for DTLS PSK Key Generation Methods 1088 5.1. Examples 1090 The following example specifies a SAM that will be accessed using 1091 HTTP over TLS. The request URI is set to 1092 "/a?ep=%5B2001:DB8::dcaf:1234%5D" (hence denoting the endpoint 1093 address to authorize). TS denotes a local timestamp in UTC. 1095 POST /a?ep=%5B2001:DB8::dcaf:1234%5D HTTP/1.1 1096 Host: sam.example.com 1097 Content-Type: application/dcaf+cbor 1098 {SAM: "https://sam.example.com/a?ep=%5B2001:DB8::dcaf:1234%5D", 1099 SAI: ["coaps://temp451.example.com/s/tempC", 1], 1100 TS: 0("2013-07-14T11:58:22.923")} 1102 The following example shows a ticket for the distributed key 1103 generation method (cf. Section 6.2), comprised of a Face (F) and a 1104 Verifier (V). The Face data structure contains authorization 1105 information SAI, a client descriptor, a timestamp using the local 1106 time scale of S, and a lifetime relative to S's time scale. 1108 The DTLS PSK Generation Method is set to hmac_sha256 denoting that 1109 the distributed key derivation is used as defined in Section 6.2 with 1110 SHA-256 as HMAC function. 1112 The Verifier V contains a shared secret to be used as DTLS PSK 1113 between C and S. 1115 HTTP/1.1 200 OK 1116 Content-Type: application/dcaf+cbor 1117 { 1118 F: { 1119 SAI: [ "/s/tempC", 1 ], 1120 TS: 2938749, 1121 L: 3600, 1122 G: hmac_sha256 1123 }, 1124 V: h'48ae5a81b87241d81618f56cab0b65ec 1125 441202f81faabbe10075b20cb57fa939' 1126 } 1128 The Face may be encrypted as illustrated in the following example. 1129 Here, the field E carries an encrypted Face data structure that 1130 contains the same information as the previous example, and an 1131 additional Verifier. Encryption was done with a secret shared by SAM 1132 and S. (This example uses AES128_CCM with the secret { 0x00, 0x01, 1133 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08, 0x09, 0x0a, 0x0b, 0x0c, 1134 0x0d, 0x0e, 0x0f } and S's timestamp { 0x00, 0x2C, 0xD7, 0x7D } as 1135 nonce.) Line breaks have been inserted to improve readability. 1137 The attribute K describes the identity of the key to be used by S to 1138 decrypt the contents of attribute E. Here, The value "key0" in this 1139 example is used to indicate that the shared session key between S and 1140 SAM was used for encrypting E. 1142 { 1143 E: h'2e75eeae01b831e0b65c2976e06d90f4 1144 82135bec5efef3be3d31520b2fa8c6fb 1145 f572f817203bf7a0940bb6183697567c 1146 e291b03e9fca5e9cbdfa7e560322d4ed 1147 3a659f44a542e55331a1a9f43d7f', 1148 K: "key0", 1149 V: h'48ae5a81b87241d81618f56cab0b65ec 1150 441202f81faabbe10075b20cb57fa939' 1151 } 1153 The decrypted contents of E are depicted below (whitespace has been 1154 added to improve readability). The presence of the attribute V 1155 indicates that the DTLS PSK Transfer is used to convey the session 1156 key (cf. Section 6.1). 1158 { 1159 F: { 1160 SAI: [ "/s/tempC", 1 ], 1161 TS: 2938749, 1162 L: 3600, 1163 G: hmac_sha256 1164 }, 1165 V: h'48ae5a81b87241d81618f56cab0b65ec 1166 441202f81faabbe10075b20cb57fa939' 1167 } 1169 6. DTLS PSK Generation Methods 1171 One goal of the DCAF protocol is to provide for a DTLS PSK shared 1172 between C and S. SAM and S MUST negotiate the method for the DTLS 1173 PSK generation. 1175 6.1. DTLS PSK Transfer 1177 The DTLS PSK is generated by AS and transmitted to C and S using a 1178 secure channel. 1180 The DTLS PSK transfer method is defined as follows: 1182 o SAM generates the DTLS PSK using an algorithm of its choice 1184 o SAM MUST include a representation of the DTLS PSK in Face and 1185 encrypt it together with all other information in Face with a key 1186 K(SAM,S) it shares with S. How SAM and S exchange K(SAM,S) is not 1187 in the scope of this document. SAM and S MAY use their preshared 1188 key as K(SAM,S). 1190 o SAM MUST include a representation of the DTLS PSK in the Verifier. 1192 o As SAM and C do not have a shared secret, the Verifier MUST be 1193 transmitted to C using encrypted channels. 1195 o S MUST decrypt Face using K(SAM,S) 1197 6.2. Distributed Key Derivation 1199 SAM generates a DTLS PSK for C which is transmitted using a secure 1200 channel. S generates its own version of the DTLS PSK using the 1201 information contained in Face (see also Section 4.1). 1203 The distributed key derivation method is defined as follows: 1205 o SAM and S both generate the DTLS PSK using the information 1206 included in Face. They use an HMAC algorithm on Face with a 1207 shared key K(SAM,S). The result serves as the DTLS PSK. How SAM 1208 and S exchange K(SAM,S) is not in the scope of this document. 1209 They MAY use their preshared key as K(SAM,S). How SAM and S 1210 negotiate the used HMAC algorithm is also not in the scope of this 1211 document. They MAY however use the HMAC algorithm they use for 1212 their DTLS connection. 1214 o SAM MUST include a representation of the DTLS PSK in the Verifier. 1216 o As SAM and C do not have a shared secret, the Verifier MUST be 1217 transmitted to C using encrypted channels. 1219 o SAM MUST NOT include a representation of the DTLS PSK in Face. 1221 o SAM MUST NOT encrypt Face. 1223 7. Authorization Configuration 1225 For the protocol defined in this document, proper configuration of 1226 CAM and SAM is crucial. The principals that are in charge of the 1227 resource, S and SAM, and the principals that are in charge of C and 1228 CAM need to define the respective permissions. The data 1229 representation of these permissions are not in the scope of this 1230 document. 1232 8. Trust Relationships 1234 C has a trust relationship with CAM: C trusts CAM to act in behalf of 1235 C's principal. S has a trust relationship with SAM: S trusts SAM to 1236 act in behalf of S's principal. 1238 Obviously, CAM trusts C with the specific permissions it hands over 1239 to it. How this trust is established, is not in the scope of this 1240 document. It may be achieved by using a bootstrapping mechanism 1241 similar to [bergmann12]. 1243 Additionally, SAM and CAM need to have a trust relationship 1244 established. Its establishment is also not in the scope of this 1245 document. It fulfills the following conditions: 1247 1. SAM has means to authenticate CAM (e.g. it has a certificate of 1248 CAM or a PKI in which CAM is included) and vice versa 1250 2. As far as SAM needs to rely on the different clients of CAM to 1251 receive different permissions, it can be sure that CAM correctly 1252 identifies these clients towards SAM and does not leak tickets 1253 that have been generated for a specific client C to another 1254 client. 1256 SAM trusts C indirectly because it trusts CAM and CAM vouches for C. 1257 The DCAF Protocol does not provide any means for SAM to validate that 1258 a resource request stems from C. 1260 C indirectly trusts SAM with some potentially confidential 1261 information, and that SAM correctly represents S, because CAM trusts 1262 SAM. 1264 CAM trusts S indirectly because it trusts SAM and SAM vouches for S. 1266 C implicitly trusts S with some potentially confidential information 1267 because it trusts CAM and because S can prove that it shares a key 1268 with SAM. 1270 CAM <------------------> SAM 1272 /|\ /|\ 1273 | | 1274 \|/ \|/ 1276 C ..................... S 1278 9. Listing Authorization Manager Information in a Resource Directory 1280 CoAP utilizes the Web Linking format [RFC5988] to facilitate 1281 discovery of services in an M2M environment. [RFC6690] defines 1282 specific link parameters that can be used to describe resources to be 1283 listed in a resource directory [I-D.ietf-core-resource-directory]. 1285 9.1. The "auth-request" Link Relation 1287 This section defines a resource type "auth-request" that can be used 1288 by clients to retrieve the request URI for a server's authorization 1289 service. When used with the parameter rt in a web link, "auth- 1290 request" indicates that the corresponding target URI can be used in a 1291 POST message to request authorization for the resource and action 1292 that are described in the request payload. 1294 The Content-Format "application/dcaf+cbor with numeric identifier 1295 TBD1 defined in this specification MAY be used to express access 1296 requests and their responses. 1298 The following example shows the web link used by CAM in this document 1299 to relay incoming Authorization Request messages to SAM. (Whitespace 1300 is included only for readability.) 1302 ;rt="auth-request";ct=TBD1 1303 ;title="Contact Remote Authorization Manager" 1305 The resource directory that hosts the resource descriptions of S 1306 could list the following description. In this example, the URI 1307 "ep/node138/a/switch2941" is relative to the resource context 1308 "coaps://sam.example.com/", i.e. the Server Authorization Manager 1309 SAM. 1311 ;rt="auth-request";ct=TBD1;ep="node138" 1312 ;title="Request Client Authorization" 1313 ;anchor="coaps://sam.example.com/" 1315 10. Examples 1317 This section gives a number of short examples with message flows for 1318 the initial Unauthorized Resource Request and the subsequent 1319 retrieval of a ticket from SAM. The notation here follows the actors 1320 conventions defined in Section 1.2.1. The payload format is encoded 1321 as proposed in Section 5. The IP address of SAM is 2001:DB8::1, the 1322 IP address of S is 2001:DB8::dcaf:1234, and C's IP address is 1323 2001:DB8::c. 1325 10.1. Access Granted 1327 This example shows an Unauthorized PUT request from C to S that is 1328 answered with a SAM Information message. C then sends a POST request 1329 to CAM with a description of its intended request. CAM forwards this 1330 request to SAM using CoAP over a DTLS-secured channel. The response 1331 from SAM contains an access ticket that is relayed back to CAM. 1333 C --> S 1334 PUT a/switch2941 [Mid=1234] 1335 Content-Format: application/senml+json 1336 {"e": [{"bv": "1"}]} 1338 C <-- S 1339 4.01 Unauthorized [Mid=1234] 1340 Content-Format: application/dcaf+cbor 1341 {SAM: "coaps://[2001:DB8::1]/ep/node138/a/switch2941"} 1343 C --> CAM 1344 POST client-authorize [Mid=1235,Token="tok"] 1345 Content-Format: application/dcaf+cbor 1346 { 1347 SAM: "coaps://[2001:DB8::1]/ep/node138/a/switch2941", 1348 SAI: ["coaps://[2001:DB8::dcaf:1234]/a/switch2941", 4] 1349 } 1351 CAM --> SAM [Mid=23146] 1352 POST ep/node138/a/switch2941 1353 Content-Format: application/dcaf+cbor 1354 { 1355 SAM: "coaps://[2001:DB8::1]/ep/node138/a/switch2941", 1356 SAI: ["coaps://[2001:DB8::dcaf:1234]/a/switch2941", 4] 1357 } 1359 CAM <-- SAM 1360 2.05 Content [Mid=23146] 1361 Content-Format: application/dcaf+cbor 1362 { F: { 1363 SAI: ["a/switch2941", 5], 1364 TS: 0("2013-07-04T20:17:38.002"), 1365 G: hmac_sha256 1366 }, 1367 V: h'7ba4d9e287c8b69dd52fd3498fb8d26d 1368 9503611917b014ee6ec2a570d857987a' 1369 } 1371 C <-- CAM 1372 2.05 Content [Mid=1235,Token="tok"] 1373 Content-Format: application/dcaf+cbor 1374 { F: { 1375 SAI: ["a/switch2941", 5], 1376 TS: 0("2013-07-04T20:17:38.002"), 1377 G: hmac_sha256 1378 }, 1379 V: h'7ba4d9e287c8b69dd52fd3498fb8d26d 1380 9503611917b014ee6ec2a570d857987a' 1381 } 1383 C --> S 1384 ClientHello (TLS_PSK_WITH_AES_128_CCM_8) 1386 C <-- S 1387 ServerHello (TLS_PSK_WITH_AES_128_CCM_8) 1388 ServerHelloDone 1390 C --> S 1391 ClientKeyExchange 1392 psk_identity=0xa301826c612f73776974636832393431 1393 0x0505c077323031332d30372d30345432 1394 0x303a31373a33382e3030320700 1396 (C decodes the contents of V and uses the result as PSK) 1397 ChangeCipherSpec 1398 Finished 1400 (S calculates PSK from SAI, TS and its session key 1401 HMAC_sha256(0xa301826c612f73776974636832393431 1402 0x0505c077323031332d30372d30345432 1403 0x303a31373a33382e3030320700, 1404 0x736563726574) 1405 = 0x7ba4d9e287c8... 1406 ) 1408 C <-- S 1409 ChangeCipherSpec 1410 Finished 1412 10.2. Access Denied 1414 This example shows a denied Authorization request for the DELETE 1415 operation. 1417 C --> S 1418 DELETE a/switch2941 1420 C <-- S 1421 4.01 Unauthorized 1422 Content-Format: application/dcaf+cbor 1423 {SAM: "coaps://[2001:DB8::1]/ep/node138/a/switch2941"} 1425 C --> CAM 1426 POST client-authorize 1427 Content-Format: application/dcaf+cbor 1428 { 1429 SAM: "coaps://[2001:DB8::1]/ep/node138/a/switch2941", 1430 SAI: ["coaps://[2001:DB8::dcaf:1234]/a/switch2941", 8] 1431 } 1433 CAM --> SAM 1434 POST ep/node138/a/switch2941 1435 Content-Format: application/dcaf+cbor 1436 { 1437 SAM: "coaps://[2001:DB8::1]/ep/node138/a/switch2941", 1438 SAI: ["coaps://[2001:DB8::dcaf:1234]/a/switch2941", 8] 1439 } 1441 CAM <-- SAM 1442 2.05 Content 1443 Content-Format: application/dcaf+cbor 1445 C <-- CAM 1446 2.05 Content 1447 Content-Format: application/dcaf+cbor 1449 10.3. Access Restricted 1451 This example shows a denied Authorization request for the operations 1452 GET, PUT, and DELETE. SAM grants access for PUT only. 1454 CAM --> SAM 1455 POST ep/node138/a/switch2941 1456 Content-Format: application/dcaf+cbor 1457 { 1458 SAM: "coaps://[2001:DB8::1]/ep/node138/a/switch2941", 1459 SAI: ["coaps://[2001:DB8::dcaf:1234]/a/switch2941", 13] 1460 } 1462 CAM <-- SAM 1463 2.05 Content 1464 Content-Format: application/dcaf+cbor 1465 { F: { 1466 SAI: ["a/switch2941", 5], 1467 TS: 0("2013-07-04T21:33:11.930"), 1468 G: hmac_sha256 1469 }, 1470 V: h'c7b5774f2ddcbd548f4ad74b30a1b2e5 1471 b6b04e66a9995edd2545e5a06216c53d' 1472 } 1474 10.4. Implicit Authorization 1476 This example shows an Authorization request using implicit 1477 authorization. CAM initially requests the actions GET and POST on 1478 the resource "coaps://[2001:DB8::dcaf:1234]/a/switch2941". SAM 1479 returns a ticket that has no SAI field in its ticket Face, hence 1480 implicitly authorizing C. 1482 CAM --> SAM 1483 POST ep/node138/a/switch2941 1484 Content-Format: application/dcaf+cbor 1485 { 1486 SAM: "coaps://[2001:DB8::1]/ep/node138/a/switch2941", 1487 SAI: ["coaps://[2001:DB8::dcaf:1234]/a/switch2941", 3] 1488 } 1490 CAM <-- SAM 1491 2.05 Content 1492 Content-Format: application/dcaf+cbor 1493 { F: { 1494 TS: 0("2013-07-16T10:15:43.663"), 1495 G: hmac_sha256 1496 }, 1497 V: h'4f7b0e7fdcc498fb2ece648bf6bdf736 1498 61a6067e51278a0078e5b8217147ea06' 1499 } 1501 11. Specific Usage Scenarios 1503 The general DCAF architure outlined in Section 3.1 illustrates the 1504 various actors who participate in the message exchange for 1505 authenticated authorization. The message types defined in this 1506 document cover the most general case where all four actors are 1507 separate entities that may or may not reside on the same device. 1509 Special implementation considerations apply when one single entity 1510 takes the role of more than one actor. This section gives advice on 1511 the most common usage scenarios where the Client Authorization 1512 Manager and Client, the Server Authorization Manager and Server or 1513 both Authorization Managers reside on the same (less-constrained) 1514 device and have a means of secure communication outside the scope of 1515 this document. 1517 11.1. Combined Authorization Manager and Client 1519 When CAM and C reside on the same (less-constrained) device, the 1520 Access Request and Ticket Transfer messages can be substituted by 1521 other means of secure communication. Figure 9 shows a simplified 1522 message exchange for a combined CAM+C device. 1524 CAM+C S SAM 1525 | | <== DTLS chan. ==> | 1526 | [Resource Req.-->] | | 1527 | | | 1528 | [<-- SAM Info.] | | 1529 | | | 1530 | <==== TLS/DTLS chan. (Mutual Auth) ===> | 1531 | | | 1532 | Ticket Request ---------------------> | 1533 | | | 1534 | <--------------------- Ticket Grant | 1535 | | | 1536 | <== DTLS chan. ==> | | 1537 | Auth. Res. Req. -> | | 1539 Figure 9: Combined Client Authorization Manager and Client 1541 11.1.1. Creating the Ticket Request Message 1543 When CAM+C receives an SAM Information message as a reaction to an 1544 Unauthorized Request message, it creates a Ticket Request message as 1545 follows: 1547 1. The destination of the Ticket Request message is derived from the 1548 authority information in the URI contained in field "SAM" of the 1549 SAM Information message payload. 1551 2. The request method is POST. 1553 3. The request URI is constructed from the SAM field received in the 1554 SAM Information message payload. 1556 4. The payload contains the SAM field from the SAM Information 1557 message, an absolute URI of the resource that CAM+C wants to 1558 access, the actions that CAM+C wants to perform on the resource, 1559 and any time stamp generated by S that was transferred with the 1560 SAM Information message. 1562 5. A label that describes CAM+C is added to the payload. 1564 11.1.2. Processing the Ticket Grant Message 1566 Based on the Ticket Grant message, CAM+C is able to establish a DTLS 1567 channel with S. To do so, CAM+C sets the psk_identity field of the 1568 DTLS ClientKeyExchange message to the ticket Face received in the 1569 Ticket Grant message and uses the ticket Verifier as PSK when 1570 constructing the premaster secret. 1572 11.2. Combined Client Authorization Manager and Server Authorization 1573 Manager 1575 In certain scenarios, CAM and SAM may be combined to a single entity 1576 that knows both, C and S, and decides if their actions are 1577 authorized. Therefore, no explicit communication between CAM and SAM 1578 is necessary, resulting in omission of the Ticket Request and Ticket 1579 Grant messages. Figure 10 depicts the resulting message sequence in 1580 this simplified architecture. 1582 C CAM+SAM S 1583 | <== DTLS chan. ==> | <== DTLS chan. ==> | 1584 | | | 1585 | [Resource Req.----------------------->] | 1586 | | | 1587 | [<-------------------- SAM Information] | 1588 | | | 1589 | Access Request --> | | 1590 | | | 1591 | <-- Ticket Transf. | | 1592 | | | 1593 | <=========== DTLS channel ===========> | 1594 | | | 1595 | Authorized Resource Request ----------> | 1597 Figure 10: Combined Client Authorization Manager and Server 1598 Authorization Manager 1600 11.2.1. Processing the Access Request Message 1602 When receiving an Access Request message, CAM+SAM performs the checks 1603 specified in Section 3.5 and returns a 4.00 (Bad Request) response in 1604 case of failure. Otherwise, if the checks have succeeded, CAM+SAM 1605 evaluates the contents of Access Request message as described in 1606 Section 3.6. 1608 The decision on the access request is performed by CAM+SAM with 1609 respect to the stored policies. When the requested action is 1610 permitted on the respective resource, CAM+SAM generates an access 1611 ticket as outlined in Section 4.1 and creates a Ticket Transfer 1612 message to convey the access ticket to the Client. 1614 11.2.2. Creating the Ticket Transfer Message 1616 A Ticket Transfer message is constructed as a 2.05 response with the 1617 access ticket contained in its payload. The response MAY contain a 1618 Max-Age option to indicate the ticket's lifetime to the receiving 1619 Client. 1621 This specification defines a CBOR data representation for the access 1622 ticket as illustrated in Section 3.6. 1624 11.3. Combined Server Authorization Manager and Server 1626 If SAM and S are colocated in one entity (SAM+S), the main objective 1627 is to allow CAM to delegate access to C. Accordingly, the 1628 authorization information could be replaced by a nonce internal to 1629 SAM+S. (TBD.) 1630 CAM C SAM+S 1631 | <== DTLS chan. ==> | | 1632 | | [Resource Req.-->] | 1633 | | | 1634 | | [<-- SAM Info.] | 1635 | | | 1636 | <-- Access Req. | | 1637 | | | 1638 | <========= TLS/DTLS channel =========> | 1639 | | | 1640 | Ticket Request ---------------------> | 1641 | | | 1642 | <--------------------- Ticket Grant | 1643 | | | 1644 | Ticket Transf. --> | | 1645 | | | 1646 | | <== DTLS chan. ==> | 1647 | | Auth. Res. Req. -> | 1649 Figure 11: Combined Server Authorization Manager and Server 1651 12. Security Considerations 1653 As this protocol builds on transitive trust between Authorization 1654 Managers as mentioned in Section 8, SAM has no direct means to 1655 validate that a resource request originates from C. It has to trust 1656 CAM that it correctly vouches for C and that it does not give 1657 authorization tickets meant for C to another client nor disclose the 1658 contained session key. 1660 The Authorization Managers also could constitute a single point of 1661 failure. If the Server Authorization Manager fails, the resources on 1662 all Servers it is responsible for cannot be accessed any more. If a 1663 Client Authorization Manager fails, all clients it is responsible are 1664 not able to access resources on a Server. Thus, it is crucial for 1665 large networks to use Authorization Managers in a redundant setup. 1667 13. IANA Considerations 1669 The following registrations are done following the procedure 1670 specified in [RFC6838]. 1672 Note to RFC Editor: Please replace all occurrences of "[RFC-XXXX]" 1673 with the RFC number of this specification. 1675 13.1. DTLS PSK Key Generation Methods 1677 A sub-registry for the values indicating the PSK key generation 1678 method as contents of the field G in a payload of type application/ 1679 dcaf+cbor is defined. Values in this sub-registry are numeric 1680 integers encoded in Concise Binary Object Notation (CBOR, [RFC7049]). 1681 This document follows the notation of [RFC7049] for binary values, 1682 i.e. a number starts with the prefix "0b". The major type is 1683 separated from the actual numeric value by an underscore to emphasize 1684 the value's internal structure. 1686 Initial entries in this sub-registry are as follows: 1688 +---------------+-------------+------------+ 1689 | Encoded Value | Name | Reference | 1690 +---------------+-------------+------------+ 1691 | 0b000_00000 | hmac_sha256 | [RFC-XXXX] | 1692 | | | | 1693 | 0b000_00001 | hmac_sha384 | [RFC-XXXX] | 1694 | | | | 1695 | 0b000_00010 | hmac_sha512 | [RFC-XXXX] | 1696 +---------------+-------------+------------+ 1698 Table 3: DTLS PSK Key Generation Methods 1700 New methods can be added to this registry based on designated expert 1701 review according to [RFC5226]. 1703 (TBD: criteria for expert review.) 1705 13.2. dcaf+cbor Media Type Registration 1707 Type name: application 1709 Subtype name: dcaf+cbor 1711 Required parameters: none 1713 Optional parameters: none 1715 Encoding considerations: Must be encoded as using a subset of the 1716 encoding allowed in [RFC7049]. Specifically, only the primitive data 1717 types String and Number are allowed. The type Number is restricted 1718 to unsigned integers (i.e., no negative numbers, fractions or 1719 exponents are allowed). Encoding MUST be UTF-8. These restrictions 1720 simplify implementations on devices that have very limited memory 1721 capacity. 1723 Security considerations: TBD 1725 Interoperability considerations: TBD 1727 Published specification: [RFC-XXXX] 1729 Applications that use this media type: TBD 1731 Additional information: 1733 Magic number(s): none 1735 File extension(s): dcaf 1737 Macintosh file type code(s): none 1739 Person & email address to contact for further information: TBD 1741 Intended usage: COMMON 1743 Restrictions on usage: None 1745 Author: TBD 1747 Change controller: IESG 1749 13.3. CoAP Content Format Registration 1751 This document specifies a new media type application/dcaf+cbor (cf. 1752 Section 13.2). For use with CoAP, a numeric Content-Format 1753 identifier is to be registered in the "CoAP Content-Formats" sub- 1754 registry within the "CoRE Parameters" registry. 1756 Note to RFC Editor: Please replace all occurrences of "RFC-XXXX" with 1757 the RFC number of this specification. 1759 +-----------------------+----------+------+------------+ 1760 | Media type | Encoding | Id. | Reference | 1761 +-----------------------+----------+------+------------+ 1762 | application/dcaf+cbor | - | TBD1 | [RFC-XXXX] | 1763 +-----------------------+----------+------+------------+ 1765 14. References 1766 14.1. Normative References 1768 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1769 Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/ 1770 RFC2119, March 1997, 1771 . 1773 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 1774 Resource Identifier (URI): Generic Syntax", STD 66, RFC 1775 3986, DOI 10.17487/RFC3986, January 2005, 1776 . 1778 [RFC4279] Eronen, P., Ed. and H. Tschofenig, Ed., "Pre-Shared Key 1779 Ciphersuites for Transport Layer Security (TLS)", RFC 1780 4279, DOI 10.17487/RFC4279, December 2005, 1781 . 1783 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 1784 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 1785 DOI 10.17487/RFC5226, May 2008, 1786 . 1788 [RFC5746] Rescorla, E., Ray, M., Dispensa, S., and N. Oskov, 1789 "Transport Layer Security (TLS) Renegotiation Indication 1790 Extension", RFC 5746, DOI 10.17487/RFC5746, February 2010, 1791 . 1793 [RFC6347] Rescorla, E. and N. Modadugu, "Datagram Transport Layer 1794 Security Version 1.2", RFC 6347, DOI 10.17487/RFC6347, 1795 January 2012, . 1797 [RFC6838] Freed, N., Klensin, J., and T. Hansen, "Media Type 1798 Specifications and Registration Procedures", BCP 13, RFC 1799 6838, DOI 10.17487/RFC6838, January 2013, 1800 . 1802 [RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object 1803 Representation (CBOR)", RFC 7049, DOI 10.17487/RFC7049, 1804 October 2013, . 1806 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 1807 Application Protocol (CoAP)", RFC 7252, DOI 10.17487/ 1808 RFC7252, June 2014, 1809 . 1811 14.2. Informative References 1813 [I-D.bormann-core-ace-aif] 1814 Bormann, C., "An Authorization Information Format (AIF) 1815 for ACE", draft-bormann-core-ace-aif-03 (work in 1816 progress), July 2015. 1818 [I-D.gerdes-ace-actors] 1819 Gerdes, S., Seitz, L., Selander, G., and C. Bormann, "An 1820 architecture for authorization in constrained 1821 environments", draft-gerdes-ace-actors-05 (work in 1822 progress), April 2015. 1824 [I-D.greevenbosch-appsawg-cbor-cddl] 1825 Vigano, C. and H. Birkholz, "CBOR data definition 1826 language: a notational convention to express CBOR data 1827 structures.", draft-greevenbosch-appsawg-cbor-cddl-06 1828 (work in progress), July 2015. 1830 [I-D.ietf-core-block] 1831 Bormann, C. and Z. Shelby, "Block-wise transfers in CoAP", 1832 draft-ietf-core-block-17 (work in progress), March 2015. 1834 [I-D.ietf-core-observe] 1835 Hartke, K., "Observing Resources in CoAP", draft-ietf- 1836 core-observe-16 (work in progress), December 2014. 1838 [I-D.ietf-core-resource-directory] 1839 Shelby, Z., Koster, M., Bormann, C., and P. Stok, "CoRE 1840 Resource Directory", draft-ietf-core-resource-directory-04 1841 (work in progress), July 2015. 1843 [I-D.ietf-cose-msg] 1844 Schaad, J. and B. Campbell, "CBOR Encoded Message Syntax", 1845 draft-ietf-cose-msg-04 (work in progress), August 2015. 1847 [I-D.schmertmann-dice-codtls] 1848 Schmertmann, L., Hartke, K., and C. Bormann, "CoDTLS: DTLS 1849 handshakes over CoAP", draft-schmertmann-dice-codtls-01 1850 (work in progress), August 2014. 1852 [RFC5988] Nottingham, M., "Web Linking", RFC 5988, DOI 10.17487/ 1853 RFC5988, October 2010, 1854 . 1856 [RFC6655] McGrew, D. and D. Bailey, "AES-CCM Cipher Suites for 1857 Transport Layer Security (TLS)", RFC 6655, DOI 10.17487/ 1858 RFC6655, July 2012, 1859 . 1861 [RFC6690] Shelby, Z., "Constrained RESTful Environments (CoRE) Link 1862 Format", RFC 6690, DOI 10.17487/RFC6690, August 2012, 1863 . 1865 [bergmann12] 1866 Bergmann, O., Gerdes, S., Schaefer, S., Junge, F., and C. 1867 Bormann, "Secure Bootstrapping of Nodes in a CoAP 1868 Network", IEEE Wireless Communications and Networking 1869 Conference Workshops (WCNCW), April 2012. 1871 Appendix A. CDDL Specification 1873 This appendix shows a formal specification of the DCAF messaging 1874 format using the CBOR data definition language (CDDL) 1875 [I-D.greevenbosch-appsawg-cbor-cddl]: 1877 dcaf-msg = sam-information-msg 1878 / access-request-msg 1879 / ticket-transfer-msg 1880 / ticket-grant-msg 1882 sam-information-msg = { sam, ? full-timestamp, ? accepted-formats, 1883 ? piggybacked } 1885 access-request-msg = { sam, sam-ai, full-timestamp } 1887 ticket-transfer-msg = { face-or-encrypted, verifier } 1888 face-or-encrypted = ( face | encrypted-face ) 1889 face = ( F => { sam-ai, limited-timestamp, lifetime, psk-gen } ) 1890 verifier = ( V => shared-secret ) 1891 shared-secret = bstr 1892 F = 8 1893 V = 9 1895 encrypted-face = ( E => bstr, K => tstr ) 1896 E = 3 1897 K = 4 1899 ticket-grant-msg = { face-or-encrypted, verifier, ? client-info } 1900 client-info = ( cam-ai, full-timestamp, lifetime) 1902 sam = (SAM => abs-uri) 1903 SAM = 0 1904 abs-uri = tstr ; .regexp "______" 1906 sam-ai = ( SAI => [* auth-info]) 1907 SAI = 1 1908 auth-info = ( uri : tstr, mask : 0..15 ) 1910 cam-ai = ( CAI => [* auth-info]) 1911 CAI = 2 1913 full-timestamp = ( TS => date) 1914 TS = 5 1915 date = tdate / localdate 1916 localdate = uint 1917 limited-timestamp = ( TS => localdate) 1919 accepted-formats = ( A => [+ content-format] ) 1920 content-format = uint ; valid entry from CoAP content format registry 1921 A=10 1923 piggybacked = ( data, lifetime, nonce ) 1924 data = ( D => bstr ) 1925 none = ( N => bstr ) 1926 lifetime = ( L => period) 1927 period = uint ; in seconds 1928 L = 6 1929 D = 11 1930 N = 12 1932 psk-gen = ( G => mac-algorithm) 1933 G = 7 1934 mac-algorithm = &( hmac-sha256: 0, hmac-sha384: 1, hmac-sha512: 2 ) 1936 Authors' Addresses 1938 Stefanie Gerdes 1939 Universitaet Bremen TZI 1940 Postfach 330440 1941 Bremen D-28359 1942 Germany 1944 Phone: +49-421-218-63906 1945 Email: gerdes@tzi.org 1946 Olaf Bergmann 1947 Universitaet Bremen TZI 1948 Postfach 330440 1949 Bremen D-28359 1950 Germany 1952 Phone: +49-421-218-63904 1953 Email: bergmann@tzi.org 1955 Carsten Bormann 1956 Universitaet Bremen TZI 1957 Postfach 330440 1958 Bremen D-28359 1959 Germany 1961 Phone: +49-421-218-63921 1962 Email: cabo@tzi.org