Lightweight Authorization using Ephemeral Diffie-Hellman Over COSE

1.1. Terminology

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.¶

Readers are expected to have an understanding of CBOR [RFC8949] and EDHOC [I-D.ietf-lake-edhoc]. Appendix C.1 of [I-D.ietf-lake-edhoc] contains some basic info about CBOR.¶

3.1. Device (U)

To authenticate to V, the device (U) runs EDHOC in the role of Initiator with authentication credential CRED_U, for example, an X.509 certificate or a CBOR Web Token (CWT, [RFC8392]). CRED_U may, for example, be carried in ID_CRED_I of EDHOC message_3 or be provisioned to V over a non-constrained network, see bottom of Figure 3.¶

U also needs to identify itself to W, this device identifier is denoted by ID_U. The purpose of ID_U is for W to be able to determine if the device with this identifier is authorized to enroll with V. ID_U may be a reference to CRED_U, like ID_CRED_I in EDHOC (see Section 3.5.2 of [I-D.ietf-lake-edhoc]), or a device identifier from a different name space, such as EUI-64 identifiers.¶

U is also provisioned with information about W:¶

• A static public DH key of W (G_W) used to establish secure communication with the enrollment server (see Section 4.4).¶

• Location information about the enrollment server (LOC_W) that can be used by V to reach W. This is typically a URI but may alternatively be only the domain name.¶

3.2. Domain Authenticator (V)

To authenticate to U, the domain authenticator (V) runs EDHOC in the role of Responder with an authentication credential CRED_V, which is a CWT Claims Set [RFC8392] containing a public key of V, see Section 4.5.2.1. This proves to U the possession of the private key corresponding to the public key of CRED_V. CRED_V typically needs to be transported to U in EDHOC (using ID_CRED_R = CRED_V, see Section 3.5.2 of [I-D.ietf-lake-edhoc]) since there is no previous relation between U and V.¶

V and W need to establish a secure (confidentiality and integrity protected) connection for the Voucher Request/Response protocol. Furthermore, W needs access the same credential CRED_V as V used with U, and V needs to prove to W the possession of the private key corresponding to the public key of CRED_V. It is RECOMMENDED that V authenticates to W using the same credential CRED_V as with U.¶

• V and W may protect the Voucher Request/Response protocol using TLS 1.3 with client authentication [RFC8446] if CRED_V is an X.509 certificate of a signature public key. However, note that CRED_V may not be a valid credential to use with TLS 1.3, e.g., when U and V run EDHOC with method 1 or 3, where the public key of CRED_V is a static Diffie-Hellman key.¶

• V may run EDHOC with W using ID_CRED_I = CRED_V. In this case the secure connection between V and W may be based on OSCORE [RFC8613].¶

Note that both TLS 1.3 and EDHOC may be run between V and W during this setup procedure. For example, W may authenticate to V using TLS 1.3 with server certificates signed by a CA trusted by V, and then V may run EDHOC using CRED_V over the secure TLS connection to W, see Figure 3.¶

Note also that the secure connection between V and W may be long lived and reused for multiple voucher requests/responses.¶

Other details of proof-of-possession related to CRED_V and transport of CRED_V are out of scope of this document.¶

3.3. Enrollment Server (W)

The enrollment server (W) is assumed to have the private DH key corresponding to G_W, which is used to establish secure communication with the device (see Section 4.4). W provides to U the authorization decision for enrollment with V in the form of a voucher (see Section 4.4.2). Authorization policies are out of scope for this document.¶

Authentication credentials and communication security with V is described in Section 3.2. To calculate the voucher, W needs access to message_1 and CRED_V as used in the EDHOC session between U and V, see Section 4.4.2.¶

• W MUST verify that CRED_V is bound to the secure connection between W and V¶

• W MUST verify that V is in possession of the private key corresponding to the public key of CRED_V¶

W needs to be available during the execution of the protocol between U and V.¶

4.1. Overview

The protocol consist of three security sessions going on in parallel:¶

1. The EDHOC session between device (U) and (domain) authenticator (V)¶

2. Voucher Request/Response between authenticator (V) and enrollment server (W)¶

3. An exchange of voucher-related information, including the voucher itself, between device (U) and enrollment server (W), mediated by the authenticator (V).¶

Figure 3 provides an overview of the message flow detailed in this section. An outline of EDHOC is given in Section 3 of [I-D.ietf-lake-edhoc].¶

4.2. Reuse of EDHOC

