# EDHOC implementation guidelines

[toc]

## Invalidating an EDHOC Session

The application is the only thing having visibility of both:

* EDHOC and its sessions.

* The OSCORE Security Contexts, and the possible fact that they were established with EDHOC.

Assuming that EDHOC is used to key OSCORE, there are three cases that the application has to handle.

### Case 1

The application learns that an EDHOC session has to be invalidated.

For example, the application has learned (possibly from a trusted external source) that the authentication credential CRED_X of another EDHOC peer has expired or has been revoked.

When this happens, the application:

- Deletes CRED_X and any stored, corresponding identifier.
- Purges each existing EDHOC session S that was run with the other peer, such that CRED_X was the used autentication credential for the other peer.
- Purges each OSCORE Security Context that was generated from the EDHOC session S.

### Case 2

The application learns from the OSCORE library/layer that key usage limits have been reached in an OSCORE Security Context CTX, or that CTX has reached its expiration time.

When this happens, the application proceeds as follows.

1. If the following conditions both hold, move to step 2. Otherwise, move to step 3.

a. The peer supports KUDOS.
b. Since the completion of EDHOC, the application has received at least one valid message decrypted with CTX (i.e., the EDHOC session has been persisted).

2. Run KUDOS with the other peer, in order to update CTX. If KUDOS terminates successfully, no further actions are taken. Otherwise, move to step 3.

3. Perform the following actions.
* Purge CTX.
* Purge the EDHOC session from which CTX was generated, or from which its "oldest ancestor" OSCORE Security Context was generated before any key update occurred.
* Run again EDHOC with the other peer.

### Case 3

The EDHOC sessions and the OSCORE Security Context have been established as per the EDHOC profile of ACE.

The application learns from the OSCORE library/layer that key usage limits have been reached in an OSCORE Security Context CTX, or that CTX has reached its expiration time.

When this happens, the application proceeds as follows.

1. If the following conditions both hold, move to step 2. Otherwise, move to step 4.

a. The access token is still valid.
b. Since the completion of EDHOC, the application has received at least one valid message decrypted with CTX (i.e., the EDHOC session has been persisted).

2. If this peer supports KUDOS, run KUDOS with the other peer, in order to update CTX. If KUDOS terminates successfully, no further actions are taken, otherwise move to step 4.

If this peer does not support KUDOS, move to step 3 or to step 4, depending on this peer being the ACE Client or Resource Server, respectively.

3. This peer, i.e., the ACE Client and EDHOC Initiator, re-uploads the same access token to the ACE Resource Server, thus triggering EDHOC-KeyUpdate() and the update of CTX by deriving new OSCORE keying material with EDHOC-Exporter(). If this terminates successfully, no further actions are taken. Otherwise, move to step 4.

4. Perform the following actions.
* Purge CTX.
* Purge the EDHOC session from which CTX was generated, or from which its "oldest ancestor" OSCORE Security Context was generated before any key update occurred.
* If the access token is not valid, the ACE Client obtains a new one and uploads it to the ACE Resource Server.
* Run again EDHOC with the other peer.

## Trusting Authentication Credentials

A new authentication credential received during an EDHOC execution MUST be validated, e.g., by means of a successful authenticated decryption or signature verification.

More specifically, an actual cryptographic validation process applies to authentication credentials that are protected by a cryptographic armor around it (like, e.g., in the case of a CWT or a signed certificate).

Instead, when applied to an unprotected authentication credential (like, e.g, in the case of a CCS), the "validation" process is typically limited to checking that the authentication credential is not malformed, i.e., that it is semantically and syntactically correct.

Besides having been validated, a new authentication credential MUST also be trusted before it can be installed. This differs depending on the specifically used trust model.

That is, there are different ways for a peer A to establish trust in the authentication credential of another peer B, and learn it before installing it. These can be expressed by having the following two features switched on or off on peer A:

- LOFU: Learn On First Use. That is, it is fine to learn and install a new valid authentication credential, as long as a corresponding trusted identifier is already pre-installed.

