Notification of Revoked Access Tokens in the Authentication and Authorization for Constrained Environments (ACE) 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.¶

Readers are expected to be familiar with the terms and concepts described in the ACE framework for Authentication and Authorization [RFC9200], as well as with terms and concepts related to CBOR Web Tokens (CWTs) [RFC8392] and JSON Web Tokens (JWTs) [RFC7519].¶

The terminology for entities in the considered architecture is defined in OAuth 2.0 [RFC6749]. In particular, this includes client, resource server (RS), and authorization server (AS).¶

Readers are also expected to be familiar with the terms and concepts related to CDDL [RFC8610], CBOR [RFC8949], JSON [RFC8259], COSE [RFC9052], CoAP [RFC7252], CoAP Observe [RFC7641], and the use of hash functions to name objects as defined in [RFC6920].¶

Note that the term "endpoint" is used here following its OAuth definition [RFC6749], aimed at denoting resources such as /token and /introspect at the AS, and /authz-info at the RS. This document does not use the CoAP definition of "endpoint", which is "An entity participating in the CoAP protocol."¶

This specification also refers to the following terminology.¶

• Token hash: identifier of an access token, in binary format encoding. The token hash has no relation to other access token identifiers possibly used, such as the 'cti' (CWT ID) claim of CBOR Web Tokens (CWTs) [RFC8392].¶

• Token Revocation List (TRL): a collection of token hashes such that the corresponding access tokens have been revoked but are not expired yet.¶

• TRL endpoint: an endpoint at the AS with a TRL as its representation. The default name of the TRL endpoint in a url-path is '/revoke/trl'. Implementations are not required to use this name, and can define their own instead.¶

• Registered device: a device registered at the AS, i.e., as a client, or an RS, or both. A registered device acts as a requester towards the TRL endpoint.¶

• Administrator: entity authorized to get full access to the TRL at the AS, and acting as a requester towards the TRL endpoint. An administrator is not necessarily a registered device as defined above, i.e., a client requesting access tokens or an RS consuming access tokens.¶

  An administrator might also be authorized to perform further administrative operations at the AS, e.g., through a dedicated admin interface that is out of the scope of this document. By considering the token hashes retrieved from the TRL together with other information obtained from the AS, the administrator becomes able to derive additional information, e.g., the fact that accesses have been revoked for specific registered devices.¶

• Pertaining access token:¶

  • With reference to an administrator, an access token issued by the AS.¶

  • With reference to a registered device, an access token intended to be owned by that device. An access token pertains to a client if the AS has issued the access token for that client following its request. An access token pertains to an RS if the AS has issued the access token to be consumed by that RS.¶

• Token hash pertaining to a requester: a token hash corresponding to an access token pertaining to that requester, i.e., an administrator or a registered device.¶

• TRL update pertaining to a requester: an update to the TRL through which token hashes pertaining to that requester have been added to the TRL or removed from the TRL.¶

• Full query: a type of query to the TRL, where the AS returns the token hashes of the revoked access tokens currently in the TRL and pertaining to the requester. Further details are specified in Section 6 and Section 7.¶

• Diff query: a type of query to the TRL, where the AS returns a list of diff entries, each related to one update occurred to the TRL and containing a set of token hashes pertaining to the requester. Further details are specified in Section 6 and Section 8.¶

Examples throughout this document are expressed in CBOR diagnostic notation as defined in Section 8 of [RFC8949] and Appendix G of [RFC8610]. Diagnostic notation comments are often used to provide a textual representation of the numeric parameter names and values.¶

In the CBOR diagnostic notation used in this document, constructs of the form e'SOME_NAME' are replaced by the value assigned to SOME_NAME in the CDDL model shown in Figure 15 of Appendix D. For example, {e'full_set': [], e'cursor': 3} stands for {0: [], 2: 3}.¶

Note to RFC Editor: Please delete the paragraph immediately preceding this note. Also, in the CBOR diagnostic notation used in this document, please replace the constructs of the form e'SOME_NAME' with the value assigned to SOME_NAME in the CDDL model shown in Figure 15 of Appendix D. Finally, please delete this note.¶

4.1. Motivation for the Used Construction

An access token can have one among different formats. The most expected formats are CWT [RFC8392] and JWT [RFC7519], with the former being the default format to use in the ACE framework (see Section 3 of [RFC9200]). While access tokens are opaque to clients, an RS is aware of whether access tokens that are issued for it to consume are either CWTs or JWTs.¶

4.2. Hash Input on the Client and the AS

The client and the AS consider the content of the 'access_token' parameter in the AS-to-Client response, where the (tagged) access token is included and provided to the requester client.¶

The following defines how the client and the AS determine the HASH_INPUT value to use as input for computing the token hash of the conveyed access token, depending on the AS-to-Client response being encoded in CBOR (see Section 4.2.1) or in JSON (see Section 4.2.2).¶

Once determined HASH_INPUT, the client and the AS use it to compute the token hash of the conveyed access token as defined in Section 4.4.¶

Header: Created (Code=2.01)
Content-Format: application/ace+cbor
Max-Age: 85800
Payload:
{
   / access_token / 1 : h'd83dd0835820a3010a044c53796d6d
                          6574726963313238054d99a0d7846e
                          762c49ffe8a63e0ba05858b918a11f
                          d81e438b7f973d9e2e119bcb22424b
                          a0f38a80f27562f400ee1d0d6c0fdb
                          559c02421fd384fc2ebe22d7071378
                          b0ea7428fff157444d45f7e6afcda1
                          aae5f6495830c58627087fc5b4974f
                          319a8707a635dd643b',
   / token_type /  34 : 2 / PoP /,
   / expires_in /   2 : 86400,
   / ace_profile / 38 : 1 / coap_dtls /,
   / (remainder of the response omitted for brevity) /
}

