idnits 2.17.1 draft-selander-ace-cose-ecdhe-12.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 (February 25, 2019) is 1881 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-21 == 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 (-43) exists of draft-ietf-tls-dtls13-30 Summary: 5 errors (**), 0 flaws (~~), 10 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: August 29, 2019 Ericsson AB 6 February 25, 2019 8 Ephemeral Diffie-Hellman Over COSE (EDHOC) 9 draft-selander-ace-cose-ecdhe-12 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. A main use case 17 for EDHOC is to establish an OSCORE security context. EDHOC uses 18 COSE for cryptography, CBOR for encoding, and CoAP for transport. By 19 reusing existing libraries, the additional code footprint can be kept 20 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 August 29, 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 . . . . . . . . . . . . . . . . . . . . . . . . . 6 60 3. EDHOC Overview . . . . . . . . . . . . . . . . . . . . . . . 7 61 3.1. Cipher Suites . . . . . . . . . . . . . . . . . . . . . . 9 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 . . . . . . . . . . . . . . . . . . . . . 14 68 4.4. EDHOC Message 3 . . . . . . . . . . . . . . . . . . . . . 17 69 5. EDHOC Authenticated with Symmetric Keys . . . . . . . . . . . 19 70 5.1. Overview . . . . . . . . . . . . . . . . . . . . . . . . 19 71 5.2. EDHOC Message 1 . . . . . . . . . . . . . . . . . . . . . 20 72 5.3. EDHOC Message 2 . . . . . . . . . . . . . . . . . . . . . 21 73 5.4. EDHOC Message 3 . . . . . . . . . . . . . . . . . . . . . 21 74 6. Error Handling . . . . . . . . . . . . . . . . . . . . . . . 21 75 6.1. EDHOC Error Message . . . . . . . . . . . . . . . . . . . 21 76 7. Transferring EDHOC and Deriving Application Keys . . . . . . 23 77 7.1. Transferring EDHOC in CoAP . . . . . . . . . . . . . . . 23 78 7.2. Transferring EDHOC over Other Protocols . . . . . . . . . 26 79 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 26 80 8.1. EDHOC Cipher Suites Registry . . . . . . . . . . . . . . 26 81 8.2. EDHOC Method Type Registry . . . . . . . . . . . . . . . 26 82 8.3. The Well-Known URI Registry . . . . . . . . . . . . . . . 26 83 8.4. Media Types Registry . . . . . . . . . . . . . . . . . . 26 84 8.5. CoAP Content-Formats Registry . . . . . . . . . . . . . . 27 85 9. Security Considerations . . . . . . . . . . . . . . . . . . . 28 86 9.1. Security Properties . . . . . . . . . . . . . . . . . . . 28 87 9.2. Cryptographic Considerations . . . . . . . . . . . . . . 28 88 9.3. Mandatory to Implement Cipher Suite . . . . . . . . . . . 29 89 9.4. Unprotected Data . . . . . . . . . . . . . . . . . . . . 29 90 9.5. Denial-of-Service . . . . . . . . . . . . . . . . . . . . 30 91 9.6. Implementation Considerations . . . . . . . . . . . . . . 30 92 9.7. Other Documents Referencing EDHOC . . . . . . . . . . . . 31 93 10. References . . . . . . . . . . . . . . . . . . . . . . . . . 31 94 10.1. Normative References . . . . . . . . . . . . . . . . . . 31 95 10.2. Informative References . . . . . . . . . . . . . . . . . 33 96 Appendix A. Use of CBOR, CDDL and COSE in EDHOC . . . . . . . . 34 97 A.1. CBOR and CDDL . . . . . . . . . . . . . . . . . . . . . . 35 98 A.2. COSE . . . . . . . . . . . . . . . . . . . . . . . . . . 36 99 Appendix B. Example Messages and Sizes . . . . . . . . . . . . . 39 100 B.1. Message Sizes RPK . . . . . . . . . . . . . . . . . . . . 39 101 B.2. Message Sizes Certificates . . . . . . . . . . . . . . . 40 102 B.3. Message Sizes PSK . . . . . . . . . . . . . . . . . . . . 40 103 B.4. Summary . . . . . . . . . . . . . . . . . . . . . . . . . 42 104 Appendix C. Test Vectors . . . . . . . . . . . . . . . . . . . . 43 105 Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . 43 106 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 43 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 protocol needs to 114 work on 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 enables use of future COSE 159 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 deals 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 can 191 in constrained environments be translated into key exchange overhead. 193 Power consumption for wireless devices is highly dependent on message 194 transmission, listening, and reception. For devices that only send a 195 few bytes occasionally, the battery lifetime may be significantly 196 reduced by a heavy key exchange protocol. Moreover, a key exchange 197 may need to be executed more than once, e.g. due to a device losing 198 power or rebooting for other reasons. 200 EDHOC is adapted to primitives and protocols designed for the 201 Internet of Things: EDHOC is built on CBOR and COSE which enables 202 small message overhead and efficient parsing in constrained devices. 203 EDHOC is not bound to a particular transport layer, but it is 204 recommended to transport the EDHOC message in CoAP payloads. By 205 reusing already existing IoT primitives in the device (CBOR, CoAP, 206 and COSE encryption and signature formats) the additional code 207 footprint can be kept very low. 209 EDHOC is not bound to a particular communication security protocol 210 but works off-the-shelf with OSCORE [I-D.ietf-core-object-security] 211 providing the necessary input parameters with required properties. 212 Since EDHOC builds on the same IoT primitives and protocols as OSCORE 213 (CoAP, CBOR, COSE encryption and signature formats) the device 214 footprint for EDHOC + OSCORE can be kept very low. The use of 215 compact native encoding formats reduces the need for a general- 216 purpose compression algorithm with associated footprint. 218 1.2. Terminology and Requirements Language 220 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 221 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 222 "OPTIONAL" in this document are to be interpreted as described in BCP 223 14 [RFC2119] [RFC8174] when, and only when, they appear in all 224 capitals, as shown here. 226 The word "encryption" without qualification always refers to 227 authenticated encryption, in practice implemented with an 228 Authenticated Encryption with Additional Data (AEAD) algorithm, see 229 [RFC5116]. 231 Readers are expected to be familiar with the terms and concepts 232 described in CBOR [I-D.ietf-cbor-7049bis], COSE [RFC8152], and CDDL 233 [I-D.ietf-cbor-cddl]. The Concise Data Definition Language (CDDL) to 234 express CBOR data structures [I-D.ietf-cbor-7049bis]. The use of the 235 CDDL unwrap operator "~" is extended to unwrapping of byte strings. 236 It is the inverse of "bstr .cbor" that wraps a data item in a bstr, 237 i.e. ~ bstr .cbor T = T. Examples of CBOR and CDDL are provided in 238 Appendix A.1. 240 2. Background 242 SIGMA (SIGn-and-MAc) is a family of theoretical protocols with a 243 large number of variants [SIGMA]. Like IKEv2 and (D)TLS 1.3, EDHOC 244 is built on a variant of the SIGMA protocol which provide identity 245 protection of the initiator (SIGMA-I), and like (D)TLS 1.3, EDHOC 246 implements the SIGMA-I variant as Sign-then-MAC. The SIGMA-I 247 protocol using an authenticated encryption algorithm is shown in 248 Figure 1. 250 Party U Party V 251 | X_U | 252 +-------------------------------------------------------->| 253 | | 254 | X_V, AEAD( K_2; ID_CRED_V, Sig(V; CRED_V, X_U, X_V) ) | 255 |<--------------------------------------------------------+ 256 | | 257 | AEAD( K_3; ID_CRED_U, Sig(U; CRED_U, X_V, X_U) ) | 258 +-------------------------------------------------------->| 259 | | 261 Figure 1: Authenticated encryption variant of the SIGMA-I protocol. 263 The parties exchanging messages are called "U" and "V". They 264 exchange identities and ephemeral public keys, compute the shared 265 secret, and derive symmetric application keys. 267 o X_U and X_V are the ECDH ephemeral public keys of U and V, 268 respectively. 270 o CRED_U and CRED_V are the credentials containing the public 271 authentication keys of U and V, respectively. 273 o ID_CRED_U and ID_CRED_V are data enabling the recipient party to 274 retrieve the credential of U and V, respectively 276 o Sig(U; . ) and S(V; . ) denote signatures made with the private 277 authentication key of U and V, respectively. 279 o AEAD(K; . ) denotes authenticated encryption with additional data 280 using the key K derived from the shared secret. The authenticated 281 encryption MUST NOT be replaced by plain encryption, see 282 Section 9. 284 In order to create a "full-fledged" protocol some additional protocol 285 elements are needed. EDHOC adds: 287 o Explicit connection identifiers C_U, C_V chosen by U and V, 288 respectively, enabling the recipient to find the protocol state. 290 o An Authenticated Encryption with Additional Data (AEAD) algorithm 291 is used. 293 o Computationally independent keys derived from the ECDH shared 294 secret and used for encryption of different messages. 296 o Verification of a common preferred cipher suite (AEAD algorithm, 297 ECDH algorithm, ECDH curve, signature algorithm): 299 * U lists supported cipher suites in order of preference 301 * V verifies that the selected cipher suite is the first 302 supported cipher suite 304 o Method types and error handling. 306 o Transport of opaque application defined data. 308 EDHOC is designed to encrypt and integrity protect as much 309 information as possible, and all symmetric keys are derived using as 310 much previous information as possible. EDHOC is furthermore designed 311 to be as compact and lightweight as possible, in terms of message 312 sizes, processing, and the ability to reuse already existing CBOR, 313 COSE, and CoAP libraries. 315 To simplify for implementors, the use of CBOR and COSE in EDHOC is 316 summarized in Appendix A and example messages in CBOR diagnostic 317 notation are given in Appendix B. 319 3. EDHOC Overview 321 EDHOC consists of three flights (message_1, message_2, message_3) 322 that maps directly to the three messages in SIGMA-I, plus an EDHOC 323 error message. All EDHOC messages consists of a sequence of CBOR 324 encoded data items, where the first data item of message_1 is an int 325 specifying the method type (asymmetric, symmetric, error). The 326 messages may be viewed as a CBOR encoding of an indefinite-length 327 array without the first and last byte, see Appendix A.1. 329 While EDHOC uses the COSE_Key, COSE_Sign1, and COSE_Encrypt0 330 structures, only a subset of the parameters is included in the EDHOC 331 messages. After creating EDHOC message_3, Party U can derive 332 symmetric application keys, and application protected data can 333 therefore be sent in parallel with EDHOC message_3. The application 334 may protect data using the algorithms (AEAD, HKDF, etc.) in the 335 selected cipher suite and the connection identifiers (C_U, C_V). 336 EDHOC may be used with the media type application/edhoc defined in 337 Section 8. 339 Party U Party V 340 | | 341 | ------------------ EDHOC message_1 -----------------> | 342 | | 343 | <----------------- EDHOC message_2 ------------------ | 344 | | 345 | ------------------ EDHOC message_3 -----------------> | 346 | | 347 | <----------- Application Protected Data ------------> | 348 | | 350 Figure 2: EDHOC message flow 352 The EDHOC message exchange may be authenticated using pre-shared keys 353 (PSK), raw public keys (RPK), or public key certificates. EDHOC 354 assumes the existence of mechanisms (certification authority, manual 355 distribution, etc.) for binding identities with authentication keys 356 (public or pre-shared). When a public key infrastructure is used, 357 the identity is included in the certificate and bound to the 358 authentication key by trust in the certification authority. When the 359 credential is manually distributed (PSK, RPK, self-signed 360 certificate), the identity and authentication key is distributed out- 361 of-band and bound together by trust in the distribution method. 362 EDHOC with symmetric key authentication is very similar to EDHOC with 363 asymmetric key authentication, the difference being that information 364 is only MACed, not signed. 366 EDHOC allows opaque application data (UAD and PAD) to be sent in the 367 EDHOC messages. Unprotected Application Data (UAD_1, UAD_2) may be 368 sent in message_1 and message_2 and can be e.g. be used to transfer 369 access tokens that are protected outside of EDHOC. Protected 370 application data (PAD_3) may be used to transfer any application data 371 in message_3. 373 Cryptographically, EDHOC does not put requirement on the lower 374 layers. EDHOC is not bound to a particular transport layer, and can 375 be used in environments without IP. It is recommended is to 376 transport the EDHOC message in CoAP payloads, see Section 7. An 377 implementation may support only Party U or only Party V. 379 3.1. Cipher Suites 381 EDHOC cipher suites consists of a set of COSE algorithms: an AEAD 382 algorithm, an ECDH algorithm (including HKDF algorithm), an ECDH 383 curve, and a signature algorithm. The signature algorithm is not 384 used when EDHOC is authenticated with symmetric keys. Each cipher 385 suite is associated with an integer value. Currently two cipher 386 suites are defined. 388 0. AES-CCM-64-64-128, ECDH-SS + HKDF-256, X25519, and Ed25519 389 1. AES-CCM-64-64-128, ECDH-SS + HKDF-256, P-256, and ES256 391 Two additional numbers are registered for application defined cipher 392 suites. Application defined cipher suites MUST only use algorithms 393 specified for COSE, are not interoperable with other deployments and 394 can therefore only be used in local networks. 396 -24. First application defined cipher suite. 397 -23. Second application defined cipher suite. 399 3.2. Ephemeral Public Keys 401 The ECDH ephemeral public keys are formatted as a COSE_Key of type 402 EC2 or OKP according to Sections 13.1 and 13.2 of [RFC8152], but only 403 a subset of the parameters is included in the EDHOC messages. For 404 Elliptic Curve Keys of type EC2, compact representation as per 405 [RFC6090] MAY be used also in the COSE_Key. If the COSE 406 implementation requires an y-coordinate, any of the possible values 407 of the y-coordinate can be used, see Appendix C of [RFC6090]. COSE 408 [RFC8152] always use compact output for Elliptic Curve Keys of type 409 EC2. 411 3.3. Key Derivation 413 Key and IV derivation SHALL be performed as specified in Section 11 414 of [RFC8152] with the following input: 416 o The KDF SHALL be the HKDF [RFC5869] in the in the selected cipher 417 suite (SUITE). 419 o The secret (Section 11.1 of [RFC8152]) SHALL be the ECDH shared 420 secret as defined in Section 12.4.1 of [RFC8152]. 422 o The salt (Section 11.1 of [RFC8152]) SHALL be the PSK when EDHOC 423 is authenticated with symmetric keys, and the empty byte string 424 when EDHOC is authenticated with asymmetric keys. Note that 425 [RFC5869] specifies that if the salt is not provided, it is set to 426 a string of zeros (see Section 2.2 of [RFC5869]). For 427 implementation purposes, not providing the salt is the same as 428 setting the salt to the empty byte string. 430 o The fields in the context information COSE_KDF_Context 431 (Section 11.2 of [RFC8152]) SHALL have the following values: 433 * AlgorithmID is an int or tstr, see below 435 * PartyUInfo = PartyVInfo = ( null, null, null ) 437 * keyDataLength is a uint, see below 439 * protected SHALL be a zero length bstr 441 * other is a bstr and SHALL be aad_2, aad_3, or exchange_hash; 442 see below 444 * SuppPrivInfo is omitted 446 where exchange_hash, in non-CDDL notation, is: 448 exchange_hash = H( bstr .cborseq [ aad_3, CIPHERTEXT_3 ] ) 450 and where aad_2 and aad_3 are hashes of previous messages and data, 451 defined in Sections 4.3.1 and 4.4.1. H() is the hash function in the 452 HKDF, which takes a CBOR byte string (bstr) as input and produces a 453 CBOR byte string as output. The use of '.cborseq' is exemplified in 454 Appendix A.1. 456 We define EDHOC-Key-Derivation to be the function which produces the 457 output as described in [RFC5869] and [RFC8152] depending on the 458 variable input AlgorithmID, keyDataLength, and other: 460 output = EDHOC-Key-Derivation(AlgorithmID, keyDataLength, other) 462 For message_i the key, called K_i, SHALL be derived using other = 463 aad_i, where i = 2 or 3. The key SHALL be derived using AlgorithmID 464 set to the integer value of the AEAD in the selected cipher suite 465 (SUITE), and keyDataLength equal to the key length of the AEAD. 467 If the AEAD algorithm uses an IV, then IV_i for message_i SHALL be 468 derived using other = aad_i, where i = 2 or 3. The IV SHALL be 469 derived using AlgorithmID = "IV-GENERATION" as specified in 470 Section 12.1.2. of [RFC8152], and keyDataLength equal to the IV 471 length of the AEAD. 473 3.3.1. EDHOC-Exporter Interface 475 Application keys and other application specific data can be derived 476 using the EDHOC-Exporter interface defined as: 478 EDHOC-Exporter(label, length) = 479 EDHOC-Key-Derivation(label, 8 * length, exchange_hash) 481 The output of the EDHOC-Exporter function SHALL be derived using 482 other = exchange_hash, AlgorithmID = label, and keyDataLength = 8 * 483 length, where label is a tstr defined by the application and length 484 is a uint defined by the application. The label SHALL be different 485 for each different exporter value. An example use of the EDHOC- 486 Exporter is given in Section 7.1.1). 488 3.3.2. EDHOC PSK Chaining 490 An application using EDHOC may want to derive new PSKs to use for 491 authentication in future EDHOC exchanges. In this case, the new PSK 492 and KID SHOULD be derived as follows where length is the key length 493 (in bytes) of the AEAD Algorithm. 495 PSK = EDHOC-Exporter("EDHOC Chaining PSK", length) 496 KID = EDHOC-Exporter("EDHOC Chaining KID", 4) 498 4. EDHOC Authenticated with Asymmetric Keys 500 4.1. Overview 502 EDHOC supports authentication with raw public keys (RPK) and public 503 key certificates with the requirements that: 505 o Party U SHALL be able to retrieve Party V's public authentication 506 key using ID_CRED_V, 508 o Party V SHALL be able to retrieve Party U's public authentication 509 key using ID_CRED_U, 511 where ID_CRED_x, for x = U or V, is encoded in a COSE map, see 512 Appendix A.2. In the following we give some examples of possible 513 COSE map labels. 515 Raw public keys are most optimally stored as COSE_Key objects and 516 identified with a 'kid' value (see [RFC8152]): 518 o kid : ID_CRED_x, for x = U or V. 520 Public key certificates can be identified in different ways, for 521 example (see [I-D.schaad-cose-x509]): 523 o by a hash value; 525 * x5t : ID_CRED_x, for x = U or V, 527 o by a URL; 529 * x5u : ID_CRED_x, for x = U or V, 531 o by a certificate chain; 533 * x5chain : ID_CRED_x, for x = U or V, 535 o or by a bag of certificates. 537 * x5bag : ID_CRED_x, for x = U or V. 539 In the latter two examples, ID_CRED_U and ID_CRED_V contains the 540 actual credential used for authentication. ID_CRED_U and ID_CRED_V 541 do not need to uniquely identify the public authentication key, but 542 doing so is recommended as the recipient may otherwise have to try 543 several public keys. ID_CRED_U and ID_CRED_V are transported in the 544 ciphertext, see Section 4.3.2 and Section 4.4.2. 546 The actual credentials CRED_U and CRED_V (e.g. a COSE_Key or a single 547 X.509 certificate) are signed by party U and V, respectively, see 548 Section 4.4.1 and Section 4.3.1. Party U and Party V MAY use 549 different type of credentials, e.g. one uses RPK and the other uses 550 certificate. 552 EDHOC with asymmetric key authentication is illustrated in Figure 3. 554 Party U Party V 555 | TYPE, C_U, SUITES_U, SUITE, X_U, UAD_1 | 556 +------------------------------------------------------------------>| 557 | message_1 | 558 | | 559 | C_U, C_V, X_V, AEAD(K_2; ID_CRED_V, Sig(V; CRED_V, aad_2), UAD_2) | 560 |<------------------------------------------------------------------+ 561 | message_2 | 562 | | 563 | C_V, AEAD(K_3; ID_CRED_U, Sig(U; CRED_U, aad_3), PAD_3) | 564 +------------------------------------------------------------------>| 565 | message_3 | 567 Figure 3: Overview of EDHOC with asymmetric key authentication. 569 4.2. EDHOC Message 1 571 4.2.1. Formatting of Message 1 573 message_1 SHALL be a sequence of CBOR data items (see Appendix A.1) 574 as defined below 576 message_1 = ( 577 TYPE : int, 578 C_U : bstr, 579 SUITES_U : suites, 580 SUITE : uint, 581 X_U : bstr, 582 ? UAD_1 : bstr, 583 ) 585 suites : int / [ 2* int ] 587 where: 589 o TYPE = 1 591 o C_U - variable length connection identifier 593 o SUITES_U - cipher suites which Party U supports, in order of 594 decreasing preference. If a single cipher suite is conveyed, an 595 int is used, if multiple cipher suites are conveyed, an array of 596 ints is used. 598 o SUITE - a single chosen cipher suite from SUITES_U (zero-based 599 index, i.e. 0 for the first or only, 1 for the second, etc.) 601 o X_U - the x-coordinate of the ephemeral public key of Party U 603 o UAD_1 - bstr containing unprotected opaque application data 605 4.2.2. Party U Processing of Message 1 607 Party U SHALL compose message_1 as follows: 609 o The supported cipher suites and the order of preference MUST NOT 610 be changed based on previous error messages. However, the list 611 SUITES_U sent to Party V MAY be truncated such that cipher suites 612 which are the least preferred are omitted. The amount of 613 truncation MAY be changed between sessions, e.g. based on previous 614 error messages (see next bullet), but all cipher suites which are 615 more preferred than the least preferred cipher suite in the list 616 MUST be included in the list. 618 o Determine the cipher suite SUITE to use with Party V in message_1. 619 If Party U previously received from Party V an error message to 620 message_1 with diagnostic payload identifying a cipher suite that 621 U supports, then U SHALL use that cipher suite. Otherwise the 622 first cipher suite in SUITES_U MUST be used. 624 o Generate an ephemeral ECDH key pair as specified in Section 5 of 625 [SP-800-56A] using the curve in the cipher suite SUITE. Let X_U 626 be the x-coordinate of the ephemeral public key. 628 o Choose a connection identifier C_U and store it for the length of 629 the protocol. Party U MUST be able to retrieve the protocol state 630 using the connection identifier C_U and optionally other 631 information such as the 5-tuple. The connection identifier MAY be 632 used with a protocol for which EDHOC establishes application keys, 633 in which case C_U SHALL adhere to the requirements for that 634 protocol. 636 o Format message_1 as the sequence of CBOR data items specified in 637 Section 4.2.1 and encode it to a byte string (see Appendix A.1). 639 4.2.3. Party V Processing of Message 1 641 Party V SHALL process message_1 as follows: 643 o Decode message_1 (see Appendix A.1). 645 o Verify that the cipher suite SUITE is supported and that no prior 646 cipher suites in SUITES_U are supported. 648 o Validate that there is a solution to the curve definition for the 649 given x-coordinate X_U. 651 o Pass UAD_1 to the application. 653 If any verification step fails, Party V MUST send an EDHOC error 654 message back, formatted as defined in Section 6, and the protocol 655 MUST be discontinued. If V does not support the cipher suite SUITE, 656 then SUITES_V MUST include one or more supported cipher suites. If V 657 does not support the cipher suite SUITE, but supports another cipher 658 suite in SUITES_U, then SUITES_V MUST include the first supported 659 cipher suite in SUITES_U. 661 4.3. EDHOC Message 2 662 4.3.1. Formatting of Message 2 664 message_2 SHALL be a sequence of CBOR data items (see Appendix A.1) 665 as defined below 667 message_2 = ( 668 data_2, 669 CIPHERTEXT_2 : bstr, 670 ) 672 data_2 = ( 673 C_U : bstr / nil, 674 C_V : bstr, 675 X_V : bstr, 676 ) 678 aad_2 : bstr 680 where aad_2, in non-CDDL notation, is: 682 aad_2 = H( bstr .cborseq [ message_1, data_2 ] ) 684 where: 686 o C_V - variable length connection identifier 688 o X_V - the x-coordinate of the ephemeral public key of Party V 690 o H() - the hash function in the HKDF, which takes a CBOR byte 691 string (bstr) as input and produces a CBOR byte string as output. 692 The use of '.cborseq' is exemplified in Appendix A.1. 694 4.3.2. Party V Processing of Message 2 696 Party V SHALL compose message_2 as follows: 698 o Generate an ephemeral ECDH key pair as specified in Section 5 of 699 [SP-800-56A] using the curve in the cipher suite SUITE. Let X_V 700 be the x-coordinate of the ephemeral public key. 702 o Choose a connection identifier C_V and store it for the length of 703 the protocol. Party V MUST be able to retrieve the protocol state 704 using the connection identifier C_V and optionally other 705 information such as the 5-tuple. The connection identifier MAY be 706 used with a protocol for which EDHOC establishes application keys, 707 in which case C_V SHALL adhere to the requirements for that 708 protocol. To reduce message overhead, party V can set the message 709 field C_U in message_2 to null (still storing the actual value of 710 C_U) if there is an external correlation mechanism (e.g. the Token 711 in CoAP) that enables Party U to correlate message_1 and 712 message_2. 714 o Compute COSE_Sign1 as defined in Section 4.4 of [RFC8152], using 715 the signature algorithm in the cipher suite SUITE, the private 716 authentication key of Party V, and the following parameters 717 (further clarifications in Appendix A.2.2). The unprotected 718 header MAY contain parameters (e.g. 'alg'). 720 * protected = bstr .cbor { abc : ID_CRED_V } 722 * payload = CRED_V 724 * external_aad = aad_2 726 * abc - any COSE map label that can identify a public 727 authentication key, see Section 4.1 729 * ID_CRED_V - a CBOR type that can be used with the COSE map 730 label. Enables the retrieval of the public authentication key 731 of Party V, see Section 4.1 733 * CRED_V - bstr credential containing the public authentication 734 key of Party V, see Section 4.1 736 Note that only 'protected' and 'signature' of the COSE_Sign1 737 object are used in message_2, see next bullet. 739 o Compute COSE_Encrypt0 as defined in Section 5.3 of [RFC8152], with 740 the AEAD algorithm in the cipher suite SUITE, K_2, IV_2, and the 741 following parameters (further clarifications in Appendix A.2.2). 742 The protected header SHALL be empty. The unprotected header MAY 743 contain parameters (e.g. 'alg'). 745 * plaintext = bstr .cborseq [ ~protected, signature, ? UAD_2 ] 747 * external_aad = aad_2 749 * UAD_2 = bstr containing opaque unprotected application data 751 Note that protected and signature in the plaintext are taken from 752 the COSE_Sign1 object, and that that only 'ciphertext' of the 753 COSE_Encrypt0 object are used in message_2, see next bullet. 755 o Format message_2 as the sequence of CBOR data items specified in 756 Section 4.3.1 and encode it to a byte string (see Appendix A.1). 757 CIPHERTEXT_2 is the COSE_Encrypt0 ciphertext. 759 4.3.3. Party U Processing of Message 2 761 Party U SHALL process message_2 as follows: 763 o Decode message_2 (see Appendix A.1). 765 o Retrieve the protocol state using the connection identifier C_U 766 and optionally other information such as the 5-tuple. 768 o Validate that there is a solution to the curve definition for the 769 given x-coordinate X_V. 771 o Decrypt and verify COSE_Encrypt0 as defined in Section 5.3 of 772 [RFC8152], with the AEAD algorithm in the cipher suite SUITE, K_2, 773 and IV_2. 775 o Verify COSE_Sign1 as defined in Section 4.4 of [RFC8152], using 776 the signature algorithm in the cipher suite SUITE and the public 777 authentication key of Party V. 779 If any verification step fails, Party U MUST send an EDHOC error 780 message back, formatted as defined in Section 6, and the protocol 781 MUST be discontinued. 783 4.4. EDHOC Message 3 785 4.4.1. Formatting of Message 3 787 message_3 SHALL be a sequence of CBOR data items (see Appendix A.1) 788 as defined below 790 message_3 = ( 791 data_3, 792 CIPHERTEXT_3 : bstr, 793 ) 795 data_3 = ( 796 C_V : bstr / nil, 797 ) 799 aad_3 : bstr 801 where aad_3, in non-CDDL notation, is: 803 aad_3 = H( bstr .cborseq [ aad_2, CIPHERTEXT_2, data_3 ] ) 805 4.4.2. Party U Processing of Message 3 807 Party U SHALL compose message_3 as follows: 809 o To reduce message overhead, party U can set the message field C_V 810 in message_3 to null (still storing the actual value of C_V) if 811 there is an external correlation mechanism (e.g. the Token in 812 CoAP) that enables Party V to correlate message_2 and message_3. 814 o Compute COSE_Sign1 as defined in Section 4.4 of [RFC8152], using 815 the signature algorithm in the cipher suite SUITE, the private 816 authentication key of Party U, and the following parameters. The 817 unprotected header MAY contain parameters (e.g. 'alg'). 819 * protected = bstr .cbor { abc : ID_CRED_U } 821 * payload = CRED_U 823 * external_aad = aad_3 825 * abc - any COSE map label that can identify a public 826 authentication key, see Section 4.1 828 * ID_CRED_U - a CBOR type that can be used with the COSE map 829 label. Enables the retrieval of the public authentication key 830 of Party U, see Section 4.1 832 * CRED_U - bstr credential containing the public authentication 833 key of Party U, see Section 4.1 835 Note that only 'protected' and 'signature' of the COSE_Sign1 836 object are used in message_3, see next bullet. 838 o Compute COSE_Encrypt0 as defined in Section 5.3 of [RFC8152], with 839 the AEAD algorithm in the cipher suite SUITE, K_3, and IV_3 and 840 the following parameters. The protected header SHALL be empty. 841 The unprotected header MAY contain parameters (e.g. 'alg'). 843 * plaintext = bstr .cborseq [ ~protected, signature, ? PAD_3 ] 845 * external_aad = aad_3 847 * PAD_3 = bstr containing opaque protected application data 849 Note that protected and signature in the plaintext are taken from 850 the COSE_Sign1 object, and that only 'ciphertext' of the 851 COSE_Encrypt0 object are used in message_3, see next bullet. 853 o Format message_3 as the sequence of CBOR data items specified in 854 Section 4.4.1 and encode it to a byte string (see Appendix A.1). 855 CIPHERTEXT_3 is the COSE_Encrypt0 ciphertext. 857 o Pass the connection identifiers (C_U, C_V) and the negotiated 858 cipher suite SUITE to the application. The application can now 859 derive application keys using the EDHOC-Exporter interface. 861 4.4.3. Party V Processing of Message 3 863 Party V SHALL process message_3 as follows: 865 o Decode message_3 (see Appendix A.1). 867 o Retrieve the protocol state using the connection identifier C_V 868 and optionally other information such as the 5-tuple. 870 o Decrypt and verify COSE_Encrypt0 as defined in Section 5.3 of 871 [RFC8152], with the AEAD algorithm in the cipher suite SUITE, K_3, 872 and IV_3. 874 o Verify COSE_Sign1 as defined in Section 4.4 of [RFC8152], using 875 the signature algorithm in the cipher suite SUITE and the public 876 authentication key of Party U. 878 If any verification step fails, Party V MUST send an EDHOC error 879 message back, formatted as defined in Section 6, and the protocol 880 MUST be discontinued. 882 o Pass PAD_3, the connection identifiers (C_U, C_V), and the 883 negotiated cipher suite SUITE to the application. The application 884 can now derive application keys using the EDHOC-Exporter 885 interface. 887 5. EDHOC Authenticated with Symmetric Keys 889 5.1. Overview 891 EDHOC supports authentication with pre-shared keys. Party U and V 892 are assumed to have a pre-shared key (PSK) with a good amount of 893 randomness and the requirement that: 895 o Party V SHALL be able to retrieve the PSK using KID. 897 KID may optionally contain information about how to retrieve the PSK. 898 KID does not need to uniquely identify the PSK, but doing so is 899 recommended as the recipient may otherwise have to try several PSKs. 901 EDHOC with symmetric key authentication is illustrated in Figure 4. 903 Party U Party V 904 | TYPE, C_U, SUITES_U, SUITE, X_U, KID, UAD_1 | 905 +------------------------------------------------------------------>| 906 | message_1 | 907 | | 908 | C_U, C_V, X_V, AEAD(K_2; aad_2, UAD_2) | 909 |<------------------------------------------------------------------+ 910 | message_2 | 911 | | 912 | C_V, AEAD(K_3; aad_3, PAD_3) | 913 +------------------------------------------------------------------>| 914 | message_3 | 916 Figure 4: Overview of EDHOC with symmetric key authentication. 918 EDHOC with symmetric key authentication is very similar to EDHOC with 919 asymmetric key authentication. In the following subsections the 920 differences compared to EDHOC with asymmetric key authentication are 921 described. 923 5.2. EDHOC Message 1 925 5.2.1. Formatting of Message 1 927 message_1 SHALL be a sequence of CBOR data items (see Appendix A.1) 928 as defined below 930 message_1 = ( 931 TYPE : int, 932 C_U : bstr, 933 SUITES_U : suites, 934 SUITE : uint, 935 X_U : bstr, 936 KID : bstr, 937 ? UAD_1 : bstr, 938 ) 940 where: 942 o TYPE = 2 944 o KID - bstr enabling the retrieval of the pre-shared key 946 5.3. EDHOC Message 2 948 5.3.1. Processing of Message 2 950 o COSE_Sign1 is not used. 952 o COSE_Encrypt0 is computed as defined in Section 5.3 of [RFC8152], 953 with the AEAD algorithm in the cipher suite SUITE, K_2, IV_2, and 954 the following parameters. The protected header SHALL be empty. 955 The unprotected header MAY contain parameters (e.g. 'alg'). 957 * external_aad = aad_2 959 * plaintext = h'' / UAD_2 961 * UAD_2 = bstr containing opaque unprotected application data 963 5.4. EDHOC Message 3 965 5.4.1. Processing of Message 3 967 o COSE_Sign1 is not used. 969 o COSE_Encrypt0 is computed as defined in Section 5.3 of [RFC8152], 970 with the AEAD algorithm in the cipher suite SUITE, K_3, IV_3, and 971 the following parameters. The protected header SHALL be empty. 972 The unprotected header MAY contain parameters (e.g. 'alg'). 974 * external_aad = aad_3 976 * plaintext = h'' / PAD_3 978 * PAD_3 = bstr containing opaque protected application data 980 6. Error Handling 982 6.1. EDHOC Error Message 984 This section defines a message format for the EDHOC error message, 985 used during the protocol. An EDHOC error message can be send by both 986 parties as a response to any non-error EDHOC message. After sending 987 an error message, the protocol MUST be discontinued. Errors at the 988 EDHOC layer are sent as normal successful messages in the lower 989 layers (e.g. CoAP POST and 2.04 Changed). An advantage of using 990 such a construction is to avoid issues created by usage of cross 991 protocol proxies (e.g. UDP to TCP). 993 error SHALL be a sequence of CBOR data items (see Appendix A.1) as 994 defined below 996 error = ( 997 TYPE : int, 998 ERR_MSG : tstr, 999 ? SUITES_V : suites, 1000 ) 1002 suites : int / [ 2* int ] 1004 where: 1006 o TYPE = 0 1008 o ERR_MSG - text string containing the diagnostic payload, defined 1009 in the same way as in Section 5.5.2 of [RFC7252] 1011 o SUITES_V - cipher suites from SUITES_U or the EDHOC cipher suites 1012 registry that V supports. Note that SUITEs_V contains the values 1013 from the EDHOC cipher suites registry and not indexes. 1015 6.1.1. Example Use of EDHOC Error Message with SUITES_V 1017 Assuming that Party U supports the five cipher suites {0, 1, 2, 3, 4} 1018 in decreasing order of preference, Figures 5 and 6 show examples of 1019 how Party U can truncate SUITES_U and how SUITES_V is used by Party V 1020 to give Party U information about the cipher suites that Party V 1021 supports. In Figure 5, Party V supports cipher suite 1 but not 1022 cipher suite 0. 1024 Party U Party V 1025 | TYPE, C_U, SUITES_U {0, 1, 2}, SUITE {0}, X_U, UAD_1 | 1026 +------------------------------------------------------------------>| 1027 | message_1 | 1028 | | 1029 | TYPE, ERR_MSG, SUITES_V {1} | 1030 |<------------------------------------------------------------------+ 1031 | error | 1032 | | 1033 | TYPE, C_U, SUITES_U {0, 1}, SUITE {1}, X_U, UAD_1 | 1034 +------------------------------------------------------------------>| 1035 | message_1 | 1037 Figure 5: Example use of error message with SUITES_V. 1039 In Figure 6, Party V supports cipher suite 2 but not cipher suites 0 1040 and 1. 1042 Party U Party V 1043 | TYPE, C_U, SUITES_U {0, 1}, SUITE {0}, X_U, UAD_1 | 1044 +------------------------------------------------------------------>| 1045 | message_1 | 1046 | | 1047 | TYPE, ERR_MSG, SUITES_V {2, 4} | 1048 |<------------------------------------------------------------------+ 1049 | error | 1050 | | 1051 | TYPE, C_U, SUITES_U {0, 1, 2}, SUITE {2}, X_U, UAD_1 | 1052 +------------------------------------------------------------------>| 1053 | message_1 | 1055 Figure 6: Example use of error message with SUITES_V. 1057 As Party U's list of supported cipher suites and order of preference 1058 is fixed, and Party V only accepts message_1 if the selected cipher 1059 suite SUITE is the first cipher suite in SUITES_U that Party V 1060 supports, the parties can verify that the selected cipher suite SUITE 1061 is the most preferred (by Party U) cipher suite supported by both 1062 parties. If SUITE is not the first cipher suite in SUITES_U that 1063 Party V supports, Party V will discontinue the protocol. 1065 7. Transferring EDHOC and Deriving Application Keys 1067 7.1. Transferring EDHOC in CoAP 1069 It is recommended is to transport EDHOC as an exchange of CoAP 1070 [RFC7252] messages. CoAP is a reliable transport that can preserve 1071 packet ordering and handle message duplication. CoAP can also 1072 perform fragmentation and protect against denial of service attacks. 1073 It is recommended to carry the EDHOC flights in Confirmable messages, 1074 especially if fragmentation is used. 1076 By default, the CoAP client is Party U and the CoAP server is Party 1077 V, but the roles SHOULD be chosen to protect the most sensitive 1078 identity, see Section 9. By default, EDHOC is transferred in POST 1079 requests and 2.04 (Changed) responses to the Uri-Path: "/.well-known/ 1080 edhoc", but an application may define its own path that can be 1081 discovered e.g. using resource directory 1082 [I-D.ietf-core-resource-directory]. 1084 By default, the message flow is as follows: EDHOC message_1 is sent 1085 in the payload of a POST request from the client to the server's 1086 resource for EDHOC. EDHOC message_2 or the EDHOC error message is 1087 sent from the server to the client in the payload of a 2.04 (Changed) 1088 response. EDHOC message_3 or the EDHOC error message is sent from 1089 the client to the server's resource in the payload of a POST request. 1091 If needed, an EDHOC error message is sent from the server to the 1092 client in the payload of a 2.04 (Changed) response. 1094 An example of a successful EDHOC exchange using CoAP is shown in 1095 Figure 7. 1097 Client Server 1098 | | 1099 +--------->| Header: POST (Code=0.02) 1100 | POST | Uri-Path: "/.well-known/edhoc" 1101 | | Content-Format: application/edhoc 1102 | | Payload: EDHOC message_1 1103 | | 1104 |<---------+ Header: 2.04 Changed 1105 | 2.04 | Content-Format: application/edhoc 1106 | | Payload: EDHOC message_2 1107 | | 1108 +--------->| Header: POST (Code=0.02) 1109 | POST | Uri-Path: "/.well-known/edhoc" 1110 | | Content-Format: application/edhoc 1111 | | Payload: EDHOC message_3 1112 | | 1113 |<---------+ Header: 2.04 Changed 1114 | 2.04 | 1115 | | 1117 Figure 7: Transferring EDHOC in CoAP 1119 The exchange in Figure 7 protects the client identity against active 1120 attackers and the server identity against passive attackers. An 1121 alternative exchange that protects the server identity against active 1122 attackers and the client identity against passive attackers is shown 1123 in Figure 8. 1125 Client Server 1126 | | 1127 +--------->| Header: POST (Code=0.02) 1128 | POST | Uri-Path: "/.well-known/edhoc" 1129 | | 1130 |<---------+ Header: 2.04 Changed 1131 | 2.04 | Content-Format: application/edhoc 1132 | | Payload: EDHOC message_1 1133 | | 1134 +--------->| Header: POST (Code=0.02) 1135 | POST | Uri-Path: "/.well-known/edhoc" 1136 | | Content-Format: application/edhoc 1137 | | Payload: EDHOC message_2 1138 | | 1139 |<---------+ Header: 2.04 Changed 1140 | 2.04 | Content-Format: application/edhoc 1141 | | Payload: EDHOC message_3 1142 | | 1144 Figure 8: Transferring EDHOC in CoAP 1146 To protect against denial-of-service attacks, the CoAP server MAY 1147 respond to the first POST request with a 4.01 (Unauthorized) 1148 containing an Echo option [I-D.ietf-core-echo-request-tag]. This 1149 forces the initiator to demonstrate its reachability at its apparent 1150 network address. If message fragmentation is needed, the EDHOC 1151 messages may be fragmented using the CoAP Block-Wise Transfer 1152 mechanism [RFC7959]. 1154 7.1.1. Deriving an OSCORE Context from EDHOC 1156 When EDHOC is used to derive parameters for OSCORE 1157 [I-D.ietf-core-object-security], the parties must make sure that the 1158 EDHOC connection identifiers are unique, i.e. C_V MUST NOT be equal 1159 to C_U. The CoAP client and server MUST be able to retrieve the 1160 OCORE protocol state using its chosen connection identifier and 1161 optionally other information such as the 5-tuple. In case that the 1162 CoAP client is party U and the CoAP server is party V: 1164 o The client's OSCORE Sender ID is C_V and the server's OSCORE 1165 Sender ID is C_U, as defined in this document 1167 o The AEAD Algorithm and the HMAC-based Key Derivation Function 1168 (HKDF) are the AEAD and HKDF algorithms in the cipher suite SUITE. 1170 o The Master Secret and Master Salt are derived as follows where 1171 length is the key length (in bytes) of the AEAD Algorithm. 1173 Master Secret = EDHOC-Exporter("OSCORE Master Secret", length) 1174 Master Salt = EDHOC-Exporter("OSCORE Master Salt", 8) 1176 7.2. Transferring EDHOC over Other Protocols 1178 EDHOC may be transported over a different transport than CoAP. In 1179 this case the lower layers need to handle message loss, reordering, 1180 message duplication, fragmentation, and denial of service protection. 1182 8. IANA Considerations 1184 8.1. EDHOC Cipher Suites Registry 1186 IANA has created a new registry titled "EDHOC Cipher Suites". 1188 TODO 1190 8.2. EDHOC Method Type Registry 1192 IANA has created a new registry titled "EDHOC Method Type". 1194 TODO 1196 8.3. The Well-Known URI Registry 1198 IANA has added the well-known URI 'edhoc' to the Well-Known URIs 1199 registry. 1201 o URI suffix: edhoc 1203 o Change controller: IETF 1205 o Specification document(s): [[this document]] 1207 o Related information: None 1209 8.4. Media Types Registry 1211 IANA has added the media type 'application/edhoc' to the Media Types 1212 registry. 1214 o Type name: application 1216 o Subtype name: edhoc 1218 o Required parameters: N/A 1220 o Optional parameters: N/A 1221 o Encoding considerations: binary 1223 o Security considerations: See Section 7 of this document. 1225 o Interoperability considerations: N/A 1227 o Published specification: [[this document]] (this document) 1229 o Applications that use this media type: To be identified 1231 o Fragment identifier considerations: N/A 1233 o Additional information: 1235 * Magic number(s): N/A 1237 * File extension(s): N/A 1239 * Macintosh file type code(s): N/A 1241 o Person & email address to contact for further information: See 1242 "Authors' Addresses" section. 1244 o Intended usage: COMMON 1246 o Restrictions on usage: N/A 1248 o Author: See "Authors' Addresses" section. 1250 o Change Controller: IESG 1252 8.5. CoAP Content-Formats Registry 1254 IANA has added the media type 'application/edhoc' to the CoAP 1255 Content-Formats registry. 1257 o Media Type: application/edhoc 1259 o Encoding: 1261 o ID: TBD42 1263 o Reference: [[this document]] 1265 9. Security Considerations 1267 9.1. Security Properties 1269 EDHOC inherits its security properties from the theoretical SIGMA-I 1270 protocol [SIGMA]. Using the terminology from [SIGMA], EDHOC provides 1271 perfect forward secrecy, mutual authentication with aliveness, 1272 consistency, peer awareness, and identity protection. As described 1273 in [SIGMA], peer awareness is provided to Party V, but not to Party 1274 U. 1276 EDHOC with asymmetric authentication offers identity protection of 1277 Party U against active attacks and identity protection of Party V 1278 against passive attacks. The roles should be assigned to protect the 1279 most sensitive identity, typically that which is not possible to 1280 infer from routing information in the lower layers. 1282 Compared to [SIGMA], EDHOC adds an explicit method type and expands 1283 the message authentication coverage to additional elements such as 1284 algorithms, application data, and previous messages. This protects 1285 against an attacker replaying messages or injecting messages from 1286 another session. 1288 EDHOC also adds negotiation of connection identifiers and downgrade 1289 protected negotiation of cryptographic parameters, i.e. an attacker 1290 cannot affect the negotiated parameters. A single session of EDHOC 1291 does not include negotiation of cipher suites, but it enables Party V 1292 to verify that the selected cipher suite is the most preferred cipher 1293 suite by U which is supported by both U and V. 1295 As required by [RFC7258], IETF protocols need to mitigate pervasive 1296 monitoring when possible. One way to mitigate pervasive monitoring 1297 is to use a key exchange that provides perfect forward secrecy. 1298 EDHOC therefore only supports methods with perfect forward secrecy. 1299 To limit the effect of breaches, it is important to limit the use of 1300 symmetrical group keys for bootstrapping. EDHOC therefore strives to 1301 make the additional cost of using raw-public keys and self-signed 1302 certificates as small as possible. Raw-public keys and self-signed 1303 certificates are not a replacement for a public key infrastructure, 1304 but SHOULD be used instead of symmetrical group keys for 1305 bootstrapping. 1307 9.2. Cryptographic Considerations 1309 The security of the SIGMA protocol requires the MAC to be bound to 1310 the identity of the signer. Hence the message authenticating 1311 functionality of the authenticated encryption in EDHOC is critical: 1312 authenticated encryption MUST NOT be replaced by plain encryption 1313 only, even if authentication is provided at another level or through 1314 a different mechanism. EDHOC implements SIGMA-I using the same Sign- 1315 then-MAC approach as TLS 1.3. 1317 To reduce message overhead EDHOC does not use explicit nonces and 1318 instead rely on the ephemeral public keys to provide randomness to 1319 each session. A good amount of randomness is important for the key 1320 generation, to provide aliveness, and to protect against interleaving 1321 attacks. For this reason, the ephemeral keys MUST NOT be reused, and 1322 both parties SHALL generate fresh random ephemeral key pairs. 1324 The choice of key length used in the different algorithms needs to be 1325 harmonized, so that a sufficient security level is maintained for 1326 certificates, EDHOC, and the protection of application data. Party U 1327 and V should enforce a minimum security level. 1329 The data rates in many IoT deployments are very limited. Given that 1330 the application keys are protected as well as the long-term 1331 authentication keys they can often be used for years or even decades 1332 before the cryptographic limits are reached. If the application keys 1333 established through EDHOC need to be renewed, the communicating 1334 parties can derive application keys with other labels or run EDHOC 1335 again. 1337 9.3. Mandatory to Implement Cipher Suite 1339 Cipher suite number 1 (AES-CCM-64-64-128, ECDH-SS + HKDF-256, X25519, 1340 Ed25519) is mandatory to implement. For many constrained IoT devices 1341 it is problematic to support more than one cipher suites, so some 1342 deployments with P-256 may not support the mandatory cipher suite. 1343 This is not a problem for local deployments. 1345 9.4. Unprotected Data 1347 Party U and V must make sure that unprotected data and metadata do 1348 not reveal any sensitive information. This also applies for 1349 encrypted data sent to an unauthenticated party. In particular, it 1350 applies to UAD_1, ID_CRED_V, UAD_2, and ERR_MSG in the asymmetric 1351 case, and KID, UAD_1, and ERR_MSG in the symmetric case. Using the 1352 same KID or UAD_1 in several EDHOC sessions allows passive 1353 eavesdroppers to correlate the different sessions. The communicating 1354 parties may therefore anonymize KID. Another consideration is that 1355 the list of supported cipher suites may be used to identify the 1356 application. 1358 Party U and V must also make sure that unauthenticated data does not 1359 trigger any harmful actions. In particular, this applies to UAD_1 1360 and ERR_MSG in the asymmetric case, and KID, UAD_1, and ERR_MSG in 1361 the symmetric case. 1363 9.5. Denial-of-Service 1365 EDHOC itself does not provide countermeasures against Denial-of- 1366 Service attacks. By sending a number of new or replayed message_1 an 1367 attacker may cause Party V to allocate state, perform cryptographic 1368 operations, and amplify messages. To mitigate such attacks, an 1369 implementation SHOULD rely on lower layer mechanisms such as the Echo 1370 option in CoAP [I-D.ietf-core-echo-request-tag] that forces the 1371 initiator to demonstrate reachability at its apparent network 1372 address. 1374 9.6. Implementation Considerations 1376 The availability of a secure pseudorandom number generator and truly 1377 random seeds are essential for the security of EDHOC. If no true 1378 random number generator is available, a truly random seed must be 1379 provided from an external source. If ECDSA is supported, 1380 "deterministic ECDSA" as specified in [RFC6979] is RECOMMENDED. 1382 The referenced processing instructions in [SP-800-56A] must be 1383 complied with, including deleting the intermediate computed values 1384 along with any ephemeral ECDH secrets after the key derivation is 1385 completed. The ECDH shared secret, keys (K_2, K_3), and IVs (IV_2, 1386 IV_3) MUST be secret. Implementations should provide countermeasures 1387 to side-channel attacks such as timing attacks. 1389 Party U and V are responsible for verifying the integrity of 1390 certificates. The selection of trusted CAs should be done very 1391 carefully and certificate revocation should be supported. The 1392 private authentication keys MUST be kept secret. 1394 Party U and V are allowed to select the connection identifiers C_U 1395 and C_V, respectively, for the other party to use in the ongoing 1396 EDHOC protocol as well as in a subsequent application protocol (e.g. 1397 OSCORE [I-D.ietf-core-object-security]). The choice of connection 1398 identifier is not security critical in EDHOC but intended to simplify 1399 the retrieval of the right security context in combination with using 1400 short identifiers. If the wrong connection identifier of the other 1401 party is used in a protocol message it will result in the receiving 1402 party not being able to retrieve a security context (which will 1403 terminate the protocol) or retrieve the wrong security context (which 1404 also terminates the protocol as the message cannot be verified). 1406 9.7. Other Documents Referencing EDHOC 1408 EDHOC has been analyzed in several other documents. A formal 1409 verification of EDHOC was done in [SSR18], an analysis of EDHOC for 1410 certificate enrollment was done in [Kron18], the use of EDHOC in 1411 LoRaWAN is analyzed in [LoRa1] and [LoRa2], the use of EDHOC in IoT 1412 bootstrapping is analyzed in [Perez18], and the use of EDHOC in 1413 6TiSCH is described in [I-D.ietf-6tisch-dtsecurity-zerotouch-join]. 1415 10. References 1417 10.1. Normative References 1419 [I-D.ietf-cbor-7049bis] 1420 Bormann, C. and P. Hoffman, "Concise Binary Object 1421 Representation (CBOR)", draft-ietf-cbor-7049bis-05 (work 1422 in progress), January 2019. 1424 [I-D.ietf-cbor-cddl] 1425 Birkholz, H., Vigano, C., and C. Bormann, "Concise data 1426 definition language (CDDL): a notational convention to 1427 express CBOR and JSON data structures", draft-ietf-cbor- 1428 cddl-07 (work in progress), February 2019. 1430 [I-D.ietf-core-echo-request-tag] 1431 Amsuess, C., Mattsson, J., and G. Selander, "Echo and 1432 Request-Tag", draft-ietf-core-echo-request-tag-03 (work in 1433 progress), October 2018. 1435 [I-D.ietf-core-object-security] 1436 Selander, G., Mattsson, J., Palombini, F., and L. Seitz, 1437 "Object Security for Constrained RESTful Environments 1438 (OSCORE)", draft-ietf-core-object-security-15 (work in 1439 progress), August 2018. 1441 [I-D.schaad-cose-x509] 1442 Schaad, J., "CBOR Object Signing and Encryption (COSE): 1443 Headers for carrying and referencing X.509 certificates", 1444 draft-schaad-cose-x509-03 (work in progress), December 1445 2018. 1447 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1448 Requirement Levels", BCP 14, RFC 2119, 1449 DOI 10.17487/RFC2119, March 1997, 1450 . 1452 [RFC5116] McGrew, D., "An Interface and Algorithms for Authenticated 1453 Encryption", RFC 5116, DOI 10.17487/RFC5116, January 2008, 1454 . 1456 [RFC5869] Krawczyk, H. and P. Eronen, "HMAC-based Extract-and-Expand 1457 Key Derivation Function (HKDF)", RFC 5869, 1458 DOI 10.17487/RFC5869, May 2010, 1459 . 1461 [RFC6090] McGrew, D., Igoe, K., and M. Salter, "Fundamental Elliptic 1462 Curve Cryptography Algorithms", RFC 6090, 1463 DOI 10.17487/RFC6090, February 2011, 1464 . 1466 [RFC6979] Pornin, T., "Deterministic Usage of the Digital Signature 1467 Algorithm (DSA) and Elliptic Curve Digital Signature 1468 Algorithm (ECDSA)", RFC 6979, DOI 10.17487/RFC6979, August 1469 2013, . 1471 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 1472 Application Protocol (CoAP)", RFC 7252, 1473 DOI 10.17487/RFC7252, June 2014, 1474 . 1476 [RFC7959] Bormann, C. and Z. Shelby, Ed., "Block-Wise Transfers in 1477 the Constrained Application Protocol (CoAP)", RFC 7959, 1478 DOI 10.17487/RFC7959, August 2016, 1479 . 1481 [RFC8152] Schaad, J., "CBOR Object Signing and Encryption (COSE)", 1482 RFC 8152, DOI 10.17487/RFC8152, July 2017, 1483 . 1485 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 1486 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 1487 May 2017, . 1489 [SIGMA] Krawczyk, H., "SIGMA - The 'SIGn-and-MAc' Approach to 1490 Authenticated Diffie-Hellman and Its Use in the IKE- 1491 Protocols (Long version)", June 2003, 1492 . 1494 [SP-800-56A] 1495 Barker, E., Chen, L., Roginsky, A., Vassilev, A., and R. 1496 Davis, "Recommendation for Pair-Wise Key-Establishment 1497 Schemes Using Discrete Logarithm Cryptography", 1498 NIST Special Publication 800-56A Revision 3, April 2018, 1499 . 1501 10.2. Informative References 1503 [CborMe] Bormann, C., "CBOR Playground", May 2018, 1504 . 1506 [I-D.hartke-core-e2e-security-reqs] 1507 Selander, G., Palombini, F., and K. Hartke, "Requirements 1508 for CoAP End-To-End Security", draft-hartke-core-e2e- 1509 security-reqs-03 (work in progress), July 2017. 1511 [I-D.ietf-6tisch-dtsecurity-zerotouch-join] 1512 Richardson, M., "6tisch Zero-Touch Secure Join protocol", 1513 draft-ietf-6tisch-dtsecurity-zerotouch-join-03 (work in 1514 progress), October 2018. 1516 [I-D.ietf-ace-oauth-authz] 1517 Seitz, L., Selander, G., Wahlstroem, E., Erdtman, S., and 1518 H. Tschofenig, "Authentication and Authorization for 1519 Constrained Environments (ACE) using the OAuth 2.0 1520 Framework (ACE-OAuth)", draft-ietf-ace-oauth-authz-21 1521 (work in progress), February 2019. 1523 [I-D.ietf-ace-oscore-profile] 1524 Palombini, F., Seitz, L., Selander, G., and M. Gunnarsson, 1525 "OSCORE profile of the Authentication and Authorization 1526 for Constrained Environments Framework", draft-ietf-ace- 1527 oscore-profile-07 (work in progress), February 2019. 1529 [I-D.ietf-core-resource-directory] 1530 Shelby, Z., Koster, M., Bormann, C., Stok, P., and C. 1531 Amsuess, "CoRE Resource Directory", draft-ietf-core- 1532 resource-directory-19 (work in progress), January 2019. 1534 [I-D.ietf-tls-dtls13] 1535 Rescorla, E., Tschofenig, H., and N. Modadugu, "The 1536 Datagram Transport Layer Security (DTLS) Protocol Version 1537 1.3", draft-ietf-tls-dtls13-30 (work in progress), 1538 November 2018. 1540 [Kron18] Krontiris, A., "Evaluation of Certificate Enrollment over 1541 Application Layer Security", May 2018, 1542 . 1545 [LoRa1] Sanchez-Iborra, R., Sanchez-Gomez, J., Perez, S., 1546 Fernandez, P., Santa, J., Hernandez-Ramos, J., and A. 1547 Skarmeta, "Enhancing LoRaWAN Security through a 1548 Lightweight and Authenticated Key Management Approach", 1549 June 2018, 1550 . 1553 [LoRa2] Sanchez-Iborra, R., Sanchez-Gomez, J., Perez, S., 1554 Fernandez, P., Santa, J., Hernandez-Ramos, J., and A. 1555 Skarmeta, "Internet Access for LoRaWAN Devices Considering 1556 Security Issues", June 2018, 1557 . 1559 [Perez18] Perez, S., Garcia-Carrillo, D., Marin-Lopez, R., 1560 Hernandez-Ramos, J., Marin-Perez, R., and A. Skarmeta, 1561 "Architecture of security association establishment based 1562 on bootstrapping technologies for enabling critical IoT 1563 infrastructures", October 2018, . 1568 [RFC7228] Bormann, C., Ersue, M., and A. Keranen, "Terminology for 1569 Constrained-Node Networks", RFC 7228, 1570 DOI 10.17487/RFC7228, May 2014, 1571 . 1573 [RFC7258] Farrell, S. and H. Tschofenig, "Pervasive Monitoring Is an 1574 Attack", BCP 188, RFC 7258, DOI 10.17487/RFC7258, May 1575 2014, . 1577 [RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol 1578 Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018, 1579 . 1581 [SSR18] Bruni, A., Sahl Joergensen, T., Groenbech Petersen, T., 1582 and C. Schuermann, "Formal Verification of Ephemeral 1583 Diffie-Hellman Over COSE (EDHOC)", November 2018, 1584 . 1588 Appendix A. Use of CBOR, CDDL and COSE in EDHOC 1590 This Appendix is intended to simplify for implementors not familiar 1591 with CBOR [I-D.ietf-cbor-7049bis], CDDL [I-D.ietf-cbor-cddl], COSE 1592 [RFC8152], and HKDF [RFC5869]. 1594 A.1. CBOR and CDDL 1596 The Concise Binary Object Representation (CBOR) 1597 [I-D.ietf-cbor-7049bis] is a data format designed for small code size 1598 and small message size. CBOR builds on the JSON data model but 1599 extends it by e.g. encoding binary data directly without base64 1600 conversion. In addition to the binary CBOR encoding, CBOR also has a 1601 diagnostic notation that is readable and editable by humans. The 1602 Concise Data Definition Language (CDDL) [I-D.ietf-cbor-cddl] provides 1603 a way to express structures for protocol messages and APIs that use 1604 CBOR. [I-D.ietf-cbor-cddl] also extends the diagnostic notation. 1606 CBOR data items are encoded to or decoded from byte strings using a 1607 type-length-value encoding scheme, where the three highest order bits 1608 of the initial byte contain information about the major type. CBOR 1609 supports several different types of data items, in addition to 1610 integers (int, uint), simple values (e.g. null), byte strings (bstr), 1611 and text strings (tstr), CBOR also supports arrays [] of data items 1612 and maps {} of pairs of data items. Some examples are given below. 1613 For a complete specification and more examples, see 1614 [I-D.ietf-cbor-7049bis] and [I-D.ietf-cbor-cddl]. We recommend 1615 implementors to get used to CBOR by using the CBOR playground 1616 [CborMe]. 1618 Diagnostic Encoded Type 1619 ------------------------------------------------------------------ 1620 1 0x01 unsigned integer 1621 24 0x1818 unsigned integer 1622 -24 0x37 negative integer 1623 -25 0x3818 negative integer 1624 null 0xf6 simple value 1625 h'12cd' 0x4212cd byte string 1626 '12cd' 0x4431326364 byte string 1627 "12cd" 0x6431326364 text string 1628 << 1, 2, null >> 0x430102f6 byte string 1629 [ 1, 2, null ] 0x830102f6 array 1630 [_ 1, 2, null ] 0x9f0102f6ff array (indefinite-length) 1631 ( 1, 2, null ) 0x0102f6 group 1632 { 4: h'cd' } 0xa10441cd map 1633 ------------------------------------------------------------------ 1635 All EDHOC messages consist of a sequence of CBOR encoded data items. 1636 While an EDHOC message in itself is not a CBOR data item, it may be 1637 viewed as the CBOR encoding of an indefinite-length array [_ 1638 message_i ] without the first byte (0x9f) and the last byte (0xff), 1639 for i = 1, 2 and 3. The same applies to the EDHOC error message. 1641 The message format specification uses the constructs '.cbor', 1642 '.cborseq' and '~' enabling conversion between different CDDL types 1643 matching different CBOR items with different encodings. Some 1644 examples are given below. 1646 A type (e.g. an uint) may be wrapped in a byte string (bstr), and 1647 back again: 1649 CDDL Type Diagnostic Encoded 1650 ------------------------------------------------------------------ 1651 uint 24 0x1818 1652 bstr .cbor uint << 24 >> 0x421818 1653 ~ bstr .cbor uint 24 0x1818 1654 ------------------------------------------------------------------ 1656 An array, say of an uint and a byte string, may be converted into a 1657 byte string (bstr): 1659 CDDL Type Diagnostic Encoded 1660 -------------------------------------------------------------------- 1661 bstr h'cd' 0x41cd 1662 [ uint, bstr ] [ 24, h'cd' ] 0x82181841cd 1663 bstr .cborseq [ uint, bstr ] << 24, h'cd' >> 0x44181841cd 1664 -------------------------------------------------------------------- 1666 A.2. COSE 1668 CBOR Object Signing and Encryption (COSE) [RFC8152] describes how to 1669 create and process signatures, message authentication codes, and 1670 encryption using CBOR. COSE builds on JOSE, but is adapted to allow 1671 more efficient processing in constrained devices. EDHOC makes use of 1672 COSE_Key, COSE_Encrypt0, COSE_Sign1, and COSE_KDF_Context objects. 1674 A.2.1. Encryption and Decryption 1676 The COSE parameters used in COSE_Encrypt0 (see Section 5.2 of 1677 [RFC8152]) are constructed as described below. Note that "i" in 1678 "K_i", "IV_i" and "aad_i" is a variable with value i = 2 or 3, 1679 depending on whether the calculation is made over message_2 or 1680 message_3. 1682 o The secret key K_i is a CBOR bstr, generated with the EDHOC-Key- 1683 Derivation function as defined in Section 3.3. 1685 o The initialization vector IV_i is a CBOR bstr, also generated with 1686 the EDHOC-Key-Derivation function as defined in Section 3.3. 1688 o The plaintext is a CBOR bstr. If the application data (UAD and 1689 PAD) is omitted, then plaintext = h'' in the symmetric case, and 1690 plaintext = << ~protected, signature >> in the asymmetric case. 1691 For instance, if protected = h'a10140' and signature = h'050607' 1692 (CBOR encoding 0x43050607), then plaintext = h'a1014043050607'. 1694 o The external_aad is a CBOR bstr. It is always set to aad_i. 1696 COSE constructs the input to the AEAD [RFC5116] as follows: 1698 o The key K is the value of the key K_i. 1700 o The nonce N is the value of the initialization vector IV_i. 1702 o The plaintext P is the value of the COSE plaintext. E.g. if the 1703 COSE plaintext = h'010203', then P = 0x010203. 1705 o The associated data A is the CBOR encoding of: 1707 [ "Encrypt0", h'', aad_i ] 1709 This equals the concatenation of 0x8368456e63727970743040 and the 1710 CBOR encoding of aad_i. For instance if aad_2 = h'010203' (CBOR 1711 encoding 0x43010203), then A = 0x8368456e6372797074304043010203. 1713 A.2.2. Signing and Verification 1715 The COSE parameters used in COSE_Sign1 (see Section 4.2 of [RFC8152]) 1716 are constructed as described below. Note that "i" in "aad_i" is a 1717 variable with values i = 2 or 3, depending on whether the calculation 1718 is made over message_2 or message_3. Note also that "x" in 1719 "ID_CRED_x" and "CRED_x" is a variable with values x = U or V, 1720 depending on whether it is the credential of U or of V that is used 1721 in the relevant protocol message. 1723 o The key is the private authentication key of U or V. This may be 1724 stored as a COSE_KEY object or as a certificate. 1726 o The protected parameter is a map { abc : ID_CRED_x } wrapped in a 1727 byte string. 1729 o The payload is a bstr containing the CBOR encoding of a COSE_KEY 1730 or a single certificate. 1732 o external_aad = aad_i. 1734 COSE constructs the input to the Signature Algorithm as follows: 1736 o The key is the private authentication key of U or V. 1738 o The message to be signed M is the CBOR encoding of: 1740 [ "Signature1", << { abc : ID_CRED_x } >>, aad_i, CRED_x ] 1742 For instance, if abc = 4 (CBOR encoding 0x04), ID_CRED_U = h'1111' 1743 (CBOR encoding 0x421111), aad_3 = h'222222' (CBOR encoding 1744 0x43222222), and CRED_U = h'55555555' (CBOR encoding 1745 0x4455555555), then M = 1746 0x846a5369676e61747572653145A104421111432222224455555555. 1748 A.2.3. Key Derivation 1750 Assuming use of the mandatory-to-implement algorithms HKDF SHA-256 1751 and AES-CCM-16-64-128, the extract phase of HKDF produces a 1752 pseudorandom key (PRK) as follows: 1754 PRK = HMAC-SHA-256( salt, ECDH shared secret ) 1756 where salt = 0x in the asymmetric case and salt = PSK in the 1757 symmetric case. As the output length L is smaller than the hash 1758 function output size, the expand phase of HKDF consists of a single 1759 HMAC invocation, and K_i and IV_i are therefore the first 16 and 13 1760 bytes, respectively, of 1762 output parameter = HMAC-SHA-256( PRK, info || 0x01 ) 1764 where || means byte string concatenation, and info is the CBOR 1765 encoding of 1767 COSE_KDF_Context = [ 1768 AlgorithmID, 1769 [ null, null, null ], 1770 [ null, null, null ], 1771 [ keyDataLength, h'', aad_i ] 1772 ] 1774 If AES-CCM-16-64-128 then AlgorithmID = 10 and keyDataLength = 128 1775 for K_i, and AlgorithmID = "IV-GENERATION" (CBOR encoding 1776 0x6d49562d47454e45524154494f4e) and keyDataLength = 104 for IV_i. 1777 Hence, if aad_2 = h'aaaa' then 1779 K_2 = HMAC-SHA-256( PRK, 0x840a83f6f6f683f6f6f68318804042aaaa01 ) 1780 IV_2 = HMAC-SHA-256( PRK, 0x846d49562d47454e45524154494f4e 1781 83f6f6f683f6f6f68318804042aaaa01 ) 1783 Appendix B. Example Messages and Sizes 1785 This appendix gives an estimate of the message sizes of EDHOC with 1786 different authentication methods. It also gives examples of messages 1787 and plaintexts in CBOR diagnostic notation and hexadecimal to help 1788 implementors. Note that the examples in this appendix are not test 1789 vectors, the cryptographic parts are just replaced with byte strings 1790 of the same length. 1792 B.1. Message Sizes RPK 1794 B.1.1. message_1 1796 message_1 = ( 1797 1, 1798 h'c3', 1799 0, 1800 0, 1801 h'000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d 1802 1e1f' 1803 ) 1805 message_1 (39 bytes): 1806 01 41 C3 00 00 58 20 00 01 02 03 04 05 06 07 08 09 0A 0B 0C 1807 0D 0E 0F 10 11 12 13 14 15 16 17 18 19 1A 1B 1C 1D 1E 1F 1809 B.1.2. message_2 1811 plaintext = << 1812 { 4 : 'acdc' }, 1813 h'000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d 1814 1e1f202122232425262728292a2b2c2d2e2f303132333435363738393a3b 1815 3c3d3e3f' 1816 >> 1818 The protected header map is 7 bytes. The length of plaintext is 73 1819 bytes so assuming a 64-bit MAC value the length of ciphertext is 81 1820 bytes. 1822 message_2 = ( 1823 null, 1824 h'c4', 1825 h'000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d 1826 1e1f', 1827 h'000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d 1828 1e1f202122232425262728292a2b2c2d2e2f303132333435363738393a3b 1829 3c3d3e3f404142434445464748494a4b4c4d4e4f50' 1830 ) 1831 message_2 (120 bytes): 1832 F6 41 C4 58 20 00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 1833 0F 10 11 12 13 14 15 16 17 18 19 1A 1B 1C 1D 1E 1F 58 51 00 1834 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F 10 11 12 13 14 1835 15 16 17 18 19 1A 1B 1C 1D 1E 1F 20 21 22 23 24 25 26 27 28 1836 29 2A 2B 2C 2D 2E 2F 30 31 32 33 34 35 36 37 38 39 3A 3B 3C 1837 3D 3E 3F 40 41 42 43 44 45 46 47 48 49 4A 4B 4C 4D 4E 4F 50 1839 B.1.3. message_3 1841 The plaintext and ciphertext in message_3 are assumed to be of equal 1842 sizes as in message_2. 1844 message_3 = ( 1845 h'c4', 1846 h'000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d 1847 1e1f202122232425262728292a2b2c2d2e2f303132333435363738393a3b 1848 3c3d3e3f404142434445464748494a4b4c4d4e4f50' 1849 ) 1851 message_3 (85 bytes): 1852 41 C4 58 51 00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F 1853 10 11 12 13 14 15 16 17 18 19 1A 1B 1C 1D 1E 1F 20 21 22 23 1854 24 25 26 27 28 29 2A 2B 2C 2D 2E 2F 30 31 32 33 34 35 36 37 1855 38 39 3A 3B 3C 3D 3E 3F 40 41 42 43 44 45 46 47 48 49 4A 4B 1856 4C 4D 4E 4F 50 1858 B.2. Message Sizes Certificates 1860 When the certificates are distributed out-of-band and identified with 1861 the x5t header and a SHA256/64 hash value, the protected header map 1862 will be 13 bytes instead of 7 bytes (assuming labels in the range 1863 -24...23). 1865 protected = << { TDB1 : [ TDB6, h'0001020304050607' ] } >> 1867 When the certificates are identified with the x5chain header, the 1868 message sizes depends on the size of the (truncated) certificate 1869 chains. The protected header map will be 3 bytes + the size of the 1870 certificate chain (assuming a label in the range -24...23). 1872 protected = << { TDB3 : h'0001020304050607...' } >> 1874 B.3. Message Sizes PSK 1875 B.3.1. message_1 1877 message_1 = ( 1878 2, 1879 h'c3', 1880 0, 1881 0, 1882 h'000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d 1883 1e1f', 1884 'abba' 1885 ) 1887 message_1 (44 bytes): 1888 02 41 C3 00 00 58 20 00 01 02 03 04 05 06 07 08 09 0A 0B 0C 1889 0D 0E 0F 10 11 12 13 14 15 16 17 18 19 1A 1B 1C 1D 1E 1F 1890 44 61 63 64 63 1892 B.3.2. message_2 1894 Assuming a 0 byte plaintext and a 64-bit MAC value the ciphertext is 1895 8 bytes 1897 message_2 = ( 1898 null, 1899 h'c4', 1900 h'000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d 1901 1e1f', 1902 h'0001020304050607' 1903 ) 1905 message_2 (46 bytes): 1906 F6 41 C4 58 20 00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 1907 0F 10 11 12 13 14 15 16 17 18 19 1A 1B 1C 1D 1E 1F 48 61 62 1908 63 64 65 66 67 68 1910 B.3.3. message_3 1912 The plaintext and ciphertext in message_3 are assumed to be of equal 1913 sizes as in message_2. 1915 message_3 = ( 1916 h'c4', 1917 h'0001020304050607' 1918 ) 1920 message_3 (11 bytes): 1921 41 C4 48 00 01 02 03 04 05 06 07 1923 B.4. Summary 1925 The previous estimates of typical message sizes are summarized in 1926 Figure 9. 1928 ===================================================================== 1929 PSK RPK x5t x5chain 1930 --------------------------------------------------------------------- 1931 message_1 44 39 39 39 1932 message_2 46 120 126 116 + Certificate chain 1933 message_3 11 85 91 81 + Certificate chain 1934 --------------------------------------------------------------------- 1935 Total 101 244 256 236 + Certificate chains 1936 ===================================================================== 1938 Figure 9: Typical message sizes in bytes 1940 In practice, most devices only have a few keys, so in deployments 1941 where assignment of key identifiers (KID, ID_CRED_V, ID_CRED_U) can 1942 be coordinated, the key identifiers can typically be much smaller 1943 (e.g. 1 byte). 1945 Figure 10 compares the message sizes of EDHOC with the DTLS 1.3 1946 handshake [I-D.ietf-tls-dtls13] with connection ID. The comparison 1947 uses a minimum number of extensions and offered algorithms/cipher 1948 suites, 4 bytes key identifiers, 1 byte connection IDs, no DTLS 1949 message fragmentation, and DTLS RPK SubjectPublicKeyInfo with point 1950 compression. 1952 ===================================================================== 1953 Flight #1 #2 #3 Total 1954 --------------------------------------------------------------------- 1955 DTLS 1.3 RPK + ECDHE 150 373 213 736 1956 DTLS 1.3 PSK + ECDHE 187 190 57 434 1957 DTLS 1.3 PSK 137 150 57 344 1958 --------------------------------------------------------------------- 1959 EDHOC RPK + ECDHE 39 120 85 244 1960 EDHOC PSK + ECDHE 44 46 11 101 1961 ===================================================================== 1963 Figure 10: Comparison of message sizes in bytes with Connection ID 1965 In reality the total overhead will be larger due to mechanisms for 1966 fragmentation, retransmission, and packet ordering. The overhead of 1967 fragmentation is roughly proportional to the number of fragments, 1968 while the expected overhead due to retransmission in noisy 1969 environments is a superlinear function of the flight sizes. 1971 Connection ID is not supported with TLS 1.3. Figure 11 compares the 1972 message sizes of EDHOC with the DTLS 1.3 [I-D.ietf-tls-dtls13] and 1973 TLS 1.3 [RFC8446] handshakes without connection ID. 1975 ===================================================================== 1976 Flight #1 #2 #3 Total 1977 --------------------------------------------------------------------- 1978 DTLS 1.3 RPK + ECDHE 144 364 212 722 1979 DTLS 1.3 PSK + ECDHE 181 183 56 420 1980 DTLS 1.3 PSK 131 143 56 330 1981 --------------------------------------------------------------------- 1982 TLS 1.3 RPK + ECDHE 129 322 194 645 1983 TLS 1.3 PSK + ECDHE 166 157 50 373 1984 TLS 1.3 PSK 116 117 50 283 1985 --------------------------------------------------------------------- 1986 EDHOC RPK + ECDHE 38 119 84 241 1987 EDHOC PSK + ECDHE 44 45 10 98 1988 ===================================================================== 1990 Figure 11: Comparison of message sizes in bytes without Connection ID 1992 Appendix C. Test Vectors 1994 This appendix provides a wealth of test vectors to ease 1995 implementation and ensure interoperability. 1997 TODO: This section needs to be updated. 1999 Acknowledgments 2001 The authors want to thank Alessandro Bruni, Theis Groenbech Petersen, 2002 Dan Harkins, Klaus Hartke, Alexandros Krontiris, Ilari Liusvaara, 2003 Karl Norrman, Salvador Perez, Michael Richardson, Thorvald Sahl 2004 Joergensen, Jim Schaad, Carsten Schuermann, Ludwig Seitz, Valery 2005 Smyslov, and Rene Struik for reviewing and commenting on intermediate 2006 versions of the draft. We are especially indebted to Jim Schaad for 2007 his continuous reviewing and implementation of different versions of 2008 the draft. 2010 Authors' Addresses 2012 Goeran Selander 2013 Ericsson AB 2015 Email: goran.selander@ericsson.com 2016 John Mattsson 2017 Ericsson AB 2019 Email: john.mattsson@ericsson.com 2021 Francesca Palombini 2022 Ericsson AB 2024 Email: francesca.palombini@ericsson.com