Traces of EDHOC

EDHOC is a lightweight authenticated key exchange protocol designed for highly constrained settings. This document contains annotated traces of EDHOC protocol runs, with input, output and intermediate processing results to simplify testing of implementations. The traces in this draft are valid for versions -11 and -12 of . A more extensive test vector suite and related code that was used to generate them can be found at: https://github.com/lake-wg/edhoc/tree/master/test-vectors-11.

EDHOC is run between an Initiator (I) and a Responder (R). The private/public key pairs and credentials of I and R required to produce the protocol messages are shown in the traces when needed for the calculations. Both I and R are assumed to support cipher suite 0, which determines the algorithms: EDHOC AEAD algorithm = AES-CCM-16-64-128 EDHOC hash algorithm = SHA-256 EDHOC MAC length in bytes (Static DH) = 8 EDHOC key exchange algorithm (ECDH curve) = X25519 EDHOC signature algorithm = EdDSA Application AEAD algorithm = AES-CCM-16-64-128 Application hash algorithm = SHA-256 External authorization data (EAD) is not used in these examples. EDHOC messages and intermediate results are encoded in CBOR and can therefore be displayed in CBOR diagnostic notation using, e.g., the CBOR playground , which makes them easy to parse for humans. NOTE 1. The same name is used for hexadecimal byte strings and their CBOR encodings. The traces contain both the raw byte strings and the corresponding CBOR encoded data items. NOTE 2. If not clear from the context, remember that CBOR sequences and CBOR arrays assume CBOR encoded data items as elements. NOTE 3. When the protocol transporting EDHOC messages does not inherently provide correlation across all messages, like CoAP, then some messages typically are prepended with connection identifiers and potentially a message_1 indicator (see Section 3.4.1 and Appendix A.3 of ). Those bytes are not included in the traces in this document.

In this example I and R are authenticated with ephemeral-static Diffie-Hellman (METHOD = 3). The public keys are represented as raw public keys (RPK), encoded in an CWT Claims Set (CCS) and identified by the COSE header parameter ‘kid’.

Both endpoints are authenticated with static DH, i.e. METHOD = 3:

I selects cipher suite 0. A single cipher suite is encoded as an int:

I creates an ephemeral key pair for use with the EDHOC key exchange algorithm:

I selects its connection identifier C_I to be the int 12:

No external authorization data:

I constructs message_1:

R creates an ephemeral key pair for use with the EDHOC key exchange algorithm:

PRK_2e is specified in Section 4.1.1 of . First, the ECDH shared secret G_XY is computed from G_X and Y, or G_Y and X:

Then, PRK_2e is calculated using Extract() determined by the EDHOC hash algorithm:

where salt is the zero-length byte string:

Since METHOD = 3, R authenticates using static DH. R’s static key pair for use with the EDHOC key exchange algorithm is based on the same curve as for the ephemeral keys, X25519:

PRK_3e2m is specified in Section 4.1.2 of . Since R authenticates with static DH (METHOD = 3), PRK_3e2m is derived from G_RX using Extract() with the EDHOC hash algorithm:

where G_RX is the ECDH shared secret calculated from G_X and R, or G_R and X.

R selects its connection identifier C_R to be the empty byte string “”:

The transcript hash TH_2 is calculated using the EDHOC hash algorithm: TH_2 = H(H(message_1), G_Y, C_R)

The input to calculate TH_2 is the CBOR sequence: H(message_1), G_Y, C_R

R constructs the remaining input needed to calculate MAC_2: MAC_2 = EDHOC-KDF(PRK_3e2m, TH_2, “MAC_2”, « ID_CRED_R, CRED_R, ? EAD_2 », mac_length_2) CRED_R is identified by a ‘kid’ with integer value 5:

CRED_R is an RPK encoded as a CCS:

No external authorization data:

