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

3.2.1. Access Token Retrieval from the Authorization Server

After the client and the authorization server mutually authenticated each other and validated each other's authorization, the client sends a token request to the authorization server's token endpoint. The client MUST add a req_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. It is RECOMMENDED that the client uses DTLS with the same keying material to secure the communication with the authorization server, proving possession of the key as part of the token request. Other mechanisms for proving possession of the key may be defined in the future.¶

An example access token request from the client to the authorization server is depicted in Figure 3.¶

   POST coaps://as.example.com/token
   Content-Format: application/ace+cbor
   Payload:
   {
     grant_type : client_credentials,
     req_aud    : "tempSensor4711",
     req_cnf    : {
       COSE_Key : {
         kty : EC2,
         crv : P-256,
         x   : h'e866c35f4c3c81bb96a1...',
         y   : h'2e25556be097c8778a20...'
       }
     }
   }

The example shows an access token request for the resource identified by the string "tempSensor4711" on the authorization server using a raw public key.¶

The authorization server MUST check if the client that it communicates with is associated with the RPK in the req_cnf parameter before issuing an access token to it. If the authorization server determines that the request is to be authorized according to the respective authorization rules, it generates an access token response for the client. The access token MUST be bound to the RPK of the client by means of the cnf claim.¶

The response MAY contain a profile parameter with the value coap_dtls to indicate that this profile MUST be used for communication between the client and the resource server. The profile may be specified out-of-band, in which case it does not have to be sent. The response also contains an access token with information for the resource server about the client's public key. The authorization server MUST return in its response the parameter rs_cnf unless it is certain that the client already knows the public key of the resource server. The authorization server MUST ascertain that the RPK specified in rs_cnf belongs to the resource server that the client wants to communicate with. The authorization server MUST protect the integrity of the access token such that the resource server can detect unauthorized changes. If the access token contains confidential data, the authorization server MUST also protect the confidentiality of the access token.¶

The client MUST ascertain that the access token response belongs to a certain previously sent access token request, as the request may specify the resource server with which the client wants to communicate.¶

