Notification of Revoked Access Tokens in the Authentication and Authorization for Constrained Environments (ACE) Framework

Status of This Memo

This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79.¶

Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet-Drafts is at https://datatracker.ietf.org/drafts/current/.¶

Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress."¶

This Internet-Draft will expire on 12 January 2023.¶

Copyright Notice

Copyright (c) 2022 IETF Trust and the persons identified as the document authors. All rights reserved.¶

This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Revised BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Revised BSD License.¶

Table of Contents

1. Introduction

Authentication and Authorization for Constrained Environments (ACE) [I-D.ietf-ace-oauth-authz] is a framework that enforces access control on IoT devices acting as Resource Servers. In order to use ACE, both Clients and Resource Servers have to register with an Authorization Server and become a registered device. Once registered, a Client can send a request to the Authorization Server, to obtain an Access Token for a Resource Server. For a Client to access the Resource Server, the Client must present the issued Access Token at the Resource Server, which then validates it before storing it (see Section 5.10.1.1 of [I-D.ietf-ace-oauth-authz]).¶

Even though Access Tokens have expiration times, there are circumstances by which an Access Token may need to be revoked before its expiration time, such as: (1) a registered device has been compromised, or is suspected of being compromised; (2) a registered device is decommissioned; (3) there has been a change in the ACE profile for a registered device; (4) there has been a change in access policies for a registered device; and (5) there has been a change in the outcome of policy evaluation for a registered device (e.g., if policy assessment depends on dynamic conditions in the execution environment, the user context, or the resource utilization).¶

As discussed in Section 6.1 of [I-D.ietf-ace-oauth-authz], only client-initiated revocation is currently specified [RFC7009] for OAuth 2.0 [RFC6749], based on the assumption that Access Tokens in OAuth are issued with a relatively short lifetime. However, this is not expected to be the case for constrained, intermittently connected devices, that need Access Tokens with relatively long lifetimes.¶

This document specifies a method for allowing registered devices to access and possibly subscribe to a Token Revocation List (TRL) resource on the Authorization Server, in order to obtain an updated list of revoked, but yet not expired, pertaining Access Tokens. In particular, registered devices can subscribe to the TRL at the Authorization Server by using resource observation [RFC7641] for the Constrained Application Protocol (CoAP) [RFC7252].¶

Unlike in the case of token introspection (see Section 5.9 of [I-D.ietf-ace-oauth-authz]), a registered device does not provide an owned Access Token to the Authorization Server for inquiring about its current state. Instead, registered devices simply obtain an updated list of revoked, but yet not expired, pertaining Access Tokens, as efficiently identified by corresponding hash values.¶

The benefits of this method are that it complements token introspection, and it does not require any additional endpoints on the registered devices. The only additional requirements for registered devices are a request/response interaction with the Authorization Server to access and possibly subscribe to the TRL (see Section 2), and the lightweight computation of hash values to use as Token identifiers (see Section 3).¶

2. Protocol Overview

This protocol defines how a CoAP-based Authorization Server informs Clients and Resource Servers, i.e., registered devices, about pertaining revoked Access Tokens. How the relationship between a registered device and the Authorization Server is established is out of the scope of this specification.¶

At a high level, the steps of this protocol are as follows.¶

• Upon startup, the Authorization Server creates a single TRL resource. At any point in time, the TRL resource represents the list of all revoked Access Tokens issued by the Authorization Server that are not expired yet.¶

• When a device registers at the Authorization Server, it also receives the url-path to the TRL resource.¶

  After the registration procedure is finished, the registered device can send an Observation Request to the TRL resource as described in [RFC7641], i.e., a GET request including the CoAP Observe Option set to 0 (register). By doing so, the registered device effectively subscribes to the TRL resource, as interested to receive notifications about its update. Upon receiving the request, the Authorization Server adds the registered device to the list of observers of the TRL resource.¶

  At any time, the registered device can send a GET request to the TRL endpoint. When doing so, it can request for: the current list of pertaining revoked Access Tokens (see Section 6); or the most recent TRL updates occurred over the list of pertaining revoked Access Tokens (see Section 7). In either case, the registered device may also rely on an Observation Request for subscribing to the TRL resource as discussed above.¶

• When an Access Token is revoked, the Authorization Server adds the corresponding token hash to the TRL. Also, when a revoked Access Token eventually expires, the Authorization Server removes the corresponding token hash from the TRL.¶

  In either case, after updating the TRL, the Authorization Server sends Observe Notifications as per [RFC7641]. That is, an Observe Notification is sent to each registered device subscribed to the TRL resource and to which the Access Token pertains.¶

  Depending on the specific subscription established through the observation request, the notification provides the current updated list of revoked Access Tokens in the portion of the TRL pertaining to that device (see Section 6), or rather the most recent TRL updates occurred over that list of pertaining revoked Access Tokens (see Section 7).¶

  Further Observe Notifications may be sent, consistently with ongoing additional observations of the TRL resource.¶