HTTP/1.1 200 OK
Content-Type: application/ace+json
Cache-Control: no-store
Pragma: no-cache
Payload:
{
   "access_token" : "eyJhbGciOiJSU0ExXzUiLCJlbmMiOiJB
                     MTI4Q0JDLUhTMjU2In0.
                     QR1Owv2ug2WyPBnbQrRARTeEk9kDO2w8
                     qDcjiHnSJflSdv1iNqhWXaKH4MqAkQtM
                     oNfABIPJaZm0HaA415sv3aeuBWnD8J-U
                     i7Ah6cWafs3ZwwFKDFUUsWHSK-IPKxLG
                     TkND09XyjORj_CHAgOPJ-Sd8ONQRnJvW
                     n_hXV1BNMHzUjPyYwEsRhDhzjAD26ima
                     sOTsgruobpYGoQcXUwFDn7moXPRfDE8-
                     NoQX7N7ZYMmpUDkR-Cx9obNGwJQ3nM52
                     YCitxoQVPzjbl7WBuB7AohdBoZOdZ24W
                     lN1lVIeh8v1K4krB8xgKvRU8kgFrEn_a
                     1rZgN5TiysnmzTROF869lQ.
                     AxY8DCtDaGlsbGljb3RoZQ.
                     MKOle7UQrG6nSxTLX6Mqwt0orbHvAKeW
                     nDYvpIAeZ72deHxz3roJDXQyhxx0wKaM
                     HDjUEOKIwrtkHthpqEanSBNYHZgmNOV7
                     sln1Eu9g3J8.
                     fiK51VwhsxJ-siBMR-YFiA",
   "token_type"   : "pop",
   "expires_in"   : 86400,
   "ace_profile"  : "1"
}

4.3. HASH_INPUT on the RS

The following defines how the RS determines the HASH_INPUT value to use as input for computing the token hash of an access token, depending on the RS using either CWTs (see Section 4.3.1) or JWTs (see Section 4.3.2).¶

4.4. Computing the Token Hash

Once determined HASH_INPUT as defined in Section 4.2 and Section 4.3, a hash value of HASH_INPUT is generated as per Section 6 of [RFC6920]. The resulting output in binary format is used as the token hash. Note that the used binary format embeds the identifier of the used hash function, in the first byte of the computed token hash.¶

The specifically used hash function MUST be collision-resistant on byte-strings, and MUST be selected from the "Named Information Hash Algorithm" Registry [Named.Information.Hash.Algorithm]. Consistent with the compliance requirements in Section 2 of [RFC6920], the hash function sha-256 as specified in [SHA-256] is mandatory to implement.¶

The AS specifies the used hash function to registered devices during their registration procedure (see Section 10).¶

5.1. Update of the TRL

The AS updates the TRL in the following two cases.¶

• When a non-expired access token is revoked, the token hash of the access token is added to the TRL. That is, a CBOR byte string with the token hash as its value is added to the CBOR array encoding the TRL.¶

• When a revoked access token expires, the token hash of the access token is removed from the TRL. That is, the CBOR byte string with the token hash as its value is removed from the CBOR array encoding the TRL.¶

The AS MAY perform a single update to the TRL such that one or more token hashes are added or removed at once. For example, this can be the case if multiple access tokens are revoked or expire at the same time, or within an acceptably narrow time window.¶

6.1. Error Responses with Problem Details

Some error responses from the TRL endpoint at the AS can convey error-specific information according to the problem-details format defined in [RFC9290]. Such error responses MUST have Content-Format set to "application/concise-problem-details+cbor". The payload of these error responses MUST be a CBOR map specifying a Concise Problem Details data item (see Section 2 of [RFC9290]). The CBOR map is formatted as follows.¶

• It MUST include the Custom Problem Detail entry 'ace-trl-error' registered in Section 15.3 of this document. This entry is formatted as a CBOR map, which includes the following fields.¶

  • The field 'error-id' MUST be present. The map key used for this field is the CBOR unsigned integer with value 0. The value of this field is a CBOR integer specifying the error occurred at the AS. This value is taken from the 'Value' column of the "ACE Token Revocation List Errors" registry defined in Section 15.5 of this document.¶

  • The field 'cursor' MAY be present. The map key used for this field is the CBOR unsigned integer with value 1. The value of this field is a CBOR unsigned integer or the CBOR simple value null (0xf6). The use of this field is defined in Section 6.3.¶

  The CDDL notation [RFC8610] of the 'ace-trl-error' entry is given below.¶

   ace-trl-error = {
       0: int,        ; error-id
     ? 1: uint / null ; cursor
   }

• It MAY include further Standard Problem Detail entries or Custom Problem Detail entries (see [RFC9290]).¶

  In particular, it can include the Standard Problem Detail entry 'detail' (map key -2), whose value is a CBOR text string that specifies a human-readable, diagnostic description of the error occurred at the AS. The diagnostic text is intended for software engineers as well as for device and network operators, in order to aid debugging and provide context for possible intervention. The diagnostic message SHOULD be logged by the AS. The 'detail' entry is unlikely relevant in an unattended setup where human intervention is not expected.¶

An example of error response using the problem-details format is shown in Figure 5.¶

Header: Bad Request (Code=4.00)
Content-Format: application/concise-problem-details+cbor
Payload:
{
  / title /     -1: "Invalid parameter value",
  / detail /    -2: "Invalid value for 'cursor': -53",
  / ace-trl-error / e'ace-trl-error': {
    / error-id / 0: 0 / "Invalid parameter value" /,
    / cursor /   1: 42
  }
}

The problem-details format in general and the Custom Problem Detail entry 'ace-trl-error' in particular are OPTIONAL to support for registered devices. A registered device supporting the entry 'ace-trl-error' and able to understand the specified error may use that information to determine what actions to take next.¶

6.2. Supporting Diff Queries

If the AS supports diff queries, it is able to transfer a list of diff entries, each of which is related to one update occurred to the TRL (see Section 6). That is, when replying to a diff query performed by a requester, the AS specifies the diff entries related to the most recent TRL updates pertaining to the requester.¶

