Datagram Transport Layer Security (DTLS) Profile for Authentication and Authorization for Constrained Environments (ACE)

This specification defines a profile of the ACE framework . In this profile, a client and a resource server use CoAP over DTLS to communicate. The client uses an access token, bound to a key (the proof-of-possession key) to authorize its access to protected resources hosted by the resource server. DTLS provides communication security, proof of possession, and server authentication. Optionally the client and the resource server may also use CoAP over DTLS to communicate with the authorization server. This specification supports the DTLS handshake with Raw Public Keys (RPK) and the DTLS handshake with Pre-Shared Keys (PSK) . The DTLS RPK handshake requires client authentication to provide proof-of-possession for the key tied to the access token. Here the access token needs to be transferred to the resource server before the handshake is initiated, as described in section 5.8.1 of draft-ietf-ace-oauth-authz. The DTLS PSK handshake provides the proof-of-possession for the key tied to the access token. Furthermore the psk_identity parameter in the DTLS PSK handshake is used to transfer the access token from the client to the resource server. communicating using CoAP over DTLS, it is expected that it applies also to CoAP over TLS, possibly with minor modifications. However, that is out of scope for this version of the draft.

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 when, and only when, they appear in all capitals, as shown here. Readers are expected to be familiar with the terms and concepts described in .

The CoAP-DTLS profile for ACE specifies the transfer of authentication and, if necessary, authorization information between the client C and the resource server RS during setup of a DTLS session for CoAP messaging. It also specifies how a Client can use CoAP over DTLS to retrieve an Access Token from the authorization server AS for a protected resource hosted on the resource server RS. This profile requires a Client (C) to retrieve an Access Token for the resource(s) it wants to access on a Resource Server (RS) as specified in . shows the typical message flow in this scenario (messages in square brackets are optional):

] | | | | | | [<----- AS Information --] | | | | | | --- Token Request ----------------------------> | | | | | <---------------------------- Access Token ----- | | + RS Information | ]]> To determine the AS in charge of a resource hosted at the RS, the client C MAY send an initial Unauthorized Resource Request message to the RS. The RS then denies the request and sends the address of its AS back to the client C. Once the client C knows the authorization server’s address, it can send an Access Token request to the token endpoint at the AS as specified in . As the Access Token request as well as the response may contain confidential data, the communication between the client and the authorization server MUST be confidentiality-protected and ensure authenticity. How the mutual authentication between the client and the authorization server is achieved is out of scope for this document; the client may have been configured with a public key of the authorization server and have been registered at the AS via the OAuth client registration mechanism as outlined in section 5.3 of draft-ietf-ace-oauth-authz. If C wants to use the CoAP RawPublicKey mode as described in Section 9 of RFC 7252 it MUST provide a key or key identifier within a cnf object in the token request. If the authorization server AS decides that the request is to be authorized it generates an access token response for the client C containing a profile parameter with the value coap_dtls to indicate that this profile MUST be used for communication between the client C and the resource server. Is also adds a cnf parameter with additional data for the establishment of a secure DTLS channel between the client and the resource server. The semantics of the ‘cnf’ parameter depend on the type of key used between the client and the resource server and control whether the client must use RPK mode or PSK mode to establish a DTLS session with the resource server, see and . The Access Token returned by the authorization server then can be used by the client to establish a new DTLS session with the resource server. When the client intends to use asymmetric cryptography in the DTLS handshake with the resource server, the client MUST upload the Access Token to the authz-info resource on the resource server before starting the DTLS handshake, as described in section 5.8.1 of draft-ietf-ace-oauth-authz. If only symmetric cryptography is used between the client and the resource server, the Access Token MAY instead be transferred in the DTLS ClientKeyExchange message (see ). depicts the common protocol flow for the DTLS profile after the client C has retrieved the Access Token from the authorization server AS.

] | | | | | | <== DTLS channel setup ==> | | | | | | == Authorized Request ===> | | | | | | <=== Protected Resource == | | ]]> The following sections specify how CoAP is used to interchange access-related data between the resource server and the authorization server so that the authorization server can provide the client and the resource server with sufficient information to establish a secure channel, and convey authorization information specific for this communication relationship to the resource server. Depending on the desired CoAP security mode, the Client-to-AS request, AS-to-Client response and DTLS session establishment carry slightly different information. addresses the use of raw public keys while defines how pre-shared keys are used in this profile.