• An administrator can access and subscribe to the TRL like a registered device, while getting the full updated representation of the TRL.¶

Figure 1 shows a high-level overview of the service provided by this protocol. In particular, it shows the Observe Notifications sent by the Authorization Server to one administrator and four registered devices, upon revocation of the issued Access Tokens t1, t2 and t3, with token hash th1, th2 and th3, respectively. Each dotted line associated with a pair of registered devices indicates the Access Token that they both own.¶

                    +----------------------+
                    | Authorization Server |
                    +-----------o----------+
                    revoke/trl  |  TRL: {th1,th2,th3}
                                |
 +-----------------+------------+------------+------------+
 |                 |            |            |            |
 | th1,th2,th3     | th1,th2    | th1        | th3        | th2,th3
 v                 v            v            v            v
+---------------+ +----------+ +----------+ +----------+ +----------+
| Administrator | | Client 1 | | Resource | | Client 2 | | Resource |
|               | |          | | Server 1 | |          | | Server 2 |
+---------------+ +----------+ +----------+ +----------+ +----------+
                     :    :        :           :            :    :
                     :    :   t1   :           :     t3     :    :
                     :    :........:           :............:    :
                     :                   t2                      :
                     :...........................................:

Section 11 provides examples of the protocol flow and message exchange between the Authorization Server and a registered device.¶

3. Token Hash

The token hash of an Access Token is computed as follows.¶

1. The Authorization Server defines ENCODED_TOKEN, as the content of the 'access_token' parameter in the Authorization Server response (see Section 5.8.2 of [I-D.ietf-ace-oauth-authz]), where the Access Token was included and provided to the requesting Client.¶

   Note that the content of the 'access_token' parameter is either:¶

   • A CBOR byte string, if the Access Token was transported using CBOR. With reference to the example in Figure 2, and assuming the string's length in bytes to be 119 (i.e., 0x77 in hexadecimal), then ENCODED_TOKEN takes the bytes {0x58 0x77 0xd0 0x83 0x44 0xa1 ...}, i.e., the raw content of the parameter 'access_token'.¶
   • A text string, if the Access Token was transported using JSON. With reference to the example in Figure 3, ENCODED_TOKEN takes "2YotnFZFEjr1zCsicMWpAA", i.e., the raw content of the parameter 'access_token'.¶

2. The Authorization Server defines HASH_INPUT as follows.¶

   • If CBOR was used to transport the Access Token (as a CWT or JWT), HASH_INPUT takes the same value of ENCODED_TOKEN.¶

   • If JSON was used to transport the Access Token (as a CWT or JWT), HASH_INPUT takes the serialization of ENCODED_TOKEN.¶

     In either case, HASH_INPUT results in the binary representation of the content of the 'access_token' parameter from the Authorization Server response.¶

3. The Authorization Server generates a hash value of HASH_INPUT 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].¶

   The Authorization Server specifies the used hash function to registered devices during their registration procedure (see Section 9).¶

2.01 Created
Content-Format: application/ace+cbor
Max-Age: 85800
Payload:
{
   "access_token" : h'd08344a1 ...
    (remainder of the Access Token omitted for brevity) ...',
   "token_type" : pop,
   "expires_in" : 86400,
   "profile" : coap_dtls,
   (remainder of the response omitted for brevity)
}

HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store
Pragma: no-cache
Payload:
{
   "access_token" : "2YotnFZFEjr1zCsicMWpAA ...
    (remainder of the Access Token omitted for brevity) ...",
   "token_type" : "pop",
   "expires_in" : 86400,
   "profile" : "coap_dtls",
   (remainder of the response omitted for brevity)
}

4. The TRL Resource

Upon startup, the Authorization Server creates a single TRL resource, encoded as a CBOR array.¶

Each element of the array is a CBOR byte string, with value the token hash of an Access Token. The order of the token hashes in the CBOR array is irrelevant, and the CBOR array MUST be treated as a set in which the order of elements has no significant meaning.¶

The TRL is initialized as empty, i.e., the initial content of the TRL resource representation MUST be an empty CBOR array.¶

5. The TRL Endpoint

Consistent with Section 6.5 of [I-D.ietf-ace-oauth-authz], all communications between a caller of the TRL endpoint and the Authorization Server MUST be encrypted, as well as integrity and replay protected. Furthermore, responses from the Authorization Server to the caller MUST be bound to the caller's request.¶