MAC_2 is computed through Expand() using the EDHOC hash algorithm, see Section 4.2 of : MAC_2 = HKDF-Expand(PRK_3e2m, info, mac_length_2) Since METHOD = 3, mac_length_2 is given by the EDHOC MAC length. info for MAC_2 is:

where the last value is the EDHOC MAC length.

Since METHOD = 3, Signature_or_MAC_2 is MAC_2:

R constructs the plaintext:

Since ID_CRED_R contains a single ‘kid’ parameter, only the int 5 is included in the plaintext.

The input needed to calculate KEYSTREAM_2 is defined in Section 4.2 of , using Expand() with the EDHOC hash algorithm:

where length is the length of PLAINTEXT_2, and info for KEYSTREAM_2 is:

where last value is the length of PLAINTEXT_2.

R calculates CIPHERTEXT_2 as XOR between PLAINTEXT_2 and KEYSTREAM_2:

R constructs message_2:

where G_Y_CIPHERTEXT_2 is the bstr encoding of the concatenation of the raw values of G_Y and CIPHERTEXT_2.

Since METHOD = 3, I authenticates using static DH. I’s static key pair for use with the EDHOC key exchange algorithm is based on the same curve as for the ephemeral keys, X25519:

PRK_4x3m is derived as specified in Section 4.1.3 of . Since I authenticates with static DH (METHOD = 3), PRK_4x3m is derived from G_IY using Extract() with the EDHOC hash algorithm:

where G_IY is the ECDH shared secret calculated from G_I and Y, or G_Y and I.

The transcript hash TH_3 is calculated using the EDHOC hash algorithm: TH_3 = H(TH_2, CIPHERTEXT_2)

I constructs the remaining input needed to calculate MAC_3:

>, mac_length_3) ]]> CRED_I is identified by a ‘kid’ with integer value -10:

ID_CRED_I (CBOR Data Item) (3 bytes) a1 04 29 CRED_I is an RPK encoded as a CCS:

No external authorization data: EAD_3 (CBOR Sequence) (0 bytes) MAC_3 is computed through Expand() using the EDHOC hash algorithm, see Section 4.2 of :

Since METHOD = 3, mac_length_3 is given by the EDHOC MAC length. info for MAC_3 is:

where the last value is the EDHOC MAC length.

Since METHOD = 3, Signature_or_MAC_3 is MAC_3:

I constructs the plaintext P_3:

Since ID_CRED_I contains a single ‘kid’ parameter, only the int -10 is included in the plaintext.

I constructs the associated data for message_3:

I constructs the input needed to derive the key K_3, see Section 4.2 of , using the EDHOC hash algorithm:

where length is the key length of EDHOC AEAD algorithm, and info for K_3 is:

where the last value is the key length of EDHOC AEAD algorithm.

I constructs the input needed to derive the nonce IV_3, see Section 4.2 of , using the EDHOC hash algorithm:

where length is the nonce length of EDHOC AEAD algorithm, and info for IV_3 is:

where the last value is the nonce length of EDHOC AEAD algorithm.

I calculates CIPHERTEXT_3 as ‘ciphertext’ of COSE_Encrypt0 applied using the EDHOC AEAD algorithm with plaintext P_3, additional data A_3, key K_3 and nonce IV_3.

message_3 is the CBOR bstr encoding of CIPHERTEXT_3:

The transcript hash TH_4 is calculated using the EDHOC hash algorithm: TH_4 = H(TH_3, CIPHERTEXT_3)

No external authorization data: EAD_4 (CBOR Sequence) (0 bytes) R constructs the plaintext P_4:

P_4 (CBOR Sequence) (0 bytes) R constructs the associated data for message_4:

R constructs the input needed to derive the EDHOC message_4 key, see Section 4.2 of , using the EDHOC hash algorithm:

where length is the key length of the EDHOC AEAD algorithm, and info for EDHOC_K_4 is:

where the last value is the key length of EDHOC AEAD algorithm.

