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

Certain security-related terms such as "authentication", "authorization", "confidentiality", "(data) integrity", "Message Authentication Code (MAC)", "Hash-based Message Authentication Code (HMAC)", and "verify" are taken from [RFC4949].¶

RESTful terminology follows HTTP [RFC7231].¶

Readers are expected to be familiar with the terms and concepts defined in OSCORE [RFC8613], such as "Security Context" and "Recipient ID".¶

Terminology for entities in the architecture is defined in OAuth 2.0 [RFC6749], such as client (C), resource server (RS), and authorization server (AS). It is assumed in this document that a given resource on a specific RS is associated to a unique AS.¶

Concise Binary Object Representation (CBOR) [RFC8949] and Concise Data Definition Language (CDDL) [RFC8610] are used in this document. CDDL predefined type names, especially "bstr" for CBOR byte strings and "tstr" for CBOR text strings, are used extensively in this document.¶

Note that the term "endpoint" is used as in [RFC9200], following its OAuth definition, which is to denote resources such as token and introspect at the AS and authz-info at the RS. The CoAP definition, which is "[a]n entity participating in the CoAP protocol" [RFC7252], is not used in this document.¶

Examples throughout this document are expressed in CBOR diagnostic notation without the tag and value abbreviations.¶

3.1. C-to-AS: POST to Token Endpoint

The client-to-AS request is specified in Section 5.8.1 of [RFC9200].¶

The client must send this POST request to the token endpoint over a secure channel that guarantees authentication, message integrity, and confidentiality (see Section 5).¶

An example of such a request is shown in Figure 2.¶

    Header: POST (Code=0.02)
    Uri-Host: "as.example.com"
    Uri-Path: "token"
    Content-Format: "application/ace+cbor"
    Payload:
    {
      "audience" : "tempSensor4711",
      "scope" : "read"
     }

If the client wants to update its access rights without changing an existing OSCORE Security Context, it MUST include a "req_cnf" object in its POST request to the token endpoint, with the kid field carrying a CBOR byte string containing the OSCORE Input Material identifier (assigned as discussed in Section 3.2). This identifier, together with other information such as audience (see Section 5.8.1 of [RFC9200]), can be used by the AS to determine the shared secret bound to the proof-of-possession token; therefore, it MUST identify a symmetric key that was previously generated by the AS as a shared secret for the communication between the client and the RS. The AS MUST verify that the received value identifies a proof-of-possession key that has previously been issued to the requesting client. If that is not the case, the client-to-AS request MUST be declined with the error code invalid_request as defined in Section 5.8.3 of [RFC9200].¶