Following a request to the TRL endpoint, the messages defined in this document that the Authorization Server sends as response use Content-Format "application/ace-trl+cbor". Their payload is formatted as a CBOR map, and the CBOR values for the parameters included therein are defined in Section 12.¶

The Authorization Server MUST implement measures to prevent access to the TRL endpoint by entities other than registered devices and authorized administrators.¶

The TRL endpoint supports only the GET method, and allows two types of query of the TRL.¶

• Full query: the Authorization Server returns the token hashes of the revoked Access Tokens currently in the TRL and pertaining to the requester.¶

  The Authorization Server MUST support this type of query. The processing of a full query and the related response format are defined in Section 6.¶

• Diff query: the Authorization Server returns a list of diff entries. Each diff entry is related to one of the most recent updates, in the portion of the TRL pertaining to the requester.¶

  The entry associated with one of such updates contains a list of token hashes, such that: i) the corresponding revoked Access Tokens pertain to the requester; and ii) they were added to or removed from the TRL at that update.¶

  The Authorization Server MAY support this type of query. In such a case, the Authorization Server maintains the history of updates to the TRL resource as defined in Section 5.1. The processing of a diff query and the related response format are defined in Section 7.¶

If it supports diff queries, the Authorization Server MAY additionally support its "Cursor" extension, which has two benefits. First, the Authorization Server can avoid excessively big latencies when several diff entries have to be transferred, by delivering one adjacent subset at the time, in different diff query responses. Second, a requester can retrieve diff entries associated with TRL updates that, even if not the most recent ones, occurred after a TRL update indicated as reference point.¶

If it supports the "Cursor" extension, the Authorization Server stores additional information when maintaining the history of updates to the TRL resource, as defined in Section 5.1.1. Also, the processing of full query requests and diff query requests, as well as the related response format, are further extended as defined in Section 8.¶

6. Full Query of the TRL

In order to produce a (notification) response to a GET request asking for a full query of the TRL, the Authorization Server performs the following actions.¶

1. From the current TRL resource representation, the Authorization Server builds a set HASHES, such that:¶

   • If the requester is a registered device, HASHES specifies the token hashes of the Access Tokens pertaining to that registered device. The Authorization Server can use the authenticated identity of the registered device to perform the necessary filtering on the TRL resource representation.¶
   • If the requester is an administrator, HASHES specifies all the token hashes in the current TRL resource representation.¶

2. The Authorization Server sends a 2.05 (Content) response to the requester. The response MUST have Content-Format "application/ace-trl+cbor". The payload of the response is a CBOR map, which MUST be formatted as follows.¶

   • The 'full_set' parameter MUST be included and specifies a CBOR array 'full_set_value'. Each element of 'full_set_value' specifies one of the token hashes from the set HASHES, encoded as a CBOR byte string. If the set HASHES is empty, the 'full_set' parameter specifies the empty CBOR array.¶

     The order of the token hashes in the CBOR array is irrelevant, i.e., the CBOR array MUST be treated as a set in which the order of elements has no significant meaning.¶

   • The 'cursor' parameter MUST be included if the Authorization Server supports both the diff queries and the related "Cursor" extension (see Section 5.1 and Section 5.1.1). Its value is specified according to what is defined in Section 8.1, and provides the requester with information for performing a follow-up diff query using the "Cursor" extension (see Section 8.2).¶

     If the Authorization Server does not support both diff queries and the "Cursor" extension, this parameter MUST NOT be included. In case the requester does not support both diff queries and the "Cursor" extension, it MUST silently ignore the 'cursor' parameter if present.¶

Figure 4 provides the CDDL definition [RFC8610] of the CBOR array 'full_set_value' specified in the response from the Authorization Server, as value of the 'full_set' parameter.¶

token_hash = bytes
full_set_value = [* token_hash]

Figure 5 shows an example of response from the Authorization Server, following a full query request to the TRL endpoint. Full token hashes are omitted for brevity.¶

2.05 Content
Content-Format: application/ace-trl+cbor
Payload:
{
   "full_set" : [
     h'01fa51cc ... ', h'01748190 ... '
   ]
}

7. Diff Query of the TRL

In order to produce a (notification) response to a GET request asking for a diff query of the TRL, the Authorization Server performs the following actions.¶

1. The Authorization Server defines the positive integer NUM as follows. If the value N specified in the query parameter 'diff' in the GET request is equal to 0 or greater than the pre-defined positive integer N_MAX (see Section 5.1), then NUM takes the value of N_MAX. Otherwise, NUM takes N.¶
2. The Authorization Server determines U = min(NUM, SIZE), where SIZE <= N_MAX is the number of TRL updates pertaining to the requester and currently stored at the Authorization Server.¶