- TOFU: Trust On First Use. That is, it is fine to unconditionally learn and install a new valid authentication credential.

An installed authentication credential is safely assumed to be valid and trusted, until its expiration or its explicit invalidation occurs (e.g., due to revocation).

That is, at any point in time, an installed authentication credential is ensured to have been validated upon its installation. Hence, unless explicitly required or signaled (e.g., through an EAD item), it is not needed to validate again an authentication credential, when this is specified by value or reference in ID_CRED_X of an incoming EDHOC message and it is currently available among the installed ones.

Note that an incoming EDHOC message can include an EAD item that states whether an authentication credential CRED_X is still valid or not. In such a case, the following applies.

* Such an EAD item must be processed before any further consideration of the CRED_X specified by ID_CRED_X (by value or by reference), for possible use in the EDHOC session.
* If the EAD item states that CRED_X is valid, the message processing continues by attempting to determine CRED_X from ID_CRED_X, with the exact steps depending on the used trust model.
* If the EAD item states that CRED_X is not valid, the message processing stops and the EDHOC execution is aborted. In particular, if ID_CRED_X specifies an already stored CRED_X, then such CRED_X is removed from local storage, together with any corresponding credential identifier.

A case in point is the reception at the Initiator of an EAD_2 item that confirms/revokes the validy of CRED_R, as the result of an OCSP process. The CRED_R in question can be either specified by value in ID_CRED_R, or be already stored at the Initiator and specified by reference (or, even if unlikely, by value) in ID_CRED_R.

The following does NOT cover two cases of "Unauthenticated Operation" (see Appendix D.5 of draft-ietf-lake-edhoc) where, only at a later stage, an EDHOC authentication credential is verified out-of-band or an EDHOC session key is bound to an identity out-of-band.

### Trust model 1 - Pre-knowledge-only

LOFU = false
TOFU = false

Since LOFU = false and TOFU = false, the peer A needs to have the authentication credential of the other peer B pre-installed, before running EDHOC.

That is, during an EDHOC execution, the peer A does not record (LOFU = false) and does not trust (TOFU = false) any **new** authentication credential that it does not know already, when specified by value in the ID_CRED_X field of an incoming EDHOC message.

Instead, the peer A relies only on those authentication credentials that it knows already, as previously provisioned by a trusted entity and properly verified.

That is, when receiving an EDHOC message with ID_CRED_X from the peer B, EDHOC can continue only if ID_CRED_X specifies (by reference or by value) an authentication credential that:

* the peer A already knows; and

* is still valid (e.g., there is no explicit indication that it is expired or that it has been revoked); and

* is determined to be fine to use in the context of the ongoing EDHOC session. This is aligned with the following points:

* From Section 3.5.0 of the EDHOC draft:

> In particular, the authentication credential needs to be validated in the context of the connection for which EDHOC is used

* From Appendix D.2 of the EDHOC draft:

> The application must decide on allowing a connection or not depending on the intended endpoint, and in particular whether it is a specific identity or in a set of identities.

### Trust model 2 - Pre-knowledge + LOFU

LOFU = true
TOFU = false

Since LOFU = true, the peer A is fine to learn **new** authentication credentials during an EDHOC execution. That is, they do not necessarily need to be pre-provisioned by a trusted entity.

However, since TOFU = false, before running EDHOC the peer A needs to have pre-installed at least **some** trusted information about the authentication credential of the other peer B.

This is a pre-installed identifier, that has been previously provisioned by a trusted entity. For example, the identifier can be in the form of a certificate hash of a certificate, which instead is going to be later transported by value in ID_CRED_X of an EDHOC message from the peer B.

* GS: As another example, this can be a trust anchor in the form of a CA root public key, against which the root certificate in a certificate chain is validated.
* MT: I am not sure about this. A CA root public key would be used for verifying the authentication credential learned during the EDHOC execution, which of course has to be verified. However, this is equivalent to "learning any new authentication credential as long as it passes verification"; this is basically TOFU, which is disabled in this configuration and comes in the next configuration. Also, it quickly opens for identifier collisions, since the same identifier is likely to be applicable to multiple authentication credentials.