R constructs the input needed to derive the EDHOC message_4 nonce, see Section 4.2 of , using the EDHOC hash algorithm:

where length is the nonce length of EDHOC AEAD algorithm, and info for EDHOC_IV_4 is:

where the last value is the nonce length of EDHOC AEAD algorithm.

R calculates CIPHERTEXT_4 as ‘ciphertext’ of COSE_Encrypt0 applied using the EDHOC AEAD algorithm with plaintext P_4, additional data A_4, key K_4 and nonce IV_4.

message_4 is the CBOR bstr encoding of CIPHERTEXT_4:

The derivation of OSCORE parameters is specified in Appendix A.2 of . The AEAD and Hash algorithms to use in OSCORE are given by the selected cipher suite:

The mapping from EDHOC connection identifiers to OSCORE Sender/Recipient IDs is defined in Section A.1of . C_R is mapped to the Recipient ID of the server, i.e., the Sender ID of the client. Since C_R is byte valued it the OSCORE Sender/Recipient ID equals the byte string (in this case the empty byte string).

C_I is mapped to the Recipient ID of the client, i.e., the Sender ID of the server. Since C_I is a numeric, it is converted to a byte string equal to its CBOR encoded form.

The OSCORE Master Secret is computed through Expand() using the Application hash algorithm, see Section 4.2 of :

where key_length is by default the key length of the Application AEAD algorithm, and info for the OSCORE Master Secret is:

where the last value is the key length of Application AEAD algorithm.

The OSCORE Master Salt is computed through Expand() using the Application hash algorithm, see Section 4.2 of :

where salt_length is the length of the OSCORE Master Salt, and info for the OSCORE Master Salt is:

where the last value is the length of the OSCORE Master Salt.

Key update is defined in Section 4.4 of :

The OSCORE Master Secret is derived with the updated PRK_4x3m: OSCORE Master Secret = HKDF-Expand(PRK_4x3m, info, key_length) where info and key_length are unchanged.

The OSCORE Master Salt is derived with the updated PRK_4x3m: OSCORE Master Salt = HKDF-Expand(PRK_4x3m, info, salt_length) where info and salt_length are unchanged.

In this example the Initiator (I) and Responder (R) are authenticated with digital signatures (METHOD = 0). The public keys are represented with dummy X.509 certificates identified by the COSE header parameter ‘x5t’.

Both endpoints are authenticated with signatures, i.e. METHOD = 0:

I selects cipher suite 0. A single cipher suite is encoded as an int:

I creates an ephemeral key pair for use with the EDHOC key exchange algorithm:

I selects its connection identifier C_I to be the int 14:

No external authorization data: EAD_1 (CBOR Sequence) (0 bytes) I constructs message_1:

R creates an ephemeral key pair for use with the EDHOC key exchange algorithm:

PRK_2e is specified in Section 4.1.1 of . First, the ECDH shared secret G_XY is computed from G_X and Y, or G_Y and X:

Then, PRK_2e is calculated using Extract() determined by the EDHOC hash algorithm:

where salt is the zero-length byte string: salt (Raw Value) (0 bytes)

Since METHOD = 0, R authenticates using signatures with the EDHOC signature algorithm. R’s signature key pair using Ed25519 is (note that Ed448 would also be compatible with EdDSA):

PRK_3e2m is specified in Section 4.1.2 of . Since R authenticates with signatures PRK_3e2m = PRK_2e.

R selects its connection identifier C_R to be the int -19

The transcript hash TH_2 is calculated using the EDHOC hash algorithm: TH_2 = H(H(message_1), G_Y, C_R)

The input to calculate TH_2 is the CBOR sequence: H(message_1), G_Y, C_R

R constructs the remaining input needed to calculate MAC_2: MAC_2 = EDHOC-KDF(PRK_3e2m, TH_2, “MAC_2”, « ID_CRED_R, CRED_R, ? EAD_2 », mac_length_2) CRED_R is identified by a 64-bit hash:

