idnits 2.17.1 draft-ietf-ace-key-groupcomm-11.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (February 22, 2021) is 1156 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) -- Looks like a reference, but probably isn't: '01' on line 1777 -- Looks like a reference, but probably isn't: '02' on line 1777 -- Looks like a reference, but probably isn't: '1' on line 3174 -- Looks like a reference, but probably isn't: '2' on line 3176 == Outdated reference: A later version (-07) exists of draft-ietf-ace-aif-02 == Outdated reference: A later version (-46) exists of draft-ietf-ace-oauth-authz-37 == Outdated reference: A later version (-21) exists of draft-ietf-core-oscore-groupcomm-11 ** Downref: Normative reference to an Informational draft: draft-ietf-cose-rfc8152bis-algs (ref. 'I-D.ietf-cose-rfc8152bis-algs') -- Possible downref: Normative reference to a draft: ref. 'I-D.ietf-cose-rfc8152bis-struct' ** Downref: Normative reference to an Informational RFC: RFC 7967 == Outdated reference: A later version (-18) exists of draft-ietf-ace-dtls-authorize-15 == Outdated reference: A later version (-17) exists of draft-ietf-ace-mqtt-tls-profile-10 == Outdated reference: A later version (-19) exists of draft-ietf-ace-oscore-profile-16 == Outdated reference: A later version (-14) exists of draft-ietf-core-coap-pubsub-09 == Outdated reference: A later version (-10) exists of draft-ietf-core-groupcomm-bis-03 Summary: 2 errors (**), 0 flaws (~~), 9 warnings (==), 6 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 ACE Working Group F. Palombini 3 Internet-Draft Ericsson AB 4 Intended status: Standards Track M. Tiloca 5 Expires: August 26, 2021 RISE AB 6 February 22, 2021 8 Key Provisioning for Group Communication using ACE 9 draft-ietf-ace-key-groupcomm-11 11 Abstract 13 This document defines message formats and procedures for requesting 14 and distributing group keying material using the ACE framework, to 15 protect communications between group members. 17 Status of This Memo 19 This Internet-Draft is submitted in full conformance with the 20 provisions of BCP 78 and BCP 79. 22 Internet-Drafts are working documents of the Internet Engineering 23 Task Force (IETF). Note that other groups may also distribute 24 working documents as Internet-Drafts. The list of current Internet- 25 Drafts is at https://datatracker.ietf.org/drafts/current/. 27 Internet-Drafts are draft documents valid for a maximum of six months 28 and may be updated, replaced, or obsoleted by other documents at any 29 time. It is inappropriate to use Internet-Drafts as reference 30 material or to cite them other than as "work in progress." 32 This Internet-Draft will expire on August 26, 2021. 34 Copyright Notice 36 Copyright (c) 2021 IETF Trust and the persons identified as the 37 document authors. All rights reserved. 39 This document is subject to BCP 78 and the IETF Trust's Legal 40 Provisions Relating to IETF Documents 41 (https://trustee.ietf.org/license-info) in effect on the date of 42 publication of this document. Please review these documents 43 carefully, as they describe your rights and restrictions with respect 44 to this document. Code Components extracted from this document must 45 include Simplified BSD License text as described in Section 4.e of 46 the Trust Legal Provisions and are provided without warranty as 47 described in the Simplified BSD License. 49 Table of Contents 51 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 52 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3 53 2. Overview . . . . . . . . . . . . . . . . . . . . . . . . . . 4 54 3. Authorization to Join a Group . . . . . . . . . . . . . . . . 7 55 3.1. Authorization Request . . . . . . . . . . . . . . . . . . 8 56 3.2. Authorization Response . . . . . . . . . . . . . . . . . 10 57 3.3. Token Post . . . . . . . . . . . . . . . . . . . . . . . 11 58 4. Keying Material Provisioning and Group Membership Management 14 59 4.1. Interface at the KDC . . . . . . . . . . . . . . . . . . 16 60 4.2. Retrieval of Group Names and URIs . . . . . . . . . . . . 38 61 4.3. Joining Exchange . . . . . . . . . . . . . . . . . . . . 38 62 4.4. Retrieval of Updated Keying Material . . . . . . . . . . 40 63 4.5. Requesting a Change of Keying Material . . . . . . . . . 43 64 4.6. Retrieval of Public Keys and Roles for Group Members . . 44 65 4.7. Update of Public Key . . . . . . . . . . . . . . . . . . 46 66 4.8. Retrieval of Group Policies . . . . . . . . . . . . . . . 47 67 4.9. Retrieval of Keying Material Version . . . . . . . . . . 48 68 4.10. Group Leaving Request . . . . . . . . . . . . . . . . . . 49 69 5. Removal of a Node from the Group . . . . . . . . . . . . . . 49 70 6. Extended Scope Format . . . . . . . . . . . . . . . . . . . . 51 71 7. ACE Groupcomm Parameters . . . . . . . . . . . . . . . . . . 53 72 8. ACE Groupcomm Error Identifiers . . . . . . . . . . . . . . . 54 73 9. Security Considerations . . . . . . . . . . . . . . . . . . . 55 74 9.1. Update of Keying Material . . . . . . . . . . . . . . . . 56 75 9.2. Block-Wise Considerations . . . . . . . . . . . . . . . . 57 76 10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 57 77 10.1. Media Type Registrations . . . . . . . . . . . . . . . . 57 78 10.2. CoAP Content-Formats Registry . . . . . . . . . . . . . 58 79 10.3. OAuth Parameters Registry . . . . . . . . . . . . . . . 59 80 10.4. OAuth Parameters CBOR Mappings Registry . . . . . . . . 59 81 10.5. ACE Groupcomm Parameters Registry . . . . . . . . . . . 59 82 10.6. ACE Groupcomm Key Registry . . . . . . . . . . . . . . . 60 83 10.7. ACE Groupcomm Profile Registry . . . . . . . . . . . . . 60 84 10.8. ACE Groupcomm Policy Registry . . . . . . . . . . . . . 61 85 10.9. Sequence Number Synchronization Method Registry . . . . 62 86 10.10. Interface Description (if=) Link Target Attribute Values 87 Registry . . . . . . . . . . . . . . . . . . . . . . . . 62 88 10.11. CBOR Tags Registry . . . . . . . . . . . . . . . . . . . 63 89 10.12. ACE Scope Semantics . . . . . . . . . . . . . . . . . . 63 90 10.13. ACE Groupcomm Errors . . . . . . . . . . . . . . . . . . 63 91 10.14. Expert Review Instructions . . . . . . . . . . . . . . . 64 92 11. References . . . . . . . . . . . . . . . . . . . . . . . . . 65 93 11.1. Normative References . . . . . . . . . . . . . . . . . . 65 94 11.2. Informative References . . . . . . . . . . . . . . . . . 67 95 11.3. URIs . . . . . . . . . . . . . . . . . . . . . . . . . . 68 96 Appendix A. Requirements on Application Profiles . . . . . . . . 68 97 Appendix B. Document Updates . . . . . . . . . . . . . . . . . . 71 98 B.1. Version -04 to -05 . . . . . . . . . . . . . . . . . . . 71 99 B.2. Version -03 to -04 . . . . . . . . . . . . . . . . . . . 72 100 B.3. Version -02 to -03 . . . . . . . . . . . . . . . . . . . 72 101 B.4. Version -01 to -02 . . . . . . . . . . . . . . . . . . . 73 102 B.5. Version -00 to -01 . . . . . . . . . . . . . . . . . . . 73 103 Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . 74 104 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 74 106 1. Introduction 108 This document expands the ACE framework [I-D.ietf-ace-oauth-authz] to 109 define the message exchanges used to request, distribute and renew 110 the keying material in a group communication scenario, e.g. based on 111 multicast [I-D.ietf-core-groupcomm-bis] or on publishing-subscribing 112 [I-D.ietf-core-coap-pubsub]. The ACE framework is based on CBOR 113 [RFC8949], so CBOR is the format used in this specification. 114 However, using JSON [RFC8259] instead of CBOR is possible, using the 115 conversion method specified in Sections 6.1 and 6.2 of [RFC8949]. 117 Profiles that use group communication can build on this document, by 118 defining a number of details such as the exact group communication 119 protocol and security protocols used. The specific list of details a 120 profile needs to define is shown in Appendix A. 122 If the application requires backward and forward security, new keying 123 material is generated and distributed to the group upon membership 124 changes. A key management scheme performs the actual distribution of 125 the new keying material to the group. In particular, the key 126 management scheme rekeys the current group members when a new node 127 joins the group, and the remaining group members when a node leaves 128 the group. Rekeying mechanisms can be based on [RFC2093], [RFC2094] 129 and [RFC2627]. 131 1.1. Terminology 133 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 134 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 135 "OPTIONAL" in this document are to be interpreted as described in BCP 136 14 [RFC2119] [RFC8174] when, and only when, they appear in all 137 capitals, as shown here. 139 Readers are expected to be familiar with the terms and concepts 140 described in [I-D.ietf-ace-oauth-authz][I-D.ietf-cose-rfc8152bis-stru 141 ct][I-D.ietf-cose-rfc8152bis-algs], such as Authorization Server (AS) 142 and Resource Server (RS). 144 This document uses names or identifiers for groups and nodes. Their 145 different meanings are summarized here: 147 o "Group name" is the invariant once established identifier of the 148 group. It is used in the communication between AS, RS and Client 149 to identify the group. 151 o "GROUPNAME" is the invariant once established text string used in 152 URIs. GROUPNAME maps to the group name of a group, although it is 153 not necessarily the same. 155 o "Group identifier" is the identifier of the group keying material. 156 Opposite to group name and GROUPNAME, this identifier changes over 157 time, when the keying material is updated. 159 o "Node name" is the invariant once established identifier of the 160 node. It is used in the communication between AS, RS and Client 161 to identify a member of the group. 163 o "NODENAME" is the invariant once established text string used in 164 URIs. NODENAME is used to identify a node in a group. 166 This document additionally uses the following terminology: 168 o Transport profile, to indicate a profile of ACE as per 169 Section 5.8.4.3 of [I-D.ietf-ace-oauth-authz]. A transport 170 profile specifies the communication protocol and communication 171 security protocol between an ACE Client and Resource Server, as 172 well as proof-of-possession methods, if it supports proof-of- 173 possession access tokens, etc. Tranport profiles of ACE include, 174 for instance, [I-D.ietf-ace-oscore-profile], 175 [I-D.ietf-ace-dtls-authorize] and [I-D.ietf-ace-mqtt-tls-profile]. 177 o Application profile, that defines how applications enforce and use 178 supporting security services they require. These services may 179 include, for instance, provisioning, revocation and distribution 180 of keying material. An application profile may define specific 181 procedures and message formats. 183 2. Overview 185 The full procedure can be separated in two phases: the first one 186 follows the ACE framework, between Client, AS and KDC; the second one 187 is the key distribution between Client and KDC. After the two phases 188 are completed, the Client is able to participate in the group 189 communication, via a Dispatcher entity. 191 +------------+ +-----------+ 192 | AS | | KDC | 193 | | .-------->| | 194 +------------+ / +-----------+ 195 ^ / 196 | / 197 v / +-----------+ 198 +------------+ / +------------+ |+-----------+ 199 | Client |<-' | Dispatcher | ||+-----------+ 200 | |<-------->| |<------->|| Group | 201 +------------+ +------------+ +| members | 202 +-----------+ 204 Figure 1: Key Distribution Participants 206 The following participants (see Figure 1) take part in the 207 authorization and key distribution. 209 o Client (C): node that wants to join the group communication. It 210 can request write and/or read rights. 212 o Authorization Server (AS): same as AS in the ACE Framework; it 213 enforces access policies, and knows if a node is allowed to join a 214 given group with write and/or read rights. 216 o Key Distribution Center (KDC): maintains the keying material to 217 protect group communications, and provides it to Clients 218 authorized to join a given group. During the first part of the 219 exchange (Section 3), it takes the role of the RS in the ACE 220 Framework. During the second part (Section 4), which is not based 221 on the ACE Framework, it distributes the keying material. In 222 addition, it provides the latest keying material to group members 223 when requested or, if required by the application, when membership 224 changes. 226 o Dispatcher: entity through which the Clients communicate with the 227 group and which distributes messages to the group members. 228 Examples of dispatchers are: the Broker node in a pub-sub setting; 229 a relayer node for group communication that delivers group 230 messages as multiple unicast messages to all group members; an 231 implicit entity as in a multicast communication setting, where 232 messages are transmitted to a multicast IP address and delivered 233 on the transport channel. 235 This document specifies a mechanism for: 237 o Authorizing a new node to join the group (Section 3), and 238 providing it with the group keying material to communicate with 239 the other group members (Section 4). 241 o Allowing a group member to leave the group (Section 5). 243 o Evicting a group member from the group (Section 5). 245 o Allowing a group member to retrieve keying material (Section 4.4 246 and Section 4.5). 248 o Renewing and re-distributing the group keying material (rekeying) 249 upon a membership change in the group (Section 4.10 and 250 Section 5). 252 Figure 2 provides a high level overview of the message flow for a 253 node joining a group communication setting, which can be expanded as 254 follows. 256 1. The joining node requests an Access Token from the AS, in order 257 to access a specific group-membership resource on the KDC and 258 hence join the associated group. This exchange between Client 259 and AS MUST be secured, as specified by the transport profile of 260 ACE used between Client and KDC. The joining node will start or 261 continue using a secure communication association with the KDC, 262 according to the response from the AS. 264 2. The joining node transfers authentication and authorization 265 information to the KDC, by posting the obtained Access Token to 266 the /authz-info endpoint at the KDC. This exchange, and all 267 further communications between the Client and the KDC, MUST occur 268 over the secure channel established as a result of the transport 269 profile of ACE used between Client and KDC. After that, a 270 joining node MUST have a secure communication association 271 established with the KDC, before starting to join a group under 272 that KDC. Possible ways to provide a secure communication 273 association are described in the DTLS transport profile 274 [I-D.ietf-ace-dtls-authorize] and OSCORE transport profile 275 [I-D.ietf-ace-oscore-profile] of ACE. 277 3. The joining node starts the joining process to become a member of 278 the group, by accessing the related group-membership resource at 279 the KDC. At the end of the joining process, the joining node has 280 received from the KDC the parameters and keying material to 281 securely communicate with the other members of the group, and the 282 KDC has stored the association between the authorization 283 information from the access token and the secure session with the 284 joining node. 286 4. The joining node and the KDC maintain the secure association, to 287 support possible future communications. These especially include 288 key management operations, such as retrieval of updated keying 289 material or participation to a group rekeying process. 291 5. The joining node can communicate securely with the other group 292 members, using the keying material provided in step 3. 294 C AS KDC Group 295 | | | Member 296 / | | | | 297 | | Authorization Request | | | 298 Defined | |-------------------------->| | | 299 in the | | | | | 300 ACE | | Authorization Response | | | 301 framework | |<--------------------------| | | 302 | | | | 303 \ |---------- Token Post --------->| | 304 | | | 305 |------- Joining Request ------->| | 306 | | | 307 |<------ Joining Response -------|-- Group Rekeying -->| 308 | | | 309 | Dispatcher | 310 | | | 311 |<===== Secure group communication =======|===========>| 312 | | | 314 Figure 2: Message Flow Upon New Node's Joining 316 3. Authorization to Join a Group 318 This section describes in detail the format of messages exchanged by 319 the participants when a node requests access to a given group. This 320 exchange is based on ACE [I-D.ietf-ace-oauth-authz]. 322 As defined in [I-D.ietf-ace-oauth-authz], the Client requests from 323 the AS an authorization to join the group through the KDC (see 324 Section 3.1). If the request is approved and authorization is 325 granted, the AS provides the Client with a proof-of-possession access 326 token and parameters to securely communicate with the KDC (see 327 Section 3.2). 329 Communications between the Client and the AS MUST be secured, as 330 defined by the transport profile of ACE used. The Content-Format 331 used in the message depends on the used transport profile of ACE. 332 For example, this can be application/ace+cbor for the first two 333 messages and application/cwt for the third message, which are defined 334 in the ACE framework. The transport profile of ACE also defines a 335 number of details such as the communication and security protocols 336 used with the KDC (see Appendix C of [I-D.ietf-ace-oauth-authz]). 338 Figure 3 gives an overview of the exchange described above. 340 Client AS KDC 341 | | | 342 |---- Authorization Request: POST /token ------>| | 343 | | | 344 |<--- Authorization Response: 2.01 (Created) ---| | 345 | | | 346 |----- POST Token: POST /authz-info --------------->| 347 | | 349 Figure 3: Message Flow of Join Authorization 351 3.1. Authorization Request 353 The Authorization Request sent from the Client to the AS is defined 354 in Section 5.8.1 of [I-D.ietf-ace-oauth-authz] and MAY contain the 355 following parameters, which, if included, MUST have the corresponding 356 values: 358 o 'scope', containing the identifier of the specific groups, or 359 topics in the case of pub-sub, that the Client wishes to access, 360 and optionally the roles that the Client wishes to take. 362 This value is a CBOR byte string, wrapping a CBOR array of one or 363 more entries. 365 By default, each entry is encoded as specified by 366 [I-D.ietf-ace-aif]. The object identifier Toid corresponds to the 367 group name and MUST be encoded as a tstr. The permission set 368 Tperm indicates the roles that the client wishes to take in the 369 group. It is up to the application profiles to define Tperm 370 (REQ2) and register Toid and Tperm to fit the use case. An 371 example of scope using the AIF format is given in Figure 4. 373 Otherwise, each scope entry can be defined as a CBOR array, which 374 contains: 376 * As first element, the identifier of the specific group or 377 topic, encoded as a tstr. 379 * Optionally, as second element, the role (or CBOR array of 380 roles) that the Client wishes to take in the group. This 381 element is optional since roles may have been pre-assigned to 382 the Client, as associated to its verifiable identity 383 credentials. Alternatively, the application may have defined a 384 single, well-known role for the target resource(s) and 385 audience(s). 387 In each entry, the encoding of the role identifiers is application 388 specific, and part of the requirements for the application profile 389 (REQ2). In particular, the application profile may specify CBOR 390 values to use for abbreviating role identifiers (OPT8). 392 An example of CDDL definition [RFC8610] of scope using the format 393 above, with group name and role identifiers encoded as text 394 strings is given in Figure 5. 396 o 'audience', with an identifier of a KDC. 398 As defined in [I-D.ietf-ace-oauth-authz], other additional parameters 399 can be included if necessary. 401 gname = tstr 403 permissions = uint . bits roles 405 roles = &( 406 Requester: 1, 407 Responder: 2, 408 Monitor: 3, 409 Verifier: 4 410 ) 412 scope_entry = AIF_Generic 414 scope = << [ + scope_entry ] >> 416 Figure 4: Example CDLL definition of scope, using the default 417 Authorization Information Format 419 gname = tstr 421 role = tstr 423 scope_entry = [ gname , ? ( role / [ 2*role ] ) ] 425 scope = << [ + scope_entry ] >> 427 Figure 5: CDLL definition of scope, using as example group name 428 encoded as tstr and role as tstr 430 3.2. Authorization Response 432 The Authorization Response sent from the AS to the Client is defined 433 in Section 5.8.2 of [I-D.ietf-ace-oauth-authz]. Note that the 434 parameter 'expires_in' MAY be omitted if the application defines how 435 the expiration time is communicated to the Client via other means, or 436 if it establishes a default value. 438 Additionally, when included, the following parameter MUST have the 439 corresponding values: 441 o 'scope' has the same format and encoding of 'scope' in the 442 Authorization Request, defined in Section 3.1. If this parameter 443 is not present, the granted scope is equal to the one requested in 444 Section 3.1}. 446 The proof-of-possession access token (in 'access_token' above) MUST 447 contain the following parameters: 449 o a confirmation claim (see for example 'cnf' defined in Section 3.1 450 of [RFC8747] for CWT); 452 o an expiration time claim (see for example 'exp' defined in 453 Section 3.1.4 of [RFC8392] for CWT); 455 o a scope claim (see for example 'scope' registered in Section 8.14 456 of [I-D.ietf-ace-oauth-authz] for CWT). 458 This claim specifies the same access control information as in the 459 'scope' parameter of the Authorization Response, if the parameter 460 is present in the message, or as in the 'scope' parameter of the 461 Authorization Request otherwise. 463 By default, this claim has the same encoding as the 'scope' 464 parameter in the Authorization Request, defined in Section 3.1. 466 Optionally, an alternative extended format of scope defined in 467 Section 6 can be used. This format explicitly signals the 468 semantics used to express the actual access control information, 469 and according to which this has to be parsed. This enables a 470 Resource Server to correctly process a received access token, also 471 in case: 473 * The Resource Server implements a KDC that supports multiple 474 application profiles of this specification, using different 475 scope semantics; and/or 477 * The Resource Server implements further services beyond a KDC 478 for group communication, using different scope semantics. 480 If the Authorization Server is aware that this applies to the 481 Resource Server for which the access token is issued, the 482 Authorization Server SHOULD use the extended format of scope 483 defined in Section 6. 485 The access token MAY additionally contain other claims that the 486 transport profile of ACE requires, or other optional parameters. 488 When receiving an Authorization Request from a Client that was 489 previously authorized, and for which the AS still owns a valid non- 490 expired access token, the AS MAY reply with that token. Note that it 491 is up to application profiles of ACE to make sure that re-posting the 492 same token does not cause re-use of keying material between nodes 493 (for example, that is done with the use of random nonces in 494 [I-D.ietf-ace-oscore-profile]). 496 3.3. Token Post 498 The Client sends a CoAP POST request including the access token to 499 the KDC, as specified in Section 5.8.1 of [I-D.ietf-ace-oauth-authz]. 501 This request differs from the one defined in 502 [I-D.ietf-ace-oauth-authz], because it allows to transport additional 503 encoding information about the public keys in the group, used for 504 source authentication, as well as any other group parameters. 506 The joining node MAY ask for this information from the KDC in the 507 same message it uses to POST the token to the RS. In such a case, 508 the message MUST have Content-Format set to application/ace+cbor 509 defined in Section 8.16 of [I-D.ietf-ace-oauth-authz]. The message 510 payload MUST be formatted as a CBOR map, which MUST include the 511 access token. The CBOR map MAY additionally include the following 512 parameter, which, if included, MUST have the corresponding values: 514 o 'sign_info' defined in Section 3.3.1, encoding the CBOR simple 515 value Null to require information about the signature algorithm, 516 signature algorithm parameters, signature key parameters and on 517 the exact encoding of public keys used in the group. 519 Alternatively, the joining node may retrieve this information by 520 other means. 522 After successful verification, the Client is authorized to receive 523 the group keying material from the KDC and join the group. 525 The KDC replies to the Client with a 2.01 (Created) response, using 526 Content-Format "application/ace+cbor". 528 The payload of the 2.01 response is a CBOR map. If the access token 529 contains a role that requires the Client to send its own public key 530 to the KDC when joining the group, the CBOR map MUST include the 531 parameter 'kdcchallenge' defined in Section 3.3.2, specifying a 532 dedicated challenge N_S generated by the KDC. The Client uses this 533 challenge to prove possession of its own private key (see the 534 'client_cred_verify' parameter in Section 4). Note that the payload 535 format of the response deviates from the one defined in the ACE 536 framework (see Section 5.10.1 of [I-D.ietf-ace-oauth-authz]), which 537 has no payload. 539 The KDC MUST store the 'kdcchallenge' value associated to the Client 540 at least until it receives a join request from it (see Section 4.3), 541 to be able to verify that the Client possesses its own private key. 542 The same challenge MAY be reused several times by the Client, to 543 generate a new proof of possession, e.g. in case of update of the 544 public key, or to join a different group with a different signing 545 key, so it is RECOMMENDED that the KDC keeps storing the 546 'kdcchallenge' after the first join is processed as well. If the KDC 547 has already discarded the 'kdcchallenge', that will trigger an error 548 response with a newly generated 'kdcchallenge' that the Client can 549 use to restart the join process, as specified in Section 4.3. 551 If 'sign_info' is included in the request, the KDC MAY include the 552 'sign_info' parameter defined in Section 3.3.1, with the same 553 encoding. Note that the field 'id' takes the value of the group name 554 for which the 'sign_info_entry' applies to. 556 Note that the CBOR map specified as payload of the 2.01 (Created) 557 response may include further parameters, e.g. according to the 558 signalled transport profile of ACE. Application profiles MAY define 559 the additional parameters to use within this exchange (OPT3). 561 Application profiles of this specification MAY define alternative 562 specific negotiations of parameter values for the signature algorithm 563 and signature keys, if 'sign_info' is not used (OPT2). 565 3.3.1. 'sign_info' Parameter 567 The 'sign_info' parameter is an OPTIONAL parameter of the Token Post 568 response message defined in Section 5.10.1. of 569 [I-D.ietf-ace-oauth-authz]. This parameter contains information and 570 parameters about the signature algorithm and the public keys to be 571 used between the Client and the RS. Its exact content is application 572 specific. 574 In this specification and in application profiles building on it, 575 this parameter is used to ask and retrieve from the KDC information 576 about the signature algorithm and related parameters used in the 577 group. 579 When used in the request, the 'sign_info' encodes the CBOR simple 580 value Null, to require information and parameters on the signature 581 algorithm and on the public keys used. 583 The CDDL notation [RFC8610] of the 'sign_info' parameter formatted as 584 in the request is given below. 586 sign_info_req = nil 588 The 'sign_info' parameter of the 2.01 (Created) response is a CBOR 589 array of one or more elements. The number of elements is at most the 590 number of groups that the client has been authorized to join. Each 591 element contains information about signing parameters and keys for 592 one or more group or topic, and is formatted as follows. 594 o The first element 'id' is a group name or an array of group names, 595 associated to groups for which the next four elements apply. In 596 the following, each specified group name is referred to as 597 'gname'. 599 o The second element 'sign_alg' is an integer or a text string if 600 the POST request included the 'sign_info' parameter with value 601 Null, and indicates the signature algorithm used in the groups 602 identified by the 'gname' values. It is REQUIRED of the 603 application profiles to define specific values that this parameter 604 can take (REQ3), selected from the set of signing algorithms of 605 the COSE Algorithms registry [COSE.Algorithms]. 607 o The third element 'sign_parameters' is a CBOR array indicating the 608 parameters of the signature algorithm used in the groups 609 identified by the 'gname' values. Its content depends on the 610 value of 'sign_alg'. It is REQUIRED of the application profiles 611 to define the possible values and structure for the elements of 612 this parameter (REQ4). 614 o The fourth element 'sign_key_parameters' is a CBOR array 615 indicating the parameters of the key used with the signature 616 algorithm, in the groups identified by the 'gname' values. Its 617 content depends on the value of 'sign_alg'. It is REQUIRED of the 618 application profiles to define the possible values and structure 619 for the elements of this parameter (REQ5). 621 o The fifth element 'pub_key_enc' parameter is either a CBOR integer 622 indicating the encoding of public keys used in the groups 623 identified by the 'gname' values, or has value Null indicating 624 that the KDC does not act as repository of public keys for group 625 members. Its acceptable values are taken from the "CWT 626 Confirmation Method" Registry defined in [RFC8747]. It is 627 REQUIRED of the application profiles to define specific values to 628 use for this parameter (REQ6). 630 The CDDL notation [RFC8610] of the 'sign_info' parameter formatted as 631 in the response is given below. 633 sign_info_res = [ + sign_info_entry ] 635 sign_info_entry = 636 [ 637 id : gname / [ + gname ], 638 sign_alg : int / tstr, 639 sign_parameters : [ any ], 640 sign_key_parameters : [ any ], 641 pub_key_enc = int / nil 642 ] 644 gname = tstr 646 3.3.2. 'kdcchallenge' Parameter 648 The 'kdcchallenge' parameter is an OPTIONAL parameter of the Token 649 Post response message defined in Section 5.10.1 of 650 [I-D.ietf-ace-oauth-authz]. This parameter contains a challenge 651 generated by the KDC and provided to the Client. The Client may use 652 this challenge to prove possession of its own private key in the 653 Joining Request (see the 'client_cred_verify' parameter in 654 Section 4). 656 4. Keying Material Provisioning and Group Membership Management 658 This section defines the interface available at the KDC. Moreover, 659 this section specifies how the clients can use this interface to join 660 a group, leave a group, retrieve the group policies or the group 661 keying material. 663 During the first exchange with the KDC ("Joining") after posting the 664 Token, the Client sends a request to the KDC, specifying the group it 665 wishes to join (see Section 4.3). Then, the KDC verifies the access 666 token and that the Client is authorized to join that group. If so, 667 it provides the Client with the keying material to securely 668 communicate with the other members of the group. 670 When the Client is already a group member, the Client can use the 671 interface at the KDC to perform the following actions: 673 o The Client can get the current keying material, for cases such as 674 expiration, loss or suspected mismatch, due to e.g. reboot or 675 missed group rekeying. This is described in Section 4.4. 677 o The Client can retrieve new keying material for itself. This is 678 described in Section 4.5. 680 o The Client can get the public keys of other group members. This 681 is described in Section 4.6. 683 o The Client can upload a new, updated public key at the KDC. This 684 is described in Section 4.7. 686 o The Client can get the group policies. This is described in 687 Section 4.8. 689 o The Client can get the version number of the keying material 690 currently used in the group. This is described in Section 4.9. 692 o The Client can request to leave the group. This is further 693 discussed in Section 4.10. 695 Upon receiving a request from a Client, the KDC MUST check that it is 696 storing a valid access token from that Client for the group name 697 associated to the endpoint. If that is not the case, i.e. the KDC 698 does not store a valid access token or this is not valid for that 699 Client for the group name, the KDC MUST respond to the Client with a 700 4.01 (Unauthorized) error message. 702 If they include a payload and specify a Content-Format, requests sent 703 to the KDC and success responses from the KDC MUST have Content- 704 Format set to application/ace-groupcomm+cbor, defined in 705 Section 10.2. 707 Some error responses from the KDC can have Content-Format set to 708 application/ace-groupcomm+cbor. In such a case, the paylod of the 709 response MUST be a CBOR map, which includes the following fields. 711 o 'error', with value a CBOR integer specifying the error occurred 712 at the KDC. The value is taken from the "Value" column of the 713 "ACE Groupcomm Errors" registry defined in Section 10.13 of this 714 specification. This field MUST be present. 716 o 'error_description', with value a CBOR text string specifying a 717 human-readable description of the error occurred at the KDC. This 718 field MAY be present. 720 CBOR labels for the 'error' and 'error_description' fields are 721 defined in Section 7. 723 Section 8 of this specification defines an initial set of error 724 identifiers, as possible values for the 'error' field. Application 725 profiles of this specification MAY define additional value (OPT12). 727 4.1. Interface at the KDC 729 The KDC is configured with the following resources. Note that the 730 root url-path "ace-group" given here are default names: 731 implementations are not required to use these names, and can define 732 their own instead. Each application profile of this specification 733 MUST register a Resource Type for the root url-path (REQ7), and that 734 Resource Type can be used to discover the correct url to access at 735 the KDC. This Resource Type can also be used at the GROUPNAME sub- 736 resource, to indicate different application profiles for different 737 groups. The Interface Description (if=) Link Target Attribute value 738 ace.group is registered (Section 10.10) and can be used to describe 739 this interface. 741 o /ace-group: this resource is invariant once established and 742 indicates that this specification is used. If other applications 743 run on a KDC implementing this specification and use this same 744 resource, these applications will collide, and a mechanism will be 745 needed to differentiate the endpoints. This resource supports the 746 FETCH method. 748 o /ace-group/GROUPNAME: one sub-resource to /ace-group is 749 implemented for each group the KDC manages. 751 If the value of the GROUPNAME URI path and the group name in the 752 access token scope ('gname' in Section 3.2) do not match, the KDC 753 MUST implement a mechanism to map the GROUPNAME value in the URI 754 to the group name, in order to retrieve the right group (REQ1). 755 Each resource contains the symmetric group keying material for 756 that group. These resources support the GET and POST methods. 758 o /ace-group/GROUPNAME/pub-key: this resource is invariant once 759 established and contains the public keys of all group members. 760 This resource supports the GET and FETCH methods. 762 o /ace-group/GROUPNAME/policies: this resource is invariant once 763 established and contains the group policies. This resource 764 supports the GET method. 766 o /ace-group/GROUPNAME/num: this resource is invariant once 767 established and contains the version number for the symmetric 768 group keying material. This sub-resource supports the GET method. 770 o /ace-group/GROUPNAME/nodes/NODENAME: one sub-resource to /ace- 771 group/GROUPNAME is implemented for each node in the group the KDC 772 manages. These resources are identified by the node name (in this 773 example, the node name has value "NODENAME"). Each resource 774 contains the group and individual keying material for that node. 775 These resources support the GET, PUT and DELETE methods. 777 o /ace-group/GROUPNAME/nodes/NODENAME/pub-key: one sub-resource to 778 /ace-group/GROUPNAME/nodes/NODENAME is implemented for each node 779 in the group the KDC manages. These resources are identified by 780 the node name (in this example, the node name has value 781 "NODENAME"). Each resource contains the individual public keying 782 material for that node. These resources support the POST method. 784 It is REQUIRED of the application profiles of this specification to 785 define what operations (e.g. CoAP methods) are allowed on each 786 resource, for each role defined in Section 3.1 according to REQ2 787 (REQ8). 789 The details for the handlers of each resource are given in the 790 following sections. These endpoints are used to perform the 791 operations introduced in Section 4. 793 4.1.1. ace-group 795 This resource implements a FETCH handler. 797 4.1.1.1. FETCH Handler 799 The FETCH handler receives group identifiers and returns the 800 corresponding group names and GROUPNAME URIs. 802 The handler expects a request with payload formatted as a CBOR map, 803 which MUST contain the following fields: 805 o 'gid', whose value is encoded as a CBOR array, containing one or 806 more group identifiers. The exact encoding of group identifier 807 MUST be specified by the application profile (REQ9). The Client 808 indicates that it wishes to receive the group names and GROUPNAMEs 809 of all groups having these identifiers. 811 The handler identifies the groups that are secured by the keying 812 material identified by those group identifiers. 814 Then, the handler returns a 2.05 (Content) message response with 815 payload formatted as a CBOR map that MUST contain the following 816 fields: 818 o 'gid', whose value is encoded as a CBOR array, containing zero or 819 more group identifiers. The handler indicates that those are the 820 identifiers it is sending group names and GROUPNAMEs for. This 821 CBOR array is a subset of the 'gid' array in the FETCH request. 823 o 'gname', whose value is encoded as a CBOR array, containing zero 824 or more group names. The elements of this array are encoded as 825 text strings. Each element of index i of this CBOR array 826 corresponds to the element of group identifier i in the 'gid' 827 array. 829 o 'guri', whose value is encoded as a CBOR array, containing zero or 830 more URIs, each indicating a GROUPNAME resource. The elements of 831 this array are encoded as text strings. Each element of index i 832 of this CBOR array corresponds to the element of group identifier 833 i in the 'gid' array. 835 If the KDC does not find any group associated with the specified 836 group identifiers, the handler returns a response with payload 837 formatted as a CBOR byte string of zero length. 839 Note that the KDC only verifies that the node is authorized by the AS 840 to access this resource. Nodes that are not members of the group but 841 are authorized to do signature verification on the group messages may 842 be allowed to access this resource, if the application needs it. 844 4.1.2. ace-group/GROUPNAME 846 This resource implements GET and POST handlers. 848 4.1.2.1. POST Handler 850 The POST handler adds the public key of the client to the list of the 851 group members' public keys and returns the symmetric group keying 852 material for the group identified by "GROUPNAME". Note that the 853 group joining exchange is done by the client via this operation, as 854 described in Section 4.3. 856 The handler expects a request with payload formatted as a CBOR map, 857 which MAY contain the following fields, which, if included, MUST have 858 the corresponding values: 860 o 'scope', with value the specific resource at the KDC that the 861 Client is authorized to access, i.e. group or topic name, and 862 role(s). This value is a CBOR byte string wrapping one scope 863 entry, as defined in Section 3.1. 865 o 'get_pub_keys', if the Client wishes to receive the public keys of 866 the other nodes in the group from the KDC. This parameter may be 867 present if the KDC stores the public keys of the nodes in the 868 group and distributes them to the Client; it is useless to have 869 here if the set of public keys of the members of the group is 870 known in another way, e.g. it was provided by the AS. Note that 871 including this parameter may result in a large message size for 872 the following response, which can be inconvenient for resource- 873 constrained devices. 875 The parameter's value is either the CBOR simple value Null, or a 876 non-empty CBOR array containing the following three elements. 878 * The first element, namely 'inclusion_flag', encodes the CBOR 879 simple value True. 881 * The second element, namely 'role_filter', is a non-empty CBOR 882 array. Each element of the array contains one role or a 883 combination of roles for the group identified by "GROUPNAME". 884 The Client indicates that it wishes to receive the public keys 885 of all group members having any of the single roles, or at 886 least all of the roles indicated in any combination of roles. 887 For example, the array ["role1", "role2+role3"] indicates that 888 the Client wishes to receive the public keys of all group 889 members that have at least "role1" or at least both "role2" and 890 "role3". 892 * The third element, namely 'id_filter', is an empty CBOR array. 894 If the Client wishes to receive all public keys of all group 895 members, it encodes the 'get_pub_key' parameter as the CBOR simple 896 value Null. 898 The CDDL definition [RFC8610] of 'get_pub_keys' is given in 899 Figure 6, using as example encoding: node identifier encoded as a 900 CBOR byte string; role identifier encoded as a CBOR text string, 901 and combination of roles encoded as a CBOR array of roles. 903 Note that the array of roles 'role_filter' is non-empty for this 904 handler, but this is not necessarily the case for other handlers 905 using this parameter: if this array is empty, it means that the 906 client is not filtering public keys based on roles. 908 Also note that the array of node identifiers 'id_filter' is empty 909 for this handler, because the joining node is not expected or 910 capable to express a filter based on node identifiers at this 911 point in time. Consistently, the 'inclusion_flag' element is set 912 to the CBOR simple value True. However, the 'id_filter' array is 913 not necessarily empty for the value of 'get_pub_keys' received by 914 the handler of FETCH to ace-group/GROUPNAME/pub-key (see 915 Section 4.1.3.1). 917 Finally, the 'get_pub_keys' parameter MUST NOT have the arrays 918 'role_filter' and 'id_filter' as both empty, i.e. in CBOR 919 diagnostic notation: [ bool, [ ], [ ] ]. Thus, if this parameter 920 is received as formatted in that way, it has to be considered 921 malformed. 923 id = bstr 925 role = tstr 927 comb_role = [ 2*role ] 929 inclusion = bool 931 get_pub_keys = null / [ [ inclusion, *(role / comb_role) ], [ *id ] ] 933 Figure 6: CDLL definition of get_pub_keys, using as example node 934 identifier encoded as bstr and role as tstr 936 o 'client_cred', with value the public key or certificate of the 937 Client, encoded as a CBOR byte string. This field contains the 938 public key of the Client. This field is used if the KDC is 939 managing (collecting from/distributing to the Client) the public 940 keys of the group members, and if the Client's role in the group 941 will require for it to send messages to one or more group members. 942 The default encoding for public keys is COSE Keys. Alternative 943 specific encodings of this parameter MAY be defined in 944 applications of this specification (OPT1 in Appendix A). 946 o 'cnonce', encoded as a CBOR byte string, and including a dedicated 947 nonce N_C generated by the Client. This parameter MUST be present 948 if the 'client_cred' parameter is present. 950 o 'client_cred_verify', encoded as a CBOR byte string. This 951 parameter MUST be present if the 'client_cred' parameter is 952 present and no public key associated to the client's token can be 953 retrieved for that group. This parameter contains a signature 954 computed by the Client over the following signature input: the 955 scope (encoded as CBOR byte string), concatenated with N_S 956 (encoded as CBOR byte string) concatenated with N_C (encoded as 957 CBOR byte string), where: 959 * scope is the CBOR byte string either specified in the 'scope' 960 parameter above, if present, or as a default scope that the 961 handler is expected to understand, if omitted. 963 * N_S is the challenge received from the KDC in the 964 'kdcchallenge' parameter of the 2.01 (Created) response to the 965 token POST request (see Section 3.3), encoded as a CBOR byte 966 string. 968 * N_C is the nonce generated by the Client and specified in the 969 'cnonce' parameter above, encoded as a CBOR byte string. 971 An example of signature input construction to compute 972 'client_cred_verify' using CBOR encoding is given in Figure 7. 974 If the token was not posted (e.g. if it is used directly to 975 validate TLS instead), it is REQUIRED of the specific profile to 976 define how the challenge N_S is generated (REQ20). The Client 977 computes the signature by using its own private key, whose 978 corresponding public key is either directly specified in the 979 'client_cred' parameter or included in the certificate specified 980 in the 'client_cred' parameter. 982 o 'pub_keys_repos', can be present if a certificate is present in 983 the 'client_cred' field, with value the URI of the certificate of 984 the Client. This parameter is encoded as a CBOR text string. 985 Alternative specific encodings of this parameter MAY be defined in 986 applications of this specification (OPT4). 988 o 'control_uri', with value a full URI, encoded as a CBOR text 989 string. If 'control_uri' is supported by the Client, the Client 990 acts as a CoAP server and hosts a resource at this specific URI. 991 The KDC MAY use this URI to send CoAP requests to the Client 992 (acting as CoAP server in this exchange), for example for 993 individual provisioning of new keying material when performing a 994 group rekeying (see Section 4.4), or to inform the Client of its 995 removal from the group Section 5. If the KDC does not implement 996 mechanisms using this resource, it can just ignore this parameter. 997 Other additional functionalities of this resource MAY be defined 998 in application profiles of this specifications (OPT10). In 999 particular, this resource is intended for communications 1000 concerning exclusively the group or topic specified in the 'scope' 1001 parameter. 1003 scope, N_S, and N_C expressed in CBOR diagnostic notation: 1004 scope = h'826667726F7570316673656E646572' 1005 N_S = h'018a278f7faab55a' 1006 N_C = h'25a8991cd700ac01' 1008 scope, N_S, and N_C as CBOR encoded byte strings: 1009 scope = 0x4f826667726F7570316673656E646572 1010 N_S = 0x48018a278f7faab55a 1011 N_C = 0x4825a8991cd700ac01 1013 input to client_cred_verify signature = 1014 0x4f 826667726F7570316673656E646572 1015 48 018a278f7faab55a 48 25a8991cd700ac01 1017 Figure 7: Example of signature input construction to compute 1018 'client_cred_verify' using CBOR encoding 1020 The handler extracts the granted scope from the access token, and 1021 checks the requested one against the token one. If the requested one 1022 is not a subset of the token one, the KDC MUST respond with a 4.01 1023 (Unauthorized) error message. 1025 If the request does not include a 'scope' field, the KDC is expected 1026 to understand which group and role(s) the Client is requesting (e.g. 1027 there is only one the Client has been granted). If the KDC can not 1028 recognize which scope the Client is requesting, it MUST respond with 1029 a 4.00 (Bad Request) error message. 1031 The KDC verifies that the group name of the /ace-group/GROUPNAME path 1032 is a subset of the 'scope' stored in the access token associated to 1033 this client. The KDC also verifies that the roles the client is 1034 granted in the group allow it to perform this operation on this 1035 resource (REQ8). If either verification fails, the KDC MUST respond 1036 with a 4.01 (Unauthorized) error message. This response MAY be an AS 1037 Request Creation Hints, as defined in Section 5.3 of 1038 [I-D.ietf-ace-oauth-authz], in which case the content format MUST be 1039 set to application/ace+cbor. 1041 If the request is not formatted correctly (i.e. required fields non 1042 received or received with incorrect format), the handler MUST respond 1043 with a 4.00 (Bad Request) error message. The response MAY have 1044 Content-Format set to application/ace+cbor and have a CBOR map as 1045 payload. For instance, the CBOR map can include the 'sign_info_res' 1046 parameter, with 'pub_key_enc' set to Null if the Client sent its own 1047 public key and the KDC is not set to store public keys of the group 1048 members. 1050 If the request contained unknown or non-expected fields present, the 1051 handler MUST silently drop them and continue processing. Application 1052 profiles MAY define optional or mandatory payload formats for 1053 specific error cases (OPT7). 1055 If the KDC stores the group members' public keys, the handler checks 1056 if one is included in the 'client_cred' field, retrieves it and 1057 associates it to the access token received, after verifications 1058 succeeded. In particular, the KDC verifies: 1060 o that such public key has an acceptable format for the group 1061 identified by "GROUPNAME", i.e. it is encoded as expected and is 1062 compatible with the signature algorithm and possible associated 1063 parameters. 1065 o that the signature contained in "client_cred_verify" passes 1066 verification. 1068 If that cannot be verified, it is RECOMMENDED that the handler stops 1069 the process and responds with a 4.00 (Bad Request) error message. 1070 Applications profiles MAY define alternatives (OPT6). 1072 If one public key is already associated to the access token and to 1073 that group, but the 'client_cred' is populated with a different 1074 public key, the handler MUST delete the previous one and replace it 1075 with this one, after verifying the points above. 1077 If no public key is included in the 'client_cred' field, the handler 1078 checks if one public key is already associated to the access token 1079 received (see Section 4.3 for an example) and to the group identified 1080 by "GROUPNAME". If that is not the case, the handler responds with a 1081 4.00 Bad Request error response. 1083 If the token was posted but the KDC cannot retrieve the 1084 'kdcchallenge' associated to this Client (see Section 3.3), the KDC 1085 MUST respond with a 4.00 Bad Request error response, including a 1086 newly generated 'kdcchallenge' in a CBOR map in the payload. This 1087 error response MUST also have Content-Format application/ace+cbor. 1089 If all verifications succeed, the handler: 1091 o Adds the node to the list of current members of the group. 1093 o Assigns a name NODENAME to the node, and creates a sub-resource to 1094 /ace-group/GROUPNAME/ at the KDC (e.g. "/ace- 1095 group/GROUPNAME/nodes/NODENAME"). 1097 o Associates the identifier "NODENAME" with the access token and the 1098 secure session for that node. 1100 o If the KDC manages public keys for group members: 1102 * Adds the retrieved public key of the node to the list of public 1103 keys stored for the group identified by "GROUPNAME" 1105 * Associates the node's public key with its access token and the 1106 group identified by "GROUPNAME", if such association did not 1107 already exist. 1109 o Returns a 2.01 (Created) message containing the symmetric group 1110 keying material, the group policies and all the public keys of the 1111 current members of the group, if the KDC manages those and the 1112 Client requested them. 1114 The response message also contains the URI path to the sub-resource 1115 created for that node in a Location-Path CoAP option. The payload of 1116 the response is formatted as a CBOR map which MUST contain the 1117 following fields and values: 1119 o 'gkty', identifying the key type of the 'key' parameter. The set 1120 of values can be found in the "Key Type" column of the "ACE 1121 Groupcomm Key" Registry. Implementations MUST verify that the key 1122 type matches the application profile being used, if present, as 1123 registered in the "ACE Groupcomm Key" registry. 1125 o 'key', containing the keying material for the group communication, 1126 or information required to derive it. 1128 o 'num', containing the version number of the keying material for 1129 the group communication, formatted as an integer. This is a 1130 strictly monotonic increasing field. The application profile MUST 1131 define the initial version number (REQ22). 1133 The exact format of the 'key' value MUST be defined in applications 1134 of this specification (REQ10), as well as values of 'gkty' accepted 1135 by the application (REQ11). Additionally, documents specifying the 1136 key format MUST register it in the "ACE Groupcomm Key" registry 1137 defined in Section 10.6, including its name, type and application 1138 profile to be used with. 1140 +----------+----------------+---------+-------------------------+ 1141 | Name | Key Type Value | Profile | Description | 1142 +----------+----------------+---------+-------------------------+ 1143 | Reserved | 0 | | This value is reserved | 1144 +----------+----------------+---------+-------------------------+ 1146 Figure 8: Key Type Values 1148 The response SHOULD contain the following parameter: 1150 o 'exp', with value the expiration time of the keying material for 1151 the group communication, encoded as a CBOR unsigned integer. This 1152 field contains a numeric value representing the number of seconds 1153 from 1970-01-01T00:00:00Z UTC until the specified UTC date/time, 1154 ignoring leap seconds, analogous to what specified for NumericDate 1155 in Section 2 of [RFC7519]. Group members MUST stop using the 1156 keying material to protect outgoing messages and retrieve new 1157 keying material at the time indicated in this field. 1159 Optionally, the response MAY contain the following parameters, which, 1160 if included, MUST have the corresponding values: 1162 o 'ace-groupcomm-profile', with value a CBOR integer that MUST be 1163 used to uniquely identify the application profile for group 1164 communication. Applications of this specification MUST register 1165 an application profile identifier and the related value for this 1166 parameter in the "ACE Groupcomm Profile" Registry (REQ15). 1168 o 'pub_keys', MUST be present if 'get_pub_keys' was present in the 1169 request, otherwise it MUST NOT be present. This parameter is a 1170 CBOR byte string, which encodes the public keys of all the group 1171 members paired with the respective member identifiers. The 1172 default encoding for public keys is COSE Keys, so the default 1173 encoding for 'pub_keys' is a CBOR byte string wrapping a 1174 COSE_KeySet (see [I-D.ietf-cose-rfc8152bis-struct]), which 1175 contains the public keys of all the members of the group. In 1176 particular, each COSE Key in the COSE_KeySet includes the node 1177 identifier of the corresponding group member as value of its 'kid' 1178 key parameter. Alternative specific encodings of this parameter 1179 MAY be defined in applications of this specification (OPT1). The 1180 specific format of the node identifiers of group members MUST be 1181 specified in the application profile (REQ12). 1183 o 'peer_roles', MUST be present if 'pub_keys' is also present, 1184 otherwise it MUST NOT be present. This parameter is a CBOR array 1185 of n elements, with n the number of public keys included in the 1186 'pub_keys' parameter (at most the number of members in the group). 1187 The i-th element of the array specifies the role (or CBOR array of 1188 roles) that the group member associated to the i-th public key in 1189 'pub_keys' has in the group. In particular, each array element is 1190 encoded as the role element of a scope entry, as defined in 1191 Section 3.1. 1193 o 'peer_identifiers', MUST be present if 'pub_keys' is also present 1194 and, at the same time, the used encoding for public keys does not 1195 allow to specify a node identifier within the associated public 1196 key. Otherwise, it MUST NOT be present. This parameter is a CBOR 1197 array of n elements, with n the number of public keys included in 1198 the 'pub_keys' parameter (at most the number of members in the 1199 group). The i-th element of the array specifies the node 1200 identifier that the group member associated to the i-th public key 1201 in 'pub_keys' has in the group. In particular, the i-th array 1202 element is encoded as a CBOR byte string wrapping the node 1203 identifier of the group member. 1205 o 'group_policies', with value a CBOR map, whose entries specify how 1206 the group handles specific management aspects. These include, for 1207 instance, approaches to achieve synchronization of sequence 1208 numbers among group members. The elements of this field are 1209 registered in the "ACE Groupcomm Policy" Registry. This 1210 specification defines the three elements "Sequence Number 1211 Synchronization Method", "Key Update Check Interval" and 1212 "Expiration Delta", which are summarized in Figure 9. Application 1213 profiles that build on this document MUST specify the exact 1214 content format and default value of included map entries (REQ17). 1216 +--------------+-------+----------|---------------------|------------+ 1217 | Name | CBOR | CBOR | Description | Reference | 1218 | | label | type | | | 1219 |--------------+-------+----------|---------------------|------------| 1220 | Sequence | TBD1 | tstr/int | Method for a re- | [[this | 1221 | Number | | | cipient node to | document]] | 1222 | Synchroniza- | | | synchronize with | | 1223 | tion Method | | | sequence numbers | | 1224 | | | | of a sender node. | | 1225 | | | | Its value is taken | | 1226 | | | | from the 'Value' | | 1227 | | | | column of the | | 1228 | | | | Sequence Number | | 1229 | | | | Synchronization | | 1230 | | | | Method registry | | 1231 | | | | | | 1232 | Key Update | TBD2 | int | Polling interval | [[this | 1233 | Check | | | in seconds, to | document]] | 1234 | Interval | | | check for new | | 1235 | | | | keying material at | | 1236 | | | | the KDC | | 1237 | | | | | | 1238 | Expiration | TBD3 | uint | Number of seconds | [[this | 1239 | Delta | | | from 'exp' until | document]] | 1240 | | | | the specified UTC | | 1241 | | | | date/time after | | 1242 | | | | which group members | | 1243 | | | | MUST stop using the | | 1244 | | | | keying material to | | 1245 | | | | verify incoming | | 1246 | | | | messages. | | 1247 +--------------+-------+----------|---------------------|------------+ 1249 Figure 9: ACE Groupcomm Policies 1251 o 'mgt_key_material', encoded as a CBOR byte string and containing 1252 the administrative keying material to participate in the group 1253 rekeying performed by the KDC. The application profile MUST 1254 define if this field is used, and if used then MUST specify the 1255 exact format and content which depend on the specific rekeying 1256 scheme used in the group. If the usage of 'mgt_key_material' is 1257 indicated and its format defined for a specific key management 1258 scheme, that format must explicitly indicate the key management 1259 scheme itself. If a new rekeying scheme is defined to be used for 1260 an existing 'mgt_key_material' in an existing profile, then that 1261 profile will have to be updated accordingly, especially with 1262 respect to the usage of 'mgt_key_material' related format and 1263 content (REQ21). 1265 Specific application profiles that build on this document MUST 1266 specify the communication protocol that members of the group use to 1267 communicate with each other (REQ13) and how exactly the keying 1268 material is used to protect the group communication (REQ14). 1270 CBOR labels for these fields are defined in Section 7. 1272 4.1.2.2. GET Handler 1274 The GET handler returns the symmetric group keying material for the 1275 group identified by "GROUPNAME". 1277 The handler expects a GET request. 1279 The KDC verifies that the group name of the /ace-group/GROUPNAME path 1280 is a subset of the 'scope' stored in the access token associated to 1281 this client. The KDC also verifies that the roles the client is 1282 granted in the group allow it to perform this operation on this 1283 resource (REQ8). If either verification fails, the KDC MUST respond 1284 with a 4.01 (Unauthorized) error message. This response MAY be an AS 1285 Request Creation Hints, as defined in Section 5.3 of 1286 [I-D.ietf-ace-oauth-authz], in which case the content format MUST be 1287 set to application/ace+cbor. 1289 Additionally, the handler verifies that the node is a current member 1290 of the group. If verification fails, the KDC MUST respond with a 1291 4.01 (Unauthorized) error message. The response MUST have Content- 1292 Format set to application/ace-groupcomm+cbor and is formatted as 1293 defined in Section 4. The value of the 'error' field MUST be set to 1294 0 ("Operation permitted only to group members"). 1296 If verification succeeds, the handler returns a 2.05 (Content) 1297 message containing the symmetric group keying material. The payload 1298 of the response is formatted as a CBOR map which MUST contain the 1299 parameters 'gkty', 'key' and 'num' specified in Section 4.1.2.1. 1301 The payload MAY also include the parameters 'ace-groupcomm-profile', 1302 'exp', and 'mgt_key_material' parameters specified in 1303 Section 4.1.2.1. 1305 4.1.3. ace-group/GROUPNAME/pub-key 1307 If the KDC does not maintain public keys for the group, the handler 1308 for any request on this resource returns a 4.05 (Method Not Allowed) 1309 error message. If it does, the rest of this section applies. 1311 This resource implements GET and FETCH handlers. 1313 4.1.3.1. FETCH Handler 1315 The FETCH handler receives identifiers of group members for the group 1316 identified by "GROUPNAME" and returns the public keys of such group 1317 members. 1319 The handler expects a request with payload formatted as a CBOR map, 1320 that MUST contain the following fields: 1322 o 'get_pub_keys', whose value is encoded as in Section 4.1.2.1 with 1323 the following modification: 1325 * The element 'inclusion_flag' encodes the CBOR simple value True 1326 if the third element 'id_filter' specifies an empty CBOR array, 1327 or if the Client wishes to receive the public keys of the nodes 1328 having their node identifier specified in 'id_filter'. 1329 Instead, this element encodes the CBOR simple value False if 1330 the Client wishes to receive the public keys of the nodes not 1331 having the node identifiers specified in the third element 1332 'id_filter'. 1334 * The array 'role_filter' may be empty, if the Client does not 1335 wish to filter the requested public keys based on the roles of 1336 the group members. 1338 * The array 'id_filter' contains zero or more node identifiers of 1339 group members, for the group identified by "GROUPNAME". The 1340 Client indicates that it wishes to receive the public keys of 1341 the nodes having or not having these node identifiers, in case 1342 the 'inclusion_flag' parameter encodes the CBOR simple value 1343 True or False, respectively. The array may be empty, if the 1344 Client does not wish to filter the requested public keys based 1345 on the node identifiers of the group members. 1347 Note that, in case both the 'role_filter' array and the 'id_filter' 1348 array are not empty: 1350 o If the 'inclusion_flag' encodes the CBOR simple value True, the 1351 handler returns the public keys of group members whose roles match 1352 with 'role_filter' and/or having their node identifier specified 1353 in 'id_filter'. 1355 o If the 'inclusion_flag' encodes the CBOR simple value False, the 1356 handler returns the public keys of group members whose roles match 1357 with 'role_filter' and, at the same time, not having their node 1358 identifier specified in 'id_filter'. 1360 Finally, as mentioned in Section 4.1.2.1, both arrays 'role_filter' 1361 and 'id_filter' MUST NOT be both empty. 1363 The specific format of public keys as well as identifiers, roles and 1364 combination of roles of group members MUST be specified by the 1365 application profile (OPT1, REQ2, REQ12). 1367 The KDC verifies that the group name of the /ace-group/GROUPNAME path 1368 is a subset of the 'scope' stored in the access token associated to 1369 this client. The KDC also verifies that the roles the client is 1370 granted in the group allow it to perform this operation on this 1371 resource (REQ8). If either verification fails, the KDC MUST respond 1372 with a 4.01 (Unauthorized) error message. 1374 If verification succeeds, the handler identifies the public keys of 1375 the current group members for which either: 1377 o the role identifier matches with one of those indicated in the 1378 request; note that the request can contain a "combination of 1379 roles", where the handler select all group members who have all 1380 roles included in the combination. 1382 o the node identifier matches with one of those indicated in the 1383 request. 1385 Then, the handler returns a 2.05 (Content) message response with 1386 payload formatted as a CBOR map, containing only the 'pub_keys' and 1387 'peer_roles' parameters from Section 4.1.2.1. In particular, 1388 'pub_keys' encodes the list of public keys of those group members 1389 including the respective member identifiers, while 'peer_roles' 1390 encodes their respective role (or CBOR array of roles) in the group. 1391 The specific format of public keys as well as of node identifiers of 1392 group members is specified by the application profile (OPT1, REQ12). 1394 If the used encoding for public keys does not allow to specify a node 1395 identifier within the associated public key, the response payload 1396 MUST include also the 'peer_identifiers' parameter from 1397 Section 4.1.2.1. Otherwise, this parameter MUST NOT be included. 1399 If the KDC does not store any public key associated with the 1400 specified node identifiers, the handler returns a response with 1401 payload formatted as a CBOR byte string of zero length. 1403 The handler MAY enforce one of the following policies, in order to 1404 handle possible node identifiers that are included in the 'id_filter' 1405 element of the 'get_pub_keys' parameter of the request but are not 1406 associated to any current group member. Such a policy MUST be 1407 specified by the application profile (REQ16). 1409 o The KDC silently ignores those node identifiers. 1411 o The KDC retains public keys of group members for a given amount of 1412 time after their leaving, before discarding them. As long as such 1413 public keys are retained, the KDC provides them to a requesting 1414 Client. 1416 Note that this resource handler only verifies that the node is 1417 authorized by the AS to access this resource. Nodes that are not 1418 members of the group but are authorized to do signature verifications 1419 on the group messages may be allowed to access this resource, if the 1420 application needs it. 1422 4.1.3.2. GET Handler 1424 The handler expects a GET request. 1426 The KDC performs the same verifications as the FETCH handler in 1427 Section 4.1.3.1, and if successful returns the same response as in 1428 Section 4.1.3.1 but without filtering based on roles or node 1429 identifiers: all the group members' public keys are returned. 1431 Note that this resource handler, as the FETCH handler for the same 1432 resource, only verifies that the node is authorized by the AS to 1433 access this resource. Nodes that are not members of the group but 1434 are authorized to do signature verifications on the group messages 1435 may be allowed to access this resource, if the application needs it. 1437 4.1.4. ace-group/GROUPNAME/policies 1439 This resource implements a GET handler. 1441 4.1.4.1. GET Handler 1443 The handler expects a GET request. 1445 The KDC verifies that the group name of the /ace-group/GROUPNAME path 1446 is a subset of the 'scope' stored in the access token associated to 1447 this client. The KDC also verifies that the roles the client is 1448 granted in the group allow it to perform this operation on this 1449 resource (REQ8). If either verification fails, the KDC MUST respond 1450 with a 4.01 (Unauthorized) error message. 1452 Additionally, the handler verifies that the node is a current member 1453 of the group. If verification fails, the KDC MUST respond with a 1454 4.01 (Unauthorized) error message. The response MUST have Content- 1455 Format set to application/ace-groupcomm+cbor and is formatted as 1456 defined in Section 4. The value of the 'error' field MUST be set to 1457 0 ("Operation permitted only to group members"). 1459 If verification succeeds, the handler returns a 2.05 (Content) 1460 message containing the list of policies for the group identified by 1461 "GROUPNAME". The payload of the response is formatted as a CBOR map 1462 including only the parameter 'group_policies' defined in 1463 Section 4.1.2.1 and specifying the current policies in the group. If 1464 the KDC does not store any policy, the payload is formatted as a 1465 zero-length CBOR byte string. 1467 The specific format and meaning of group policies MUST be specified 1468 in the application profile (REQ17). 1470 4.1.5. ace-group/GROUPNAME/num 1472 This resource implements a GET handler. 1474 4.1.5.1. GET Handler 1476 The handler expects a GET request. 1478 The KDC verifies that the group name of the /ace-group/GROUPNAME path 1479 is a subset of the 'scope' stored in the access token associated to 1480 this client. The KDC also verifies that the roles the client is 1481 granted in the group allow it to perform this operation on this 1482 resource (REQ8). If either verification fails, the KDC MUST respond 1483 with a 4.01 (Unauthorized) error message. 1485 Additionally, the handler verifies that the node is a current member 1486 of the group. If verification fails, the KDC MUST respond with a 1487 4.01 (Unauthorized) error message. The response MUST have Content- 1488 Format set to application/ace-groupcomm+cbor and is formatted as 1489 defined in Section 4. The value of the 'error' field MUST be set to 1490 0 ("Operation permitted only to group members"). 1492 If verification succeeds, the handler returns a 2.05 (Content) 1493 message containing an integer that represents the version number of 1494 the symmetric group keying material. This number is incremented on 1495 the KDC every time the KDC updates the symmetric group keying 1496 material, before the new keying material is distributed. This number 1497 is stored in persistent storage. 1499 The payload of the response is formatted as a CBOR integer. 1501 4.1.6. ace-group/GROUPNAME/nodes/NODENAME 1503 This resource implements GET, PUT and DELETE handlers. 1505 4.1.6.1. PUT Handler 1507 The PUT handler is used to get the KDC to produce and return 1508 individual keying material to protect outgoing messages for the node 1509 (identified by "NODENAME") for the group identified by "GROUPNAME". 1510 Application profiles MAY also use this handler to rekey the whole 1511 group. It is up to the application profiles to specify if this 1512 handler supports renewal of individual keying material, renewal of 1513 the group keying material or both (OPT9). 1515 The handler expects a request with empty payload. In case the 1516 request has a non-empty payload, the KDC MUST respond with a 4.00 1517 (Bad Request) error message. 1519 The KDC verifies that the group name of the /ace-group/GROUPNAME path 1520 is a subset of the 'scope' stored in the access token associated to 1521 the client identified by "NODENAME". The KDC also verifies that the 1522 roles the client is granted in the group allow it to perform this 1523 operation on this resource (REQ8). If either verification fails, the 1524 KDC MUST respond with a 4.01 (Unauthorized) error message. 1526 The handler also verifies that the node sending the request and the 1527 node name used in the Uri-Path match. If that is not the case, the 1528 handler responds with a 4.01 (Unauthorized) error response. 1530 Additionally, the handler verifies that the node is a current member 1531 of the group. If the verification fails, the KDC MUST respond with a 1532 4.01 (Unauthorized) error message. The response MUST have Content- 1533 Format set to application/ace-groupcomm+cbor and is formatted as 1534 defined in Section 4. The value of the 'error' field MUST be set to 1535 0 ("Operation permitted only to group members"). 1537 Also, the handler verifies that this operation is consistent with the 1538 set of roles that the node has in the group. If the verification 1539 fails, the KDC MUST respond with a 4.00 (Bad Request) error message. 1540 The response MUST have Content-Format set to application/ace- 1541 groupcomm+cbor and is formatted as defined in Section 4. The value 1542 of the 'error' field MUST be set to 1 ("Request inconsistent with the 1543 current roles"). 1545 If the KDC is currently not able to serve this request, i.e. to 1546 generate new individual keying material for the requesting client, 1547 the KDC MUST respond with a 5.03 (Service Unavailable) error message. 1548 The response MUST have Content-Format set to application/ace- 1549 groupcomm+cbor and is formatted as defined in Section 4. The value 1550 of the 'error' field MUST be set to 4 ("No available node 1551 identifiers"). 1553 If all verifications succeed, the handler returns a 2.05 (Content) 1554 message containing newly-generated keying material for the Client, 1555 and/or, if the application profiles requires it (OPT9), starts the 1556 complete group rekeying. The payload of the response is formatted as 1557 a CBOR map. The specific format of newly-generated individual keying 1558 material for group members, or of the information to derive it, and 1559 corresponding CBOR label, MUST be specified in the application 1560 profile (REQ18) and registered in Section 10.5. 1562 4.1.6.2. GET Handler 1564 The handler expects a GET request. 1566 The KDC verifies that the group name of the /ace-group/GROUPNAME path 1567 is a subset of the 'scope' stored in the access token associated to 1568 the client identified by "NODENAME". The KDC also verifies that the 1569 roles the client is granted in the group allow it to perform this 1570 operation on this resource (REQ8). If either verification fails, the 1571 KDC MUST respond with a 4.01 (Unauthorized) error message. 1573 The handler also verifies that the node sending the request and the 1574 node name used in the Uri-Path match. If that is not the case, the 1575 handler responds with a 4.01 (Unauthorized) error response. 1577 Additionally, the handler verifies that the node is a current member 1578 of the group. If verification fails, the KDC MUST respond with a 1579 4.01 (Unauthorized) error message. The response MUST have Content- 1580 Format set to application/ace-groupcomm+cbor and is formatted as 1581 defined in Section 4. The value of the 'error' field MUST be set to 1582 0 ("Operation permitted only to group members"). 1584 If verification succeeds, the handler returns a 2.05 (Content) 1585 message containing both the group keying material and the individual 1586 keying material for the Client, or information enabling the Client to 1587 derive it. The payload of the response is formatted as a CBOR map. 1588 The format for the group keying material is the same as defined in 1589 the response of Section 4.1.2.2. The specific format of individual 1590 keying material for group members, or of the information to derive 1591 it, and corresponding CBOR label, MUST be specified in the 1592 application profile (REQ18) and registered in Section 10.5. 1594 Optionally, the KDC can make the sub-resource at ace- 1595 group/GROUPNAME/nodes/NODENAME also Observable [RFC7641] for the 1596 associated node. In case the KDC removes that node from the group 1597 without having been explicitly asked for it, this allows the KDC to 1598 send an unsolicited 4.04 (Not Found) response to the node as a 1599 notification of eviction from the group (see Section 5). 1601 Note that the node could have been observing also the resource at 1602 ace-group/GROUPNAME, in order to be informed of changes in the keying 1603 material. In such a case, this method would result in largely 1604 overlapping notifications received for the resource at ace-group/ 1605 GROUPNAME and the sub-resource at ace-group/GROUPNAME/nodes/NODENAME. 1607 In order to mitigate this, a node that supports the No-Response 1608 option [RFC7967] can use it when starting the observation of the sub- 1609 resource at ace-group/GROUPNAME/nodes/NODENAME. In particular, the 1610 GET observation request can also include the No-Response option, with 1611 value set to 2 (Not interested in 2.xx responses). 1613 4.1.6.3. DELETE Handler 1615 The DELETE handler removes the node identified by "NODENAME" from the 1616 group identified by "GROUPNAME". 1618 The handler expects a request with method DELETE (and empty payload). 1620 The handler verifies that the group name of the /ace-group/GROUPNAME 1621 path is a subset of the 'scope' stored in the access token associated 1622 to the client identified by "NODENAME". If the verification fails, 1623 the KDC MUST respond with a 4.01 (Unauthorized) error message. 1625 The handler also verifies that the node sending the request and the 1626 node name used in the Uri-Path match. If that is not the case, the 1627 handler responds with a 4.01 (Unauthorized) error response. 1629 Additionally, the handler verifies that the node is a current member 1630 of the group. If verification fails, the KDC MUST respond with a 1631 4.01 (Unauthorized) error message. The response MUST have Content- 1632 Format set to application/ace-groupcomm+cbor and is formatted as 1633 defined in Section 4. The value of the 'error' field MUST be set to 1634 0 ("Operation permitted only to group members"). 1636 If verification succeeds, the handler removes the client from the 1637 group identified by "GROUPNAME". That includes removing the public 1638 key of the client if the KDC keep tracks of that, and possibly 1639 removing the evicted node from the list of observers of the resource 1640 at ace-group/GROUPNAME (if observable). Then, the handler deletes 1641 the sub-resource nodes/NODENAME and returns a 2.02 (Deleted) message 1642 with empty payload. 1644 4.1.7. ace-group/GROUPNAME/nodes/NODENAME/pub-key 1646 This resource implements a POST handler, if the KDC stores the public 1647 key of group members. If the KDC does not store the public keys of 1648 group members, the handler does not implement any method, and every 1649 request returns a 4.05 Method Not Allowed error. 1651 4.1.7.1. POST Handler 1653 The POST handler is used to replace the stored public key of this 1654 client (identified by "NODENAME") with the one specified in the 1655 request at the KDC, for the group identified by "GROUPNAME". 1657 The handler expects a POST request with payload as specified in 1658 Section 4.1.2.1, with the difference that it includes only the 1659 parameters 'client_cred', 'cnonce' and 'client_cred_verify'. In 1660 particular, the signature included in 'client_cred_verify' is 1661 expected to be computed as defined in Section 4.1.2.1, with a newly 1662 generated N_C nonce and the previously received N_S. The specific 1663 format of public keys is specified by the application profile (OPT1). 1665 The handler verifies that the group name GROUPNAME is a subset of the 1666 'scope' stored in the access token associated to the client 1667 identified by "NODENAME". The KDC also verifies that the roles the 1668 client is granted in the group allow it to perform this operation on 1669 this resource (REQ8). If either verification fails, the KDC MUST 1670 respond with a 4.01 (Unauthorized) error message. 1672 The handler also verifies that the node sending the request and the 1673 node name used in the Uri-Path match. If that is not the case, the 1674 handler responds with a 4.01 (Unauthorized) error response. 1676 Additionally, the handler verifies that the node is a current member 1677 of the group. If the verification fails, the KDC MUST respond with a 1678 4.01 (Unauthorized) error message. The response MUST have Content- 1679 Format set to application/ace-groupcomm+cbor and is formatted as 1680 defined in Section 4. The value of the 'error' field MUST be set to 1681 0 ("Operation permitted only to group members"). 1683 Also, the handler verifies that this operation is consistent with the 1684 set of roles that the node has in the group. If the verification 1685 fails, the KDC MUST respond with a 4.00 (Bad Request) error message. 1686 The response MUST have Content-Format set to application/ace- 1687 groupcomm+cbor and is formatted as defined in Section 4. The value 1688 of the 'error' field MUST be set to 1 ("Request inconsistent with the 1689 current roles") 1690 If the request is not formatted correctly (i.e. required fields non 1691 received or received with incorrect format), the handler MUST respond 1692 with a 4.00 (Bad Request) error message. If the request contains 1693 unknown or non-expected fields present, the handler MUST silently 1694 ignore them and continue processing. Application profiles MAY define 1695 optional or mandatory payload formats for specific error cases 1696 (OPT7). 1698 Otherwise, the handler checks that the public key specified in the 1699 'client_cred' field has a valid format for the group identified by 1700 "GROUPNAME", i.e. it is encoded as expected and is compatible with 1701 the signature algorithm and possible associated parameters. If that 1702 cannot be successfully verified, the handler MUST respond with a 4.00 1703 (Bad Request) error message. The response MUST have Content-Format 1704 set to application/ace-groupcomm+cbor and is formatted as defined in 1705 Section 4. The value of the 'error' field MUST be set to 2 ("Public 1706 key incompatible with the group configuration"). 1708 If the KDC cannot retrieve the 'kdcchallenge' associated to this 1709 Client (see Section 3.3), the KDC MUST respond with a 4.00 Bad 1710 Request error response, whose payload is a CBOR map including a newly 1711 generated 'kdcchallenge'. This error response MUST also have 1712 Content-Format application/ace+cbor. 1714 Otherwise, the handler verifies the signature contained in the 1715 'client_cred_verify' field of the request, using the public key 1716 specified in the 'client_cred' field. If the signature does not pass 1717 verification, the handler MUST respond with a 4.01 (Unauthorized) 1718 error message. The response MUST have Content-Format set to 1719 application/ace-groupcomm+cbor and is formatted as defined in 1720 Section 4. The value of the 'error' field MUST be set to 3 ("Invalid 1721 proof-of-possession signature"). 1723 If verification succeeds, the handler replaces the old public key of 1724 the node NODENAME with the one specified in the 'client_cred' field 1725 of the request, and stores it as the new current public key of the 1726 node NODENAME, in the list of group members' public keys for the 1727 group identified by GROUPNAME. 1729 If COSE Keys are used as encoding of public keys in the group, the 1730 KDC MUST set the 'kid' key parameter of the new current public key to 1731 the node identifier that the client has in the group. If an 1732 alternative encoding of public keys is used, the KDC MUST set the 1733 node identifier of the client in the new current public key as 1734 appropriate, if that encoding supports it. 1736 Then, the handler replies with a 2.04 (Changed) response, which does 1737 not include a payload. 1739 4.2. Retrieval of Group Names and URIs 1741 In case the joining node only knows the group identifier of the group 1742 it wishes to join or about which it wishes to get update information 1743 from the KDC, the node can contact the KDC to request the 1744 corresponding group name and joining resource URI. The node can 1745 request several group identifiers at once. It does so by sending a 1746 CoAP FETCH request to the /ace-group endpoint at the KDC formatted as 1747 defined in Section 4.1.1.1. 1749 Figure 10 gives an overview of the exchanges described above, and 1750 Figure 11 shows an example. 1752 Client KDC 1753 | | 1754 |-------- Group Name and URI Retrieval Request: -------->| 1755 | FETCH /ace-group | 1756 | | 1757 |<-Group Name and URI Retrieval Response: 2.05 (Content)-| 1758 | | 1760 Figure 10: Message Flow of Group Name and URI Retrieval Request- 1761 Response 1763 Request: 1765 Header: FETCH (Code=0.05) 1766 Uri-Host: "kdc.example.com" 1767 Uri-Path: "ace-group" 1768 Content-Format: "application/ace-groupcomm+cbor" 1769 Payload (in CBOR diagnostic notation): 1770 { "gid": [01, 02] } 1772 Response: 1774 Header: Content (Code=2.05) 1775 Content-Format: "application/ace-groupcomm+cbor" 1776 Payload (in CBOR diagnostic notation): 1777 { "gid": [01, 02], "gname": ["group1", "group2"], 1778 "guri": ["ace-group/g1", "ace-group/g2"] } 1780 Figure 11: Example of Group Name and URI Retrieval Request-Response 1782 4.3. Joining Exchange 1784 Figure 12 gives an overview of the Joining exchange between Client 1785 and KDC, when the Client first joins a group, while Figure 13 shows 1786 an example. 1788 Client KDC 1789 | | 1790 |----- Joining Request: POST /ace-group/GROUPNAME ------>| 1791 | | 1792 |<--------- Joining Response: 2.01 (Created) ----------- | 1793 | Location-Path = "/ace-group/GROUPNAME/nodes/NODENAME" | 1795 Figure 12: Message Flow of First Exchange for Group Joining 1797 Request: 1799 Header: POST (Code=0.02) 1800 Uri-Host: "kdc.example.com" 1801 Uri-Path: "ace-group" 1802 Uri-Path: "g1" 1803 Content-Format: "application/ace-groupcomm+cbor" 1804 Payload (in CBOR diagnostic notation, 1805 with PUB_KEY and SIG being CBOR byte strings): 1806 { "scope": << [ "group1", ["sender", "receiver"] ] >> , 1807 "get_pub_keys": [true, ["sender"], []], "client_cred": PUB_KEY 1808 "cnonce": h'6df49c495409a9b5', "client_cred_verify": SIG } 1810 Response: 1812 Header: Created (Code=2.01) 1813 Content-Format: "application/ace-groupcomm+cbor" 1814 Location-Path: "kdc.example.com" 1815 Location-Path: "g1" 1816 Location-Path: "nodes" 1817 Location-Path: "c101" 1818 Payload (in CBOR diagnostic notation, 1819 with KEY being a CBOR byte strings): 1820 { "gkty": 13, "key": KEY, "num": 12, "exp": 1609459200, 1821 "pub_keys": << [ PUB_KEY1, PUB_KEY2 ] >>, 1822 "peer_roles": ["sender", ["sender", "receiver"]] } 1824 Figure 13: Example of First Exchange for Group Joining 1826 If not previously established, the Client and the KDC MUST first 1827 establish a pairwise secure communication channel (REQ19). This can 1828 be achieved, for instance, by using a transport profile of ACE. The 1829 Joining exchange MUST occur over that secure channel. The Client and 1830 the KDC MAY use that same secure channel to protect further pairwise 1831 communications that must be secured. 1833 The secure communication protocol is REQUIRED to establish the secure 1834 channel between Client and KDC by using the proof-of-possession key 1835 bound to the access token. As a result, the proof-of-possession to 1836 bind the access token to the Client is performed by using the proof- 1837 of-possession key bound to the access token for establishing secure 1838 communication between the Client and the KDC. 1840 To join the group, the Client sends a CoAP POST request to the /ace- 1841 group/GROUPNAME endpoint at the KDC, where GROUPNAME is the group 1842 name of the group to join, formatted as specified in Section 4.1.2.1. 1843 This group name is the same as in the scope entry corresponding to 1844 that group, specified in the 'scope' parameter of the Authorization 1845 Request/Response, or it can be retrieved from it. Note that, in case 1846 of successful joining, the Client will receive the URI to retrieve 1847 group keying material and to leave the group in the Location-Path 1848 option of the response. 1850 If the node is joining a group for the first time, and the KDC 1851 maintains the public keys of the group members, the Client is 1852 REQUIRED to send its own public key and proof of possession 1853 ("client_cred" and "client_cred_verify" in Section 4.1.2.1). The 1854 request is only accepted if both public key and proof of possession 1855 are provided. If a node re-joins a group with the same access token 1856 and the same public key, it can omit to send the public key and the 1857 proof of possession, or just omit the proof of possession, and the 1858 KDC will be able to retrieve its public key associated to its token 1859 for that group (if the key has been discarded, the KDC will reply 1860 with 4.00 Bad Request, as specified in Section 4.1.2.1). If a node 1861 re-joins a group but wants to update its own public key, it needs to 1862 send both public key and proof of possession. 1864 If the application requires backward security, the KDC MUST generate 1865 new group keying material and securely distribute it to all the 1866 current group members, upon a new node's joining the group. To this 1867 end, the KDC uses the message format of the response defined in 1868 Section 4.1.2.2. Application profiles may define alternative ways of 1869 retrieving the keying material, such as sending separate requests to 1870 different resources at the KDC (Section 4.1.2.2, Section 4.1.3.2, 1871 Section 4.1.4.1). After distributing the new group keying material, 1872 the KDC MUST increment the version number of the keying material. 1874 4.4. Retrieval of Updated Keying Material 1876 When any of the following happens, a node MUST stop using the owned 1877 group keying material to protect outgoing messages, and SHOULD stop 1878 using it to decrypt and verify incoming messages. 1880 o Upon expiration of the keying material, according to what 1881 indicated by the KDC with the 'exp' parameter in a Joining 1882 Response, or to a pre-configured value. 1884 o Upon receiving a notification of revoked/renewed keying material 1885 from the KDC, possibly as part of an update of the keying material 1886 (rekeying) triggered by the KDC. 1888 o Upon receiving messages from other group members without being 1889 able to retrieve the keying material to correctly decrypt them. 1890 This may be due to rekeying messages previously sent by the KDC, 1891 that the Client was not able to receive or decrypt. 1893 In either case, if it wants to continue participating in the group 1894 communication, the node has to request the latest keying material 1895 from the KDC. To this end, the Client sends a CoAP GET request to 1896 the /ace-group/GROUPNAME/nodes/NODENAME endpoint at the KDC, 1897 formatted as specified in Section 4.1.6.2. 1899 Note that policies can be set up, so that the Client sends a Key Re- 1900 Distribution request to the KDC only after a given number of received 1901 messages could not be decrypted (because of failed decryption 1902 processing or inability to retrieve the necessary keying material). 1904 It is application dependent and pertaining to the particular message 1905 exchange (e.g. [I-D.ietf-core-oscore-groupcomm]) to set up these 1906 policies for instructing clients to retain incoming messages and for 1907 how long (OPT5). This allows clients to possibly decrypt such 1908 messages after getting updated keying material, rather than just 1909 consider them non valid messages to discard right away. 1911 The same Key Distribution Request could also be sent by the Client 1912 without being triggered by a failed decryption of a message, if the 1913 Client wants to be sure that it has the latest group keying material. 1914 If that is the case, the Client will receive from the KDC the same 1915 group keying material it already has in memory. 1917 Figure 14 gives an overview of the exchange described above, while 1918 Figure 15 shows an example. 1920 Client KDC 1921 | | 1922 |------------------ Key Distribution Request: --------------->| 1923 | GET ace-group/GROUPNAME/nodes/NODENAME | 1924 | | 1925 |<-------- Key Distribution Response: 2.05 (Content) ---------| 1926 | | 1928 Figure 14: Message Flow of Key Distribution Request-Response 1929 Request: 1931 Header: GET (Code=0.01) 1932 Uri-Host: "kdc.example.com" 1933 Uri-Path: "ace-group" 1934 Uri-Path: "g1" 1935 Uri-Path: "nodes" 1936 Uri-Path: "c101" 1937 Payload: - 1939 Response: 1941 Header: Content (Code=2.05) 1942 Content-Format: "application/ace-groupcomm+cbor" 1943 Payload (in CBOR diagnostic notation, 1944 with KEY and IND_KEY being CBOR byte strings, 1945 and "ind-key" the profile-specified label 1946 for individual keying material): 1947 { "gkty": 13, "key": KEY, "num": 12, "ind-key": IND_KEY } 1949 Figure 15: Example of Key Distribution Request-Response 1951 Alternatively, the re-distribution of keying material can be 1952 initiated by the KDC, which e.g.: 1954 o Can make the ace-group/GROUPNAME resource Observable [RFC7641], 1955 and send notifications to observer Clients when the keying 1956 material is updated. 1958 In case the KDC deletes the group identified by "GROUPNAME", this 1959 also allows the KDC to send an unsolicited 4.04 (Not Found) 1960 response to each observer group member, as a notification of group 1961 termination. The response MUST have Content-Format set to 1962 application/ace-groupcomm+cbor and is formatted as defined in 1963 Section 4. The value of the 'error' field MUST be set to 6 1964 ("Group deleted"). 1966 o Can send the payload of the Key Distribution Response in one or 1967 multiple multicast POST requests to the members of the group, 1968 using secure rekeying schemes such as [RFC2093][RFC2094][RFC2627]. 1970 o Can send unicast POST requests to each Client over a secure 1971 channel, with the same payload as the Key Distribution Response. 1972 When sending such requests, the KDC can target the URI path 1973 provided by the intended recipient upon joining the group, as 1974 specified in the 'control_uri' parameter of the Joining Request 1975 (see Section 4.1.2.1). 1977 o Can act as a publisher in a pub-sub scenario, and update the 1978 keying material by publishing on a specific topic on a broker, 1979 which all the members of the group are subscribed to. 1981 Note that these methods of KDC-initiated key distribution have 1982 different security properties and require different security 1983 associations. 1985 4.5. Requesting a Change of Keying Material 1987 Beside possible expiration, the client may need to communicate to the 1988 KDC its need for the keying material to be renewed, e.g. due to 1989 exhaustion of AEAD nonces, if AEAD is used for protecting group 1990 communication. Depending on the application profile (OPT9), this can 1991 result in renewal of individual keying material, group keying 1992 material, or both. 1994 For example, if the Client uses an individual key to protect outgoing 1995 traffic and has to renew it, the node may request a new one, or new 1996 input material to derive it, without renewing the whole group keying 1997 material. 1999 To this end, the client performs a Key Renewal Request/Response 2000 exchange with the KDC, i.e. it sends a CoAP PUT request to the /ace- 2001 group/GROUPNAME/nodes/NODENAME endpoint at the KDC, where GROUPNAME 2002 is the group name and NODENAME is its node name, and formatted as 2003 defined in Section 4.1.6.2. 2005 Figure 16 gives an overview of the exchange described above, while 2006 Figure 17 shows an example. 2008 Client KDC 2009 | | 2010 |------------------ Key Renewal Request: -------------->| 2011 | PUT ace-group/GROUPNAME/nodes/NODENAME | 2012 | | 2013 |<-------- Key Renewal Response: 2.05 (Content) --------| 2014 | | 2016 Figure 16: Message Flow of Key Renewal Request-Response 2018 Request: 2020 Header: PUT (Code=0.03) 2021 Uri-Host: "kdc.example.com" 2022 Uri-Path: "ace-group" 2023 Uri-Path: "g1" 2024 Uri-Path: "nodes" 2025 Uri-Path: "c101" 2026 Payload: - 2028 Response: 2030 Header: Content (Code=2.05) 2031 Content-Format: "application/ace-groupcomm+cbor" 2032 Payload (in CBOR diagnostic notation, with IND_KEY being 2033 a CBOR byte string, and "ind-key" the profile-specified 2034 label for individual keying material): 2035 { "ind-key": IND_KEY } 2037 Figure 17: Example of Key Renewal Request-Response 2039 Note the difference between the Key Distribution Request and the Key 2040 Renewal Request: while the first one only triggers distribution (the 2041 renewal might have happened independently, e.g. because of 2042 expiration), the second one triggers the KDC to produce new 2043 individual keying material for the requesting node. 2045 4.6. Retrieval of Public Keys and Roles for Group Members 2047 In case the KDC maintains the public keys of group members, a node in 2048 the group can contact the KDC to request public keys and roles of 2049 either all group members or a specified subset, by sending a CoAP GET 2050 or FETCH request to the /ace-group/GROUPNAME/pub-key endpoint at the 2051 KDC, where GROUPNAME is the group name, and formatted as defined in 2052 Section 4.1.3.2 and Section 4.1.3.1. 2054 Figure 18 and Figure 20 give an overview of the exchanges described 2055 above, while Figure 19 and Figure 21 show an example for each 2056 exchange. 2058 Client KDC 2059 | | 2060 |--Public Key Request: GET /ace-group/GROUPNAME/pub-key->| 2061 | | 2062 |<--------- Public Key Response: 2.05 (Content) ---------| 2063 | | 2065 Figure 18: Message Flow of Public Key Exchange to Request All Members 2066 Public Keys 2068 Request: 2070 Header: GET (Code=0.01) 2071 Uri-Host: "kdc.example.com" 2072 Uri-Path: "ace-group" 2073 Uri-Path: "g1" 2074 Uri-Path: "pub-key" 2075 Payload: - 2077 Response: 2079 Header: Content (Code=2.05) 2080 Content-Format: "application/ace-groupcomm+cbor" 2081 Payload (in CBOR diagnostic notation): 2082 { "pub_keys": << [ PUB_KEY1, PUB_KEY2, PUB_KEY3 ] >>, 2083 "peer_roles": ["sender", ["sender", "receiver"], "receiver"] } 2085 Figure 19: Example of Public Key Exchange to Request All Members 2086 Public Keys 2088 Client KDC 2089 | | 2090 |-Public Key Request: FETCH /ace-group/GROUPNAME/pub-key->| 2091 | | 2092 |<--------- Public Key Response: 2.05 (Created) ----------| 2093 | | 2095 Figure 20: Message Flow of Public Key Exchange to Request Specific 2096 Members Public Keys 2098 Request: 2100 Header: FETCH (Code=0.05) 2101 Uri-Host: "kdc.example.com" 2102 Uri-Path: "ace-group" 2103 Uri-Path: "g1" 2104 Uri-Path: "pub-key" 2105 Content-Format: "application/ace-groupcomm+cbor" 2106 Payload: 2107 { "get_pub_keys": [true, [], ["c3"]] } 2109 Response: 2111 Header: Content (Code=2.05) 2112 Content-Format: "application/ace-groupcomm+cbor" 2113 Payload (in CBOR diagnostic notation): 2114 { "pub_keys": << [ PUB_KEY3 ] >>, 2115 "peer_roles": ["receiver"] } 2117 Figure 21: Example of Public Key Exchange to Request Specific Members 2118 Public Keys 2120 4.7. Update of Public Key 2122 In case the KDC maintains the public keys of group members, a node in 2123 the group can contact the KDC to upload a new public key to use in 2124 the group, and replace the currently stored one. 2126 To this end, the Client performs a Public Key Update Request/Response 2127 exchange with the KDC, i.e. it sends a CoAP POST request to the /ace- 2128 group/GROUPNAME/nodes/NODENAME/pub-key endpoint at the KDC, where 2129 GROUPNAME is the group name and NODENAME is its node name. 2131 The request is formatted as specified in Section 4.1.7.1. 2133 Figure Figure 22 gives an overview of the exchange described above, 2134 while Figure 23 shows an example. 2136 Client KDC 2137 | | 2138 |-------------- Public Key Update Request: ---------------------->| 2139 | POST ace-group/GROUPNAME/nodes/NODENAME/pub-key | 2140 | | 2141 |<------- Public Key Update Response: 2.04 (Changed) -------------| 2142 | | 2144 Figure 22: Message Flow of Public Key Update Request-Response 2145 Request: 2147 Header: POST (Code=0.02) 2148 Uri-Host: "kdc.example.com" 2149 Uri-Path: "ace-group" 2150 Uri-Path: "g1" 2151 Uri-Path: "nodes" 2152 Uri-Path: "c101" 2153 Uri-Path: "pub-key" 2154 Content-Format: "application/ace-groupcomm+cbor" 2155 Payload (in CBOR diagnostic notation, with PUB_KEY 2156 and SIG being CBOR byte strings): 2157 { "client_cred": PUB_KEY, "cnonce": h'9ff7684414affcc8', 2158 "client_cred_verify": SIG } 2160 Response: 2162 Header: Changed (Code=2.04) 2163 Payload: - 2165 Figure 23: Example of Public Key Update Request-Response 2167 If the application requires backward security, the KDC MUST generate 2168 new group keying material and securely distribute it to all the 2169 current group members, upon a group member updating its own public 2170 key. To this end, the KDC uses the message format of the response 2171 defined in Section 4.1.2.2. Application profiles may define 2172 alternative ways of retrieving the keying material, such as sending 2173 separate requests to different resources at the KDC (Section 4.1.2.2, 2174 Section 4.1.3.2, Section 4.1.4.1). The KDC MUST increment the 2175 version number of the current keying material, before distributing 2176 the newly generated keying material to the group. After that, the 2177 KDC SHOULD store the distributed keying material in persistent 2178 storage. 2180 Additionally, after updating its own public key, a group member MAY 2181 send a number of the later requests including an identifier of the 2182 updated public key, to signal nodes that they need to retrieve it. 2183 How that is done depends on the group communication protocol used, 2184 and therefore is application profile specific (OPT11). 2186 4.8. Retrieval of Group Policies 2188 A node in the group can contact the KDC to retrieve the current group 2189 policies, by sending a CoAP GET request to the /ace-group/GROUPNAME/ 2190 policies endpoint at the KDC, where GROUPNAME is the group name, and 2191 formatted as defined in Section 4.1.4.1 2192 Figure 24 gives an overview of the exchange described above, while 2193 Figure 25 shows an example. 2195 Client KDC 2196 | | 2197 |-Policies Request: GET ace-group/GROUPNAME/policies ->| 2198 | | 2199 |<--------- Policies Response: 2.05 (Content) ---------| 2200 | | 2202 Figure 24: Message Flow of Policies Request-Response 2204 Request: 2206 Header: GET (Code=0.01) 2207 Uri-Host: "kdc.example.com" 2208 Uri-Path: "ace-group" 2209 Uri-Path: "g1" 2210 Uri-Path: "policies" 2211 Payload: - 2213 Response: 2215 Header: Content (Code=2.05) 2216 Content-Format: "application/ace-groupcomm+cbor" 2217 Payload(in CBOR diagnostic notation): 2218 { "group_policies": {"exp-delta": 120} } 2220 Figure 25: Example of Policies Request-Response 2222 4.9. Retrieval of Keying Material Version 2224 A node in the group can contact the KDC to request information about 2225 the version number of the symmetric group keying material, by sending 2226 a CoAP GET request to the /ace-group/GROUPNAME/num endpoint at the 2227 KDC, where GROUPNAME is the group name, formatted as defined in 2228 Section 4.1.5.1. In particular, the version is incremented by the 2229 KDC every time the group keying material is renewed, before it's 2230 distributed to the group members. 2232 Figure 26 gives an overview of the exchange described above, while 2233 Figure 27 shows an example. 2235 Client KDC 2236 | | 2237 |---- Version Request: GET ace-group/GROUPNAME/num ---->| 2238 | | 2239 |<--------- Version Response: 2.05 (Content) -----------| 2240 | | 2242 Figure 26: Message Flow of Version Request-Response 2244 Request: 2246 Header: GET (Code=0.01) 2247 Uri-Host: "kdc.example.com" 2248 Uri-Path: "ace-group" 2249 Uri-Path: "g1" 2250 Uri-Path: "num" 2251 Payload: - 2253 Response: 2255 Header: Content (Code=2.05) 2256 Content-Format: text/plain 2257 Payload(in CBOR diagnostic notation): 2258 13 2260 Figure 27: Example of Version Request-Response 2262 4.10. Group Leaving Request 2264 A node can actively request to leave the group. In this case, the 2265 Client sends a CoAP DELETE request to the endpoint /ace- 2266 group/GROUPNAME/nodes/NODENAME at the KDC, where GROUPNAME is the 2267 group name and NODENAME is its node name, formatted as defined in 2268 Section 4.1.6.3 2270 Alternatively, a node may be removed by the KDC, without having 2271 explicitly asked for it. This is further discussed in Section 5. 2273 5. Removal of a Node from the Group 2275 This section describes the different scenarios according to which a 2276 node ends up being removed from the group. 2278 If the application requires forward security, the KDC MUST generate 2279 new group keying material and securely distribute it to all the 2280 current group members but the leaving node, using the message format 2281 of the Key Distribution Response (see Section 4.4). Application 2282 profiles may define alternative message formats. Before distributing 2283 the new group keying material, the KDC MUST increment the version 2284 number of the keying material. 2286 Note that, after having left the group, a node may wish to join it 2287 again. Then, as long as the node is still authorized to join the 2288 group, i.e. it still has a valid access token, it can request to re- 2289 join the group directly to the KDC without needing to retrieve a new 2290 access token from the AS. This means that the KDC might decide to 2291 keep track of nodes with valid access tokens, before deleting all 2292 information about the leaving node. 2294 A node may be evicted from the group in the following cases. 2296 1. The node explicitly asks to leave the group, as defined in 2297 Section 4.10. 2299 2. The node has been found compromised or is suspected so. 2301 3. The node's authorization to be a group member is not valid 2302 anymore, either because the access token has expired, or it has 2303 been revoked. If the AS provides Token introspection (see 2304 Section 5.9 of [I-D.ietf-ace-oauth-authz]), the KDC can 2305 optionally use it and check whether the node is still authorized 2306 for that group in that role. 2308 In either case, once aware that a node is not authorized anymore, 2309 the KDC has to remove the unauthorized node from the list of 2310 group members, if the KDC keeps track of that. 2312 Furthermore, in case of forced eviction, the KDC removes the public 2313 key of the evicted node if the KDC keep tracks of that, and possibly 2314 removes the evicted node from the list of observers of the resource 2315 at ace-group/GROUPNAME (if observable). 2317 Then, the KDC deletes the sub-resource ace-group/GROUPNAME/nodes/ 2318 NODENAME associated to the evicted node. After that, the KDC MAY 2319 explicitly inform the evicted node, by means of the following 2320 methods. 2322 o If the evicted node implements the 'control_uri' resource 2323 specified in Section 4.1.2.1, the KDC sends a DELETE request, 2324 targeting the URI specified in the 'control_uri' parameter of the 2325 Joining Request (see Section 4.1.2.1). 2327 o If the evicted node is observing its associated sub-resource at 2328 ace-group/GROUPNAME/nodes/NODENAME (see Section 4.1.6.2), the KDC 2329 sends an unsolicited 4.04 (Not Found) response, which does not 2330 include the Observe option and indicates that the observed 2331 resource has been deleted (see Section 3.2 of [RFC7641]). 2333 The response MUST have Content-Format set to application/ace- 2334 groupcomm+cbor and is formatted as defined in Section 4. The 2335 value of the 'error' field MUST be set to 5 ("Group membership 2336 terminated"). 2338 Consistently, the KDC also removes the node's entry from the list 2339 of observers of the sub-resource. 2341 6. Extended Scope Format 2343 This section defines an extended format of binary encoded scope, 2344 which additionally specifies the semantics used to express the same 2345 access control information from the corresponding original scope. 2347 As also discussed in Section 3.2, this enables a Resource Server to 2348 unambiguously process a received access token, also in case the 2349 Resource Server runs multiple applications or application profiles 2350 that involve different scope semantics. 2352 The extended format is intended only for the 'scope' claim of access 2353 tokens, for the cases where the claim takes as value a CBOR byte 2354 string. That is, the extended format does not apply to the 'scope' 2355 parameter included in ACE messages, i.e. the Authorization Request 2356 and Authorization Response exchanged between the client and the 2357 Authorization Server (see Sections 5.8.1 and 5.8.2 of 2358 [I-D.ietf-ace-oauth-authz]), the AS Request Creation Hints message 2359 from the Resource Server (see Section 5.3 of 2360 [I-D.ietf-ace-oauth-authz]), and the Introspection Response from the 2361 Authorization Server (see Section 5.9.2 of 2362 [I-D.ietf-ace-oauth-authz]). 2364 The value of the 'scope' claim following the extended format is 2365 composed as follows. Given the original scope using a semantics SEM 2366 and encoded as a CBOR byte string, the corresponding extended scope 2367 is encoded as a tagged CBOR byte string, wrapping a CBOR sequence 2368 [RFC8742] of two elements. In particular: 2370 o The first element of the sequence is a CBOR integer, and 2371 identifies the semantics SEM used for this scope. The value of 2372 this element has to be taken from the "Value" column of the "ACE 2373 Scope Semantics" registry defined in Section 10.12 of this 2374 specification. 2376 When defining a new semantics for a binary scope, it is up to the 2377 applications and application profiles to define and register the 2378 corresponding integer identifier (REQ23). 2380 o The second element of the sequence is the original scope using the 2381 semantics SEM, encoded as a CBOR byte string. 2383 Finally, the CBOR byte string wrapping the CBOR sequence is tagged, 2384 and identified by the CBOR tag TBD_TAG "ACE Extended Scope Format", 2385 defined in Section 10.11 of this specification. 2387 The resulting tagged CBOR byte string is used as value of the 'scope' 2388 claim of the access token. 2390 The usage of the extended scope format is not limited to application 2391 profiles of this specification or to applications based on group 2392 communication. Rather, it is generally applicable to any application 2393 and application profile where access control information in the 2394 access token is expressed as a binary encoded scope. 2396 Figure 28 and Figure 29 build on the examples in Section 3.2, and 2397 show the corresponding extended scopes. 2399 gname = tstr 2401 permissions = uint . bits roles 2403 roles = &( 2404 Requester: 1, 2405 Responder: 2, 2406 Monitor: 3, 2407 Verifier: 4 2408 ) 2410 scope_entry = AIF_Generic 2412 scope = << [ + scope_entry ] >> 2414 semantics = int 2416 ; This defines an array, the elements 2417 ; of which are to be used in a CBOR Sequence: 2418 sequence = [semantics, scope] 2420 extended_scope = #6.TBD_TAG(<< sequence >>) 2422 Figure 28: Example CDLL definition of scope, using the default 2423 Authorization Information Format 2425 gname = tstr 2427 role = tstr 2429 scope_entry = [ gname , ? ( role / [ 2*role ] ) ] 2431 scope = << [ + scope_entry ] >> 2433 semantics = int 2435 ; This defines an array, the elements 2436 ; of which are to be used in a CBOR Sequence: 2437 sequence = [semantics, scope] 2439 extended_scope = #6.TBD_TAG(<< sequence >>) 2441 Figure 29: CDLL definition of scope, using as example group name 2442 encoded as tstr and role as tstr 2444 7. ACE Groupcomm Parameters 2446 This specification defines a number of fields used during the second 2447 part of the message exchange, after the ACE Token POST exchange. The 2448 table below summarizes them, and specifies the CBOR key to use 2449 instead of the full descriptive name. 2451 Note that the media type application/ace-groupcomm+cbor MUST be used 2452 when these fields are transported. 2454 +-----------------------+------+-----------------+------------------+ 2455 | Name | CBOR | CBOR Type | Reference | 2456 | | Key | | | 2457 +-----------------------+------+-----------------+------------------+ 2458 | scope | TBD | byte string | Section 4.1.2.1 | 2459 | | | | | 2460 | get_pub_keys | TBD | array / simple | Section 4.1.2.1, | 2461 | | | value null | Section 4.1.3.1 | 2462 | | | | | 2463 | client_cred | TBD | byte string | Section 4.1.2.1 | 2464 | | | | | 2465 | cnonce | TBD | byte string | Section 4.1.2.1 | 2466 | | | | | 2467 | client_cred_verify | TBD | byte string | Section 4.1.2.1 | 2468 | | | | | 2469 | pub_keys_repos | TBD | text string | Section 4.1.2.1 | 2470 | | | | | 2471 | control_uri | TBD | text string | Section 4.1.2.1 | 2472 | | | | | 2473 | gkty | TBD | integer / text | Section 4.1.2.1 | 2474 | | | string | | 2475 | | | | | 2476 | key | TBD | see "ACE | Section 4.1.2.1 | 2477 | | | Groupcomm Key" | | 2478 | | | Registry | | 2479 | | | | | 2480 | num | TBD | int | Section 4.1.2.1 | 2481 | | | | | 2482 | ace-groupcomm-profile | TBD | int | Section 4.1.2.1 | 2483 | | | | | 2484 | exp | TBD | int | Section 4.1.2.1 | 2485 | | | | | 2486 | pub_keys | TBD | byte string | Section 4.1.2.1 | 2487 | | | | | 2488 | peer_roles | TBD | array | Section 4.1.2.1 | 2489 | | | | | 2490 | peer_identifiers | TBD | array | Section 4.1.2.1 | 2491 | | | | | 2492 | group_policies | TBD | map | Section 4.1.2.1 | 2493 | | | | | 2494 | mgt_key_material | TBD | byte string | Section 4.1.2.1 | 2495 | | | | | 2496 | gid | TBD | array | Section 4.1.1.1 | 2497 | | | | | 2498 | gname | TBD | array of text | Section 4.1.1.1 | 2499 | | | strings | | 2500 | | | | | 2501 | guri | TBD | array of text | Section 4.1.1.1 | 2502 | | | strings | | 2503 | | | | | 2504 | error | TBD | int | Section 4 | 2505 | | | | | 2506 | error_description | TBD | text string | Section 4 | 2507 +-----------------------+------+-----------------+------------------+ 2509 8. ACE Groupcomm Error Identifiers 2511 This specification defines a number of values that the KDC can 2512 include as error identifiers, in the 'error' field of an error 2513 response with Content-Format application/ace-groupcomm+cbor. 2515 +-------+------------------------------------------------------+ 2516 | Value | Description | 2517 +-------+------------------------------------------------------+ 2518 | 0 | Operation permitted only to group members | 2519 | | | 2520 | 1 | Request inconsistent with the current roles | 2521 | | | 2522 | 2 | Public key incompatible with the group configuration | 2523 | | | 2524 | 3 | Invalid proof-of-possession signature | 2525 | | | 2526 | 4 | No available node identifiers | 2527 | | | 2528 | 5 | Group membership terminated | 2529 | | | 2530 | 6 | Group deleted | 2531 +-------+------------------------------------------------------+ 2533 9. Security Considerations 2535 When a Client receives a message from a sender for the first time, it 2536 needs to have a mechanism in place to avoid replay, e.g. 2537 Appendix B.2 of [RFC8613]. In case the Client rebooted and lost the 2538 security state used to protect previous communication with that 2539 sender, such a mechanism is useful for the recipient to be on the 2540 safe side. 2542 Besides, if the KDC has renewed the group keying material, and the 2543 time interval between the end of the rekeying process and the joining 2544 of the Client is sufficiently small, that Client is also on the safe 2545 side, since replayed older messages protected with the previous 2546 keying material will not be accepted. 2548 The KDC must renew the group keying material upon its expiration. 2550 The KDC should renew the keying material upon group membership 2551 change, and should provide it to the current group members through 2552 the rekeying scheme used in the group. 2554 The KDC should renew the group keying material after rebooting, even 2555 in the case where all keying material is stored in persistent 2556 storage. However, if the KDC relies on Observe responses to notify 2557 the group of renewed keying material, after rebooting the KDC will 2558 have lost all the current ongoing Observations with the group 2559 members, and the previous keying material will be used to protect 2560 messages in the group anyway. The KDC will rely on each node 2561 requesting updates of the group keying material to establish the new 2562 keying material in the nodes, or, if implemented, it can push the 2563 update to the nodes in the group using the 'control_uri' resource. 2565 The KDC may enforce a rekeying policy that takes into account the 2566 overall time required to rekey the group, as well as the expected 2567 rate of changes in the group membership. 2569 That is, the KDC may not rekey the group at every membership change, 2570 for instance if members' joining and leaving occur frequently and 2571 performing a group rekeying takes too long. The KDC may rekey the 2572 group after a minimum number of group members have joined or left 2573 within a given time interval, or after maximum amount of time since 2574 the last rekeying was completed, or yet during predictable network 2575 inactivity periods. 2577 However, this would result in the KDC not constantly preserving 2578 backward and forward security. Newly joining group members could be 2579 able to access the keying material used before their joining, and 2580 thus could access past group communications. Also, until the KDC 2581 performs a group rekeying, the newly leaving nodes would still be 2582 able to access upcoming group communications that are protected with 2583 the keying material that has not yet been updated. 2585 The KDC needs to have a mechanism in place to detect DoS attacks from 2586 nodes constantly initiating rekey events (for example by updating 2587 their public key), such as removing these nodes from the group. 2589 The KDC also needs to have a congestion control mechanism in place to 2590 avoid network congestion when the KDC renews the group keying 2591 material; CoAP and Observe give guidance on such mechanisms, see 2592 Section 4.7 of [RFC7252] and Section 4.5.1 of [RFC7641]. 2594 9.1. Update of Keying Material 2596 A group member can receive a message shortly after the group has been 2597 rekeyed, and new keying material has been distributed by the KDC. In 2598 the following two cases, this may result in misaligned keying 2599 material between the group members. 2601 In the first case, the sender protects a message using the old keying 2602 material. However, the recipient receives the message after having 2603 received the new keying material, hence not being able to correctly 2604 process it. A possible way to ameliorate this issue is to preserve 2605 the old, recent, keying material for a maximum amount of time defined 2606 by the application. By doing so, the recipient can still try to 2607 process the received message using the old retained keying material. 2608 Note that a former (compromised) group member can take advantage of 2609 this by sending messages protected with the old retained keying 2610 material. Therefore, a conservative application policy should not 2611 admit the storage of old keying material. 2613 In the second case, the sender protects a message using the new 2614 keying material, but the recipient receives that request before 2615 having received the new keying material. Therefore, the recipient 2616 would not be able to correctly process the request and hence discards 2617 it. If the recipient receives the new keying material shortly after 2618 that and the application at the sender endpoint performs 2619 retransmissions, the former will still be able to receive and 2620 correctly process the message. In any case, the recipient should 2621 actively ask the KDC for an updated keying material according to an 2622 application-defined policy, for instance after a given number of 2623 unsuccessfully decrypted incoming messages. 2625 A node that has left the group should not expect any of its outgoing 2626 messages to be successfully processed, if received after its leaving, 2627 due to a possible group rekeying occurred before the message 2628 reception. 2630 9.2. Block-Wise Considerations 2632 If the block-wise options [RFC7959] are used, and the keying material 2633 is updated in the middle of a block-wise transfer, the sender of the 2634 blocks just changes the keying material to the updated one and 2635 continues the transfer. As long as both sides get the new keying 2636 material, updating the keying material in the middle of a transfer 2637 will not cause any issue. Otherwise, the sender will have to 2638 transmit the message again, when receiving an error message from the 2639 recipient. 2641 Compared to a scenario where the transfer does not use block-wise, 2642 depending on how fast the keying material is changed, the nodes might 2643 consume a larger amount of the network bandwidth resending the blocks 2644 again and again, which might be problematic. 2646 10. IANA Considerations 2648 This document has the following actions for IANA. 2650 10.1. Media Type Registrations 2652 This specification registers the 'application/ace-groupcomm+cbor' 2653 media type for messages of the protocols defined in this document 2654 following the ACE exchange and carrying parameters encoded in CBOR. 2655 This registration follows the procedures specified in [RFC6838]. 2657 Type name: application 2658 Subtype name: ace-groupcomm+cbor 2660 Required parameters: N/A 2662 Optional parameters: N/A 2664 Encoding considerations: Must be encoded as CBOR map containing the 2665 protocol parameters defined in [this document]. 2667 Security considerations: See Section 9 of this document. 2669 Interoperability considerations: n/a 2671 Published specification: [this document] 2673 Applications that use this media type: The type is used by 2674 authorization servers, clients and resource servers that support the 2675 ACE groupcomm framework as specified in [this document]. 2677 Fragment identifier considerations: N/A 2679 Additional information: N/A 2681 Person & email address to contact for further information: 2682 iesg@ietf.org [1] 2684 Intended usage: COMMON 2686 Restrictions on usage: None 2688 Author: Francesca Palombini francesca.palombini@ericsson.com [2] 2690 Change controller: IESG 2692 10.2. CoAP Content-Formats Registry 2694 This specification registers the following entry to the "CoAP 2695 Content-Formats" registry, within the "CoRE Parameters" registry: 2697 Media Type: application/ace-groupcomm+cbor 2699 Encoding: - 2701 ID: TBD 2703 Reference: [this document] 2705 10.3. OAuth Parameters Registry 2707 The following registrations are done for the OAuth Parameters 2708 Registry following the procedure specified in section 11.2 of 2709 [RFC6749]: 2711 o Parameter name: sign_info o Parameter usage location: token 2712 request, token response o Change Controller: IESG o Specification 2713 Document(s): [[This specification]] 2715 o Parameter name: kdcchallenge o Parameter usage location: token 2716 response o Change Controller: IESG o Specification Document(s): 2717 [[This specification]] 2719 10.4. OAuth Parameters CBOR Mappings Registry 2721 The following registrations are done for the OAuth Parameters CBOR 2722 Mappings Registry following the procedure specified in section 8.10 2723 of [I-D.ietf-ace-oauth-authz]: 2725 * Name: sign_info 2726 * CBOR Key: TBD (range -256 to 255) 2727 * Value Type: any 2728 * Reference: \[\[This specification\]\] 2730 * Name: kdcchallenge 2731 * CBOR Key: TBD (range -256 to 255) 2732 * Value Type: byte string 2733 * Reference: \[\[This specification\]\] 2735 10.5. ACE Groupcomm Parameters Registry 2737 This specification establishes the "ACE Groupcomm Parameters" IANA 2738 Registry. The Registry has been created to use the "Expert Review" 2739 registration procedure [RFC8126]. Expert review guidelines are 2740 provided in Section 10.14. 2742 The columns of this Registry are: 2744 o Name: This is a descriptive name that enables easier reference to 2745 the item. The name MUST be unique. It is not used in the 2746 encoding. 2748 o CBOR Key: This is the value used as CBOR key of the item. These 2749 values MUST be unique. The value can be a positive integer, a 2750 negative integer, or a string. 2752 o CBOR Type: This contains the CBOR type of the item, or a pointer 2753 to the registry that defines its type, when that depends on 2754 another item. 2756 o Reference: This contains a pointer to the public specification for 2757 the item. 2759 This Registry has been initially populated by the values in 2760 Section 7. The Reference column for all of these entries refers to 2761 sections of this document. 2763 10.6. ACE Groupcomm Key Registry 2765 This specification establishes the "ACE Groupcomm Key" IANA Registry. 2766 The Registry has been created to use the "Expert Review" registration 2767 procedure [RFC8126]. Expert review guidelines are provided in 2768 Section 10.14. 2770 The columns of this Registry are: 2772 o Name: This is a descriptive name that enables easier reference to 2773 the item. The name MUST be unique. It is not used in the 2774 encoding. 2776 o Key Type Value: This is the value used to identify the keying 2777 material. These values MUST be unique. The value can be a 2778 positive integer, a negative integer, or a text string. 2780 o Profile: This field may contain one or more descriptive strings of 2781 application profiles to be used with this item. The values should 2782 be taken from the Name column of the "ACE Groupcomm Profile" 2783 Registry. 2785 o Description: This field contains a brief description of the keying 2786 material. 2788 o References: This contains a pointer to the public specification 2789 for the format of the keying material, if one exists. 2791 This Registry has been initially populated by the values in Figure 8. 2792 The specification column for all of these entries will be this 2793 document. 2795 10.7. ACE Groupcomm Profile Registry 2797 This specification establishes the "ACE Groupcomm Profile" IANA 2798 Registry. The Registry has been created to use the "Expert Review" 2799 registration procedure [RFC8126]. Expert review guidelines are 2800 provided in Section 10.14. It should be noted that, in addition to 2801 the expert review, some portions of the Registry require a 2802 specification, potentially a Standards Track RFC, to be supplied as 2803 well. 2805 The columns of this Registry are: 2807 o Name: The name of the application profile, to be used as value of 2808 the profile attribute. 2810 o Description: Text giving an overview of the application profile 2811 and the context it is developed for. 2813 o CBOR Value: CBOR abbreviation for the name of this application 2814 profile. Different ranges of values use different registration 2815 policies [RFC8126]. Integer values from -256 to 255 are 2816 designated as Standards Action. Integer values from -65536 to 2817 -257 and from 256 to 65535 are designated as Specification 2818 Required. Integer values greater than 65535 are designated as 2819 Expert Review. Integer values less than -65536 are marked as 2820 Private Use. 2822 o Reference: This contains a pointer to the public specification of 2823 the abbreviation for this application profile, if one exists. 2825 10.8. ACE Groupcomm Policy Registry 2827 This specification establishes the "ACE Groupcomm Policy" IANA 2828 Registry. The Registry has been created to use the "Expert Review" 2829 registration procedure [RFC8126]. Expert review guidelines are 2830 provided in Section 10.14. It should be noted that, in addition to 2831 the expert review, some portions of the Registry require a 2832 specification, potentially a Standards Track RFC, to be supplied as 2833 well. 2835 The columns of this Registry are: 2837 o Name: The name of the group communication policy. 2839 o CBOR label: The value to be used to identify this group 2840 communication policy. Key map labels MUST be unique. The label 2841 can be a positive integer, a negative integer or a string. 2842 Integer values between 0 and 255 and strings of length 1 are 2843 designated as Standards Track Document required. Integer values 2844 from 256 to 65535 and strings of length 2 are designated as 2845 Specification Required. Integer values greater than 65535 and 2846 strings of length greater than 2 are designated as expert review. 2847 Integer values less than -65536 are marked as private use. 2849 o CBOR type: the CBOR type used to encode the value of this group 2850 communication policy. 2852 o Description: This field contains a brief description for this 2853 group communication policy. 2855 o Reference: This field contains a pointer to the public 2856 specification providing the format of the group communication 2857 policy, if one exists. 2859 This registry will be initially populated by the values in Figure 9. 2861 10.9. Sequence Number Synchronization Method Registry 2863 This specification establishes the "Sequence Number Synchronization 2864 Method" IANA Registry. The Registry has been created to use the 2865 "Expert Review" registration procedure [RFC8126]. Expert review 2866 guidelines are provided in Section 10.14. It should be noted that, 2867 in addition to the expert review, some portions of the Registry 2868 require a specification, potentially a Standards Track RFC, to be 2869 supplied as well. 2871 The columns of this Registry are: 2873 o Name: The name of the sequence number synchronization method. 2875 o Value: The value to be used to identify this sequence number 2876 synchronization method. 2878 o Description: This field contains a brief description for this 2879 sequence number synchronization method. 2881 o Reference: This field contains a pointer to the public 2882 specification describing the sequence number synchronization 2883 method. 2885 10.10. Interface Description (if=) Link Target Attribute Values 2886 Registry 2888 This specification registers the following entry to the "Interface 2889 Description (if=) Link Target Attribute Values Registry" registry, 2890 within the "CoRE Parameters" registry: 2892 o Attribute Value: ace.group 2894 o Description: The 'ace group' interface is used to provision keying 2895 material and related information and policies to members of a 2896 group using the Ace framework. 2898 o Reference: [This Document] 2900 10.11. CBOR Tags Registry 2902 This specification registers the following entry to the "CBOR Tags" 2903 registry: 2905 o Tag : TBD_TAG 2907 o Data Item: byte string 2909 o Semantics: Extended ACE scope format, including the identifier of 2910 the used scope semantics. 2912 o Reference: [This Document] 2914 10.12. ACE Scope Semantics 2916 This specification establishes the "ACE Scope Semantics" IANA 2917 Registry. The Registry has been created to use the "Expert Review" 2918 registration procedure [RFC8126]. Expert review guidelines are 2919 provided in Section 10.14. It should be noted that, in addition to 2920 the expert review, some portions of the Registry require a 2921 specification, potentially a Standards Track RFC, to be supplied as 2922 well. 2924 The columns of this Registry are: 2926 o Value: The value to be used to identify this scope semantics. The 2927 value MUST be unique. The value can be a positive integer or a 2928 negative integer. Integer values between 0 and 255 are designated 2929 as Standards Track Document required. Integer values from 256 to 2930 65535 are designated as Specification Required. Integer values 2931 greater than 65535 are designated as expert review. Integer 2932 values less than -65536 are marked as private use. 2934 o Description: This field contains a brief description of the scope 2935 semantics. 2937 o Reference: This field contains a pointer to the public 2938 specification defining the scope semantics, if one exists. 2940 10.13. ACE Groupcomm Errors 2942 This specification establishes the "ACE Groupcomm Errors" IANA 2943 Registry. The Registry has been created to use the "Expert Review" 2944 registration procedure [RFC8126]. Expert review guidelines are 2945 provided in Section 10.14. It should be noted that, in addition to 2946 the expert review, some portions of the Registry require a 2947 specification, potentially a Standards Track RFC, to be supplied as 2948 well. 2950 The columns of this Registry are: 2952 o Value: The value to be used to identify the error. The value MUST 2953 be unique. The value can be a positive integer or a negative 2954 integer. Integer values between 0 and 255 are designated as 2955 Standards Track Document required. Integer values from 256 to 2956 65535 are designated as Specification Required. Integer values 2957 greater than 65535 are designated as expert review. Integer 2958 values less than -65536 are marked as private use. 2960 o Description: This field contains a brief description of the error. 2962 o Reference: This field contains a pointer to the public 2963 specification defining the error, if one exists. 2965 This Registry has been initially populated by the values in 2966 Section 8. The Reference column for all of these entries refers to 2967 this document. 2969 10.14. Expert Review Instructions 2971 The IANA Registries established in this document are defined as 2972 expert review. This section gives some general guidelines for what 2973 the experts should be looking for, but they are being designated as 2974 experts for a reason so they should be given substantial latitude. 2976 Expert reviewers should take into consideration the following points: 2978 o Point squatting should be discouraged. Reviewers are encouraged 2979 to get sufficient information for registration requests to ensure 2980 that the usage is not going to duplicate one that is already 2981 registered and that the point is likely to be used in deployments. 2982 The zones tagged as private use are intended for testing purposes 2983 and closed environments, code points in other ranges should not be 2984 assigned for testing. 2986 o Specifications are required for the standards track range of point 2987 assignment. Specifications should exist for specification 2988 required ranges, but early assignment before a specification is 2989 available is considered to be permissible. Specifications are 2990 needed for the first-come, first-serve range if they are expected 2991 to be used outside of closed environments in an interoperable way. 2992 When specifications are not provided, the description provided 2993 needs to have sufficient information to identify what the point is 2994 being used for. 2996 o Experts should take into account the expected usage of fields when 2997 approving point assignment. The fact that there is a range for 2998 standards track documents does not mean that a standards track 2999 document cannot have points assigned outside of that range. The 3000 length of the encoded value should be weighed against how many 3001 code points of that length are left, the size of device it will be 3002 used on, and the number of code points left that encode to that 3003 size. 3005 11. References 3007 11.1. Normative References 3009 [COSE.Algorithms] 3010 IANA, "COSE Algorithms", 3011 . 3014 [I-D.ietf-ace-aif] 3015 Bormann, C., "An Authorization Information Format (AIF) 3016 for ACE", draft-ietf-ace-aif-02 (work in progress), 3017 February 2021. 3019 [I-D.ietf-ace-oauth-authz] 3020 Seitz, L., Selander, G., Wahlstroem, E., Erdtman, S., and 3021 H. Tschofenig, "Authentication and Authorization for 3022 Constrained Environments (ACE) using the OAuth 2.0 3023 Framework (ACE-OAuth)", draft-ietf-ace-oauth-authz-37 3024 (work in progress), February 2021. 3026 [I-D.ietf-core-oscore-groupcomm] 3027 Tiloca, M., Selander, G., Palombini, F., Mattsson, J., and 3028 J. Park, "Group OSCORE - Secure Group Communication for 3029 CoAP", draft-ietf-core-oscore-groupcomm-11 (work in 3030 progress), February 2021. 3032 [I-D.ietf-cose-rfc8152bis-algs] 3033 Schaad, J., "CBOR Object Signing and Encryption (COSE): 3034 Initial Algorithms", draft-ietf-cose-rfc8152bis-algs-12 3035 (work in progress), September 2020. 3037 [I-D.ietf-cose-rfc8152bis-struct] 3038 Schaad, J., "CBOR Object Signing and Encryption (COSE): 3039 Structures and Process", draft-ietf-cose-rfc8152bis- 3040 struct-15 (work in progress), February 2021. 3042 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 3043 Requirement Levels", BCP 14, RFC 2119, 3044 DOI 10.17487/RFC2119, March 1997, 3045 . 3047 [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", 3048 RFC 6749, DOI 10.17487/RFC6749, October 2012, 3049 . 3051 [RFC6838] Freed, N., Klensin, J., and T. Hansen, "Media Type 3052 Specifications and Registration Procedures", BCP 13, 3053 RFC 6838, DOI 10.17487/RFC6838, January 2013, 3054 . 3056 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 3057 Application Protocol (CoAP)", RFC 7252, 3058 DOI 10.17487/RFC7252, June 2014, 3059 . 3061 [RFC7967] Bhattacharyya, A., Bandyopadhyay, S., Pal, A., and T. 3062 Bose, "Constrained Application Protocol (CoAP) Option for 3063 No Server Response", RFC 7967, DOI 10.17487/RFC7967, 3064 August 2016, . 3066 [RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for 3067 Writing an IANA Considerations Section in RFCs", BCP 26, 3068 RFC 8126, DOI 10.17487/RFC8126, June 2017, 3069 . 3071 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 3072 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 3073 May 2017, . 3075 [RFC8610] Birkholz, H., Vigano, C., and C. Bormann, "Concise Data 3076 Definition Language (CDDL): A Notational Convention to 3077 Express Concise Binary Object Representation (CBOR) and 3078 JSON Data Structures", RFC 8610, DOI 10.17487/RFC8610, 3079 June 2019, . 3081 [RFC8742] Bormann, C., "Concise Binary Object Representation (CBOR) 3082 Sequences", RFC 8742, DOI 10.17487/RFC8742, February 2020, 3083 . 3085 [RFC8747] Jones, M., Seitz, L., Selander, G., Erdtman, S., and H. 3086 Tschofenig, "Proof-of-Possession Key Semantics for CBOR 3087 Web Tokens (CWTs)", RFC 8747, DOI 10.17487/RFC8747, March 3088 2020, . 3090 [RFC8949] Bormann, C. and P. Hoffman, "Concise Binary Object 3091 Representation (CBOR)", STD 94, RFC 8949, 3092 DOI 10.17487/RFC8949, December 2020, 3093 . 3095 11.2. Informative References 3097 [I-D.ietf-ace-dtls-authorize] 3098 Gerdes, S., Bergmann, O., Bormann, C., Selander, G., and 3099 L. Seitz, "Datagram Transport Layer Security (DTLS) 3100 Profile for Authentication and Authorization for 3101 Constrained Environments (ACE)", draft-ietf-ace-dtls- 3102 authorize-15 (work in progress), January 2021. 3104 [I-D.ietf-ace-mqtt-tls-profile] 3105 Sengul, C. and A. Kirby, "Message Queuing Telemetry 3106 Transport (MQTT)-TLS profile of Authentication and 3107 Authorization for Constrained Environments (ACE) 3108 Framework", draft-ietf-ace-mqtt-tls-profile-10 (work in 3109 progress), December 2020. 3111 [I-D.ietf-ace-oscore-profile] 3112 Palombini, F., Seitz, L., Selander, G., and M. Gunnarsson, 3113 "OSCORE Profile of the Authentication and Authorization 3114 for Constrained Environments Framework", draft-ietf-ace- 3115 oscore-profile-16 (work in progress), January 2021. 3117 [I-D.ietf-core-coap-pubsub] 3118 Koster, M., Keranen, A., and J. Jimenez, "Publish- 3119 Subscribe Broker for the Constrained Application Protocol 3120 (CoAP)", draft-ietf-core-coap-pubsub-09 (work in 3121 progress), September 2019. 3123 [I-D.ietf-core-groupcomm-bis] 3124 Dijk, E., Wang, C., and M. Tiloca, "Group Communication 3125 for the Constrained Application Protocol (CoAP)", draft- 3126 ietf-core-groupcomm-bis-03 (work in progress), February 3127 2021. 3129 [RFC2093] Harney, H. and C. Muckenhirn, "Group Key Management 3130 Protocol (GKMP) Specification", RFC 2093, 3131 DOI 10.17487/RFC2093, July 1997, 3132 . 3134 [RFC2094] Harney, H. and C. Muckenhirn, "Group Key Management 3135 Protocol (GKMP) Architecture", RFC 2094, 3136 DOI 10.17487/RFC2094, July 1997, 3137 . 3139 [RFC2627] Wallner, D., Harder, E., and R. Agee, "Key Management for 3140 Multicast: Issues and Architectures", RFC 2627, 3141 DOI 10.17487/RFC2627, June 1999, 3142 . 3144 [RFC7519] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token 3145 (JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015, 3146 . 3148 [RFC7641] Hartke, K., "Observing Resources in the Constrained 3149 Application Protocol (CoAP)", RFC 7641, 3150 DOI 10.17487/RFC7641, September 2015, 3151 . 3153 [RFC7959] Bormann, C. and Z. Shelby, Ed., "Block-Wise Transfers in 3154 the Constrained Application Protocol (CoAP)", RFC 7959, 3155 DOI 10.17487/RFC7959, August 2016, 3156 . 3158 [RFC8259] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 3159 Interchange Format", STD 90, RFC 8259, 3160 DOI 10.17487/RFC8259, December 2017, 3161 . 3163 [RFC8392] Jones, M., Wahlstroem, E., Erdtman, S., and H. Tschofenig, 3164 "CBOR Web Token (CWT)", RFC 8392, DOI 10.17487/RFC8392, 3165 May 2018, . 3167 [RFC8613] Selander, G., Mattsson, J., Palombini, F., and L. Seitz, 3168 "Object Security for Constrained RESTful Environments 3169 (OSCORE)", RFC 8613, DOI 10.17487/RFC8613, July 2019, 3170 . 3172 11.3. URIs 3174 [1] mailto:iesg@ietf.org 3176 [2] mailto:francesca.palombini@ericsson.com 3178 Appendix A. Requirements on Application Profiles 3180 This section lists the requirements on application profiles of this 3181 specification,for the convenience of application profile designers. 3183 o REQ1: If the value of the GROUPNAME URI path and the group name in 3184 the access token scope (gname in Section 3.2) don't match, specify 3185 the mechanism to map the GROUPNAME value in the URI to the group 3186 name (REQ1) (see Section 4.1). 3188 o REQ2: Specify the encoding and value of roles, for scope entries 3189 of 'scope' (see Section 3.1). 3191 o REQ3: If used, specify the acceptable values for 'sign_alg' (see 3192 Section 3.3). 3194 o REQ4: If used, specify the acceptable values for 'sign_parameters' 3195 (see Section 3.3). 3197 o REQ5: If used, specify the acceptable values for 3198 'sign_key_parameters' (see Section 3.3). 3200 o REQ6: If used, specify the acceptable values for 'pub_key_enc' 3201 (see Section 3.3). 3203 o REQ7: Register a Resource Type for the root url-path, which is 3204 used to discover the correct url to access at the KDC (see 3205 Section 4.1). 3207 o REQ8: Define what operations (e.g. CoAP methods) are allowed on 3208 each resource, for each role defined in REQ2 (see Section 3.3). 3210 o REQ9: Specify the exact encoding of group identifier (see 3211 Section 4.1.1.1). 3213 o REQ10: Specify the exact format of the 'key' value (see 3214 Section 4.1.2.1). 3216 o REQ11: Specify the acceptable values of 'gkty' (see 3217 Section 4.1.2.1). 3219 o REQ12: Specify the format of the identifiers of group members (see 3220 Section 4.1.2.1). 3222 o REQ13: Specify the communication protocol the members of the group 3223 must use (e.g., multicast CoAP). 3225 o REQ14: Specify the security protocol the group members must use to 3226 protect their communication (e.g., group OSCORE). This must 3227 provide encryption, integrity and replay protection. 3229 o REQ15: Specify and register the application profile identifier 3230 (see Section 4.1.2.1). 3232 o REQ16: Specify policies at the KDC to handle ids that are not 3233 included in 'get_pub_keys' (see Section 4.1.3.1). 3235 o REQ17: If used, specify the format and content of 'group_policies' 3236 and its entries. Specify the policies default values (see 3237 Section 4.1.2.1). 3239 o REQ18: Specify the format of newly-generated individual keying 3240 material for group members, or of the information to derive it, 3241 and corresponding CBOR label (see Section 4.1.6.2). 3243 o REQ19: Specify how the communication is secured between Client and 3244 KDC. Optionally, specify tranport profile of ACE 3245 [I-D.ietf-ace-oauth-authz] to use between Client and KDC (see 3246 Section 4.3. 3248 o REQ20: Specify how the nonce N_S is generated, if the token was 3249 not posted (e.g. if it is used directly to validate TLS instead). 3251 o REQ21: Specify if 'mgt_key_material' used, and if yes specify its 3252 format and content (see Section 4.1.2.1). If the usage of 3253 'mgt_key_material' is indicated and its format defined for a 3254 specific key management scheme, that format must explicitly 3255 indicate the key management scheme itself. If a new rekeying 3256 scheme is defined to be used for an existing 'mgt_key_material' in 3257 an existing profile, then that profile will have to be updated 3258 accordingly, especially with respect to the usage of 3259 'mgt_key_material' related format and content. 3261 o REQ22: Define the initial value of the 'num' parameter (see 3262 Section 4.1.2.1). 3264 o REQ23: Specify and register the identifier of newly defined 3265 semantics for binary scopes (see Section 6). 3267 o OPT1: Optionally, specify the encoding of public keys, of 3268 'client_cred', and of 'pub_keys' if COSE_Keys are not used (see 3269 Section 4.1.2.1). 3271 o OPT2: Optionally, specify the negotiation of parameter values for 3272 signature algorithm and signature keys, if 'sign_info' is not used 3273 (see Section 3.3). 3275 o OPT3: Optionally, specify the additional parameters used in the 3276 Token Post exchange (see Section 3.3). 3278 o OPT4: Optionally, specify the encoding of 'pub_keys_repos' if the 3279 default is not used (see Section 4.1.2.1). 3281 o OPT5: Optionally, specify policies that instruct clients to retain 3282 messages and for how long, if they are unsuccessfully decrypted 3283 (see Section 4.4). This makes it possible to decrypt such 3284 messages after getting updated keying material. 3286 o OPT6: Optionally, specify the behavior of the handler in case of 3287 failure to retrieve a public key for the specific node (see 3288 Section 4.1.2.1). 3290 o OPT7: Optionally, specify possible or required payload formats for 3291 specific error cases. 3293 o OPT8: Optionally, specify CBOR values to use for abbreviating 3294 identifiers of roles in the group or topic (see Section 3.1). 3296 o OPT9: Optionally, specify for the KDC to perform group rekeying 3297 (together or instead of renewing individual keying material) when 3298 receiving a Key Renewal Request (see Section 4.5). 3300 o OPT10: Optionally, specify the functionalities implemented at the 3301 'control_uri' resource hosted at the Client, including message 3302 exchange encoding and other details (see Section 4.1.2.1). 3304 o OPT11: Optionally, specify how the identifier of the sender's 3305 public key is included in the group request (see Section 4.7). 3307 o OPT12: Optionally, specify additional identifiers of error types, 3308 as values of the 'error' field in an error response from the KDC. 3310 Appendix B. Document Updates 3312 RFC EDITOR: PLEASE REMOVE THIS SECTION. 3314 B.1. Version -04 to -05 3316 o Updated uppercase/lowercase URI segments for KDC resources. 3318 o Supporting single Access Token for multiple groups/topics. 3320 o Added 'control_uri' parameter in the Joining Request. 3322 o Added 'peer_roles' parameter to support legal requesters/ 3323 responders. 3325 o Clarification on stopping using owned keying material. 3327 o Clarification on different reasons for processing failures, 3328 related policies, and requirement OPT4. 3330 o Added a KDC sub-resource for group members to upload a new public 3331 key. 3333 o Possible group rekeying following an individual Key Renewal 3334 Request. 3336 o Clarified meaning of requirement REQ3; added requirement OPT8. 3338 o Editorial improvements. 3340 B.2. Version -03 to -04 3342 o Revised RESTful interface, as to methods and parameters. 3344 o Extended processing of joining request, as to check/retrieval of 3345 public keys. 3347 o Revised and extended profile requirements. 3349 o Clarified specific usage of parameters related to signature 3350 algorithms/keys. 3352 o Included general content previously in draft-ietf-ace-key- 3353 groupcomm-oscore 3355 o Registration of media type and content format application/ace- 3356 group+cbor 3358 o Editorial improvements. 3360 B.3. Version -02 to -03 3362 o Exchange of information on the countersignature algorithm and 3363 related parameters, during the Token POST (Section 3.3). 3365 o Restructured KDC interface, with new possible operations 3366 (Section 4). 3368 o Client PoP signature for the Joining Request upon joining 3369 (Section 4.1.2.1). 3371 o Revised text on group member removal (Section 5). 3373 o Added more profile requirements (Appendix A). 3375 B.4. Version -01 to -02 3377 o Editorial fixes. 3379 o Distinction between transport profile and application profile 3380 (Section 1.1). 3382 o New parameters 'sign_info' and 'pub_key_enc' to negotiate 3383 parameter values for signature algorithm and signature keys 3384 (Section 3.3). 3386 o New parameter 'type' to distinguish different Key Distribution 3387 Request messages (Section 4.1). 3389 o New parameter 'client_cred_verify' in the Key Distribution Request 3390 to convey a Client signature (Section 4.1). 3392 o Encoding of 'pub_keys_repos' (Section 4.1). 3394 o Encoding of 'mgt_key_material' (Section 4.1). 3396 o Improved description on retrieval of new or updated keying 3397 material (Section 6). 3399 o Encoding of 'get_pub_keys' in Public Key Request (Section 7.1). 3401 o Extended security considerations (Sections 10.1 and 10.2). 3403 o New "ACE Public Key Encoding" IANA Registry (Section 11.2). 3405 o New "ACE Groupcomm Parameters" IANA Registry (Section 11.3), 3406 populated with the entries in Section 8. 3408 o New "Ace Groupcomm Request Type" IANA Registry (Section 11.4), 3409 populated with the values in Section 9. 3411 o New "ACE Groupcomm Policy" IANA Registry (Section 11.7) populated 3412 with two entries "Sequence Number Synchronization Method" and "Key 3413 Update Check Interval" (Section 4.2). 3415 o Improved list of requirements for application profiles 3416 (Appendix A). 3418 B.5. Version -00 to -01 3420 o Changed name of 'req_aud' to 'audience' in the Authorization 3421 Request (Section 3.1). 3423 o Defined error handling on the KDC (Sections 4.2 and 6.2). 3425 o Updated format of the Key Distribution Response as a whole 3426 (Section 4.2). 3428 o Generalized format of 'pub_keys' in the Key Distribution Response 3429 (Section 4.2). 3431 o Defined format for the message to request leaving the group 3432 (Section 5.2). 3434 o Renewal of individual keying material and methods for group 3435 rekeying initiated by the KDC (Section 6). 3437 o CBOR type for node identifiers in 'get_pub_keys' (Section 7.1). 3439 o Added section on parameter identifiers and their CBOR keys 3440 (Section 8). 3442 o Added request types for requests to a Join Response (Section 9). 3444 o Extended security considerations (Section 10). 3446 o New IANA registries "ACE Groupcomm Key Registry", "ACE Groupcomm 3447 Profile Registry", "ACE Groupcomm Policy Registry" and "Sequence 3448 Number Synchronization Method Registry" (Section 11). 3450 o Added appendix about requirements for application profiles of ACE 3451 on group communication (Appendix A). 3453 Acknowledgments 3455 The following individuals were helpful in shaping this document: 3456 Christian Amsuess, Carsten Bormann, Rikard Hoeglund, Ben Kaduk, John 3457 Mattsson, Daniel Migault, Jim Schaad, Ludwig Seitz, Goeran Selander 3458 and Peter van der Stok. 3460 The work on this document has been partly supported by VINNOVA and 3461 the Celtic-Next project CRITISEC; by the H2020 project SIFIS-Home 3462 (Grant agreement 952652); and by the EIT-Digital High Impact 3463 Initiative ACTIVE. 3465 Authors' Addresses 3466 Francesca Palombini 3467 Ericsson AB 3468 Torshamnsgatan 23 3469 Kista SE-16440 Stockholm 3470 Sweden 3472 Email: francesca.palombini@ericsson.com 3474 Marco Tiloca 3475 RISE AB 3476 Isafjordsgatan 22 3477 Kista SE-16440 Stockholm 3478 Sweden 3480 Email: marco.tiloca@ri.se