The following defines how the AS builds and maintains an ordered list of diff entries, for each registered device and administrator, hereafter referred to as requesters. In particular, a requester's diff entry associated with a TRL update contains a set of token hashes pertaining to that requester, which were added to the TRL or removed from the TRL at that update.¶

The AS defines the single, constant positive integer MAX_N >= 1. For each requester, the AS maintains an update collection of maximum MAX_N series items, each of which is a diff entry. For each requester, the AS MUST keep track of the MAX_N most recent TRL updates pertaining to the requester. If the AS supports diff queries, the AS MUST provide requesters with the value of MAX_N, upon their registration (see Section 10).¶

The series items in the update collection MUST be strictly ordered in a chronological fashion. That is, at any point in time, the current first series item is the one least recently added to the update collection and still retained by the AS, while the current last series item is the one most recently added to the update collection. The particular method used to achieve this is implementation-specific.¶

Each time the TRL changes, the AS performs the following operations for each requester.¶

1. The AS considers the subset of the TRL pertaining to that requester. If the TRL subset is not affected by this TRL update, the AS stops the processing for that requester. Otherwise, the AS moves to step 2.¶

2. The AS creates two sets "trl_patch" of token hashes, i.e., one "removed" set and one "added" set, as related to this TRL update.¶

3. The AS fills the two sets with the token hashes of the removed and added access tokens, respectively, from/to the TRL subset considered at step 1.¶

4. The AS creates a new series item, which includes the two sets from step 3.¶

5. If the update collection associated with the requester currently includes MAX_N series items, the AS MUST delete the oldest series item in the update collection.¶

6. The AS adds the series item to the update collection associated with the requester, as the last (most recent) one.¶

6.3. Query Parameters

A GET request to the TRL endpoint can include the following query parameters. The AS MUST silently ignore unknown query parameters.¶

• 'diff': if included, it indicates to perform a diff query of the TRL (see Section 8). Its value MUST be either:¶

  • the integer 0, indicating that a (notification) response should include as many diff entries as the AS can provide in the response; or¶

  • a positive integer strictly greater than 0, indicating the maximum number of diff entries that a (notification) response should include.¶

  If the AS does not support diff queries, it ignores the 'diff' query parameter when present in the GET request, and proceeds like when processing a full query of the TRL (see Section 7).¶

  Otherwise, the AS MUST return a 4.00 (Bad Request) response in case the 'diff' query parameter of the GET request specifies a value that is neither 0 nor a positive integer, irrespective of the presence of the 'cursor' parameter and its value (see below). The response MUST have Content-Format "application/concise-problem-details+cbor" and its payload is formatted as defined in Section 6.1. Within the Custom Problem Detail entry 'ace-trl-error', the value of the 'error-id' field MUST be set to 0 ("Invalid parameter value"), and the field 'cursor' MUST NOT be present.¶

• 'cursor': if included, it indicates to perform a diff query of the TRL together with the "Cursor" extension, as defined in Section 9.2. Its value MUST be either 0 or a positive integer. If the 'cursor' query parameter is included, then the 'diff' query parameter MUST also be included.¶

  If included, the 'cursor' query parameter specifies an unsigned integer value that was provided by the AS in a previous response from the TRL endpoint (see Section 9.1, Section 9.2.2, and Section 9.2.3).¶

  If the AS does not support the "Cursor" extension, it ignores the 'cursor' query parameter when present in the GET request. In such a case, the AS proceeds as specified elsewhere in this document, i.e.: i) it performs a diff query of the TRL (see Section 8), if it supports diff queries and the 'diff' query parameter is present in the GET request; or ii) it performs a full query of the TRL (see Section 7) otherwise.¶

  If the AS supports both diff queries and the "Cursor" extension, and the GET request specifies the 'cursor' query parameter, then the AS MUST return a 4.00 (Bad Request) response in case any of the conditions below holds.¶

  The 4.00 (Bad Request) response MUST have Content-Format "application/concise-problem-details+cbor" and its payload is formatted as defined in Section 6.1.¶

  • The GET request does not specify the 'diff' query parameter, irrespective of the value of the 'cursor' parameter.¶

    Within the Custom Problem Detail entry 'ace-trl-error', the value of the 'error-id' field MUST be set to 1 ("Invalid set of parameters"), and the field 'cursor' MUST NOT be present.¶

  • The 'cursor' query parameter has a value that is neither 0 nor a positive integer, or it has a value strictly greater than MAX_INDEX (see Section 6.2.1).¶

    Within the Custom Problem Detail entry 'ace-trl-error', the value of the 'error-id' field MUST be set to 0 ("Invalid parameter value"). The entry 'ace-trl-error' MUST include the field 'cursor', whose value is either: the CBOR simple value null (0xf6), if the update collection associated with the requester is empty; or the corresponding current value of 'last_index' otherwise.¶

  • All of the following hold: the update collection associated with the requester is not empty; no wrap-around of its 'index' value has occurred; and the 'cursor' query parameter has a value strictly greater than the current 'last_index' on the update collection (see Section 6.2.1).¶

    Within the Custom Problem Detail entry 'ace-trl-error', the value of the 'error-id' field MUST be set to 2 ("Out of bound cursor value"), and the field 'cursor' MUST NOT be present.¶

9.1. Response to Full Query

When processing a full query request to the TRL endpoint, the AS composes a response as defined in Section 7.¶

In particular, the 'cursor' parameter included in the CBOR map carried in the response payload specifies either the CBOR simple value null (0xf6) or a CBOR unsigned integer.¶

The 'cursor' parameter MUST specify the CBOR simple value null in case there are currently no TRL updates pertaining to the requester, i.e., the update collection for that requester is empty. This is the case from when the requester registers at the AS until the first update pertaining to that requester occurs to the TRL.¶

