OSCORE Profile of the Authentication and Authorization for Constrained Environments Framework

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", and "verify" are taken from [RFC4949].¶

RESTful terminology follows HTTP [RFC7231].¶

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) [I-D.ietf-cbor-7049bis] and Concise Data Definition Language (CDDL) [RFC8610] are used in this specification. CDDL predefined type names, especially bstr for CBOR byte strings and tstr for CBOR text strings, are used extensively in the document.¶

Note that the term "endpoint" is used here, as in [I-D.ietf-ace-oauth-authz], 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 [RFC7252] definition, which is "An entity participating in the CoAP protocol" is not used in this memo.¶

3.1. C-to-AS: POST to token endpoint

The client-to-AS request is specified in Section 5.6.1 of [I-D.ietf-ace-oauth-authz].¶

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, with payload in CBOR diagnostic notation without the tag and value abbreviations is reported in Figure 2¶

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

If the client wants to update its access rights without changing an existing OSCORE Security Context, it MUST include in its POST request to the token endpoint a req_cnf object, 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.6.1 of [I-D.ietf-ace-oauth-authz]), can be used by the AS to determine the shared secret bound to the proof-of-possession token and therefore 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.6.3 of [I-D.ietf-ace-oauth-authz].¶

An example of such a request, with payload in CBOR diagnostic notation without the tag and value abbreviations is reported in Figure 3¶

    Header: POST (Code=0.02)
    Uri-Host: "as.example.com"
    Uri-Path: "token"
    Content-Format: "application/ace+cbor"
    Payload:
    {
      "req_aud" : "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.6.2 of [I-D.ietf-ace-oauth-authz]. If the client request was invalid, or not authorized, the AS returns an error response as described in section 5.6.3 of [I-D.ietf-ace-oauth-authz].¶

The AS can signal that the use of OSCORE is REQUIRED for a specific access token by including the "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 pre-configured 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¶
• 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 [I-D.ietf-ace-oauth-params], as the value of a field named 'osc', registered in Section 9.5 and Section 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, this parameters MUST be communicated as the 'contextId' field in the OSCORE_Input_Material. The applications 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' parameeter of the access token response. If included, the AEAD algorithm is sent 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. This profile RECOMMENDS the use of CBOR web token (CWT) as specified in [RFC8392]. 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 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, with payload in CBOR diagnostic notation without the tag and value abbreviations. 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)',
      "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, in CBOR diagnostic notation without tag and value abbreviations.¶

{
  "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 [I-D.ietf-ace-oauth-authz] 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 easiness of readability.¶

NOTE TO THE RFC EDITOR: before publishing, it should be checked (and in case fixed) that the values used below (which are not yet registered) are the final values registered in IANA.¶

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, with payload in CBOR diagnostic notation without the tag and value abbreviations. 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)',
      "profile" : "coap_oscore",
      "expires_in" : "3600"
    }

Figure 8 shows an example CWT Claims Set, containing the necessary OSCORE parameters in the 'cnf' claim for update of access rights, in CBOR diagnostic notation without tag and value abbreviations.¶

  {
    "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 very unlikely to have been previously used with the same input keying material. This profile RECOMMENDS to use a 64-bit long random number as nonce's value. 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 [I-D.ietf-ace-oauth-authz] 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 [I-D.ietf-ace-oauth-authz], 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 [I-D.ietf-ace-oauth-authz]. 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 nonces will be used.¶

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

Figure 10 shows an example of the request sent from the client to the RS, with payload in CBOR diagnostic notation without the tag and value abbreviations. 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 are 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 [I-D.ietf-ace-oauth-authz]: 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 is missing (e.g., any of the mandatory parameters from the AS or the identifier 'id1'), or if any parameters received in the 'osc' field is 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.7.1 of [I-D.ietf-ace-oauth-authz]) to validate the token before responding to the POST request to the authz-info endpoint.¶

Additionally, the RS MUST generate a nonce N2 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. This profile RECOMMENDS to use a 64-bit long random number as nonce's value. The RS MUST use the Content-Format "application/ace+cbor" defined in section 8.14 of [I-D.ietf-ace-oauth-authz].¶

Figure 11 shows an example of the response sent from the RS to the client, with payload in CBOR diagnostic notation without the tag and value abbreviations.¶

      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 [I-D.ietf-ace-oauth-authz], 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 a 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 was 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 [I-D.ietf-ace-oauth-authz], 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 receiving the 2.01 (Created) response 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, where salt is the CBOR byte string received from the AS in Section 3.2, and where 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 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 is missing (e.g., any of the mandatory parameters from the AS or the RS), or if ace_client_recipientid equals ace_server_recipientid, 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 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 Section 4.4. The RS MUST NOT use the Security Context after the related token has expired, and MUST respond with a 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, 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 in the Security Contexts of client and RS being updated; 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 [I-D.ietf-ace-oauth-authz]: 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.¶