| Internet-Draft | Key Provisioning for Group Communication | September 2020 |
| Palombini & Tiloca | Expires March 8, 2021 | [Page] |
This document defines message formats and procedures for requesting and distributing group keying material using the ACE framework, to protect communications between group members.¶
This note is to be removed before publishing as an RFC.¶
Source for this draft and an issue tracker can be found at https://github.com/ace-wg/ace-key-groupcomm.¶
This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79.¶
Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet-Drafts is at https://datatracker.ietf.org/drafts/current/.¶
Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress."¶
This Internet-Draft will expire on March 8, 2021.¶
Copyright (c) 2020 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 Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License.¶
This document expands the ACE framework [I-D.ietf-ace-oauth-authz] to define the message exchanges used to request, distribute and renew the keying material in a group communication scenario, e.g. based on multicast [I-D.ietf-core-groupcomm-bis] or on publishing-subscribing [I-D.ietf-core-coap-pubsub]. The ACE framework is based on CBOR [RFC7049], so CBOR is the format used in this specification. However, using JSON [RFC8259] instead of CBOR is possible, using the conversion method specified in Sections 4.1 and 4.2 of [RFC7049].¶
Profiles that use group communication can build on this document, by defining a number of details such as the exact group communication protocol and security protocols used. The specific list of details a profile needs to define is shown in Appendix A.¶
If the application requires backward and forward security, new keying material is generated and distributed to the group upon membership changes. A key management scheme performs the actual distribution of the new keying material to the group. In particular, the key management scheme rekeys the current group members when a new node joins the group, and the remaining group members when a node leaves the group. Rekeying mechanisms can be based on [RFC2093], [RFC2094] and [RFC2627].¶
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.¶
Readers are expected to be familiar with the terms and concepts described in [I-D.ietf-ace-oauth-authz][I-D.ietf-cose-rfc8152bis-struct][I-D.ietf-cose-rfc8152bis-algs], such as Authorization Server (AS) and Resource Server (RS).¶
This document uses names or identifiers for groups and nodes. Their different meanings are summarized here:¶
This document additionally uses the following terminology:¶
The full procedure can be separated in two phases: the first follows the ACE framework, between Client, AS and KDC. The second part is the key distribution between Client and KDC. After the two phases the Client is able to participate in the group communication, via a Dispatcher entity.¶
+------------+ +-----------+
| AS | | KDC |
| | .-------->| |
+------------+ / +-----------+
^ /
| /
v / +-----------+
+------------+ / +------------+ |+-----------+
| Client |<-' | Dispatcher | ||+-----------+
| |<-------->| |<------->|| Group |
+------------+ +------------+ +| members |
+-----------+
The following participants (see Figure 1) take part in the authorization and key distribution.¶
This document specifies a mechanism for:¶
Figure 2 provides a high level overview of the message flow for a node joining a group communication setting, which can be expanded as follows.¶
C AS KDC Group
| | | Member
/ | | | |
| | Authorization Request | | |
Defined | |-------------------------->| | |
in the | | | | |
ACE | | Authorization Response | | |
framework | |<--------------------------| | |
| | | |
\ |---------- Token Post --------->| |
| | |
|------- Joining Request ------->| |
| | |
|<------ Joining Response -------|-- Group Rekeying -->|
| | |
| Dispatcher |
| | |
|<===== Secure group communication =======|===========>|
| | |
This section describes in detail the format of messages exchanged by the participants when a node requests access to a given group. This exchange is based on ACE [I-D.ietf-ace-oauth-authz].¶
As defined in [I-D.ietf-ace-oauth-authz], the Client requests from the AS an authorization to join the group through the KDC (see Section 3.1). If the request is approved and authorization is granted, the AS provides the Client with a proof-of-possession access token and parameters to securely communicate with the KDC (see Section 3.2).¶
Communications between the Client and the AS MUST be secured, as defined by the transport profile of ACE used. The Content-Format used in the message depends on the used transport profile of ACE. For example, this 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 [I-D.ietf-ace-oauth-authz]).¶
Figure 3 gives an overview of the exchange described above.¶
Client AS KDC | | | |---- Authorization Request: POST /token ------>| | | | | |<--- Authorization Response: 2.01 (Created) ---| | | | | |----- POST Token: POST /authz-info --------------->| | |
The Client sends a CoAP POST request including the access token to the KDC, as specified in Section 5.8.1 of [I-D.ietf-ace-oauth-authz]. If the specific transport profile of ACE defines it, the Client MAY use a different endpoint than /authz-info at the KDC to post the access token to.¶
Optionally, the Client might want to request encoding information about the public keys in the group, used for source authentication, as well as any other group parameters. The joining node MAY ask for this information from the KDC in the same message it uses to POST the token to the RS.¶
The payload of the message MUST be formatted as a CBOR map including the access token.¶
Additionally, the CoAP POST request MAY contain the following parameter, which, if included, MUST have the corresponding values:¶
Alternatively, the joining node may retrieve this information by other means.¶
After successful verification, the Client is authorized to receive the group keying material from the KDC and join the group.¶
The KDC replies to the Client with a 2.01 (Created) response, using Content-Format "application/ace+cbor" defined in Section 8.14 of [I-D.ietf-ace-oauth-authz].¶
The payload of the 2.01 response is a CBOR map. If the access token contains a role that requires the Client to send its own public key to the KDC when joining the group, the CBOR map MUST include the parameter 'kdcchallenge' defined in Section Section 3.3.2, specifying a dedicated challenge N_S generated by the KDC. The Client uses this challenge to prove possession of its own private key (see the 'client_cred_verify' parameter in Section 4). Note that the payload format of the response deviates from the one defined in the ACE framework (see Section 5.8.1 of [I-D.ietf-ace-oauth-authz]), which has no payload.¶
The KDC MUST store the 'kdcchallenge' value associated to the Client at least until it receives a join request from it (see Section 4.3), to be able to verify the proof of possession. The same challenge MAY be reused several times by the Client, to generate new proof of possessions, e.g. in case of update of the public key, or to join a different group with a different signing key, so it is RECOMMENDED that the KDC keeps storing the 'kdcchallenge' after the first join is processed as well. If the KDC has already discarded the 'kdcchallenge', that will trigger an error response with a newly generated 'kdcchallenge' that the client can use to restart the join process, as specified in Section 4.3.¶
If 'sign_info' is included in the request, the KDC MAY include the 'sign_info' parameter defined in Section 3.3.1, with the same encoding. Note that the field 'id' takes the value of the group name for which the 'sign_info_entry' applies to.¶
Note that the CBOR map specified as payload of the 2.01 (Created) response may include further parameters, e.g. according to the signalled transport profile of ACE.¶
Application profiles of this specification MAY define alternative specific negotiations of parameter values for signature algorithm and signature keys, if 'sign_info' is not used (OPT2).¶
The 'sign_info' parameter is an OPTIONAL parameter of the Token Post response message defined in Section 5.1.2. of [I-D.ietf-ace-oauth-authz]. This parameter contains information and parameters about the signature algorithm and the public keys to be used between the Client and the RS. Its exact content is application specific.¶
In this specification and in application profiles building on it, this parameter is used to ask and retrieve from the KDC information about the signature algorithm and related parameters used in the group.¶
When used in the request, the 'sign_info' encodes the CBOR simple value Null, to require information and parameters on the signature algorithm and on the public keys used.¶
The CDDL notation [RFC8610] of the 'sign_info' parameter formatted as in the request is given below.¶
sign_info_req = nil¶
The 'sign_info' parameter of the 2.01 (Created) response is a CBOR array of one or more elements. The number of elements is at most the number of groups the client has been authorized to join. Each element contains information about signing parameters and keys for one or more group or topic and is formatted as follows.¶
The CDDL notation [RFC8610] of the 'sign_info' parameter formatted as in the response is given below.¶
sign_info_res = [ + sign_info_entry ]
sign_info_entry =
[
id : gname / [ + gname ],
sign_alg : int / tstr,
sign_parameters : [ any ],
sign_key_parameters : [ any ],
pub_key_enc = int / nil
]
gname = tstr
¶
The 'kdcchallenge' parameter is an OPTIONAL parameter of the Token Post response message defined in Section 5.1.2. of [I-D.ietf-ace-oauth-authz]. This parameter contains a challenge generated by the KDC and provided to the Client. The Client may use this challenge to prove possession of its own private key in the Joining Request (see the 'client_cred_verify' parameter in Section 4).¶
This section defines the interface available at the KDC. Moreover, this section specifies how the clients can use this interface to join a group, leave a group, retrieve the group policies or the new keying material.¶
During the first exchange with the KDC ("Joining") after posting the Token, the Client sends a request to the KDC, specifying the group it wishes to join (see Section 4.3). Then, the KDC verifies the access token and that the Client is authorized to join that group. If so, it provides the Client with the keying material to securely communicate with the other members of the group. Whenever used, the Content-Format in messages containing a payload is set to application/ace-groupcomm+cbor, as defined in Section 8.2.¶
When the Client is already a group member, the Client can use the interface at the KDC to perform the following actions:¶
Upon receiving a request from a Client, the KDC MUST check that it is storing a valid access token from that Client for the group name associated to the endpoint. If that is not the case, i.e. the KDC does not store a valid access token or this is not valid for that Client for the group name, the KDC MUST respond to the Client with a 4.01 (Unauthorized) error message.¶
The KDC is configured with the following resources. Note that the root url-path "ace-group" given here are default names: implementations are not required to use these names, and can define their own instead. Each application profile of this specification MUST register a Resource Type for the root url-path (REQ7a), and that Resource Type can be used to discover the correct url to access at the KDC. This Resource Type can also be used at the GROUPNAME sub-resource, to indicate different application profiles for different groups. The Interface Description (if=) Link Target Attribute value ace.group is registered (Section 8.10) and can be used to describe this interface.¶
The details for the handlers of each resource are given in the following sections. These endpoints are used to perform the operations introduced in Section 4.¶
This resource implements a FETCH handler.¶
The FETCH handler receives group identifiers and returns the corresponding group names and GROUPNAME URIs.¶
The handler expects a request with payload formatted as a CBOR map. The payload of this request is a CBOR Map that MUST contain the following fields:¶
The handler identifies the groups that are secured by the keying material identified by those group identifiers.¶
Then, the handler returns a 2.05 (Content) message response with payload formatted as a CBOR map that MUST contain the following fields:¶
If the KDC does not find any group associated with the specified group identifiers, the handler returns a response with payload formatted as a CBOR byte string of zero length.¶
This resource implements GET and POST handlers.¶
The POST handler adds the public key of the client to the list of the group members' public keys and returns the symmetric group keying material for the group identified by "GROUPNAME". Note that the group joining exchange is done by the client via this operation, as described in Section 4.3.¶
The handler expects a request with payload formatted as a CBOR map which MAY contain the following fields, which, if included, MUST have the corresponding values:¶
'get_pub_keys', if the Client wishes to receive the public keys of the other nodes in the group from the KDC. This parameter may be present if the KDC stores the public keys of the nodes in the group and distributes them to the Client; it is useless to have here if the set of public keys of the members of the group is known in another way, e.g. it was provided by the AS. Note that including this parameter may result in a large message size for the following response, which can be inconvenient for resource-constrained devices. The parameter's value is a non-empty CBOR array containing two CBOR arrays:¶
The CDDL definition [RFC8610] of 'get_pub_keys' is given in Figure 6 using as example encoding: node identifier encoded as byte string, role identifier as text string, and combination of roles encoded as a CBOR array of roles. Note that the array ids is empty for this handler, but is not necessarily empty for the value of "get_pub_keys" received by the handler of FETCH to ace-group/GROUPNAME/pub-key (see Section 4.1.3.1).¶
id = bstr role = tstr comb_role = [ 2*role ] get_pub_keys = [ [ *(role / comb_role) ], [ *id ] ]
'client_cred_verify', encoded as a CBOR byte string. This parameter MUST be present if the 'client_cred' parameter is present and no public key associated to the client's token can be retrieved for that group. This parameter contains a signature computed by the Client over the scope concatenated with N_S concatenated with N_C, where:¶
If the token was not posted (e.g. if it is used directly to validate TLS instead), it is REQUIRED of the specific profile to define how the challenge N_S is generated (REQ17). The Client computes the signature by using its own private key, whose corresponding public key is either directly specified in the 'client_cred' parameter or included in the certificate specified in the 'client_cred' parameter.¶
The handler extracts the granted scope from the access token, and checks the requested one against the token one. If this join message does not include a 'scope' field, the KDC is expected to understand which group and role the Client is requesting (e.g. there is only one the Client has been granted). If the KDC can not recognize which scope the Client is requesting, it MUST respond with a 4.00 (Bad Request) error message.¶
The handler verifies that the group name of the /ace-group/GROUPNAME path is a subset of the 'scope' stored in the access token associated to this client. If verification fails, the KDC MUST respond with a 4.01 (Unauthorized) error message. The KDC MAY respond with an AS Request Creation Hints, as defined in Section 5.1.2 of [I-D.ietf-ace-oauth-authz]. Note that in this case, the content format MUST be set to application/ace+cbor.¶
If the request is not formatted correctly (i.e. required fields non received or received with incorrect format), the handler MUST respond with a 4.00 (Bad Request) error message. The response MAY contain a CBOR map in the payload with ace+cbor format, e.g. it could send back 'sign_info_res' with 'pub_key_enc' set to Null if the Client sent its own public key and the KDC is not set to store public keys of the group members. If the request contained unknown or non-expected fields present, the handler MUST silently drop them and continue processing. Application profiles MAY define optional or mandatory payload formats for specific error cases (OPT6).¶
If the KDC stores the group members' public keys, the handler checks if one is included in the 'client_cred' field, retrieves it and associates it to the access token received, after verifications succeeded. In particular, the KDC verifies:¶
If that cannot be verified, it is RECOMMENDED that the handler stops the process and responds with a 4.00 (Bad Request) error message. Applications profiles MAY define alternatives (OPT5).¶
If one public key is already associated to the access token and to that group, but the 'client_cred' is populated with a different public key, the handler MUST delete the previous one and replace it with this one, after verifying the points above.¶
If no public key is included in the 'client_cred' field, the handler checks if one public key is already associated to the access token received (see Section 4.3 for an example) and to the group identified by "GROUPNAME". If that is not the case, the handler responds with a 4.00 Bad Request error response.¶
If the token was posted but the KDC cannot retrieve the 'kdcchallenge' associated to this Client (see Section 3.3), the KDC MUST respond with a 4.00 Bad Request error response, including a newly generated 'kdcchallenge' in a CBOR map in the payload. This error response MUST also have Content-Format "application/ace+cbor".¶
If all verifications succeed, the handler:¶
If the KDC manages public keys for group members:¶
The response message also contains the URI path to the sub-resource created for that node in a Location-Path CoAP option. The payload of the response is formatted as a CBOR map which MUST contain the following fields and values:¶
The exact format of the 'key' value MUST be defined in applications of this specification (REQ7), as well as accepted values of 'gkty' by the application (REQ8). Additionally, documents specifying the key format MUST register it in the "ACE Groupcomm Key" registry defined in Section 8.6, including its name, type and application profile to be used with.¶
+----------+----------------+---------+-------------------------+ | Name | Key Type Value | Profile | Description | +----------+----------------+---------+-------------------------+ | Reserved | 0 | | This value is reserved | +----------+----------------+---------+-------------------------+
The response SHOULD contain the following parameter:¶
Optionally, the response MAY contain the following parameters, which, if included, MUST have the corresponding values:¶
+--------------+-------+----------|--------------------|------------+ | Name | CBOR | CBOR | Description | Reference | | | label | type | | | |--------------+-------+----------|--------------------|------------| | Sequence | TBD1 | tstr/int | Method for a re- | [[this | | Number | | | cipient node to | document]] | | Synchroniza- | | | synchronize with | | | tion Method | | | sequence numbers | | | | | | of a sender node. | | | | | | Its value is taken | | | | | | from the 'Value' | | | | | | column of the | | | | | | Sequence Number | | | | | | Synchronization | | | | | | Method registry | | | | | | | | | Key Update | TBD2 | int | Polling interval | [[this | | Check | | | in seconds, to | document]] | | Interval | | | check for new | | | | | | keying material at | | | | | | the KDC | | | | | | | | | Expiration | TBD3 | uint | Number of seconds | [[this | | Delta | | | from 'exp' until | document]] | | | | | the specified UTC | | | | | | date/time after | | | | | | which group members| | | | | | MUST stop using the| | | | | | keying material to | | | | | | verify incoming | | | | | | messages. | | +--------------+-------+----------|--------------------|------------+
Specific application profiles that build on this document MUST specify the communication protocol that members of the group use to communicate with each other (REQ10) and how exactly the keying material is used to protect the group communication (REQ11).¶
The GET handler returns the symmetric group keying material for the group identified by "GROUPNAME".¶
The handler expects a GET request.¶
The handler verifies that the group name of the /ace-group/GROUPNAME path is a subset of the 'scope' stored in the access token associated to this client. If verification fails, the KDC MUST respond with a 4.01 (Unauthorized) error message. The KDC MAY respond with an AS Request Creation Hints, as defined in Section 5.1.2 of [I-D.ietf-ace-oauth-authz]. Note that in this case, the content format MUST be set to application/ace+cbor.¶
Additionally, the handler verifies that the node is a current member of the group. If verification fails, the KDC MUST respond with a 4.00 (Bad Request) error message.¶
If verification succeeds, the handler returns a 2.05 (Content) message containing the symmetric group keying material. The payload of the response is formatted as a CBOR map which MUST contain the parameters 'gkty','key' and 'num' specified in Section 4.1.2.1.¶
The payload MAY also include the parameters 'ace-groupcomm-profile', 'exp', and 'mgt_key_material' parameters specified in Section 4.1.2.1.¶
If the KDC does not maintain public keys for the group, the handler for any request on this resource returns a 4.05 (Method Not Allowed) error message. If it does, the rest of this section applies.¶
This resource implements GET and FETCH handlers.¶
The FETCH handler receives identifiers of group members for the group identified by "GROUPNAME" and returns the public keys of such group members.¶
The handler expects a request with payload formatted as a CBOR map. The payload of this request is a CBOR Map that MUST contain the following fields:¶
'get_pub_keys', whose value is encoded as in Section 4.1.2.1 with the following modification:¶
The specific format of public keys as well as identifiers, roles and combination of roles of group members MUST be specified by the application profile (OPT1, REQ2, REQ9).¶
The handler verifies that the group name of the /ace-group/GROUPNAME path is a subset of the 'scope' stored in the access token associated to this client. If verification fails, the KDC MUST respond with a 4.01 (Unauthorized) error message.¶
If verification succeeds, the handler identifies the public keys of the current group members for which either:¶
Then, the handler returns a 2.05 (Content) message response with payload formatted as a CBOR map, containing only the 'pub_keys' and 'peer_roles' parameters from Section 4.1.2.1. In particular, 'pub_keys' encodes the list of public keys of those group members including the respective member identifiers, while 'peer_roles' encodes their respective role (or CBOR array of roles) in the group. The specific format of public keys as well as of identifiers of group members is specified by the application profile (OPT1, REQ9).¶
If the KDC does not store any public key associated with the specified member identifiers, the handler returns a response with payload formatted as a CBOR byte string of zero length.¶
The handler MAY enforce one of the following policies, in order to handle possible identifiers that are included in the 'get_pub_keys' parameter of the request but are not associated to any current group member. Such a policy MUST be specified by the application profile (REQ13)¶
Note that this resource handler 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 verifications on the group messages may be allowed to access this resource, if the application needs it.¶
The handler expects a GET request.¶
The handler verifies that the group name of the /ace-group/GROUPNAME path is a subset of the 'scope' stored in the access token associated to this client. If verification fails, the KDC MUST respond with a 4.01 (Unauthorized) error message.¶
If verification succeeds, the handler returns a 2.05 (Content) message containing the public keys of all the current group members, for the group identified by "GROUPNAME". The payload of the response is formatted as a CBOR map, containing only the 'pub_keys' and 'peer_roles' parameters from Section 4.1.2.1. In particular, 'pub_keys' encodes the list of public keys of those group members including the respective member identifiers, while 'peer_roles' encodes their respective role (or CBOR array of roles) in the group.¶
If the KDC does not store any public key for the group, the handler returns a response with payload formatted as a CBOR byte string of zero length. The specific format of public keys as well as of identifiers of group members is specified by the application profile (OPT1, REQ9).¶
Note that this resource handler 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 verifications on the group messages may be allowed to access this resource, if the application needs it.¶
This resource implements a GET handler.¶
The handler expects a GET request.¶
The handler verifies that the group name of the /ace-group/GROUPNAME path is a subset of the 'scope' stored in the access token associated to this client. If verification fails, the KDC MUST respond with a 4.01 (Unauthorized) error message.¶
Additionally, the handler verifies that the node is a current member of the group. If verification fails, the KDC MUST respond with a 4.00 (Bad Request) error message.¶
If verification succeeds, the handler returns a 2.05 (Content) message 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 parameter 'group_policies' defined in Section 4.1.2.1 and specifying the current policies in the group. If the KDC does not store any policy, the payload is formatted as a zero-length CBOR byte string.¶
The specific format and meaning of group policies MUST be specified in the application profile (REQ14).¶
This resource implements GET, PUT and DELETE handlers.¶
The PUT handler is used to get the KDC to produce and return individual keying material to protect outgoing messages for the node (identified by "NODENAME") for the group identified by "GROUPNAME". Application profiles MAY also use this handler to rekey the whole group. (OPT8) It is up to the application profiles to specify if this handler supports renewal of individual keying material, renewal of the group keying material or both.¶
The handler expects a request with empty payload.¶
The handler verifies that the group name of the /ace-group/GROUPNAME path is a subset of the 'scope' stored in the access token associated to this client, identified by "NODENAME". If verification fails, the KDC MUST respond with a 4.01 (Unauthorized) error message.¶
Additionally, the handler verifies that the node is a current member of the group. If verification fails, the KDC MUST respond with a 4.00 (Bad Request) error message.¶
If verification succeeds, the handler returns a 2.05 (Content) message containing newly-generated keying material for the Client, and/or, if the application profiles requires it (OPT8), starts the comprete group rekeying. The payload of the response is formatted as a CBOR map. The specific format of newly-generated individual keying material for group members, or of the information to derive it, and corresponding CBOR label, MUST be specified in the application profile (REQ15) and registered in Section 8.5.¶
The handler expects a GET request.¶
The handler verifies that the group name of the /ace-group/GROUPNAME path is a subset of the 'scope' stored in the access token associated to this client, identified by "NODENAME". If verification fails, the KDC MUST respond with a 4.01 (Unauthorized) error message.¶
The handler also verifies that the node sending the request and the node name used in the Uri-Path match. If that is not the case, the handler responds with a 4.01 (Unauthorized) error response.¶
Additionally, the handler verifies that the node is a current member of the group. If verification fails, the KDC MUST respond with a 4.00 (Bad Request) error message.¶
If verification succeeds, the handler returns a 2.05 (Content) message containing both the group keying material and the individual keying material for the Client, or information enabling the Client to derive it. The payload of the response is formatted as a CBOR map. The format for the group keying material is the same as defined in the response of Section 4.1.2.2. The specific format of individual keying material for group members, or of the information to derive it, and corresponding CBOR label, MUST be specified in the application profile (REQ15) and registered in Section 8.5.¶
The DELETE handler removes the node identified by "NODENAME" from the group identified by "GROUPNAME".¶
The handler expects a request with method DELETE (and empty payload).¶
The handler verifies that the group name of the /ace-group/GROUPNAME path is a subset of the 'scope' stored in the access token associated to this client, identified by "NODENAME". If verification fails, the KDC MUST respond with a 4.01 (Unauthorized) error message.¶
The handler also verifies that the node sending the request and the node name used in the Uri-Path match. If that is not the case, the handler responds with a 4.01 (Unauthorized) error response.¶
Additionally, the handler verifies that the node is a current member of the group. If verification fails, the KDC MUST respond with a 4.00 (Bad Request) error message.¶
If verification succeeds, the handler removes the client from the group identified by "GROUPNAME", for specific roles if roles were specified in the 'scope' field, or for all roles. That includes removing the public key of the client if the KDC keep tracks of that. Then, the handler delete the sub-resource nodes/NODENAME and returns a 2.02 (Deleted) message with empty payload.¶
This resource implements a POST handler, if the KDC stores the public key of group members. If the KDC does not store the public keys of group members, the handler does not implement any method, and every request returns a 4.05 Method Not Allowed error.¶
The POST handler is used to replace the stored public key of this client (identified by "NODENAME") with the one specified in the request at the KDC, for the group identified by "GROUPNAME".¶
The handler expects a POST request with payload as specified in Section 4.1.2.1, with the difference that it includes only the parameters 'client_cred', 'cnonce' and 'client_cred_verify'. In particular, the signature included in 'client_cred_verify' is expected to be computed as defined in Section 4.1.2.1, with a newly generated N_C nonce and the previously received N_S. The specific format of public keys is specified by the application profile (OPT1).¶
The handler verifies that the group name GROUPNAME is a subset of the 'scope' stored in the access token associated to this client. If verification fails, the KDC MUST respond with a 4.01 (Unauthorized) error message.¶
If the request is not formatted correctly (i.e. required fields non received or received with incorrect format), the handler MUST respond with a 4.00 (Bad Request) error message. If the request contained unknown or non-expected fields present, the handler MUST silently drop them and continue processing. Application profiles MAY define optional or mandatory payload formats for specific error cases (OPT6).¶
Otherwise, the handler checks that the public key specified in the 'client_cred' field has a valid format for the group identified by "GROUPNAME", i.e. it is encoded as expected and is compatible with the signature algorithm and possible associated parameters. If that cannot be verified, the handler MUST respond with a 4.00 (Bad Request) error message. Applications profiles MAY define alternatives (OPT5).¶
Otherwise, the handler verifies the signature contained in the 'client_cred_verify' field of the request, using the public key specified in the 'client_cred' field. If the signature does not pass verification, the handler MUST respond with a 4.00 (Bad Request) error message. If the KDC cannot retrieve the 'kdcchallenge' associated to this Client (see Section 3.3), the KDC MUST respond with a 4.00 Bad Request error respons, including a newly generated 'kdcchallenge' in a CBOR map in the payload the payload. This error response MUST also have Content-Format "application/ace+cbor".¶
If verification succeeds, the handler replaces the old public key of the node NODENAME with the one specified in the 'client_cred' field of the request, and stores it as the new current public key of the node NODENAME, in the list of group members' public keys for the group identified by GROUPNAME. Then, the handler replies with a 2.04 (Changed) response, which does not include a payload.¶
In case the joining node only knows the group identifier of the group it wishes to join or about which it wishes to get update information from the KDC, the node can contact the KDC to request the corresponding group name and joining resource URI. The node can request several group identifiers at once. It does so by sending a CoAP FETCH request to the /ace-group endpoint at the KDC formatted as defined in Section 4.1.1.1.¶
Figure 9 gives an overview of the exchanges described above.¶
Client KDC | | |-------- Group Name and URI Retrieval Request: -------->| | FETCH /ace-group | | | |<-Group Name and URI Retrieval Response: 2.05 (Content)-| | |
Figure 10 gives an overview of the Joining exchange between Client and KDC, when the Client first joins a group.¶
Client KDC | | |----- Joining Request: POST /ace-group/GROUPNAME ------>| | | |<--------- Joining Response: 2.01 (Created) ----------- | | Location-Path = "/ace-group/GROUPNAME/nodes/NODENAME" |
If not previously established, the Client and the KDC MUST first establish a pairwise secure communication channel (REQ16). This can be achieved, for instance, by using a transport profile of ACE. The Joining exchange MUST occur over that secure channel. The Client and the KDC MAY use that same secure channel to protect further pairwise communications that must be secured.¶
The secure communication protocol is REQUIRED to establish the secure channel between Client and KDC 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 secure communication 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 GROUPNAME is the group name of the group to join, formatted as specified in Section 4.1.2.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 retrieved from it. Note that, in case of successful joining, the Client will receive the URI to retrieve group keying material and to leave the group in the Location-Path option of the response.¶
If the node is joining a group for the first time, and the KDC maintains the public keys of the group members, the Client is REQUIRED to send its own public key and proof of possession ("client_cred" and "client_cred_verify" in Section 4.1.2.1). The request is only accepted if both public key and proof of possession are provided. If a node re-joins a group with the same access token and the same public key, it can omit to send the public key and the proof of possession, or just omit the proof of possession, and the KDC will be able to retrieve its public key associated to its token for that group (if the key has been discarded, the KDC will reply with 4.00 Bad Request, as specified in Section 4.1.2.1). If a node re-joins a group but wants to update its own public key, it needs to send both public key and proof of possession.¶
If the application requires backward security, the KDC MUST generate new group keying material and securely distribute it to all the current group members, upon a new node's joining the group. To this end, the KDC uses the message format of the response defined in Section 4.1.2.2. Application profiles may define alternative ways of retrieving the keying material, such as sending separate requests to different resources at the KDC (Section 4.1.2.2, Section 4.1.3.2, Section 4.1.4.1). After distributing the new group keying material, the KDC MUST increment the version number of the keying material.¶
When any of the following happens, a node MUST stop using the owned group keying material to protect outgoing messages, and SHOULD stop using it to decrypt and verify incoming messages.¶
In either case, if it wants to continue participating in the group communication, the node has to request the latest keying material from the KDC. To this end, the Client sends a CoAP GET request to the /ace-group/GROUPNAME/nodes/NODENAME endpoint at the KDC, formatted as specified in Section 4.1.6.2.¶
Note that policies can be set up, so that the Client sends a Key Re-Distribution request to the KDC only after a given number of received messages could not be decrypted (because of failed decryption processing or inability to retrieve the necessary keying material).¶
It is application dependent and pertaining to the particular message exchange (e.g. [I-D.ietf-core-oscore-groupcomm]) to set up these policies, to instruct clients to retain incoming messages and for how long (OPT4). This allows clients to possibly decrypt such messages after getting updated keying material, rather than just consider them non valid messages to discard right away.¶
The same Key Distribution Request could also be sent by the Client without being triggered by a failed decryption of a message, if the Client wants to be sure that it has the latest group keying material. If that is the case, the Client will receive from the KDC the same group keying material it already has in memory.¶
Figure 11 gives an overview of the exchange described above.¶
Client KDC | | |------------------ Key Distribution Request: --------------->| | GET ace-group/GROUPNAME/nodes/NODENAME | | | |<-------- Key Distribution Response: 2.05 (Content) ---------| | |
Alternatively, the re-distribution of keying material can be initiated by the KDC, which e.g.:¶
Note that these methods of KDC-initiated key distribution have different security properties and require different security associations.¶
Beside possible expiration, the client may need to communicate to the KDC its need for the keying material to be renewed, e.g. due to exhaustion of AEAD nonces, if AEAD is used for protecting group communnication. Depending on the application profile (OPT8), this can result in renewal of idividual keying material, group keying material, or both. For example, if the Client uses an individual key to protect outgoing traffic and has to renew it, the node may request a new one, or new input material to derive it, without renewing the whole group keying material.¶
To this end, the client performs a Key Renewal Request/Response exchange with the KDC, i.e. it sends a CoAP PUT request to the /ace-group/GROUPNAME/nodes/NODENAME endpoint at the KDC, where GROUPNAME is the group name and NODENAME is the node's name, and formatted as defined in Section 4.1.6.2.¶
Figure 12 gives an overview of the exchange described above.¶
Client KDC | | |------------------ Key Renewal Request: -------------->| | PUT ace-group/GROUPNAME/nodes/NODENAME | | | |<-------- Key Renewal Response: 2.05 (Content) --------| | |
Note the difference between the Key Distribution Request and the Key Renewal Request: while the first one only triggers distribution (the renewal might have happened independently, e.g. because of expiration), the second one triggers the KDC to produce new individual keying material for the requesting node.¶
In case the KDC maintains the public keys of group members, a node in the group can contact the KDC to request public keys and roles of either all group members or a specified subset, by sending a CoAP GET or FETCH request to the /ace-group/GROUPNAME/pub-key endpoint at the KDC, where GROUPNAME is the group name, and formatted as defined in Section 4.1.3.2 and Section 4.1.3.1.¶
Figure 13 and Figure 14 give an overview of the exchanges described above.¶
Client KDC | | |--Public Key Request: GET /ace-group/GROUPNAME/pub-key->| | | |<--------- Public Key Response: 2.05 (Content) ---------| | |
Client KDC | | |-Public Key Request: FETCH /ace-group/GROUPNAME/pub-key->| | | |<--------- Public Key Response: 2.05 (Created) ----------| | |
In case the KDC maintains the public keys of group members, a node in the group can contact the KDC to upload a new public key to use in the group, and replace the currently stored one.¶
To this end, the Client performs a Public Key Update Request/Response exchange with the KDC, i.e. it sends a CoAP POST request to the /ace-group/GROUPNAME/nodes/NODENAME/pub-key endpoint at the KDC, where GROUPNAME is the group name and NODENAME is the node's name.¶
The request is formatted as specified in Section 4.1.7.1.¶
Figure Figure 15 gives an overview of the exchange described above.¶
Client KDC | | |-------------- Public Key Update Request: ---------------------->| | POST ace-group/GROUPNAME/nodes/NODENAME/pub-key | | | |<------- Public Key Update Response: 2.04 (Changed) -------------| | |
If the application requires backward security, the KDC MUST generate new group keying material and securely distribute it to all the current group members, upon a group member updating its own public key. To this end, the KDC uses the message format of the response defined in Section 4.1.2.2. Application profiles may define alternative ways of retrieving the keying material, such as sending separate requests to different resources at the KDC (Section 4.1.2.2, Section 4.1.3.2, Section 4.1.4.1). The KDC MUST increment the version number of the current keying material, before distributing the newly generated keying material to the group. After that, the KDC SHOULD store the distributed keying material in persistent storage.¶
Additionally, after updating its own public key, a group member MAY send a number of the later requests including an identifier of the updated public key, to signal nodes that they need to retrieve it. How that is done depends on the group communication protocol used, and therefore is application profile specific (OPT10).¶
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, where GROUPNAME is the group name, and formatted as defined in Section 4.1.4.1¶
Figure 16 gives an overview of the exchange described above.¶
Client KDC | | |-Policies Request: GET ace-group/GROUPNAME/policies ->| | | |<--------- Policies Response: 2.05 (Content) ---------| | |
A node in the group can contact the KDC to request information about the version number of the symmetric group keying material, by sending a CoAP GET request to the /ace-group/GROUPNAME/num endpoint at the KDC, where GROUPNAME is the group name, formatted as defined in Section 4.1.5.1. In particular, the version is incremented by the KDC every time the group keying material is renewed, before it's distributed to the group members.¶
Figure 17 gives an overview of the exchange described above.¶
Client KDC | | |---- Version Request: GET ace-group/GROUPNAME/num ---->| | | |<--------- Version Response: 2.05 (Content) -----------| | |
A node can actively request to leave the group. In this case, the Client sends a CoAP DELETE request to the endpoint /ace-group/GROUPNAME/nodes/NODENAME at the KDC, where GROUPNAME is the group name and NODENAME is the node's name, formatted as defined in Section 4.1.6.3¶
Alternatively, a node may be removed by the KDC, without having explicitly asked for it. This is further discussed in Section 5.¶
This section describes the different scenarios according to which a node ends up being removed from the group.¶
If the application requires forward security, the KDC MUST generate new group keying material and securely distribute it to all the current group members but the leaving node, using the message format of the Key Distribution Response (see Section 4.4). Application profiles may define alternative message formats. Before distributing the new group keying material, the KDC MUST increment the version number of the keying material.¶
Note that, after having left the group, a node may wish to join it again. Then, as long as the node is still authorized to join the group, i.e. it still has a valid access token, it can re-request to join the group directly to the KDC without needing to retrieve a new access token from the AS. This means that the KDC might decide to keep track of nodes with valid access tokens, before deleting all information about the leaving node.¶
A node may be evicted from the group in the following cases.¶
In either case, once aware that a node is not authorized anymore, the KDC has to remove the unauthorized node from the list of group members, if the KDC keeps track of that.¶
In case of forced eviction, the KDC MAY explicitly inform the leaving node, if the Client implements the 'control_path' resource specified in Section 4.1.2.1. To this end, the KDC MAY send a DEL request, targeting the URI specified in the 'control_path' parameter of the Joining Request.¶
This specification defines a number of fields used during the second part of the message exchange, after the ACE Token POST exchange. The table below summarizes them, and specifies the CBOR key to use instead of the full descriptive name. Note that the media type ace-groupcomm+cbor MUST be used when these fields are transported.¶
| Name | CBOR Key | CBOR Type | Reference |
|---|---|---|---|
| scope | TBD | byte string | Section 4.1.2.1 |
| get_pub_keys | TBD | array | Section 4.1.2.1, Section 4.1.3.1 |
| client_cred | TBD | byte string | Section 4.1.2.1 |
| cnonce | TBD | byte string | Section 4.1.2.1 |
| client_cred_verify | TBD | byte string | Section 4.1.2.1 |
| pub_keys_repos | TBD | text string | Section 4.1.2.1 |
| control_path | TBD | text string | Section 4.1.2.1 |
| gkty | TBD | integer / text string | Section 4.1.2.1 |
| key | TBD | see "ACE Groupcomm Key" Registry | Section 4.1.2.1 |
| num | TBD | integer | Section 4.1.2.1 |
| ace-groupcomm-profile | TBD | int | Section 4.1.2.1 |
| exp | TBD | int | Section 4.1.2.1 |
| pub_keys | TBD | byte string | Section 4.1.2.1 |
| peer_roles | TBD | array | Section 4.1.2.1 |
| group_policies | TBD | map | Section 4.1.2.1 |
| mgt_key_material | TBD | byte string | Section 4.1.2.1 |
| gid | TBD | array | Section 4.1.1.1 |
| gname | TBD | array of text string | Section 4.1.1.1 |
| guri | TBD | array of text string | Section 4.1.1.1 |
When a Client receives a message from a sender for the first time, it needs to have a mechanism in place to avoid replay, e.g. Appendix B.2 of [RFC8613]. In case the Client rebooted and lost the security state used to protect previous communication with that sender, such a mechanism is useful for the recipient to be on the safe side. Besides, if the KDC has renewed the group keying material, and the time interval between the end of the rekeying process and the joining of the Client is sufficiently small, that Client is also on the safe side, since replayed older messages protected with the previous keying material will not be accepted.¶
The KDC must renew the group keying material upon its expiration.¶
The KDC should renew the keying material upon group membership change, and should provide it to the current group members through the rekeying scheme used in the group.¶
The KDC should renew the group keying material after rebooting, even in the case where all keying material is stored in persistent storage. However, if the KDC relies on Observe responses to notify the group of renewed keying material, after rebooting the KDC will have lost all the current ongoing Observations with the group members, and the previous keying material will be used to protect messages in the group anyway. The KDC will rely on each node requesting updates of the group keying material to establish the new keying material in the nodes, or, if implemented, it can push the update to the nodes in the group using the 'control_path' resource.¶
The KDC may enforce a rekeying policy that takes into account the overall time required to rekey the group, as well as the expected rate of changes in the group membership.¶
That is, the KDC may not rekey the group at every membership change, for instance if members' joining and leaving occur frequently and performing a group rekeying takes too long. The KDC may rekey the group after a minimum number of group members have joined or left within a given time interval, or after maximum amount of time since the last rekeying was completed, or yet during predictable network inactivity periods.¶
However, this would result in the KDC not constantly preserving backward and forward security. Newly joining group members could be able to access the keying material used before their joining, and thus could access past group communications. Also, until the KDC performs a group rekeying, the newly leaving nodes would still be able to access upcoming group communications that are protected with the keying material that has not yet been updated.¶
The KDC needs to have a mechanism in place to detect DoS attacks from nodes constantly initiating rekey events (for example by updating their public key), such as removing these nodes from the group.¶
The KDC also needs to have a congestion control mechanism in place to avoid network congestion when the KDC renews the group keying material; CoAP and Observe give guidance on such mechanisms, see Section 4.7 of [RFC7252] and Section 4.5.1 of [RFC7641].¶
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 keying material. However, the recipient receives the message after having received the new keying material, hence not being able to correctly process it. A possible way to ameliorate this issue is to preserve the old, recent, keying material for a maximum amount of time defined by the application. By doing so, the recipient can still try to process the received message using the old retained keying material. Note that a former (compromised) group member can take advantage of this by sending messages protected with the old retained keying material. Therefore, a conservative application policy should not admit the storage of old keying material.¶
In the second case, the sender protects a message using the new keying material, but the recipient receives that request before having received the new keying material. Therefore, the recipient would not be able to correctly process the request and hence discards it. If the recipient receives the new 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 an updated keying material according to an application-defined policy, for instance after a given number of unsuccessfully decrypted incoming messages.¶
A node that has left the group should not expect any of its outgoing messages to be successfully processed, if received after its leaving, due to a possible group rekeying occurred before the message reception.¶
If the block-wise options [RFC7959] are used, and the keying material is updated in the middle of a block-wise transfer, the sender of the blocks just changes the keying material to the updated one and continues the transfer. As long as both sides get the new keying material, updating the keying material in the middle of a transfer will not cause any issue. Otherwise, the sender will have to transmit the message again, when receiving an error message from the recipient.¶
Compared to a scenario where the transfer does not use block-wise, depending on how fast the keying material is changed, the nodes might consume a larger amount of the network bandwidth resending the blocks again and again, which might be problematic.¶
This document has the following actions for IANA.¶
This specification registers the 'application/ace-groupcomm+cbor' media type for messages of the protocols defined in this document following the ACE exchange and carrying parameters encoded in CBOR. This registration follows the procedures specified in [RFC6838].¶
Type name: application¶
Subtype name: ace-groupcomm+cbor¶
Required parameters: none¶
Optional parameters: none¶
Encoding considerations: Must be encoded as CBOR map containing the protocol parameters defined in [this document].¶
Security considerations: See Section 7 of this document.¶
Interoperability considerations: n/a¶
Published specification: [this document]¶
Applications that use this media type: The type is used by authorization servers, clients and resource servers that support the ACE groupcomm framework as specified in [this document].¶
Additional information:¶
Magic number(s): n/a¶
File extension(s): .ace-groupcomm¶
Macintosh file type code(s): n/a¶
Person & email address to contact for further information: iesg@ietf.org¶
Intended usage: COMMON¶
Restrictions on usage: None¶
Author: Francesca Palombini francesca.palombini@ericsson.com¶
Change controller: IESG¶
This specification registers the following entry to the "CoAP Content-Formats" registry, within the "CoRE Parameters" registry:¶
Media Type: application/ace-groupcomm+cbor¶
Encoding: -¶
ID: TBD¶
Reference: [this document]¶
The following registrations are done for the OAuth ParametersRegistry following the procedure specified in section 11.2 of [RFC6749]:¶
o Parameter name: sign_info o Parameter usage location: token request, token response o Change Controller: IESG o Specification Document(s): [[This specification]]¶
o Parameter name: kdcchallenge o Parameter usage location: token response o Change Controller: IESG o Specification Document(s): [[This specification]]¶
The following registrations are done for the OAuth Parameters CBOR Mappings Registry following the procedure specified in section 8.9 of [I-D.ietf-ace-oauth-authz]:¶
* Name: sign_info * CBOR Key: TBD (range -256 to 255) * Value Type: any * Reference: \[\[This specification\]\] * Name: kdcchallenge * CBOR Key: TBD (range -256 to 255) * Value Type: byte string * Reference: \[\[This specification\]\]¶
This specification establishes the "ACE Groupcomm Parameters" IANA Registry. The Registry has been created to use the "Expert Review Required" registration procedure [RFC8126]. Expert review guidelines are provided in Section 8.11.¶
The columns of this Registry are:¶
This Registry has been initially populated by the values in Section 6. The Reference column for all of these entries refers to sections of this document.¶
This specification establishes the "ACE Groupcomm Key" IANA Registry. The Registry has been created to use the "Expert Review Required" registration procedure [RFC8126]. Expert review guidelines are provided in Section 8.11.¶
The columns of this Registry are:¶
This Registry has been initially populated by the values in Figure 7. The specification column for all of these entries will be this document.¶
This specification establishes the "ACE Groupcomm Profile" IANA Registry. The Registry has been created to use the "Expert Review Required" registration procedure [RFC8126]. Expert review guidelines are provided in Section 8.11. It should be noted that, in addition to the expert review, some portions of the Registry require a specification, potentially a Standards Track RFC, be supplied as well.¶
The columns of this Registry are:¶
This specification establishes the "ACE Groupcomm Policy" IANA Registry. The Registry has been created to use the "Expert Review Required" registration procedure [RFC8126]. Expert review guidelines are provided in Section 8.11. It should be noted that, in addition to the expert review, some portions of the Registry require a specification, potentially a Standards Track RFC, be supplied as well.¶
The columns of this Registry are:¶
This registry will be initially populated by the values in Figure 8.¶
This specification establishes the "Sequence Number Synchronization Method" IANA Registry. The Registry has been created to use the "Expert Review Required" registration procedure [RFC8126]. Expert review guidelines are provided in Section 8.11. It should be noted that, in addition to the expert review, some portions of the Registry require a specification, potentially a Standards Track RFC, be supplied as well.¶
The columns of this Registry are:¶
This specification registers the following entry to the "Interface Description (if=) Link Target Attribute Values Registry" registry, within the "CoRE Parameters" registry:¶
The IANA Registries established in this document are defined as expert review. This section gives some general guidelines for what the experts should be looking for, but they are being designated as experts for a reason so they should be given substantial latitude.¶
Expert reviewers should take into consideration the following points:¶
This section lists the requirements on application profiles of this specification,for the convenience of application profile designers.¶
RFC EDITOR: PLEASE REMOVE THIS SECTION.¶
The following individuals were helpful in shaping this document: Carsten Bormann, Rikard Hoeglund, Ben Kaduk, John Mattsson, Daniel Migault, Jim Schaad, Ludwig Seitz, Goeran Selander and Peter van der Stok.¶
The work on this document has been partly supported by VINNOVA and the Celtic-Next project CRITISEC; and by the EIT-Digital High Impact Initiative ACTIVE.¶