idnits 2.17.1 draft-selander-ace-cose-ecdhe-05.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 (March 13, 2017) is 2594 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-09 == 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-05 == Outdated reference: A later version (-16) exists of draft-ietf-core-object-security-01 == Outdated reference: A later version (-06) exists of draft-seitz-ace-oscoap-profile-01 Summary: 2 errors (**), 0 flaws (~~), 7 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: September 14, 2017 Ericsson AB 6 March 13, 2017 8 Ephemeral Diffie-Hellman Over COSE (EDHOC) 9 draft-selander-ace-cose-ecdhe-05 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 September 14, 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 . . . . . . . . . . 7 60 4.1. Overview . . . . . . . . . . . . . . . . . . . . . . . . 7 61 4.2. EDHOC Message 1 . . . . . . . . . . . . . . . . . . . . . 8 62 4.3. EDHOC Message 2 . . . . . . . . . . . . . . . . . . . . . 10 63 4.4. EDHOC Message 3 . . . . . . . . . . . . . . . . . . . . . 12 64 5. EDHOC Authenticated with Symmetric Keys . . . . . . . . . . . 14 65 5.1. Overview . . . . . . . . . . . . . . . . . . . . . . . . 14 66 5.2. EDHOC Message 1 . . . . . . . . . . . . . . . . . . . . . 15 67 5.3. EDHOC Message 2 . . . . . . . . . . . . . . . . . . . . . 17 68 5.4. EDHOC Message 3 . . . . . . . . . . . . . . . . . . . . . 18 69 6. Error Handling . . . . . . . . . . . . . . . . . . . . . . . 20 70 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 20 71 7.1. Media Types Registry . . . . . . . . . . . . . . . . . . 20 72 8. Security Considerations . . . . . . . . . . . . . . . . . . . 21 73 9. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 23 74 10. References . . . . . . . . . . . . . . . . . . . . . . . . . 23 75 10.1. Normative References . . . . . . . . . . . . . . . . . . 23 76 10.2. Informative References . . . . . . . . . . . . . . . . . 24 77 Appendix A. Test Vectors . . . . . . . . . . . . . . . . . . . . 25 78 Appendix B. EDHOC with CoAP and OSCOAP . . . . . . . . . . . . . 25 79 B.1. Transferring EDHOC in CoAP . . . . . . . . . . . . . . . 25 80 B.2. Deriving an OSCOAP context from EDHOC . . . . . . . . . . 25 81 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 26 83 1. Introduction 85 Security at the application layer provides an attractive option for 86 protecting Internet of Things (IoT) deployments, for example where 87 transport layer security is not sufficient 88 [I-D.hartke-core-e2e-security-reqs]. IoT devices may be constrained 89 in various ways, including memory, storage, processing capacity, and 90 energy [RFC7228]. A method for protecting individual messages at the 91 application layer suitable for constrained devices, is provided by 92 CBOR Object Signing and Encryption (COSE) [I-D.ietf-cose-msg]), which 93 builds on the Concise Binary Object Representation (CBOR) [RFC7049]. 95 In order for a communication session to provide forward secrecy, the 96 communicating parties can run a Elliptic Curve Diffie-Hellman (ECDH) 97 key exchange protocol with ephemeral keys, from which shared key 98 material can be derived. This document specifies Ephemeral Diffie- 99 Hellman Over COSE (EDHOC), an authenticated ECDH protocol using CBOR 100 and COSE objects. Authentication is based on credentials established 101 out of band, e.g. from a trusted third party, such as an 102 Authorization Server as specified by [I-D.ietf-ace-oauth-authz]. 103 EDHOC supports authentication using pre-shared keys (PSK), raw public 104 keys (RPK), and certificates (Cert). Note that this document focuses 105 on authentication and key establishment: for integration with 106 authorization of resource access, refer to 107 [I-D.seitz-ace-oscoap-profile]. This document also specifies the 108 derivation of shared key material. 110 The ECDH exchange and the key derivation follow [SIGMA], NIST SP- 111 800-56a [SP-800-56a], and HKDF [RFC5869]. CBOR [RFC7049] and COSE 112 [I-D.ietf-cose-msg] are used to implement these standards. 114 1.1. Terminology 116 This document use the same informational CBOR Data Definition 117 Language (CDDL) [I-D.greevenbosch-appsawg-cbor-cddl] grammar as COSE 118 (see Section 1.3 of [I-D.ietf-cose-msg]). A vertical bar | denotes 119 byte string concatenation. 121 1.2. Requirements Language 123 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 124 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 125 document are to be interpreted as described in [RFC2119]. These 126 words may also appear in this document in lowercase, absent their 127 normative meanings. 129 2. Protocol Overview 131 SIGMA (SIGn-and-MAc) is a family of theoretical protocols with a 132 large number of variants [SIGMA]. Like IKEv2 and TLS 1.3, EDHOC is 133 built on a variant of the SIGMA protocol which provide identity 134 protection, and like TLS 1.3, EDHOC implements the SIGMA-I variant as 135 Sign-then-MAC. The SIGMA-I protocol using an AEAD algorithm is shown 136 in Figure 1. 138 Party U Party V 139 | E_U | 140 +------------------------------------------------------>| 141 | | 142 | E_V, Enc(K_2; ID_V, Sig(V; E_U, E_V);) | 143 |<------------------------------------------------------+ 144 | | 145 | Enc(K_3; ID_U, Sig(U; E_V, E_U);) | 146 +------------------------------------------------------>| 147 | | 149 Figure 1: AEAD variant of the SIGMA-I protocol 151 The parties exchanging messages are called "U" and "V". They 152 exchange identities and ephemeral public keys, compute the shared 153 secret, and derive the keying material. The messages are signed, 154 MACed, and encrypted. 156 o E_U and E_V are the ECDH ephemeral public keys of U and V, 157 respectively. 159 o ID_U and ID_V are identifiers for the public keys of U and V, 160 respectively. 162 o Sig(U; . ) and S(V; . ) denote signatures made with the private 163 key of U and V, respectively. 165 o Enc(K; P; A) denotes AEAD encryption of plaintext P and additional 166 authenticated data A using the key K derived from the shared 167 secret. The AEAD MUST NOT be replaced by plain encryption, see 168 Section 8. 170 As described in Appendix B of [SIGMA], in order to create a "full- 171 fledge" protocol some additional protocol elements are needed. EDHOC 172 adds: 174 o Explicit session identifiers S_U, S_V chosen by U and V, 175 respectively. 177 o Explicit nonces N_U, N_V chosen freshly and anew with each session 178 by U and V, respectively. 180 o Computationally independent keys derived from the ECDH shared 181 secret and used for encryption of different messages. 183 EDHOC also makes the following additions: 185 o Negotiation of key derivation, encryption, and signature 186 algorithms: 188 * U proposes one or more algorithms of the following kinds: 190 + HKDF 192 + AEAD 194 + Signature verification 196 + Signature generation 198 * V selects one algorithm of each kind 200 o Transmission of application defined extensions. 202 EDHOC is designed to encrypt and integrity protect as much 203 information as possible, and all symmetric keys are derived using as 204 much previous information as possible. EDHOC is furthermore designed 205 to be as compact and lightweight as possible, in terms of message 206 sizes, processing, and the ability to reuse already existing CBOR and 207 COSE libraries. EDHOC does not put any requirement on the lower 208 layers and can therefore be also be used e.g. in environments without 209 IP. 211 This paper is organized as follows: Section 3 specifies general 212 properties of EDHOC, including formatting of the ephemeral public 213 keys and key derivation, Section 4 specifies EDHOC with asymmetric 214 key authentication, Section 5 specifies EDHOC with symmetric key 215 authentication, and Appendix A provides a wealth of test vectors to 216 ease implementation and ensure interoperability. 218 3. EDHOC Overview 220 EDHOC consists of three messages (message_1, message_2, message_3) 221 that maps directly to the three messages in SIGMA-I. All EDHOC 222 messages consists of a CBOR array where the first element is an int 223 specifying the message type (MSG_TYPE). After creating EDHOC 224 message_3, Party U can derive the traffic key (master secret) and 225 protected application data can therefore be sent in parallel with 226 EDHOC message_3. The application data may e.g. be protected using 227 the negotiated AEAD algorithm. EDHOC may be used with the media type 228 application/edhoc defined in Section 7. 230 Party U Party V 231 | | 232 | ------------------ EDHOC message_1 -----------------> | 233 | | 234 | <----------------- EDHOC message_2 ------------------ | 235 | | 236 | ----------------- EDHOC message_3 ------------------> | 237 | | 238 | <----------- Protected Application Data ------------> | 239 | | 241 Figure 2: EDHOC message flow 243 The EDHOC message exchange may be authenticated using pre-shared keys 244 (PSK), raw public keys (RPK), or certificates (Cert). EDHOC assumes 245 the existence of mechanisms (certification authority, manual 246 distribution, etc.) for binding identities with authentication keys 247 (public or pre-shared). EDHOC with symmetric key authentication is 248 very similar to EDHOC with asymmetric key authentication, the 249 differences are that information is only MACed (not signed) and that 250 EDHOC with symmetric key authentication offers encryption, integrity 251 protection, and key proof-of-possession already in message_1. 253 EDHOC allows application defined extensions (EXT_1, EXT_2, EXT_3) to 254 be sent in the respective messages. When EDHOC are used with 255 asymmetric key authentication, EXT_1 is unprotected, EXT_2 is 256 protected (encrypted and integrity protected), but sent to an 257 unauthenticated party, and EXT_3 is protected and mutually 258 authenticated. When EDHOC is used with symmetric key authentication, 259 all extensions are protected and mutually authenticated. 261 3.1. Formatting of the Ephemeral Public Keys 263 The ECDH ephemeral public key SHALL be formatted as a COSE_Key of 264 type EC2 or OKP according to section 13.1 and 13.2 of 265 [I-D.ietf-cose-msg]. The curve X25519 is mandatory to implement. 266 For Elliptic Curve Keys of type EC2, point compression is mandatory 267 to implement. 269 3.2. Key Derivation 271 Key and IV derivation SHALL be done as specified in Section 11.1 of 272 [I-D.ietf-cose-msg] with the following input: 274 o The PRF SHALL be the HKDF [RFC5869] in the ECDH-SS w/ HKDF 275 negotiated during the message exchange (HKDF_V). 277 o The secret SHALL be the ECDH shared secret as defined in 278 Section 12.4.1 of [I-D.ietf-cose-msg]. 280 o salt = PSK / nil 282 o The context information SHALL be the serialized COSE_KDF_Context 283 with the following values: 285 * PartyInfo = ( nil, nil, nil ) 287 * SuppPubInfo SHALL contain: 289 + protected SHALL be a zero length bstr 291 + other = aad_1 / aad_2 / aad_3 / 292 H( H( H(message_1) | message_2 ) | message_3 ) | label 294 The salt SHALL only be present in the symmetric case. 296 The symmetric key and IV used to protect message_i is called K_i and 297 IV_i, and are derived using byte string aad_i defined for each EDHOC 298 message i = 1, 2 or 3 that make use of a symmetric key. 300 K_1 and IV_1 are only used in EDHOC with symmetric key authentication 301 and are derived with the exceptions that secret SHALL be empty and 302 the PRF SHALL be HKDF-256 (or a HKDF decided by the application). 304 All other keys are derived with the negotiated PRF and with the 305 secret set to the ECDH shared secret. 307 Application specific traffic keys and key identifiers are derived 308 using the byte string H( H( H(message_1) | message_2 ) | message_3 309 ) | label, where H() is the hash function in HKDF_V, label is a byte 310 string, and | denotes byte string concatenation. Each application 311 making use of EDHOC defines its own labels and how they are used. 313 4. EDHOC Authenticated with Asymmetric Keys 315 4.1. Overview 317 EDHOC supports authentication with raw public keys (RPK) and 318 certificates (Cert) with the requirements that: 320 o Party U's SHALL be able to uniquely identify Party V's public key 321 using ID_V. 323 o Party V's SHALL be able to uniquely identify Party U's public key 324 using ID_U. 326 ID_U and ID_V either enable the other party to retrieve the public 327 key (kid, x5t, x5u) or they contain the public key (x5c), see 328 [I-D.schaad-cose-x509]. Party U and party V MAY use different type 329 of credentials, e.g. one uses RPK and the other Cert. Party U and 330 party V MAY use different signature algorithms. 332 EDHOC with asymmetric key authentication is illustrated in Figure 3. 334 Party U Party V 335 | S_U, N_U, E_U, ALG_1, EXT_1 | 336 +--------------------------------------------------------------------->| 337 | message_1 | 338 | | 339 |S_U, S_V, N_V, E_V, ALG_2, Enc(K_2; EXT_2, ID_V, Sig(V; aad_2); aad_2)| 340 |<---------------------------------------------------------------------+ 341 | message_2 | 342 | | 343 | S_V, Enc(K_3; EXT_3, ID_U, Sig(U; aad_3); aad_3) | 344 +--------------------------------------------------------------------->| 345 | message_3 | 347 Figure 3: EDHOC with asymmetric key authentication. 349 4.1.1. Mandatory to Implement Algorithms 351 For EDHOC authenticated with asymmetric keys, the COSE algorithms 352 ECDH-SS + HKDF-256, AES-CCM-64-64-128, and EdDSA are mandatory to 353 implement. 355 4.2. EDHOC Message 1 357 4.2.1. Formatting of Message 1 359 message_1 SHALL be a CBOR array as defined below 360 message_1 = [ 361 MSG_TYPE : int, 362 S_U : bstr, 363 N_U : bstr, 364 E_U : serialized_COSE_Key, 365 HKDFs_U : alg_array, 366 AEADs_U : alg_array, 367 SIGs_V : alg_array, 368 SIGs_U : alg_array, 369 ? EXT_1 : bstr 370 ] 372 serialized_COSE_Key = bstr .cbor COSE_Key 374 alg_array = [ + alg : int / tstr ] 376 where: 378 o MSG_TYPE = 1 380 o S_U - variable length session identifier 382 o N_U - 64-bit random nonce 384 o E_U - the ephemeral public key of Party U 386 o HKDFs_U - supported ECDH-SS w/ HKDF algorithms 388 o AEADs_U - supported AEAD algorithms 390 o SIGs_V - signature algorithms, with which Party U supports 391 verification 393 o SIGs_U - signature algorithms, with which Party U supports signing 395 o EXT_1 - application defined extensions 397 4.2.2. Party U Processing of Message 1 399 Party U SHALL compose message_1 as follows: 401 o Generate a fresh ephemeral ECDH key pair as specified in Section 5 402 of [SP-800-56a] and format the ephemeral public key E_U as a 403 COSE_key as specified in Section 3.1. 405 o Generate the pseudo-random nonce N_U 406 o Chose a session identifier S_U and store it for the length of the 407 protocol. 409 o Format message_1 as specified in Section 4.2.1. 411 4.2.3. Party V Processing of Message 1 413 Party V SHALL process message_1 as follows: 415 o Verify (OPTIONAL) that N_U has not been received before. 417 o Verify that at least one of each kind of the proposed algorithms 418 are supported. 420 If any verification step fails, the message MUST be discarded and the 421 protocol discontinued. 423 4.3. EDHOC Message 2 425 4.3.1. Formatting of Message 2 427 message_2 SHALL be a CBOR array as defined below 429 message_2 = [ 430 data_2, 431 COSE_ENC_2 : COSE_Encrypt0 432 ] 434 data_2 = ( 435 MSG_TYPE : int, 436 S_U : bstr, 437 S_V : bstr, 438 N_V : bstr, 439 E_V : serialized_COSE_Key, 440 HKDF_V : int / tstr, 441 AEAD_V : int / tstr, 442 SIG_V : int / tstr, 443 SIG_U : int / tstr 444 ) 446 aad_2 = H(message_1) | [ data_2 ] | ? Cert_V 448 where: 450 o MSG_TYPE = 2 452 o S_V - variable length session identifier 453 o N_V - 64-bit random nonce 455 o E_V - the ephemeral public key of Party V 457 o HKDF_V - a single chosen algorithm from HKDFs_U 459 o AEAD_V - a single chosen algorithm from AEADs_U 461 o SIG_V - a single chosen algorithm from SIGs_V with which Party V 462 signs 464 o SIG_U - a single chosen algorithm from SIGs_U with which Party U 465 signs 467 o COSE_ENC_2 has the following fields and values: 469 * external_aad = aad_2 471 * plaintext = [ COSE_SIG_V, ? EXT_2 ] 473 o COSE_SIG_V is a COSE_Sign1 object with the following fields and 474 values: 476 * unprotected = { xyz: ID_V } 478 * detached payload = aad_2 480 o xyz - any COSE map label that can identify a public key 482 o ID_V - identifier for the public key of Party V 484 o EXT_2 - application defined extensions 486 o Cert_V - The end-entity certificate of Party V encoded as a bstr 488 o H() - the hash function in HKDF_V 490 4.3.2. Party V Processing of Message 2 492 Party V SHALL compose message_2 as follows: 494 o Generate a fresh ephemeral ECDH key pair as specified in Section 5 495 of [SP-800-56a] using same curve as used in E_U. Format the 496 ephemeral public key E_V as a COSE_key as specified in 497 Section 3.1. 499 o Generate the pseudo-random nonce N_V 500 o Chose a session identifier S_V and store it for the length of the 501 protocol. 503 o Select HKDF_V, AEAD_V, SIG_V, and SIG_U from the algorithms 504 proposed in HKDFs_U, AEADs_U, SIGs_V, and SIGs_U. 506 o Format message_2 as specified in Section 4.3.1: 508 * COSE_Sign1 is computed as defined in section 4.4 of 509 [I-D.ietf-cose-msg], using algorithm SIG_V and the private key 510 of Party V. 512 * COSE_Encrypt0 is computed as defined in section 5.3 of 513 [I-D.ietf-cose-msg], with AEAD_V, K_2, and IV_2. The AEAD 514 algorithm MUST NOT be replaced by plain encryption, see 515 Section 8. 517 + If certificates are used then aad_2 MUST include Cert_V 519 4.3.3. Party U Processing of Message 2 521 Party U SHALL process message_2 as follows: 523 o Use the session identifier S_U to retrieve the protocol state. 525 o Verify that HKDF_V, AEAD_V, SIG_V, and SIG_U were proposed in 526 HKDFs_U, AEADs_U, SIGs_V, and SIGs_U. 528 o Verify (OPTIONAL) that N_V has not been received before. 530 o Verify message_2 as specified in Section 4.3.1: 532 * COSE_Encrypt0 is decrypted defined in section 5.3 of 533 [I-D.ietf-cose-msg], with AEAD_V, K_2, and IV_2. 535 * COSE_Sign1 is verified as defined in section 4.4 of 536 [I-D.ietf-cose-msg], using algorithm SIG_V and the public key 537 of Party V. 539 If any verification step fails, the message MUST be discarded and the 540 protocol discontinued. 542 4.4. EDHOC Message 3 543 4.4.1. Formatting of Message 3 545 message_3 SHALL be a CBOR array as defined below 547 message_3 = [ 548 data_3, 549 COSE_ENC_3 : COSE_Encrypt0 550 ] 552 data_3 = ( 553 MSG_TYPE : int, 554 S_V : bstr 555 ) 557 aad_3 = H( H(message_1) | message_2 ) | [ data_3 ] | ? Cert_U 559 where: 561 o MSG_TYPE = 3 563 o COSE_ENC_3 has the following fields and values: 565 * external_aad = aad_3 567 * plaintext = [ COSE_SIG_U, ? EXT_3 ] 569 o COSE_SIG_U is a COSE_Sign1 object with the following fields and 570 values: 572 * unprotected = { xyz: ID_U } 574 * detached payload = aad_3 576 o xyz - any COSE map label that can identify a public key 578 o ID_U - identifier for the public key of Party U 580 o EXT_3 - application defined extensions 582 o Cert_U - The end-entity certificate of Party U encoded as a bstr 584 4.4.2. Party U Processing of Message 3 586 Party U SHALL compose message_3 as follows: 588 o Format message_3 as specified in Section 4.4.1: 590 * COSE_Sign1 is computed as defined in section 4.4 of 591 [I-D.ietf-cose-msg], using algorithm SIG_U and the private key 592 of Party U. 594 * COSE_Encrypt0 is computed as defined in section 5.3 of 595 [I-D.ietf-cose-msg], with AEAD_V, K_3, and IV_3. The AEAD 596 algorithm MUST NOT be replaced by plain encryption, see 597 Section 8. 599 + If certificates are used then aad_3 MUST include Cert_U 601 4.4.3. Party V Processing of Message 3 603 Party V SHALL process message_3 as follows: 605 o Use the session identifier S_V to retrieve the protocol state. 607 o Verify message_3 as specified in Section 4.4.1. 609 * COSE_Encrypt0 is decrypted as defined in section 5.3 of 610 [I-D.ietf-cose-msg], with AEAD_V, K_3, and IV_3. 612 * COSE_Sign1 is verified as defined in section 4.4 of 613 [I-D.ietf-cose-msg], using algorithm SIG_U and the public key 614 of Party U; 616 If any verification step fails, the message MUST be discarded and the 617 protocol discontinued. 619 5. EDHOC Authenticated with Symmetric Keys 621 5.1. Overview 623 EDHOC supports authentication with pre-shared keys. Party U and V 624 are assumed to have a pre-shared uniformly random key (PSK) with the 625 requirement that: 627 o Party V SHALL be able to uniquely identify the PSK using KID. 629 KID either enable the other party to retrieve the PSK or contain the 630 PSK (e.g. CBOR Web Token). 632 EDHOC with symmetric key authentication is illustrated in Figure 4. 634 Party U Party V 635 | S_U, N_U, E_U, ALG_1, KID, Enc(K_1; EXT_1; aad_1) | 636 +------------------------------------------------------------------>| 637 | message_1 | 638 | | 639 | S_U, S_V, N_V, E_V, ALG_2, Enc(K_2; EXT_2; aad_2) | 640 |<------------------------------------------------------------------+ 641 | message_2 | 642 | | 643 | S_V, Enc(K_3; EXT_3; aad_3) | 644 +------------------------------------------------------------------>| 645 | message_3 | 647 Figure 4: EDHOC with symmetric key authentication. 649 5.1.1. Mandatory to Implement Algorithms 651 For EDHOC authenticated with symmetric keys, the COSE algorithms 652 ECDH-SS + HKDF-256 and AES-CCM-64-64-128 are mandatory to implement. 654 5.2. EDHOC Message 1 656 5.2.1. Formatting of Message 1 658 message_1 SHALL be a CBOR array as defined below 660 message_1 = [ 661 data_1, 662 COSE_ENC_1 : COSE_Encrypt0 663 ] 665 data_1 = ( 666 MSG_TYPE : int, 667 S_U : bstr, 668 N_U : bstr, 669 E_U : serialized_COSE_Key, 670 HKDFs_U : alg_array, 671 AEADs_U : alg_array, 672 KID : bstr 673 ) 675 aad_1 = [ data_1 ] 677 serialized_COSE_Key = bstr .cbor COSE_Key 679 alg_array = [ + alg : int / tstr ] 681 where: 683 o MSG_TYPE = 4 685 o S_U - variable length session identifier 687 o N_U - 64-bit random nonce 689 o E_U - the ephemeral public key of Party U 691 o HKDFs_U - supported ECDH-SS w/ HKDF algorithms 693 o AEADs_U - supported AEAD algorithms 695 o KID - identifier of the pre-shared key 697 o COSE_ENC_1 has the following fields and values: 699 * external_aad = aad_1 701 * plaintext = ? EXT_1 703 o EXT_1 - bstr containing application defined extensions 705 5.2.2. Party U Processing of Message 1 707 Party U SHALL compose message_1 as follows: 709 o Generate a fresh ephemeral ECDH key pair as specified in Section 5 710 of [SP-800-56a] and format the ephemeral public key E_U as a 711 COSE_key as specified in Section 3.1. 713 o Generate the pseudo-random nonce N_U 715 o Chose a session identifier S_U and store it for the length of the 716 protocol. 718 o Format message_1 as specified in Section 5.2.1 where COSE_Encrypt0 719 is computed as defined in section 5.3 of [I-D.ietf-cose-msg], with 720 AES-CCM-64-64-128 (or an AEAD decided by the application), K_1, 721 and IV_1. 723 5.2.3. Party V Processing of Message 1 725 Party V SHALL process message_1 as follows: 727 o Verify (OPTIONAL) that N_U has not been received before. 729 o Verify that at least one of each kind of the proposed algorithms 730 are supported. 732 o Verify message_1 as specified in Section 5.2.1 where COSE_Encrypt0 733 is decrypted defined in section 5.3 of [I-D.ietf-cose-msg], with 734 AES-CCM-64-64-128 (or an AEAD decided by the application), K_1, 735 and IV_1. 737 If any verification step fails, the message MUST be discarded and the 738 protocol discontinued. 740 5.3. EDHOC Message 2 742 5.3.1. Formatting of Message 2 744 message_2 SHALL be a CBOR array as defined below 746 message_2 = [ 747 data_2, 748 COSE_ENC_2 : COSE_Encrypt0 749 ] 751 data_2 = ( 752 MSG_TYPE : int, 753 S_U : bstr, 754 S_V : bstr, 755 N_V : bstr, 756 E_V : serialized_COSE_Key, 757 HKDF_V : int / tstr, 758 AEAD_V : int / tstr 759 ) 761 aad_2 = H(message_1) | [ data_2 ] 763 where: 765 o MSG_TYPE = 5 767 o S_V - variable length session identifier 769 o N_V - 64-bit random nonce 771 o E_V - the ephemeral public key of Party V 773 o HKDF_V - an single chosen algorithm from HKDFs_U 775 o AEAD_V - an single chosen algorithm from AEADs_U 777 o COSE_ENC_2 has the following fields and values: 779 * external_aad = aad_2 780 * plaintext = ? EXT_2 782 o EXT_2 - bstr containing application defined extensions 784 o H() - the hash function in HKDF_V 786 5.3.2. Party V Processing of Message 2 788 Party V SHALL compose message_2 as follows: 790 o Generate a fresh ephemeral ECDH key pair as specified in Section 5 791 of [SP-800-56a] using same curve as used in E_U. Format the 792 ephemeral public key E_V as a COSE_key as specified in 793 Section 3.1. 795 o Generate the pseudo-random nonce N_V 797 o Chose a session identifier S_V and store it for the length of the 798 protocol. 800 o Select HKDF_V and AEAD_V from the algorithms proposed in HKDFs_U 801 and AEADs_U. 803 o Format message_2 as specified in Section 5.3.1 where COSE_Encrypt0 804 is computed as defined in section 5.3 of [I-D.ietf-cose-msg], with 805 AEAD_V, K_2, and IV_2. 807 5.3.3. Party U Processing of Message 2 809 Party U SHALL process message_2 as follows: 811 o Use the session identifier S_U to retrieve the protocol state. 813 o Verify message_2 as specified in Section 5.3.1 where COSE_Encrypt0 814 is decrypted defined in section 5.3 of [I-D.ietf-cose-msg], with 815 AEAD_V, K_2, and IV_2. 817 If any verification step fails, the message MUST be discarded and the 818 protocol discontinued. 820 5.4. EDHOC Message 3 822 5.4.1. Formatting of Message 3 824 message_3 SHALL be a CBOR array as defined below 825 message_3 = [ 826 data_3, 827 COSE_ENC_3 : COSE_Encrypt0 828 ] 830 data_3 = ( 831 MSG_TYPE : int, 832 S_V : bstr 833 ) 835 aad_3 = H( H(message_1) | message_2 ) | [ data_3 ] 837 where: 839 o MSG_TYPE = 6 841 o COSE_ENC_3 has the following fields and values: 843 * external_aad = aad_3 845 * plaintext = ? EXT_3 847 o EXT_3 - bstr containing application defined extensions 849 5.4.2. Party U Processing of Message 3 851 Party U SHALL compose message_3 as follows: 853 o Format message_3 as specified in Section 5.4.1 where COSE_Encrypt0 854 is computed as defined in section 5.3 of [I-D.ietf-cose-msg], with 855 AEAD_V, K_3, and IV_3. 857 5.4.3. Party V Processing of Message 3 859 Party V SHALL process message_3 as follows: 861 o Use the session identifier S_V to retrieve the protocol state. 863 o Verify message_3 as specified in Section 5.4.1 where COSE_Encrypt0 864 is decrypted and verified as defined in section 5.3 of 865 [I-D.ietf-cose-msg], with AEAD_V, K_3, and IV_3. 867 If any verification step fails, the message MUST be discarded and the 868 protocol discontinued. 870 6. Error Handling 872 TODO: One error is e.g. if the ephemeral key is unsupported. 874 7. IANA Considerations 876 7.1. Media Types Registry 878 IANA has added the media type 'application/edhoc' to the Media Types 879 registry: 881 Type name: application 883 Subtype name: edhoc 885 Required parameters: N/A 887 Optional parameters: N/A 889 Encoding considerations: binary 891 Security considerations: See Section 7 of this document. 893 Interoperability considerations: N/A 895 Published specification: [[this document]] (this document) 897 Applications that use this media type: To be identified 899 Fragment identifier considerations: N/A 901 Additional information: 903 * Magic number(s): N/A 905 * File extension(s): N/A 907 * Macintosh file type code(s): N/A 909 Person & email address to contact for further information: 910 Goeran Selander 912 Intended usage: COMMON 914 Restrictions on usage: N/A 916 Author: Goeran Selander 918 Change Controller: IESG 920 8. Security Considerations 922 EDHOC builds on the SIGMA-I family of theoretical protocols that 923 provides perfect forward secrecy and identity protection with a 924 minimal number of messages. The encryption algorithm of the SIGMA-I 925 protocol provides identity protection, but the security of the 926 protocol requires the MAC to cover the identity of the signer. Hence 927 the message authenticating functionality of the authenticated 928 encryption in EDHOC is critical: authenticated encryption MUST NOT be 929 replaced by plain encryption only, even if authentication is provided 930 at another level or through a different mechanism. 932 EDHOC adds an explicit message type and expands the authentication 933 coverage to additional elements such as algorithms, extensions, and 934 previous messages. EDHOC uses the same Sign-then-MAC approach as TLS 935 1.3. 937 Party U and V must make sure that unprotected data and metadata do 938 not reveal any sensitive information. This also applies for 939 encrypted data sent to an unauthenticated party. In particular, it 940 applies to EXT_1 and EXT_2 in the asymmetrical case, and KID in the 941 symmetrical case. The communicating parties may therefore anonymize 942 KID. 944 Using the same KID or unprotected extension in several EDHOC sessions 945 allows passive eavesdroppers to correlate the different sessions. 946 Another consideration is that the list of supported algorithms may be 947 used to identify the application. 949 Party U and V must make sure that unprotected data does not trigger 950 any harmful actions. In particular, this applies to EXT_1 in the 951 asymmetrical case, and KID in the symmetrical case. Party V should 952 be aware that replays of EDHOC message_1 cannot be detected unless 953 unless previous nonces are stored. 955 The availability of a secure pseudorandom number generator and truly 956 random seeds are essential for the security of EDHOC. If no true 957 random number generator is available, a truly random seed must be 958 provided from an external source. If ECDSA is supported, 959 "deterministic ECDSA" as specified in RFC6979 is RECOMMENDED. 961 Nonces MUST NOT be reused, both parties MUST generate fresh random 962 nonces. Ephemeral keys SHOULD NOT be reused, both parties SHOULD 963 generate fresh random ephemeral key pairs. 965 The referenced processing instructions in [SP-800-56a] must be 966 complied with, including deleting the intermediate computed values 967 along with any ephemeral ECDH secrets after the key derivation is 968 completed. 970 Party U and V are responsible for verifying the integrity of 971 certificates. The selection of trusted CAs should be done very 972 carefully and certificate revocation should be supported. 974 The choice of key length used in the different algorithms needs to be 975 harmonized, so that a sufficient security level is maintained for 976 certificates, EDHOC, and the protection of application data. Party U 977 and V should enforce a minimum security level. 979 Note that, depending on the application, the keys established through 980 the EDHOC protocol will need to be renewed, in which case the 981 communicating parties need to run the protocol again. 983 Implementations should provide countermeasures to side-channel 984 attacks such as timing attacks. 986 9. Acknowledgments 988 The authors want to thank Jim Schaad, Ilari Liusvaara and Ludwig 989 Seitz for reviewing previous versions of the draft. 991 TODO: This section should be after Appendixes and before Author's 992 address according to RFC7322. 994 10. References 996 10.1. Normative References 998 [I-D.ietf-cose-msg] 999 Schaad, J., "CBOR Object Signing and Encryption (COSE)", 1000 draft-ietf-cose-msg-24 (work in progress), November 2016. 1002 [I-D.schaad-cose-x509] 1003 Schaad, J., "CBOR Encoded Message Syntax (COSE): Headers 1004 for carrying and referencing X.509 certificates", draft- 1005 schaad-cose-x509-00 (work in progress), November 2016. 1007 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1008 Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/ 1009 RFC2119, March 1997, 1010 . 1012 [RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object 1013 Representation (CBOR)", RFC 7049, DOI 10.17487/RFC7049, 1014 October 2013, . 1016 [SIGMA] Krawczyk, H., "SIGMA - The 'SIGn-and-MAc' Approach to 1017 Authenticated Diffie-Hellman and Its Use in the IKE- 1018 Protocols (Long version)", June 2003, 1019 . 1021 [SP-800-56a] 1022 Barker, E., Chen, L., Roginsky, A., and M. Smid, 1023 "Recommendation for Pair-Wise Key Establishment Schemes 1024 Using Discrete Logarithm Cryptography", NIST Special 1025 Publication 800-56A Revision 2, May 2013, 1026 . 1028 10.2. Informative References 1030 [I-D.greevenbosch-appsawg-cbor-cddl] 1031 Vigano, C. and H. Birkholz, "CBOR data definition language 1032 (CDDL): a notational convention to express CBOR data 1033 structures", draft-greevenbosch-appsawg-cbor-cddl-09 (work 1034 in progress), September 2016. 1036 [I-D.hartke-core-e2e-security-reqs] 1037 Selander, G., Palombini, F., and K. Hartke, "Requirements 1038 for CoAP End-To-End Security", draft-hartke-core-e2e- 1039 security-reqs-02 (work in progress), January 2017. 1041 [I-D.ietf-ace-oauth-authz] 1042 Seitz, L., Selander, G., Wahlstroem, E., Erdtman, S., and 1043 H. Tschofenig, "Authentication and Authorization for 1044 Constrained Environments (ACE)", draft-ietf-ace-oauth- 1045 authz-05 (work in progress), February 2017. 1047 [I-D.ietf-core-object-security] 1048 Selander, G., Mattsson, J., Palombini, F., and L. Seitz, 1049 "Object Security of CoAP (OSCOAP)", draft-ietf-core- 1050 object-security-01 (work in progress), December 2016. 1052 [I-D.seitz-ace-oscoap-profile] 1053 Seitz, L. and F. Palombini, "OSCOAP profile of ACE", 1054 draft-seitz-ace-oscoap-profile-01 (work in progress), 1055 October 2016. 1057 [RFC5869] Krawczyk, H. and P. Eronen, "HMAC-based Extract-and-Expand 1058 Key Derivation Function (HKDF)", RFC 5869, DOI 10.17487/ 1059 RFC5869, May 2010, 1060 . 1062 [RFC7228] Bormann, C., Ersue, M., and A. Keranen, "Terminology for 1063 Constrained-Node Networks", RFC 7228, DOI 10.17487/ 1064 RFC7228, May 2014, 1065 . 1067 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 1068 Application Protocol (CoAP)", RFC 7252, DOI 10.17487/ 1069 RFC7252, June 2014, 1070 . 1072 Appendix A. Test Vectors 1074 TODO: This section needs to be updated. 1076 Appendix B. EDHOC with CoAP and OSCOAP 1078 B.1. Transferring EDHOC in CoAP 1080 EDHOC can be transferred as an exchange of CoAP [RFC7252] messages, 1081 with the CoAP client as party U and the CoAP server as party V. By 1082 default EDHOC is sent to the Uri-Path: "edhoc". 1084 Client Server 1085 | | 1086 +--------->| Header: POST (Code=0.02) 1087 | POST | Uri-Path: "edhoc" 1088 | | Content-Type: application/edhoc 1089 | | Payload: EDHOC message_1 1090 | | 1091 |<---------+ Header: 2.04 Changed 1092 | 2.04 | Content-Type: application/edhoc 1093 | | Payload: EDHOC message_2 1094 | | 1095 +--------->| Header: POST (Code=0.02) 1096 | POST | Uri-Path: "edhoc" 1097 | | Content-Type: application/edhoc 1098 | | Payload: EDHOC message_3 1099 | | 1100 |<---------+ Header: 2.04 Changed 1101 | 2.04 | 1102 | | 1104 Figure 5: Transferring EDHOC in CoAP 1106 B.2. Deriving an OSCOAP context from EDHOC 1108 When EDHOC is use to derive parameters for OSCOAP 1109 [I-D.ietf-core-object-security], the parties must make sure that the 1110 EDHOC session identifiers are unique Recipient IDs in OSCOAP. In 1111 case that the CoAP client is party U and the CoAP server is party V: 1113 o The AEAD Algorithm is AEAD_V, as defined in this document 1114 o The KDF algorithm is HKDF_V, as defined in this document 1116 o The Client's Sender ID is S_V, as defined in this document 1118 o The Server's Sender ID is S_U, as defined in this document 1120 o The Master Secret is derived as specified in Section 3.2 of this 1121 document, with label = "OSCOAP Master Secret". The length is 1122 equal to the key length of AEAD_V. 1124 o The Master Salt is derived as specified in Section 3.2 of this 1125 document, with label = "OSCOAP Master Salt". The length is 64 1126 bits. 1128 Authors' Addresses 1130 Goeran Selander 1131 Ericsson AB 1132 Faeroegatan 6 1133 Kista SE-164 80 Stockholm 1134 Sweden 1136 Email: goran.selander@ericsson.com 1138 John Mattsson 1139 Ericsson AB 1140 Faeroegatan 6 1141 Kista SE-164 80 Stockholm 1142 Sweden 1144 Email: john.mattsson@ericsson.com 1146 Francesca Palombini 1147 Ericsson AB 1148 Faeroegatan 6 1149 Kista SE-164 80 Stockholm 1150 Sweden 1152 Email: francesca.palombini@ericsson.com