rfc9770.original   rfc9770.txt 
ACE Working Group M. Tiloca Internet Engineering Task Force (IETF) M. Tiloca
Internet-Draft RISE AB Request for Comments: 9770 RISE AB
Intended status: Standards Track F. Palombini Category: Standards Track F. Palombini
Expires: 26 March 2025 Ericsson AB ISSN: 2070-1721 Ericsson AB
S. Echeverria S. Echeverria
G. Lewis G. Lewis
CMU SEI CMU SEI
22 September 2024 June 2025
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-09
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. As specified (i.e., registered devices) about revoked access tokens. As specified
in this document, the method allows clients and resource servers to in this document, the method allows clients and resource servers
access a Token Revocation List on the authorization server by using (RSs) to access a Token Revocation List (TRL) on the authorization
the Constrained Application Protocol (CoAP), with the possible server by using the Constrained Application Protocol (CoAP), with the
additional use of resource observation. Resulting (unsolicited) possible additional use of resource observation. Resulting
notifications of revoked access tokens complement alternative (unsolicited) notifications of revoked access tokens complement
approaches such as token introspection, while not requiring alternative approaches such as token introspection, while not
additional endpoints on clients and resource servers. requiring additional endpoints on clients and RSs.
Discussion Venues
This note is to be removed before publishing as an RFC.
Discussion of this document takes place on the Authentication and
Authorization for Constrained Environments Working Group mailing list
(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
https://github.com/ace-wg/ace-revoked-token-notification.
Status of This Memo Status of This Memo
This Internet-Draft is submitted in full conformance with the This is an Internet Standards Track document.
provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet-
Drafts is at https://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months This document is a product of the Internet Engineering Task Force
and may be updated, replaced, or obsoleted by other documents at any (IETF). It represents the consensus of the IETF community. It has
time. It is inappropriate to use Internet-Drafts as reference received public review and has been approved for publication by the
material or to cite them other than as "work in progress." Internet Engineering Steering Group (IESG). Further information on
Internet Standards is available in Section 2 of RFC 7841.
This Internet-Draft will expire on 26 March 2025. Information about the current status of this document, any errata,
and how to provide feedback on it may be obtained at
https://www.rfc-editor.org/info/rfc9770.
Copyright Notice Copyright Notice
Copyright (c) 2024 IETF Trust and the persons identified as the Copyright (c) 2025 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
license-info) in effect on the date of publication of this document. (https://trustee.ietf.org/license-info) in effect on the date of
Please review these documents carefully, as they describe your rights publication of this document. Please review these documents
and restrictions with respect to this document. Code Components carefully, as they describe your rights and restrictions with respect
extracted from this document must include Revised BSD License text as to this document. Code Components extracted from this document must
described in Section 4.e of the Trust Legal Provisions and are include Revised BSD License text as described in Section 4.e of the
provided without warranty as described in the Revised BSD License. Trust Legal Provisions and are provided without warranty as described
in the Revised BSD License.
Table of Contents Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 4 1. Introduction
1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 5 1.1. Terminology
2. Protocol Overview . . . . . . . . . . . . . . . . . . . . . . 7 2. Protocol Overview
3. Issuing of Access Tokens at the AS . . . . . . . . . . . . . 9 3. Issuing of Access Tokens at the AS
4. Token Hash . . . . . . . . . . . . . . . . . . . . . . . . . 11 4. Token Hash
4.1. Motivation for the Used Construction . . . . . . . . . . 12 4.1. Motivation for the Used Construction
4.1.1. Issuing of the Access Token to the Client . . . . . . 12 4.1.1. Issuing of the Access Token to the Client
4.1.2. Provisioning of Access Tokens to the RS . . . . . . . 13 4.1.2. Provisioning of Access Tokens to the RS
4.1.3. Design Rationale . . . . . . . . . . . . . . . . . . 14 4.1.3. Design Rationale
4.2. Hash Input on the Client and the AS . . . . . . . . . . . 14 4.2. Hash Input on the Client and the AS
4.2.1. AS-to-Client Response Encoded in CBOR . . . . . . . . 15 4.2.1. AS-to-Client Response Encoded in CBOR
4.2.2. AS-to-Client Response Encoded in JSON . . . . . . . . 15 4.2.2. AS-to-Client Response Encoded in JSON
4.3. HASH_INPUT on the RS . . . . . . . . . . . . . . . . . . 17 4.3. HASH_INPUT on the RS
4.3.1. Access Tokens as CWTs . . . . . . . . . . . . . . . . 17 4.3.1. Access Tokens as CWTs
4.3.2. Access Tokens as JWTs . . . . . . . . . . . . . . . . 18 4.3.2. Access Tokens as JWTs
4.4. Computing the Token Hash . . . . . . . . . . . . . . . . 19 4.4. Computing the Token Hash
5. Token Revocation List (TRL) . . . . . . . . . . . . . . . . . 19 5. Token Revocation List (TRL)
5.1. Update of the TRL . . . . . . . . . . . . . . . . . . . . 20 5.1. Update of the TRL
6. The TRL Endpoint . . . . . . . . . . . . . . . . . . . . . . 20 6. The TRL Endpoint
6.1. Error Responses with Problem Details . . . . . . . . . . 21 6.1. Error Responses with Problem Details
6.2. Supporting Diff Queries . . . . . . . . . . . . . . . . . 23 6.2. Supporting Diff Queries
6.2.1. Supporting the "Cursor" Extension . . . . . . . . . . 24 6.2.1. Supporting the "Cursor" Extension
6.3. Query Parameters . . . . . . . . . . . . . . . . . . . . 25 6.3. Query Parameters
7. Full Query of the TRL . . . . . . . . . . . . . . . . . . . . 27 7. Full Query of the TRL
8. Diff Query of the TRL . . . . . . . . . . . . . . . . . . . . 29 8. Diff Query of the TRL
9. Response Messages when Using the "Cursor" Extension . . . . . 32 9. Response Messages when Using the "Cursor" Extension
9.1. Response to Full Query . . . . . . . . . . . . . . . . . 32 9.1. Response to Full Query
9.2. Response to Diff Query . . . . . . . . . . . . . . . . . 32 9.2. Response to Diff Query
9.2.1. Empty Collection . . . . . . . . . . . . . . . . . . 33 9.2.1. Empty Update Collection
9.2.2. Cursor Not Specified in the Diff Query Request . . . 33 9.2.2. Cursor Not Included in the Diff Query Request
9.2.3. Cursor Specified in the Diff Query Request . . . . . 34 9.2.3. Cursor Included in the Diff Query Request
10. Registration at the Authorization Server . . . . . . . . . . 37 10. Registration at the Authorization Server
11. Notification of Revoked Access Tokens . . . . . . . . . . . . 38 11. Notification of Revoked Access Tokens
11.1. Handling of Revoked Access Tokens and Token Hashes . . . 40 11.1. Handling of Revoked Access Tokens and Token Hashes
12. ACE Token Revocation List Parameters . . . . . . . . . . . . 42 12. ACE Token Revocation List Parameters
13. ACE Token Revocation List Error Identifiers . . . . . . . . . 43 13. ACE Token Revocation List Error Identifiers
14. Security Considerations . . . . . . . . . . . . . . . . . . . 43 14. Security Considerations
14.1. Content Retrieval from the TRL . . . . . . . . . . . . . 43 14.1. Content Retrieval from the TRL
14.2. Size of the TRL . . . . . . . . . . . . . . . . . . . . 44 14.2. Size of the TRL
14.3. Communication Patterns . . . . . . . . . . . . . . . . . 44 14.3. Communication Patterns
14.4. Request of New Access Tokens . . . . . . . . . . . . . . 45 14.4. Request of New Access Tokens
14.5. Vulnerable Time Window at the RS . . . . . . . . . . . . 45 14.5. Vulnerable Time Window at the RS
14.6. Preventing Unnoticed Manipulation of Access Tokens . . . 46 14.6. Preventing Unnoticed Manipulation of Access Tokens
14.7. Two Token Hashes at the RS using JWTs . . . . . . . . . 47 14.7. Two Token Hashes at the RS Using JWTs
14.8. Additional Security Measures . . . . . . . . . . . . . . 48 14.8. Additional Security Measures
15. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 48 15. IANA Considerations
15.1. Media Type Registrations . . . . . . . . . . . . . . . . 48 15.1. Media Type Registrations
15.2. CoAP Content-Formats Registry . . . . . . . . . . . . . 49 15.2. CoAP Content-Formats Registry
15.3. Custom Problem Detail Keys Registry . . . . . . . . . . 50 15.3. Custom Problem Detail Keys Registry
15.4. ACE Token Revocation List Parameters Registry . . . . . 50 15.4. ACE Token Revocation List Parameters Registry
15.5. ACE Token Revocation List Errors . . . . . . . . . . . . 51 15.5. ACE Token Revocation List Errors
15.6. Expert Review Instructions . . . . . . . . . . . . . . . 52 15.6. Expert Review Instructions
16. References . . . . . . . . . . . . . . . . . . . . . . . . . 53 16. References
16.1. Normative References . . . . . . . . . . . . . . . . . . 53 16.1. Normative References
16.2. Informative References . . . . . . . . . . . . . . . . . 56 16.2. Informative References
Appendix A. On using the Series Transfer Pattern . . . . . . . . 57 Appendix A. On Using the Series Transfer Pattern
Appendix B. Local Supportive Parameters of the TRL Endpoint . . 58 Appendix B. Local Supportive Parameters of the TRL Endpoint
Appendix C. Interaction Examples . . . . . . . . . . . . . . . . 59 Appendix C. Interaction Examples
C.1. Full Query with Observe . . . . . . . . . . . . . . . . . 60 C.1. Full Query with Observe
C.2. Diff Query with Observe . . . . . . . . . . . . . . . . . 62 C.2. Diff Query with Observe
C.3. Full Query with Observe plus Diff Query . . . . . . . . . 64 C.3. Full Query with Observe and Diff Query
C.4. Diff Query with Observe and "Cursor" . . . . . . . . . . 67 C.4. Diff Query with Observe and "Cursor" Extension
C.5. Full Query with Observe plus Diff Query with "Cursor" . . 70 C.5. Full Query with Observe and Diff Query with "Cursor"
Appendix D. CDDL Model . . . . . . . . . . . . . . . . . . . . . 76 Extension
Appendix E. Document Updates . . . . . . . . . . . . . . . . . . 76 Acknowledgments
E.1. Version -08 to -09 . . . . . . . . . . . . . . . . . . . 76 Authors' Addresses
E.2. Version -07 to -08 . . . . . . . . . . . . . . . . . . . 77
E.3. Version -06 to -07 . . . . . . . . . . . . . . . . . . . 78
E.4. Version -05 to -06 . . . . . . . . . . . . . . . . . . . 79
E.5. Version -04 to -05 . . . . . . . . . . . . . . . . . . . 79
E.6. Version -03 to -04 . . . . . . . . . . . . . . . . . . . 79
E.7. Version -02 to -03 . . . . . . . . . . . . . . . . . . . 80
E.8. Version -01 to -02 . . . . . . . . . . . . . . . . . . . 80
E.9. Version -00 to -01 . . . . . . . . . . . . . . . . . . . 80
Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . 81
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 81
1. Introduction 1. Introduction
Authentication and Authorization for Constrained Environments (ACE) Authentication and Authorization for Constrained Environments (ACE)
[RFC9200] is a framework that enforces access control on IoT devices [RFC9200] is a framework that enforces access control on Internet of
acting as resource servers (RSs). In order to use ACE, both clients Things (IoT) devices acting as resource servers (RSs). In order to
and RSs have to register with an authorization server (AS) and become use ACE, both clients and RSs have to register with an authorization
a registered device. Once registered, a client can send a request to server (AS) and become registered devices. Once registered, a client
the AS, to obtain an access token for an RS. For a client to access can send a request to the AS to obtain an access token for an RS.
the RS, the client must present the issued access token at the RS, For a client to access the RS, the client must present the issued
which then validates it before storing it (see Section 5.10.1.1 of access token at the RS, which then validates it before storing it
[RFC9200]). (see Section 5.10.1.1 of [RFC9200]).
Even though access tokens have expiration times, there are Even though access tokens have expiration times, there are
circumstances by which an access token may need to be revoked before circumstances by which an access token may need to be revoked before
its expiration time, such as: (1) a registered device has been its expiration time, such as when:
compromised, or is suspected of being compromised; (2) a registered
device is decommissioned; (3) there has been a change in the ACE 1. a registered device has been compromised or is suspected of being
profile for a registered device; (4) there has been a change in compromised;
access policies for a registered device; and (5) there has been a
change in the outcome of policy evaluation for a registered device 2. a registered device is decommissioned;
(e.g., if policy assessment depends on dynamic conditions in the
execution environment, the user context, or the resource 3. there has been a change in the ACE profile for a registered
utilization). device;
4. there has been a change in access policies for a registered
device; or
5. there has been a change in the outcome of policy evaluation for a
registered device (e.g., if policy assessment depends on dynamic
conditions in the execution environment, the user context, or the
resource utilization).
As discussed in Section 6.1 of [RFC9200], only client-initiated As discussed in Section 6.1 of [RFC9200], only client-initiated
revocation is currently specified [RFC7009] for OAuth 2.0 [RFC6749], revocation is currently specified [RFC7009] for OAuth 2.0 [RFC6749],
based on the assumption that access tokens in OAuth are issued with a based on the assumption that access tokens in OAuth are issued with a
relatively short lifetime. However, this is not expected to be the relatively short lifetime. However, this is not expected to be the
case for constrained, intermittently connected devices, that need case for constrained, intermittently connected devices that need
access tokens with relatively long lifetimes. 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) on the access and possibly subscribe to a Token Revocation List (TRL) on the
AS, in order to obtain updated information about pertaining access AS in order to obtain updated information about pertaining access
tokens that were revoked prior to their expiration. As specified in tokens that were revoked prior to their expiration. As specified in
this document, the registered devices use the Constrained Application this document, the registered devices use the Constrained Application
Protocol (CoAP) [RFC7252] to communicate with the AS and with one Protocol (CoAP) [RFC7252] to communicate with the AS and with one
another, and can subscribe to the TRL on the AS by using resource another and can subscribe to the TRL on the AS by using resource
observation for CoAP [RFC7641]. Other underlying protocols than CoAP observation for CoAP [RFC7641]. Underlying protocols other than CoAP
are not prohibited from being supported in the future, if they are are not prohibited from being supported in the future, if they are
defined to be used in the ACE framework for Authentication and defined to be used in the ACE framework.
Authorization.
Unlike in the case of token introspection (see Section 5.9 of Unlike in the case of token introspection (see Section 5.9 of
[RFC9200]), a registered device does not provide an owned access [RFC9200]), a registered device does not provide an owned access
token to the AS for inquiring about its current state. Instead, token to the AS for inquiring about its current state. Instead,
registered devices simply obtain updated information about pertaining registered devices simply obtain updated information about pertaining
access tokens that were revoked prior to their expiration, as access tokens that were revoked prior to their expiration as
efficiently identified by corresponding hash values. efficiently identified by corresponding hash values.
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 the registered devices to introspection and does not require the registered devices to support
support any additional endpoints (see Section 1.1). The only any additional endpoints (see Section 1.1). The only additional
additional requirements for registered devices are a request/response requirements for registered devices are a request/response
interaction with the AS to access and possibly subscribe to the TRL interaction with the AS to access and possibly subscribe to the TRL
(see Section 2), and the lightweight computation of hash values to (see Section 2) and the lightweight computation of hash values to use
use as access token identifiers (see Section 4). as access token identifiers (see Section 4).
The process by which access tokens are declared revoked is out of the The process by which access tokens are declared revoked is out of the
scope of this document. It is also out of scope the method by which scope of this document. The method by which the AS determines or is
the AS determines or is notified of revoked access tokens, according notified of revoked access tokens, according to which the AS
to which the AS consequently updates the TRL as specified in this consequently updates the TRL as specified in this document, is also
document. out of scope.
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 "OPTIONAL" in this document are to be interpreted as described in BCP
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
described in the ACE framework for Authentication and Authorization described in the ACE framework [RFC9200], as well as with terms and
[RFC9200], as well as with terms and concepts related to CBOR Web concepts related to CBOR Web Tokens (CWTs) [RFC8392] and JSON Web
Tokens (CWTs) [RFC8392] and JSON Web Tokens (JWTs) [RFC7519]. Tokens (JWTs) [RFC7519].
The terminology for entities in the considered architecture is The terminology for entities in the considered architecture is
defined in OAuth 2.0 [RFC6749]. In particular, this includes client, defined in OAuth 2.0 [RFC6749]. In particular, this includes client,
resource server (RS), and authorization server (AS). RS, and authorization server (AS).
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 CDDL [RFC8610], CBOR [RFC8949], JSON [RFC8259], COSE related to the Concise Data Definition Language (CDDL) [RFC8610],
[RFC9052], CoAP [RFC7252], CoAP Observe [RFC7641], and the use of Concise Binary Object Representation (CBOR) [RFC8949], JSON
hash functions to name objects as defined in [RFC6920]. [RFC8259], CBOR Object Signing and Encryption (COSE) [RFC9052], CoAP
[RFC7252], CoAP Observe [RFC7641], and the use of hash functions to
name objects as defined in [RFC6920].
Note that the term "endpoint" is used here following its OAuth Note that the term "endpoint" is used here following its OAuth
definition [RFC6749], aimed at denoting resources such as /token and definition [RFC6749], aimed at denoting resources such as /token and
/introspect at the AS, and /authz-info at the RS. This document does /introspect at the AS, and /authz-info at the RS. The CoAP
not use the CoAP definition of "endpoint", which is "An entity definition, which is "[a]n entity participating in the CoAP protocol"
participating in the CoAP protocol." [RFC7252], is not used in this document.
This specification also refers to the following terminology. This specification also uses 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 access token encoding. The token hash has no relation to other access token
identifiers possibly used, such as the 'cti' (CWT ID) claim of identifiers possibly used, such as the 'cti' (CWT ID) claim of
CBOR Web Tokens (CWTs) [RFC8392]. CBOR Web Tokens (CWTs) [RFC8392].
* Token Revocation List (TRL): a collection of token hashes such Token Revocation List (TRL): a collection of token hashes such that
that the corresponding access tokens have been revoked but are not the corresponding access tokens have been revoked but are not
expired yet. expired yet.
* TRL endpoint: an endpoint at the AS with a TRL as its TRL endpoint: an endpoint at the AS with a TRL as its
representation. The default name of the TRL endpoint in a url- representation. The default name of the TRL endpoint in a url-
path is '/revoke/trl'. Implementations are not required to use path is '/revoke/trl'. Implementations are not required to use
this name, and can define their own instead. this name and can define their own instead.
* Registered device: a device registered at the AS, i.e., as a Registered device: a device registered at the AS, i.e., as a client,
client, or an RS, or both. A registered device acts as a an RS, or both. A registered device acts as a requester towards
requester towards the TRL endpoint. the TRL endpoint.
* Administrator: entity authorized to get full access to the TRL at Administrator: an entity that is authorized to get full access to
the AS, and acting as a requester towards the TRL endpoint. An the TRL at the AS and that acts as a requester towards the TRL
administrator is not necessarily a registered device as defined endpoint. An administrator is not necessarily a registered device
above, i.e., a client requesting access tokens or an RS consuming as defined above, i.e., a client requesting access tokens or an RS
access tokens. consuming access tokens.
An administrator might also be authorized to perform further An administrator might also be authorized to perform further
administrative operations at the AS, e.g., through a dedicated administrative operations at the AS, e.g., through a dedicated
admin interface that is out of the scope of this document. By admin interface that is out of the scope of this document. By
considering the token hashes retrieved from the TRL together with considering the token hashes retrieved from the TRL together with
other information obtained from the AS, the administrator becomes other information obtained from the AS, the administrator becomes
able to derive additional information, e.g., the fact that able to derive additional information, e.g., the fact that
accesses have been revoked for specific registered devices. accesses have been revoked for specific registered devices.
* 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 AS. the AS.
- With reference to a registered device, an access token intended * With reference to a registered device, an access token intended
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 AS has issued the access token for that client client if the AS has issued the access token for that client
following its request. An access token pertains to an RS if following its request. An access token pertains to an RS if
the AS has issued the access token to be consumed by that RS. the AS has issued the access token to be consumed by that RS.
* Token hash pertaining to a requester: a token hash corresponding Token hash pertaining to a requester: a token hash corresponding to
to an access token pertaining to that requester, i.e., an an access token pertaining to that requester, i.e., an
administrator or a registered device. administrator or a registered device.
* TRL update pertaining to a requester: an update to the TRL through TRL update pertaining to a requester: an update to the TRL through
which token hashes pertaining to that requester have been added to which token hashes pertaining to that requester have been added to
the TRL or removed from the TRL. or removed from the TRL.
* Full query: a type of query to the TRL, where the AS returns the Full query: a type of query to the TRL where the AS returns the
token hashes of the revoked access tokens currently in the TRL and token hashes of the revoked access tokens currently in the TRL and
pertaining to the requester. Further details are specified in pertaining to the requester. Further details are specified in
Section 6 and Section 7. Sections 6 and 7.
* Diff query: a type of query to the TRL, where the AS returns a Diff query: a type of query to the TRL where the AS returns a list
list of diff entries, each related to one update occurred to the of diff entries, each related to one update that occurred to the
TRL and containing a set of token hashes pertaining to the TRL and containing a set of token hashes pertaining to the
requester. Further details are specified in Section 6 and requester. Further details are specified in Sections 6 and 8.
Section 8.
See Section 4 for further terminology used throughout that section.
Examples throughout this document are expressed in CBOR diagnostic Examples throughout this document are expressed in CBOR diagnostic
notation as defined in Section 8 of [RFC8949] and Appendix G of notation as defined in Section 8 of [RFC8949] and Appendix G of
[RFC8610]. Diagnostic notation comments are often used to provide a [RFC8610]. Diagnostic notation comments are often used to provide a
textual representation of the numeric parameter names and values. textual representation of the numeric parameter names and values.
In the CBOR diagnostic notation used in this document, constructs of
the form e'SOME_NAME' are replaced by the value assigned to SOME_NAME
in the CDDL model shown in Figure 15 of Appendix D. For example,
{e'full_set': [], e'cursor': 3} stands for {0: [], 2: 3}.
Note to RFC Editor: Please delete the paragraph immediately preceding
this note. Also, in the CBOR diagnostic notation used in this
document, please replace the constructs of the form e'SOME_NAME' with
the value assigned to SOME_NAME in the CDDL model shown in Figure 15
of Appendix D. Finally, please delete this note.
2. Protocol Overview 2. Protocol Overview
This protocol defines how a CoAP-based authorization server informs This protocol defines how a CoAP-based AS informs clients and RSs,
clients and resource servers, i.e., registered devices, about i.e., registered devices, about pertaining revoked access tokens.
pertaining revoked access tokens. How the relationship between a How the relationship between a registered device and the AS is
registered device and the AS is established is out of the scope of established is out of the scope of 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:
* Upon startup, the AS creates a single TRL accessible through the 1. Upon startup, the AS creates a single TRL accessible through the
TRL endpoint. At any point in time, the TRL represents the list TRL endpoint. At any point in time, the TRL represents the list
of all revoked access tokens issued by the AS that are not expired of all revoked access tokens issued by the AS that are not
yet. expired yet.
* When a device registers at the AS, it also receives the url-path 2. When a device registers at the AS, it also receives the url-path
to the TRL endpoint. to the TRL endpoint.
At any time after the registration procedure is finished, the At any time after the registration procedure is finished, the
registered device can send a GET request to the TRL endpoint at registered device can send a GET request to the TRL endpoint at
the AS. When doing so, it can request for: the current list of the AS. When doing so, it can request the following: the current
pertaining revoked access tokens (see Section 7); or the most list of pertaining revoked access tokens (see Section 7) or the
recent updates that occurred over the list of pertaining revoked most recent updates that occurred over the list of pertaining
access tokens (see Section 8). revoked access tokens (see Section 8).
In particular, the registered device can rely on Observation for In particular, the registered device can rely on Observation for
CoAP [RFC7641]. In such a case, the GET request sent to the TRL CoAP [RFC7641]. In such a case, the GET request sent to the TRL
endpoint includes the CoAP Observe Option set to 0 (register), endpoint includes the CoAP Observe Option set to 0 (register),
i.e., it is an Observation Request. By doing so, the registered i.e., it is an Observation Request. By doing so, the registered
device effectively subscribes to the TRL, as interested in device effectively subscribes to the TRL, as the device is
receiving notifications about its update. Upon receiving the interested in receiving notifications about the TRL's update.
Observation Request, the AS adds the registered device to the list Upon receiving the Observation Request, the AS adds the
of observers of the TRL endpoint. registered device to the list of observers of the TRL endpoint.
* When an access token is revoked, the AS adds the corresponding 3. When an access token is revoked, the AS adds the corresponding
token hash to the TRL. Also, when a revoked access token token hash to the TRL. Also, when a revoked access token
eventually expires, the AS removes the corresponding token hash eventually expires, the AS removes the corresponding token hash
from the TRL. from the TRL.
In either case, after updating the TRL, the AS sends Observe In either case, after updating the TRL, the AS sends Observe
notifications as per [RFC7641]. That is, an Observe notification notifications as per [RFC7641]. That is, an Observe notification
is sent to each registered device subscribed to the TRL and to is sent to each registered device that is subscribed to the TRL
which the access token pertains. 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 either the current
list of revoked access tokens in the subset of the TRL pertaining updated list of revoked access tokens in the subset of the TRL
to that device (see Section 7), or the most recent TRL updates pertaining to that device (see Section 7) or the most recent TRL
occurred over that list of pertaining revoked access tokens (see updates that occurred over that list of pertaining revoked access
Section 8). tokens (see Section 8).
Further Observe notifications may be sent, consistently with Further Observe notifications may be sent, consistent with
ongoing additional observations of the TRL endpoint. ongoing additional observations of the TRL endpoint.
* An administrator can access and subscribe to the TRL like a 4. An administrator can access and subscribe to the TRL like a
registered device, while getting the content of the whole TRL (see registered device while getting the content of the whole TRL (see
Section 7) or the most recent updates occurred to the whole TRL Section 7) or the most recent updates that occurred to the whole
(see Section 8). TRL (see Section 8).
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. For the sake of simplicity, the example shown in the protocol. For the sake of simplicity, the example shown in the
figure considers the simultaneous revocation of the three access figure considers the simultaneous revocation of the three access
tokens t1, t2, and t3, whose corresponding token hashes are th1, th2, tokens t1, t2, and t3 whose corresponding token hashes are th1, th2,
and th3, respectively. Consequently, the AS adds the three token and th3, respectively. Consequently, the AS adds the three token
hashes to the TRL at once, and sends Observe notifications to one hashes to the TRL at once and sends Observe notifications to one
administrator and four registered devices. Each dotted line administrator and four registered devices. Each dotted line
associated with a pair of registered devices indicates the access associated with a pair of registered devices indicates the access
token 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)
| |
+-----------------+------------+------------+------------+ +-----------------+------------+------------+------------+
skipping to change at page 9, line 47 skipping to change at line 391
:...........................................: :...........................................:
Figure 1: Protocol Overview Figure 1: Protocol Overview
Appendix C provides examples of the protocol flow and message Appendix C provides examples of the protocol flow and message
exchanges between the AS and a registered device. exchanges between the AS and a registered device.
3. Issuing of Access Tokens at the AS 3. Issuing of Access Tokens at the AS
An AS that supports the method defined in this document MUST adhere An AS that supports the method defined in this document MUST adhere
to the following rules when issuing an access token. to the following rules when issuing an access token:
* All the intended header parameters in the access token MUST be * All the intended header parameters in the access token MUST be
specified within integrity-protected fields. specified within integrity-protected fields.
* If the access token is a CWT, the following applies. * If the access token is a CWT, the following applies:
- Any "unprotected" field MUST be empty, i.e., its value MUST be - Any "unprotected" field MUST be empty, i.e., its value MUST be
encoded as the empty CBOR map (0xa0). This applies to: the encoded as the empty CBOR map (0xa0). This applies to the top-
top-level "unprotected" field of the COSE object used for the level "unprotected" field of the COSE object used for the CWT,
CWT; the "unprotected" field of each element of the the "unprotected" field of each element of the "signatures"
"signatures" array; and the "unprotected" field of each element array, and the "unprotected" field of each element of any
of any "recipients" array (see Sections 2, 3, 4, 5, and 6 of "recipients" array (see Sections 2, 3, 4, 5, and 6 of
[RFC9052]). [RFC9052]).
- Consistent with the specific COSE object used for the CWT, the - Consistent with the specific COSE object used for the CWT, the
corresponding tagged structure in the set COSE_Tagged_Message corresponding tagged structure in the set COSE_Tagged_Message
MUST be used (see Section 2 of [RFC9052]). That is, the CBOR MUST be used (see Section 2 of [RFC9052]). That is, the CBOR
array that encodes the CWT MUST be tagged by using the COSE array that encodes the CWT MUST be tagged by using the COSE
CBOR tag corresponding to the used COSE object. Table 1 in CBOR tag corresponding to the used COSE object. Table 1 in
Section 2 of [RFC9052] specifies the tag numbers in question. Section 2 of [RFC9052] specifies the tag numbers in question.
In turn, the resulting tagged data item MUST be tagged by using In turn, the resulting tagged data item MUST be tagged by using
the CWT CBOR tag with tag number 61 (see Section 6 of the CWT CBOR tag with tag number 61 (see Section 6 of
[RFC8392]). After that, the resulting data item MUST NOT be [RFC8392]). After that, the resulting data item MUST NOT be
further tagged. further tagged.
Encoding of the tag numbers MUST be done using definite Encoding of the tag numbers MUST be done using definite
lengths, and the length of the encoded tag numbers MUST be the lengths, and the length of the encoded tag numbers MUST be the
minimum possible length. This means that the tag number 16 is minimum possible length. This means that tag number 16 is
encoded as 0xd0 and not as 0xd810. encoded as 0xd0 and not as 0xd810.
The example in Figure 2 shows a CWT that uses the COSE object The example in Figure 2 shows a CWT that uses the COSE object
COSE_Encrypt0 (see Section 5.2 of [RFC9052]). COSE_Encrypt0 (see Section 5.2 of [RFC9052]).
* If, like for JWTs [RFC7519], the access token relies on a JSON * If, like for JWTs [RFC7519], the access token relies on a JSON
object for encoding its claims, the following applies. object for encoding its claims, the following applies:
Consistent with the ACE framework [RFC9200], this document Consistent with the ACE framework [RFC9200], this document
specifically considers JWTs, which are always represented using specifically considers JWTs, which are always represented using
the JWS Compact Serialization from [RFC7515] or the JWE Compact the JSON Web Signature (JWS) Compact Serialization from [RFC7515]
Serialization from [RFC7516]. Consequently, all the header or the JSON Web Encryption (JWE) Compact Serialization from
parameters are specified within integrity-protected fields. [RFC7516]. Consequently, all the header parameters are specified
within integrity-protected fields.
In case alternative access tokens were used, the following In case alternative access tokens were used, the following
applies: applies:
- If the access token uses the JWS JSON Serialization from - If the access token uses the JWS JSON Serialization from
[RFC7515], it MUST NOT include the JWS Unprotected Header. [RFC7515], it MUST NOT include the JWS Unprotected Header.
- If the access token uses the JWE JSON Serialization from - If the access token uses the JWE JSON Serialization from
[RFC7516], it MUST NOT include the JWE Shared Unprotected [RFC7516], it MUST NOT include the JWE Shared Unprotected
Header and it MUST NOT include the "header" member in any of Header and it MUST NOT include the "header" member in any of
skipping to change at page 11, line 24 skipping to change at line 466
78b0ea7428fff157444d45f7e6afcda1 78b0ea7428fff157444d45f7e6afcda1
aae5f6495830c58627087fc5b4974f31 aae5f6495830c58627087fc5b4974f31
9a8707a635dd643b' 9a8707a635dd643b'
] ]
) )
) )
Figure 2: Example of CWT Using COSE_Encrypt0 Figure 2: Example of CWT Using COSE_Encrypt0
Section 14.6 discusses how adhering to the rules above neutralizes an Section 14.6 discusses how adhering to the rules above neutralizes an
attack against the RS, where an active adversary can induce the RS to attack against the RS where an active adversary can induce the RS to
compute a token hash different from the correct one. compute a token hash different from the correct one.
4. Token Hash 4. Token Hash
This section specifies how token hashes are computed. This section specifies how token hashes are computed.
First, Section 4.1 provides the motivation for the used construction. First, Section 4.1 provides the motivation for the used construction.
Building on that, the value used as input to compute a token hash is Building on that, the value used as input to compute a token hash is
defined in Section 4.2 for the client and the AS, and in Section 4.3 defined in Section 4.2 for the client and the AS and in Section 4.3
for the RS. Finally, Section 4.4 defines how such an input is used for the RS. Finally, Section 4.4 defines how such an input is used
for computing the token hash. for computing the token hash.
The process outlined below refers to the base64url encoding and The process outlined below refers to the base64url encoding and
decoding without padding (see Section 5 of [RFC4648]), and denotes as decoding without padding (see Section 5 of [RFC4648]) and denotes as
"binary representation" of a text string the corresponding UTF-8 "binary representation" of a text string the corresponding UTF-8
encoding [RFC3629], which is the implied charset used in JSON (see encoding [RFC3629], which is the implied charset used in JSON (see
Section 8.1 of [RFC8259]). Section 8.1 of [RFC8259]).
Consistent with Section 3.4 of [RFC8949], the term "tag" is used for Consistent with Section 3.4 of [RFC8949], the term "tag" is used for
the entire CBOR data item consisting of both a tag number and the tag the entire CBOR data item consisting of both a tag number and the tag
content: the tag content is the CBOR data item that is being tagged. content: the tag content is the CBOR data item that is being tagged.
Also, "tagged access token" is used to denote nested CBOR tags Also, "tagged access token" is used to denote nested CBOR tags
(possibly a single one), with the innermost tag content being a CWT. (possibly a single one), with the innermost tag content being a CWT.
skipping to change at page 12, line 17 skipping to change at line 505
An access token can have one among different formats. The most An access token can have one among different formats. The most
expected formats are CWT [RFC8392] and JWT [RFC7519], with the former expected formats are CWT [RFC8392] and JWT [RFC7519], with the former
being the default format to use in the ACE framework (see Section 3 being the default format to use in the ACE framework (see Section 3
of [RFC9200]). While access tokens are opaque to clients, an RS is of [RFC9200]). While access tokens are opaque to clients, an RS is
aware of whether access tokens that are issued for it to consume are aware of whether access tokens that are issued for it to consume are
either CWTs or JWTs. either CWTs or JWTs.
4.1.1. Issuing of the Access Token to the Client 4.1.1. Issuing of the Access Token to the Client
There are two possible encodings that the AS can use for the AS-to- There are two possible encodings that the AS can use for the AS-to-
Client response (see Section 5.8.2 of [RFC9200]), where the issued Client response (see Section 5.8.2 of [RFC9200]) where the issued
access token is included and provided to the requester client. The access token is included and provided to the requester client. The
RS may not be aware of which encoding is used for that response to RS may not be aware of which encoding is used for that response to
that particular requester client. that particular requester client.
* One way relies on CBOR, which is required if CoAP is used (see * One method of encoding relies on CBOR, which is required if CoAP
Section 5 of [RFC9200]) and is recommended otherwise (see is used (see Section 5 of [RFC9200]) and is recommended otherwise
Section 3 of [RFC9200]). That is, the AS-to-Client response has (see Section 3 of [RFC9200]). That is, the AS-to-Client response
media-type "application/ace+cbor". has media-type "application/ace+cbor".
This implies that, within the CBOR map specified as message This implies that, within the CBOR map specified as message
payload, the parameter 'access_token' is a CBOR data item of type payload, the 'access_token' parameter is a CBOR data item of type
CBOR byte string and with value BYTES. In particular: CBOR byte string and with a value of BYTES. In particular:
- If the access token is a CWT, then BYTES is the binary - If the access token is a CWT, then BYTES is the binary
representation of the CWT (i.e., of the CBOR array that encodes representation of the CWT (i.e., of the CBOR array that encodes
the untagged CWT) or of a tagged access token with the CWT as the untagged CWT) or of a tagged access token with the CWT as
innermost tag content. the innermost tag content.
- If the access token is a JWT, then BYTES is the binary - If the access token is a JWT, then BYTES is the binary
representation of the JWT (i.e., of the text string that representation of the JWT (i.e., of the text string that
encodes the JWT). encodes the JWT).
* An alternative way relies on JSON. That is, the AS-to-Client * An alternative method of encoding relies on JSON. That is, the
response has media-type "application/ace+json". AS-to-Client response has media-type "application/ace+json".
This implies that, within the JSON object specified as message This implies that, within the JSON object specified as message
payload, the parameter 'access_token' has as value a text string payload, the 'access_token' parameter has as a value a text string
TEXT. In particular: TEXT. In particular:
- If the access token is a JWT, then TEXT is the text string that - If the access token is a JWT, then TEXT is the text string that
encodes the JWT. encodes the JWT.
- If the access token is a CWT, then TEXT is the base64url- - If the access token is a CWT, then TEXT is the base64url-
encoded text string of BYTES, which is the binary encoded text string of BYTES, which is the binary
representation of the CWT (i.e., of the CBOR array that encodes representation of the CWT (i.e., of the CBOR array that encodes
the untagged CWT) or of a tagged access token with the CWT as the untagged CWT) or of a tagged access token with the CWT as
innermost tag content. the innermost tag content.
4.1.2. Provisioning of Access Tokens to the RS 4.1.2. Provisioning of Access Tokens to the RS
In accordance with the used transport profile of ACE (e.g., In accordance with the used transport profile of ACE (e.g.,
[RFC9202], [RFC9203], [RFC9431]), the RS receives a piece of token- [RFC9202], [RFC9203], [RFC9431]), the RS receives a piece of token-
related information hereafter denoted as TOKEN_INFO. related information hereafter denoted as TOKEN_INFO.
In particular: In particular:
* If the AS-to-Client response was encoded in CBOR, then TOKEN_INFO * If the AS-to-Client response was encoded in CBOR, then TOKEN_INFO
is the value of the CBOR byte string conveyed by the is the value of the CBOR byte string conveyed by the
'access_token' parameter of that response. That is, TOKEN_INFO is 'access_token' parameter of that response. That is, TOKEN_INFO is
the binary representation of the (tagged) access token. the binary representation of the access token.
* If the AS-to-Client response was encoded in JSON and the access * If the AS-to-Client response was encoded in JSON and the access
token is a JWT, then TOKEN_INFO is the binary representation of token is a JWT, then TOKEN_INFO is the binary representation of
the text string conveyed by the 'access_token' parameter of that the text string conveyed by the 'access_token' parameter of that
response. That is, TOKEN_INFO is the binary representation of the response. That is, TOKEN_INFO is the binary representation of the
access token. access token.
* If the AS-to-Client response was encoded in JSON and the access * If the AS-to-Client response was encoded in JSON and the access
token is a CWT, then TOKEN_INFO is the binary representation of token is a CWT, then TOKEN_INFO is the binary representation of
the base64url-encoded text string that encodes the binary the base64url-encoded text string that encodes the binary
representation of the (tagged) access token. That is, TOKEN_INFO representation of the access token. That is, TOKEN_INFO is the
is the binary representation of the base64url-encoded text string binary representation of the base64url-encoded text string
conveyed by the 'access_token' parameter. conveyed by the 'access_token' parameter.
The following overviews how the above specifically applies to the The following overviews how the above specifically applies to the
existing transport profiles of ACE. existing transport profiles of ACE:
* The (tagged) access token can be uploaded to the RS by means of a * The access token can be uploaded to the RS by means of a POST
POST request to the /authz-info endpoint (see Section 5.10.1 of request to the /authz-info endpoint (see Section 5.10.1 of
[RFC9200]), using a CoAP Content-Format or HTTP media-type that [RFC9200]), using a CoAP Content-Format or HTTP media-type that
reflects the format of the access token, if available (e.g., reflects the format of the access token, if available (e.g.,
"application/cwt" for CWTs), or "application/octet-stream" "application/cwt" for CWTs), or "application/octet-stream"
otherwise. When doing so (e.g., like in [RFC9202]), TOKEN_INFO is otherwise. When doing so (e.g., like in [RFC9202]), TOKEN_INFO is
the payload of the POST request. the payload of the POST request.
* The (tagged) access token can be uploaded to the RS by means of a * The access token can be uploaded to the RS by means of a POST
POST request to the /authz-info endpoint, using the media-type request to the /authz-info endpoint, using the media-type
"application/ace+cbor". When doing so (e.g., like in [RFC9203]), "application/ace+cbor". When doing so (e.g., like in [RFC9203]),
TOKEN_INFO is the value of the CBOR byte string conveyed by the TOKEN_INFO is the value of the CBOR byte string conveyed by the
'access_token' parameter, within the CBOR map specified as payload 'access_token' parameter, within the CBOR map specified as payload
of the POST request. of the POST request.
* The (tagged) access token can be uploaded to the RS during a DTLS * The access token can be uploaded to the RS during a DTLS session
session establishment, e.g., like it is defined in Section 3.2.2 establishment, e.g., like it is defined in Section 3.3.2 of
of [RFC9202]. When doing so, TOKEN_INFO is the value of the [RFC9202]. When doing so, TOKEN_INFO is the value of the
'psk_identity' field of the ClientKeyExchange message (when using 'psk_identity' field of the ClientKeyExchange message (when using
DTLS 1.2 [RFC6347]), or of the 'identity' field of a PSKIdentity, DTLS 1.2 [RFC6347]) or of the 'identity' field of a PSKIdentity,
within the PreSharedKeyExtension of a ClientHello message (when within the PreSharedKeyExtension of a ClientHello message (when
using DTLS 1.3 [RFC9147]). using DTLS 1.3 [RFC9147]).
* The (tagged) access token can be uploaded to the RS within the * The access token can be uploaded to the RS within the MQTT CONNECT
MQTT CONNECT packet, e.g., like it is defined in Section 2.2.4.1 packet, e.g., like it is defined in Section 2.2.4.1 of [RFC9431].
of [RFC9431]. When doing so, TOKEN_INFO is specified within the When doing so, TOKEN_INFO is specified within the 'Authentication
'Authentication Data' field of the MQTT CONNECT packet, following Data' field of the MQTT CONNECT packet, following the property
the property identifier 22 (0x16) and the token length. identifier 22 (0x16) and the token length.
Note that, if the access token is a CWT, it is specifically tagged as
defined in Section 3.
4.1.3. Design Rationale 4.1.3. Design Rationale
Considering the possible variants discussed above, it must always be Considering the possible variants discussed above, it must always be
ensured that the same HASH_INPUT value is used as input for ensured that the same HASH_INPUT value is used as input for
generating the token hash of a given access token, by the AS that has generating the token hash of a given access token, by the AS that has
issued the access token and by the registered devices to which the issued the access token and by the registered devices to which the
access token pertains (both client and RS). access token pertains (both client and RS).
This is achieved by building HASH_INPUT according to the content of This is achieved by building HASH_INPUT according to the content of
the 'access_token' parameter in the AS-to-Client responses, since the 'access_token' parameter in the AS-to-Client responses because
that is what all among the AS, the client, and the RS are able to that is what the AS, the client, and the RS are all able to see.
see.
4.2. Hash Input on the Client and the AS 4.2. Hash Input on the Client and the AS
The client and the AS consider the content of the 'access_token' The client and the AS consider the content of the 'access_token'
parameter in the AS-to-Client response, where the (tagged) access parameter in the AS-to-Client response, in which the access token is
token is included and provided to the requester client. included and provided to the requester client. Note that, if the
access token is a CWT, it is specifically tagged as defined in
Section 3.
The following defines how the client and the AS determine the The following defines how the client and the AS determine the
HASH_INPUT value to use as input for computing the token hash of the HASH_INPUT value to use as input for computing the token hash of the
conveyed access token, depending on the AS-to-Client response being conveyed access token, depending on the AS-to-Client response being
encoded in CBOR (see Section 4.2.1) or in JSON (see Section 4.2.2). encoded in CBOR (see Section 4.2.1) or in JSON (see Section 4.2.2).
Once determined HASH_INPUT, the client and the AS use it to compute Once HASH_INPUT is determined, the client and the AS use it to
the token hash of the conveyed access token as defined in compute the token hash of the conveyed access token as defined in
Section 4.4. Section 4.4.
4.2.1. AS-to-Client Response Encoded in CBOR 4.2.1. AS-to-Client Response Encoded in CBOR
If the AS-to-Client response is encoded in CBOR, then HASH_INPUT is If the AS-to-Client response is encoded in CBOR, then HASH_INPUT is
defined as follows: defined as follows:
* BYTES denotes the value of the CBOR byte string conveyed in the * BYTES denotes the value of the CBOR byte string conveyed in the
parameter 'access_token'. 'access_token' parameter.
With reference to the example in Figure 3, BYTES is the bytes With reference to the example in Figure 3, BYTES is the bytes
{0xd8 0x3d 0xd0 ... 0x64 0x3b}. {0xd8, 0x3d, 0xd0, ..., 0x64, 0x3b}.
Note that BYTES is the binary representation of the tagged access Note that BYTES is the binary representation of the tagged access
token if this is a CWT (as per Section 3), or of the access token token if this is a CWT (as per Section 3) or of the access token
if this is a JWT. if this is a JWT.
* HASH_INPUT_TEXT is the base64url-encoded text string that encodes * HASH_INPUT_TEXT is the base64url-encoded text string that encodes
BYTES. BYTES.
* HASH_INPUT is the binary representation of HASH_INPUT_TEXT. * HASH_INPUT is the binary representation of HASH_INPUT_TEXT.
Header: Created (Code=2.01) Header: Created (Code=2.01)
Content-Format: application/ace+cbor Content-Format: 19 (application/ace+cbor)
Max-Age: 85800 Max-Age: 85800
Payload: Payload:
{ {
/ access_token / 1 : h'd83dd0835820a3010a044c53796d6d / access_token / 1 : h'd83dd0835820a3010a044c53796d6d
6574726963313238054d99a0d7846e 6574726963313238054d99a0d7846e
762c49ffe8a63e0ba05858b918a11f 762c49ffe8a63e0ba05858b918a11f
d81e438b7f973d9e2e119bcb22424b d81e438b7f973d9e2e119bcb22424b
a0f38a80f27562f400ee1d0d6c0fdb a0f38a80f27562f400ee1d0d6c0fdb
559c02421fd384fc2ebe22d7071378 559c02421fd384fc2ebe22d7071378
b0ea7428fff157444d45f7e6afcda1 b0ea7428fff157444d45f7e6afcda1
aae5f6495830c58627087fc5b4974f aae5f6495830c58627087fc5b4974f
319a8707a635dd643b', 319a8707a635dd643b',
/ token_type / 34 : 2 / PoP /, / token_type / 34 : 2 / PoP /,
/ expires_in / 2 : 86400, / expires_in / 2 : 86400,
/ ace_profile / 38 : 1 / coap_dtls /, / ace_profile / 38 : 1 / coap_dtls /
/ (remainder of the response omitted for brevity) / / (remainder of the response omitted for brevity) /
} }
Figure 3: Example of AS-to-Client CoAP response using CBOR Figure 3: Example of AS-to-Client CoAP Response Using CBOR
4.2.2. AS-to-Client Response Encoded in JSON 4.2.2. AS-to-Client Response Encoded in JSON
If the AS-to-Client response is encoded in JSON, then HASH_INPUT is If the AS-to-Client response is encoded in JSON, then HASH_INPUT is
the binary representation of the text string conveyed by the the binary representation of the text string conveyed by the
'access_token' parameter. 'access_token' parameter.
With reference to the example in Figure 4, HASH_INPUT is the binary With reference to the example in Figure 4, HASH_INPUT is the binary
representation of "eyJh...YFiA". When showing the access token, representation of "eyJh...YFiA". When showing the access token,
Figure 4 uses line breaks for display purposes only. Figure 4 uses line breaks for display purposes only.
Note that: Note that:
* If the access token is a JWT, then HASH_INPUT is the binary * If the access token is a JWT, then HASH_INPUT is the binary
representation of the JWT. representation of the JWT.
* If the access token is a CWT, then HASH_INPUT is the binary * If the access token is a CWT, then HASH_INPUT is the binary
representation of a base64url-encoded text string, which encodes representation of a base64url-encoded text string, which encodes
the binary representation of a tagged access token with the CWT as the binary representation of a tagged access token with the CWT as
innermost tag content (as per Section 3). the innermost tag content (as per Section 3).
HTTP/1.1 200 OK HTTP/1.1 200 OK
Content-Type: application/ace+json Content-Type: application/ace+json
Cache-Control: no-store Cache-Control: no-store
Pragma: no-cache Pragma: no-cache
Payload: Payload:
{ {
"access_token" : "eyJhbGciOiJSU0ExXzUiLCJlbmMiOiJB "access_token" : "eyJhbGciOiJSU0ExXzUiLCJlbmMiOiJB
MTI4Q0JDLUhTMjU2In0. MTI4Q0JDLUhTMjU2In0.
QR1Owv2ug2WyPBnbQrRARTeEk9kDO2w8 QR1Owv2ug2WyPBnbQrRARTeEk9kDO2w8
skipping to change at page 16, line 44 skipping to change at line 721
NoQX7N7ZYMmpUDkR-Cx9obNGwJQ3nM52 NoQX7N7ZYMmpUDkR-Cx9obNGwJQ3nM52
YCitxoQVPzjbl7WBuB7AohdBoZOdZ24W YCitxoQVPzjbl7WBuB7AohdBoZOdZ24W
lN1lVIeh8v1K4krB8xgKvRU8kgFrEn_a lN1lVIeh8v1K4krB8xgKvRU8kgFrEn_a
1rZgN5TiysnmzTROF869lQ. 1rZgN5TiysnmzTROF869lQ.
AxY8DCtDaGlsbGljb3RoZQ. AxY8DCtDaGlsbGljb3RoZQ.
MKOle7UQrG6nSxTLX6Mqwt0orbHvAKeW MKOle7UQrG6nSxTLX6Mqwt0orbHvAKeW
nDYvpIAeZ72deHxz3roJDXQyhxx0wKaM nDYvpIAeZ72deHxz3roJDXQyhxx0wKaM
HDjUEOKIwrtkHthpqEanSBNYHZgmNOV7 HDjUEOKIwrtkHthpqEanSBNYHZgmNOV7
sln1Eu9g3J8. sln1Eu9g3J8.
fiK51VwhsxJ-siBMR-YFiA", fiK51VwhsxJ-siBMR-YFiA",
"token_type" : "pop", "token_type" : "PoP",
"expires_in" : 86400, "expires_in" : 86400,
"ace_profile" : "1" "ace_profile" : "coap_dtls"
} }
Figure 4: Example of AS-to-Client HTTP response using JSON Figure 4: Example of AS-to-Client HTTP Response Using JSON
4.3. HASH_INPUT on the RS 4.3. HASH_INPUT on the RS
The following defines how the RS determines the HASH_INPUT value to The following defines how the RS determines the HASH_INPUT value to
use as input for computing the token hash of an access token, use as input for computing the token hash of an access token,
depending on the RS using either CWTs (see Section 4.3.1) or JWTs depending on the RS using either CWTs (see Section 4.3.1) or JWTs
(see Section 4.3.2). (see Section 4.3.2).
4.3.1. Access Tokens as CWTs 4.3.1. Access Tokens as CWTs
If the RS expects access tokens to be CWTs, then the RS performs the If the RS expects access tokens to be CWTs, then the RS performs the
following steps. following steps:
1. The RS receives the token-related information TOKEN_INFO, in 1. The RS receives the token-related information TOKEN_INFO, in
accordance with what is specified by the used profile of ACE (see accordance with what is specified by the used profile of ACE (see
Section 4.1.2). Section 4.1.2).
2. The RS assumes that the client received the access token in an 2. The RS assumes that the client received the access token in an
AS-to-Client response encoded in CBOR (see Section 4.2.1). AS-to-Client response encoded in CBOR (see Section 4.2.1).
Hence, the RS assumes TOKEN_INFO to be the binary representation Hence, the RS assumes TOKEN_INFO to be the binary representation
of the tagged access token with the CWT as innermost tag content of the tagged access token with the CWT as the innermost tag
(as per Section 3). content (as per Section 3).
3. The RS verifies the access token as per Section 5.10.1.1 of 3. The RS verifies the access token as per Section 5.10.1.1 of
[RFC9200]. If the verification fails, then the RS does not [RFC9200]. If the verification fails, then the RS does not
discard the access token yet, and it instead moves to step 4. discard the access token yet; instead, it moves to Step 4.
Otherwise, the RS stores the access token and computes the Otherwise, the RS stores the access token and computes the
corresponding token hash, as defined in Section 4.4. In corresponding token hash as defined in Section 4.4. In
particular, the RS considers HASH_INPUT_TEXT as the base64url- particular, the RS considers HASH_INPUT_TEXT as the base64url-
encoded text string that encodes TOKEN_INFO. Then, HASH_INPUT is encoded text string that encodes TOKEN_INFO. Then, HASH_INPUT is
the binary representation of HASH_INPUT_TEXT. the binary representation of HASH_INPUT_TEXT.
After that, the RS stores the computed token hash as associated After that, the RS stores the computed token hash as associated
with the access token, and then terminates this algorithm. with the access token; then, it terminates this algorithm.
4. The RS assumes that the client received the access token in an 4. The RS assumes that the client received the access token in an
AS-to-Client response encoded in JSON (see Section 4.2.2). AS-to-Client response encoded in JSON (see Section 4.2.2).
Hence, the RS assumes TOKEN_INFO to be the binary representation Hence, the RS assumes TOKEN_INFO to be the binary representation
of HASH_INPUT_TEXT. In turn, HASH_INPUT_TEXT is the base64url- of HASH_INPUT_TEXT. In turn, HASH_INPUT_TEXT is the base64url-
encoded text string that encodes the binary representation of the encoded text string that encodes the binary representation of the
tagged access token with the CWT as innermost tag content (as per tagged access token with the CWT as the innermost tag content (as
Section 3). per Section 3).
5. The RS performs the base64url decoding of HASH_INPUT_TEXT, and 5. The RS performs the base64url decoding of HASH_INPUT_TEXT and
considers the result as the binary representation of the tagged considers the result to be the binary representation of the
access token. tagged access token.
6. The RS verifies the access token as per Section 5.10.1.1 of 6. The RS verifies the access token as per Section 5.10.1.1 of
[RFC9200]. If the verification fails, then the RS terminates [RFC9200]. If the verification fails, then the RS terminates
this algorithm. this algorithm.
Otherwise, the RS stores the access token and computes the Otherwise, the RS stores the access token and computes the
corresponding token hash, as defined in Section 4.4. In corresponding token hash as defined in Section 4.4. In
particular, HASH_INPUT is TOKEN_INFO. particular, HASH_INPUT is TOKEN_INFO.
After that, the RS stores the computed token hash as associated After that, the RS stores the computed token hash as associated
with the access token. with the access token.
4.3.2. Access Tokens as JWTs 4.3.2. Access Tokens as JWTs
If the RS expects access tokens to be JWTs, then the RS performs the If the RS expects access tokens to be JWTs, then the RS performs the
following steps. following steps:
1. The RS receives the token-related information TOKEN_INFO, in 1. The RS receives the token-related information TOKEN_INFO, in
accordance with what is specified by the used profile of ACE (see accordance with what is specified by the used profile of ACE (see
Section 4.1.2). Section 4.1.2).
2. The RS verifies the access token as per Section 5.10.1.1 of 2. The RS verifies the access token as per Section 5.10.1.1 of
[RFC9200]. If the verification fails, then the RS terminates [RFC9200]. If the verification fails, then the RS terminates
this algorithm. Otherwise, the RS stores the access token. this algorithm. Otherwise, the RS stores the access token.
3. The RS computes a first token hash associated with the access 3. The RS computes a first token hash associated with the access
token, as defined in Section 4.4. token as defined in Section 4.4.
In particular, the RS assumes that the client received the access In particular, the RS assumes that the client received the access
token in an AS-to-Client response encoded in JSON (see token in an AS-to-Client response encoded in JSON (see
Section 4.2.2). Hence, HASH_INPUT is TOKEN_INFO. Section 4.2.2). Hence, HASH_INPUT is TOKEN_INFO.
After that, the RS stores the computed token hash as associated After that, the RS stores the computed token hash as associated
with the access token. with the access token.
4. The RS computes a second token hash associated with the access 4. The RS computes a second token hash associated with the access
token, as defined in Section 4.4. token as defined in Section 4.4.
In particular, the RS assumes that the client received the access In particular, the RS assumes that the client received the access
token in an AS-to-Client response encoded in CBOR (see token in an AS-to-Client response encoded in CBOR (see
Section 4.2.1). Hence, HASH_INPUT is the binary representation Section 4.2.1). Hence, HASH_INPUT is the binary representation
of HASH_INPUT_TEXT, which in turn is the base64url-encoded text of HASH_INPUT_TEXT, which, in turn, is the base64url-encoded text
string that encodes TOKEN_INFO. string that encodes TOKEN_INFO.
After that, the RS stores the computed token hash as associated After that, the RS stores the computed token hash as associated
with the access token. with the access token.
The RS skips step 3 only if it is certain that all its pertaining The RS skips Step 3 only if it is certain that all its pertaining
access tokens are provided to any client by means of AS-to-Client access tokens are provided to any client by means of AS-to-Client
responses encoded as CBOR messages. Otherwise, the RS MUST perform responses encoded as CBOR messages. Otherwise, the RS MUST perform
step 3. Step 3.
The RS skips step 4 only if it is certain that all its pertaining The RS skips Step 4 only if it is certain that all its pertaining
access tokens are provided to any client by means of AS-to-Client access tokens are provided to any client by means of AS-to-Client
responses encoded as JSON messages. Otherwise, the RS MUST perform responses encoded as JSON messages. Otherwise, the RS MUST perform
step 4. Step 4.
If the RS performs both step 3 and step 4 above, then the RS MUST If the RS performs both Steps 3 and 4 above, then the RS MUST store,
store, maintain, and rely on both token hashes as associated with the maintain, and rely on both token hashes as associated with the access
access token, consistent with what is specified in Section 11.1. token, consistent with what is specified in Section 11.1.
Section 14.7 discusses how computing and storing both token hashes Section 14.7 discusses how computing and storing both token hashes
neutralizes an attack against the RS, where a dishonest client can neutralizes an attack against the RS, where a dishonest client can
induce the RS to compute a token hash different from the correct one. induce the RS to compute a token hash different from the correct one.
4.4. Computing the Token Hash 4.4. Computing the Token Hash
Once determined HASH_INPUT as defined in Section 4.2 and Section 4.3, Once HASH_INPUT is determined as defined in Sections 4.2 and 4.3, a
a hash value of HASH_INPUT is generated as per Section 6 of hash value of HASH_INPUT is generated as per Section 6 of [RFC6920].
[RFC6920]. The resulting output in binary format is used as the The resulting output in binary format is used as the token hash.
token hash. Note that the used binary format embeds the identifier Note that the used binary format embeds the identifier of the used
of the used hash function, in the first byte of the computed token hash function in the first byte of the computed token hash.
hash.
The specifically used hash function MUST be collision-resistant on The specific hash function used MUST be collision resistant on byte
byte-strings, and MUST be selected from the "Named Information Hash strings and MUST be selected from the "Named Information Hash
Algorithm" Registry [Named.Information.Hash.Algorithm]. Consistent Algorithm Registry" [IANA.Hash.Algorithms]. Consistent with the
with the compliance requirements in Section 2 of [RFC6920], the hash compliance requirements in Section 2 of [RFC6920], the hash function
function sha-256 as specified in [SHA-256] is mandatory to implement. sha-256 as specified in [SHA-256] is mandatory to implement.
The AS specifies the used hash function to registered devices during The AS specifies the used hash function to registered devices during
their registration procedure (see Section 10). their registration procedure (see Section 10).
5. Token Revocation List (TRL) 5. Token Revocation List (TRL)
Upon startup, the AS creates a single Token Revocation List (TRL), Upon startup, the AS creates a single Token Revocation List (TRL)
encoded as a CBOR array. encoded as a CBOR array.
Each element of the array is a CBOR byte string, with value the token Each element of the array is a CBOR byte string, whose value is the
hash of an access token. The CBOR array MUST be treated as a set, token hash of an access token. The CBOR array MUST be treated as a
i.e., the order of its elements has no meaning. set, i.e., the order of its elements has no meaning.
The TRL is initialized as empty, i.e., its initial content MUST be The TRL is initialized as empty, i.e., its initial content MUST be
the empty CBOR array. The TRL is accessible through the TRL endpoint the empty CBOR array. The TRL is accessible through the TRL endpoint
at the AS. at the AS.
5.1. Update of the TRL 5.1. Update of the TRL
The AS updates the TRL in the following two cases. The AS updates the TRL in the following two cases:
* When a non-expired access token is revoked, the token hash of the * When a non-expired access token is revoked, the token hash of the
access token is added to the TRL. That is, a CBOR byte string access token is added to the TRL. That is, a CBOR byte string
with the token hash as its value is added to the CBOR array with the token hash as its value is added to the CBOR array
encoding the TRL. encoding the TRL.
* When a revoked access token expires, the token hash of the access * When a revoked access token expires, the token hash of the access
token is removed from the TRL. That is, the CBOR byte string with token is removed from the TRL. That is, the CBOR byte string with
the token hash as its value is removed from the CBOR array the token hash as its value is removed from the CBOR array
encoding the TRL. encoding the TRL.
The AS MAY perform a single update to the TRL such that one or more The AS MAY perform a single update to the TRL such that one or more
token hashes are added or removed at once. For example, this can be token hashes are added or removed at once. For example, this can be
the case if multiple access tokens are revoked or expire at the same the case if multiple access tokens are revoked or expire at the same
time, or within an acceptably narrow time window. time or within an acceptably narrow time frame.
6. The TRL Endpoint 6. The TRL Endpoint
Consistent with Section 6.5 of [RFC9200], all communications between Consistent with Section 6.5 of [RFC9200], all communications between
a requester towards the TRL endpoint and the AS MUST be encrypted, as the AS and a requester interacting with the TRL endpoint at the AS
well as integrity and replay protected. Furthermore, responses from MUST be encrypted, as well as integrity and replay protected.
the AS to the requester MUST be bound to the corresponding requests. Furthermore, responses from the AS to the requester MUST be bound to
the corresponding requests.
Following a request to the TRL endpoint, the corresponding, success Following a request to the TRL endpoint, the corresponding success
response messages sent by the AS use Content-Format "application/ace- response messages sent by the AS use Content-Format "application/ace-
trl+cbor". Their payload is formatted as a CBOR map, and the CBOR trl+cbor". Their payload is formatted as a CBOR map, and the CBOR
values used to abbreviate the parameters included therein are defined values used to abbreviate the parameters included therein are defined
in Section 12. in Section 12.
The AS MUST implement measures to prevent access to the TRL endpoint The AS MUST implement measures to prevent access to the TRL endpoint
by entities other than registered devices and authorized by entities other than registered devices and authorized
administrators (see Section 10). administrators (see Section 10).
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 queries of the TRL. of queries of the TRL:
* Full query: the AS returns the token hashes of the revoked access 1. Full query: the AS returns the token hashes of the revoked access
tokens currently in the TRL and pertaining to the requester. tokens currently in the TRL and pertaining to the requester.
The AS MUST support this type of query. The processing of a full The AS MUST support this type of query. The processing of a full
query and the related response format are defined in Section 7. query and the related response format are defined in Section 7.
* Diff query: the AS returns a list of diff entries. Each diff 2. Diff query: the AS returns a list of diff entries. Each diff
entry is related to one update occurred to the TRL, and it entry is related to one update that occurred to the TRL, and it
contains a set of token hashes pertaining to the requester. In contains a set of token hashes pertaining to the requester. In
particular, all such token hashes were added to the TRL or removed particular, all such token hashes were added to the TRL or
from the TRL at the update related to the diff entry in question. removed from the TRL at the update related to the diff entry in
question.
The AS MAY support this type of query. In such a case, the AS The AS MAY support this type of query. In such a case, the AS
maintains the history of updates to the TRL as defined in maintains the history of updates to the TRL as defined in
Section 6.2. The processing of a diff query and the related Section 6.2. The processing of a diff query and the related
response format are defined in Section 8. response format are defined in Section 8.
If it supports diff queries, the AS MAY additionally support its If it supports diff queries, the AS MAY additionally support the
"Cursor" extension, which has two benefits. First, the AS can avoid related "Cursor" extension, which has two benefits:
excessively long messages when several diff entries have to be
transferred, by delivering several diff query responses, each 1. The AS can avoid excessively long messages when several diff
containing one adjacent subset of diff entries at a time. Second, a entries have to be transferred by delivering several diff query
requester can retrieve diff entries associated with TRL updates that, responses, each containing one adjacent subset of diff entries at
even if not the most recent ones, occurred after a TRL update a time.
associated with a diff entry indicated as reference point.
2. A requester can retrieve diff entries associated with TRL updates
that, even if not the most recent ones, occurred after a TRL
update associated with a diff entry indicated as a reference
point.
If it supports the "Cursor" extension, the AS stores additional If it supports the "Cursor" extension, the AS stores additional
information when maintaining the history of updates to the TRL, as information when maintaining the history of updates to the TRL as
defined in Section 6.2.1. Also, the processing of full query defined in Section 6.2.1. Also, the processing of full query
requests and diff query requests, as well as the related response requests and diff query requests, as well as the related response
format, are further extended as defined in Section 9. format, are further extended as defined in Section 9.
Appendix B provides an aggregated overview of the local supportive Appendix B provides an aggregated overview of the local supportive
parameters that the AS internally uses at its TRL endpoint, when parameters that the AS internally uses at its TRL endpoint when
supporting diff queries and the "Cursor" extension. supporting diff queries and the "Cursor" extension.
6.1. Error Responses with Problem Details 6.1. Error Responses with Problem Details
Some error responses from the TRL endpoint at the AS can convey Some error responses from the TRL endpoint at the AS can convey
error-specific information according to the problem-details format error-specific information according to the problem-details format
defined in [RFC9290]. Such error responses MUST have Content-Format defined in [RFC9290]. Such error responses MUST have Content-Format
set to "application/concise-problem-details+cbor". The payload of set to "application/concise-problem-details+cbor". The payload of
these error responses MUST be a CBOR map specifying a Concise Problem these error responses MUST be a CBOR map specifying a Concise Problem
Details data item (see Section 2 of [RFC9290]). The CBOR map is Details data item (see Section 2 of [RFC9290]). The CBOR map is
formatted as follows. formatted as follows:
* It MUST include the Custom Problem Detail entry 'ace-trl-error' * It MUST include the Custom Problem Detail entry 'ace-trl-error'
registered in Section 15.3 of this document. This entry is registered in Section 15.3 of this document. This entry is
formatted as a CBOR map, which includes the following fields. formatted as a CBOR map, which includes the following fields:
- The field 'error-id' MUST be present. The map key used for - The 'error-id' field MUST be present. The map key used for
this field is the CBOR unsigned integer with value 0. The this field is the CBOR unsigned integer with a value of 0. The
value of this field is a CBOR integer specifying the error value of this field is a CBOR integer specifying the error that
occurred at the AS. This value is taken from the 'Value' occurred at the AS. This value is taken from the 'Value'
column of the "ACE Token Revocation List Errors" registry column of the "ACE Token Revocation List Errors" registry
defined in Section 15.5 of this document. defined in Section 15.5 of this document.
- The field 'cursor' MAY be present. The map key used for this - The 'cursor' field MAY be present. The map key used for this
field is the CBOR unsigned integer with value 1. The value of field is the CBOR unsigned integer with a value of 1. The
this field is a CBOR unsigned integer or the CBOR simple value value of this field is a CBOR unsigned integer or the CBOR
null (0xf6). The use of this field is defined in Section 6.3. simple value null (0xf6). The use of this field is defined in
Section 6.3.
The CDDL notation [RFC8610] of the 'ace-trl-error' entry is given The CDDL notation [RFC8610] of the 'ace-trl-error' entry is given
below. below:
ace-trl-error = { ace-trl-error = {
0: int, ; error-id 0: int, ; error-id
? 1: uint / null ; cursor ? 1: uint / null ; cursor
} }
* It MAY include further Standard Problem Detail entries or Custom * It MAY include further Standard Problem Detail entries or Custom
Problem Detail entries (see [RFC9290]). Problem Detail entries (see [RFC9290]).
In particular, it can include the Standard Problem Detail entry In particular, it can include the Standard Problem Detail entry
'detail' (map key -2), whose value is a CBOR text string that 'detail' (map key -2), whose value is a CBOR text string that
specifies a human-readable, diagnostic description of the error specifies a human-readable diagnostic description of the error
occurred at the AS. The diagnostic text is intended for software that occurred at the AS. The diagnostic text is intended for
engineers as well as for device and network operators, in order to software engineers as well as for device and network operators in
aid debugging and provide context for possible intervention. The order to aid in debugging and provide context for possible
diagnostic message SHOULD be logged by the AS. The 'detail' entry intervention. The diagnostic message SHOULD be logged by the AS.
is unlikely relevant in an unattended setup where human The 'detail' entry is unlikely to be relevant in an unattended
intervention is not expected. setup where human intervention is not expected.
An example of error response using the problem-details format is An example of an error response using the problem-details format is
shown in Figure 5. shown in Figure 5.
Header: Bad Request (Code=4.00) Header: Bad Request (Code=4.00)
Content-Format: application/concise-problem-details+cbor Content-Format: 257 (application/concise-problem-details+cbor)
Payload: Payload:
{ {
/ title / -1: "Invalid parameter value", / title / -1: "Invalid parameter value",
/ detail / -2: "Invalid value for 'cursor': -53", / detail / -2: "Invalid value for 'cursor': -53",
/ ace-trl-error / e'ace-trl-error': { / ace-trl-error / 1: {
/ error-id / 0: 0 / "Invalid parameter value" /, / error-id / 0: 0 / "Invalid parameter value" /,
/ cursor / 1: 42 / cursor / 1: 42
} }
} }
Figure 5: Example of Error Response with Problem Details Figure 5: Example of Error Response with Problem Details
The problem-details format in general and the Custom Problem Detail The problem-details format in general and the Custom Problem Detail
entry 'ace-trl-error' in particular are OPTIONAL to support for entry 'ace-trl-error' in particular are OPTIONAL to support for
registered devices. A registered device supporting the entry 'ace- registered devices. A registered device supporting the entry 'ace-
trl-error' and able to understand the specified error may use that trl-error' and that is able to understand the specified error may use
information to determine what actions to take next. that information to determine what actions to take next.
6.2. Supporting Diff Queries 6.2. Supporting Diff Queries
If the AS supports diff queries, it is able to transfer a list of If the AS supports diff queries, it is able to transfer a list of
diff entries, each of which is related to one update occurred to the diff entries, each of which is related to one update that occurred to
TRL (see Section 6). That is, when replying to a diff query the TRL (see Section 6). That is, when replying to a diff query
performed by a requester, the AS specifies the diff entries related performed for a requester, the AS provides the diff entries related
to the most recent TRL updates pertaining to the requester. to the most recent TRL updates pertaining to the requester.
The following defines how the AS builds and maintains an ordered list The following defines how the AS builds and maintains an ordered list
of diff entries, for each registered device and administrator, of diff entries, for each registered device and administrator,
hereafter referred to as requesters. In particular, a requester's hereafter referred to as "requesters". In particular, a requester's
diff entry associated with a TRL update contains a set of token diff entry associated with a TRL update contains a set of token
hashes pertaining to that requester, which were added to the TRL or hashes pertaining to that requester, each of which was added to the
removed from the TRL at that update. TRL or removed from the TRL at that update.
The AS defines the single, constant positive integer MAX_N >= 1. For The AS defines the single constant positive integer MAX_N >= 1. For
each requester, the AS maintains an update collection of maximum each requester, the AS maintains an update collection of maximum
MAX_N series items, each of which is a diff entry. For each MAX_N series items, each of which is a diff entry. For each
requester, the AS MUST keep track of the MAX_N most recent TRL requester, the AS MUST keep track of the MAX_N most recent TRL
updates pertaining to the requester. If the AS supports diff updates pertaining to the requester. If the AS supports diff
queries, the AS MUST provide requesters with the value of MAX_N, upon queries, the AS MUST provide requesters with the value of MAX_N upon
their registration (see Section 10). their registration (see Section 10).
The series items in the update collection MUST be strictly ordered in The series of items in the update collection MUST be strictly
a chronological fashion. That is, at any point in time, the current chronologically ordered. That is, at any point in time, the first
first series item is the one least recently added to the update series item is the one least recently added to the update collection
collection and still retained by the AS, while the current last and still retained by the AS; the last series item is the one most
series item is the one most recently added to the update collection. recently added to the update collection. The particular method used
The particular method used to achieve this is implementation- to achieve this is implementation specific.
specific.
Each time the TRL changes, the AS performs the following operations Each time the TRL changes, the AS performs the following operations
for each requester. for each requester:
1. The AS considers the subset of the TRL pertaining to that 1. The AS considers the subset of the TRL pertaining to that
requester. If the TRL subset is not affected by this TRL update, requester. If the TRL subset is not affected by this TRL update,
the AS stops the processing for that requester. Otherwise, the the AS stops the processing for that requester. Otherwise, the
AS moves to step 2. AS moves to Step 2.
2. The AS creates two sets "trl_patch" of token hashes, i.e., one 2. The AS creates two trl_patch sets of token hashes, i.e., one
"removed" set and one "added" set, as related to this TRL update. 'removed' set and one 'added' set, as related to this TRL update.
3. The AS fills the two sets with the token hashes of the removed 3. The AS fills the two sets with the token hashes of the removed
and added access tokens, respectively, from/to the TRL subset and added access tokens, respectively, from/to the TRL subset
considered at step 1. considered at Step 1.
4. The AS creates a new series item, which includes the two sets 4. The AS creates a new series item that includes the two sets from
from step 3. Step 3.
5. If the update collection associated with the requester currently 5. If the update collection associated with the requester currently
includes MAX_N series items, the AS MUST delete the oldest series includes MAX_N series items, the AS MUST delete the oldest series
item in the update collection. item in the update collection.
6. The AS adds the series item to the update collection associated 6. The AS adds the series item to the update collection associated
with the requester, as the last (most recent) one. with the requester as the last (most recent) series item.
6.2.1. Supporting the "Cursor" Extension 6.2.1. Supporting the "Cursor" Extension
If it supports the "Cursor" extension for diff queries, the AS If it supports the "Cursor" extension for diff queries, the AS also
performs also the following actions. performs the following actions:
The AS defines the single, constant unsigned integer MAX_INDEX <= The AS defines the single constant unsigned integer MAX_INDEX <=
((2^64) - 1), where "^" is the exponentiation operator. The value of ((2^64) - 1). The value of MAX_INDEX is REQUIRED to be at least
MAX_INDEX is REQUIRED to be at least (MAX_N - 1), and is RECOMMENDED (MAX_N - 1) and is RECOMMENDED to be at least ((2^32) - 1).
to be at least ((2^32) - 1). MAX_INDEX SHOULD be orders of magnitude MAX_INDEX SHOULD be orders of magnitude greater than MAX_N.
greater than MAX_N.
The following applies separately for each requester's update The following applies separately for each requester's update
collection. collection:
* Each series item X in the update collection is also associated * Each series item X in the update collection is also associated
with an unsigned integer 'index', whose minimum value is 0 and with an unsigned integer 'index', whose minimum value is 0 and
whose maximum value is MAX_INDEX. The first series item ever whose maximum value is MAX_INDEX. The first series item ever
added to the update collection MUST have 'index' with value 0. added to the update collection MUST have an 'index' with a value
of 0.
If i_X is the value of 'index' associated with a series item X, If i_X is the value of 'index' associated with a series item X,
then the following series item Y will take 'index' with value i_Y then the following series item Y will take 'index' with a value of
= (i_X + 1) % (MAX_INDEX + 1). That is, after having added a i_Y = (i_X + 1) % (MAX_INDEX + 1). That is, after having added a
series item whose associated 'index' has value MAX_INDEX, the next series item whose associated 'index' has a value of MAX_INDEX, the
added series item will result in a wrap-around of the 'index' next added series item will result in a wraparound of the 'index'
value, and will thus take 'index' with value 0. value; thus, it will take an 'index' with a value of 0.
For example, assuming MAX_N = 3, the values of 'index' in the For example, assuming MAX_N = 3, the values of 'index' in the
update collection chronologically evolve as follows, as new series update collection chronologically evolve as follows, as new series
items are added and old series items are deleted. items are added and old series items are deleted:
- ... - ...
- (i_A = MAX_INDEX - 2, i_B = MAX_INDEX - 1, i_C = MAX_INDEX) - (i_A = MAX_INDEX - 2, i_B = MAX_INDEX - 1, i_C = MAX_INDEX)
- (i_B = MAX_INDEX - 1, i_C = MAX_INDEX, i_D = 0) - (i_B = MAX_INDEX - 1, i_C = MAX_INDEX, i_D = 0)
- (i_C = MAX_INDEX, i_D = 0, i_E = 1) - (i_C = MAX_INDEX, i_D = 0, i_E = 1)
- (i_D = 0, i_E = 1, i_F = 2) - (i_D = 0, i_E = 1, i_F = 2)
skipping to change at page 25, line 25 skipping to change at line 1128
* The unsigned integer 'last_index' is also defined, with minimum * The unsigned integer 'last_index' is also defined, with minimum
value 0 and maximum value MAX_INDEX. value 0 and maximum value MAX_INDEX.
If the update collection is empty (i.e., no series items have been If the update collection is empty (i.e., no series items have been
added yet), the value of 'last_index' is not defined. If the added yet), the value of 'last_index' is not defined. If the
update collection is not empty, 'last_index' has the value of update collection is not empty, 'last_index' has the value of
'index' currently associated with the last series item in the 'index' currently associated with the last series item in the
update collection. update collection.
That is, after having added V series items to the update That is, after having added V series items to the update
collection, the last and most recently added series item has collection, the last and most recently added series item has an
'index' with value 'last_index' = (V - 1) % (MAX_INDEX + 1). 'index' with a value of 'last_index' = (V - 1) % (MAX_INDEX + 1).
As long as a wrap-around of the 'index' value has not occurred, As long as a wraparound of the 'index' value has not occurred, the
the value of 'last_index' is the absolute counter of series items value of 'last_index' is the absolute counter of series items
added to that update collection, minus 1. added to that update collection, minus 1.
When processing a diff query using the "Cursor" extension, the values When processing a diff query using the "Cursor" extension, the values
of 'index' are used as cursor information, as defined in Section 9.2. of 'index' are used as cursor information, as defined in Section 9.2.
For each requester's update collection, the AS also defines a For each requester's update collection, the AS also defines a
constant, positive integer MAX_DIFF_BATCH <= MAX_N, whose value constant positive integer MAX_DIFF_BATCH <= MAX_N, whose value
specifies the maximum number of diff entries to be included in a specifies the maximum number of diff entries to be included in a
single diff query response. The specific value MAY depend on the single diff query response. The specific value MAY depend on the
specific registered device or administrator associated with the specific registered device or administrator associated with the
update collection in question. If supporting the "Cursor" extension, update collection in question. If supporting the "Cursor" extension,
the AS MUST provide registered devices and administrators with the the AS MUST provide registered devices and administrators with the
corresponding value of MAX_DIFF_BATCH, upon their registration (see corresponding value of MAX_DIFF_BATCH upon their registration (see
Section 10). Section 10).
6.3. Query Parameters 6.3. Query Parameters
A GET request to the TRL endpoint can include the following query A GET request to the TRL endpoint can include the following query
parameters. The AS MUST silently ignore unknown query parameters. parameters. The AS MUST silently ignore unknown query parameters.
* 'diff': if included, it indicates to perform a diff query of the * 'diff': if included, it asks the AS to perform a diff query of the
TRL (see Section 8). Its value MUST be either: TRL (see Section 8). 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 AS can provide in the include as many diff entries as the AS can provide in the
response; or response; or
- a positive integer strictly greater than 0, indicating the - a positive integer strictly greater than 0, indicating the
maximum number of diff entries that a (notification) response maximum number of diff entries that a (notification) response
should include. should include.
If the AS does not support diff queries, it ignores the 'diff' If the AS does not support diff queries, it ignores the 'diff'
query parameter when present in the GET request, and proceeds like query parameter when present in the GET request and proceeds like
when processing a full query of the TRL (see Section 7). when performing a full query of the TRL (see Section 7).
Otherwise, the AS MUST return a 4.00 (Bad Request) response in Otherwise, the AS MUST return a 4.00 (Bad Request) response in
case the 'diff' query parameter of the GET request specifies a case the 'diff' query parameter of the GET request has a value
value that is neither 0 nor a positive integer, irrespective of that is neither 0 nor a positive integer, irrespective of the
the presence of the 'cursor' parameter and its value (see below). presence of the 'cursor' query parameter and its value (see
The response MUST have Content-Format "application/concise- below). The response MUST have Content-Format set to
problem-details+cbor" and its payload is formatted as defined in "application/concise-problem-details+cbor", and its payload is
Section 6.1. Within the Custom Problem Detail entry 'ace-trl- formatted as defined in Section 6.1. Within the Custom Problem
error', the value of the 'error-id' field MUST be set to 0 Detail entry 'ace-trl-error', the value of the 'error-id' field
("Invalid parameter value"), and the field 'cursor' MUST NOT be MUST be set to 0 ("Invalid parameter value"), and the 'cursor'
present. field MUST NOT be present.
* 'cursor': if included, it indicates to perform a diff query of the * 'cursor': if included, it asks the AS to perform a diff query of
TRL together with the "Cursor" extension, as defined in the TRL together with the "Cursor" extension, as defined in
Section 9.2. Its value MUST be either 0 or a positive integer. Section 9.2. Its value MUST be either 0 or a positive integer.
If the 'cursor' query parameter is included, then the 'diff' query If the 'cursor' query parameter is included, then the 'diff' query
parameter MUST also be included. parameter MUST also be included.
If included, the 'cursor' query parameter specifies an unsigned If included, the 'cursor' query parameter has an unsigned integer
integer value that was provided by the AS in a previous response value that was provided by the AS in a previous response from the
from the TRL endpoint (see Section 9.1, Section 9.2.2, and TRL endpoint (see Sections 9.1, 9.2.2, and 9.2.3).
Section 9.2.3).
If the AS does not support the "Cursor" extension, it ignores the If the AS does not support the "Cursor" extension, it ignores the
'cursor' query parameter when present in the GET request. In such 'cursor' query parameter when present in the GET request. In such
a case, the AS proceeds as specified elsewhere in this document, a case, the AS proceeds as specified elsewhere in this document,
i.e.: i) it performs a diff query of the TRL (see Section 8), if that is:
it supports diff queries and the 'diff' query parameter is present
in the GET request; or ii) it performs a full query of the TRL 1. it performs a diff query of the TRL (see Section 8), if it
(see Section 7) otherwise. supports diff queries and the 'diff' query parameter is
present in the GET request; otherwise,
2. it performs a full query of the TRL (see Section 7).
If the AS supports both diff queries and the "Cursor" extension, If the AS supports both diff queries and the "Cursor" extension,
and the GET request specifies the 'cursor' query parameter, then and the GET request includes the 'cursor' query parameter, then
the AS MUST return a 4.00 (Bad Request) response in case any of the AS MUST return a 4.00 (Bad Request) response in case any of
the conditions below holds. the conditions below holds.
The 4.00 (Bad Request) response MUST have Content-Format The 4.00 (Bad Request) response MUST have Content-Format set to
"application/concise-problem-details+cbor" and its payload is "application/concise-problem-details+cbor", and its payload is
formatted as defined in Section 6.1. formatted as defined in Section 6.1.
- The GET request does not specify the 'diff' query parameter, - The GET request does not include the 'diff' query parameter,
irrespective of the value of the 'cursor' parameter. irrespective of the value of the 'cursor' query parameter.
Within the Custom Problem Detail entry 'ace-trl-error', the Within the Custom Problem Detail entry 'ace-trl-error', the
value of the 'error-id' field MUST be set to 1 ("Invalid set of value of the 'error-id' field MUST be set to 1 ("Invalid set of
parameters"), and the field 'cursor' MUST NOT be present. parameters"), and the 'cursor' field MUST NOT be present.
- The 'cursor' query parameter has a value that is neither 0 nor - The 'cursor' query parameter has a value that is neither 0 nor
a positive integer, or it has a value strictly greater than a positive integer; or it has a value strictly greater than
MAX_INDEX (see Section 6.2.1). MAX_INDEX (see Section 6.2.1).
Within the Custom Problem Detail entry 'ace-trl-error', the Within the Custom Problem Detail entry 'ace-trl-error', the
value of the 'error-id' field MUST be set to 0 ("Invalid value of the 'error-id' field MUST be set to 0 ("Invalid
parameter value"). The entry 'ace-trl-error' MUST include the parameter value"). The entry 'ace-trl-error' MUST include the
field 'cursor', whose value is either: the CBOR simple value 'cursor' field, whose value is either:
null (0xf6), if the update collection associated with the
requester is empty; or the corresponding current value of o the CBOR simple value null (0xf6), if the update collection
'last_index' otherwise. associated with the requester is empty; or, otherwise
o the corresponding current value of 'last_index'.
- All of the following hold: the update collection associated - All of the following hold: the update collection associated
with the requester is not empty; no wrap-around of its 'index' with the requester is not empty; no wraparound of the 'index'
value has occurred; and the 'cursor' query parameter has a value has occurred; and the 'cursor' query parameter has a
value strictly greater than the current 'last_index' on the value strictly greater than the current 'last_index' on the
update collection (see Section 6.2.1). update collection (see Section 6.2.1).
Within the Custom Problem Detail entry 'ace-trl-error', the Within the Custom Problem Detail entry 'ace-trl-error', the
value of the 'error-id' field MUST be set to 2 ("Out of bound value of the 'error-id' field MUST be set to 2 ("Out of bound
cursor value"), and the field 'cursor' MUST NOT be present. cursor value"), and the 'cursor' field MUST NOT be present.
7. Full Query of the TRL 7. 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 AS performs the following actions. for a full query of the TRL, the AS performs the following actions:
1. From the TRL, the AS builds a set HASHES such that: 1. From the TRL, the AS builds a HASHES set such that:
* If the requester is a registered device, HASHES specifies the * If the requester is a registered device, HASHES specifies the
token hashes currently in the TRL and associated with the token hashes currently in the TRL and associated with the
access tokens pertaining to that registered device. The AS access tokens pertaining to that registered device. The AS
can always use the authenticated identity of the registered can always use the authenticated identity of the registered
device to perform the necessary filtering on the TRL content. device to perform the necessary filtering on the TRL content.
* If the requester is an administrator, HASHES specifies all the * If the requester is an administrator, HASHES specifies all the
token hashes currently in the TRL. token hashes currently in the TRL.
2. The AS sends a 2.05 (Content) response to the requester. The 2. The AS sends a 2.05 (Content) response to the requester. The
response MUST have Content-Format "application/ace-trl+cbor". response MUST have Content-Format set to "application/ace-
The payload of the response is a CBOR map, which MUST be trl+cbor". The payload of the response is a CBOR map, which MUST
formatted as follows. be formatted as follows.
* The 'full_set' parameter MUST be included and specifies a CBOR * The 'full_set' parameter MUST be included and MUST encode a
array 'full_set_value'. Each element of 'full_set_value' is a CBOR array 'full_set_value'. Each element of 'full_set_value'
CBOR byte string, with value one of the token hashes from the is a CBOR byte string, whose value is one of the token hashes
set HASHES. If the set HASHES is empty, the 'full_set' from the HASHES set. If the HASHES set is empty, the
parameter specifies the empty CBOR array. 'full_set' parameter specifies the empty CBOR array.
The CBOR array MUST be treated as a set, i.e., the order of The CBOR array MUST be treated as a set, i.e., the order of
its elements has no meaning. its elements has no meaning.
* The 'cursor' parameter MUST be included if the AS supports * The 'cursor' parameter MUST be included if the AS supports
both diff queries and the related "Cursor" extension (see both diff queries and the related "Cursor" extension (see
Section 6.2 and Section 6.2.1). Its value is set as specified Sections 6.2 and 6.2.1). Its value is set as specified in
in Section 9.1, and provides the requester with information Section 9.1 and provides the requester with information for
for performing a follow-up diff query using the "Cursor" sending a new request that asks the AS to perform a follow-up
extension (see Section 9.2). diff query using the "Cursor" extension (see Section 9.2).
If the AS does not support both diff queries and the "Cursor" If the AS does not support both diff queries and the "Cursor"
extension, this parameter MUST NOT be included. In case the extension, this parameter MUST NOT be included. In case the
requester does not support both diff queries and the "Cursor" requester does not support both diff queries and the "Cursor"
extension, it MUST silently ignore the 'cursor' parameter if extension, it MUST silently ignore the 'cursor' parameter if
present. present.
Figure 6 provides the CDDL definition [RFC8610] of the CBOR array Figure 6 provides the CDDL definition [RFC8610] of the CBOR array
'full_set_value' specified in the response from the AS, as value of 'full_set_value' specified in the response from the AS as the value
the 'full_set' parameter. of the 'full_set' parameter.
token_hash = bytes token_hash = bytes
full_set_value = [* token_hash] full_set_value = [* token_hash]
Figure 6: CDDL definition of 'full_set_value' Figure 6: CDDL Definition of 'full_set_value'
Figure 7 shows an example response from the AS, following a full Figure 7 shows an example of a response from the AS following a full
query request to the TRL endpoint. In this example, the AS does not query request to the TRL endpoint. In this example, the AS does not
support diff queries nor the "Cursor" extension, hence the 'cursor' support diff queries nor the "Cursor" extension; hence the 'cursor'
parameter is not included in the payload of the response. Also, full parameter is not included in the payload of the response. Also, full
token hashes are omitted for brevity. token hashes are omitted for brevity.
Header: Content (Code=2.05) Header: Content (Code=2.05)
Content-Format: application/ace-trl+cbor Content-Format: 262 (application/ace-trl+cbor)
Payload: Payload:
{ {
e'full_set' : [ / full_set / 0: [
h'01fa51cc...4819', / elided for brevity / h'01fa51cc...4819', / elided for brevity /
h'01748190...223d' / elided for brevity / h'01748190...223d' / elided for brevity /
] ]
} }
Figure 7: Example of response following a full query request to Figure 7: Example of a Response Following a Full Query Request to
the TRL endpoint the TRL Endpoint
8. Diff Query of the TRL 8. 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 AS performs the following actions. for a diff query of the TRL, the AS performs the following actions:
Note that, if the AS supports both diff queries and the related Note that, if the AS supports both diff queries and the related
"Cursor" extension, the steps 3 and 4 defined below are extended as "Cursor" extension, Steps 3 and 4 defined below are extended as
defined in Section 9.2. defined in Section 9.2.
1. The AS defines the positive integer NUM as follows. If the value 1. The AS defines the positive integer NUM as follows: if the value
N specified in the 'diff' query parameter in the GET request is N specified in the 'diff' query parameter in the GET request is
equal to 0 or greater than the pre-defined positive integer MAX_N equal to 0 or greater than the predefined positive integer MAX_N
(see Section 6.2), then NUM takes the value of MAX_N. Otherwise, (see Section 6.2), then NUM takes the value of MAX_N. Otherwise,
NUM takes N. NUM takes N.
2. The AS determines U = min(NUM, SIZE), where SIZE <= MAX_N. In 2. The AS determines U = min(NUM, SIZE), where SIZE <= MAX_N. In
particular, SIZE is the number of diff entries currently stored particular, SIZE is the number of diff entries currently stored
in the requester's update collection. in the requester's update collection.
3. The AS prepares U diff entries. If U is equal to 0 (e.g., 3. The AS prepares U diff entries. If U is equal to 0 (e.g.,
because SIZE is equal to 0 at step 2), then no diff entries are because SIZE is equal to 0 at Step 2), then no diff entries are
prepared. prepared.
The prepared diff entries are related to the U most recent TRL The prepared diff entries are related to the U most recent TRL
updates pertaining to the requester, as maintained in the update updates pertaining to the requester, as maintained in the update
collection for that requester (see Section 6.2). In particular, collection for that requester (see Section 6.2). In particular,
the first diff entry refers to the most recent of such updates, the first diff entry refers to the most recent of such updates,
the second diff entry refers to the second from last of such the second diff entry refers to the second-to-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 'trl_patch' set of token hashes, a. A trl_patch set of token hashes encoded as a CBOR array
encoded as a CBOR array 'removed'. Each element of the array 'removed'. Each element of the array is a CBOR byte string,
is a CBOR byte string, with value the token hash of an access whose value is the token hash of an access token such that it
token such that: it pertained to the requester; and it was pertains to the requester and was removed from the TRL during
removed from the TRL during the update associated with the the update associated with the diff entry.
diff entry.
* The second element is a 'trl_patch' set of token hashes, b. A trl_patch set of token hashes encoded as a CBOR array
encoded as a CBOR array 'added'. Each element of the array is 'added'. Each element of the array is a CBOR byte string,
a CBOR byte string, with value the token hash of an access whose value is the token hash of an access token such that it
token such that: it pertains to the requester; and it was pertains to the requester and was added to the TRL during the
added to the TRL during the update associated with the diff update associated with the diff entry.
entry.
The CBOR arrays 'removed' and 'added' MUST be treated as sets, The CBOR arrays 'removed' and 'added' MUST be treated as sets,
i.e., the order of their elements has no meaning. i.e., the order of their elements has no meaning.
4. The AS prepares a 2.05 (Content) response for the requester. The 4. The AS prepares a 2.05 (Content) response for the requester. The
response MUST have Content-Format "application/ace-trl+cbor". response MUST have Content-Format set to "application/ace-
The payload of the response is a CBOR map, which MUST be trl+cbor". The payload of the response is a CBOR map, which MUST
formatted as follows. be formatted as follows:
* The 'diff_set' parameter MUST be present and specifies a CBOR * The 'diff_set' parameter MUST be present and MUST encode a
array 'diff_set_value' of U elements. Each element of CBOR array 'diff_set_value' of U elements. Each element of
'diff_set_value' specifies one of the CBOR arrays 'diff_entry' 'diff_set_value' specifies one of the CBOR arrays 'diff_entry'
prepared above as a diff entry. Note that U might have value prepared above as a diff entry. Note that U might have a
0, in which case 'diff_set_value' is the empty CBOR array. value of 0; in this case, 'diff_set_value' is the empty CBOR
array.
Within 'diff_set_value', the CBOR arrays 'diff_entry' MUST be Within 'diff_set_value', the 'diff_entry' CBOR arrays MUST be
sorted to reflect the corresponding updates to the TRL in 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_set_value' relates to the most recent TRL element of 'diff_set_value' relates to the most recent TRL
update pertaining to the requester. The second 'diff_entry' update pertaining to the requester. The second 'diff_entry'
element relates to the second from last most recent TRL update element relates to the second-to-last most recent TRL update
pertaining to the requester, and so on. pertaining to the requester, and so on.
* The 'cursor' parameter and the 'more' parameter MUST be * The 'cursor' parameter and the 'more' parameter MUST be
included if the AS supports both diff queries and the related included if the AS supports both diff queries and the related
"Cursor" extension (see Section 6.2.1). Their values are set "Cursor" extension (see Section 6.2.1). Their values are set
as specified in Section 9.2, and provide the requester with as specified in Section 9.2 and provide the requester with
information for performing a follow-up query of the TRL (see information for sending a new request that asks the AS to
Section 9.2). perform a follow-up query of the TRL (see Section 9.2).
In case the AS supports diff queries but not the "Cursor" In case the AS supports diff queries but not the "Cursor"
extension, these parameters MUST NOT be included. In case the extension, these parameters MUST NOT be included. In case the
requester supports diff queries but not the "Cursor" requester supports diff queries but not the "Cursor"
extension, it MUST silently ignore the 'cursor' parameter and extension, the requester MUST silently ignore the 'cursor'
the 'more' parameter if present. parameter and the 'more' parameter, if present.
Figure 8 provides the CDDL definition [RFC8610] of the CBOR array Figure 8 provides the CDDL definition [RFC8610] of the CBOR array
'diff_set_value' specified in the response from the AS, as value of 'diff_set_value' specified in the response from the AS, as the value
the 'diff_set' parameter. of the 'diff_set' parameter.
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_set_value = [* diff_entry] diff_set_value = [* diff_entry]
Figure 8: CDDL definition of 'diff_set_value' Figure 8: CDDL Definition of 'diff_set_value'
Figure 9 shows an example response from the AS, following a diff Figure 9 shows an example of a response from the AS following a diff
query request to the TRL endpoint, where U = 3 diff entries are query request to the TRL endpoint, where U = 3 diff entries are
specified. In this example, the AS does not support the "Cursor" included. In this example, the AS does not support the "Cursor"
extension, hence the 'cursor' parameter and the 'more' parameter are extension; hence, the 'cursor' parameter and the 'more' parameter are
not included in the payload of the response. Also, full token hashes not included in the payload of the response. Also, full token hashes
are omitted for brevity. are omitted for brevity.
Header: Content (Code=2.05) Header: Content (Code=2.05)
Content-Format: application/ace-trl+cbor Content-Format: 262 (application/ace-trl+cbor)
Payload: Payload:
{ {
e'diff_set' : [ / diff_set / 1: [
[ [
[ h'01fa51cc...0f6a', / elided for brevity / [ h'01fa51cc...0f6a', / elided for brevity /
h'01748190...8bce' / elided for brevity / h'01748190...8bce' / elided for brevity /
], ],
[ h'01cdf1ca...563d', / elided for brevity / [ h'01cdf1ca...563d', / elided for brevity /
h'01be41a6...a057' / elided for brevity / h'01be41a6...a057' / elided for brevity /
] ]
], ],
[ [
[ h'0144dd12...77bc', / elided for brevity / [ h'0144dd12...77bc', / elided for brevity /
skipping to change at page 31, line 51 skipping to change at line 1438
], ],
[ [
[], [],
[ h'01ca986f...ffc1', / elided for brevity / [ h'01ca986f...ffc1', / elided for brevity /
h'01fe1a2b...def0' / elided for brevity / h'01fe1a2b...def0' / elided for brevity /
] ]
] ]
] ]
} }
Figure 9: Example of response following a diff query request to Figure 9: Example of Response Following a Diff Query Request to
the TRL endpoint the TRL Endpoint
Appendix A discusses how performing a diff query of the TRL is in Appendix A discusses how performing a diff query of the TRL is, in
fact a usage example of the Series Transfer Pattern defined in fact, a usage example of the Series Transfer Pattern defined in
[I-D.bormann-t2trg-stp]. [STP].
9. Response Messages when Using the "Cursor" Extension 9. Response Messages when Using the "Cursor" Extension
If the AS supports both diff queries and the "Cursor" extension, it If the AS supports both diff queries and the "Cursor" extension, it
composes a response to a full query request or diff query request as composes a response to a full query request or diff query request as
defined in Section 9.1 and Section 9.2, respectively. defined in Sections 9.1 and 9.2, respectively.
The exact format of the response depends on the request being a full The exact format of the response depends on:
query or diff query request, on the presence of the 'diff' and
'cursor' query parameters and their values in the diff query request, * the request being a full query or diff query request,
and on the current status of the update collection associated with
the requester. * the presence of the 'diff' and 'cursor' query parameters and their
values in the diff query request, and
* the current status of the update collection associated with the
requester.
Error handling and the possible resulting error responses are as Error handling and the possible resulting error responses are as
defined in Section 6.3. defined in Section 6.3.
9.1. Response to Full Query 9.1. Response to Full Query
When processing a full query request to the TRL endpoint, the AS When processing a full query request to the TRL endpoint, the AS
composes a response as defined in Section 7. composes a response as defined in Section 7.
In particular, the 'cursor' parameter included in the CBOR map In particular, the 'cursor' parameter included in the CBOR map
carried in the response payload specifies either the CBOR simple carried in the response payload specifies either the CBOR simple
value null (0xf6) or a CBOR unsigned integer. value null (0xf6) or a CBOR unsigned integer.
The 'cursor' parameter MUST specify the CBOR simple value null in The 'cursor' parameter MUST encode the CBOR simple value null (0xf6)
case there are currently no TRL updates pertaining to the requester, in case there are currently no TRL updates pertaining to the
i.e., the update collection for that requester is empty. This is the requester, i.e., the update collection for that requester is empty.
case from when the requester registers at the AS until the first This is the case from when the requester registers at the AS until
update pertaining to that requester occurs to the TRL. the first update pertaining to that requester occurs to the TRL.
Otherwise, the 'cursor' parameter MUST specify a CBOR unsigned Otherwise, the 'cursor' parameter MUST encode a CBOR unsigned
integer. This MUST take the 'index' value of the last series item in integer. The unsigned integer MUST take the 'index' value of the
the update collection associated with the requester (see last series item in the update collection associated with the
Section 6.2.1), as corresponding to the most recent TRL update requester (see Section 6.2.1) as corresponding to the most recent TRL
pertaining to the requester. Such a value is in fact the current update pertaining to the requester. In fact, such a value is the
value of 'last_index' for the update collection associated with the current value of 'last_index' for the update collection associated
requester. with the requester.
9.2. Response to Diff Query 9.2. Response to Diff Query
When processing a diff query request to the TRL endpoint, the AS When processing a diff query request to the TRL endpoint, the AS
composes a response as defined in the following. composes a response as defined in the following subsections.
9.2.1. Empty Collection 9.2.1. Empty Update Collection
If the update collection associated with the requester has no If the update collection associated with the requester has no
elements, the AS returns a 2.05 (Content) response. The response elements, the AS returns a 2.05 (Content) response. The response
MUST have Content-Format "application/ace-trl+cbor" and its payload MUST have Content-Format set to "application/ace-trl+cbor", and its
MUST be a CBOR map formatted as follows. payload MUST be a CBOR map formatted as follows:
* The 'diff_set' parameter MUST be included and specifies the empty * The 'diff_set' parameter MUST be included and MUST encode the
CBOR array. empty CBOR array.
* The 'cursor' parameter MUST be included and specifies the CBOR * The 'cursor' parameter MUST be included and MUST encode the CBOR
simple value null (0xf6). simple value null (0xf6).
* The 'more' parameter MUST be included and specifies the CBOR * The 'more' parameter MUST be included and MUST encode the CBOR
simple value false (0xf4). simple value false (0xf4).
Note that the above applies when the update collection associated Note that the above applies when the update collection associated
with the requester has no elements, regardless of whether the with the requester has no elements, regardless of whether or not the
'cursor' query parameter is included or not in the diff query 'cursor' query parameter is included in the diff query request and
request, and irrespective of the specified unsigned integer value if irrespective of the specified unsigned integer value if present.
present.
9.2.2. Cursor Not Specified in the Diff Query Request 9.2.2. Cursor Not Included in the Diff Query Request
If the update collection associated with the requester is not empty If the update collection associated with the requester is not empty
and the diff query request does not include the 'cursor' query and the diff query request does not include the 'cursor' query
parameter, the AS performs the actions defined in Section 8, with the parameter, the AS performs the actions defined in Section 8, with the
following differences. following differences:
* At step 3, the AS considers the value MAX_DIFF_BATCH (see * At Step 3, the AS considers the value MAX_DIFF_BATCH (see
Section 6.2.1), and prepares L = min(U, MAX_DIFF_BATCH) diff Section 6.2.1) and prepares L = min(U, MAX_DIFF_BATCH) diff
entries. entries.
If U <= MAX_DIFF_BATCH, the prepared diff entries are the last If U <= MAX_DIFF_BATCH, the prepared diff entries are the last
series items in the update collection associated with the series items in the update collection associated with the
requester, corresponding to the L most recent TRL updates requester, corresponding to the L most recent TRL updates
pertaining to the requester. pertaining to the requester.
If U > MAX_DIFF_BATCH, the prepared diff entries are the eldest of If U > MAX_DIFF_BATCH, the prepared diff entries are the eldest of
the last U series items in the update collection associated with the last U series items in the update collection associated with
the requester, as corresponding to the first L of the U most the requester, as corresponding to the first L of the U most
recent TRL updates pertaining to the requester. recent TRL updates pertaining to the requester.
* At step 4, the CBOR map to carry in the payload of the 2.05 * At Step 4, the CBOR map to carry in the payload of the 2.05
(Content) response MUST be formatted as follows. (Content) response MUST be formatted as follows:
- The 'diff_set' parameter MUST be present and specifies a CBOR - The 'diff_set' parameter MUST be present and MUST encode a CBOR
array 'diff_set_value' of L elements. Each element of array 'diff_set_value' of L elements. Each element of
'diff_set_value' specifies one of the CBOR arrays 'diff_entry' 'diff_set_value' specifies one of the CBOR arrays 'diff_entry'
prepared as a diff entry. prepared as a diff entry.
- The 'cursor' parameter MUST be present and specifies a CBOR - The 'cursor' parameter MUST be present and MUST encode a CBOR
unsigned integer. This MUST take the 'index' value of the unsigned integer. The unsigned integer MUST take the 'index'
series item of the update collection included as first diff value of the series item of the update collection included as
entry in the 'diff_set_value' CBOR array, which is specified by first diff entry in the 'diff_set_value' CBOR array, which is
the 'diff_set' parameter. That is, the 'cursor' parameter specified by the 'diff_set' parameter. That is, the 'cursor'
takes the 'index' value of the series item in the update parameter takes the 'index' value of the series item in the
collection corresponding to the most recent TRL update update collection corresponding to the most recent TRL update
pertaining to the requester and returned in this diff query pertaining to the requester and returned in this diff query
response. response.
Note that the 'cursor' parameter takes the same 'index' value Note that the 'cursor' parameter takes the same 'index' value
of the last series item in the update collection when U <= of the last series item in the update collection when U <=
MAX_DIFF_BATCH. MAX_DIFF_BATCH.
- The 'more' parameter MUST be present and MUST specify the CBOR - The 'more' parameter MUST be present. The parameter MUST
simple value false (0xf4) if U <= MAX_DIFF_BATCH, or the CBOR encode the CBOR simple value false (0xf4) if U <=
simple value true (0xf5) otherwise. MAX_DIFF_BATCH; otherwise, it MUST encode the CBOR simple value
true (0xf5).
If the 'more' parameter in the payload of the received 2.05 (Content) If the 'more' parameter in the payload of the received 2.05 (Content)
response has value true, the requester can send a follow-up diff response has a value of true, the requester can send a follow-up diff
query request including the 'cursor' query parameter, with the same query request including the 'cursor' query parameter with the same
value of the 'cursor' parameter specified in this diff query value of the 'cursor' parameter specified in this diff query
response. As defined in Section 9.2.3, this would result in the AS response. As defined in Section 9.2.3, this would result in the AS
transferring the following subset of series items as diff entries, transferring the following subset of series items as diff entries,
thus resuming from where interrupted in the previous transfer. thus resuming from where interrupted in the previous transfer.
9.2.3. Cursor Specified in the Diff Query Request 9.2.3. Cursor Included in the Diff Query Request
If the update collection associated with the requester is not empty If the update collection associated with the requester is not empty
and the diff query request includes the 'cursor' query parameter with and the diff query request includes the 'cursor' query parameter with
value P, the AS proceeds as follows, depending on which of the value P, the AS proceeds as follows, depending on which of the
following two cases hold. following two cases hold:
* Case A - The series item X with 'index' having value P and the Case A: The series item X with 'index' having value P and the series
series item Y with 'index' having value (P + 1) % (MAX_INDEX + 1) item Y with 'index' having value (P + 1) % (MAX_INDEX + 1)
are both not found in the update collection associated with the are both not found in the update collection associated with
requester. This occurs when the item Y (and possibly further ones the requester. This occurs when the item Y (and possibly
after it) has been previously removed from the update collection further ones after it) has been previously removed from the
for that requester (see step 5 at Section 6.2). update collection for that requester (see Step 5 at
Section 6.2).
In this case, the AS returns a 2.05 (Content) response. The In this case, the AS returns a 2.05 (Content) response. The
response MUST have Content-Format "application/ace-trl+cbor" and response MUST have Content-Format set to "application/ace-
its payload MUST be a CBOR map formatted as follows. trl+cbor", and its payload MUST be a CBOR map formatted as
follows:
- The 'diff_set' parameter MUST be included and specifies the * The 'diff_set' parameter MUST be included and MUST encode
empty CBOR array. the empty CBOR array.
- The 'cursor' parameter MUST be included and specifies the CBOR * The 'cursor' parameter MUST be included and MUST encode
simple value null (0xf6). the CBOR simple value null (0xf6).
- The 'more' parameter MUST be included and specifies the CBOR * The 'more' parameter MUST be included and MUST encode the
simple value true (0xf5). CBOR simple value true (0xf5).
With the combination ('cursor', 'more') = (null, true), the AS is With the combination ('cursor', 'more') = (null, true), the
indicating that the update collection is in fact not empty, but AS is indicating that the update collection is, in fact, not
that one or more series items have been lost due to their removal. empty, but that one or more series items have been lost due
These include the item with 'index' value (P + 1) % (MAX_INDEX + to their removal. These include the item with 'index' value
1), that the requester wished to obtain as the first one following (P + 1) % (MAX_INDEX + 1) that the requester wished to
the specified reference point with 'index' value P. 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
a new full query request to the AS. A successful response SHOULD send a new full query request to the AS. A
provides the requester with the full, current pertaining subset of successful response provides the requester with the full
the TRL, as well as with a valid value of the 'cursor' parameter current pertaining subset of the TRL as well as a valid
(see Section 9.1) to be possibly used as query parameter in a value of the 'cursor' parameter (see Section 9.1) to be,
following diff query request. possibly, used as query parameter in a following diff query
request.
* Case B - The series item X with 'index' having value P is found in Case B: The series item X with 'index' having value P is found in
the update collection associated with the requester; or the series the update collection associated with the requester, or
item X is not found and the series item Y with 'index' having instead the series item X is not found and the series item Y
value (P + 1) % (MAX_INDEX + 1) is found in the update collection with 'index' having value (P + 1) % (MAX_INDEX + 1) is found
associated with the requester. in the update collection associated with the requester.
In this case, the AS performs the actions defined in Section 8, In this case, the AS performs the actions defined in
with the following differences. Section 8 with the following differences:
- At step 3, the AS considers the value MAX_DIFF_BATCH (see * At Step 3, the AS considers the value MAX_DIFF_BATCH (see
Section 6.2.1), and prepares L = min(SUB_U, MAX_DIFF_BATCH) Section 6.2.1) and prepares L = min(SUB_U,
diff entries, where SUB_U = min(NUM, SUB_SIZE), and SUB_SIZE is MAX_DIFF_BATCH) diff entries, where SUB_U = min(NUM,
the number of series items in the update collection starting SUB_SIZE) and SUB_SIZE is the number of series items in
from and including the series item added immediately after X. the update collection starting from and including the
If L is equal to 0 (e.g., because SUB_U is equal to 0), then no series item added immediately after X. If L is equal to
diff entries are prepared. 0 (e.g., because SUB_U is equal to 0), then no diff
entries are prepared.
If SUB_U <= MAX_DIFF_BATCH, the prepared diff entries are the If SUB_U <= MAX_DIFF_BATCH, the prepared diff entries are
last series items in the update collection associated with the the last series items in the update collection associated
requester, corresponding to the L most recent TRL updates with the requester, corresponding to the L most recent
pertaining to the requester. TRL updates pertaining to the requester.
If SUB_U > MAX_DIFF_BATCH, the prepared diff entries are the If SUB_U > MAX_DIFF_BATCH, the prepared diff entries are
eldest of the last SUB_U series items in the update collection the eldest of the last SUB_U series items in the update
associated with the requester, corresponding to the first L of collection associated with the requester, corresponding
the SUB_U most recent TRL updates pertaining to the requester. to the first L of the SUB_U most recent TRL updates
pertaining to the requester.
- At step 4, the CBOR map to carry in the payload of the 2.05 * At Step 4, the CBOR map to carry in the payload of the
(Content) response MUST be formatted as follows. 2.05 (Content) response MUST be formatted as follows:
o The 'diff_set' parameter MUST be present and specifies a - The 'diff_set' parameter MUST be present and MUST
CBOR array 'diff_set_value' of L elements. Each element of encode a CBOR array 'diff_set_value' of L elements.
'diff_set_value' specifies one of the CBOR arrays Each element of 'diff_set_value' specifies one of the
'diff_entry' prepared as a diff entry. Note that L might CBOR arrays 'diff_entry' prepared as a diff entry.
have value 0, in which case 'diff_set_value' is the empty Note that L might have value 0, in which case
CBOR array. 'diff_set_value' is the empty CBOR array.
o The 'cursor' parameter MUST be present and MUST specify a - The 'cursor' parameter MUST be present and MUST encode
CBOR unsigned integer. In particular: a CBOR unsigned integer. In particular:
+ If L is equal to 0, i.e., the series item X is the last o If L is equal to 0, i.e., the series item X is the
one in the update collection, then the 'cursor' parameter last one in the update collection, then the
MUST take the same 'index' value of the last series item 'cursor' parameter MUST take the same 'index' value
in the update collection. Such a value is in fact the of the last series item in the update collection.
current value of 'last_index' for the update collection. In fact, such a value is the current value of
'last_index' for the update collection.
+ If L is different than 0, then the 'cursor' parameter o If L is different than 0, then the 'cursor'
MUST take the 'index' value of the series element of the parameter MUST take the 'index' value of the series
update collection included as first diff entry in the element of the update collection included as first
'diff_set' CBOR array. That is, the 'cursor' parameter diff entry in the 'diff_set' CBOR array. That is,
takes the 'index' value of the series item in the update the 'cursor' parameter takes the 'index' value of
collection corresponding to the most recent TRL update the series item in the update collection
pertaining to the requester and returned in this diff corresponding to the most recent TRL update
query response. pertaining to the requester and returned in this
diff query response.
Note that the 'cursor' parameter takes the same 'index' Note that the 'cursor' parameter takes the same
value of the last series item in the update collection when 'index' value of the last series item in the update
SUB_U <= MAX_DIFF_BATCH. collection when SUB_U <= MAX_DIFF_BATCH.
o The 'more' parameter MUST be present and MUST specify the - The 'more' parameter MUST be present. The parameter
CBOR simple value false (0xf4) if SUB_U <= MAX_DIFF_BATCH, MUST encode the CBOR simple value false (0xf4) if
or the CBOR simple value true (0xf5) otherwise. SUB_U <= MAX_DIFF_BATCH; otherwise, it MUST encode the
CBOR simple value true (0xf5).
If the 'more' parameter in the payload of the received 2.05 If the 'more' parameter in the payload of the received 2.05
(Content) response has value true, the requester can send a (Content) response has value true, the requester can send a
follow-up diff query request including the 'cursor' query follow-up diff query request including the 'cursor' query
parameter, with the same value of the 'cursor' parameter specified parameter with the same value of the 'cursor' parameter
in this diff query response. This would result in the AS specified in this diff query response. This would result in
transferring the following subset of series items as diff entries, the AS transferring the following subset of series items as
thus resuming from where interrupted in the previous transfer. diff entries, thus resuming from where interrupted in the
previous transfer.
10. Registration at the Authorization Server 10. Registration at the Authorization Server
During the registration process at the AS, an administrator or a During the registration process at the AS, an administrator or a
registered device receives the following information as part of the registered device receives the following information as part of the
registration response. registration response:
* The url-path to the TRL endpoint at the AS. * The url-path to the TRL endpoint at the AS.
* The hash function used to compute token hashes. This is specified * The hash function used to compute token hashes. This is specified
by identifying an entry in the "Named Information Hash Algorithm" by identifying an entry in the "Named Information Hash Algorithm
Registry [Named.Information.Hash.Algorithm]. The specific means Registry" [IANA.Hash.Algorithms]. The specific means for this is
for this is outside the scope of this document. outside the scope of this document.
* A positive integer MAX_N, if the AS supports diff queries of the * A positive integer MAX_N, if the AS supports diff queries of the
TRL (see Section 6.2 and Section 8). TRL (see Sections 6.2 and 8).
* A positive integer MAX_DIFF_BATCH, if the AS supports diff queries * A positive integer MAX_DIFF_BATCH, if the AS supports diff queries
of the TRL as well as the related "Cursor" extension (see of the TRL as well as the related "Cursor" extension (see Sections
Section 6.2.1 and Section 9). 6.2.1 and 9).
Once completed the registration process, the AS maintains the Once the registration process is completed, the AS maintains the
registration and related information until a possible deregistration registration and related information until a possible deregistration
occurs, hence keeping track of active administrators and registered occurs, hence keeping track of active administrators and registered
devices. The particular way to achieve this is implementation- devices. The particular way to achieve this is implementation
specific. Such a mechanism to maintain registrations is enforced in specific. In any case, such a mechanism to maintain registrations is
any case at the AS, in order to ensure that requests sent by clients enforced at the AS in order to ensure that requests sent by clients
to the /token endpoint (see Section 5.8 of [RFC9200]) and by RSs to to the /token endpoint (see Section 5.8 of [RFC9200]) and by RSs to
the /introspect endpoint (see Section 5.9 of [RFC9200]) are processed the /introspect endpoint (see Section 5.9 of [RFC9200]) are processed
as intended. as intended.
When communicating with one another, the registered devices and the When communicating with one another, the registered devices and the
AS have to use a secure communication association and be mutually AS have to use a secure communication association and be mutually
authenticated (see Section 5 of [RFC9200]). authenticated (see Section 5 of [RFC9200]).
In the same spirit, it MUST be ensured that communications between In the same spirit, communications between the AS and an
the AS and an administrator are mutually authenticated, encrypted and administrator MUST be ensured to be mutually authenticated,
integrity protected, as well as protected against message replay. encrypted, and integrity protected as well as protected against
message replay.
Before starting its registration process at the AS, an administrator Before starting its registration process at the AS, an administrator
has to establish such a secure communication association with the AS, has to establish such a secure communication association with the AS,
if they do not share one already. In particular, mutual if they do not share one already. In particular, mutual
authentication is REQUIRED during the establishment of the secure authentication is REQUIRED during the establishment of the secure
association. To this end, the administrator and the AS can rely, association. To this end, the administrator and the AS can rely,
e.g., on establishing a TLS or DTLS secure session with mutual e.g., on establishing a TLS or DTLS secure session with mutual
authentication [RFC8446][RFC9147], or an OSCORE Security Context authentication (see [RFC8446] and [RFC9147]) or an Object Security
for Constrained RESTful Environments (OSCORE) Security Context
[RFC8613] by running the authenticated key exchange protocol EDHOC [RFC8613] by running the authenticated key exchange protocol EDHOC
[RFC9528]. [RFC9528].
When receiving authenticated requests from the administrator for When receiving authenticated requests from the administrator for
accessing the TRL endpoint, the AS can always check whether the accessing the TRL endpoint, the AS can always check whether the
requester is authorized to take such a role, i.e., to access the requester is authorized to take such a role, i.e., to access the
content of the whole TRL. content of the whole TRL.
To this end, the AS may rely on a local access control list or To this end, the AS may rely on a local access control list or
similar, which specifies the authentication credentials of trusted, similar, which specifies the authentication credentials of trusted,
authorized administrators. In particular, the AS verifies the authorized administrators. In particular, the AS verifies the
requester to the TRL endpoint as an authorized administrator, only if requester to the TRL endpoint as an authorized administrator only if
the access control list includes the same authentication credential the access control list includes the same authentication credential
used by the requester when establishing the mutually-authenticated used by the requester when establishing the mutually authenticated
secure communication association with the AS. secure communication association with the AS.
Further details about the registration process at the AS are out of Further details about the registration process at the AS are out of
scope for this specification. Note that the registration process is scope for this specification. Note that the registration process is
also out of the scope of the ACE framework for Authentication and also out of the scope of the ACE framework (see Section 5.5 of
Authorization (see Section 5.5 of [RFC9200]). [RFC9200]).
11. Notification of Revoked Access Tokens 11. Notification of Revoked Access Tokens
Once registered at the AS, the administrator or registered device can Once registered at the AS, the administrator or a registered device
send a GET request to the TRL endpoint at the AS. The request can can send a GET request to the TRL endpoint at the AS. The request
express the wish for a full query (see Section 7) or a diff query can express the wish for a full query (see Section 7) or a diff query
(see Section 8) of the TRL. Also, the request can include the CoAP (see Section 8) of the TRL. Also, the request can include the CoAP
Observe Option set to 0 (register), in order to start an observation Observe Option set to 0 (register) in order to start an observation
of the TRL endpoint as per Section 3.1 of [RFC7641]. of the TRL endpoint as per Section 3.1 of [RFC7641].
In case the request is successfully processed, the AS replies with a In case the request is successfully processed, the AS replies with a
response specifying the CoAP response code 2.05 (Content). In 2.05 (Content) response. In particular, if the AS supports diff
particular, if the AS supports diff queries but not the "Cursor" queries but not the "Cursor" extension (see Sections 6.2 and 6.2.1),
extension (see Section 6.2 and Section 6.2.1), then the payload of then the payload of the response is formatted as defined in Sections
the response is formatted as defined in Section 7 or in Section 8, in 7 or 8, in case the GET request has yielded the execution of a full
case the GET request has yielded the execution of a full query or of query or of a diff query of the TRL, respectively. Instead, if the
a diff query of the TRL, respectively. Instead, if the AS supports AS supports both diff queries and the related "Cursor" extension,
both diff queries and the related "Cursor" extension, then the then the payload of the response is formatted as defined in
payload of the response is formatted as defined in Section 9. Section 9.
In case a requester does not receive a response from the TRL endpoint In case a requester does not receive a response from the TRL endpoint
or it receives an error response from the TRL endpoint, the requester or it receives an error response from the TRL endpoint, the requester
does not make any assumption or draw any conclusion regarding the does not make any assumptions or draw any conclusions regarding the
revocation or expiration of its pertaining access tokens. The revocation or expiration of its pertaining access tokens. The
requester MAY try again by sending a new request to the TRL endpoint. requester MAY try again by sending a new request to the TRL endpoint.
When the TRL is updated (see Section 5.1), the AS sends Observe When the TRL is updated (see Section 5.1), the AS sends Observe
notifications to the observers whose pertaining subset of the TRL has notifications to the observers whose pertaining subset of the TRL has
changed. Observe notifications are sent as per Section 4.2 of changed. Observe notifications are sent as per Section 4.2 of
[RFC7641]. If supported by the AS, an observer may configure the [RFC7641]. If supported by the AS, an observer may configure the
behavior according to which the AS sends those Observe notifications. behavior according to which the AS sends those Observe notifications.
To this end, a possible way relies on the conditional control To this end, a possible way relies on the conditional control
attribute "c.pmax" defined in [I-D.ietf-core-conditional-attributes], parameter "c.pmax" defined in [COND-PARAMETERS], which can be
which can be included as a "name=value" query parameter in an included as a "name=value" query parameter in an Observation Request.
Observation Request. This ensures that no more than c.pmax seconds This ensures that no more than c.pmax seconds elapse between two
elapse between two consecutive notifications sent to that observer, consecutive notifications sent to that observer, regardless of
regardless of whether the TRL has changed or not. whether or not the TRL has changed.
Following a first exchange with the AS, an administrator or a Following a first exchange with the AS, an administrator or a
registered device can send additional GET (Observation) requests to registered device can send additional GET requests to the TRL
the TRL endpoint at any time, analogously to what is defined above. endpoint at any time, analogously to what is defined above. When
When doing so, the requester towards the TRL endpoint can perform a doing so, the requester towards the TRL endpoint can ask the AS to
full query (see Section 7) or a diff query (see Section 8) of the perform a full query (see Section 7) or a diff query (see Section 8)
TRL. In the latter case, the requester can additionally rely on the of the TRL. In the latter case, the requester can additionally rely
"Cursor" extension (see Section 6.3 and Section 9.2). on the "Cursor" extension (see Sections 6.3 and 9.2).
As specified in Section 6.2, an AS supporting diff queries maintains As specified in Section 6.2, an AS supporting diff queries maintains
an update collection of maximum MAX_N series items for each an update collection of maximum MAX_N series items for each
administrator or registered device, hereafter referred to as administrator or registered device, hereafter referred to as a
requester. In particular, if an update collection includes MAX_N "requester". In particular, if an update collection includes MAX_N
series items, adding a further series item to that update collection series items, adding a further series item to that update collection
results in deleting the oldest series item from that update results in deleting the oldest series item from that update
collection. collection.
From then on, the requester associated with the update collection From then on, the requester associated with the update collection
will not be able to retrieve the deleted series item, when sending a will not be able to retrieve the deleted series item when sending a
new diff query request to the TRL endpoint. If that series item new diff query request to the TRL endpoint. If that series item
reflected the revocation of an access token pertaining to the reflected the revocation of an access token pertaining to the
requester, then the requester will not learn about that when requester, then the requester will not learn about that when
receiving the corresponding diff query response from the AS. receiving the corresponding diff query response from the AS.
Sending a diff query request specifically as an Observation request, Sending a diff query request specifically as an Observation Request,
and thus relying on Observe notifications, largely reduces the and, thus, relying on Observe notifications, largely reduces the
chances for a requester to miss updates occurred to its associated chances for a requester to miss updates that have occurred to its
update collection altogether. In turn, this relies on the requester associated update collection. In turn, this relies on the requester
successfully receiving the Observe notification responses from the successfully receiving the Observe notification responses from the
TRL (see also Section 14.3). TRL (see also Section 14.3).
In order to limit the amount of time during which the requester is In order to limit the amount of time during which the requester is
unaware of pertaining access tokens that have been revoked but are unaware of pertaining access tokens that have been revoked but are
not expired yet, a requester SHOULD NOT rely solely on diff query not expired yet, a requester SHOULD NOT rely solely on diff query
requests. In particular, a requester SHOULD also regularly send a requests. In particular, a requester SHOULD also regularly send a
full query request to the TRL endpoint according to a related full query request to the TRL endpoint according to a related
application policy. application policy.
skipping to change at page 40, line 20 skipping to change at line 1848
it MUST NOT delete the stored token hash after having expunged the it MUST NOT delete the stored token hash after having expunged the
associated access token. associated access token.
If an RS uses the method defined in this document with the AS that If an RS uses the method defined in this document with the AS that
has issued an access token, then the RS MUST NOT accept and store has issued an access token, then the RS MUST NOT accept and store
that access token if any of the following holds. that access token if any of the following holds.
* The token hash corresponding to the access token is among the * The token hash corresponding to the access token is among the
currently stored ones. currently stored ones.
* The access token is a CWT and any of the following holds. * The access token is a CWT and any of the following holds:
- The access token includes a non-empty "unprotected" field, - The access token includes a non-empty "unprotected" field,
i.e., the value of the field is not encoded as the empty CBOR i.e., the value of the field is not encoded as the empty CBOR
map (0xa0). This applies to: the top-level "unprotected" field map (0xa0). This applies to the top-level "unprotected" field
of the COSE object used for the CWT; the "unprotected" field of of the COSE object used for the CWT, the "unprotected" field of
each element of the "signatures" array; and the "unprotected" each element of the "signatures" array, and the "unprotected"
field of each element of any "recipients" array. field of each element of any "recipients" array.
- The received CBOR data item that embodies the access token does - The received CBOR data item that embodies the access token does
not comply with what is defined in Section 3. This concerns: not comply with what is defined in Section 3. This concerns:
the use of exactly two nested CBOR tags, where the outer tag is
the CWT CBOR tag and the inner tag is one of the COSE CBOR o the use of exactly two nested CBOR tags, where the outer tag
tags; the tag numbers encoded with the minimum possible length; is the CWT CBOR tag and the inner tag is one of the COSE
and the access token being the innermost tag content of the CBOR tags;
received CBOR data item.
o the tag numbers encoded with the minimum possible length;
and
o the access token being the innermost tag content of the
received CBOR data item.
- In the received CBOR data item that embodies the access token, - In the received CBOR data item that embodies the access token,
the inner tag has a tag number that is not consistent with the the inner tag has a tag number that is not consistent with the
actual COSE data item to process. For instance, the inner tag actual COSE data item to process. For instance, the inner tag
number is 16 (COSE_Encrypt0), but the CWT is actually a number is 16 (COSE_Encrypt0) but the CWT is actually a
COSE_Sign data item. COSE_Sign data item.
* The access token relies on a JSON object for encoding its claims, * The access token relies on a JSON object for encoding its claims,
but it is not a JWT [RFC7519] and any of the following holds. but it is not a JWT [RFC7519] and any of the following holds:
- The access token uses the JWS JSON Serialization from - The access token uses the JWS JSON Serialization from [RFC7515]
[RFC7515], and it includes the JWS Unprotected Header. and includes the JWS Unprotected Header.
- The access token uses the JWE JSON Serialization from - The access token uses the JWE JSON Serialization from [RFC7516]
[RFC7516], and it includes the JWE Shared Unprotected Header and includes the JWE Shared Unprotected Header and/or includes
and/or includes the "header" member in any of the elements of the "header" member in any of the elements of the "recipients"
the "recipients" array. array.
An RS MUST store the token hash th1 corresponding to an access token An RS MUST store the token hash th1 corresponding to an access token
t1 until both the following conditions hold. t1 until both the following conditions hold:
* The RS has received and seen t1, irrespective of having accepted * The RS has received and seen t1, irrespective of having accepted
and stored it. and stored it.
* The RS has gained knowledge that t1 has expired. This can be * The RS has gained knowledge that t1 has expired. This can be
achieved, e.g., through the following means. achieved, e.g., through the following means:
- A response from the TRL endpoint indicating that t1 has expired - A response from the TRL endpoint indicating that t1 has expired
after its earlier revocation, i.e., the token hash th1 has been after its earlier revocation, i.e., the token hash th1 has been
removed from the TRL. This can be indicated, for instance, in removed from the TRL. This can be indicated, for instance, in
a response from the TRL endpoint following a diff query of the a response from the TRL endpoint following a diff query of the
TRL (see Section 8). TRL (see Section 8).
- The value of the 'exp' claim specified in t1 indicates that t1 - The value of the 'exp' claim specified in t1 indicates that t1
has expired. has expired.
skipping to change at page 41, line 37 skipping to change at line 1919
- The result of token introspection performed on t1 (see - The result of token introspection performed on t1 (see
Section 5.9 of [RFC9200]), if supported by both the RS and the Section 5.9 of [RFC9200]), if supported by both the RS and the
AS. AS.
The RS MUST NOT delete the stored token hashes whose corresponding The RS MUST NOT delete the stored token hashes whose corresponding
access tokens do not fulfill both the two conditions above, unless it access tokens do not fulfill both the two conditions above, unless it
becomes necessary due to memory limitations. In such a case, the RS becomes necessary due to memory limitations. In such a case, the RS
MUST delete the earliest stored token hashes first. MUST delete the earliest stored token hashes first.
Retaining the stored token hashes as specified above limits the Retaining the stored token hashes as specified above limits the
impact from a (dishonest) client whose pertaining access token: i) impact from a (dishonest) client whose pertaining access token:
specifies the 'exi' claim; ii) is uploaded at the RS for the first
time after it has been revoked and later expired; and iii) has the
sequence number encoded in the 'cti' claim (for CWTs) or in the 'jti'
claim (for JWTs) greater than the highest sequence number among the
expired access tokens specifying the 'exi' claim for the RS (see
Section 5.10.3 of [RFC9200]). That is, the RS would not accept such
a revoked and expired access token as long as it stores the
corresponding token hash.
In order to further limit such a risk, when receiving an access token 1. includes the 'exi' claim,
that specifies the 'exi' claim and for which a corresponding token
hash is not stored, the RS can introspect the access token (see 2. is uploaded at the RS for the first time after it has been
Section 5.9 of [RFC9200]), if token introspection is implemented by revoked and later expired, and
both the RS and the AS.
3. has the sequence number encoded in the 'cti' claim (for CWTs) or
in the 'jti' claim (for JWTs) greater than the highest sequence
number among the expired access tokens including the 'exi' claim
for the RS (see Section 5.10.3 of [RFC9200]).
That is, the RS would not accept such a revoked and expired access
token as long as it stores the corresponding token hash.
This risk can be further limited. Specifically, if token
introspection is implemented by both the RS and the AS, the RS can
introspect the access token (see Section 5.9 of [RFC9200]) when
receiving an access token that includes the 'exi' claim and for which
a corresponding token hash is not stored.
When, due to the stored and corresponding token hash th2, an access When, due to the stored and corresponding token hash th2, an access
token t2 that includes the 'exi' claim is expunged or is not accepted token t2 that includes the 'exi' claim is expunged or is not accepted
upon its upload, the RS retrieves the sequence number sn2 encoded in upon its upload, the RS retrieves the sequence number sn2 encoded in
the 'cti' claim (for CWTs) or in the 'jti' claim (for JWTs) (see the 'cti' claim (for CWTs) or in the 'jti' claim (for JWTs) (see
Section 5.10.3 of [RFC9200]). Then, the RS stores sn2 as associated Section 5.10.3 of [RFC9200]). Then, the RS stores sn2 as associated
with th2. If expunging or not accepting t2 yields the deletion of with th2. If expunging or not accepting t2 yields the deletion of
th2, then the RS MUST associate sn2 with th2 before continuing with th2, then the RS MUST associate sn2 with th2 before continuing with
the deletion of th2. the deletion of th2.
When deleting any token hash, the RS checks whether the token hash is When deleting any token hash, the RS checks whether the token hash is
associated with a sequence number sn_th. In such a case, the RS associated with a sequence number sn_th. In such a case, the RS
checks whether sn_th is greater than the highest sequence number sn* checks whether sn_th is greater than the highest sequence number sn*
among the expired access tokens specifying the 'exi' claim for the among the expired access tokens including the 'exi' claim for the RS.
RS. If that is the case, sn* MUST take the value of sn_th. If that is the case, sn* MUST take the value of sn_th.
By virtue of what is defined in Section 5.10.3 of [RFC9200], this By virtue of what is defined in Section 5.10.3 of [RFC9200], this
ensures that, following the deletion of the token hash associated ensures that, following the deletion of the token hash associated
with an access token specifying the 'exi' claim and uploaded for the with an access token including the 'exi' claim and uploaded for the
first time after it has been revoked and later expired, the RS will first time after it has been revoked and later expired, the RS will
not accept the access token at that point in time or in the future. not accept the access token at that point in time or in the future.
12. ACE Token Revocation List Parameters 12. ACE Token Revocation List Parameters
This specification defines a number of parameters that can be This specification defines a number of parameters that can be
transported in the response from the TRL endpoint, when the response transported in the response from the TRL endpoint, when the response
payload is a CBOR map. Note that such a response MUST use the payload is a CBOR map. Note that such a response MUST use the
Content-Format "application/ace-trl+cbor" defined in Section 15.2 of Content-Format "application/ace-trl+cbor" defined in Section 15.2 of
this specification. this specification.
skipping to change at page 42, line 51 skipping to change at line 1986
+==========+==========+==========================+ +==========+==========+==========================+
| full_set | 0 | array | | full_set | 0 | array |
+----------+----------+--------------------------+ +----------+----------+--------------------------+
| diff_set | 1 | array | | diff_set | 1 | array |
+----------+----------+--------------------------+ +----------+----------+--------------------------+
| cursor | 2 | Null or unsigned integer | | cursor | 2 | Null or unsigned integer |
+----------+----------+--------------------------+ +----------+----------+--------------------------+
| more | 3 | True or False | | more | 3 | True or False |
+----------+----------+--------------------------+ +----------+----------+--------------------------+
Table 1: CBOR abbreviations for the ACE Token Table 1: CBOR Abbreviations for the ACE Token
Revocation List parameters Revocation List Parameters
13. ACE Token Revocation List Error Identifiers 13. ACE Token Revocation List Error Identifiers
This specification defines a number of values that the AS can use as This specification defines a number of values that the AS can use as
error identifiers. These are used in error responses with Content- error identifiers. These are used in error responses with Content-
Format "application/concise-problem-details+cbor", as values of the Format "application/concise-problem-details+cbor", as values of the
'error-id' field within the Custom Problem Detail entry 'ace-trl- 'error-id' field within the Custom Problem Detail entry 'ace-trl-
error' (see Section 6.1). error' (see Section 6.1).
+=======+===========================+ +=======+===========================+
skipping to change at page 43, line 29 skipping to change at line 2013
+-------+---------------------------+ +-------+---------------------------+
| 2 | Out of bound cursor value | | 2 | Out of bound cursor value |
+-------+---------------------------+ +-------+---------------------------+
Table 2: ACE Token Revocation Table 2: ACE Token Revocation
List Error Identifiers List Error Identifiers
14. Security Considerations 14. Security Considerations
The protocol defined in this document inherits the security The protocol defined in this document inherits the security
considerations from the ACE framework for Authentication and considerations from the ACE framework [RFC9200] and those about the
Authorization [RFC9200], from [RFC8392] as to the usage of CWTs, from usage of CWTs from [RFC8392], the usage of JWTs from [RFC7519] and
[RFC7519] and [RFC8725] as to the usage of JWTs, from [RFC7641] as to [RFC8725], the usage of CoAP Observe from [RFC7641], and the
the usage of CoAP Observe, and from [RFC6920] with regard to computation of the token hashes from [RFC6920]. The following
computing the token hashes. The following considerations also apply. considerations also apply.
14.1. Content Retrieval from the TRL 14.1. Content Retrieval from the TRL
The AS MUST ensure that each registered device can access and The AS MUST ensure that each registered device can access and
retrieve only its pertaining subset of the TRL. To this end, the AS retrieve only its pertaining subset of the TRL. To this end, the AS
can always perform the required filtering based on the authenticated can always perform the required filtering based on the authenticated
identity of the registered device, i.e., a (non-public) identifier identity of the registered device, i.e., a (non-public) identifier
that the AS can securely relate to the registered device and the that the AS can securely relate to the registered device and the
secure association that they use to communicate. secure association that they use to communicate.
The AS MUST ensure that, other than registered devices accessing The AS MUST ensure that, other than registered devices accessing
their own pertaining subset of the TRL, only authorized and their own pertaining subset of the TRL, only authorized and
authenticated administrators can access the content of the whole TRL authenticated administrators can access the content of the whole TRL
(see Section 10). (see Section 10).
Note that the TRL endpoint supports only the GET method (see Note that the TRL endpoint supports only the GET method (see
Section 6). Therefore, as detailed in Section 7 and Section 8, Section 6). Therefore, as detailed in Sections 7 and 8, access to
accesses to the TRL endpoint are performed only by means of protected the TRL endpoint is performed only by means of protected and
and authenticated GET requests, which by definition are safe in the authenticated GET requests, which, by definition, are safe in the
REST sense and do not alter the content of the TRL. That is, REST sense and do not alter the content of the TRL. That is,
registered devices and administrators can perform exclusively read- registered devices and administrators can perform exclusively read-
only operations when accessing the TRL endpoint. only operations when accessing the TRL endpoint.
In fact, the content of the TRL can be updated only internally by the In fact, the content of the TRL can be updated only internally by the
AS, in the two circumstances described in Section 5.1. Therefore, an AS, in the two circumstances described in Section 5.1. Therefore, an
adversary that is not in control of the AS cannot manipulate the adversary that is not in control of the AS cannot manipulate the
content of the TRL, e.g., by removing a token hash and thereby content of the TRL, e.g., by removing a token hash and thereby
fraudulently allowing a client to access protected resources in spite fraudulently allowing a client to access protected resources in spite
of a revoked access token, or by adding a token hash and thereby of a revoked access token or by adding a token hash and thereby
fraudulently stopping a client from accessing protected resources in fraudulently stopping a client from accessing protected resources in
spite of an access token being still valid. spite of an access token being still valid.
14.2. Size of the TRL 14.2. Size of the TRL
If many non-expired access tokens associated with a registered device If many non-expired access tokens associated with a registered device
are revoked, the pertaining subset of the TRL could grow to a size are revoked, the pertaining subset of the TRL could grow to a size
bigger than what the registered device is prepared to handle upon bigger than what the registered device is prepared to handle upon
reception of a response from the TRL endpoint, especially if relying reception of a response from the TRL endpoint, especially if relying
on a full query of the TRL (see Section 7). on a full query of the TRL (see Section 7).
skipping to change at page 44, line 43 skipping to change at line 2076
specification is expected to especially rely on CoAP Observe specification is expected to especially rely on CoAP Observe
notifications sent from the AS to a requester (i.e., an administrator notifications sent from the AS to a requester (i.e., an administrator
or a registered device). The suppression of those notifications by or a registered device). The suppression of those notifications by
an external attacker that has access to the network would prevent an external attacker that has access to the network would prevent
requesters from ever knowing that their pertaining access tokens have requesters from ever knowing that their pertaining access tokens have
been revoked. been revoked.
In order to avoid this, a requester SHOULD NOT rely solely on the In order to avoid this, a requester SHOULD NOT rely solely on the
CoAP Observe notifications. In particular, a requester SHOULD also CoAP Observe notifications. In particular, a requester SHOULD also
regularly poll the AS for the most current information about revoked regularly poll the AS for the most current information about revoked
access tokens, by sending GET requests to the TRL endpoint. Specific access tokens by sending GET requests to the TRL endpoint. Specific
strategies and schedules for polling the AS are to be defined by a strategies and schedules for polling the AS are to be defined by a
related application policy, by also taking into account the expected related application policy and by taking into account the expected
operational and availability patterns adopted by the requester (e.g., operational and availability patterns adopted by the requester (e.g.,
in the interest of energy saving and other optimizations). in the interest of energy saving and other optimizations).
14.4. Request of New Access Tokens 14.4. Request of New Access Tokens
If a client stores an access token that it still believes to be If a client stores an access token that it still believes to be
valid, and it accordingly attempts to access a protected resource at valid, and it accordingly attempts to access a protected resource at
the RS, the client may receive an unprotected 4.01 (Unauthorized) the RS, the client may receive an unprotected 4.01 (Unauthorized)
response from the RS. response from the RS.
This can be due to a number of causes. For example, the access token This can be due to a number of causes, for example:
has been revoked, and the RS has become aware of it and has expunged
the access token, but the client is not aware of it (yet). As * the access token has been revoked, the RS has become aware of it,
another example, the access token is still valid, but an on-path and the RS has expunged the access token, but the client is not
active adversary might have injected a forged 4.01 (Unauthorized) aware of this (yet).
response, or the RS might have deleted the access token from its
local storage due to its dedicated storage space being all consumed. * the access token is still valid, but an on-path active adversary
might have injected a forged 4.01 (Unauthorized) response or the
RS might have deleted the access token from its local storage due
to its dedicated storage space being all consumed.
In either case, if the client believes that the access token is still In either case, if the client believes that the access token is still
valid, it SHOULD NOT immediately ask for a new access token to the valid, it SHOULD NOT immediately ask for a new access token to the AS
authorization server upon receiving a 4.01 (Unauthorized) response upon receiving a 4.01 (Unauthorized) response from the RS. Instead,
from the RS. Instead, the client SHOULD send a request to the TRL the client SHOULD send a request to the TRL endpoint at the AS. If
endpoint at the AS. If the client gains knowledge that the access the client gains knowledge that the access token is not valid
token is not valid anymore, the client expunges the access token and anymore, the client expunges the access token and can ask for a new
can ask for a new one. Otherwise, the client can try again to upload one. Otherwise, the client can try again to upload the same access
the same access token to the RS, or instead to request a new one. token to the RS or request a new one.
14.5. Vulnerable Time Window at the RS 14.5. Vulnerable Time Window at the RS
A client may attempt to access a protected resource at an RS after A client may attempt to access a protected resource at an RS after
the access token allowing such an access has been revoked, but before the access token allowing such an access has been revoked but before
the RS is aware of the revocation. the RS is aware of the revocation.
In such a case, if the RS is still storing the access token, the In such a case, if the RS is still storing the access token, the
client will be able to access the protected resource, even though it client will be able to access the protected resource even though it
should not. Such an access is a security violation, even if the should not. Such access is a security violation, even if the client
client is not attempting to be malicious. is not attempting to be malicious.
In order to minimize such a risk, if an RS relies solely on polling In order to minimize such a risk, if an RS relies solely on polling
through individual requests to the TRL endpoint to learn of revoked through individual requests to the TRL endpoint to learn of revoked
access tokens, the RS SHOULD implement an adequate trade-off between access tokens, the RS SHOULD implement an adequate trade-off between
the polling frequency and the maximum length of the vulnerable time the polling frequency and the maximum length of the vulnerable time
window. window.
14.6. Preventing Unnoticed Manipulation of Access Tokens 14.6. Preventing Unnoticed Manipulation of Access Tokens
As defined in Section 3, issued access tokens MUST NOT rely on As defined in Section 3, issued access tokens MUST NOT rely on
unprotected headers to specify information as header parameters. unprotected headers to specify information as header parameters.
Also, when issued access tokens are CWTs, they MUST be tagged by Also, when issued access tokens are CWTs, they MUST be tagged by
using the COSE CBOR tag corresponding to the used COSE object, the using the COSE CBOR tag corresponding to the used COSE object.
result MUST be in turn tagged by using the CWT CBOR tag, and no Further, the result MUST be tagged using the CWT CBOR tag; no further
further tagging is performed. tagging is performed.
This ensures that the RS always computes the correct token hash This ensures that the RS always computes the correct token hash
corresponding to an access token, i.e., the same token hash computed corresponding to an access token, i.e., the same token hash computed
by the AS and C for that access token. by the AS and C for that access token.
By construction, the rules defined in Section 3 prevent an active By construction, the rules defined in Section 3 prevent an active
adversary from successfully performing an attack against the RS, adversary from successfully performing an attack against the RS,
which would otherwise be possible in case the access token is which would otherwise be possible in case the access token is
uploaded to the RS over an unprotected communication channel. uploaded to the RS over an unprotected communication channel.
In such an attack, the adversary intercepts the access token when In such an attack, the adversary intercepts the access token en route
this is sent to the RS. Then, the adversary manipulates the access to the RS. Then, the adversary manipulates the access token in a way
token in a way which is going to be unnoticed by the RS, but without that is going to be unnoticed by the RS but without preventing the
preventing the successful, cryptographic validation of the access successful cryptographic validation of the access token at the RS.
token at the RS. To this end, the adversary has two possible To this end, the adversary has two possible options:
options:
* Adding and/or removing fields within the unprotected header(s) of * Adding and/or removing fields within the unprotected header(s) of
the access token, as long as those fields do not play a role in the access token, as long as those fields do not play a role in
the cryptographic validation of the access token. the cryptographic validation of the access token.
* Specifically when the access token is a CWT, adding/removing or * Specifically when the access token is a CWT, adding, removing, or
manipulating possible CBOR tag(s) enclosing the access token. manipulating possible CBOR tags enclosing the access token.
After that, the adversary sends the manipulated access token to the After that, the adversary sends the manipulated access token to the
RS. RS.
After having successfully validated the manipulated access token, the After having successfully validated the manipulated access token, the
RS computes a corresponding token hash different from the one RS computes a corresponding token hash different from the one
computed and stored by C and the AS. Finally, the RS stores the computed and stored by C and the AS. Finally, the RS stores the
manipulated access token and the corresponding wrong token hash. manipulated access token and the corresponding wrong token hash.
Later on, if the access token is revoked and the AS provides the RS Later on, if the access token is revoked and the AS provides the RS
with the corresponding correct token hash, the RS does not recognize with the corresponding correct token hash, the RS does not recognize
the received token hash among the stored ones, and therefore does not the received token hash among the stored ones; therefore, the RS does
delete the revoked access token. not delete the revoked access token.
14.7. Two Token Hashes at the RS using JWTs 14.7. Two Token Hashes at the RS Using JWTs
Section 4.3.2 defines that an RS using JWTs as access tokens has to Section 4.3.2 specifies that an RS using JWTs as access tokens has to
compute and store two token hashes associated with the same access compute and store two token hashes associated with the same access
token. This is because, when using JWTs, the RS does not know for token. This is because the RS does not know for sure if the AS
sure if the AS provided the access token to the client by means of an provided the access token to the client by means of an AS-to-Client
AS-to-Client response encoded in CBOR or in JSON. response encoded in CBOR or in JSON.
Taking advantage of that, a dishonest client can attempt to perform Taking advantage of that, a dishonest client can attempt to perform
an attack against the RS. That is, the client can first receive the an attack against the RS. That is, the client can first receive the
JWT in an AS-to-Client response encoded in CBOR (JSON). Then, the JWT in an AS-to-Client response encoded in CBOR (JSON). Then, the
client can upload the JWT to the RS in a way that makes the RS client can upload the JWT to the RS in a way that makes the RS
believe that the client instead received the JWT in an AS-to-Client believe that the client instead received the JWT in an AS-to-Client
response encoded in JSON (CBOR). response encoded in JSON (CBOR).
Consequently, the RS considers a HASH_INPUT different from the one Consequently, the RS considers a HASH_INPUT different from the one
considered by the AS and the client (see Section 4.2). Hence, the RS considered by the AS and the client (see Section 4.2). Hence, the RS
computes a token hash h' different from the token hash h computed by computes a token hash h' different from the token hash h computed by
the AS and the client. It follows that, if the AS revokes the access the AS and the client. It follows that, if the AS revokes the access
token and advertises the right token hash h, then the RS will not token and advertises the right token hash h, then the RS will not
learn about the access token revocation and thus will not delete the learn about the access token revocation; therefore, the RS will not
access token. delete the access token.
Fundamentally, this would happen because the HASH_INPUT used to Fundamentally, this would happen because the HASH_INPUT used to
compute the token hash of a JWT depends on whether the AS-to-Client compute the token hash of a JWT depends on whether the AS-to-Client
response is encoded in CBOR or in JSON. This makes the RS vulnerable response is encoded in CBOR or in JSON. This makes the RS vulnerable
to the attack described above, when JWTs are used as access tokens. to the attack described above when JWTs are used as access tokens.
Instead, this is not a problem if the access token is a CWT, since However, this is not a problem if the access token is a CWT, since
the HASH_INPUT used to compute the token hash of a CWT does not the HASH_INPUT used to compute the token hash of a CWT does not
depend on whether the AS-to-Client response is encoded in CBOR or in depend on whether the AS-to-Client response is encoded in CBOR or in
JSON. JSON.
While this asymmetry cannot be avoided altogether, the method defined While this asymmetry cannot be avoided altogether, the method defined
for the AS and the client in Section 4.2 deliberately penalizes the for the AS and the client in Section 4.2 deliberately penalizes the
case where the RS uses JWTs as access tokens. In such a case, the RS case where the RS uses JWTs as access tokens. In such a case, the RS
effectively neutralizes the attack described above, by computing and effectively neutralizes the attack described above by computing and
storing two token hashes associated with the same access token (see storing two token hashes associated with the same access token (see
Section 4.3.2). Section 4.3.2).
Conversely, this design deliberately favors the case where the RS Conversely, this design deliberately favors the case where the RS
uses CWTs as access tokens, which is a preferable option for uses CWTs as access tokens, which is a preferable option for
resource-constrained RSs as well as the default case in the ACE resource-constrained RSs as well as the default case in the ACE
framework (see Section 3 of [RFC9200]). That is, if an RS uses CWTs framework (see Section 3 of [RFC9200]). That is, if an RS uses CWTs
as access tokens, then the RS is not exposed to the attack described as access tokens, then the RS is not exposed to the attack described
above, and thus it safely computes and stores only one token hash per above; therefore, the RS safely computes and stores only one token
access token (see Section 4.3.1). hash per access token (see Section 4.3.1).
14.8. Additional Security Measures 14.8. Additional Security Measures
By accessing the TRL at the AS, registered devices and administrators By accessing the TRL at the AS, registered devices and administrators
are able to learn that their pertaining access tokens have been are able to learn that their pertaining access tokens have been
revoked. However, they cannot learn the reason why that happened, revoked. However, they cannot learn the reason why, including when
including when that reason is the compromise, misbehavior, or that reason is the compromise, misbehavior, or decommissioning of a
decommissioning of a registered device. registered device.
In fact, even the AS might not know that a registered device to which In fact, even the AS might not know that a registered device to which
a revoked access token pertains has been specifically compromised, a revoked access token pertains has been specifically compromised,
misbehaving, or decommissioned. At the same time, it might not be misbehaving, or decommissioned. At the same time, it might not be
acceptable to only revoke the access tokens pertaining to such a acceptable to only revoke the access tokens pertaining to such a
registered device. registered device.
Therefore, in order to preserve the security of the system and Therefore, in order to preserve the security of the system and
application, the entity that authoritatively declares a registered application, the entity that authoritatively declares a registered
device to be compromised, misbehaving, or decommissioned should also device to be compromised, misbehaving, or decommissioned should also
promptly trigger the execution of additional revocation processes as promptly trigger the execution of additional revocation processes as
deemed appropriate. These include, for instance: deemed appropriate. These include, for instance:
* The de-registration of the registered device from the AS, so that * The deregistration of the registered device from the AS so that
the AS does not issue further access tokens pertaining to that the AS does not issue further access tokens pertaining to that
device. device.
* If applicable, the revocation of the public authentication * If applicable, the revocation of the public authentication
credential associated with the registered device (e.g., its public credential associated with the registered device (e.g., its public
key certificate). key certificate).
The methods by which these processes are triggered and carried out The methods by which these processes are triggered and carried out
are out of the scope of this document. are out of the scope of this document.
15. IANA Considerations 15. IANA Considerations
This document has the following actions for IANA. The IANA actions for this document are described in the following
subsections.
Note to RFC Editor: Please replace all occurrences of "[RFC-XXXX]"
with the RFC number of this specification and delete this paragraph.
15.1. Media Type Registrations 15.1. Media Type Registrations
IANA is asked to register the media type "application/ace-trl+cbor" IANA has registered the media type "application/ace-trl+cbor" for
for messages of the protocol defined in this document encoded in messages of the protocol defined in this document encoded in CBOR.
CBOR. This registration follows the procedures specified in 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
Optional parameters: N/A Required parameters: N/A
Encoding considerations: Must be encoded as a CBOR map containing the Optional parameters: N/A
protocol parameters defined in [RFC-XXXX].
Security considerations: See Section 14 of this document. Encoding considerations: Must be encoded as a CBOR map containing
the protocol parameters defined in RFC 9770.
Interoperability considerations: N/A Security considerations: See Section 14 of RFC 9770.
Published specification: [RFC-XXXX] Interoperability considerations: N/A
Applications that use this media type: The type is used by Published specification: RFC 9770
authorization servers, clients, and resource servers that support the
notification of revoked access tokens, according to a Token
Revocation List maintained by the authorization server as specified
in [RFC-XXXX].
Fragment identifier considerations: N/A Applications that use this media type: The type is used by
authorization servers, clients, and RSs that support the
notification of revoked access tokens according to a Token
Revocation List maintained by the authorization server as
specified in RFC 9770.
Additional information: N/A Fragment identifier considerations: N/A
Person & email address to contact for further information: ACE WG Additional information: N/A
mailing list (ace@ietf.org) or IETF Applications and Real-Time Area
(art@ietf.org)
Intended usage: COMMON Person & email address to contact for further information: ACE WG
mailing list (ace@ietf.org) or IETF Applications and Real-Time
Area (art@ietf.org)
Restrictions on usage: None Intended usage: COMMON
Author/Change controller: IETF Restrictions on usage: None
Provisional registration: No Author/Change controller: IETF
15.2. CoAP Content-Formats Registry 15.2. CoAP Content-Formats Registry
IANA is asked to add the following entry to the "CoAP Content- IANA has registered the following entry to the "CoAP Content-Formats"
Formats" registry within the "Constrained RESTful Environments (CoRE) registry within the "Constrained RESTful Environments (CoRE)
Parameters" registry group. Parameters" registry group.
Content Type: application/ace-trl+cbor Content Type: application/ace-trl+cbor
Content Coding: -
Content Coding: - ID: 262
Reference: RFC 9770
ID: TBD
Reference: [RFC-XXXX]
15.3. Custom Problem Detail Keys Registry 15.3. Custom Problem Detail Keys Registry
IANA is asked to register the following entry in the "Custom Problem IANA has registered the following entry in the "Custom Problem Detail
Detail Keys" registry within the "Constrained RESTful Environments Keys" registry within the "Constrained RESTful Environments (CoRE)
(CoRE) Parameters" registry group. Parameters" registry group.
* Key Value: TBD
* Name: ace-trl-error
* Brief Description: Carry [RFC-XXXX] problem details in a Concise Key Value: 1
Name: ace-trl-error
Brief Description: Carry RFC 9770 problem details in a Concise
Problem Details data item. Problem Details data item.
Change Controller: IETF
* Change Controller: IETF Reference: Section 6.1 of RFC 9770
* Reference: Section 6.1 of [RFC-XXXX]
15.4. ACE Token Revocation List Parameters Registry 15.4. ACE Token Revocation List Parameters Registry
IANA is asked to establish the "ACE Token Revocation List Parameters" IANA has established the "ACE Token Revocation List Parameters"
IANA registry within the "Authentication and Authorization for registry within the "Authentication and Authorization for Constrained
Constrained Environments (ACE)" registry group. Environments (ACE)" registry group.
As registration policy, the registry uses either "Standards Action One of the following registration policies is used: "Standards Action
with Expert Review", or "Specification Required" per Section 4.6 of With Expert Review", "Specification Required" per Section 4.6 of
[RFC8126], or "Expert Review" per Section 4.5 of [RFC8126]. Expert [RFC8126], or "Expert Review" per Section 4.5 of [RFC8126]. Expert
Review guidelines are provided in Section 15.6. Review guidelines are provided in Section 15.6.
All assignments according to "Standards Action with Expert Review" All assignments according to "Standards Action With Expert Review"
are made on a "Standards Action" basis per Section 4.9 of [RFC8126], are made on a "Standards Action" basis per Section 4.9 of [RFC8126]
with Expert Review additionally required per Section 4.5 of with Expert Review additionally required per Section 4.5 of
[RFC8126]. The procedure for early IANA allocation of Standards [RFC8126]. The procedure for early IANA allocation of Standards
Track code points defined in [RFC7120] also applies. When such a Track code points defined in [RFC7120] also applies. When such a
procedure is used, IANA will ask the designated expert(s) to approve procedure is used, IANA will ask the designated expert(s) to approve
the early allocation before registration. In addition, WG chairs are the early allocation before registration. In addition, WG chairs are
encouraged to consult the expert(s) early during the process outlined encouraged to consult the expert(s) early during the process outlined
in Section 3.1 of [RFC7120]. in Section 3.1 of [RFC7120].
The columns of this registry are: The columns of this registry are as follows:
* Name: This field contains a descriptive name that enables easier * Name: This field contains a descriptive name that enables easier
reference to the item. The name MUST be unique and it is not used reference to the item. The name MUST be unique, and it is not
in the encoding. used in the encoding.
* CBOR Key: This field contains the value used as CBOR map key of * CBOR Key: This field contains the value used as CBOR map key of
the item. The value MUST be unique. The value is an unsigned the item. The value MUST be unique. The value is an unsigned
integer or a negative integer. Different ranges of values use integer or a negative integer. Different ranges of values use
different registration policies [RFC8126]. Integer values from different registration policies [RFC8126]. Integer values from
-256 to 255 are designated as "Standards Action With Expert -256 to 255 are designated as "Standards Action With Expert
Review". Integer values from -65536 to -257 and from 256 to 65535 Review". Integer values from -65536 to -257 and from 256 to 65535
are designated as "Specification Required". Integer values are designated as "Specification Required". Integer values
greater than 65535 are designated as "Expert Review". Integer greater than 65535 are designated as "Expert Review". Integer
values less than -65536 are marked as "Private Use". values less than -65536 are marked as "Private Use".
* CBOR Type: This field contains the allowable CBOR data types for * CBOR Type: This field contains the allowable CBOR data types for
values of this item, or a pointer to the registry that defines its values of this item or a pointer to the registry that defines its
type, when that depends on another item. type, when that depends on another item.
* Reference: This field contains a pointer to the public * Reference: This field contains a pointer to the public
specification for the item. specification for the item.
This registry has been initially populated by the values in This registry has been initially populated by the values in
Section 12. The "Reference" column for all of these entries refers Section 12. The "Reference" column for all of these entries refers
to this document. to this document.
15.5. ACE Token Revocation List Errors 15.5. ACE Token Revocation List Errors
IANA is asked to establish the "ACE Token Revocation List Errors" IANA has established the "ACE Token Revocation List Errors" registry
IANA registry within the "Authentication and Authorization for within the "Authentication and Authorization for Constrained
Constrained Environments (ACE)" registry group. Environments (ACE)" registry group.
As registration policy, the registry uses either "Standards Action One of the following registration policies is used: "Standards Action
with Expert Review", or "Specification Required" per Section 4.6 of With Expert Review", "Specification Required" per Section 4.6 of
[RFC8126], or "Expert Review" per Section 4.5 of [RFC8126]. Expert [RFC8126], or "Expert Review" per Section 4.5 of [RFC8126]. Expert
Review guidelines are provided in Section 15.6. Review guidelines are provided in Section 15.6.
All assignments according to "Standards Action with Expert Review" All assignments according to "Standards Action With Expert Review"
are made on a "Standards Action" basis per Section 4.9 of [RFC8126], are made on a "Standards Action" basis per Section 4.9 of [RFC8126]
with Expert Review additionally required per Section 4.5 of with Expert Review additionally required per Section 4.5 of
[RFC8126]. The procedure for early IANA allocation of Standards [RFC8126]. The procedure for early IANA allocation of Standards
Track code points defined in [RFC7120] also applies. When such a Track code points defined in [RFC7120] also applies. When such a
procedure is used, IANA will ask the designated expert(s) to approve procedure is used, IANA will ask the designated expert(s) to approve
the early allocation before registration. In addition, WG chairs are the early allocation before registration. In addition, WG chairs are
encouraged to consult the expert(s) early during the process outlined encouraged to consult the expert(s) early during the process outlined
in Section 3.1 of [RFC7120]. in Section 3.1 of [RFC7120].
The columns of this registry are: The columns of this registry are as follows:
* Value: The field contains the value to be used to identify the * Value: The field contains the value to be used to identify the
error. The value MUST be unique. The value is an unsigned error. The value MUST be unique. The value is an unsigned
integer or a negative integer. Different ranges of values use integer or a negative integer. Different ranges of values use
different registration policies [RFC8126]. Integer values from different registration policies [RFC8126]. Integer values from
-256 to 255 are designated as "Standards Action With Expert -256 to 255 are designated as "Standards Action With Expert
Review". Integer values from -65536 to -257 and from 256 to 65535 Review". Integer values from -65536 to -257 and from 256 to 65535
are designated as "Specification Required". Integer values are designated as "Specification Required". Integer values
greater than 65535 are designated as "Expert Review". Integer greater than 65535 are designated as "Expert Review". Integer
values less than -65536 are marked as "Private Use". values less than -65536 are marked as "Private Use".
skipping to change at page 52, line 26 skipping to change at line 2412
* Reference: This field contains a pointer to the public * Reference: This field contains a pointer to the public
specification defining the error, if one exists. specification defining the error, if one exists.
This registry has been initially populated by the values in This registry has been initially populated by the values in
Section 13. The "Reference" column for all of these entries refers Section 13. The "Reference" column for all of these entries refers
to this document. to this document.
15.6. Expert Review Instructions 15.6. Expert Review Instructions
The IANA registries established in this document are defined as The IANA registries established by this document use "Standards
"Standards Action with Expert Review", "Specification Required", or Action With Expert Review", "Specification Required", or "Expert
"Expert Review", depending on the range of values for which an Review" registration procedures depending on the range of values for
assignment is requested. This section gives some general guidelines which an assignment is requested. This section gives some general
for what the experts should be looking for, but they are being guidelines for what the experts should be looking for, but they are
designated as experts for a reason so they should be given being designated as experts for a reason, so they should be given
substantial latitude. 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.
The zones tagged as private use are intended for testing purposes The zones tagged as Private Use are intended for testing purposes
and closed environments. Code points in other ranges should not and closed environments. Code points in other ranges should not
be assigned for testing. be assigned for testing.
* Specifications are required for the "Standards Action With Expert * Specifications are required for the "Standards Action With Expert
Review" range of point assignment. Specifications should exist Review" range of point assignment. Specifications should exist
for "Specification Required" ranges, but early assignment before a for "Specification Required" ranges, but early assignment before a
specification is available is considered to be permissible. For specification is available is considered to be permissible. For
the "Expert Review" range of point assignment, specifications are the "Expert Review" range of point assignment, specifications are
recommended, and are needed if they are expected to be used recommended and are needed if they are expected to be used outside
outside of closed environments in an interoperable way. When of closed environments in an interoperable way. When
specifications are not provided, the description provided needs to specifications are not provided, the description provided needs to
have sufficient information to identify what the point is being have sufficient information to identify what the point is being
used for. used for.
* 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.
16. References 16. References
16.1. Normative References 16.1. Normative References
[Named.Information.Hash.Algorithm] [IANA.Hash.Algorithms]
IANA, "Named Information Hash Algorithm", IANA, "Named Information Hash Algorithm Registry",
<https://www.iana.org/assignments/named-information/named- <https://www.iana.org/assignments/named-information>.
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/rfc/rfc2119>. <https://www.rfc-editor.org/info/rfc2119>.
[RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO
10646", STD 63, RFC 3629, DOI 10.17487/RFC3629, November 10646", STD 63, RFC 3629, DOI 10.17487/RFC3629, November
2003, <https://www.rfc-editor.org/rfc/rfc3629>. 2003, <https://www.rfc-editor.org/info/rfc3629>.
[RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data
Encodings", RFC 4648, DOI 10.17487/RFC4648, October 2006, Encodings", RFC 4648, DOI 10.17487/RFC4648, October 2006,
<https://www.rfc-editor.org/rfc/rfc4648>. <https://www.rfc-editor.org/info/rfc4648>.
[RFC6347] Rescorla, E. and N. Modadugu, "Datagram Transport Layer [RFC6347] Rescorla, E. and N. Modadugu, "Datagram Transport Layer
Security Version 1.2", RFC 6347, DOI 10.17487/RFC6347, Security Version 1.2", RFC 6347, DOI 10.17487/RFC6347,
January 2012, <https://www.rfc-editor.org/rfc/rfc6347>. January 2012, <https://www.rfc-editor.org/info/rfc6347>.
[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/rfc/rfc6749>. <https://www.rfc-editor.org/info/rfc6749>.
[RFC6838] Freed, N., Klensin, J., and T. Hansen, "Media Type [RFC6838] Freed, N., Klensin, J., and T. Hansen, "Media Type
Specifications and Registration Procedures", BCP 13, Specifications and Registration Procedures", BCP 13,
RFC 6838, DOI 10.17487/RFC6838, January 2013, RFC 6838, DOI 10.17487/RFC6838, January 2013,
<https://www.rfc-editor.org/rfc/rfc6838>. <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/rfc/rfc6920>. <https://www.rfc-editor.org/info/rfc6920>.
[RFC7120] Cotton, M., "Early IANA Allocation of Standards Track Code [RFC7120] Cotton, M., "Early IANA Allocation of Standards Track Code
Points", BCP 100, RFC 7120, DOI 10.17487/RFC7120, January Points", BCP 100, RFC 7120, DOI 10.17487/RFC7120, January
2014, <https://www.rfc-editor.org/rfc/rfc7120>. 2014, <https://www.rfc-editor.org/info/rfc7120>.
[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/rfc/rfc7252>. <https://www.rfc-editor.org/info/rfc7252>.
[RFC7515] Jones, M., Bradley, J., and N. Sakimura, "JSON Web [RFC7515] Jones, M., Bradley, J., and N. Sakimura, "JSON Web
Signature (JWS)", RFC 7515, DOI 10.17487/RFC7515, May Signature (JWS)", RFC 7515, DOI 10.17487/RFC7515, May
2015, <https://www.rfc-editor.org/rfc/rfc7515>. 2015, <https://www.rfc-editor.org/info/rfc7515>.
[RFC7516] Jones, M. and J. Hildebrand, "JSON Web Encryption (JWE)", [RFC7516] Jones, M. and J. Hildebrand, "JSON Web Encryption (JWE)",
RFC 7516, DOI 10.17487/RFC7516, May 2015, RFC 7516, DOI 10.17487/RFC7516, May 2015,
<https://www.rfc-editor.org/rfc/rfc7516>. <https://www.rfc-editor.org/info/rfc7516>.
[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/rfc/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/rfc/rfc7641>. <https://www.rfc-editor.org/info/rfc7641>.
[RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for [RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for
Writing an IANA Considerations Section in RFCs", BCP 26, Writing an IANA Considerations Section in RFCs", BCP 26,
RFC 8126, DOI 10.17487/RFC8126, June 2017, RFC 8126, DOI 10.17487/RFC8126, June 2017,
<https://www.rfc-editor.org/rfc/rfc8126>. <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/rfc/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/rfc/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/rfc/rfc8392>. May 2018, <https://www.rfc-editor.org/info/rfc8392>.
[RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol [RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol
Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018, Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018,
<https://www.rfc-editor.org/rfc/rfc8446>. <https://www.rfc-editor.org/info/rfc8446>.
[RFC8610] Birkholz, H., Vigano, C., and C. Bormann, "Concise Data [RFC8610] Birkholz, H., Vigano, C., and C. Bormann, "Concise Data
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/rfc/rfc8610>. June 2019, <https://www.rfc-editor.org/info/rfc8610>.
[RFC8613] Selander, G., Mattsson, J., Palombini, F., and L. Seitz, [RFC8613] Selander, G., Mattsson, J., Palombini, F., and L. Seitz,
"Object Security for Constrained RESTful Environments "Object Security for Constrained RESTful Environments
(OSCORE)", RFC 8613, DOI 10.17487/RFC8613, July 2019, (OSCORE)", RFC 8613, DOI 10.17487/RFC8613, July 2019,
<https://www.rfc-editor.org/rfc/rfc8613>. <https://www.rfc-editor.org/info/rfc8613>.
[RFC8725] Sheffer, Y., Hardt, D., and M. Jones, "JSON Web Token Best [RFC8725] Sheffer, Y., Hardt, D., and M. Jones, "JSON Web Token Best
Current Practices", BCP 225, RFC 8725, Current Practices", BCP 225, RFC 8725,
DOI 10.17487/RFC8725, February 2020, DOI 10.17487/RFC8725, February 2020,
<https://www.rfc-editor.org/rfc/rfc8725>. <https://www.rfc-editor.org/info/rfc8725>.
[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/rfc/rfc8949>. <https://www.rfc-editor.org/info/rfc8949>.
[RFC9052] Schaad, J., "CBOR Object Signing and Encryption (COSE): [RFC9052] Schaad, J., "CBOR Object Signing and Encryption (COSE):
Structures and Process", STD 96, RFC 9052, Structures and Process", STD 96, RFC 9052,
DOI 10.17487/RFC9052, August 2022, DOI 10.17487/RFC9052, August 2022,
<https://www.rfc-editor.org/rfc/rfc9052>. <https://www.rfc-editor.org/info/rfc9052>.
[RFC9147] Rescorla, E., Tschofenig, H., and N. Modadugu, "The [RFC9147] Rescorla, E., Tschofenig, H., and N. Modadugu, "The
Datagram Transport Layer Security (DTLS) Protocol Version Datagram Transport Layer Security (DTLS) Protocol Version
1.3", RFC 9147, DOI 10.17487/RFC9147, April 2022, 1.3", RFC 9147, DOI 10.17487/RFC9147, April 2022,
<https://www.rfc-editor.org/rfc/rfc9147>. <https://www.rfc-editor.org/info/rfc9147>.
[RFC9200] Seitz, L., Selander, G., Wahlstroem, E., Erdtman, S., and [RFC9200] Seitz, L., Selander, G., Wahlstroem, E., Erdtman, S., and
H. Tschofenig, "Authentication and Authorization for H. Tschofenig, "Authentication and Authorization for
Constrained Environments Using the OAuth 2.0 Framework Constrained Environments Using the OAuth 2.0 Framework
(ACE-OAuth)", RFC 9200, DOI 10.17487/RFC9200, August 2022, (ACE-OAuth)", RFC 9200, DOI 10.17487/RFC9200, August 2022,
<https://www.rfc-editor.org/rfc/rfc9200>. <https://www.rfc-editor.org/info/rfc9200>.
[RFC9202] Gerdes, S., Bergmann, O., Bormann, C., Selander, G., and [RFC9202] Gerdes, S., Bergmann, O., Bormann, C., Selander, G., and
L. Seitz, "Datagram Transport Layer Security (DTLS) L. Seitz, "Datagram Transport Layer Security (DTLS)
Profile for Authentication and Authorization for Profile for Authentication and Authorization for
Constrained Environments (ACE)", RFC 9202, Constrained Environments (ACE)", RFC 9202,
DOI 10.17487/RFC9202, August 2022, DOI 10.17487/RFC9202, August 2022,
<https://www.rfc-editor.org/rfc/rfc9202>. <https://www.rfc-editor.org/info/rfc9202>.
[RFC9203] Palombini, F., Seitz, L., Selander, G., and M. Gunnarsson, [RFC9203] Palombini, F., Seitz, L., Selander, G., and M. Gunnarsson,
"The Object Security for Constrained RESTful Environments "The Object Security for Constrained RESTful Environments
(OSCORE) Profile of the Authentication and Authorization (OSCORE) Profile of the Authentication and Authorization
for Constrained Environments (ACE) Framework", RFC 9203, for Constrained Environments (ACE) Framework", RFC 9203,
DOI 10.17487/RFC9203, August 2022, DOI 10.17487/RFC9203, August 2022,
<https://www.rfc-editor.org/rfc/rfc9203>. <https://www.rfc-editor.org/info/rfc9203>.
[RFC9290] Fossati, T. and C. Bormann, "Concise Problem Details for [RFC9290] Fossati, T. and C. Bormann, "Concise Problem Details for
Constrained Application Protocol (CoAP) APIs", RFC 9290, Constrained Application Protocol (CoAP) APIs", RFC 9290,
DOI 10.17487/RFC9290, October 2022, DOI 10.17487/RFC9290, October 2022,
<https://www.rfc-editor.org/rfc/rfc9290>. <https://www.rfc-editor.org/info/rfc9290>.
[RFC9431] Sengul, C. and A. Kirby, "Message Queuing Telemetry [RFC9431] Sengul, C. and A. Kirby, "Message Queuing Telemetry
Transport (MQTT) and Transport Layer Security (TLS) Transport (MQTT) and Transport Layer Security (TLS)
Profile of Authentication and Authorization for Profile of Authentication and Authorization for
Constrained Environments (ACE) Framework", RFC 9431, Constrained Environments (ACE) Framework", RFC 9431,
DOI 10.17487/RFC9431, July 2023, DOI 10.17487/RFC9431, July 2023,
<https://www.rfc-editor.org/rfc/rfc9431>. <https://www.rfc-editor.org/info/rfc9431>.
[RFC9528] Selander, G., Preuß Mattsson, J., and F. Palombini, [RFC9528] Selander, G., Preuß Mattsson, J., and F. Palombini,
"Ephemeral Diffie-Hellman Over COSE (EDHOC)", RFC 9528, "Ephemeral Diffie-Hellman Over COSE (EDHOC)", RFC 9528,
DOI 10.17487/RFC9528, March 2024, DOI 10.17487/RFC9528, March 2024,
<https://www.rfc-editor.org/rfc/rfc9528>. <https://www.rfc-editor.org/info/rfc9528>.
[SHA-256] NIST, "Secure Hash Standard", FIPS 180-3 , October 2008, [SHA-256] NIST, "Secure Hash Standard", NIST FIPS PUB 180-4,
<http://csrc.nist.gov/publications/fips/fips180-3/ DOI 10.6028/NIST.FIPS.180-4, August 2015,
fips180-3_final.pdf>. <https://nvlpubs.nist.gov/nistpubs/FIPS/
NIST.FIPS.180-4.pdf>.
16.2. Informative References 16.2. Informative References
[I-D.bormann-t2trg-stp] [COND-PARAMETERS]
Bormann, C. and K. Hartke, "The Series Transfer Pattern Silverajan, B., Koster, M., and A. Soloway, "Conditional
Query Parameters for CoAP Observe", Work in Progress,
Internet-Draft, draft-ietf-core-conditional-attributes-11,
16 March 2025, <https://datatracker.ietf.org/doc/html/
draft-ietf-core-conditional-attributes-11>.
[RFC7009] Lodderstedt, T., Ed., Dronia, S., and M. Scurtescu, "OAuth
2.0 Token Revocation", RFC 7009, DOI 10.17487/RFC7009,
August 2013, <https://www.rfc-editor.org/info/rfc7009>.
[STP] 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://datatracker.ietf.org/doc/html/draft-bormann- <https://datatracker.ietf.org/doc/html/draft-bormann-
t2trg-stp-03>. t2trg-stp-03>.
[I-D.ietf-core-conditional-attributes] Appendix A. On Using the Series Transfer Pattern
Koster, M., Soloway, A., and B. Silverajan, "Conditional
Attributes for Constrained RESTful Environments", Work in
Progress, Internet-Draft, draft-ietf-core-conditional-
attributes-07, 8 July 2024,
<https://datatracker.ietf.org/doc/html/draft-ietf-core-
conditional-attributes-07>.
[RFC7009] Lodderstedt, T., Ed., Dronia, S., and M. Scurtescu, "OAuth
2.0 Token Revocation", RFC 7009, DOI 10.17487/RFC7009,
August 2013, <https://www.rfc-editor.org/rfc/rfc7009>.
Appendix A. On using the Series Transfer Pattern
Performing a diff query of the TRL as specified in Section 8 is in Performing a diff query of the TRL as specified in Section 8 is, in
fact a usage example of the Series Transfer Pattern defined in fact, a usage example of the Series Transfer Pattern (STP) defined in
[I-D.bormann-t2trg-stp]. [STP].
That is, a diff query enables the transfer of a series of diff That is, a diff query enables the transfer of a series of diff
entries, with the AS specifying U <= MAX_N diff entries as related to entries with the AS providing U <= MAX_N diff entries as related to
the U most recent TRL updates pertaining to a requester, i.e., a the U most recent TRL updates pertaining to a requester, i.e., a
registered device or an administrator. registered device or an administrator.
When responding to a diff query request from a requester (see When responding to a diff query request from a requester (see
Section 8), 'diff_set' is a subset of the update collection Section 8), 'diff_set' is a subset of the update collection
associated with the requester, where each 'diff_entry' record is a associated with the requester where each 'diff_entry' record is a
series item from that update collection. Note that 'diff_set' series item from that update collection. Note that 'diff_set'
specifies the whole current update collection when the value of U is specifies the whole current update collection when the value of U is
equal to SIZE, i.e., the current number of series items in the update equal to SIZE, i.e., the current number of series items in the update
collection. collection.
The value N of the 'diff' query parameter in the GET request allows The value N of the 'diff' query parameter in the GET request allows
the requester and the AS to trade the amount of provided information the requester and the AS to trade the amount of provided information
with the latency of the information transfer. with the latency of the information transfer.
Since the update collection associated with each requester includes Since the update collection associated with each requester includes
up to MAX_N series items, the AS deletes the oldest series item when up to MAX_N series items, the AS deletes the oldest series item when
a new one is generated and added to the end of the update collection, a new one is generated and added to the end of the update collection,
due to a new TRL update pertaining to that requester (see due to a new TRL update pertaining to that requester (see
Section 6.2). This addresses the question "When can the server Section 6.2). This addresses the question "When can the server
decide to no longer retain older items?" raised in Section 3.2 of decide to no longer retain older items?" raised in Section 3.2 of
[I-D.bormann-t2trg-stp]. [STP].
Furthermore, performing a diff query of the TRL together with the Furthermore, performing a diff query of the TRL together with the
"Cursor" extension as specified in Section 9 in fact relies on the "Cursor" extension as specified in Section 9 relies, in fact, on the
"Cursor" pattern of the Series Transfer Pattern (see Section 3.3 of "cursor" pattern of the STP (see Section 3.3 of [STP]).
[I-D.bormann-t2trg-stp]).
Appendix B. Local Supportive Parameters of the TRL Endpoint Appendix B. Local Supportive Parameters of the TRL Endpoint
Table 3 provides an aggregated overview of the local supportive Table 3 provides an aggregated overview of the local supportive
parameters that the AS internally uses at its TRL endpoint, when parameters that the AS internally uses at its TRL endpoint when
supporting diff queries (see Section 6) and the "Cursor" extension supporting diff queries (see Section 6) and the "Cursor" extension
(see Section 6.2.1). (see Section 6.2.1).
Except for MAX_N defined in Section 6.2, all the other parameters are Except for MAX_N defined in Section 6.2, all the other parameters are
defined in Section 6.2.1 and are used only if the AS supports the defined in Section 6.2.1 and are used only if the AS supports the
"Cursor" extension. "Cursor" extension.
For each parameter, the columns of the table specify the following For each parameter, the columns of the table provide the following
information. Both a registered device and an administrator are information. Both a registered device and an administrator are
referred to as "requester". referred to as "requester".
* Name: parameter name. A name with letters in uppercase denotes a Name: The parameter name. A name with letters in uppercase denotes
parameter whose value does not change after its initialization. a parameter whose value does not change after its initialization.
* Single instance: "Y", if there is a single parameter instance Single instance: "Y" if there is a single parameter instance
associated with the TRL; or "N", if there is one parameter associated with the TRL or "N" if there is one parameter instance
instance per update collection (i.e., per requester). per update collection (i.e., per requester).
* Description: short parameter description. Description: A short description of the parameter.
* Values: the unsigned integer values that the parameter can assume, Values: The unsigned integer values that the parameter can assume,
where LB and UB denote the inclusive lower bound and upper bound, where LB and UB denote the inclusive lower bound and upper bound,
respectively, and "^" is the exponentiation operator. respectively.
+================+==========+====================+==================+ +================+==========+====================+==================+
| Name | Single | Description | Values | | Name | Single | Description | Values |
| | instance | | | | | instance | | |
+================+==========+====================+==================+ +================+==========+====================+==================+
| MAX_N | Y | Max number of | LB = 1 | | MAX_N | Y | Max number of | LB = 1 |
| | | series items in | | | | | series items in | |
| | | the update | If supporting | | | | the update | If supporting |
| | | collection of | "Cursor", then | | | | collection of each | the "Cursor" |
| | | each requester | UB = MAX_INDEX+1 | | | | requester | extension, then |
| | | | UB = |
| | | | MAX_INDEX+1 |
+----------------+----------+--------------------+------------------+ +----------------+----------+--------------------+------------------+
| MAX_DIFF_BATCH | N | Max number of | LB = 1 | | MAX_DIFF_BATCH | N | Max number of diff | LB = 1 |
| | | diff entries | | | | | entries included | |
| | | included in a | UB = MAX_N | | | | in a diff query | UB = MAX_N |
| | | diff query | |
| | | response when | | | | | response when | |
| | | using "Cursor" | | | | | using the "Cursor" | |
| | | extension | |
+----------------+----------+--------------------+------------------+ +----------------+----------+--------------------+------------------+
| MAX_INDEX | Y | Max value of each | LB = MAX_N-1 | | MAX_INDEX | Y | Max value of each | LB = MAX_N-1 |
| | | instance of the | | | | | instance of | |
| | | 'index' parameter | UB = (2^64)-1 | | | | 'index' | UB = (2^64)-1 |
+----------------+----------+--------------------+------------------+ +----------------+----------+--------------------+------------------+
| index | N | Value associated | LB = 0 | | index | N | Value associated | LB = 0 |
| | | with a series | | | | | with a series item | |
| | | item of an update | UB = MAX_INDEX | | | | of an update | UB = MAX_INDEX |
| | | collection | | | | | collection | |
+----------------+----------+--------------------+------------------+ +----------------+----------+--------------------+------------------+
| last_index | N | The 'index' value | LB = 0 | | last_index | N | The 'index' value | LB = 0 |
| | | of the most | | | | | of the most | |
| | | recently added | UB = MAX_INDEX | | | | recently added | UB = MAX_INDEX |
| | | series item in an | | | | | series item in an | |
| | | update collection | | | | | update collection | |
+----------------+----------+--------------------+------------------+ +----------------+----------+--------------------+------------------+
Table 3: Local Supportive Parameters of the TRL Endpoint Table 3: Local Supportive Parameters of the TRL Endpoint
Appendix C. Interaction Examples Appendix C. Interaction Examples
This section provides examples of interactions between an RS as a This section provides examples of interactions between an RS as a
registered device and an AS. In the examples, all the access tokens registered device and an AS. In the examples, all the access tokens
issued by the AS are intended to be consumed by the considered RS. issued by the AS are intended to be consumed by the considered RS.
The AS supports both full queries and diff queries of the TRL, as The AS supports both full queries and diff queries of the TRL, as
defined in Section 7 and Section 8, respectively. defined in Sections 7 and 8, respectively.
Registration is assumed to be done by the RS sending a POST request The RS registration is assumed to be done by the RS sending a POST
with an unspecified payload to the AS, which replies with a 2.01 request with an unspecified payload to the AS, which replies with a
(Created) response. The payload of the registration response is 2.01 (Created) response. The payload of the registration response is
assumed to be a CBOR map, which in turn is assumed to include the assumed to be a CBOR map, which, in turn, is assumed to include the
following entries: following entries:
* a 'trl_path' parameter, specifying the path of the TRL endpoint; * a 'trl_path' parameter specifying the path of the TRL endpoint;
* a 'trl_hash' parameter, specifying the "Hash Name String" of the * a 'trl_hash' parameter specifying the "Hash Name String" of the
hash function used to compute token hashes as defined in hash function used to compute token hashes as defined in
Section 4; Section 4;
* a 'max_n' parameter, specifying the value of MAX_N, i.e., the * a 'max_n' parameter specifying the value of MAX_N, i.e., the
maximum number of series items that the AS retains in the update maximum number of series items that the AS retains in the update
collection associated with a registered device (see Section 8); collection associated with a registered device (see Section 6.2);
* 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 4 of this specification and token hashes, as defined in Section 4 of this specification and
according to [RFC6920]. Assuming the usage of CWTs transported in according to [RFC6920]. Assuming the usage of CWTs transported in
AS-to-Client responses encoded in CBOR (see Section 4.2.1), AS-to-Client responses encoded in CBOR (see Section 4.2.1),
'bstr.h(t1)' and 'bstr.h(t2)' denote the CBOR byte strings with value 'bstr.h(t1)' and 'bstr.h(t2)' denote CBOR byte strings, whose values
the token hashes of the access tokens t1 and t2, respectively. are the token hashes of the access tokens t1 and t2, respectively.
C.1. Full Query with Observe C.1. Full Query with Observe
Figure 10 shows an interaction example considering a CoAP observation Figure 10 shows an interaction example of a CoAP observation and a
and a full query of the TRL. full query of the TRL.
In this example, the AS does not support the "Cursor" extension. In this example, the AS does not support the "Cursor" extension.
Hence, the 'cursor' parameter is not included in the payload of the Hence, the 'cursor' parameter is not included in the payload of the
responses to a full query request. responses to a full query request.
RS AS RS AS
| | | |
| Registration: POST | | Registration: POST |
+--------------------------------------------------->| +------------------------------------------------------>|
| | | |
|<---------------------------------------------------+ |<------------------------------------------------------+
| 2.01 Created | | 2.01 Created |
| Payload: { | | Payload: { |
| / ... / | | / ... / |
| "trl_path" : "/revoke/trl", | | "trl_path": "/revoke/trl", |
| "trl_hash" : "sha-256", | | "trl_hash": "sha-256", |
| "max_n" : 10 | | "max_n": 10 |
| } | | } |
| | | |
| GET coap://as.example.com/revoke/trl/ | | GET coap://as.example.com/revoke/trl/ |
| Observe: 0 | | Observe: 0 |
+--------------------------------------------------->| +------------------------------------------------------>|
| | | |
|<---------------------------------------------------+ |<------------------------------------------------------+
| 2.05 Content | | 2.05 Content |
| Observe: 42 | | Observe: 42 |
| Content-Format: application/ace-trl+cbor | | Content-Format: 262 (application/ace-trl+cbor) |
| Payload: { | | Payload: { |
| e'full_set' : [] | | / full_set / 0: [] |
| } | | } |
| | | |
| ... | | ... |
| | | |
| (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 | | 2.05 Content |
| Observe: 53 | | Observe: 53 |
| Content-Format: application/ace-trl+cbor | | Content-Format: 262 (application/ace-trl+cbor) |
| Payload: { | | Payload: { |
| e'full_set' : [bstr.h(t1)] | | / full_set / 0: [bstr.h(t1)] |
| } | | } |
| | | |
| ... | | ... |
| | | |
| (Access token t2 is revoked) | | (Access token t2 is revoked) |
| | | |
|<---------------------------------------------------+ |<------------------------------------------------------+
| 2.05 Content | | 2.05 Content |
| Observe: 64 | | Observe: 64 |
| Content-Format: application/ace-trl+cbor | | Content-Format: 262 (application/ace-trl+cbor) |
| Payload: { | | Payload: { |
| e'full_set' : [bstr.h(t1), bstr.h(t2)] | | / full_set / 0: [bstr.h(t1), bstr.h(t2)] |
| } | | } |
| | | |
| ... | | ... |
| | | |
| (Access token t1 expires) | | (Access token t1 expires) |
| | | |
|<---------------------------------------------------+ |<------------------------------------------------------+
| 2.05 Content | | 2.05 Content |
| Observe: 75 | | Observe: 75 |
| Content-Format: application/ace-trl+cbor | | Content-Format: 262 (application/ace-trl+cbor) |
| Payload: { | | Payload: { |
| e'full_set' : [bstr.h(t2)] | | / full_set / 0: [bstr.h(t2)] |
| } | | } |
| | | |
| ... | | ... |
| | | |
| (Access token t2 expires) | | (Access token t2 expires) |
| | | |
|<---------------------------------------------------+ |<------------------------------------------------------+
| 2.05 Content | | 2.05 Content |
| Observe: 86 | | Observe: 86 |
| Content-Format: application/ace-trl+cbor | | Content-Format: 262 (application/ace-trl+cbor) |
| Payload: { | | Payload: { |
| e'full_set' : [] | | / full_set / 0: [] |
| } | | } |
| | | |
Figure 10: Interaction for full query with Observe Figure 10: Interaction for Full Query with Observe
C.2. Diff Query with Observe C.2. Diff Query with Observe
Figure 11 shows an interaction example considering a CoAP observation Figure 11 shows an interaction example of a CoAP observation and a
and a diff query of the TRL. diff query of the TRL.
The RS indicates N = 3 as value of the 'diff' query parameter, i.e., The RS indicates N = 3 as the value of the 'diff' query parameter,
as the maximum number of diff entries to be specified in a response i.e., as the maximum number of diff entries to be included in a
from the AS. response from the AS.
In this example, the AS does not support the "Cursor" extension. In this example, the AS does not support the "Cursor" extension.
Hence, the 'cursor' parameter and the 'more' parameter are not Hence, the 'cursor' parameter and the 'more' parameter are not
included in the payload of the responses to a diff query request. included in the payload of the responses to a diff query request.
RS AS RS AS
| | | |
| Registration: POST | | Registration: POST |
+--------------------------------------------------->| +------------------------------------------------------>|
| | | |
|<---------------------------------------------------+ |<------------------------------------------------------+
| 2.01 Created | | 2.01 Created |
| Payload: { | | Payload: { |
| / ... / | | / ... / |
| "trl_path" : "/revoke/trl", | | "trl_path": "/revoke/trl", |
| "trl_hash" : "sha-256", | | "trl_hash": "sha-256", |
| "max_n" : 10 | | "max_n": 10 |
| } | | } |
| | | |
| GET coap://as.example.com/revoke/trl?diff=3 | | GET coap://as.example.com/revoke/trl?diff=3 |
| Observe: 0 | | Observe: 0 |
+--------------------------------------------------->| +------------------------------------------------------>|
| | | |
|<---------------------------------------------------+ |<------------------------------------------------------+
| 2.05 Content | | 2.05 Content |
| Observe: 42 | | Observe: 42 |
| Content-Format: application/ace-trl+cbor | | Content-Format: 262 (application/ace-trl+cbor) |
| Payload: { | | Payload: { |
| e'diff_set' : [] | | / diff_set / 1: [] |
| } | | } |
| | | |
| ... | | ... |
| | | |
| (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 | | 2.05 Content |
| Observe: 53 | | Observe: 53 |
| Content-Format: application/ace-trl+cbor | | Content-Format: 262 (application/ace-trl+cbor) |
| Payload: { | | Payload: { |
| e'diff_set' : [ | | / diff_set / 1: [ |
| [ [], [bstr.h(t1)] ] | | [ [], [bstr.h(t1)] ] |
| ] | | ] |
| } | | } |
| | | |
| ... | | ... |
| | | |
| (Access token t2 is revoked) | | (Access token t2 is revoked) |
| | | |
|<---------------------------------------------------+ |<------------------------------------------------------+
| 2.05 Content | | 2.05 Content |
| Observe: 64 | | Observe: 64 |
| Content-Format: application/ace-trl+cbor | | Content-Format: 262 (application/ace-trl+cbor) |
| Payload: { | | Payload: { |
| e'diff_set' : [ | | / diff_set / 1: [ |
| [ [], [bstr.h(t2)] ], | | [ [], [bstr.h(t2)] ], |
| [ [], [bstr.h(t1)] ] | | [ [], [bstr.h(t1)] ] |
| ] | | ] |
| } | | } |
| | | |
| ... | | ... |
| | | |
| (Access token t1 expires) | | (Access token t1 expires) |
| | | |
|<---------------------------------------------------+ |<------------------------------------------------------+
| 2.05 Content | | 2.05 Content |
| Observe: 75 | | Observe: 75 |
| Content-Format: application/ace-trl+cbor | | Content-Format: 262 (application/ace-trl+cbor) |
| Payload: { | | Payload: { |
| e'diff_set' : [ | | / diff_set / 1: [ |
| [ [bstr.h(t1)], [] ], | | [ [bstr.h(t1)], [] ], |
| [ [], [bstr.h(t2)] ], | | [ [], [bstr.h(t2)] ], |
| [ [], [bstr.h(t1)] ] | | [ [], [bstr.h(t1)] ] |
| ] | | ] |
| } | | } |
| | | |
| ... | | ... |
| | | |
| (Access token t2 expires) | | (Access token t2 expires) |
| | | |
|<---------------------------------------------------+ |<------------------------------------------------------+
| 2.05 Content | | 2.05 Content |
| Observe: 86 | | Observe: 86 |
| Content-Format: application/ace-trl+cbor | | Content-Format: 262 (application/ace-trl+cbor) |
| Payload: { | | Payload: { |
| e'diff_set' : [ | | / diff_set / 1: [ |
| [ [bstr.h(t2)], [] ], | | [ [bstr.h(t2)], [] ], |
| [ [bstr.h(t1)], [] ], | | [ [bstr.h(t1)], [] ], |
| [ [], [bstr.h(t2)] ] | | [ [], [bstr.h(t2)] ] |
| ] | | ] |
| } | | } |
| | | |
Figure 11: Interaction for diff query with Observe Figure 11: Interaction for Diff Query with Observe
C.3. Full Query with Observe plus Diff Query C.3. Full Query with Observe and Diff Query
Figure 12 shows an interaction example considering a CoAP observation Figure 12 shows an interaction example of 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 AS to The example also shows one of the notifications from the AS getting
get lost in transmission, and thus not reaching the RS. lost in transmission; thus, that notification does not reach the RS.
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 RS sends a GET request with no Observe application has elapsed, the RS sends a GET request with no Observe
Option to the AS, to perform a diff query of the TRL. The RS Option to the AS, asking the AS to perform a diff query of the TRL.
indicates N = 8 as value of the 'diff' query parameter, i.e., as the The RS indicates N = 8 as the value of the 'diff' query parameter,
maximum number of diff entries to be specified in a response from the i.e., as the maximum number of diff entries to be included in a
AS. response from the AS.
In this example, the AS does not support the "Cursor" extension. In this example, the AS does not support the "Cursor" extension.
Hence, the 'cursor' parameter is not included in the payload of the Hence, the 'cursor' parameter is not included in the payload of the
responses to a full query request. Also, the 'cursor' parameter and responses to a full query request. Also, the 'cursor' parameter and
the 'more' parameter are not included in the payload of the responses the 'more' parameter are not included in the payload of the responses
to a diff query request. to a diff query request.
RS AS RS AS
| | | |
| Registration: POST | | Registration: POST |
+--------------------------------------------------->| +------------------------------------------------------>|
| | | |
|<---------------------------------------------------+ |<------------------------------------------------------+
| 2.01 Created | | 2.01 Created |
| Payload: { | | Payload: { |
| / ... / | | / ... / |
| "trl_path" : "/revoke/trl", | | "trl_path": "/revoke/trl", |
| "trl_hash" : "sha-256", | | "trl_hash": "sha-256", |
| "max_n" : 10 | | "max_n": 10 |
| } | | } |
| | | |
| GET coap://as.example.com/revoke/trl/ | | GET coap://as.example.com/revoke/trl/ |
| Observe: 0 | | Observe: 0 |
+--------------------------------------------------->| +------------------------------------------------------>|
| | | |
|<---------------------------------------------------+ |<------------------------------------------------------+
| 2.05 Content | | 2.05 Content |
| Observe: 42 | | Observe: 42 |
| Content-Format: application/ace-trl+cbor | | Content-Format: 262 (application/ace-trl+cbor) |
| Payload: { | | Payload: { |
| e'full_set' : [] | | / full_set / 0: [] |
| } | | } |
| | | |
| ... | | ... |
| | | |
| (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 | | 2.05 Content |
| Observe: 53 | | Observe: 53 |
| Content-Format: application/ace-trl+cbor | | Content-Format: 262 (application/ace-trl+cbor) |
| Payload: { | | Payload: { |
| e'full_set' : [bstr.h(t1)] | | / full_set / 0: [bstr.h(t1)] |
| } | | } |
| | | |
| ... | | ... |
| | | |
| (Access token t2 is revoked) | | (Access token t2 is revoked) |
| | | |
|<---------------------------------------------------+ |<------------------------------------------------------+
| 2.05 Content | | 2.05 Content |
| Observe: 64 | | Observe: 64 |
| Content-Format: application/ace-trl+cbor | | Content-Format: 262 (application/ace-trl+cbor) |
| Payload: { | | Payload: { |
| e'full_set' : [bstr.h(t1), bstr.h(t2)] | | / full_set / 0: [bstr.h(t1), bstr.h(t2)] |
| } | | } |
| | | |
| ... | | ... |
| | | |
| (Access token t1 expires) | | (Access token t1 expires) |
| | | |
|<---------------------------------------------------+ |<------------------------------------------------------+
| 2.05 Content | | 2.05 Content |
| Observe: 75 | | Observe: 75 |
| Content-Format: application/ace-trl+cbor | | Content-Format: 262 (application/ace-trl+cbor) |
| Payload: { | | Payload: { |
| e'full_set' : [bstr.h(t2)] | | / full_set / 0: [bstr.h(t2)] |
| } | | } |
| | | |
| ... | | ... |
| | | |
| (Access token t2 expires) | | (Access token t2 expires) |
| | | |
| Lost X <------------------------------------------+ | Lost X <---------------------------------------------+
| 2.05 Content | | 2.05 Content |
| Observe: 86 | | Observe: 86 |
| Content-Format: application/ace-trl+cbor | | Content-Format: 262 (application/ace-trl+cbor) |
| Payload: { | | Payload: { |
| e'full_set' : [] | | / full_set / 0: [] |
| } | | } |
| | | |
| ... | | ... |
| | | |
| (Enough time has passed since | | (Enough time has passed since |
| the latest received notification) | | the latest received notification) |
| | | |
| | | |
| GET coap://as.example.com/revoke/trl?diff=8 | | GET coap://as.example.com/revoke/trl?diff=8 |
+--------------------------------------------------->| +------------------------------------------------------>|
| | | |
|<---------------------------------------------------+ |<------------------------------------------------------+
| 2.05 Content | | 2.05 Content |
| Content-Format: application/ace-trl+cbor | | Content-Format: 262 (application/ace-trl+cbor) |
| Payload: { | | Payload: { |
| e'diff_set' : [ | | / diff_set / 1: [ |
| [ [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 12: Interaction for full query with Observe plus diff query Figure 12: Interaction for Full Query with Observe and Diff Query
C.4. Diff Query with Observe and "Cursor" C.4. Diff Query with Observe and "Cursor" Extension
In this example, the AS supports the "Cursor" extension. Hence, the In this example, the AS supports the "Cursor" extension. Hence, the
CBOR map conveyed as payload of the registration response CBOR map conveyed as payload of the registration response
additionally includes a "max_diff_batch" parameter. This specifies additionally includes a "max_diff_batch" parameter. This specifies
the value of MAX_DIFF_BATCH, i.e., the maximum number of diff entries the value of MAX_DIFF_BATCH, i.e., the maximum number of diff entries
that can be included in a response to a diff query request from this that can be included in a response to a diff query request from this
RS. RS.
Figure 13 shows an interaction example considering a CoAP observation Figure 13 shows an interaction example of a CoAP observation and a
and a diff query of the TRL. diff query of the TRL.
The RS specifies the query parameter 'diff' with value 3, i.e., the The RS specifies the 'diff' query parameter with a value of 3, i.e.,
maximum number of diff entries to be specified in a response from the the maximum number of diff entries to be included in a response from
AS. the AS.
After the RS has not received a notification from the AS for a If the RS has not received a notification from the AS for a waiting
waiting time defined by the application, the RS sends a GET request time defined by the application, the RS sends a GET request with no
with no Observe Option to the AS, to perform a diff query of the TRL. Observe Option to the AS, asking the AS to perform a diff query of
the TRL.
This is followed up by a further diff query request that specifies This is followed up by a further diff query request that includes the
the query parameter 'cursor'. Note that the payload of the 'cursor' query parameter. Note that the payload of the corresponding
corresponding response differs from the payload of the response to response differs from the payload of the response to the previous
the previous diff query request. diff query request.
RS AS RS AS
| | | |
| Registration: POST | | Registration: POST |
+------------------------------------------------------->| +---------------------------------------------------------->|
| | | |
|<-------------------------------------------------------+ |<----------------------------------------------------------+
| 2.01 Created | | 2.01 Created |
| Payload: { | | Payload: { |
| / ... / | | / ... / |
| "trl_path" : "/revoke/trl", | | "trl_path": "/revoke/trl", |
| "trl_hash" : "sha-256", | | "trl_hash": "sha-256", |
| "max_n" : 10, | | "max_n": 10, |
| "max_diff_batch": 5 | | "max_diff_batch": 5 |
| } | | } |
| | | |
| GET coap://as.example.com/revoke/trl?diff=3 | | GET coap://as.example.com/revoke/trl?diff=3 |
| Observe: 0 | | Observe: 0 |
+------------------------------------------------------->| +---------------------------------------------------------->|
| | | |
|<-------------------------------------------------------+ |<----------------------------------------------------------+
| 2.05 Content | | 2.05 Content |
| Observe: 42 | | Observe: 42 |
| Content-Format: application/ace-trl+cbor | | Content-Format: 262 (application/ace-trl+cbor) |
| Payload: { | | Payload: { |
| e'diff_set' : [], | | / diff_set / 1: [], |
| e'cursor' : null, | | / cursor / 2: null, |
| e'more' : false | | / more / 3: false |
| } | | } |
| | | |
| ... | | ... |
| | | |
| (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 | | 2.05 Content |
| Observe: 53 | | Observe: 53 |
| Content-Format: application/ace-trl+cbor | | Content-Format: 262 (application/ace-trl+cbor) |
| Payload: { | | Payload: { |
| e'diff_set' : [ | | / diff_set / 1: [ |
| [ [], [bstr.h(t1)] ] | | [ [], [bstr.h(t1)] ] |
| ], | | ], |
| e'cursor' : 0, | | / cursor / 2: 0, |
| e'more' : false | | / more / 3: false |
| } | | } |
| | | |
| ... | | ... |
| | | |
| (Access token t2 is revoked) | | (Access token t2 is revoked) |
| | | |
|<-------------------------------------------------------+ |<----------------------------------------------------------+
| 2.05 Content | | 2.05 Content |
| Observe: 64 | | Observe: 64 |
| Content-Format: application/ace-trl+cbor | | Content-Format: 262 (application/ace-trl+cbor) |
| Payload: { | | Payload: { |
| e'diff_set' : [ | | / diff_set / 1: [ |
| [ [], [bstr.h(t2)] ], | | [ [], [bstr.h(t2)] ], |
| [ [], [bstr.h(t1)] ] | | [ [], [bstr.h(t1)] ] |
| ], | | ], |
| e'cursor' : 1, | | / cursor / 2: 1, |
| e'more' : false | | / more / 3: false |
| } | | } |
| | | |
| ... | | ... |
| | | |
| (Access token t1 expires) | | (Access token t1 expires) |
| | | |
|<-------------------------------------------------------+ |<----------------------------------------------------------+
| 2.05 Content | | 2.05 Content |
| Observe: 75 | | Observe: 75 |
| Content-Format: application/ace-trl+cbor | | Content-Format: 262 (application/ace-trl+cbor) |
| Payload: { | | Payload: { |
| e'diff_set' : [ | | / diff_set / 1: [ |
| [ [bstr.h(t1)], [] ], | | [ [bstr.h(t1)], [] ], |
| [ [], [bstr.h(t2)] ], | | [ [], [bstr.h(t2)] ], |
| [ [], [bstr.h(t1)] ] | | [ [], [bstr.h(t1)] ] |
| ], | | ], |
| e'cursor' : 2, | | / cursor / 2: 2, |
| e'more' : false | | / more / 3: false |
| } | | } |
| | | |
| ... | | ... |
| | | |
| (Access token t2 expires) | | (Access token t2 expires) |
| | | |
|<-------------------------------------------------------+ |<----------------------------------------------------------+
| 2.05 Content | | 2.05 Content |
| Observe: 86 | | Observe: 86 |
| Content-Format: application/ace-trl+cbor | | Content-Format: 262 (application/ace-trl+cbor) |
| Payload: { | | Payload: { |
| e'diff_set' : [ | | / diff_set / 1: [ |
| [ [bstr.h(t2)], [] ], | | [ [bstr.h(t2)], [] ], |
| [ [bstr.h(t1)], [] ], | | [ [bstr.h(t1)], [] ], |
| [ [], [bstr.h(t2)] ] | | [ [], [bstr.h(t2)] ] |
| ], | | ], |
| e'cursor' : 3, | | / cursor / 2: 3, |
| e'more' : false | | / more / 3: false |
| } | | } |
| | | |
| ... | | ... |
| | | |
| (Enough time has passed since | | (Enough time has passed since |
| the latest received notification) | | the latest received notification) |
| | | |
| | | |
| GET coap://as.example.com/revoke/trl?diff=3 | | GET coap://as.example.com/revoke/trl?diff=3 |
+------------------------------------------------------->| +---------------------------------------------------------->|
| | | |
|<-------------------------------------------------------+ |<----------------------------------------------------------+
| 2.05 Content | | 2.05 Content |
| Content-Format: application/ace-trl+cbor | | Content-Format: 262 (application/ace-trl+cbor) |
| Payload: { | | Payload: { |
| e'diff_set' : [ | | / diff_set / 1: [ |
| [ [bstr.h(t2)], [] ], | | [ [bstr.h(t2)], [] ], |
| [ [bstr.h(t1)], [] ], | | [ [bstr.h(t1)], [] ], |
| [ [], [bstr.h(t2)] ] | | [ [], [bstr.h(t2)] ] |
| ], | | ], |
| e'cursor' : 3, | | / cursor / 2: 3, |
| e'more' : false | | / more / 3: false |
| } | | } |
| | | |
| GET coap://as.example.com/revoke/trl?diff=3&cursor=3 | | GET coap://as.example.com/revoke/trl?diff=3&cursor=3 |
+------------------------------------------------------->| +---------------------------------------------------------->|
| | | |
|<-------------------------------------------------------+ |<----------------------------------------------------------+
| 2.05 Content | | 2.05 Content |
| Content-Format: application/ace-trl+cbor | | Content-Format: 262 (application/ace-trl+cbor) |
| Payload: { | | Payload: { |
| e'diff_set' : [], | | / diff_set / 1: [], |
| e'cursor' : 3, | | / cursor / 2: 3, |
| e'more' : false | | / more / 3: false |
| } | | } |
| | | |
Figure 13: Interaction for diff query with Observe and "Cursor" Figure 13: Interaction for Diff Query with Observe and "Cursor"
Extension
C.5. Full Query with Observe plus Diff Query with "Cursor" C.5. Full Query with Observe and Diff Query with "Cursor" Extension
In this example, the AS supports the "Cursor" extension. Hence, the In this example, the AS supports the "Cursor" extension. Hence, the
CBOR map conveyed as payload of the registration response CBOR map conveyed as payload of the registration response
additionally includes a "max_diff_batch" parameter. This specifies additionally includes a "max_diff_batch" parameter. This specifies
the value of MAX_DIFF_BATCH, i.e., the maximum number of diff entries the value of MAX_DIFF_BATCH, i.e., the maximum number of diff entries
that can be included in a response to a diff query request from this that can be included in a response to a diff query request from this
RS. RS.
Figure 14 shows an interaction example considering a CoAP observation Figure 14 shows an interaction example of a CoAP observation and a
and a full query of the TRL. full query of the TRL.
The example also considers some of the notifications from the AS to The example also shows some of the notifications from the AS getting
get lost in transmission, and thus not reaching the RS. lost in transmission; thus, those notifications do not reach the RS.
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 RS sends a GET request with no Observe application has elapsed, the RS sends a GET request with no Observe
Option to the AS, to perform a diff query of the TRL. In particular, Option to the AS, asking the AS to perform a diff query of the TRL.
the RS specifies: In particular, the RS specifies:
* The query parameter 'diff' with value 8, i.e., the maximum number * The 'diff' query parameter with a value of 8, i.e., the maximum
of diff entries to be specified in a response from the AS. number of diff entries to be included in a response from the AS.
* The query parameter 'cursor' with value 2, thus requesting from * The 'cursor' query parameter with a value of 2, thus requesting
the update collection the series items following the one with from the update collection the series items following the one with
'index' value equal to 2 (i.e., following the last series item the 'index' value equal to 2 (i.e., following the last series item
that the RS successfully received in an earlier notification that the RS successfully received in an earlier notification
response). response).
The response from the AS conveys a first batch of MAX_DIFF_BATCH = 5 The response from the AS conveys a first batch of MAX_DIFF_BATCH = 5
series items from the update collection corresponding to the RS. The series items from the update collection corresponding to the RS. The
AS indicates that further series items are actually available in the AS indicates that further series items are actually available in the
update collection, by setting the 'more' parameter of the response to update collection by setting the 'more' parameter of the response to
true. Also, the 'cursor' parameter of the response is set to 7, true. Also, the 'cursor' parameter of the response is set to 7,
i.e., to the 'index' value of the most recent series item included in i.e., to the 'index' value of the most recent series item included in
the response. the response.
After that, the RS follows up with a further diff query request After that, the RS follows up with a further diff query request
specifying the query parameter 'cursor' with value 7, in order to including the 'cursor' query parameter with a value of 7 in order to
retrieve the next and last batch of series items from the update retrieve the next and last batch of series items from the update
collection. collection.
RS AS RS AS
| | | |
| Registration: POST | | Registration: POST |
+-------------------------------------------------------------->| +----------------------------------------------------------------->|
| | | |
|<--------------------------------------------------------------+ |<-----------------------------------------------------------------+
| 2.01 Created | | 2.01 Created |
| Payload: { | | Payload: { |
| / ... / | | / ... / |
| "trl_path" : "/revoke/trl", | | "trl_path": "/revoke/trl", |
| "trl_hash" : "sha-256", | | "trl_hash": "sha-256", |
| "max_n" : 10, | | "max_n": 10, |
| "max_diff_batch": 5 | | "max_diff_batch": 5 |
| } | | } |
| | | |
| GET coap://as.example.com/revoke/trl/ | | GET coap://as.example.com/revoke/trl/ |
| Observe: 0 | | Observe: 0 |
+-------------------------------------------------------------->| +----------------------------------------------------------------->|
| | | |
|<--------------------------------------------------------------+ |<-----------------------------------------------------------------+
| 2.05 Content | | 2.05 Content |
| Observe: 42 | | Observe: 42 |
| Content-Format: application/ace-trl+cbor | | Content-Format: 262 (application/ace-trl+cbor) |
| Payload: { | | Payload: { |
| e'full_set' : [], | | / full_set / 0: [], |
| e'cursor' : null | | / cursor / 2: null |
| } | | } |
| | | |
| ... | | ... |
| | | |
| (Access tokens t1, t2, t3 issued | | (Access tokens t1, t2, t3 issued |
| and successfully submitted to RS) | | and successfully submitted to RS) |
| | | |
| ... | | ... |
| | | |
| (Access tokens t4, t5, t6 issued | | (Access tokens t4, t5, t6 issued |
| and successfully submitted to RS) | | and successfully submitted to RS) |
| | | |
| ... | | ... |
| | | |
| (Access token t1 is revoked) | | (Access token t1 is revoked) |
| | | |
|<--------------------------------------------------------------+ |<-----------------------------------------------------------------+
| 2.05 Content | | 2.05 Content |
| Observe: 53 | | Observe: 53 |
| Content-Format: application/ace-trl+cbor | | Content-Format: 262 (application/ace-trl+cbor) |
| Payload: { | | Payload: { |
| e'full_set' : [bstr.h(t1)], | | / full_set / 0: [bstr.h(t1)], |
| e'cursor' : 0 | | / cursor / 2: 0 |
| } | | } |
| | | |
| ... | | ... |
| | | |
| (Access token t2 is revoked) | | (Access token t2 is revoked) |
| | | |
|<--------------------------------------------------------------+ |<-----------------------------------------------------------------+
| 2.05 Content | | 2.05 Content |
| Observe: 64 | | Observe: 64 |
| Content-Format: application/ace-trl+cbor | | Content-Format: 262 (application/ace-trl+cbor) |
| Payload: { | | Payload: { |
| e'full_set' : [bstr.h(t1), bstr.h(t2)], | | / full_set / 0: [bstr.h(t1), bstr.h(t2)], |
| e'cursor' : 1 | | / cursor / 2: 1 |
| } | | } |
| | | |
| ... | | ... |
| | | |
| (Access token t1 expires) | | (Access token t1 expires) |
| | | |
|<--------------------------------------------------------------+ |<-----------------------------------------------------------------+
| 2.05 Content | | 2.05 Content |
| Observe: 75 | | Observe: 75 |
| Content-Format: application/ace-trl+cbor | | Content-Format: 262 (application/ace-trl+cbor) |
| Payload: { | | Payload: { |
| e'full_set' : [bstr.h(t2)], | | / full_set / 0: [bstr.h(t2)], |
| e'cursor' : 2 | | / cursor / 2: 2 |
| } | | } |
| | | |
| ... | | ... |
| | | |
| (Access token t2 expires) | | (Access token t2 expires) |
| | | |
| Lost X <-----------------------------------------------------+ | Lost X <--------------------------------------------------------+
| 2.05 Content | | 2.05 Content |
| Observe: 86 | | Observe: 86 |
| Content-Format: application/ace-trl+cbor | | Content-Format: 262 (application/ace-trl+cbor) |
| Payload: { | | Payload: { |
| e'full_set' : [], | | / full_set / 0: [], |
| e'cursor' : 3 | | / cursor / 2: 3 |
| } | | } |
| | | |
| ... | | ... |
| | | |
| (Access token t3 is revoked) | | (Access token t3 is revoked) |
| | | |
| Lost X <-----------------------------------------------------+ | Lost X <--------------------------------------------------------+
| 2.05 Content | | 2.05 Content |
| Observe: 88 | | Observe: 88 |
| Content-Format: application/ace-trl+cbor | | Content-Format: 262 (application/ace-trl+cbor) |
| Payload: { | | Payload: { |
| e'full_set' : [bstr.h(t3)], | | / full_set / 0: [bstr.h(t3)], |
| e'cursor' : 4 | | / cursor / 2: 4 |
| } | | } |
| | | |
| ... | | ... |
| | | |
| (Access token t4 is revoked) | | (Access token t4 is revoked) |
| | | |
| Lost X <-----------------------------------------------------+ | Lost X <--------------------------------------------------------+
| 2.05 Content | | 2.05 Content |
| Observe: 89 | | Observe: 89 |
| Content-Format: application/ace-trl+cbor | | Content-Format: 262 (application/ace-trl+cbor) |
| Payload: { | | Payload: { |
| e'full_set' : [bstr.h(t3), bstr.h(t4)], | | / full_set / 0: [bstr.h(t3), bstr.h(t4)], |
| e'cursor' : 5 | | / cursor / 2: 5 |
| } | | } |
| | | |
| ... | | ... |
| | | |
| (Access token t3 expires) | | (Access token t3 expires) |
| | | |
| Lost X <-----------------------------------------------------+ | Lost X <--------------------------------------------------------+
| 2.05 Content | | 2.05 Content |
| Observe: 90 | | Observe: 90 |
| Content-Format: application/ace-trl+cbor | | Content-Format: 262 (application/ace-trl+cbor) |
| Payload: { | | Payload: { |
| e'full_set' : [bstr.h(t4)], | | / full_set / 0: [bstr.h(t4)], |
| e'cursor' : 6 | | / cursor / 2: 6 |
| } | | } |
| | | |
| ... | | ... |
| | | |
| (Access token t4 expires) | | (Access token t4 expires) |
| | | |
| Lost X <-----------------------------------------------------+ | Lost X <--------------------------------------------------------+
| 2.05 Content | | 2.05 Content |
| Observe: 91 | | Observe: 91 |
| Content-Format: application/ace-trl+cbor | | Content-Format: 262 (application/ace-trl+cbor) |
| Payload: { | | Payload: { |
| e'full_set' : [], | | / full_set / 0: [], |
| e'cursor' : 7 | | / cursor / 2: 7 |
| } | | } |
| | | |
| ... | | ... |
| | | |
| (Access tokens t5 and t6 are revoked) | | (Access tokens t5 and t6 are revoked) |
| | | |
| Lost X <-----------------------------------------------------+ | Lost X <--------------------------------------------------------+
| 2.05 Content | | 2.05 Content |
| Observe: 92 | | Observe: 92 |
| Content-Format: application/ace-trl+cbor | | Content-Format: 262 (application/ace-trl+cbor) |
| Payload: { | | Payload: { |
| e'full_set' : [bstr.h(t5), bstr.h(t6)], | | / full_set / 0: [bstr.h(t5), bstr.h(t6)], |
| e'cursor' : 8 | | / cursor / 2: 8 |
| } | | } |
| | | |
| ... | | ... |
| | | |
| (Access token t5 expires) | | (Access token t5 expires) |
| | | |
| Lost X <-----------------------------------------------------+ | Lost X <--------------------------------------------------------+
| 2.05 Content | | 2.05 Content |
| Observe: 93 | | Observe: 93 |
| Content-Format: application/ace-trl+cbor | | Content-Format: 262 (application/ace-trl+cbor) |
| Payload: { | | Payload: { |
| e'full_set' : [bstr.h(t6)], | | / full_set / 0: [bstr.h(t6)], |
| e'cursor' : 9 | | / cursor / 2: 9 |
| } | | } |
| | | |
| ... | | ... |
| | | |
| (Access token t6 expires) | | (Access token t6 expires) |
| | | |
| Lost X <-----------------------------------------------------+ | Lost X <--------------------------------------------------------+
| 2.05 Content | | 2.05 Content |
| Observe: 94 | | Observe: 94 |
| Content-Format: application/ace-trl+cbor | | Content-Format: 262 (application/ace-trl+cbor) |
| Payload: { | | Payload: { |
| e'full_set' : [], | | / full_set / 0: [], |
| e'cursor' : 10 | | / cursor / 2: 10 |
| } | | } |
| | | |
| ... | | ... |
| | | |
| (Enough time has passed since | | (Enough time has passed since |
| the latest received notification) | | the latest received notification) |
| | | |
| | | |
| GET coap://as.example.com/revoke/trl?diff=8&cursor=2 | | GET coap://as.example.com/revoke/trl?diff=8&cursor=2 |
+-------------------------------------------------------------->| +----------------------------------------------------------------->|
| | | |
|<--------------------------------------------------------------+ |<-----------------------------------------------------------------+
| 2.05 Content | | 2.05 Content |
| Content-Format: application/ace-trl+cbor | | Content-Format: 262 (application/ace-trl+cbor) |
| Payload: { | | Payload: { |
| e'diff_set' : [ | | / diff_set / 1: [ |
| [ [bstr.h(t4)], [] ], | | [ [bstr.h(t4)], [] ], |
| [ [bstr.h(t3)], [] ], | | [ [bstr.h(t3)], [] ], |
| [ [], [bstr.h(t4)] ], | | [ [], [bstr.h(t4)] ], |
| [ [], [bstr.h(t3)] ], | | [ [], [bstr.h(t3)] ], |
| [ [bstr.h(t2)], [] ] | | [ [bstr.h(t2)], [] ] |
| ], | | ], |
| e'cursor' : 7, | | / cursor / 2: 7, |
| e'more' : true | | / more / 3: true |
| } | | } |
| | | |
| GET coap://as.example.com/revoke/trl?diff=8&cursor=7 | | GET coap://as.example.com/revoke/trl?diff=8&cursor=7 |
+-------------------------------------------------------------->| +----------------------------------------------------------------->|
| | | |
|<--------------------------------------------------------------+ |<-----------------------------------------------------------------+
| 2.05 Content | | 2.05 Content |
| Content-Format: application/ace-trl+cbor | | Content-Format: 262 (application/ace-trl+cbor) |
| Payload: { | | Payload: { |
| e'diff_set' : [ | | / diff_set / 1: [ |
| [ [bstr.h(t6)], [] ], | | [ [bstr.h(t6)], [] ], |
| [ [bstr.h(t5)], [] ], | | [ [bstr.h(t5)], [] ], |
| [ [], [bstr.h(t5), bstr.h(t6)] ] | | [ [], [bstr.h(t5), bstr.h(t6)] ] |
| ], | | ], |
| e'cursor' : 10, | | / cursor / 2: 10, |
| e'more' : false | | / more / 3: false |
| } | | } |
| | | |
Figure 14: Interaction for full query with Observe plus diff
query with "Cursor"
Appendix D. CDDL Model
This section is to be removed before publishing as an RFC.
full_set = 0
diff_set = 1
cursor = 2
more = 3
ace-trl-error = 1
Figure 15: CDDL model
Appendix E. Document Updates
This section is to be removed before publishing as an RFC.
E.1. Version -08 to -09
* Terminology:
- Improved definition of "administrator".
- Added early definitions of "Full query" and "Diff query".
* Rephrased "full TRL" to avoid confusion with "full query".
* Consistent with RFC 6920, defined sha-256 as mandatory to
implement.
* Prevented an attack to the RS by:
- Using only Protected Headers in access tokens.
- Using canonical CBOR tagging of CWTs.
* Clarifications:
- Handling of access tokens with 'exi' for both CWTs and JWTs.
- Registrations of devices are persisted and tracked at the AS.
- No response or error response from the TRL endpoint yields no
assumption.
- Rationale of application policies in defining strategies and
schedules for polling the AS.
* Security considerations:
- Added reference to RFC 8725.
- Improved considerations on content retrieval from the TRL.
* IANA:
- Added a pointer to where the use of the field 'cursor' in
problem-details is defined.
- Revised text on Expert Review when using early allocation per
RFC 7120.
* Split elision and comments in examples with CBOR Diagnostic
Notation.
* Lowercase capitalization for "client", "resource server", and
"authorization server".
* Editorial improvements.
E.2. Version -07 to -08
* Added definition of pertaining token hash.
* Added definition of pertaining TRL update.
* Rephrased example of token uploading to be more future ready.
* Consistent use of "TRL update" throughout the document.
* Editorial improvements.
E.3. Version -06 to -07
* RFC 9290 is used instead of the custom format for error responses.
* Avoided quotation marks when using CBOR simple values.
* CBOR diagnostic notation uses placeholders from a CDDL model.
* Early mentioning that there is a single MAX_N value.
* Added more details on the authorization of administrators.
* Added recommendations for avoiding lost TRL updates from going
unnoticed.
* If diff queries are supported, the AS MUST provide MAX_N at
registration.
* If the "Cursor" extension is supported, the AS MUST provide
MAX_DIFF_BATCH at registration.
* Clarified that how the token revocation specifically happens is
out of scope.
* Clearer, upfront distinction between using CoAP Observe or not.
* Revised and extended method for computing the token hashes.
* Clearer presentation of invalid requests to the TRL endpoint.
* Clearer expected relation between MAX_INDEX and MAX_N values.
* Clarified meaning of registered parameters.
* Generalized security considerations on vulnerable time window at
the RS.
* Added security considerations on additional security measures.
* Fixes and improvements in the IANA considerations.
* Used AASVG in diagrams.
* Used actual tables instead of figures.
* Fixed notation in the examples.
* Clarifications and editorial improvements.
E.4. Version -05 to -06
* Clarified instructions for Expert Review in the IANA
considerations.
E.5. Version -04 to -05
* Explicit focus on CoAP in the abstract and introduction.
* Removed terminology aliasing ("TRL endpoint" vs. "TRL resource").
* Use "requester" instead of "caller".
* Use "subset" instead of "portion".
* Revised presentation of how token hashes are computed.
* Improved error handling.
* Revised examples.
* More precise security considerations.
* Clarifications and editorial improvements.
* Updated author list.
E.6. Version -03 to -04
* Improved presentation of pre- and post-registration operations.
* Removed moot processing cases with the "Cursor" extension.
* Positive integers as CBOR abbreviations for all parameters.
* Renamed N_MAX as MAX_N.
* Access tokens are not necessarily uploaded through /authz-info.
* The use of the "c.pmax" conditional attribute is just an example.
* Revised handling of token hashes at the RS.
* Extended and improved security considerations.
* Fixed details in IANA considerations.
* New appendix overviewing parameters of the TRL endpoint.
* Examples of message exchange moved to an appendix.
* Added examples of message exchange with the "Cursor" extension.
* Clarifications and editorial improvements.
E.7. Version -02 to -03
* Definition of MAX_INDEX for the "Cursor" extension.
* Handling wrap-around of 'index' when using the "Cursor" extension.
* Error handling for the case where 'cursor' > MAX_INDEX.
* Improved error handling in case 'index' is out-of-bound.
* Clarified parameter semantics, message content and examples.
* Editorial improvements.
E.8. Version -01 to -02
* Earlier mentioning of error cases.
* Clearer distinction between maintaining the history of TRL updates
and preparing the response to a diff query.
* Defined the use of "cursor" in the document body, as an extension
of diff queries.
* Both success and error responses have a CBOR map as payload.
* Corner cases of message processing explained more explicitly.
* Clarifications and editorial improvements.
E.9. Version -00 to -01
* Added actions to perform upon receiving responses from the TRL
endpoint.
* Fixed off-by-one error when using the "Cursor" pattern.
* Improved error handling, with registered error codes.
* Section restructuring (full- and diff-query as self-standing
sections).
* Renamed identifiers and CBOR parameters.
* Clarifications and editorial improvements. Figure 14: Interaction for Full Query with Observe and Diff Query
with "Cursor" Extension
Acknowledgments Acknowledgments
Ludwig Seitz contributed as a co-author of initial versions of this Ludwig Seitz contributed as a coauthor of initial versions of this
document. document.
The authors sincerely thank Christian Amsüss, Carsten Bormann, Deb The authors sincerely thank Christian Amsüss, Carsten Bormann, Deb
Cooley, Roman Danyliw, Dhruv Dhody, Rikard Höglund, Benjamin Kaduk, Cooley, Roman Danyliw, Dhruv Dhody, Rikard Höglund, Benjamin Kaduk,
David Navarro, Joerg Ott, Marco Rasori, Michael Richardson, Kyle David Navarro, Joerg Ott, Marco Rasori, Michael Richardson, Kyle
Rose, Zaheduzzaman Sarker, Jim Schaad, Göran Selander, Travis Rose, Zaheduzzaman Sarker, Jim Schaad, Göran Selander, Travis
Spencer, Orie Steele, Éric Vyncke, Niklas Widell, Dale Worley, and Spencer, Orie Steele, Éric Vyncke, Niklas Widell, Dale Worley, and
Paul Wouters for their comments and feedback. Paul Wouters for their comments and feedback.
The work on this document has been partly supported by the Sweden's The work on this document has been partly supported by the Sweden's
Innovation Agency VINNOVA and the Celtic-Next projects CRITISEC and Innovation Agency VINNOVA and the Celtic-Next projects CRITISEC and
CYPRESS; and by the H2020 project SIFIS-Home (Grant agreement CYPRESS; and by the H2020 project SIFIS-Home (Grant agreement
952652). 952652).
Authors' Addresses Authors' Addresses
Marco Tiloca Marco Tiloca
RISE AB RISE AB
Isafjordsgatan 22 Isafjordsgatan 22
SE-16440 Kista SE-164 40 Kista
Sweden Sweden
Email: marco.tiloca@ri.se Email: marco.tiloca@ri.se
Francesca Palombini Francesca Palombini
Ericsson AB Ericsson AB
Torshamnsgatan 23 Torshamnsgatan 23
SE-16440 Kista SE-164 40 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. 436 change blocks. 
1929 lines changed or deleted 1701 lines changed or added

This html diff was produced by rfcdiff 1.48.