RFC 9594
Key Provisioning for Group Communication Using Authentication and Authorization for Constrained Environments (ACE)
Key Provisioning for Group Communication Using Authentication and Authorization for Constrained Environments (ACE) 🎀
Okay bestie, this is RFC 9594 💖 It's from the Internet Engineering Task Force (IETF) and it's a Standards Track document, so it's an actual Internet standard, not just a suggestion 👑. It came out in September 2024 with ISSN 2070-1721. The authors are F. Palombini from Ericsson AB and M. Tiloca from RISE AB, and they're literally the ones who wrote the whole spec ✨. The header doesn't list anything it obsoletes or updates, so it's a brand new standard and isn't replacing or patching any other RFC 🦋.
Abstract
This document defines how to use the Authentication and Authorization for Constrained Environments (ACE) framework to distribute keying material and configuration parameters for secure group communication. Candidate group members that act as Clients and are authorized to join a group can do so by interacting with a Key Distribution Center (KDC) acting as the Resource Server, from which they obtain the keying material to communicate with other group members. While defining general message formats as well as the interface and operations available at the KDC, this document supports different approaches and protocols for secure group communication. Therefore, details are delegated to separate application profiles of this document as specialized instances that target a particular group communication approach and define how communications in the group are protected. Compliance requirements for such application profiles are also specified. 🌸
Status of This Memo
This is an Internet Standards Track document.
This document is a product of the Internet Engineering Task Force (IETF). It represents the consensus of the IETF community. It has received public review and has been approved for publication by the Internet Engineering Steering Group (IESG). Further information on Internet Standards is available in Section 2 of RFC 7841.
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/rfc9594. 🧚
Copyright Notice
Copyright (c) 2024 IETF Trust and the persons identified as the document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Revised BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Revised BSD License. 💅
Table of Contents 🍓
1. Introduction
1.1. Terminology
2. Overview
3. Authorization to Join a Group
3.1. Authorization Request
3.2. Authorization Response
3.3. Token Transferring
3.3.1. 'sign_info' Parameter
3.3.2. 'kdcchallenge' Parameter
4. KDC Functionalities
4.1. Interface at the KDC
4.1.1. Operations Supported by Clients
4.1.2. Error Handling
4.2. /ace-group
4.2.1. FETCH Handler
4.2.1.1. Retrieve Group Names
4.3. /ace-group/GROUPNAME
4.3.1. POST Handler
4.3.1.1. Join the Group
4.3.2. GET Handler
4.3.2.1. Retrieve Group Keying Material
4.4. /ace-group/GROUPNAME/creds
4.4.1. FETCH Handler
4.4.1.1. Retrieve a Subset of Authentication Credentials in
the Group
4.4.2. GET Handler
4.4.2.1. Retrieve All Authentication Credentials in the
Group
4.5. /ace-group/GROUPNAME/kdc-cred
4.5.1. GET Handler
4.5.1.1. Retrieve the KDC's Authentication Credential
4.6. /ace-group/GROUPNAME/policies
4.6.1. GET Handler
4.6.1.1. Retrieve the Group Policies
4.7. /ace-group/GROUPNAME/num
4.7.1. GET Handler
4.7.1.1. Retrieve the Keying Material Version
4.8. /ace-group/GROUPNAME/nodes/NODENAME
4.8.1. GET Handler
4.8.1.1. Retrieve Group and Individual Keying Material
4.8.2. POST Handler
4.8.2.1. Request to Change Individual Keying Material
4.8.3. DELETE Handler
4.8.3.1. Leave the Group
4.9. /ace-group/GROUPNAME/nodes/NODENAME/cred
4.9.1. POST Handler
4.9.1.1. Uploading an Authentication Credential
5. Removal of a Group Member
6. Group Rekeying Process
6.1. Point-to-Point Group Rekeying
6.2. One-to-Many Group Rekeying
6.2.1. Protection of Rekeying Messages
6.3. Misalignment of Group Keying Material
7. Extended Scope Format
8. ACE Groupcomm Parameters
9. ACE Groupcomm Error Identifiers
10. Security Considerations
10.1. Secure Communication in the Group
10.2. Update of Group Keying Material
10.3. Block-Wise Considerations
11. IANA Considerations
11.1. Media Type Registrations
11.2. CoAP Content-Formats
11.3. OAuth Parameters
11.4. OAuth Parameters CBOR Mappings
11.5. Interface Description (if=) Link Target Attribute Values
11.6. Custom Problem Detail Keys Registry
11.7. ACE Groupcomm Parameters
11.8. ACE Groupcomm Key Types
11.9. ACE Groupcomm Profiles
11.10. ACE Groupcomm Policies
11.11. Sequence Number Synchronization Methods
11.12. ACE Groupcomm Errors
11.13. ACE Groupcomm Rekeying Schemes
11.14. Expert Review Instructions
12. References
12.1. Normative References
12.2. Informative References
Appendix A. Requirements for Application Profiles
A.1. Mandatory-to-Address Requirements
A.2. Optional-to-Address Requirements
Appendix B. Extensibility for Future COSE Algorithms
B.1. Format of 'sign_info_entry'
Acknowledgments
Authors' Addresses1. Introduction 🦋
This document builds on the Authentication and Authorization for Constrained Environments (ACE) framework and defines how to request, distribute, and renew keying material and configuration parameters to protect message exchanges in a group communication environment. ✨
Candidate group members that act as ACE Clients and are authorized to join a group can interact with the Key Distribution Center (KDC) acting as the ACE Resource Server that is responsible for that group in order to obtain the necessary keying material and parameters to communicate with other group members. 🫶
In particular, this document defines the operations and interface available at the KDC, as well as general message formats for the interactions between Clients and the KDC. At the same time, communications in the group can rely on different approaches, e.g., based on multicast [GROUP-CoAP] or publish-subscribe (pub-sub) messaging [CoAP-PUBSUB], and can be protected in different ways. 🌈
Therefore, this document delegates details on the communication and security approaches used in a group to separate application profiles. These are specialized instances of this document that target a particular group communication approach and define how communications in the group are protected, as well as the specific keying material and configuration parameters provided to group members. 💜
In order to ensure consistency and aid the development of such application profiles, Appendix A of this document defines a number of related compliance requirements. In particular, Appendix A.1 compiles the requirements that application profiles are REQUIRED to fulfill; these are referred to by an identifier that starts with "REQ". Instead, Appendix A.2 compiles the requirements that application profiles MAY fulfill; these are referred to by an identifier that starts with "OPT". 🎀
New keying material is intended to be generated and distributed to the group upon membership changes (rekeying). If the application requires backward security (i.e., new group members must be prevented from accessing communications in the group prior to their joining), then a rekeying has to occur every time new members join the group. If the application requires forward security (i.e., former group members must be prevented from accessing communications in the group after their leaving), then a rekeying has to occur every time current members leave or are evicted from the group. 🔥
A group rekeying scheme performs the actual distribution of the new keying material by rekeying the current group members when a new Client joins the group and rekeying the remaining group members when a Client leaves the group. This can rely on different approaches, including efficient group rekeying schemes such as those described in [RFC2093], [RFC2094], and [RFC2627]. 🌸
Consistently with what is recommended in the ACE framework, this document uses Concise Binary Object Representation (CBOR) [RFC8949] for data encoding. However, using JSON [RFC8259] instead of CBOR is possible by relying on the conversion method specified in Sections 6.1 and 6.2 of [RFC8949]. Part 1 of 27 is all set, let's keep going! 🍓
1.1. Terminology 💅
Okay bestie, the BCP 14 key words are "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" 🎀. They only count as real requirement words when they're written in all capitals, just like shown here, and they get read the BCP 14 way [RFC2119] [RFC8174] 💜.
Before we dive in, you should already know these (iykyk 🫶):
- The ACE framework [RFC9200] and the Authorization Information Format (AIF) [RFC9237], which is how we express authorization info ✨. The entity terms for this architecture come from OAuth 2.0 [RFC6749], so we've got Client (C), Resource Server (RS), and Authorization Server (AS) 👑.
- The Constrained Application Protocol (CoAP) [RFC7252] 🌸. We borrow "endpoint" from OAuth here, meaning stuff like
/tokenand/introspectat the AS, and/authz-infoat the RS 🦋. This doc does not use the CoAP definition, which is "An entity participating in the CoAP protocol" 🙈. - Concise Data Definition Language (CDDL) [RFC8610], CBOR [RFC8949], and CBOR Object Signing and Encryption (COSE) [RFC9052] [RFC9053] [RFC9338] 🧚.
A node that wants to join group communication, and a node that's already a group member, are both called "Client" interchangeably 💖. Lowkey the same person, just at different stages 😭.
This document also uses the following terms 💅.
Group: A set of nodes that share common keying material and security parameters used to protect their communications with one another. Basically, this is a "security group," so that's what the term refers to 🔐.
Don't mix this up with an "application group," which lives at the application level and whose members share a common pool of resources or content 🍓. Examples of application groups are the set of all nodes deployed in a same physical room or the set of nodes registered to a pub-sub topic 🌈.
Also don't mix it up with a "multicast group," which lives at the network level and whose members all listen to a group network address for receiving messages sent to that group ✨. An example of a multicast group is the set of nodes that are configured to receive messages that are sent to the group's associated IP multicast address 📡.
The same security group might be associated with multiple application groups. Also, the same application group might be associated with multiple security groups 🦄. Further details and considerations on the mapping between the three types of groups are out of the scope of this document 🙃.
Key Distribution Center (KDC): The entity responsible for managing one or multiple groups, with particular reference to the group membership and the keying material to use for protecting group communications 👑🔑.
Furthermore, this document uses "names" or "identifiers" for groups and nodes 🎀. Their different meanings are summarized below 💕.
Group name: The identifier of a group as a text string encoded as UTF-8 [RFC3629] 🌷. Once established, it is invariant 💎. It is used in the interactions between the Client, AS, and RS to identify a group 🫶. A group name is always unique among the group names of the existing groups under the same KDC 💯.
GROUPNAME: The text string used in URIs to identify a group 🌐. Once established, it is invariant 💎. GROUPNAME uniquely maps to the group name of a group, although they do not necessarily coincide ✨.
Group identifier: The identifier of the group keying material used in a group 🗝️. Unlike group name and GROUPNAME, this identifier changes over time when the group keying material is updated 🔄.
Node name: The identifier of a node as a text string encoded as UTF-8 [RFC3629] and consistent with the semantics of URI path segments (see Section 3.3 of [RFC3986]) 🧁. Once established, it is invariant 💎. It is used in the interactions between the Client and RS, as well as to identify a member of a group 🧚. A node name is always unique among the node names of the current nodes within a group 💜.
NODENAME: The text string used in URIs to identify a member of a group 🍭. Once established, it is invariant 💎. Its value coincides with the node name of the associated group member 🌸.
This document additionally uses the following terminology 💅.
Transport profile: A profile of the ACE framework as per Section 5.8.4.3 of [RFC9200] 🚀. A transport profile specifies the communication protocol and communication security protocol between an ACE Client and Resource Server, as well as proof-of-possession methods if it supports proof-of-possession access tokens 🔐. Transport profiles of ACE include, for instance, those described in [RFC9202], [RFC9203], and [RFC9431] 🦋.
Application profile: A profile that defines how applications enforce and use supporting security services they require 🎀. These services may include, for instance, provisioning, revocation, and distribution of keying material 🔑. An application profile may define specific procedures and message formats 📝.
Authentication credential: The set of information associated with an entity, including that entity's public key and parameters associated with the public key 🪪. Examples of authentication credentials are CBOR Web Tokens (CWTs) and CWT Claims Sets (CCSs) [RFC8392], X.509 certificates [RFC5280], and C509 certificates [C509-CERT] 🌟.
Individual keying material: Information pertaining exclusively to a group member, as associated with its group membership and related to other keying material and parameters used in the group 🧸. For example, this can be an identifier that the secure communication protocol employs to uniquely identify a node as a group member (e.g., a cryptographic key identifier uniquely associated with the group member in question) 🆔. The specific nature and format of individual keying material used in a group is defined in the application profiles of this specification 📚. The individual keying material of a group member is not related to the secure association between that group member and the KDC 🫧.
Throughout this document, examples for CBOR data items are expressed in CBOR extended diagnostic notation as defined in Section 8 of [RFC8949] and Appendix G of [RFC8610] ("diagnostic notation"), unless noted otherwise 🦄. We often use diagnostic notation comments to provide a textual representation of the parameters' keys and values 💖✨.
2. Overview ✨
okay bestie, big picture first 🦋 the key provisioning process is split into two phases. phase one follows the ACE framework between the Client, AS, and KDC. phase two is the actual key distribution between the Client and KDC. once both phases are done, the Client can join the group chat (aka group communication) through a Dispatcher entity 💅
.------------. .------------.
| AS | .----->| KDC |
'------------' | '------------'
^ |
| |
v |
.------------. | .-----------.
| Client |<-------' .------------. | .---------+-.
| |<------------->| Dispatcher |<----->| | .---------+-.
'------------' '------------' '-+ | Group |
'-+ members |
'-----------'
Figure 1: Key Distribution Participantsthese are the main characters (see Figure 1) who show up for authorization and key distribution 💜
- Client (C): a node that wants to join a group and take part in group communication with other group members. inside the group, the Client can have different roles 🎀
- Authorization Server (AS): as the AS is defined in the ACE framework [RFC9200], it enforces access policies that decide whether a node is allowed to join a given group or not, and with what roles and rights (e.g., write and/or read). its whole vibe is gatekeeping 🔐
- Key Distribution Center (KDC): an entity that maintains the keying material that protects group communications, and provides it to Clients who are authorized to join a given group. during the first phase of the process (Section 3), the KDC takes the role of the RS in the ACE framework. during the second phase (Section 4), which is not based on the ACE framework, the KDC distributes the keying material. the KDC also gives the latest keying material to group members when they request it or, if the application requires it, when group membership changes 🧚
- Group members: nodes that have joined a group, where they take part in group communication with one another and protect it with the group keying material obtained from the KDC. squad goals 🫶
- Dispatcher: an entity the Clients use to communicate with the group when they send a message meant for multiple group members. basically, the Dispatcher distributes that one-to-many message to the group members as its intended recipients. the Dispatcher does not have access to the group keying material 🙈 a single-recipient message meant for only one group member may be delivered by alternative means, i.e., with no assistance from the Dispatcher.
examples of a Dispatcher are: the Broker in a pub-sub setting 📮; a relayer for group communication that delivers group messages as multiple unicast messages to all group members 🏃♀️; and an implicit entity, as in a multicast communication setting, where messages are sent to a multicast IP address and delivered on the transport channel 🌈
if it's an explicit entity, like a pub-sub Broker or a message relayer, the Dispatcher is comparable to an untrusted on-path intermediary. so it can see the messages Clients send in the group, but it can't decrypt them and read the plain content 👀
This document specifies a mechanism for:
- Authorizing a Client to join the group (Section 3) and providing it with the group keying material to communicate with the other group members (Section 4),
- Allowing a group member to retrieve group keying material (Sections 4.3.2.1 and 4.8.1.1),
- Allowing a group member to retrieve authentication credentials of other group members (Section 4.4.1.1) and to provide an updated authentication credential (Section 4.9.1.1),
- Allowing a group member to leave the group (Section 4.8.3.1),
- Evicting a group member from the group (Section 5), and
- Renewing and redistributing the group keying material (rekeying), e.g., upon a membership change in the group (Section 6).
rekeying the group may cause a temporary misalignment of the keying material stored by the different group members. the different situations where this can happen, and how they can be handled, are discussed in Section 6.3 🔄
figure 2 gives a high-level overview of the message flow for a node joining a group ✨ the flow can be expanded like this:
- the joining node requests an access token from the AS so it can access one or more group-membership resources at the KDC and join the associated groups 🎟️
this exchange between the Client and AS MUST be secured, as specified by the transport profile of ACE used between the Client and KDC. based on the response from the AS, the joining node will establish or continue using a secure communication association with the KDC 🔒
- the joining node transfers its authentication and authorization information to the KDC by transferring the obtained access token. this is typically done by including the access token in a request sent to the
/authz-infoendpoint at the KDC 📨
once this exchange is completed, the joining node MUST have a secure communication association established with the KDC before joining a group under that KDC 💅
this exchange, and the secure communications that follow between the Client and the KDC, MUST occur in accordance with the transport profile of ACE used between the Client and KDC, such as the DTLS transport profile of ACE [RFC9202] or the OSCORE transport profile of ACE [RFC9203] 🛡️
- the joining node starts the joining process to become a member of the group by sending a request to the related group-membership resource at the KDC. based on the application requirements and policies, the KDC may perform a group rekeying by generating new group keying material and distributing it to the current group members through the rekeying scheme used in the group 🔑
at the end of the joining process, the joining node has received the parameters and group keying material from the KDC so it can securely communicate with the other group members. the KDC has also stored the association between the authorization information from the access token and the secure communication association with the joining node 🎀
- the joining node and the KDC maintain the secure communication association to support future communications. these especially include key management operations, such as retrieving updated keying material or taking part in a group rekeying process 🧁
- the joining node can communicate securely with the other group members by using the keying material obtained in step 3 🥳
C AS KDC Group
| | | Members
/ | | | |
| |--- Authorization Request -->| | |
| | | | |
| |<-- Authorization Response --| | |
(*) < | | | |
| | | | |
| |--- Token Transfer Request ---->| |
| | | |
| |<--- Token Transfer Response-----| |
\ | | | |
| | | |
|--------- Join Request --------->| |
| | | |
| | | -- Group rekeying -->|
| | | (optional) |
|<-------- Join Response ---------| |
| | | |
| | | |
| | | Dispatcher |
| | |
|<======= Secure group communication =========|=========>|
| | |
(*) Defined in the ACE framework
Figure 2: Message Flow upon a New Node's Joining3. Authorization to Join a Group 💖
this section gets into the nitty-gritty format of the messages the participants swap when a node asks for access to a given group 🧚 this exchange is based on ACE [RFC9200].
as defined in [RFC9200], the Client asks the AS for authorization to join the group through the KDC (see Section 3.1). if the request is approved and authorization is granted, the AS gives the Client a proof-of-possession access token and the parameters to securely communicate with the KDC (see Section 3.2) 🎟️
communications between the Client and the AS MUST be secured according to what the used transport profile of ACE defines 🔐 the Content-Format in the message also depends on the used transport profile of ACE. for example, it can be application/ace+cbor for the first two messages and application/cwt for the third message, which are defined in the ACE framework 📜
the transport profile of ACE also defines a number of details, such as the communication and security protocols used with the KDC (see Appendix C of [RFC9200]) 🌸
figure 3 gives an overview of the exchange described above 🦋
Client AS KDC
| | |
|---- Authorization Request: POST /token ------->| |
| | |
|<--- Authorization Response: 2.01 (Created) ----| |
| | |
|---- Token Transfer Request: POST /authz-info ------->|
| | |
|<--- Token Transfer Response: 2.01 (Created) -------->|
| | |
Figure 3: Message Flow of Join Authorization3.1. Authorization Request 🎀
okay bestie, the Authorization Request is the message the Client sends to the AS 📨 It's defined in Section 5.8.1 of [RFC9200], and it MAY contain the following parameters. If they show up, they MUST have the format and value described below 💅
'scope': this one says which groups the Client wants to access and, optionally, which roles it wants to have in those groups 👑
This parameter is encoded as a CBOR byte string that wraps a CBOR array of scope entries. Every scope entry follows the same format, which is either the Authorization Information Format (AIF) or the textual format described below 🧚
- If AIF is used, each scope entry is encoded as per [RFC9237], so it's a CBOR array [Toid, Tperm] ✨ If a scope entry expresses a set of roles to take in a group (as per this document), the object identifier "Toid" names the group and MUST be encoded as a CBOR text string. The permission set "Tperm" lists the roles the Client wants to take in that group 🦋
AIF is the default for application profiles of this specification, and it's the move if you want a compact encoding of scope 💖 It's especially useful for profiles that define several roles, where the Client might ask for multiple roles at once 🌈
Figure 4 shows an example in CDDL notation [RFC8610] where scope uses AIF 📝
- If the textual format is used, each scope entry is a CBOR array formatted like this 🍓
- First up, the group name, encoded as a CBOR text string.
- Optionally, as the second element, the role or CBOR array of roles that the Client wants to take in the group. This element is optional because roles may already have been pre-assigned to the Client, tied to its verifiable identity credentials. Or the application may have defined a single, well-known role for the target resource(s) and audience(s) 🫶
Figure 5 shows an example in CDDL notation where scope uses the textual format, with the group name and role identifiers encoded as CBOR text strings 🌸
It is REQUIRED for application profiles of this specification to specify the exact format and encoding of scope (REQ1) 😭 That includes defining the set of possible roles and their identifiers, plus the matching encoding to use in the scope entries for the scope format they're using.
If the application profile uses AIF, it is also REQUIRED to register its specific instance of "Toid" and "Tperm", along with the corresponding media type and Content-Format, following the guidelines in [RFC9237] (REQ2) 📋
If the application profile uses the textual format, it MAY additionally specify CBOR values to use for abbreviating the role identifiers (OPT1) 🎀
'audience': an identifier of the KDC 🫧
As defined in [RFC9200], other additional parameters can be included if necessary 💜
Here's Figure 4, the AIF example, so you can see it in action 👀
;# include rfc9237
gname = tstr
permissions = uint .bits roles
roles = &(
Requester: 1,
Responder: 2,
Monitor: 3,
Verifier: 4
)
scope_entries = AIF-Generic<gname, permissions>
scope = bstr .cbor scope_entriesFigure 4: Example of scope Using AIF
And here's Figure 5, the textual format example, with the role identifiers encoded as text strings 🧚♀️
gname = tstr
role = tstr
scope_entry = [gname, ? ( role / [2* role] )]
scope_entries = [* scope_entry]
scope = bstr .cbor scope_entriesFigure 5: Example of scope Using the Textual Format, with the Role Identifiers Encoded as Text Strings
3.2. Authorization Response 🦋
the AS processes the Authorization Request as defined in Section 5.8.2 of [RFC9200] 🔍 It especially checks that the Client is allowed to access the specified groups with the requested roles, or possibly a subset of those 🕵️♀️
If the verification works out, the Authorization Response sent from the AS to the Client is also defined in Section 5.8.2 of [RFC9200] 🎉 One note: the 'expires_in' parameter MAY be omitted if the application defines how the expiration time gets communicated to the Client some other way, or if it sets a default value ⏳
When included, the following parameter MUST have the corresponding values 💅
'scope'has the same format and encoding as'scope'in the Authorization Request, as defined in Section 3.1. If this parameter is not present, the granted scope is equal to the one requested in Section 3.1 ✨
The proof-of-possession access token in the 'access_token' parameter MUST contain the following 🔐
- a confirmation claim (for example, see
'cnf'defined in Section 3.1 of [RFC8747] for CWTs) 💌 - an expiration time claim (for example, see
'exp'defined in Section 3.1.4 of [RFC8392] for CWTs) ⏰ - a scope claim (for example, see
'scope'registered in Section 8.14 of [RFC9200] for CWTs) 💖
If the 'scope' parameter is present in the Authorization Response, this claim specifies the same access control information as the 'scope' parameter. But if the 'scope' parameter is not present in the Authorization Response, this claim specifies the same access control information as the 'scope' parameter of the Authorization Request (if that parameter is present there), or otherwise the default scope that the AS is granting the Client 🌈
By default, this claim has the same encoding as the 'scope' parameter in the Authorization Request, as defined in Section 3.1 🎀
Optionally, an alternative extended format of scope, defined in Section 7, can be used 🦄 This format explicitly signals the semantics used to express the actual access control information, which has to be parsed. That way a Resource Server can correctly process a received access token, even in case:
- The Resource Server implements a KDC that supports multiple application profiles of this specification using different scope semantics, and/or
- The Resource Server implements further services beyond a KDC for group communication using different scope semantics 🧚
If the Authorization Server is aware that this applies to the Resource Server the access token is issued for, the Authorization Server SHOULD use the extended format of scope defined in Section 7 🫶
The access token MAY additionally contain other claims that the transport profile of ACE or other optional parameters require 🍓
When the AS receives an Authorization Request from a Client that was previously authorized, and for which the AS still stores a valid non-expired access token, the AS MAY reply with that token 🥹 Note that it's up to application profiles of ACE to make sure that reposting the same access token does not cause reuse of keying material between nodes. (For example, that's accomplished with the use of random nonces in [RFC9203].) 🔥
3.3. Token Transferring 💌
okay so bestie, the Client sends a Token Transfer Request to the KDC. It's a CoAP POST request that carries the access token and targets the /authz-info endpoint (see Section 5.10.1 of [RFC9200]) 🦋
ngl this request is a little different from the one in [RFC9200] 🙈 because it lets the Client ask the KDC for extra info about the authentication credentials used in the group, so source authentication is covered, plus any possible extra group parameters ✨
The joining node MAY ask for this information from the KDC through the same Token Transfer Request. In this case, the message MUST have Content-Format "application/ace+cbor", registered in Section 8.16 of [RFC9200], and the message payload MUST be formatted as a CBOR map, which MUST include the access token. The CBOR map MAY additionally include the following parameter, which, if included, MUST have the format and value as specified below. 🎀
'sign_info': defined in Section 3.3.1, specifying the CBOR simple value null (0xf6) to request information about the signature algorithm, the signature algorithm parameters, the signature key parameters, and the exact format of authentication credentials used in the groups that the Client has been authorized to join.
Alternatively, that info might already be pre-configured on the joining node, or it can be retrieved by other means. For example, the joining node may have done an early group discovery process and gotten the link to the associated group-membership resource at the KDC, along with attributes describing the group configuration (e.g., see [OSCORE-DISCOVERY]) 🧚
After successful verification, the Client is authorized to receive the group keying material from the KDC and join the group. So the KDC replies to the Client with a Token Transfer Response, which is a CoAP 2.01 (Created) response 🌸
The Token Transfer Response MUST have Content-Format "application/ace+cbor", and its payload is a CBOR map. Note that this deviates from the ACE framework, where the response from the /authz-info endpoint is defined as conveying no payload (see Section 5.10.1 of [RFC9200]) 👀
If a scope entry in the access token specifies a role that requires the Client to send its own authentication credential to the KDC when joining the related group, then the CBOR map MUST include the 'kdcchallenge' parameter defined in Section 3.3.2, specifying a dedicated challenge N_S generated by the KDC. 🔥
Later, when joining the group (see Section 4.3.1.1), the Client uses the 'kdcchallenge' value and additional information to build a proof-of-possession (PoP) input. That input is then used to compute the PoP evidence the Client also gives to the KDC, to prove it possesses its own private key (see the 'client_cred_verify' parameter in Section 4.3.1) 💜
While storing the access token, the KDC MUST store the 'kdcchallenge' value associated with the Client, at least until it receives a Join Request from the Client (see Section 4.3.1.1). That's how it can verify the PoP evidence from the join process and confirm the Client actually has its own private key 🔐 The KDC deletes the 'kdcchallenge' value associated with the Client when it deletes the access token (e.g., when the token expires, see Section 5.10.3 of [RFC9200]) 🫶
The same 'kdcchallenge' value MAY be reused several times by the Client to generate new PoP evidence. For example, the Client might give the KDC a new authentication credential while it's already a group member (see Section 4.9.1.1), or it might join a different group where it wants to use a different authentication credential. Therefore, it is RECOMMENDED that the KDC keeps storing the 'kdcchallenge' value even after the first join is processed. If, upon receiving a Join Request from a Client, the KDC has already discarded the 'kdcchallenge' value, that triggers an error response with a newly generated 'kdcchallenge' value. The Client can use that to restart the join process, as specified in Section 4.3.1.1 🔄
If 'sign_info' is included in the Token Transfer Request, the KDC SHOULD include the 'sign_info' parameter in the Token Transfer Response, in the format defined in Section 3.3.1. Note that the field 'id' of each 'sign_info_entry' specifies the name or array of group names that the 'sign_info_entry' applies to. As an exception, the KDC MAY omit the 'sign_info' parameter from the Token Transfer Response, even if 'sign_info' was included in the Token Transfer Request, in case none of the groups the Client is authorized to join use signatures to achieve source authentication. 🌈
Note that the CBOR map specified as the payload of the 2.01 (Created) response may include further parameters, e.g., depending on the transport profile of ACE being used. Application profiles of this specification MAY define additional parameters to use within this exchange (OPT2). ⭐
Application profiles of this specification MAY define alternative specific negotiations of parameter values for the signature algorithm and signature keys if 'sign_info' is not used (OPT3). 🍓
If the transport profile of ACE allows it, the Client may provide the access token to the KDC by other means than the Token Transfer Request. An example is the DTLS transport profile of ACE, where the Client can provide the access token to the KDC during secure session establishment (see Section 3.3.2 of [RFC9202]) 🦋
3.3.1. 'sign_info' Parameter ✨
The 'sign_info' parameter is an OPTIONAL parameter of the request and response messages exchanged between the Client and the /authz-info endpoint at the RS (see Section 5.10.1 of [RFC9200]) 💖
This parameter lets the Client and the RS swap info about a signature algorithm, and about authentication credentials to use with it for signature verification. Its exact semantics and content are application specific 🧁
In this specification and in application profiles building on it, this parameter is used to exchange info about the signature algorithm, and about the authentication credentials to be used with it, in the groups indicated by the transferred access token via its 'scope' claim (see Section 3.2) 🎀
When used in the Token Transfer Request sent to the KDC (see Section 3.3), the 'sign_info' parameter specifies the CBOR simple value null (0xf6). This asks for info about the signature algorithm and the authentication credentials used in the groups that the Client has been authorized to join or interact with under its granted roles (e.g., as an external signature verifier) 🕵️♀️
When used in the following Token Transfer Response from the KDC (see Section 3.3), the 'sign_info' parameter is a CBOR array of one or more elements. The number of elements is at most the number of groups that the Client has been authorized to join or interact with. Each element contains info about signing parameters and about authentication credentials for one or more groups, and is formatted as follows 📋
- The first element
'id'is a group name or a CBOR array of group names, associated with the groups for which the next four elements apply. Each specified group name is a CBOR text string and is hereafter referred to as'gname'. - The second element
'sign_alg'is a CBOR integer or a text string that indicates the signature algorithm used in the groups identified by the'gname'values. It is REQUIRED for application profiles to define specific values that this parameter can take (REQ3), which are selected from the set of signing algorithms of the "COSE Algorithms" registry [COSE.Algorithms]. 🔥 - The third element
'sign_parameters'is a CBOR array that indicates the parameters of the signature algorithm used in the groups identified by the'gname'values. Its content depends on the value of'sign_alg'. It is REQUIRED for application profiles to define the possible values and structure for the elements of this parameter (REQ4). 💅 - The fourth element
'sign_key_parameters'is a CBOR array that indicates the parameters of the key used with the signature algorithm in the groups identified by the'gname'values. Its content depends on the value of'sign_alg'. It is REQUIRED for application profiles to define the possible values and structure for the elements of this parameter (REQ5). 🔑 - The fifth element
'cred_fmt'is either a CBOR integer indicating the format of the authentication credentials used in the groups identified by the'gname'values, or the CBOR simple value null (0xf6), which means the KDC does not act as a repository of authentication credentials for group members. Its acceptable integer values are taken from the "Label" column of the "COSE Header Parameters" registry [COSE.Header.Parameters], and some of those values also indicate the type of container to use for exchanging the authentication credentials with the KDC (e.g., a chain or bag of certificates). It is REQUIRED for application profiles to define specific values to use for this parameter, consistent with the acceptable formats of authentication credentials (REQ6). 👑
The CDDL notation [RFC8610] of the 'sign_info' parameter is given below. 🧩
sign_info = sign_info_req / sign_info_resp
sign_info_req = null ; in the Token Transfer
; Request to the KDC
sign_info_resp = [+ sign_info_entry] ; in the Token Transfer
; Response from the KDC
sign_info_entry =
[
id: gname / [+ gname],
sign_alg: int / tstr,
sign_parameters: [any],
sign_key_parameters: [+ parameter: any],
cred_fmt: int / null
]
gname = tstrThis format is consistent with every signature algorithm currently defined in [RFC9053], i.e., with algorithms that have only the COSE key type as their COSE capability. Appendix B describes how the format of each 'sign_info_entry' can be generalized for possible future registered algorithms with a different set of COSE capabilities. 🦄
3.3.2. 'kdcchallenge' Parameter ✨
The 'kdcchallenge' parameter is an OPTIONAL parameter of the response message returned from the /authz-info endpoint at the RS, as defined in Section 5.10.1 of [RFC9200]. This parameter contains a challenge generated by the RS and provided to the Client. 🌸
In this specification and in application profiles building on it, the Client can use this challenge to prove possession of its own private key in the Join Request (see the 'client_cred_verify' parameter in Section 4.3.1). 🫶
4. KDC Functionalities 👑
Okay bestie, this section is all about the KDC 🔑, the group's gatekeeper and keyring. It covers how the KDC hands out the keying material and runs group membership. It defines the KDC's interface, explains what each resource does, and shows how Clients use those resources to join a group and do their group member stuff 🫶.
A key move for the Client is the Join Request-Response exchange with the KDC, and it happens after the Client has transferred its access token to the KDC 🎀. In the Join Request, the Client names the group it wants to join (see Section 4.3.1.1). Then the KDC checks the stored access token linked to that Client and confirms the Client is actually authorized to join that group. If the check passes, the KDC gives the Client the keying material it needs to talk securely with the other group members 🔐✨.
Once the Client is a group member, it can keep using the KDC interface for extra operations that match the roles it has in the group 💅.
4.1. Interface at the KDC 🦋
The KDC provides its interface by hosting the resources below. Heads up, the root url-path ace-group is just a default name 🧚. Implementations are not required to use it and can pick their own.
If request messages sent to the KDC, and success response messages from the KDC, include a payload and specify a Content-Format, those messages MUST have Content-Format application/ace-groupcomm+cbor. That format is registered in Section 11.2. The CBOR map keys used for message parameters are defined in Section 8 🌈.
/ace-group🌸: the path of this root resource stays the same once the resource is set up. Using it tells you this specification is in play. If other applications run on a KDC that implements this specification and use this same path, they will collide, so a mechanism will be needed to tell the endpoints apart 😭.
A Client can hit this resource to get back a set of group names, one for each group identifier it's been given. This operation is described in Section 4.2.1.1.
Clients may be authorized to access this resource even if they aren't members of any group the KDC manages, and even if they aren't authorized to become group members. For example, they might be authorized to act as external signature verifiers 🦋.
The Interface Description (if=) Link Target Attribute value "ace.groups" is registered in Section 11.5, and you can use it to describe the interface this root resource provides ✨.
Here's an example. A KDC with address 2001:db8::ab hosts the resource /ace-group and sends back a link to it in link-format [RFC6690] 💖.
Request:
Header: GET (Code=0.01)
Uri-Host: "kdc.example.com"
Uri-Path: ".well-known"
Uri-Path: "core"
Uri-Query: "if=ace.groups"
Response:
Header: Content (Code=2.05)
Content-Format: 40 (application/link-format)
Payload:
<coap://[2001:db8::ab]/ace-group>;if="ace.groups"/ace-group/GROUPNAME🍓: there's one of these sub-resources under/ace-groupfor each group named GROUPNAME that the KDC manages. It's the group-membership resource for that group, and it holds the symmetric group keying material for that group 🔥.
A Client can use this resource to join the group named GROUPNAME. Once it's a group member, it can also use it to fetch the current group keying material. These operations are described in Sections 4.3.1.1 and 4.3.2.1, respectively.
The Interface Description (if=) Link Target Attribute value "ace.group" is registered in Section 11.5, and you can use it to describe the interface a group-membership resource provides 🌸.
Example time 🧚. A KDC with address 2001:db8::ab hosts the group-membership resource /ace-group/gp1 and sends back a link to it in link-format [RFC6690].
Request:
Header: GET (Code=0.01)
Uri-Host: "kdc.example.com"
Uri-Path: ".well-known"
Uri-Path: "core"
Uri-Query: "if=ace.group"
Response:
Header: Content (Code=2.05)
Content-Format: 40 (application/link-format)
Payload:
<coap://[2001:db8::ab]/ace-group/gp1>;if="ace.group"If the value of the GROUPNAME URI path and the group name in the access token scope ('gname' in Section 3.1) don't have to match, the KDC MUST implement a mechanism that maps the GROUPNAME value in the URI to the group name, so it points at the right group 🗺️ (REQ7).
/ace-group/GROUPNAME/creds💜: the path of this resource stays the same once it's set up. It holds the authentication credentials of all the members of the group named GROUPNAME 🪪.
This resource only gets created if the KDC acts as a repository of authentication credentials for group members 🗃️.
As a group member, a Client can read this resource to get the authentication credentials of other group members. It can grab the credentials of all the current members, or just a subset picked with filter criteria. These operations are described in Sections 4.4.2.1 and 4.4.1.1, respectively.
Clients may be authorized to access this resource even without being group members. For instance, they might be authorized to act as external signature verifiers for the group 👀.
/ace-group/GROUPNAME/kdc-cred🎀: the path of this resource stays the same once it's set up. It holds the KDC's own authentication credential for the group named GROUPNAME 🪄.
This resource only gets created if the KDC has an associated authentication credential and that credential is needed for the group to work correctly. It is REQUIRED for application profiles to define whether the KDC has such an associated authentication credential (REQ8) 📋.
As a group member, a Client can read this resource to get the KDC's current authentication credential. This operation is described in Section 4.5.1.1.
Clients may be authorized to access this resource even without being group members. For example, they might be authorized to act as external signature verifiers for the group 🫧.
/ace-group/GROUPNAME/policies📜: the path of this resource stays the same once it's set up. It holds the group policies of the group named GROUPNAME 💅.
A Client can read this resource as a group member to get the group policies. This operation is described in Section 4.6.1.1.
/ace-group/GROUPNAME/num🔢: the path of this resource stays the same once it's set up. It holds the current version number for the symmetric group keying material of the group named GROUPNAME 🧁.
A Client can read this resource as a group member to get the version number of the keying material currently in use in the group. This operation is described in Section 4.7.1.1.
/ace-group/GROUPNAME/nodes/NODENAME🧚♀️: there's one of these sub-resources under/ace-group/GROUPNAMEfor each group member of the group named GROUPNAME. Each one is identified by the node name NODENAME of its associated group member, and it holds the group keying material plus that group member's individual keying material 🗝️.
As a group member, a Client can use this resource to get the current group keying material together with its individual keying material. It can also request new individual keying material to use in the group, and it can leave the group 👋. These operations are described in Sections 4.8.1.1, 4.8.2.1, and 4.8.3.1, respectively.
/ace-group/GROUPNAME/nodes/NODENAME/cred🪪: the path of this resource stays the same once it's set up. It holds the individual authentication credential for the node named NODENAME as a group member of the group named GROUPNAME 🌷.
A Client can use this resource to upload a new authentication credential to the KDC, for use in the group. This operation is described in Section 4.9.1.1.
This resource isn't created if the group member doesn't have an authentication credential to use in the group, or if the KDC doesn't store the authentication credentials of group members 🙈.
The KDC is expected to fully provide the interface defined above 💪. Otherwise, it is REQUIRED for the application profiles of this specification to indicate which resources are not hosted. In other words, they say which parts of the interface defined in this section the KDC doesn't support (REQ9) 🚫. Application profiles of this specification MAY extend the KDC interface by defining additional handlers, and by defining additional resources and their handlers 🌈.
It is REQUIRED for application profiles of this specification to register a Resource Type for the group-membership resources (REQ10) 🏷️. This Resource Type helps discover the correct URL for sending a Join Request to the KDC. It can also show which specific application profile of this specification a particular group-membership resource at the KDC is using 🔍.
It is REQUIRED for application profiles of this specification to define which specific actions (for example, CoAP methods) are allowed on each resource the KDC interface provides. The rules depend on whether the Client is a current group member, on the roles the Client is authorized to take according to the access token it obtained (see Section 3.1), and on the roles the Client has as a current group member (REQ11) 💖.
4.1.1. Operations Supported by Clients ✨
Okay bestie, so it's expected that a Client minimally supports this set of primary operations and the matching interactions with the KDC 🎀
- FETCH request to
/ace-group/to retrieve group names associated with group identifiers 🌸 - POST and GET requests to
/ace-group/GROUPNAME/to join a group (POST) and later retrieve the current group keying material as a group member (GET) 🦋 - GET and FETCH requests to
/ace-group/GROUPNAME/credsto retrieve the authentication credentials of all the other group members (GET) or only some of them by filtering (FETCH). GET is still totally possible for grabbing credentials, but filtering with FETCH lets Clients seriously shrink the size of exchanged messages 💅 - GET request to
/ace-group/GROUPNAME/numto retrieve the current version of the group keying material as a group member 🧚 - DELETE request to
/ace-group/GROUPNAME/nodes/NODENAMEto leave the group 👋
Now, some Clients may rather not support the following set of secondary operations and interactions with the KDC 🙈 This can be specified, for instance, in compliance documents defining minimalistic Clients and their capabilities in specific deployments. These might also have to consider the application profile of this specification being used.
- GET request to
/ace-group/GROUPNAME/kdc-credto retrieve the current authentication credential of the KDC. This is relevant only if the KDC has an associated authentication credential and this is required for the correct group operation 🔐 - GET request to
/ace-group/GROUPNAME/policiesto retrieve the current group policies as a group member 📜 - GET request to
/ace-group/GROUPNAME/nodes/NODENAMEto retrieve the current group keying material and individual keying material. The former can also be retrieved through a GET request to/ace-group/GROUPNAME/(see above) 🗝️ - POST request to
/ace-group/GROUPNAME/nodes/NODENAMEto ask for new individual keying material. Alternatively, the Client could obtain new individual keying material by rejoining the group through a POST request to/ace-group/GROUPNAME/(see above). Furthermore, depending on its roles in the group or on the application profile of this specification, the Client might simply not be associated with any individual keying material 🌈 - POST request to
/ace-group/GROUPNAME/nodes/NODENAME/credto provide the KDC with a new authentication credential. Alternatively, the Client could provide a new authentication credential by rejoining the group through a POST request to/ace-group/GROUPNAME/(see above). Furthermore, depending on its roles in the group, the Client might simply not have an associated authentication credential to provide 🎭
It is REQUIRED for application profiles of this specification to categorize possible newly defined operations for Clients into primary and secondary operations and to provide accompanying considerations (REQ12). Put simply, if you're writing a new profile, you've got homework 📝✨
4.1.2. Error Handling 🚨
Upon receiving a request from a Client, the KDC MUST check that it is storing a valid access token from that Client. If this is not the case, the KDC MUST reply with a 4.01 (Unauthorized) error response 🙅♀️
Unless the request targets the /ace-group resource, the KDC MUST check that it is storing a valid access token for that Client such that:
- the scope specified in the access token includes a scope entry related to the group name GROUPNAME associated with the targeted resource and
- the set of roles specified in that scope entry allows the Client to perform the requested operation on the targeted resource (REQ11).
In case the KDC stores a valid access token but the verifications above fail, the KDC MUST reply with a 4.03 (Forbidden) error response. This response MAY be an AS Request Creation Hints, as defined in Section 5.3 of [RFC9200], in which case the Content-Format MUST be "application/ace+cbor" 🚫
If the request is not formatted correctly (e.g., required fields are not present or are not encoded as expected), the KDC MUST reply with a 4.00 (Bad Request) error response 😬
If the request includes unknown or unexpected fields, the KDC MUST silently ignore them and continue processing the request. Application profiles of this specification MAY define optional or mandatory payload formats for specific error cases (OPT4) 🤫
Some error responses from the KDC can convey error-specific information according to the problem-details format defined in [RFC9290]. Such error responses MUST have Content-Format "application/concise-problem-details+cbor". The payload of these error responses MUST be a CBOR map specifying a Concise Problem Details data item (see Section 2 of [RFC9290]). The CBOR map is formatted as follows. 🧩
- It MUST include the Custom Problem Detail entry
'ace-groupcomm-error', which is registered in Section 11.6 of this document.
This entry is formatted as a CBOR map including only one field, namely 'error-id'. The map key for 'error-id' is the CBOR unsigned integer with value 0. The value of 'error-id' is a CBOR integer specifying the error that occurred at the KDC. This value is taken from the "Value" column of the "ACE Groupcomm Errors" registry defined in Section 11.12 of this document.
The CDDL notation [RFC8610] of the 'ace-groupcomm-error' entry is given below.
ace-groupcomm-error = {
&(error-id: 0) => int
}- It MAY include further Standard Problem Detail entries or Custom Problem Detail entries (see [RFC9290]).
In particular, it can include the Standard Problem Detail entry 'detail' (map key -2), whose value is a CBOR text string that specifies a human-readable, diagnostic description of the error occurred at the KDC. The diagnostic text is intended for software engineers as well as for device and network operators in order to aid debugging and provide context for possible intervention. The diagnostic message SHOULD be logged by the KDC. The 'detail' entry is unlikely relevant in an unattended setup where human intervention is not expected. 🪵
An example of an error response using the problem-details format is shown in Figure 6 🎀
Response:
Header: Service Unavailable (Code=5.03)
Content-Format: 257 (application/concise-problem-details+cbor)
Payload:
{
/ title / -1: "No available individual keying material",
/ detail / -2: "Things will change after a
group rekeying; try later",
/ ace-groupcomm-error / 0: {
/ error-id / 0: 4 / "No available individual keying material" /
}
}Figure 6: Example of an Error Response with Problem Details
The problem-details format (in general) and the Custom Problem Detail entry 'ace-groupcomm-error' (in particular) are OPTIONAL for Clients to support. A Client supporting the entry 'ace-groupcomm-error' and that can understand the specified error may use that information to determine what actions to take next 💁♀️
Section 9 of this specification defines an initial set of error identifiers as possible values for the 'error-id' field. Application profiles of this specification inherit this initial set of error identifiers and MAY define additional values (OPT5) 🌟
4.2. /ace-group
This resource implements the FETCH handler. 🧺
4.2.1. FETCH Handler 🔍
The FETCH handler receives group identifiers and returns the corresponding group names and GROUPNAME URIs.
The handler expects a request with the payload formatted as a CBOR map, which MUST contain the following fields:
'gid': its value is encoded as a CBOR array, containing one or more group identifiers. The exact encoding of the group identifier MUST be specified by the application profile (REQ13). The Client indicates that it wishes to receive the group names of all the groups having these identifiers. 🆔
The handler identifies the groups where communications are secured by using the keying material identified by those group identifiers.
If all verifications succeed, the handler replies with a 2.05 (Content) response, whose payload is formatted as a CBOR map that MUST contain the following fields:
'gid': its value is encoded as a CBOR array, containing zero or more group identifiers. The handler indicates that those are the identifiers it is sending group names for. This CBOR array is a subset of the'gid'array in the FETCH request. 📬'gname': its value is encoded as a CBOR array, containing zero or more group names. The elements of this array are encoded as text strings. Each element of index i in this CBOR array is associated with the element of index i in the'gid'array. 🏷️'guri': its value is encoded as a CBOR array, containing zero or more URIs, each indicating a group-membership resource. The elements of this array are encoded as text strings. Each element of index i in this CBOR array is associated with the element of index i in the'gid'array. 🔗
If the KDC does not find any group associated with the specified group identifiers, the handler returns a response with the payload formatted as a CBOR byte string of zero length (0x40) 🫥
Note that the KDC only verifies that the node is authorized by the AS to access this resource. Nodes that are not members of the group but are authorized to do signature verification on the group messages may be allowed to access this resource if the application needs it. 👀
4.2.1.1. Retrieve Group Names 🌷
In case the joining node only knows the group identifier of the group it wishes to join or about which it wishes to get updated information from the KDC, the node can contact the KDC to request the corresponding group name and group-membership resource URI. In particular, it does so by sending a CoAP FETCH request to the /ace-group endpoint at the KDC formatted as defined in Section 4.2.1. The node can specify several group identifiers at once. 📞
Figure 7 gives an overview of the exchanges described above, and Figure 8 shows an example. 🦋
Client KDC
| |
|------------ Group Name and URI Retrieval Request: -------->|
| FETCH /ace-group |
| |
|<-- Group Name and URI Retrieval Response: 2.05 (Content) --|
| |Figure 7: Message Flow of Group Name and URI Retrieval Request-Response
Request:
Header: FETCH (Code=0.05)
Uri-Host: "kdc.example.com"
Uri-Path: "ace-group"
Content-Format: 261 (application/ace-groupcomm+cbor)
Payload (in CBOR diagnostic notation):
{
/ gid / 0: [1, 2]
}Response:
Header: Content (Code=2.05)
Content-Format: 261 (application/ace-groupcomm+cbor)
Payload (in CBOR diagnostic notation):
{
/ gid / 0: [1, 2],
/ gname / 1: ["group1", "group2"],
/ guri / 2: ["/ace-group/g1", "/ace-group/g2"]
}Figure 8: Example of Group Name and URI Retrieval Request-Response
4.3. /ace-group/GROUPNAME
This resource implements the POST and GET handlers. 🎉
4.3.1. POST Handler 💌
Okay so the POST handler is basically the bouncer at the group chat door 💅🎀. It processes the Join Request a Client sends to join a group, and when things go well it returns a Join Response as the successful result (see Section 4.3.1.1) 🦋. At a high level, the handler adds the Client to the list of current group members ✨, adds the Client's authentication credential to the list of the group members' authentication credentials 🫶, and returns the symmetric group keying material for the group identified by GROUPNAME 🔐.
The handler expects a request whose payload is a CBOR map 🧚. That map MAY contain the following fields, and if a field is included, it MUST have the format and value described below 📝.
'scope': its value names the group the Client is trying to join, plus the roles the Client wants to have in that group 🍓. This value is a CBOR byte string wrapping one scope entry, as defined in Section 3.1.'get_creds': this is included if the Client wants to receive the authentication credentials of the current group members from the KDC 👀. It's useful if the KDC stores those credentials, but not so useful if the Client gets them some other way, like from the AS. Heads up: including this parameter might result in a following Join Response of a large size, which can be inconvenient for resource-constrained devices 😭.
If the Client wants the authentication credentials of all the current group members, the 'get_creds' parameter MUST encode the CBOR simple value null (0xf6). Otherwise, if the Client wants credentials for nodes with specific roles, the 'get_creds' parameter MUST encode a non-empty CBOR array containing the three elements 'inclusion_flag', 'role_filter', and 'id_filter', as defined below 🌈.
- The first element,
'inclusion_flag', encodes the CBOR simple value true (0xf5) if the Client wants the credentials of the nodes whose node identifier is specified in'id_filter'(that's selection by inclusive filtering) 💜. It encodes the CBOR simple value false (0xf4) if the Client wants the credentials of the nodes that do NOT have the node identifiers in the third element'id_filter'(that's selection by exclusive filtering) 🙈. In the Join Request, this parameter encodes the CBOR simple value true (0xf5). - The second element,
'role_filter', is a CBOR array 🎀. Each element holds one role or a combination of roles for the group identified by GROUPNAME. This tells the KDC the Client wants the credentials of every group member with any of the specified roles, or any of the specified combinations (meaning any of those single roles, or at least all the roles in any of those combinations) 💖.
For example, the array ["role1", "role2+role3"] means the Client wants the credentials of all group members that have at least "role1", or at least both "role2" and "role3" 🦋. In the Join Request, this parameter is a non-empty array.
- The third element,
'id_filter', is a CBOR array 🧾. Each element holds the node identifier of a group member for the group identified by GROUPNAME. This means the Client wants the credentials of the nodes that have, or do not have, the specified node identifiers, depending on'inclusion_flag'(so it's inclusive or exclusive filtering) 🌸. In the Join Request, the Client doesn't filter credentials by node identifier, so this parameter is an empty array.
Real talk: when first joining, the Client is not expected or capable of expressing a filter based on the node identifiers of other group members 🙅. Instead, when it's already a group member and sends a Join Request to rejoin, the Client is not expected to include the 'get_creds' parameter in the Join Request at all, since it can retrieve authentication credentials associated with specific group identifiers instead, as defined in Section 4.4.1.1 ✨.
The CDDL definition [RFC8610] of 'get_creds' is in Figure 9. As an example, it uses node identifiers encoded as CBOR byte strings, role identifiers encoded as CBOR text strings, and combinations of roles encoded as CBOR arrays of role identifiers 🧚.
Note that for this handler, 'inclusion_flag' is always set to true, and the array of roles 'role_filter' is always non-empty, while the array of node identifiers 'id_filter' is always empty 💅. However, this is not necessarily the case for other handlers using the 'get_creds' parameter 🤷♀️.
inclusion_flag = bool
role = tstr
comb_role = [2* role]
role_filter = [* ( role / comb_role )]
id = bstr
id_filter = [* id]
get_creds = null / [inclusion_flag, role_filter, id_filter] Figure 9: CDDL Definition of 'get_creds', Using an Example
Node Identifier Encoded as bstr and Role as tstr'client_cred': encoded as a CBOR byte string, whose value is the original binary representation of the Client's authentication credential 🔏. This parameter MUST be present if the KDC is managing (collecting from and distributing to Clients) the authentication credentials of the group members, and the Client's role in the group requires it to send messages to one or more group members 📨. It is REQUIRED for application profiles to define the specific formats that are acceptable to use for authentication credentials in the group (REQ6) 🎯.'cnonce': encoded as a CBOR byte string, whose value is a dedicated nonce N_C generated by the Client 🎲. This parameter MUST be present.'client_cred_verify': encoded as a CBOR byte string 🔑. This parameter MUST be present if the'client_cred'parameter is present and no authentication credential associated with the Client's access token can be retrieved for that group 💀.
The value of the CBOR byte string is the proof-of-possession (PoP) evidence computed by the Client over the following PoP input: the scope (encoded as a CBOR byte string) concatenated with N_S (encoded as a CBOR byte string) concatenated with N_C (encoded as a CBOR byte string), where:
- scope is either the one specified in the
'scope'parameter above, if present, or a default scope entry that the handler is expected to know otherwise 🍑; - N_S is the challenge received from the KDC in the
'kdcchallenge'parameter of the 2.01 (Created) response to the Token Transfer Request (see Section 3.3), encoded as a CBOR byte string 🌈; and - N_C is the nonce generated by the Client and specified in the
'cnonce'parameter above, encoded as a CBOR byte string 💜.
An example of PoP input to compute 'client_cred_verify' using CBOR encoding is given in Figure 10 🎀.
A possible type of PoP evidence is a signature that the Client computes using its own private key, whose corresponding public key is specified in the authentication credential carried in the 'client_cred' parameter 🖊️. Application profiles of this specification MUST specify the exact approaches used to compute the PoP evidence to include in 'client_cred_verify', and MUST specify which of those approaches is used in which case (REQ14) 📋.
If the access token was not provided to the KDC through a Token Transfer Request (for example, the access token is instead transferred during the establishment of a secure communication association), it is REQUIRED of the specific application profile to define how the challenge N_S is generated (REQ15) 🛠️.
'creds_repo': this can be present if the format of the Client's authentication credential conveyed in the'client_cred'parameter is a certificate 📜. In that case, the value of this parameter is the URI of the certificate. It's encoded as a CBOR text string. Alternative specific encodings of this parameter MAY be defined in application profiles of this specification (OPT6) 🌷.'control_uri': its value is a full URI, encoded as a CBOR text string 🔗. A default url-path is/ace-group/GROUPNAME/node, although implementations can use different ones instead. The URI MUST NOT have url-path/ace-group/GROUPNAME🚫.
If 'control_uri' is specified in the Join Request, the Client acts as a CoAP server and hosts a resource at this specific URI 🌐. The KDC MAY use this URI to send CoAP requests to the Client (acting as a CoAP server in this exchange), for example for one-to-one provisioning of new group keying material when performing a group rekeying (see Section 6.1), or to inform the Client of its removal from the group (see Section 5) 🔄.
In particular, this resource is intended only for communications concerning the group identified by GROUPNAME, whose group name is specified in the 'scope' parameter of the Join Request, if present there 🎯. If the KDC does not implement mechanisms using this resource for that group, it can ignore this parameter. Other additional functionalities of this resource MAY be defined in application profiles of this specification (OPT7) 🧁.
Here's how scope, N_S, and N_C look in CBOR diagnostic notation 🔍:
scope = h'826667726f7570316673656e646572'
N_S = h'018a278f7faab55a'
N_C = h'25a8991cd700ac01'And here they are as CBOR encoded byte strings 🧸:
scope = 0x4f826667726f7570316673656e646572
N_S = 0x48018a278f7faab55a
N_C = 0x4825a8991cd700ac01
PoP input:
0x4f 826667726f7570316673656e646572
48 018a278f7faab55a 48 25a8991cd700ac01 Figure 10: Example of PoP Input to Compute 'client_cred_verify'
Using CBOR EncodingIf the request does not include the 'scope' parameter, the KDC is expected to understand which roles the Client is requesting to join the group with 🧠. For example, according to the access token, the Client might have been granted access to the group with only one role. If the KDC cannot determine which exact roles should be considered for the Client, it MUST reply with a 4.00 (Bad Request) error response 🙅♀️.
The handler looks at the scope specified in the access token associated with the Client and checks the scope entry related to the group identified by the GROUPNAME associated with the endpoint 🔎. Specifically, it checks whether the set of roles in that scope entry includes all the roles the Client wants to have in the group, as per the Join Request. If that isn't the case, the KDC MUST reply with a 4.03 (Forbidden) error response 🚫💅.
If the KDC manages the group members' authentication credentials, the handler checks whether one is included in the 'client_cred' parameter. If so, the KDC retrieves the authentication credential and performs the following actions 👑.
- Okay so if the access token came in through a Token Transfer Request (see Section 3.3) but the KDC can't find the
'kdcchallenge'linked to this Client (see Section 3.3) 😭, the KDC MUST reply with a4.00 (Bad Request)error response, and that response MUST also have Content-Format"application/ace-groupcomm+cbor". The payload is a CBOR map with a freshly generated'kdcchallenge'value in the'kdcchallenge'parameter. The KDC MUST store that new value as the'kdcchallenge'for this Client, replacing whatever was saved before (if anything) 🧚 - The KDC checks that the authentication credential is valid for the group named GROUPNAME. Basically it checks that the credential has the format the group uses, that it's meant for the public key algorithm the group uses, and that it lines up with the possible associated parameters used in the group ✨
If this check fails, the handler MUST reply with a 4.00 (Bad Request) error response. The response MUST have Content-Format "application/concise-problem-details+cbor" and be formatted as defined in Section 4.1.2. Inside the Custom Problem Detail entry 'ace-groupcomm-error', the 'error-id' field MUST be set to 2 ("Authentication credential incompatible with the group configuration") 💀
- The KDC verifies the PoP evidence sent in the
'client_cred_verify'parameter. Application profiles of this specification MUST spell out the exact approaches used to verify PoP evidence and MUST say which approach is used in which case (REQ14) 🔥
If the PoP evidence doesn't pass verification, the handler MUST reply with a 4.00 (Bad Request) error response. The response MUST have Content-Format "application/concise-problem-details+cbor" and be formatted as defined in Section 4.1.2. Inside the Custom Problem Detail entry 'ace-groupcomm-error', the 'error-id' field MUST be set to 3 ("Invalid proof-of-possession evidence") 🙈
If there's no authentication credential in the 'client_cred' parameter, the handler checks whether the KDC is already storing one that's linked to both the access token and the group GROUPNAME (see also Section 4.3.1.1). Heads up, the same joining node can use different authentication credentials in different groups, and all of those credentials are tied to the same access token 🦋
If an eligible authentication credential for the Client is neither in the 'client_cred' parameter nor stored at the KDC, it is RECOMMENDED that the handler stops processing and replies with a 4.00 (Bad Request) error response. Application profiles MAY define alternatives (OPT8) 🌸
No matter the reason, if the KDC replies with a 4.00 (Bad Request) error response, the payload of that response MAY be a CBOR map. For example, the CBOR map can include a 'sign_info' parameter formatted as 'sign_info_resp' (defined in Section 3.3.1), with the 'cred_fmt' element set to the CBOR simple value null (0xf6) if the Client sent its own authentication credential and the KDC isn't set to store the group members' authentication credentials. When the response payload is a CBOR map with those parameters, the error response has Content-Format "application/ace-groupcomm+cbor" 💅
If all the verifications above succeed, the KDC moves on as follows.
First, but only if the Client is not already a group member, the handler does the following:
- The handler adds the Client to the list of current members of the group.
- The handler assigns a name NODENAME to the Client and creates a sub-resource under
/ace-group/GROUPNAMEat the KDC, i.e.,/ace-group/GROUPNAME/nodes/NODENAME. - The handler associates the node identifier NODENAME with the access token and the secure communication association for the Client.
Then, the handler does the following:
- If the KDC manages the group members' authentication credentials:
- The handler associates the retrieved Client's authentication credential with the tuple made of the node name NODENAME, the group name GROUPNAME, and the access token.
- The handler adds the retrieved Client's authentication credential to the list of authentication credentials stored for the group identified by GROUPNAME. If that list already includes an authentication credential for the Client, but a different one is specified in the
'client_cred'parameter, then the handler MUST replace the old credential in the list with the one specified in the'client_cred'parameter. 🔄
- If backward security is prescribed by application policies installed at the KDC or by the application profile of this specification being used, then the KDC MUST generate new group keying material and securely distribute it to the current group members (see Section 6) 🔐
- The handler returns a successful Join Response, as defined below. It contains the symmetric group keying material, the group policies, and the authentication credentials of the current group members if the KDC manages those and the Client asked for them 🎀
The Join Response MUST have response code 2.01 (Created) if the Client was added to the list of group members in this join exchange (see above), or 2.04 (Changed) otherwise, i.e., if the Client is rejoining the group without having left it 💖
The Join Response message MUST include the Location-Path CoAP Options, which specify the path to the sub-resource associated with the Client, i.e., /ace-group/GROUPNAME/nodes/NODENAME 📍
The Join Response message MUST have Content-Format "application/ace-groupcomm+cbor". The payload is a CBOR map, and it MUST contain the following fields with the values specified below:
'gkty': identifies the key type of the keying material in the'key'parameter. This parameter is encoded as a CBOR integer or a CBOR text string. Possible values come from the "Key Type Value" column of the "ACE Groupcomm Key Types" registry defined in Section 11.8 of this specification. Implementations MUST verify that the key type given by this parameter matches the application profile being used and, if applicable, that the application profile is listed in the "Profile" column of the "ACE Groupcomm Key Types" registry for that key type 🧐'key': contains the keying material used to secure the group communication, or the information needed to derive that keying material 🗝️'num': contains the current version number of the group keying material, encoded as a CBOR integer. The version number increases in a strictly monotonic way as the group keying material changes. The application profile MUST define the initial value of the version number (REQ16) 🔢
The format of the keying material in the 'key' parameter MUST be defined in application profiles of this specification (REQ17), together with the corresponding key types to put as the value of the 'gkty' parameter and that are accepted by the application (REQ18). On top of that, documents that specify a type of keying material MUST register an entry in the "ACE Groupcomm Key Types" registry defined in Section 11.8, including its name, the corresponding key type to specify as the value for the 'gkty' parameter, and the application profile to be used with ✨
+==========+================+=========+=============+===========+
| Name | Key Type Value | Profile | Description | Reference |
+==========+================+=========+=============+===========+
| Reserved | 0 | | This value | RFC 9594 |
| | | | is reserved | |
+----------+----------------+---------+-------------+-----------+Table 1: ACE Groupcomm Key Types
The Join Response SHOULD contain the following fields with the values specified below:
'exp': its value gives the expiration time of the group keying material in the'key'parameter, encoded as a CBOR unsigned integer. The value is the number of seconds from 1970-01-01T00:00:00Z UTC until the specified UTC date/time, ignoring leap seconds, analogous to what Section 2 of [RFC7519] specifies for NumericDate. After the time in this parameter, group members MUST NOT use the group keying material in the'key'parameter. Group members can grab the latest group keying material from the KDC ⏰'exi': its value gives the residual lifetime of the group keying material, encoded as a CBOR unsigned integer. If the'exp'parameter is included, this parameter MUST also be included. The value is the residual lifetime of the group keying material in the'key'parameter, i.e., the number of seconds between the current time at the KDC and the time the keying material expires (as given in the'exp'parameter, if present). A Client works out the expiration time by adding the seconds in the'exi'parameter to its current time when it receives the Join Response containing'exi'. After that expiration time, the Client MUST NOT use the group keying material in the'key'parameter. The Client can fetch the latest group keying material from the KDC ⌛
If a Client has a reliable way to sync its internal clock with UTC, and both the 'exp' and 'exi' parameters are present, then the Client MUST use the 'exp' parameter value as the expiration time for the group keying material. Otherwise, the Client uses the 'exi' parameter value to work out the expiration time, as defined above 🕰️
When a Client relies on the 'exi' parameter, the expiration time it computes is offset into the future compared with the real expiration time the KDC intended, which is given in the 'exp' parameter (if present). That offset is the amount of time between when the KDC sends the response with the 'exi' parameter and when the Client receives it. So, especially if the response is delayed on its way to the Client, the Client will think the keying material is valid for longer than the KDC actually means 😬 Still, before the actual expiration time gets close, the KDC is expected to rekey the group and distribute new keying material (see Section 6) 🔁
Optionally, the Join Response MAY contain the following parameters, which, if included, MUST have the format and value specified below:
'ace_groupcomm_profile': its value is encoded as a CBOR integer and MUST be used to uniquely identify the application profile for group communication. Applications of this specification MUST register an application profile identifier and the related value for this parameter in the "ACE Groupcomm Profiles" registry (REQ19) 🌈
+==========+========================+============+===========+
| Name | Description | CBOR Value | Reference |
+==========+========================+============+===========+
| Reserved | This value is reserved | 0 | RFC 9594 |
+----------+------------------------+------------+-----------+
Table 2: ACE Groupcomm Profiles'creds'🧺 okay so this one is the list of authentication credentials for the group members ✨ it MUST be present if'get_creds'was present in the Join Request; otherwise, it MUST NOT be present. Its value is encoded as a CBOR array of the authentication credentials of the group members, which means all of them, or only the ones picked by the'get_creds'parameter in the Join Request. Each element of the array is a CBOR byte string, and its value is the original binary representation of one group member's authentication credential 💅 It is REQUIRED for application profiles to define the specific formats of authentication credentials that are acceptable to use in the group (REQ6).'peer_roles'👑 this one tells you what role each member has, and it SHOULD be present if'creds'is also present; otherwise, it MUST NOT be present. Its value is a CBOR array of n elements, where n is the number of authentication credentials included in'creds'(at most, the number of members in the group). The i-th element says which role(s) the group member tied to the i-th authentication credential in'creds'has in the group. Each array element is encoded like the role element of a scope entry, which fits the format being used (see Section 3.1) 🦋
This parameter MAY be omitted if the Client can rely on other means to figure out the role of each group member whose authentication credential is in the 'creds' parameter. For example, all of those members could have the same role in the group the Client joined, and the Client could assume that role unambiguously (for instance, based on what the used application profile defines). Another example: each authentication credential in the 'creds' parameter can say which role(s) its group member has in the group the Client joined 🌸
When the KDC receives the authentication credential of a Client in the 'client_cred' parameter of a Join Request (see Section 4.3.1.1), or in an Authentication Credential Update Request (see Section 4.9.1.1), it is not expected to check that the credential shows the role(s) the Client can have or does have in that group. When the KDC is preparing a Join Response, it can decide whether to include the 'peer_roles' parameter, depending on the exact set of authentication credentials in the 'creds' parameter of that Join Response ✨
'peer_identifiers'🪪 this one MUST be present if'creds'is also present; otherwise, it MUST NOT be present. Its value is a CBOR array of n elements, where n is the number of authentication credentials included in'creds'(at most, the number of members in the group). The i-th element says which node identifier the group member tied to the i-th authentication credential in'creds'has in the group. Each i-th array element is a CBOR byte string, and its value is that group member's node identifier 🧚 The specific format of node identifiers of group members is specified by the application profile (REQ25).'group_policies'🎀 its value is a CBOR map, and each element of that map says how the group handles specific management aspects. For instance, these can include approaches to get the sequence numbers of group members synchronized. The possible elements of the CBOR map are registered in the "ACE Groupcomm Policies" registry defined in Section 11.10 of this specification. This specification defines the three elements "Sequence Number Synchronization Methods", "Key Update Check Interval", and "Expiration Delta", which are summarized in Table 3 🌈 Application profiles of this specification MUST specify the format and default values for the entries of the CBOR map conveyed in the'group_policies'parameter (REQ20).
+=================+=======+======+===================+===========+
| Name | CBOR | CBOR | Description | Reference |
| | Label | Type | | |
+=================+=======+======+===================+===========+
| Sequence Number | 0 | int | Method for | RFC 9594 |
| Synchronization | | or | recipient group | |
| Method | | tstr | members to | |
| | | | synchronize with | |
| | | | sequence numbers | |
| | | | of sender group | |
| | | | members. Its | |
| | | | value is taken | |
| | | | from the "Value" | |
| | | | column of the | |
| | | | "Sequence Number | |
| | | | Synchronization | |
| | | | Method" | |
| | | | registry. | |
+-----------------+-------+------+-------------------+-----------+
| Key Update | 1 | int | Polling interval | RFC 9594 |
| Check Interval | | | in seconds, for | |
| | | | group members to | |
| | | | check at the KDC | |
| | | | if the latest | |
| | | | group keying | |
| | | | material is the | |
| | | | one that they | |
| | | | store. | |
+-----------------+-------+------+-------------------+-----------+
| Expiration | 2 | uint | Number of | RFC 9594 |
| Delta | | | seconds from | |
| | | | 'exp' until a | |
| | | | UTC date/time, | |
| | | | after which | |
| | | | group members | |
| | | | MUST stop using | |
| | | | the group keying | |
| | | | material that | |
| | | | they store to | |
| | | | decrypt incoming | |
| | | | messages. | |
+-----------------+-------+------+-------------------+-----------+
Table 3: ACE Groupcomm Policies'kdc_cred'🔐 its value is the original binary representation of the KDC's authentication credential, encoded as a CBOR byte string. This parameter is used if the KDC has an associated authentication credential and that credential is needed for the group to work correctly. It is REQUIRED for application profiles to define whether the KDC has an authentication credential needed for correct group operation, and whether that has to be provided through the'kdc_cred'parameter (REQ8) 😭
If the KDC has an authentication credential needed for correct group operation, the KDC's authentication credential MUST have the same format used for the authentication credentials of the group members. It is REQUIRED for application profiles to define the specific formats that are acceptable to use for the authentication credentials in the group (REQ6) 💜
'kdc_nonce'🎲 its value is a dedicated nonce N_KDC generated by the KDC, encoded as a CBOR byte string. This parameter MUST be present if the'kdc_cred'parameter is present.'kdc_cred_verify'🫧 its value is as defined below, and it is encoded as a CBOR byte string. This parameter MUST be present if the'kdc_cred'parameter is present.
The value of this parameter is the proof-of-possession (PoP) evidence computed by the KDC over the following PoP input: the nonce N_C (encoded as a CBOR byte string) concatenated with the nonce N_KDC (encoded as a CBOR byte string), where:
N_Cis the nonce generated by the Client and specified in the'cnonce'parameter of the Join Request.N_KDCis the nonce generated by the KDC and specified in the'kdc_nonce'parameter.
An example of PoP input to compute 'kdc_cred_verify' using CBOR encoding is given in Figure 11 📖
A possible type of PoP evidence is a signature that the KDC computes by using its own private key, whose corresponding public key is specified in the authentication credential conveyed in the 'kdc_cred' parameter. Application profiles of this specification MUST specify the approaches the KDC uses to compute the PoP evidence to include in 'kdc_cred_verify', and MUST specify which of those approaches is used in which case (REQ21) 🌟
'rekeying_scheme'🔁 this one identifies the rekeying scheme the KDC uses to hand new group keying material to the group members. Its value is encoded as a CBOR integer, taken from the "Value" column of the "ACE Groupcomm Rekeying Schemes" registry defined in Section 11.13 of this specification 🍓
+=======+================+===========================+===========+
| Value | Name | Description | Reference |
+=======+================+===========================+===========+
| 0 | Point-to-Point | The KDC individually | RFC 9594 |
| | | targets each node to | |
| | | rekey, using the | |
| | | pairwise secure | |
| | | communication | |
| | | association with | |
| | | that node | |
+-------+----------------+---------------------------+-----------+
Table 4: ACE Groupcomm Rekeying SchemesApplication profiles of this specification MAY define a default group rekeying scheme to refer to in case the 'rekeying_scheme' parameter is not included in the Join Response (OPT9) 🦋
'mgt_key_material'🔑: this one is encoded as a CBOR byte string, and it holds the specific administrative keying material that the joining node needs so it can take part in the group rekeying process run by the KDC. This parameter MUST NOT be present if the'rekeying_scheme'parameter is not present and the application profile does not specify a default group rekeying scheme to use in the group. Some simple rekeying schemes don't need any specific administrative keying material to be handed over, e.g., the basic "Point-to-Point" group rekeying scheme (see Section 6.1). 🫶
In more advanced group rekeying schemes, the administrative keying material can be made of multiple keys organized, for instance, into a logical tree hierarchy, whose root key is the only administrative key shared by all the group members. ✨ In that setup, each group member is exclusively associated with one leaf key in the hierarchy and stores only the administrative keys from its leaf key all the way up the path to the root key. So different group members can be given a different subset of the overall administrative keying material. 🌳
It is expected that separate documents will define how the advanced group rekeying scheme, possibly indicated in the 'rekeying_scheme' parameter, is used by an application profile of this specification. This includes defining the format of the administrative keying material to specify in 'mgt_key_material', consistently with the group rekeying scheme and the application profile in question. 📝
'control_group_uri'📡: its value is a full URI, encoded as a CBOR text string. The URI MUST specify addressing information intended to reach all the members in the group. For example, this can be a multicast IP address, optionally together with a port number. If the port number is omitted, it defaults to 5683, i.e., the default port number for the "coap" URI scheme (see Section 6.1 of [RFC7252]). The URI MUST include GROUPNAME in the url-path. A default url-path is/ace-group/GROUPNAME, although implementations can use different ones instead. The URI MUST NOT have url-path/ace-group/GROUPNAME/nodes. 🙅♀️
If 'control_group_uri' is included in the Join Response, the Clients supporting this parameter act as CoAP servers, host a resource at this specific URI, and listen to the specified addressing information. 🎀
The KDC MAY use this URI to send one-to-many CoAP requests to the Client group members (acting as CoAP servers in this exchange). For example, it can do this for one-to-many provisioning of new group keying material when performing a group rekeying (see Section 6.2), or to inform the Clients of their removal from the group (see Section 5). 📣
In particular, this resource is intended for communications exclusively concerning the group identified by GROUPNAME, whose group name was specified in the 'scope' parameter of the Join Request, if present. If the KDC does not implement mechanisms using this resource for that group, it can ignore this parameter. Other additional functionalities of this resource MAY be defined in application profiles of this specifications (OPT10). 🧚
N_C and N_KDC expressed in CBOR diagnostic notation:
N_C = h'25a8991cd700ac01'
N_KDC = h'cef04b2aa791bc6d'
N_C and N_KDC as CBOR encoded byte strings:
N_C = 0x4825a8991cd700ac01
N_KDC = 0x48cef04b2aa791bc6d
PoP input:
0x48 25a8991cd700ac01 48 cef04b2aa791bc6d
Figure 11: Example of PoP Input to Compute 'kdc_cred_verify'
Using CBOR EncodingAfter sending the Join Response, if the KDC has an associated authentication credential as required for the correct group operation, then the KDC MUST store the N_C value specified in the 'cnonce' parameter of the Join Request as a 'clientchallenge' value associated with the Client, replacing the currently stored value (if any). 💾 If, as a group member, the Client later sends a GET request to the /ace-group/GROUPNAME/kdc-cred resource for retrieving the latest KDC's authentication credential (see Section 4.5.1), then the KDC uses the stored 'clientchallenge' to compute the PoP evidence to include in the response sent to the Client. That way it proves it has possession of its own private key. 🔐
If the Join Response includes the 'kdc_cred_verify' parameter, the Client verifies the conveyed PoP evidence, and it considers the group joining unsuccessful in case of failed verification. ❌ Application profiles of this specification MUST specify the exact approaches used by the Client to verify the PoP evidence in 'kdc_cred_verify', and MUST specify which of those approaches is used in which case (REQ21). 📋
Application profiles of this specification MUST specify the communication protocol that members of the group use to communicate with each other (REQ22), and the security protocol that they use to protect the group communication (REQ23). 🛡️
4.3.1.1. Join the Group
Figure 12 gives an overview of the join exchange between the Client and the KDC when the Client first joins a group, while Figure 13 shows an example. 👀
Client KDC
| |
|-------- Join Request: POST /ace-group/GROUPNAME ------>|
| |
|<------------ Join Response: 2.01 (Created) ----------- |
| Location-Path = "/ace-group/GROUPNAME/nodes/NODENAME" |
Figure 12: Message Flow of the Join Request-ResponseRequest:
Header: POST (Code=0.02)
Uri-Host: "kdc.example.com"
Uri-Path: "ace-group"
Uri-Path: "g1"
Content-Format: 261 (application/ace-groupcomm+cbor)
Payload (in CBOR diagnostic notation):
{
/ scope / 3: <<["group1", ["sender", "receiver"]]>>,
/ get_creds / 4: [true, ["sender"], []],
/ client_cred / 5: h'a2026008a101a5010202410a20012158
20bbc34960526ea4d32e940cad2a2341
48ddc21791a12afbcbac93622046dd44
f02258204519e257236b2a0ce2023f09
31f1f386ca7afda64fcde0108c224c51
eabf6072',
/ cnonce / 6: h'25a8991cd700ac01',
/ client_cred_verify / 24: h'66e6d9b0db009f3e105a673f88556117
26caed57f530f8cae9d0b168513ab949
fedc3e80a96ebe94ba08d3f8d3bf8348
7458e2ab4c2f936ff78b50e33c885e35'
}Response:
Header: Created (Code=2.01)
Content-Format: 261 (application/ace-groupcomm+cbor)
Location-Path: "ace-group"
Location-Path: "g1"
Location-Path: "nodes"
Location-Path: "c101"
Payload (in CBOR diagnostic notation):
{
/ gkty / 7: 65600,
/ key / 8: h'73657373696f6e6b6579',
/ num / 9: 12,
/ exp / 11: 1924992000,
/ exi / 12: 2592000,
/ creds / 13: [h'a2026008a101a5010202410220012158
20cd4177ba62433375ede279b5e18e8b
91bc3ed8f1e174474a26fc0edb44ea53
73225820a0391de29c5c5badda610d4e
301eaaa18422367722289cd18cbe6624
e89b9cfd',
h'a2026008a101a5010202410320012158
20ac75e9ece3e50bfc8ed60399889522
405c47bf16df96660a41298cb4307f7e
b62258206e5de611388a4b8a8211334a
c7d37ecb52a387d257e6db3c2a93df21
ff3affc8'],
/ peer_roles / 14: ["sender", ["sender", "receiver"]],
/ peer_identifiers / 15: [h'01', h'02']
}
Figure 13: Example of the First Join Request-Response for Group
JoiningIf not previously established, the Client and the KDC MUST first establish a pairwise secure communication association (REQ24). 🤝 This can be achieved, for instance, by using a transport profile of ACE. The join exchange MUST occur over that secure communication association. The Client and the KDC MAY use that same secure communication association to protect further pairwise communications that must be protected. 🔒
It is REQUIRED that the secure communication association between the Client and the KDC is established by using the proof-of-possession key bound to the access token. As a result, the proof of possession to bind the access token to the Client is performed by using the proof-of-possession key bound to the access token for establishing the pairwise secure communication association between the Client and the KDC. 🎟️
To join the group, the Client sends a CoAP POST request to the /ace-group/GROUPNAME endpoint at the KDC, where the group to join is identified by GROUPNAME. 🚪 The group name is specified in the scope entry conveyed by the 'scope' parameter of the request (if present), formatted as specified in Section 4.3.1. This group name is the same as in the scope entry corresponding to that group, specified in the 'scope' parameter of the Authorization Request/Response, or it can be determined from it. Note that, in case of successful joining, the Location-Path Options in the Join Response provide the Client with the path of the URI to use for retrieving individual keying material and for leaving the group. 🗝️
If the node is joining a group for the first time and the KDC maintains the authentication credentials of the group members, the Client is REQUIRED to send its own authentication credential and proof-of-possession (PoP) evidence in the Join Request (see the 'client_cred' and 'client_cred_verify' parameters in Section 4.3.1). The request is accepted only if both the authentication credential is provided and the PoP evidence is successfully verified. ✅
If a node rejoins a group as authorized by the same access token and using the same authentication credential, it can omit the authentication credential and the PoP evidence, or just the PoP evidence, from the Join Request. Then, the KDC will be able to retrieve the node's authentication credential associated with the access token for that group. If the authentication credential has been discarded, the KDC replies with a 4.00 (Bad Request) error response, as specified in Section 4.3.1. 🔁 If a node rejoins a group but wants to update its own authentication credential, it needs to include both its authentication credential and the PoP evidence in the Join Request, like when it joined the group for the first time. 🌸
4.3.2. GET Handler ✨
okay so the GET handler is the "just give me the keys" endpoint 🔑💖 it hands back the symmetric group keying material for whatever group is named in GROUPNAME
the handler expects a GET request. 🎀
on top of everything in Section 4.1.2, the handler double-checks that the Client is a current member of the group 👀 if that check fails, the KDC MUST reply with a 4.03 (Forbidden) error response. the response MUST have Content-Format "application/concise-problem-details+cbor" and it's formatted as defined in Section 4.1.2. inside the Custom Problem Detail entry ace-groupcomm-error, the error-id field MUST be set to 0, which means "Operation permitted only to group members" 🚫
if every verification passes, the handler replies with a 2.05 (Content) response containing the symmetric group keying material 🥳 the payload is a CBOR map that MUST contain the parameters gkty, key, and num, as specified in Section 4.3.1.
the payload MUST also include the parameters rekeying_scheme and mgt_key_material (as specified in Section 4.3.1) if they show up in the payload of the Join Responses sent for the group ✨
the payload MAY also include ace_groupcomm_profile, exp, and exi, as specified in Section 4.3.1. but here's the catch: if exp is included, exi MUST also be included 🙈 and if exi is included, its value tells you the residual lifetime of the group keying material from the current time at the KDC ⏳
4.3.2.1. Retrieve Group Keying Material
so a node in the group can ping the KDC to grab the current group keying material 🌸 it does this by sending a CoAP GET request to the /ace-group/GROUPNAME endpoint at the KDC, where GROUPNAME names the group.
Figure 14 gives you the big-picture flow of the key distribution exchange between the Client and the KDC, and Figure 15 shows an example 🦋
Client KDC
| |
|------ Key Distribution Request: GET /ace-group/GROUPNAME ------>|
| |
|<----------- Key Distribution Response: 2.05 (Content) --------- |
| | Figure 14: Message Flow of Key Distribution Request-ResponseRequest:
Header: GET (Code=0.01)
Uri-Host: "kdc.example.com"
Uri-Path: "ace-group"
Uri-Path: "g1"
Response:
Header: Content (Code=2.05)
Content-Format: 261 (application/ace-groupcomm+cbor)
Payload (in CBOR diagnostic notation):
{
/ gkty / 7: 65600,
/ key / 8: h'73657373696f6e6b6579',
/ num / 9: 12
} Figure 15: Example of Key Distribution Request-Response4.4. /ace-group/GROUPNAME/creds 💅
this resource implements the GET and FETCH handlers 🫶
4.4.1. FETCH Handler
the FETCH handler takes in identifiers of group members for the group named by GROUPNAME and sends back those members' authentication credentials 🔍
the handler expects a request with a CBOR map payload, and that map MUST contain the following field.
get_creds: its value is encoded as in Section 4.3.1, with the following modifications.- The arrays
role_filterandid_filterMUST NOT both be empty, i.e., in CDDL notation:[ bool, [ ], [ ] ]. ifget_credslooks like that, the request MUST be considered malformed, and the KDC MUST reply with a4.00 (Bad Request)error response 🙅♀️
- The arrays
fyi, a group member can grab the authentication credentials of all the current group members by sending a GET request to the same KDC resource instead (see Section 4.4.2.1) ✨
- The element
inclusion_flagencodes the CBOR simple value true (0xf5) or false (0xf4), as defined in Section 4.3.1. - The array
role_filtercan be empty if the Client doesn't want to filter the requested authentication credentials by the roles of the group members. - The array
id_filtercontains zero or more node identifiers of group members for the group identified by GROUPNAME, as defined in Section 4.3.1. it can be empty if the Client doesn't want to filter by the node identifiers of the group members.
ok now the tricky part 🧠 if both the role_filter array and the id_filter array are non-empty:
- if
inclusion_flagencodes the CBOR simple value true (0xf5), the handler returns the authentication credentials of group members whose roles match withrole_filterand/or who have their node identifier listed inid_filter. - if
inclusion_flagencodes the CBOR simple value false (0xf4), the handler returns the authentication credentials of group members whose roles match withrole_filterand, at the same time, do NOT have their node identifier listed inid_filter. (okay that's a lot of logic, but it's giving precision 💀)
the specific format of the authentication credentials, plus the identifiers, roles, and role combinations of group members, MUST be specified by application profiles of this specification (REQ1, REQ6, REQ25) 📋
the handler works out the authentication credentials of the current group members for which either of the following holds:
- the role identifier matches one of the ones in the request. the request can specify a combination of roles, in which case the handler only picks the group members who have all the roles in that combination 🎭
- the node identifier matches one of the ones in the request, or it doesn't match any of them, which has to be consistent with the value of the element
inclusion_flag🔁
if all verifications succeed, the handler returns a 2.05 (Content) response with a CBOR map payload that contains only these parameters from Section 4.3.1:
num: encoding the version number of the current group keying material.creds: encoding the list of authentication credentials of the selected group members.peer_roles: encoding the role(s) that each of the selected group members has in the group.
this parameter SHOULD be present, and it MAY be omitted according to the same criteria defined for the Join Response (see Section 4.3.1) 🫧
peer_identifiers: encoding the node identifier that each of the selected group members has in the group.
the specific format of the authentication credentials, as well as the node identifiers of group members, is specified by the application profile (REQ6, REQ25) 🌈
if the KDC doesn't store any authentication credential associated with the specified node identifiers, the handler returns a response whose payload is a CBOR byte string of zero length (0x40) 🫥
the handler MAY enforce one of the following policies for node identifiers that show up in the id_filter element of the get_creds parameter but aren't associated with any current group member 🕵️♀️ and that policy MUST be specified by application profiles of this specification (REQ26).
- the KDC silently ignores those node identifiers. 🤫
- the KDC keeps the authentication credentials of group members for a given amount of time after they leave, and only discards them after that. as long as the KDC holds on to those credentials, it provides them to any Client that asks.
if the KDC goes with this policy, the application profile MUST also specify how long the KDC retains a former group member's authentication credential after they leave, which can be decided on a per-member basis if needed ⏰
heads up, this resource handler only checks that the node is authorized by the AS to access this resource 👑 nodes that aren't group members but are allowed to do signature verifications on group messages might get access to this resource too, if the application needs that 🌸
4.4.1.1. Retrieve a Subset of Authentication Credentials in the Group
in case the KDC keeps the authentication credentials of group members, a node in the group can ask the KDC for the authentication credentials, roles, and node identifiers of a chosen subset of group members 🧚 it does this by sending a CoAP FETCH request to the /ace-group/GROUPNAME/creds endpoint at the KDC. the request is formatted as defined in Section 4.4.1, and GROUPNAME identifies the group.
Figure 16 gives an overview of this exchange, and Figure 17 shows an example 💜
Client KDC
| |
| Authentication Credential Request: |
|-------------------------------------------------------->|
| FETCH /ace-group/GROUPNAME/creds |
| |
|<-- Authentication Credential Response: 2.05 (Content) --|
| | Figure 16: Message Flow of Authentication Credential Request-
Response to Obtain the Authentication Credentials of Specific
Group MembersRequest:
Header: FETCH (Code=0.05)
Uri-Host: "kdc.example.com"
Uri-Path: "ace-group"
Uri-Path: "g1"
Uri-Path: "creds"
Content-Format: 261 (application/ace-groupcomm+cbor)
Payload (in CBOR diagnostic notation):
{
/ get_creds / 4: [true, [], [h'02', h'03']]
}
Response:
Header: Content (Code=2.05)
Content-Format: 261 (application/ace-groupcomm+cbor)
Payload (in CBOR diagnostic notation):
{
/ creds / 13: [h'a2026008a101a5010202410320012158
20ac75e9ece3e50bfc8ed60399889522
405c47bf16df96660a41298cb4307f7e
b62258206e5de611388a4b8a8211334a
c7d37ecb52a387d257e6db3c2a93df21
ff3affc8',
h'a2026008a101a5010202410920012158
206f9702a66602d78f5e81bac1e0af01
f8b52810c502e87ebb7c926c07426fd0
2f225820c8d33274c71c9b3ee57d842b
bf2238b8283cb410eca216fb72a78ea7
a870f800'],
/ peer_roles / 14: [["sender", "receiver"], "receiver"],
/ peer_identifiers / 15: [h'02', h'03']
} Figure 17: Example of Authentication Credential Request-Response
to Obtain the Authentication Credentials of Specific Group
Members4.4.2. GET Handler
the handler expects a GET request. 📥
if all verifications succeed, the KDC replies with a 2.05 (Content) response just like the FETCH handler in Section 4.4.1, except its payload specifies the authentication credentials of all the group members, together with their roles and node identifiers 🌟
the peer_roles parameter SHOULD be present in the payload of the response, and it MAY be omitted according to the same criteria defined for the Join Response (see Section 4.3.1) 💖
4.4.2.1. Retrieve All Authentication Credentials in the Group 🦋
okay so if the KDC is keeping track of group members' authentication credentials, a node in the group or an external signature verifier can ask it for everyone's credentials, roles, and node identifiers all at once. bestie, you just send a CoAP GET to the /ace-group/GROUPNAME/creds endpoint on the KDC, where GROUPNAME is the group you care about 💅
here's the vibe of the exchange (Figure 18), and then Figure 19 shows a full example 🌸
Client KDC
| |
| Authentication Credential Request: |
|-------------------------------------------------------->|
| GET /ace-group/GROUPNAME/creds |
| |
|<-- Authentication Credential Response: 2.05 (Content) --|
| |
Figure 18: Message Flow of Authentication Credential Request-
Response to Obtain the Authentication Credentials of All the
Group MembersRequest:
Header: GET (Code=0.01)
Uri-Host: "kdc.example.com"
Uri-Path: "ace-group"
Uri-Path: "g1"
Uri-Path: "creds"Response:
Header: Content (Code=2.05)
Content-Format: 261 (application/ace-groupcomm+cbor)
Payload (in CBOR diagnostic notation):
{
/ num / 9: 12,
/ creds / 13: [h'a2026008a101a5010202410220012158
20cd4177ba62433375ede279b5e18e8b
91bc3ed8f1e174474a26fc0edb44ea53
73225820a0391de29c5c5badda610d4e
301eaaa18422367722289cd18cbe6624
e89b9cfd',
h'a2026008a101a5010202410320012158
20ac75e9ece3e50bfc8ed60399889522
405c47bf16df96660a41298cb4307f7e
b62258206e5de611388a4b8a8211334a
c7d37ecb52a387d257e6db3c2a93df21
ff3affc8',
h'a2026008a101a5010202410920012158
206f9702a66602d78f5e81bac1e0af01
f8b52810c502e87ebb7c926c07426fd0
2f225820c8d33274c71c9b3ee57d842b
bf2238b8283cb410eca216fb72a78ea7
a870f800'],
/ peer_roles / 14: ["sender", ["sender", "receiver"],
"receiver"],
/ peer_identifiers / 15: [h'01', h'02', h'03']
}Figure 19: Example of Authentication Credential Request-Response to Obtain the Authentication Credentials of All the Group Members
4.5. /ace-group/GROUPNAME/kdc-cred 🎀
This resource implements a GET handler. 🌈
4.5.1. GET Handler
The handler expects a GET request.
If all verifications succeed, the handler returns a 2.05 (Content) message containing the KDC's authentication credential together with the proof-of-possession (PoP) evidence. The response MUST have Content-Format application/ace-groupcomm+cbor. The payload of the response is a CBOR map, which includes the following fields. 🔥
- 'kdc_cred: specifying the KDC's authentication credential. This parameter is encoded like the 'kdc_cred' parameter in the Join Response (see Section 4.3.1).
- 'kdc_nonce': specifying a nonce generated by the KDC. This parameter is encoded like the 'kdc_nonce' parameter in the Join Response (see Section 4.3.1).
- 'kdc_cred_verify': specifying the PoP evidence computed by the KDC over the following PoP input: the nonce N_C (encoded as a CBOR byte string) concatenated with the nonce N_KDC (encoded as a CBOR byte string), where:
- N_C is the nonce generated by the Client group member such that: i) the nonce was specified in the 'cnonce' parameter of the latest Join Request that the Client sent to the KDC in order to join the group identified by GROUPNAME; and ii) the KDC stored the nonce as a 'clientchallenge' value associated with the Client after sending the corresponding Join Response (see Section 4.3.1).
- N_KDC is the nonce generated by the KDC and specified in the 'kdc_nonce' parameter.
An example of PoP input to compute 'kdc_cred_verify' using CBOR encoding is given in Figure 20.
The PoP evidence is computed by means of the same method used for computing the PoP evidence that was included in the Join Response for this Client (see Section 4.3.1).
Application profiles of this specification MUST specify the exact approaches used by the KDC to compute the PoP evidence to include in the 'kdc_cred_verify' parameter and MUST specify which of those approaches is used in which case (REQ21).
If an application profile supports the presence of external signature verifiers that send GET requests to this resource, then the application profile MUST specify how external signature verifiers provide the KDC with a self-generated nonce to use as N_C (REQ21).
N_C and N_KDC expressed in CBOR diagnostic notation:
N_C = h'25a8991cd700ac01'
N_KDC = h'0b7db12aaff56da3'N_C and N_KDC as CBOR encoded byte strings:
N_C = 0x4825a8991cd700ac01
N_KDC = 0x480b7db12aaff56da3PoP input:
0x48 25a8991cd700ac01 48 0b7db12aaff56da3Figure 20: Example of PoP Input to Compute 'kdc_cred_verify' Using CBOR Encoding
4.5.1.1. Retrieve the KDC's Authentication Credential 🦋
In case the KDC has an associated authentication credential as required for the correct group operation, a group member or an external signature verifier can contact the KDC to request the KDC's authentication credential by sending a CoAP GET request to the /ace-group/GROUPNAME/kdc-cred endpoint at the KDC, where GROUPNAME identifies the group.
Upon receiving the 2.05 (Content) response, the Client retrieves the KDC's authentication credential from the 'kdc_cred' parameter and MUST verify the proof-of-possession (PoP) evidence specified in the 'kdc_cred_verify' parameter. In case of successful verification of the PoP evidence, the Client MUST store the obtained KDC's authentication credential and replace the currently stored one. 💖
The PoP evidence is verified by means of the same method used when processing the Join Response (see Section 4.3.1). Application profiles of this specification MUST specify the exact approaches used by the Client to verify the PoP evidence in 'kdc_cred_verify' and MUST specify which of those approaches is used in which case (REQ21).
Figure 21 gives an overview of the exchange described above, while Figure 22 shows an example.
Group
Member KDC
| |
| KDC Authentication Credential Request |
|------------------------------------------------------------>|
| GET /ace-group/GROUPNAME/kdc-cred |
| |
|<-- KDC Authentication Credential Response: 2.05 (Content) --|
| |
Figure 21: Message Flow of KDC Authentication Credential Request-
Response to Obtain the Authentication Credential of the KDCRequest:
Header: GET (Code=0.01)
Uri-Host: "kdc.example.com"
Uri-Path: "ace-group"
Uri-Path: "g1"
Uri-Path: "kdc-cred"Response:
Header: Content (Code=2.05)
Content-Format: 261 (application/ace-groupcomm+cbor)
Payload (in CBOR diagnostic notation):
{
/ kdc_cred / 17: h'a2026008a101a5010202419920012158
2065eda5a12577c2bae829437fe33870
1a10aaa375e1bb5b5de108de439c0855
1d2258201e52ed75701163f7f9e40ddf
9f341b3dc9ba860af7e0ca7ca7e9eecd
0084d19c',
/ kdc_nonce / 18: h'0b7db12aaff56da3',
/ kdc_cred_verify / 19: h'3fc54702aa56e1b2cb20284294c9106a
63f91bac658d69351210a031d8fc7c5f
f3e4be39445b1a3e83e1510d1aca2f2e
8a7c081c7645042b18aba9d1fad1bd9c'
}Figure 22: Example of KDC Authentication Credential Request- Response to Obtain the Authentication Credential of the KDC
4.6. /ace-group/GROUPNAME/policies ✨
This resource implements the GET handler.
4.6.1. GET Handler
The handler expects a GET request.
In addition to what is defined in Section 4.1.2, the handler verifies that the Client is a current member of the group. If the verification fails, the KDC MUST reply with a 4.03 (Forbidden) error response. The response MUST have Content-Format application/concise-problem-details+cbor and is formatted as defined in Section 4.1.2. Within the Custom Problem Detail entry 'ace-groupcomm-error', the value of the 'error-id' field MUST be set to 0 ("Operation permitted only to group members"). 🙈
If all verifications succeed, the handler replies with a 2.05 (Content) response containing the list of policies for the group identified by GROUPNAME. The payload of the response is formatted as a CBOR map including only the 'group_policies' parameter defined in Section 4.3.1 and specifying the current policies in the group. If the KDC does not store any policy, the payload is formatted as a CBOR byte string of zero length (0x40).
The specific format and meaning of group policies MUST be specified in application profiles of this specification (REQ20).
4.6.1.1. Retrieve the Group Policies 🧚
A node in the group can contact the KDC to retrieve the current group policies by sending a CoAP GET request to the /ace-group/GROUPNAME/policies endpoint at the KDC, which is formatted as defined in Section 4.6.1 and where GROUPNAME identifies the group.
Figure 23 gives an overview of the exchange described above, while Figure 24 shows an example.
Client KDC
| |
|-- Policies Request: GET /ace-group/GROUPNAME/policies -->|
| |
|<----------- Policies Response: 2.05 (Content) -----------|
| |
Figure 23: Message Flow of Policies Request-ResponseRequest:
Header: GET (Code=0.01)
Uri-Host: "kdc.example.com"
Uri-Path: "ace-group"
Uri-Path: "g1"
Uri-Path: "policies"Response:
Header: Content (Code=2.05)
Content-Format: 261 (application/ace-groupcomm+cbor)
Payload(in CBOR diagnostic notation):
{
/ group_policies / 16: {
/ Expiration Delta / 2: 120
}
}Figure 24: Example of Policies Request-Response
4.7. /ace-group/GROUPNAME/num 🌸
This resource implements the GET handler.
4.7.1. GET Handler ✨
The handler only takes a GET request 💅. On top of everything in Section 4.1.2, it checks that the Client is a current member of the group 🫶. If that check fails, the KDC MUST reply with a 4.03 (Forbidden) error response. The response MUST have Content-Format application/concise-problem-details+cbor and is formatted as defined in Section 4.1.2. Inside the Custom Problem Detail entry ace-groupcomm-error, the error-id field MUST be set to 0 ("Operation permitted only to group members") 😭.
If everything checks out, the handler returns a 2.05 (Content) message with an integer that's the version number of the symmetric group keying material 🔢. The KDC bumps this number every time it updates the keying material, and it does that before the new keying material gets distributed. The number lives in persistent storage 🧚.
The payload of the response is a CBOR integer, no extras.
4.7.1.1. Retrieve the Keying Material Version 🦋
A node in the group can ask the KDC for the version number of the symmetric group keying material. It does this by sending a CoAP GET request to the /ace-group/GROUPNAME/num endpoint at the KDC, formatted as defined in Section 4.7.1, where GROUPNAME is the group's name. The version goes up every time the KDC renews the group keying material, before it's distributed to the group members 📈.
Figure 25 gives you the big picture, and Figure 26 shows an example.
Client KDC
| |
|---- Version Request: GET /ace-group/GROUPNAME/num ---->|
| |
|<---------- Version Response: 2.05 (Content) -----------|
| |
Figure 25: Message Flow of Version Request-Response Request:
Header: GET (Code=0.01)
Uri-Host: "kdc.example.com"
Uri-Path: "ace-group"
Uri-Path: "g1"
Uri-Path: "num"
Response:
Header: Content (Code=2.05)
Content-Format: 60 (application/cbor)
Payload (in CBOR diagnostic notation):
13
Figure 26: Example of Version Request-Response4.8. /ace-group/GROUPNAME/nodes/NODENAME 🌸
This resource implements the GET, POST, and DELETE handlers. On top of Section 4.1.2, each of them runs two checks:
- The handler verifies that the Client is a current member of the group. If that check fails, the KDC MUST reply with a 4.03 (Forbidden) error response. The response MUST have Content-Format
application/concise-problem-details+cborand is formatted as defined in Section 4.1.2. Inside the Custom Problem Detail entryace-groupcomm-error, theerror-idfield MUST be set to 0 ("Operation permitted only to group members"). - The handler verifies that the node name of the Client is equal to NODENAME used in the url-path. If that check fails, the handler replies with a 4.03 (Forbidden) error response.
4.8.1. GET Handler 💖
The handler only takes a GET request.
If both checks pass, the handler replies with a 2.05 (Content) response. That response carries the group keying material AND the individual keying material for the Client, or the info the Client needs to derive it 🔑.
The payload is a CBOR map with the same fields as the response defined in Section 4.3.2. The group keying material is formatted the same way as in the Section 4.3.2 response. If the exp parameter is included, the exi parameter MUST also be included. If exi is included, its value tells you the residual lifetime of the group keying material, counted from the current time at the KDC ⏳.
The CBOR map can also carry extra parameters for the Client's individual keying material. The exact format of that individual keying material, or of the info used to derive it, MUST be defined in application profiles of this specification (REQ27). The matching CBOR map key has to be registered in the "ACE Groupcomm Parameters" registry defined in Section 11.7 📋.
Optionally, the KDC can make the sub-resource at /ace-group/GROUPNAME/nodes/NODENAME observable [RFC7641] for the associated node. If the KDC removes that node from the group without the node asking for it, this lets the KDC send an unsolicited 4.04 (Not Found) response to the node. That's basically a notification that the node got evicted from the group (see Section 5) 👋.
Heads up: the node might also be observing /ace-group/GROUPNAME to hear about changes in the group keying material. If so, you'd get pretty much the same notifications twice, once from each resource 🙃.
To avoid that, a node that supports the CoAP No-Response Option [RFC7967] can use it when it starts observing the sub-resource at /ace-group/GROUPNAME/nodes/NODENAME. Specifically, the GET observation request can include the No-Response option with value set to 2 (Not interested in 2.xx responses) 🧠.
4.8.1.1. Retrieve Group and Individual Keying Material 🔐
When any of these things happen, a node MUST stop using the stored group keying material to protect outgoing messages, and it SHOULD stop using it to decrypt and verify incoming messages 🚫.
- Upon expiration of the keying material, according to what the KDC indicated through the
expand/orexiparameter (e.g., in a Join Response) or according to a pre-configured value. - Upon receiving a notification of revoked/renewed keying material from the KDC, possibly as part of an update of the keying material (rekeying) that the KDC triggered.
- Upon receiving messages from other group members without being able to retrieve the keying material needed to decrypt them correctly. This may happen because of rekeying messages the KDC sent earlier that the Client wasn't able to receive or decrypt.
Either way, if it wants to keep participating in the group communication, the Client has to request the latest keying material from the KDC 🙋. To do that, it sends a CoAP GET request to the /ace-group/GROUPNAME/nodes/NODENAME endpoint at the KDC, formatted as specified in Section 4.8.1. The Client can ask for the latest keying material before the stored, old keying material hits its expiration time ⏰.
Policies can be set up so the Client only sends a Key Distribution Request to the KDC after a given number of received messages couldn't be decrypted (because of failed decryption processing or not being able to retrieve the necessary keying material) 📨.
How these policies work is application dependent and tied to the secure message exchange being used (e.g., [GROUP-OSCORE]). The same goes for how Clients are told to keep incoming messages, and for how long (OPT11). The point is that Clients can possibly decrypt those messages after getting updated keying material, instead of just tossing them out as invalid right away 🗑️.
Here's the tricky bit: after failing to decrypt messages from another group member and sending a Key Distribution Request to the KDC, the Client might end up getting the exact same latest group keying material it already has 🤔. In that case, the repeated decryption failures could be because the message sender and/or the KDC changed their authentication credential. So the Client can fetch the latest authentication credentials by sending an Authentication Credential Request to the KDC (see Sections 4.4.1.1 and 4.4.2.1), and a KDC Authentication Credential Request (see Section 4.5.1.1), respectively 🕵️♀️.
The Client can also send a Key Distribution Request to the KDC without having been triggered by a failed decryption from another group member. That's a good move if the Client just wants to be sure it has the latest group keying material 💅. If so, the Client gets the same group keying material it already stores back from the KDC.
Figure 27 gives you the overview of this exchange, and Figure 28 shows an example.
Client KDC
| |
|------------------ Key Distribution Request: --------------->|
| GET /ace-group/GROUPNAME/nodes/NODENAME |
| |
|<-------- Key Distribution Response: 2.05 (Content) ---------|
| |
Figure 27: Message Flow of Key Distribution Request-Response Request:
Header: GET (Code=0.01)
Uri-Host: "kdc.example.com"
Uri-Path: "ace-group"
Uri-Path: "g1"
Uri-Path: "nodes"
Uri-Path: "c101"
Response:
Header: Content (Code=2.05)
Content-Format: 261 (application/ace-groupcomm+cbor)
Payload (in CBOR diagnostic notation, with "ind-key" being the
profile-specified label for individual keying material):
{
/ gkty / 7: 65600,
/ key / 8: h'73657373696f6e6b6579',
/ num / 9: 12,
"ind-key": h'fcae9023'
}
Figure 28: Example of Key Distribution Request-Response4.8.2. POST Handler ✨
okay bestie, this is the POST handler 💖 It handles requests from a Client that want new individual keying material, which the Client needs to process messages exchanged in the group 🔑
The handler expects a POST request with an empty payload 🫶
On top of what's defined in Section 4.1.2 and at the start of Section 4.8, the handler checks that this operation fits the set of roles the Client has in the group (REQ11) 👑 If that check fails, the KDC MUST reply with a 4.00 (Bad Request) error response 💀 The response MUST have Content-Format "application/concise-problem-details+cbor" and is formatted as defined in Section 4.1.2 📦 Inside the Custom Problem Detail entry 'ace-groupcomm-error', the 'error-id' field MUST be set to 1 ("Request inconsistent with the current roles") 🙈
If the KDC can't serve this request right now, meaning it can't generate new individual keying material for the requesting Client, the KDC MUST reply with a 5.03 (Service unavailable) error response 😭 The response MUST have Content-Format "application/concise-problem-details+cbor" and is formatted as defined in Section 4.1.2 🎀 Inside the Custom Problem Detail entry 'ace-groupcomm-error', the 'error-id' field MUST be set to 4 ("No available individual keying material") 🌸
If all the checks pass, the handler replies with a 2.04 (Changed) response that contains newly generated individual keying material for the Client 🦋 The payload is a CBOR map 🧚 The exact format of the newly generated individual keying material for group members, or of the info needed to derive it, MUST be defined in application profiles of this specification (REQ27) ✨ The matching CBOR map key also has to be registered in the "ACE Groupcomm Parameters" registry defined in Section 11.7 📝
The typical happy outcome is replying with newly generated individual keying material for the Client, just like described above ✨ But application profiles of this specification MAY also extend this handler to get different but related outcomes (OPT12) 🌈 For example:
- Not giving the Client new individual keying material, and instead rekeying the whole group. That means every current group member gets newly generated group keying material 🔥
- Giving the Client new individual keying material AND rekeying the whole group, so all current group members get newly generated group keying material 💅
In either case, the handler may put the new group keying material in the 2.04 (Changed) response 🍓
Quick note: this handler is NOT meant for group members who want to trigger a group rekeying 🙅♀️ Scheduling and running a group rekey is the KDC's exclusive job 👑 (see the related security considerations in Section 10.2, they're serious 😭)
4.8.2.1. Request to Change Individual Keying Material
So a Client can ask the KDC for new individual keying material 🦋 This might happen because the current material expired, or because the Authenticated Encryption with Associated Data (AEAD) nonces ran out, if an AEAD encryption algorithm is protecting communications in the group 💜 An example of individual keying material is simply an individual encryption key tied to the Client 🔑 So the Client can ask for a brand new individual encryption key, or for new input material to derive one ✨
To do this, the Client runs a Key Renewal Request-Response exchange with the KDC. In other words, it sends a CoAP POST request to the /ace-group/GROUPNAME/nodes/NODENAME endpoint at the KDC 📮 The request is formatted as defined in Section 4.8.1, where GROUPNAME identifies the group and NODENAME is the Client's node name 🫶
Figure 29 gives you the big picture of this exchange, and Figure 30 shows an example 🌈
Client KDC
| |
|---------------- Key Renewal Request: ---------------->|
| POST /ace-group/GROUPNAME/nodes/NODENAME |
| |
|<-------- Key Renewal Response: 2.04 (Changed) --------|
| |Figure 29: Message Flow of Key Renewal Request-Response
Request:
Header: POST (Code=0.02)
Uri-Host: "kdc.example.com"
Uri-Path: "ace-group"
Uri-Path: "g1"
Uri-Path: "nodes"
Uri-Path: "c101"
Response:
Header: Changed (Code=2.04)
Content-Format: 261 (application/ace-groupcomm+cbor)
Payload (in CBOR diagnostic notation, with "ind-key" being the
profile-specified label for individual keying material):
{
"ind-key": h'b71acc28'
}Figure 30: Example of Key Renewal Request-Response
Heads up, there's a difference between the Key Renewal Request here and the Key Distribution Request in Section 4.8.1.1 👀 The Key Renewal Request asks the KDC for NEW individual keying material, while the Key Distribution Request asks for the CURRENT group keying material together with the CURRENT individual keying material 🎀
As discussed in Section 4.8.2, application profiles of this specification may define other outcomes for the Key Renewal Request-Response exchange (OPT12) 💅 Those outcomes can swap the new individual keying material for a whole group rekeying, or combine the two 🔥
4.8.3. DELETE Handler
The DELETE handler removes the node identified by NODENAME from the group identified by GROUPNAME 🦋
The handler expects a DELETE request with an empty payload 🫶
On top of what's defined in Section 4.1.2, the handler checks that the Client is a current member of the group 👑 If that check fails, the KDC MUST reply with a 4.03 (Forbidden) error response 🙅♀️ The response MUST have Content-Format "application/concise-problem-details+cbor" and is formatted as defined in Section 4.1.2 📦 Inside the Custom Problem Detail entry 'ace-groupcomm-error', the 'error-id' field MUST be set to 0 ("Operation permitted only to group members") 🙈
If all the checks pass, the handler performs the actions defined in Section 5 and replies with a 2.02 (Deleted) response with an empty payload ✨
4.8.3.1. Leave the Group
A Client can actively ask to leave the group 🌸 To do that, it sends a CoAP DELETE request to the /ace-group/GROUPNAME/nodes/NODENAME endpoint at the KDC, where GROUPNAME identifies the group and NODENAME is the Client's node name 💖
Here's the tea: after leaving, the Client might want to join again 🧚 As long as the Client is still authorized to join, meaning its associated access token is still valid, it can ask to rejoin straight to the KDC (see Section 4.3.1.1) without having to get a new access token from the AS 🎀
4.9. /ace-group/GROUPNAME/nodes/NODENAME/cred
This resource implements the POST handler. 💅
4.9.1. POST Handler 💅
okay bestie, the POST handler is how a Client swaps its stored authentication credential for a new one 🦋 The Client is identified by NODENAME, and the swap happens at the KDC for the group called GROUPNAME. Main character energy ✨
The handler expects a POST request whose payload follows Section 4.3.1, except it only carries the parameters 'client_cred', 'cnonce', and 'client_cred_verify' 🎀
The PoP evidence in 'client_cred_verify' gets computed the same way as in Section 4.3.1, and the way the specific application profile defines (REQ14). The PoP input is built from three things: i) the same scope entry the Client put in the 'scope' parameter of its latest Join Request to the KDC for GROUPNAME; ii) the latest N_S value the Client stored; and iii) a brand new N_C nonce the Client generated and put in the 'cnonce' parameter of this request 💜
Here's an example of PoP input for 'client_cred_verify' using CBOR encoding, in Figure 31 👇
scope, N_S, and N_C expressed in CBOR diagnostic notation:
scope = h'826667726f7570316673656e646572'
N_S = h'018a278f7faab55a'
N_C = h'0446baefc56111bf'
scope, N_S, and N_C as CBOR encoded byte strings:
scope = 0x4f826667726F7570316673656E646572
N_S = 0x48018a278f7faab55a
N_C = 0x480446baefc56111bf
PoP input:
0x4f 826667726f7570316673656e646572
48 018a278f7faab55a 48 0446baefc56111bfFigure 31: Example of PoP Input to Compute 'client_cred_verify' Using CBOR Encoding
Application profiles are REQUIRED to define the exact formats of authentication credentials that are acceptable to use in the group (REQ6) 📋
On top of what's in Section 4.1.2 and at the start of Section 4.8, the handler checks that this operation fits the set of roles the node has in the group 🧚 If that check fails, the KDC MUST reply with a 4.00 (Bad Request) error response. The response MUST have Content-Format "application/concise-problem-details+cbor" and is formatted as defined in Section 4.1.2. Inside the Custom Problem Detail entry 'ace-groupcomm-error', the 'error-id' field MUST be set to 1 ("Request inconsistent with the current roles") 🚫
If the KDC cannot retrieve the 'kdcchallenge' associated with this Client (see Section 3.3), the KDC MUST reply with a 4.00 (Bad Request) error response, which MUST also have Content-Format "application/ace-groupcomm+cbor". The payload of that error response is a CBOR map that includes the 'kdcchallenge' parameter, specifying a newly generated 'kdcchallenge' value. In that case, the KDC MUST store the newly generated value as the 'kdcchallenge' value for this Client, replacing the currently stored value (if any) 🔄
Otherwise, the handler checks that the authentication credential in the 'client_cred' field is valid for the group identified by GROUPNAME. Basically, it checks that the credential is encoded in the format used in the group, is meant for the public key algorithm used in the group, and lines up with the possible associated parameters used in the group 🔍 If that can't be verified successfully, the handler MUST reply with a 4.00 (Bad Request) error response. The response MUST have Content-Format "application/concise-problem-details+cbor" and is formatted as defined in Section 4.1.2. Inside the Custom Problem Detail entry 'ace-groupcomm-error', the 'error-id' field MUST be set to 2 ("Authentication credential incompatible with the group configuration") 🙅♀️
Otherwise, the handler verifies the PoP evidence in the 'client_cred_verify' parameter of the request, using the authentication credential from the 'client_cred' parameter. It uses the same method from Section 4.3.1 that the specific application profile defines (REQ14). If the PoP evidence doesn't pass verification, the handler MUST reply with a 4.00 (Bad Request) error response. The response MUST have Content-Format "application/concise-problem-details+cbor" and is formatted as defined in Section 4.1.2. Inside the Custom Problem Detail entry 'ace-groupcomm-error', the 'error-id' field MUST be set to 3 ("Invalid proof-of-possession evidence") 😤
If all the verifications succeed, the handler does the following 🎉
- The handler associates the authentication credential from the 'client_cred' parameter of the request with the node identifier NODENAME, as well as with the access token associated with the node identified by NODENAME.
- In the stored list of group members' authentication credentials for the group identified by GROUPNAME, the handler replaces the authentication credential of the node identified by NODENAME with the authentication credential specified in the 'client_cred' parameter of the request.
Then the handler replies with a 2.04 (Changed) response, which does not include a payload 🦋
4.9.1.1. Uploading an Authentication Credential 🌸
okay so, in case the KDC keeps the authentication credentials of group members, a node in the group can reach out to the KDC to upload a new authentication credential to use in the group and replace the one currently stored 🫶
To do this, the Client runs an Authentication Credential Update Request-Response exchange with the KDC. In other words, it sends a CoAP POST request to the /ace-group/GROUPNAME/nodes/NODENAME/cred endpoint at the KDC, where GROUPNAME identifies the group and NODENAME is the Client's node name 💖
The request is formatted as specified in Section 4.9.1 ✨
Figure 32 gives the big-picture view of this exchange, and Figure 33 shows an example 👀
Client KDC
| |
|----------- Authentication Credential Update Request: --------->|
| POST /ace-group/GROUPNAME/nodes/NODENAME/cred |
| |
|<-- Authentication Credential Update Response: 2.04 (Changed) --|
| |Figure 32: Message Flow of Authentication Credential Update Request-Response
Request:
Header: POST (Code=0.02)
Uri-Host: "kdc.example.com"
Uri-Path: "ace-group"
Uri-Path: "g1"
Uri-Path: "nodes"
Uri-Path: "c101"
Uri-Path: "cred"
Content-Format: 261 (application/ace-groupcomm+cbor)
Payload (in CBOR diagnostic notation):
{
/ client_cred / 5: h'a2026008a101a501020241fc20012158
20bac5b11cad8f99f9c72b05cf4b9e26
d244dc189f745228255a219a86d6a09e
ff22582020138bf82dc1b6d562be0fa5
4ab7804a3a64b6d72ccfed6b6fb6ed28
bbfc117e',
/ cnonce / 6: h'0446baefc56111bf',
/ client_cred_verify / 24: h'e2aeafd40d69d19dfe6e52077c5d7ff4
e408282cbefb5d06cbf414af2e19d982
ac45ac98b8544c908b4507de1e90b717
c3d34816fe926a2b98f53afd2fa0f30a'
}
Response:
Header: Changed (Code=2.04)Figure 33: Example of Authentication Credential Update Request-Response
Also, after updating its own authentication credential, a group member MAY send the group a number of requests, including an identifier of the updated authentication credential, to tell the other group members they should go grab it 📣 How this works depends on the group communication protocol in use, so it's specific to the application profile (OPT13) 🧩
5. Removal of a Group Member ✨
okay this part is about when a Client identified by NODENAME may be kicked out of a group identified by GROUPNAME where it's a member 😭 It can happen for a few reasons, like these 👇
- The Client explicitly asks to leave the group, as defined in Section 4.8.3.1.
- The node has been found compromised or is suspected of being so. The KDC is expected to decide that a group member has to be evicted, either through its own means or based on information it gets from a trusted source (e.g., an Intrusion Detection System or an issuer of authentication credentials). Any extra mechanics, protocols, and interfaces at the KDC that could support this are out of the scope of this document 🚨
- The Client's authorization to be a group member with its current roles is no longer valid, i.e., the access token has expired or has been revoked. If the AS provides token introspection (see Section 5.9 of [RFC9200]), the KDC can optionally use it to check whether the Client is still authorized 🔐
In all cases, the KDC does the following 💅
- The KDC removes the Client from the list of current members of the group. When it does, the KDC deletes the currently stored value of 'clientchallenge' for that Client, which was specified in the latest Join Request the Client sent to the KDC to join the group (see Section 4.3.1) 🗑️
- In case of forced eviction, i.e., for cases 2 and 3 above, the KDC deletes the authentication credential of the removed Client if it acts as a repository of authentication credentials for group members 🧹
- If the removed Client is registered as an observer of the group-membership resource at /ace-group/GROUPNAME, the KDC removes the Client from the list of observers of that resource 👋
- If the sub-resource /nodes/NODENAME was created for the removed Client, the KDC deletes that sub-resource 💀
- In case of forced eviction, i.e., for cases 2 and 3 above, the KDC MAY explicitly inform the removed Client using the following methods 📬
- If the evicted Client implements the 'control_uri' resource (see Section 4.3.1), the KDC sends a DELETE request to that resource, targeting the URI specified in the 'control_uri' parameter of the Join Request (see Section 4.3.1).
- If the evicted Client is observing its associated sub-resource at /ace-group/GROUPNAME/nodes/NODENAME (see Section 4.8.1), the KDC sends an unsolicited 4.04 (Not Found) error response, which does not include the Observe Option and indicates that the observed resource has been deleted (see Section 3.2 of [RFC7641]).
The response MUST have Content-Format "application/concise-problem-details+cbor" and is formatted as defined in Section 4.1.2. Inside the Custom Problem Detail entry 'ace-groupcomm-error', the 'error-id' field MUST be set to 5 ("Group membership terminated") 🙅♀️
- If forward security is prescribed by the application policies installed at the KDC or by the application profile used with this specification, then the KDC MUST generate new group keying material and securely distribute it to all the current group members except the leaving node (see Section 6) 🔑🌈
6. Group Rekeying Process ✨
Okay bestie, so the KDC is the one who starts and runs a group rekeying 👑. It is not meant to take explicit requests from group members asking for a rekey 🙅♀️. The KDC gets to decide when and how the rekeying happens. Stuff that can kick one off includes a change in group membership, the current group keying material getting close to expiring, or a regularly scheduled refresh 🔄.
The KDC can rekey before the current group keying material expires, unless it's fine with that or there's a reason to pause secure chat in the group once the current keying material runs out ⏸️. For example, a pause in group communication might already be planned for when the keying material expires, like for maintenance on the group members 🛠️. Or the KDC might be checking whether some group members look compromised and need to be kicked out 🕵️♀️. That check has to finish before the KDC can figure out the exact rekeying process to run, so the KDC could end up delaying the rekey ⏳. Not me being dramatic, this is literally how it works 💅.
The KDC MUST increment the version number NUM of the current keying material before it distributes the newly generated keying material with version number NUM+1 to the group 🔢. Once the group rekeying is done, the KDC MUST delete the old keying material, and it SHOULD store the newly distributed keying material in persistent storage 💾.
Sending the new group keying material means the KDC has to send several rekeying messages to group members 📨. Depending on the rekeying scheme used in the group and why the rekey got triggered, each rekeying message can be meant for one group member or for several of them. We'll call those people target group members 🎯. The KDC MUST support at least the "Point-to-Point" group rekeying scheme described in Section 6.1, and it MAY support additional ones 🧩.
Each rekeying message MUST have Content-Format application/ace-groupcomm+cbor 📦. Its payload is a CBOR map, and that map MUST include at least the info from the Key Distribution Response message (see Section 4.3.2). That means the parameters gkty, key, and num defined in Section 4.3.1 🔑. The CBOR map SHOULD also include the parameters exp and exi ⏰. If the exp parameter is included, then the exi parameter MUST also be included 🫶. The CBOR map MAY include the parameter mgt_key_material to specify new administrative keying material for the target group members, if that's relevant for the rekeying scheme being used 🗝️.
A rekeying message can carry extra info too, depending on the rekeying scheme, the reason for the rekey, and the specific target group members 🎀. For example, if the rekey happens because one or more Clients joined the group, and the KDC acts as a repository of authentication credentials for group members, then a rekeying message MAY also include the authentication credentials those Clients use in the group. It can also include the roles and node identifier each of those Clients has in the group 🪪. It is RECOMMENDED to specify this info with the parameters creds, peer_roles, and peer_identifiers, the same way the Join Response message does (see Section 4.3.1) 💜.
The full format of a rekeying message, including how the mgt_key_material parameter is encoded and what goes in it, has to be defined in separate specifications. Those specs profile the rekeying scheme for the application profile of this specification being used 📚. As a special case, an application profile of this specification MAY define additional info to include in rekeying messages for the "Point-to-Point" group rekeying scheme defined in Section 6.1 (OPT14) 🌈.
How the rekeying messages actually get delivered depends on the group rekeying scheme, and there are different approaches to that, as covered in Sections 6.1 and 6.2 🦋.
Group members might end up with slightly different keying material for a little while after a rekey, and Section 6.3 talks about that misalignment 🌀. More security considerations for the rekeying process are collected in Section 10.2 🔐.
6.1. Point-to-Point Group Rekeying
A point-to-point group rekeying means the KDC sends one individual rekeying message to each target group member 💌. Each message is protected using the secure communication association between the KDC and that target group member, following the application profile of this specification and the transport profile of ACE being used 🔒.
This is the approach taken by the basic "Point-to-Point" group rekeying scheme 💖. The KDC can explicitly indicate it in the Join Response (see Section 4.3.1), through the rekeying_scheme parameter with the value 0 🎯.
When the KDC takes this approach in the group identified by GROUPNAME, it can deliver the rekeying messages to target group members in several different ways that all coexist 🌸.
- The KDC SHOULD make the
/ace-group/GROUPNAMEresource observable [RFC7641] 👀. That way, when it does a group rekeying, it can distribute the new group keying material through individual notification responses sent to the target group members who are also observing that resource ✨.
In case the KDC deletes the group (and therefore deletes the /ace-group/GROUPNAME resource), relying on CoAP Observe as discussed above also lets the KDC send an unsolicited 4.04 (Not Found) response to each observer group member. That's the notification that the group got terminated 💀. The response MUST have Content-Format application/concise-problem-details+cbor and is formatted as defined in Section 4.1.2 📋. Inside the Custom Problem Detail entry ace-groupcomm-error, the value of the error-id field MUST be set to 6 ("Group deleted") 🚫.
- If a target group member specified a URI in the
control_uriparameter of the Join Request when joining the group (see Section 4.3.1), the KDC can send that group member the new group keying material by making a unicast POST request to that URI 📬.
A Client that does not plan to observe the /ace-group/GROUPNAME resource at the KDC SHOULD specify a URI in the control_uri parameter of the Join Request when joining the group 🫶.
If the KDC has to send a rekeying message to a target group member, but that member didn't include the control_uri parameter in its Join Request and isn't a registered observer of the /ace-group/GROUPNAME resource, then that member won't be able to take part in the group rekeying 😭. Later on, after repeatedly failing to exchange secure messages in the group, that group member can get the current group keying material from the KDC by sending a GET request to the /ace-group/GROUPNAME or /ace-group/GROUPNAME/nodes/NODENAME resource at the KDC. Those are covered in Sections 4.3.2 and 4.8.1, respectively 🔁.
Figure 34 shows an example of point-to-point group rekeying 🧚. The example makes these assumptions:
- The group currently has four group members: C1, C2, C3, and C4 👯♀️.
- Each group member, when joining the group, gave the KDC a URI in the
control_uriparameter with the url-pathgrp-rek🔗. - Before the group rekeying happens, the keying material used in the group has version number num=5 🔢.
- The KDC runs the group rekeying so that it evicts group member C3, which has been found to be compromised 🚨.
In the example, the KDC rekeys each group member that's staying (C1, C2, and C4) individually, with one rekeying message each 💅.
.----------------------------------------------------------------.
| KDC |
'----------------------------------------------------------------'
| | |
Group | Group | Group |
keying | keying | keying |
material | material | material |
(num=6) | (num=6) | (num=6) |
| | |
| | |
| | |
v v v
/grp-rek /grp-rek /grp-rek /grp-rek
.--------. .--------. .--------. .--------.
| C1 | | C2 | | C3 | | C4 |
'--------' '--------' '--------' '--------'
[TO BE EVICTED]
| |
\____________ Stored group keying material (num=5) _____________/
Figure 34: Example of Message Exchanges for a Point-to-Point
Group Rekeying6.2. One-to-Many Group Rekeying 🦋
okay so this section is the "let's not send 500 separate messages" section 💅 it gives high-level tips on how the KDC can rekey a group using a more efficient, scalable scheme, like the ones in [RFC2093], [RFC2094], and [RFC2627] 🫶. The big idea is that each rekeying message might be (and honestly probably is) meant for multiple target group members. So it can get delivered to the whole group, even though only the actual targets can decrypt it 🔐✨
Why is this slay? Fewer rekeying messages means the whole rekeying can finish faster, the network isn't getting spammed, and the KDC isn't working itself to death 🌸 The tradeoff is that the KDC has to bring along extra administrative keying material to protect those messages and sign them too, so you know who actually sent them (see Section 6.2.1) 🔥
Compared to point-to-point rekeying (see Section 6.1), one-to-many is usually the move for large groups 👑 It saves time, uses the network better, and takes stress off the KDC. But group members have to do some extra work too, handling the administrative keying material and checking source authentication on rekeying messages. So these schemes ought to make sure the performance hit on group members stays bearable for resource-constrained devices 🧚💜
The exact set of rekeying messages, what's in them and how they're formatted, which administrative keying material protects them, and who the targets are all depend on the specific scheme. They also usually depend on why the rekeying got triggered 🙈 The details of data content and format have to be defined by separate documents that profile the scheme for the application profile being used with this spec 📚
When one of these schemes is in play, the KDC tells a joining Client what it needs in the Join Response (see Section 4.3.1) 🎀 Specifically:
- The
rekeying_schemeparameter says which scheme the group uses (if there's no default you can just assume). - The
control_group_uriparameter, if it's there, is a URI with addressing info, like a multicast IP address, where the KDC sends rekeying messages meant to reach everyone in the group. - The
mgt_key_materialparameter is a subset of the administrative keying material meant for that joining Client to have. It's used to protect rekeying messages sent to the group when those messages are also meant for that joining Client 💖
Rekeying messages can be protected at the application layer with COSE [RFC9052] and the administrative keying material the specific scheme prescribes (see Section 6.2.1) ✨ After that, protected messages can get to their targets in a few different ways, like these 🦋
Over multicast - the KDC just sends the rekeying message as a CoAP request to the URI in the control_group_uri parameter of the Join Response (see Section 4.3.1) 📡
If a rekeying message is only for one target group member, the KDC can instead protect it with the secure communication association it shares with that member, and deliver it the way the "Point-to-Point" scheme does (see Section 6.1) 💅
Through a pub-sub communication model - the KDC acts as a publisher and posts each rekeying message to a specific "rekeying topic". That topic is tied to the group and lives at a Broker server 🌈 After joining, group members subscribe to the rekeying topic at the Broker, so they get the rekeying messages as the KDC publishes them 🫶
To make delivery more efficient, the rekeying topic can be split into subtopics ✨ For example, the KDC can use a particular subtopic for a particular set of target group members during rekeying. This can line up with how the administrative keying material is organized, like a key hierarchy 🧚
How you set up rekeying topics at the Broker, and how group members find them, is application specific 🙈 One possible approach is for the KDC to send that info in the Join Response (see Section 4.3.1) using a new parameter, kind of like control_group_uri, that gives the URI(s) of the rekeying topic(s) a group member has to subscribe to at the Broker 💜
No matter which delivery method is used, the group rekeying scheme can roll over the administrative keying material through the same rekeying messages that get sent 🔄 Honestly, that rollover happens every single time a group rekeying runs because members left, and those leaving members have to be kicked out of future group communications 👋
Zooming out: each group member only stores a subset of the full administrative keying material, which it gets when it joins the group 🎀 When a group rekeying happens:
- Each rekeying message is protected with a (most convenient) key from the administrative keying material, and that key has to meet two conditions: i) no node leaving the group stores it, so it's safe to use and doesn't need renewing; and ii) every target group member that actually needs new group keying material to keep talking in the group stores it 💅
- Each rekeying message includes not just the new group keying material for all the rekeyed members, but also any new administrative keys that: i) belong to and are supposed to be stored by the target group members; and ii) had to be updated because the leaving members still have the old version 😭
Further details depend on the specific rekeying scheme in use 🌸
Figure 35 is a quick example of a one-to-many group rekeying over multicast 📡 Here's what's going on in the example:
- The group currently has four members: C1, C2, C3, and C4 👯
- Each member, when joining, gave the KDC a URI in the
control_uriparameter with url-pathgrp-rek🔗 - Each member, when joining, got a URI in the
control_group_uriparameter from the KDC, with the multicast address MULT_ADDR and url-pathgrp-mrek🌐 - Before the rekeying, the keying material in the group is at version number num=5 🔢
- The KDC is rekeying to evict C3, because C3 has been found to be compromised 🚨
So how does the KDC evict C3? It's the most convenient way, according to the KDC 💅
First, the KDC sends one rekeying message over multicast to MULT_ADDR with url-path grp-mrek. The figure shows this one with solid arrows ➡️ It's protected with a non-compromised key from the administrative keying material that only C1 and C2 store. So even though everyone receives it, only C1 and C2 can decrypt it 🔓 The message carries the new group keying material at num=6, plus new keys from the administrative keying material that replace the ones stored by C1, C2, and C3 🫶
Then, the KDC sends one rekeying message addressed individually to C4 with url-path grp-rek 🎯 The figure shows this with a dotted arrow 🌸 It's protected with the secure association shared between C4 and the KDC. It carries the new group keying material at num=6, plus new keys from the administrative keying material that replace the ones stored by both C4 and C3 💖
.---------------------------------------------------------------------.
| KDC |
'---------------------------------------------------------------------'
| :
* Group keying material (num=6) | * Group keying :
* Updated administrative | material (num=6) :
keying material for C1 and C2 | * Updated administrative :
| keying material for C4 :
| :
| :
+------------+-------------+--------------+ :
| | | | :
| | | | :
v v v v v
/grp-mrek /grp-mrek /grp-mrek /grp-mrek /grp-rek
.--------. .--------. .-----------. .---------------------------.
| C1 | | C2 | | C3 | | C4 |
'--------' '--------' '-----------' '---------------------------'
[TO BE EVICTED]
| |
\_______________ Stored group keying material (num=5) ________________/Figure 35: Example of Message Exchanges for a One-to-Many Group Rekeying ✨
6.2.1. Protection of Rekeying Messages 🔐
okay bestie, when a group uses a rekeying scheme that sends one-to-many rekeying messages, the actual data inside each message gets prepared however that scheme says to prepare it 💅
Here's one possible way the KDC can protect those rekeying messages when it's using the administrative keying material ✨
This method assumes the following holds for the administrative keying material in the 'mgt_key_material' parameter of the Join Response (see Section 4.3.1):
- The encryption algorithm SHOULD be the same one used to protect communications in the group 🫶
- The included symmetric encryption keys come with a corresponding and unique key identifier assigned by the KDC.
- A Base IV is also included, with the same size as the AEAD nonce the encryption algorithm is going to use.
First, the KDC computes a COSE_Encrypt0 object like this 🦋
- The encryption key to use is selected from the administrative keying material, as defined by the rekeying scheme used in the group.
- The plaintext is the actual data content of the current rekeying message.
- The Additional Authenticated Data (AAD) is empty unless separate documents profiling the use of the group rekeying scheme say otherwise.
- Since the KDC is the only sender of rekeying messages, the AEAD nonce can be computed as follows, where NONCE_SIZE is the size in bytes of the AEAD nonce. Separate documents profiling the use of the group rekeying scheme may define alternative ways to compute the AEAD nonce. The KDC considers the following values.
COUNT: as a 2-byte unsigned integer associated with the used encryption key. Its value is set to 0 when starting to perform a new group rekeying instance and is incremented after each use of the encryption key.NEW_NUM: as the version number of the new group keying material to distribute in this rekeying instance, left-padded with zeros to exactly NONCE_SIZE - 2 bytes.
Then, the KDC computes a Partial IV as the byte string concatenation of COUNT and NEW_NUM in this order. Finally, the AEAD nonce is computed as the XOR between the Base IV and the Partial IV.
In order to comply with the security requirements of AEAD encryption algorithms, the KDC MUST NOT reuse the same pair (AEAD encryption key, AEAD nonce). For example, this includes not using the same encryption key from the administrative keying material more than 2^16 times during the same rekeying instance. 😭
- The protected header of the COSE_Encrypt0 object MUST include the following parameters.
'alg': specifying the used encryption algorithm.'kid': specifying the identifier of the encryption key from the administrative keying material used to protect the current rekeying message.
- The unprotected header of the COSE_Encrypt0 object MUST include the
'Partial IV'parameter with the value of the Partial IV computed above.
In order to ensure source authentication, each rekeying message protected with the administrative keying material MUST be signed by the KDC. To this end, the KDC computes a countersignature of the COSE_Encrypt0 object, as described in Sections 3.2 and 3.3 of [RFC9338]. In particular, the following applies when computing the countersignature:
- The Countersign_structure contains the context text string "CounterSignature0".
- The private key of the KDC is used as the signing key.
- The payload is the ciphertext of the COSE_Encrypt0 object.
- The Additional Authenticated Data (AAD) is empty, unless otherwise specified by separate documents profiling a group rekeying scheme.
- The protected header of the signing object MUST include the parameter
'alg', which specifies the used signature algorithm.
If the source authentication of messages exchanged in the group is also ensured by means of signatures, then rekeying messages MUST be signed using the same signature algorithm and related parameters. Also, the KDC's authentication credential including the public key to use for signature verification MUST be provided in the Join Response through the 'kdc_cred' parameter, together with the corresponding proof-of-possession (PoP) evidence in the 'kdc_cred_verify' parameter. 🔑
If source authentication of messages exchanged in the group is not ensured by means of signatures, then the administrative keying material conveyed in the 'mgt_key_material' parameter of the Join Response sent by KDC (see Section 4.3.1) MUST also comprise a KDC's authentication credential including the public key to use for signature verification, together with the corresponding PoP evidence. Within the 'mgt_key_material' parameter, it is RECOMMENDED to specify this information by using the same format and encoding used for the parameters 'kdc_cred', 'kdc_nonce', and 'kdc_cred_verify' in the Join Response. It is up to separate documents profiling the use of the group rekeying scheme to specify such details.
After that, the KDC specifies the computed countersignature in the 'Countersignature0 version 2' header parameter of the COSE_Encrypt0 object.
Finally, the KDC specifies the COSE_Encrypt0 object as payload of a CoAP request, which is sent to the target group members as per the used message delivery method. 🎀
6.3. Misalignment of Group Keying Material
A group member can receive a message shortly after the group has been rekeyed and new keying material has been distributed by the KDC. In the following two cases, this may result in misaligned keying material between the group members. 🙈
In the first case, the sender protects a message using the old group keying material. However, the recipient receives the message after having received the new group keying material, hence it is not able to correctly process the message. A possible way to limit the impact of this issue is to preserve the old, retained group keying material for a maximum amount of time defined by the application, during which such group keying material is used solely for processing incoming messages. By doing so, the recipient can still temporarily process received messages also by using the old, retained group keying material. Note that a former (compromised) group member can take advantage of this by sending messages protected with the old, retained group keying material. Therefore, a conservative application policy should not admit the storage of old group keying material. Eventually, the sender will have obtained the new group keying material too and can possibly resend the message protected with such keying material. 🧚
In the second case, the sender protects a message using the new group keying material, but the recipient receives that message before having received the new group keying material. Therefore, the recipient will not be able to correctly process the message and hence will discard it. If the recipient receives the new group keying material shortly after that and the application at the sender endpoint performs retransmissions, the former will still be able to receive and correctly process the message. In any case, the recipient should actively ask the KDC for the latest group keying material according to an application-defined policy, for instance, after a given number of unsuccessfully decrypted incoming messages. 💀
7. Extended Scope Format ✨
This section defines an extended format of binary-encoded scope, which additionally specifies the semantics used to express the same access control information from the corresponding original scope. 🌸
As also discussed in Section 3.2, this enables a Resource Server to unambiguously process a received access token, also in case the Resource Server runs multiple applications or application profiles that involve different scope semantics. Main character energy, honestly 👑
The extended format is intended only for the 'scope' claim of access tokens for the cases where the claim takes a CBOR byte string as the value. That is, the extended format does not apply to the 'scope' parameter included in ACE messages, i.e., the Authorization Request and Authorization Response exchanged between the Client and the Authorization Server (see Sections 5.8.1 and 5.8.2 of [RFC9200]), the AS Request Creation Hints message from the Resource Server (see Section 5.3 of [RFC9200]), and the Introspection Response from the Authorization Server (see Section 5.9.2 of [RFC9200]). 🧐
The value of the 'scope' claim following the extended format is composed as follows. Given the original scope using semantics SEM and encoded as a CBOR byte string, the corresponding extended scope consists of the same CBOR byte string enclosed by a CBOR tag [RFC8949], whose tag number identifies the semantics SEM.
The resulting tagged CBOR byte string is used as the value of the 'scope' claim of the access token.
Figures 36 and 37 build on the examples in Section 3.1 and show the corresponding extended scopes. 🦋
;# include rfc9237
gname = tstr
permissions = uint .bits roles
roles = &(
Requester: 1,
Responder: 2,
Monitor: 3,
Verifier: 4
)
scope_entries = AIF-Generic<gname, permissions>
scope = bstr .cbor scope_entries
extended_scope = #6.<TAG_FOR_THIS_SEMANTICS>(scope)
TAG_FOR_THIS_SEMANTICS = uint
Figure 36: Example of Extended scope Using AIF gname = tstr
role = tstr
scope_entry = [ gname , ? ( role / [ 2*role ] ) ]
scope_entries = [ * scope_entry ]
scope = bstr .cbor scope_entries
extended_scope = #6.<TAG_FOR_THIS_SEMANTICS>(scope)
TAG_FOR_THIS_SEMANTICS = uint
Figure 37: Example of Extended scope Using the Textual Format,
with the Role Identifiers Encoded as Text StringsThe usage of the extended scope format is not limited to application profiles of this specification or to applications based on group communication. Rather, it is generally applicable to any application and application profile where access control information in the access token is expressed as a binary-encoded scope. Literally anything that uses binary scopes can use this, which is so cute 🍓
Applications and application profiles using the extended format of scope have to specify which CBOR tag from [CBOR.Tags] is used for identifying the scope semantics or to register a new CBOR tag if a suitable one does not exist already (REQ28). In case there is an already existing, suitable CBOR tag, a new CBOR tag should not be registered in order to avoid code point squatting. 🚫
If the binary-encoded scope uses semantics associated with a registered CoAP Content-Format [RFC7252] [CoAP.Content.Formats], then a suitable CBOR tag associated with that CoAP Content-Format would already be registered, as defined in Section 4.3 of [RFC9277].
This is especially relevant when the binary encoded scope uses AIF. That is, it is expected that the definition of an AIF-specific data model comes together with the registration of CoAP Content-Formats for the relevant combinations of its Toid and Tperm values. As discussed above, this yields the automatic registration of the CBOR tags associated with those CoAP Content-Formats. Everything clicks together, bestie 🌈💖
8. ACE Groupcomm Parameters ✨
okay so this section is where we list all the parameters we use in the second phase of key provisioning 🎀. That's the part after the exchange after the exchange of Token Transfer Request and Response (yes, it says "exchange" twice, bestie, we see the typo 💀). The table below sums everything up and gives you the CBOR map keys to use instead of the long descriptive names 🧚
Quick one: the media type "application/ace-groupcomm+cbor" MUST be used whenever these parameters are carried in their CBOR map entries. Non-negotiable, no cap 🔥
+=======================+======+========================+===========+
| Name | CBOR | CBOR Type | Reference |
| | Key | | |
+=======================+======+========================+===========+
| gid | 0 | array | RFC 9594 |
+-----------------------+------+------------------------+-----------+
| gname | 1 | array of tstr | RFC 9594 |
+-----------------------+------+------------------------+-----------+
| guri | 2 | array of tstr | RFC 9594 |
+-----------------------+------+------------------------+-----------+
| scope | 3 | bstr | RFC 9594 |
+-----------------------+------+------------------------+-----------+
| get_creds | 4 | Null or array | RFC 9594 |
+-----------------------+------+------------------------+-----------+
| client_cred | 5 | bstr | RFC 9594 |
+-----------------------+------+------------------------+-----------+
| cnonce | 6 | bstr | RFC 9594 |
+-----------------------+------+------------------------+-----------+
| gkty | 7 | int or tstr | RFC 9594 |
+-----------------------+------+------------------------+-----------+
| key | 8 | See the "ACE | RFC 9594 |
| | | Groupcomm Key | |
| | | Types" registry | |
+-----------------------+------+------------------------+-----------+
| num | 9 | int | RFC 9594 |
+-----------------------+------+------------------------+-----------+
| ace_groupcomm_profile | 10 | int | RFC 9594 |
+-----------------------+------+------------------------+-----------+
| exp | 11 | uint | RFC 9594 |
+-----------------------+------+------------------------+-----------+
| exi | 12 | uint | RFC 9594 |
+-----------------------+------+------------------------+-----------+
| creds | 13 | array | RFC 9594 |
+-----------------------+------+------------------------+-----------+
| peer_roles | 14 | array | RFC 9594 |
+-----------------------+------+------------------------+-----------+
| peer_identifiers | 15 | array | RFC 9594 |
+-----------------------+------+------------------------+-----------+
| group_policies | 16 | map | RFC 9594 |
+-----------------------+------+------------------------+-----------+
| kdc_cred | 17 | bstr | RFC 9594 |
+-----------------------+------+------------------------+-----------+
| kdc_nonce | 18 | bstr | RFC 9594 |
+-----------------------+------+------------------------+-----------+
| kdc_cred_verify | 19 | bstr | RFC 9594 |
+-----------------------+------+------------------------+-----------+
| rekeying_scheme | 20 | int | RFC 9594 |
+-----------------------+------+------------------------+-----------+
| client_cred_verify | 24 | bstr | RFC 9594 |
+-----------------------+------+------------------------+-----------+
| creds_repo | 25 | tstr | RFC 9594 |
+-----------------------+------+------------------------+-----------+
| control_uri | 26 | tstr | RFC 9594 |
+-----------------------+------+------------------------+-----------+
| mgt_key_material | 27 | bstr | RFC 9594 |
+-----------------------+------+------------------------+-----------+
| control_group_uri | 28 | tstr | RFC 9594 |
+-----------------------+------+------------------------+-----------+
| sign_info | 29 | Null or array | RFC 9594 |
+-----------------------+------+------------------------+-----------+
| kdcchallenge | 30 | bstr | RFC 9594 |
+-----------------------+------+------------------------+-----------+
Table 5: ACE Groupcomm ParametersThe KDC is expected to support all of the parameters above 🧠. But a Client can totally get away with supporting only a subset, depending on the roles it expects to take in the joined groups or on other conditions set out in application profiles of this specification 💅.
So the parameters get sorted by how much support Clients need to have 📋. A Client that supports a parameter is able to: i) use and specify it in a request message to the KDC; and ii) understand and process it if it's specified in a response message from the KDC. It is REQUIRED of application profiles of this specification to sort their newly defined parameters using this same categorization (REQ29) 🫶.
Note that whether a parameter actually gets used, and whether it shows up in a message, depends on the specific exchange, the specific Client and group involved, and what the used application profile of this specification defines 👑.
A Client MUST support the following parameters.
'scope''cnonce''gkty''key''num''exp''exi''gid''gname''guri''creds''peer_identifiers''ace_groupcomm_profile''control_uri''rekeying_scheme'
A Client SHOULD support the following parameter.
'get_creds': Not supporting this one would be the inconvenient and undesirable kind of drama 😭. The Client would i) not ask for the other group members' authentication credentials when joining the group (see Section 4.3.1.1); and ii) later on, as a group member, only retrieve the authentication credentials of all group members (see Section 4.4.2.1). Nobody wants that, periodt 🙈.
The following conditional parameters are only relevant if specific conditions hold 🦋. It is REQUIRED of application profiles of this specification to define whether Clients must, should, or may support these parameters, and under which circumstances (REQ30) ✨.
'client_cred'and'client_cred_verify': These are relevant for a Client that has an authentication credential to use in a joined group 🌸.'kdcchallenge': This is relevant for a Client that has an authentication credential to use in a joined group and that provides the access token to the KDC through a Token Transfer Request (see Section 3.3) 🔥.'creds_repo': This is relevant for a Client that has an authentication credential to use in a joined group and that makes it available from a key repository different from the KDC 🍓.'group_policies': This is relevant for a Client that is interested in the specific policies used in a group, but doesn't know them or can't become aware of them before joining that group 🧚.'peer_roles': This is relevant for a Client that has to know about the roles of other group members, especially when retrieving and handling their corresponding authentication credentials 💜.'kdc_nonce','kdc_cred', and'kdc_cred_verify': These are relevant for a Client that joins a group for which, as per the used application profile of this specification, the KDC has an associated authentication credential, and this is required for the correct group operation 👑.'mgt_key_material': This is relevant for a Client that supports an advanced rekeying scheme possibly used in the group, such as one based on one-to-many rekeying messages sent over IP multicast 🌈.'control_group_uri': This is relevant for a Client that also acts as a CoAP server supporting: i) hosting a dedicated resource for each group the Client is interested in being a part of; and ii) receiving one-to-many requests sent to those resources by the KDC (e.g., over IP multicast), targeting multiple members of the corresponding group. Examples of management operations the KDC can perform this way are evicting group members and running a group rekeying process through an advanced rekeying scheme, such as one based on one-to-many rekeying messages 🫧.
9. ACE Groupcomm Error Identifiers 💖
okay bestie, this part is all about the error codes the KDC can throw back at you 😭 this spec defines a bunch of values the KDC can use as error identifiers. they show up in error responses with Content-Format application/concise-problem-details+cbor, as values of the error-id field inside the Custom Problem Detail entry ace-groupcomm-error (see Section 4.1.2) 🎀
+=======+=============================================+
| Value | Description |
+=======+=============================================+
| 0 | Operation permitted only to group members |
+-------+---------------------------------------------+
| 1 | Request inconsistent with the current roles |
+-------+---------------------------------------------+
| 2 | Authentication credential incompatible with |
| | the group configuration |
+-------+---------------------------------------------+
| 3 | Invalid proof-of-possession evidence |
+-------+---------------------------------------------+
| 4 | No available individual keying material |
+-------+---------------------------------------------+
| 5 | Group membership terminated |
+-------+---------------------------------------------+
| 6 | Group deleted |
+-------+---------------------------------------------+
Table 6: ACE Groupcomm Error Identifiersokay so if a Client supports the problem-details format [RFC9290] ✨, and it supports the Custom Problem Detail entry ace-groupcomm-error defined in Section 4.1.2 of this document 💅, and it can actually understand the error in the error-id field, then the Client can use that info to figure out what to do next 🧚 if the Concise Problem Details data item in the error response has the detail entry and the Client supports it, that entry may give extra context 🌸
so here's the vibe: the following guidelines apply, and application profiles of this spec can define even more detailed actions for the Client to take when a specific error happens 🦋
- Error 0: the Client should stop sending that request to the KDC 🙅♀️ instead, it should first join the targeted group. if it hasn't already, this first needs the Client to get an appropriate access token that authorizes access to the group, and then give it to the KDC 🔑
- Error 1: the Client, as a group member, should rejoin the group with all the roles it needs to do the operation 👑 this might mean getting a new access token and giving it to the KDC first, if the current one doesn't let the Client take those roles in the group. for operations allowed for a Client that isn't a group member (like an external signature verifier), the Client should first get a new access token that also authorizes the missing roles 💜
- Error 2: the Client has to get or self-generate a different asymmetric key pair 🌈 it needs to match the public key algorithm and parameters used in the targeted group. after that, the Client should give the KDC its new authentication credential, which needs to fit the format used in the targeted group and include the new public key ✨
- Error 3: the Client should make sure it computes its proof-of-possession evidence by correctly using the parameters and procedures defined in the application profile of this spec that's being used 🫶 heads up, in an unattended setup it might not be possible for the Client to figure out the error on its own and pick a useful next step 🙈
- Error 4: the Client should wait for a certain (pre-configured) amount of time before trying to resend its request to the KDC ⏳
- Error 5: the Client may try joining the group again 🦋 this might mean getting a new access token and giving it to the KDC first, e.g., if the current access token has expired 🍓
- Error 6: the Client should clean up its state about the group, just like it would if it had left the group with no plans to rejoin 🧹
10. Security Considerations 🔐
ngl this section is serious, so let's get into it 🥺 security considerations are inherited from the ACE framework [RFC9200] and from the specific transport profile of ACE used between the Clients and the KDC, e.g., [RFC9202] and [RFC9203] 💜
when you use the problem-details format defined in [RFC9290] for error responses, the privacy and security considerations from Sections 4 and 5 of [RFC9290] also apply 🛡️
furthermore, the following security considerations apply, bestie 👀
10.1. Secure Communication in the Group 💬
when a group member gets a message from a certain sender for the first time since joining the group, it needs to have a mechanism in place to avoid replayed messages and to check their freshness 🕰️ for example, as described in Appendix B.1.2 of [RFC8613] or Section 10 of [GROUP-OSCORE]. this kind of mechanism also helps the recipient group member if it has rebooted and lost the security state it used to protect earlier group communications with that sender 🔄
okay real talk, the KDC holds a LOT of trust 😭 it's the one that generates and hands out the symmetric keying material used to protect communications in each of its groups. details depend on the specific communication and security protocols used in the group, but the KDC is in a position to decrypt messages exchanged in the group as if it were a group member too, as long as those messages are protected with commonly shared group keying material 🙀
so if the KDC gets compromised, the attacker is in the exact same position, which also means that:
- the attacker can generate and control new group keying material 🔑, so they could rekey the group and evict certain group members as part of a bigger attack 💀
- the attacker can actively take part in communications in a group, even without having been authorized to join it, and can let further unauthorized entities do the same 🚨
- the attacker can build wrong associations between node identifiers and group members' authentication credentials 🙅♀️
on the other hand, as long as the security protocol used in the group makes sure messages are source-authenticated (e.g., with signatures), the KDC can't impersonate group members, since it doesn't have their private keys 🫶 phew 🥹
further security considerations are specific to the communication and security protocols used in the group, so those protocols have to provide them, and the application profiles of this spec that use them need to complement them 📚
10.2. Update of Group Keying Material ✨
okay bestie, so the KDC can whip up brand new group keying material and hand it to the group members (that's rekeying 🔑) using whatever rekeying scheme the group runs, which we dig into in Section 6 💅
The KDC must renew the latest group keying material upon its expiration. Before then, the KDC MAY also renew the group keying material on a regular or periodical basis 🗓️
Unless an application profile of this specification defines otherwise, the KDC SHOULD renew the group keying material whenever group membership changes 🔄 There's a possible exception: the KDC may not rekey the group when a new member joins, if the application doesn't need backward security 🙈 And there's another one, which we'll talk about more later in this section: the KDC may rely on a rekeying policy that reasonably considers how fast group membership is changing and how long a group rekeying takes ⏱️
Since the minimum number of group members is one, the KDC SHOULD give even a Client that joins an empty group new keying material that was never used before in that group 🌱 Similarly, the KDC SHOULD also give new group keying material to a Client that ends up as the only member left after the other members leave 🦋
Quick reminder: the replay-message considerations from Section 10.1 still hold, even if the KDC rekeys the group on every single join 🫶 But here's the cute part: if the KDC renewed the group keying material when a member joined, and the gap between the end of that rekeying and the member's join is small enough, then that member is also on the safe side 🛡️ It won't accept replayed messages that were protected with the old keying material from before it joined 💜
Once a joining node gets the new, latest keying material through a Join Response from the KDC (see Section 4.3.1.1), it can read any message that was exchanged in the group and protected with that keying material 📬 This holds as long as the KDC gives the current group members the new, latest keying material before finishing the joining procedure ✅ The joining node still can't read messages protected with older keying material than the one in the Join Response, meaning anything with a strictly lower version number NUM 🙅♀️
A node that has left the group should not expect any of its outgoing messages to be processed successfully if other nodes in the group receive them after it leaves, since a group rekeying might happen before those messages arrive 👻
The KDC may enforce a rekeying policy that looks at the overall time a group rekeying takes, along with how fast group membership changes. That means the KDC may not rekey the group at each and every membership change, for example when members join and leave a lot and a rekeying takes too long 🐢 Instead, the KDC might rekey the group after a minimum number of members have joined or left within a given time interval, after a maximum amount of time since the last group rekeying was completed, or during predictable network inactivity periods 😴
Heads up though, bestie, this means the KDC isn't constantly preserving backward and forward security in the group 😬 Specifically:
- Newly joining group members would be able to access the keying material used before they joined, so they could read past group communications if they recorded old exchanged messages. This might still be fine for some applications, and in situations where the new members are freshly deployed through strictly controlled procedures 🧐
- Leaving group members would remain able to access upcoming group communications, since those are protected with the current keying material that hasn't been updated. This is usually a big no-no 🚫, especially if the leaving member is compromised or suspected to be, and it might impact or compromise the security properties of the protocols the group uses to protect messages exchanged among its members 💀
The KDC should renew the group keying material in case it has rebooted, even if it stores the whole group keying material in persistent storage 🔁 This assumes that the secure communication associations with the current group members, along with any administrative keying material needed to rekey the group, are also stored in persistent storage 💾
Now, if the KDC relies on Observe notifications to distribute the new group keying material, it would have lost all of its ongoing Observations with the group members after rebooting, and the group members would keep using the old group keying material 😱 So the KDC will rely on each group member asking for the new group keying material (see Sections 4.3.2.1 and 4.8.1.1), or perform a group rekeying by actively sending rekeying messages to group members as discussed in Section 6 📨
The KDC needs a mechanism to detect DoS attacks from nodes that repeatedly do things that might trigger a group rekeying 🚨 Those actions can include leaving and/or rejoining the group at high rates, or often asking the KDC for new individual keying material. In the end, the KDC can remove these nodes from the group and (temporarily) stop them from joining again 🚪
The KDC also needs a congestion control mechanism in place so it doesn't cause network congestion when it distributes new group keying material 🚦 For example, CoAP and Observe give guidance on such mechanisms: see Section 4.7 of [RFC7252] and Section 4.5.1 of [RFC7641] 📚
10.3. Block-Wise Considerations 🧱
If the Block-Wise CoAP options [RFC7959] are used and the keying material gets updated in the middle of a Block-Wise transfer, the sender of the blocks just switches to the updated group keying material and keeps the transfer going 🏃♀️ As long as both sides get the new group keying material, updating it mid-transfer won't cause any issues ✨ Otherwise, the sender will have to send the message again when it gets an error message from the recipient 🔂
Compared to a scenario where the transfer doesn't use Block-Wise, and depending on how fast the group keying material changes, the group members might eat up more network bandwidth by repeatedly resending the same blocks 📉 That could be a problem 😩
11. IANA Considerations 🏛️
Per this document, IANA has completed the following actions. 💅
11.1. Media Type Registrations 🎀
This specification registered the application/ace-groupcomm+cbor media type for messages of the protocols defined in this document that follow the ACE exchange and carry parameters encoded in CBOR 📦 This registration follows the procedures specified in [RFC6838] 🌷
Type name: application
Subtype name: ace-groupcomm+cbor
Required parameters: N/A
Optional parameters: N/A
Encoding considerations: Must be encoded as a CBOR map containing
the parameters defined in RFC 9594.
Security considerations: See Section 10 of RFC 9594.
Interoperability considerations: N/A
Published specification: RFC 9594
Applications that use this media type: The type is used by
Authorization Servers, Clients, and Resource Servers that support
the ACE groupcomm framework as specified in RFC 9594.
Fragment identifier considerations: N/A
Additional information: N/A
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)
Intended usage: COMMON
Restrictions on usage: None
Author/Change controller: IETF
Provisional registration: No11.2. CoAP Content-Formats 📝
IANA registered the following entry in the "CoAP Content-Formats" registry within the "CoRE Parameters" registry group 🌸
Content Type: application/ace-groupcomm+cbor
Content Coding: -
ID: 261
Reference: RFC 959411.3. OAuth Parameters 🔑
IANA registered the following entries in the "OAuth Parameters" registry, following the procedure specified in Section 11.2 of [RFC6749] 🧾
Name: sign_info
Parameter Usage Location: client-rs request, rs-client response
Change Controller: IETF
Reference: RFC 9594
Name: kdcchallenge
Parameter Usage Location: rs-client response
Change Controller: IETF
Reference: RFC 959411.4. OAuth Parameters CBOR Mappings 🗺️
IANA registered the following entries in the "OAuth Parameters CBOR Mappings" registry, following the procedure specified in Section 8.10 of [RFC9200] 🫧
Name: sign_info
CBOR Key: 45
Value Type: Null or array
Reference: RFC 9594
Name: kdcchallenge
CBOR Key: 46
Value Type: byte string
Reference: RFC 959411.5. Interface Description (if=) Link Target Attribute Values 🔗
IANA registered the following entry in the "Interface Description (if=) Link Target Attribute Values" registry within the "Constrained RESTful Environments (CoRE) Parameters" registry group 🍓
Value: ace.groups
Description: The KDC interface at the parent resource of group-
membership resources is used to retrieve names of security groups
using the ACE framework.
Reference: Section 4.1 of RFC 9594
Value: ace.group
Description: The KDC interface at a group-membership resource is
used to provision keying material and related information and
policies to members of the corresponding security group using the
ACE framework.
Reference: Section 4.1 of RFC 959411.6. Custom Problem Detail Keys Registry 🧚
IANA registered the following entry in the "Custom Problem Detail Keys" registry within the "Constrained RESTful Environments (CoRE) Parameters" registry group ✨
Key Value: 0
Name: ace-groupcomm-error
Brief Description: Carry RFC 9594 problem details in a Concise
Problem Details data item.
Change Controller: IETF
Reference: RFC 9594, Section 4.1.211.7. ACE Groupcomm Parameters ✨
Okay bestie, this one sets up the "ACE Groupcomm Parameters" IANA registry 🎀. It lives inside the "Authentication and Authorization for Constrained Environments (ACE)" registry group, so it's giving organized 💅.
Values in here fall under different registration policies, and some of those need Expert Review. For the guidelines, check Section 11.14 🫶.
The columns are:
Name: A descriptive name so the item is easier to reference 🏷️. The name MUST be unique. It is not used in the encoding.CBOR Key: The value used as the CBOR map key of the item. These values MUST be unique. The value can be a positive integer, a negative integer, or a text string. Different ranges use different registration policies [RFC8126]. Integer values from -256 to 255, as well as text strings of length 1, are designated as "Standards Action With Expert Review". Integer values from -65536 to -257, and from 256 to 65535, as well as text strings of length 2, are designated as "Specification Required". Integer values greater than 65535, as well as text strings of length greater than 2, are designated as "Expert Review". Integer values less than -65536 are marked as "Private Use" 🌈.CBOR Type: The CBOR type of the item, or a pointer to the registry that defines its type when that depends on another item 🧚.Reference: A pointer to the public specification for the item 📚.
This registry has been initially populated with the values in Table 5 💖.
11.8. ACE Groupcomm Key Types 🔑
This specification establishes the "ACE Groupcomm Key Types" IANA registry within the "Authentication and Authorization for Constrained Environments (ACE)" registry group. Iconic 👑.
Values here also follow different registration policies, and some need Expert Review. Guidelines are in Section 11.14 🫶.
The columns are:
Name: A descriptive name for easier reference. The name MUST be unique. It is not used in the encoding.Key Type Value: The value used to identify the keying material. These values MUST be unique. The value can be a positive integer, a negative integer, or a text string. Different ranges use different registration policies [RFC8126]. Integer values from -256 to 255, as well as text strings of length 1, are designated as "Standards Action With Expert Review". Integer values from -65536 to -257, and from 256 to 65535, as well as text strings of length 2, are designated as "Specification Required". Integer values greater than 65535, as well as text strings of length greater than 2, are designated as "Expert Review". Integer values less than -65536 are marked as "Private Use" 🌸.Profile: May contain one or more descriptive strings of application profiles to use with this item. The values should be taken from the "Name" column of the "ACE Groupcomm Profiles" registry 🦋.Description: A brief description of the keying material 💜.Reference: A pointer to the public specification for the format of the keying material, if one exists 📖.
This registry has been initially populated with the value in Table 1 ✨.
11.9. ACE Groupcomm Profiles 🎀
This specification establishes the "ACE Groupcomm Profiles" IANA registry within the "Authentication and Authorization for Constrained Environments (ACE)" registry group 🌷.
Values follow different registration policies, and some need Expert Review. See Section 11.14 for the guidelines 🫶.
The columns are:
Name: The name of the application profile 🏷️.Description: Text giving an overview of the application profile and the context it was developed for 🍓.CBOR Value: The CBOR abbreviation for the name of this application profile. These values MUST be unique. The value can be a positive integer or a negative integer. Different ranges use different registration policies [RFC8126]. Integer values from -256 to 255 are designated as "Standards Action With Expert Review". Integer values from -65536 to -257, and from 256 to 65535, are designated as "Specification Required". Integer values greater than 65535 are designated as "Expert Review". Integer values less than -65536 are marked as "Private Use" 🌈.Reference: A pointer to the public specification for this application profile, if one exists 📚.
This registry has been initially populated with the value in Table 2 💅.
11.10. ACE Groupcomm Policies 🛡️
This specification establishes the "ACE Groupcomm Policies" IANA registry within the "Authentication and Authorization for Constrained Environments (ACE)" registry group 💖.
Values here follow different registration policies, and some need Expert Review. Guidelines are in Section 11.14 🫶.
The columns are:
Name: The name of the group communication policy 🏷️.CBOR Label: The value used to identify this group communication policy. These values MUST be unique. The value can be a positive integer, a negative integer, or a text string. Different ranges use different registration policies [RFC8126]. Integer values from -256 to 255, as well as text strings of length 1, are designated as "Standards Action With Expert Review". Integer values from -65536 to -257, and from 256 to 65535, as well as text strings of length 2, are designated as "Specification Required". Integer values greater than 65535, as well as text strings of length greater than 2, are designated as "Expert Review". Integer values less than -65536 are marked as "Private Use" 🌈.CBOR Type: The CBOR type used to encode the value of this group communication policy 🧚.Description: A brief description of this group communication policy 💜.Reference: A pointer to the public specification for this group communication policy and its format, if one exists 📖.
This registry has been initially populated with the values in Table 3 ✨.
11.11. Sequence Number Synchronization Methods 🔄
This specification establishes the "Sequence Number Synchronization Methods" IANA registry within the "Authentication and Authorization for Constrained Environments (ACE)" registry group 🌸.
Values follow different registration policies, and some need Expert Review. Check Section 11.14 for the guidelines 🫶.
The columns are:
Name: The name of the sequence number synchronization method 🏷️.Value: The value used to identify this sequence number synchronization method. These values MUST be unique. The value can be a positive integer, a negative integer, or a text string. Different ranges use different registration policies [RFC8126]. Integer values from -256 to 255, as well as text strings of length 1, are designated as "Standards Action With Expert Review". Integer values from -65536 to -257, and from 256 to 65535, as well as text strings of length 2, are designated as "Specification Required". Integer values greater than 65535, as well as text strings of length greater than 2, are designated as "Expert Review". Integer values less than -65536 are marked as "Private Use" 🌈.Description: A brief description of this sequence number synchronization method 🦋.Reference: A pointer to the public specification describing the sequence number synchronization method 📚.
11.12. ACE Groupcomm Errors 🚨
This specification establishes the "ACE Groupcomm Errors" IANA registry within the "Authentication and Authorization for Constrained Environments (ACE)" registry group 🙈.
Values follow different registration policies, and some need Expert Review. Guidelines live in Section 11.14 🫶.
The columns are:
Value: The value used to identify the error. These values MUST be unique. The value can be a positive integer or a negative integer. Different ranges use different registration policies [RFC8126]. Integer values from -256 to 255 are designated as "Standards Action With Expert Review". Integer values from -65536 to -257, and from 256 to 65535, are designated as "Specification Required". Integer values greater than 65535 are designated as "Expert Review". Integer values less than -65536 are marked as "Private Use" 🌈.Description: A brief description of the error 💀.Reference: A pointer to the public specification defining the error, if one exists 📚.
This registry has been initially populated with the values in Table 6. The "Reference" column for all of these entries refers to this document 💜.
11.13. ACE Groupcomm Rekeying Schemes 🗝️
This specification establishes the "ACE Groupcomm Rekeying Schemes" IANA registry within the "Authentication and Authorization for Constrained Environments (ACE)" registry group 🎀.
Values follow different registration policies, and some need Expert Review. See Section 11.14 for the guidelines 🫶.
The columns are:
Value: The value used to identify the group rekeying scheme. These values MUST be unique. The value can be a positive integer or a negative integer. Different ranges use different registration policies [RFC8126]. Integer values from -256 to 255 are designated as "Standards Action With Expert Review". Integer values from -65536 to -257, and from 256 to 65535, are designated as "Specification Required". Integer values greater than 65535 are designated as "Expert Review". Integer values less than -65536 are marked as "Private Use" 🌈.Name: The name of the group rekeying scheme 🏷️.Description: A brief description of the group rekeying scheme 🍓.Reference: A pointer to the public specification defining the group rekeying scheme, if one exists 📖.
This registry has been initially populated with the value in Table 4 ✨.
11.14. Expert Review Instructions 🧐✨
Okay bestie, every IANA registry in this document is Expert Review 📋. This section is basically a vibe check for the experts, but they were picked for a reason 💅, so they get major latitude. Here's what they should be keeping an eye on:
- Point squatting should be discouraged 🙅♀️. Reviewers are encouraged to get enough info in each registration request to make sure the usage won't duplicate something already registered, and that the point is likely to actually get used in deployments. The zones tagged "Private Use" are for testing and closed environments, so code points in other ranges should not be assigned for testing 🧪.
- Specifications are required for the Standards Track range of point assignment 📜. Specifications should exist for Specification Required ranges, but early assignment before a specification is available is considered to be permissible 🌸. When specifications aren't provided, the description needs to have enough information to identify what the point is being used for 🔍.
- Experts should take expected usage of fields into account when approving point assignments 🎯. Having a range for Standards Track documents doesn't mean a Standards Track document can't have points assigned outside that range 🦋. The length of the encoded value should be weighed against how many code points of that length are left, the size of the device it'll be used on, and how many code points left encode to that size 📏.
12. References 📚
12.1. Normative References 🔗
[CBOR.Tags]IANA, "Concise Binary Object Representation (CBOR) Tags",<https://www.iana.org/assignments/cbor-tags/>.[CoAP.Content.Formats]IANA, "CoAP Content-Formats",<https://www.iana.org/assignments/core-parameters/>.[COSE.Algorithms]IANA, "COSE Algorithms",<https://www.iana.org/assignments/cose/>.[COSE.Header.Parameters]IANA, "COSE Header Parameters",<https://www.iana.org/assignments/cose/>.[COSE.Key.Types]IANA, "COSE Key Types",<https://www.iana.org/assignments/cose/>.[RFC2119]Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997,<https://www.rfc-editor.org/info/rfc2119>. 📖[RFC3629]Yergeau, F., "UTF-8, a transformation format of ISO 10646", STD 63, RFC 3629, DOI 10.17487/RFC3629, November 2003,<https://www.rfc-editor.org/info/rfc3629>.[RFC6690]Shelby, Z., "Constrained RESTful Environments (CoRE) Link Format", RFC 6690, DOI 10.17487/RFC6690, August 2012,<https://www.rfc-editor.org/info/rfc6690>.[RFC6749]Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", RFC 6749, DOI 10.17487/RFC6749, October 2012,<https://www.rfc-editor.org/info/rfc6749>.[RFC6838]Freed, N., Klensin, J., and T. Hansen, "Media Type Specifications and Registration Procedures", BCP 13, RFC 6838, DOI 10.17487/RFC6838, January 2013,<https://www.rfc-editor.org/info/rfc6838>.[RFC7252]Shelby, Z., Hartke, K., and C. Bormann, "The Constrained Application Protocol (CoAP)", RFC 7252, DOI 10.17487/RFC7252, June 2014,<https://www.rfc-editor.org/info/rfc7252>. 🌈[RFC7967]Bhattacharyya, A., Bandyopadhyay, S., Pal, A., and T. Bose, "Constrained Application Protocol (CoAP) Option for No Server Response", RFC 7967, DOI 10.17487/RFC7967, August 2016,<https://www.rfc-editor.org/info/rfc7967>.[RFC8126]Cotton, M., Leiba, B., and T. Narten, "Guidelines for Writing an IANA Considerations Section in RFCs", BCP 26, RFC 8126, DOI 10.17487/RFC8126, June 2017,<https://www.rfc-editor.org/info/rfc8126>.[RFC8174]Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, May 2017,<https://www.rfc-editor.org/info/rfc8174>. ✨[RFC8610]Birkholz, H., Vigano, C., and C. Bormann, "Concise Data Definition Language (CDDL): A Notational Convention to Express Concise Binary Object Representation (CBOR) and JSON Data Structures", RFC 8610, DOI 10.17487/RFC8610, June 2019,<https://www.rfc-editor.org/info/rfc8610>.[RFC8747]Jones, M., Seitz, L., Selander, G., Erdtman, S., and H. Tschofenig, "Proof-of-Possession Key Semantics for CBOR Web Tokens (CWTs)", RFC 8747, DOI 10.17487/RFC8747, March 2020,<https://www.rfc-editor.org/info/rfc8747>.[RFC8949]Bormann, C. and P. Hoffman, "Concise Binary Object Representation (CBOR)", STD 94, RFC 8949, DOI 10.17487/RFC8949, December 2020,<https://www.rfc-editor.org/info/rfc8949>. 🦋[RFC9052]Schaad, J., "CBOR Object Signing and Encryption (COSE): Structures and Process", STD 96, RFC 9052, DOI 10.17487/RFC9052, August 2022,<https://www.rfc-editor.org/info/rfc9052>.[RFC9053]Schaad, J., "CBOR Object Signing and Encryption (COSE): Initial Algorithms", RFC 9053, DOI 10.17487/RFC9053, August 2022,<https://www.rfc-editor.org/info/rfc9053>.[RFC9200]Seitz, L., Selander, G., Wahlstroem, E., Erdtman, S., and H. Tschofenig, "Authentication and Authorization for Constrained Environments Using the OAuth 2.0 Framework (ACE-OAuth)", RFC 9200, DOI 10.17487/RFC9200, August 2022,<https://www.rfc-editor.org/info/rfc9200>. 💜[RFC9237]Bormann, C., "An Authorization Information Format (AIF) for Authentication and Authorization for Constrained Environments (ACE)", RFC 9237, DOI 10.17487/RFC9237, August 2022,<https://www.rfc-editor.org/info/rfc9237>.[RFC9290]Fossati, T. and C. Bormann, "Concise Problem Details for Constrained Application Protocol (CoAP) APIs", RFC 9290, DOI 10.17487/RFC9290, October 2022,<https://www.rfc-editor.org/info/rfc9290>.[RFC9338]Schaad, J., "CBOR Object Signing and Encryption (COSE): Countersignatures", STD 96, RFC 9338, DOI 10.17487/RFC9338, December 2022,<https://www.rfc-editor.org/info/rfc9338>. 🎀
12.2. Informative References ✨
okay bestie, these are the informative refs, meaning the extra reading that backs up the spec 📚
[C509-CERT] Preuß Mattsson, J., Selander, G., Raza, S., Höglund, J., and M. Furuhed, "CBOR Encoded X.509 Certificates (C509 Certificates)", Work in Progress, Internet-Draft, draft-ietf-cose-cbor-encoded-cert-11, 8 July 2024, https://datatracker.ietf.org/doc/html/draft-ietf-cose-cbor-encoded-cert-11. 🎀
[CoAP-PUBSUB] Jimenez, J., Koster, M., and A. Keränen, "A publish-subscribe architecture for the Constrained Application Protocol (CoAP)", Work in Progress, Internet-Draft, draft-ietf-core-coap-pubsub-14, 18 April 2024, https://datatracker.ietf.org/doc/html/draft-ietf-core-coap-pubsub-14. 🦋
[GROUP-CoAP] Dijk, E., Wang, C., and M. Tiloca, "Group Communication for the Constrained Application Protocol (CoAP)", Work in Progress, Internet-Draft, draft-ietf-core-groupcomm-bis-11, 24 April 2024, https://datatracker.ietf.org/doc/html/draft-ietf-core-groupcomm-bis-11. 🌸
[GROUP-OSCORE] Tiloca, M., Selander, G., Palombini, F., Preuß Mattsson, J., and R. Höglund, "Group Object Security for Constrained RESTful Environments (Group OSCORE)", Work in Progress, Internet-Draft, draft-ietf-core-oscore-groupcomm-22, 28 August 2024, https://datatracker.ietf.org/doc/html/draft-ietf-core-oscore-groupcomm-22. 💜
[OSCORE-DISCOVERY] Tiloca, M., Amsüss, C., and P. Van der Stok, "Discovery of OSCORE Groups with the CoRE Resource Directory", Work in Progress, Internet-Draft, draft-tiloca-core-oscore-discovery-16, 4 September 2024, https://datatracker.ietf.org/doc/html/draft-tiloca-core-oscore-discovery-16. ✨
[RFC2093] Harney, H. and C. Muckenhirn, "Group Key Management Protocol (GKMP) Specification", RFC 2093, DOI 10.17487/RFC2093, July 1997, https://www.rfc-editor.org/info/rfc2093. 🧚
[RFC2094] Harney, H. and C. Muckenhirn, "Group Key Management Protocol (GKMP) Architecture", RFC 2094, DOI 10.17487/RFC2094, July 1997, https://www.rfc-editor.org/info/rfc2094. 🍓
[RFC2627] Wallner, D., Harder, E., and R. Agee, "Key Management for Multicast: Issues and Architectures", RFC 2627, DOI 10.17487/RFC2627, June 1999, https://www.rfc-editor.org/info/rfc2627. 🌈
[RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform Resource Identifier (URI): Generic Syntax", STD 66, RFC 3986, DOI 10.17487/RFC3986, January 2005, https://www.rfc-editor.org/info/rfc3986. 👑
[RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., Housley, R., and W. Polk, "Internet X.509 Public Key Infrastructure Certificate and Certificate Revocation List (CRL) Profile", RFC 5280, DOI 10.17487/RFC5280, May 2008, https://www.rfc-editor.org/info/rfc5280. 🔥
[RFC7519] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token (JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015, https://www.rfc-editor.org/info/rfc7519. 💅
[RFC7641] Hartke, K., "Observing Resources in the Constrained Application Protocol (CoAP)", RFC 7641, DOI 10.17487/RFC7641, September 2015, https://www.rfc-editor.org/info/rfc7641. 🫶
[RFC7959] Bormann, C. and Z. Shelby, Ed., "Block-Wise Transfers in the Constrained Application Protocol (CoAP)", RFC 7959, DOI 10.17487/RFC7959, August 2016, https://www.rfc-editor.org/info/rfc7959. 🦋
[RFC8259] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data Interchange Format", STD 90, RFC 8259, DOI 10.17487/RFC8259, December 2017, https://www.rfc-editor.org/info/rfc8259. 🌸
[RFC8392] Jones, M., Wahlstroem, E., Erdtman, S., and H. Tschofenig, "CBOR Web Token (CWT)", RFC 8392, DOI 10.17487/RFC8392, May 2018, https://www.rfc-editor.org/info/rfc8392. 💜
[RFC8613] Selander, G., Mattsson, J., Palombini, F., and L. Seitz, "Object Security for Constrained RESTful Environments (OSCORE)", RFC 8613, DOI 10.17487/RFC8613, July 2019, https://www.rfc-editor.org/info/rfc8613. ✨
[RFC9202] Gerdes, S., Bergmann, O., Bormann, C., Selander, G., and L. Seitz, "Datagram Transport Layer Security (DTLS) Profile for Authentication and Authorization for Constrained Environments (ACE)", RFC 9202, DOI 10.17487/RFC9202, August 2022, https://www.rfc-editor.org/info/rfc9202. 🧚
[RFC9203] Palombini, F., Seitz, L., Selander, G., and M. Gunnarsson, "The Object Security for Constrained RESTful Environments (OSCORE) Profile of the Authentication and Authorization for Constrained Environments (ACE) Framework", RFC 9203, DOI 10.17487/RFC9203, August 2022, https://www.rfc-editor.org/info/rfc9203. 🍓
[RFC9277] Richardson, M. and C. Bormann, "On Stable Storage for Items in Concise Binary Object Representation (CBOR)", RFC 9277, DOI 10.17487/RFC9277, August 2022, https://www.rfc-editor.org/info/rfc9277. 🌈
[RFC9431] Sengul, C. and A. Kirby, "Message Queuing Telemetry Transport (MQTT) and Transport Layer Security (TLS) Profile of Authentication and Authorization for Constrained Environments (ACE) Framework", RFC 9431, DOI 10.17487/RFC9431, July 2023, https://www.rfc-editor.org/info/rfc9431. 👑
Appendix A. Requirements for Application Profiles 🎀
This section lists the requirements for application profiles of this specification for the convenience of application profile designers. application profile designers, this one's for you 💖
A.1. Mandatory-to-Address Requirements ✨
REQ1 💖 Specify the format and encoding of scope. That means defining the full set of possible roles and their identifiers, plus how each one gets encoded in the scope entries, based on whichever scope format is used (see Section 3.1).
REQ2 🎀 If scope uses AIF, register its specific instance of "Toid" and "Tperm" as media type parameters, plus a matching Content-Format, following the guidelines in [RFC9237].
REQ3 🦋 If used, specify the acceptable values for the sign_alg parameter (see Section 3.3.1).
REQ4 🌸 If used, specify the acceptable values and structure for the sign_parameters parameter (see Section 3.3.1).
REQ5 🧚 If used, specify the acceptable values and structure for the sign_key_parameters parameter (see Section 3.3.1).
REQ6 💅 Specify the acceptable formats for authentication credentials and, if applicable, the acceptable values for the cred_fmt parameter (see Section 3.3.1).
REQ7 🫶 If the GROUPNAME value in the URI path and the group name in the access token scope (gname in Section 3.1) aren't required to match, specify the mechanism that maps the GROUPNAME value in the URI to the group name (see Section 4.1).
REQ8 👑 Define whether the KDC has an authentication credential that's needed for correct group operation, and whether that credential has to be provided through the kdc_cred parameter (see Sections 4.1 and 4.3.1).
REQ9 🔥 Specify if any part of the KDC interface defined in this document isn't supported by the KDC (see Section 4.1).
REQ10 🌈 Register a Resource Type for the group-membership resources. It's used to discover the correct URL for sending a Join Request to the KDC (see Section 4.1).
REQ11 ⭐ Define which specific actions (e.g., CoAP methods) are allowed on each resource accessible through the KDC interface. This depends on whether the Client is a current group member, the roles the Client is authorized to take per the access token it obtained (see Section 3.1), and the roles the Client has as a current group member.
REQ12 💜 Sort possible newly defined operations for Clients into primary operations that are expected to be minimally supported, and secondary operations. Also provide accompanying considerations (see Section 4.1.1).
REQ13 🍓 Specify the encoding of group identifiers (see Section 4.2.1).
REQ14 🦋 Specify the approaches used to compute and verify the PoP evidence to include in the client_cred_verify parameter, and which approach is used in which case (see Section 4.3.1).
REQ15 🌸 Specify how the nonce N_S is generated, if the access token isn't provided to the KDC through the Token Transfer Request sent to the /authz-info endpoint (e.g., the access token is instead transferred while a secure communication association is being set up).
REQ16 ✨ Define the initial value of the version number for the group keying material (see Section 4.3.1).
REQ17 💖 Specify the format of the group keying material conveyed in the key parameter (see Section 4.3.1).
REQ18 🎀 Specify the acceptable values of the gkty parameter (see Section 4.3.1). For each one, register a matching entry in the "ACE Groupcomm Key Types" IANA registry if it doesn't already exist there.
REQ19 🧚 Specify and register the application profile identifier (see Section 4.3.1).
REQ20 💅 If used, specify the format and default values of the entries of the CBOR map to include in the group_policies parameter (see Section 4.3.1).
REQ21 🫶 Specify the approaches used to compute and verify the PoP evidence to include in the kdc_cred_verify parameter, and which approach is used in which case (see Sections 4.3.1 and 4.5.1). If external signature verifiers are supported, specify how they provide a nonce to the KDC to be used when computing the PoP evidence (see Section 4.5.1).
REQ22 👑 Specify the communication protocol that group members use to talk to each other (e.g., CoAP for group communication).
REQ23 🔥 Specify the security protocol that group members use to protect group communication (e.g., Group OSCORE). This must provide encryption, integrity, and replay protection. No cap, this one is non-negotiable 🔒
REQ24 🌈 Specify how communication is secured between the Client and the KDC. Optionally, specify a transport profile of ACE [RFC9200] to use between the Client and the KDC (see Section 4.3.1.1).
REQ25 ⭐ Specify the format of the node identifiers of group members (see Sections 4.3.1 and 4.4.1).
REQ26 💜 Specify KDC policies for handling node identifiers that are included in the get_creds parameter but aren't associated with any current group member (see Section 4.4.1).
REQ27 🍓 Specify the format of (newly generated) individual keying material for group members, or of the information used to derive that keying material. Also specify the corresponding CBOR map key that has to be registered in the "ACE Groupcomm Parameters" registry (see Sections 4.8.1 and 4.8.2).
REQ28 🦋 Specify which CBOR tag identifies the semantics of binary scopes, or register a new CBOR tag if a suitable one doesn't exist yet (see Section 7).
REQ29 🌸 Sort newly defined parameters according to the same criteria as Section 8.
REQ30 ✨ Define whether Clients must, should, or may support the conditional parameters defined in Section 8, and under which circumstances.
A.2. Optional-to-Address Requirements 🎀
OPT1 💖 Optionally, if the textual format of scope is used, specify CBOR values to abbreviate the role identifiers in the group (see Section 3.1).
OPT2 🧚 Optionally, specify any additional parameters used in the exchange of Token Transfer Request and Response (see Section 3.3).
OPT3 💅 Optionally, specify the negotiation of parameter values for signature algorithm and signature keys, if the sign_info parameter isn't used (see Section 3.3).
OPT4 🫶 Optionally, specify possible or required payload formats for specific error cases (see Section 4.1.2).
OPT5 👑 Optionally, specify additional identifiers of error types as values of the error-id field within the Custom Problem Detail entry ace-groupcomm-error (see Section 4.1.2).
OPT6 🔥 Optionally, specify the encoding of the creds_repo parameter if the default one isn't used (see Section 4.3.1).
OPT7 🌈 Optionally, specify the functionalities implemented at the resource hosted by the Client at the URI indicated in the control_uri parameter, including the encoding of exchanged messages and other details (see Section 4.3.1).
OPT8 ⭐ Optionally, specify the behavior of the POST handler of group-membership resources for the case when it fails to retrieve an authentication credential for the specific Client (see Section 4.3.1).
OPT9 💜 Optionally, define a default group rekeying scheme to refer to in case the rekeying_scheme parameter isn't included in the Join Response (see Section 4.3.1).
OPT10 🍓 Optionally, specify the functionalities implemented at the resource hosted by the Client at the URI indicated in the control_group_uri parameter, including the encoding of exchanged messages and other details (see Section 4.3.1).
OPT11 🦋 Optionally, specify policies that instruct Clients to retain messages, and for how long, if those messages aren't successfully decrypted (see Section 4.8.1.1). This makes it possible for Clients to decrypt such messages after obtaining updated keying material.
OPT12 🌸 Optionally, specify that the KDC performs a group rekeying when it receives a Key Renewal Request, together with or instead of renewing individual keying material (see Section 4.8.2.1).
OPT13 ✨ Optionally, specify how the identifier of a group member's authentication credential is included in requests sent to other group members (see Section 4.9.1.1).
OPT14 💖 Optionally, specify additional information to include in rekeying messages for the "Point-to-Point" group rekeying scheme (see Section 6).
Appendix B. Extensibility for Future COSE Algorithms 🌈
As defined in Section 8.1 of [RFC9053], future algorithms can be registered in the "COSE Algorithms" registry [COSE.Algorithms] as specifying none or multiple COSE capabilities. Iykyk, this is how new algorithms get a seat at the table 🪑
To let future registered algorithms be used seamlessly, this section defines a general, agile format for each sign_info_entry of the sign_info parameter in the Token Transfer Response (see Section 3.3.1). 💅
If any of the currently registered COSE algorithms are considered, using this general format yields the same structure of sign_info_entry defined in this document, so backward compatibility is preserved 🫶
B.1. Format of 'sign_info_entry' 🎀
The format of each sign_info_entry (see Section 3.3.1) is generalized as follows.
sign_parametersincludes N >= 0 elements, each of which is a COSE capability of the signature algorithm indicated insign_alg.
In particular, sign_parameters has the same format and value as the COSE capabilities array for the signature algorithm indicated in sign_alg, as specified for that algorithm in the "Capabilities" column of the "COSE Algorithms" registry [COSE.Algorithms].
sign_key_parametersis replaced by N elementssign_capab, each of which is a CBOR array.
The i-th sign_capab array (i = 0, ..., N-1) is the array of COSE capabilities for the algorithm capability specified in sign_parameters[i].
In particular, each sign_capab array has the same format and value as the COSE capabilities array for the algorithm capability specified in sign_parameters[i].
Such a COSE capabilities array is currently defined for the algorithm capability COSE key type in the "Capabilities" column of the "COSE Key Types" registry [COSE.Key.Types].
sign_info_entry =
[
id : gname / [+ gname],
sign_alg : int / tstr,
sign_parameters : [* alg_capab : any],
* sign_capab : [* capab : any],
cred_fmt : int / null
]
gname = tstrFigure 38: 'sign_info_entry' with a General Format 🧚
Acknowledgments ✨
Huge thank-you to these amazing people who helped shape this document 🫶: Christian Amsüss, Carsten Bormann, Roman Danyliw, Martin Duke, Thomas Fossati, Vidhi Goel, Rikard Höglund, Ben Kaduk, Erik Kline, Warren Kumari, Watson Ladd, Daniel Migault, John Preuß Mattsson, Zaheduzzaman Sarker, Jim Schaad, Ludwig Seitz, Göran Selander, Cigdem Sengul, Dave Thaler, Henry Thompson, Peter van der Stok, and Paul Wouters 💖.
The work on this document was partly supported by Sweden's Innovation Agency VINNOVA and the Celtic-Next project CRITISEC, by the H2020 project SIFIS-Home (Grant agreement 952652), and by the EIT-Digital High Impact Initiative ACTIVE 🌈💜.
Authors' Addresses 🎀
Francesca Palombini Ericsson AB Torshamnsgatan 23 SE-164 40 Kista Sweden Email: francesca.palombini@ericsson.com
Marco Tiloca RISE AB Isafjordsgatan 22 SE-164 40 Kista Sweden Email: marco.tiloca@ri.se 🦋
📦 where this page comes from
- ietf: rfc9594 2024-09
- 💖 girlified by claude-haiku-5-5 on : a language model's rewrite of the original, under its terms