Otherwise, the 'cursor' parameter MUST specify a CBOR unsigned integer. This MUST take the 'index' value of the last series item in the update collection associated with the requester (see Section 6.2.1), as corresponding to the most recent TRL update pertaining to the requester. Such a value is in fact the current value of 'last_index' for the update collection associated with the requester.¶

9.2. Response to Diff Query

When processing a diff query request to the TRL endpoint, the AS composes a response as defined in the following.¶

11.1. Handling of Revoked Access Tokens and Token Hashes

When receiving a response from the TRL endpoint, a registered device MUST expunge every stored access token associated with a token hash specified in the response. In case the registered device is an RS, it MUST NOT delete the stored token hash after having expunged the associated access token.¶

If an RS uses the method defined in this document with the AS that has issued an access token, then the RS MUST NOT accept and store that access token if any of the following holds.¶

• The token hash corresponding to the access token is among the currently stored ones.¶

• The access token is a CWT and any of the following holds.¶

  • The access token includes a non-empty "unprotected" field, i.e., the value of the field is not encoded as the empty CBOR map (0xa0). This applies to: the top-level "unprotected" field of the COSE object used for the CWT; the "unprotected" field of each element of the "signatures" array; and the "unprotected" field of each element of any "recipients" array.¶

  • The received CBOR data item that embodies the access token does not comply with what is defined in Section 3. This concerns: the use of exactly two nested CBOR tags, where the outer tag is the CWT CBOR tag and the inner tag is one of the COSE CBOR tags; the tag numbers encoded with the minimum possible length; and the access token being the innermost tag content of the received CBOR data item.¶

  • In the received CBOR data item that embodies the access token, the inner tag has a tag number that is not consistent with the actual COSE data item to process. For instance, the inner tag number is 16 (COSE_Encrypt0), but the CWT is actually a COSE_Sign data item.¶

• The access token relies on a JSON object for encoding its claims, but it is not a JWT [RFC7519] and any of the following holds.¶

  • The access token uses the JWS JSON Serialization from [RFC7515], and it includes the JWS Unprotected Header.¶

  • The access token uses the JWE JSON Serialization from [RFC7516], and it includes the JWE Shared Unprotected Header and/or includes the "header" member in any of the elements of the "recipients" array.¶

An RS MUST store the token hash th1 corresponding to an access token t1 until both the following conditions hold.¶

• The RS has received and seen t1, irrespective of having accepted and stored it.¶

• The RS has gained knowledge that t1 has expired. This can be achieved, e.g., through the following means.¶

  • A response from the TRL endpoint indicating that t1 has expired after its earlier revocation, i.e., the token hash th1 has been removed from the TRL. This can be indicated, for instance, in a response from the TRL endpoint following a diff query of the TRL (see Section 8).¶

  • The value of the 'exp' claim specified in t1 indicates that t1 has expired.¶

  • The locally determined expiration time for t1 has passed, based on the time at the RS when t1 was first accepted and on the value of its 'exi' claim.¶

  • The result of token introspection performed on t1 (see Section 5.9 of [RFC9200]), if supported by both the RS and the AS.¶

The RS MUST NOT delete the stored token hashes whose corresponding access tokens do not fulfill both the two conditions above, unless it becomes necessary due to memory limitations. In such a case, the RS MUST delete the earliest stored token hashes first.¶

Retaining the stored token hashes as specified above limits the impact from a (dishonest) client whose pertaining access token: i) specifies the 'exi' claim; ii) is uploaded at the RS for the first time after it has been revoked and later expired; and iii) has the sequence number encoded in the 'cti' claim (for CWTs) or in the 'jti' claim (for JWTs) greater than the highest sequence number among the expired access tokens specifying the 'exi' claim for the RS (see Section 5.10.3 of [RFC9200]). That is, the RS would not accept such a revoked and expired access token as long as it stores the corresponding token hash.¶

In order to further limit such a risk, when receiving an access token that specifies the 'exi' claim and for which a corresponding token hash is not stored, the RS can introspect the access token (see Section 5.9 of [RFC9200]), if token introspection is implemented by both the RS and the AS.¶

When, due to the stored and corresponding token hash th2, an access token t2 that includes the 'exi' claim is expunged or is not accepted upon its upload, the RS retrieves the sequence number sn2 encoded in the 'cti' claim (for CWTs) or in the 'jti' claim (for JWTs) (see Section 5.10.3 of [RFC9200]). Then, the RS stores sn2 as associated with th2. If expunging or not accepting t2 yields the deletion of th2, then the RS MUST associate sn2 with th2 before continuing with the deletion of th2.¶

When deleting any token hash, the RS checks whether the token hash is associated with a sequence number sn_th. In such a case, the RS checks whether sn_th is greater than the highest sequence number sn* among the expired access tokens specifying the 'exi' claim for the RS. If that is the case, sn* MUST take the value of sn_th.¶

By virtue of what is defined in Section 5.10.3 of [RFC9200], this ensures that, following the deletion of the token hash associated with an access token specifying the 'exi' claim and uploaded for the first time after it has been revoked and later expired, the RS will not accept the access token at that point in time or in the future.¶

14.1. Content Retrieval from the TRL

The AS MUST ensure that each registered device can access and retrieve only its pertaining subset of the TRL. To this end, the AS can always perform the required filtering based on the authenticated identity of the registered device, i.e., a (non-public) identifier that the AS can securely relate to the registered device and the secure association that they use to communicate.¶

The AS MUST ensure that, other than registered devices accessing their own pertaining subset of the TRL, only authorized and authenticated administrators can access the content of the whole TRL (see Section 10).¶

Note that the TRL endpoint supports only the GET method (see Section 6). Therefore, as detailed in Section 7 and Section 8, accesses to the TRL endpoint are performed only by means of protected and authenticated GET requests, which by definition are safe in the REST sense and do not alter the content of the TRL. That is, registered devices and administrators can perform exclusively read-only operations when accessing the TRL endpoint.¶