An example of such a request is shown in Figure 3.¶

    Header: POST (Code=0.02)
    Uri-Host: "as.example.com"
    Uri-Path: "token"
    Content-Format: "application/ace+cbor"
    Payload:
    {
      "audience" : "tempSensor4711",
      "scope" : "write",
      "req_cnf" : {
        "kid" : h'01'
     }

3.2. AS-to-C: Access Token

After verifying the POST request to the token endpoint and that the client is authorized to obtain an access token corresponding to its access token request, the AS responds as defined in Section 5.8.2 of [RFC9200]. If the client request was invalid, or not authorized, the AS returns an error response as described in Section 5.8.3 of [RFC9200].¶

The AS can signal that the use of OSCORE is REQUIRED for a specific access token by including the ace_profile parameter with the value "coap_oscore" in the access token response. This means that the client MUST use OSCORE towards all resource servers for which this access token is valid, and follow Section 4.3 to derive the security context to run OSCORE. Usually, it is assumed that constrained devices will be preconfigured with the necessary profile, so that this kind of profile signaling can be omitted.¶

Moreover, the AS MUST send the following data:¶

• a Master Secret¶
• an identifier of the OSCORE Input Material¶

Additionally, the AS MAY send the following data, in the same response.¶

• a context identifier¶
• an AEAD algorithm¶
• an HMAC-based key derivation function (HKDF) algorithm [RFC5869]; see Section 3.1 of [RFC9053]¶
• a salt¶
• the OSCORE version number¶

This data is transported in the OSCORE_Input_Material. The OSCORE_Input_Material is a CBOR map object, defined in Section 3.2.1. This object is transported in the cnf parameter of the access token response, as defined in Section 3.2 of [RFC9201], as the value of a field named "osc", which is registered in Sections 9.5 and 9.6.¶

The AS MAY assign an identifier to the context (context identifier). This identifier is used as ID Context in the OSCORE context as described in Section 3.1 of [RFC8613]. If assigned, these parameters MUST be communicated as the contextId field in the OSCORE_Input_Material. The application needs to consider that this identifier is sent in the clear and may reveal information about the endpoints, as mentioned in Section 12.8 of [RFC8613].¶

The Master Secret and the identifier of the OSCORE_Input_Material MUST be communicated as the ms and id field in the osc field in the cnf parameter of the access token response. If included, the following are sent: the AEAD algorithm in the alg parameter in the OSCORE_Input_Material; the HKDF algorithm in the hkdf parameter of the OSCORE_Input_Material; a salt in the salt parameter of the OSCORE_Input_Material; and the OSCORE version in the version parameter of the OSCORE_Input_Material.¶

The same parameters MUST be included in the claims associated with the access token. The OSCORE Master Secret MUST be encrypted by the authorization server so that only the resource server can decrypt it (see Section 6.1 of [RFC9200]). The use of a CBOR Web Token (CWT) protected with COSE_Encrypt/COSE_Encrypt0 as specified in [RFC8392] is RECOMMENDED in this profile. If the token is a CWT, the same OSCORE_Input_Material structure defined above MUST be placed in the osc field of the cnf claim of this token.¶

The AS MUST send a different OSCORE_Input_Material (and therefore different access tokens) to different authorized clients, in order for the RS to differentiate between clients.¶

Figure 4 shows an example of an AS response. The access token has been truncated for readability.¶

    Header: Created (Code=2.01)
    Content-Type: "application/ace+cbor"
    Payload:
    {
      "access_token" : h'8343a1010aa2044c53 ...
       (remainder of access token (CWT) omitted for brevity)',
      "ace_profile" : "coap_oscore",
      "expires_in" : "3600",
      "cnf" : {
        "osc" : {
          "id" : h'01',
          "ms" : h'f9af838368e353e78888e1426bd94e6f'
        }
      }
    }

Figure 5 shows an example CWT Claims Set, including the relevant OSCORE parameters in the cnf claim.¶

{
  "aud" : "tempSensorInLivingRoom",
  "iat" : "1360189224",
  "exp" : "1360289224",
  "scope" :  "temperature_g firmware_p",
  "cnf" : {
    "osc" : {
      "ms" : h'f9af838368e353e78888e1426bd94e6f',
      "id" : h'01'
    }
  }
}

The same CWT Claims Set as in Figure 5, using the value abbreviations defined in [RFC9200] and [RFC8747] and encoded in CBOR, is shown in Figure 6. The bytes in hexadecimal are reported in the first column, while their corresponding CBOR meaning is reported after the # sign on the second column, for readability.¶

A5                                      # map(5)
   63                                   # text(3)
      617564                            # "aud"
   76                                   # text(22)
      74656D7053656E736F72496E4C6976696E67526F6F6D
                                        # "tempSensorInLivingRoom"
   63                                   # text(3)
      696174                            # "iat"
   6A                                   # text(10)
      31333630313839323234              # "1360189224"
   63                                   # text(3)
      657870                            # "exp"
   6A                                   # text(10)
      31333630323839323234              # "1360289224"
   65                                   # text(5)
      73636F7065                        # "scope"
   78 18                                # text(24)
      74656D70657261747572655F67206669726D776172655F70
                                        # "temperature_g firmware_p"
   63                                   # text(3)
      636E66                            # "cnf"
   A1                                   # map(1)
      63                                # text(3)
         6F7363                         # "osc"
      A2                                # map(2)
         62                             # text(2)
            6D73                        # "ms"
         50                             # bytes(16)
            F9AF838368E353E78888E1426BD94E6F
                                        # "\xF9\xAF\x83\x83h\xE3S\xE7
                                        \x88\x88\xE1Bk\xD9No"
         62                             # text(2)
            6964                        # "id"
         41                             # bytes(1)
            01                          # "\x01"

If the client has requested an update to its access rights using the same OSCORE Security Context, which is valid and authorized, the AS MUST omit the cnf parameter in the response and MUST carry the OSCORE Input Material identifier in the kid field in the cnf claim of the token. This identifier needs to be included in the token in order for the RS to identify the correct OSCORE Input Material.¶

Figure 7 shows an example of such an AS response. The access token has been truncated for readability.¶

    Header: Created (Code=2.01)
    Content-Type: "application/ace+cbor"
    Payload:
    {
      "access_token" : h'8343a1010aa2044c53 ...
       (remainder of access token (CWT) omitted for brevity)',
      "ace_profile" : "coap_oscore",
      "expires_in" : "3600"
    }

Figure 8 shows an example CWT Claims Set that contains the necessary OSCORE parameters in the cnf claim for the update of access rights.¶

  {
    "aud" : "tempSensorInLivingRoom",
    "iat" : "1360189224",
    "exp" : "1360289224",
    "scope" :  "temperature_h",
    "cnf" : {
      "kid" : h'01'
    }
  }

        "osc" : {
          "alg" : "AES-CCM-16-64-128",
          "id" : b64'AQ=='
          "ms" : b64'+a+Dg2jjU+eIiOFCa9lObw'
        }

OSCORE_Input_Material = {
    ? 0 => bstr,              ; id
    ? 1 => int,               ; version
    ? 2 => bstr,              ; ms
    ? 3 => tstr / int,        ; hkdf
    ? 4 => tstr / int,        ; alg
    ? 5 => bstr,              ; salt
    ? 6 => bstr,              ; contextId
    * int / tstr => any
}

4.1. C-to-RS: POST to authz-info Endpoint

The client MUST generate a nonce value N1 that is very unlikely to have been previously used with the same input keying material. The use of a 64-bit long random number as the nonce's value is RECOMMENDED in this profile. The client MUST store the nonce N1 as long as the response from the RS is not received and the access token related to it is still valid (to the best of the client's knowledge).¶

