idnits 2.17.1 draft-seitz-ace-oscoap-profile-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 (October 25, 2017) is 2374 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) == Outdated reference: A later version (-15) exists of draft-ietf-ace-cbor-web-token-08 == Outdated reference: A later version (-46) exists of draft-ietf-ace-oauth-authz-07 == Outdated reference: A later version (-16) exists of draft-ietf-core-object-security-05 ** Obsolete normative reference: RFC 8152 (Obsoleted by RFC 9052, RFC 9053) == Outdated reference: A later version (-07) exists of draft-ietf-ace-actors-05 == Outdated reference: A later version (-14) exists of draft-selander-ace-cose-ecdhe-07 -- 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 L. Seitz 3 Internet-Draft RISE SICS AB 4 Intended status: Standards Track F. Palombini 5 Expires: April 28, 2018 Ericsson AB 6 M. Gunnarsson 7 RISE SICS AB 8 October 25, 2017 10 OSCORE profile of the Authentication and Authorization for Constrained 11 Environments Framework 12 draft-seitz-ace-oscoap-profile-06 14 Abstract 16 This memo specifies a profile for the Authentication and 17 Authorization for Constrained Environments (ACE) framework. It 18 utilizes Object Security for Constrained RESTful Environments 19 (OSCORE) to provide communication security, server authentication, 20 and proof-of-possession for a key owned by the client and bound to an 21 OAuth 2.0 access token. 23 Status of This Memo 25 This Internet-Draft is submitted in full conformance with the 26 provisions of BCP 78 and BCP 79. 28 Internet-Drafts are working documents of the Internet Engineering 29 Task Force (IETF). Note that other groups may also distribute 30 working documents as Internet-Drafts. The list of current Internet- 31 Drafts is at https://datatracker.ietf.org/drafts/current/. 33 Internet-Drafts are draft documents valid for a maximum of six months 34 and may be updated, replaced, or obsoleted by other documents at any 35 time. It is inappropriate to use Internet-Drafts as reference 36 material or to cite them other than as "work in progress." 38 This Internet-Draft will expire on April 28, 2018. 40 Copyright Notice 42 Copyright (c) 2017 IETF Trust and the persons identified as the 43 document authors. All rights reserved. 45 This document is subject to BCP 78 and the IETF Trust's Legal 46 Provisions Relating to IETF Documents 47 (https://trustee.ietf.org/license-info) in effect on the date of 48 publication of this document. Please review these documents 49 carefully, as they describe your rights and restrictions with respect 50 to this document. Code Components extracted from this document must 51 include Simplified BSD License text as described in Section 4.e of 52 the Trust Legal Provisions and are provided without warranty as 53 described in the Simplified BSD License. 55 Table of Contents 57 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 58 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3 59 2. Client to Resource Server . . . . . . . . . . . . . . . . . . 3 60 2.1. Signaling the use of OSCORE . . . . . . . . . . . . . . . 3 61 2.2. Key establishment for OSCORE . . . . . . . . . . . . . . 4 62 3. Client to Authorization Server . . . . . . . . . . . . . . . 6 63 4. Resource Server to Authorization Server . . . . . . . . . . . 7 64 5. Security Considerations . . . . . . . . . . . . . . . . . . . 7 65 6. Privacy Considerations . . . . . . . . . . . . . . . . . . . 7 66 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 7 67 8. References . . . . . . . . . . . . . . . . . . . . . . . . . 7 68 8.1. Normative References . . . . . . . . . . . . . . . . . . 7 69 8.2. Informative References . . . . . . . . . . . . . . . . . 8 70 Appendix A. Profile Requirements . . . . . . . . . . . . . . . . 9 71 Appendix B. Using the pop-key with EDHOC (EDHOC+OSCORE) . . . . 10 72 B.1. Using Asymmetric Keys . . . . . . . . . . . . . . . . . . 10 73 B.2. Using Symmetric Keys . . . . . . . . . . . . . . . . . . 12 74 B.3. Processing . . . . . . . . . . . . . . . . . . . . . . . 13 75 Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . 15 76 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 16 78 1. Introduction 80 This memo specifies a profile of the ACE framework 81 [I-D.ietf-ace-oauth-authz]. In this profile, a client and a resource 82 server use CoAP [RFC7252] to communicate. The client uses an access 83 token, bound to a key (the proof-of-possession key) to authorize its 84 access to the resource server. In order to provide communication 85 security, proof of possession, and server authentication they use 86 Object Security for Constrained RESTful Environments (OSCORE) 87 [I-D.ietf-core-object-security]. Optionally the client and the 88 resource server may also use CoAP and OSCORE to communicate with the 89 authorization server. 91 OSCORE specifies how to use CBOR Object Signing and Encryption (COSE) 92 [RFC8152] to secure CoAP messages. In order to provide replay and 93 reordering protection OSCORE also introduces sequence numbers that 94 are used together with COSE. 96 Note that OSCORE can be used to secure CoAP messages, as well as HTTP 97 and combinations of HTTP and CoAP; a profile of ACE similar to the 98 one described in this document, with the difference of using HTTP 99 instead of CoAP as communication protocol, could be specified 100 analogously to this one. 102 1.1. Terminology 104 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 105 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 106 document are to be interpreted as described in [RFC2119]. These 107 words may also appear in this document in lowercase, absent their 108 normative meanings. 110 Certain security-related terms such as "authentication", 111 "authorization", "confidentiality", "(data) integrity", "message 112 authentication code", and "verify" are taken from [RFC4949]. 114 Since we describe exchanges as RESTful protocol interactions HTTP 115 [RFC7231] offers useful terminology. 117 Terminology for entities in the architecture is defined in OAuth 2.0 118 [RFC6749] and [I-D.ietf-ace-actors], such as client (C), resource 119 server (RS), and authorization server (AS). It is assumed in this 120 document that a given resource on a specific RS is associated to a 121 unique AS. 123 2. Client to Resource Server 125 The use of OSCORE for arbitrary CoAP messages is specified in 126 [I-D.ietf-core-object-security]. This section defines the specific 127 uses and their purpose for securing the communication between a 128 client and a resource server, and the parameters needed to negotiate 129 the use of this profile with the token resource at the authorization 130 server as specified in section 5.5 of the ACE framework 131 [I-D.ietf-ace-oauth-authz]. 133 2.1. Signaling the use of OSCORE 135 A client requests a token at an AS via the /token resource. This 136 follows the message formats specified in section 5.5.1 of the ACE 137 framework [I-D.ietf-ace-oauth-authz]. 139 The AS responding to a successful access token request as defined in 140 section 5.5.2 of the ACE framework can signal that the use of OSCORE 141 is REQUIRED for a specific access token by including the "profile" 142 parameter with the value "coap_oscore" in the access token response. 143 This means that the client MUST use OSCORE towards all resource 144 servers for which this access token is valid, and follow Section 2.2 145 to derive the security context to run OSCORE. 147 The error response procedures defined in section 5.5.3 of the ACE 148 framework are unchanged by this profile. 150 Note the the client and the authorization server MAY OPTIONALLY use 151 OSCORE to protect the interaction via the /token resource. See 152 Section 3 for details. 154 2.2. Key establishment for OSCORE 156 Section 3.2 of OSCORE [I-D.ietf-core-object-security] defines how to 157 derive a security context based on a shared master secret and a set 158 of other parameters, established between client and server. The 159 proof-of-possession key (pop-key) provisioned from the AS MAY, in 160 case of pre-shared keys, be used directly as master secret in OSCORE. 162 If OSCORE is used directly with the symmetric pop-key as master 163 secret, then the AS MUST provision the following data, in response to 164 the access token request: 166 o a master secret 168 o the sender identifier 170 o the recipient identifier 172 Additionally, the AS MAY provision the following data, in the same 173 response. In case these parameters are omitted, the default values 174 are used as described in section 3.2 of 175 [I-D.ietf-core-object-security]. 177 o an AEAD algorithm 179 o a KDF algorithm 181 o a salt 183 o a replay window type and size 185 The master secret MUST be communicated as COSE_Key in the 'cnf' 186 parameter of the access token response as defined in section 5.5.4.5 187 of [I-D.ietf-ace-oauth-authz]. The AEAD algorithm MAY be included as 188 the 'alg' parameter in the COSE_Key; the KDF algorithm MAY be 189 included as the 'kdf' parameter of the COSE_Key and the salt MAY be 190 included as the 'slt' parameter of the COSE_Key as defined in table 191 1. The same parameters MUST be included as metadata of the access 192 token; if the token is a CWT [I-D.ietf-ace-cbor-web-token], the same 193 COSE_Key structure MUST be placed in the 'cnf' claim of this token. 194 The AS MUST also assign identifiers to both client and RS, which are 195 then used as Sender ID and Recipient ID in the OSCORE context as 196 described in section 3.1 of [I-D.ietf-core-object-security]. These 197 identifiers MUST be unique in the set of all clients and RS 198 identifiers for a certain AS. Moreover, these MUST be included in 199 the COSE_Key as header parameters, as defined in table 1. 201 We assume in this document that a resource is associated to one 202 single AS, which makes it possible to assume unique identifiers for 203 each client requesting a particular resource to a RS. If this is not 204 the case, collisions of identifiers may appear in the RS, in which 205 case the RS needs to have a mechanism in place to disambiguate 206 identifiers or mitigate their effect. 208 Note that C should set the Sender ID of its security context to the 209 clientId value received and the Recipient ID to the serverId value, 210 and RS should do the opposite. 212 +----------+-------+--------------+------------+-------------------+ 213 | name | label | CBOR type | registry | description | 214 +----------+-------+--------------+------------+-------------------+ 215 | clientId | TBD | bstr | | Identifies the | 216 | | | | | client in an | 217 | | | | | OSCORE context | 218 | | | | | using this key | 219 | | | | | | 220 | serverId | TBD | bstr | | Identifies the | 221 | | | | | server in an | 222 | | | | | OSCORE context | 223 | | | | | using this key | 224 | | | | | | 225 | kdf | TBD | bstr | | Identifies the | 226 | | | | | KDF algorithm in | 227 | | | | | an OSCORE context | 228 | | | | | using this key | 229 | | | | | | 230 | slt | TBD | bstr | | Identifies the | 231 | | | | | master salt in | 232 | | | | | an OSCORE context | 233 | | | | | using this key | 234 +----------+-------+--------------+------------+-------------------+ 235 Table 1: Additional common header parameters for COSE_Key 237 Figure 1 shows an example of such an AS response, in CBOR diagnostic 238 notation without the tag and value abbreviations. 240 Header: Created (Code=2.01) 241 Content-Type: "application/cose+cbor" 242 Payload: 243 { 244 "access_token" : b64'SlAV32hkKG ... 245 (remainder of access token omitted for brevity)', 246 "profile" : "coap_oscore", 247 "expires_in" : "3600", 248 "cnf" : { 249 "COSE_Key" : { 250 "kty" : "Symmetric", 251 "alg" : "AES-CCM-16-64-128", 252 "clientId" : b64'qA', 253 "serverId" : b64'Qg', 254 "k" : b64'+a+Dg2jjU+eIiOFCa9lObw' 255 } 256 } 257 } 259 Figure 1: Example AS response with OSCORE parameters. 261 Figure 2 shows an example CWT, containing the necessary OSCORE 262 parameters in the 'cnf' claim, in CBOR diagnostic notation without 263 tag and value abbreviations. 265 { 266 "aud" : "tempSensorInLivingRoom", 267 "iat" : "1360189224", 268 "exp" : "1360289224", 269 "scope" : "temperature_g firmware_p", 270 "cnf" : { 271 "COSE_Key" : { 272 "kty" : "Symmetric", 273 "alg" : "AES-CCM-16-64-128", 274 "clientId" : b64'Qg', 275 "serverId" : b64'qA', 276 "k" : b64'+a+Dg2jjU+eIiOFCa9lObw' 277 } 278 } 280 Figure 2: Example CWT with OSCORE parameters. 282 3. Client to Authorization Server 284 As specified in the ACE framework section 5.5 285 [I-D.ietf-ace-oauth-authz], the Client and AS can also use CoAP 286 instead of HTTP to communicate via the token resource. This section 287 specifies how to use OSCORE between Client and AS together with CoAP. 289 The use of OSCORE for this communication is OPTIONAL in this profile, 290 other security protocols (such as DTLS) MAY be used instead. 292 The client and the AS are expected to have pre-established security 293 contexts in place. How these security contexts are established is 294 out of scope for this profile. Furthermore the client and the AS 295 communicate using OSCORE ([I-D.ietf-core-object-security]) through 296 the introspection resource as specified in section 5.6 of 297 [I-D.ietf-ace-oauth-authz]. 299 4. Resource Server to Authorization Server 301 As specified in the ACE framework section 5.6 302 [I-D.ietf-ace-oauth-authz], the RS and AS can also use CoAP instead 303 of HTTP to communicate via the introspection resource. This section 304 specifies how to use OSCORE between RS and AS. The use of OSCORE for 305 this communication is OPTIONAL in this profile, other security 306 protocols (such as DTLS) MAY be used instead. 308 The RS and the AS are expected to have pre-established security 309 contexts in place. How these security contexts are established is 310 out of scope for this profile. Furthermore the RS and the AS 311 communicate using OSCORE ([I-D.ietf-core-object-security]) through 312 the introspection resource as specified in section 5.6 of 313 [I-D.ietf-ace-oauth-authz]. 315 5. Security Considerations 317 TBD. 319 6. Privacy Considerations 321 TBD. 323 7. IANA Considerations 325 TBD. 'coap_oscore' as profile id. Header parameters 'sid', 'rid', 326 'kdf' and 'slt' for COSE_Key. 328 8. References 330 8.1. Normative References 332 [I-D.ietf-ace-cbor-web-token] 333 Jones, M., Wahlstroem, E., Erdtman, S., and H. Tschofenig, 334 "CBOR Web Token (CWT)", draft-ietf-ace-cbor-web-token-08 335 (work in progress), August 2017. 337 [I-D.ietf-ace-oauth-authz] 338 Seitz, L., Selander, G., Wahlstroem, E., Erdtman, S., and 339 H. Tschofenig, "Authentication and Authorization for 340 Constrained Environments (ACE)", draft-ietf-ace-oauth- 341 authz-07 (work in progress), August 2017. 343 [I-D.ietf-core-object-security] 344 Selander, G., Mattsson, J., Palombini, F., and L. Seitz, 345 "Object Security for Constrained RESTful Environments 346 (OSCORE)", draft-ietf-core-object-security-05 (work in 347 progress), September 2017. 349 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 350 Requirement Levels", BCP 14, RFC 2119, 351 DOI 10.17487/RFC2119, March 1997, 352 . 354 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 355 Application Protocol (CoAP)", RFC 7252, 356 DOI 10.17487/RFC7252, June 2014, 357 . 359 [RFC8152] Schaad, J., "CBOR Object Signing and Encryption (COSE)", 360 RFC 8152, DOI 10.17487/RFC8152, July 2017, 361 . 363 8.2. Informative References 365 [I-D.gerdes-ace-dcaf-authorize] 366 Gerdes, S., Bergmann, O., and C. Bormann, "Delegated CoAP 367 Authentication and Authorization Framework (DCAF)", draft- 368 gerdes-ace-dcaf-authorize-04 (work in progress), October 369 2015. 371 [I-D.ietf-ace-actors] 372 Gerdes, S., Seitz, L., Selander, G., and C. Bormann, "An 373 architecture for authorization in constrained 374 environments", draft-ietf-ace-actors-05 (work in 375 progress), March 2017. 377 [I-D.selander-ace-cose-ecdhe] 378 Selander, G., Mattsson, J., and F. Palombini, "Ephemeral 379 Diffie-Hellman Over COSE (EDHOC)", draft-selander-ace- 380 cose-ecdhe-07 (work in progress), July 2017. 382 [RFC4949] Shirey, R., "Internet Security Glossary, Version 2", 383 FYI 36, RFC 4949, DOI 10.17487/RFC4949, August 2007, 384 . 386 [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", 387 RFC 6749, DOI 10.17487/RFC6749, October 2012, 388 . 390 [RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object 391 Representation (CBOR)", RFC 7049, DOI 10.17487/RFC7049, 392 October 2013, . 394 [RFC7231] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 395 Protocol (HTTP/1.1): Semantics and Content", RFC 7231, 396 DOI 10.17487/RFC7231, June 2014, 397 . 399 Appendix A. Profile Requirements 401 This section lists the specifications on this profile based on the 402 requirements on the framework, as requested in Appendix C. of 403 [I-D.ietf-ace-oauth-authz]. 405 o (Optional) discovery process of how the client finds the right AS 406 for an RS it wants to send a request to: Not specified 408 o communication protocol the client and the RS must use: CoAP 410 o security protocol the client and RS must use: OSCORE 412 o how the client and the RS mutually authenticate: Implicitly by 413 possession of a common OSCORE security context 415 o Content-format of the protocol messages: "application/cose+cbor" 417 o proof-of-possession protocol(s) and how to select one; which key 418 types (e.g. symmetric/asymmetric) supported: OSCORE algorithms; 419 pre-established symmetric keys 421 o profile identifier: coap_oscore 423 o (Optional) how the RS talks to the AS for introspection: HTTP/CoAP 424 (+ TLS/DTLS/OSCORE) 426 o how the client talks to the AS for requesting a token: HTTP/CoAP 427 (+ TLS/DTLS/OSCORE) 429 o how/if the /authz-info endpoint is protected: Security protocol 430 above 432 o (Optional)other methods of token transport than the /authz-info 433 endpoint: no 435 Appendix B. Using the pop-key with EDHOC (EDHOC+OSCORE) 437 EDHOC specifies an authenticated Diffie-Hellman protocol that allows 438 two parties to use CBOR [RFC7049] and COSE in order to establish a 439 shared secret key with perfect forward secrecy. The use of Ephemeral 440 Diffie-Hellman Over COSE (EDHOC) [I-D.selander-ace-cose-ecdhe] in 441 this profile in addition to OSCORE, provides perfect forward secrecy 442 (PFS) and the initial proof-of-possession, which ties the proof-of- 443 possession key to an OSCORE security context. 445 If EDHOC is used together with OSCORE, and the pop-key (symmetric or 446 asymmetric) is used to authenticate the messages in EDHOC, then the 447 AS MUST provision the following data, in response to the access token 448 request: 450 o a symmetric or public key (associated to the RS) 452 o a key identifier; 454 How these parameters are communicated depends on the type of key 455 (asymmetric or symmetric). Moreover, the AS MUST signal the use of 456 OSCORE + EDHOC with the 'profile' parameter set to 457 "coap_oscore_edhoc" and follow Appendix B to derive the security 458 context to run OSCORE. 460 Note that in the case described in this section, the 'expires_in' 461 parameter, defined in section 4.2.2. of [RFC6749] defines the 462 lifetime in seconds of both the access token and the shared secret. 463 After expiration, C MUST acquire a new access token from the AS, and 464 run EDHOC again, as specified in this section 466 B.1. Using Asymmetric Keys 468 In case of an asymmetric key, C MUST communicate its own asymmetric 469 key to the AS in the 'cnf' parameter of the access token request, as 470 specified in section 5.5.1 of [I-D.ietf-ace-oauth-authz]; the AS MUST 471 communicate the RS's public key to C in the response, in the 'rs_cnf' 472 parameter, as specified in section 5.5.1 of 473 [I-D.ietf-ace-oauth-authz]. Note that the RS's public key MUST 474 include a 'kid' parameter, and that the value of the 'kid' MUST be 475 included in the access token, to let the RS know which of its public 476 keys C used. If the access token is a CWT 477 [I-D.ietf-ace-cbor-web-token], the key identifier MUST be placed 478 directly in the 'cnf' structure (if the key is only referenced). 480 Figure 3 shows an example of such a request in CBOR diagnostic 481 notation without tag and value abbreviations. 483 Header: POST (Code=0.02) 484 Uri-Host: "server.example.com" 485 Uri-Path: "token" 486 Content-Type: "application/cose+cbor" 487 Payload: 488 { 489 "grant_type" : "client_credentials", 490 "cnf" : { 491 "COSE_Key" : { 492 "kid" : "client_key" 493 "kty" : "EC", 494 "crv" : "P-256", 495 "x" : b64'usWxHK2PmfnHKwXPS54m0kTcGJ90UiglWiGahtagnv8', 496 "y" : b64'IBOL+C3BttVivg+lSreASjpkttcsz+1rb7btKLv8EX4' 497 } 498 } 499 } 501 Figure 3: Example access token request (OSCORE+EDHOC, asymmetric). 503 Figure 4 shows an example of a corresponding response in CBOR 504 diagnostic notation without tag and value abbreviations. 506 Header: Created (Code=2.01) 507 Content-Type: "application/cose+cbor" 508 Payload: 509 { 510 "access_token" : b64'SlAV32hkKG ... 511 (contains "kid" : "client_key")', 512 "profile" : "coap_oscore_edhoc", 513 "expires_in" : "3600", 514 "cnf" : { 515 "COSE_Key" : { 516 "kid" : "server_key" 517 "kty" : "EC", 518 "crv" : "P-256", 519 "x" : b64'cGJ90UiglWiGahtagnv8usWxHK2PmfnHKwXPS54m0kT', 520 "y" : b64'reASjpkttcsz+1rb7btKLv8EX4IBOL+C3BttVivg+lS' 521 } 522 } 523 } 525 Figure 4: Example AS response (EDHOC+OSCORE, asymmetric). 527 B.2. Using Symmetric Keys 529 In the case of a symmetric key, the AS MUST communicate the key to 530 the client in the 'cnf' parameter of the access token response, as 531 specified in section 5.5.2. of [I-D.ietf-ace-oauth-authz]. AS MUST 532 also select a key identifier, that MUST be included as the 'kid' 533 parameter either directly in the 'cnf' structure, as in figure 4 of 534 [I-D.ietf-ace-oauth-authz], or as the 'kid' parameter of the 535 COSE_key, as in figure 6 of [I-D.ietf-ace-oauth-authz]. 537 Figure 5 shows an example of the necessary parameters in the AS 538 response to the access token request when EDHOC is used. The example 539 uses CBOR diagnostic notation without tag and value abbreviations. 541 Header: Created (Code=2.01) 542 Content-Type: "application/cose+cbor" 543 Payload: 544 { 545 "access_token" : b64'SlAV32hkKG ... 546 (remainder of access token omitted for brevity)', 547 "profile" : "coap_oscore_edhoc", 548 "expires_in" : "3600", 549 "cnf" : { 550 "COSE_Key" : { 551 "kty" : "Symmetric", 552 "kid" : b64'5tOS+h42dkw', 553 "k" : b64'+a+Dg2jjU+eIiOFCa9lObw' 554 } 555 } 556 } 558 Figure 5: Example AS response (EDHOC+OSCORE, symmetric). 560 In both cases, the AS MUST also include the same key identifier as 561 'kid' parameter in the access token metadata. If the access token is 562 a CWT [I-D.ietf-ace-cbor-web-token], the key identifier MUST be 563 placed inside the 'cnf' claim as 'kid' parameter of the COSE_Key or 564 directly in the 'cnf' structure (if the key is only referenced). 566 Figure 6 shows an example CWT containing the necessary EDHOC+OSCORE 567 parameters in the 'cnf' claim, in CBOR diagnostic notation without 568 tag and value abbreviations. 570 { 571 "aud" : "tempSensorInLivingRoom", 572 "iat" : "1360189224", 573 "exp" : "1360289224", 574 "scope" : "temperature_g firmware_p", 575 "cnf" : { 576 "COSE_Key" : { 577 "kty" : "Symmetric", 578 "kid" : b64'5tOS+h42dkw', 579 "k" : b64'+a+Dg2jjU+eIiOFCa9lObw' 580 } 581 } 583 Figure 6: Example CWT with EDHOC+OSCORE, symmetric case. 585 All other parameters defining OSCORE security context are derived 586 from EDHOC message exchange, including the master secret (see 587 Appendix C.2 of [I-D.selander-ace-cose-ecdhe]). 589 B.3. Processing 591 To provide forward secrecy and mutual authentication in the case of 592 pre-shared keys, pre-established raw public keys or with X.509 593 certificates it is RECOMMENDED to use EDHOC 594 [I-D.selander-ace-cose-ecdhe] to generate the keying material. EDHOC 595 MUST be used as defined in Appendix C of 596 [I-D.selander-ace-cose-ecdhe], with the following additions and 597 modifications. 599 The first EDHOC message is sent after the access token is posted to 600 the /authz-info resource of the RS as specified in section 5.7.1 of 601 [I-D.ietf-ace-oauth-authz]. Then the EDHOC message_1 is sent and the 602 EDHOC protocol is initiated [I-D.selander-ace-cose-ecdhe]). 604 Before the RS continues with the EDHOC protocol and responds to this 605 token submission request, additional verifications on the access 606 token are done: the RS SHALL process the access token according to 607 [I-D.ietf-ace-oauth-authz]. If the token is valid then the RS 608 continues processing EDHOC following Appendix C of 609 [I-D.selander-ace-cose-ecdhe], otherwise it discontinues EDHOC and 610 responds with the error code as specified in 611 [I-D.ietf-ace-oauth-authz]. 613 o In case the EDHOC verification fails, the RS MUST return an error 614 response to the client with code 4.01 (Unauthorized). 616 o If RS has an access token for C but not for the resource that C 617 has requested, RS MUST reject the request with a 4.03 (Forbidden). 619 o If RS has an access token for C but it does not cover the action C 620 requested on the resource, RS MUST reject the request with a 4.05 621 (Method Not Allowed). 623 o If all verifications above succeeds, further communication between 624 client and RS is protected with OSCORE, including the RS response 625 to the OSCORE request. 627 In the case of EDHOC being used with symmetric keys, the protocol in 628 section 5 of [I-D.selander-ace-cose-ecdhe] MUST be used. If the key 629 is asymmetric, the RS MUST also use an asymmetric key for 630 authentication. This key is known to the client through the access 631 token response (see section 5.5.2 of the ACE framework). In this 632 case the protocol in section 4 of [I-D.selander-ace-cose-ecdhe] MUST 633 be used. 635 Figure 7 illustrates the message exchanges for using OSCORE+EDHOC 636 (step C in figure 1 of [I-D.ietf-ace-oauth-authz]). 638 Resource 639 Client Server 640 | | 641 | | 642 +--------->| Header: POST (Code=0.02) 643 | POST | Uri-Path:"authz-info" 644 | | Content-Type: application/cbor 645 | | Payload: access token 646 | | 647 | | 648 +--------->| Header: POST (Code=0.02) 649 | POST | Uri-Path: "/.well-known/edhoc" 650 | | Content-Type: application/edhoc 651 | | Payload: EDHOC message_1 652 | | 653 |<---------+ Header: 2.04 Changed 654 | 2.04 | Content-Type: application/edhoc 655 | | Payload: EDHOC message_2 656 | | 657 +--------->| Header: POST (Code=0.02) 658 | POST | Uri-Path: "/.well-known/edhoc" 659 | | Content-Type: application/edhoc 660 | | Payload: EDHOC message_3 661 | | 662 |<---------+ Header: 2.04 Changed 663 | 2.04 | 664 | | 665 start of protected communication 666 | | 667 +--------->| CoAP request + 668 | OSCORE | Object-Security option 669 | request | 670 | | 671 |<---------+ CoAP response + 672 | OSCORE | Object-Security option 673 | response | 674 | | 676 Figure 7: Access token and key establishment with EDHOC 678 Acknowledgments 680 The authors wish to thank Jim Schaad, Goeran Selander and Marco 681 Tiloca for the input on this memo. The error responses specified in 682 Appendix B.3 were originally specified by Gerdes et al. in 683 [I-D.gerdes-ace-dcaf-authorize]. 685 Authors' Addresses 687 Ludwig Seitz 688 RISE SICS AB 689 Scheelevagen 17 690 Lund 22370 691 SWEDEN 693 Email: ludwig.seitz@ri.se 695 Francesca Palombini 696 Ericsson AB 697 Farogatan 6 698 Kista SE-16480 Stockholm 699 Sweden 701 Email: francesca.palombini@ericsson.com 703 Martin Gunnarsson 704 RISE SICS AB 705 Scheelevagen 17 706 Lund 22370 707 SWEDEN 709 Email: martin.gunnarsson@ri.se