In fact, the content of the TRL can be updated only internally by the AS, in the two circumstances described in Section 5.1. Therefore, an adversary that is not in control of the AS cannot manipulate the content of the TRL, e.g., by removing a token hash and thereby fraudulently allowing a client to access protected resources in spite of a revoked access token, or by adding a token hash and thereby fraudulently stopping a client from accessing protected resources in spite of an access token being still valid.¶

14.2. Size of the TRL

If many non-expired access tokens associated with a registered device are revoked, the pertaining subset of the TRL could grow to a size bigger than what the registered device is prepared to handle upon reception of a response from the TRL endpoint, especially if relying on a full query of the TRL (see Section 7).¶

This could be exploited by attackers to negatively affect the behavior of a registered device. Therefore, in order to help reduce the size of the TRL, the AS SHOULD refrain from issuing access tokens with an excessively long expiration time.¶

14.3. Communication Patterns

The communication about revoked access tokens presented in this specification is expected to especially rely on CoAP Observe notifications sent from the AS to a requester (i.e., an administrator or a registered device). The suppression of those notifications by an external attacker that has access to the network would prevent requesters from ever knowing that their pertaining access tokens have been revoked.¶

In order to avoid this, a requester SHOULD NOT rely solely on the CoAP Observe notifications. In particular, a requester SHOULD also regularly poll the AS for the most current information about revoked access tokens, by sending GET requests to the TRL endpoint. Specific strategies and schedules for polling the AS are to be defined by a related application policy, by also taking into account the expected operational and availability patterns adopted by the requester (e.g., in the interest of energy saving and other optimizations).¶

14.4. Request of New Access Tokens

If a client stores an access token that it still believes to be valid, and it accordingly attempts to access a protected resource at the RS, the client may receive an unprotected 4.01 (Unauthorized) response from the RS.¶

This can be due to a number of causes. For example, the access token has been revoked, and the RS has become aware of it and has expunged the access token, but the client is not aware of it (yet). As another example, the access token is still valid, but an on-path active adversary might have injected a forged 4.01 (Unauthorized) response, or the RS might have deleted the access token from its local storage due to its dedicated storage space being all consumed.¶

In either case, if the client believes that the access token is still valid, it SHOULD NOT immediately ask for a new access token to the authorization server upon receiving a 4.01 (Unauthorized) response from the RS. Instead, the client SHOULD send a request to the TRL endpoint at the AS. If the client gains knowledge that the access token is not valid anymore, the client expunges the access token and can ask for a new one. Otherwise, the client can try again to upload the same access token to the RS, or instead to request a new one.¶

14.5. Vulnerable Time Window at the RS

A client may attempt to access a protected resource at an RS after the access token allowing such an access has been revoked, but before the RS is aware of the revocation.¶

In such a case, if the RS is still storing the access token, the client will be able to access the protected resource, even though it should not. Such an access is a security violation, even if the client is not attempting to be malicious.¶

In order to minimize such a risk, if an RS relies solely on polling through individual requests to the TRL endpoint to learn of revoked access tokens, the RS SHOULD implement an adequate trade-off between the polling frequency and the maximum length of the vulnerable time window.¶

14.6. Preventing Unnoticed Manipulation of Access Tokens

As defined in Section 3, issued access tokens MUST NOT rely on unprotected headers to specify information as header parameters. Also, when issued access tokens are CWTs, they MUST be tagged by using the COSE CBOR tag corresponding to the used COSE object, the result MUST be in turn tagged by using the CWT CBOR tag, and no further tagging is performed.¶

This ensures that the RS always computes the correct token hash corresponding to an access token, i.e., the same token hash computed by the AS and C for that access token.¶

By construction, the rules defined in Section 3 prevent an active adversary from successfully performing an attack against the RS, which would otherwise be possible in case the access token is uploaded to the RS over an unprotected communication channel.¶

In such an attack, the adversary intercepts the access token when this is sent to the RS. Then, the adversary manipulates the access token in a way which is going to be unnoticed by the RS, but without preventing the successful, cryptographic validation of the access token at the RS. To this end, the adversary has two possible options:¶

• Adding and/or removing fields within the unprotected header(s) of the access token, as long as those fields do not play a role in the cryptographic validation of the access token.¶

• Specifically when the access token is a CWT, adding/removing or manipulating possible CBOR tag(s) enclosing the access token.¶

After that, the adversary sends the manipulated access token to the RS.¶

After having successfully validated the manipulated access token, the RS computes a corresponding token hash different from the one computed and stored by C and the AS. Finally, the RS stores the manipulated access token and the corresponding wrong token hash.¶

Later on, if the access token is revoked and the AS provides the RS with the corresponding correct token hash, the RS does not recognize the received token hash among the stored ones, and therefore does not delete the revoked access token.¶

14.7. Two Token Hashes at the RS using JWTs

Section 4.3.2 defines that an RS using JWTs as access tokens has to compute and store two token hashes associated with the same access token. This is because, when using JWTs, the RS does not know for sure if the AS provided the access token to the client by means of an AS-to-Client response encoded in CBOR or in JSON.¶

Taking advantage of that, a dishonest client can attempt to perform an attack against the RS. That is, the client can first receive the JWT in an AS-to-Client response encoded in CBOR (JSON). Then, the client can upload the JWT to the RS in a way that makes the RS believe that the client instead received the JWT in an AS-to-Client response encoded in JSON (CBOR).¶

Consequently, the RS considers a HASH_INPUT different from the one considered by the AS and the client (see Section 4.2). Hence, the RS computes a token hash h' different from the token hash h computed by the AS and the client. It follows that, if the AS revokes the access token and advertises the right token hash h, then the RS will not learn about the access token revocation and thus will not delete the access token.¶

