3.2.1.Access Token Retrieval from the Authorization Server

After the client and the authorization server mutually authenticated each other and validated eachother's authorization, the client sends a token request to the authorization server's token endpoint.The clientMUST add areq_cnf object carrying either its raw public keyor a unique identifier for a public key that it has previously madeknown to the authorization server. It isRECOMMENDED thatthe client uses DTLS with the same keying material to secure thecommunication with the authorization server, proving possession of the keyas part of the token request. Other mechanisms for proving possession ofthe key may be defined in the future.¶

An example access token request from the client to the authorizationserver is depicted inFigure 3.¶

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

The example shows an access token request for the resource identifiedby the string "tempSensor4711" on the authorization serverusing a raw public key.¶

The authorization serverMUST check if the client that it communicateswith is associated with the RPK in thereq_cnf parameter beforeissuing an access token to it. If the authorization server determinesthat the request is to be authorized according to the respectiveauthorization rules, it generates an access token response for theclient. The access tokenMUST be bound to the RPK of the client bymeans of thecnf claim.¶

The responseMUST contain anace_profile parameter if theace_profile parameter in the request is empty andMAY contain this parameter otherwise (seeSection 5.8.2 of [RFC9200]). This parameter is set tocoap_dtls to indicate that this profileMUST be used for communication between the client and the resource server. The response also contains an access token with information for the resource server about the client's public key. The authorization serverMUST return in its response the parameterrs_cnf unless it is certain that the client already knows the public key of the resource server. The authorization serverMUST ascertain that the RPK specified inrs_cnf belongs to the resource server that the client wants to communicate with. The authorization serverMUST 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 serverMUST also protect the confidentiality of the access token.¶

The clientMUST 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 inFigure 4. Here, the contents of theaccess_token claim have been truncated to improve readability. For the client, the response comprises Access Information that contains the server's public key in thers_cnf parameter. 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 serverSHOULD adjust the Max-Age option such that it does not exceed theexpires_in parameter to avoid stale responses.¶

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

3.2.2.DTLS Channel Setup between the Client and Resource Server

Before the client initiates the DTLS handshake with the resourceserver, the clientMUST send aPOST request containing the obtainedaccess token to the authz-info resource hosted by the resourceserver. After the client receives a confirmation that the resourceserver has accepted the access token, it proceeds to establish anew DTLS channel with the resource server. The clientMUST use itscorrect public key in the DTLS handshake. If the authorization serverhas specified acnf field in the access token response, the clientMUST use this key. Otherwise, the clientMUST use the public key thatit specified in thereq_cnf of the access token request. The clientMUST specify this public key in the SubjectPublicKeyInfo structure ofthe DTLS handshake, as described in[RFC7250].¶

If the client does not have the keying material belonging to thepublic key, the clientMAY try to send an access token request to theAS, where the client specifies its public key in thereq_cnf parameter. Ifthe AS still specifies a public key in the response that the clientdoes not have, the clientSHOULD re-register with the authorizationserver to establish a new client public key. This process is out ofscope for this document.¶

To be consistent with[RFC7252], which allows for shortened Message Authentication Code (MAC) tagsin constrained environments,an implementation that supports the RPK mode of this profileMUST atleast support the cipher suiteTLS_ECDHE_ECDSA_WITH_AES_128_CCM_8[RFC7251].As discussed in[RFC7748], new Elliptic Curve Cryptography (ECC) curves have been defined recently that are considered superior to the so-called NIST curves. Implementations of this profileMUST therefore implement support for curve25519 (cf. [RFC8032],[RFC8422]), as this curve is said to be efficient and less dangerous, regarding implementation errors, than the secp256r1 curve mandated in[RFC7252].¶

The resource serverMUST check if the access token is still valid, ifthe resource server is the intended destination (i.e., the audience)of the token, and if the token was issued by an authorizedauthorization server (see alsoSection 5.10.1.1 of [RFC9200]).The access token is constructed by theauthorization server such that the resource server can associate theaccess token with the client's public key. Thecnf claimMUSTcontain either the client's RPK or, if the key is already known by theresource server (e.g., from previous communication), a reference tothis key. If the authorization server has no certain knowledge thatthe client's key is already known to the resource server, the client'spublic keyMUST be included in the access token'scnf parameter. IfCBOR web tokens[RFC8392] are used (as recommended in[RFC9200]), keysMUST be encoded as specified in[RFC8747]. A resource serverMUST have the capacity to store oneaccess token for every proof-of-possession key of every authorized client.¶