where the COSE header value 34 (‘x5t’) indicates a hash of an X.509 certficate, and the COSE algorithm -15 indicates the hash algorithm SHA-256 truncated to 64 bits. ID_CRED_R (CBOR Data Item) (14 bytes) a1 18 22 82 2e 48 60 78 0e 94 51 bd c4 3c CRED_R is a byte string acting as a dummy X.509 certificate:

No external authorization data:

MAC_2 is computed through Expand() using the EDHOC hash algorithm, Section 4.2 of : MAC_2 = HKDF-Expand(PRK_3e2m, info, mac_length_2) Since METHOD = 0, mac_length_2 is given by the EDHOC hash algorithm. info for MAC_2 is:

where the last value is the output size of the EDHOC hash algorithm.

Since METHOD = 0, Signature_or_MAC_2 is the ‘signature’ of the COSE_Sign1 object. R constructs the message to be signed:

>, << TH_2, CRED_R, ? EAD_2 >>, MAC_2 ] = [ "Signature1", h'A11822822E4860780E9451BDC43C', h'58200782DBB687C30288A30B706B074BED789574573F24443E91833D68CDDD7F 9B39586F000102030405060708090A0B0C0D0E0F101112131415161718191A1B 1C1D1E1F202122232425262728292A2B2C2D2E2F303132333435363738393A3B 3C3D3E3F404142434445464748494A4B4C4D4E4F505152535455565758595A5B 5C5D5E5F606162636465666768696A6B6C6D6E', h'27C8F1E4A7AFF2A0F0BC0F918393EEF18B690C4D4C3D81BDFE22954240BCC4CC' ] ]]>

R signs using the private authentication key SK_R

R constructs the plaintext:

The input needed to calculate KEYSTREAM_2 is defined in Section 4.2 of , using Expand() with the EDHOC hash algorithm:

where length is the length of PLAINTEXT_2, and info for KEYSTREAM_2 is:

where the last value is the length of PLAINTEXT_2.

R calculates CIPHERTEXT_2 as XOR between PLAINTEXT_2 and KEYSTREAM_2:

R constructs message_2:

where G_Y_CIPHERTEXT_2 is the bstr encoding of the concatenation of the raw values of G_Y and CIPHERTEXT_2.

Since METHOD = 0, I authenticates using signatures with the EDHOC signature algorithm. I’s signature key pair using Ed25519 is (note that Ed448 would also be compatible with EdDSA):

PRK_4x3m is specified in Section 4.1.3 of . Since R authenticates with signatures PRK_4x3m = PRK_3e2m.

The transcript hash TH_3 is calculated using the EDHOC hash algorithm: TH_3 = H(TH_2, CIPHERTEXT_2)

I constructs the remaining input needed to calculate MAC_3:

>, mac_length_3) ]]> CRED_I is identified by a 64-bit hash:

where the COSE header value 34 (‘x5t’) indicates a hash of an X.509 certficate, and the COSE algorithm -15 indicates the hash algorithm SHA-256 truncated to 64 bits.

CRED_I is a byte string acting as a dummy X.509 certificate:

No external authorization data:

MAC_3 is computed through Expand() using the EDHOC hash algorithm, see Section 4.2 of :

Since METHOD = 0, mac_length_3 is given by the EDHOC hash algorithm. info for MAC_3 is:

where the last value is the output size of the EDHOC hash algorithm.

Since METHOD = 0, Signature_or_MAC_3 is the ‘signature’ of the COSE_Sign1 object. I constructs the message to be signed:

>, << TH_3, CRED_I, ? EAD_3 >>, MAC_3 ] = [ "Signature1", h'A11822822E4881D45BE06329D63A', h'58205AA25B46397C2F145EB792ED0D17EA2B078C73E4EE148780C3C2E7341372 CBAD5889000102030405060708090A0B0C0D0E0F101112131415161718191A1B 1C1D1E1F202122232425262728292A2B2C2D2E2F303132333435363738393A3B 3C3D3E3F404142434445464748494A4B4C4D4E4F505152535455565758595A5B 5C5D5E5F606162636465666768696A6B6C6D6E6F707172737475767778797A7B 7C7D7E7F808182838485868788', h'FC86E7D4F18B348C297C2FA3EB19529ACC3E0A4CB1BA99B69D16AAB19D333C12' ] ]]>

