draft-tiloca-ace-revoked-token-notification-03.txt   draft-tiloca-ace-revoked-token-notification-04.txt 
ACE Working Group M. Tiloca ACE Working Group M. Tiloca
Internet-Draft RISE AB Internet-Draft RISE AB
Intended status: Standards Track L. Seitz Intended status: Standards Track L. Seitz
Expires: May 6, 2021 Combitech Expires: August 26, 2021 Combitech
F. Palombini F. Palombini
Ericsson AB Ericsson AB
S. Echeverria S. Echeverria
G. Lewis G. Lewis
CMU SEI CMU SEI
November 02, 2020 February 22, 2021
Notification of Revoked Access Tokens in the Authentication and Notification of Revoked Access Tokens in the Authentication and
Authorization for Constrained Environments (ACE) Framework Authorization for Constrained Environments (ACE) Framework
draft-tiloca-ace-revoked-token-notification-03 draft-tiloca-ace-revoked-token-notification-04
Abstract Abstract
This document specifies a method of the Authentication and This document specifies a method of the Authentication and
Authorization for Constrained Environments (ACE) framework, which Authorization for Constrained Environments (ACE) framework, which
allows an Authorization Server to notify Clients and Resource Servers allows an Authorization Server to notify Clients and Resource Servers
(i.e., registered devices) about revoked Access Tokens. The method (i.e., registered devices) about revoked Access Tokens. The method
relies on resource observation for the Constrained Application relies on resource observation for the Constrained Application
Protocol (CoAP), with Clients and Resource Servers observing a Token Protocol (CoAP), with Clients and Resource Servers observing a Token
Revocation List on the Authorization Server. Resulting unsolicited Revocation List on the Authorization Server. Resulting unsolicited
skipping to change at page 1, line 46 skipping to change at page 1, line 46
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet- working documents as Internet-Drafts. The list of current Internet-
Drafts is at https://datatracker.ietf.org/drafts/current/. Drafts is at https://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." material or to cite them other than as "work in progress."
This Internet-Draft will expire on May 6, 2021. This Internet-Draft will expire on August 26, 2021.
Copyright Notice Copyright Notice
Copyright (c) 2020 IETF Trust and the persons identified as the Copyright (c) 2021 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents Provisions Relating to IETF Documents
(https://trustee.ietf.org/license-info) in effect on the date of (https://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents publication of this document. Please review these documents
carefully, as they describe your rights and restrictions with respect carefully, as they describe your rights and restrictions with respect
to this document. Code Components extracted from this document must to this document. Code Components extracted from this document must
include Simplified BSD License text as described in Section 4.e of include Simplified BSD License text as described in Section 4.e of
the Trust Legal Provisions and are provided without warranty as the Trust Legal Provisions and are provided without warranty as
described in the Simplified BSD License. described in the Simplified BSD License.
Table of Contents Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3
1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 4
2. Protocol Overview . . . . . . . . . . . . . . . . . . . . . . 5 2. Protocol Overview . . . . . . . . . . . . . . . . . . . . . . 5
3. Token Hash . . . . . . . . . . . . . . . . . . . . . . . . . 7 3. Token Hash . . . . . . . . . . . . . . . . . . . . . . . . . 7
4. The TRL Resource . . . . . . . . . . . . . . . . . . . . . . 8 4. The TRL Resource . . . . . . . . . . . . . . . . . . . . . . 9
4.1. Update of the TRL Resource . . . . . . . . . . . . . . . 9 4.1. Update of the TRL Resource . . . . . . . . . . . . . . . 9
5. The TRL Endpoint . . . . . . . . . . . . . . . . . . . . . . 9 5. The TRL Endpoint . . . . . . . . . . . . . . . . . . . . . . 9
5.1. Full Query of the TRL . . . . . . . . . . . . . . . . . . 10 5.1. Full Query of the TRL . . . . . . . . . . . . . . . . . . 10
5.2. Diff Query of the TRL . . . . . . . . . . . . . . . . . . 10 5.2. Diff Query of the TRL . . . . . . . . . . . . . . . . . . 11
6. Upon Registration . . . . . . . . . . . . . . . . . . . . . . 12 6. Upon Registration . . . . . . . . . . . . . . . . . . . . . . 13
7. Notification of Revoked Tokens . . . . . . . . . . . . . . . 13 7. Notification of Revoked Tokens . . . . . . . . . . . . . . . 14
8. Interaction Examples . . . . . . . . . . . . . . . . . . . . 13 8. Interaction Examples . . . . . . . . . . . . . . . . . . . . 14
8.1. Full Query with Observation . . . . . . . . . . . . . . . 14 8.1. Full Query with Observation . . . . . . . . . . . . . . . 15
8.2. Diff Query with Observation . . . . . . . . . . . . . . . 15 8.2. Diff Query with Observation . . . . . . . . . . . . . . . 16
8.3. Full Query with Observation and Additional Diff Query . . 17 8.3. Full Query with Observation and Additional Diff Query . . 18
9. Security Considerations . . . . . . . . . . . . . . . . . . . 20 9. Security Considerations . . . . . . . . . . . . . . . . . . . 21
10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 21 10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 22
11. References . . . . . . . . . . . . . . . . . . . . . . . . . 21 10.1. Media Type Registrations . . . . . . . . . . . . . . . . 22
11.1. Normative References . . . . . . . . . . . . . . . . . . 21 10.2. CoAP Content-Formats Registry . . . . . . . . . . . . . 23
11.2. Informative References . . . . . . . . . . . . . . . . . 22 10.3. Token Revocation List Registry . . . . . . . . . . . . . 23
Appendix A. Usage of the Series Transfer Pattern . . . . . . . . 22 10.4. Expert Review Instructions . . . . . . . . . . . . . . . 24
Appendix B. Usage of the "Cursor" Pattern . . . . . . . . . . . 23 11. References . . . . . . . . . . . . . . . . . . . . . . . . . 24
B.1. Full Query Request . . . . . . . . . . . . . . . . . . . 24 11.1. Normative References . . . . . . . . . . . . . . . . . . 24
B.2. Full Query Response . . . . . . . . . . . . . . . . . . . 24 11.2. Informative References . . . . . . . . . . . . . . . . . 26
B.3. Diff Query Request . . . . . . . . . . . . . . . . . . . 24 Appendix A. Usage of the Series Transfer Pattern . . . . . . . . 26
B.4. Diff Query Response . . . . . . . . . . . . . . . . . . . 25 Appendix B. Usage of the "Cursor" Pattern . . . . . . . . . . . 28
B.4.1. Empty Collection . . . . . . . . . . . . . . . . . . 25 B.1. Full Query Request . . . . . . . . . . . . . . . . . . . 28
B.4.2. Cursor Not Specified in the Diff Query Request . . . 25 B.2. Full Query Response . . . . . . . . . . . . . . . . . . . 28
B.4.3. Cursor Specified in the Diff Query Request . . . . . 26 B.3. Diff Query Request . . . . . . . . . . . . . . . . . . . 29
Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . 27 B.4. Diff Query Response . . . . . . . . . . . . . . . . . . . 29
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 28 B.4.1. Empty Collection . . . . . . . . . . . . . . . . . . 29
B.4.2. Cursor Not Specified in the Diff Query Request . . . 29
B.4.3. Cursor Specified in the Diff Query Request . . . . . 30
B.4.4. TRL Parameters . . . . . . . . . . . . . . . . . . . 32
Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . 33
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 33
1. Introduction 1. Introduction
Authentication and Authorization for Constrained Environments (ACE) Authentication and Authorization for Constrained Environments (ACE)
[I-D.ietf-ace-oauth-authz] is a framework that enforces access [I-D.ietf-ace-oauth-authz] is a framework that enforces access
control on IoT devices acting as Resource Servers. In order to use control on IoT devices acting as Resource Servers. In order to use
ACE, both Clients and Resource Servers have to register with an ACE, both Clients and Resource Servers have to register with an
Authorization Server and become a registered device. Once Authorization Server and become a registered device. Once
registered, a Client can send a request to the Authorization Server, registered, a Client can send a request to the Authorization Server,
to obtain an Access Token for a Resource Server. For a Client to to obtain an Access Token for a Resource Server. For a Client to
skipping to change at page 4, line 14 skipping to change at page 4, line 22
Readers are expected to be familiar with the terms and concepts Readers are expected to be familiar with the terms and concepts
described in the ACE framework for Authentication and Authorization described in the ACE framework for Authentication and Authorization
[I-D.ietf-ace-oauth-authz], as well as with terms and concepts [I-D.ietf-ace-oauth-authz], as well as with terms and concepts
related to CBOR Web Tokens (CWTs) [RFC8392], and JSON Web Tokens related to CBOR Web Tokens (CWTs) [RFC8392], and JSON Web Tokens
(JWTs) [RFC7519]. The terminology for entities in the considered (JWTs) [RFC7519]. The terminology for entities in the considered
architecture is defined in OAuth 2.0 [RFC6749]. In particular, this architecture is defined in OAuth 2.0 [RFC6749]. In particular, this
includes Client, Resource Server, and Authorization Server. includes Client, Resource Server, and Authorization Server.
Readers are also expected to be familiar with the terms and concepts Readers are also expected to be familiar with the terms and concepts
related to CBOR [I-D.ietf-cbor-7049bis], JSON [RFC8259], the CoAP related to CBOR [RFC8949], JSON [RFC8259], the CoAP protocol
protocol [RFC7252], CoAP Observe [RFC7641], and the use of hash [RFC7252], CoAP Observe [RFC7641], and the use of hash functions to
functions to name objects as defined in [RFC6920]. name objects as defined in [RFC6920].
Note that, unless otherwise indicated, the term "endpoint" is used Note that, unless otherwise indicated, the term "endpoint" is used
here following its OAuth definition, aimed at denoting resources such here following its OAuth definition, aimed at denoting resources such
as /token and /introspect at the Authorization Server, and /authz- as /token and /introspect at the Authorization Server, and /authz-
info at the Resource Server. This document does not use the CoAP info at the Resource Server. This document does not use the CoAP
definition of "endpoint", which is "An entity participating in the definition of "endpoint", which is "An entity participating in the
CoAP protocol." CoAP protocol."
This specification also refers to the following terminology. This specification also refers to the following terminology.
skipping to change at page 5, line 35 skipping to change at page 5, line 45
this specification. this specification.
At a high level, the steps of this protocol are as follows. At a high level, the steps of this protocol are as follows.
o Upon startup, the Authorization Server creates a TRL resource. At o Upon startup, the Authorization Server creates a TRL resource. At
any point in time, the TRL resource represents the list of all any point in time, the TRL resource represents the list of all
revoked Access Tokens issued by the Authorization Server that are revoked Access Tokens issued by the Authorization Server that are
yet not expired. yet not expired.
o When a device registers at the Authorization Server, it receives o When a device registers at the Authorization Server, it receives
the url-path to the TRL resource. After the registration the url-path to the TRL resource.
procedure is finished, the registered device sends an Observation
Request to that TRL resource as described in [RFC7641], i.e. a GET After the registration procedure is finished, the registered
request with an Observe option set to 0 (register). Upon device sends an Observation Request to that TRL resource as
receiving the request, the Authorization Server adds the described in [RFC7641], i.e. a GET request with an Observe option
registered device to the list of observers of the TRL resource. set to 0 (register). 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 At any time, the registered device can send a GET request to the
TRL endpoint, in order to get the current list of pertaining TRL endpoint. When doing so, it can request for: the current list
revoked Access Tokens. of pertaining revoked Access Tokens (see Section 5.1); or the most
recent TRL updates occurred over the list of pertaining revoked
Access Tokens (see Section 5.2). In either case, the registered
devices may especially rely on an Observation Request.
o When an Access Token is revoked, the Authorization Server adds the o When an Access Token is revoked, the Authorization Server adds the
corresponding token hash to the TRL. Also, when a revoked Access corresponding token hash to the TRL. Also, when a revoked Access
Token eventually expires, the Authorization Server removes the Token eventually expires, the Authorization Server removes the
corresponding token hash from the TRL. In either case, after corresponding token hash from the TRL.
updating the TRL, the Authorization Server sends Observe
Notifications as described in [RFC7641]. That is, one Observe In either case, after updating the TRL, the Authorization Server
Notification is sent to each registered device the Access Token sends Observe Notifications as per [RFC7641]. That is, one
pertains to, and specifies the current updated list of token Observe Notification is sent to each registered device the Access
Token pertains to, and specifies the current updated list of token
hashes in the portion of the TRL pertaining to that device. hashes in the portion of the TRL pertaining to that device.
Further Observe Notifications may be sent, consistently with
ongoing additional observations of the TRL resource.
o An administrator can observe and access the TRL like a registered o An administrator can observe and access the TRL like a registered
device, while getting the full updated representation of the TRL. device, while getting the full updated representation of the TRL.
Figure 1 provides a high-level overview of the service provided by Figure 1 shows a high-level overview of the service provided by this
this protocol. Each dotted line associated to a pair of registered protocol. In particular, it shows the Observe Notifications sent by
devices indicates the Access Token that they both own. In the Authorization Server to one administrator and four registered
particular, Figure 1 shows the Observe Notifications sent by the devices, upon revocation of the issued Access Tokens t1, t2 and t3,
Authorization Server to four registered devices and one with token hash th1, th2 and th3, respectively. Each dotted line
administrator, upon revocation of the issued Access Tokens t1, t2 and associated to a pair of registered devices indicates the Access Token
t3, with token hash th1, th2 and th3, respectively. that they both own.
+---------------+ +----------------------+
| | | Authorization Server |
| Authorization | +-----------o----------+
| Server |
| |
+-------o-------+
revoke/trl | TRL: {th1,th2,th3} revoke/trl | TRL: {th1,th2,th3}
| |
|
+-----------------+------------+------------+------------+ +-----------------+------------+------------+------------+
| | | | | | | | | |
| | | | |
| th1,th2,th3 | th1,th2 | th1 | th3 | th2,th3 | th1,th2,th3 | th1,th2 | th1 | th3 | th2,th3
v v v v v v v v v v
+---------------+ +----------+ +----------+ +----------+ +----------+ +---------------+ +----------+ +----------+ +----------+ +----------+
| | | | | | | | | |
| Administrator | | Client 1 | | Resource | | Client 2 | | Resource | | Administrator | | Client 1 | | Resource | | Client 2 | | Resource |
| | | | | Server 1 | | | | Server 2 | | | | | | Server 1 | | | | Server 2 |
+---------------+ +----------+ +----------+ +----------+ +----------+ +---------------+ +----------+ +----------+ +----------+ +----------+
: : : : : : : : : : : :
: : t1 : : t3 : : : : t1 : : t3 : :
: :........: :............: : : :........: :............: :
: : : t2 :
: t2 :
:...........................................: :...........................................:
Figure 1: Protocol Overview Figure 1: Protocol Overview
More detailed examples describing the protocol flow and message Section 8 provides examples of the protocol flow and message exchange
exchange between the Authorization Server and a registered device are between the Authorization Server and a registered device.
provided in Section 8.
3. Token Hash 3. Token Hash
The token hash of an Access Token is computed as follows. The token hash of an Access Token is computed as follows.
1. The Authorization Server defines ENCODED_TOKEN, as the content of 1. The Authorization Server defines ENCODED_TOKEN, as the content of
the 'access_token' parameter in the Authorization Server response the 'access_token' parameter in the Authorization Server response
(see Section 5.6.2 of [I-D.ietf-ace-oauth-authz]), where the (see Section 5.8.2 of [I-D.ietf-ace-oauth-authz]), where the
Access Token was included and returned to the requesting Client. Access Token was included and returned to the requesting Client.
Note that the content of the 'access_token' parameter is either: Note that the content of the 'access_token' parameter is either:
* A CBOR byte string, if the Access Token was transported using * A CBOR byte string, if the Access Token was transported using
CBOR. With reference to the example in Figure 2, and assuming CBOR. With reference to the example in Figure 2, and assuming
the string's length in bytes to be 119 (i.e., 0x77 in the string's length in bytes to be 119 (i.e., 0x77 in
hexadecimal), then ENCODED_TOKEN takes the bytes {0x58 0x77 hexadecimal), then ENCODED_TOKEN takes the bytes {0x58 0x77
0xd0 0x83 0x44 0xa1 ...}, i.e. the raw content of the 0xd0 0x83 0x44 0xa1 ...}, i.e. the raw content of the
parameter 'access_token'. parameter 'access_token'.
skipping to change at page 8, line 41 skipping to change at page 9, line 26
(remainder of the response omitted for brevity) (remainder of the response omitted for brevity)
} }
Figure 3: Example of Authorization Server response using JSON Figure 3: Example of Authorization Server response using JSON
4. The TRL Resource 4. The TRL Resource
Upon startup, the Authorization Server creates a single TRL resource, Upon startup, the Authorization Server creates a single TRL resource,
encoded as a CBOR array. encoded as a CBOR array.
Each element of the array is a token hash, encoded as a CBOR byte Each element of the array is a CBOR byte string, with value the token
string. The order of the token hashes in the CBOR array is hash of an Access Token. The order of the token hashes in the CBOR
irrelevant, and the CBOR array MUST be treated as a set in which the array is irrelevant, and the CBOR array MUST be treated as a set in
order has no significant meaning. which the order has no significant meaning.
The TRL is initialized as empty, i.e. the initial content of the TRL The TRL is initialized as empty, i.e. the initial content of the TRL
resource representation MUST be an empty CBOR array. resource representation MUST be an empty CBOR array.
4.1. Update of the TRL Resource 4.1. Update of the TRL Resource
The Authorization Server updates the TRL in the following two cases. The Authorization Server updates the TRL in the following two cases.
o When a non-expired Access Token is revoked, the token hash of the o When a non-expired Access Token is revoked, the token hash of the
Access Token is added to the TRL resource representation. That Access Token is added to the TRL resource representation. That
is, a CBOR byte string encoding the token hash is added to the is, a CBOR byte string with the token hash as its value is added
CBOR array used as TRL resource representation. to the CBOR array used as TRL resource representation.
o When a revoked Access Token expires, the token hash of the Access o When a revoked Access Token expires, the token hash of the Access
Token is removed from the TRL resource representation. That is, Token is removed from the TRL resource representation. That is,
the CBOR byte string encoding the token hash is removed from the the CBOR byte string with the token hash as its value is removed
CBOR array used as TRL resource representation. from the CBOR array used as TRL resource representation.
5. The TRL Endpoint 5. The TRL Endpoint
Consistent with Section 6.5 of [I-D.ietf-ace-oauth-authz], all Consistent with Section 6.5 of [I-D.ietf-ace-oauth-authz], all
communications between a caller of the TRL endpoint and the communications between a caller of the TRL endpoint and the
Authorization Server MUST be encrypted, as well as integrity and Authorization Server MUST be encrypted, as well as integrity and
replay protected. Furthermore, responses from the Authorization replay protected. Furthermore, responses from the Authorization
Server to the caller MUST be bound to the caller's request. Server to the caller MUST be bound to the caller's request.
The Authorization Server MUST implement measures to prevent access to The Authorization Server MUST implement measures to prevent access to
the TRL endpoint by entities other than registered devices and the TRL endpoint by entities other than registered devices and
authorized administrators. authorized administrators.
The TRL endpoint supports only the GET method, and provides two types The TRL endpoint supports only the GET method, and allows two types
of query of the TRL. of query of the TRL.
o Full query: the Authorization Server returns the token hashes of o Full query: the Authorization Server returns the token hashes of
the revoked Access Tokens currently in the TRL and pertaining to the revoked Access Tokens currently in the TRL and pertaining to
the requester. The processing of a full query and the related the requester. The Authorization Server MUST support this type of
response format are defined in Section 5.1. query. The processing of a full query and the related response
format are defined in Section 5.1.
o Diff query: the Authorization Server returns a list of diff o Diff query: the Authorization Server returns a list of diff
entries. Each entry is related to one of the most recent updates, entries. Each diff entry is related to one of the most recent
in the portion of the TRL pertaining to the requester. In updates, in the portion of the TRL pertaining to the requester.
particular, the entry associated to one of such updates contains a The Authorization Server MAY support this type of query.
list of token hashes, such that: i) the corresponding revoked
Access Tokens pertain to the requester; and ii) they were added to The entry associated to one of such updates contains a list of
or removed from the TRL at that update. The processing of a diff 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 processing of a diff
query and the related response format are defined in Section 5.2. query and the related response format are defined in Section 5.2.
The TRL endpoint allows the following query parameter in a GET The TRL endpoint allows the following query parameter in a GET
request. request.
o 'diff': if included, it indicates to perform a diff query of the o 'diff': if included, it indicates to perform a diff query of the
TRL. Its value MUST be either: i) 0, indicating that a TRL. Its value MUST be either:
(notification) response should include as many diff entries as the
Authorization Server can provide; or ii) a positive integer * the integer 0, indicating that a (notification) response should
greater than 0, indicating the maximum number of diff entries that include as many diff entries as the Authorization Server can
a (notification) response should include. provide in the response; or
* a positive integer greater than 0, indicating the maximum
number of diff entries that a (notification) response should
include.
5.1. Full Query of the TRL 5.1. Full Query of the TRL
In order to produce a (notification) response to a GET request asking In order to produce a (notification) response to a GET request asking
for a full query of the TRL, the Authorization Server performs the for a full query of the TRL, the Authorization Server performs the
following actions. following actions.
1. From the current TRL resource representation, the Authorization 1. From the current TRL resource representation, the Authorization
Server builds a set HASHES, such that: Server builds a set HASHES, such that:
skipping to change at page 11, line 13 skipping to change at page 11, line 51
Authorization Server. That is, the diff entries are related to Authorization Server. That is, the diff entries are related to
the U most recent TRL updates pertaining to the requester. In the U most recent TRL updates pertaining to the requester. In
particular, the first entry refers to the most recent of such particular, the first entry refers to the most recent of such
updates, the second entry refers to the second from last of such updates, the second entry refers to the second from last of such
updates, and so on. updates, and so on.
Each diff entry is a CBOR array 'diff-entry', which includes the Each diff entry is a CBOR array 'diff-entry', which includes the
following two elements. following two elements.
* The first element is a CBOR array 'removed'. Each element of * The first element is a CBOR array 'removed'. Each element of
the array is a CBOR byte string encoding the token hash of an the array is a CBOR byte string, with value the token hash of
Access Token, that pertained to the requester and that was an Access Token such that: it pertained to the requester; and
removed from the TRL during the update associated to the diff it was removed from the TRL during the update associated to
entry. the diff entry.
* The second element is a CBOR array 'added'. Each element of * The second element is a CBOR array 'added'. Each element of
the array is a CBOR byte string encoding the token hash of an the array is a CBOR byte string, with value the token hash of
Access Token, that pertains to the requester and that was an Access Token such that: it pertains to the requester; and
added to the TRL during the update associated to the diff it was added to the TRL during the update associated to the
entry. diff entry.
The order of the token hashes in the CBOR arrays 'removed' and The order of the token hashes in the CBOR arrays 'removed' and
'added' is irrelevant. That is, 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 'added' MUST be treated as a set in which the order of elements
has no significant meaning. has no significant meaning.
3. The Authorization Server prepares a 2.05 (Content) Response for 3. The Authorization Server prepares a 2.05 (Content) Response for
the requester, with a CBOR array 'diff' of U elements as payload. the requester, with a CBOR array 'diff' of U elements as payload.
Each element of the array specifies one of the CBOR arrays 'diff- Each element of the CBOR array 'diff' specifies one of the CBOR
entry' prepared at point 2 as diff entries. arrays 'diff-entry' prepared at point 2 as diff entries.
Within the CBOR array 'diff', the CBOR arrays 'diff-entry' MUST Within the CBOR array 'diff', the CBOR arrays 'diff-entry' MUST
be sorted to reflect the corresponding updates to the TRL in be sorted to reflect the corresponding updates to the TRL in
reverse chronological order. That is, the first 'diff-entry' reverse chronological order. That is, the first 'diff-entry'
element of 'diff' relates to the most recent update to the element of 'diff' relates to the most recent update to the
portion of the TRL pertaining to the requester. portion of the TRL pertaining to the requester.
The CDDL definition [RFC8610] of the CBOR array 'diff' formatted as The CDDL definition [RFC8610] of the CBOR array 'diff' formatted as
in the response from the Authorization Server is provided below. in the response from the Authorization Server is provided below.
token-hash = bytes token-hash = bytes
trl-patch = [* token-hash] trl-patch = [* token-hash]
diff-entry = [removed: trl-patch, added: trl-patch] diff-entry = [removed: trl-patch, added: trl-patch]
diff = [* diff-entry] diff = [* diff-entry]
Figure 4: CDDL definition of the response payload following a Diff Figure 4: CDDL definition of the response payload following a Diff
Query request to the TRL endpoint Query request to the TRL endpoint
If the Authorization Server supports diff queries: If the Authorization Server supports diff queries:
o The Authorization Server MUST return a 4.00 (Bad Request) response
in case the 'diff' parameter specifies a value other than 0 or
than a positive integer.
o The Authorization Server MUST keep track of N_MAX most recent o The Authorization Server MUST keep track of N_MAX most recent
updates to the portion of the TRL that pertains to each caller of updates to the portion of the TRL that pertains to each caller of
the TRL endpoint. The particular method to achieve this is the TRL endpoint. The particular method to achieve this is
implementation-specific. implementation-specific.
o When SIZE is equal to N_MAX, and a new TRL update occurs as o When SIZE is equal to N_MAX, and a new TRL update occurs as
pertaining to a registered device, the Authorization Server MUST pertaining to a registered device, the Authorization Server MUST
first delete the oldest stored update for that device, before first delete the oldest stored update for that device, before
storing this latest update as the most recent one for that device. storing this latest update as the most recent one for that device.
skipping to change at page 13, line 7 skipping to change at page 13, line 50
supports diff queries of the TRL resource (see Section 5.2). supports diff queries of the TRL resource (see Section 5.2).
After the registration procedure is finished, the administrator or After the registration procedure is finished, the administrator or
registered device performs a GET request to the TRL resource, registered device performs a GET request to the TRL resource,
including the CoAP Observe option set to 0 (register), in order to including the CoAP Observe option set to 0 (register), in order to
start an observation of the TRL resource at the Authorization Server, start an observation of the TRL resource at the Authorization Server,
as per Section 3.1 of [RFC7641]. The GET request can express the as per Section 3.1 of [RFC7641]. The GET request can express the
wish for a full query (see Section 5.1) or a diff query (see wish for a full query (see Section 5.1) or a diff query (see
Section 5.2) of the TRL. Section 5.2) of the TRL.
The Authorization Server MUST reply using the CoAP response code 2.05 In case the request is successfully processed, The Authorization
(Content) and including the CoAP Observe option in the response. The Server replies using the CoAP response code 2.05 (Content) and
payload of the response is formatted as defined in Section 5.1 or in including the CoAP Observe option in the response. The payload of
the response is formatted as defined in Section 5.1 or in
Section 5.2, in case the GET request was for a full query or a diff Section 5.2, in case the GET request was for a full query or a diff
query of the TRL, respectively. 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]).
7. Notification of Revoked Tokens 7. Notification of Revoked Tokens
In the case the TRL is updated (see Section 4.1), the Authorization When the TRL is updated (see Section 4.1), the Authorization Server
Server sends Observe Notifications to every observer of the TRL sends Observe Notifications to every observer of the TRL resource.
resource. Observe Notifications are sent as per Section 4.2 of Observe Notifications are sent as per Section 4.2 of [RFC7641].
[RFC7641].
The payload of each Observe Notification is formatted as defined in The payload of each Observe Notification is formatted as defined in
Section 5.1 or in Section 5.2, in case the original Observation Section 5.1 or in Section 5.2, in case the original Observation
Request was for a full query or a diff query of the TRL, Request was for a full query or a diff query of the TRL,
respectively. respectively.
Furthermore, an administrator or a registered device can send Furthermore, an administrator or a registered device can send
additional GET requests to the TRL endpoint at any time, in order to additional GET requests to the TRL endpoint at any time, in order to
retrieve the token hashes of the pertaining revoked Access Tokens. retrieve the token hashes of the pertaining revoked Access Tokens.
When doing so, the caller of the TRL endpoint can perform a full When doing so, the caller of the TRL endpoint can perform a full
skipping to change at page 13, line 47 skipping to change at page 14, line 47
The details of the registration process are omitted, but it is The details of the registration process are omitted, but it is
assumed that the Resource Server sends an unspecified payload to the assumed that the Resource Server sends an unspecified payload to the
Authorization Server, which replies with a 2.01 (Created) response. Authorization Server, which replies with a 2.01 (Created) response.
The payload of the registration response is a CBOR map, which The payload of the registration response is a CBOR map, which
includes the following entries: includes the following entries:
o a "trl" parameter, specifying the path of the TRL resource; o a "trl" parameter, specifying the path of the TRL resource;
o a "trl-hash" parameter, specifying the hash function used to o a "trl_hash" parameter, specifying the hash function used to
computed token hashes as defined in Section 3; computed token hashes as defined in Section 3;
o an "n-max" parameter, specifying the value of N_MAX, i.e. the o an "n_max" parameter, specifying the value of N_MAX, i.e. the
maximum number of TRL updates pertaining to each registered device maximum number of TRL updates pertaining to each registered device
that the Authorization Server retains for that device (see that the Authorization Server retains for that device (see
Section 5.2); Section 5.2);
o possible further parameters related to the registration process. o possible further parameters related to the registration process.
Furthermore, 'h(x)' refers to the hash function used to compute the Furthermore, 'h(x)' refers to the hash function used to compute the
token hashes, as defined in Section 3 of this specification and token hashes, as defined in Section 3 of this specification and
according to [RFC6920]. Assuming the usage of CWTs transported in according to [RFC6920]. Assuming the usage of CWTs transported in
CBOR, 'bstr.h(t1)' and 'bstr.h(t2)' denote the byte-string CBOR, 'bstr.h(t1)' and 'bstr.h(t2)' denote the byte-string
representations of the token hashes for the Access Tokens t1 and t2, representations of the token hashes for the Access Tokens t1 and t2,
respectively. respectively.
8.1. Full Query with Observation 8.1. Full Query with Observation
Figure 5 shows an example interaction between the Resource Server RS Figure 5 shows an example interaction considering a CoAP observation
and the Authorization Server AS, considering a CoAP observation and a and a full query of the TRL.
full query of the TRL.
RS AS RS AS
| | | |
| Registration: POST | | Registration: POST |
+-------------------------------------->| +-------------------------------------->|
| | | |
|<--------------------------------------+ |<--------------------------------------+
| 2.01 CREATED | | 2.01 CREATED |
| Payload: { | | Payload: { |
| ... | | ... |
| "trl" = "revoke/trl", | | "trl" = "revoke/trl", |
| "trl-hash" = "sha-256", | | "trl_hash" = "sha-256", |
| "n-max" = 10 | | "n_max" = 10 |
| } | | } |
| | | |
| GET Observe: 0 | | GET Observe: 0 |
| coap://example.as.com/revoke/trl/ | | coap://example.as.com/revoke/trl/ |
+-------------------------------------->| +-------------------------------------->|
| | | |
|<--------------------------------------+ |<--------------------------------------+
| 2.05 CONTENT Observe: 42 | | 2.05 CONTENT Observe: 42 |
| Payload: [] | | Payload: [] |
| . | | . |
| . | | . |
| . | | . |
| | | |
| (Access Tokens t1 and t2 issued | | (Access Tokens t1 and t2 issued |
| and successfully submitted to RS) | | and successfully submitted to RS) |
| . | | . |
| . | | . |
| . | | . |
| | | |
| |
| (Access Token t1 is revoked) | | (Access Token t1 is revoked) |
| | | |
|<--------------------------------------+ |<--------------------------------------+
| 2.05 CONTENT Observe: 53 | | 2.05 CONTENT Observe: 53 |
| Payload: [bstr.h(t1)] | | Payload: [bstr.h(t1)] |
| . | | . |
| . | | . |
| . | | . |
| | | |
| (Access Token t2 is revoked) | | (Access Token t2 is revoked) |
skipping to change at page 15, line 44 skipping to change at page 16, line 44
| | | |
|<--------------------------------------+ |<--------------------------------------+
| 2.05 CONTENT Observe: 86 | | 2.05 CONTENT Observe: 86 |
| Payload: [] | | Payload: [] |
| | | |
Figure 5: Interaction for Full Query with Observation Figure 5: Interaction for Full Query with Observation
8.2. Diff Query with Observation 8.2. Diff Query with Observation
Figure 6 shows an example interaction between the Resource Server RS Figure 6 shows an example interaction considering a CoAP observation
and the Authorization Server AS, considering a CoAP observation and a and a diff query of the TRL.
diff query of the TRL.
The Resource Server indicates N=3 as value of the query parameter The Resource Server indicates N=3 as value of the query parameter
"diff", i.e. as the maximum number of diff entries to be specified in "diff", i.e. as the maximum number of diff entries to be specified in
a response from the Authorization Server. a response from the Authorization Server.
RS AS RS AS
| | | |
| Registration: POST | | Registration: POST |
+--------------------------------------------->| +--------------------------------------------->|
| | | |
|<---------------------------------------------+ |<---------------------------------------------+
| 2.01 CREATED | | 2.01 CREATED |
| Payload: { | | Payload: { |
| ... | | ... |
| "trl" = "revoke/trl", | | "trl" = "revoke/trl", |
| "trl-hash" = "sha-256", | | "trl_hash" = "sha-256", |
| "n-max" = 10 | | "n_max" = 10 |
| } | | } |
| | | |
| GET Observe: 0 | | GET Observe: 0 |
| coap://example.as.com/revoke/trl?diff=3 | | coap://example.as.com/revoke/trl?diff=3 |
+--------------------------------------------->| +--------------------------------------------->|
| | | |
|<---------------------------------------------+ |<---------------------------------------------+
| 2.05 CONTENT Observe: 42 | | 2.05 CONTENT Observe: 42 |
| Payload: [] | | Payload: [] |
| . | | . |
skipping to change at page 16, line 47 skipping to change at page 17, line 47
| | | |
|<---------------------------------------------+ |<---------------------------------------------+
| 2.05 CONTENT Observe: 53 | | 2.05 CONTENT Observe: 53 |
| Payload: [ | | Payload: [ |
| [ [], [bstr.h(t1)] ] | | [ [], [bstr.h(t1)] ] |
| ] | | ] |
| . | | . |
| . | | . |
| . | | . |
| | | |
| |
| (Access Token t2 is revoked) | | (Access Token t2 is revoked) |
| | | |
| | | |
|<---------------------------------------------+ |<---------------------------------------------+
| 2.05 CONTENT Observe: 64 | | 2.05 CONTENT Observe: 64 |
| Payload: [ | | Payload: [ |
| [ [], [bstr.h(t2)] ], | | [ [], [bstr.h(t2)] ], |
| [ [], [bstr.h(t1)] ] | | [ [], [bstr.h(t1)] ] |
| ] | | ] |
| . | | . |
skipping to change at page 17, line 43 skipping to change at page 18, line 43
| [ [bstr.h(t2)], [] ], | | [ [bstr.h(t2)], [] ], |
| [ [bstr.h(t1)], [] ], | | [ [bstr.h(t1)], [] ], |
| [ [], [bstr.h(t2)] ] | | [ [], [bstr.h(t2)] ] |
| ] | | ] |
| | | |
Figure 6: Interaction for Diff Query with Observation Figure 6: Interaction for Diff Query with Observation
8.3. Full Query with Observation and Additional Diff Query 8.3. Full Query with Observation and Additional Diff Query
Figure 7 shows an example interaction between the Resource Server RS Figure 7 shows an example interaction considering a CoAP observation
and the Authorization Server AS, considering a CoAP observation and a and a full query of the TRL.
full query of the TRL.
The example also considers one of the notifications from the The example also considers one of the notifications from the
Authorization Server to get lost in transmission, and thus not Authorization Server to get lost in transmission, and thus not
reaching the Resource Server. reaching the Resource Server.
When this happens, and after a waiting time defined by the When this happens, and after a waiting time defined by the
application has elapsed, the Resource Server sends a GET request with application has elapsed, the Resource Server sends a GET request with
no observation to the Authorization Server, to perform a diff query no observation to the Authorization Server, to perform a diff query
of the TRL. of the TRL. The Resource Server indicates N=8 as value of the query
parameter "diff", i.e. as the maximum number of diff entries to be
In particular, the Resource Server indicates N=8 as value of the specified in a response from the Authorization Server.
query parameter "diff", i.e. as the maximum number of diff entries to
be specified in a response from the Authorization Server.
RS AS RS AS
| | | |
| Registration: POST | | Registration: POST |
+--------------------------------------------->| +--------------------------------------------->|
| | | |
|<---------------------------------------------+ |<---------------------------------------------+
| 2.01 CREATED | | 2.01 CREATED |
| Payload: { | | Payload: { |
| ... | | ... |
| "trl" = "revoke/trl", | | "trl" = "revoke/trl", |
| "trl-hash" = "sha-256", | | "trl_hash" = "sha-256", |
| "n-max" = 10 | | "n_max" = 10 |
| } | | } |
| | | |
| GET Observe: 0 | | GET Observe: 0 |
| coap://example.as.com/revoke/trl/ | | coap://example.as.com/revoke/trl/ |
+--------------------------------------------->| +--------------------------------------------->|
| | | |
|<---------------------------------------------+ |<---------------------------------------------+
| 2.05 CONTENT Observe: 42 | | 2.05 CONTENT Observe: 42 |
| Payload: [] | | Payload: [] |
| . | | . |
skipping to change at page 18, line 50 skipping to change at page 19, line 45
| and successfully submitted to RS) | | and successfully submitted to RS) |
| . | | . |
| . | | . |
| . | | . |
| | | |
| (Access Token t1 is revoked) | | (Access Token t1 is revoked) |
| | | |
|<---------------------------------------------+ |<---------------------------------------------+
| 2.05 CONTENT Observe: 53 | | 2.05 CONTENT Observe: 53 |
| Payload: [bstr.h(t1)] | | Payload: [bstr.h(t1)] |
| |
| . | | . |
| . | | . |
| . | | . |
| | | |
| (Access Token t2 is revoked) | | (Access Token t2 is revoked) |
| | | |
| |
|<---------------------------------------------+ |<---------------------------------------------+
| 2.05 CONTENT Observe: 64 | | 2.05 CONTENT Observe: 64 |
| Payload: [bstr.h(t1), | | Payload: [bstr.h(t1), |
| bstr.h(t2)] | | bstr.h(t2)] |
| . | | . |
| . | | . |
| . | | . |
| | | |
| (Access Token t1 expires) | | (Access Token t1 expires) |
| | | |
skipping to change at page 19, line 32 skipping to change at page 20, line 30
| . | | . |
| | | |
| (Access Token t2 expires) | | (Access Token t2 expires) |
| | | |
| X<-------------------------------------+ | X<-------------------------------------+
| 2.05 CONTENT Observe: 86 | | 2.05 CONTENT Observe: 86 |
| Payload: [] | | Payload: [] |
| . | | . |
| . | | . |
| . | | . |
| |
| (Enough time has passed since | | (Enough time has passed since |
| the latest received notification) | | the latest received notification) |
| | | |
| GET | | GET |
| coap://example.as.com/revoke/trl?diff=8 | | coap://example.as.com/revoke/trl?diff=8 |
+--------------------------------------------->| +--------------------------------------------->|
| | | |
|<---------------------------------------------+ |<---------------------------------------------+
| 2.05 CONTENT | | 2.05 CONTENT |
| Payload: [ | | Payload: [ |
skipping to change at page 21, line 7 skipping to change at page 22, line 7
network would prevent registered devices from ever knowing that their network would prevent registered devices from ever knowing that their
pertaining Access Tokens have been revoked. To avoid this, a pertaining Access Tokens have been revoked. To avoid this, a
registered device SHOULD NOT rely solely on the CoAP Observe registered device SHOULD NOT rely solely on the CoAP Observe
notifications. In particular, a registered device SHOULD also notifications. In particular, a registered device SHOULD also
regularly poll the Authorization Server for the most current regularly poll the Authorization Server for the most current
information about revoked Access Tokens, by sending GET requests to information about revoked Access Tokens, by sending GET requests to
the TRL endpoint according to an application policy. the TRL endpoint according to an application policy.
10. IANA Considerations 10. IANA Considerations
This document has no actions for IANA. This document has the following actions for IANA.
10.1. Media Type Registrations
This specification registers the 'application/ace-trl+cbor' media
type for messages of the protocols 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 CBOR map containing the
protocol parameters defined in [this document].
Security considerations: See Section 9 of this document.
Interoperability considerations: N/A
Published specification: [this document]
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 [this document].
Fragment identifier considerations: N/A
Additional information: N/A
Person & email address to contact for further information:
<iesg@ietf.org>
Intended usage: COMMON
Restrictions on usage: None
Author: Marco Tiloca <marco.tiloca@ri.se.com>
Change controller: IESG
10.2. CoAP Content-Formats Registry
This specification registers the following entry to the "CoAP
Content-Formats" registry, within the "CoRE Parameters" registry:
Media Type: application/ace-trl+cbor
Encoding: -
ID: TBD
Reference: [this document]
10.3. Token Revocation List Registry
This specification establishes the "Token Revocation List" IANA
Registry. The Registry has been created to use the "Expert Review"
registration procedure [RFC8126]. Expert review guidelines are
provided in Section 10.4. It should be noted that, in addition to
the expert review, some portions of the Registry require a
specification, potentially a Standards Track RFC, to be supplied as
well.
The columns of this Registry are:
o Name: This is a descriptive name that enables easier reference to
the item. The name MUST be unique. It is not used in the
encoding.
o CBOR Key: This is the value used as CBOR key of the item. These
values MUST be unique. The value can be a positive 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. 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.
o CBOR Type: This contains the CBOR type of the item, or a pointer
to the registry that defines its type, when that depends on
another item.
o Reference: This contains a pointer to the public specification for
the item.
This Registry has been initially populated by the values in
Appendix B.4.4. The Reference column for all of these entries refers
to this document.
10.4. Expert Review Instructions
The IANA registry established in this document is defined as expert
review. 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:
o 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.
o Specifications are required for the standards track range of point
assignment. Specifications should exist for specification
required ranges, but early assignment before a specification is
available is considered to be permissible. Specifications are
needed for the first-come, first-serve range 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.
o 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.
11. References 11. References
11.1. Normative References 11.1. Normative References
[I-D.ietf-ace-oauth-authz] [I-D.ietf-ace-oauth-authz]
Seitz, L., Selander, G., Wahlstroem, E., Erdtman, S., and Seitz, L., Selander, G., Wahlstroem, E., Erdtman, S., and
H. Tschofenig, "Authentication and Authorization for H. Tschofenig, "Authentication and Authorization for
Constrained Environments (ACE) using the OAuth 2.0 Constrained Environments (ACE) using the OAuth 2.0
Framework (ACE-OAuth)", draft-ietf-ace-oauth-authz-35 Framework (ACE-OAuth)", draft-ietf-ace-oauth-authz-37
(work in progress), June 2020. (work in progress), February 2021.
[I-D.ietf-cbor-7049bis]
Bormann, C. and P. Hoffman, "Concise Binary Object
Representation (CBOR)", draft-ietf-cbor-7049bis-16 (work
in progress), September 2020.
[Named.Information.Hash.Algorithm] [Named.Information.Hash.Algorithm]
IANA, "Named Information Hash Algorithm", IANA, "Named Information Hash Algorithm",
<https://www.iana.org/assignments/named-information/named- <https://www.iana.org/assignments/named-information/named-
information.xhtml>. information.xhtml>.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, Requirement Levels", BCP 14, RFC 2119,
DOI 10.17487/RFC2119, March 1997, DOI 10.17487/RFC2119, March 1997,
<https://www.rfc-editor.org/info/rfc2119>. <https://www.rfc-editor.org/info/rfc2119>.
[RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework",
RFC 6749, DOI 10.17487/RFC6749, October 2012, RFC 6749, DOI 10.17487/RFC6749, October 2012,
<https://www.rfc-editor.org/info/rfc6749>. <https://www.rfc-editor.org/info/rfc6749>.
[RFC6838] Freed, N., Klensin, J., and T. Hansen, "Media Type
Specifications and Registration Procedures", BCP 13,
RFC 6838, DOI 10.17487/RFC6838, January 2013,
<https://www.rfc-editor.org/info/rfc6838>.
[RFC6920] Farrell, S., Kutscher, D., Dannewitz, C., Ohlman, B., [RFC6920] Farrell, S., Kutscher, D., Dannewitz, C., Ohlman, B.,
Keranen, A., and P. Hallam-Baker, "Naming Things with Keranen, A., and P. Hallam-Baker, "Naming Things with
Hashes", RFC 6920, DOI 10.17487/RFC6920, April 2013, Hashes", RFC 6920, DOI 10.17487/RFC6920, April 2013,
<https://www.rfc-editor.org/info/rfc6920>. <https://www.rfc-editor.org/info/rfc6920>.
[RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained
Application Protocol (CoAP)", RFC 7252, Application Protocol (CoAP)", RFC 7252,
DOI 10.17487/RFC7252, June 2014, DOI 10.17487/RFC7252, June 2014,
<https://www.rfc-editor.org/info/rfc7252>. <https://www.rfc-editor.org/info/rfc7252>.
[RFC7519] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token [RFC7519] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token
(JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015, (JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015,
<https://www.rfc-editor.org/info/rfc7519>. <https://www.rfc-editor.org/info/rfc7519>.
[RFC7641] Hartke, K., "Observing Resources in the Constrained [RFC7641] Hartke, K., "Observing Resources in the Constrained
Application Protocol (CoAP)", RFC 7641, Application Protocol (CoAP)", RFC 7641,
DOI 10.17487/RFC7641, September 2015, DOI 10.17487/RFC7641, September 2015,
<https://www.rfc-editor.org/info/rfc7641>. <https://www.rfc-editor.org/info/rfc7641>.
[RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for
Writing an IANA Considerations Section in RFCs", BCP 26,
RFC 8126, DOI 10.17487/RFC8126, June 2017,
<https://www.rfc-editor.org/info/rfc8126>.
[RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
May 2017, <https://www.rfc-editor.org/info/rfc8174>. May 2017, <https://www.rfc-editor.org/info/rfc8174>.
[RFC8259] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data [RFC8259] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data
Interchange Format", STD 90, RFC 8259, Interchange Format", STD 90, RFC 8259,
DOI 10.17487/RFC8259, December 2017, DOI 10.17487/RFC8259, December 2017,
<https://www.rfc-editor.org/info/rfc8259>. <https://www.rfc-editor.org/info/rfc8259>.
[RFC8392] Jones, M., Wahlstroem, E., Erdtman, S., and H. Tschofenig, [RFC8392] Jones, M., Wahlstroem, E., Erdtman, S., and H. Tschofenig,
"CBOR Web Token (CWT)", RFC 8392, DOI 10.17487/RFC8392, "CBOR Web Token (CWT)", RFC 8392, DOI 10.17487/RFC8392,
May 2018, <https://www.rfc-editor.org/info/rfc8392>. May 2018, <https://www.rfc-editor.org/info/rfc8392>.
[RFC8610] Birkholz, H., Vigano, C., and C. Bormann, "Concise Data
Definition Language (CDDL): A Notational Convention to
Express Concise Binary Object Representation (CBOR) and
JSON Data Structures", RFC 8610, DOI 10.17487/RFC8610,
June 2019, <https://www.rfc-editor.org/info/rfc8610>.
[RFC8949] Bormann, C. and P. Hoffman, "Concise Binary Object
Representation (CBOR)", STD 94, RFC 8949,
DOI 10.17487/RFC8949, December 2020,
<https://www.rfc-editor.org/info/rfc8949>.
11.2. Informative References 11.2. Informative References
[I-D.bormann-t2trg-stp] [I-D.bormann-t2trg-stp]
Bormann, C. and K. Hartke, "The Series Transfer Pattern Bormann, C. and K. Hartke, "The Series Transfer Pattern
(STP)", draft-bormann-t2trg-stp-03 (work in progress), (STP)", draft-bormann-t2trg-stp-03 (work in progress),
April 2020. April 2020.
[RFC7009] Lodderstedt, T., Ed., Dronia, S., and M. Scurtescu, "OAuth [RFC7009] Lodderstedt, T., Ed., Dronia, S., and M. Scurtescu, "OAuth
2.0 Token Revocation", RFC 7009, DOI 10.17487/RFC7009, 2.0 Token Revocation", RFC 7009, DOI 10.17487/RFC7009,
August 2013, <https://www.rfc-editor.org/info/rfc7009>. August 2013, <https://www.rfc-editor.org/info/rfc7009>.
[RFC8610] Birkholz, H., Vigano, C., and C. Bormann, "Concise Data
Definition Language (CDDL): A Notational Convention to
Express Concise Binary Object Representation (CBOR) and
JSON Data Structures", RFC 8610, DOI 10.17487/RFC8610,
June 2019, <https://www.rfc-editor.org/info/rfc8610>.
Appendix A. Usage of the Series Transfer Pattern Appendix A. Usage of the Series Transfer Pattern
This section discusses how the diff query of the TRL defined in This section discusses how the diff query of the TRL defined in
Section 5.2 is a usage example of the Series Transfer Pattern defined Section 5.2 is a usage example of the Series Transfer Pattern defined
in [I-D.bormann-t2trg-stp]. in [I-D.bormann-t2trg-stp].
A diff query enables the transfer of a series of TRL updates, with 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 the Authorization Server specifying U <= N_MAX diff entries as the U
most recent updates to the portion of the TRL pertaining to a most recent updates to the portion of the TRL pertaining to a
registered device. registered device.
skipping to change at page 24, line 18 skipping to change at page 28, line 28
To this end, each series item in an update collection is also To this end, each series item in an update collection is also
associated with an unsigned integer 'index', with value the absolute associated with an unsigned integer 'index', with value the absolute
counter of series items added to that collection minus 1. That is, counter of series items added to that collection minus 1. That is,
the first series item added to a collection has 'index' with value 0. the first series item added to a collection has 'index' with value 0.
Then, the values of 'index' are used as cursor information. Then, the values of 'index' are used as cursor information.
Furthermore, the Authorization Server defines an unsigned integer Furthermore, the Authorization Server defines an unsigned integer
MAX_DIFF_BATCH <= N_MAX, specifying the maximum number of diff MAX_DIFF_BATCH <= N_MAX, specifying the maximum number of diff
entries to be included in a single diff query response. If entries to be included in a single diff query response. If
supporting diff queries, the Authorization Server should provide supporting diff queries, the Authorization Server SHOULD provide
registered devices and administrators with the value of registered devices and administrators with the value of
MAX_DIFF_BATCH, upon their registration. MAX_DIFF_BATCH, upon their registration (see Section 6).
Finally, the full query and diff query exchanges defined in Finally, the full query and diff query exchanges defined in
Section 5.1 and Section 5.2 are extended as follows. Section 5.1 and Section 5.2 are extended as follows.
In particular, successul responses from the TRL endpoint MUST use the
Content-Format "application/ace-trl+cbor" defined in Section 10.2 of
this specification.
B.1. Full Query Request B.1. Full Query Request
No changes apply to what defined in Section 5.1. No changes apply to what defined in Section 5.1.
B.2. Full Query Response B.2. Full Query Response
The response to a full query request (see Section 5.1) includes the When sending a 2.05 (Content) response to a full query request (see
CBOR array of token hashes as well as a parameter 'cursor', encoded Appendix B.1), the response payload includes a CBOR map with the
either as a CBOR unsigned integer or the CBOR simple value Null. following fields, whose CBOR labels are defined in Appendix B.4.4.
The 'cursor' parameter specifies the value Null if there are o 'trl': this field MUST include a CBOR array of token hashes. The
currently no updates pertinent to the requester, i.e. the update CBOR array is populated and formatted as defined in Section 5.1.
collection for that requester is empty. This is the case from when
the requester registers at the Authorization Server until a first
update pertaining that requester occurs to the TRL.
Otherwise, the 'cursor' parameter takes the value of 'index' for the o 'cursor': this field MUST include either the CBOR simple value
last series item in the collection, as corresponding to the most Null or a CBOR unsigned integer.
recent update pertaining to the requester occurred to the TRL.
The CBOR simple value Null MUST be used to indicate that there are
currently no TRL updates pertinent to the requester, i.e. the
update collection for that requester is empty. This is the case
from when the requester registers at the Authorization Server
until a first update pertaining that requester occurs to the TRL.
Otherwise, the field MUST include a CBOR unsigned integer,
encoding the 'index' value of the last series item in the
collection, as corresponding to the most recent update pertaining
to the requester occurred to the TRL.
B.3. Diff Query Request B.3. Diff Query Request
In addition to the query parameter 'diff' (see Section 5.2), the In addition to the query parameter 'diff' (see Section 5.2), the
requester can specify a query parameter 'cursor', with value an requester can specify a query parameter 'cursor', with value an
unsigned integer. unsigned integer.
B.4. Diff Query Response B.4. Diff Query Response
When receiving the diff query request, the Authorization Server The Authorization Server composes a response to a diff query request
proceeds as follows. (see Appendix B.3) as follows, depending on the parameters specified
in the request and on the current status of the update collection for
the requester.
B.4.1. Empty Collection B.4.1. Empty Collection
If the collection associated to the requester has no elements, the If the collection associated to the requester has no elements, the
Authorization Server returns a diff query response that contains: Authorization Server returns a 2.05 (Content) diff query response.
o The 'diff' parameter, encoding an empty CBOR array. The response payload includes a CBOR map with the following fields,
whose CBOR labels are defined in Appendix B.4.4.
o A 'cursor' parameter, encoding the CBOR simple value Null. o 'diff': this field MUST include an empty CBOR array.
o A 'more' parameter, encoding the CBOR simple value False. o 'cursor': this field MUST include the CBOR simple value Null.
o 'more': this fields MUST include the CBOR simple value False.
B.4.2. Cursor Not Specified in the Diff Query Request B.4.2. Cursor Not Specified in the Diff Query Request
If the update collection associated to the requester is not empty and If the update collection associated to the requester is not empty and
the diff query request does not include the query parameter 'cursor', the diff query request does not include the query parameter 'cursor',
the Authorization Server returns a diff query response that contains: the Authorization Server returns a 2.05 (Content) diff query
response.
o The 'diff' CBOR array, including L = min(U, MAX_DIFF_BATCH) diff The response payload includes a CBOR map with the following fields,
entries. In particular: whose CBOR labels are defined in Appendix B.4.4.
o 'diff': this field MUST include a CBOR array, containing L =
min(U, MAX_DIFF_BATCH) diff entries. In particular, the CBOR
array is populated as follows.
* If U <= MAX_DIFF_BATCH, these diff entries are the last series * If U <= MAX_DIFF_BATCH, these diff entries are the last series
items in the collection associated to the requester, items in the collection associated to the requester,
corresponding to the L most recent TRL updates pertaining to corresponding to the L most recent TRL updates pertaining to
the requester. the requester.
* If U > MAX_DIFF_BATCH, these diff entries are the eldest of the * If U > MAX_DIFF_BATCH, these diff entries are the eldest of the
last L series items in the collection associated to the last L series items in the collection associated to the
requester, as corresponding to the first L of the U most recent requester, as corresponding to the first L of the U most recent
TRL updates pertaining to the requester. TRL updates pertaining to the requester.
o A 'cursor' parameter, encoded as a CBOR unsigned integer. This The 'diff' CBOR array as well as the individual diff entries have
the same format specified in Figure 4 and used for the reponse
payload defined in Section 5.2.
o 'cursor': this field MUST include a CBOR unsigned integer. This
takes the 'index' value of the series element of the collection takes the 'index' value of the series element of the collection
included as first diff entry in the 'diff' CBOR array. That is, included as first diff entry in the 'diff' CBOR array. That is,
it takes the 'index' value of the series item in the collection it takes the 'index' value of the series item in the collection
corresponding to the most recent update pertaining to the corresponding to the most recent update pertaining to the
requester and returned in this diff query response. requester and returned in this diff query response.
Note that 'cursor' takes the same 'index' value of the last series Note that 'cursor' takes the same 'index' value of the last series
item in the collection when U <= MAX_DIFF_BATCH. item in the collection when U <= MAX_DIFF_BATCH.
o A 'more' parameter, encoded as the CBOR simple value False if U <= o 'more': this field MUST include the CBOR simple value False if U
MAX_DIFF_BATCH, or as the CBOR simple value True otherwise. <= MAX_DIFF_BATCH, or the CBOR simple value True otherwise.
If 'more' has value True, the requester can send a follow-up diff If 'more' has value True, the requester can send a follow-up diff
query request including the query parameter 'cursor', with the query request including the query parameter 'cursor', with the
same value of the 'cursor' parameter included in this response. same value of the 'cursor' field included in this diff query
This would result in the Authorization Server transfering the response. This would result in the Authorization Server
following subset of series items as diff entries, i.e. resuming transfering the following subset of series items as diff entries,
from where interrupted in the previous transfer. i.e. resuming from where interrupted in the previous transfer.
B.4.3. Cursor Specified in the Diff Query Request B.4.3. Cursor Specified in the Diff Query Request
If the update collection associated to the requester is not empty and If the update collection associated to the requester is not empty and
the diff query request includes the query parameter 'cursor' with the diff query request includes the query parameter 'cursor' with
value P, the Authorization Server proceeds as follows. value P, the Authorization Server proceeds as follows.
o The Authorization Server MUST return a 4.00 (Bad Request) response
in case the 'cursor' parameter specifies a value other than 0 or
than a positive integer.
o If no series item X with 'index' having value P is found in the o If no series item X with 'index' having value P is found in the
collection associated to the requester, then that item has been collection associated to the requester, then that item has been
previously removed from the history of updates for that requester previously removed from the history of updates for that requester
(see Appendix A). In this case, the Authorization Server returns (see Appendix A). In this case, the Authorization Server returns
a diff query response that contains: a 2.05 (Content) diff query response.
* The 'diff' parameter, encoding an empty CBOR array. The response payload includes a CBOR map with the following
fields, whose CBOR labels are defined in Appendix B.4.4.
* A 'cursor' parameter, encoding the CBOR simple value Null. * 'diff': this field MUST include an empty CBOR array.
* A 'more' parameter, encoding the CBOR simple value True. * 'cursor': this field MUST include the CBOR simple value Null.
* 'more': this field MUST include the CBOR simple value True.
With the combination ('cursor', 'more') = (Null, True), the With the combination ('cursor', 'more') = (Null, True), the
Authorization Server is signaling that the update collection is in Authorization Server is signaling that the update collection is in
fact not empty, but that some series items have been lost due to fact not empty, but that some series items have been lost due to
their removal, including the item with 'index' value P that the their removal, including the item with 'index' value P that the
requester wished to use as checkpoint. requester wished to use as checkpoint.
When receiving this diff query response, the requester should send When receiving this diff query response, the requester should send
a new full query request to the Authorization Server, in order to a new full query request to the Authorization Server, in order to
fully retrieve the current pertaining portion of the TRL. fully retrieve the current pertaining portion of the TRL.
o If the series item X with 'index' having value P is found in the o If the series item X with 'index' having value P is found in the
collection associated to the requester, the Authorization Server collection associated to the requester, the Authorization Server
returns a diff query response that contains: returns a 2.05 (Content) diff query response.
* The 'diff' CBOR array, including L = min(SUB_U, MAX_DIFF_BATCH) The response payload includes a CBOR map with the following
diff entries, where SUB_U = min(NUM, SUB_SIZE), and SUB_SIZE is fields, whose CBOR labels are defined in Appendix B.4.4.
the number of series items in the collection following the
series item X. * 'diff': this field MUST include a CBOR array, containing L =
min(SUB_U, MAX_DIFF_BATCH) diff entries, where SUB_U = min(NUM,
SUB_SIZE), and SUB_SIZE is the number of series items in the
collection following the series item X.
That is, these are the L updates pertaining to the requester That is, these are the L updates pertaining to the requester
that immediately follow the series item X indicated as that immediately follow the series item X indicated as
checkpoint. In particular: checkpoint. In particular, the CBOR array is populated as
follows.
+ If SUB_U <= MAX_DIFF_BATCH, these diff entries are the last + If SUB_U <= MAX_DIFF_BATCH, these diff entries are the last
series items in the collection associated to the requester, series items in the collection associated to the requester,
corresponding to the L most recent TRL updates pertaining to corresponding to the L most recent TRL updates pertaining to
the requester. the requester.
+ If SUB_U > MAX_DIFF_BATCH, these diff entries are the eldest + If SUB_U > MAX_DIFF_BATCH, these diff entries are the eldest
of the last L series items in the collection associated to of the last L series items in the collection associated to
the requester, corresponding to the first L of the SUB_U the requester, corresponding to the first L of the SUB_U
most recent TRL updates pertaining to the requester. most recent TRL updates pertaining to the requester.
* A 'cursor' parameter, encoded as a CBOR unsigned integer. If L The 'diff' CBOR array as well as the individual diff entries
is equal to 0, i.e. the series item X is the last one in the have the same format specified in Figure 4 and used for the
collection, 'cursor' takes the same 'index' value of the last reponse payload defined in Section 5.2.
series item in the collection. Otherwise, 'cursor' takes the
'index' value of the series element of the collection included * 'cursor': this field MUST include a CBOR unsigned integer. In
as first diff entry in the 'diff' CBOR array. That is, it particular:
takes the 'index' value of the series item in the collection
corresponding to the most recent update pertaining to the + If L is equal to 0, i.e. the series item X is the last one
requester and returned in this diff query response. in the collection, 'cursor' takes the same 'index' value of
the last series item in the collection.
+ If L is different than 0, 'cursor' takes the 'index' value
of the series element of the collection included as first
diff entry in the 'diff' CBOR array. That is, it takes the
'index' value of the series item in the collection
corresponding to the most recent update pertaining to the
requester and returned in this diff query response.
Note that 'cursor' takes the same 'index' value of the last Note that 'cursor' takes the same 'index' value of the last
series item in the collection when SUB_U <= MAX_DIFF_BATCH. series item in the collection when SUB_U <= MAX_DIFF_BATCH.
* A 'more' parameter, encoded as the CBOR simple value False if * 'more': this field MUST include the CBOR simple value False if
SUB_U <= MAX_DIFF_BATCH, or as the CBOR simple value True SUB_U <= MAX_DIFF_BATCH, or the CBOR simple value True
otherwise. otherwise.
If 'more' has value True, the requester can send a follow-up If 'more' has value True, the requester can send a follow-up
diff query request including the query parameter 'cursor', with diff query request including the query parameter 'cursor', with
the same value of the 'cursor' parameter specified in this diff the same value of the 'cursor' field specified in this diff
query response. This would result in the Authorization Server query response. This would result in the Authorization Server
transfering the following subset of series items as diff transfering the following subset of series items as diff
entries, i.e. resuming from where interrupted in the previous entries, i.e. resuming from where interrupted in the previous
transfer. transfer.
B.4.4. TRL Parameters
This specification defines a number of fields used in the response to
a diff query request to the TRL endpoint relying on the "Cursor"
pattern, as defined in Appendix B.
The table below summarizes them, and specifies the CBOR key to use
instead of the full descriptive name. Note that the Content-Format
"application/ace-trl+cbor" defined in Section 10.2 of this
specification MUST be used when these fields are transported.
+--------+----------+---------------------+-----------+
| Name | CBOR Key | CBOR Type | Reference |
+--------+----------+---------------------+-----------+
| trl | TBD | array | [This |
| | | | Document] |
+--------+----------+---------------------+-----------+
| cursor | TBD | simple value null / | [This |
| | | unsigned integer | Document] |
+--------+----------+---------------------+-----------+
| diff | TBD | array | [This |
| | | | Document] |
+--------+----------+---------------------+-----------+
| more | TBD | simple value True | [This |
| | | or False | Document] |
+--------+----------+---------------------+-----------+
Acknowledgments Acknowledgments
The authors sincerely thank Carsten Bormann, Benjamin Kaduk, Jim The authors sincerely thank Carsten Bormann, Benjamin Kaduk, Jim
Schaad, Goeran Selander and Travis Spencer for their comments and Schaad, Goeran Selander and Travis Spencer for their comments and
feedback. feedback.
The work on this document has been partly supported by VINNOVA and The work on this document has been partly supported by VINNOVA and
the Celtic-Next project CRITISEC; and by the H2020 project SIFIS-Home the Celtic-Next project CRITISEC; and by the H2020 project SIFIS-Home
(Grant agreement 952652). (Grant agreement 952652).
 End of changes. 83 change blocks. 
196 lines changed or deleted 428 lines changed or added

This html diff was produced by rfcdiff 1.45. The latest version is available from http://tools.ietf.org/tools/rfcdiff/