3. The Authorization Server prepares U diff entries. If U is equal to 0 (e.g., because SIZE is equal to 0 at step 2), then no diff entries are prepared.¶

   The prepared diff entries are related to the U most recent TRL updates pertaining to the requester, as maintained in the update collection for that requester (see Section 5.1). In particular, the first diff entry refers to the most recent of such updates, the second diff entry refers to the second from last of such updates, and so on.¶

   Each diff entry is a CBOR array 'diff_entry', which includes the following two elements.¶

   • The first element is a CBOR array 'removed'. Each element of the array is a CBOR byte string, with value the token hash of an Access Token such that: it pertained to the requester; and it was removed from the TRL during the update associated with the diff entry.¶
   • The second element is a CBOR array 'added'. Each element of the array is a CBOR byte string, with value the token hash of an Access Token such that: it pertains to the requester; and it was added to the TRL during the update associated with the diff entry.¶

   The order of the token hashes in the CBOR arrays 'removed' and 'added' is irrelevant. That is, the CBOR arrays 'removed' and 'added' MUST be treated as a set in which the order of elements has no significant meaning.¶

4. The Authorization Server prepares a 2.05 (Content) response for the requester. The response MUST have Content-Format "application/ace-trl+cbor". The payload of the response is a CBOR map, which MUST be formatted as follows.¶

   • The 'diff_set' parameter MUST be present and specifies a CBOR array 'diff_set_value' of U elements. Each element of 'diff_set_value' specifies one of the CBOR arrays 'diff_entry' prepared above as diff entry. Note that U might have value 0, in which case 'diff_set_value' is the empty CBOR array.¶

     Within 'diff_set_value', the CBOR arrays 'diff_entry' MUST be sorted to reflect the corresponding updates to the TRL in reverse chronological order. That is, the first 'diff_entry' element of 'diff_set_value' relates to the most recent update to the portion of the TRL pertaining to the requester. The second 'diff_entry' element relates to the second from last most recent update to that portion, and so on.¶

   • The 'cursor' parameter and the 'more' parameters MUST be included if the Authorization Server supports both the diff queries and the related "Cursor" extension (see Section 5.1.1). Their values are specified according to what is defined in Section 8.2, and provide the requester with information for performing a follow-up query to the TRL endpoint (see Section 8.2).¶

     If the Authorization Server does not support both diff queries and the "Cursor" extension, these parameters MUST NOT be included. In case the requester does not support both diff queries and the "Cursor" extension, it MUST silently ignore the 'cursor' parameter and the 'more' parameter if present.¶

Figure 6 provides the CDDL definition [RFC8610] of the CBOR array 'diff_set_value' specified in the response from the Authorization Server, as value of the 'diff_set' parameter.¶

   token_hash = bytes
   trl_patch = [* token_hash]
   diff_entry = [removed: trl_patch, added: trl_patch]
   diff_set_value = [* diff_entry]

Figure 7 shows an example of response from the Authorization Server, following a Diff Query request to the TRL endpoint, where U = 3 diff entries are specified. Full token hashes are omitted for brevity.¶

2.05 Content
Content-Format: application/ace-trl+cbor
Payload:
{
   "diff_set" : [
     [
       [ h'01fa51cc ... ', h'01748190 ... '],
       [ h'01cdf1ca ... ', h'01be41a6 ... ']
     ],
     [
       [ h'0144dd12 ... ', h'01231fff ... '],
       []
     ],
     [
       [],
       [ h'01ca986f ... ', h'01fe1a2b ... ']
     ]
   ]
}

Appendix A discusses how performing a diff query of the TRL is in fact a usage example of the Series Transfer Pattern defined in [I-D.bormann-t2trg-stp].¶

8. Using the "Cursor" Extension

If it supports both diff queries and the "Cursor" extension, the Authorization Server composes a response to a full query request or diff query request as defined in Section 8.1 and Section 8.2, respectively.¶

The exact format of the response depends on the request being a full query or diff query request, on the presence of the query parameter 'cursor' in the diff query request, and on the current status of the update collection associated with the requester.¶

9. Upon Registration

During the registration process at the Authorization Server, an administrator or a registered device receives the following information as part of the registration response.¶

• The url-path to the TRL endpoint at the Authorization Server.¶
• The hash function used to compute token hashes. This is specified as an integer or a text string, taking value from the "ID" or "Hash Name String" column of the "Named Information Hash Algorithm" Registry [Named.Information.Hash.Algorithm], respectively.¶
• Optionally, a positive integer N_MAX, if the Authorization Server supports diff queries of the TRL resource (see Section 5.1 and Section 7).¶
• Optionally, a positive integer MAX_DIFF_BATCH, if the Authorization Server supports diff queries of the TRL resource as well as the related "Cursor" extension (see Section 5.1.1 and Section 8).¶

