idnits 2.17.1 draft-selander-ace-cose-ecdhe-13.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 11, 2019) is 1873 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 (-16) exists of draft-ietf-cbor-7049bis-05 -- Possible downref: Normative reference to a draft: ref. 'I-D.ietf-cbor-7049bis' == Outdated reference: A later version (-08) exists of draft-ietf-cbor-cddl-07 == Outdated reference: A later version (-14) exists of draft-ietf-core-echo-request-tag-03 == Outdated reference: A later version (-16) exists of draft-ietf-core-object-security-15 ** Downref: Normative reference to an Informational draft: draft-schaad-cose-x509 (ref. 'I-D.schaad-cose-x509') ** Downref: Normative reference to an Informational RFC: RFC 5869 ** Downref: Normative reference to an Informational RFC: RFC 6090 ** Downref: Normative reference to an Informational RFC: RFC 6979 ** Obsolete normative reference: RFC 8152 (Obsoleted by RFC 9052, RFC 9053) -- Possible downref: Non-RFC (?) normative reference: ref. 'SIGMA' -- Possible downref: Non-RFC (?) normative reference: ref. 'SP-800-56A' == Outdated reference: A later version (-04) exists of draft-ietf-6tisch-dtsecurity-zerotouch-join-03 == Outdated reference: A later version (-46) exists of draft-ietf-ace-oauth-authz-22 == Outdated reference: A later version (-19) exists of draft-ietf-ace-oscore-profile-07 == Outdated reference: A later version (-28) exists of draft-ietf-core-resource-directory-19 == Outdated reference: A later version (-07) exists of draft-ietf-lwig-security-protocol-comparison-02 == Outdated reference: A later version (-43) exists of draft-ietf-tls-dtls13-30 Summary: 5 errors (**), 0 flaws (~~), 11 warnings (==), 4 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 12, 2019 Ericsson AB 6 March 11, 2019 8 Ephemeral Diffie-Hellman Over COSE (EDHOC) 9 draft-selander-ace-cose-ecdhe-13 11 Abstract 13 This document specifies Ephemeral Diffie-Hellman Over COSE (EDHOC), a 14 very compact, and lightweight authenticated Diffie-Hellman key 15 exchange with ephemeral keys. EDHOC provides mutual authentication, 16 perfect forward secrecy, and identity protection. EDHOC is intended 17 for usage in constrained scenarios and a main use case is to 18 establish an OSCORE security context. By reusing COSE for 19 cryptography, CBOR for encoding, and CoAP for transport, the 20 additional code footprint can be kept very low. 22 Status of This Memo 24 This Internet-Draft is submitted in full conformance with the 25 provisions of BCP 78 and BCP 79. 27 Internet-Drafts are working documents of the Internet Engineering 28 Task Force (IETF). Note that other groups may also distribute 29 working documents as Internet-Drafts. The list of current Internet- 30 Drafts is at https://datatracker.ietf.org/drafts/current/. 32 Internet-Drafts are draft documents valid for a maximum of six months 33 and may be updated, replaced, or obsoleted by other documents at any 34 time. It is inappropriate to use Internet-Drafts as reference 35 material or to cite them other than as "work in progress." 37 This Internet-Draft will expire on September 12, 2019. 39 Copyright Notice 41 Copyright (c) 2019 IETF Trust and the persons identified as the 42 document authors. All rights reserved. 44 This document is subject to BCP 78 and the IETF Trust's Legal 45 Provisions Relating to IETF Documents 46 (https://trustee.ietf.org/license-info) in effect on the date of 47 publication of this document. Please review these documents 48 carefully, as they describe your rights and restrictions with respect 49 to this document. Code Components extracted from this document must 50 include Simplified BSD License text as described in Section 4.e of 51 the Trust Legal Provisions and are provided without warranty as 52 described in the Simplified BSD License. 54 Table of Contents 56 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 57 1.1. Rationale for EDHOC . . . . . . . . . . . . . . . . . . . 4 58 1.2. Terminology and Requirements Language . . . . . . . . . . 5 59 2. Background . . . . . . . . . . . . . . . . . . . . . . . . . 5 60 3. EDHOC Overview . . . . . . . . . . . . . . . . . . . . . . . 7 61 3.1. Cipher Suites . . . . . . . . . . . . . . . . . . . . . . 8 62 3.2. Ephemeral Public Keys . . . . . . . . . . . . . . . . . . 9 63 3.3. Key Derivation . . . . . . . . . . . . . . . . . . . . . 9 64 4. EDHOC Authenticated with Asymmetric Keys . . . . . . . . . . 11 65 4.1. Overview . . . . . . . . . . . . . . . . . . . . . . . . 11 66 4.2. EDHOC Message 1 . . . . . . . . . . . . . . . . . . . . . 13 67 4.3. EDHOC Message 2 . . . . . . . . . . . . . . . . . . . . . 15 68 4.4. EDHOC Message 3 . . . . . . . . . . . . . . . . . . . . . 18 69 5. EDHOC Authenticated with Symmetric Keys . . . . . . . . . . . 20 70 5.1. Overview . . . . . . . . . . . . . . . . . . . . . . . . 20 71 5.2. EDHOC Message 1 . . . . . . . . . . . . . . . . . . . . . 21 72 5.3. EDHOC Message 2 . . . . . . . . . . . . . . . . . . . . . 21 73 5.4. EDHOC Message 3 . . . . . . . . . . . . . . . . . . . . . 22 74 6. Error Handling . . . . . . . . . . . . . . . . . . . . . . . 22 75 6.1. EDHOC Error Message . . . . . . . . . . . . . . . . . . . 22 76 7. Transferring EDHOC and Deriving Application Keys . . . . . . 24 77 7.1. Transferring EDHOC in CoAP . . . . . . . . . . . . . . . 24 78 7.2. Transferring EDHOC over Other Protocols . . . . . . . . . 27 79 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 27 80 8.1. EDHOC Cipher Suites Registry . . . . . . . . . . . . . . 27 81 8.2. EDHOC Method Type Registry . . . . . . . . . . . . . . . 27 82 8.3. The Well-Known URI Registry . . . . . . . . . . . . . . . 27 83 8.4. Media Types Registry . . . . . . . . . . . . . . . . . . 27 84 8.5. CoAP Content-Formats Registry . . . . . . . . . . . . . . 28 85 9. Security Considerations . . . . . . . . . . . . . . . . . . . 29 86 9.1. Security Properties . . . . . . . . . . . . . . . . . . . 29 87 9.2. Cryptographic Considerations . . . . . . . . . . . . . . 30 88 9.3. Mandatory to Implement Cipher Suite . . . . . . . . . . . 30 89 9.4. Unprotected Data . . . . . . . . . . . . . . . . . . . . 31 90 9.5. Denial-of-Service . . . . . . . . . . . . . . . . . . . . 31 91 9.6. Implementation Considerations . . . . . . . . . . . . . . 31 92 9.7. Other Documents Referencing EDHOC . . . . . . . . . . . . 32 93 10. References . . . . . . . . . . . . . . . . . . . . . . . . . 32 94 10.1. Normative References . . . . . . . . . . . . . . . . . . 32 95 10.2. Informative References . . . . . . . . . . . . . . . . . 34 96 Appendix A. Use of CBOR, CDDL and COSE in EDHOC . . . . . . . . 36 97 A.1. CBOR and CDDL . . . . . . . . . . . . . . . . . . . . . . 36 98 A.2. COSE . . . . . . . . . . . . . . . . . . . . . . . . . . 38 99 Appendix B. Example Messages and Sizes . . . . . . . . . . . . . 40 100 B.1. Message Sizes RPK . . . . . . . . . . . . . . . . . . . . 40 101 B.2. Message Sizes Certificates . . . . . . . . . . . . . . . 42 102 B.3. Message Sizes PSK . . . . . . . . . . . . . . . . . . . . 42 103 B.4. Summary . . . . . . . . . . . . . . . . . . . . . . . . . 43 104 Appendix C. Test Vectors . . . . . . . . . . . . . . . . . . . . 44 105 Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . 44 106 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 44 108 1. Introduction 110 Security at the application layer provides an attractive option for 111 protecting Internet of Things (IoT) deployments, for example where 112 transport layer security is not sufficient 113 [I-D.hartke-core-e2e-security-reqs] or where the protection needs to 114 work over a variety of underlying protocols. IoT devices may be 115 constrained in various ways, including memory, storage, processing 116 capacity, and energy [RFC7228]. A method for protecting individual 117 messages at the application layer suitable for constrained devices, 118 is provided by CBOR Object Signing and Encryption (COSE) [RFC8152]), 119 which builds on the Concise Binary Object Representation (CBOR) 120 [I-D.ietf-cbor-7049bis]. Object Security for Constrained RESTful 121 Environments (OSCORE) [I-D.ietf-core-object-security] is a method for 122 application-layer protection of the Constrained Application Protocol 123 (CoAP), using COSE. 125 In order for a communication session to provide forward secrecy, the 126 communicating parties can run an Elliptic Curve Diffie-Hellman (ECDH) 127 key exchange protocol with ephemeral keys, from which shared key 128 material can be derived. This document specifies Ephemeral Diffie- 129 Hellman Over COSE (EDHOC), a lightweight key exchange protocol 130 providing perfect forward secrecy and identity protection. 131 Authentication is based on credentials established out of band, e.g. 132 from a trusted third party, such as an Authorization Server as 133 specified by [I-D.ietf-ace-oauth-authz]. EDHOC supports 134 authentication using pre-shared keys (PSK), raw public keys (RPK), 135 and public key certificates. After successful completion of the 136 EDHOC protocol, application keys and other application specific data 137 can be derived using the EDHOC-Exporter interface. A main use case 138 for EDHOC is to establish an OSCORE security context. EDHOC uses 139 COSE for cryptography, CBOR for encoding, and CoAP for transport. By 140 reusing existing libraries, the additional code footprint can be kept 141 very low. Note that this document focuses on authentication and key 142 establishment: for integration with authorization of resource access, 143 refer to [I-D.ietf-ace-oscore-profile]. 145 EDHOC is designed to work in highly constrained scenarios making it 146 especially suitable for network technologies such as Cellular IoT, 147 6TiSCH [I-D.ietf-6tisch-dtsecurity-zerotouch-join], LoRaWAN 148 [LoRa1][LoRa2]. These network technologies are characterized by 149 their low throughput, low power consumption, and small frame sizes. 150 Compared to the DTLS 1.3 handshake [I-D.ietf-tls-dtls13] with ECDH 151 and connection ID, the number of bytes in EDHOC is less than 1/4 when 152 PSK authentication is used and less than 1/3 when RPK authentication 153 is used, see Appendix B. 155 The ECDH exchange and the key derivation follow [SIGMA], NIST SP- 156 800-56A [SP-800-56A], and HKDF [RFC5869]. CBOR 157 [I-D.ietf-cbor-7049bis] and COSE [RFC8152] are used to implement 158 these standards. The use of COSE provides crypto agility and enables 159 use of future algorithms and headers designed for constrained IoT. 161 This document is organized as follows: Section 2 describes how EDHOC 162 builds on SIGMA-I, Section 3 specifies general properties of EDHOC, 163 including message flow, formatting of the ephemeral public keys, and 164 key derivation, Section 4 specifies EDHOC with asymmetric key 165 authentication, Section 5 specifies EDHOC with symmetric key 166 authentication, Section 6 specifies the EDHOC error message, and 167 Section 7 describes how EDHOC can be transferred in CoAP and used to 168 establish an OSCORE security context. 170 1.1. Rationale for EDHOC 172 Many constrained IoT systems today do not use any security at all, 173 and when they do, they often do not follow best practices. One 174 reason is that many current security protocols are not designed with 175 constrained IoT in mind. Constrained IoT systems often deal with 176 personal information, valuable business data, and actuators 177 interacting with the physical world. Not only do such systems need 178 security and privacy, they often need end-to-end protection with 179 source authentication and perfect forward secrecy. EDHOC and OSCORE 180 [I-D.ietf-core-object-security] enables security following current 181 best practices to devices and systems where current security 182 protocols are impractical. 184 EDHOC is optimized for small message sizes and can therefore be sent 185 over a small number of radio frames. The message size of a key 186 exchange protocol may have a large impact on the performance of an 187 IoT deployment, especially in noisy environments. For example, in a 188 network bootstrapping setting a large number of devices turned on in 189 a short period of time may result in large latencies caused by 190 parallel key exchanges. Requirements on network formation time in 191 constrained environments can be translated into key exchange 192 overhead. In networks technologies with transmission back-off time, 193 each additional frame significantly increases the latency even if no 194 other devices are transmitting. 196 Power consumption for wireless devices is highly dependent on message 197 transmission, listening, and reception. For devices that only send a 198 few bytes occasionally, the battery lifetime may be significantly 199 reduced by a heavy key exchange protocol. Moreover, a key exchange 200 may need to be executed more than once, e.g. due to a device losing 201 power or rebooting for other reasons. 203 EDHOC is adapted to primitives and protocols designed for the 204 Internet of Things: EDHOC is built on CBOR and COSE which enables 205 small message overhead and efficient parsing in constrained devices. 206 EDHOC is not bound to a particular transport layer, but it is 207 recommended to transport the EDHOC message in CoAP payloads. EDHOC 208 is not bound to a particular communication security protocol but 209 works off-the-shelf with OSCORE [I-D.ietf-core-object-security] 210 providing the necessary input parameters with required properties. 211 Maximum code complexity (ROM/Flash) is often a constraint in many 212 devices and by reusing already existing libraries, the additional 213 code footprint for EDHOC + OSCORE can be kept very low. 215 1.2. Terminology and Requirements Language 217 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 218 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 219 "OPTIONAL" in this document are to be interpreted as described in BCP 220 14 [RFC2119] [RFC8174] when, and only when, they appear in all 221 capitals, as shown here. 223 The word "encryption" without qualification always refers to 224 authenticated encryption, in practice implemented with an 225 Authenticated Encryption with Additional Data (AEAD) algorithm, see 226 [RFC5116]. 228 Readers are expected to be familiar with the terms and concepts 229 described in CBOR [I-D.ietf-cbor-7049bis], COSE [RFC8152], and CDDL 230 [I-D.ietf-cbor-cddl]. The Concise Data Definition Language (CDDL) is 231 used to express CBOR data structures [I-D.ietf-cbor-7049bis]. 232 Examples of CBOR and CDDL are provided in Appendix A.1. 234 2. Background 236 SIGMA (SIGn-and-MAc) is a family of theoretical protocols with a 237 large number of variants [SIGMA]. Like IKEv2 and (D)TLS 1.3 238 [RFC8446], EDHOC is built on a variant of the SIGMA protocol which 239 provide identity protection of the initiator (SIGMA-I), and like 240 (D)TLS 1.3, EDHOC implements the SIGMA-I variant as Sign-then-MAC. 242 The SIGMA-I protocol using an authenticated encryption algorithm is 243 shown in Figure 1. 245 Party U Party V 246 | X_U | 247 +-------------------------------------------------------->| 248 | | 249 | X_V, AEAD( K_2; ID_CRED_V, Sig(V; CRED_V, X_U, X_V) ) | 250 |<--------------------------------------------------------+ 251 | | 252 | AEAD( K_3; ID_CRED_U, Sig(U; CRED_U, X_V, X_U) ) | 253 +-------------------------------------------------------->| 254 | | 256 Figure 1: Authenticated encryption variant of the SIGMA-I protocol. 258 The parties exchanging messages are called "U" and "V". They 259 exchange identities and ephemeral public keys, compute the shared 260 secret, and derive symmetric application keys. 262 o X_U and X_V are the ECDH ephemeral public keys of U and V, 263 respectively. 265 o CRED_U and CRED_V are the credentials containing the public 266 authentication keys of U and V, respectively. 268 o ID_CRED_U and ID_CRED_V are data enabling the recipient party to 269 retrieve the credential of U and V, respectively 271 o Sig(U; . ) and S(V; . ) denote signatures made with the private 272 authentication key of U and V, respectively. 274 o AEAD(K; . ) denotes authenticated encryption with additional data 275 using the key K derived from the shared secret. The authenticated 276 encryption MUST NOT be replaced by plain encryption, see 277 Section 9. 279 In order to create a "full-fledged" protocol some additional protocol 280 elements are needed. EDHOC adds: 282 o Explicit connection identifiers C_U, C_V chosen by U and V, 283 respectively, enabling the recipient to find the protocol state. 285 o Transcript hashes TH_2, TH_3, TH_4 used for key derivation and as 286 additional authenticated data. 288 o Computationally independent keys derived from the ECDH shared 289 secret and used for encryption of different messages. 291 o Verification of a common preferred cipher suite (AEAD algorithm, 292 ECDH algorithm, ECDH curve, signature algorithm): 294 * U lists supported cipher suites in order of preference 296 * V verifies that the selected cipher suite is the first 297 supported cipher suite 299 o Method types and error handling. 301 o Transport of opaque application defined data. 303 EDHOC is designed to encrypt and integrity protect as much 304 information as possible, and all symmetric keys are derived using as 305 much previous information as possible. EDHOC is furthermore designed 306 to be as compact and lightweight as possible, in terms of message 307 sizes, processing, and the ability to reuse already existing CBOR, 308 COSE, and CoAP libraries. 310 To simplify for implementors, the use of CBOR and COSE in EDHOC is 311 summarized in Appendix A and example messages in CBOR diagnostic 312 notation are given in Appendix B. 314 3. EDHOC Overview 316 EDHOC consists of three flights (message_1, message_2, message_3) 317 that maps directly to the three messages in SIGMA-I, plus an EDHOC 318 error message. All EDHOC messages consist of a sequence of CBOR 319 encoded data items, where the first data item of message_1 is an int 320 (TYPE) specifying the method (asymmetric, symmetric, error) and the 321 correlation properties of the transport used. The messages may be 322 viewed as a CBOR encoding of an indefinite-length array without the 323 first and last byte, see Appendix A.1. 325 While EDHOC uses the COSE_Key, COSE_Sign1, and COSE_Encrypt0 326 structures, only a subset of the parameters is included in the EDHOC 327 messages. After creating EDHOC message_3, Party U can derive 328 symmetric application keys, and application protected data can 329 therefore be sent in parallel with EDHOC message_3. The application 330 may protect data using the algorithms (AEAD, HKDF, etc.) in the 331 selected cipher suite and the connection identifiers (C_U, C_V). 332 EDHOC may be used with the media type application/edhoc defined in 333 Section 8. 335 Party U Party V 336 | | 337 | ------------------ EDHOC message_1 -----------------> | 338 | | 339 | <----------------- EDHOC message_2 ------------------ | 340 | | 341 | ------------------ EDHOC message_3 -----------------> | 342 | | 343 | <----------- Application Protected Data ------------> | 344 | | 346 Figure 2: EDHOC message flow 348 The EDHOC message exchange may be authenticated using pre-shared keys 349 (PSK), raw public keys (RPK), or public key certificates. EDHOC 350 assumes the existence of mechanisms (certification authority, manual 351 distribution, etc.) for binding identities with authentication keys 352 (public or pre-shared). When a public key infrastructure is used, 353 the identity is included in the certificate and bound to the 354 authentication key by trust in the certification authority. When the 355 credential is manually distributed (PSK, RPK, self-signed 356 certificate), the identity and authentication key is distributed out- 357 of-band and bound together by trust in the distribution method. 358 EDHOC with symmetric key authentication is very similar to EDHOC with 359 asymmetric key authentication, the difference being that information 360 is only MACed, not signed, and that session keys are derived from the 361 ECDH shared secret and the PSK. 363 EDHOC allows opaque application data (UAD and PAD) to be sent in the 364 EDHOC messages. Unprotected Application Data (UAD_1, UAD_2) may be 365 sent in message_1 and message_2 and can be e.g. be used to transfer 366 access tokens that are protected outside of EDHOC. Protected 367 application data (PAD_3) may be used to transfer any application data 368 in message_3. 370 Cryptographically, EDHOC does not put requirements on the lower 371 layers. EDHOC is not bound to a particular transport layer, and can 372 be used in environments without IP. It is recommended to transport 373 the EDHOC message in CoAP payloads, see Section 7. An implementation 374 may support only Party U or only Party V. 376 3.1. Cipher Suites 378 EDHOC cipher suites consist of a set of COSE algorithms: an AEAD 379 algorithm, an ECDH algorithm (including HKDF algorithm), an ECDH 380 curve, a signature algorithm, and signature algorithm parameters. 381 The signature algorithm is not used when EDHOC is authenticated with 382 symmetric keys. Each cipher suite is either identified with a pre- 383 defined int label or with an array of labels and values from the COSE 384 Algorithms and Elliptic Curves registries. 386 suite = int / [ 4*4 algs: int / tstr, ? para: any ] 388 This document specifies two pre-defined cipher suites. 390 0. [ 12, -27, 4, -8, 6 ] 391 (AES-CCM-64-64-128, ECDH-SS + HKDF-256, X25519, EdDSA, Ed25519) 393 1. [ 12, -27, 1, -7 ] 394 (AES-CCM-64-64-128, ECDH-SS + HKDF-256, P-256, ES256) 396 Two additional numbers are registered for application defined cipher 397 suites. Application defined cipher suites MUST only use algorithms 398 specified for COSE, are not interoperable with other deployments and 399 can therefore only be used in local networks. 401 -24. First application defined cipher suite. 402 -23. Second application defined cipher suite. 404 3.2. Ephemeral Public Keys 406 The ECDH ephemeral public keys are formatted as a COSE_Key of type 407 EC2 or OKP according to Sections 13.1 and 13.2 of [RFC8152], but only 408 a subset of the parameters is included in the EDHOC messages. For 409 Elliptic Curve Keys of type EC2, compact representation as per 410 [RFC6090] MAY be used also in the COSE_Key. If the COSE 411 implementation requires an y-coordinate, any of the possible values 412 of the y-coordinate can be used, see Appendix C of [RFC6090]. COSE 413 [RFC8152] always use compact output for Elliptic Curve Keys of type 414 EC2. 416 3.3. Key Derivation 418 Key and IV derivation SHALL be performed as specified in Section 11 419 of [RFC8152] with the following input: 421 o The KDF SHALL be the HKDF [RFC5869] in the selected cipher suite. 423 o The secret (Section 11.1 of [RFC8152]) SHALL be the ECDH shared 424 secret as defined in Section 12.4.1 of [RFC8152]. 426 o The salt (Section 11.1 of [RFC8152]) SHALL be the PSK when EDHOC 427 is authenticated with symmetric keys, and the empty byte string 428 when EDHOC is authenticated with asymmetric keys. The secret and 429 the salt are both inputs to the HKDF extract stage and the PSK is 430 used as 'salt' to simplify implementation. Note that [RFC5869] 431 specifies that if the salt is not provided, it is set to a string 432 of zeros (see Section 2.2 of [RFC5869]). For implementation 433 purposes, not providing the salt is the same as setting the salt 434 to the empty byte string. 436 o The fields in the context information COSE_KDF_Context 437 (Section 11.2 of [RFC8152]) SHALL have the following values: 439 * AlgorithmID is an int or tstr, see below 441 * PartyUInfo = PartyVInfo = ( null, null, null ) 443 * keyDataLength is a uint, see below 445 * protected SHALL be a zero length bstr 447 * other is a bstr and SHALL be one of the transcript hashes TH_2, 448 TH_3, or TH_4 as defined in Sections 4.3.1, 4.4.1, and 3.3.1. 450 * SuppPrivInfo is omitted 452 We define EDHOC-Key-Derivation to be the function which produces the 453 output as described in [RFC5869] and [RFC8152] depending on the 454 variable input AlgorithmID, keyDataLength, and other: 456 output = EDHOC-Key-Derivation(AlgorithmID, keyDataLength, other) 458 For message_2 and message_3, the keys K_2 and K_3 SHALL be derived 459 using other set to the transcript hashes TH_2 and TH_3 respectively. 460 The key SHALL be derived using AlgorithmID set to the integer value 461 of the AEAD in the selected cipher suite, and keyDataLength equal to 462 the key length of the AEAD. 464 If the AEAD algorithm uses an IV, then IV_2 and IV_3 for message_2 465 and message_3 SHALL be derived using other set to the transcript 466 hashes TH_2 and TH_3 respectively. The IV SHALL be derived using 467 AlgorithmID = "IV-GENERATION" as specified in Section 12.1.2. of 468 [RFC8152], and keyDataLength equal to the IV length of the AEAD. 470 3.3.1. EDHOC-Exporter Interface 472 Application keys and other application specific data can be derived 473 using the EDHOC-Exporter interface defined as: 475 EDHOC-Exporter(label, length) = 476 EDHOC-Key-Derivation(label, 8 * length, TH_4) 478 The output of the EDHOC-Exporter function SHALL be derived using 479 other = TR_4, AlgorithmID = label, and keyDataLength = 8 * length, 480 where label is a tstr defined by the application and length is a uint 481 defined by the application. The label SHALL be different for each 482 different exporter value. The transcript hash TR_4, in non-CDDL 483 notation, is: 485 TH_4 = H( bstr .cborseq [ TH_3, CIPHERTEXT_3 ] ) 487 where H() is the hash function in the HKDF, which takes a CBOR byte 488 string (bstr) as input and produces a CBOR byte string as output. 489 The use of '.cborseq' is exemplified in Appendix A.1. Example use of 490 the EDHOC-Exporter is given in Sections 3.3.2 and 7.1.1. 492 3.3.2. EDHOC PSK Chaining 494 An application using EDHOC may want to derive new PSKs to use for 495 authentication in future EDHOC exchanges. In this case, the new PSK 496 and the ID_PSK 'kid' parameter SHOULD be derived as follows where 497 length is the key length (in bytes) of the AEAD Algorithm. 499 PSK = EDHOC-Exporter("EDHOC Chaining PSK", length) 500 ID_PSK = EDHOC-Exporter("EDHOC Chaining ID_PSK", 4) 502 4. EDHOC Authenticated with Asymmetric Keys 504 4.1. Overview 506 EDHOC supports authentication with raw public keys (RPK) and public 507 key certificates with the requirements that: 509 o Only Party V SHALL have access to the private authentication key 510 of Party V, 512 o Only Party U SHALL have access to the private authentication key 513 of Party U, 515 o Party U is able to retrieve Party V's public authentication key 516 using ID_CRED_V, 518 o Party V is able to retrieve Party U's public authentication key 519 using ID_CRED_U, 521 where the identifiers ID_CRED_U and ID_CRED_V are COSE header maps 522 containing COSE header parameter that can identify a public 523 authentication key, see Appendix A.2. In the following we give some 524 examples of possible COSE header parameters. 526 Raw public keys are most optimally stored as COSE_Key objects and 527 identified with a 'kid' parameter (see [RFC8152]): 529 o ID_CRED_x = { 4 : bstr }, for x = U or V. 531 Public key certificates can be identified in different ways. Several 532 header parameters for identifying X.509 certificates are defined in 533 [I-D.schaad-cose-x509] (the exact labels are TBD): 535 o by a hash value with the 'x5t' parameter; 537 * ID_CRED_x = { TBD1 : COSE_CertHash }, for x = U or V, 539 o by a URL with the 'x5u' parameter; 541 * ID_CRED_x = { TBD2 : uri }, for x = U or V, 543 o or by a bag of certificates with the 'x5bag' parameter; 545 * ID_CRED_x = { TBD3 : COSE_X509 }, for x = U or V. 547 o by a certificate chain with the 'x5chain' parameter; 549 * ID_CRED_x = { TBD4 : COSE_X509 }, for x = U or V, 551 In the latter two examples, ID_CRED_U and ID_CRED_V contain the 552 actual credential used for authentication. The purpose of ID_CRED_U 553 and ID_CRED_V is to facilitate retrieval of a public authentication 554 key and when they do not contain the actual credential, they may be 555 very short. It is RECOMMENDED that they uniquely identify the public 556 authentication key as the recipient may otherwise have to try several 557 keys. ID_CRED_U and ID_CRED_V are transported in the ciphertext, see 558 Section 4.3.2 and Section 4.4.2. 560 The actual credentials CRED_U and CRED_V (e.g. a COSE_Key or a single 561 X.509 certificate) are signed by party U and V, respectively to 562 prevent duplicate-signature key selection (DSKS) attacks, see 563 Section 4.4.1 and Section 4.3.1. Party U and Party V MAY use 564 different types of credentials, e.g. one uses RPK and the other uses 565 certificate. 567 The connection identifiers C_U and C_V do not have any cryptographic 568 purpose in EDHOC. They contain information facilitating retrieval of 569 the protocol state and may therefore be very short. The connection 570 identifier MAY be used with an application protocol (e.g. OSCORE) 571 for which EDHOC establishes keys, in which case the connection 572 identifiers SHALL adhere to the requirements for that protocol. Each 573 party choses a connection identifier it desires the other party to 574 use in outgoing messages. 576 The first data item of message_1 is an int TYPE = 4 * method + corr 577 specifying the method and the correlation properties of the transport 578 used. corr = 0 is used when there is no external correlation 579 mechanism. corr = 1 is used when there is an external correlation 580 mechanism (e.g. the Token in CoAP) that enables Party U to correlate 581 message_1 and message_2. corr = 2 is used when there is an external 582 correlation mechanism that enables Party V to correlate message_2 and 583 message_3. corr = 3 is used when there is an external correlation 584 mechanism that enables the parties to correlate all the messages. 585 The use of the correlation parameter is exemplified in Section 7.1. 587 EDHOC with asymmetric key authentication is illustrated in Figure 3. 589 Party U Party V 590 | TYPE, SUITES_U, X_U, C_U, UAD_1 | 591 +------------------------------------------------------------------>| 592 | message_1 | 593 | | 594 | C_U, X_V, C_V, AEAD(K_2; ID_CRED_V, Sig(V; CRED_V, TH_2), UAD_2) | 595 |<------------------------------------------------------------------+ 596 | message_2 | 597 | | 598 | C_V, AEAD(K_3; ID_CRED_U, Sig(U; CRED_U, TH_3), PAD_3) | 599 +------------------------------------------------------------------>| 600 | message_3 | 602 Figure 3: Overview of EDHOC with asymmetric key authentication. 604 4.2. EDHOC Message 1 606 4.2.1. Formatting of Message 1 608 message_1 SHALL be a sequence of CBOR data items (see Appendix A.1) 609 as defined below 611 message_1 = ( 612 TYPE : int, 613 SUITES_U : suite / [ index: uint, 2* suite ], 614 X_U : bstr, 615 C_U : bstr, 616 ? UAD_1 : bstr, 617 ) 619 where: 621 o TYPE = 4 * method + corr, where the method = 0 and the connection 622 parameter corr is chosen based on the transport and determines 623 which connection identifiers that are omitted (see Section 4.1). 625 o SUITES_U - cipher suites which Party U supports, in order of 626 decreasing preference. If a single cipher suite is conveyed, a 627 single suite is used, if multiple cipher suites are conveyed, an 628 array of suites and an index is used. The zero-based index (i.e. 629 0 for the first, 1 for the second, etc.) identifies a single 630 selected cipher suite from the array. 632 o X_U - the x-coordinate of the ephemeral public key of Party U 634 o C_U - variable length connection identifier 636 o UAD_1 - bstr containing unprotected opaque application data 638 4.2.2. Party U Processing of Message 1 640 Party U SHALL compose message_1 as follows: 642 o The supported cipher suites and the order of preference MUST NOT 643 be changed based on previous error messages. However, the list 644 SUITES_U sent to Party V MAY be truncated such that cipher suites 645 which are the least preferred are omitted. The amount of 646 truncation MAY be changed between sessions, e.g. based on previous 647 error messages (see next bullet), but all cipher suites which are 648 more preferred than the least preferred cipher suite in the list 649 MUST be included in the list. 651 o Determine the cipher suite to use with Party V in message_1. If 652 Party U previously received from Party V an error message to 653 message_1 with diagnostic payload identifying a cipher suite that 654 U supports, then U SHALL use that cipher suite. Otherwise the 655 first cipher suite in SUITES_U MUST be used. 657 o Generate an ephemeral ECDH key pair as specified in Section 5 of 658 [SP-800-56A] using the curve in the selected cipher suite. Let 659 X_U be the x-coordinate of the ephemeral public key. 661 o Choose a connection identifier C_U and store it for the length of 662 the protocol. 664 o Format message_1 as the sequence of CBOR data items specified in 665 Section 4.2.1 and encode it to a byte string (see Appendix A.1). 667 4.2.3. Party V Processing of Message 1 669 Party V SHALL process message_1 as follows: 671 o Decode message_1 (see Appendix A.1). 673 o Verify that the selected cipher suite is supported and that no 674 prior cipher suites in SUITES_U are supported. 676 o Validate that there is a solution to the curve definition for the 677 given x-coordinate X_U. 679 o Pass UAD_1 to the application. 681 If any verification step fails, Party V MUST send an EDHOC error 682 message back, formatted as defined in Section 6, and the protocol 683 MUST be discontinued. If V does not support the selected cipher 684 suite, then SUITES_V MUST include one or more supported cipher 685 suites. If V does not support the selected cipher suite, but 686 supports another cipher suite in SUITES_U, then SUITES_V MUST include 687 the first supported cipher suite in SUITES_U. 689 4.3. EDHOC Message 2 691 4.3.1. Formatting of Message 2 693 message_2 SHALL be a sequence of CBOR data items (see Appendix A.1) 694 as defined below 696 message_2 = ( 697 data_2, 698 CIPHERTEXT_2 : bstr, 699 ) 701 data_2 = ( 702 ? C_U : bstr, 703 X_V : bstr, 704 C_V : bstr, 705 ) 707 TH_2 : bstr 709 where the transcript hash TH_2, in non-CDDL notation, is: 711 TH_2 = H( bstr .cborseq [ message_1, data_2 ] ) 713 where: 715 o X_V - the x-coordinate of the ephemeral public key of Party V 717 o C_V - variable length connection identifier 719 o H() - the hash function in the HKDF, which takes a CBOR byte 720 string (bstr) as input and produces a CBOR byte string as output. 721 The use of '.cborseq' is exemplified in Appendix A.1. 723 4.3.2. Party V Processing of Message 2 725 Party V SHALL compose message_2 as follows: 727 o If TYPE mod 4 equals 1 or 3, C_U is omitted, otherwise C_U is not 728 omitted. 730 o Generate an ephemeral ECDH key pair as specified in Section 5 of 731 [SP-800-56A] using the curve in the selected cipher suite. Let 732 X_V be the x-coordinate of the ephemeral public key. 734 o Choose a connection identifier C_V and store it for the length of 735 the protocol. 737 o Compute COSE_Sign1 as defined in Section 4.4 of [RFC8152], using 738 the signature algorithm in the selected cipher suite, the private 739 authentication key of Party V, and the following parameters 740 (further clarifications in Appendix A.2.2). The unprotected 741 header (not included in the EDHOC message) MAY contain parameters 742 (e.g. 'alg'). 744 * protected = bstr .cbor ID_CRED_V 746 * payload = CRED_V 748 * external_aad = TH_2 750 * ID_CRED_V - identifier to facilitate retrieval of a public 751 authentication key of Party V, see Section 4.1 753 * CRED_V - bstr credential containing the public authentication 754 key of Party V, see Section 4.1 756 Note that only 'protected' and 'signature' of the COSE_Sign1 757 object are used in message_2, see next bullet. 759 o Compute COSE_Encrypt0 as defined in Section 5.3 of [RFC8152], with 760 the AEAD algorithm in the selected cipher suite, K_2, IV_2, and 761 the following parameters (further clarifications in 762 Appendix A.2.2). The protected header SHALL be empty. The 763 unprotected header (not included in the EDHOC message) MAY contain 764 parameters (e.g. 'alg'). 766 * plaintext = bstr .cborseq [ ID_CRED_V, signature, ? UAD_2 ] 768 * external_aad = TH_2 770 * UAD_2 = bstr containing opaque unprotected application data 772 Note that 'protected' and 'signature' in the plaintext are taken 773 from the COSE_Sign1 object, and that only 'ciphertext' of the 774 COSE_Encrypt0 object are used in message_2, see next bullet. If 775 ID_CRED_V contains a single 'kid' parameter, i.e., ID_CRED_V = { 4 776 : bstr }, only the bstr is conveyed in the plaintext, in CDDL 777 notation 779 plaintext = bstr .cborseq [ bstr / header_map, bstr, ? bstr ] 781 o Format message_2 as the sequence of CBOR data items specified in 782 Section 4.3.1 and encode it to a byte string (see Appendix A.1). 783 CIPHERTEXT_2 is the COSE_Encrypt0 ciphertext. 785 4.3.3. Party U Processing of Message 2 787 Party U SHALL process message_2 as follows: 789 o Decode message_2 (see Appendix A.1). 791 o Retrieve the protocol state using the connection identifier C_U 792 and/or other external information such as the CoAP Token and the 793 5-tuple. 795 o Validate that there is a solution to the curve definition for the 796 given x-coordinate X_V. 798 o Decrypt and verify COSE_Encrypt0 as defined in Section 5.3 of 799 [RFC8152], with the AEAD algorithm in the selected cipher suite, 800 K_2, and IV_2. 802 o Verify COSE_Sign1 as defined in Section 4.4 of [RFC8152], using 803 the signature algorithm in the selected cipher suite and the 804 public authentication key of Party V. 806 If any verification step fails, Party U MUST send an EDHOC error 807 message back, formatted as defined in Section 6, and the protocol 808 MUST be discontinued. 810 4.4. EDHOC Message 3 812 4.4.1. Formatting of Message 3 814 message_3 SHALL be a sequence of CBOR data items (see Appendix A.1) 815 as defined below 817 message_3 = ( 818 data_3, 819 CIPHERTEXT_3 : bstr, 820 ) 822 data_3 = ( 823 ? C_V : bstr, 824 ) 826 TH_3 : bstr 828 where the transcript hash TH_3, in non-CDDL notation, is: 830 TH_3 = H( bstr .cborseq [ TH_2, CIPHERTEXT_2, data_3 ] ) 832 4.4.2. Party U Processing of Message 3 834 Party U SHALL compose message_3 as follows: 836 o If TYPE mod 4 equals 2 or 3, C_V is omitted, otherwise C_V is not 837 omitted. 839 o Compute COSE_Sign1 as defined in Section 4.4 of [RFC8152], using 840 the signature algorithm in the selected cipher suite, the private 841 authentication key of Party U, and the following parameters. The 842 unprotected header (not included in the EDHOC message) MAY contain 843 parameters (e.g. 'alg'). 845 * protected = bstr .cbor ID_CRED_U 847 * payload = CRED_U 849 * external_aad = TH_3 851 * ID_CRED_U - identifier to facilitate retrieval of a public 852 authentication key of Party U, see Section 4.1 854 * CRED_U - bstr credential containing the public authentication 855 key of Party U, see Section 4.1 857 Note that only 'protected' and 'signature' of the COSE_Sign1 858 object are used in message_3, see next bullet. 860 o Compute COSE_Encrypt0 as defined in Section 5.3 of [RFC8152], with 861 the AEAD algorithm in the selected cipher suite, K_3, and IV_3 and 862 the following parameters. The protected header SHALL be empty. 863 The unprotected header (not included in the EDHOC message) MAY 864 contain parameters (e.g. 'alg'). 866 * plaintext = bstr .cborseq [ ID_CRED_U, signature, ? PAD_3 ] 868 * external_aad = TH_3 870 * PAD_3 = bstr containing opaque protected application data 872 Note that 'protected' and 'signature' in the plaintext are taken 873 from the COSE_Sign1 object, and that only 'ciphertext' of the 874 COSE_Encrypt0 object are used in message_3, see next bullet. If 875 ID_CRED_U contains a single 'kid' parameter, i.e., ID_CRED_U = { 4 876 : bstr }, only the bstr is conveyed in the plaintext. 878 o Format message_3 as the sequence of CBOR data items specified in 879 Section 4.4.1 and encode it to a byte string (see Appendix A.1). 880 CIPHERTEXT_3 is the COSE_Encrypt0 ciphertext. 882 o Pass the connection identifiers (C_U, C_V) and the selected cipher 883 suite to the application. The application can now derive 884 application keys using the EDHOC-Exporter interface. 886 4.4.3. Party V Processing of Message 3 888 Party V SHALL process message_3 as follows: 890 o Decode message_3 (see Appendix A.1). 892 o Retrieve the protocol state using the connection identifier C_V 893 and/or other external information such as the CoAP Token and the 894 5-tuple. 896 o Decrypt and verify COSE_Encrypt0 as defined in Section 5.3 of 897 [RFC8152], with the AEAD algorithm in the selected cipher suite, 898 K_3, and IV_3. 900 o Verify COSE_Sign1 as defined in Section 4.4 of [RFC8152], using 901 the signature algorithm in the selected cipher suite and the 902 public authentication key of Party U. 904 If any verification step fails, Party V MUST send an EDHOC error 905 message back, formatted as defined in Section 6, and the protocol 906 MUST be discontinued. 908 o Pass PAD_3, the connection identifiers (C_U, C_V), and the 909 selected cipher suite to the application. The application can now 910 derive application keys using the EDHOC-Exporter interface. 912 5. EDHOC Authenticated with Symmetric Keys 914 5.1. Overview 916 EDHOC supports authentication with pre-shared keys. Party U and V 917 are assumed to have a pre-shared key (PSK) with a good amount of 918 randomness and the requirement that: 920 o Only Party U and Party V SHALL have access to the PSK, 922 o Party V is able to retrieve the PSK using ID_PSK. 924 where the identifier ID_PSK is a COSE header maps containing COSE 925 header parameter that can identify a pre-shared key. Pre-shared keys 926 are typically stored as COSE_Key objects and identified with a 'kid' 927 parameter (see [RFC8152]): 929 o ID_PSK = { 4 : bstr } 931 The purpose of ID_PSK is to facilitate retrieval of the PSK and in 932 the case a 'kid' parameter is used it may be very short. It is 933 RECOMMENDED that it uniquely identify the PSK as the recipient may 934 otherwise have to try several keys. 936 EDHOC with symmetric key authentication is illustrated in Figure 4. 938 Party U Party V 939 | TYPE, SUITES_U, X_U, C_U, ID_PSK, UAD_1 | 940 +------------------------------------------------------------------>| 941 | message_1 | 942 | | 943 | C_U, X_V, C_V, AEAD(K_2; TH_2, UAD_2) | 944 |<------------------------------------------------------------------+ 945 | message_2 | 946 | | 947 | C_V, AEAD(K_3; TH_3, PAD_3) | 948 +------------------------------------------------------------------>| 949 | message_3 | 951 Figure 4: Overview of EDHOC with symmetric key authentication. 953 EDHOC with symmetric key authentication is very similar to EDHOC with 954 asymmetric key authentication. In the following subsections the 955 differences compared to EDHOC with asymmetric key authentication are 956 described. 958 5.2. EDHOC Message 1 960 5.2.1. Formatting of Message 1 962 message_1 SHALL be a sequence of CBOR data items (see Appendix A.1) 963 as defined below 965 message_1 = ( 966 TYPE : int, 967 SUITES_U : suite / [ index: uint, 2* suite ], 968 X_U : bstr, 969 C_U : bstr, 970 ID_PSK : bstr / header_map, 971 ? UAD_1 : bstr, 972 ) 974 where: 976 o TYPE = 4 * method + corr, where the method = 1 and the connection 977 parameter corr is chosen based on the transport and determines 978 which connection identifiers that are omitted (see Section 4.1). 980 o ID_PSK - identifier to facilitate retrieval of the pre-shared key. 981 If ID_PSK contains a single 'kid' parameter, i.e., ID_PSK = { 4 : 982 bstr }, only the bstr used. 984 5.3. EDHOC Message 2 986 5.3.1. Processing of Message 2 988 o COSE_Sign1 is not used. 990 o COSE_Encrypt0 is computed as defined in Section 5.3 of [RFC8152], 991 with the AEAD algorithm in the selected cipher suite, K_2, IV_2, 992 and the following parameters. The protected header SHALL be 993 empty. The unprotected header MAY contain parameters (e.g. 994 'alg'). 996 * external_aad = TH_2 998 * plaintext = h'' / UAD_2 1000 * UAD_2 = bstr containing opaque unprotected application data 1002 5.4. EDHOC Message 3 1004 5.4.1. Processing of Message 3 1006 o COSE_Sign1 is not used. 1008 o COSE_Encrypt0 is computed as defined in Section 5.3 of [RFC8152], 1009 with the AEAD algorithm in the selected cipher suite, K_3, IV_3, 1010 and the following parameters. The protected header SHALL be 1011 empty. The unprotected header MAY contain parameters (e.g. 1012 'alg'). 1014 * external_aad = TH_3 1016 * plaintext = h'' / PAD_3 1018 * PAD_3 = bstr containing opaque protected application data 1020 6. Error Handling 1022 6.1. EDHOC Error Message 1024 This section defines a message format for the EDHOC error message, 1025 used during the protocol. An EDHOC error message can be send by both 1026 parties as a response to any non-error EDHOC message. After sending 1027 an error message, the protocol MUST be discontinued. Errors at the 1028 EDHOC layer are sent as normal successful messages in the lower 1029 layers (e.g. CoAP POST and 2.04 Changed). An advantage of using 1030 such a construction is to avoid issues created by usage of cross 1031 protocol proxies (e.g. UDP to TCP). 1033 error SHALL be a sequence of CBOR data items (see Appendix A.1) as 1034 defined below 1036 error = ( 1037 TYPE : int, 1038 ERR_MSG : tstr, 1039 ? SUITES_V : suite / [ 2* suite ], 1040 ) 1042 where: 1044 o TYPE = -1 1046 o ERR_MSG - text string containing the diagnostic payload, defined 1047 in the same way as in Section 5.5.2 of [RFC7252] 1049 o SUITES_V - cipher suites from SUITES_U or the EDHOC cipher suites 1050 registry that V supports. Note that SUITEs_V only contains the 1051 values from the EDHOC cipher suites registry and no index. 1053 6.1.1. Example Use of EDHOC Error Message with SUITES_V 1055 Assuming that Party U supports the five cipher suites {5, 6, 7, 8, 9} 1056 in decreasing order of preference, Figures 5 and 6 show examples of 1057 how Party U can truncate SUITES_U and how SUITES_V is used by Party V 1058 to give Party U information about the cipher suites that Party V 1059 supports. In Figure 5, Party V supports cipher suite 6 but not 1060 cipher suite 5. 1062 Party U Party V 1063 | TYPE, SUITES_U {0, 5, 6, 7}, X_U, C_U, UAD_1 | 1064 +------------------------------------------------------------------>| 1065 | message_1 | 1066 | | 1067 | TYPE, ERR_MSG, SUITES_V {6} | 1068 |<------------------------------------------------------------------+ 1069 | error | 1070 | | 1071 | TYPE, SUITES_U {1, 5, 6}, X_U, C_U, UAD_1 | 1072 +------------------------------------------------------------------>| 1073 | message_1 | 1075 Figure 5: Example use of error message with SUITES_V. 1077 In Figure 6, Party V supports cipher suite 7 but not cipher suites 5 1078 and 6. 1080 Party U Party V 1081 | TYPE, SUITES_U {0, 5, 6}, X_U, C_U, UAD_1 | 1082 +------------------------------------------------------------------>| 1083 | message_1 | 1084 | | 1085 | TYPE, ERR_MSG, SUITES_V {7, 9} | 1086 |<------------------------------------------------------------------+ 1087 | error | 1088 | | 1089 | TYPE, SUITES_U {2, 5, 6, 7}, X_U, C_U, UAD_1 | 1090 +------------------------------------------------------------------>| 1091 | message_1 | 1093 Figure 6: Example use of error message with SUITES_V. 1095 As Party U's list of supported cipher suites and order of preference 1096 is fixed, and Party V only accepts message_1 if the selected cipher 1097 suite is the first cipher suite in SUITES_U that Party V supports, 1098 the parties can verify that the selected cipher suite is the most 1099 preferred (by Party U) cipher suite supported by both parties. If 1100 the selected cipher suite is not the first cipher suite in SUITES_U 1101 that Party V supports, Party V will discontinue the protocol. 1103 7. Transferring EDHOC and Deriving Application Keys 1105 7.1. Transferring EDHOC in CoAP 1107 It is recommended is to transport EDHOC as an exchange of CoAP 1108 [RFC7252] messages. CoAP is a reliable transport that can preserve 1109 packet ordering and handle message duplication. CoAP can also 1110 perform fragmentation and protect against denial of service attacks. 1111 It is recommended to carry the EDHOC flights in Confirmable messages, 1112 especially if fragmentation is used. 1114 By default, the CoAP client is Party U and the CoAP server is Party 1115 V, but the roles SHOULD be chosen to protect the most sensitive 1116 identity, see Section 9. By default, EDHOC is transferred in POST 1117 requests and 2.04 (Changed) responses to the Uri-Path: "/.well-known/ 1118 edhoc", but an application may define its own path that can be 1119 discovered e.g. using resource directory 1120 [I-D.ietf-core-resource-directory]. 1122 By default, the message flow is as follows: EDHOC message_1 is sent 1123 in the payload of a POST request from the client to the server's 1124 resource for EDHOC. EDHOC message_2 or the EDHOC error message is 1125 sent from the server to the client in the payload of a 2.04 (Changed) 1126 response. EDHOC message_3 or the EDHOC error message is sent from 1127 the client to the server's resource in the payload of a POST request. 1128 If needed, an EDHOC error message is sent from the server to the 1129 client in the payload of a 2.04 (Changed) response. 1131 An example of a successful EDHOC exchange using CoAP is shown in 1132 Figure 7. In this case the CoAP Token enables Party U to correlate 1133 message_1 and message_2 so the correlation parameter corr = 1. 1135 Client Server 1136 | | 1137 +--------->| Header: POST (Code=0.02) 1138 | POST | Uri-Path: "/.well-known/edhoc" 1139 | | Content-Format: application/edhoc 1140 | | Payload: EDHOC message_1 1141 | | 1142 |<---------+ Header: 2.04 Changed 1143 | 2.04 | Content-Format: application/edhoc 1144 | | Payload: EDHOC message_2 1145 | | 1146 +--------->| Header: POST (Code=0.02) 1147 | POST | Uri-Path: "/.well-known/edhoc" 1148 | | Content-Format: application/edhoc 1149 | | Payload: EDHOC message_3 1150 | | 1151 |<---------+ Header: 2.04 Changed 1152 | 2.04 | 1153 | | 1155 Figure 7: Transferring EDHOC in CoAP 1157 The exchange in Figure 7 protects the client identity against active 1158 attackers and the server identity against passive attackers. An 1159 alternative exchange that protects the server identity against active 1160 attackers and the client identity against passive attackers is shown 1161 in Figure 8. In this case the CoAP Token enables Party V to 1162 correlate message_2 and message_3 so the correlation parameter corr = 1163 2. 1165 Client Server 1166 | | 1167 +--------->| Header: POST (Code=0.02) 1168 | POST | Uri-Path: "/.well-known/edhoc" 1169 | | 1170 |<---------+ Header: 2.04 Changed 1171 | 2.04 | Content-Format: application/edhoc 1172 | | Payload: EDHOC message_1 1173 | | 1174 +--------->| Header: POST (Code=0.02) 1175 | POST | Uri-Path: "/.well-known/edhoc" 1176 | | Content-Format: application/edhoc 1177 | | Payload: EDHOC message_2 1178 | | 1179 |<---------+ Header: 2.04 Changed 1180 | 2.04 | Content-Format: application/edhoc 1181 | | Payload: EDHOC message_3 1182 | | 1184 Figure 8: Transferring EDHOC in CoAP 1186 To protect against denial-of-service attacks, the CoAP server MAY 1187 respond to the first POST request with a 4.01 (Unauthorized) 1188 containing an Echo option [I-D.ietf-core-echo-request-tag]. This 1189 forces the initiator to demonstrate its reachability at its apparent 1190 network address. If message fragmentation is needed, the EDHOC 1191 messages may be fragmented using the CoAP Block-Wise Transfer 1192 mechanism [RFC7959]. 1194 7.1.1. Deriving an OSCORE Context from EDHOC 1196 When EDHOC is used to derive parameters for OSCORE 1197 [I-D.ietf-core-object-security], the parties must make sure that the 1198 EDHOC connection identifiers are unique, i.e. C_V MUST NOT be equal 1199 to C_U. The CoAP client and server MUST be able to retrieve the 1200 OCORE protocol state using its chosen connection identifier and 1201 optionally other information such as the 5-tuple. In case that the 1202 CoAP client is party U and the CoAP server is party V: 1204 o The client's OSCORE Sender ID is C_V and the server's OSCORE 1205 Sender ID is C_U, as defined in this document 1207 o The AEAD Algorithm and the HMAC-based Key Derivation Function 1208 (HKDF) are the AEAD and HKDF algorithms in the selected cipher 1209 suite. 1211 o The Master Secret and Master Salt are derived as follows where 1212 length is the key length (in bytes) of the AEAD Algorithm. 1214 Master Secret = EDHOC-Exporter("OSCORE Master Secret", length) 1215 Master Salt = EDHOC-Exporter("OSCORE Master Salt", 8) 1217 7.2. Transferring EDHOC over Other Protocols 1219 EDHOC may be transported over a different transport than CoAP. In 1220 this case the lower layers need to handle message loss, reordering, 1221 message duplication, fragmentation, and denial of service protection. 1223 8. IANA Considerations 1225 8.1. EDHOC Cipher Suites Registry 1227 IANA has created a new registry titled "EDHOC Cipher Suites". 1229 TODO 1231 8.2. EDHOC Method Type Registry 1233 IANA has created a new registry titled "EDHOC Method Type". 1235 TODO 1237 8.3. The Well-Known URI Registry 1239 IANA has added the well-known URI 'edhoc' to the Well-Known URIs 1240 registry. 1242 o URI suffix: edhoc 1244 o Change controller: IETF 1246 o Specification document(s): [[this document]] 1248 o Related information: None 1250 8.4. Media Types Registry 1252 IANA has added the media type 'application/edhoc' to the Media Types 1253 registry. 1255 o Type name: application 1257 o Subtype name: edhoc 1259 o Required parameters: N/A 1261 o Optional parameters: N/A 1262 o Encoding considerations: binary 1264 o Security considerations: See Section 7 of this document. 1266 o Interoperability considerations: N/A 1268 o Published specification: [[this document]] (this document) 1270 o Applications that use this media type: To be identified 1272 o Fragment identifier considerations: N/A 1274 o Additional information: 1276 * Magic number(s): N/A 1278 * File extension(s): N/A 1280 * Macintosh file type code(s): N/A 1282 o Person & email address to contact for further information: See 1283 "Authors' Addresses" section. 1285 o Intended usage: COMMON 1287 o Restrictions on usage: N/A 1289 o Author: See "Authors' Addresses" section. 1291 o Change Controller: IESG 1293 8.5. CoAP Content-Formats Registry 1295 IANA has added the media type 'application/edhoc' to the CoAP 1296 Content-Formats registry. 1298 o Media Type: application/edhoc 1300 o Encoding: 1302 o ID: TBD42 1304 o Reference: [[this document]] 1306 9. Security Considerations 1308 9.1. Security Properties 1310 EDHOC inherits its security properties from the theoretical SIGMA-I 1311 protocol [SIGMA]. Using the terminology from [SIGMA], EDHOC provides 1312 perfect forward secrecy, mutual authentication with aliveness, 1313 consistency, peer awareness, and identity protection. As described 1314 in [SIGMA], peer awareness is provided to Party V, but not to Party 1315 U. EDHOC also inherits Key Compromise Impersonation (KCI) resistance 1316 from SIGMA-I. 1318 EDHOC with asymmetric authentication offers identity protection of 1319 Party U against active attacks and identity protection of Party V 1320 against passive attacks. The roles should be assigned to protect the 1321 most sensitive identity, typically that which is not possible to 1322 infer from routing information in the lower layers. 1324 Compared to [SIGMA], EDHOC adds an explicit method type and expands 1325 the message authentication coverage to additional elements such as 1326 algorithms, application data, and previous messages. This protects 1327 against an attacker replaying messages or injecting messages from 1328 another session. 1330 EDHOC also adds negotiation of connection identifiers and downgrade 1331 protected negotiation of cryptographic parameters, i.e. an attacker 1332 cannot affect the negotiated parameters. A single session of EDHOC 1333 does not include negotiation of cipher suites, but it enables Party V 1334 to verify that the selected cipher suite is the most preferred cipher 1335 suite by U which is supported by both U and V. 1337 As required by [RFC7258], IETF protocols need to mitigate pervasive 1338 monitoring when possible. One way to mitigate pervasive monitoring 1339 is to use a key exchange that provides perfect forward secrecy. 1340 EDHOC therefore only supports methods with perfect forward secrecy. 1341 To limit the effect of breaches, it is important to limit the use of 1342 symmetrical group keys for bootstrapping. EDHOC therefore strives to 1343 make the additional cost of using raw-public keys and self-signed 1344 certificates as small as possible. Raw-public keys and self-signed 1345 certificates are not a replacement for a public key infrastructure, 1346 but SHOULD be used instead of symmetrical group keys for 1347 bootstrapping. 1349 Compromise of the long-term keys (PSK or private authentication keys) 1350 does not compromise the security of completed EDHOC exchanges. 1351 Compromising the private authentication keys of one party lets the 1352 attacker impersonate that compromised party in EDHOC exchanges with 1353 other parties, but does not let the attacker impersonate other 1354 parties in EDHOC exchanges with the compromised party. Compromising 1355 the PSK lets the attacker impersonate Party U in EDHOC exchanges with 1356 Party V and impersonate Party V in EDHOC exchanges with Party U. 1357 Compromise of the HDKF input parameters (ECDH shared secret and/or 1358 PSK) leads to compromise of all session keys derived from that 1359 compromised shared secret. Compromise of one session key does not 1360 compromise other session keys. 1362 9.2. Cryptographic Considerations 1364 The security of the SIGMA protocol requires the MAC to be bound to 1365 the identity of the signer. Hence the message authenticating 1366 functionality of the authenticated encryption in EDHOC is critical: 1367 authenticated encryption MUST NOT be replaced by plain encryption 1368 only, even if authentication is provided at another level or through 1369 a different mechanism. EDHOC implements SIGMA-I using the same Sign- 1370 then-MAC approach as TLS 1.3. 1372 To reduce message overhead EDHOC does not use explicit nonces and 1373 instead rely on the ephemeral public keys to provide randomness to 1374 each session. A good amount of randomness is important for the key 1375 generation, to provide liveness, and to protect against interleaving 1376 attacks. For this reason, the ephemeral keys MUST NOT be reused, and 1377 both parties SHALL generate fresh random ephemeral key pairs. 1379 The choice of key length used in the different algorithms needs to be 1380 harmonized, so that a sufficient security level is maintained for 1381 certificates, EDHOC, and the protection of application data. Party U 1382 and V should enforce a minimum security level. 1384 The data rates in many IoT deployments are very limited. Given that 1385 the application keys are protected as well as the long-term 1386 authentication keys they can often be used for years or even decades 1387 before the cryptographic limits are reached. If the application keys 1388 established through EDHOC need to be renewed, the communicating 1389 parties can derive application keys with other labels or run EDHOC 1390 again. 1392 9.3. Mandatory to Implement Cipher Suite 1394 Cipher suite number 0 (AES-CCM-64-64-128, ECDH-SS + HKDF-256, X25519, 1395 Ed25519) is mandatory to implement. For many constrained IoT devices 1396 it is problematic to support more than one cipher suites, so some 1397 deployments with P-256 may not support the mandatory cipher suite. 1398 This is not a problem for local deployments. 1400 9.4. Unprotected Data 1402 Party U and V must make sure that unprotected data and metadata do 1403 not reveal any sensitive information. This also applies for 1404 encrypted data sent to an unauthenticated party. In particular, it 1405 applies to UAD_1, ID_CRED_V, UAD_2, and ERR_MSG in the asymmetric 1406 case, and ID_PSK, UAD_1, and ERR_MSG in the symmetric case. Using 1407 the same ID_PSK or UAD_1 in several EDHOC sessions allows passive 1408 eavesdroppers to correlate the different sessions. The communicating 1409 parties may therefore anonymize ID_PSK. Another consideration is 1410 that the list of supported cipher suites may be used to identify the 1411 application. 1413 Party U and V must also make sure that unauthenticated data does not 1414 trigger any harmful actions. In particular, this applies to UAD_1 1415 and ERR_MSG in the asymmetric case, and ID_PSK, UAD_1, and ERR_MSG in 1416 the symmetric case. 1418 9.5. Denial-of-Service 1420 EDHOC itself does not provide countermeasures against Denial-of- 1421 Service attacks. By sending a number of new or replayed message_1 an 1422 attacker may cause Party V to allocate state, perform cryptographic 1423 operations, and amplify messages. To mitigate such attacks, an 1424 implementation SHOULD rely on lower layer mechanisms such as the Echo 1425 option in CoAP [I-D.ietf-core-echo-request-tag] that forces the 1426 initiator to demonstrate reachability at its apparent network 1427 address. 1429 9.6. Implementation Considerations 1431 The availability of a secure pseudorandom number generator and truly 1432 random seeds are essential for the security of EDHOC. If no true 1433 random number generator is available, a truly random seed must be 1434 provided from an external source. If ECDSA is supported, 1435 "deterministic ECDSA" as specified in [RFC6979] is RECOMMENDED. 1437 The referenced processing instructions in [SP-800-56A] must be 1438 complied with, including deleting the intermediate computed values 1439 along with any ephemeral ECDH secrets after the key derivation is 1440 completed. The ECDH shared secret, keys (K_2, K_3), and IVs (IV_2, 1441 IV_3) MUST be secret. Implementations should provide countermeasures 1442 to side-channel attacks such as timing attacks. 1444 Party U and V are responsible for verifying the integrity of 1445 certificates. The selection of trusted CAs should be done very 1446 carefully and certificate revocation should be supported. The 1447 private authentication keys and the PSK (even though it is used as 1448 salt) MUST be kept secret. 1450 Party U and V are allowed to select the connection identifiers C_U 1451 and C_V, respectively, for the other party to use in the ongoing 1452 EDHOC protocol as well as in a subsequent application protocol (e.g. 1453 OSCORE [I-D.ietf-core-object-security]). The choice of connection 1454 identifier is not security critical in EDHOC but intended to simplify 1455 the retrieval of the right security context in combination with using 1456 short identifiers. If the wrong connection identifier of the other 1457 party is used in a protocol message it will result in the receiving 1458 party not being able to retrieve a security context (which will 1459 terminate the protocol) or retrieve the wrong security context (which 1460 also terminates the protocol as the message cannot be verified). 1462 Party V MUST finish the verification step of message_3 before passing 1463 PAD_3 to the application. 1465 9.7. Other Documents Referencing EDHOC 1467 EDHOC has been analyzed in several other documents. A formal 1468 verification of EDHOC was done in [SSR18], an analysis of EDHOC for 1469 certificate enrollment was done in [Kron18], the use of EDHOC in 1470 LoRaWAN is analyzed in [LoRa1] and [LoRa2], the use of EDHOC in IoT 1471 bootstrapping is analyzed in [Perez18], and the use of EDHOC in 1472 6TiSCH is described in [I-D.ietf-6tisch-dtsecurity-zerotouch-join]. 1474 10. References 1476 10.1. Normative References 1478 [I-D.ietf-cbor-7049bis] 1479 Bormann, C. and P. Hoffman, "Concise Binary Object 1480 Representation (CBOR)", draft-ietf-cbor-7049bis-05 (work 1481 in progress), January 2019. 1483 [I-D.ietf-cbor-cddl] 1484 Birkholz, H., Vigano, C., and C. Bormann, "Concise data 1485 definition language (CDDL): a notational convention to 1486 express CBOR and JSON data structures", draft-ietf-cbor- 1487 cddl-07 (work in progress), February 2019. 1489 [I-D.ietf-core-echo-request-tag] 1490 Amsuess, C., Mattsson, J., and G. Selander, "Echo and 1491 Request-Tag", draft-ietf-core-echo-request-tag-03 (work in 1492 progress), October 2018. 1494 [I-D.ietf-core-object-security] 1495 Selander, G., Mattsson, J., Palombini, F., and L. Seitz, 1496 "Object Security for Constrained RESTful Environments 1497 (OSCORE)", draft-ietf-core-object-security-15 (work in 1498 progress), August 2018. 1500 [I-D.schaad-cose-x509] 1501 Schaad, J., "CBOR Object Signing and Encryption (COSE): 1502 Headers for carrying and referencing X.509 certificates", 1503 draft-schaad-cose-x509-03 (work in progress), December 1504 2018. 1506 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1507 Requirement Levels", BCP 14, RFC 2119, 1508 DOI 10.17487/RFC2119, March 1997, 1509 . 1511 [RFC5116] McGrew, D., "An Interface and Algorithms for Authenticated 1512 Encryption", RFC 5116, DOI 10.17487/RFC5116, January 2008, 1513 . 1515 [RFC5869] Krawczyk, H. and P. Eronen, "HMAC-based Extract-and-Expand 1516 Key Derivation Function (HKDF)", RFC 5869, 1517 DOI 10.17487/RFC5869, May 2010, 1518 . 1520 [RFC6090] McGrew, D., Igoe, K., and M. Salter, "Fundamental Elliptic 1521 Curve Cryptography Algorithms", RFC 6090, 1522 DOI 10.17487/RFC6090, February 2011, 1523 . 1525 [RFC6979] Pornin, T., "Deterministic Usage of the Digital Signature 1526 Algorithm (DSA) and Elliptic Curve Digital Signature 1527 Algorithm (ECDSA)", RFC 6979, DOI 10.17487/RFC6979, August 1528 2013, . 1530 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 1531 Application Protocol (CoAP)", RFC 7252, 1532 DOI 10.17487/RFC7252, June 2014, 1533 . 1535 [RFC7959] Bormann, C. and Z. Shelby, Ed., "Block-Wise Transfers in 1536 the Constrained Application Protocol (CoAP)", RFC 7959, 1537 DOI 10.17487/RFC7959, August 2016, 1538 . 1540 [RFC8152] Schaad, J., "CBOR Object Signing and Encryption (COSE)", 1541 RFC 8152, DOI 10.17487/RFC8152, July 2017, 1542 . 1544 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 1545 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 1546 May 2017, . 1548 [SIGMA] Krawczyk, H., "SIGMA - The 'SIGn-and-MAc' Approach to 1549 Authenticated Diffie-Hellman and Its Use in the IKE- 1550 Protocols (Long version)", June 2003, 1551 . 1553 [SP-800-56A] 1554 Barker, E., Chen, L., Roginsky, A., Vassilev, A., and R. 1555 Davis, "Recommendation for Pair-Wise Key-Establishment 1556 Schemes Using Discrete Logarithm Cryptography", 1557 NIST Special Publication 800-56A Revision 3, April 2018, 1558 . 1560 10.2. Informative References 1562 [CborMe] Bormann, C., "CBOR Playground", May 2018, 1563 . 1565 [I-D.hartke-core-e2e-security-reqs] 1566 Selander, G., Palombini, F., and K. Hartke, "Requirements 1567 for CoAP End-To-End Security", draft-hartke-core-e2e- 1568 security-reqs-03 (work in progress), July 2017. 1570 [I-D.ietf-6tisch-dtsecurity-zerotouch-join] 1571 Richardson, M., "6tisch Zero-Touch Secure Join protocol", 1572 draft-ietf-6tisch-dtsecurity-zerotouch-join-03 (work in 1573 progress), October 2018. 1575 [I-D.ietf-ace-oauth-authz] 1576 Seitz, L., Selander, G., Wahlstroem, E., Erdtman, S., and 1577 H. Tschofenig, "Authentication and Authorization for 1578 Constrained Environments (ACE) using the OAuth 2.0 1579 Framework (ACE-OAuth)", draft-ietf-ace-oauth-authz-22 1580 (work in progress), March 2019. 1582 [I-D.ietf-ace-oscore-profile] 1583 Palombini, F., Seitz, L., Selander, G., and M. Gunnarsson, 1584 "OSCORE profile of the Authentication and Authorization 1585 for Constrained Environments Framework", draft-ietf-ace- 1586 oscore-profile-07 (work in progress), February 2019. 1588 [I-D.ietf-core-resource-directory] 1589 Shelby, Z., Koster, M., Bormann, C., Stok, P., and C. 1590 Amsuess, "CoRE Resource Directory", draft-ietf-core- 1591 resource-directory-19 (work in progress), January 2019. 1593 [I-D.ietf-lwig-security-protocol-comparison] 1594 Mattsson, J. and F. Palombini, "Comparison of CoAP 1595 Security Protocols", draft-ietf-lwig-security-protocol- 1596 comparison-02 (work in progress), January 2019. 1598 [I-D.ietf-tls-dtls13] 1599 Rescorla, E., Tschofenig, H., and N. Modadugu, "The 1600 Datagram Transport Layer Security (DTLS) Protocol Version 1601 1.3", draft-ietf-tls-dtls13-30 (work in progress), 1602 November 2018. 1604 [Kron18] Krontiris, A., "Evaluation of Certificate Enrollment over 1605 Application Layer Security", May 2018, 1606 . 1609 [LoRa1] Sanchez-Iborra, R., Sanchez-Gomez, J., Perez, S., 1610 Fernandez, P., Santa, J., Hernandez-Ramos, J., and A. 1611 Skarmeta, "Enhancing LoRaWAN Security through a 1612 Lightweight and Authenticated Key Management Approach", 1613 June 2018, 1614 . 1617 [LoRa2] Sanchez-Iborra, R., Sanchez-Gomez, J., Perez, S., 1618 Fernandez, P., Santa, J., Hernandez-Ramos, J., and A. 1619 Skarmeta, "Internet Access for LoRaWAN Devices Considering 1620 Security Issues", June 2018, 1621 . 1623 [Perez18] Perez, S., Garcia-Carrillo, D., Marin-Lopez, R., 1624 Hernandez-Ramos, J., Marin-Perez, R., and A. Skarmeta, 1625 "Architecture of security association establishment based 1626 on bootstrapping technologies for enabling critical IoT 1627 infrastructures", October 2018, . 1632 [RFC7228] Bormann, C., Ersue, M., and A. Keranen, "Terminology for 1633 Constrained-Node Networks", RFC 7228, 1634 DOI 10.17487/RFC7228, May 2014, 1635 . 1637 [RFC7258] Farrell, S. and H. Tschofenig, "Pervasive Monitoring Is an 1638 Attack", BCP 188, RFC 7258, DOI 10.17487/RFC7258, May 1639 2014, . 1641 [RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol 1642 Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018, 1643 . 1645 [SSR18] Bruni, A., Sahl Joergensen, T., Groenbech Petersen, T., 1646 and C. Schuermann, "Formal Verification of Ephemeral 1647 Diffie-Hellman Over COSE (EDHOC)", November 2018, 1648 . 1652 Appendix A. Use of CBOR, CDDL and COSE in EDHOC 1654 This Appendix is intended to simplify for implementors not familiar 1655 with CBOR [I-D.ietf-cbor-7049bis], CDDL [I-D.ietf-cbor-cddl], COSE 1656 [RFC8152], and HKDF [RFC5869]. 1658 A.1. CBOR and CDDL 1660 The Concise Binary Object Representation (CBOR) 1661 [I-D.ietf-cbor-7049bis] is a data format designed for small code size 1662 and small message size. CBOR builds on the JSON data model but 1663 extends it by e.g. encoding binary data directly without base64 1664 conversion. In addition to the binary CBOR encoding, CBOR also has a 1665 diagnostic notation that is readable and editable by humans. The 1666 Concise Data Definition Language (CDDL) [I-D.ietf-cbor-cddl] provides 1667 a way to express structures for protocol messages and APIs that use 1668 CBOR. [I-D.ietf-cbor-cddl] also extends the diagnostic notation. 1670 CBOR data items are encoded to or decoded from byte strings using a 1671 type-length-value encoding scheme, where the three highest order bits 1672 of the initial byte contain information about the major type. CBOR 1673 supports several different types of data items, in addition to 1674 integers (int, uint), simple values (e.g. null), byte strings (bstr), 1675 and text strings (tstr), CBOR also supports arrays [] of data items 1676 and maps {} of pairs of data items. Some examples are given below. 1677 For a complete specification and more examples, see 1678 [I-D.ietf-cbor-7049bis] and [I-D.ietf-cbor-cddl]. We recommend 1679 implementors to get used to CBOR by using the CBOR playground 1680 [CborMe]. 1682 Diagnostic Encoded Type 1683 ------------------------------------------------------------------ 1684 1 0x01 unsigned integer 1685 24 0x1818 unsigned integer 1686 -24 0x37 negative integer 1687 -25 0x3818 negative integer 1688 null 0xf6 simple value 1689 h'12cd' 0x4212cd byte string 1690 '12cd' 0x4431326364 byte string 1691 "12cd" 0x6431326364 text string 1692 << 1, 2, null >> 0x430102f6 byte string 1693 [ 1, 2, null ] 0x830102f6 array 1694 [_ 1, 2, null ] 0x9f0102f6ff array (indefinite-length) 1695 ( 1, 2, null ) 0x0102f6 group 1696 { 4: h'cd' } 0xa10441cd map 1697 ------------------------------------------------------------------ 1699 All EDHOC messages consist of a sequence of CBOR encoded data items. 1700 While an EDHOC message in itself is not a CBOR data item, it may be 1701 viewed as the CBOR encoding of an indefinite-length array [_ 1702 message_i ] without the first byte (0x9f) and the last byte (0xff), 1703 for i = 1, 2 and 3. The same applies to the EDHOC error message. 1705 The message format specification uses the constructs '.cbor' and 1706 '.cborseq' enabling conversion between different CDDL types matching 1707 different CBOR items with different encodings. Some examples are 1708 given below. 1710 A type (e.g. an uint) may be wrapped in a byte string (bstr): 1712 CDDL Type Diagnostic Encoded 1713 ------------------------------------------------------------------ 1714 uint 24 0x1818 1715 bstr .cbor uint << 24 >> 0x421818 1716 ------------------------------------------------------------------ 1718 An array, say of an uint and a byte string, may be converted into a 1719 byte string (bstr): 1721 CDDL Type Diagnostic Encoded 1722 -------------------------------------------------------------------- 1723 bstr h'cd' 0x41cd 1724 [ uint, bstr ] [ 24, h'cd' ] 0x82181841cd 1725 bstr .cborseq [ uint, bstr ] << 24, h'cd' >> 0x44181841cd 1726 -------------------------------------------------------------------- 1728 A.2. COSE 1730 CBOR Object Signing and Encryption (COSE) [RFC8152] describes how to 1731 create and process signatures, message authentication codes, and 1732 encryption using CBOR. COSE builds on JOSE, but is adapted to allow 1733 more efficient processing in constrained devices. EDHOC makes use of 1734 COSE_Key, COSE_Encrypt0, COSE_Sign1, and COSE_KDF_Context objects. 1736 A.2.1. Encryption and Decryption 1738 The COSE parameters used in COSE_Encrypt0 (see Section 5.2 of 1739 [RFC8152]) are constructed as described below. Note that "i" in 1740 "K_i", "IV_i" and "TH_i" is a variable with value i = 2 or 3, 1741 depending on whether the calculation is made over message_2 or 1742 message_3. 1744 o The secret key K_i is a CBOR bstr, generated with the EDHOC-Key- 1745 Derivation function as defined in Section 3.3. 1747 o The initialization vector IV_i is a CBOR bstr, also generated with 1748 the EDHOC-Key-Derivation function as defined in Section 3.3. 1750 o The plaintext is a CBOR bstr. If the application data (UAD and 1751 PAD) is omitted, then plaintext = h'' in the symmetric case, and 1752 plaintext = << ID_CRED_x, signature >> in the asymmetric case. 1753 Note that if ID_CRED_x contains a single 'kid' parameter, i.e., 1754 ID_CRED_x = { 4 : bstr }, only the bstr is conveyed in the 1755 plaintext. For instance, if ID_CRED_x = { 4 : h'40' } (CBOR 1756 encoding 0xA1044140) and signature = h'050607' (CBOR encoding 1757 0x43050607), then plaintext = h'414043050607'. 1759 o The external_aad is a CBOR bstr. It is always set to the 1760 transcript hash TH_i. 1762 COSE constructs the input to the AEAD [RFC5116] as follows: 1764 o The key K is the value of the key K_i. 1766 o The nonce N is the value of the initialization vector IV_i. 1768 o The plaintext P is the value of the COSE plaintext. E.g. if the 1769 COSE plaintext = h'010203', then P = 0x010203. 1771 o The associated data A is the CBOR encoding of: 1773 [ "Encrypt0", h'', TH_i ] 1774 This equals the concatenation of 0x8368456e63727970743040 and the 1775 CBOR encoding of TH_i. For instance if TH_2 = h'010203' (CBOR 1776 encoding 0x43010203), then A = 0x8368456e6372797074304043010203. 1778 A.2.2. Signing and Verification 1780 The COSE parameters used in COSE_Sign1 (see Section 4.2 of [RFC8152]) 1781 are constructed as described below. Note that "i" in "TH_i" is a 1782 variable with values i = 2 or 3, depending on whether the calculation 1783 is made over message_2 or message_3. Note also that "x" in 1784 "ID_CRED_x" and "CRED_x" is a variable with values x = U or V, 1785 depending on whether it is the credential of U or of V that is used 1786 in the relevant protocol message. 1788 o The key is the private authentication key of U or V. This may be 1789 stored as a COSE_KEY object or as a certificate. 1791 o The protected parameter is a map ID_CRED_x = { label : value } is 1792 wrapped in a byte string. 1794 o The payload is a bstr containing the CBOR encoding of a COSE_KEY 1795 or a single certificate. 1797 o external_aad = TH_i. 1799 COSE constructs the input to the Signature Algorithm as follows: 1801 o The key is the private authentication key of U or V. 1803 o The message to be signed M is the CBOR encoding of: 1805 [ "Signature1", << { label : value } >>, TH_i, CRED_x ] 1807 For instance, if ID_CRED_x = { 4 : h'1111' } (CBOR encoding 1808 0xA104421111), TH_3 = h'222222' (CBOR encoding 0x43222222), and 1809 CRED_U = h'55555555' (CBOR encoding 0x4455555555), then M = 1810 0x846a5369676e61747572653145A104421111432222224455555555. 1812 A.2.3. Key Derivation 1814 Assuming use of the mandatory-to-implement algorithms HKDF SHA-256 1815 and AES-CCM-16-64-128, the extract phase of HKDF produces a 1816 pseudorandom key (PRK) as follows: 1818 PRK = HMAC-SHA-256( salt, ECDH shared secret ) 1820 where salt = 0x (the empty byte string) in the asymmetric case and 1821 salt = PSK in the symmetric case. As the output length L is smaller 1822 than the hash function output size, the expand phase of HKDF consists 1823 of a single HMAC invocation, and K_i and IV_i are therefore the first 1824 16 and 13 bytes, respectively, of 1826 output parameter = HMAC-SHA-256( PRK, info || 0x01 ) 1828 where || means byte string concatenation, and info is the CBOR 1829 encoding of 1831 COSE_KDF_Context = [ 1832 AlgorithmID, 1833 [ null, null, null ], 1834 [ null, null, null ], 1835 [ keyDataLength, h'', TH_i ] 1836 ] 1838 If AES-CCM-16-64-128 then AlgorithmID = 10 and keyDataLength = 128 1839 for K_i, and AlgorithmID = "IV-GENERATION" (CBOR encoding 1840 0x6d49562d47454e45524154494f4e) and keyDataLength = 104 for IV_i. 1841 Hence, if TH_2 = h'aaaa' then 1843 K_2 = HMAC-SHA-256( PRK, 0x840a83f6f6f683f6f6f68318804042aaaa01 ) 1844 IV_2 = HMAC-SHA-256( PRK, 0x846d49562d47454e45524154494f4e 1845 83f6f6f683f6f6f68318804042aaaa01 ) 1847 Appendix B. Example Messages and Sizes 1849 To help implementors, this appendix gives examples in CBOR diagnostic 1850 notation and hexadecimal of EDHOC messages and plaintexts with 1851 different authentication methods. The examples use 1 byte key 1852 identifiers, 1 byte connection IDs, and the default mapping to CoAP 1853 (corr = 1). Note that the examples in this appendix are not test 1854 vectors, the cryptographic parts are just replaced with byte strings 1855 of the same length. 1857 B.1. Message Sizes RPK 1859 B.1.1. message_1 1861 message_1 = ( 1862 1, 1863 0, 1864 h'000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d 1865 1e1f', 1866 h'c3' 1867 ) 1868 message_1 (38 bytes): 1869 01 00 58 20 00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F 1870 10 11 12 13 14 15 16 17 18 19 1A 1B 1C 1D 1E 1F 41 C3 1872 B.1.2. message_2 1874 plaintext = << 1875 h'a1', 1876 h'000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d 1877 1e1f202122232425262728292a2b2c2d2e2f303132333435363738393a3b 1878 3c3d3e3f' 1879 >> 1881 In the plaintext, the header map { 4 : h'a1' } is encoded as the two 1882 bytes h'a1'. The length of plaintext is 68 bytes so assuming a 1883 64-bit MAC value the length of ciphertext is 76 bytes. 1885 message_2 = ( 1886 h'000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d 1887 1e1f', 1888 h'c4', 1889 h'000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d 1890 1e1f202122232425262728292a2b2c2d2e2f303132333435363738393a3b 1891 3c3d3e3f404142434445464748494a4b' 1892 ) 1894 message_2 (114 bytes): 1895 58 20 00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F 10 11 1896 12 13 14 15 16 17 18 19 1A 1B 1C 1D 1E 1F 41 C4 58 51 00 01 1897 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F 10 11 12 13 14 15 1898 16 17 18 19 1A 1B 1C 1D 1E 1F 20 21 22 23 24 25 26 27 28 29 1899 2A 2B 2C 2D 2E 2F 30 31 32 33 34 35 36 37 38 39 3A 3B 3C 3D 1900 3E 3F 40 41 42 43 44 45 46 47 48 49 4A 4B 1902 B.1.3. message_3 1904 The plaintext and ciphertext in message_3 are assumed to be of equal 1905 sizes as in message_2. 1907 message_3 = ( 1908 h'c4', 1909 h'000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d 1910 1e1f202122232425262728292a2b2c2d2e2f303132333435363738393a3b 1911 3c3d3e3f404142434445464748494a4b' 1912 ) 1913 message_3 (80 bytes): 1914 41 C4 58 51 00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F 1915 10 11 12 13 14 15 16 17 18 19 1A 1B 1C 1D 1E 1F 20 21 22 23 1916 24 25 26 27 28 29 2A 2B 2C 2D 2E 2F 30 31 32 33 34 35 36 37 1917 38 39 3A 3B 3C 3D 3E 3F 40 41 42 43 44 45 46 47 48 49 4A 4B 1919 B.2. Message Sizes Certificates 1921 When the certificates are distributed out-of-band and identified with 1922 the x5t header parameter and a SHA256/64 hash value, the header map 1923 will be 13 bytes (assuming labels in the range -24...23). 1925 { TDB1 : [ TDB6, h'0001020304050607' ] } 1927 When the certificates are identified with the x5chain header 1928 parameter, the message sizes depends on the size of the (truncated) 1929 certificate chains. The header map will be 3 bytes + the size of the 1930 certificate chain (assuming a label in the range -24...23). 1932 { TDB3 : h'0001020304050607...' } 1934 B.3. Message Sizes PSK 1936 B.3.1. message_1 1938 message_1 = ( 1939 4, 1940 0, 1941 h'000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d 1942 1e1f', 1943 h'c3', 1944 h'a2' 1945 ) 1947 message_1 (40 bytes): 1948 04 00 58 20 00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F 1949 10 11 12 13 14 15 16 17 18 19 1A 1B 1C 1D 1E 1F 41 C3 41 A2 1951 B.3.2. message_2 1953 Assuming a 0 byte plaintext and a 64-bit MAC value the ciphertext is 1954 8 bytes 1955 message_2 = ( 1956 h'000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d 1957 1e1f', 1958 h'c4', 1959 h'0001020304050607' 1960 ) 1962 message_2 (45 bytes): 1963 58 20 00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F 10 11 1964 12 13 14 15 16 17 18 19 1A 1B 1C 1D 1E 1F 41 C4 48 61 62 63 1965 64 65 66 67 68 1967 B.3.3. message_3 1969 The plaintext and ciphertext in message_3 are assumed to be of equal 1970 sizes as in message_2. 1972 message_3 = ( 1973 h'c4', 1974 h'0001020304050607' 1975 ) 1977 message_3 (11 bytes): 1978 41 C4 48 00 01 02 03 04 05 06 07 1980 B.4. Summary 1982 The previous examples of typical message sizes are summarized in 1983 Figure 9. 1985 ===================================================================== 1986 PSK RPK x5t x5chain 1987 --------------------------------------------------------------------- 1988 message_1 40 38 38 38 1989 message_2 45 114 126 116 + Certificate chain 1990 message_3 11 80 91 81 + Certificate chain 1991 --------------------------------------------------------------------- 1992 Total 96 232 255 235 + Certificate chains 1993 ===================================================================== 1995 Figure 9: Typical message sizes in bytes 1997 These examples use 1 byte key identifiers and connection IDs, this is 1998 realistic in many scenarios as most constrained devices only have a 1999 few keys and connection. In cases where a node only have one 2000 connection or key, the identifiers may even be the empty byte string. 2002 For a comparison with other protocols, see 2003 [I-D.ietf-lwig-security-protocol-comparison]. 2005 Appendix C. Test Vectors 2007 This appendix provides a wealth of test vectors to ease 2008 implementation and ensure interoperability. 2010 TODO: This section needs to be updated. 2012 Acknowledgments 2014 The authors want to thank Alessandro Bruni, Theis Groenbech Petersen, 2015 Dan Harkins, Klaus Hartke, Russ Housley, Alexandros Krontiris, Ilari 2016 Liusvaara, Karl Norrman, Salvador Perez, Michael Richardson, Thorvald 2017 Sahl Joergensen, Jim Schaad, Carsten Schuermann, Ludwig Seitz, 2018 Stanislav Smyshlyaev, Valery Smyslov, and Rene Struik for reviewing 2019 and commenting on intermediate versions of the draft. We are 2020 especially indebted to Jim Schaad for his continuous reviewing and 2021 implementation of different versions of the draft. 2023 Authors' Addresses 2025 Goeran Selander 2026 Ericsson AB 2028 Email: goran.selander@ericsson.com 2030 John Mattsson 2031 Ericsson AB 2033 Email: john.mattsson@ericsson.com 2035 Francesca Palombini 2036 Ericsson AB 2038 Email: francesca.palombini@ericsson.com