Fundamentally, this would happen because the HASH_INPUT used to compute the token hash of a JWT depends on whether the AS-to-Client response is encoded in CBOR or in JSON. This makes the RS vulnerable to the attack described above, when JWTs are used as access tokens. Instead, this is not a problem if the access token is a CWT, since the HASH_INPUT used to compute the token hash of a CWT does not depend on whether the AS-to-Client response is encoded in CBOR or in JSON.¶

While this asymmetry cannot be avoided altogether, the method defined for the AS and the client in Section 4.2 deliberately penalizes the case where the RS uses JWTs as access tokens. In such a case, the RS effectively neutralizes the attack described above, by computing and storing two token hashes associated with the same access token (see Section 4.3.2).¶

Conversely, this design deliberately favors the case where the RS uses CWTs as access tokens, which is a preferable option for resource-constrained RSs as well as the default case in the ACE framework (see Section 3 of [RFC9200]). That is, if an RS uses CWTs as access tokens, then the RS is not exposed to the attack described above, and thus it safely computes and stores only one token hash per access token (see Section 4.3.1).¶

14.8. Additional Security Measures

By accessing the TRL at the AS, registered devices and administrators are able to learn that their pertaining access tokens have been revoked. However, they cannot learn the reason why that happened, including when that reason is the compromise, misbehavior, or decommissioning of a registered device.¶

In fact, even the AS might not know that a registered device to which a revoked access token pertains has been specifically compromised, misbehaving, or decommissioned. At the same time, it might not be acceptable to only revoke the access tokens pertaining to such a registered device.¶

Therefore, in order to preserve the security of the system and application, the entity that authoritatively declares a registered device to be compromised, misbehaving, or decommissioned should also promptly trigger the execution of additional revocation processes as deemed appropriate. These include, for instance:¶

• The de-registration of the registered device from the AS, so that the AS does not issue further access tokens pertaining to that device.¶

• If applicable, the revocation of the public authentication credential associated with the registered device (e.g., its public key certificate).¶

The methods by which these processes are triggered and carried out are out of the scope of this document.¶

15.1. Media Type Registrations

IANA is asked to register the media type "application/ace-trl+cbor" for messages of the protocol defined in this document encoded in CBOR. This registration follows the procedures specified in [RFC6838].¶

Type name: application¶

Subtype name: ace-trl+cbor¶

Required parameters: N/A¶

Optional parameters: N/A¶

Encoding considerations: Must be encoded as a CBOR map containing the protocol parameters defined in [RFC-XXXX].¶

Security considerations: See Section 14 of this document.¶

Interoperability considerations: N/A¶

Published specification: [RFC-XXXX]¶

Applications that use this media type: The type is used by authorization servers, clients, and resource servers that support the notification of revoked access tokens, according to a Token Revocation List maintained by the authorization server as specified in [RFC-XXXX].¶

Fragment identifier considerations: N/A¶

Additional information: N/A¶

Person & email address to contact for further information: ACE WG mailing list ([email protected]) or IETF Applications and Real-Time Area ([email protected])¶

Intended usage: COMMON¶

Restrictions on usage: None¶

Author/Change controller: IETF¶

Provisional registration: No¶

15.2. CoAP Content-Formats Registry

IANA is asked to add the following entry to the "CoAP Content-Formats" registry within the "Constrained RESTful Environments (CoRE) Parameters" registry group.¶

Content Type: application/ace-trl+cbor¶

Content Coding: -¶

ID: TBD¶

Reference: [RFC-XXXX]¶

15.3. Custom Problem Detail Keys Registry

IANA is asked to register the following entry in the "Custom Problem Detail Keys" registry within the "Constrained RESTful Environments (CoRE) Parameters" registry group.¶

• Key Value: TBD¶

• Name: ace-trl-error¶

• Brief Description: Carry [RFC-XXXX] problem details in a Concise Problem Details data item.¶

• Change Controller: IETF¶

• Reference: Section 6.1 of [RFC-XXXX]¶

15.4. ACE Token Revocation List Parameters Registry

IANA is asked to establish the "ACE Token Revocation List Parameters" IANA registry within the "Authentication and Authorization for Constrained Environments (ACE)" registry group.¶

As registration policy, the registry uses either "Standards Action with Expert Review", or "Specification Required" per Section 4.6 of [RFC8126], or "Expert Review" per Section 4.5 of [RFC8126]. Expert Review guidelines are provided in Section 15.6.¶

All assignments according to "Standards Action with Expert Review" are made on a "Standards Action" basis per Section 4.9 of [RFC8126], with Expert Review additionally required per Section 4.5 of [RFC8126]. The procedure for early IANA allocation of Standards Track code points defined in [RFC7120] also applies. When such a procedure is used, IANA will ask the designated expert(s) to approve the early allocation before registration. In addition, WG chairs are encouraged to consult the expert(s) early during the process outlined in Section 3.1 of [RFC7120].¶

The columns of this registry are:¶

• Name: This field contains a descriptive name that enables easier reference to the item. The name MUST be unique and it is not used in the encoding.¶

• CBOR Key: This field contains the value used as CBOR map key of the item. The value MUST be unique. The value is an unsigned integer or a negative integer. Different ranges of values use different registration policies [RFC8126]. Integer values from -256 to 255 are designated as "Standards Action With Expert Review". Integer values from -65536 to -257 and from 256 to 65535 are designated as "Specification Required". Integer values greater than 65535 are designated as "Expert Review". Integer values less than -65536 are marked as "Private Use".¶

• CBOR Type: This field contains the allowable CBOR data types for values of this item, or a pointer to the registry that defines its type, when that depends on another item.¶

• Reference: This field contains a pointer to the public specification for the item.¶

This registry has been initially populated by the values in Section 12. The "Reference" column for all of these entries refers to this document.¶

15.5. ACE Token Revocation List Errors

IANA is asked to establish the "ACE Token Revocation List Errors" IANA registry within the "Authentication and Authorization for Constrained Environments (ACE)" registry group.¶