After the registration procedure is finished, the administrator or registered device can send a GET request to the TRL resource, including the CoAP Observe Option set to 0 (register), in order to start an observation of the TRL resource at the Authorization Server as per Section 3.1 of [RFC7641]. The GET request can express the wish for a full query (see Section 6) or a diff query (see Section 7) of the TRL.¶

In case the request is successfully processed, the Authorization Server replies with a response specifying the CoAP response code 2.05 (Content) and including the CoAP Observe Option. The payload of the response is formatted as defined in Section 6 or in Section 7, in case the GET request yielded the execution of a full query or a diff query of the TRL, respectively.¶

Further details about the registration process at the Authorization Server are out of scope for this specification. Note that the registration process is also out of the scope of the ACE framework for Authentication and Authorization (see Section 5.5 of [I-D.ietf-ace-oauth-authz]).¶

10. Notification of Revoked Tokens

When the TRL is updated (see Section 4.1), the Authorization Server sends Observe Notifications to the observers of the TRL resource. Observe Notifications are sent as per Section 4.2 of [RFC7641].¶

If the 'pmax' query parameter was specified in the Observation Request starting an observation (see Section 5.2), the Authorization Server might accordingly send additional Observe Notifications to the associated observer. That is, the Authorization Server ensures that no more than pmax seconds elapse between two consecutive notifications sent to that observer, regardless whether the TRL resource has changed or not. If the 'pmax' query parameter was not specified in the Observation Request, a possible maximum time to consider is up to the Authorization Server.¶

The payload of each Observe Notification is formatted as defined in Section 6 or in Section 7, in case the original Observation Request yielded the execution of a full query or a diff query of the TRL, respectively.¶

Furthermore, an administrator or a registered device can send additional GET requests to the TRL endpoint at any time, in order to retrieve the token hashes of the pertaining revoked Access Tokens. When doing so, the caller of the TRL endpoint can perform a full query (see Section 6) or a diff query (see Section 7) of the TRL.¶

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

When a Resource Server RS receives a response from the TRL endpoint specifying the token hash th1 associated with a revoked Access Token t1, the RS might not have received and stored that Access Token yet. This occurs if the Access Token is revoked before it is successfully posted to the Authorization Information Endpoint at the RS (see Section 5.10.1 of [I-D.ietf-ace-oauth-authz]). Such a delay can be due, for example, to messages that get lost in transmission, or rather to the Client experiencing failures in sending the Access Token to the RS, or deliberately holding the Access Token back.¶

Thus, in order to ensure that no revoked Access Tokens are accepted and stored, the RS performs the following actions.¶

• The RS MUST store the token hash th1, until gaining knowledge that the associated revoked Access Token t1 is also expired.¶

  This can happen when receiving a subsequent response from the TRL endpoint (i.e., indicating that the token hash th1 is not in the TRL portion pertaining to the RS anymore), or when the Access Token t1 is posted to the Authorization Information Endpoint and is found to be expired based on its 'exp' claim [RFC7519], if included.¶

• The RS MUST NOT accept as valid and store an Access Token t1 posted to the Authorization Information Endpoint, if the corresponding token hash th1 is among the stored ones.¶

11. Interaction Examples

This section provides examples of interactions between a Resource Server RS as a registered device and an Authorization Server AS. The Authorization Server supports both full query and diff query of the TRL, as defined in Section 6 and Section 7, respectively.¶

The details of the registration process are omitted, but it is assumed that the Resource Server sends an unspecified payload to the Authorization Server, which replies with a 2.01 (Created) response.¶

The payload of the registration response is a CBOR map, which includes the following entries:¶

• a "trl_path" parameter, specifying the path of the TRL resource;¶
• a "trl_hash" parameter, specifying the hash function used to computed token hashes as defined in Section 3;¶
• an "n_max" parameter, specifying the value of N_MAX, i.e., the maximum number of TRL updates pertaining to each registered device that the Authorization Server retains for that device (see Section 7);¶
• possible further parameters related to the registration process.¶

Furthermore, 'h(x)' refers to the hash function used to compute the token hashes, as defined in Section 3 of this specification and according to [RFC6920]. Assuming the usage of CWTs transported in CBOR, 'bstr.h(t1)' and 'bstr.h(t2)' denote the byte-string representations of the token hashes for the Access Tokens t1 and t2, respectively.¶

