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