As registration policy, the registry uses either "Standards Action with Expert Review", or "Specification Required" per Section 4.6 of [RFC8126], or "Expert Review" per Section 4.5 of [RFC8126]. Expert Review guidelines are provided in Section 15.6.¶

All assignments according to "Standards Action with Expert Review" are made on a "Standards Action" basis per Section 4.9 of [RFC8126], with Expert Review additionally required per Section 4.5 of [RFC8126]. The procedure for early IANA allocation of Standards Track code points defined in [RFC7120] also applies. When such a procedure is used, IANA will ask the designated expert(s) to approve the early allocation before registration. In addition, WG chairs are encouraged to consult the expert(s) early during the process outlined in Section 3.1 of [RFC7120].¶

The columns of this registry are:¶

• Value: The field contains the value to be used to identify the error. The value MUST be unique. The value is an unsigned integer or a negative integer. Different ranges of values use different registration policies [RFC8126]. Integer values from -256 to 255 are designated as "Standards Action With Expert Review". Integer values from -65536 to -257 and from 256 to 65535 are designated as "Specification Required". Integer values greater than 65535 are designated as "Expert Review". Integer values less than -65536 are marked as "Private Use".¶

• Description: This field contains a brief description of the error.¶

• Reference: This field contains a pointer to the public specification defining the error, if one exists.¶

This registry has been initially populated by the values in Section 13. The "Reference" column for all of these entries refers to this document.¶

15.6. Expert Review Instructions

The IANA registries established in this document are defined as "Standards Action with Expert Review", "Specification Required", or "Expert Review", depending on the range of values for which an assignment is requested. This section gives some general guidelines for what the experts should be looking for, but they are being designated as experts for a reason so they should be given substantial latitude.¶

Expert reviewers should take into consideration the following points:¶

• Point squatting should be discouraged. Reviewers are encouraged to get sufficient information for registration requests to ensure that the usage is not going to duplicate one that is already registered and that the point is likely to be used in deployments. The zones tagged as private use are intended for testing purposes and closed environments. Code points in other ranges should not be assigned for testing.¶

• Specifications are required for the "Standards Action With Expert Review" range of point assignment. Specifications should exist for "Specification Required" ranges, but early assignment before a specification is available is considered to be permissible. For the "Expert Review" range of point assignment, specifications are recommended, and are needed if they are expected to be used outside of closed environments in an interoperable way. When specifications are not provided, the description provided needs to have sufficient information to identify what the point is being used for.¶

• Experts should take into account the expected usage of fields when approving point assignment. The fact that there is a range for Standards Track documents does not mean that a Standards Track document cannot have points assigned outside of that range. The length of the encoded value should be weighed against how many code points of that length are left, the size of device it will be used on, and the number of code points left that encode to that size.¶

C.1. Full Query with Observe

Figure 10 shows an interaction example considering a CoAP observation and a full query of the TRL.¶

In this example, the AS does not support the "Cursor" extension. Hence, the 'cursor' parameter is not included in the payload of the responses to a full query request.¶

C.2. Diff Query with Observe

Figure 11 shows an interaction example considering a CoAP observation and a diff query of the TRL.¶

The RS indicates N = 3 as value of the 'diff' query parameter, i.e., as the maximum number of diff entries to be specified in a response from the AS.¶

In this example, the AS does not support the "Cursor" extension. Hence, the 'cursor' parameter and the 'more' parameter are not included in the payload of the responses to a diff query request.¶

C.3. Full Query with Observe plus Diff Query

Figure 12 shows an interaction example considering a CoAP observation and a full query of the TRL.¶

The example also considers one of the notifications from the AS to get lost in transmission, and thus not reaching the RS.¶

When this happens, and after a waiting time defined by the application has elapsed, the RS sends a GET request with no Observe Option to the AS, to perform a diff query of the TRL. The RS indicates N = 8 as value of the 'diff' query parameter, i.e., as the maximum number of diff entries to be specified in a response from the AS.¶

In this example, the AS does not support the "Cursor" extension. Hence, the 'cursor' parameter is not included in the payload of the responses to a full query request. Also, the 'cursor' parameter and the 'more' parameter are not included in the payload of the responses to a diff query request.¶

C.4. Diff Query with Observe and "Cursor"

In this example, the AS supports the "Cursor" extension. Hence, the CBOR map conveyed as payload of the registration response additionally includes a "max_diff_batch" parameter. This specifies the value of MAX_DIFF_BATCH, i.e., the maximum number of diff entries that can be included in a response to a diff query request from this RS.¶

Figure 13 shows an interaction example considering a CoAP observation and a diff query of the TRL.¶

The RS specifies the query parameter 'diff' with value 3, i.e., the maximum number of diff entries to be specified in a response from the AS.¶

After the RS has not received a notification from the AS for a waiting time defined by the application, the RS sends a GET request with no Observe Option to the AS, to perform a diff query of the TRL.¶

This is followed up by a further diff query request that specifies the query parameter 'cursor'. Note that the payload of the corresponding response differs from the payload of the response to the previous diff query request.¶

C.5. Full Query with Observe plus Diff Query with "Cursor"

In this example, the AS supports the "Cursor" extension. Hence, the CBOR map conveyed as payload of the registration response additionally includes a "max_diff_batch" parameter. This specifies the value of MAX_DIFF_BATCH, i.e., the maximum number of diff entries that can be included in a response to a diff query request from this RS.¶

Figure 14 shows an interaction example considering a CoAP observation and a full query of the TRL.¶

The example also considers some of the notifications from the AS to get lost in transmission, and thus not reaching the RS.¶

When this happens, and after a waiting time defined by the application has elapsed, the RS sends a GET request with no Observe Option to the AS, to perform a diff query of the TRL. In particular, the RS specifies:¶

• The query parameter 'diff' with value 8, i.e., the maximum number of diff entries to be specified in a response from the AS.¶