RS                                                 AS
|                                                   |
| Registration: POST                                |
+-------------------------------------------------->|
|                                                   |
|<--------------------------------------------------+
|                   2.01 CREATED                    |
|                     Payload: {                    |
|                        ...                        |
|                        "trl_path" : "revoke/trl", |
|                        "trl_hash" : "sha-256",    |
|                        "n_max" : 10               |
|                     }                             |
|                                                   |
| GET Observe: 0                                    |
|  coap://as.example.com/revoke/trl/                |
+-------------------------------------------------->|
|                                                   |
|<--------------------------------------------------+
|        2.05 CONTENT Observe: 42                   |
|        Content-Format: "application/ace-trl+cbor" |
|         Payload: {                                |
|           "full_set" : []                         |
|         }                                         |
|                         .                         |
|                         .                         |
|                         .                         |
|                                                   |
|          (Access Tokens t1 and t2 issued          |
|          and successfully submitted to RS)        |
|                         .                         |
|                         .                         |
|                         .                         |
|                                                   |
|                                                   |
|            (Access Token t1 is revoked)           |
|                                                   |
|<--------------------------------------------------+
|        2.05 CONTENT Observe: 53                   |
|        Content-Format: "application/ace-trl+cbor" |
|         Payload: {                                |
|           "full_set" : [bstr.h(t1)]               |
|         }                                         |
|                         .                         |
|                         .                         |
|                         .                         |
|                                                   |
|            (Access Token t2 is revoked)           |
|                                                   |
|<--------------------------------------------------+
|        2.05 CONTENT Observe: 64                   |
|        Content-Format: "application/ace-trl+cbor" |
|         Payload: {                                |
|           "full_set" : [bstr.h(t1), bstr.h(t2)]   |
|        }                                          |
|                                                   |
|                         .                         |
|                         .                         |
|                         .                         |
|                                                   |
|             (Access Token t1 expires)             |
|                                                   |
|<--------------------------------------------------+
|        2.05 CONTENT Observe: 75                   |
|        Content-Format: "application/ace-trl+cbor" |
|         Payload: {                                |
|           "full_set" : [bstr.h(t2)]               |
|         }                                         |
|                         .                         |
|                         .                         |
|                         .                         |
|                                                   |
|            (Access Token t2 expires)              |
|                                                   |
|<--------------------------------------------------+
|        2.05 CONTENT Observe: 86                   |
|        Content-Format: "application/ace-trl+cbor" |
|         Payload: {                                |
|           "full_set" : []                         |
|         }                                         |
|                                                   |

RS                                                 AS
|                                                   |
| Registration: POST                                |
+-------------------------------------------------->|
|                                                   |
|<--------------------------------------------------+
|                    2.01 CREATED                   |
|                     Payload: {                    |
|                        ...                        |
|                        "trl_path" : "revoke/trl", |
|                        "trl_hash" : "sha-256",    |
|                        "n_max" : 10               |
|                     }                             |
|                                                   |
| GET Observe: 0                                    |
|  coap://as.example.com/revoke/trl?diff=3          |
+-------------------------------------------------->|
|                                                   |
|<--------------------------------------------------+
|        2.05 CONTENT Observe: 42                   |
|        Content-Format: "application/ace-trl+cbor" |
|         Payload: {                                |
|           "diff_set" : []                         |
|         }                                         |
|                         .                         |
|                         .                         |
|                         .                         |
|                                                   |
|          (Access Tokens t1 and t2 issued          |
|          and successfully submitted to RS)        |
|                         .                         |
|                         .                         |
|                         .                         |
|                                                   |
|            (Access Token t1 is revoked)           |
|                                                   |
|<--------------------------------------------------+
|        2.05 CONTENT Observe: 53                   |
|        Content-Format: "application/ace-trl+cbor" |
|         Payload: {                                |
|           "diff_set" : [                          |
|                          [ [], [bstr.h(t1)] ]     |
|                        ]                          |
|         }                                         |
|                         .                         |
|                         .                         |
|                         .                         |
|                                                   |
|            (Access Token t2 is revoked)           |
|                                                   |
|<--------------------------------------------------+
|        2.05 CONTENT Observe: 64                   |
|        Content-Format: "application/ace-trl+cbor" |
|         Payload: {                                |
|           "diff_set" : [                          |
|                          [ [], [bstr.h(t2)] ],    |
|                          [ [], [bstr.h(t1)] ]     |
|                        ]                          |
|         }                                         |
|                         .                         |
|                         .                         |
|                         .                         |
|                                                   |
|              (Access Token t1 expires)            |
|                                                   |
|<--------------------------------------------------+
|        2.05 CONTENT Observe: 75                   |
|        Content-Format: "application/ace-trl+cbor" |
|         Payload: {                                |
|           "diff_set" : [                          |
|                          [ [bstr.h(t1)], [] ],    |
|                          [ [], [bstr.h(t2)] ],    |
|                          [ [], [bstr.h(t1)] ]     |
|                        ]                          |
|         }                                         |
|                         .                         |
|                         .                         |
|                         .                         |
|                                                   |
|              (Access Token t2 expires)            |
|                                                   |
|<--------------------------------------------------+
|        2.05 CONTENT Observe: 86                   |
|        Content-Format: "application/ace-trl+cbor" |
|         Payload: {                                |
|           "diff_set" : [                          |
|                          [ [bstr.h(t2)], [] ],    |
|                          [ [bstr.h(t1)], [] ],    |
|                          [ [], [bstr.h(t2)] ]     |
|                        ]                          |
|         }                                         |
|                                                   |