The client generates its own Recipient ID, ID1, for the OSCORE Security Context that it is establishing with the RS. By generating its own Recipient ID, the client makes sure that it does not collide with any of its Recipient IDs, nor with any other identifier ID1 if the client is executing this exchange with a different RS at the same time.¶

The client MUST use CoAP and the authorization information resource as described in Section 5.8.1 of [RFC9200] to transport the token, N1, and ID1 to the RS.¶

Note that the use of the payload and the Content-Format is different from what is described in Section 5.8.1 of [RFC9200], which only transports the token without any CBOR wrapping. In this profile, the client MUST wrap the token, N1, and ID1 in a CBOR map. The client MUST use the Content-Format "application/ace+cbor" defined in Section 8.14 of [RFC9200]. The client MUST include the access token using the access_token parameter; N1 using the nonce1 parameter defined in Section 4.1.1; and ID1 using the ace_client_recipientid parameter defined in Section 4.1.2.¶

The communication with the authz-info endpoint does not have to be protected, except for the update of access rights case described below.¶

Note that a client may be required to re-POST the access token in order to complete a request, since an RS may delete a stored access token (and associated Security Context) at any time, for example, due to all storage space being consumed. This situation is detected by the client when it receives an AS Request Creation Hints response. Reposting the same access token will result in deriving a new OSCORE Security Context to be used with the RS, as different exchanged nonces will be used.¶

The client may also choose to re-POST the access token in order to update its OSCORE Security Context. In that case, the client and the RS will exchange newly generated nonces, renegotiate identifiers, and derive new keying material. The client and RS might decide to keep the same identifiers or renew them during the renegotiation.¶

Figure 10 shows an example of the request sent from the client to the RS. The access token has been truncated for readability.¶

      Header: POST (Code=0.02)
      Uri-Host: "rs.example.com"
      Uri-Path: "authz-info"
      Content-Format: "application/ace+cbor"
      Payload:
        {
          "access_token": h'8343a1010aa2044c53 ...
       (remainder of access token (CWT) omitted for brevity)',
          "nonce1": h'018a278f7faab55a',
          "ace_client_recipientid" : h'1645'
        }

If the client has already posted a valid token, has already established a security association with the RS, and wants to update its access rights, the client can do so by posting the new token (retrieved from the AS and containing the update of access rights) to the /authz-info endpoint. The client MUST protect the request using the OSCORE Security Context established during the first token exchange. The client MUST only send the access_token field in the CBOR map in the payload; no nonce or identifier is sent. After proper verification (see Section 4.2), the RS will replace the old token with the new one, maintaining the same Security Context.¶

4.2. RS-to-C: 2.01 (Created)