The raw public key used in the DTLS handshake with the clientMUSTbelong to the resource server. If the resource server has several rawpublic keys, it needs to determine which key to use. The authorizationserver can help with this decision by including acnf parameter inthe access token that is associated with this communication. In thiscase, the resource serverMUST use the information from thecnffield to select the proper keying material.¶

Thus, the handshake only finishes if the client and the resourceserver 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 toaccess, the clientMAY include areq_cnf object carrying an identifierfor a symmetric key in its access token request to the authorizationserver. This identifier can be used by the authorization server todetermine the shared secret to construct the proof-of-possessiontoken. The authorization serverMUST check if the identifier refersto a symmetric key that was previously generated by the authorizationserver as a shared secret for the communication between this clientand the resource server. If no such symmetric key was found, theauthorization serverMUST generate a new symmetric key that isreturned in its response to the client.¶

The authorization serverMUST 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 theace_profile parameter is present, it is set tocoap_dtls. The authorization serverMUST ascertain that the access token is generated for the resource server that the client wants to communicate with. Also, the authorization serverMUST 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 tokenMUST 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 set up a DTLS channel with the resource server. The authorization server adds acnf parameter to the Access Information carrying aCOSE_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 thecnf claim or provide sufficient information to enable the resource server to derive the shared secret from the access token. As an alternative, the resource serverMAY 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 symmetricproof-of-possession key is illustrated inFigure 5.¶

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

A corresponding example access token response is illustrated inFigure 6. In this example, the authorization server returns a2.01 response containing a new access token (truncated to improvereadability) and information for the client, including the symmetrickey in thecnf claim. The information is transferred as a CBOR datastructure as specified in[RFC9200].¶

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

The access token also comprises acnf claim. This claim usuallycontains aCOSE_Key object[RFC8152] that carries either the symmetric keyitself or a key identifier that can be used by the resource server todetermine the secret key it shares with the client. If the accesstoken carries a symmetric key, the access tokenMUST be encryptedusing aCOSE_Encrypt0 structure (seeSection 7.1 of [RFC8392]). Theauthorization serverMUST usethe keying material shared with the resource server to encrypt thetoken.¶

Thecnf structure in the access token is provided inFigure 7.¶

/ cnf / 8 : {  / COSE_Key / 1 : {    / kty / 1 : / symmetric / 4,    / kid / 2 : h'3d027833fc6267ce'  }}

A response that declines any operation on the requested resource isconstructed according toSection 5.2 of [RFC6749](cf. Section 5.8.3 of [RFC9200]).Figure 8shows an example for a request that has been rejected due to invalidrequest parameters.¶

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

The method for how the resource server determines the symmetric keyfrom an access token containing only a key identifier isapplication specific; the remainder of this section provides oneexample.¶

The authorization server and the resource server are assumed to sharea key derivation key used to derive the symmetric key shared with theclient from the key identifier in the access token. The keyderivation key may be derived from some other secret key sharedbetween the authorization server and the resource server. This keyneeds to be securely stored and processed in the same way as the keyused to protect the communication between the authorization server andthe resource server.¶

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

In order to generate a new symmetric key to be used by the client andresource server, the authorization server generates a new keyidentifier thatMUST be unique among all key identifiers used by theauthorization server for this resource server. The authorization server then uses the keyderivation key shared with the resource server to derive the symmetrickey, as specified below. Instead of providing the keying material inthe access token, the authorization server includes the key identifierin thekid parameter (seeFigure 7). This key identifier enablesthe resource server to calculate the symmetric key used for thecommunication with the client using the key derivation key and a key derivation function (KDF)to be defined by the application, for example, HKDF-SHA-256. The keyidentifier picked by the authorization serverMUST be unique foreach access token where a unique symmetric key is required.¶