RS                                                 AS
|                                                   |
| Registration: POST                                |
+-------------------------------------------------->|
|                                                   |
|<--------------------------------------------------+
|                    2.01 CREATED                   |
|                     Payload: {                    |
|                        ...                        |
|                        "trl_path" : "revoke/trl", |
|                        "trl_hash" : "sha-256",    |
|                        "n_max" : 10               |
|                     }                             |
|                                                   |
| GET Observe: 0                                    |
|  coap://as.example.com/revoke/trl/                |
+-------------------------------------------------->|
|                                                   |
|<--------------------------------------------------+
|        2.05 CONTENT Observe: 42                   |
|        Content-Format: "application/ace-trl+cbor" |
|         Payload: {                                |
|           "full_set" : []                         |
|         }                                         |
|                         .                         |
|                         .                         |
|                         .                         |
|                                                   |
|          (Access Tokens t1 and t2 issued          |
|          and successfully submitted to RS)        |
|                         .                         |
|                         .                         |
|                         .                         |
|                                                   |
|            (Access Token t1 is revoked)           |
|                                                   |
|<--------------------------------------------------+
|        2.05 CONTENT Observe: 53                   |
|        Content-Format: "application/ace-trl+cbor" |
|         Payload: {                                |
|           "full_set" : [bstr.h(t1)]               |
|         }                                         |
|                         .                         |
|                         .                         |
|                         .                         |
|                                                   |
|            (Access Token t2 is revoked)           |
|                                                   |
|<--------------------------------------------------+
|        2.05 CONTENT Observe: 64                   |
|        Content-Format: "application/ace-trl+cbor" |
|         Payload: {                                |
|           "full_set" : [bstr.h(t1), bstr.h(t2)]   |
|         }                                         |
|                         .                         |
|                         .                         |
|                         .                         |
|                                                   |
|             (Access Token t1 expires)             |
|                                                   |
|<--------------------------------------------------+
|        2.05 CONTENT Observe: 75                   |
|        Content-Format: "application/ace-trl+cbor" |
|         Payload: {                                |
|           "full_set" : [bstr.h(t2)]               |
|         }                                         |
|                         .                         |
|                         .                         |
|                         .                         |
|                                                   |
|             (Access Token t2 expires)             |
|                                                   |
|    X<---------------------------------------------+
|        2.05 CONTENT Observe: 86                   |
|        Content-Format: "application/ace-trl+cbor" |
|         Payload: {                                |
|           "full_set" : []                         |
|         }                                         |
|                         .                         |
|                         .                         |
|                         .                         |
|                                                   |
|           (Enough time has passed since           |
|         the latest received notification)         |
|                                                   |
| GET                                               |
|  coap://as.example.com/revoke/trl?diff=8          |
+-------------------------------------------------->|
|                                                   |
|<--------------------------------------------------+
|        2.05 CONTENT                               |
|        Content-Format: "application/ace-trl+cbor" |
|         Payload: {                                |
|           "diff_set" : [                          |
|                          [ [bstr.h(t2)], [] ],    |
|                          [ [bstr.h(t1)], [] ],    |
|                          [ [], [bstr.h(t2)] ],    |
|                          [ [], [bstr.h(t1)] ]     |
|                        ]                          |
|         }                                         |
|                                                   |

12. ACE Token Revocation List Parameters

This specification defines a number of parameters that can be transported in the response from the TRL endpoint, when the response payload is a CBOR map. Note that such a response MUST use the Content-Format "application/ace-trl+cbor" defined in Section 15.2 of this specification.¶

The table below summarizes them, and specifies the CBOR value to use as abbreviation instead of the full descriptive name.¶

+-------------------+------------+------------------------+
| Name              | CBOR Value | CBOR Type              |
+-------------------+------------+------------------------+
| full_set          |  0         | array                  |
+-------------------+------------+------------------------+
| diff_set          |  1         | array                  |
+-------------------+------------+------------------------+
| cursor            |  2         | unsigned integer /     |
|                   |            | simple value "null"    |
+-------------------+------------+------------------------+
| more              |  3         | simple value "false" / |
|                   |            | simple value "true"    |
+-------------------+------------+------------------------+
| error             | -1         | int                    |
+-------------------+------------+------------------------+
| error_description | -2         | tstr                   |
+-------------------+------------+------------------------+