An example access token response from the authorization server to the client is depicted in Figure 4. Here, the contents of the access_token claim have been truncated to improve readability. Caching proxies process the Max-Age option in the CoAP response which has a default value of 60 seconds (Section 5.6.1 of [RFC7252]). The authorization server SHOULD adjust the Max-Age option such that it does not exceed the expires_in parameter to avoid stale responses.¶

   2.01 Created
   Content-Format: application/ace+cbor
   Max-Age: 3560
   Payload:
   {
     access_token : b64'SlAV32hkKG...
      (remainder of CWT omitted for brevity;
      CWT contains the client's RPK in the cnf claim)',
     expires_in : 3600,
     rs_cnf     : {
       COSE_Key : {
         kty : EC2,
         crv : P-256,
         x   : h'd7cc072de2205bdc1537...',
         y   : h'f95e1d4b851a2cc80fff...'
       }
     }
   }

3.2.2. DTLS Channel Setup Between Client and Resource Server

Before the client initiates the DTLS handshake with the resource server, the client MUST send a POST request containing the obtained access token to the authz-info resource hosted by the resource server. After the client receives a confirmation that the resource server has accepted the access token, it SHOULD proceed to establish a new DTLS channel with the resource server. The client MUST use its correct public key in the DTLS handshake. If the authorization server has specified a cnf field in the access token response, the client MUST use this key. Otherwise, the client MUST use the public key that it specified in the req_cnf of the access token request. The client MUST specify this public key in the SubjectPublicKeyInfo structure of the DTLS handshake as described in [RFC7250].¶

To be consistent with [RFC7252] which allows for shortened MAC tags in constrained environments, an implementation that supports the RPK mode of this profile MUST at least support the ciphersuite TLS_ECDHE_ECDSA_WITH_AES_128_CCM_8 [RFC7251]. As discussed in [RFC7748], new ECC curves have been defined recently that are considered superior to the so-called NIST curves. This specification therefore mandates implementation support for curve25519 (cf. [RFC8032], [RFC8422]) as this curve said to be efficient and less dangerous regarding implementation errors than the secp256r1 curve mandated in [RFC7252].¶

The resource server MUST check if the access token is still valid, if the resource server is the intended destination (i.e., the audience) of the token, and if the token was issued by an authorized authorization server. 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. The cnf claim MUST contain either the client's RPK or, if the key is already known by the resource server (e.g., from previous communication), a reference to this key. 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. If CBOR web tokens [RFC8392] are used (as recommended in [I-D.ietf-ace-oauth-authz]), keys MUST be encoded as specified in [RFC8747]. A resource server MUST have the capacity to store one access token for every proof-of-possession key of every authorized client.¶

The raw public key used in the DTLS handshake with the client MUST belong to the resource server. If the resource server has several raw public keys, it needs to determine which key to use. The authorization server can help with this decision by including a cnf parameter in the access token that is associated with this communication. In this case, the resource server MUST use the information from the cnf field to select the proper keying material.¶

Thus, the handshake only finishes if the client and the resource server are able to use their respective keying material.¶

3.3.1. Access Token Retrieval from the Authorization Server

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 shared secret to construct the proof-of-possession token. The authorization server MUST check if the identifier refers to a symmetric key that was previously generated by the authorization server as a shared secret for the communication between this client and the resource server. If no such symmetric key was found, the authorization server MUST generate a new symmetric key that is returned in its response to the client.¶

The authorization server MUST determine the authorization rules for the client it communicates with as defined by the resource owner and generate the access token accordingly. If the authorization server authorizes the client, it returns an AS-to-Client response. If the profile parameter is present, it is set to coap_dtls. The authorization server MUST ascertain that the access token is generated for the resource server that the client wants to communicate with. Also, the authorization server MUST protect the integrity of the access token to ensure that the resource server can detect unauthorized changes. If the token contains confidential data such as the symmetric key, the confidentiality of the token MUST also be protected. Depending on the requested token type and algorithm in the access token request, the authorization server adds access Information to the response that provides the client with sufficient information to setup a DTLS channel with the resource server. The authorization server adds a cnf parameter to the access information carrying a COSE_Key object that informs the client about the shared secret that is to be used between the client and the resource server. To convey the same secret to the resource server, the authorization server can include it directly in the access token by means of the cnf claim or provide sufficient information to enable the resource server to derive the shared secret from the access token. As an alternative, the resource server MAY use token introspection to retrieve the keying material for this access token directly from the authorization server.¶

An example access token request for an access token with a symmetric proof-of-possession key is illustrated in Figure 5.¶

   POST coaps://as.example.com/token
   Content-Format: application/ace+cbor
   Payload:
   {
     audience    : "smokeSensor1807",
   }

A corresponding example access token response is illustrated in Figure 6. In this example, the authorization server returns a 2.01 response containing a new access token (truncated to improve readability) and information for the client, including the symmetric key in the cnf claim. The information is transferred as a CBOR data structure as specified in [I-D.ietf-ace-oauth-authz].¶

   2.01 Created
   Content-Format: application/ace+cbor
   Max-Age: 85800
   Payload:
   {
      access_token : h'd08343a10...
      (remainder of CWT omitted for brevity)
      token_type : PoP,
      expires_in : 86400,
      profile    : coap_dtls,
      cnf        : {
        COSE_Key : {
          kty : symmetric,
          kid : h'3d027833fc6267ce',
          k   : h'73657373696f6e6b6579'
        }
      }
   }

The access token also comprises a cnf claim. This claim usually contains a COSE_Key object that carries either the symmetric key itself or a key identifier that can be used by the resource server to determine the secret key it shares with the client. If the access token carries a symmetric key, the access token MUST be encrypted using a COSE_Encrypt0 structure. The authorization server MUST use the keying material shared with the resource server to encrypt the token.¶

The cnf structure in the access token is provided in Figure 7.¶

cnf : {
  COSE_Key : {
    kty : symmetric,
    kid : h'3d027833fc6267ce'
  }
}

A response that declines any operation on the requested resource is constructed according to Section 5.2 of [RFC6749], (cf. Section 5.6.3. of [I-D.ietf-ace-oauth-authz]). Figure 8 shows an example for a request that has been rejected due to invalid request parameters.¶

    4.00 Bad Request
    Content-Format: application/ace+cbor
    Payload:
    {
      error : invalid_request
    }

The method for how the resource server determines the symmetric key from an access token containing only a key identifier is application-specific; the remainder of this section provides one example.¶

The authorization server and the resource server are assumed to share a key derivation key used to derive the symmetric key shared with the client from the key identifier in the access token. The key derivation key may be derived from some other secret key shared between the authorization server and the resource server. This key needs to be securely stored and processed in the same way as the key used to protect the communication between the authorization server and the resource server.¶

Knowledge of the symmetric key shared with the client must not reveal any information about the key derivation key or other secret keys shared between the authorization server and resource server.¶

In order to generate a new symmetric key to be used by client and resource server, the authorization server generates a new key identifier which MUST be unique among all key identifiers used by the authorization server for this resource server. The authorization server then uses the key derivation key shared with the resource server to derive the symmetric key as specified below. Instead of providing the keying material in the access token, the authorization server includes the key identifier in the kid parameter, see Figure 7. This key identifier enables the resource server to calculate the symmetric key used for the communication with the client using the key derivation key and a KDF to be defined by the application, for example HKDF-SHA-256. The key identifier picked by the authorization server MUST be unique for each access token where a unique symmetric key is required.¶

In this example, HKDF consists of the composition of the HKDF-Extract and HKDF-Expand steps [RFC5869]. The symmetric key is derived from the key identifier, the key derivation key and other data:¶

OKM = HKDF(salt, IKM, info, L),¶

where:¶

• OKM, the output keying material, is the derived symmetric key¶
• salt is the empty byte string¶
• IKM, the input keying material, is the key derivation key as defined above¶
• info is the serialization of a CBOR array consisting of ([RFC8610]):¶

      info = [
        type : tstr,
        L : uint,
        access_token: bytes
      ]

where:¶

• type is set to the constant text string "ACE-CoAP-DTLS-key-derivation",¶
• L is the size of the symmetric key in bytes,¶
• access_token is the content of the access_token field as transferred from the authorization server to the resource server.¶

All CBOR data types are encoded in CBOR using preferred serialization and deterministic encoding as specified in Section 4 of [RFC8949]. This implies in particular that the type and L components use the minimum length encoding. The content of the access_token field is treated as opaque data for the purpose of key derivation.¶

Use of a unique (per resource server) kid and the use of a key derivation IKM that MUST be unique per authorization server/resource server pair as specified above will ensure that the derived key is not shared across multiple clients. However, to additionally provide variation in the derived key across different tokens used by the same client, it is additionally RECOMMENDED to include the "iat" claim and either the "exp" or "exi" claims in the access token.¶

3.3.2. DTLS Channel Setup Between Client and Resource Server

When a client receives an access token response from an authorization server, the client MUST check if the access token response is bound to a certain previously sent access token request, as the request may specify the resource server with which the client wants to communicate.¶

The client checks if the payload of the access token response contains an access_token parameter and a cnf parameter. With this information the client can initiate the 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 [RFC4279] using the key conveyed in the cnf parameter of the AS response as PSK when constructing the premaster secret. To be consistent with the recommendations in [RFC7252] a client is expected to offer at least the ciphersuite TLS_PSK_WITH_AES_128_CCM_8 [RFC6655] to the resource server.¶

In PreSharedKey mode, the knowledge of the shared secret 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 shared secret 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. The client then needs to indicate during the DTLS handshake which previously uploaded access token it intends to use. To do so, it MUST create a COSE_Key structure with the kid that was conveyed in the rs_cnf claim in the token response from the authorization server and the key type symmetric. This structure then is included as the only element in the cnf structure that is used as value for psk_identity as shown in Figure 9.¶

{ cnf : {
   COSE_Key : {
      kty: symmetric,
      kid : h'3d027833fc6267ce'
    }
  }
}

As an alternative to the access token upload, the client can 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 as specified in Section 4.2 of [RFC7925] and not perform any re-coding. This allows the resource server to retrieve the shared secret directly from the cnf claim of the access token.¶

If a resource server receives a ClientKeyExchange message that contains a psk_identity with a length greater than zero, it MUST parse the contents of the psk_identity field as CBOR data structure and process the contents as following:¶

• If the data contains a cnf field with a COSE_Key structure with a kid, the resource server continues the DTLS handshake with the associated key that corresponds to this kid.¶
• If the data comprises additional CWT information, this information must be stored as an access token for this DTLS association before continuing with the DTLS handshake.¶

If the contents of the psk_identity do not yield sufficient information to select a valid access token for the requesting client, the resource server aborts the DTLS handshake with an illegal_parameter alert.¶

When the resource server receives an access token, it MUST check if the access token is still valid, if the resource server is the intended destination (i.e., the audience of the token), and if the token was issued by an authorized authorization server. This specification implements access tokens as proof-of-possession tokens. Therefore, the access token is bound to a symmetric PoP key that is used as shared secret between the client and the resource server. A resource server MUST have the capacity to store one access token for every proof-of-possession key of every authorized client. The resource server may use token introspection [RFC7662] on the access token to retrieve more information about the specific token. The use of introspection is out of scope for this specification.¶

While the client can retrieve the shared secret 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 secret when no explicit kid was provided in the psk_identity field. If key derivation is used, the resource server uses the COSE_KDF_Context information as described above.¶