idnits 2.17.1 draft-selander-ace-cose-ecdhe-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 (April 25, 2017) is 2529 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 (-03) exists of draft-schaad-cose-x509-00 ** Downref: Normative reference to an Informational draft: draft-schaad-cose-x509 (ref. 'I-D.schaad-cose-x509') ** Obsolete normative reference: RFC 7049 (Obsoleted by RFC 8949) -- Possible downref: Non-RFC (?) normative reference: ref. 'SIGMA' -- Possible downref: Non-RFC (?) normative reference: ref. 'SP-800-56a' == Outdated reference: A later version (-11) exists of draft-greevenbosch-appsawg-cbor-cddl-10 == Outdated reference: A later version (-03) exists of draft-hartke-core-e2e-security-reqs-02 == Outdated reference: A later version (-46) exists of draft-ietf-ace-oauth-authz-06 == Outdated reference: A later version (-16) exists of draft-ietf-core-object-security-02 == Outdated reference: A later version (-28) exists of draft-ietf-core-resource-directory-10 == Outdated reference: A later version (-06) exists of draft-seitz-ace-oscoap-profile-01 Summary: 2 errors (**), 0 flaws (~~), 8 warnings (==), 3 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 ACE Working Group G. Selander 3 Internet-Draft J. Mattsson 4 Intended status: Standards Track F. Palombini 5 Expires: October 27, 2017 Ericsson AB 6 April 25, 2017 8 Ephemeral Diffie-Hellman Over COSE (EDHOC) 9 draft-selander-ace-cose-ecdhe-06 11 Abstract 13 This document specifies Ephemeral Diffie-Hellman Over COSE (EDHOC), a 14 compact, and lightweight authenticated Diffie-Hellman key exchange 15 with ephemeral keys that can be used over any layer. EDHOC messages 16 are encoded with CBOR and COSE, allowing reuse of existing libraries. 18 Status of This Memo 20 This Internet-Draft is submitted in full conformance with the 21 provisions of BCP 78 and BCP 79. 23 Internet-Drafts are working documents of the Internet Engineering 24 Task Force (IETF). Note that other groups may also distribute 25 working documents as Internet-Drafts. The list of current Internet- 26 Drafts is at http://datatracker.ietf.org/drafts/current/. 28 Internet-Drafts are draft documents valid for a maximum of six months 29 and may be updated, replaced, or obsoleted by other documents at any 30 time. It is inappropriate to use Internet-Drafts as reference 31 material or to cite them other than as "work in progress." 33 This Internet-Draft will expire on October 27, 2017. 35 Copyright Notice 37 Copyright (c) 2017 IETF Trust and the persons identified as the 38 document authors. All rights reserved. 40 This document is subject to BCP 78 and the IETF Trust's Legal 41 Provisions Relating to IETF Documents 42 (http://trustee.ietf.org/license-info) in effect on the date of 43 publication of this document. Please review these documents 44 carefully, as they describe your rights and restrictions with respect 45 to this document. Code Components extracted from this document must 46 include Simplified BSD License text as described in Section 4.e of 47 the Trust Legal Provisions and are provided without warranty as 48 described in the Simplified BSD License. 50 Table of Contents 52 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 53 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3 54 1.2. Requirements Language . . . . . . . . . . . . . . . . . . 3 55 2. Protocol Overview . . . . . . . . . . . . . . . . . . . . . . 3 56 3. EDHOC Overview . . . . . . . . . . . . . . . . . . . . . . . 5 57 3.1. Formatting of the Ephemeral Public Keys . . . . . . . . . 6 58 3.2. Key Derivation . . . . . . . . . . . . . . . . . . . . . 6 59 4. EDHOC Authenticated with Asymmetric Keys . . . . . . . . . . 8 60 4.1. Overview . . . . . . . . . . . . . . . . . . . . . . . . 8 61 4.2. EDHOC Message 1 . . . . . . . . . . . . . . . . . . . . . 8 62 4.3. EDHOC Message 2 . . . . . . . . . . . . . . . . . . . . . 11 63 4.4. EDHOC Message 3 . . . . . . . . . . . . . . . . . . . . . 13 64 5. EDHOC Authenticated with Symmetric Keys . . . . . . . . . . . 15 65 5.1. Overview . . . . . . . . . . . . . . . . . . . . . . . . 15 66 5.2. EDHOC Message 1 . . . . . . . . . . . . . . . . . . . . . 16 67 5.3. EDHOC Message 2 . . . . . . . . . . . . . . . . . . . . . 18 68 5.4. EDHOC Message 3 . . . . . . . . . . . . . . . . . . . . . 19 69 6. Error Handling . . . . . . . . . . . . . . . . . . . . . . . 21 70 6.1. Error Message Format . . . . . . . . . . . . . . . . . . 21 71 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 21 72 7.1. Media Types Registry . . . . . . . . . . . . . . . . . . 21 73 8. Security Considerations . . . . . . . . . . . . . . . . . . . 22 74 9. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 24 75 10. References . . . . . . . . . . . . . . . . . . . . . . . . . 24 76 10.1. Normative References . . . . . . . . . . . . . . . . . . 24 77 10.2. Informative References . . . . . . . . . . . . . . . . . 25 78 Appendix A. Test Vectors . . . . . . . . . . . . . . . . . . . . 26 79 Appendix B. PSK Chaining . . . . . . . . . . . . . . . . . . . . 26 80 Appendix C. EDHOC with CoAP and OSCOAP . . . . . . . . . . . . . 26 81 C.1. Transferring EDHOC in CoAP . . . . . . . . . . . . . . . 26 82 C.2. Deriving an OSCOAP context from EDHOC . . . . . . . . . . 27 83 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 28 85 1. Introduction 87 Security at the application layer provides an attractive option for 88 protecting Internet of Things (IoT) deployments, for example where 89 transport layer security is not sufficient 90 [I-D.hartke-core-e2e-security-reqs] or where the protocol needs to 91 work on a variety of underlying protocols. IoT devices may be 92 constrained in various ways, including memory, storage, processing 93 capacity, and energy [RFC7228]. A method for protecting individual 94 messages at the application layer suitable for constrained devices, 95 is provided by CBOR Object Signing and Encryption (COSE) 96 [I-D.ietf-cose-msg]), which builds on the Concise Binary Object 97 Representation (CBOR) [RFC7049]. 99 In order for a communication session to provide forward secrecy, the 100 communicating parties can run an Elliptic Curve Diffie-Hellman (ECDH) 101 key exchange protocol with ephemeral keys, from which shared key 102 material can be derived. This document specifies Ephemeral Diffie- 103 Hellman Over COSE (EDHOC), an authenticated ECDH protocol using CBOR 104 and COSE objects. Authentication is based on credentials established 105 out of band, e.g. from a trusted third party, such as an 106 Authorization Server as specified by [I-D.ietf-ace-oauth-authz]. 107 EDHOC supports authentication using pre-shared keys (PSK), raw public 108 keys (RPK), and certificates (Cert). Note that this document focuses 109 on authentication and key establishment: for integration with 110 authorization of resource access, refer to 111 [I-D.seitz-ace-oscoap-profile]. This document also specifies the 112 derivation of shared key material. 114 The ECDH exchange and the key derivation follow [SIGMA], NIST SP- 115 800-56a [SP-800-56a], and HKDF [RFC5869]. CBOR [RFC7049] and COSE 116 [I-D.ietf-cose-msg] are used to implement these standards. 118 1.1. Terminology 120 This document use the same informational CBOR Data Definition 121 Language (CDDL) [I-D.greevenbosch-appsawg-cbor-cddl] grammar as COSE 122 (see Section 1.3 of [I-D.ietf-cose-msg]). A vertical bar | denotes 123 byte string concatenation. 125 1.2. Requirements Language 127 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 128 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 129 document are to be interpreted as described in [RFC2119]. These 130 words may also appear in this document in lowercase, absent their 131 normative meanings. 133 2. Protocol Overview 135 SIGMA (SIGn-and-MAc) is a family of theoretical protocols with a 136 large number of variants [SIGMA]. Like IKEv2 and TLS 1.3, EDHOC is 137 built on a variant of the SIGMA protocol which provide identity 138 protection, and like TLS 1.3, EDHOC implements the SIGMA-I variant as 139 Sign-then-MAC. The SIGMA-I protocol using an AEAD algorithm is shown 140 in Figure 1. 142 Party U Party V 143 | E_U | 144 +------------------------------------------------------>| 145 | | 146 | E_V, Enc(K_2; ID_V, Sig(V; E_U, E_V);) | 147 |<------------------------------------------------------+ 148 | | 149 | Enc(K_3; ID_U, Sig(U; E_V, E_U);) | 150 +------------------------------------------------------>| 151 | | 153 Figure 1: AEAD variant of the SIGMA-I protocol 155 The parties exchanging messages are called "U" and "V". They 156 exchange identities and ephemeral public keys, compute the shared 157 secret, and derive the keying material. The messages are signed, 158 MACed, and encrypted. 160 o E_U and E_V are the ECDH ephemeral public keys of U and V, 161 respectively. 163 o ID_U and ID_V are identifiers for the public keys of U and V, 164 respectively. 166 o Sig(U; . ) and S(V; . ) denote signatures made with the private 167 key of U and V, respectively. 169 o Enc(K; P; A) denotes AEAD encryption of plaintext P and additional 170 authenticated data A using the key K derived from the shared 171 secret. The AEAD MUST NOT be replaced by plain encryption, see 172 Section 8. 174 As described in Appendix B of [SIGMA], in order to create a "full- 175 fledge" protocol some additional protocol elements are needed. EDHOC 176 adds: 178 o Explicit session identifiers S_U, S_V chosen by U and V, 179 respectively. 181 o Explicit nonces N_U, N_V chosen freshly and anew with each session 182 by U and V, respectively. 184 o Computationally independent keys derived from the ECDH shared 185 secret and used for encryption of different messages. 187 EDHOC also makes the following additions: 189 o Negotiation of key derivation, encryption, and signature 190 algorithms: 192 * U proposes one or more algorithms of the following kinds: 194 + HKDF 196 + AEAD 198 + Signature verification 200 + Signature generation 202 * V selects one algorithm of each kind 204 o Verification of common preferred ECDH curve: 206 * U lists supported ECDH curves in order of preference 208 * V verifies that the ECDH curve of the ephemeral key is the most 209 preferred common curve 211 o Transport of opaque application defined data. 213 EDHOC is designed to encrypt and integrity protect as much 214 information as possible, and all symmetric keys are derived using as 215 much previous information as possible. EDHOC is furthermore designed 216 to be as compact and lightweight as possible, in terms of message 217 sizes, processing, and the ability to reuse already existing CBOR and 218 COSE libraries. EDHOC does not put any requirement on the lower 219 layers and can therefore be also be used e.g. in environments without 220 IP. 222 This paper is organized as follows: Section 3 specifies general 223 properties of EDHOC, including formatting of the ephemeral public 224 keys and key derivation, Section 4 specifies EDHOC with asymmetric 225 key authentication, Section 5 specifies EDHOC with symmetric key 226 authentication, and Appendix A provides a wealth of test vectors to 227 ease implementation and ensure interoperability. 229 3. EDHOC Overview 231 EDHOC consists of three messages (message_1, message_2, message_3) 232 that maps directly to the three messages in SIGMA-I, plus an EDHOC 233 error message. All EDHOC messages consists of a CBOR array where the 234 first element is an int specifying the message type (MSG_TYPE). 235 After creating EDHOC message_3, Party U can derive the traffic key 236 (master secret) and protected application data can therefore be sent 237 in parallel with EDHOC message_3. The application data may e.g. be 238 protected using the negotiated AEAD algorithm. EDHOC may be used 239 with the media type application/edhoc defined in Section 7. 241 Party U Party V 242 | | 243 | ------------------ EDHOC message_1 -----------------> | 244 | | 245 | <----------------- EDHOC message_2 ------------------ | 246 | | 247 | ----------------- EDHOC message_3 ------------------> | 248 | | 249 | <----------- Protected Application Data ------------> | 250 | | 252 Figure 2: EDHOC message flow 254 The EDHOC message exchange may be authenticated using pre-shared keys 255 (PSK), raw public keys (RPK), or certificates (Cert). EDHOC assumes 256 the existence of mechanisms (certification authority, manual 257 distribution, etc.) for binding identities with authentication keys 258 (public or pre-shared). EDHOC with symmetric key authentication is 259 very similar to EDHOC with asymmetric key authentication, the 260 difference being that information is only MACed, not signed. 262 EDHOC also allows application data (APP_1, APP_2, APP_3) to be sent 263 in the respective messages. APP_1 is unprotected, APP_2 is protected 264 (encrypted and integrity protected), and APP_3 is protected and 265 mutually authenticated. When EDHOC is used with asymmetric key 266 authentication APP_2 is sent to an unauthenticated party, but with 267 symmetric key authentication APP_2 is mutually authenticated. 269 3.1. Formatting of the Ephemeral Public Keys 271 The ECDH ephemeral public key SHALL be formatted as a COSE_Key of 272 type EC2 or OKP according to section 13.1 and 13.2 of 273 [I-D.ietf-cose-msg]. The curve X25519 is mandatory to implement. 274 For Elliptic Curve Keys of type EC2, point compression is mandatory 275 to implement. 277 3.2. Key Derivation 279 Key and IV derivation SHALL be done as specified in Section 11.1 of 280 [I-D.ietf-cose-msg] with the following input: 282 o The PRF SHALL be the HKDF [RFC5869] in the ECDH-SS w/ HKDF 283 negotiated during the message exchange (HKDF_V). 285 o The secret SHALL be the ECDH shared secret as defined in 286 Section 12.4.1 of [I-D.ietf-cose-msg]. 288 o salt = PSK / nil 290 o The context information SHALL be the serialized COSE_KDF_Context 291 with the following values: 293 * AlgorithmID = tstr / int 295 * PartyInfo = ( nil, nil, nil ) 297 * SuppPubInfo SHALL contain: 299 + keyDataLength int 301 + protected SHALL be a zero length bstr 303 + other = aad_2 / aad_3 / exchange_hash 305 exchange_hash = bstr 307 where exchange_hash, in diagnostic non-normative notation, is: 309 exchange_hash = H( H( message_1 | message_2 ) | message_3 ) 311 where H() is the hash function in HKDF_V, and | denotes byte string 312 concatenation. 314 The salt SHALL only be present in the symmetric case. 316 Symmetric keys and IVs SHALL be derived with the negotiated PRF 317 (HKDF_V) and with the secret set to the ECDH shared secret. 319 For message_i the key and IV, called K_i and IV_i, SHALL be derived 320 using other = aad_i, where i = 2 or 3. The key SHALL be derived 321 using AlgorithmID set to the negotiated AEAD (AEAD_V), and 322 keyDataLength equal to the key length of AEAD_V. The IV SHALL be 323 derived using AlgorithmID = "IV-GENERATION" as specified in section 324 12.1.2. of [I-D.ietf-cose-msg], and keyDataLength equal to the IV 325 length of AEAD_V. 327 Application specific traffic keys and other data SHALL be derived 328 using other = exchange_hash. AlgorithmID is defined by the 329 application and SHALL be different for different data being derived 330 (an example is given in Appendix C.2). keyDataLength is set to the 331 length of the data being derived. 333 4. EDHOC Authenticated with Asymmetric Keys 335 4.1. Overview 337 EDHOC supports authentication with raw public keys (RPK) and 338 certificates (Cert) with the requirements that: 340 o Party U's SHALL be able to identify Party V's public key using 341 ID_V. 343 o Party V's SHALL be able to identify Party U's public key using 344 ID_U. 346 ID_U and ID_V either enable the other party to retrieve the public 347 key (kid, x5t, x5u) or they contain the public key (x5c), see 348 [I-D.schaad-cose-x509]. Party U and party V MAY use different type 349 of credentials, e.g. one uses RPK and the other Cert. Party U and 350 party V MAY use different signature algorithms. 352 EDHOC with asymmetric key authentication is illustrated in Figure 3. 354 Party U Party V 355 | S_U, N_U, E_U, ALG_1, APP_1 | 356 +--------------------------------------------------------------------->| 357 | message_1 | 358 | | 359 |S_U, S_V, N_V, E_V, ALG_2, Enc(K_2; APP_2, ID_V, Sig(V; aad_2); aad_2)| 360 |<---------------------------------------------------------------------+ 361 | message_2 | 362 | | 363 | S_V, Enc(K_3; APP_3, ID_U, Sig(U; aad_3); aad_3) | 364 +--------------------------------------------------------------------->| 365 | message_3 | 367 Figure 3: EDHOC with asymmetric key authentication. 369 4.1.1. Mandatory to Implement Algorithms 371 For EDHOC authenticated with asymmetric keys, the COSE algorithms 372 ECDH-SS + HKDF-256, AES-CCM-64-64-128, and EdDSA are mandatory to 373 implement. 375 4.2. EDHOC Message 1 376 4.2.1. Formatting of Message 1 378 message_1 SHALL be a CBOR array as defined below 380 message_1 = [ 381 MSG_TYPE : int, 382 S_U : bstr, 383 N_U : bstr, 384 E_U : serialized_COSE_Key, 385 ECDH-Curves_U : alg_array, 386 HKDFs_U : alg_array, 387 AEADs_U : alg_array, 388 SIGs_V : alg_array, 389 SIGs_U : alg_array, 390 ? APP_1 : bstr 391 ] 393 serialized_COSE_Key = bstr .cbor COSE_Key 395 alg_array = [ + alg : int / tstr ] 397 where: 399 o MSG_TYPE = 1 401 o S_U - variable length session identifier 403 o N_U - 64-bit random nonce 405 o E_U - the ephemeral public key of Party U 407 o ECDH-Curves_U - EC curves for ECDH which Party U supports, in the 408 order of decreasing preference 410 o HKDFs_U - supported ECDH-SS w/ HKDF algorithms 412 o AEADs_U - supported AEAD algorithms 414 o SIGs_V - signature algorithms, with which Party U supports 415 verification 417 o SIGs_U - signature algorithms, with which Party U supports signing 419 o APP_1 - bstr containing application data 421 4.2.2. Party U Processing of Message 1 423 Party U SHALL compose message_1 as follows: 425 o Determine which ECDH curve to use with Party V. If U previously 426 received from Party V an error message to message_1 with 427 diagnostic payload identifying an ECDH curve in ECDH-Curves_U, 428 then U SHALL retrieve an ephemeral from that curve. Otherwise the 429 first curve in ECDH-Curves_U MUST be used. 431 o Retrieve an ephemeral ECDH key pair generated as specified in 432 Section 5 of [SP-800-56a] and format the ephemeral public key E_U 433 as a COSE_key as specified in Section 3.1. 435 o Generate the pseudo-random nonce N_U 437 o Choose a session identifier S_U and store it for the length of the 438 protocol. 440 o Format message_1 as specified in Section 4.2.1. 442 4.2.3. Party V Processing of Message 1 444 Party V SHALL process message_1 as follows: 446 o Verify (OPTIONAL) that N_U has not been received before. 448 o Verify that at least one of each kind of the proposed algorithms 449 are supported. 451 o Verify that the ECDH curve used in E_U is supported, and that no 452 prior curve in ECDH-Curves_U is supported 454 If any verification step fails, Party V MUST send an EDHOC error 455 message back, formatted as defined in Section 6.1, and the protocol 456 MUST be discontinued. If V does not support the ECDH curve used in 457 E_U, but supports another ECDH curves in ECDH-Curves_U, then the 458 error message MUST include the following diagnostic payload 459 describing the first supported ECDH curve in ECDH-Curves_U: 461 ERR_MSG = "Curve not supported; X" 463 where X is the first curve in ECDH-Curves_U that V supports, 464 encoded as in Table 22 of {{I-D.ietf-cose-msg}}. 466 4.3. EDHOC Message 2 468 4.3.1. Formatting of Message 2 470 message_2 SHALL be a CBOR array as defined below 472 message_2 = [ 473 data_2, 474 COSE_ENC_2 : COSE_Encrypt0 475 ] 477 data_2 = ( 478 MSG_TYPE : int, 479 S_U : bstr, 480 S_V : bstr, 481 N_V : bstr, 482 E_V : serialized_COSE_Key, 483 HKDF_V : int / tstr, 484 AEAD_V : int / tstr, 485 SIG_V : int / tstr, 486 SIG_U : int / tstr 487 ) 489 aad_2 = bstr 491 where aad_2, in diagnostic non-normative notation, is: 493 aad_2 = message_1 | [ data_2 ] | ? Cert_V 495 where: 497 o MSG_TYPE = 2 499 o S_V - variable length session identifier 501 o N_V - 64-bit random nonce 503 o E_V - the ephemeral public key of Party V 505 o HKDF_V - a single chosen algorithm from HKDFs_U 507 o AEAD_V - a single chosen algorithm from AEADs_U 509 o SIG_V - a single chosen algorithm from SIGs_V with which Party V 510 signs 512 o SIG_U - a single chosen algorithm from SIGs_U with which Party U 513 signs 515 o COSE_ENC_2 has the following fields and values: 517 * external_aad = aad_2 519 * plaintext = [ COSE_SIG_V, ? APP_2 ] 521 o COSE_SIG_V is a COSE_Sign1 object with the following fields and 522 values: 524 * unprotected = { xyz: ID_V } 526 * detached payload = aad_2 528 o xyz - any COSE map label that can identify a public key, see 529 Section 4.1 531 o ID_V - identifier for the public key of Party V 533 o APP_2 - bstr containing application data 535 o Cert_V - The end-entity certificate of Party V 537 o H() - the hash function in HKDF_V 539 4.3.2. Party V Processing of Message 2 541 Party V SHALL compose message_2 as follows: 543 o Retrieve an ephemeral ECDH key pair generated as specified in 544 Section 5 of [SP-800-56a] using same curve as used in E_U. Format 545 the ephemeral public key E_V as a COSE_key as specified in 546 Section 3.1. 548 o Generate the pseudo-random nonce N_V 550 o Choose a session identifier S_V and store it for the length of the 551 protocol. 553 o Select HKDF_V, AEAD_V, SIG_V, and SIG_U from the algorithms 554 proposed in HKDFs_U, AEADs_U, SIGs_V, and SIGs_U. 556 o Format message_2 as specified in Section 4.3.1: 558 * COSE_Sign1 is computed as defined in section 4.4 of 559 [I-D.ietf-cose-msg], using algorithm SIG_V and the private key 560 of Party V. 562 * COSE_Encrypt0 is computed as defined in section 5.3 of 563 [I-D.ietf-cose-msg], with AEAD_V, K_2, and IV_2. The AEAD 564 algorithm MUST NOT be replaced by plain encryption, see 565 Section 8. 567 + If certificates are used then aad_2 MUST include Cert_V 569 4.3.3. Party U Processing of Message 2 571 Party U SHALL process message_2 as follows: 573 o Use the session identifier S_U to retrieve the protocol state. 575 o Verify that HKDF_V, AEAD_V, SIG_V, and SIG_U were proposed in 576 HKDFs_U, AEADs_U, SIGs_V, and SIGs_U. 578 o Verify (OPTIONAL) that N_V has not been received before. 580 o Verify message_2 as specified in Section 4.3.1: 582 * COSE_Encrypt0 is decrypted defined in section 5.3 of 583 [I-D.ietf-cose-msg], with AEAD_V, K_2, and IV_2. 585 * COSE_Sign1 is verified as defined in section 4.4 of 586 [I-D.ietf-cose-msg], using algorithm SIG_V and the public key 587 of Party V. 589 If any verification step fails, Party V MUST send an EDHOC error 590 message back, formatted as defined in Section 6.1, and the protocol 591 MUST be discontinued. 593 4.4. EDHOC Message 3 595 4.4.1. Formatting of Message 3 597 message_3 SHALL be a CBOR array as defined below 599 message_3 = [ 600 data_3, 601 COSE_ENC_3 : COSE_Encrypt0 602 ] 604 data_3 = ( 605 MSG_TYPE : int, 606 S_V : bstr 607 ) 609 aad_3 = bstr 610 where aad_3, in diagnostic non-normative notation, is: 612 aad_3 = H( message_1 | message_2 ) | [ data_3 ] | ? Cert_U 614 where: 616 o MSG_TYPE = 3 618 o COSE_ENC_3 has the following fields and values: 620 * external_aad = aad_3 622 * plaintext = [ COSE_SIG_U, ? APP_3 ] 624 o COSE_SIG_U is a COSE_Sign1 object with the following fields and 625 values: 627 * unprotected = { xyz: ID_U } 629 * detached payload = aad_3 631 o xyz - any COSE map label that can identify a public key, see 632 Section 4.1 634 o ID_U - identifier for the public key of Party U 636 o APP_3 - bstr containing application data 638 o Cert_U - The end-entity certificate of Party U 640 4.4.2. Party U Processing of Message 3 642 Party U SHALL compose message_3 as follows: 644 o Format message_3 as specified in Section 4.4.1: 646 * COSE_Sign1 is computed as defined in section 4.4 of 647 [I-D.ietf-cose-msg], using algorithm SIG_U and the private key 648 of Party U. 650 * COSE_Encrypt0 is computed as defined in section 5.3 of 651 [I-D.ietf-cose-msg], with AEAD_V, K_3, and IV_3. The AEAD 652 algorithm MUST NOT be replaced by plain encryption, see 653 Section 8. 655 + If certificates are used then aad_3 MUST include Cert_U 657 4.4.3. Party V Processing of Message 3 659 Party V SHALL process message_3 as follows: 661 o Use the session identifier S_V to retrieve the protocol state. 663 o Verify message_3 as specified in Section 4.4.1. 665 * COSE_Encrypt0 is decrypted as defined in section 5.3 of 666 [I-D.ietf-cose-msg], with AEAD_V, K_3, and IV_3. 668 * COSE_Sign1 is verified as defined in section 4.4 of 669 [I-D.ietf-cose-msg], using algorithm SIG_U and the public key 670 of Party U; 672 If any verification step fails, Party V MUST send an EDHOC error 673 message back, formatted as defined in Section 6.1, and the protocol 674 MUST be discontinued. 676 5. EDHOC Authenticated with Symmetric Keys 678 5.1. Overview 680 EDHOC supports authentication with pre-shared keys. Party U and V 681 are assumed to have a pre-shared uniformly random key (PSK) with the 682 requirement that: 684 o Party V SHALL be able to identify the PSK using KID. 686 KID either enable the other party to retrieve the PSK or contain the 687 PSK (e.g. CBOR Web Token). 689 EDHOC with symmetric key authentication is illustrated in Figure 4. 691 Party U Party V 692 | S_U, N_U, E_U, ALG_1, KID, APP_1 | 693 +------------------------------------------------------------------>| 694 | message_1 | 695 | | 696 | S_U, S_V, N_V, E_V, ALG_2, Enc(K_2; APP_2; aad_2) | 697 |<------------------------------------------------------------------+ 698 | message_2 | 699 | | 700 | S_V, Enc(K_3; APP_3; aad_3) | 701 +------------------------------------------------------------------>| 702 | message_3 | 704 Figure 4: EDHOC with symmetric key authentication. 706 5.1.1. Mandatory to Implement Algorithms 708 For EDHOC authenticated with symmetric keys, the COSE algorithms 709 ECDH-SS + HKDF-256 and AES-CCM-64-64-128 are mandatory to implement. 711 5.2. EDHOC Message 1 713 5.2.1. Formatting of Message 1 715 message_1 SHALL be a CBOR array as defined below 717 message_1 = [ 718 data_1 719 ] 721 data_1 = ( 722 MSG_TYPE : int, 723 S_U : bstr, 724 N_U : bstr, 725 E_U : serialized_COSE_Key, 726 ECDH-Curves_U : alg_array, 727 HKDFs_U : alg_array, 728 AEADs_U : alg_array, 729 KID : bstr, 730 ? APP_1 : bstr 731 ) 733 serialized_COSE_Key = bstr .cbor COSE_Key 735 alg_array = [ + alg : int / tstr ] 737 where: 739 o MSG_TYPE = 4 741 o S_U - variable length session identifier 743 o N_U - 64-bit random nonce 745 o E_U - the ephemeral public key of Party U 747 o ECDH-Curves_U - EC curves for ECDH which Party U supports, in the 748 order of decreasing preference 750 o HKDFs_U - supported ECDH-SS w/ HKDF algorithms 752 o AEADs_U - supported AEAD algorithms 753 o KID - identifier of the pre-shared key 755 o APP_1 - bstr containing application data 757 5.2.2. Party U Processing of Message 1 759 Party U SHALL compose message_1 as follows: 761 o Determine which ECDH curve to use with Party V. If U previously 762 received from Party V an error message to message_1 with 763 diagnostic payload identifying an ECDH curve in ECDH-Curves_U, 764 then U SHALL retrieve an ephemeral from that curve. Otherwise the 765 first curve in ECDH-Curves_U MUST be used. 767 o Retrieve an ephemeral ECDH key pair generated as specified in 768 Section 5 of [SP-800-56a] and format the ephemeral public key E_U 769 as a COSE_key as specified in Section 3.1. 771 o Generate the pseudo-random nonce N_U 773 o Choose a session identifier S_U and store it for the length of the 774 protocol. 776 o Format message_1 as specified in Section 5.2.1. 778 5.2.3. Party V Processing of Message 1 780 Party V SHALL process message_1 as follows: 782 o Verify (OPTIONAL) that N_U has not been received before. 784 o Verify that at least one of each kind of the proposed algorithms 785 are supported. 787 o Verify that the ECDH curve used in E_U is supported, and that no 788 prior curve in ECDH-Curves_U is supported. 790 If any verification step fails, Party V MUST send an EDHOC error 791 message back, formatted as defined in Section 6.1, and the protocol 792 MUST be discontinued. If V does not support the ECDH curve used in 793 E_U, but supports another ECDH curves in ECDH-Curves_U, then the 794 error message SHOULD include a diagnostic payload describing the 795 first supported ECDH curve in ECDH-Curves_U. 797 5.3. EDHOC Message 2 799 5.3.1. Formatting of Message 2 801 message_2 SHALL be a CBOR array as defined below 803 message_2 = [ 804 data_2, 805 COSE_ENC_2 : COSE_Encrypt0 806 ] 808 data_2 = ( 809 MSG_TYPE : int, 810 S_U : bstr, 811 S_V : bstr, 812 N_V : bstr, 813 E_V : serialized_COSE_Key, 814 HKDF_V : int / tstr, 815 AEAD_V : int / tstr 816 ) 818 aad_2, in diagnostic non-normative notation, is: 820 aad_2 = message_1 | [ data_2 ] 822 where: 824 o MSG_TYPE = 5 826 o S_V - variable length session identifier 828 o N_V - 64-bit random nonce 830 o E_V - the ephemeral public key of Party V 832 o HKDF_V - an single chosen algorithm from HKDFs_U 834 o AEAD_V - an single chosen algorithm from AEADs_U 836 o COSE_ENC_2 has the following fields and values: 838 * external_aad = aad_2 840 * plaintext = ? APP_2 842 o APP_2 - bstr containing application data 844 o H() - the hash function in HKDF_V 846 5.3.2. Party V Processing of Message 2 848 Party V SHALL compose message_2 as follows: 850 o Retrieve an ephemeral ECDH key pair generated as specified in 851 Section 5 of [SP-800-56a] using same curve as used in E_U. Format 852 the ephemeral public key E_V as a COSE_key as specified in 853 Section 3.1. 855 o Generate the pseudo-random nonce N_V 857 o Choose a session identifier S_V and store it for the length of the 858 protocol. 860 o Select HKDF_V and AEAD_V from the algorithms proposed in HKDFs_U 861 and AEADs_U. 863 o Format message_2 as specified in Section 5.3.1 where COSE_Encrypt0 864 is computed as defined in section 5.3 of [I-D.ietf-cose-msg], with 865 AEAD_V, K_2, and IV_2. 867 5.3.3. Party U Processing of Message 2 869 Party U SHALL process message_2 as follows: 871 o Use the session identifier S_U to retrieve the protocol state. 873 o Verify message_2 as specified in Section 5.3.1 where COSE_Encrypt0 874 is decrypted defined in section 5.3 of [I-D.ietf-cose-msg], with 875 AEAD_V, K_2, and IV_2. 877 If any verification step fails, Party U MUST send an EDHOC error 878 message back, formatted as defined in Section 6.1, and the protocol 879 MUST be discontinued. 881 5.4. EDHOC Message 3 883 5.4.1. Formatting of Message 3 885 message_3 SHALL be a CBOR array as defined below 886 message_3 = [ 887 data_3, 888 COSE_ENC_3 : COSE_Encrypt0 889 ] 891 data_3 = ( 892 MSG_TYPE : int, 893 S_V : bstr 894 ) 896 aad_3, in diagnostic non-normative notation, is: 898 aad_3 = H( message_1 | message_2 ) | [ data_3 ] 900 where: 902 o MSG_TYPE = 6 904 o COSE_ENC_3 has the following fields and values: 906 * external_aad = aad_3 908 * plaintext = ? APP_3 910 o APP_3 - bstr containing application data 912 5.4.2. Party U Processing of Message 3 914 Party U SHALL compose message_3 as follows: 916 o Format message_3 as specified in Section 5.4.1 where COSE_Encrypt0 917 is computed as defined in section 5.3 of [I-D.ietf-cose-msg], with 918 AEAD_V, K_3, and IV_3. 920 5.4.3. Party V Processing of Message 3 922 Party V SHALL process message_3 as follows: 924 o Use the session identifier S_V to retrieve the protocol state. 926 o Verify message_3 as specified in Section 5.4.1 where COSE_Encrypt0 927 is decrypted and verified as defined in section 5.3 of 928 [I-D.ietf-cose-msg], with AEAD_V, K_3, and IV_3. 930 If any verification step fails, Party V MUST send an EDHOC error 931 message back, formatted as defined in Section 6.1, and the protocol 932 MUST be discontinued. 934 6. Error Handling 936 6.1. Error Message Format 938 This section defines a message format for an EDHOC error message, 939 used during the protocol. This is an error on EDHOC level and is 940 independent of the transport layer used. An advantage of using such 941 a construction is to avoid issues created by usage of cross protocol 942 proxies (e.g. UDP to TCP). 944 error SHALL be a CBOR array as defined below 946 error = [ 947 MSG_TYPE : int, 948 ? ERR_MSG : tstr 949 ] 951 where: 953 o MSG_TYPE = 0 955 o ERR_MSG is an optional text string containing the diagnostic 956 payload, defined in the same way as in Section 5.5.2 of [RFC7252]. 958 7. IANA Considerations 960 7.1. Media Types Registry 962 IANA has added the media type 'application/edhoc' to the Media Types 963 registry: 965 Type name: application 967 Subtype name: edhoc 969 Required parameters: N/A 971 Optional parameters: N/A 973 Encoding considerations: binary 975 Security considerations: See Section 7 of this document. 977 Interoperability considerations: N/A 979 Published specification: [[this document]] (this document) 981 Applications that use this media type: To be identified 983 Fragment identifier considerations: N/A 985 Additional information: 987 * Magic number(s): N/A 989 * File extension(s): N/A 991 * Macintosh file type code(s): N/A 993 Person & email address to contact for further information: 994 Goeran Selander 996 Intended usage: COMMON 998 Restrictions on usage: N/A 1000 Author: Goeran Selander 1002 Change Controller: IESG 1004 8. Security Considerations 1006 EDHOC builds on the SIGMA-I family of theoretical protocols that 1007 provides perfect forward secrecy and identity protection with a 1008 minimal number of messages. The encryption algorithm of the SIGMA-I 1009 protocol provides identity protection, but the security of the 1010 protocol requires the MAC to cover the identity of the signer. Hence 1011 the message authenticating functionality of the authenticated 1012 encryption in EDHOC is critical: authenticated encryption MUST NOT be 1013 replaced by plain encryption only, even if authentication is provided 1014 at another level or through a different mechanism. 1016 EDHOC adds an explicit message type and expands the message 1017 authentication coverage to additional elements such as algorithms, 1018 application data, and previous messages. EDHOC uses the same Sign- 1019 then-MAC approach as TLS 1.3. 1021 EDHOC does not include negotiation of parameters related to the 1022 ephemeral key, but it enables Party V to verify that the ECDH curve 1023 used in the protocol is the most preferred curve by U which is 1024 supported by both U and V. 1026 Party U and V must make sure that unprotected data and metadata do 1027 not reveal any sensitive information. This also applies for 1028 encrypted data sent to an unauthenticated party. In particular, it 1029 applies to APP_1 and APP_2 in the asymmetric case, and APP_1 and KID 1030 in the symmetric case. The communicating parties may therefore 1031 anonymize KID. 1033 Using the same KID or unprotected application data in several EDHOC 1034 sessions allows passive eavesdroppers to correlate the different 1035 sessions. Another consideration is that the list of supported 1036 algorithms may be used to identify the application. 1038 Party U and V must make sure that unprotected data does not trigger 1039 any harmful actions. In particular, this applies to APP_1 in the 1040 asymmetric case, and APP_1 and KID in the symmetric case. Party V 1041 should be aware that replays of EDHOC message_1 cannot be detected 1042 unless previous nonces are stored. 1044 The availability of a secure pseudorandom number generator and truly 1045 random seeds are essential for the security of EDHOC. If no true 1046 random number generator is available, a truly random seed must be 1047 provided from an external source. If ECDSA is supported, 1048 "deterministic ECDSA" as specified in RFC6979 is RECOMMENDED. 1050 Nonces MUST NOT be reused, both parties MUST generate fresh random 1051 nonces. 1053 Ephemeral keys SHOULD NOT be reused, both parties SHOULD generate 1054 fresh random ephemeral key pairs. Party V MAY reuse the ephemeral 1055 key to limit the effect of certain DoS attacks. For example, to 1056 reduce processing costs in the case of repeated uncompleted protocol 1057 runs, party V MAY pre-compute its ephemeral key E_V and reuse it for 1058 a small number of concurrent EDHOC executions, for example until a 1059 number of EDHOC protocol instances has been successfully completed, 1060 which triggers party V to pre-compute a new ephemeral key E_V to use 1061 with subsequent protocol runs. 1063 The referenced processing instructions in [SP-800-56a] must be 1064 complied with, including deleting the intermediate computed values 1065 along with any ephemeral ECDH secrets after the key derivation is 1066 completed. 1068 Party U and V are responsible for verifying the integrity of 1069 certificates. The selection of trusted CAs should be done very 1070 carefully and certificate revocation should be supported. 1072 The choice of key length used in the different algorithms needs to be 1073 harmonized, so that a sufficient security level is maintained for 1074 certificates, EDHOC, and the protection of application data. Party U 1075 and V should enforce a minimum security level. 1077 Note that, depending on the application, the keys established through 1078 the EDHOC protocol will need to be renewed, in which case the 1079 communicating parties need to run the protocol again. 1081 Implementations should provide countermeasures to side-channel 1082 attacks such as timing attacks. 1084 9. Acknowledgments 1086 The authors want to thank Jim Schaad for reviewing intermediate 1087 versions and for contributing many concrete proposals incorporated in 1088 this version. We are also greatful to Ilari Liusvaara and Ludwig 1089 Seitz for reviewing previous versions of the draft. 1091 TODO: This section should be after Appendixes and before Author's 1092 address according to RFC7322. 1094 10. References 1096 10.1. Normative References 1098 [I-D.ietf-cose-msg] 1099 Schaad, J., "CBOR Object Signing and Encryption (COSE)", 1100 draft-ietf-cose-msg-24 (work in progress), November 2016. 1102 [I-D.schaad-cose-x509] 1103 Schaad, J., "CBOR Encoded Message Syntax (COSE): Headers 1104 for carrying and referencing X.509 certificates", draft- 1105 schaad-cose-x509-00 (work in progress), November 2016. 1107 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1108 Requirement Levels", BCP 14, RFC 2119, 1109 DOI 10.17487/RFC2119, March 1997, 1110 . 1112 [RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object 1113 Representation (CBOR)", RFC 7049, DOI 10.17487/RFC7049, 1114 October 2013, . 1116 [SIGMA] Krawczyk, H., "SIGMA - The 'SIGn-and-MAc' Approach to 1117 Authenticated Diffie-Hellman and Its Use in the IKE- 1118 Protocols (Long version)", June 2003, 1119 . 1121 [SP-800-56a] 1122 Barker, E., Chen, L., Roginsky, A., and M. Smid, 1123 "Recommendation for Pair-Wise Key Establishment Schemes 1124 Using Discrete Logarithm Cryptography", NIST Special 1125 Publication 800-56A Revision 2, May 2013, 1126 . 1128 10.2. Informative References 1130 [I-D.greevenbosch-appsawg-cbor-cddl] 1131 Birkholz, H., Vigano, C., and C. Bormann, "CBOR data 1132 definition language (CDDL): a notational convention to 1133 express CBOR data structures", draft-greevenbosch-appsawg- 1134 cbor-cddl-10 (work in progress), March 2017. 1136 [I-D.hartke-core-e2e-security-reqs] 1137 Selander, G., Palombini, F., and K. Hartke, "Requirements 1138 for CoAP End-To-End Security", draft-hartke-core-e2e- 1139 security-reqs-02 (work in progress), January 2017. 1141 [I-D.ietf-ace-oauth-authz] 1142 Seitz, L., Selander, G., Wahlstroem, E., Erdtman, S., and 1143 H. Tschofenig, "Authentication and Authorization for 1144 Constrained Environments (ACE)", draft-ietf-ace-oauth- 1145 authz-06 (work in progress), March 2017. 1147 [I-D.ietf-core-object-security] 1148 Selander, G., Mattsson, J., Palombini, F., and L. Seitz, 1149 "Object Security of CoAP (OSCOAP)", draft-ietf-core- 1150 object-security-02 (work in progress), March 2017. 1152 [I-D.ietf-core-resource-directory] 1153 Shelby, Z., Koster, M., Bormann, C., and P. Stok, "CoRE 1154 Resource Directory", draft-ietf-core-resource-directory-10 1155 (work in progress), March 2017. 1157 [I-D.seitz-ace-oscoap-profile] 1158 Seitz, L. and F. Palombini, "OSCOAP profile of ACE", 1159 draft-seitz-ace-oscoap-profile-01 (work in progress), 1160 October 2016. 1162 [RFC5869] Krawczyk, H. and P. Eronen, "HMAC-based Extract-and-Expand 1163 Key Derivation Function (HKDF)", RFC 5869, 1164 DOI 10.17487/RFC5869, May 2010, 1165 . 1167 [RFC7228] Bormann, C., Ersue, M., and A. Keranen, "Terminology for 1168 Constrained-Node Networks", RFC 7228, 1169 DOI 10.17487/RFC7228, May 2014, 1170 . 1172 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 1173 Application Protocol (CoAP)", RFC 7252, 1174 DOI 10.17487/RFC7252, June 2014, 1175 . 1177 Appendix A. Test Vectors 1179 TODO: This section needs to be updated. 1181 Appendix B. PSK Chaining 1183 An application using EDHOC with symmetric keys may have a security 1184 policy to change the PSK as a result of successfully completing the 1185 EDHOC protocol. In this case, the old PSK SHALL be replaced with a 1186 new PSK derived using other = exchange_hash, AlgorithmID = "EDHOC PSK 1187 Chaining" and keyDataLength equal to the key length of AEAD_V, see 1188 Section 3.2. 1190 Appendix C. EDHOC with CoAP and OSCOAP 1192 C.1. Transferring EDHOC in CoAP 1194 EDHOC can be transferred as an exchange of CoAP [RFC7252] messages, 1195 with the CoAP client as party U and the CoAP server as party V. By 1196 default EDHOC is sent to the Uri-Path: "/.well-known/edhoc", but an 1197 application may define its own path that can be discorvered e.g. 1198 using resource directory [I-D.ietf-core-resource-directory]. 1200 In practice, EDHOC message_1 is sent in the payload of a POST request 1201 from the client to the server's resource for EDHOC. EDHOC message_2 1202 or the EDHOC error message is sent from the server to the client in 1203 the payload of a 2.04 Changed response. EDHOC message_3 or the EDHOC 1204 error message is sent from the client to the server's resource in the 1205 payload of a POST request. If needed, an EDHOC error message is sent 1206 from the server to the client in the payload of a 2.04 Changed 1207 response 1209 An example of successful EDHOC exchange using CoAP is shown in 1210 Figure 5. 1212 Client Server 1213 | | 1214 +--------->| Header: POST (Code=0.02) 1215 | POST | Uri-Path: "/.well-known/edhoc" 1216 | | Content-Type: application/edhoc 1217 | | Payload: EDHOC message_1 1218 | | 1219 |<---------+ Header: 2.04 Changed 1220 | 2.04 | Content-Type: application/edhoc 1221 | | Payload: EDHOC message_2 1222 | | 1223 +--------->| Header: POST (Code=0.02) 1224 | POST | Uri-Path: "/.well-known/edhoc" 1225 | | Content-Type: application/edhoc 1226 | | Payload: EDHOC message_3 1227 | | 1228 |<---------+ Header: 2.04 Changed 1229 | 2.04 | 1230 | | 1232 Figure 5: Transferring EDHOC in CoAP 1234 C.2. Deriving an OSCOAP context from EDHOC 1236 When EDHOC is use to derive parameters for OSCOAP 1237 [I-D.ietf-core-object-security], the parties must make sure that the 1238 EDHOC session identifiers are unique Recipient IDs in OSCOAP. In 1239 case that the CoAP client is party U and the CoAP server is party V: 1241 o The AEAD Algorithm is AEAD_V, as defined in this document 1243 o The KDF algorithm is HKDF_V, as defined in this document 1245 o The Client's Sender ID is S_V, as defined in this document 1247 o The Server's Sender ID is S_U, as defined in this document 1248 o The Master Secret is derived as specified in Section 3.2 of this 1249 document, with other = exchange_hash, AlgorithmID = "EDHOC OSCOAP 1250 Master Secret" and keyDataLength equal to the key length of 1251 AEAD_V. 1253 o The Master Salt is derived as specified in Section 3.2 of this 1254 document, with other = exchange_hash, AlgorithmID = "EDHOC OSCOAP 1255 Master Salt" and keyDataLength equal to 64 bits. 1257 Authors' Addresses 1259 Goeran Selander 1260 Ericsson AB 1261 Faeroegatan 6 1262 Kista SE-164 80 Stockholm 1263 Sweden 1265 Email: goran.selander@ericsson.com 1267 John Mattsson 1268 Ericsson AB 1269 Faeroegatan 6 1270 Kista SE-164 80 Stockholm 1271 Sweden 1273 Email: john.mattsson@ericsson.com 1275 Francesca Palombini 1276 Ericsson AB 1277 Faeroegatan 6 1278 Kista SE-164 80 Stockholm 1279 Sweden 1281 Email: francesca.palombini@ericsson.com