R signs using the private authentication key SK_R:

R constructs the plaintext:

I constructs the associated data for message_3:

I constructs the input needed to derive the key K_3, see Section 4.2 of , using the EDHOC hash algorithm:

where length is the key length of EDHOC AEAD algorithm, and info for K_3 is:

where the last value is the key length of EDHOC AEAD algorithm.

I constructs the input needed to derive the nonce IV_3, see Section 4.2 of , using the EDHOC hash algorithm:

where length is the nonce length of EDHOC AEAD algorithm, and info for IV_3 is:

where the last value is the nonce length of EDHOC AEAD algorithm.

I calculates CIPHERTEXT_3 as ‘ciphertext’ of COSE_Encrypt0 applied using the EDHOC AEAD algorithm with plaintext P_3, additional data A_3, key K_3 and nonce IV_3.

message_3 is the CBOR bstr encoding of CIPHERTEXT_3:

The transcript hash TH_4 is calculated using the EDHOC hash algorithm: TH_4 = H(TH_3, CIPHERTEXT_3)

No external authorization data:

R constructs the plaintext P_4:

R constructs the associated data for message_4:

R constructs the input needed to derive the EDHOC message_4 key, see Section 4.2 of , using the EDHOC hash algorithm:

where length is the key length of the EDHOC AEAD algorithm, and info for EDHOC_K_4 is:

where the last value is the key length of EDHOC AEAD algorithm.

R constructs the input needed to derive the EDHOC message_4 nonce, see Section 4.2 of , using the EDHOC hash algorithm:

where length is the nonce length of EDHOC AEAD algorithm, and info for EDHOC_IV_4 is:

where the last value is the nonce length of EDHOC AEAD algorithm.

R calculates CIPHERTEXT_4 as ‘ciphertext’ of COSE_Encrypt0 applied using the EDHOC AEAD algorithm with plaintext P_4, additional data A_4, key K_4 and nonce IV_4.

message_4 is the CBOR bstr encoding of CIPHERTEXT_4:

The derivation of OSCORE parameters is specified in Appendix A.2 of . The AEAD and Hash algorithms to use in OSCORE are given by the selected cipher suite:

The mapping from EDHOC connection identifiers to OSCORE Sender/Recipient IDs is defined in Appendix A.1 of . C_R is mapped to the Recipient ID of the server, i.e., the Sender ID of the client. Since C_R is a numeric, it is converted to a byte string equal to its CBOR encoded form.

C_I is mapped to the Recipient ID of the client, i.e., the Sender ID of the server. Since C_I is a numeric, it is converted to a byte string equal to its CBOR encoded form.

The OSCORE Master Secret is computed through Expand() using the Application hash algorithm, see Section 4.2 of :

where key_length is by default the key length of the Application AEAD algorithm, and info for the OSCORE Master Secret is:

where the last value is the key length of Application AEAD algorithm.

The OSCORE Master Salt is computed through Expand() using the Application hash algorithm, see Section 4.2 of :

where salt_length is the length of the OSCORE Master Salt, and info for the OSCORE Master Salt is:

where the last value is the length of the OSCORE Master Salt.

Key update is defined in Section 4.4 of .

The OSCORE Master Secret is derived with the updated PRK_4x3m:

where info and key_length are unchanged.

The OSCORE Master Salt is derived with the updated PRK_4x3m:

where info and salt_length are unchanged.

This document contains examples of EDHOC whose security considerations apply. The keys printed in these examples cannot be considered secret and must not be used.

There are no IANA considerations.