Once a DTLS channel has been established as described in and , respectively, the client is authorized to access resources covered by the Access Token it has uploaded to the authz-info resource hosted by the resource server. On the resource server side, successful establishment of the DTLS channel binds the client to the access token, functioning as a proof-of-possession associated key. Any request that the resource server receives on this channel MUST be checked against these authorization rules that are associated with the identity of the client. Incoming CoAP requests that are not authorized with respect to any Access Token that is associated with the client MUST be rejected by the resource server with 4.01 response as described in Section 5.1.1 of draft-ietf-ace-oauth-authz. during the DTLS handshake. In the asymmetric case, the public key will define the client’s identity, while in the PSK case, the client’s identity is defined by the session key generated by the authorization server for this communication. The resource server SHOULD treat an incoming CoAP request as authorized if the following holds: The message was received on a secure channel that has been established using the procedure defined in this document. The authorization information tied to the sending peer is valid. The request is destined for the resource server. The resource URI specified in the request is covered by the authorization information. The request method is an authorized action on the resource with respect to the authorization information. Incoming CoAP requests received on a secure DTLS channel MUST be rejected according to [Section 5.1.1 of draft-ietf-ace-oauth-authz](https://tools.ietf.org/html/draft-ietf-ace-oauth-authz-10#section-5.1.1 with response code 4.03 (Forbidden) when the resource URI specified in the request is not covered by the authorization information, and with response code 4.05 (Method Not Allowed) when the resource URI specified in the request covered by the authorization information but not the requested action. The client cannot always know a priori if an Authorized Resource Request will succeed. If the client repeatedly gets error responses containing AS Information (cf. Section 5.1.1 of draft-ietf-ace-oauth-authz as response to its requests, it SHOULD request a new Access Token from the authorization server in order to continue communication with the resource server.

The client can update the authorization information stored at the resource server at any time without changing an established DTLS session. To do so, the Client requests from the authorization server a new Access Token for the intended action on the respective resource and uploads this Access Token to the authz-info resource on the resource server. depicts the message flow where the client C requests a new Access Token after a security association between the client and the resource server RS has been established using this protocol. The token request MUST specify the key identifier of the existing DTLS channel between the client and the resource server in the kid parameter of the Client-to-AS request. The authorization server MUST verify that the specified kid denotes a valid verifier for a proof-of-possession ticket that has previously been issued to the requesting client. Otherwise, the Client-to-AS request MUST be declined with a the error code unsupported_pop_key as defined in Section 5.6.3 of draft-ietf-ace-oauth-authz. When the authorization server issues a new access token to update existing authorization information it MUST include the specified kid parameter in this access token. A resource server MUST associate the updated authorization information with any existing DTLS session that is identified by this key identifier. existing DTLS session, the authorization information can be updated without changing the cryptographic keys for the DTLS communication between the client and the resource server, i.e. an existing session can be used with updated permissions.

| | | + Access Token | | | | | | --- Token Request ----------------------------> | | | | | <---------------------------- New Access Token - | | + RS Information | | | | | --- Update /authz-info --> | | | New Access Token | | | | | | == Authorized Request ===> | | | | | | <=== Protected Resource == | | ]]>

DTLS sessions that have been established in accordance with this profile are always tied to a specific set of access tokens. As these tokens may become invalid at any time (either because the token has expired or the responsible authorization server has revoked the token), the session may become useless at some point. A resource server therefore may decide to terminate existing DTLS sessions after the last valid access token for this session has been deleted. As specified in section 5.8.2 of draft-ietf-ace-oauth-authz, the resource server MUST notify the client with an error response with code 4.01 (Unauthorized) for any long running request before terminating the session. The resource server MAY also keep the session alive for some time and respond to incoming requests with a 4.01 (Unauthorized) error message including AS Information to signal that the client needs to upload a new access token before it can continue using this DTLS session. The AS Information is created as specified in section 5.1.2 of draft-ietf-ace-oauth-authz. The resource server SHOULD add a kid parameter to the AS Information denoting the identifier of the key that it uses internally for this DTLS session. The client then includes this kid parameter in a Client-to-AS request used to retrieve a new access token to be used with this DTLS session. In case the key identifier is already known by the client (e.g. because it was included in the RS Information in an AS-to-Client response), the kid parameter MAY be elided from the AS Information. updates Figure 2 in section 5.1.2 of draft-ietf-ace-oauth-authz with the new kid parameter in accordance with . Parameter name CBOR Key Major Type kid 4 2 (byte string)