The protocol illustrated in Figure 3 reuses several components of EDHOC:¶

• G_X, the ephemeral public Diffie-Hellman key of U, is also used in the protocol between U and W.¶

• SUITES_I includes the cipher suite for EDHOC selected by U, and also defines the algorithms used between U and W (see Section 3.6 of [I-D.ietf-lake-edhoc]):¶

  • EDHOC AEAD algorithm: used to encrypt ID_U¶

  • EDHOC hash algorithm: used for key derivation and to calculate the voucher¶

  • EDHOC MAC length in bytes: length of the voucher¶

  • EDHOC key exchange algorithm: used to calculate the shared secret between U and W¶

• EAD_1, EAD_2 are the External Authorization Data message fields of message_1 and message_2, respectively, see Section 3.8 of [I-D.ietf-lake-edhoc]. This document specifies the EAD items with ead_label = TBD1, see Section 7.1).¶

• ID_CRED_I and ID_CRED_R are used to identify the authentication credentials CRED_U and CRED_V, respectively. As shown at the bottom of Figure 3, V may use W to obtain CRED_U. CRED_V is transported in ID_CRED_R in message_2, see Section 4.5.2.1.¶

The protocol also reuses the EDHOC-Extract and EDHOC-Expand key derivation from EDHOC (see Section 4 of [I-D.ietf-lake-edhoc]).¶

• The intermediate pseudo-random key PRK is derived using EDHOC-Extract():¶

  • PRK = EDHOC-Extract(salt, IKM)¶

    • where salt = 0x (the zero-length byte string)¶

    • IKM is computed as an ECDH cofactor Diffie-Hellman shared secret from the public key of W, G_W, and the private key corresponding to G_X (or v.v.), see Section 5.7.1.2 of [NIST-800-56A].¶

The output keying material OKM is derived from PRK using EDHOC-Expand(), which is defined in terms of the EDHOC hash algorithm of the selected cipher suite, see Section 4.2 of [I-D.ietf-lake-edhoc]:¶

• OKM = EDHOC-Expand(PRK, info, length)¶

  where¶

info = (
   info_label : int,
   context : bstr,
   length : uint,
)

4.3. Stateless Operation of V

V may act statelessly with respect to U: the state of the EDHOC session started by U may be dropped at V until authorization from W is received. Once V has received EDHOC message_1 from U and extracted LOC_W from EAD_1, message_1 is forwarded unmodified to W in the form of a Voucher Request. V encapsulates the internal state that it needs to later respond to U, and sends that to W together with EDHOC message_1. This state typically contains U's IP address and port number, together with any other implementation-specific parameter needed by V to respond to U. At this point, V can drop the EDHOC session that was initiated by U.¶

V MUST encrypt and integrity protect the encapsulated state using a uniformly-distributed (pseudo-)random key, known only to itself. How V serializes and encrypts its internal state is out of scope of this specification. For example, V may use the existing CBOR and COSE libraries.¶

Editor's note: Consider to include an example of serialized internal state.¶

W sends to V the voucher together with echoed message_1, as received from U, and V's internal state. This allows V to act as a simple message relay until it has obtained the authorization from W to enroll U. The reception of a successful Voucher Response at V from W implies the authorization for V to enroll U. At this point, V can initialize a new EDHOC session with U, based on the message and the state retrieved from the Voucher Response from W.¶

4.4. Device <-> Enrollment Server (U <-> W)

The protocol between U and W is carried between U and V in message_1 and message_2 (Section 4.5), and between V and W in the Voucher Request/Response (Section 4.6). The data is protected between the endpoints using secret keys derived from a Diffie-Hellman shared secret (see Section 4.2) as further detailed in this section.¶

Voucher_Info = bstr .cbor Voucher_Info_Seq

Voucher_Info_Seq = (
    LOC_W:      tstr,
    ENC_U_INFO:     bstr
)

plaintext = (
    ID_U:            bstr,
    ?OPAQUE_INFO:    bstr,
)

external_aad = (
    SS:              int,
)

Voucher = COSE_Encrypt0.ciphertext

plaintext = (
    ?OPAQUE_INFO: bstr
)

external_aad = (
    H(message_1):  bstr,
    CRED_V:        bstr,
)

4.5. Device <-> Authenticator (U <-> V)

This section describes the processing in U and V, which include the EDHOC protocol, see Figure 3. Normal EDHOC processing is omitted here.¶