The peer A performs the following actions when receiving a **new** authentication credential of the other peer B, as specified by value in the ID_CRED_X field of an EDHOC message from B.

1. The peer A validates the authentication credential, e.g., by verifying the chain of related signatures. In case of failed validation, the EDHOC execution is aborted, otherwise A moves to step 2.

2. The peer A recomputes the identifier associated to the authentication credential, and verifies that it matches with the pre-installed identifier. In case of negative match, the EDHOC execution is aborted, otherwise A moves to step 3.

3. The peer A validates the received authentication credential specified in ID_CRED_X. If the validation process is not successful, the EDHOC execution is aborted. Otherwise, the peer trusts and installs the authentication credential and then moves to step 4.

* GS: This seems like a mix between verifying a certificate chain against a trust anchor, and verifying a certificate against a certificate hash. Both cases are valid and should be described.
* MT: Both things are necessary and have different purposes. The first step is about verifying that the authentication credential is intact and issued by the alleged issuer. The second step is about validating that one of the pre-installed trusted identifiers (e.g., an x5t certificate hash) is indeed consistent with the authentication credential in questions.

4. The peer actually uses the new authentication credential if this is determined fine to use in the context of the ongoing EDHOC session. This is aligned with the following points:

* From Section 3.5.0 of the EDHOC draft:

> In particular, the authentication credential needs to be validated in the context of the connection for which EDHOC is used

* From Appendix D.2 of the EDHOC draft:

> The application must decide on allowing a connection or not depending on the intended endpoint, and in particular whether it is a specific identity or in a set of identities.

That is, when receiving an EDHOC message with ID_CRED_X from the peer B, EDHOC can continue only if ID_CRED_X: i) specifies (by reference or by value) a still valid authentication credential that the peer A already knows and that is determined fine to be used for the ongoing EDHOC session, as defined for "Configuration 1"; or ii) passes the four steps above, by virtue of a LOFU policy.

### Trust model 3 - Pre-knowledge + TOFU

LOFU = true
TOFU = true

(practically, a TOFU policy overshadows a LOFU policy)

Since LOFU = true and TOFU = true, it is fine if, before running EDHOC, the peer A neither has pre-installed the authentication credential of the other peer B, nor has pre-installed a corresponding identifier.

That is, as long as they are valid, the peer A is fine to learn new authentication credentials during an EDHOC execution, without knowing anything at all about them in advance. Hence, neither the authentication credentials nor a corresponding trusted identifier are needed to have been pre-installed at the peer by a trusted entity.

The peer A performs the following actions when receiving a **new** authentication credential of the other peer B, as specified by value in the ID_CRED_X field of an EDHOC message from B.

1. The peer A validates the authentication credential, e.g., by verifying the chain of related signatures. In case of failed validation, the EDHOC execution is aborted, otherwise A moves to step 2.

2. The peer A computes the identifier of the credential. If A has the identifier of the authentication credential as pre-installed and trusted, then A asserts that the recomputed identifier matches with the pre-installed identifier. In case of negative match, the EDHOC execution is aborted, otherwise A moves to step 3.

* GS: I don't understand why this step is necessary.
* MT: It is a consistency check. For some reason, the peer A might have a pre-installed certificate hash as trusted identifier of the authentication credential. Even though TOFU in itself admits the learning of any authentication credential that is valid, in this case the peer A has to ensure consistency with the pre-installed identifier before installing the authentication credential.

3. The peer A validates the received authentication credential specified in ID_CRED_X. If the validation process is not successful, the EDHOC execution is aborted. Otherwise, the peer trusts and installs the authentication credential together with the computed identifier if this was not installed already, and then moves to step 4.

4. The peer A can use the authentication credential of B in the current EDHOC execution, if the authentication credential is determined fine to be used for the ongoing EDHOC session. Otherwise, the peer A aborts the EDHOC execution. This is aligned with the following points:

