idnits 2.17.1 draft-ietf-ace-oscore-profile-04.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (October 8, 2018) is 2020 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) == Unused Reference: 'I-D.gerdes-ace-dcaf-authorize' is defined on line 792, but no explicit reference was found in the text == Outdated reference: A later version (-46) exists of draft-ietf-ace-oauth-authz-15 == Outdated reference: A later version (-16) exists of draft-ietf-ace-oauth-params-00 == Outdated reference: A later version (-16) exists of draft-ietf-core-object-security-15 ** Obsolete normative reference: RFC 8152 (Obsoleted by RFC 9052, RFC 9053) == Outdated reference: A later version (-14) exists of draft-selander-ace-cose-ecdhe-10 -- Obsolete informational reference (is this intentional?): RFC 7049 (Obsoleted by RFC 8949) -- Obsolete informational reference (is this intentional?): RFC 7231 (Obsoleted by RFC 9110) Summary: 1 error (**), 0 flaws (~~), 6 warnings (==), 3 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 ACE Working Group F. Palombini 3 Internet-Draft Ericsson AB 4 Intended status: Standards Track L. Seitz 5 Expires: April 11, 2019 RISE SICS AB 6 G. Selander 7 Ericsson AB 8 M. Gunnarsson 9 RISE SICS AB 10 October 8, 2018 12 OSCORE profile of the Authentication and Authorization for Constrained 13 Environments Framework 14 draft-ietf-ace-oscore-profile-04 16 Abstract 18 This memo specifies a profile for the Authentication and 19 Authorization for Constrained Environments (ACE) framework. It 20 utilizes Object Security for Constrained RESTful Environments 21 (OSCORE) to provide communication security, server authentication, 22 and proof-of-possession for a key owned by the client and bound to an 23 OAuth 2.0 access token. 25 Status of This Memo 27 This Internet-Draft is submitted in full conformance with the 28 provisions of BCP 78 and BCP 79. 30 Internet-Drafts are working documents of the Internet Engineering 31 Task Force (IETF). Note that other groups may also distribute 32 working documents as Internet-Drafts. The list of current Internet- 33 Drafts is at https://datatracker.ietf.org/drafts/current/. 35 Internet-Drafts are draft documents valid for a maximum of six months 36 and may be updated, replaced, or obsoleted by other documents at any 37 time. It is inappropriate to use Internet-Drafts as reference 38 material or to cite them other than as "work in progress." 40 This Internet-Draft will expire on April 11, 2019. 42 Copyright Notice 44 Copyright (c) 2018 IETF Trust and the persons identified as the 45 document authors. All rights reserved. 47 This document is subject to BCP 78 and the IETF Trust's Legal 48 Provisions Relating to IETF Documents 49 (https://trustee.ietf.org/license-info) in effect on the date of 50 publication of this document. Please review these documents 51 carefully, as they describe your rights and restrictions with respect 52 to this document. Code Components extracted from this document must 53 include Simplified BSD License text as described in Section 4.e of 54 the Trust Legal Provisions and are provided without warranty as 55 described in the Simplified BSD License. 57 Table of Contents 59 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 60 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3 61 2. Protocol Overview . . . . . . . . . . . . . . . . . . . . . . 3 62 3. Client-AS Communication . . . . . . . . . . . . . . . . . . . 5 63 3.1. C-to-AS: POST /token . . . . . . . . . . . . . . . . . . 5 64 3.2. AS-to-C: Access Token . . . . . . . . . . . . . . . . . . 7 65 4. Client-RS Communication . . . . . . . . . . . . . . . . . . . 11 66 4.1. C-to-RS: POST /authz-info . . . . . . . . . . . . . . . . 12 67 4.2. RS-to-C: 2.01 (Created) . . . . . . . . . . . . . . . . . 12 68 4.3. OSCORE Setup . . . . . . . . . . . . . . . . . . . . . . 13 69 4.4. Access rights verification . . . . . . . . . . . . . . . 15 70 5. Secure Communication with AS . . . . . . . . . . . . . . . . 15 71 6. Security Considerations . . . . . . . . . . . . . . . . . . . 15 72 7. Privacy Considerations . . . . . . . . . . . . . . . . . . . 16 73 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 17 74 9. References . . . . . . . . . . . . . . . . . . . . . . . . . 18 75 9.1. Normative References . . . . . . . . . . . . . . . . . . 18 76 9.2. Informative References . . . . . . . . . . . . . . . . . 19 77 Appendix A. Profile Requirements . . . . . . . . . . . . . . . . 19 78 Appendix B. Using the pop-key with EDHOC (EDHOC+OSCORE) . . . . 20 79 B.1. Using Asymmetric Keys . . . . . . . . . . . . . . . . . . 20 80 B.2. Using Symmetric Keys . . . . . . . . . . . . . . . . . . 22 81 B.3. Processing . . . . . . . . . . . . . . . . . . . . . . . 24 82 Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . 25 83 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 26 85 1. Introduction 87 This memo specifies a profile of the ACE framework 88 [I-D.ietf-ace-oauth-authz]. In this profile, a client and a resource 89 server use CoAP [RFC7252] to communicate. The client uses an access 90 token, bound to a key (the proof-of-possession key) to authorize its 91 access to the resource server. In order to provide communication 92 security, proof of possession, and server authentication they use 93 Object Security for Constrained RESTful Environments (OSCORE) 94 [I-D.ietf-core-object-security]. 96 OSCORE specifies how to use CBOR Object Signing and Encryption (COSE) 97 [RFC8152] to secure CoAP messages. Note that OSCORE can be used to 98 secure CoAP messages, as well as HTTP and combinations of HTTP and 99 CoAP; a profile of ACE similar to the one described in this document, 100 with the difference of using HTTP instead of CoAP as communication 101 protocol, could be specified analogously to this one. 103 1.1. Terminology 105 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 106 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 107 document are to be interpreted as described in [RFC2119]. These 108 words may also appear in this document in lowercase, absent their 109 normative meanings. 111 Certain security-related terms such as "authentication", 112 "authorization", "confidentiality", "(data) integrity", "message 113 authentication code", and "verify" are taken from [RFC4949]. 115 RESTful terminology follows HTTP [RFC7231]. 117 Terminology for entities in the architecture is defined in OAuth 2.0 118 [RFC6749], such as client (C), resource server (RS), and 119 authorization server (AS). It is assumed in this document that a 120 given resource on a specific RS is associated to a unique AS. 122 2. Protocol Overview 124 This section gives an overview on how to use the ACE Framework 125 [I-D.ietf-ace-oauth-authz] to secure the communication between a 126 client and a resource server using OSCORE 127 [I-D.ietf-core-object-security]. The parameters needed by the client 128 to negotiate the use of this profile with the authorization server, 129 as well as OSCORE setup process, are described in detail in the 130 following sections. 132 This profile requires a client to retrieve an access token from the 133 AS for the resource it wants to access on a RS, using the token 134 resource, as specified in section 5.6 of [I-D.ietf-ace-oauth-authz]. 135 To determine the AS in charge of a resource hosted at the RS, the 136 client C MAY send an initial Unauthorized Resource Request message to 137 the RS. The RS then denies the request and sends the address of its 138 AS back to the client C as specified in section 5.1 of 139 [I-D.ietf-ace-oauth-authz]. The access token request and response 140 MUST be confidentiality-protected and ensure authenticity. This 141 profile RECOMMENDS the use of OSCORE between client and AS, but TLS 142 or DTLS MAY be used additionally or instead. 144 Once the client has retrieved the access token, it posts it to the RS 145 using the authz-info resource and mechanisms specified in section 5.8 146 of [I-D.ietf-ace-oauth-authz]. If the access token is valid, the RS 147 replies to this request with a 2.01 (Created) response, which 148 contains a nonce N1. 150 After receiving the nonce N1, the client generates a nonce N2, 151 concatenates it with N1 and sets the ID Context in its Security 152 Context (see section 3 of [I-D.ietf-core-object-security]) to N1 153 concatenated with N2. The client then derives the complete Security 154 Context from the ID Context plus the parameters received from the AS. 156 Finally, the client sends a request protected with OSCORE to the RS. 157 This message contains the ID Context value. When receiving this 158 request after the 2.01 (Created) response, the server extract the ID 159 Context from it, verifies that the first part is equal to the nonce 160 N1 it previously sent, and if so, sets its own ID Context and derives 161 the complete Security Context from it plus the parameters received in 162 the AS, following section 3.2 of [I-D.ietf-core-object-security]. If 163 the request verifies, then this Security Context is stored in the 164 server, and used in the response, and in further communications with 165 the client, until token expiration. Once the client receives a valid 166 response, it does not continue to include the ID Context value in 167 further requests. 169 An overview of the profile flow for the OSCORE profile is given in 170 Figure 1. 172 C RS AS 173 | [-- Resource Request --->] | | 174 | | | 175 | [<----- AS Information --] | | 176 | | | 177 | ----- POST /token ----------------------------> | 178 | | | 179 | <---------------------------- Access Token ----- | 180 | + RS Information | 181 | ---- POST /authz-info ---> | | 182 | | | 183 | <--- 2.01 Created (N1) --- | | 184 | | | 185 /Sec Context Derivation/ | | 186 | | | 187 | ---- OSCORE Request -----> | | 188 | (N1, N2) | | 189 | | | 190 | /Sec Context Derivation/ | 191 | | | 192 | <--- OSCORE Response ----- | | 193 | | | 194 | ---- OSCORE Request -----> | | 195 | | | 196 | <--- OSCORE Response ----- | | 197 | ... | | 199 Figure 1: Protocol Overview 201 3. Client-AS Communication 203 The following subsections describe the details of the POST /token 204 request and response between client and AS. Section 3.2 of 205 [I-D.ietf-core-object-security] defines how to derive a Security 206 Context based on a shared master secret and a set of other 207 parameters, established between client and server, which the client 208 receives from the AS in this exchange. The proof-of-possession key 209 (pop-key) provisioned from the AS MUST be used as master secret in 210 OSCORE. 212 3.1. C-to-AS: POST /token 214 The client-to-AS request is specified in Section 5.6.1 of 215 [I-D.ietf-ace-oauth-authz]. 217 The client MUST send this POST /token request over a secure channel 218 that guarantees authentication, message integrity and confidentiality 219 (see Section 5). 221 An example of such a request, in CBOR diagnostic notation without the 222 tag and value abbreviations is reported in Figure 2 224 Header: POST (Code=0.02) 225 Uri-Host: "as.example.com" 226 Uri-Path: "token" 227 Content-Format: "application/ace+cbor" 228 Payload: 229 { 230 "grant_type" : "client_credentials", 231 "client_id" : "myclient", 232 "req_aud" : "tempSensor4711", 233 "scope" : "read" 234 } 236 Figure 2: Example C-to-AS POST /token request for an access token 237 bound to a symmetric key. 239 If the client wants to update its access rights without changing an 240 existing OSCORE Security Context, it MUST include in its POST /token 241 request a req_cnf object carrying the client's identifier (that was 242 assigned in section Section 3.2) in the kid field. This identifier 243 can be used by the AS to determine the shared secret to construct the 244 proof-of-possession token and therefore MUST identify a symmetric key 245 that was previously generated by the AS as a shared secret for the 246 communication between the client and the RS. The AS MUST verify that 247 the received value identifies a proof-of-possession key and token 248 that have previously been issued to the requesting client. If that 249 is not the case, the Client-to-AS request MUST be declined with the 250 error code 'invalid_request' as defined in Section 5.6.3 of 251 [I-D.ietf-ace-oauth-authz]. 253 An example of such a request, in CBOR diagnostic notation without the 254 tag and value abbreviations is reported in Figure 3 255 Header: POST (Code=0.02) 256 Uri-Host: "as.example.com" 257 Uri-Path: "token" 258 Content-Format: "application/ace+cbor" 259 Payload: 260 { 261 "grant_type" : "client_credentials", 262 "client_id" : "myclient", 263 "req_aud" : "tempSensor4711", 264 "scope" : "write", 265 "req_cnf" : { 266 "kid" : b64'Qg' 267 } 269 Figure 3: Example C-to-AS POST /token request for updating rights to 270 an access token bound to a symmetric key. 272 3.2. AS-to-C: Access Token 274 After verifying the POST /token request and that the client is 275 authorized to obtain an access token corresponding to its access 276 token request, the AS responds as defined in section 5.6.2 of 277 [I-D.ietf-ace-oauth-authz]. If the client request was invalid, or 278 not authorized, the AS returns an error response as described in 279 section 5.6.3 of [I-D.ietf-ace-oauth-authz]. 281 The AS signals that the use of OSCORE is REQUIRED for a specific 282 access token by including the "profile" parameter with the value 283 "coap_oscore" in the access token response. This means that the 284 client MUST use OSCORE towards all resource servers for which this 285 access token is valid, and follow Section 4.3 to derive the security 286 context to run OSCORE. 288 Moreover, the AS MUST provision the following data: 290 o a master secret 292 o a client identifier 294 o a server identifier 296 Additionally, the AS MAY provision the following data, in the same 297 response. 299 o an AEAD algorithm 301 o an HKDF algorithm 302 o a salt 304 o a replay window type and size 306 The master secret MUST be communicated as COSE_Key in the 'cnf' 307 parameter of the access token response as defined in Section 3.2 of 308 [I-D.ietf-ace-oauth-params]. The AEAD algorithm MAY be included as 309 the 'alg' parameter in the COSE_Key; the HKDF algorithm MAY be 310 included as the 'hkdf' parameter of the COSE_Key and the salt MAY be 311 included as the 'slt' parameter of the COSE_Key as defined in 312 Figure 4. 314 The same parameters MUST be included as metadata of the access token. 315 This profile RECOMMENDS the use of CBOR web token (CWT) as specified 316 in [RFC8392]. If the token is a CWT, the same COSE_Key structure 317 defined above MUST be placed in the 'cnf' claim of this token. 319 The AS MUST also assign identifiers to both client and RS, which are 320 then used as Sender ID and Recipient ID in the OSCORE context as 321 described in section 3.1 of [I-D.ietf-core-object-security]. These 322 identifiers MUST be unique in the set of all clients and RS 323 identifiers for a certain AS. Moreover, these MUST be included in 324 the COSE_Key as header parameters, as defined in Figure 4. 326 We assume in this document that a resource is associated to one 327 single AS, which makes it possible to assume unique identifiers for 328 each client requesting a particular resource to a RS. If this is not 329 the case, collisions of identifiers may appear in the RS, in which 330 case the RS needs to have a mechanism in place to disambiguate 331 identifiers or mitigate their effect. 333 Note that in Section 4.3 C sets the Sender ID of its Security Context 334 to the clientId value received and the Recipient ID to the serverId 335 value, and RS does the opposite. 337 +----------+-------+--------------+------------+-------------------+ 338 | name | label | CBOR type | registry | description | 339 +----------+-------+--------------+------------+-------------------+ 340 | clientId | TBD1 | bstr | | Identifies the | 341 | | | | | client in an | 342 | | | | | OSCORE context | 343 | | | | | using this key | 344 | | | | | | 345 | serverId | TBD2 | bstr | | Identifies the | 346 | | | | | server in an | 347 | | | | | OSCORE context | 348 | | | | | using this key | 349 | | | | | | 350 | hkdf | TBD3 | bstr | | Identifies the | 351 | | | | | KDF algorithm in | 352 | | | | | an OSCORE context | 353 | | | | | using this key | 354 | | | | | | 355 | slt | TBD4 | bstr | | Identifies the | 356 | | | | | master salt in | 357 | | | | | an OSCORE context | 358 | | | | | using this key | 359 +----------+-------+--------------+------------+-------------------+ 361 Figure 4: Additional COSE_Key Common Parameters 363 Figure 5 shows an example of such an AS response, in CBOR diagnostic 364 notation without the tag and value abbreviations. 366 Header: Created (Code=2.01) 367 Content-Type: "application/cose+cbor" 368 Payload: 369 { 370 "access_token" : b64'SlAV32hkKG ... 371 (remainder of access token omitted for brevity)', 372 "profile" : "coap_oscore", 373 "expires_in" : "3600", 374 "cnf" : { 375 "COSE_Key" : { 376 "kty" : "Symmetric", 377 "alg" : "AES-CCM-16-64-128", 378 "clientId" : b64'qA', 379 "serverId" : b64'Qg', 380 "k" : b64'+a+Dg2jjU+eIiOFCa9lObw' 381 } 382 } 383 } 385 Figure 5: Example AS-to-C Access Token response with OSCORE profile. 387 Figure 6 shows an example CWT, containing the necessary OSCORE 388 parameters in the 'cnf' claim, in CBOR diagnostic notation without 389 tag and value abbreviations. 391 { 392 "aud" : "tempSensorInLivingRoom", 393 "iat" : "1360189224", 394 "exp" : "1360289224", 395 "scope" : "temperature_g firmware_p", 396 "cnf" : { 397 "COSE_Key" : { 398 "kty" : "Symmetric", 399 "alg" : "AES-CCM-16-64-128", 400 "clientId" : b64'Qg', 401 "serverId" : b64'qA', 402 "k" : b64'+a+Dg2jjU+eIiOFCa9lObw' 403 } 404 } 406 Figure 6: Example CWT with OSCORE parameters. 408 If the client has requested an update to its access rights using the 409 same OSCORE Security Context, which is valid and authorized, the AS 410 MUST omit the 'cnf' parameter in the response, and MUST carry the 411 client identifier in the 'kid' field in the 'cnf' parameter of the 412 token. The client identifier needs to be provisioned, in order for 413 the RS to identify the previously generated Security Context. 415 Figure 7 shows an example of such an AS response, in CBOR diagnostic 416 notation without the tag and value abbreviations. 418 Header: Created (Code=2.01) 419 Content-Type: "application/cose+cbor" 420 Payload: 421 { 422 "access_token" : b64'SlAV32hkKG ... 423 (remainder of access token omitted for brevity)', 424 "profile" : "coap_oscore", 425 "expires_in" : "3600" 426 } 428 Figure 7: Example AS-to-C Access Token response with OSCORE profile, 429 for update of access rights. 431 Figure 8 shows an example CWT, containing the necessary OSCORE 432 parameters in the 'cnf' claim for update of access rights, in CBOR 433 diagnostic notation without tag and value abbreviations. 435 { 436 "aud" : "tempSensorInLivingRoom", 437 "iat" : "1360189224", 438 "exp" : "1360289224", 439 "scope" : "temperature_h", 440 "cnf" : { 441 "kid" : b64'Qg' 442 } 443 } 445 Figure 8: Example CWT with OSCORE parameters for update of access 446 rights. 448 4. Client-RS Communication 450 The following subsections describe the details of the POST /authz- 451 info request and response between client and RS. The client posts 452 the token that includes the materials provisioned by the AS to the 453 RS, which can then use Section 3.2 of [I-D.ietf-core-object-security] 454 to derive a security context based on a shared master secret and a 455 set of other parameters, established between client and server. 457 Note that the proof-of-possession required to bind the access token 458 to the client is implicitly performed by generating the shared OSCORE 459 Security Context using the pop-key as master secret, for both client 460 and RS. An attacker using a stolen token will not be able to 461 generate a valid OSCORE context and thus not be able to prove 462 possession of the pop-key. 464 4.1. C-to-RS: POST /authz-info 466 The client MUST use CoAP and the Authorization Information resource 467 as described in section 5.8.1 of [I-D.ietf-ace-oauth-authz] to 468 transport the token to the RS. 470 The authz-info resource is not protected, nor are the responses from 471 this resource. 473 The access token MUST be encrypted, since it is transferred from the 474 client to the RS over an unprotected channel. 476 Note that a client may be required to re-POST the access token, since 477 an RS may delete a stored access token, due to lack of memory. 479 Figure 9 shows an example of the request sent from the client to the 480 RS. 482 Header: POST (Code=0.02) 483 Uri-Host: "rs.example.com" 484 Uri-Path: "authz-info" 485 Content-Format: "application/cwt" 486 Payload: 487 b64'SlAV32hkKG ... 488 (remainder of access token omitted for brevity)', 490 Figure 9: Example C-to-RS POST /authz-info request using CWT 492 4.2. RS-to-C: 2.01 (Created) 494 The RS MUST follow the procedures defined in section 5.8.1 of 495 [I-D.ietf-ace-oauth-authz]: the RS MUST verify the validity of the 496 token. If the token is valid, the RS MUST respond to the POST 497 request with 2.01 (Created). If the token is valid but is associated 498 to claims that the RS cannot process (e.g., an unknown scope) the RS 499 MUST respond with a response code equivalent to the CoAP code 4.00 500 (Bad Request). In the latter case the RS MAY provide additional 501 information in the error response, in order to clarify what went 502 wrong. The RS MAY make an introspection request to validate the 503 token before responding to the POST request to the authz-info 504 resource. 506 Additionally, the RS MUST generate a nonce (N1) with a good amount of 507 randomness, and include it in the payload of the 2.01 (Created) 508 response as a CBOR byte string. This profile RECOMMENDS to use a 509 nonce of 64 bits. The RS MUST store this nonce as long as the access 510 token related to it is still valid. 512 Note that, when using this profile, an identifier of the token (e.g., 513 the cti for a CWT) is not transported in the payload of this request, 514 as section 5.8.1 of [I-D.ietf-ace-oauth-authz] allows. 516 Figure 10 shows an example of the response sent from the RS to the 517 client. 519 Header: Created (Code=2.01) 520 Content-Format: "application/cbor" 521 Payload: 522 h'018a278f7faab55a', 524 Figure 10: Example RS-to-C 2.01 (Created) response 526 When receiving an updated access token with updated authorization 527 information from the client (see section Section 3.1), it is 528 RECOMMENDED that the RS overwrites the previous token, that is only 529 the latest authorization information in the token received by the RS 530 is valid. This simplifies for the RS to keep track of authorization 531 information for a given client. 533 As specified in section 5.8.3 of [I-D.ietf-ace-oauth-authz], the RS 534 MUST notify the client with an error response with code 4.01 535 (Unauthorized) for any long running request before terminating the 536 session, when the access token expires. 538 4.3. OSCORE Setup 540 Once receiving the 2.01 (Created) response from the RS, following the 541 POST /authz-info request, the client MUST extract the nonce N1 from 542 the CBOR byte string in the payload of the response. The client MUST 543 generate itself a nonce (N2) with a good amount of randomness. This 544 profile RECOMMENDS to use a nonce of 64 bits. Then, the client MUST 545 set the ID Context of the Security Context created to communicate 546 with the RS to the concatenation of N1 and N2, in this order: ID 547 Context = N1 | N2, where | denotes byte string concatenation. The 548 client MUST set the Master Secret, Sender ID and Recipient ID from 549 the parameters received from the AS in Section 3.2. The client MUST 550 set the AEAD Algorithm, Master Salt, HKDF and Replay Window from the 551 parameters received from the AS in Section 3.2, if present. In case 552 these parameters are omitted, the default values are used as 553 described in section 3.2 of [I-D.ietf-core-object-security]. After 554 that, the client MUST derive the complete Security Context following 555 section 3.2.1 of [I-D.ietf-core-object-security]. From this point 556 on, the client MUST use this Security Context to communicate with the 557 RS when accessing the resources as specified by the authorization 558 information. 560 The client then uses this Security Context to send requests to RS 561 using OSCORE. In the first request sent to the RS, the client MUST 562 include the kid context, with value ID Context, i.e. N1 concatenated 563 with N2. The client needs to make sure the RS receives the kid 564 context, possibly adding the kid context to later requests, until it 565 receives a valid OSCORE response from the RS using the same Security 566 Context. 568 When the RS receives this first OSCORE-protected request, it MUST 569 extract the kid context from the message first. Then, it needs to 570 verify that the first part of the kid context corresponds to the 571 nonce N1 it previously sent, and that it is followed by a non-zero- 572 length byte string. If that is verified, the RS MUST set the ID 573 Context to the kid context value. Then, the RS MUST set the Master 574 Secret, Sender ID and Recipient ID from the parameters received from 575 the client in the access token in Section 4.1. The RS MUST set the 576 AEAD Algorithm, Master Salt, HKDF and Replay Window from the 577 parameters received from the client in the access token in 578 Section 4.1, if present. In case these parameters are omitted, the 579 default values are used as described in section 3.2 of 580 [I-D.ietf-core-object-security]. After that, the RS MUST derive the 581 complete Security Context following section 3.2.1 of 582 [I-D.ietf-core-object-security], and MUST associate this Security 583 Context with the authorization information from the access token. 584 Then, the RS MUST delete the nonce N1 from memory. 586 The RS then uses this Security Context to verify the request and send 587 responses to RS using OSCORE. If OSCORE verification fails, error 588 responses are used, as specified in section 8 of 589 [I-D.ietf-core-object-security]. Additionally, if OSCORE 590 verification succeeds, the verification of access rights is performed 591 as described in section Section 4.4. The RS MUST NOT use the 592 Security Context after the related token has expired, and MUST 593 respond with a unprotected 4.01 (Unauthorized) error message. 595 4.4. Access rights verification 597 The RS MUST follow the procedures defined in section 5.8.2 of 598 [I-D.ietf-ace-oauth-authz]: if an RS receives an OSCORE-protected 599 request from a client, then it processes according to 600 [I-D.ietf-core-object-security]. If OSCORE verification succeeds, 601 and the target resource requires authorization, the RS retrieves the 602 authorization information from the access token associated to the 603 Security Context. The RS then MUST verify that the authorization 604 information covers the resource and the action requested. 606 The response code MUST be 4.01 (Unauthorized) in case the client has 607 not used the Security Context associated with the access token, or if 608 RS has no valid access token for the client. If RS has an access 609 token for the client but not for the resource that was requested, RS 610 MUST reject the request with a 4.03 (Forbidden). If RS has an access 611 token for the client but it does not cover the action that was 612 requested on the resource, RS MUST reject the request with a 4.05 613 (Method Not Allowed). 615 5. Secure Communication with AS 617 As specified in the ACE framework (section 5.7 of 618 [I-D.ietf-ace-oauth-authz]), the requesting entity (RS and/or client) 619 and the AS communicates via the introspection or token resource. The 620 use of CoAP and OSCORE for this communication is RECOMMENDED in this 621 profile, other protocols (such as HTTP and DTLS or TLS) MAY be used 622 instead. 624 If OSCORE is used, the requesting entity and the AS are expected to 625 have pre-established security contexts in place. How these security 626 contexts are established is out of scope for this profile. 627 Furthermore the requesting entity and the AS communicate using OSCORE 628 ([I-D.ietf-core-object-security]) through the introspection resource 629 as specified in section 5.7 of [I-D.ietf-ace-oauth-authz] and through 630 the token resource as specified in section 5.6 of 631 [I-D.ietf-ace-oauth-authz]. 633 6. Security Considerations 635 This document specifies a profile for the Authentication and 636 Authorization for Constrained Environments (ACE) framework 637 [I-D.ietf-ace-oauth-authz]. Thus the general security considerations 638 from the framework also apply to this profile. 640 Furthermore the general security considerations of OSCORE 641 [I-D.ietf-core-object-security] also apply to this specific use of 642 the OSCORE protocol. 644 OSCORE is designed to secure point-to-point communication, providing 645 a secure binding between the request and the response(s). Thus the 646 basic OSCORE protocol is not intended for use in point-to-multipoint 647 communication (e.g. multicast, publish-subscribe). Implementers of 648 this profile should make sure that their usecase corresponds to the 649 expected use of OSCORE, to prevent weakening the security assurances 650 provided by OSCORE. 652 The use of nonces during the OSCORE Setup Section 4.3 prevents the 653 reuse of AEAD nonces in the RS Security Context, in case the RS loses 654 the Security Context associated with a client (e.g. in case of 655 unplanned reboot) and receives a replayed access token. In fact, by 656 using random nonces as ID Context, the POST /auth-info request 657 results in a different Security Context, since Master Secret, Sender 658 ID and Recipient ID are the same but ID Context is different. 659 Therefore, the main requirement for the nonces is that they have a 660 good amount of randomness. Moreover, the client echoes the nonce 661 created by the RS, which verifies it before deriving the Security 662 Context, and this protects against an adversary acting as a Man-in- 663 the-Middle and substituting the nonce in transit from client to RS to 664 provoke the creation of different Security Contexts in the client and 665 RS. 667 This profiles recommends that the RS maintains a single access token 668 for a client. The use of multiple access tokens for a single client 669 increases the strain on the resource server as it must consider every 670 access token and calculate the actual permissions of the client. 671 Also, tokens may contradict each other which may lead the server to 672 enforce wrong permissions. If one of the access tokens expires 673 earlier than others, the resulting permissions may offer insufficient 674 protection. Developers should avoid using multiple access tokens for 675 a client. 677 7. Privacy Considerations 679 This document specifies a profile for the Authentication and 680 Authorization for Constrained Environments (ACE) framework 681 [I-D.ietf-ace-oauth-authz]. Thus the general privacy considerations 682 from the framework also apply to this profile. 684 As this document uses OSCORE, thus the privacy considerations from 685 [I-D.ietf-core-object-security] apply here as well. 687 An unprotected response to an unauthorized request may disclose 688 information about the resource server and/or its existing 689 relationship with the client. It is advisable to include as little 690 information as possible in an unencrypted response. When an OSCORE 691 Security Context already exists between the client and the resource 692 server, more detailed information may be included. 694 Note that some information might still leak after OSCORE is 695 established, due to observable message sizes, the source, and the 696 destination addresses. 698 8. IANA Considerations 700 Note to RFC Editor: Please replace all occurrences of "[[this 701 specification]]" with the RFC number of this specification and delete 702 this paragraph. 704 The following registration is done for the ACE OAuth Profile Registry 705 following the procedure specified in section 8.7 of 706 [I-D.ietf-ace-oauth-authz]: 708 o Profile name: coap_oscore 709 o Profile Description: Profile for using OSCORE to secure 710 communication between constrained nodes using the Authentication 711 and Authorization for Constrained Environments framework. 712 o Profile ID: TBD (value between 1 and 255) 713 o Change Controller: IESG 714 o Specification Document(s): [[this specification]] 716 The following registrations are done for the COSE Key Common 717 Parameter Registry specified in section 16.5 of [RFC8152]: 719 o Name: clientId 720 o Label: TBD1 (value between 1 and 255) 721 o CBOR Type: bstr 722 o Value Registry: N/A 723 o Description: Identifies the client in an OSCORE context 724 o Reference: [[this specification]] 726 o Name: serverId 727 o Label: TBD2 (value between 1 and 255) 728 o Value Type: bstr 729 o Value Registry: N/A 730 o Description: Identifies the server in an OSCORE context 731 o Reference: [[this specification]] 733 o Name: hkdf 734 o Label: TBD3 (value between 1 and 255) 735 o Value Type: bstr 736 o Value Registry: COSE Algorithms registry 737 o Description: Identifies the KDF algorithm to be used in an OSCORE 738 context 740 o Reference: [[this specification]] 742 o Name: slt 743 o Label: TBD4 (value between 1 and 255) 744 o Value Type: bstr 745 o Value Registry: N/A 746 o Description: Identifies the master salt of to be used in an OSCORE 747 context 748 o Reference: [[this specification]] 750 9. References 752 9.1. Normative References 754 [I-D.ietf-ace-oauth-authz] 755 Seitz, L., Selander, G., Wahlstroem, E., Erdtman, S., and 756 H. Tschofenig, "Authentication and Authorization for 757 Constrained Environments (ACE) using the OAuth 2.0 758 Framework (ACE-OAuth)", draft-ietf-ace-oauth-authz-15 759 (work in progress), September 2018. 761 [I-D.ietf-ace-oauth-params] 762 Seitz, L., "Additional OAuth Parameters for Authorization 763 in Constrained Environments (ACE)", draft-ietf-ace-oauth- 764 params-00 (work in progress), September 2018. 766 [I-D.ietf-core-object-security] 767 Selander, G., Mattsson, J., Palombini, F., and L. Seitz, 768 "Object Security for Constrained RESTful Environments 769 (OSCORE)", draft-ietf-core-object-security-15 (work in 770 progress), August 2018. 772 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 773 Requirement Levels", BCP 14, RFC 2119, 774 DOI 10.17487/RFC2119, March 1997, 775 . 777 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 778 Application Protocol (CoAP)", RFC 7252, 779 DOI 10.17487/RFC7252, June 2014, 780 . 782 [RFC8152] Schaad, J., "CBOR Object Signing and Encryption (COSE)", 783 RFC 8152, DOI 10.17487/RFC8152, July 2017, 784 . 786 [RFC8392] Jones, M., Wahlstroem, E., Erdtman, S., and H. Tschofenig, 787 "CBOR Web Token (CWT)", RFC 8392, DOI 10.17487/RFC8392, 788 May 2018, . 790 9.2. Informative References 792 [I-D.gerdes-ace-dcaf-authorize] 793 Gerdes, S., Bergmann, O., and C. Bormann, "Delegated CoAP 794 Authentication and Authorization Framework (DCAF)", draft- 795 gerdes-ace-dcaf-authorize-04 (work in progress), October 796 2015. 798 [I-D.selander-ace-cose-ecdhe] 799 Selander, G., Mattsson, J., and F. Palombini, "Ephemeral 800 Diffie-Hellman Over COSE (EDHOC)", draft-selander-ace- 801 cose-ecdhe-10 (work in progress), September 2018. 803 [RFC4949] Shirey, R., "Internet Security Glossary, Version 2", 804 FYI 36, RFC 4949, DOI 10.17487/RFC4949, August 2007, 805 . 807 [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", 808 RFC 6749, DOI 10.17487/RFC6749, October 2012, 809 . 811 [RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object 812 Representation (CBOR)", RFC 7049, DOI 10.17487/RFC7049, 813 October 2013, . 815 [RFC7231] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 816 Protocol (HTTP/1.1): Semantics and Content", RFC 7231, 817 DOI 10.17487/RFC7231, June 2014, 818 . 820 Appendix A. Profile Requirements 822 This section lists the specifications on this profile based on the 823 requirements on the framework, as requested in Appendix C of 824 [I-D.ietf-ace-oauth-authz]. 826 o (Optional) discovery process of how the client finds the right AS 827 for an RS it wants to send a request to: Not specified 828 o communication protocol the client and the RS must use: CoAP 829 o security protocol the client and RS must use: OSCORE 830 o how the client and the RS mutually authenticate: Implicitly by 831 possession of a common OSCORE security context 832 o Content-format of the protocol messages: "application/cose+cbor" 833 o proof-of-possession protocol(s) and how to select one; which key 834 types (e.g. symmetric/asymmetric) supported: OSCORE algorithms; 835 pre-established symmetric keys 836 o profile identifier: coap_oscore 837 o (Optional) how the RS talks to the AS for introspection: HTTP/CoAP 838 (+ TLS/DTLS/OSCORE) 839 o how the client talks to the AS for requesting a token: HTTP/CoAP 840 (+ TLS/DTLS/OSCORE) 841 o how/if the /authz-info endpoint is protected: Security protocol 842 above 843 o (Optional)other methods of token transport than the /authz-info 844 endpoint: no 846 Appendix B. Using the pop-key with EDHOC (EDHOC+OSCORE) 848 EDHOC specifies an authenticated Diffie-Hellman protocol that allows 849 two parties to use CBOR [RFC7049] and COSE in order to establish a 850 shared secret key with perfect forward secrecy. The use of Ephemeral 851 Diffie-Hellman Over COSE (EDHOC) [I-D.selander-ace-cose-ecdhe] in 852 this profile in addition to OSCORE, provides perfect forward secrecy 853 (PFS) and the initial proof-of-possession, which ties the proof-of- 854 possession key to an OSCORE security context. 856 If EDHOC is used together with OSCORE, and the pop-key (symmetric or 857 asymmetric) is used to authenticate the messages in EDHOC, then the 858 AS MUST provision the following data, in response to the access token 859 request: 861 o a symmetric or public key (associated to the RS) 862 o a key identifier; 864 How these parameters are communicated depends on the type of key 865 (asymmetric or symmetric). Moreover, the AS MUST signal the use of 866 OSCORE + EDHOC with the 'profile' parameter set to 867 "coap_oscore_edhoc". 869 Note that in the case described in this section, the 'expires_in' 870 parameter, defined in Section 4.2.2. of [RFC6749] defines the 871 lifetime in seconds of both the access token and the shared secret. 872 After expiration, C MUST acquire a new access token from the AS, and 873 run EDHOC again, as specified in this section 875 B.1. Using Asymmetric Keys 877 In case of an asymmetric key, C MUST communicate its own asymmetric 878 key to the AS in the 'req_cnf' parameter of the access token request, 879 as specified in Section 3.1 of [I-D.ietf-ace-oauth-params]; the AS 880 MUST communicate the RS's public key to C in the response, in the 881 'rs_cnf' parameter, as specified in Section 3.2 of 882 [I-D.ietf-ace-oauth-params]. Note that the RS's public key MUST 883 include a 'kid' parameter, and that the value of the 'kid' MUST be 884 included in the access token, to let the RS know which of its public 885 keys C used. If the access token is a CWT [RFC8392], the key 886 identifier MUST be placed directly in the 'cnf' structure (if the key 887 is only referenced). 889 Figure 3 shows an example of such a request in CBOR diagnostic 890 notation without tag and value abbreviations. 892 Header: POST (Code=0.02) 893 Uri-Host: "server.example.com" 894 Uri-Path: "token" 895 Content-Type: "application/cose+cbor" 896 Payload: 897 { 898 "grant_type" : "client_credentials", 899 "req_cnf" : { 900 "COSE_Key" : { 901 "kid" : "client_key" 902 "kty" : "EC", 903 "crv" : "P-256", 904 "x" : b64'usWxHK2PmfnHKwXPS54m0kTcGJ90UiglWiGahtagnv8', 905 "y" : b64'IBOL+C3BttVivg+lSreASjpkttcsz+1rb7btKLv8EX4' 906 } 907 } 908 } 910 Figure 3: Example access token request (OSCORE+EDHOC, asymmetric). 912 Figure 4 shows an example of a corresponding response in CBOR 913 diagnostic notation without tag and value abbreviations. 915 Header: Created (Code=2.01) 916 Content-Type: "application/cose+cbor" 917 Payload: 918 { 919 "access_token" : b64'SlAV32hkKG ... 920 (contains "kid" : "client_key")', 921 "profile" : "coap_oscore_edhoc", 922 "expires_in" : "3600", 923 "cnf" : { 924 "COSE_Key" : { 925 "kid" : "server_key" 926 "kty" : "EC", 927 "crv" : "P-256", 928 "x" : b64'cGJ90UiglWiGahtagnv8usWxHK2PmfnHKwXPS54m0kT', 929 "y" : b64'reASjpkttcsz+1rb7btKLv8EX4IBOL+C3BttVivg+lS' 930 } 931 } 932 } 934 Figure 4: Example AS response (EDHOC+OSCORE, asymmetric). 936 B.2. Using Symmetric Keys 938 In the case of a symmetric key, the AS MUST communicate the key to 939 the client in the 'cnf' parameter of the access token response, as 940 specified in Section 3.2. of [I-D.ietf-ace-oauth-params]. The AS 941 MUST also select a key identifier, that MUST be included as the 'kid' 942 parameter of the COSE_key, as in figure 9 of 943 [I-D.ietf-ace-oauth-authz]. 945 Figure 5 shows an example of the necessary parameters in the AS 946 response to the access token request when EDHOC is used. The example 947 uses CBOR diagnostic notation without tag and value abbreviations. 949 Header: Created (Code=2.01) 950 Content-Type: "application/cose+cbor" 951 Payload: 952 { 953 "access_token" : b64'SlAV32hkKG ... 954 (remainder of access token omitted for brevity)', 955 "profile" : "coap_oscore_edhoc", 956 "expires_in" : "3600", 957 "cnf" : { 958 "COSE_Key" : { 959 "kty" : "Symmetric", 960 "kid" : b64'5tOS+h42dkw', 961 "k" : b64'+a+Dg2jjU+eIiOFCa9lObw' 962 } 963 } 964 } 966 Figure 5: Example AS response (EDHOC+OSCORE, symmetric). 968 In both cases, the AS MUST also include the same key identifier as 969 'kid' parameter in the access token metadata. If the access token is 970 a CWT [RFC8392], the key identifier MUST be placed inside the 'cnf' 971 claim as 'kid' parameter of the COSE_Key or directly in the 'cnf' 972 structure (if the key is only referenced). 974 Figure 6 shows an example CWT containing the necessary EDHOC+OSCORE 975 parameters in the 'cnf' claim, in CBOR diagnostic notation without 976 tag and value abbreviations. 978 { 979 "aud" : "tempSensorInLivingRoom", 980 "iat" : "1360189224", 981 "exp" : "1360289224", 982 "scope" : "temperature_g firmware_p", 983 "cnf" : { 984 "COSE_Key" : { 985 "kty" : "Symmetric", 986 "kid" : b64'5tOS+h42dkw', 987 "k" : b64'+a+Dg2jjU+eIiOFCa9lObw' 988 } 989 } 991 Figure 6: Example CWT with EDHOC+OSCORE, symmetric case. 993 All other parameters defining OSCORE security context are derived 994 from EDHOC message exchange, including the master secret (see 995 Appendix D.2 of [I-D.selander-ace-cose-ecdhe]). 997 B.3. Processing 999 To provide forward secrecy and mutual authentication in the case of 1000 pre-shared keys, pre-established raw public keys or with X.509 1001 certificates it is RECOMMENDED to use EDHOC 1002 [I-D.selander-ace-cose-ecdhe] to generate the keying material. EDHOC 1003 MUST be used as defined in Appendix D of 1004 [I-D.selander-ace-cose-ecdhe], with the following additions and 1005 modifications. 1007 The first EDHOC message is sent after the access token is posted to 1008 the /authz-info resource of the RS as specified in Section 5.8.1 of 1009 [I-D.ietf-ace-oauth-authz]. Then the EDHOC message_1 is sent and the 1010 EDHOC protocol is initiated [I-D.selander-ace-cose-ecdhe]). 1012 Before the RS continues with the EDHOC protocol and responds to this 1013 token submission request, additional verifications on the access 1014 token are done: the RS SHALL process the access token according to 1015 [I-D.ietf-ace-oauth-authz]. If the token is valid then the RS 1016 continues processing EDHOC following Appendix D of 1017 [I-D.selander-ace-cose-ecdhe], otherwise it discontinues EDHOC and 1018 responds with the error code as specified in 1019 [I-D.ietf-ace-oauth-authz]. 1021 o In case the EDHOC verification fails, the RS MUST return an error 1022 response to the client with code 4.01 (Unauthorized). 1023 o If RS has an access token for C but not for the resource that C 1024 has requested, RS MUST reject the request with a 4.03 (Forbidden). 1025 o If RS has an access token for C but it does not cover the action C 1026 requested on the resource, RS MUST reject the request with a 4.05 1027 (Method Not Allowed). 1028 o If all verifications above succeeds, further communication between 1029 client and RS is protected with OSCORE, including the RS response 1030 to the OSCORE request. 1032 In the case of EDHOC being used with symmetric keys, the protocol in 1033 Section 5 of [I-D.selander-ace-cose-ecdhe] MUST be used. If the key 1034 is asymmetric, the RS MUST also use an asymmetric key for 1035 authentication. This key is known to the client through the access 1036 token response (see Section 5.6.2 of [I-D.ietf-ace-oauth-authz]). In 1037 this case the protocol in Section 4 of [I-D.selander-ace-cose-ecdhe] 1038 MUST be used. 1040 Figure 7 illustrates the message exchanges for using OSCORE+EDHOC 1041 (step C in figure 1 of [I-D.ietf-ace-oauth-authz]). 1043 Resource 1044 Client Server 1045 | | 1046 | | 1047 +--------->| Header: POST (Code=0.02) 1048 | POST | Uri-Path:"authz-info" 1049 | | Content-Type: application/cbor 1050 | | Payload: access token 1051 | | 1052 | | 1053 +--------->| Header: POST (Code=0.02) 1054 | POST | Uri-Path: "/.well-known/edhoc" 1055 | | Content-Type: application/edhoc 1056 | | Payload: EDHOC message_1 1057 | | 1058 |<---------+ Header: 2.04 Changed 1059 | 2.04 | Content-Type: application/edhoc 1060 | | Payload: EDHOC message_2 1061 | | 1062 +--------->| Header: POST (Code=0.02) 1063 | POST | Uri-Path: "/.well-known/edhoc" 1064 | | Content-Type: application/edhoc 1065 | | Payload: EDHOC message_3 1066 | | 1067 |<---------+ Header: 2.04 Changed 1068 | 2.04 | 1069 | | 1070 start of protected communication 1071 | | 1072 +--------->| CoAP request + 1073 | OSCORE | Object-Security option 1074 | request | 1075 | | 1076 |<---------+ CoAP response + 1077 | OSCORE | Object-Security option 1078 | response | 1079 | | 1081 Figure 7: Access token and key establishment with EDHOC 1083 Acknowledgments 1085 The authors wish to thank Jim Schaad and Marco Tiloca for the input 1086 on this memo. 1088 Authors' Addresses 1090 Francesca Palombini 1091 Ericsson AB 1093 Email: francesca.palombini@ericsson.com 1095 Ludwig Seitz 1096 RISE SICS AB 1097 Scheelevagen 17 1098 Lund 22370 1099 Sweden 1101 Email: ludwig.seitz@ri.se 1103 Goeran Selander 1104 Ericsson AB 1106 Email: goran.selander@ericsson.com 1108 Martin Gunnarsson 1109 RISE SICS AB 1110 Scheelevagen 17 1111 Lund 22370 1112 Sweden 1114 Email: martin.gunnarsson@ri.se