idnits 2.17.1 draft-ietf-ace-dtls-authorize-06.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 (February 28, 2019) is 1883 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 727, but not defined == Outdated reference: A later version (-11) exists of draft-ietf-ace-cwt-proof-of-possession-06 == Outdated reference: A later version (-46) exists of draft-ietf-ace-oauth-authz-21 == Outdated reference: A later version (-16) exists of draft-ietf-ace-oauth-params-04 ** Obsolete normative reference: RFC 6347 (Obsoleted by RFC 9147) ** Obsolete normative reference: RFC 8152 (Obsoleted by RFC 9052, RFC 9053) Summary: 2 errors (**), 0 flaws (~~), 5 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 ACE Working Group S. Gerdes 3 Internet-Draft O. Bergmann 4 Intended status: Standards Track C. Bormann 5 Expires: September 1, 2019 Universitaet Bremen TZI 6 G. Selander 7 Ericsson AB 8 L. Seitz 9 RISE SICS 10 February 28, 2019 12 Datagram Transport Layer Security (DTLS) Profile for Authentication and 13 Authorization for Constrained Environments (ACE) 14 draft-ietf-ace-dtls-authorize-06 16 Abstract 18 This specification defines a profile of the ACE framework that allows 19 constrained servers to delegate client authentication and 20 authorization. The protocol relies on DTLS for communication 21 security between entities in a constrained network using either raw 22 public keys or pre-shared keys. A resource-constrained server can 23 use this protocol to delegate management of authorization information 24 to a trusted host with less severe limitations regarding processing 25 power and memory. 27 Status of This Memo 29 This Internet-Draft is submitted in full conformance with the 30 provisions of BCP 78 and BCP 79. 32 Internet-Drafts are working documents of the Internet Engineering 33 Task Force (IETF). Note that other groups may also distribute 34 working documents as Internet-Drafts. The list of current Internet- 35 Drafts is at https://datatracker.ietf.org/drafts/current/. 37 Internet-Drafts are draft documents valid for a maximum of six months 38 and may be updated, replaced, or obsoleted by other documents at any 39 time. It is inappropriate to use Internet-Drafts as reference 40 material or to cite them other than as "work in progress." 42 This Internet-Draft will expire on September 1, 2019. 44 Copyright Notice 46 Copyright (c) 2019 IETF Trust and the persons identified as the 47 document authors. All rights reserved. 49 This document is subject to BCP 78 and the IETF Trust's Legal 50 Provisions Relating to IETF Documents 51 (https://trustee.ietf.org/license-info) in effect on the date of 52 publication of this document. Please review these documents 53 carefully, as they describe your rights and restrictions with respect 54 to this document. Code Components extracted from this document must 55 include Simplified BSD License text as described in Section 4.e of 56 the Trust Legal Provisions and are provided without warranty as 57 described in the Simplified BSD License. 59 Table of Contents 61 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 62 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3 63 2. Protocol Overview . . . . . . . . . . . . . . . . . . . . . . 3 64 3. Protocol Flow . . . . . . . . . . . . . . . . . . . . . . . . 5 65 3.1. Communication between C and AS . . . . . . . . . . . . . 5 66 3.2. RawPublicKey Mode . . . . . . . . . . . . . . . . . . . . 6 67 3.2.1. DTLS Channel Setup Between C and RS . . . . . . . . . 7 68 3.3. PreSharedKey Mode . . . . . . . . . . . . . . . . . . . . 8 69 3.3.1. DTLS Channel Setup Between C and RS . . . . . . . . . 11 70 3.4. Resource Access . . . . . . . . . . . . . . . . . . . . . 12 71 4. Dynamic Update of Authorization Information . . . . . . . . . 13 72 5. Token Expiration . . . . . . . . . . . . . . . . . . . . . . 14 73 6. Security Considerations . . . . . . . . . . . . . . . . . . . 15 74 7. Privacy Considerations . . . . . . . . . . . . . . . . . . . 15 75 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 16 76 9. References . . . . . . . . . . . . . . . . . . . . . . . . . 16 77 9.1. Normative References . . . . . . . . . . . . . . . . . . 16 78 9.2. Informative References . . . . . . . . . . . . . . . . . 17 79 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 18 81 1. Introduction 83 This specification defines a profile of the ACE framework 84 [I-D.ietf-ace-oauth-authz]. In this profile, a client and a resource 85 server use CoAP [RFC7252] over DTLS [RFC6347] to communicate. The 86 client obtains an access token, bound to a key (the proof-of- 87 possession key), from an authorization server to prove its 88 authorization to access protected resources hosted by the resource 89 server. Also, the client and the resource server are provided by the 90 authorization server with the necessary keying material to establish 91 a DTLS session. The communication between client and authorization 92 server may also be secured with DTLS. This specification supports 93 DTLS with Raw Public Keys (RPK) [RFC7250] and with Pre-Shared Keys 94 (PSK) [RFC4279]. 96 The DTLS handshake requires the client and server to prove that they 97 can use certain keying material. In the RPK mode, the client proves 98 with the DTLS handshake that it can use the RPK bound to the token 99 and the server shows that it can use a certain RPK. The access token 100 must be presented to the resource server. For the RPK mode, the 101 access token needs to be uploaded to the resource server before the 102 handshake is initiated, as described in Section 5.8.1 of the ACE 103 framework [I-D.ietf-ace-oauth-authz]. 105 In the PSK mode, client and server show with the DTLS handshake that 106 they can use the keying material that is bound to the access token. 107 To transfer the access token from the client to the resource server, 108 the "psk_identity" parameter in the DTLS PSK handshake may be used 109 instead of uploading the token prior to the handshake. 111 1.1. Terminology 113 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 114 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 115 "OPTIONAL" in this document are to be interpreted as described in BCP 116 14 [RFC2119] [RFC8174] when, and only when, they appear in all 117 capitals, as shown here. 119 Readers are expected to be familiar with the terms and concepts 120 described in [I-D.ietf-ace-oauth-authz] and in 121 [I-D.ietf-ace-oauth-params]. 123 The authz-info resource refers to the authz-info endpoint as 124 specified in [I-D.ietf-ace-oauth-authz]. 126 2. Protocol Overview 128 The CoAP-DTLS profile for ACE specifies the transfer of 129 authentication information and, if necessary, authorization 130 information between the client (C) and the resource server (RS) 131 during setup of a DTLS session for CoAP messaging. It also specifies 132 how C can use CoAP over DTLS to retrieve an access token from the 133 authorization server (AS) for a protected resource hosted on the 134 resource server. 136 This profile requires the client to retrieve an access token for 137 protected resource(s) it wants to access on RS as specified in 138 [I-D.ietf-ace-oauth-authz]. Figure 1 shows the typical message flow 139 in this scenario (messages in square brackets are optional): 141 C RS AS 142 | [-- Resource Request --->] | | 143 | | | 144 | [<----- AS Information --] | | 145 | | | 146 | --- Token Request ----------------------------> | 147 | | | 148 | <---------------------------- Access Token ----- | 149 | + Access Information | 151 Figure 1: Retrieving an Access Token 153 To determine the AS in charge of a resource hosted at the RS, C MAY 154 send an initial Unauthorized Resource Request message to the RS. The 155 RS then denies the request and sends an AS information message 156 containing the address of its AS back to the client as specified in 157 Section 5.1.2 of [I-D.ietf-ace-oauth-authz]. 159 Once the client knows the authorization server's address, it can send 160 an access token request to the token endpoint at the AS as specified 161 in [I-D.ietf-ace-oauth-authz]. As the access token request as well 162 as the response may contain confidential data, the communication 163 between the client and the authorization server MUST be 164 confidentiality-protected and ensure authenticity. C may have been 165 registered at the AS via the OAuth 2.0 client registration mechanism 166 as outlined in Section 5.3 of [I-D.ietf-ace-oauth-authz]. 168 The access token returned by the authorization server can then be 169 used by the client to establish a new DTLS session with the resource 170 server. When the client intends to use asymmetric cryptography in 171 the DTLS handshake with the resource server, the client MUST upload 172 the access token to the authz-info resource, i.e. the authz-info 173 endpoint, on the resource server before starting the DTLS handshake, 174 as described in Section 5.8.1 of [I-D.ietf-ace-oauth-authz]. If only 175 symmetric cryptography is used between the client and the resource 176 server, the access token MAY instead be transferred in the DTLS 177 ClientKeyExchange message (see Section 3.3.1). 179 Figure 2 depicts the common protocol flow for the DTLS profile after 180 the client C has retrieved the access token from the authorization 181 server AS. 183 C RS AS 184 | [--- Access Token ------>] | | 185 | | | 186 | <== DTLS channel setup ==> | | 187 | | | 188 | == Authorized Request ===> | | 189 | | | 190 | <=== Protected Resource == | | 192 Figure 2: Protocol overview 194 3. Protocol Flow 196 The following sections specify how CoAP is used to interchange 197 access-related data between the resource server, the client and the 198 authorization server so that the authorization server can provide the 199 client and the resource server with sufficient information to 200 establish a secure channel, and convey authorization information 201 specific for this communication relationship to the resource server. 203 Section 3.1 describes how the communication between C and AS must be 204 secured. Depending on the used CoAP security mode (see also 205 Section 9 of [RFC7252], the Client-to-AS request, AS-to-Client 206 response and DTLS session establishment carry slightly different 207 information. Section 3.2 addresses the use of raw public keys while 208 Section 3.3 defines how pre-shared keys are used in this profile. 210 3.1. Communication between C and AS 212 To retrieve an access token for the resource that the client wants to 213 access, the client requests an access token from the authorization 214 server. Before C can request the access token, C and AS must 215 establish a secure communication channel. C must securely have 216 obtained keying material to communicate with AS, and C must securely 217 have received authorization information intended for C that states 218 that AS is authorized to provide keying material concerning RS to C. 219 Also, AS must securely have obtained keying material for C, and 220 obtained authorization rules approved by the resource owner (RO) 221 concerning C and RS that relate to this keying material. C and AS 222 must use their respective keying material for all exchanged messages. 223 How the security association between C and AS is established is not 224 part of this document. C and AS MUST ensure the confidentiality, 225 integrity and authenticity of all exchanged messages. 227 If C is constrained, C and AS should use DTLS to communicate with 228 each other. But C and AS may also use other means to secure their 229 communication, e.g., TLS. The used security protocol must provide 230 confidentiality, integrity and authenticity, and enable the client to 231 determine if it is the intended recipient of a message, e.g., by 232 using an AEAD mechanism. C must also be able to determine if a 233 response from AS belongs to a certain request. Additionally, the 234 protocol must offer replay protection. 236 3.2. RawPublicKey Mode 238 After C and AS mutually authenticated each other and validated each 239 other's authorization, C sends a token request to AS's token 240 endpoint. The client MUST add a "req_cnf" object carrying either its 241 raw public key or a unique identifier for a public key that it has 242 previously made known to the authorization server. To prove that the 243 client is in possession of this key, C MUST use the same keying 244 material that it uses to secure the communication with AS, e.g., the 245 DTLS session. 247 An example access token request from the client to the AS is depicted 248 in Figure 3. 250 POST coaps://as.example.com/token 251 Content-Format: application/ace+cbor 252 { 253 grant_type: client_credentials, 254 req_aud: "tempSensor4711", 255 req_cnf: { 256 COSE_Key: { 257 kty: EC2, 258 crv: P-256, 259 x: h'e866c35f4c3c81bb96a1...', 260 y: h'2e25556be097c8778a20...' 261 } 262 } 263 } 265 Figure 3: Access Token Request Example for RPK Mode 267 The example shows an access token request for the resource identified 268 by the string "tempSensor4711" on the authorization server using a 269 raw public key. 271 AS MUST check if the client that it communicates with is associated 272 with the RPK in the cnf object before issuing an access token to it. 273 If AS determines that the request is to be authorized according to 274 the respective authorization rules, it generates an access token 275 response for C. The response SHOULD contain a "profile" parameter 276 with the value "coap_dtls" to indicate that this profile must be used 277 for communication between the client C and the resource server. The 278 response also contains an access token and an "rs_cnf" parameter 279 containing information about the public key that is used by the 280 resource server. AS MUST ascertain that the RPK specified in 281 "rs_cnf" belongs to the resource server that C wants to communicate 282 with. AS MUST protect the integrity of the token. If the access 283 token contains confidential data, AS MUST also protect the 284 confidentiality of the access token. 286 C MUST ascertain that the access token response belongs to a certain 287 previously sent access token request, as the request may specify the 288 resource server with which C wants to communicate. 290 3.2.1. DTLS Channel Setup Between C and RS 292 Before the client initiates the DTLS handshake with the resource 293 server, C MUST send a "POST" request containing the new access token 294 to the authz-info resource hosted by the resource server. If this 295 operation yields a positive response, the client SHOULD proceed to 296 establish a new DTLS channel with the resource server. To use the 297 RawPublicKey mode, the client MUST specify the public key that AS 298 defined in the "cnf" field of the access token response in the 299 SubjectPublicKeyInfo structure in the DTLS handshake as specified in 300 [RFC7250]. 302 An implementation that supports the RPK mode of this profile MUST at 303 least support the ciphersuite TLS_ECDHE_ECDSA_WITH_AES_128_CCM_8 304 [RFC7251] with the ed25519 curve (cf. [RFC8032], [RFC8422]). 306 Note: According to [RFC7252], CoAP implementations MUST support the 307 ciphersuite TLS_ECDHE_ECDSA_WITH_AES_128_CCM_8 [RFC7251] and the 308 NIST P-256 curve. As discussed in [RFC7748], new ECC curves have 309 been defined recently that are considered superior to the so- 310 called NIST curves. The curve that is mandatory to implement in 311 this specification is said to be efficient and less dangerous 312 regarding implementation errors than the secp256r1 curve mandated 313 in [RFC7252]. 315 RS MUST check if the access token is still valid, if RS is the 316 intended destination, i.e., the audience, of the token, and if the 317 token was issued by an authorized AS. The access token is 318 constructed by the authorization server such that the resource server 319 can associate the access token with the Client's public key. The 320 "cnf" claim MUST contain either C's RPK or, if the key is already 321 known by the resource server (e.g., from previous communication), a 322 reference to this key. If the authorization server has no certain 323 knowledge that the Client's key is already known to the resource 324 server, the Client's public key MUST be included in the access 325 token's "cnf" parameter. If CBOR web tokens [RFC8392] are used as 326 recommended in [I-D.ietf-ace-oauth-authz], keys MUST be encoded as 327 specified in [I-D.ietf-ace-cwt-proof-of-possession]. RS MUST use the 328 keying material in the handshake that AS specified in the rs_cnf 329 parameter in the access token. Thus, the handshake only finishes if 330 C and RS are able to use their respective keying material. 332 3.3. PreSharedKey Mode 334 To retrieve an access token for the resource that the client wants to 335 access, the client MAY include a "cnf" object carrying an identifier 336 for a symmetric key in its access token request to the authorization 337 server. This identifier can be used by the authorization server to 338 determine the shared secret to construct the proof-of-possession 339 token. AS MUST check if the identifier refers to a symmetric key 340 that was previously generated by AS as a shared secret for the 341 communication between this client and the resource server. 343 The authorization server MUST determine the authorization rules for 344 the C it communicates with as defined by RO and generate the access 345 token accordingly. If the authorization server authorizes the 346 client, it returns an AS-to-Client response. If the profile 347 parameter is present, it is set to "coap_dtls". AS MUST ascertain 348 that the access token is generated for the resource server that C 349 wants to communicate with. Also, AS MUST protect the integrity of 350 the access token. If the token contains confidential data such as 351 the symmetric key, the confidentiality of the token MUST also be 352 protected. Depending on the requested token type and algorithm in 353 the access token request, the authorization server adds access 354 Information to the response that provides the client with sufficient 355 information to setup a DTLS channel with the resource server. AS 356 adds a "cnf" parameter to the access information carrying a 357 "COSE_Key" object that informs the client about the symmetric key 358 that is to be used between C and the resource server. 360 An example access token response is illustrated in Figure 4. In this 361 example, the authorization server returns a 2.01 response containing 362 a new access token and information for the client, including the 363 symmetric key in the cnf claim. The information is transferred as a 364 CBOR data structure as specified in [I-D.ietf-ace-oauth-authz]. 366 2.01 Created 367 Content-Format: application/ace+cbor 368 Max-Age: 86400 369 { 370 access_token: h'd08343a10... 371 (remainder of CWT omitted for brevity) 372 token_type: pop, 373 expires_in: 86400, 374 profile: coap_dtls, 375 cnf: { 376 COSE_Key: { 377 kty: symmetric, 378 alg: TLS_PSK_WITH_AES_128_CCM_8 379 kid: h'3d027833fc6267ce', 380 k: h'73657373696f6e6b6579' 381 } 382 } 383 } 385 Figure 4: Example Access Token Response 387 The access token also comprises a "cnf" claim. This claim usually 388 contains a "COSE_Key" object that carries either the symmetric key 389 itself or a key identifier that can be used by the resource server to 390 determine the secret key shared with the client. If the access token 391 carries a symmetric key, the access token MUST be encrypted using a 392 "COSE_Encrypt0" structure. The AS MUST use the keying material 393 shared with the RS to encrypt the token. 395 A response that declines any operation on the requested resource is 396 constructed according to Section 5.2 of [RFC6749], (cf. 397 Section 5.6.3. of [I-D.ietf-ace-oauth-authz]). 399 4.00 Bad Request 400 Content-Format: application/ace+cbor 401 { 402 error: invalid_request 403 } 405 Figure 5: Example Access Token Response With Reject 407 The method for how the resource server determines the symmetric key 408 from an access token containing only a key identifier is application 409 specific, the remainder of this section provides one example. 411 The AS and the resource server are assumed to share a key derivation 412 key used to derive the symmetric key shared with the client from the 413 key identifier in the access token. The key derivation key may be 414 derived from some other secret key shared between the AS and the 415 resource server. Knowledge of the symmetric key shared with the 416 client must not reveal any information about the key derivation key 417 or other secret keys shared between AS and resource server. 419 In order to generate a new symmetric key to be used by client and 420 resource server, the AS generates a key identifier and uses the key 421 derivation key shared with the resource server to derive the 422 symmetric key as specified below. Instead of providing the keying 423 material in the access token, the AS includes the key identifier in 424 the "kid" parameter, see Figure 6. This key identifier enables the 425 resource server to calculate the keying material for the 426 communication with the client from the access token using the key 427 derivation key and following Section 11 of [RFC8152] with parameters 428 as specified here. The KDF to be used needs to be defined by the 429 application, for example HKDF-SHA-256. The key identifier picked by 430 the AS needs to be unique for each access token where a unique 431 symmetric key is required. 433 The fields in the context information "COSE_KDF_Context" 434 (Section 11.2 of [RFC8152]) have the following values: 436 o AlgorithmID = "ACE-CoAP-DTLS-key-derivation" 438 o PartyUInfo = PartyVInfo = ( null, null, null ) 440 o keyDataLength is a uint equal the length of the symmetric key 441 shared between C and RS in bits 443 o protected MUST be a zero length bstr 445 o other is a zero length bstr 447 o SuppPrivInfo is omitted 449 The "cnf" structure in the access token is provided in Figure 6. 451 cnf : { 452 COSE_Key : { 453 kty : symmetric, 454 alg : TLS_PSK_WITH_AES_128_CCM_8, 455 kid : h'eIiOFCa9lObw' 456 } 457 } 459 Figure 6: Access Token without Keying Material 461 3.3.1. DTLS Channel Setup Between C and RS 463 When a client receives an access token response from an authorization 464 server, C MUST ascertain that the access token response belongs to a 465 certain previously sent access token request, as the request may 466 specify the resource server with which C wants to communicate. 468 C checks if the payload of the access token response contains an 469 "access_token" parameter and a "cnf" parameter. With this 470 information the client can initiate the establishment of a new DTLS 471 channel with a resource server. To use DTLS with pre-shared keys, 472 the client follows the PSK key exchange algorithm specified in 473 Section 2 of [RFC4279] using the key conveyed in the "cnf" parameter 474 of the AS response as PSK when constructing the premaster secret. 476 In PreSharedKey mode, the knowledge of the shared secret by the 477 client and the resource server is used for mutual authentication 478 between both peers. Therefore, the resource server must be able to 479 determine the shared secret from the access token. Following the 480 general ACE authorization framework, the client can upload the access 481 token to the resource server's authz-info resource before starting 482 the DTLS handshake. Alternatively, the client MAY provide the most 483 recent access token in the "psk_identity" field of the 484 ClientKeyExchange message. To do so, the client MUST treat the 485 contents of the "access_token" field from the AS-to-Client response 486 as opaque data and not perform any re-coding. 488 Note: As stated in Section 4.2 of [RFC7925], the PSK identity should 489 be treated as binary data in the Internet of Things space and not 490 assumed to have a human-readable form of any sort. 492 If a resource server receives a ClientKeyExchange message that 493 contains a "psk_identity" with a length greater zero, it uses the 494 contents as index for its key store (i.e., treat the contents as key 495 identifier). The resource server MUST check if it has one or more 496 access tokens that are associated with the specified key. 498 If no key with a matching identifier is found, the resource server 499 MAY process the contents of the "psk_identity" field as access token 500 that is stored with the authorization information endpoint, before 501 continuing the DTLS handshake. If the contents of the "psk_identity" 502 do not yield a valid access token for the requesting client, the DTLS 503 session setup is terminated with an "illegal_parameter" DTLS alert 504 message. 506 Note1: As a resource server cannot provide a client with a 507 meaningful PSK identity hint in response to the client's 508 ClientHello message, the resource server SHOULD NOT send a 509 ServerKeyExchange message. 511 Note2: According to [RFC7252], CoAP implementations MUST support the 512 ciphersuite TLS_PSK_WITH_AES_128_CCM_8 [RFC6655]. A client is 513 therefore expected to offer at least this ciphersuite to the 514 resource server. 516 When RS receives an access token, RS MUST check if the access token 517 is still valid, if RS is the intended destination, i.e., the audience 518 of the token, and if the token was issued by an authorized AS. This 519 specification assumes that the access token is a PoP token as 520 described in [I-D.ietf-ace-oauth-authz] unless specifically stated 521 otherwise. Therefore, the access token is bound to a symmetric PoP 522 key that is used as shared secret between the client and the resource 523 server. 525 While the client can retrieve the shared secret from the contents of 526 the "cnf" parameter in the AS-to-Client response, the resource server 527 uses the information contained in the "cnf" claim of the access token 528 to determine the actual secret when no explicit "kid" was provided in 529 the "psk_identity" field. If key derivation is used, the RS uses the 530 "COSE_KDF_Context" information as described above. 532 3.4. Resource Access 534 Once a DTLS channel has been established as described in Section 3.2 535 and Section 3.3, respectively, the client is authorized to access 536 resources covered by the access token it has uploaded to the authz- 537 info resource hosted by the resource server. 539 With the successful establishment of the DTLS channel, C and RS have 540 proven that they can use their respective keying material. An access 541 token that is bound to the client's keying material is associated 542 with the channel. Any request that the resource server receives on 543 this channel MUST be checked against these authorization rules. RS 544 MUST check for every request if the access token is still valid. 545 Incoming CoAP requests that are not authorized with respect to any 546 access token that is associated with the client MUST be rejected by 547 the resource server with 4.01 response as described in Section 5.1.1 548 of [I-D.ietf-ace-oauth-authz]. 550 The resource server SHOULD treat an incoming CoAP request as 551 authorized if the following holds: 553 1. The message was received on a secure channel that has been 554 established using the procedure defined in this document. 556 2. The authorization information tied to the sending client is 557 valid. 559 3. The request is destined for the resource server. 561 4. The resource URI specified in the request is covered by the 562 authorization information. 564 5. The request method is an authorized action on the resource with 565 respect to the authorization information. 567 Incoming CoAP requests received on a secure DTLS channel that are not 568 thus authorized MUST be rejected according to Section 5.8.2 of 569 [I-D.ietf-ace-oauth-authz] 571 1. with response code 4.03 (Forbidden) when the resource URI 572 specified in the request is not covered by the authorization 573 information, and 575 2. with response code 4.05 (Method Not Allowed) when the resource 576 URI specified in the request covered by the authorization 577 information but not the requested action. 579 The client cannot always know a priori if an Authorized Resource 580 Request will succeed. It must check the validity of its keying 581 material before sending a request or processing a response. If the 582 client repeatedly gets error responses containing AS Creation Hints 583 (cf. Section 5.1.2 of [I-D.ietf-ace-oauth-authz] as response to its 584 requests, it SHOULD request a new access token from the authorization 585 server in order to continue communication with the resource server. 587 Unauthorized requests that have been received over a DTLS session 588 SHOULD be treated as non-fatal by the RS, i.e., the DTLS session 589 SHOULD be kept alive until the associated access token has expired. 591 4. Dynamic Update of Authorization Information 593 The client can update the authorization information stored at the 594 resource server at any time without changing an established DTLS 595 session. To do so, the Client requests a new access token from the 596 authorization server for the intended action on the respective 597 resource and uploads this access token to the authz-info resource on 598 the resource server. 600 Figure 7 depicts the message flow where the C requests a new access 601 token after a security association between the client and the 602 resource server has been established using this protocol. If the 603 client wants to update the authorization information, the token 604 request MUST specify the key identifier of the existing DTLS channel 605 between the client and the resource server in the "kid" parameter of 606 the Client-to-AS request. The authorization server MUST verify that 607 the specified "kid" denotes a valid verifier for a proof-of- 608 possession token that has previously been issued to the requesting 609 client. Otherwise, the Client-to-AS request MUST be declined with 610 the error code "unsupported_pop_key" as defined in Section 5.6.3 of 611 [I-D.ietf-ace-oauth-authz]. 613 When the authorization server issues a new access token to update 614 existing authorization information, it MUST include the specified 615 "kid" parameter in this access token. A resource server MUST replace 616 the authorization information of any existing DTLS session that is 617 identified by this key identifier with the updated authorization 618 information. 620 Note: By associating the access tokens with the identifier of an 621 existing DTLS session, the authorization information can be 622 updated without changing the cryptographic keys for the DTLS 623 communication between the client and the resource server, i.e. an 624 existing session can be used with updated permissions. 626 C RS AS 627 | <===== DTLS channel =====> | | 628 | + Access Token | | 629 | | | 630 | --- Token Request ----------------------------> | 631 | | | 632 | <---------------------------- New Access Token - | 633 | + Access Information | 634 | | | 635 | --- Update /authz-info --> | | 636 | New Access Token | | 637 | | | 638 | == Authorized Request ===> | | 639 | | | 640 | <=== Protected Resource == | | 642 Figure 7: Overview of Dynamic Update Operation 644 5. Token Expiration 646 DTLS sessions that have been established in accordance with this 647 profile are always tied to a specific set of access tokens. As these 648 tokens may become invalid at any time (either because the token has 649 expired or the responsible authorization server has revoked the 650 token), the session may become useless at some point. A resource 651 server therefore MUST terminate existing DTLS sessions after the last 652 valid access token for this session has been deleted. 654 As specified in Section 5.8.3 of [I-D.ietf-ace-oauth-authz], the 655 resource server MUST notify the client with an error response with 656 code 4.01 (Unauthorized) for any long running request before 657 terminating the session. 659 6. Security Considerations 661 This document specifies a profile for the Authentication and 662 Authorization for Constrained Environments (ACE) framework 663 [I-D.ietf-ace-oauth-authz]. As it follows this framework's general 664 approach, the general security and privacy considerations from 665 section 6 and section 7 also apply to this profile. 667 Constrained devices that use DTLS [RFC6347] are inherently vulnerable 668 to Denial of Service (DoS) attacks as the handshake protocol requires 669 creation of internal state within the device. This is specifically 670 of concern where an adversary is able to intercept the initial cookie 671 exchange and interject forged messages with a valid cookie to 672 continue with the handshake. A similar issue exists with the 673 authorization information endpoint where the resource server needs to 674 keep valid access tokens until their expiry. Adversaries can fill up 675 the constrained resource server's internal storage for a very long 676 time with interjected or otherwise retrieved valid access tokens. 678 The use of multiple access tokens for a single client increases the 679 strain on the resource server as it must consider every access token 680 and calculate the actual permissions of the client. Also, tokens may 681 contradict each other which may lead the server to enforce wrong 682 permissions. If one of the access tokens expires earlier than 683 others, the resulting permissions may offer insufficient protection. 684 Developers should avoid using multiple access tokens for a client. 686 7. Privacy Considerations 688 An unprotected response to an unauthorized request may disclose 689 information about the resource server and/or its existing 690 relationship with the client. It is advisable to include as little 691 information as possible in an unencrypted response. When a DTLS 692 session between the client and the resource server already exists, 693 more detailed information may be included with an error response to 694 provide the client with sufficient information to react on that 695 particular error. 697 Also, unprotected requests to the resource server may reveal 698 information about the client, e.g., which resources the client 699 attempts to request or the data that the client wants to provide to 700 the resource server. The client should not send confidential data in 701 an unprotected request. 703 Note that some information might still leak after DTLS session is 704 established, due to observable message sizes, the source, and the 705 destination addresses. 707 8. IANA Considerations 709 The following registrations are done for the ACE OAuth Profile 710 Registry following the procedure specified in 711 [I-D.ietf-ace-oauth-authz]. 713 Note to RFC Editor: Please replace all occurrences of "[RFC-XXXX]" 714 with the RFC number of this specification and delete this paragraph. 716 Profile name: coap_dtls 718 Profile Description: Profile for delegating client authentication and 719 authorization in a constrained environment by establishing a Datagram 720 Transport Layer Security (DTLS) channel between resource-constrained 721 nodes. 723 Profile ID: 1 725 Change Controller: IESG 727 Reference: [RFC-XXXX] 729 9. References 731 9.1. Normative References 733 [I-D.ietf-ace-cwt-proof-of-possession] 734 Jones, M., Seitz, L., Selander, G., Erdtman, S., and H. 735 Tschofenig, "Proof-of-Possession Key Semantics for CBOR 736 Web Tokens (CWTs)", draft-ietf-ace-cwt-proof-of- 737 possession-06 (work in progress), February 2019. 739 [I-D.ietf-ace-oauth-authz] 740 Seitz, L., Selander, G., Wahlstroem, E., Erdtman, S., and 741 H. Tschofenig, "Authentication and Authorization for 742 Constrained Environments (ACE) using the OAuth 2.0 743 Framework (ACE-OAuth)", draft-ietf-ace-oauth-authz-21 744 (work in progress), February 2019. 746 [I-D.ietf-ace-oauth-params] 747 Seitz, L., "Additional OAuth Parameters for Authorization 748 in Constrained Environments (ACE)", draft-ietf-ace-oauth- 749 params-04 (work in progress), February 2019. 751 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 752 Requirement Levels", BCP 14, RFC 2119, 753 DOI 10.17487/RFC2119, March 1997, 754 . 756 [RFC4279] Eronen, P., Ed. and H. Tschofenig, Ed., "Pre-Shared Key 757 Ciphersuites for Transport Layer Security (TLS)", 758 RFC 4279, DOI 10.17487/RFC4279, December 2005, 759 . 761 [RFC6347] Rescorla, E. and N. Modadugu, "Datagram Transport Layer 762 Security Version 1.2", RFC 6347, DOI 10.17487/RFC6347, 763 January 2012, . 765 [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", 766 RFC 6749, DOI 10.17487/RFC6749, October 2012, 767 . 769 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 770 Application Protocol (CoAP)", RFC 7252, 771 DOI 10.17487/RFC7252, June 2014, 772 . 774 [RFC7925] Tschofenig, H., Ed. and T. Fossati, "Transport Layer 775 Security (TLS) / Datagram Transport Layer Security (DTLS) 776 Profiles for the Internet of Things", RFC 7925, 777 DOI 10.17487/RFC7925, July 2016, 778 . 780 [RFC8152] Schaad, J., "CBOR Object Signing and Encryption (COSE)", 781 RFC 8152, DOI 10.17487/RFC8152, July 2017, 782 . 784 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 785 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 786 May 2017, . 788 9.2. Informative References 790 [RFC6655] McGrew, D. and D. Bailey, "AES-CCM Cipher Suites for 791 Transport Layer Security (TLS)", RFC 6655, 792 DOI 10.17487/RFC6655, July 2012, 793 . 795 [RFC7250] Wouters, P., Ed., Tschofenig, H., Ed., Gilmore, J., 796 Weiler, S., and T. Kivinen, "Using Raw Public Keys in 797 Transport Layer Security (TLS) and Datagram Transport 798 Layer Security (DTLS)", RFC 7250, DOI 10.17487/RFC7250, 799 June 2014, . 801 [RFC7251] McGrew, D., Bailey, D., Campagna, M., and R. Dugal, "AES- 802 CCM Elliptic Curve Cryptography (ECC) Cipher Suites for 803 TLS", RFC 7251, DOI 10.17487/RFC7251, June 2014, 804 . 806 [RFC7748] Langley, A., Hamburg, M., and S. Turner, "Elliptic Curves 807 for Security", RFC 7748, DOI 10.17487/RFC7748, January 808 2016, . 810 [RFC8032] Josefsson, S. and I. Liusvaara, "Edwards-Curve Digital 811 Signature Algorithm (EdDSA)", RFC 8032, 812 DOI 10.17487/RFC8032, January 2017, 813 . 815 [RFC8392] Jones, M., Wahlstroem, E., Erdtman, S., and H. Tschofenig, 816 "CBOR Web Token (CWT)", RFC 8392, DOI 10.17487/RFC8392, 817 May 2018, . 819 [RFC8422] Nir, Y., Josefsson, S., and M. Pegourie-Gonnard, "Elliptic 820 Curve Cryptography (ECC) Cipher Suites for Transport Layer 821 Security (TLS) Versions 1.2 and Earlier", RFC 8422, 822 DOI 10.17487/RFC8422, August 2018, 823 . 825 Authors' Addresses 827 Stefanie Gerdes 828 Universitaet Bremen TZI 829 Postfach 330440 830 Bremen D-28359 831 Germany 833 Phone: +49-421-218-63906 834 Email: gerdes@tzi.org 835 Olaf Bergmann 836 Universitaet Bremen TZI 837 Postfach 330440 838 Bremen D-28359 839 Germany 841 Phone: +49-421-218-63904 842 Email: bergmann@tzi.org 844 Carsten Bormann 845 Universitaet Bremen TZI 846 Postfach 330440 847 Bremen D-28359 848 Germany 850 Phone: +49-421-218-63921 851 Email: cabo@tzi.org 853 Goeran Selander 854 Ericsson AB 856 Email: goran.selander@ericsson.com 858 Ludwig Seitz 859 RISE SICS 860 Scheelevaegen 17 861 Lund 223 70 862 Sweden 864 Email: ludwig.seitz@ri.se