--- 1/draft-ietf-lake-edhoc-09.txt 2021-09-04 10:13:12.438652203 -0700 +++ 2/draft-ietf-lake-edhoc-10.txt 2021-09-04 10:13:12.574655600 -0700 @@ -1,19 +1,19 @@ Network Working Group G. Selander Internet-Draft J. Preuß Mattsson Intended status: Standards Track F. Palombini -Expires: 24 February 2022 Ericsson - 23 August 2021 +Expires: 8 March 2022 Ericsson + 4 September 2021 Ephemeral Diffie-Hellman Over COSE (EDHOC) - draft-ietf-lake-edhoc-09 + draft-ietf-lake-edhoc-10 Abstract This document specifies Ephemeral Diffie-Hellman Over COSE (EDHOC), a very compact and lightweight authenticated Diffie-Hellman key exchange with ephemeral keys. EDHOC provides mutual authentication, forward secrecy, and identity protection. EDHOC is intended for usage in constrained scenarios and a main use case is to establish an OSCORE security context. By reusing COSE for cryptography, CBOR for encoding, and CoAP for transport, the additional code size can be @@ -27,21 +27,21 @@ Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet- Drafts is at https://datatracker.ietf.org/drafts/current/. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." - This Internet-Draft will expire on 24 February 2022. + This Internet-Draft will expire on 8 March 2022. Copyright Notice Copyright (c) 2021 IETF Trust and the persons identified as the document authors. All rights reserved. This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/ license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights @@ -52,23 +52,23 @@ Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 1.1. Motivation . . . . . . . . . . . . . . . . . . . . . . . 3 1.2. Use of EDHOC . . . . . . . . . . . . . . . . . . . . . . 5 1.3. Message Size Examples . . . . . . . . . . . . . . . . . . 5 1.4. Document Structure . . . . . . . . . . . . . . . . . . . 6 1.5. Terminology and Requirements Language . . . . . . . . . . 6 2. EDHOC Outline . . . . . . . . . . . . . . . . . . . . . . . . 7 - 3. Protocol Elements . . . . . . . . . . . . . . . . . . . . . . 9 + 3. Protocol Elements . . . . . . . . . . . . . . . . . . . . . . 8 3.1. General . . . . . . . . . . . . . . . . . . . . . . . . . 9 - 3.2. Method . . . . . . . . . . . . . . . . . . . . . . . . . 10 + 3.2. Method . . . . . . . . . . . . . . . . . . . . . . . . . 9 3.3. Connection Identifiers . . . . . . . . . . . . . . . . . 10 3.4. Transport . . . . . . . . . . . . . . . . . . . . . . . . 11 3.5. Authentication Parameters . . . . . . . . . . . . . . . . 12 3.6. Cipher Suites . . . . . . . . . . . . . . . . . . . . . . 18 3.7. Ephemeral Public Keys . . . . . . . . . . . . . . . . . . 20 3.8. External Authorization Data (EAD) . . . . . . . . . . . . 20 3.9. Applicability Statement . . . . . . . . . . . . . . . . . 21 4. Key Derivation . . . . . . . . . . . . . . . . . . . . . . . 23 4.1. Extract . . . . . . . . . . . . . . . . . . . . . . . . . 23 4.2. Expand . . . . . . . . . . . . . . . . . . . . . . . . . 24 @@ -85,42 +85,43 @@ 6.2. Unspecified . . . . . . . . . . . . . . . . . . . . . . . 39 6.3. Wrong Selected Cipher Suite . . . . . . . . . . . . . . . 39 7. Security Considerations . . . . . . . . . . . . . . . . . . . 41 7.1. Security Properties . . . . . . . . . . . . . . . . . . . 41 7.2. Cryptographic Considerations . . . . . . . . . . . . . . 44 7.3. Cipher Suites and Cryptographic Algorithms . . . . . . . 45 7.4. Unprotected Data . . . . . . . . . . . . . . . . . . . . 45 7.5. Denial-of-Service . . . . . . . . . . . . . . . . . . . . 46 7.6. Implementation Considerations . . . . . . . . . . . . . . 46 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 48 - 8.1. EDHOC Exporter Label . . . . . . . . . . . . . . . . . . 48 + 8.1. EDHOC Exporter Label Registry . . . . . . . . . . . . . . 48 8.2. EDHOC Cipher Suites Registry . . . . . . . . . . . . . . 48 8.3. EDHOC Method Type Registry . . . . . . . . . . . . . . . 50 8.4. EDHOC Error Codes Registry . . . . . . . . . . . . . . . 50 - 8.5. COSE Header Parameters Registry . . . . . . . . . . . . . 50 + 8.5. EDHOC External Authorization Data Registry . . . . . . . 50 8.6. COSE Header Parameters Registry . . . . . . . . . . . . . 51 - 8.7. COSE Key Common Parameters Registry . . . . . . . . . . . 51 - 8.8. The Well-Known URI Registry . . . . . . . . . . . . . . . 51 - 8.9. Media Types Registry . . . . . . . . . . . . . . . . . . 52 - 8.10. CoAP Content-Formats Registry . . . . . . . . . . . . . . 53 - 8.11. EDHOC External Authorization Data . . . . . . . . . . . . 53 - 8.12. Expert Review Instructions . . . . . . . . . . . . . . . 53 + 8.7. COSE Header Parameters Registry . . . . . . . . . . . . . 51 + 8.8. COSE Key Common Parameters Registry . . . . . . . . . . . 51 + 8.9. CWT Confirmation Methods Registry . . . . . . . . . . . . 52 + 8.10. The Well-Known URI Registry . . . . . . . . . . . . . . . 52 + 8.11. Media Types Registry . . . . . . . . . . . . . . . . . . 52 + 8.12. CoAP Content-Formats Registry . . . . . . . . . . . . . . 53 + 8.13. Expert Review Instructions . . . . . . . . . . . . . . . 54 9. References . . . . . . . . . . . . . . . . . . . . . . . . . 54 9.1. Normative References . . . . . . . . . . . . . . . . . . 54 - 9.2. Informative References . . . . . . . . . . . . . . . . . 56 - Appendix A. Use with OSCORE and Transfer over CoAP . . . . . . . 59 - A.1. Selecting EDHOC Connection Identifier . . . . . . . . . . 59 - A.2. Deriving the OSCORE Security Context . . . . . . . . . . 60 - A.3. Transferring EDHOC over CoAP . . . . . . . . . . . . . . 61 - Appendix B. Compact Representation . . . . . . . . . . . . . . . 64 + 9.2. Informative References . . . . . . . . . . . . . . . . . 57 + Appendix A. Use with OSCORE and Transfer over CoAP . . . . . . . 60 + A.1. Selecting EDHOC Connection Identifier . . . . . . . . . . 60 + A.2. Deriving the OSCORE Security Context . . . . . . . . . . 61 + A.3. Transferring EDHOC over CoAP . . . . . . . . . . . . . . 62 + Appendix B. Compact Representation . . . . . . . . . . . . . . . 65 Appendix C. Use of CBOR, CDDL and COSE in EDHOC . . . . . . . . 65 - C.1. CBOR and CDDL . . . . . . . . . . . . . . . . . . . . . . 65 + C.1. CBOR and CDDL . . . . . . . . . . . . . . . . . . . . . . 66 C.2. CDDL Definitions . . . . . . . . . . . . . . . . . . . . 66 C.3. COSE . . . . . . . . . . . . . . . . . . . . . . . . . . 68 Appendix D. Test Vectors . . . . . . . . . . . . . . . . . . . . 68 Appendix E. Applicability Template . . . . . . . . . . . . . . . 68 Appendix F. EDHOC Message Deduplication . . . . . . . . . . . . 69 Appendix G. Transports Not Natively Providing Correlation . . . 70 Appendix H. Change Log . . . . . . . . . . . . . . . . . . . . . 70 Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . 75 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 75 @@ -341,28 +342,21 @@ secret and used for authenticated encryption of different messages. * An optional fourth message giving explicit key confirmation to I in deployments where no protected application data is sent from R to I. * A key material exporter and a key update function enabling forward secrecy. - * Verification of a common preferred cipher suite: - - - The Initiator lists supported cipher suites in order of - preference - - - The Responder verifies that the selected cipher suite is the - first supported cipher suite (or else rejects and states - supported cipher suites). + * Verification of a common preferred cipher suite. * Method types and error handling. * Selection of connection identifiers C_I and C_R which may be used to identify established keys or protocol state. * Transport of external authorization data. EDHOC is designed to encrypt and integrity protect as much information as possible, and all symmetric keys are derived using as @@ -658,20 +652,21 @@ An example of CRED_x being a UCCS in bytewise lexicographic order containing an X25519 static Diffie-Hellman key and where the parties have agreed on an EUI-64 identity is shown below: { /UCCS/ 2 : "42-50-31-FF-EF-37-32-39", /sub/ 8 : { /cnf/ 1 : { /COSE_Key/ 1 : 1, /kty/ + 2 : 0, /kid/ -1 : 4, /crv/ -2 : h'b1a3e89460e88d3a8d54211dc95f0b90 /x/ 3ff205eb71912d6db8f4af980d2db83a' } } } 3.5.3. Identities EDHOC assumes the existence of mechanisms (certification authority, @@ -769,40 +763,40 @@ - ID_CRED_x = { 35 : uri }, for x = I or R, - ID_CRED_x = { TBD4 : uri }, for x = I or R. ID_CRED_x MAY contain the actual credential used for authentication, CRED_x. For example, a certificate chain can be transported in ID_CRED_x with COSE header parameter c5c or x5chain, defined in [I-D.ietf-cose-cbor-encoded-cert] and [I-D.ietf-cose-x509]. Credentials of type CWT and UCCS are transported with the COSE header - parameter registered in Section 8.5: + parameters registered in Section 8.6: * ID_CRED_x = { TBD1 : CWT }, for x = I or R, - * ID_CRED_x = { TBD1 : UCCS }, for x = I or R. + * ID_CRED_x = { TBD2 : UCCS }, for x = I or R. It is RECOMMENDED that ID_CRED_x uniquely identify the public authentication key as the recipient may otherwise have to try several keys. ID_CRED_I and ID_CRED_R are transported in the 'ciphertext', see Section 5.4.2 and Section 5.3.2. When ID_CRED_x does not contain the actual credential, it may be very short, e.g., if the endpoints have agreed to use a key identifier parameter 'kid': * ID_CRED_x = { 4 : key_id_x }, where key_id_x : kid, for x = I or R. Note that 'kid' is extended to support int values to allow more one- - byte identifiers (see Section 8.6 and Section 8.7) which may be + byte identifiers (see Section 8.7 and Section 8.8) which may be useful in many scenarios since constrained devices only have a few keys. 3.6. Cipher Suites An EDHOC cipher suite consists of an ordered set of algorithms from the "COSE Algorithms" and "COSE Elliptic Curves" registries as well as the EDHOC MAC length. Algorithms need to be specified with enough parameters to make them completely determined. Currently, none of the algorithms require parameters. EDHOC is only specified for use @@ -887,25 +881,24 @@ 25. ( 24, -45, 16, 5, -8, 24, -45 ) (ChaCha20/Poly1305, SHAKE256, 16, X448, EdDSA, ChaCha20/Poly1305, SHAKE256) The different methods use the same cipher suites, but some algorithms are not used in some methods. The EDHOC signature algorithm is not used in methods without signature authentication. The Initiator needs to have a list of cipher suites it supports in order of preference. The Responder needs to have a list of cipher - suites it supports. SUITES_I is a CBOR array containing cipher - suites that the Initiator supports. SUITES_I is formatted and - processed as detailed in Section 5.2.1 to secure the cipher suite - negotiation. Examples of cipher suite negotiation are given in - Section 6.3.2. + suites it supports. SUITES_I contains cipher suites supported by the + Initiator, formatted and processed as detailed in Section 5.2.1 to + secure the cipher suite negotiation. Examples of cipher suite + negotiation are given in Section 6.3.2. 3.7. Ephemeral Public Keys EDHOC always uses compact representation of elliptic curve points, see Appendix B. In COSE compact representation is achieved by formatting the ECDH ephemeral public keys as COSE_Keys of type EC2 or OKP according to Sections 7.1 and 7.2 of [I-D.ietf-cose-rfc8152bis-algs], but only including the 'x' parameter in G_X and G_Y. For Elliptic Curve Keys of type EC2, compact representation MAY be used also in the COSE_Key. If the COSE @@ -934,21 +927,21 @@ consisting of one or more (type, ext_authz_data) pairs as defined below: ead = 1* ( type : int, ext_authz_data : any, ) where ext_authz_data is authorization related data defined in a separate specification and its type is an int. Different types of - ext_authz_data are registered in Section 8.11. + ext_authz_data are registered in Section 8.5. The EAD fields of EDHOC are not intended for generic application data. Since data carried in EAD_1 and EAD_2 fields may not be protected, special considerations need to be made such that it does not violate security and privacy requirements of the service which uses this data. Moreover, the content in an EAD field may impact the security properties provided by EDHOC. Security applications making use of the EAD fields must perform the necessary security analysis. 3.9. Applicability Statement @@ -988,22 +981,22 @@ EAD_4; see Section 3.8). 6. Identifier used as identity of endpoint; see Section 3.5.3. 7. If message_4 shall be sent/expected, and if not, how to ensure a protected application message is sent from the Responder to the Initiator; see Section 5.5. The applicability statement may also contain information about supported cipher suites. The procedure for selecting and verifying - cipher suite is still performed as specified by the protocol, but it - may become simplified by this knowledge. + cipher suite is still performed as described in Section 5.2.1 and + Section 6.3, but it may become simplified by this knowledge. An example of an applicability statement is shown in Appendix E. For some parameters, like METHOD, ID_CRED_x, type of EAD, the receiver is able to verify compliance with applicability statement, and if it needs to fail because of incompliance, to infer the reason why the protocol failed. For other parameters, like CRED_x in the case that it is not transported, it may not be possible to verify that incompliance with @@ -1117,47 +1110,46 @@ 4.2. Expand The keys, IVs and MACs used in EDHOC are derived from the PRKs using Expand, and instantiated with the EDHOC AEAD algorithm in the selected cipher suite. OKM = EDHOC-KDF( PRK, transcript_hash, label, context, length ) = Expand( PRK, info, length ) - where info is the CBOR encoding of + where info is encoded as the CBOR sequence - info = [ + info = ( edhoc_aead_id : int / tstr, transcript_hash : bstr, label : tstr, - * context : any, + context : bstr, length : uint, - ] + ) where * edhoc_aead_id is an int or tstr containing the algorithm identifier of the EDHOC AEAD algorithm in the selected cipher suite encoded as defined in [I-D.ietf-cose-rfc8152bis-algs]. Note that a single fixed edhoc_aead_id is used in all invocations of EDHOC-KDF, including the derivation of KEYSTREAM_2 and invocations of the EDHOC-Exporter (see Section 4.3). * transcript_hash is a bstr set to one of the transcript hashes TH_2, TH_3, or TH_4 as defined in Sections 5.3.1, 5.4.1, and 4.3. * label is a tstr set to the name of the derived key, IV or MAC; i.e., "KEYSTREAM_2", "MAC_2", "K_3ae", "IV_3ae", or "MAC_3". - * context is a CBOR sequence, i.e., zero or more encoded CBOR data - items + * context is a bstr * length is the length of output keying material (OKM) in bytes The definition of Expand depends on the EDHOC hash algorithm of the selected cipher suite: * if the EDHOC hash algorithm is SHA-2, then Expand( PRK, info, length ) = HKDF-Expand( PRK, info, length ) [RFC5869] * if the EDHOC hash algorithm is SHAKE128, then Expand( PRK, info, @@ -1189,28 +1181,28 @@ 4.3. EDHOC-Exporter Application keys and other application specific data can be derived using the EDHOC-Exporter interface defined as: EDHOC-Exporter(label, context, length) = EDHOC-KDF(PRK_4x3m, TH_4, label, context, length) where label is a registered tstr from the EDHOC Exporter Label - registry (Section 8.1), context is a CBOR sequence defined by the - application, and length is a uint defined by the application. The - (label, context) pair must be unique, i.e., a (label, context) MUST - NOT be used for two different purposes. However an application can - re-derive the same key several times as long as it is done in a - secure way. For example, in most encryption algorithms the same - (key, nonce) pair must not be reused. The context can for example be - the empty (zero-length) sequence or a single CBOR byte string. + registry (Section 8.1), context is a bstr defined by the application, + and length is a uint defined by the application. The (label, + context) pair must be unique, i.e., a (label, context) MUST NOT be + used for two different purposes. However an application can re- + derive the same key several times as long as it is done in a secure + way. For example, in most encryption algorithms the same (key, + nonce) pair must not be reused. The context can for example be the + empty (zero-length) sequence or a single CBOR byte string. The transcript hash TH_4 is a CBOR encoded bstr and the input to the hash function is a CBOR Sequence. TH_4 = H( TH_3, CIPHERTEXT_3 ) where H() is the hash function in the selected cipher suite. Examples of use of the EDHOC-Exporter are given in Section 5.5.2 and Appendix A. @@ -1289,68 +1281,67 @@ 5.2. EDHOC Message 1 5.2.1. Formatting of Message 1 message_1 SHALL be a CBOR Sequence (see Appendix C.1) as defined below message_1 = ( METHOD : int, - SUITES_I : [ selected : suite, supported : 2* suite ] / suite, + SUITES_I : suites, G_X : bstr, C_I : bstr / int, ? EAD_1 : ead, ) suite = int + suites = [ 2* suite ] / suite where: * METHOD = 0, 1, 2, or 3 (see Figure 4). - * SUITES_I - cipher suites which the Initiator supports in order of - (decreasing) preference. The list of supported cipher suites can - be truncated at the end, as is detailed in the processing steps - below and Section 6.3. One of the supported cipher suites is - selected. The selected suite is the first suite in the SUITES_I - CBOR array. If a single supported cipher suite is conveyed, then - that cipher suite is selected and SUITES_I is encoded as an int - instead of an array. + * SUITES_I - array of cipher suites which the Initiator supports in + order of preference, starting with the most preferred and ending + with the cipher suite selected for this session. If the most + preferred cipher suite is selected then SUITES_I is encoded as + that cipher suite, i.e. as an int. The processing steps are + detailed below and in Section 6.3. * G_X - the ephemeral public key of the Initiator * C_I - variable length connection identifier * EAD_1 - unprotected external authorization data, see Section 3.8. 5.2.2. Initiator Processing of Message 1 The Initiator SHALL compose message_1 as follows: * The supported cipher suites and the order of preference MUST NOT - be changed based on previous error messages. However, the list - SUITES_I sent to the Responder MAY be truncated such that cipher - suites which are the least preferred are omitted. The amount of - truncation MAY be changed between sessions, e.g., based on - previous error messages (see next bullet), but all cipher suites - which are more preferred than the least preferred cipher suite in - the list MUST be included in the list. + be changed based on previous error messages. SUITES_I contains + the ordered list of supported cipher suites, truncated after the + cipher suite selected for this session. The selected cipher suite + MAY be changed between sessions, e.g., based on previous error + messages (see next bullet), but all cipher suites which are more + preferred than the selected cipher suite in the list MUST be + included in SUITES_I. * The Initiator MUST select its most preferred cipher suite, conditioned on what it can assume to be supported by the Responder. If the Initiator previously received from the Responder an error message with error code 2 (see Section 6.3) - indicating cipher suites supported by the Responder which also are - supported by the Initiator, then the Initiator SHOULD select the - most preferred cipher suite of those (note that error messages are - not authenticated and may be forged). + indicating cipher suites supported by the Responder, then the + Initiator SHOULD select the most preferred supported cipher suite + among those (note that error messages are not authenticated and + may be forged). * Generate an ephemeral ECDH key pair using the curve in the selected cipher suite and format it as a COSE_Key. Let G_X be the 'x' parameter of the COSE_Key. * Choose a connection identifier C_I and store it for the length of the protocol. * Encode message_1 as a sequence of CBOR encoded data items as specified in Section 5.2.1 @@ -1401,27 +1392,28 @@ * Choose a connection identifier C_R and store it for the length of the protocol. * Compute the transcript hash TH_2 = H( H(message_1), G_Y, C_R ) where H() is the hash function in the selected cipher suite. The transcript hash TH_2 is a CBOR encoded bstr and the input to the hash function is a CBOR Sequence. Note that H(message_1) can be computed and cached already in the processing of message_1. - * Compute MAC_2 = EDHOC-KDF( PRK_3e2m, TH_2, "MAC_2", ( ID_CRED_R, - CRED_R, ? EAD_2 ), mac_length ). If the Responder authenticates - with a static Diffie-Hellman key (method equals 1 or 3), then - mac_length is the EDHOC MAC length given by the cipher suite. If - the Responder authenticates with a signature key (method equals 0 - or 2), then mac_length is equal to the output size of the EDHOC - hash algorithm given by the cipher suite. + * Compute MAC_2 = EDHOC-KDF( PRK_3e2m, TH_2, "MAC_2", << ID_CRED_R, + CRED_R, ? EAD_2 >>, mac_length_2 ). If the Responder + authenticates with a static Diffie-Hellman key (method equals 1 or + 3), then mac_length_2 is the EDHOC MAC length given by the + selected cipher suite. If the Responder authenticates with a + signature key (method equals 0 or 2), then mac_length_2 is equal + to the output size of the EDHOC hash algorithm given by the + selected cipher suite. - ID_CRED_R - identifier to facilitate retrieval of CRED_R, see Section 3.5.4 - CRED_R - CBOR item containing the credential of the Responder, see Section 3.5.4 - EAD_2 = unprotected external authorization data, see Section 3.8 @@ -1506,27 +1498,28 @@ 5.4.2. Initiator Processing of Message 3 The Initiator SHALL compose message_3 as follows: * Compute the transcript hash TH_3 = H(TH_2, CIPHERTEXT_2) where H() is the hash function in the selected cipher suite. The transcript hash TH_3 is a CBOR encoded bstr and the input to the hash function is a CBOR Sequence. Note that H(TH_2, CIPHERTEXT_2) can be computed and cached already in the processing of message_2. - * Compute MAC_3 = EDHOC-KDF( PRK_4x3m, TH_3, "MAC_3", ( ID_CRED_I, - CRED_I, ? EAD_3 ), mac_length ). If the Initiator authenticates - with a static Diffie-Hellman key (method equals 2 or 3), then - mac_length is the EDHOC MAC length given by the cipher suite. If - the Initiator authenticates with a signature key (method equals 0 - or 1), then mac_length is equal to the output size of the EDHOC - hash algorithm given by the cipher suite. + * Compute MAC_3 = EDHOC-KDF( PRK_4x3m, TH_3, "MAC_3", << ID_CRED_I, + CRED_I, ? EAD_3 >>, mac_length_3 ). If the Initiator + authenticates with a static Diffie-Hellman key (method equals 2 or + 3), then mac_length_3 is the EDHOC MAC length given by the + selected cipher suite. If the Initiator authenticates with a + signature key (method equals 0 or 1), then mac_length_3 is equal + to the output size of the EDHOC hash algorithm given by the + selected cipher suite. - ID_CRED_I - identifier to facilitate retrieval of CRED_I, see Section 3.5.4 - CRED_I - CBOR item containing the credential of the Initiator, see Section 3.5.4 - EAD_3 = protected external authorization data, see Section 3.8 * If the Initiator authenticates with a static Diffie-Hellman key @@ -1562,23 +1555,23 @@ - plaintext = ( ID_CRED_I / bstr / int, Signature_or_MAC_3, ? EAD_3 ) o Note that if ID_CRED_I contains a single 'kid' parameter, i.e., ID_CRED_I = { 4 : kid_I }, only the byte string or integer kid_I is conveyed in the plaintext encoded as a bstr or int. COSE constructs the input to the AEAD [RFC5116] as follows: - - Key K = EDHOC-KDF( PRK_3e2m, TH_3, "K_3ae", length ) + - Key K = EDHOC-KDF( PRK_3e2m, TH_3, "K_3ae", h'', length ) - - Nonce N = EDHOC-KDF( PRK_3e2m, TH_3, "IV_3ae", length ) + - Nonce N = EDHOC-KDF( PRK_3e2m, TH_3, "IV_3ae", h'', length ) - Plaintext P = ( ID_CRED_I / bstr / int, Signature_or_MAC_3, ? EAD_3 ) - Associated data A = [ "Encrypt0", h'', TH_3 ] CIPHERTEXT_3 is the 'ciphertext' of the outer COSE_Encrypt0. * Encode message_3 as a sequence of CBOR encoded data items as specified in Section 5.4.1. @@ -1680,23 +1673,24 @@ - protected = h'' - external_aad = TH_4 - plaintext = ( ? EAD_4 ) where EAD_4 is protected external authorization data, see Section 3.8. COSE constructs the input to the AEAD [RFC5116] as follows: - - Key K = EDHOC-Exporter( "EDHOC_message_4_Key", , length ) + - Key K = EDHOC-Exporter( "EDHOC_message_4_Key", h'', length ) - - Nonce N = EDHOC-Exporter( "EDHOC_message_4_Nonce", , length ) + - Nonce N = EDHOC-Exporter( "EDHOC_message_4_Nonce", h'', length + ) - Plaintext P = ( ? EAD_4 ) - Associated data A = [ "Encrypt0", h'', TH_4 ] CIPHERTEXT_4 is the ciphertext of the COSE_Encrypt0. * Encode message_4 as a sequence of CBOR encoded data items as specified in Section 5.5.1. @@ -1764,21 +1758,21 @@ Additional error codes and corresponding error information may be specified. +----------+---------------+----------------------------------------+ | ERR_CODE | ERR_INFO Type | Description | +==========+===============+========================================+ | 0 | any | Success | +----------+---------------+----------------------------------------+ | 1 | tstr | Unspecified | +----------+---------------+----------------------------------------+ - | 2 | SUITES_R | Wrong selected cipher suite | + | 2 | suites | Wrong selected cipher suite | +----------+---------------+----------------------------------------+ Figure 6: Error Codes and Error Information 6.1. Success Error code 0 MAY be used internally in an application to indicate success, e.g., in log files. ERR_INFO can contain any type of CBOR item. Error code 0 MUST NOT be used as part of the EDHOC message exchange flow. @@ -1792,91 +1786,95 @@ debugging need to interpret it in the context of the EDHOC specification. The diagnostic message SHOULD be provided to the calling application where it SHOULD be logged. 6.3. Wrong Selected Cipher Suite Error code 2 MUST only be used in a response to message_1 in case the cipher suite selected by the Initiator is not supported by the Responder, or if the Responder supports a cipher suite more preferred by the Initiator than the selected cipher suite, see Section 5.2.3. - ERR_INFO is of type SUITES_R: - - SUITES_R : [ supported : 2* suite ] / suite - - If the Responder does not support the selected cipher suite, then - SUITES_R MUST include one or more supported cipher suites. If the - Responder does not support the selected cipher suite, but supports - another cipher suite in SUITES_I, then SUITES_R MUST include the - first supported cipher suite in SUITES_I. + ERR_INFO is in this case denoted SUITES_R and is of type suites, see + Section 5.2.1). If the Responder does not support the selected + cipher suite, then SUITES_R MUST include one or more supported cipher + suites. If the Responder supports a cipher suite in SUITES_I other + than the selected cipher suite (independently of if the selected + cipher suite is supported or not) then SUITES_R MUST include the + supported cipher suite in SUITES_I which is most preferred by the + Initiator. SUITES_R MAY include a single cipher suite, i.e. be + encoded as an int. If the Responder does not support any cipher + suite in SUITES_I, then it SHOULD include all its supported cipher + suites in SUITES_R in any order. 6.3.1. Cipher Suite Negotiation After receiving SUITES_R, the Initiator can determine which cipher - suite to select for the next EDHOC run with the Responder. + suite to select (if any) for the next EDHOC run with the Responder. If the Initiator intends to contact the Responder in the future, the Initiator SHOULD remember which selected cipher suite to use until the next message_1 has been sent, otherwise the Initiator and - Responder will likely run into an infinite loop. After a successful - run of EDHOC, the Initiator MAY remember the selected cipher suite to - use in future EDHOC runs. Note that if the Initiator or Responder is - updated with new cipher suite policies, any cached information may be + Responder will likely run into an infinite loop where the Initiator + selects its most preferred and the Responder sends an error with + supported cipher suites. After a successful run of EDHOC, the + Initiator MAY remember the selected cipher suite to use in future + EDHOC sessions. Note that if the Initiator or Responder is updated + with new cipher suite policies, any cached information may be outdated. 6.3.2. Examples Assume that the Initiator supports the five cipher suites 5, 6, 7, 8, and 9 in decreasing order of preference. Figures 7 and 8 show - examples of how the Initiator can truncate SUITES_I and how SUITES_R - is used by Responders to give the Initiator information about the - cipher suites that the Responder supports. + examples of how the Initiator can format SUITES_I and how SUITES_R is + used by Responders to give the Initiator information about the cipher + suites that the Responder supports. In the first example (Figure 7), the Responder supports cipher suite 6 but not the initially selected cipher suite 5. Initiator Responder | METHOD, SUITES_I = 5, G_X, C_I, EAD_1 | +------------------------------------------------------------------>| | message_1 | | | - | DIAG_MSG, SUITES_R = 6 | + | ERR_CODE = 2, SUITES_R = 6 | |<------------------------------------------------------------------+ | error | | | - | METHOD, SUITES_I = [6, 5, 6], G_X, C_I, EAD_1 | + | METHOD, SUITES_I = [5, 6], G_X, C_I, EAD_1 | +------------------------------------------------------------------>| | message_1 | Figure 7: Example of Responder supporting suite 6 but not suite 5. In the second example (Figure 8), the Responder supports cipher suites 8 and 9 but not the more preferred (by the Initiator) cipher suites 5, 6 or 7. To illustrate the negotiation mechanics we let the Initiator first make a guess that the Responder supports suite 6 but not suite 5. Since the Responder supports neither 5 nor 6, it - responds with an error and SUITES_R, after which the Initiator - selects its most preferred supported suite. The order of cipher - suites in SUITES_R does not matter. (If the Responder had supported - suite 5, it would include it in SUITES_R of the response, and it - would in that case have become the selected suite in the second - message_1.) + responds with SUITES_R containing the supported suites, after which + the Initiator selects its most preferred supported suite. The order + of cipher suites in SUITES_R does not matter. (If the Responder had + supported suite 5, it would have included it in SUITES_R of the + response, and it would in that case have become the selected suite in + the second message_1.) Initiator Responder - | METHOD, SUITES_I = [6, 5, 6], G_X, C_I, EAD_1 | + | METHOD, SUITES_I = [5, 6], G_X, C_I, EAD_1 | +------------------------------------------------------------------>| | message_1 | | | - | DIAG_MSG, SUITES_R = [9, 8] | + | ERR_CODE = 2, SUITES_R = [9, 8] | |<------------------------------------------------------------------+ | error | | | - | METHOD, SUITES_I = [8, 5, 6, 7, 8], G_X, C_I, EAD_1 | + | METHOD, SUITES_I = [5, 6, 7, 8], G_X, C_I, EAD_1 | +------------------------------------------------------------------>| | message_1 | Figure 8: Example of Responder supporting suites 8 and 9 but not 5, 6 or 7. Note that the Initiator's list of supported cipher suites and order of preference is fixed (see Section 5.2.1 and Section 5.2.2). Furthermore, the Responder shall only accept message_1 if the selected cipher suite is the first cipher suite in SUITES_I that the @@ -1988,21 +1986,21 @@ PRK_4x3m and TH_4. Key compromise impersonation (KCI): In EDHOC authenticated with signature keys, EDHOC provides KCI protection against an attacker having access to the long-term key or the ephemeral secret key. With static Diffie-Hellman key authentication, KCI protection would be provided against an attacker having access to the long-term Diffie- Hellman key, but not to an attacker having access to the ephemeral secret key. Note that the term KCI has typically been used for compromise of long-term keys, and that an attacker with access to the - ephemeral secret key can only attack that specific protocol run. + ephemeral secret key can only attack that specific session. Repudiation: In EDHOC authenticated with signature keys, the Initiator could theoretically prove that the Responder performed a run of the protocol by presenting the private ephemeral key, and vice versa. Note that storing the private ephemeral keys violates the protocol requirements. With static Diffie-Hellman key authentication, both parties can always deny having participated in the protocol. Two earlier versions of EDHOC have been formally analyzed [Norrman20] @@ -2184,21 +2182,21 @@ protect against such attacks EDHOC needs to be in its own zone. To provide better protection against some forms of physical attacks, sensitive EDHOC data should be stored inside the SoC or encrypted and integrity protected when sent on a data bus (e.g., between the CPU and RAM or Flash). Secure boot can be used to increase the security of code and data in the Rich Execution Environment (REE) by validating the REE image. 8. IANA Considerations -8.1. EDHOC Exporter Label +8.1. EDHOC Exporter Label Registry IANA has created a new registry titled "EDHOC Exporter Label" under the new heading "EDHOC". The registration procedure is "Expert Review". The columns of the registry are Label, Description, and Reference. All columns are text strings. The initial contents of the registry are: Label: EDHOC_message_4_Key Description: Key used to protect EDHOC message_4 Reference: [[this document]] @@ -2305,78 +2303,112 @@ 8.4. EDHOC Error Codes Registry IANA has created a new registry entitled "EDHOC Error Codes" under the new heading "EDHOC". The registration procedure is "Specification Required". The columns of the registry are ERR_CODE, ERR_INFO Type and Description, where ERR_CODE is an integer, ERR_INFO is a CDDL defined type, and Description is a text string. The initial contents of the registry are shown in Figure 6. -8.5. COSE Header Parameters Registry +8.5. EDHOC External Authorization Data Registry + + IANA has created a new registry entitled "EDHOC External + Authorization Data" under the new heading "EDHOC". The registration + procedure is "Expert Review". The columns of the registry are Value, + Description, and Reference, where Value is an integer and the other + columns are text strings. + +8.6. COSE Header Parameters Registry This document registers the following entries in the "COSE Header Parameters" registry under the "CBOR Object Signing and Encryption - (COSE)" heading. The value of the 'cwt' header parameter is a CWT - [RFC8392] or an Unprotected CWT Claims Set, see Section 1.5. + (COSE)" heading. The value of the 'cwt' header parameter is a COSE + Web Token (CWT) [RFC8392] and the value of the 'uccs' header + parameter is an Unprotected CWT Claims Set (UCCS), see Section 1.5. - +-----------+-------+----------------+------------------------------+ + +-----------+-------+----------------+---------------------------+ | Name | Label | Value Type | Description | - +===========+=======+================+==============================+ - | cwt | TBD1 | COSE_Messages | A CBOR Web Token (CWT) or an | - | | | / map | Unprotected CWT Claims Set | - +-----------+-------+----------------+------------------------------+ + +===========+=======+================+===========================+ + | cwt | TBD1 | COSE_Messages | A CBOR Web Token (CWT) | + +-----------+-------+----------------+---------------------------+ + | uccs | TBD2 | map | An Unprotected CWT Claims | + | | | | Set (UCCS) | + +-----------+-------+----------------+---------------------------+ -8.6. COSE Header Parameters Registry +8.7. COSE Header Parameters Registry IANA has extended the Value Type of the COSE Header Parameter 'kid' to also allow the Value Type int. The resulting Value Type is bstr / int. The 'kid' parameter can be used to identify a key stored in a UCCS, in a CWT, or in a public key certificate. (The Value Registry for this item is empty and omitted from the table below.) +------+-------+------------+----------------+-------------------+ | Name | Label | Value Type | Description | Reference | +------+-------+------------+----------------+-------------------+ | kid | 4 | bstr / int | Key identifier | [RFC9052] | | | | | | [[This document]] | +------+-------+------------+----------------+-------------------+ -8.7. COSE Key Common Parameters Registry +8.8. COSE Key Common Parameters Registry IANA has extended the Value Type of the COSE Key Common Parameter 'kid' to the COSE Key Value Type int. The resulting Value Type is bstr / int. (The Value Registry for this item is empty and omitted from the table below.) +------+-------+------------+----------------+-------------------+ | Name | Label | Value Type | Description | Reference | +------+-------+------------+----------------+-------------------+ | kid | 2 | bstr / int | Key identifi- | [RFC9052] | | | | | cation value - | [[This document]] | | | | | match to kid | | | | | | in message | | +------+-------+------------+----------------+-------------------+ -8.8. The Well-Known URI Registry +8.9. CWT Confirmation Methods Registry + + IANA has extended the Value Type of the WT Confirmation Methods 'kid' + to the COSE Key Value Type int. The incorrect term binary string has + been corrected to bstr. The resulting Value Type is bstr / int. The + new updated content for the 'kid' method is shown in the list below. + + * Confirmation Method Name: kid + + * Confirmation Method Description: Key Identifier + + * JWT Confirmation Method Name: kid + + * Confirmation Key: 3 + + * Confirmation Value Type(s): bstr / int + + * Change Controller: IESG + + * Specification Document(s): Section 3.4 of RFC 8747 [[This + document]] + +8.10. The Well-Known URI Registry IANA has added the well-known URI "edhoc" to the Well-Known URIs registry. * URI suffix: edhoc * Change controller: IETF * Specification document(s): [[this document]] + * Related information: None -8.9. Media Types Registry +8.11. Media Types Registry IANA has added the media type "application/edhoc" to the Media Types registry. * Type name: application * Subtype name: edhoc * Required parameters: N/A @@ -2406,42 +2437,34 @@ "Authors' Addresses" section. * Intended usage: COMMON * Restrictions on usage: N/A * Author: See "Authors' Addresses" section. * Change Controller: IESG -8.10. CoAP Content-Formats Registry +8.12. CoAP Content-Formats Registry IANA has added the media type "application/edhoc" to the CoAP Content-Formats registry. * Media Type: application/edhoc * Encoding: * ID: TBD42 * Reference: [[this document]] -8.11. EDHOC External Authorization Data - - IANA has created a new registry entitled "EDHOC External - Authorization Data" under the new heading "EDHOC". The registration - procedure is "Expert Review". The columns of the registry are Value, - Description, and Reference, where Value is an integer and the other - columns are text strings. - -8.12. Expert Review Instructions +8.13. Expert Review Instructions The IANA Registries established in this document is defined as "Expert Review". This section gives some general guidelines for what the experts should be looking for, but they are being designated as experts for a reason so they should be given substantial latitude. Expert reviewers should take into consideration the following points: * Clarity and correctness of registrations. Experts are expected to check the clarity of purpose and use of the requested entries. @@ -2780,22 +2803,22 @@ Salt", respectively. The context parameter is h'' (0x40), the empty CBOR byte string. By default, key_length is the key length (in bytes) of the application AEAD Algorithm of the selected cipher suite for the EDHOC session. Also by default, salt_length has value 8. The Initiator and Responder MAY agree out-of-band on a longer key_length than the default and on a different salt_length. - Master Secret = EDHOC-Exporter( "OSCORE Master Secret", , key_length ) - Master Salt = EDHOC-Exporter( "OSCORE Master Salt", , salt_length ) + Master Secret = EDHOC-Exporter("OSCORE Master Secret", h'', key_length) + Master Salt = EDHOC-Exporter("OSCORE Master Salt", h'', salt_length) * The AEAD Algorithm is the application AEAD algorithm of the selected cipher suite for the EDHOC session. * The HKDF Algorithm is the one based on the application hash algorithm of the selected cipher suite for the EDHOC session. For example, if SHA-256 is the application hash algorithm of the selected ciphersuite, HKDF SHA-256 is used as HKDF Algorithm in the OSCORE Security Context. @@ -3028,60 +3051,60 @@ ( 1, 2, true ) 0x0102f5 sequence 1, 2, true 0x0102f5 sequence ------------------------------------------------------------------ C.2. CDDL Definitions This sections compiles the CDDL definitions for ease of reference. suite = int + suites = [ 2* suite ] / suite + ead = 1* ( type : int, ext_authz_data : any, ) message_1 = ( METHOD : int, - SUITES_I : [ selected : suite, supported : 2* suite ] / suite, + SUITES_I : suites, G_X : bstr, C_I : bstr / int, ? EAD_1 : ead, ) message_2 = ( G_Y_CIPHERTEXT_2 : bstr, C_R : bstr / int, ) message_3 = ( CIPHERTEXT_3 : bstr, ) message_4 = ( CIPHERTEXT_4 : bstr, ) - SUITES_R : [ supported : 2* suite ] / suite - error = ( ERR_CODE : int, ERR_INFO : any, ) - info = [ + info = ( edhoc_aead_id : int / tstr, transcript_hash : bstr, label : tstr, - * context : any, + context : bstr, length : uint, - ] + ) C.3. COSE CBOR Object Signing and Encryption (COSE) [I-D.ietf-cose-rfc8152bis-struct] describes how to create and process signatures, message authentication codes, and encryption using CBOR. COSE builds on JOSE, but is adapted to allow more efficient processing in constrained devices. EDHOC makes use of COSE_Key, COSE_Encrypt0, and COSE_Sign1 objects in the message processing: @@ -3202,21 +3225,32 @@ server does not send any such indicator, as responses are matched to request by the client-server protocol design. Protocols that do not provide any correlation at all can prescribe prepending of the peer's chosen C_x to all messages. Appendix H. Change Log RFC Editor: Please remove this appendix. - Main changes: + * From -09 to -10: + + - SUITES_I simplified to only contain the selected and more + preferred suites + + - Info is a CBOR sequence and context is a bstr + + - Added kid to UCCS example + + - Separate header parameters for CWT and UCCS + + - CWT Confirmation Method kid extended to bstr / int * From -08 to -09: - G_Y and CIPHERTEXT_2 are now included in one CBOR bstr - MAC_2 and MAC_3 are now generated with EDHOC-KDF - Info field "context" is now general and explicit in EDHOC-KDF - Restructured Section 4, Key Derivation