4.6. Authenticator <-> Enrollment Server (V <-> W)

It is assumed that V and W have set up a secure connection, W has accessed the authentication credential CRED_V to be used in the EDHOC session between V and with U, and that W has verified that V is in possession of the private key corresponding to CRED_V, see Section 3.2 and Section 3.3. V and W run the Voucher Request/Response protocol over the secure connection.¶

Voucher_Request = [
    message_1:      bstr,
    ? opaque_state: bstr
]

Voucher_Response = [
    message_1:      bstr,
    Voucher:        bstr,
    ? opaque_state: bstr
]

4.7. Error Handling

This section specifies a new EDHOC error code and how it is used in the proposed protocol.¶

error_content = (
  REJECT_TYPE : int,
  ? REJECT_INFO : bstr,
)

plaintext = (
    OPAQUE_INFO:     bstr,
 )

external_aad = (
    H(message_1):    bstr,
 )

5.1. Scheme "https"

In case the scheme indicates "https", V MUST perform a TLS handshake with W and use HTTP. If the authentication credential CRED_V can be used in a TLS handshake, e.g. an X.509 certificate of a signature public key, then V SHOULD use it to authenticate to W as a client. If the authentication credential CRED_V cannot be used in a TLS handshake, e.g. if the public key is a static Diffie-Hellman key, then V SHOULD first perform a TLS handshake with W using available compatible keys. V MUST then perform an EDHOC session over the TLS connection proving to W the possession of the private key corresponding to CRED_V. Performing the EDHOC session is only necessary if V did not authenticate with CRED_V in the TLS handshake with W.¶

Editor's note: Clarify that performing TLS handshake is not necessary for each device request; if there already is a TLS connection between V and W that should be reused. Similar considerations for 5.2 and 5.3.¶

5.2. Scheme "coaps"

In case the scheme indicates "coaps", V SHOULD perform a DTLS handshake with W and access the resources defined in Section 5.4 using CoAP. The normative requirements in Section 5.1 on performing the DTLS handshake and EDHOC session remain the same, except that TLS is replaced with DTLS.¶

5.3. Scheme "coap"

In case the scheme indicates "coap", V SHOULD perform an EDHOC session with W, as specified in Appendix A of [I-D.ietf-lake-edhoc] and access the resources defined in Section 5.4 using OSCORE and CoAP. The authentication credential in this EDHOC session MUST be CRED_V.¶

5.4. URIs

The URIs defined below are valid for both HTTP and CoAP. W MUST support the use of the path-prefix "/.well-known/", as defined in [RFC8615], and the registered name "lake-authz". A valid URI in case of HTTP thus begins with¶

• "https://www.example.com/.well-known/lake-authz"¶

In case of CoAP with DTLS:¶

• "coaps://example.com/.well-known/lake-authz"¶

In case of EDHOC and OSCORE:¶

• "coap://example.com/.well-known/lake-authz"¶

Each operation specified in the following is indicated by a path-suffix.¶

7.1. EDHOC External Authorization Data Registry

IANA has registered the following entry in the "EDHOC External Authorization Data" registry under the group name "Ephemeral Diffie- Hellman Over COSE (EDHOC)". The ead_label = TBD1 corresponds to the ead_value Voucher_Info in EAD_1, and Voucher in EAD_2 with processing specified in Section 4.5.1 and Section 4.5.2, respectively, of this document.¶

7.2. The Well-Known URI Registry

IANA has registered the following entry in "The Well-Known URI Registry", using the template from [RFC8615]:¶

• URI suffix: lake-authz¶

• Change controller: IETF¶

• Specification document: [[this document]]¶

• Related information: None¶

7.3. Well-Known Name Under ".arpa" Name Space

This document allocates a well-known name under the .arpa name space according to the rules given in [RFC3172] and [RFC6761]. The name "lake-authz.arpa" is requested. No subdomains are expected, and addition of any such subdomains requires the publication of an IETF Standards Track RFC. No A, AAAA, or PTR record is requested.¶

7.4. Media Types Registry

IANA has added the media types "application/lake-authz-voucherrequest+cbor" to the "Media Types" registry.¶

7.5. CoAP Content-Formats Registry

IANA has added the media type "application/lake-authz-voucherrequest+cbor" to the "CoAP Content-Formats" registry under the registry group "Constrained RESTful Environments (CoRE) Parameters".¶

A.1. Network Discovery