* From Section 3.5.0 of the EDHOC draft:

> In particular, the authentication credential needs to be validated in the context of the connection for which EDHOC is used

* From Appendix D.2 of the EDHOC draft:

> The application must decide on allowing a connection or not depending on the intended endpoint, and in particular whether it is a specific identity or in a set of identities.

That is, when receiving an EDHOC message with ID_CRED_X from the peer B, EDHOC can continue only if ID_CRED_X: i) specifies (by reference or by value) a still valid authentication credential that the peer A already knows and that is determined fine to be used for the ongoing EDHOC session, as defined for "Configuration 1"; or ii) passes the four steps above, by virtue of a TOFU policy.

## Processing of Authentication Credentials and EAD Items

The following tries to provide a general framework for fetching/validating authentication credentials as well as for processing EAD items, upon receiving an EDHOC message.

As per Section 8.1 of the EDHOC draft:

> Designing a secure mechanism that uses EAD is not necessarily straightforward. This document only provides the EAD transport mechanism, but the problem of agreeing on the surrounding context and the meaning of the information passed to and from the application remains. Any new uses of EAD should be subject to careful review.

While EAD-specific documents are intended to specify the meaning of information passed to and from applications through new EAD items, the proposed general framework attempts to guide implementors in navigating the "surrounding context" mentioned above, irrespective of the specific EAD items. In particular, it takes into account that:

* 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.
* The validation of the other peer's authentication credential might depend on using the content of an EAD item to be validated first. For instance, EAD_2 may contain a Voucher to be used for validating the other peer's authentication credential.
* Some EAD items may be processed only after verifying the EDHOC message (e.g., after successfully verifying Signature_or_MAC). For instance, EAD_3 may contain an Entity Attestation Token (EAT) or a Certificate Signing Request (CSR), hence it can be processed only once the recipient peer has attained proof of the other peer possessing its private key.

The application can prepare in advance one "processor object" that takes care of the operations above. The application provides EDHOC with the processor object before starting the EDHOC execution, then EDHOC will transfer control to the processor object at the right point in time.

The goal of a processor object is to perform: i) for message_2 and message_3, fetching and/or validation of the other peer's authentication credential CRED_X, based on the ID_CRED_X in the incoming EDHOC message; ii) processing of the EAD items conveyed in the incoming EDHOC message.

Furthermore, the processor object will store and make available to the application the results of the operations it has performed. Also, it will make available to EDHOC the EAD items to be included in the next outgoing EDHOC message.

The application has to provide EDHOC with access to such a processor object, and has to provide the processor objects with instructions about how to prepare any EAD item that is independent of the processing of EAD items from incoming messages.

When processing an incoming EDHOC message, at the right point in time, the peer invokes the processor object. EDHOC provides the following input to the processing object:

- The current EDHOC session associated with the current EDHOC execution, and the full set of related information. This especially includes the selected cipher suite and the ephemeral Diffie-Hellman public keys G_X and G_Y that the two peers have exchanged.
- The set of other peers' authentication credentials that this peer stores.
- All the decrypted information elements from the incoming EDHOC message.
- EAD items from the incoming EDHOC message.
- Note that EDHOC itself might do some preliminary work, in order to pass to the processor objects only relevant EAD items. This requires the application to provide EDHOC with the ead_labels of the understood EAD items.
Then, EDHOC can abort in case the incoming message includes any critical and not understood EAD item. Otherwise, EDHOC can remove any padding EAD item, as well as any non critical and not understood EAD item. After that, EDHOC will provide the processor object with only understood EAD item.
- The processor object might actually need to store all the processed EAD items throughout the whole EDHOC execution.
- When processing an incoming message_2 or message_3, an indication of whether this invocation is happening before or after the message verification.

### Incoming EDHOC message_1

The processor object is invoked only once, after the Responder has successfully decoded the message and accepted the selected cipher suite.

The processor object processes the EAD_1 items, if present.

### Incoming EDHOC message_4