13. ACE Token Revocation List Error Identifiers

This specification defines a number of values that the Authorization Server can include as error identifiers, in the 'error' field of an error response from the TRL endpoint. This applies to error responses whose payload is a CBOR map and whose Content-Format is "application/ace-trl+cbor".¶

+-------+---------------------------+
| Value | Description               |
+-------+---------------------------+
|   0   | Invalid parameter value   |
+-------+---------------------------+
|   1   | Invalid set of parameters |
+-------+---------------------------+
|   2   | Out of bound cursor value |
+-------+---------------------------+

14. Security Considerations

Security considerations are inherited from the ACE framework for Authentication and Authorization [I-D.ietf-ace-oauth-authz], from [RFC8392] as to the usage of CWTs, from [RFC7519] as to the usage of JWTs, from [RFC7641] as to the usage of CoAP Observe, and from [RFC6920] with regard to resource naming through hashes. The following considerations also apply.¶

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

Disclosing any information about revoked Access Tokens to entities other than the intended registered devices may result in privacy concerns. Therefore, the Authorization Server MUST ensure that, other than registered devices accessing their own pertaining portion of the TRL, only authorized and authenticated administrators can retrieve the full TRL. To this end, the Authorization Server may rely on an access control list or similar.¶

If a registered device has many non-expired Access Tokens associated with itself that are revoked, the pertaining portion of the TRL could grow to a size bigger than what the registered device is prepared to handle upon reception, especially if relying on a full query of the TRL resource (see Section 6). This could be exploited by attackers to negatively affect the behavior of a registered device. Issuing Access Tokens with not too long expiration time could help reduce the size of a TRL, but an Authorization Server SHOULD take measures to limit this size.¶

Most of the communication about revoked Access Tokens presented in this specification relies on CoAP Observe Notifications sent from the Authorization Server to a registered device. The suppression of those notifications by an external attacker that has access to the network would prevent registered devices from ever knowing that their pertaining Access Tokens have been revoked. In order to avoid this, a registered device SHOULD NOT rely solely on the CoAP Observe notifications. In particular, a registered device SHOULD also regularly poll the Authorization Server for the most current information about revoked Access Tokens, by sending GET requests to the TRL endpoint according to a related application policy.¶

15. IANA Considerations

This document has the following actions for IANA.¶

Note to RFC Editor: Please replace all occurrences of "[RFC-XXXX]" with the RFC number of this specification and delete this paragraph.¶

Appendix A. On using the Series Transfer Pattern

Performing a diff query of the TRL as specified in Section 7 is in fact a usage example of the Series Transfer Pattern defined in [I-D.bormann-t2trg-stp].¶

That is, a diff query enables the transfer of a series of TRL updates, with the Authorization Server specifying U <= N_MAX diff entries as the U most recent updates to the portion of the TRL pertaining to a requester, i.e., a registered device or an administrator.¶

When responding to a diff query request from a requester (see Section 7), 'diff_set' is a subset of the update collection associated with the requester, where each 'diff_entry' record is a series item from that update collection. Note that 'diff_set' specifies the whole current update collection when the value of U is equal to SIZE, i.e., the current number of series items in the update collection.¶

The value N of the query parameter 'diff' in the GET request allows the requester and the Authorization Server to trade the amount of provided information with the latency of the information transfer.¶

Since the update collection associated with each requester includes up to N_MAX series item, the Authorization Server deletes the oldest series item when a new one is generated and added to the end of the update collection, due to a new TRL update pertaining to that requester (see Section 5.1). This addresses the question "When can the server decide to no longer retain older items?" raised in Section 3.2 of [I-D.bormann-t2trg-stp].¶

Furthermore, performing a diff query of the TRL together with the "Cursor" extension as specified in Section 8 in fact relies on the "Cursor" pattern of the Series Transfer Pattern (see Section 3.3 of [I-D.bormann-t2trg-stp]).¶

Appendix B. Document Updates

RFC EDITOR: Please remove this section.¶

Acknowledgments

The authors sincerely thank Christian Amsüss, Carsten Bormann, Benjamin Kaduk, David Navarro, Marco Rasori, Michael Richardson, Jim Schaad, Göran Selander and Travis Spencer for their comments and feedback.¶

The work on this document has been partly supported by VINNOVA and the Celtic-Next project CRITISEC; and by the H2020 project SIFIS-Home (Grant agreement 952652).¶

Authors' Addresses