The RS MUST follow the procedures defined in Section 5.8.1 of [RFC9200]: the RS must verify the validity of the token. If the token is valid, the RS must respond to the POST request with 2.01 (Created). If the token is valid but is associated to claims that the RS cannot process (e.g., an unknown scope), or if any of the expected parameters are missing (e.g., any of the mandatory parameters from the AS or the identifier ID1), or if any parameters received in the osc field are unrecognized, the RS must respond with an error response code equivalent to the CoAP code 4.00 (Bad Request). In the latter two cases, the RS may provide additional information in the error response, in order to clarify what went wrong. The RS may make an introspection request (see Section 5.9.1 of [RFC9200]) to validate the token before responding to the POST request to the authz-info endpoint.¶

Additionally, the RS MUST generate a nonce N2 that is very unlikely to have been previously used with the same input keying material and its own Recipient ID, ID2. The RS makes sure that ID2 does not collide with any of its Recipient IDs. The RS MUST ensure that ID2 is different from the value received in the ace_client_recipientid parameter. The RS sends N2 and ID2 within the 2.01 (Created) response. The payload of the 2.01 (Created) response MUST be a CBOR map containing the nonce2 parameter defined in Section 4.2.1, set to N2, and the ace_server_recipientid parameter defined in Section 4.2.2, set to ID2. The use of a 64-bit long random number as the nonce's value is RECOMMENDED in this profile. The RS MUST use the Content-Format "application/ace+cbor" defined in Section 8.14 of [RFC9200].¶

Figure 11 shows an example of the response sent from the RS to the client.¶

      Header: Created (Code=2.01)
      Content-Format: "application/ace+cbor"
      Payload:
        {
          "nonce2": h'25a8991cd700ac01',
          "ace_server_recipientid" : h'0000'
        }

As specified in Section 5.8.3 of [RFC9200], the RS must notify the client with an error response with code 4.01 (Unauthorized) for any long running request before terminating the session, when the access token expires.¶

If the RS receives the token in an OSCORE-protected message, it means that the client is requesting an update of access rights. The RS MUST ignore any nonce and identifiers in the request, if any were sent. The RS MUST check that the "kid" of the cnf claim of the new access token matches the identifier of the OSCORE Input Material of the context used to protect the message. If that is the case, the RS MUST overwrite the old token and associate the new token to the Security Context identified by the "kid" value in the cnf claim. The RS MUST respond with a 2.01 (Created) response protected with the same Security Context, with no payload. If any verification fails, the RS MUST respond with a 4.01 (Unauthorized) error response.¶

As specified in Section 5.8.1 of [RFC9200], when receiving an updated access token with updated authorization information from the client (see Section 3.1), it is recommended that the RS overwrites the previous token; that is, only the latest authorization information in the token received by the RS is valid. This simplifies the process needed by the RS to keep track of authorization information for a given client.¶

4.3. OSCORE Setup

Once the 2.01 (Created) response is received from the RS, following the POST request to authz-info endpoint, the client MUST extract the bstr nonce N2 from the nonce2 parameter in the CBOR map in the payload of the response. Then, the client MUST set the Master Salt of the Security Context created to communicate with the RS to the concatenation of salt, N1, and N2 in this order: Master Salt = salt | N1 | N2, where | denotes byte string concatenation, salt is the CBOR byte string received from the AS in Section 3.2, and N1 and N2 are the two nonces encoded as CBOR byte strings. An example of Master Salt construction using CBOR encoding is given in Figure 12.¶

N1, N2 and input salt expressed in CBOR diagnostic notation:
      nonce1 = h'018a278f7faab55a'
      nonce2 = h'25a8991cd700ac01'
      input salt = h'f9af838368e353e78888e1426bd94e6f'

N1, N2 and input salt as CBOR encoded byte strings:
      nonce1 = 0x48018a278f7faab55a
      nonce2 = 0x4825a8991cd700ac01
      input salt = 0x50f9af838368e353e78888e1426bd94e6f

Master Salt = 0x50 f9af838368e353e78888e1426bd94e6f
                48 018a278f7faab55a 48 25a8991cd700ac01

If JSON is used instead of CBOR, the Master Salt of the Security Context is the base64 encoding of the concatenation of the same parameters, each of them prefixed by their size, encoded in 1 byte. When using JSON, the nonces and input salt have a maximum size of 255 bytes. An example of Master Salt construction using base64 encoding is given in Figure 13.¶