When a device first boots, it needs to discover the network it attempts to join. The network discovery procedure is defined by the link-layer technology in use. In case of Time-slotted Channel Hopping (TSCH) networks, a mode of [IEEE802.15.4], the device scans the radio channels for Enhanced Beacon (EB) frames, a procedure known as passive scan. EBs carry the information about the network, and particularly the network identifier. Based on the EB, the network identifier, the information pre-configured into the device, the device makes the decision on whether it should join the network advertised by the received EB frame. This process is described in Section 4.1 of [RFC9031]. In case of other, non-TSCH modes of IEEE 802.15.4 it is possible to use the active scan procedure and send solicitation frames. These solicitation frames trigger the nearest network coordinator to respond by emitting a beacon frame. The network coordinator emitting beacons may be multiple link-layer hops away from the domain authenticator (V), in which case it plays the role of a Join Proxy (see [RFC9031]). Join Proxy does not participate in the protocol and acts as a transparent router between the device and the domain authenticator. For simplicity, Figure 6 illustrates the case when the device and the domain authenticator are a single hop away and can communicate directly.¶

A.2. The Enrollment Protocol with Parameter Provisioning

B.1. Domain Authenticator hints

In case W denies the enrollment of U to a given V, a list of Domain Authenticator hints (v_hint) can be sent from W to U. The hint is optional and is included in the REJECT_INFO item in the Access Denied error message. It consists of a list of application-defined identifiers of V (e.g. MAC addresses, SSIDs, PAN IDs, etc.), as defined below:¶

v_hint = [ 1* bstr ]¶

B.2. Device Hints

U may send a Device hint (u_hint) so that it can help W to select which Vs to include in v_hint. This can be useful in large scale scenarios with many gateways (V). The hint is an optional field included in the OPAQUE_INFO field within EAD_1, and it must be encrypted. The hint itself is application dependent, and can contain GPS coordinates, application-specific tags, the list of Vs detected by U, or other relevant information. It is defined as follows:¶

u_hint: [ 1* bstr ]¶

C.1. Minimal

This is a simple example that demonstrates successful execution of the protocol.¶

Premises:¶

• device u1 has ID_U = key id = 14¶

• the access policy in W specifies, via a list of ID_U, that device u1 can enroll via any domain authenticator, i.e., the list contains ID_U = 14. In this case, the policy only specifies a restriction in terms of U, effectively allowing enrollment via any V.¶

Execution:¶

1. device u1 discovers a gateway (v1) and tries to enroll¶

2. gateway v1 identifies the zero-touch join attempt by checking that the label of EAD_1 = TBD1, and prepares a Voucher Request using the information contained in the value of EAD_1¶

3. upon receiving the request, W obtains ID_U = 14, authorizes the access, and replies with Voucher Response¶

C.2. Wrong gateway

In this example, a device u1 tries to enroll a domain via gateway v1, but W denies the request because the pairing (u1, v1) is not configured in its access policies.¶

This example also illustrates how the REJECT_INFO field of the EDHOC error Access Denied could be used, in this case to suggest that the device should select another gateway for the join procedure.¶

Premises:¶

• devices and gateways communicate via Bluetooth Low Energy (BLE), therefore their network identifers are MAC addresses (EUI-48)¶

• device u1 has ID_U = key id = 14¶

• there are 3 gateways in the radio range of u1:¶

  • v1 with MAC address = A2-A1-88-EE-97-75¶

  • v2 with MAC address = 28-0F-70-84-51-E4¶

  • v3 with MAC address = 39-63-C9-D0-5C-62¶

• the access policy in W specifies, via a mapping of shape (ID_U; MAC1, MAC2, ...) that device u1 can only join via gateway v3, i.e., the mapping is: (14; 39-63-C9-D0-5C-62)¶

• W is able to map the PoP key of the gateways to their respective MAC addresses¶

Execution:¶

1. device u1 tries to join via gateway v1, which forwards the request to W¶

2. W verifies that MAC address A2-A1-88-EE-97-75 is not in the access policy mapping, and replies with an error. The error_content has REJECT_TYPE = 1, and the plaintext of REJECT_INFO contains a list of suggested gateways = [h'3963C9D05C62']. The single element in the list is the 6-byte MAC address of v3, serialized as a bstr.¶

3. gateway v1 assembles an EDHOC error "Access Denied" with error_content, and sends it to u1¶

4. device u1 processes the error, decrypts REJECT_INFO, and retries the protocol via gateway v3¶