In this example, the HMAC-based key derivation function (HKDF) consists of the composition of the HKDF-Extractand HKDF-Expand steps[RFC5869]. The symmetric key is derived from thekey 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 theaccess_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 inSection 4 of [RFC8949]. In particular, this implies that thetype andL components use the minimum length encoding. The content of theaccess_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 thatMUST be unique per AS/RS pair, as specified above, will ensure that the derived key is not shared across multiple clients. However, to provide variation in the derived key across different tokens used by the same client, it is additionallyRECOMMENDED to include theiat claim and either theexp orexi claims in the access token.¶

3.3.2.DTLS Channel Setup between the Client and Resource Server

When a client receives an access token response from an authorizationserver, the clientMUST check if the access token response is bound toa certain, previously sent access token request, as the request mayspecify the resource server with which the client wants tocommunicate.¶

The client checks if the payload of the access token response contains anaccess_token parameter and acnf 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 inSection 2 of [RFC4279], using the key conveyed in thecnf parameter of the AS response as a PSK when constructing the premaster secret. To be consistent with the recommendations in[RFC7252], a client in the PSK modeMUST support the cipher suite TLS_PSK_WITH_AES_128_CCM_8[RFC6655].¶

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, itMUST create aCOSE_Key structure with thekid that was conveyed in thers_cnf claim in the token response from the authorization server and the key typesymmetric. This structure then is included as the only element in thecnf structure whose CBOR serialization is used as value forpsk_identity, as shown inFigure 9.¶

{ / cnf / 8 : {   / COSE_Key / 1 : {      / kty / 1 : / symmetric / 4,      / kid / 2 : h'3d027833fc6267ce'    }  }}

The actual CBOR serialization for the data structure fromFigure 9 as a sequence of bytes in hexadecimal notation will be:¶

A1 08 A1 01 A2 01 04 02 48 3D 02 78 33 FC 62 67 CE

As an alternative to the access token upload, the client can providethe most recent access token in thepsk_identity field of theClientKeyExchange message. To do so, the clientMUST treat thecontents of theaccess_token field from the AS-to-client response asopaque data, as specified inSection 4.2 of [RFC7925], and not performany recoding. This allows the resource server to retrieve the sharedsecret directly from thecnf claim of the access token.¶

DTLS 1.3[RFC9147] does not use the ClientKeyExchange message; for DTLS 1.3, the access token is placed in theidentity field of aPSKIdentity within thePreSharedKeyExtension of theClientHello.¶

If a resource server receives a ClientKeyExchange message thatcontains apsk_identity with a length greater than zero, itMUSTparse the contents of thepsk_identity field as a CBOR data structureand process the contents as following:¶

• If the data contains acnf field with aCOSE_Key structure withakid, the resource server continues the DTLS handshake with theassociated key that corresponds to this kid.¶
• If the data comprises additional CWT information, this informationmust be stored as an access token for this DTLS association beforecontinuing with the DTLS handshake.¶

If the contents of thepsk_identity do not yield sufficientinformation to select a valid access token for the requesting client,the resource server aborts the DTLS handshake with anillegal_parameter alert.¶

When the resource server receives an access token, itMUST check ifthe access token is still valid, if the resource server is theintended destination (i.e., the audience of the token), and if thetoken was issued by an authorized authorization server. Thisspecification implements access tokens as proof-of-possession tokens.Therefore, the access token is bound to a symmetric PoP keythat is used as a shared secret between the client and the resourceserver. A resource serverMUST have the capacity to store oneaccess token for every proof-of-possession key of every authorized client.The resource server may use token introspection[RFC7662] onthe access token to retrieve more information about the specifictoken. The use of introspection is out of scope for thisspecification.¶

While the client can retrieve the shared secret from the contents ofthecnf parameter in the AS-to-client response, the resource serveruses the information contained in thecnf claim of the access tokento determine the actual secret when no explicitkid was provided inthepsk_identity field. If key derivation is used, thecnf claimMUST contain akid parameter to be used by the server as the IKM forkey derivation, as described above.¶