N1, N2 and input salt values:
      nonce1 = 0x018a278f7faab55a (8 bytes)
      nonce2 = 0x25a8991cd700ac01 (8 bytes)
      input salt = 0xf9af838368e353e78888e1426bd94e6f (16 bytes)

Input to Base64 encoding: 0x10 f9af838368e353e78888e1426bd94e6f
                            08 018a278f7faab55a 08 25a8991cd700ac01

Master Salt = b64'EPmvg4No41PniIjhQmvZTm8IAYonj3+qtVoIJaiZHNcArAE='

The client MUST set the Sender ID to the ace_server_recipientid received in Section 4.2 and set the Recipient ID to the ace_client_recipientid sent in Section 4.1. The client MUST set the Master Secret from the parameter received from the AS in Section 3.2. The client MUST set the AEAD algorithm, ID Context, HKDF, and OSCORE version from the parameters received from the AS in Section 3.2, if present. In case an optional parameter is omitted, the default value SHALL be used as described in Sections 3.2 and 5.4 of [RFC8613]. After that, the client MUST derive the complete Security Context following Section 3.2.1 of [RFC8613]. From this point on, the client MUST use this Security Context to communicate with the RS when accessing the resources as specified by the authorization information.¶

If any of the expected parameters are missing (e.g., any of the mandatory parameters from the AS or the RS), or if ace_client_recipientid equals ace_server_recipientid (and as a consequence, the Sender and Recipient Keys derived would be equal; see Section 3.3 of [RFC8613]), then the client MUST stop the exchange and MUST NOT derive the Security Context. The client MAY restart the exchange, to get the correct security material.¶

The client then uses this Security Context to send requests to the RS using OSCORE.¶

After sending the 2.01 (Created) response, the RS MUST set the Master Salt of the Security Context created to communicate with the client to the concatenation of salt, N1, and N2 in the same way described above. An example of Master Salt construction using CBOR encoding is given in Figure 12 and using base64 encoding is given in Figure 13. The RS MUST set the Sender ID from the ace_client_recipientid received in Section 4.1 and set the Recipient ID from the ace_server_recipientid sent in Section 4.2. The RS MUST set the Master Secret from the parameter received from the AS and forwarded by the client in the access token in Section 4.1 after validation of the token as specified in Section 4.2. The RS MUST set the AEAD algorithm, ID Context, HKDF, and OSCORE version from the parameters received from the AS and forwarded by the client in the access token in Section 4.1 after validation of the token as specified in Section 4.2, if present. In case an optional parameter is omitted, the default value SHALL be used as described in Sections 3.2 and 5.4 of [RFC8613]. After that, the RS MUST derive the complete Security Context following Section 3.2.1 of [RFC8613] and MUST associate this Security Context with the authorization information from the access token.¶

The RS then uses this Security Context to verify requests and send responses to the client using OSCORE. If OSCORE verification fails, error responses are used, as specified in Section 8 of [RFC8613]. Additionally, if OSCORE verification succeeds, the verification of access rights is performed as described in Section 4.4. The RS MUST NOT use the Security Context after the related token has expired and MUST respond with an unprotected 4.01 (Unauthorized) error message to requests received that correspond to a Security Context with an expired token.¶

Note that the ID Context can be assigned by the AS, communicated and set in both the RS and client after the exchange specified in this profile is executed. Subsequently, the client and RS can update their ID Context by running a mechanism such as the one defined in Appendix B.2 of [RFC8613] if they both support it and are configured to do so. In that case, the ID Context in the OSCORE Security Context will not match the contextId parameter of the corresponding OSCORE_Input_Material. Running Appendix B.2 results in the keying material being updated in the Security Contexts of the client and RS; this same result can also be achieved by the client reposting the access token to the unprotected /authz-info endpoint at the RS, as described in Section 4.1, but without updating the ID Context.¶

4.4. Access Rights Verification

The RS MUST follow the procedures defined in Section 5.8.2 of [RFC9200]: if an RS receives an OSCORE-protected request from a client, then the RS processes it according to [RFC8613]. If OSCORE verification succeeds, and the target resource requires authorization, the RS retrieves the authorization information using the access token associated to the Security Context. The RS then must verify that the authorization information covers the resource and the action requested.¶