The processor object is invoked only once, after the Initiator has successfully decrypted the message.

The processor object processes the EAD_4 items, if present.

### Incoming EDHOC message_2 / message_3

In the following, "message verification" refers to the verification of Signature_or_MAC_X for the incoming EDHOC message_X.

The processor object is invoked twice, i.e.: i) right after the message has been decrypted (pre-verification processing); and ii) right after the message has been successfully verified (post-verification processing).

**Pre-verification processing**

This invocation occurs right after having decrypted the message.

The following operations are performed.

* Phase 1 - Determine the other peer's authentication credential CRED_X to use.

1. Determine CRED_X based on ID_CRED_X.

Note that ID_CRED_X can specify CRED_X by value, or the URI of a resource at a trusted repository or a credential identifier relevant at an already-known trusted repository from which CRED_X can be retrieved. In such a case, if the retrieval of CRED_X fails, go to step 9.

If CRED_X ultimately points to an already installed CRED_X, go to step 2. Otherwise, go to step 3.

* The typical way to find an already installed CRED_X is by leveraging ID_CRED_X in the incoming message.
* As an alternative, the recipient peer might have a specific CRED_X to be used as the other peer's authentication credential for this EDHOC session. In such a case, the ID_CRED_X in the incoming message may be a dummy sentinel value.
A case in point is the **old design** [draft-selander-ace-ake-authz](https://datatracker.ietf.org/doc/draft-selander-ace-ake-authz/), where the Domain Authenticator acting as EDHOC Responder uses exactly a CCS learned from the external Authorization Server as authentication credential CRED_I of the other peer. In order to limit the overhead, ID_CRED_I in EDHOC message_3 specifies an empty CBOR byte string as 'kid' value.
2. Determine if the stored CRED_X is still valid. In case of positive outcome, move to step 8. Otherwise, move to step 9.
* The validation process may rely on an EAD item included in the incoming message, e.g., an EAD_2 item that confirms/revokes the validy of CRED_R indicated by ID_CRED_R, as the result of an OCSP process.
3. In case of Pre-knowledge-only trust model, go to step 9. Otherwise, go to step 4.
4. In case of Pre-knowledge + TOFU trust model, go to step 6. Otherwise, move to step 5.
5. This is the case of Pre-knowledge + LOFU trust model. Then, check if an identifier corresponding to CRED_X is pre-installed. If such an identifier is found, go to step 6. Otherwise, go to step 9.
6. Validate CRED_X. In case of successful validation, go to step 7. Otherwise, go to step 9.
* The validation may require to first process an EAD item (e.g., when EAD_2 specifies a Voucher for validating CRED_R as a CCS transported by value in ID_CRED_R, or an OSCP response for validating CRED_R as a certificate transported by value or reference in ID_CRED_R).
* Generally, a CCS can be only semantically and syntactically validated. Instead, it's certificates/CWTs/... that have to be validated more extensively and cryptographically, e.g., by verifying a chain of signatures.
7. CRED_X is stored as valid and trusted, by also pairing it with the corresponding identifiers of all the identifer types supported by this peer. Then, go to step 8.
8. If CRED_X is determined good to use in the context of the ongoing EDHOC session, then CRED_X is used as authentication credential of the other peer, Phase 1 finishes and the process moves to Phase 2. Otherwise, go to step 9.
9. A valid authentication credential to use was not found. Abort EDHOC.

* Phase 2 - Process EAD items

If the incoming message includes EAD items that have **not** been processed already during phase 1 and that can be processed before message verification, then the processing associated with such EAD items is carried out.

Once all the EAD items have been processed, EDHOC continues with the verification of the incoming message.

**Post-verification processing**

This invocation occurs right after having successfully verified the incoming EDHOC message.

If the incoming message includes EAD items associated with processing to be performed after message verification, such processing is carried out.

Such post-verification processing typically requires this peer to have asserted that the other peer does possess the private key corresponding to the public key of the other peer's used authentication credential. This is achieved after a successful verification of the incoming EDHOC message.