To retrieve an access token for the resource that the client wants to access, the client requests an Access Token from the authorization server. The client MUST add a cnf object carrying either its raw public key or a unique identifier for a public key that it has previously made known to the authorization server. To prove that the client is in possession of this key, it MUST use the same public key as in certificate message that is used to establish the DTLS session with the authorization server. An example Access Token request from the client to the resource server is depicted in .

The example shows an Access Token request for the resource identified by the audience string “tempSensor4711” on the authorization server using a raw public key. When the authorization server authorizes a request, it will return an Access Token and a cnf object in the AS-to-Client response. Before the client initiates the DTLS handshake with the resource server, it MUST send a POST request containing the new Access Token to the authz-info resource hosted by the resource server. If this operation yields a positive response, the client SHOULD proceed to establish a new DTLS channel with the resource server. To use raw public key mode, the client MUST pass the same public key that was used for constructing the Access Token with the SubjectPublicKeyInfo structure in the DTLS handshake as specified in . An implementation that supports the RPK mode of this profile MUST at least support the ciphersuite TLS_ECDHE_ECDSA_WITH_AES_128_CCM_8 with the ed25519 curve (cf. , ). According to , CoAP implementations MUST support the ciphersuite TLS_ECDHE_ECDSA_WITH_AES_128_CCM_8 and the NIST P-256 curve. As discussed in , new ECC curves have been defined recently that are considered superior to the so-called NIST curves. The curve that is mandatory to implement in this specification is said to be efficient and less dangerous regarding implementation errors than the secp256r1 curve mandated in . The Access Token is constructed by the authorization server such that the resource server can associate the Access Token with the Client’s public key. If CBOR web tokens are used as recommended in , the authorization server MUST include a COSE_Key object in the cnf claim of the Access Token. This COSE_Key object MAY contain a reference to a key for the client that is already known by the resource server (e.g., from previous communication). If the authorization server has no certain knowledge that the Client’s key is already known to the resource server, the Client’s public key MUST be included in the Access Token’s cnf parameter.

To retrieve an access token for the resource that the client wants to access, the client MAY include a cnf object carrying an identifier for a symmetric key in its Access Token request to the authorization server. This identifier can be used by the authorization server to determine the session key to construct the proof-of-possession token and therefore MUST specify a symmetric key that was previously generated by the authorization server as a session key for the communication between the client and the resource server. Depending on the requested token type and algorithm in the Access Token request, the authorization server adds RS Information to the response that provides the client with sufficient information to setup a DTLS channel with the resource server. For symmetric proof-of-possession keys (c.f. ), the client must ensure that the Access Token request is sent over a secure channel that guarantees authentication, message integrity and confidentiality. When the authorization server authorizes the client it returns an AS-to-Client response with the profile parameter set to coap_dtls and a cnf parameter carrying a COSE_Key object that contains the symmetric session key to be used between the client and the resource server as illustrated in .

In this example, the authorization server returns a 2.01 response containing a new Access Token. The information is transferred as a CBOR data structure as specified in . The Max-Age option tells the receiving Client how long this token will be valid. A response that declines any operation on the requested resource is constructed according to Section 5.2 of RFC 6749, (cf. Section 5.7.3 of ).