• The query parameter 'cursor' with value 2, thus requesting from the update collection the series items following the one with 'index' value equal to 2 (i.e., following the last series item that the RS successfully received in an earlier notification response).¶

The response from the AS conveys a first batch of MAX_DIFF_BATCH = 5 series items from the update collection corresponding to the RS. The AS indicates that further series items are actually available in the update collection, by setting the 'more' parameter of the response to true. Also, the 'cursor' parameter of the response is set to 7, i.e., to the 'index' value of the most recent series item included in the response.¶

After that, the RS follows up with a further diff query request specifying the query parameter 'cursor' with value 7, in order to retrieve the next and last batch of series items from the update collection.¶

E.1. Version -08 to -09

• Terminology:¶

  • Improved definition of "administrator".¶

  • Added early definitions of "Full query" and "Diff query".¶

• Rephrased "full TRL" to avoid confusion with "full query".¶

• Consistent with RFC 6920, defined sha-256 as mandatory to implement.¶

• Prevented an attack to the RS by:¶

  • Using only Protected Headers in access tokens.¶

  • Using canonical CBOR tagging of CWTs.¶

• Clarifications:¶

  • Handling of access tokens with 'exi' for both CWTs and JWTs.¶

  • Registrations of devices are persisted and tracked at the AS.¶

  • No response or error response from the TRL endpoint yields no assumption.¶

  • Rationale of application policies in defining strategies and schedules for polling the AS.¶

• Security considerations:¶

  • Added reference to RFC 8725.¶

  • Improved considerations on content retrieval from the TRL.¶

• IANA:¶

  • Added a pointer to where the use of the field 'cursor' in problem-details is defined.¶

  • Revised text on Expert Review when using early allocation per RFC 7120.¶

• Split elision and comments in examples with CBOR Diagnostic Notation.¶

• Lowercase capitalization for "client", "resource server", and "authorization server".¶

• Editorial improvements.¶

E.2. Version -07 to -08

• Added definition of pertaining token hash.¶

• Added definition of pertaining TRL update.¶

• Rephrased example of token uploading to be more future ready.¶

• Consistent use of "TRL update" throughout the document.¶

• Editorial improvements.¶

E.3. Version -06 to -07

• RFC 9290 is used instead of the custom format for error responses.¶

• Avoided quotation marks when using CBOR simple values.¶

• CBOR diagnostic notation uses placeholders from a CDDL model.¶

• Early mentioning that there is a single MAX_N value.¶

• Added more details on the authorization of administrators.¶

• Added recommendations for avoiding lost TRL updates from going unnoticed.¶

• If diff queries are supported, the AS MUST provide MAX_N at registration.¶

• If the "Cursor" extension is supported, the AS MUST provide MAX_DIFF_BATCH at registration.¶

• Clarified that how the token revocation specifically happens is out of scope.¶

• Clearer, upfront distinction between using CoAP Observe or not.¶

• Revised and extended method for computing the token hashes.¶

• Clearer presentation of invalid requests to the TRL endpoint.¶

• Clearer expected relation between MAX_INDEX and MAX_N values.¶

• Clarified meaning of registered parameters.¶

• Generalized security considerations on vulnerable time window at the RS.¶

• Added security considerations on additional security measures.¶

• Fixes and improvements in the IANA considerations.¶

• Used AASVG in diagrams.¶

• Used actual tables instead of figures.¶

• Fixed notation in the examples.¶

• Clarifications and editorial improvements.¶

E.4. Version -05 to -06

• Clarified instructions for Expert Review in the IANA considerations.¶

E.5. Version -04 to -05

• Explicit focus on CoAP in the abstract and introduction.¶

• Removed terminology aliasing ("TRL endpoint" vs. "TRL resource").¶

• Use "requester" instead of "caller".¶

• Use "subset" instead of "portion".¶

• Revised presentation of how token hashes are computed.¶

• Improved error handling.¶

• Revised examples.¶

• More precise security considerations.¶

• Clarifications and editorial improvements.¶

• Updated author list.¶

E.6. Version -03 to -04

• Improved presentation of pre- and post-registration operations.¶

• Removed moot processing cases with the "Cursor" extension.¶

• Positive integers as CBOR abbreviations for all parameters.¶

• Renamed N_MAX as MAX_N.¶

• Access tokens are not necessarily uploaded through /authz-info.¶

• The use of the "c.pmax" conditional attribute is just an example.¶

• Revised handling of token hashes at the RS.¶

• Extended and improved security considerations.¶

• Fixed details in IANA considerations.¶

• New appendix overviewing parameters of the TRL endpoint.¶

• Examples of message exchange moved to an appendix.¶

• Added examples of message exchange with the "Cursor" extension.¶

• Clarifications and editorial improvements.¶

E.7. Version -02 to -03

• Definition of MAX_INDEX for the "Cursor" extension.¶

• Handling wrap-around of 'index' when using the "Cursor" extension.¶

• Error handling for the case where 'cursor' > MAX_INDEX.¶

• Improved error handling in case 'index' is out-of-bound.¶

• Clarified parameter semantics, message content and examples.¶

• Editorial improvements.¶

E.8. Version -01 to -02

• Earlier mentioning of error cases.¶

• Clearer distinction between maintaining the history of TRL updates and preparing the response to a diff query.¶

• Defined the use of "cursor" in the document body, as an extension of diff queries.¶

• Both success and error responses have a CBOR map as payload.¶

• Corner cases of message processing explained more explicitly.¶

• Clarifications and editorial improvements.¶

E.9. Version -00 to -01

• Added actions to perform upon receiving responses from the TRL endpoint.¶

• Fixed off-by-one error when using the "Cursor" pattern.¶

• Improved error handling, with registered error codes.¶

• Section restructuring (full- and diff-query as self-standing sections).¶

• Renamed identifiers and CBOR parameters.¶

• Clarifications and editorial improvements.¶