| Internet-Draft | Implementation Considerations for EDHOC | October 2023 |
| Tiloca | Expires 25 April 2024 | [Page] |
This document provides considerations for guiding the implementation of the authenticated key exchange protocol Ephemeral Diffie-Hellman Over COSE (EDHOC).¶
This note is to be removed before publishing as an RFC.¶
Discussion of this document takes place on the Lightweight Authenticated Key Exchange Working Group mailing list (lake@ietf.org), which is archived at https://mailarchive.ietf.org/arch/browse/lake/.¶
Source for this draft and an issue tracker can be found at https://gitlab.com/crimson84/draft-tiloca-lake-edhoc-implem-cons.¶
This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79.¶
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 25 April 2024.¶
Copyright (c) 2023 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 and restrictions with respect to this document. Code Components extracted from this document must include Revised BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Revised BSD License.¶
Ephemeral Diffie-Hellman Over COSE (EDHOC) [I-D.ietf-lake-edhoc] is a lightweight authenticated key exchange protocol, especially intended for use in constrained scenarios.¶
During the development of EDHOC, a number of side topics were raised and discussed, as emerging from reviews of the protocol latest design and from implementation activities. These topics were identified as strongly pertaining to the implementation of EDHOC rather than to the protocol in itself. Hence, they are not discussed in [I-D.ietf-lake-edhoc], which rightly focuses on specifying the actual protocol.¶
At the same time, implementors of an application using the EDHOC protocol or of an "EDHOC library" enabling its use cannot simply ignore such topics, and will have to take them into account throughout their implementation work.¶
In order to prevent multiple, independent re-discoveries and assessments of those topics, as well as to facilitate and guide implementation activities, this document collects such topics and discusses them through considerations about the implementation of EDHOC. At a high-level, the topics in question are summarized below.¶
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.¶
The reader is expected to be familiar with terms and concepts related to the EDHOC protocol and defined in [I-D.ietf-lake-edhoc].¶
This section considers the most common situation where, given a certain peer, only the application at that peer has visibility and control of both:¶
Building on the above, the following expands on three relevant cases concerning the handling of EDHOC sessions and application keys, in the event that any of those become invalid.¶
As a case in point to provide more concrete guidance, the following also considers the specific case where "applications keys" stands for the keying material and parameters that compose an OSCORE Security Context [RFC8613] and that are derived from an EDHOC session (see Appendix A.1 of [I-D.ietf-lake-edhoc]).¶
Nevertheless, the same considerations are applicable in case EDHOC is used to derive other application keys, e.g., to key different security protocols than OSCORE or to provide the application with secure values bound to an EDHOC session.¶
The application at a peer P may have learned that a completed EDHOC session S has to be invalidated. When S is marked as invalid, the application at P purges S and deletes each set of application keys (e.g., each OSCORE Security Context) that was generated from S.¶
As a possible reason, an authentication credential CRED_X may have expired, or P may have learned from a trusted source that CRED_X has been revoked. This effectively invalidates CRED_X, and therefore also invalidates any EDHOC session where CRED_X was used as authentication credential of either peer in the session (i.e., P itself or the other peer). In such a case, the application at P has to additionally delete CRED_X and any stored, corresponding identifier.¶
The application at a peer P may have learned that a set of application keys is not safe to use anymore. When such a set is specifically an OSCORE Security Context, the application may have learned that from the used OSCORE library or from an OSCORE layer that takes part to the communication stack.¶
A current set SET of application keys shared with another peer can become unsafe to use, for example, due to the following reasons.¶
When this happens, the application at the peer P proceeds as follows.¶
If the following conditions both hold, then the application moves to step 2. Otherwise, it moves to step 3.¶
The application at P runs the key update protocol mentioned at step 1 with the other peer, in order to update SET. When SET is specifically an OSCORE Security Context, this means that the application at P runs KUDOS with the other peer.¶
If the key update protocol terminates successfully, no further actions are taken. Otherwise, the application at P moves to step 3.¶
The application at the peer P performs the following actions.¶
The following considers two peers that use the ACE framework for authentication and authorization in constrained environments (ACE) [RFC9200], and specifically the EDHOC and OSCORE profile of ACE defined in [I-D.ietf-ace-edhoc-oscore-profile].¶
When doing so, one of the two peers acts as ACE Resource Server (RS) hosting protected resources. The other peer acts as ACE Client, requests from an ACE Authorization Server (AS) an Access Token that specifies access rights for accessing protected resources at the RS, and uploads the Access Token to the RS as part of the ACE workflow.¶
Consistent with the used EDHOC and OSCORE profile of ACE, the two peers run EDHOC in order to specifically derive an OSCORE Security Context as their shared set of application keys (see Appendix A.1 of [I-D.ietf-lake-edhoc]). In particular, the peer acting as ACE Client acts as EDHOC Initiator, while the peer acting as ACE RS acts as EDHOC Responder (see Section 2 of [I-D.ietf-lake-edhoc]).¶
Then, the peer acting as ACE Client can access the protected resources hosted at the other peer, according to the access rights specified in the Access Token. The communications between the two peers are protected by means of the established OSCORE Security Context, which in turn is bound to the used Access Token.¶
Later on, the application at one of the two peers P may have learned that the established OSCORE Security Context CTX is not safe to use anymore, e.g., from the used OSCORE library or from an OSCORE layer that takes part to the communication stack. The reasons that make CTX not safe to use anymore are the same ones discussed in Section 2.2 when considering a set of application keys in general, plus the event where the Access Token bound to CTX becomes invalid (e.g., it has expired or it has been revoked).¶
When this happens, the application at the peer P proceeds as follows.¶
If the following conditions both hold, then the application moves to step 2. Otherwise, it moves to step 3.¶
If the peer P supports the key update protocol KUDOS [I-D.ietf-core-oscore-key-update], then P runs KUDOS with the other peer, in order to update CTX. If the execution of KUDOS terminates successfully, no further actions are taken. Otherwise, if the execution of KUDOS does not terminate successfully, the application at P moves to step 3.¶
If the peer P does not support KUDOS altogether, then the application at P moves to step 3.¶
The application at the peer P performs the following actions.¶
A peer P relies on authentication credentials of other peers, in order to authenticate those peers when running EDHOC with them.¶
There are different ways for P to acquire an authentication credential CRED of another peer. For example, CRED can be supplied to P out-of-band by a trusted provider.¶
Alternatively, CRED can be specified by the other peer during the EDHOC execution with P. This relies on EDHOC message_2 or message_3, whose respective ID_CRED_R and ID_CRED_I can specify CRED by value, or instead a URI or other external reference where CRED can be retrieved from (see Section 3.5.3 of [I-D.ietf-lake-edhoc]).¶
When obtaining a new credential CRED, P has to validate it before storing it. The validation steps to perform depend on the specific type of CRED (e.g., a public key certificate [RFC5280][I-D.ietf-cose-cbor-encoded-cert]), and can rely on (the authentication credential of) a trusted third party acting as a trust anchor.¶
Upon retrieving a new CRED through ID_CRED_R/ID_CRED_I in a received EDHOC message and following the successful validation of CRED, the peer P stores CRED only if it assesses CRED to be also trusted, and must not store CRED otherwise.¶
An exception applies for the two unauthenticated operations described in Appendix D.5 of [I-D.ietf-lake-edhoc], where a trust relationship with an unknown or not-yet-trusted endpoint is established later. That is, CRED is verified out-of-band at a later stage, or an EDHOC session key is bound to an identity out-of-band at a later stage.¶
If P stores CRED, then P will consider CRED as valid and trusted until it possibly becomes invalid, e.g., because it expires or because P gains knowledge that it has been revoked.¶
When storing CRED, P should generate the authentication credential identifier(s) corresponding to CRED and store them as associated with CRED. For example, if CRED is a public key certificate, an identifier of CRED can be the hash of the certificate. In general, P should generate and associate with CRED one corresponding identifier for each type of authentication credential identifier that P supports and that is compatible with CRED.¶
In future executions of EDHOC with the other peer associated with CRED, this allows such other peer to specify CRED by reference, by indicating its credential identifier as ID_CRED_R/ID_CRED_I in the EDHOC message_2 or message_3 addressed to the peer P. In turn, this allows P to retrieve CRED from its local storage.¶
In order to determine whether to trust a valid authentication credential CRED retrieved through ID_CRED_R/ID_CRED_I of a received EDHOC message, the peer P can rely on and enforce one of the following trust policies.¶
PRE-KNOWLEDGE-ONLY (PKO): according to this policy, the peer P trusts CRED if and only if P is already storing CRED.¶
When P receives an EDHOC message with ID_CRED_R/ID_CRED_I, then P can continue the execution of EDHOC only if ID_CRED_R/ID_CRED_I specifies (by reference or by value) an authentication credential CRED such that P currently stores CRED and this is still valid (i.e., P believes CRED to not be expired or revoked).¶
LEARN-ON-FIRST-USE (LOFU): according to this policy, the peer P trusts CRED if and only if P is already storing CRED and/or a valid identifier of CRED.¶
The valid identifier may have been previously provisioned to P by a trusted entity. As an example, if CRED is a public key certificate, such an identifier can be the hash of the certificate. During an EDHOC execution, the identifier can be specified as ID_CRED_R/ID_CRED_I in the EDHOC message_2 or message_3 addressed to P.¶
The peer P performs the following steps, upon receiving an EDHOC message_2 or message_3 where ID_CRED_R/ID_CRED_I specifies CRED by value, or instead a URI or other external reference where CRED can be retrieved from.¶
P determines the possible identifiers associated with CRED, and checks whether any of those matches with an already stored identifier that is compatible with CRED.¶
For example, if CRED is a public key certificate, P can compute its associated hash. Instead, if CRED is a CWT [RFC8392], this can be as simple as retrieving the 'kid' field of the CWT.¶
In case P is not already storing any of those identifiers, P aborts the EDHOC session with the other peer, otherwise P moves to step 3.¶
TRUST-ON-FIRST-USE (TOFU): according to this policy, P trusts CRED even if P is not already storing CRED and/or a valid identifier of CRED.¶
The peer P performs the following steps, upon receiving an EDHOC message_2 or message_3 where ID_CRED_R/ID_CRED_I specifies CRED by value, or instead a URI or other external reference where CRED can be retrieved from.¶
Irrespective of the adopted trust policy, P actually uses CRED only if it is determined to be fine to use in the context of the ongoing EDHOC session, also depending on the specific identity of the other peer (see Sections 3.5 and D.2 of [I-D.ietf-lake-edhoc]). If this is not the case, P aborts the EDHOC session with the other peer.¶
This section describes an approach that EDHOC peers can use upon receiving EDHOC messages, in order to fetch/validate authentication credentials and to process External Authorization Data (EAD) items.¶
Per Section 9.1 of [I-D.ietf-lake-edhoc], the EDHOC protocol provides a transport mechanism for conveying EAD items, but specifications defining those items have to set the ground for "agreeing on the surrounding context and the meaning of the information passed to and from the application".¶
The approach described in this section aims to help implementors navigate the surrounding context mentioned above, irrespective of the specific EAD items conveyed in the EDHOC messages. In particular, the described approach takes into account the following points.¶
The fetching and validation of the other peer's authentication credential occur upon receiving EDHOC message_2 or message_3, once completed the message decryption. However, the validation of the other peer's authentication credential might depend on using the value of an EAD item, which in turn has to be validated first.¶
For instance, an EAD item within the EAD_2 field may contain a voucher to be used for validating the other peer's authentication credential (see [I-D.selander-lake-authz]).¶
Some EAD items may be processed only after having successfully verified the EDHOC message (i.e., after a successful verification of the Signature_or_MAC field).¶
For instance, an EAD item within the EAD_3 field may contain a Certificate Signing Request (CSR) [RFC2986]. Hence, such an EAD item can be processed only once the recipient peer has attained proof of the other peer possessing its private key.¶
In order to conveniently handle such processing, the application can prepare in advance one "side-processor object" (SPO), which takes care of the operations above during the EDHOC execution.¶
In particular, the application provides EDHOC with the SPO before starting an EDHOC execution, during which EDHOC will temporarily transfer control to the SPO at the right point in time, in order to perform the required side-processing of an incoming EDHOC message.¶
Furthermore, the application has to instruct the SPO about how to prepare any EAD item such that: it has to be included in the next outgoing EDHOC message; and it is independent of the processing of other EAD items included in the incoming EDHOC message. This includes, for instance, the preparation of padding EAD items.¶
At the right point in time during the processing of an incoming EDHOC message M at the peer P, EDHOC invokes the SPO and provides it with the following input:¶
The EAD items included in M.¶
Note that EDHOC might do some preliminary work on M before invoking the SPO, in order to provide the SPO only with actually relevant EAD items. This requires the application to additionally provide EDHOC with the ead_labels of the EAD items that the peer P recognizes (see Section 3.8 of [I-D.ietf-lake-edhoc]).¶
With such information available, EDHOC can early abort the current session in case M includes any EAD item which is both critical and not recognized by the peer P.¶
If no such EAD items are found, EDHOC can remove any padding EAD item (see Section 3.8.1 of [I-D.ietf-lake-edhoc]), as well as any EAD item which is neither critical nor recognized (since the SPO is going to ignore it anyway). As a result, EDHOC is able to provide the SPO only with EAD items that will be recognized and that require actual processing.¶
The SPO performs the following tasks on an incoming EDHOC message M.¶
When the SPO has completed its side processing and transfers control back to EDHOC, the SPO provides EDHOC with the produced EAD items to include in the EAD field of the next outgoing EDHOC message. The production of such EAD items can be triggered, e.g., by:¶
The following describes more in detail the actions performed by the SPO on the different, incoming EDHOC messages.¶
During the processing of an incoming EDHOC message_1, EDHOC invokes the SPO only once, after the Responder peer has successfully decoded the message and accepted the selected cipher suite.¶
If the EAD_1 field is present, the SPO processes the EAD items included therein.¶
Once all such EAD items have been processed the SPO transfers control back to EDHOC. When doing so, the SPO also provides EDHOC with any produced EAD items to include in the EAD field of the next outgoing EDHOC message.¶
Then, EDHOC resumes its execution and advances its protocol state.¶
During the processing of an incoming EDHOC message_4, EDHOC invokes the SPO only once, after the Initiator peer has successfully decrypted the message.¶
If the EAD_4 field is present, the SPO processes the EAD items included therein.¶
Once all such EAD items have been processed, the SPO transfers control back to EDHOC, which resumes its execution and advances its protocol state.¶
The following refers to message_X as an incoming EDHOC message_2 or message_3, and to "message verification" as the verification of Signature_or_MAC_X in message_X.¶
During the processing of a message_X, EDHOC invokes the SPO two times:¶
The pre-verification side processing occurs in two sequential phases, namely PHASE_1 and PHASE_2.¶
PHASE_1 - During PHASE_1, the SPO at the recipient peer P determines CRED, i.e., the other peer's authentication credential to use in the ongoing EDHOC session. In particular, the SPO performs the following steps.¶
The SPO determines CRED based on ID_CRED in message_X.¶
ID_CRED may specify CRED by value, or instead a URI or other external reference where CRED can be retrieved from. In such a case, if the retrieval of CRED fails, the SPO moves to step 9.¶
If ID_CRED ultimately points to an already installed authentication credential CRED, the SPO moves to step 2. Otherwise, the SPO moves to step 3.¶
The SPO determines if the stored CRED is currently valid, e.g., by asserting that CRED has not expired and has not been revoked.¶
Performing such a validation may require the SPO to first process an EAD item included in message_X. For example, it can be an EAD item in EDHOC message_2, which confirms or revokes the validity of CRED_R specified by ID_CRED_R, as the result of an OCSP process [RFC6960].¶
In case CRED is determined to be valid, the SPO moves to step 8. Otherwise, the SPO moves to step 9.¶
If this step has been reached, the peer P uses the trust policy LOFU (see Section 3). Consistently, the SPO checks if P is already storing a valid identifier of CRED.¶
If such an identifier is found, the SPO moves to step 6. Otherwise, the SPO moves to step 9.¶
The SPO determines if CRED is currently valid, e.g., by asserting that CRED has not expired and has not been revoked.¶
Performing such a validation may require the SPO to first process an EAD item included in message_X. For example, it can be an EAD item in EDHOC message_2 that: i) specifies a voucher for validating CRED_R as a CWT Claims Set (CCS) [RFC8392] transported by value in ID_CRED_R (see [I-D.selander-lake-authz]); or instead ii) an OSCP response [RFC6960] for validating CRED_R as a certificate transported by value or reference in ID_CRED_R.¶
In case CRED is determined to be valid, the SPO moves to step 7. Otherwise, the SPO moves to step 9.¶
The SPO checks if CRED is fine to use in the context of the ongoing EDHOC session, also depending on the specific identity of the other peer (see Sections 3.5 and D.2 of [I-D.ietf-lake-edhoc]).¶
If this is the case, then P uses CRED as authentication credential of the other peer in the ongoing EDHOC session, PHASE_1 ends, and the pre-verification side processing moves to PHASE_2. Otherwise, the SPO moves to step 9.¶
PHASE_2 - During PHASE_2, the SPO processes any EAD item included in message_X such that both the following conditions hold.¶
Once all such EAD items have been processed, the SPO transfers control back to EDHOC, which either aborts the ongoing EDHOC session or continues the processing of message_X with its corresponding message verification.¶
During the post-verification side processing, the SPO processes any EAD item included in message_X such that the processing of that EAD item had to wait for completing the successful message verification.¶
The late processing of such EAD items is typically due the fact that a pre-requirement has to be fulfilled first. That is, the recipient peer P has to have first asserted that the other peer does possess the private key corresponding to the public key of the other peer's authentication credential CRED determined during the pre-verification side processing (see Section 4.3.1). This requirement is fulfilled after a successful message verification of message_X.¶
Once all such EAD items have been processed, the SPO transfers control back to EDHOC. When doing so, the SPO also provides EDHOC with any produced EAD items to include in the EAD field of the next outgoing EDHOC message.¶
Then, EDHOC resumes its execution and advances its protocol state.¶
This document has no actions for IANA.¶
TBD¶