When a client receives an Access Token from an authorization server, it checks if the payload contains an access_token parameter and a cnf parameter. With this information the client can initiate establishment of a new DTLS channel with a resource server. To use DTLS with pre-shared keys, the client follows the PSK key exchange algorithm specified in Section 2 of using the key conveyed in the cnf parameter of the AS response as PSK when constructing the premaster secret. In PreSharedKey mode, the knowledge of the session key by the client and the resource server is used for mutual authentication between both peers. Therefore, the resource server must be able to determine the session key from the Access Token. Following the general ACE authorization framework, the client can upload the Access Token to the resource server’s authz-info resource before starting the DTLS handshake. Alternatively, the client MAY provide the most recent Access Token in the psk_identity field of the ClientKeyExchange message. To do so, the client MUST treat the contents of the access_token field from the AS-to-Client response as opaque data and not perform any re-coding. Note: As stated in section 4.2 of , the PSK identity should be treated as binary data in the Internet of Things space and not assumed to have a human-readable form of any sort. If a resource server receives a ClientKeyExchange message that contains a psk_identity with a length greater zero, it uses the contents as index for its key store (i.e., treat the contents as key identifier). The resource server MUST check if it has one or more Access Tokens that are associated with the specified key. If no valid Access Token is available for this key, the DTLS session setup is terminated with an illegal_parameter DTLS alert message. If no key with a matching identifier is found the resource server the resource server MAY process the decoded contents of the psk_identity field as access token that is stored with the authorization information endpoint before continuing the DTLS handshake. If the decoded contents of the psk_identity do not yield a valid access token for the requesting client, the DTLS session setup is terminated with an illegal_parameter DTLS alert message. response to the client’s ClientHello message, the resource server SHOULD NOT send a ServerKeyExchange message. According to , CoAP implementations MUST support the ciphersuite TLS_PSK_WITH_AES_128_CCM_8 . A client is therefore expected to offer at least this ciphersuite to the resource server. This specification assumes that the Access Token is a PoP token as described in unless specifically stated otherwise. Therefore, the Access Token is bound to a symmetric PoP key that is used as session key between the client and the resource server. While the client can retrieve the session key from the contents of the cnf parameter in the AS-to-Client response, the resource server uses the information contained in the cnf claim of the Access Token to determine the actual session key when no explicit kid was provided in the psk_identity field. Usually, this is done by including a COSE_Key object carrying either a key that has been encrypted with a shared secret between the authorization server and the resource server, or a key identifier that can be used by the resource server to lookup the session key. Instead of the COSE_Key object, the authorization server MAY include a COSE_Encrypt structure to enable the resource server to calculate the session key from the Access Token. The COSE_Encrypt structure MUST use the Direct Key with KDF method as described in Section 12.1.2 of RFC 8152. The authorization server MUST include a Context information structure carrying a PartyU nonce parameter carrying the nonce that has been used by the authorization server to construct the session key. This specification mandates that at least the key derivation algorithm HKDF SHA-256 as defined in MUST be supported. This key derivation function is the default when no alg field is included in the COSE_Encrypt structure for the resource server.

Usually, the authorization information that the resource server keeps for a client is updated by uploading a new Access Token as described in . If the security association with the resource server still exists and the resource server has indicated support for session renegotiation according to , the new Access Token MAY be used to renegotiate the existing DTLS session. In this case, the Access Token is used as psk_identity as defined in . The Client MAY also perform a new DTLS handshake according to that replaces the existing DTLS session. After successful completion of the DTLS handshake the resource server updates the existing authorization information for the client according to the new Access Token.

This document specifies a profile for the Authentication and Authorization for Constrained Environments (ACE) framework . As it follows this framework’s general approach, the general security and privacy considerations from section 6 and section 7 also apply to this profile. Constrained devices that use DTLS are inherently vulnerable to Denial of Service (DoS) attacks as the handshake protocol requires creation of internal state within the device. This is specifically of concern where an adversary is able to intercept the initial cookie exchange and interject forged messages with a valid cookie to continue with the handshake. specifies a TLS extension to prevent this type of attack which is applicable especially for constrained environments where the authorization server can act as trust anchor.

An unprotected response to an unauthorized request may disclose information about the resource server and/or its existing relationship with the client. It is advisable to include as little information as possible in an unencrypted response. When a DTLS session between the client and the resource server already exists, more detailed information may be included with an error response to provide the client with sufficient information to react on that particular error. Note that some information might still leak after DTLS session is established, due to observable message sizes, the source, and the destination addresses.

The following registrations are done for the ACE OAuth Profile Registry following the procedure specified in . Note to RFC Editor: Please replace all occurrences of “&SELF;” with the RFC number of this specification and delete this paragraph. Profile name: coap_dtls Profile Description: Profile for delegating client authentication and authorization in a constrained environment by establishing a Datagram Transport Layer Security (DTLS) channel between resource-constrained nodes. Profile ID: 1 Change Controller: IESG Reference: &SELF;