< draft-ietf-ace-revoked-token-notification-00.txt   draft-ietf-ace-revoked-token-notification-01.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: 30 May 2022 Combitech Expires: 8 September 2022 Combitech
F. Palombini F. Palombini
Ericsson AB Ericsson AB
S. Echeverria S. Echeverria
G. Lewis G. Lewis
CMU SEI CMU SEI
26 November 2021 7 March 2022
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-ietf-ace-revoked-token-notification-00 draft-ietf-ace-revoked-token-notification-01
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 allows Clients and Resource Servers to access a Token Revocation List
Protocol (CoAP), with Clients and Resource Servers observing a Token on the Authorization Server, with the possible additional use of
Revocation List on the Authorization Server. Resulting unsolicited resource observation for the Constrained Application Protocol (CoAP).
notifications of revoked Access Tokens complement alternative Resulting (unsolicited) notifications of revoked Access Tokens
approaches such as token introspection, while not requiring complement alternative approaches such as token introspection, while
additional endpoints on Clients and Resource Servers. not requiring additional endpoints on Clients and Resource Servers.
Discussion Venues Discussion Venues
This note is to be removed before publishing as an RFC. This note is to be removed before publishing as an RFC.
Discussion of this document takes place on the Constrained RESTful Discussion of this document takes place on the Authentication and
Environments Working Group mailing list (ace@ietf.org), which is Authorization for Constrained Environments Working Group mailing list
archived at https://mailarchive.ietf.org/arch/browse/ace/. (ace@ietf.org), which is archived at
https://mailarchive.ietf.org/arch/browse/ace/.
Source for this draft and an issue tracker can be found at Source for this draft and an issue tracker can be found at
https://gitlab.com/crimson84/draft-tiloca-ace-revoked-token- https://github.com/ace-wg/ace-revoked-token-notification.
notification.
Status of This Memo Status of This Memo
This Internet-Draft is submitted in full conformance with the This Internet-Draft is submitted in full conformance with the
provisions of BCP 78 and BCP 79. provisions of BCP 78 and BCP 79.
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 30 May 2022. This Internet-Draft will expire on 8 September 2022.
Copyright Notice Copyright Notice
Copyright (c) 2021 IETF Trust and the persons identified as the Copyright (c) 2022 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 (https://trustee.ietf.org/ Provisions Relating to IETF Documents (https://trustee.ietf.org/
license-info) in effect on the date of publication of this document. license-info) in effect on the date of publication of this document.
Please review these documents carefully, as they describe your rights Please review these documents carefully, as they describe your rights
and restrictions with respect to this document. Code Components and restrictions with respect to this document. Code Components
extracted from this document must include Simplified BSD License text extracted from this document must include Revised BSD License text as
as described in Section 4.e of the Trust Legal Provisions and are described in Section 4.e of the Trust Legal Provisions and are
provided without warranty as described in the Simplified BSD License. provided without warranty as described in the Revised BSD License.
Table of Contents Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3
1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 4 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 4
2. Protocol Overview . . . . . . . . . . . . . . . . . . . . . . 6 2. Protocol Overview . . . . . . . . . . . . . . . . . . . . . . 6
3. Token Hash . . . . . . . . . . . . . . . . . . . . . . . . . 8 3. Token Hash . . . . . . . . . . . . . . . . . . . . . . . . . 8
4. The TRL Resource . . . . . . . . . . . . . . . . . . . . . . 9 4. The TRL Resource . . . . . . . . . . . . . . . . . . . . . . 9
4.1. Update of the TRL Resource . . . . . . . . . . . . . . . 10 4.1. Update of the TRL Resource . . . . . . . . . . . . . . . 10
5. The TRL Endpoint . . . . . . . . . . . . . . . . . . . . . . 10 5. The TRL Endpoint . . . . . . . . . . . . . . . . . . . . . . 10
5.1. Full Query of the TRL . . . . . . . . . . . . . . . . . . 11 6. Full Query of the TRL . . . . . . . . . . . . . . . . . . . . 11
5.2. Diff Query of the TRL . . . . . . . . . . . . . . . . . . 12 7. Diff Query of the TRL . . . . . . . . . . . . . . . . . . . . 12
6. Upon Registration . . . . . . . . . . . . . . . . . . . . . . 14 8. Upon Registration . . . . . . . . . . . . . . . . . . . . . . 14
7. Notification of Revoked Tokens . . . . . . . . . . . . . . . 15 9. Notification of Revoked Tokens . . . . . . . . . . . . . . . 15
8. Interaction Examples . . . . . . . . . . . . . . . . . . . . 15 10. Interaction Examples . . . . . . . . . . . . . . . . . . . . 16
8.1. Full Query with Observation . . . . . . . . . . . . . . . 16 10.1. Full Query with Observation . . . . . . . . . . . . . . 17
8.2. Diff Query with Observation . . . . . . . . . . . . . . . 18 10.2. Diff Query with Observation . . . . . . . . . . . . . . 18
8.3. Full Query with Observation and Additional Diff Query . . 19 10.3. Full Query with Observation and Additional Diff Query . 20
9. Security Considerations . . . . . . . . . . . . . . . . . . . 22 11. ACE Token Revocation List Parameters . . . . . . . . . . . . 23
10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 23 12. ACE Token Revocation List Error Identifiers . . . . . . . . . 23
10.1. Media Type Registrations . . . . . . . . . . . . . . . . 23 13. Security Considerations . . . . . . . . . . . . . . . . . . . 24
10.2. CoAP Content-Formats Registry . . . . . . . . . . . . . 24 14. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 25
10.3. Token Revocation List Registry . . . . . . . . . . . . . 24 14.1. Media Type Registrations . . . . . . . . . . . . . . . . 25
10.4. Expert Review Instructions . . . . . . . . . . . . . . . 25 14.2. CoAP Content-Formats Registry . . . . . . . . . . . . . 26
11. References . . . . . . . . . . . . . . . . . . . . . . . . . 25 14.3. ACE Token Revocation List Parameters Registry . . . . . 26
11.1. Normative References . . . . . . . . . . . . . . . . . . 25 14.4. ACE Token Revocation List Errors . . . . . . . . . . . . 27
11.2. Informative References . . . . . . . . . . . . . . . . . 27 14.5. Expert Review Instructions . . . . . . . . . . . . . . . 28
Appendix A. Usage of the Series Transfer Pattern . . . . . . . . 27 15. References . . . . . . . . . . . . . . . . . . . . . . . . . 28
Appendix B. Usage of the "Cursor" Pattern . . . . . . . . . . . 29 15.1. Normative References . . . . . . . . . . . . . . . . . . 28
B.1. Full Query Request . . . . . . . . . . . . . . . . . . . 29 15.2. Informative References . . . . . . . . . . . . . . . . . 30
B.2. Full Query Response . . . . . . . . . . . . . . . . . . . 29 Appendix A. On using the Series Transfer Pattern . . . . . . . . 30
B.3. Diff Query Request . . . . . . . . . . . . . . . . . . . 30 Appendix B. Usage of the "Cursor" Pattern . . . . . . . . . . . 32
B.4. Diff Query Response . . . . . . . . . . . . . . . . . . . 30 B.1. Full Query Request . . . . . . . . . . . . . . . . . . . 33
B.4.1. Empty Collection . . . . . . . . . . . . . . . . . . 30 B.2. Full Query Response . . . . . . . . . . . . . . . . . . . 33
B.4.2. Cursor Not Specified in the Diff Query Request . . . 30 B.3. Diff Query Request . . . . . . . . . . . . . . . . . . . 33
B.4.3. Cursor Specified in the Diff Query Request . . . . . 31 B.4. Diff Query Response . . . . . . . . . . . . . . . . . . . 34
B.4.4. TRL Parameters . . . . . . . . . . . . . . . . . . . 33 B.4.1. Empty Collection . . . . . . . . . . . . . . . . . . 34
Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . 34 B.4.2. Cursor Not Specified in the Diff Query Request . . . 34
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 34 B.4.3. Cursor Specified in the Diff Query Request . . . . . 35
Appendix C. Document Updates . . . . . . . . . . . . . . . . . . 38
C.1. Version -00 to -01 . . . . . . . . . . . . . . . . . . . 38
Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . 38
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 38
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 7 skipping to change at page 4, line 14
As discussed in Section 6.1 of [I-D.ietf-ace-oauth-authz], only As discussed in Section 6.1 of [I-D.ietf-ace-oauth-authz], only
client-initiated revocation is currently specified [RFC7009] for client-initiated revocation is currently specified [RFC7009] for
OAuth 2.0 [RFC6749], based on the assumption that Access Tokens in OAuth 2.0 [RFC6749], based on the assumption that Access Tokens in
OAuth are issued with a relatively short lifetime. However, this is OAuth are issued with a relatively short lifetime. However, this is
not expected to be the case for constrained, intermittently connected not expected to be the case for constrained, intermittently connected
devices, that need Access Tokens with relatively long lifetimes. devices, that need Access Tokens with relatively long lifetimes.
This document specifies a method for allowing registered devices to This document specifies a method for allowing registered devices to
access and possibly subscribe to a Token Revocation List (TRL) access and possibly subscribe to a Token Revocation List (TRL)
resource on the Authorization Server, in order to get an updated list resource on the Authorization Server, in order to obtain an updated
of revoked, but yet not expired, pertaining Access Tokens. In list of revoked, but yet not expired, pertaining Access Tokens. In
particular, registered devices can subscribe to the TRL at the particular, registered devices can subscribe to the TRL at the
Authorization Server by using resource observation [RFC7641] for the Authorization Server by using resource observation [RFC7641] for the
Constrained Application Protocol (CoAP) [RFC7252]. Constrained Application Protocol (CoAP) [RFC7252].
Unlike in the case of token introspection (see Section 5.9 of 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 [I-D.ietf-ace-oauth-authz]), a registered device does not provide an
owned Access Token to the Authorization Server for inquiring about owned Access Token to the Authorization Server for inquiring about
its current state. Instead, registered devices simply obtain an its current state. Instead, registered devices simply obtain an
updated list of revoked, but yet not expired, pertaining Access updated list of revoked, but yet not expired, pertaining Access
Tokens, as efficiently identified by corresponding hash values. Tokens, as efficiently identified by corresponding hash values.
In fact, the benefits of this method are that it complements token The benefits of this method are that it complements token
introspection, and it does not require any additional endpoints on introspection, and it does not require any additional endpoints on
the registered devices. The only additional requirements for the registered devices. The only additional requirements for
registered devices are a request/response interaction with the registered devices are a request/response interaction with the
Authorization Server to access and possibly subscribe to the TRL (see Authorization Server to access and possibly subscribe to the TRL (see
Section 2), and the lightweight computation of hash values as Token Section 2), and the lightweight computation of hash values to use as
identifiers (see Section 3). Token identifiers (see Section 3).
1.1. Terminology 1.1. Terminology
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
"OPTIONAL" in this document are to be interpreted as described in BCP "OPTIONAL" in this document are to be interpreted as described in BCP
14 [RFC2119] [RFC8174] when, and only when, they appear in all 14 [RFC2119] [RFC8174] when, and only when, they appear in all
capitals, as shown here. capitals, as shown here.
Readers are expected to be familiar with the terms and concepts Readers are expected to be familiar with the terms and concepts
skipping to change at page 5, line 19 skipping to change at page 5, line 24
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.
* Token hash: identifier of an Access Token, in binary format * Token hash: identifier of an Access Token, in binary format
encoding. The token hash has no relation to other possibly used encoding. The token hash has no relation to other possibly used
token identifiers, such as the "cti" (CWT ID) claim of CBOR Web token identifiers, such as the "cti" (CWT ID) claim of CBOR Web
Tokens (CWTs) [RFC8392]. Tokens (CWTs) [RFC8392].
* Token Revocation List (TRL): a collection of token hashes, in * Token Revocation List (TRL): a collection of token hashes such
which the corresponding Access Tokens have been revoked but are that the corresponding Access Tokens have been revoked but are not
not expired yet. expired yet.
* TRL resource: a resource on the Authorization Server, with a TRL * TRL resource: a resource on the Authorization Server, with a TRL
as its representation. as its representation.
* TRL endpoint: an endpoint at the Authorization Server associated * TRL endpoint: an endpoint at the Authorization Server associated
to the TRL resource. The default name of the TRL endpoint in a with the TRL resource. The default name of the TRL endpoint in a
url-path is '/revoke/trl'. Implementations are not required to url-path is '/revoke/trl'. Implementations are not required to
use this name, and can define their own instead. use this name, and can define their own instead.
* Registered device: a device registered at the Authorization * Registered device: a device registered at the Authorization
Server, i.e., as a Client, or a Resource Server, or both. A Server, i.e., as a Client, or a Resource Server, or both. A
registered device acts as caller of the TRL endpoint. registered device acts as a caller of the TRL endpoint.
* Administrator: entity authorized to get full access to the TRL at * Administrator: entity authorized to get full access to the TRL at
the Authorization Server, and acting as caller of the TRL the Authorization Server, and acting as a caller of the TRL
endpoint. An administrator is not necessarily a registered device endpoint. An administrator is not necessarily a registered device
as defined above, i.e., a Client requesting Access Tokens or a as defined above, i.e., a Client requesting Access Tokens or a
Resource Server consuming Access Tokens. How the administrator Resource Server consuming Access Tokens. How the administrator
authorization is established and verified is out of the scope of authorization is established and verified is out of the scope of
this specification. this specification.
* Pertaining Access Token: * Pertaining Access Token:
- With reference to an administrator, an Access Token issued by - With reference to an administrator, an Access Token issued by
the Authorization Server. the Authorization Server.
skipping to change at page 6, line 16 skipping to change at page 6, line 16
to be owned by that device. An Access Token pertains to a to be owned by that device. An Access Token pertains to a
Client if the Authorization Server has issued the Access Token Client if the Authorization Server has issued the Access Token
and provided it to that Client. An Access Token pertains to a and provided it to that Client. An Access Token pertains to a
Resource Server if the Authorization Server has issued the Resource Server if the Authorization Server has issued the
Access Token to be consumed by that Resource Server. Access Token to be consumed by that Resource Server.
2. Protocol Overview 2. Protocol Overview
This protocol defines how a CoAP-based Authorization Server informs This protocol defines how a CoAP-based Authorization Server informs
Clients and Resource Servers, i.e., registered devices, about Clients and Resource Servers, i.e., registered devices, about
pertaining revoked Access Tokens. How the relationship between the pertaining revoked Access Tokens. How the relationship between a
registered device and the Authorization Server is established is out registered device and the Authorization Server is established is out
of the scope of this specification. of the scope of 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.
* Upon startup, the Authorization Server creates a single TRL * Upon startup, the Authorization Server creates a single TRL
resource. At any point in time, the TRL resource represents the resource. At any point in time, the TRL resource represents the
list of all revoked Access Tokens issued by the Authorization list of all revoked Access Tokens issued by the Authorization
Server that are not expired yet. Server that are not expired yet.
* When a device registers at the Authorization Server, it receives * When a device registers at the Authorization Server, it also
the url-path to the TRL resource. receives the url-path to the TRL resource.
After the registration procedure is finished, the registered After the registration procedure is finished, the registered
device sends an Observation Request to that TRL resource as device can send an Observation Request to the TRL resource as
described in [RFC7641], i.e., a GET request with an Observe option described in [RFC7641], i.e., a GET request with an Observe option
set to 0 (register). By doing so, the registered device set to 0 (register). By doing so, the registered device
effectively subscribes to the TRL resource, as interested to effectively subscribes to the TRL resource, as interested to
receive notifications about its update. Upon receiving the receive notifications about its update. Upon receiving the
request, the Authorization Server adds the registered device to request, the Authorization Server adds the registered device to
the list of observers of the TRL resource. 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. When doing so, it can request for: the current list TRL endpoint. When doing so, it can request for: the current list
of pertaining revoked Access Tokens (see Section 5.1); or the most of pertaining revoked Access Tokens (see Section 6); or the most
recent TRL updates occurred over the list of pertaining revoked recent TRL updates occurred over the list of pertaining revoked
Access Tokens (see Section 5.2). In either case, the registered Access Tokens (see Section 7). In either case, the registered
device may especially rely on an Observation Request for device may especially rely on an Observation Request for
subscribing to the TRL resource as discussed above. subscribing to the TRL resource as discussed above.
* When an Access Token is revoked, the Authorization Server adds the * 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. corresponding token hash from the TRL.
In either case, after updating the TRL, the Authorization Server In either case, after updating the TRL, the Authorization Server
sends Observe Notifications as per [RFC7641]. That is, an Observe sends Observe Notifications as per [RFC7641]. That is, an Observe
Notification is sent to each registered device subscribed to the Notification is sent to each registered device subscribed to the
TRL resource and to which the Access Token pertains. TRL resource and to which the Access Token pertains.
Depending on the specific subscription established through the Depending on the specific subscription established through the
observation request, the notification provides the current updated observation request, the notification provides the current updated
list of revoked Access Tokens in the portion of the TRL pertaining list of revoked Access Tokens in the portion of the TRL pertaining
to that device (see Section 5.1), or rather the most recent TRL to that device (see Section 6), or rather the most recent TRL
updates occurred over that list of pertaining revoked Access updates occurred over that list of pertaining revoked Access
Tokens (see Section 5.2). Tokens (see Section 7).
Further Observe Notifications may be sent, consistently with Further Observe Notifications may be sent, consistently with
ongoing additional observations of the TRL resource. ongoing additional observations of the TRL resource.
* An administrator can access and subscribe to the TRL like a * An administrator can access and subscribe to the TRL like a
registered device, while getting the full updated representation registered device, while getting the full updated representation
of the TRL. of the TRL.
Figure 1 shows a high-level overview of the service provided by this Figure 1 shows a high-level overview of the service provided by this
protocol. In particular, it shows the Observe Notifications sent by protocol. In particular, it shows the Observe Notifications sent by
the Authorization Server to one administrator and four registered the Authorization Server to one administrator and four registered
devices, upon revocation of the issued Access Tokens t1, t2 and t3, devices, upon revocation of the issued Access Tokens t1, t2 and t3,
with token hash th1, th2 and th3, respectively. Each dotted line with token hash th1, th2 and th3, respectively. Each dotted line
associated to a pair of registered devices indicates the Access Token associated with a pair of registered devices indicates the Access
that they both own. Token that they both own.
+----------------------+ +----------------------+
| Authorization Server | | Authorization Server |
+-----------o----------+ +-----------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
skipping to change at page 8, line 5 skipping to change at page 8, line 5
| | | | | Server 1 | | | | Server 2 | | | | | | Server 1 | | | | Server 2 |
+---------------+ +----------+ +----------+ +----------+ +----------+ +---------------+ +----------+ +----------+ +----------+ +----------+
: : : : : : : : : : : :
: : t1 : : t3 : : : : t1 : : t3 : :
: :........: :............: : : :........: :............: :
: t2 : : t2 :
:...........................................: :...........................................:
Figure 1: Protocol Overview Figure 1: Protocol Overview
Section 8 provides examples of the protocol flow and message exchange Section 10 provides examples of the protocol flow and message
between the Authorization Server and a registered device. exchange between the Authorization Server and a registered device.
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.8.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 provided to the requesting Client. Access Token was included and provided to the requesting Client.
skipping to change at page 9, line 7 skipping to change at page 9, line 7
format is used as the token hash. Note that the used binary format is used as the token hash. Note that the used binary
format embeds the identifier of the used hash function, in the format embeds the identifier of the used hash function, in the
first byte of the computed token hash. first byte of the computed token hash.
The specifically used hash function MUST be collision-resistant The specifically used hash function MUST be collision-resistant
on byte-strings, and MUST be selected from the "Named Information on byte-strings, and MUST be selected from the "Named Information
Hash Algorithm" Registry [Named.Information.Hash.Algorithm]. Hash Algorithm" Registry [Named.Information.Hash.Algorithm].
The Authorization Server specifies the used hash function to The Authorization Server specifies the used hash function to
registered devices during their registration procedure (see registered devices during their registration procedure (see
Section 6). Section 8).
2.01 Created 2.01 Created
Content-Format: application/ace+cbor Content-Format: application/ace+cbor
Max-Age: 85800 Max-Age: 85800
Payload: Payload:
{ {
access_token : h'd08344a1...' access_token : h'd08344a1...'
(remainder of the Access Token omitted for brevity) (remainder of the Access Token omitted for brevity)
token_type : pop, token_type : pop,
expires_in : 86400, expires_in : 86400,
skipping to change at page 10, line 38 skipping to change at page 10, line 38
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 allows two types The TRL endpoint supports only the GET method, and allows two types
of query of the TRL. of query of the TRL.
* Full query: the Authorization Server returns the token hashes of * 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 Authorization Server MUST support this type of the requester. The Authorization Server MUST support this type of
query. The processing of a full query and the related response query. The processing of a full query and the related response
format are defined in Section 5.1. format are defined in Section 6.
* Diff query: the Authorization Server returns a list of diff * Diff query: the Authorization Server returns a list of diff
entries. Each diff entry is related to one of the most recent entries. Each diff entry is related to one of the most recent
updates, in the portion of the TRL pertaining to the requester. updates, in the portion of the TRL pertaining to the requester.
The Authorization Server MAY support this type of query. The Authorization Server MAY support this type of query.
The entry associated to one of such updates contains a list of The entry associated with one of such updates contains a list of
token hashes, such that: i) the corresponding revoked Access token hashes, such that: i) the corresponding revoked Access
Tokens pertain to the requester; and ii) they were added to or Tokens pertain to the requester; and ii) they were added to or
removed from the TRL at that update. The processing of a diff 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 7.
The TRL endpoint allows the following query parameter in a GET The TRL endpoint allows the following query parameters in a GET
request. request. The Authorization Server MUST silently ignore unknown query
parameters.
* 'pmax': if included, it follows the semantics defined in * 'pmax': if included, it follows the semantics defined in
Section 3.2.2 of [I-D.ietf-core-conditional-attributes]. This Section 3.2.2 of [I-D.ietf-core-conditional-attributes]. This
query parameter is relevant only in case the GET request is query parameter is relevant only in case the GET request is
specifically an Observation Request, i.e., if it includes the CoAP specifically an Observation Request, i.e., if it includes the CoAP
Observe option set to 0 (register). In such a case, this Observe option set to 0 (register). In such a case, this
parameter indicates the maximum time, in seconds, between two parameter indicates the maximum time, in seconds, between two
consecutive notifications for the observation in question, consecutive notifications for the observation in question,
regardless whether the TRL resource has changed or not. regardless whether the TRL resource has changed or not.
skipping to change at page 11, line 25 skipping to change at page 11, line 29
the maximum time to consider is up to the Authorization Server. the maximum time to consider is up to the Authorization Server.
If the Observation Request includes the 'pmax' parameter, its If the Observation Request includes the 'pmax' parameter, its
value MUST be greater than zero, otherwise the Authorization value MUST be greater than zero, otherwise the Authorization
Server MUST return a 4.00 (Bad Request) response. Server MUST return a 4.00 (Bad Request) response.
If the GET request is not an Observation Request, the If the GET request is not an Observation Request, the
Authorization Server MUST ignore the 'pmax' parameter, in case Authorization Server MUST ignore the 'pmax' parameter, in case
this is included. this is included.
* 'diff': if included, it indicates to perform a diff query of the * 'diff': if included, it indicates to perform a diff query of the
TRL. Its value MUST be either: TRL (see Section 7). Its value MUST be either:
- the integer 0, indicating that a (notification) response should - the integer 0, indicating that a (notification) response should
include as many diff entries as the Authorization Server can include as many diff entries as the Authorization Server can
provide in the response; or provide in the response; or
- a positive integer greater than 0, indicating the maximum - a positive integer greater than 0, indicating the maximum
number of diff entries that a (notification) response should number of diff entries that a (notification) response should
include. include.
5.1. Full Query of the TRL If the Authorization Server does not support diff queries, it
ignores the query parameter 'diff' when present in the GET request
and proceeds like when processing a full query of the TRL (see
Section 6).
6. 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:
* If the requester is a registered device, HASHES specifies the * If the requester is a registered device, HASHES specifies the
token hashes of the Access Tokens pertaining to that token hashes of the Access Tokens pertaining to that
registered device. The Authorization Server can use the registered device. The Authorization Server can use the
authenticated identity of the registered device to perform the authenticated identity of the registered device to perform the
necessary filtering on the TRL resource representation. necessary filtering on the TRL resource representation.
* If the requester is an administrator, HASHES specifies all the * If the requester is an administrator, HASHES specifies all the
token hashes in the current TRL resource representation. token hashes in the current TRL resource representation.
2. The Authorization Server sends a 2.05 (Content) Response to the 2. The Authorization Server sends a 2.05 (Content) Response to the
requester, with a CBOR array 'full' as payload. Each element of requester, with a CBOR array 'full-set' as payload. Each element
the array specifies one of the token hashes from the set HASHES, of the array specifies one of the token hashes from the set
encoded as a CBOR byte string. HASHES, encoded as a CBOR byte string.
The order of the token hashes in the CBOR array is irrelevant, 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 i.e., the CBOR array MUST be treated as a set in which the order
has no significant meaning. has no significant meaning.
The CDDL definition [RFC8610] of the CBOR array 'full' specified as The CDDL definition [RFC8610] of the CBOR array 'full-set' specified
payload in the response from the Authorization Server is provided as payload in the response from the Authorization Server is provided
below. below.
token-hash = bytes token-hash = bytes
full = [* token-hash] full-set = [* token-hash]
Figure 4: CDDL definition of the response payload following a Figure 4: CDDL definition of the response payload following a
Full Query request to the TRL endpoint Full Query request to the TRL endpoint
5.2. Diff Query of the TRL 7. Diff 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 diff query of the TRL, the Authorization Server performs the for a diff query of the TRL, the Authorization Server performs the
following actions. following actions.
1. The Authorization Server defines the positive integer NUM. If 1. The Authorization Server defines the positive integer NUM. If
the value N specified in the query parameter 'diff' of the GET the value N specified in the query parameter 'diff' in the GET
request is equal to 0 or greater than a pre-defined positive request is equal to 0 or greater than a pre-defined positive
integer N_MAX, then NUM takes the value of N_MAX. Otherwise, NUM integer N_MAX, then NUM takes the value of N_MAX. Otherwise, NUM
takes N. takes N.
2. The Authorization Server prepares U = min(NUM, SIZE) diff 2. The Authorization Server prepares U = min(NUM, SIZE) diff
entries, where SIZE <= N_MAX is the number of TRL updates entries, where SIZE <= N_MAX is the number of TRL updates
pertaining to the requester and currently stored at the pertaining to the requester and currently stored at the
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, with value the token hash 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 an Access Token such that: it pertained to the requester; and
it was removed from the TRL during the update associated to it was removed from the TRL during the update associated with
the diff 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, with value the token hash 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 an Access Token such that: it pertains to the requester; and
it was added to the TRL during the update associated to the it was added to the TRL during the update associated with the
diff 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-set' of U elements as
Each element of the CBOR array 'diff' specifies one of the CBOR payload. Each element of the CBOR array 'diff-set' specifies one
arrays 'diff-entry' prepared at step 2 as diff entries. of the CBOR arrays 'diff-entry' prepared at step 2 as diff
entries.
Within the CBOR array 'diff', the CBOR arrays 'diff-entry' MUST Within the CBOR array 'diff-set', the CBOR arrays 'diff-entry'
be sorted to reflect the corresponding updates to the TRL in MUST 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-set' relates to the most recent update to the
portion of the TRL pertaining to the requester. The second portion of the TRL pertaining to the requester. The second
'diff-entry' element of 'diff' relates to the second from last 'diff-entry' element of 'diff-set' relates to the second from
most recent update to that portion, and so on. last most recent update to that portion, and so on.
The CDDL definition [RFC8610] of the CBOR array 'diff' specified as The CDDL definition [RFC8610] of the CBOR array 'diff-set' specified
payload in the response from the Authorization Server is provided as payload in the response from the Authorization Server is provided
below. 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-set = [* diff-entry]
Figure 5: CDDL definition of the response payload following a Figure 5: CDDL definition of the response payload following a
Diff Query request to the TRL endpoint Diff Query request to the TRL endpoint
If the Authorization Server supports diff queries: If the Authorization Server supports diff queries:
* The Authorization Server MUST return a 4.00 (Bad Request) response * The Authorization Server MUST return a 4.00 (Bad Request) response
in case the 'diff' parameter specifies a value other than 0 or in case the query parameter 'diff' of the GET request specifies a
than a positive integer. value other than 0 or than a positive integer.
The response MUST have Content-Format "application/ace-trl+cbor".
The payload of the response is a CBOR map, which MUST include the
'error' field with value 0 ("Invalid parameter value") and MAY
include the 'error_description' field to provide additional
context.
* The Authorization Server MUST keep track of N_MAX most recent * 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.
* When SIZE is equal to N_MAX, and a new TRL update occurs as * 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.
* The Authorization Server SHOULD provide registered devices and * The Authorization Server SHOULD provide registered devices and
administrators with the value of N_MAX, upon their registration administrators with the value of N_MAX, upon their registration
(see Section 6). (see Section 8).
If the Authorization Server does not support diff queries, it
proceeds as when processing a full query (see Section 5.1).
Appendix A discusses how the diff query of the TRL is in fact a usage Appendix A discusses how performing a diff query of the TRL is in
example of the Series Transfer Pattern defined in fact a usage example of the Series Transfer Pattern defined in
[I-D.bormann-t2trg-stp]. [I-D.bormann-t2trg-stp].
Appendix B discusses how the diff query of the TRL can be further Appendix B discusses how the execution of a diff query of the TRL can
improved by using the "Cursor" pattern defined in Section 3.3 of be further improved by using the "Cursor" pattern defined in
[I-D.bormann-t2trg-stp]. Section 3.3 of [I-D.bormann-t2trg-stp].
6. Upon Registration 8. Upon Registration
During the registration process at the Authorization Server, an During the registration process at the Authorization Server, an
administrator or a registered device receives the following administrator or a registered device receives the following
information as part of the registration response. information as part of the registration response.
* The url-path to the TRL endpoint at the Authorization Server. * The url-path to the TRL endpoint at the Authorization Server.
* The hash function used to compute token hashes. This is specified * The hash function used to compute token hashes. This is specified
as an integer or a text string, taking value from the "ID" or as an integer or a text string, taking value from the "ID" or
"Hash Name String" column of the "Named Information Hash "Hash Name String" column of the "Named Information Hash
Algorithm" Registry [Named.Information.Hash.Algorithm], Algorithm" Registry [Named.Information.Hash.Algorithm],
respectively. respectively.
* Optionally, a positive integer N_MAX, if the Authorization Server * Optionally, a positive integer N_MAX, if the Authorization Server
supports diff queries of the TRL resource (see Section 5.2). supports diff queries of the TRL resource (see Section 7).
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 can send 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 6) or a diff query (see Section 7)
Section 5.2) of the TRL. of the TRL.
In case the request is successfully processed, The Authorization In case the request is successfully processed, the Authorization
Server replies using the CoAP response code 2.05 (Content) and Server replies with a response specifying the CoAP response code 2.05
including the CoAP Observe option in the response. The payload of (Content) and including the CoAP Observe option. The payload of the
the response is formatted as defined in Section 5.1 or in response is formatted as defined in Section 6 or in Section 7, in
Section 5.2, in case the GET request was for a full query or a diff case the GET yielded the execution of a full query or a diff query of
query of the TRL, respectively. the TRL, respectively.
Further details about the registration process at the Authorization Further details about the registration process at the Authorization
Server are out of scope for this specification. Note that the Server are out of scope for this specification. Note that the
registration process is also out of the scope of the ACE framework registration process is also out of the scope of the ACE framework
for Authentication and Authorization (see Section 5.5 of for Authentication and Authorization (see Section 5.5 of
[I-D.ietf-ace-oauth-authz]). [I-D.ietf-ace-oauth-authz]).
7. Notification of Revoked Tokens 9. Notification of Revoked Tokens
When the TRL is updated (see Section 4.1), the Authorization Server When the TRL is updated (see Section 4.1), the Authorization Server
sends Observe Notifications to the observers of the TRL resource. sends Observe Notifications to the observers of the TRL resource.
Observe Notifications are sent as per Section 4.2 of [RFC7641]. Observe Notifications are sent as per Section 4.2 of [RFC7641].
If the 'pmax' query parameter was specified in the Observation If the 'pmax' query parameter was specified in the Observation
Request starting an observation (see Section 5), the Authorization Request starting an observation (see Section 5), the Authorization
Server might accordingly send additional Observe Notifications to the Server might accordingly send additional Observe Notifications to the
associated observer. That is, the Authorization Server ensures that associated observer. That is, the Authorization Server ensures that
no more than pmax seconds elapse between two consecutive no more than pmax seconds elapse between two consecutive
notifications sent to that observer, regardless whether the TRL notifications sent to that observer, regardless whether the TRL
resource has changed or not. If the 'pmax' query parameter was not resource has changed or not. If the 'pmax' query parameter was not
specified in the Observation Request, a possible maximum time to specified in the Observation Request, a possible maximum time to
consider is up to the Authorization Server. consider is up to the Authorization Server.
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 6 or in Section 7, in case the original Observation Request
Request was for a full query or a diff query of the TRL, yielded the execution of 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
query (see Section 5.1) or a diff query (see Section 5.2). query (see Section 6) or a diff query (see Section 7).
8. Interaction Examples 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 H associated with a certain revoked Access
Token, 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 or
deliberately holding the Access Token back.
In such a case, the RS performs the following actions.
* The RS MUST store the token hash H, until gaining knowledge that
the associated revoked Access Token is also expired.
This can happen when receiving a subsequent response from the TRL
endpoint (i.e., indicating that the token hash is not in the TRL
portion pertaining to the RS anymore), or when the Access Token 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 posted
to the Authorization Information Endpoint, if the corresponding
token hash H is among the stored ones.
10. Interaction Examples
This section provides examples of interactions between a Resource This section provides examples of interactions between a Resource
Server RS as registered device and an Authorization Server AS. The Server RS as a registered device and an Authorization Server AS. The
Authorization Server supports both full query and diff query of the Authorization Server supports both full query and diff query of the
TRL, as defined in Section 5.1 and Section 5.2, respectively. TRL, as defined in Section 6 and Section 7, respectively.
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:
* a "trl" parameter, specifying the path of the TRL resource; * a "trl_path" parameter, specifying the path of the TRL resource;
* a "trl_hash" parameter, specifying the hash function used to * 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;
* an "n_max" parameter, specifying the value of N_MAX, i.e., the * 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 7);
* possible further parameters related to the registration process. * 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 10.1. Full Query with Observation
Figure 6 shows an interaction example considering a CoAP observation Figure 6 shows an interaction example considering a CoAP observation
and a full query of the TRL. and a 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_path" = "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 5 skipping to change at page 18, line 44
| | | |
| (Access Token t2 expires) | | (Access Token t2 expires) |
| | | |
|<--------------------------------------+ |<--------------------------------------+
| 2.05 CONTENT Observe: 86 | | 2.05 CONTENT Observe: 86 |
| Payload: [] | | Payload: [] |
| | | |
Figure 6: Interaction for Full Query with Observation Figure 6: Interaction for Full Query with Observation
8.2. Diff Query with Observation 10.2. Diff Query with Observation
Figure 7 shows an interaction example considering a CoAP observation Figure 7 shows an interaction example considering a CoAP observation
and a diff query of the TRL. and a 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 "diff", i.e., as the maximum number of diff entries to be specified
in a response from the Authorization Server. 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_path" = "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 19, line 47 skipping to change at page 20, line 38
| 2.05 CONTENT Observe: 86 | | 2.05 CONTENT Observe: 86 |
| Payload: [ | | Payload: [ |
| [ [bstr.h(t2)], [] ], | | [ [bstr.h(t2)], [] ], |
| [ [bstr.h(t1)], [] ], | | [ [bstr.h(t1)], [] ], |
| [ [], [bstr.h(t2)] ] | | [ [], [bstr.h(t2)] ] |
| ] | | ] |
| | | |
Figure 7: Interaction for Diff Query with Observation Figure 7: Interaction for Diff Query with Observation
8.3. Full Query with Observation and Additional Diff Query 10.3. Full Query with Observation and Additional Diff Query
Figure 8 shows an interaction example considering a CoAP observation Figure 8 shows an interaction example considering a CoAP observation
and a full query of the TRL. and a 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 Observe Option to the Authorization Server, to perform a diff
of the TRL. The Resource Server indicates N=8 as value of the query query of the TRL. The Resource Server indicates N=8 as value of the
parameter "diff", i.e., as the maximum number of diff entries to be query parameter "diff", i.e., as the maximum number of diff entries
specified in a response from the Authorization Server. 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_path" = "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 22, line 7 skipping to change at page 23, line 5
| Payload: [ | | Payload: [ |
| [ [bstr.h(t2)], [] ], | | [ [bstr.h(t2)], [] ], |
| [ [bstr.h(t1)], [] ], | | [ [bstr.h(t1)], [] ], |
| [ [], [bstr.h(t2)] ], | | [ [], [bstr.h(t2)] ], |
| [ [], [bstr.h(t1)] ] | | [ [], [bstr.h(t1)] ] |
| ] | | ] |
| | | |
Figure 8: Interaction for Full Query with Observation and Diff Query Figure 8: Interaction for Full Query with Observation and Diff Query
9. Security Considerations 11. 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 encoded as a CBOR map. Note that such a response MUST use
the Content-Format "application/ace-trl+cbor" defined in Section 14.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 | TBD | array |
| | | |
+-------------------+------------+-----------------------+
| cursor | TBD | simple value "null" / |
| | | unsigned integer |
+-------------------+------------+-----------------------+
| diff-set | TBD | array |
| | | |
+-------------------+------------+-----------------------+
| more | TBD | simple value "true" |
| | | or "false" |
+-------------------+------------+-----------------------+
| error | TBD | int |
| | | |
+-------------------+------------+-----------------------+
| error_description | TBD | tstr |
| | | |
+-------------------+------------+-----------------------+
Figure 9: CBOR abbreviations for the ACE Token Revocation List
parameters
12. 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 encoded as 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 |
+-------+---------------------------+
Figure 10: ACE Token Revocation List Error Identifiers
13. Security Considerations
Security considerations are inherited from the ACE framework for Security considerations are inherited from the ACE framework for
Authentication and Authorization [I-D.ietf-ace-oauth-authz], from Authentication and Authorization [I-D.ietf-ace-oauth-authz], from
[RFC8392] as to the usage of CWTs, from [RFC7519] as to the usage of [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 JWTs, from [RFC7641] as to the usage of CoAP Observe, and from
[RFC6920] with regard to resource naming through hashes. The [RFC6920] with regard to resource naming through hashes. The
following considerations also apply. following considerations also apply.
The Authorization Server MUST ensure that each registered device can The Authorization Server MUST ensure that each registered device can
access and retrieve only its pertaining portion of the TRL. To this access and retrieve only its pertaining portion of the TRL. To this
skipping to change at page 22, line 33 skipping to change at page 24, line 43
Disclosing any information about revoked Access Tokens to entities Disclosing any information about revoked Access Tokens to entities
other than the intended registered devices may result in privacy other than the intended registered devices may result in privacy
concerns. Therefore, the Authorization Server MUST ensure that, concerns. Therefore, the Authorization Server MUST ensure that,
other than registered devices accessing their own pertaining portion other than registered devices accessing their own pertaining portion
of the TRL, only authorized and authenticated administrators can of the TRL, only authorized and authenticated administrators can
retrieve the full TRL. To this end, the Authorization Server may retrieve the full TRL. To this end, the Authorization Server may
rely on an access control list or similar. rely on an access control list or similar.
If a registered device has many non-expired Access Tokens associated If a registered device has many non-expired Access Tokens associated
to itself that are revoked, the pertaining portion of the TRL could 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 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 handle upon reception, especially if relying on a full query of the
TRL resource (see Section 5.1). This could be exploited by attackers TRL resource (see Section 6). This could be exploited by attackers
to negatively affect the behavior of a registered device. Issuing to negatively affect the behavior of a registered device. Issuing
Access Tokens with not too long expiration time could help reduce the Access Tokens with not too long expiration time could help reduce the
size of a TRL, but an Authorization Server SHOULD take measures to size of a TRL, but an Authorization Server SHOULD take measures to
limit this size. limit this size.
Most of the communication about revoked Access Tokens presented in Most of the communication about revoked Access Tokens presented in
this specification relies on CoAP Observe Notifications sent from the this specification relies on CoAP Observe Notifications sent from the
Authorization Server to a registered device. The suppression of Authorization Server to a registered device. The suppression of
those notifications by an external attacker that has access to the those notifications by an external attacker that has access to the
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 a related application policy. the TRL endpoint according to a related application policy.
10. IANA Considerations 14. IANA Considerations
RFC EDITOR: Throughout this section, please replace [this document]
with the RFC number of this specification and remove this note.
This document has the following actions for IANA. This document has the following actions for IANA.
10.1. Media Type Registrations 14.1. Media Type Registrations
IANA is asked to register the 'application/ace-trl+cbor' media type IANA is asked to register the media type "application/ace-trl+cbor"
for messages of the protocols defined in this document encoded in for messages of the protocols defined in this document encoded in
CBOR. This registration follows the procedures specified in CBOR. This registration follows the procedures specified in
[RFC6838]. [RFC6838].
Type name: application Type name: application
Subtype name: ace-trl+cbor Subtype name: ace-trl+cbor
Required parameters: N/A Required parameters: N/A
Optional parameters: N/A Optional parameters: N/A
Encoding considerations: Must be encoded as CBOR map containing the Encoding considerations: Must be encoded as CBOR map containing the
protocol parameters defined in [this document]. protocol parameters defined in [this document].
Security considerations: See Section 9 of this document. Security considerations: See Section 13 of this document.
Interoperability considerations: N/A Interoperability considerations: N/A
Published specification: [this document] Published specification: [this document]
Applications that use this media type: The type is used by Applications that use this media type: The type is used by
Authorization Servers, Clients and Resource Servers that support the Authorization Servers, Clients and Resource Servers that support the
notification of revoked Access Tokens, according to a Token notification of revoked Access Tokens, according to a Token
Revocation List maintained by the Authorization Server as specified Revocation List maintained by the Authorization Server as specified
in [this document]. in [this document].
skipping to change at page 24, line 5 skipping to change at page 26, line 20
<iesg@ietf.org> <iesg@ietf.org>
Intended usage: COMMON Intended usage: COMMON
Restrictions on usage: None Restrictions on usage: None
Author: Marco Tiloca <marco.tiloca@ri.se> Author: Marco Tiloca <marco.tiloca@ri.se>
Change controller: IESG Change controller: IESG
10.2. CoAP Content-Formats Registry 14.2. CoAP Content-Formats Registry
IANA is asked to add the following entry to the "CoAP Content- IANA is asked to add the following entry to the "CoAP Content-
Formats" registry within the "CoRE Parameters" registry group. Formats" registry within the "CoRE Parameters" registry group.
Media Type: application/ace-trl+cbor Media Type: application/ace-trl+cbor
Encoding: - Encoding: -
ID: TBD ID: TBD
Reference: [this document] Reference: [this document]
10.3. Token Revocation List Registry 14.3. ACE Token Revocation List Parameters Registry
This specification establishes the "Token Revocation List" IANA This specification establishes the "ACE Token Revocation List
registry. The registry has been created to use the "Expert Review" Parameters" IANA registry. The registry has been created to use the
registration procedure [RFC8126]. Expert review guidelines are "Expert Review" registration procedure [RFC8126]. Expert review
provided in Section 10.4. It should be noted that, in addition to guidelines are provided in Section 14.5. It should be noted that, in
the expert review, some portions of the registry require a addition to the expert review, some portions of the registry require
specification, potentially a Standards Track RFC, to be supplied as a specification, potentially a Standards Track RFC, to be supplied as
well. well.
The columns of this registry are: The columns of this registry are:
* Name: This is a descriptive name that enables easier reference to * Name: This is a descriptive name that enables easier reference to
the item. The name MUST be unique. It is not used in the the item. The name MUST be unique. It is not used in the
encoding. encoding.
* CBOR Value: This is the value used as CBOR abbreviation of the * CBOR Value: This is the value used as CBOR abbreviation of the
item. These values MUST be unique. The value can be a positive item. These values MUST be unique. The value can be a positive
skipping to change at page 24, line 51 skipping to change at page 27, line 17
designated as Expert Review. Integer values less than -65536 are designated as Expert Review. Integer values less than -65536 are
marked as Private Use. marked as Private Use.
* CBOR Type: This contains the CBOR type of the item, or a pointer * CBOR Type: This contains the CBOR type of the item, or a pointer
to the registry that defines its type, when that depends on to the registry that defines its type, when that depends on
another item. another item.
* Reference: This contains a pointer to the public specification for * Reference: This contains a pointer to the public specification for
the item. the item.
This registry has been initially populated with the values from This registry has been initially populated by the values in
Figure 9 in Appendix B.4.4. Section 11. The Reference column for all of these entries refers to
this document.
10.4. Expert Review Instructions 14.4. ACE Token Revocation List Errors
The IANA registry established in this document is defined as expert This specification establishes the "ACE Token Revocation List Errors"
IANA registry. The registry has been created to use the "Expert
Review" registration procedure [RFC8126]. Expert review guidelines
are provided in Section 14.5. 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:
* Value: The value to be used to identify the error. The value MUST
be unique. The value can be a positive integer or a negative
integer. Integer values between 0 and 255 are designated as
Standards Track Document required. Integer values from 256 to
65535 are designated as Specification Required. Integer values
greater than 65535 are designated as expert review. Integer
values less than -65536 are marked as private use.
* Description: This field contains a brief description of the error.
* Reference: This field contains a pointer to the public
specification defining the error, if one exists.
This registry has been initially populated by the values in
Section 12. The Reference column for all of these entries refers to
this document.
14.5. Expert Review Instructions
The IANA registries established in this document is defined as expert
review. This section gives some general guidelines for what the review. This section gives some general guidelines for what the
experts should be looking for, but they are being designated as experts should be looking for, but they are being designated as
experts for a reason so they should be given substantial latitude. experts for a reason so they should be given substantial latitude.
Expert reviewers should take into consideration the following points: Expert reviewers should take into consideration the following points:
* Point squatting should be discouraged. Reviewers are encouraged * Point squatting should be discouraged. Reviewers are encouraged
to get sufficient information for registration requests to ensure to get sufficient information for registration requests to ensure
that the usage is not going to duplicate one that is already that the usage is not going to duplicate one that is already
registered and that the point is likely to be used in deployments. registered and that the point is likely to be used in deployments.
skipping to change at page 25, line 41 skipping to change at page 28, line 41
* Experts should take into account the expected usage of fields when * Experts should take into account the expected usage of fields when
approving point assignment. The fact that there is a range for approving point assignment. The fact that there is a range for
standards track documents does not mean that a standards track standards track documents does not mean that a standards track
document cannot have points assigned outside of that range. The document cannot have points assigned outside of that range. The
length of the encoded value should be weighed against how many 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 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 used on, and the number of code points left that encode to that
size. size.
11. References 15. References
11.1. Normative References 15.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)", Work in Progress, Internet-Draft, Framework (ACE-OAuth)", Work in Progress, Internet-Draft,
draft-ietf-ace-oauth-authz-46, 8 November 2021, draft-ietf-ace-oauth-authz-46, 8 November 2021,
<https://www.ietf.org/archive/id/draft-ietf-ace-oauth- <https://www.ietf.org/archive/id/draft-ietf-ace-oauth-
authz-46.txt>. authz-46.txt>.
[I-D.ietf-core-conditional-attributes]
Koster, M., Soloway, A., and B. Silverajan, "Conditional
Attributes for Constrained RESTful Environments", Work in
Progress, Internet-Draft, draft-ietf-core-conditional-
attributes-02, 24 February 2022,
<https://www.ietf.org/archive/id/draft-ietf-core-
conditional-attributes-02.txt>.
[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>.
skipping to change at page 27, line 25 skipping to change at page 30, line 34
Definition Language (CDDL): A Notational Convention to Definition Language (CDDL): A Notational Convention to
Express Concise Binary Object Representation (CBOR) and Express Concise Binary Object Representation (CBOR) and
JSON Data Structures", RFC 8610, DOI 10.17487/RFC8610, JSON Data Structures", RFC 8610, DOI 10.17487/RFC8610,
June 2019, <https://www.rfc-editor.org/info/rfc8610>. June 2019, <https://www.rfc-editor.org/info/rfc8610>.
[RFC8949] Bormann, C. and P. Hoffman, "Concise Binary Object [RFC8949] Bormann, C. and P. Hoffman, "Concise Binary Object
Representation (CBOR)", STD 94, RFC 8949, Representation (CBOR)", STD 94, RFC 8949,
DOI 10.17487/RFC8949, December 2020, DOI 10.17487/RFC8949, December 2020,
<https://www.rfc-editor.org/info/rfc8949>. <https://www.rfc-editor.org/info/rfc8949>.
11.2. Informative References 15.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)", Work in Progress, Internet-Draft, draft-bormann- (STP)", Work in Progress, Internet-Draft, draft-bormann-
t2trg-stp-03, 7 April 2020, t2trg-stp-03, 7 April 2020,
<https://www.ietf.org/archive/id/draft-bormann-t2trg-stp- <https://www.ietf.org/archive/id/draft-bormann-t2trg-stp-
03.txt>. 03.txt>.
[I-D.ietf-core-conditional-attributes]
Koster, M. and B. Silverajan, "Conditional Attributes for
Constrained RESTful Environments", Work in Progress,
Internet-Draft, draft-ietf-core-conditional-attributes-00,
12 July 2021, <https://www.ietf.org/archive/id/draft-ietf-
core-conditional-attributes-00.txt>.
[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>.
Appendix A. Usage of the Series Transfer Pattern Appendix A. On using the Series Transfer Pattern
This section discusses how the diff query of the TRL defined in Performing a diff query of the TRL as specified in Section 7 is a
Section 5.2 is a usage example of the Series Transfer Pattern defined usage example of the Series Transfer Pattern defined in
in [I-D.bormann-t2trg-stp]. [I-D.bormann-t2trg-stp].
A diff query enables the transfer of a series of TRL updates, with That is, a diff query enables the transfer of a series of TRL
the Authorization Server specifying U <= N_MAX diff entries as the U updates, with the Authorization Server specifying U <= N_MAX diff
most recent updates to the portion of the TRL pertaining to a entries as the U most recent updates to the portion of the TRL
registered device. pertaining to a registered device.
For each registered device, the Authorization Server maintains an For each registered device, the Authorization Server maintains an
update collection of maximum N_MAX items. Each time the TRL changes, update collection of maximum N_MAX items. Each time the TRL changes,
the Authorization Server performs the following operations for each the Authorization Server performs the following operations for each
registered device. registered device.
1. The Authorization Server considers the portion of the TRL 1. The Authorization Server considers the portion of the TRL
pertaining to that registered device. If the TRL portion is not pertaining to that registered device. If the TRL portion is not
affected by this TRL update, the Authorization Server stops the affected by this TRL update, the Authorization Server stops the
processing for that registered device. processing for that registered device.
skipping to change at page 28, line 30 skipping to change at page 31, line 30
2. Otherwise, the Authorization Server creates two sets 'trl_patch' 2. Otherwise, the Authorization Server creates two sets 'trl_patch'
of token hashes, i.e., one "removed" set and one "added" set, as of token hashes, i.e., one "removed" set and one "added" set, as
related to this TRL update. related to this TRL update.
3. The Authorization Server fills the two sets with the token hashes 3. The Authorization Server fills the two sets with the token hashes
of the removed and added Access Tokens, respectively, from/to the of the removed and added Access Tokens, respectively, from/to the
TRL portion from step 1. TRL portion from step 1.
4. The Authorization Server creates a new series item including the 4. The Authorization Server creates a new series item including the
two sets from step 3, and adds the series item to the update two sets from step 3, and adds the series item to the update
collection associated to the registered device. collection associated with the registered device.
When responding to a diff query request from a registered device (see When responding to a diff query request from a registered device (see
Section 5.2), 'diff' is a subset of the collection associated to the Section 7), 'diff-set' is a subset of the collection associated with
requester, where each 'diff_entry' record is a series item from that the requester, where each 'diff_entry' record is a series item from
collection. Note that 'diff' specifies the whole current collection that collection. Note that 'diff-set' specifies the whole current
when the value of U is equal to SIZE, i.e., the current number of collection when the value of U is equal to SIZE, i.e., the current
series items in the collection. number of series items in the collection.
The value N of the 'diff' query parameter in the diff query request The value N of the query parameter 'diff' in the GET request allows
allows the requester and the Authorization Server to trade the amount the requester and the Authorization Server to trade the amount of
of provided information with the latency of the information transfer. provided information with the latency of the information transfer.
Since the collection associated to each registered device includes up Since the collection associated with each registered device includes
to N_MAX series item, the Authorization Server deletes the oldest 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 series item when a new one is generated and added to the end of the
collection, due to a new TRL update pertaining to that registered collection, due to a new TRL update pertaining to that registered
device. This addresses the question "When can the server decide to device. This addresses the question "When can the server decide to
no longer retain older items?" in Section 3.2 of no longer retain older items?" in Section 3.2 of
[I-D.bormann-t2trg-stp]. [I-D.bormann-t2trg-stp].
Appendix B. Usage of the "Cursor" Pattern Appendix B. Usage of the "Cursor" Pattern
Building on Appendix A, this section describes how the diff query of This section defines how the execution of a diff query of the TRL
the TRL defined in Section 5.2 can be further improved by using the specified in Section 7 can be extended, by using the "Cursor" pattern
"Cursor" pattern of the Series Transfer Pattern (see Section 3.3 of of the Series Transfer Pattern (see Section 3.3 of
[I-D.bormann-t2trg-stp]). [I-D.bormann-t2trg-stp]).
[ TODO
Merge what is defined below into the document body.
* What is defined below for "Full Query Response" becomes part of
the full query processing in the document body. The successful
response payload is a CBOR map if the AS supports both the "Diff
Query" mode and the "Cursor" pattern, or just the CBOR array full-
set otherwise.
* The diff-query processing in the document body becomes as defined
below for "Diff Query Request" and "Diff Query Response". The
successful response payload is a CBOR map if the AS supports both
the "Diff Query" mode and the "Cursor" pattern, or just the CBOR
array diff-set otherwise.
* An example using also the "Cursor" pattern can be added in
"Interaction Examples".
]
This has two benefits. First, the Authorization Server can avoid This has two benefits. First, the Authorization Server can avoid
excessively big latencies when several diff entries have to be excessively big latencies when several diff entries have to be
transferred, by delivering one adjacent subset at the time, in transferred, by delivering one adjacent subset at the time, in
different diff query responses. Second, a requester can retrieve different diff query responses. Second, a requester can retrieve
diff entries associated to TRL updates that, even if not the most diff entries associated with TRL updates that, even if not the most
recent ones, occurred after a TRL update indicated as reference recent ones, occurred after a TRL update indicated as reference
point. point.
To this end, each series item in an update collection is also To this end, each series item X in an update collection is also
associated to 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 until and including
the first series item added to a collection has 'index' with value 0. X, minus 1. That is, the first series item added to a collection has
Then, the values of 'index' are used as cursor information. 'index' with value 0. Then, the values of 'index' are used as cursor
information.
Within an update collection, the unsigned integer LAST_INDEX denotes
the value of 'index' associated with the latest added series item,
i.e., the total number of series items added to the collection minus
1.
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 (see Section 6). MAX_DIFF_BATCH, upon their registration (see Section 8).
Finally, the full query and diff query exchanges defined in Finally, the full query and diff query exchanges defined in Section 6
Section 5.1 and Section 5.2 are extended as follows. and Section 7 are extended as follows.
In particular, successul responses from the TRL endpoint MUST use the In particular, successful responses from the TRL endpoint MUST use
Content-Format "application/ace-trl+cbor" defined in Section 10.2 of the Content-Format "application/ace-trl+cbor" defined in Section 14.2
this specification. 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 is defined in Section 6.
B.2. Full Query Response B.2. Full Query Response
When sending a 2.05 (Content) response to a full query request (see When sending a 2.05 (Content) response to a full query request (see
Appendix B.1), the response payload includes a CBOR map with the Appendix B.1), the response payload includes a CBOR map with the
following fields, whose CBOR labels are defined in Appendix B.4.4. following fields, whose CBOR labels are defined in Section 11.
* 'trl': this field MUST include a CBOR array of token hashes. The * 'full-set': this field MUST include a CBOR array of token hashes.
CBOR array is populated and formatted as defined for the CBOR The CBOR array is populated and formatted as defined for the CBOR
array 'full' in Section 5.1. array 'full-set' in Section 6.
* 'cursor': this field MUST include either the CBOR simple value * 'cursor': this field MUST include either the CBOR simple value
Null or a CBOR unsigned integer. "null" (0xf6) or a CBOR unsigned integer.
The CBOR simple value Null MUST be used to indicate that there are The CBOR simple value "null" MUST be used to indicate that there
currently no TRL updates pertinent to the requester, i.e., the are currently no TRL updates pertinent to the requester, i.e., the
update collection for that requester is empty. This is the case update collection for that requester is empty. This is the case
from when the requester registers at the Authorization Server from when the requester registers at the Authorization Server
until a first update pertaining that requester occurs to the TRL. until a first update pertaining that requester occurs to the TRL.
Otherwise, the field MUST include a CBOR unsigned integer, Otherwise, the field MUST include a CBOR unsigned integer,
encoding the 'index' value of the last series item in the encoding the 'index' value of the last series item in the
collection, as corresponding to the most recent update pertaining collection, as corresponding to the most recent update pertaining
to the requester occurred to the TRL. 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 7), 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.
The Authorization Server MUST return a 4.00 (Bad Request) response in
case the query parameter 'cursor' is present but the query parameter
'diff' is not present. The response MUST have Content-Format
"application/ace-trl+cbor". The payload of the response is a CBOR
map, which MUST include the 'error' field with value 1 ("Invalid set
of parameters") and MAY include the 'error_description' field to
provide additional context.
B.4. Diff Query Response B.4. Diff Query Response
The Authorization Server composes a response to a diff query request The Authorization Server composes a response to a diff query request
(see Appendix B.3) as follows, depending on the parameters specified (see Appendix B.3) as follows, depending on the parameters specified
in the request and on the current status of the update collection for in the request and on the current status of the update collection for
the requester. 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 with the requester has no elements, the
Authorization Server returns a 2.05 (Content) diff query response. Authorization Server returns a 2.05 (Content) diff query response.
The response payload includes a CBOR map with the following fields, The response payload includes a CBOR map with the following fields,
whose CBOR labels are defined in Appendix B.4.4. whose CBOR labels are defined in Section 11.
* 'diff': this field MUST include an empty CBOR array. * 'diff-set': this field MUST include an empty CBOR array.
* 'cursor': this field MUST include the CBOR simple value Null. * 'cursor': this field MUST include the CBOR simple value "null"
(0xf6).
* 'more': this fields MUST include the CBOR simple value False. * 'more': this field MUST include the CBOR simple value "false"
(0xf4).
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 with the requester is not empty
the diff query request does not include the query parameter 'cursor', and the diff query request does not include the query parameter
the Authorization Server returns a 2.05 (Content) diff query 'cursor', the Authorization Server returns a 2.05 (Content) diff
response. query response.
The response payload includes a CBOR map with the following fields, The response payload includes a CBOR map with the following fields,
whose CBOR labels are defined in Appendix B.4.4. whose CBOR labels are defined in Section 11.
* 'diff': this field MUST include a CBOR array, containing L = * 'diff-set': this field MUST include a CBOR array, containing L =
min(U, MAX_DIFF_BATCH) diff entries. In particular, the CBOR min(U, MAX_DIFF_BATCH) diff entries. In particular, the CBOR
array is populated as follows. 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 with 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 U series items in the collection associated to the last U series items in the collection associated with 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.
The 'diff' CBOR array as well as the individual diff entries have The 'diff-set' CBOR array as well as the individual diff entries
the same format specified in Figure 5 and used for the response have the same format specified in Figure 5 and used for the
payload defined in Section 5.2. response payload defined in Section 7.
* 'cursor': this field MUST include a CBOR unsigned integer. This * '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-set' CBOR array. That
it takes the 'index' value of the series item in the collection is, it takes the 'index' value of the series item in the
corresponding to the most recent update pertaining to the collection corresponding to the most recent update pertaining to
requester and returned in this diff query response. the 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.
* 'more': this field MUST include the CBOR simple value False if U * 'more': this field MUST include the CBOR simple value "false"
<= MAX_DIFF_BATCH, or the CBOR simple value True otherwise. (0xf4) if U <= MAX_DIFF_BATCH, or the CBOR simple value "true"
(0xf5) 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
query request including the query parameter 'cursor', with the diff query request including the query parameter 'cursor', with
same value of the 'cursor' field included in this diff query the same value of the 'cursor' field included in this diff query
response. As defined in Appendix B.4.3, this would result in the response. As defined in Appendix B.4.3, this would result in the
Authorization Server transferring the following subset of series Authorization Server transferring the following subset of series
items as diff entries, i.e., resuming from where interrupted in items as diff entries, i.e., resuming from where interrupted in
the previous transfer. 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 with the requester is not empty
the diff query request includes the query parameter 'cursor' with and 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.
* The Authorization Server MUST return a 4.00 (Bad Request) response * The Authorization Server MUST return a 4.00 (Bad Request) response
in case the 'cursor' parameter specifies a value other than 0 or in case the query parameter 'cursor' specifies a value other than
than a positive integer. 0 or than a positive integer.
* If no series item X with 'index' having value P is found in the The response MUST have Content-Format "application/ace-trl+cbor".
collection associated to the requester, then that item has been The payload of the response is a CBOR map, which MUST include the
previously removed from the history of updates for that requester 'error' field with value 0 ("Invalid parameter value") and MAY
(see Appendix A). In this case, the Authorization Server returns include the 'error_description' field to provide additional
a 2.05 (Content) diff query response. context.
* The Authorization Server MUST return a 4.00 (Bad Request) response
in case the 'cursor' parameter specifies a value strictly greater
than the current LAST_INDEX for the update collection associated
with the requester.
The response MUST have Content-Format "application/ace-trl+cbor".
The payload of the response is a CBOR map, which MUST include the
'error' field with value 2 ("Out of bound cursor value") and the
'cursor' field with value the current LAST_INDEX for the update
collection associated with the requester. The CBOR map MAY also
include the 'error_description' field to provide additional
context.
* The Authorization Server returns a 2.05 (Content) diff query
response formatted as follows, in case the series item X with
'index' having value P and the series item Y with 'index' having
value P+1 are both not found in the collection associated with the
requester. This occurs when the item Y (and possibly further ones
after it) has been previously removed from the history of updates
for that requester (see Appendix A).
The response payload includes a CBOR map with the following The response payload includes a CBOR map with the following
fields, whose CBOR labels are defined in Appendix B.4.4. fields, whose CBOR labels are defined in Section 11.
- 'diff': this field MUST include an empty CBOR array. - 'diff-set': this field MUST include an empty CBOR array.
- 'cursor': this field MUST include the CBOR simple value Null. - 'cursor': this field MUST include the CBOR simple value "null"
(0xf6).
- 'more': this field MUST include the CBOR simple value True. - 'more': this field MUST include the CBOR simple value "true"
(0xf5).
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 one or more series items have been lost
their removal, including the item with 'index' value P that the due to their removal. These include the item with 'index' value
requester wished to use as reference point. P+1, that the requester wished to obtain as the first one
following the specified reference point with 'index' value P.
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.
* If the series item X with 'index' having value P is found in the * The Authorization Server returns a 2.05 (Content) diff query
collection associated to the requester, the Authorization Server response formatted as follows, in case i) the series item X with
returns a 2.05 (Content) diff query response. 'index' having value P is found in the collection associated with
the requester; or ii) the series item X is not found and the
series item Y with 'index' having value P+1 is found in the
collection associated with the requester.
The response payload includes a CBOR map with the following The response payload includes a CBOR map with the following
fields, whose CBOR labels are defined in Appendix B.4.4. fields, whose CBOR labels are defined in Section 11.
- 'diff': this field MUST include a CBOR array, containing L = - 'diff-set': this field MUST include a CBOR array, containing L
min(SUB_U, MAX_DIFF_BATCH) diff entries, where SUB_U = min(NUM, = min(SUB_U, MAX_DIFF_BATCH) diff entries, where SUB_U =
SUB_SIZE), and SUB_SIZE is the number of series items in the min(NUM, SUB_SIZE), and SUB_SIZE is the number of series items
collection following the series item X. 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
reference point. In particular, the CBOR array is populated as reference point. In particular, the CBOR array is populated as
follows. follows.
o If SUB_U <= MAX_DIFF_BATCH, these diff entries are the last o 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 with the
corresponding to the L most recent TRL updates pertaining to requester, corresponding to the L most recent TRL updates
the requester. pertaining to the requester.
o If SUB_U > MAX_DIFF_BATCH, these diff entries are the eldest o If SUB_U > MAX_DIFF_BATCH, these diff entries are the eldest
of the last SUB_U series items in the collection associated of the last SUB_U series items in the collection associated
to the requester, corresponding to the first L of the SUB_U with the requester, corresponding to the first L of the
most recent TRL updates pertaining to the requester. SUB_U most recent TRL updates pertaining to the requester.
The 'diff' CBOR array as well as the individual diff entries The 'diff-set' CBOR array as well as the individual diff
have the same format specified in Figure 5 and used for the entries have the same format specified in Figure 5 and used for
response payload defined in Section 5.2. the response payload defined in Section 7.
- 'cursor': this field MUST include a CBOR unsigned integer. In - 'cursor': this field MUST include a CBOR unsigned integer. In
particular: particular:
o If L is equal to 0, i.e., the series item X is the last one o If L is equal to 0, i.e., the series item X is the last one
in the collection, 'cursor' takes the same 'index' value of in the collection, 'cursor' takes the same 'index' value of
the last series item in the collection. the last series item in the collection.
o If L is different than 0, 'cursor' takes the 'index' value o If L is different than 0, 'cursor' takes the 'index' value
of the series element of the collection included as first of the series element of the collection included as first
diff entry in the 'diff' CBOR array. That is, it takes the diff entry in the 'diff-set' CBOR array. That is, it takes
'index' value of the series item in the collection 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 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.
- 'more': this field MUST include the CBOR simple value False if - 'more': this field MUST include the CBOR simple value "false"
SUB_U <= MAX_DIFF_BATCH, or the CBOR simple value True (0xf4) if SUB_U <= MAX_DIFF_BATCH, or the CBOR simple value
otherwise. "true" (0xf5) 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' field 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
transferring the following subset of series items as diff transferring 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 Appendix C. Document Updates
This specification defines a number of fields used in the response to RFC EDITOR: Please remove this section.
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 value to use C.1. Version -00 to -01
as abbreviation 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.
+--------+------------+---------------------+-----------+ * Added actions to perform upon receiving responses from the TRL
| Name | CBOR Value | CBOR Type | Reference | endpoint.
+--------+------------+---------------------+-----------+
| 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] |
+--------+------------+---------------------+-----------+
Figure 9: CBOR abbreviations for TRL parameters * Fixed off-by-one error when using the "Cursor" pattern.
* Improved error handling, with registered error codes.
* Section restructuring (full- and diff-query as self-standing
sections).
* Renamed identifiers and CBOR parameters.
* Clarifications and editorial improvements.
Acknowledgments Acknowledgments
The authors sincerely thank Carsten Bormann, Benjamin Kaduk, Michael The authors sincerely thank Carsten Bormann, Benjamin Kaduk, Marco
Richardson, Jim Schaad, Goeran Selander and Travis Spencer for their Rasori, Michael Richardson, Jim Schaad, Goeran Selander and Travis
comments and feedback. Spencer for their comments and 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).
Authors' Addresses Authors' Addresses
Marco Tiloca Marco Tiloca
RISE AB RISE AB
Isafjordsgatan 22 Isafjordsgatan 22
SE-16440 Kista SE-16440 Kista
Sweden Sweden
Email: marco.tiloca@ri.se Email: marco.tiloca@ri.se
Ludwig Seitz Ludwig Seitz
Combitech Combitech
Djaeknegatan 31 Djaeknegatan 31
SE-21135 Malmoe SE-21135 Malmoe
Sweden Sweden
Email: ludwig.seitz@combitech.com Email: ludwig.seitz@combitech.com
Francesca Palombini Francesca Palombini
Ericsson AB Ericsson AB
Torshamnsgatan 23 Torshamnsgatan 23
SE-16440 Kista SE-16440 Kista
Sweden Sweden
Email: francesca.palombini@ericsson.com Email: francesca.palombini@ericsson.com
Sebastian Echeverria Sebastian Echeverria
CMU SEI CMU SEI
4500 Fifth Avenue 4500 Fifth Avenue
Pittsburgh, PA, 15213-2612 Pittsburgh, PA, 15213-2612
United States of America United States of America
Email: secheverria@sei.cmu.edu Email: secheverria@sei.cmu.edu
Grace Lewis Grace Lewis
CMU SEI CMU SEI
4500 Fifth Avenue 4500 Fifth Avenue
Pittsburgh, PA, 15213-2612 Pittsburgh, PA, 15213-2612
United States of America United States of America
Email: glewis@sei.cmu.edu Email: glewis@sei.cmu.edu
 End of changes. 155 change blocks. 
329 lines changed or deleted 513 lines changed or added

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