idnits 2.17.1 draft-ietf-ace-key-groupcomm-13.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 (12 July 2021) is 1018 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 1831 -- Looks like a reference, but probably isn't: '02' on line 1831 == Unused Reference: 'I-D.ietf-cose-rfc8152bis-struct' is defined on line 3137, but no explicit reference was found in the text == Outdated reference: A later version (-07) exists of draft-ietf-ace-aif-03 == Outdated reference: A later version (-46) exists of draft-ietf-ace-oauth-authz-43 == Outdated reference: A later version (-21) exists of draft-ietf-core-oscore-groupcomm-12 ** 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 (-17) exists of draft-ietf-ace-mqtt-tls-profile-12 == Outdated reference: A later version (-14) exists of draft-ietf-core-coap-pubsub-09 == Outdated reference: A later version (-11) exists of draft-ietf-core-groupcomm-bis-04 Summary: 2 errors (**), 0 flaws (~~), 8 warnings (==), 4 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: 13 January 2022 RISE AB 6 12 July 2021 8 Key Provisioning for Group Communication using ACE 9 draft-ietf-ace-key-groupcomm-13 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 Discussion Venues 19 This note is to be removed before publishing as an RFC. 21 Source for this draft and an issue tracker can be found at 22 https://github.com/ace-wg/ace-key-groupcomm. 24 Status of This Memo 26 This Internet-Draft is submitted in full conformance with the 27 provisions of BCP 78 and BCP 79. 29 Internet-Drafts are working documents of the Internet Engineering 30 Task Force (IETF). Note that other groups may also distribute 31 working documents as Internet-Drafts. The list of current Internet- 32 Drafts is at https://datatracker.ietf.org/drafts/current/. 34 Internet-Drafts are draft documents valid for a maximum of six months 35 and may be updated, replaced, or obsoleted by other documents at any 36 time. It is inappropriate to use Internet-Drafts as reference 37 material or to cite them other than as "work in progress." 39 This Internet-Draft will expire on 13 January 2022. 41 Copyright Notice 43 Copyright (c) 2021 IETF Trust and the persons identified as the 44 document authors. All rights reserved. 46 This document is subject to BCP 78 and the IETF Trust's Legal 47 Provisions Relating to IETF Documents (https://trustee.ietf.org/ 48 license-info) in effect on the date of publication of this document. 49 Please review these documents carefully, as they describe your rights 50 and restrictions with respect to this document. Code Components 51 extracted from this document must include Simplified BSD License text 52 as described in Section 4.e of the Trust Legal Provisions and are 53 provided without warranty as described in the Simplified BSD License. 55 Table of Contents 57 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 58 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 4 59 2. Overview . . . . . . . . . . . . . . . . . . . . . . . . . . 5 60 3. Authorization to Join a Group . . . . . . . . . . . . . . . . 8 61 3.1. Authorization Request . . . . . . . . . . . . . . . . . . 8 62 3.2. Authorization Response . . . . . . . . . . . . . . . . . 10 63 3.3. Token Post . . . . . . . . . . . . . . . . . . . . . . . 12 64 4. Keying Material Provisioning and Group Membership 65 Management . . . . . . . . . . . . . . . . . . . . . . . 15 66 4.1. Interface at the KDC . . . . . . . . . . . . . . . . . . 17 67 4.2. Retrieval of Group Names and URIs . . . . . . . . . . . . 39 68 4.3. Joining Exchange . . . . . . . . . . . . . . . . . . . . 40 69 4.4. Retrieval of Updated Keying Material . . . . . . . . . . 42 70 4.5. Requesting a Change of Keying Material . . . . . . . . . 44 71 4.6. Retrieval of Public Keys and Roles for Group Members . . 45 72 4.7. Update of Public Key . . . . . . . . . . . . . . . . . . 47 73 4.8. Retrieval of Group Policies . . . . . . . . . . . . . . . 48 74 4.9. Retrieval of Keying Material Version . . . . . . . . . . 49 75 4.10. Group Leaving Request . . . . . . . . . . . . . . . . . . 50 76 5. Removal of a Node from the Group . . . . . . . . . . . . . . 50 77 6. Extended Scope Format . . . . . . . . . . . . . . . . . . . . 52 78 7. ACE Groupcomm Parameters . . . . . . . . . . . . . . . . . . 54 79 8. ACE Groupcomm Error Identifiers . . . . . . . . . . . . . . . 55 80 9. Security Considerations . . . . . . . . . . . . . . . . . . . 56 81 9.1. Update of Keying Material . . . . . . . . . . . . . . . . 57 82 9.2. Block-Wise Considerations . . . . . . . . . . . . . . . . 58 83 10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 58 84 10.1. Media Type Registrations . . . . . . . . . . . . . . . . 58 85 10.2. CoAP Content-Formats Registry . . . . . . . . . . . . . 59 86 10.3. OAuth Parameters Registry . . . . . . . . . . . . . . . 60 87 10.4. OAuth Parameters CBOR Mappings Registry . . . . . . . . 60 88 10.5. ACE Groupcomm Parameters Registry . . . . . . . . . . . 61 89 10.6. ACE Groupcomm Key Registry . . . . . . . . . . . . . . . 61 90 10.7. ACE Groupcomm Profile Registry . . . . . . . . . . . . . 62 91 10.8. ACE Groupcomm Policy Registry . . . . . . . . . . . . . 63 92 10.9. Sequence Number Synchronization Method Registry . . . . 63 93 10.10. Interface Description (if=) Link Target Attribute Values 94 Registry . . . . . . . . . . . . . . . . . . . . . . . 64 95 10.11. CBOR Tags Registry . . . . . . . . . . . . . . . . . . . 64 96 10.12. ACE Scope Semantics . . . . . . . . . . . . . . . . . . 65 97 10.13. ACE Groupcomm Errors . . . . . . . . . . . . . . . . . . 65 98 10.14. Expert Review Instructions . . . . . . . . . . . . . . . 66 99 11. References . . . . . . . . . . . . . . . . . . . . . . . . . 66 100 11.1. Normative References . . . . . . . . . . . . . . . . . . 66 101 11.2. Informative References . . . . . . . . . . . . . . . . . 69 102 Appendix A. Requirements on Application Profiles . . . . . . . . 70 103 Appendix B. Extensibility for Future COSE Algorithms . . . . . . 73 104 B.1. Format of 'sign_info_entry' . . . . . . . . . . . . . . . 74 105 Appendix C. Document Updates . . . . . . . . . . . . . . . . . . 74 106 C.1. Version -04 to -05 . . . . . . . . . . . . . . . . . . . 74 107 C.2. Version -03 to -04 . . . . . . . . . . . . . . . . . . . 75 108 C.3. Version -02 to -03 . . . . . . . . . . . . . . . . . . . 75 109 C.4. Version -01 to -02 . . . . . . . . . . . . . . . . . . . 76 110 C.5. Version -00 to -01 . . . . . . . . . . . . . . . . . . . 76 111 Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . 77 112 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 77 114 1. Introduction 116 This document expands the ACE framework [I-D.ietf-ace-oauth-authz] to 117 define the message exchanges used to request, distribute and renew 118 the keying material in a group communication scenario, e.g., based on 119 multicast [I-D.ietf-core-groupcomm-bis] or on publishing-subscribing 120 [I-D.ietf-core-coap-pubsub]. The ACE framework is based on CBOR 121 [RFC8949], so CBOR is the format used in this specification. 122 However, using JSON [RFC8259] instead of CBOR is possible, using the 123 conversion method specified in Sections 6.1 and 6.2 of [RFC8949]. 125 Profiles that use group communication can build on this document, by 126 defining a number of details such as the exact group communication 127 protocol and security protocols used. The specific list of details a 128 profile needs to define is shown in Appendix A. 130 If the application requires backward and forward security, new keying 131 material is generated and distributed to the group upon membership 132 changes. A key management scheme performs the actual distribution of 133 the new keying material to the group. In particular, the key 134 management scheme rekeys the current group members when a new node 135 joins the group, and the remaining group members when a node leaves 136 the group. Rekeying mechanisms can be based on [RFC2093], [RFC2094] 137 and [RFC2627]. 139 1.1. Terminology 141 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 142 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 143 "OPTIONAL" in this document are to be interpreted as described in BCP 144 14 [RFC2119] [RFC8174] when, and only when, they appear in all 145 capitals, as shown here. 147 Readers are expected to be familiar with the terms and concepts 148 described in [I-D.ietf-ace-oauth-authz][I-D.ietf-cose-rfc8152bis-stru 149 ct][I-D.ietf-cose-rfc8152bis-algs], such as Authorization Server (AS) 150 and Resource Server (RS). 152 This document uses names or identifiers for groups and nodes. Their 153 different meanings are summarized here: 155 * "Group name" is the invariant once established identifier of the 156 group. It is used in the communication between AS, RS and Client 157 to identify the group. 159 * "GROUPNAME" is the invariant once established text string used in 160 URIs. GROUPNAME maps to the group name of a group, although it is 161 not necessarily the same. 163 * "Group identifier" is the identifier of the group keying material. 164 Opposite to group name and GROUPNAME, this identifier changes over 165 time, when the keying material is updated. 167 * "Node name" is the invariant once established identifier of the 168 node. It is used in the communication between AS, RS and Client 169 to identify a member of the group. 171 * "NODENAME" is the invariant once established text string used in 172 URIs. NODENAME is used to identify a node in a group. 174 This document additionally uses the following terminology: 176 * Transport profile, to indicate a profile of ACE as per 177 Section 5.8.4.3 of [I-D.ietf-ace-oauth-authz]. A transport 178 profile specifies the communication protocol and communication 179 security protocol between an ACE Client and Resource Server, as 180 well as proof-of-possession methods, if it supports proof-of- 181 possession access tokens, etc. Tranport profiles of ACE include, 182 for instance, [I-D.ietf-ace-oscore-profile], 183 [I-D.ietf-ace-dtls-authorize] and [I-D.ietf-ace-mqtt-tls-profile]. 185 * Application profile, that defines how applications enforce and use 186 supporting security services they require. These services may 187 include, for instance, provisioning, revocation and distribution 188 of keying material. An application profile may define specific 189 procedures and message formats. 191 2. Overview 193 The full procedure can be separated in two phases: the first one 194 follows the ACE framework, between Client, AS and KDC; the second one 195 is the key distribution between Client and KDC. After the two phases 196 are completed, the Client is able to participate in the group 197 communication, via a Dispatcher entity. 199 +------------+ +-----------+ 200 | AS | | KDC | 201 | | .-------->| | 202 +------------+ / +-----------+ 203 ^ / 204 | / 205 v / +-----------+ 206 +------------+ / +------------+ |+-----------+ 207 | Client |<-' | Dispatcher | ||+-----------+ 208 | |<-------->| |<------->|| Group | 209 +------------+ +------------+ +| members | 210 +-----------+ 212 Figure 1: Key Distribution Participants 214 The following participants (see Figure 1) take part in the 215 authorization and key distribution. 217 * Client (C): node that wants to join the group communication. It 218 can request write and/or read rights. 220 * Authorization Server (AS): same as AS in the ACE Framework; it 221 enforces access policies, and knows if a node is allowed to join a 222 given group with write and/or read rights. 224 * Key Distribution Center (KDC): maintains the keying material to 225 protect group communications, and provides it to Clients 226 authorized to join a given group. During the first part of the 227 exchange (Section 3), it takes the role of the RS in the ACE 228 Framework. During the second part (Section 4), which is not based 229 on the ACE Framework, it distributes the keying material. In 230 addition, it provides the latest keying material to group members 231 when requested or, if required by the application, when membership 232 changes. 234 * Dispatcher: entity through which the Clients communicate with the 235 group and which distributes messages to the group members. 236 Examples of dispatchers are: the Broker node in a pub-sub setting; 237 a relayer node for group communication that delivers group 238 messages as multiple unicast messages to all group members; an 239 implicit entity as in a multicast communication setting, where 240 messages are transmitted to a multicast IP address and delivered 241 on the transport channel. 243 This document specifies a mechanism for: 245 * Authorizing a new node to join the group (Section 3), and 246 providing it with the group keying material to communicate with 247 the other group members (Section 4). 249 * Allowing a group member to retrieve group keying material 250 (Section 4.4 and Section 4.5). 252 * Allowing a group member to retrieve public keys of other group 253 members (Section 4.6) and to provide an updated public key 254 (Section 4.7). 256 * Allowing a group member to leave the group (Section 5). 258 * Evicting a group member from the group (Section 5). 260 * Renewing and re-distributing the group keying material (rekeying) 261 upon a membership change in the group (Section 4.10 and 262 Section 5). 264 Figure 2 provides a high level overview of the message flow for a 265 node joining a group communication setting, which can be expanded as 266 follows. 268 1. The joining node requests an Access Token from the AS, in order 269 to access a specific group-membership resource on the KDC and 270 hence join the associated group. This exchange between Client 271 and AS MUST be secured, as specified by the transport profile of 272 ACE used between Client and KDC. The joining node will start or 273 continue using a secure communication association with the KDC, 274 according to the response from the AS. 276 2. The joining node transfers authentication and authorization 277 information to the KDC, by posting the obtained Access Token to 278 the /authz-info endpoint at the KDC. This exchange, and all 279 further communications between the Client and the KDC, MUST occur 280 over the secure channel established as a result of the transport 281 profile of ACE used between Client and KDC. After that, a 282 joining node MUST have a secure communication association 283 established with the KDC, before starting to join a group under 284 that KDC. Possible ways to provide a secure communication 285 association are described in the DTLS transport profile 286 [I-D.ietf-ace-dtls-authorize] and OSCORE transport profile 287 [I-D.ietf-ace-oscore-profile] of ACE. 289 3. The joining node starts the joining process to become a member of 290 the group, by accessing the related group-membership resource at 291 the KDC. At the end of the joining process, the joining node has 292 received from the KDC the parameters and keying material to 293 securely communicate with the other members of the group, and the 294 KDC has stored the association between the authorization 295 information from the access token and the secure session with the 296 joining node. 298 4. The joining node and the KDC maintain the secure association, to 299 support possible future communications. These especially include 300 key management operations, such as retrieval of updated keying 301 material or participation to a group rekeying process. 303 5. The joining node can communicate securely with the other group 304 members, using the keying material provided in step 3. 306 C AS KDC Group 307 | | | Member 308 / | | | | 309 | | Authorization Request | | | 310 Defined | |-------------------------->| | | 311 in the | | | | | 312 ACE | | Authorization Response | | | 313 framework | |<--------------------------| | | 314 | | | | 315 \ |---------- Token Post --------->| | 316 | | | 317 |------- Joining Request ------->| | 318 | | | 319 |<------ Joining Response -------|-- Group Rekeying -->| 320 | | | 321 | Dispatcher | 322 | | | 323 |<===== Secure group communication =======|===========>| 324 | | | 326 Figure 2: Message Flow Upon New Node's Joining 328 3. Authorization to Join a Group 330 This section describes in detail the format of messages exchanged by 331 the participants when a node requests access to a given group. This 332 exchange is based on ACE [I-D.ietf-ace-oauth-authz]. 334 As defined in [I-D.ietf-ace-oauth-authz], the Client requests from 335 the AS an authorization to join the group through the KDC (see 336 Section 3.1). If the request is approved and authorization is 337 granted, the AS provides the Client with a proof-of-possession access 338 token and parameters to securely communicate with the KDC (see 339 Section 3.2). 341 Communications between the Client and the AS MUST be secured, as 342 defined by the transport profile of ACE used. The Content-Format 343 used in the message depends on the used transport profile of ACE. 344 For example, this can be application/ace+cbor for the first two 345 messages and application/cwt for the third message, which are defined 346 in the ACE framework. The transport profile of ACE also defines a 347 number of details such as the communication and security protocols 348 used with the KDC (see Appendix C of [I-D.ietf-ace-oauth-authz]). 350 Figure 3 gives an overview of the exchange described above. 352 Client AS KDC 353 | | | 354 |---- Authorization Request: POST /token ------>| | 355 | | | 356 |<--- Authorization Response: 2.01 (Created) ---| | 357 | | | 358 |----- POST Token: POST /authz-info --------------->| 359 | | 361 Figure 3: Message Flow of Join Authorization 363 3.1. Authorization Request 365 The Authorization Request sent from the Client to the AS is defined 366 in Section 5.8.1 of [I-D.ietf-ace-oauth-authz] and MAY contain the 367 following parameters, which, if included, MUST have the corresponding 368 values: 370 * 'scope', containing the identifier of the specific groups, or 371 topics in the case of pub-sub, that the Client wishes to access, 372 and optionally the roles that the Client wishes to take. 374 This value is a CBOR byte string, wrapping a CBOR array of one or 375 more entries. 377 By default, each entry is encoded as specified by 378 [I-D.ietf-ace-aif]. The object identifier Toid corresponds to the 379 group name and MUST be encoded as a tstr. The permission set 380 Tperm indicates the roles that the client wishes to take in the 381 group. It is up to the application profiles to define Tperm 382 (REQ2) and register Toid and Tperm to fit the use case. An 383 example of scope using the AIF format is given in Figure 4. 385 Otherwise, each scope entry can be defined as a CBOR array, which 386 contains: 388 - As first element, the identifier of the specific group or 389 topic, encoded as a tstr. 391 - Optionally, as second element, the role (or CBOR array of 392 roles) that the Client wishes to take in the group. This 393 element is optional since roles may have been pre-assigned to 394 the Client, as associated to its verifiable identity 395 credentials. Alternatively, the application may have defined a 396 single, well-known role for the target resource(s) and 397 audience(s). 399 In each entry, the encoding of the role identifiers is application 400 specific, and part of the requirements for the application profile 401 (REQ2). In particular, the application profile may specify CBOR 402 values to use for abbreviating role identifiers (OPT7). 404 An example of CDDL definition [RFC8610] of scope using the format 405 above, with group name and role identifiers encoded as text 406 strings is given in Figure 5. 408 * 'audience', with an identifier of a KDC. 410 As defined in [I-D.ietf-ace-oauth-authz], other additional parameters 411 can be included if necessary. 413 gname = tstr 415 permissions = uint . bits roles 417 roles = &( 418 Requester: 1, 419 Responder: 2, 420 Monitor: 3, 421 Verifier: 4 422 ) 424 scope_entry = AIF_Generic 426 scope = << [ + scope_entry ] >> 428 Figure 4: Example CDLL definition of scope, using the default 429 Authorization Information Format 431 gname = tstr 433 role = tstr 435 scope_entry = [ gname , ? ( role / [ 2*role ] ) ] 437 scope = << [ + scope_entry ] >> 439 Figure 5: CDLL definition of scope, using as example group name 440 encoded as tstr and role as tstr 442 3.2. Authorization Response 444 The Authorization Response sent from the AS to the Client is defined 445 in Section 5.8.2 of [I-D.ietf-ace-oauth-authz]. Note that the 446 parameter 'expires_in' MAY be omitted if the application defines how 447 the expiration time is communicated to the Client via other means, or 448 if it establishes a default value. 450 Additionally, when included, the following parameter MUST have the 451 corresponding values: 453 * 'scope' has the same format and encoding of 'scope' in the 454 Authorization Request, defined in Section 3.1. If this parameter 455 is not present, the granted scope is equal to the one requested in 456 Section 3.1}. 458 The proof-of-possession access token (in 'access_token' above) MUST 459 contain the following parameters: 461 * a confirmation claim (see for example 'cnf' defined in Section 3.1 462 of [RFC8747] for CWT); 464 * an expiration time claim (see for example 'exp' defined in 465 Section 3.1.4 of [RFC8392] for CWT); 467 * a scope claim (see for example 'scope' registered in Section 8.14 468 of [I-D.ietf-ace-oauth-authz] for CWT). 470 This claim specifies the same access control information as in the 471 'scope' parameter of the Authorization Response, if the parameter 472 is present in the message, or as in the 'scope' parameter of the 473 Authorization Request otherwise. 475 By default, this claim has the same encoding as the 'scope' 476 parameter in the Authorization Request, defined in Section 3.1. 478 Optionally, an alternative extended format of scope defined in 479 Section 6 can be used. This format explicitly signals the 480 semantics used to express the actual access control information, 481 and according to which this has to be parsed. This enables a 482 Resource Server to correctly process a received access token, also 483 in case: 485 - The Resource Server implements a KDC that supports multiple 486 application profiles of this specification, using different 487 scope semantics; and/or 489 - The Resource Server implements further services beyond a KDC 490 for group communication, using different scope semantics. 492 If the Authorization Server is aware that this applies to the 493 Resource Server for which the access token is issued, the 494 Authorization Server SHOULD use the extended format of scope 495 defined in Section 6. 497 The access token MAY additionally contain other claims that the 498 transport profile of ACE requires, or other optional parameters. 500 When receiving an Authorization Request from a Client that was 501 previously authorized, and for which the AS still owns a valid non- 502 expired access token, the AS MAY reply with that token. Note that it 503 is up to application profiles of ACE to make sure that re-posting the 504 same token does not cause re-use of keying material between nodes 505 (for example, that is done with the use of random nonces in 506 [I-D.ietf-ace-oscore-profile]). 508 3.3. Token Post 510 The Client sends a CoAP POST request including the access token to 511 the KDC, as specified in Section 5.8.1 of [I-D.ietf-ace-oauth-authz]. 513 This request differs from the one defined in 514 [I-D.ietf-ace-oauth-authz], because it allows to transport additional 515 encoding information about the public keys in the group, used for 516 source authentication, as well as any other group parameters. 518 The joining node MAY ask for this information from the KDC in the 519 same message it uses to POST the token to the RS. In such a case, 520 the message MUST have Content-Format set to application/ace+cbor 521 defined in Section 8.16 of [I-D.ietf-ace-oauth-authz]. The message 522 payload MUST be formatted as a CBOR map, which MUST include the 523 access token. The CBOR map MAY additionally include the following 524 parameter, which, if included, MUST have the corresponding values: 526 * 'sign_info' defined in Section 3.3.1, encoding the CBOR simple 527 value Null to require information about the signature algorithm, 528 signature algorithm parameters, signature key parameters and on 529 the exact encoding of public keys used in the group. 531 Alternatively, the joining node may retrieve this information by 532 other means. 534 After successful verification, the Client is authorized to receive 535 the group keying material from the KDC and join the group. 537 The KDC replies to the Client with a 2.01 (Created) response, using 538 Content-Format "application/ace+cbor". 540 The payload of the 2.01 response is a CBOR map. If the access token 541 contains a role that requires the Client to send its own public key 542 to the KDC when joining the group, the CBOR map MUST include the 543 parameter 'kdcchallenge' defined in Section 3.3.2, specifying a 544 dedicated challenge N_S generated by the KDC. The Client uses this 545 challenge to prove possession of its own private key (see the 546 'client_cred_verify' parameter in Section 4). Note that the payload 547 format of the response deviates from the one defined in the ACE 548 framework (see Section 5.10.1 of [I-D.ietf-ace-oauth-authz]), which 549 has no payload. 551 The KDC MUST store the 'kdcchallenge' value associated to the Client 552 at least until it receives a join request from it (see Section 4.3), 553 to be able to verify that the Client possesses its own private key. 554 The same challenge MAY be reused several times by the Client, to 555 generate a new proof of possession, e.g., in case of update of the 556 public key, or to join a different group with a different signing 557 key, so it is RECOMMENDED that the KDC keeps storing the 558 'kdcchallenge' after the first join is processed as well. If the KDC 559 has already discarded the 'kdcchallenge', that will trigger an error 560 response with a newly generated 'kdcchallenge' that the Client can 561 use to restart the join process, as specified in Section 4.3. 563 If 'sign_info' is included in the request, the KDC MAY include the 564 'sign_info' parameter defined in Section 3.3.1, with the same 565 encoding. Note that the field 'id' takes the value of the group name 566 for which the 'sign_info_entry' applies to. 568 Note that the CBOR map specified as payload of the 2.01 (Created) 569 response may include further parameters, e.g. according to the 570 signalled transport profile of ACE. Application profiles MAY define 571 the additional parameters to use within this exchange (OPT2). 573 Application profiles of this specification MAY define alternative 574 specific negotiations of parameter values for the signature algorithm 575 and signature keys, if 'sign_info' is not used (OPT1). 577 3.3.1. 'sign_info' Parameter 579 The 'sign_info' parameter is an OPTIONAL parameter of the Token Post 580 response message defined in Section 5.10.1. of 581 [I-D.ietf-ace-oauth-authz]. This parameter contains information and 582 parameters about the signature algorithm and the public keys to be 583 used between the Client and the RS. Its exact content is application 584 specific. 586 In this specification and in application profiles building on it, 587 this parameter is used to ask and retrieve from the KDC information 588 about the signature algorithm and related parameters used in the 589 group. 591 When used in the request, the 'sign_info' encodes the CBOR simple 592 value Null, to require information and parameters on the signature 593 algorithm and on the public keys used. 595 The CDDL notation [RFC8610] of the 'sign_info' parameter formatted as 596 in the request is given below. 598 sign_info_req = nil 600 The 'sign_info' parameter of the 2.01 (Created) response is a CBOR 601 array of one or more elements. The number of elements is at most the 602 number of groups that the client has been authorized to join. Each 603 element contains information about signing parameters and keys for 604 one or more group or topic, and is formatted as follows. 606 * The first element 'id' is a group name or an array of group names, 607 associated to groups for which the next four elements apply. In 608 the following, each specified group name is referred to as 609 'gname'. 611 * The second element 'sign_alg' is an integer or a text string if 612 the POST request included the 'sign_info' parameter with value 613 Null, and indicates the signature algorithm used in the groups 614 identified by the 'gname' values. It is REQUIRED of the 615 application profiles to define specific values that this parameter 616 can take (REQ3), selected from the set of signing algorithms of 617 the COSE Algorithms registry [COSE.Algorithms]. 619 * The third element 'sign_parameters' is a CBOR array indicating the 620 parameters of the signature algorithm used in the groups 621 identified by the 'gname' values. Its content depends on the 622 value of 'sign_alg'. It is REQUIRED of the application profiles 623 to define the possible values and structure for the elements of 624 this parameter (REQ4). 626 * The fourth element 'sign_key_parameters' is a CBOR array 627 indicating the parameters of the key used with the signature 628 algorithm, in the groups identified by the 'gname' values. Its 629 content depends on the value of 'sign_alg'. It is REQUIRED of the 630 application profiles to define the possible values and structure 631 for the elements of this parameter (REQ5). 633 * The fifth element 'pub_key_enc' parameter is either a CBOR integer 634 indicating the encoding of public keys used in the groups 635 identified by the 'gname' values, or has value Null indicating 636 that the KDC does not act as repository of public keys for group 637 members. Its acceptable integer values are taken from the 'Label' 638 column of the "COSE Header Parameters" Registry 639 [COSE.Header.Parameters]. It is REQUIRED of the application 640 profiles to define specific values to use for this parameter, 641 consistently with the acceptable formats of public keys (REQ6). 643 The CDDL notation [RFC8610] of the 'sign_info' parameter formatted as 644 in the response is given below. 646 sign_info_res = [ + sign_info_entry ] 648 sign_info_entry = 649 [ 650 id : gname / [ + gname ], 651 sign_alg : int / tstr, 652 sign_parameters : [ any ], 653 sign_key_parameters : [ any ], 654 pub_key_enc = int / nil 655 ] 657 gname = tstr 659 This format is consistent with every signature algorithm currently 660 considered in [I-D.ietf-cose-rfc8152bis-algs], i.e., with algorithms 661 that have only the COSE key type as their COSE capability. 662 Appendix B describes how the format of each 'sign_info_entry' can be 663 generalized for possible future registered algorithms having a 664 different set of COSE capabilities. 666 3.3.2. 'kdcchallenge' Parameter 668 The 'kdcchallenge' parameter is an OPTIONAL parameter of the Token 669 Post response message defined in Section 5.10.1 of 670 [I-D.ietf-ace-oauth-authz]. This parameter contains a challenge 671 generated by the KDC and provided to the Client. The Client may use 672 this challenge to prove possession of its own private key in the 673 Joining Request (see the 'client_cred_verify' parameter in 674 Section 4). 676 4. Keying Material Provisioning and Group Membership Management 678 This section defines the interface available at the KDC. Moreover, 679 this section specifies how the clients can use this interface to join 680 a group, leave a group, retrieve the group policies or the group 681 keying material. 683 During the first exchange with the KDC ("Joining") after posting the 684 Token, the Client sends a request to the KDC, specifying the group it 685 wishes to join (see Section 4.3). Then, the KDC verifies the access 686 token and that the Client is authorized to join that group. If so, 687 it provides the Client with the keying material to securely 688 communicate with the other members of the group. 690 When the Client is already a group member, the Client can use the 691 interface at the KDC to perform the following actions: 693 * The Client can get the current keying material, for cases such as 694 expiration, loss or suspected mismatch, due to e.g., reboot or 695 missed group rekeying. This is described in Section 4.4. 697 * The Client can retrieve new keying material for itself. This is 698 described in Section 4.5. 700 * The Client can get the public keys of other group members. This 701 is described in Section 4.6. 703 * The Client can upload a new, updated public key at the KDC. This 704 is described in Section 4.7. 706 * The Client can get the group policies. This is described in 707 Section 4.8. 709 * The Client can get the version number of the keying material 710 currently used in the group. This is described in Section 4.9. 712 * The Client can request to leave the group. This is further 713 discussed in Section 4.10. 715 Upon receiving a request from a Client, the KDC MUST check that it is 716 storing a valid access token from that Client for the group name 717 associated to the endpoint. If that is not the case, i.e., the KDC 718 does not store a valid access token or this is not valid for that 719 Client for the group name, the KDC MUST respond to the Client with a 720 4.01 (Unauthorized) error message. 722 If they include a payload and specify a Content-Format, requests sent 723 to the KDC and success responses from the KDC MUST have Content- 724 Format set to application/ace-groupcomm+cbor, defined in 725 Section 10.2. 727 Some error responses from the KDC can have Content-Format set to 728 application/ace-groupcomm+cbor. In such a case, the paylod of the 729 response MUST be a CBOR map, which includes the following fields. 731 * 'error', with value a CBOR integer specifying the error occurred 732 at the KDC. The value is taken from the "Value" column of the 733 "ACE Groupcomm Errors" registry defined in Section 10.13 of this 734 specification. This field MUST be present. 736 * 'error_description', with value a CBOR text string specifying a 737 human-readable description of the error occurred at the KDC. This 738 field MAY be present. 740 CBOR labels for the 'error' and 'error_description' fields are 741 defined in Section 7. 743 Section 8 of this specification defines an initial set of error 744 identifiers, as possible values for the 'error' field. Application 745 profiles of this specification MAY define additional value (OPT11). 747 4.1. Interface at the KDC 749 The KDC is configured with the following resources. Note that the 750 root url-path "ace-group" given here are default names: 751 implementations are not required to use these names, and can define 752 their own instead. Each application profile of this specification 753 MUST register a Resource Type for the root url-path (REQ7), and that 754 Resource Type can be used to discover the correct url to access at 755 the KDC. This Resource Type can also be used at the GROUPNAME sub- 756 resource, to indicate different application profiles for different 757 groups. The Interface Description (if=) Link Target Attribute value 758 ace.group is registered (Section 10.10) and can be used to describe 759 this interface. 761 * /ace-group: this resource is invariant once established and 762 indicates that this specification is used. If other applications 763 run on a KDC implementing this specification and use this same 764 resource, these applications will collide, and a mechanism will be 765 needed to differentiate the endpoints. This resource supports the 766 FETCH method. 768 * /ace-group/GROUPNAME: one sub-resource to /ace-group is 769 implemented for each group the KDC manages. 771 If the value of the GROUPNAME URI path and the group name in the 772 access token scope ('gname' in Section 3.2) do not match, the KDC 773 MUST implement a mechanism to map the GROUPNAME value in the URI 774 to the group name, in order to retrieve the right group (REQ1). 775 Each resource contains the symmetric group keying material for 776 that group. These resources support the GET and POST methods. 778 * /ace-group/GROUPNAME/pub-key: this resource is invariant once 779 established and contains the public keys of all group members. 780 This resource supports the GET and FETCH methods. 782 * /ace-group/GROUPNAME/policies: this resource is invariant once 783 established and contains the group policies. This resource 784 supports the GET method. 786 * /ace-group/GROUPNAME/num: this resource is invariant once 787 established and contains the version number for the symmetric 788 group keying material. This sub-resource supports the GET method. 790 * /ace-group/GROUPNAME/nodes/NODENAME: one sub-resource to /ace- 791 group/GROUPNAME is implemented for each node in the group the KDC 792 manages. These resources are identified by the node name (in this 793 example, the node name has value NODENAME). Each resource 794 contains the group and individual keying material for that node. 795 These resources support the GET, PUT and DELETE methods. 797 * /ace-group/GROUPNAME/nodes/NODENAME/pub-key: one sub-resource to 798 /ace-group/GROUPNAME/nodes/NODENAME is implemented for each node 799 in the group the KDC manages. These resources are identified by 800 the node name (in this example, the node name has value NODENAME). 801 Each resource contains the individual public keying material for 802 that node. These resources support the POST method. 804 It is REQUIRED of the application profiles of this specification to 805 define what operations (e.g., CoAP methods) are allowed on each 806 resource, for each role defined in Section 3.1 according to REQ2 807 (REQ8). 809 The details for the handlers of each resource are given in the 810 following sections. These endpoints are used to perform the 811 operations introduced in Section 4. 813 4.1.1. ace-group 815 This resource implements a FETCH handler. 817 4.1.1.1. FETCH Handler 819 The FETCH handler receives group identifiers and returns the 820 corresponding group names and GROUPNAME URIs. 822 The handler expects a request with payload formatted as a CBOR map, 823 which MUST contain the following fields: 825 * 'gid', whose value is encoded as a CBOR array, containing one or 826 more group identifiers. The exact encoding of group identifier 827 MUST be specified by the application profile (REQ9). The Client 828 indicates that it wishes to receive the group names and GROUPNAMEs 829 of all groups having these identifiers. 831 The handler identifies the groups that are secured by the keying 832 material identified by those group identifiers. 834 Then, the handler returns a 2.05 (Content) message response with 835 payload formatted as a CBOR map that MUST contain the following 836 fields: 838 * 'gid', whose value is encoded as a CBOR array, containing zero or 839 more group identifiers. The handler indicates that those are the 840 identifiers it is sending group names and GROUPNAMEs for. This 841 CBOR array is a subset of the 'gid' array in the FETCH request. 843 * 'gname', whose value is encoded as a CBOR array, containing zero 844 or more group names. The elements of this array are encoded as 845 text strings. Each element of index i of this CBOR array 846 corresponds to the element of group identifier i in the 'gid' 847 array. 849 * 'guri', whose value is encoded as a CBOR array, containing zero or 850 more URIs, each indicating a GROUPNAME resource. The elements of 851 this array are encoded as text strings. Each element of index i 852 of this CBOR array corresponds to the element of group identifier 853 i in the 'gid' array. 855 If the KDC does not find any group associated to the specified group 856 identifiers, the handler returns a response with payload formatted as 857 a CBOR byte string of zero length. 859 Note that the KDC only verifies that the node is authorized by the AS 860 to access this resource. Nodes that are not members of the group but 861 are authorized to do signature verification on the group messages may 862 be allowed to access this resource, if the application needs it. 864 4.1.2. ace-group/GROUPNAME 866 This resource implements GET and POST handlers. 868 4.1.2.1. POST Handler 870 The POST handler adds the public key of the client to the list of the 871 group members' public keys and returns the symmetric group keying 872 material for the group identified by GROUPNAME. Note that the group 873 joining exchange is done by the client via this operation, as 874 described in Section 4.3. 876 The handler expects a request with payload formatted as a CBOR map, 877 which MAY contain the following fields, which, if included, MUST have 878 the corresponding values: 880 * 'scope', with value the specific resource at the KDC that the 881 Client is authorized to access, i.e., group or topic name, and 882 role(s). This value is a CBOR byte string wrapping one scope 883 entry, as defined in Section 3.1. 885 * 'get_pub_keys', if the Client wishes to receive the public keys of 886 the other nodes in the group from the KDC. This parameter may be 887 present if the KDC stores the public keys of the nodes in the 888 group and distributes them to the Client; it is useless to have 889 here if the set of public keys of the members of the group is 890 known in another way, e.g., it was provided by the AS. Note that 891 including this parameter may result in a large message size for 892 the following response, which can be inconvenient for resource- 893 constrained devices. 895 The parameter's value is either the CBOR simple value Null, or a 896 non-empty CBOR array containing the following three elements. 898 - The first element, namely 'inclusion_flag', encodes the CBOR 899 simple value True. 901 - The second element, namely 'role_filter', is a non-empty CBOR 902 array. Each element of the array contains one role or a 903 combination of roles for the group identified by GROUPNAME. 904 The Client indicates that it wishes to receive the public keys 905 of all group members having any of the single roles, or at 906 least all of the roles indicated in any combination of roles. 907 For example, the array ["role1", "role2+role3"] indicates that 908 the Client wishes to receive the public keys of all group 909 members that have at least "role1" or at least both "role2" and 910 "role3". 912 - The third element, namely 'id_filter', is an empty CBOR array. 914 If the Client wishes to receive all public keys of all group 915 members, it encodes the 'get_pub_key' parameter as the CBOR simple 916 value Null. 918 The CDDL definition [RFC8610] of 'get_pub_keys' is given in 919 Figure 6, using as example encoding: node identifier encoded as a 920 CBOR byte string; role identifier encoded as a CBOR text string, 921 and combination of roles encoded as a CBOR array of roles. 923 Note that the array of roles 'role_filter' is non-empty for this 924 handler, but this is not necessarily the case for other handlers 925 using this parameter: if this array is empty, it means that the 926 client is not filtering public keys based on roles. 928 Also note that the array of node identifiers 'id_filter' is empty 929 for this handler, because the joining node is not expected or 930 capable to express a filter based on node identifiers at this 931 point in time. Consistently, the 'inclusion_flag' element is set 932 to the CBOR simple value True. However, the 'id_filter' array is 933 not necessarily empty for the value of 'get_pub_keys' received by 934 the handler of FETCH to ace-group/GROUPNAME/pub-key (see 935 Section 4.1.3.1). 937 Finally, the 'get_pub_keys' parameter MUST NOT have the arrays 938 'role_filter' and 'id_filter' as both empty, i.e., in CBOR 939 diagnostic notation: [ bool, [ ], [ ] ]. Thus, if this parameter 940 is received as formatted in that way, it has to be considered 941 malformed. 943 id = bstr 945 role = tstr 947 comb_role = [ 2*role ] 949 inclusion = bool 951 get_pub_keys = null / [ [ inclusion, *(role / comb_role) ], [ *id ] ] 953 Figure 6: CDLL definition of get_pub_keys, using as example node 954 identifier encoded as bstr and role as tstr 956 * 'client_cred', encoded as a CBOR byte string, which wraps the 957 original binary representation of the Client's public key. This 958 parameter is used if the KDC is managing (collecting from/ 959 distributing to the Client) the public keys of the group members, 960 and if the Client's role in the group will require for it to send 961 messages to one or more group members. It is REQUIRED of the 962 application profiles to define the specific formats that are 963 acceptable to use for encoding public keys in the group (REQ6). 965 * 'cnonce', encoded as a CBOR byte string, and including a dedicated 966 nonce N_C generated by the Client. This parameter MUST be present 967 if the 'client_cred' parameter is present. 969 * 'client_cred_verify', encoded as a CBOR byte string. This 970 parameter MUST be present if the 'client_cred' parameter is 971 present and no public key associated to the client's token can be 972 retrieved for that group. 974 This parameter contains a proof-of-possession (PoP) evidence 975 computed by the Client over the following PoP input: the scope 976 (encoded as CBOR byte string), concatenated with N_S (encoded as 977 CBOR byte string) concatenated with N_C (encoded as CBOR byte 978 string), where: 980 - scope is the CBOR byte string either specified in the 'scope' 981 parameter above, if present, or as a default scope that the 982 handler is expected to understand, if omitted. 984 - N_S is the challenge received from the KDC in the 985 'kdcchallenge' parameter of the 2.01 (Created) response to the 986 token POST request (see Section 3.3), encoded as a CBOR byte 987 string. 989 - N_C is the nonce generated by the Client and specified in the 990 'cnonce' parameter above, encoded as a CBOR byte string. 992 An example of PoP input to compute 'client_cred_verify' using CBOR 993 encoding is given in Figure 7. 995 A possible type of PoP evidence is a signature, that the Client 996 computes by using its own private key, whose corresponding public 997 key is specified in the 'client_cred' parameter. Application 998 profiles of this specification MUST specify the exact approaches 999 used to compute the PoP evidence to include in 1000 'client_cred_verify', and MUST specify which of those approaches 1001 is used in which case (REQ20). 1003 If the token was not posted (e.g., if it is used directly to 1004 validate TLS instead), it is REQUIRED of the specific profile to 1005 define how the challenge N_S is generated (REQ21). 1007 * 'pub_keys_repos', which can be present if the format of the 1008 Client's public key in the 'client_cred' parameter is a 1009 certificate. In such a case, this parameter has as value the URI 1010 of the certificate. This parameter is encoded as a CBOR text 1011 string. Alternative specific encodings of this parameter MAY be 1012 defined in applications of this specification (OPT3). 1014 * 'control_uri', with value a full URI, encoded as a CBOR text 1015 string. If 'control_uri' is supported by the Client, the Client 1016 acts as a CoAP server and hosts a resource at this specific URI. 1017 The KDC MAY use this URI to send CoAP requests to the Client 1018 (acting as CoAP server in this exchange), for example for 1019 individual provisioning of new keying material when performing a 1020 group rekeying (see Section 4.4), or to inform the Client of its 1021 removal from the group Section 5. If the KDC does not implement 1022 mechanisms using this resource, it can just ignore this parameter. 1023 Other additional functionalities of this resource MAY be defined 1024 in application profiles of this specifications (OPT9). In 1025 particular, this resource is intended for communications 1026 concerning exclusively the group or topic specified in the 'scope' 1027 parameter. 1029 scope, N_S, and N_C expressed in CBOR diagnostic notation: 1030 scope = h'826667726F7570316673656E646572' 1031 N_S = h'018a278f7faab55a' 1032 N_C = h'25a8991cd700ac01' 1034 scope, N_S, and N_C as CBOR encoded byte strings: 1035 scope = 0x4f826667726F7570316673656E646572 1036 N_S = 0x48018a278f7faab55a 1037 N_C = 0x4825a8991cd700ac01 1039 PoP input = 1040 0x4f 826667726F7570316673656E646572 1041 48 018a278f7faab55a 48 25a8991cd700ac01 1043 Figure 7: Example of PoP input to compute 'client_cred_verify' 1044 using CBOR encoding 1046 The handler extracts the granted scope from the access token, and 1047 checks the requested one against the token one. If the requested one 1048 is not a subset of the token one, the KDC MUST respond with a 4.01 1049 (Unauthorized) error message. 1051 If the request does not include a 'scope' field, the KDC is expected 1052 to understand which group and role(s) the Client is requesting (e.g., 1053 there is only one the Client has been granted). If the KDC can not 1054 recognize which scope the Client is requesting, it MUST respond with 1055 a 4.00 (Bad Request) error message. 1057 The KDC verifies that the group name of the /ace-group/GROUPNAME path 1058 is a subset of the 'scope' stored in the access token associated to 1059 this client. The KDC also verifies that the roles the client is 1060 granted in the group allow it to perform this operation on this 1061 resource (REQ8). If either verification fails, the KDC MUST respond 1062 with a 4.01 (Unauthorized) error message. This response MAY be an AS 1063 Request Creation Hints, as defined in Section 5.3 of 1064 [I-D.ietf-ace-oauth-authz], in which case the content format MUST be 1065 set to application/ace+cbor. 1067 If the request is not formatted correctly (i.e., required fields non 1068 received or received with incorrect format), the handler MUST respond 1069 with a 4.00 (Bad Request) error message. The response MAY have 1070 Content-Format set to application/ace-groupcomm+cbor and have a CBOR 1071 map as payload. For instance, the CBOR map can include a 'sign_info' 1072 parameter formatted as 'sign_info_res' defined in Section 3.3.1, with 1073 the 'pub_key_enc' element set to Null if the Client sent its own 1074 public key and the KDC is not set to store public keys of the group 1075 members. 1077 If the request contained unknown or non-expected fields present, the 1078 handler MUST silently drop them and continue processing. Application 1079 profiles MAY define optional or mandatory payload formats for 1080 specific error cases (OPT5). 1082 If the KDC manages the group members' public keys, the handler checks 1083 if one is included in the 'client_cred' field. If so, the KDC 1084 retrieves the public key and performs the following actions. 1086 * If the access token was posted but the KDC cannot retrieve the 1087 'kdcchallenge' associated to this Client (see Section 3.3), the 1088 KDC MUST respond with a 4.00 Bad Request error response, which 1089 MUST also have Content-Format application/ace-groupcomm+cbor. The 1090 payload of the error response is a CBOR map including a newly 1091 generated 'kdcchallenge' value. This is specified in the 1092 'kdcchallenge' parameter, whose CBOR label is defined in 1093 Section 7. 1095 * The KDC checks the public key to be valid for the group identified 1096 by GROUPNAME. That is, it checks that the public key is encoded 1097 according to the format used in the group, is intended for the 1098 public key algorithm used in the group, and is aligned with the 1099 possible associated parameters used in the group. 1101 If this verification fails, the handler MUST respond with a 4.00 1102 (Bad Request) error message. The response MUST have Content- 1103 Format set to application/ace-groupcomm+cbor and is formatted as 1104 defined in Section 4. The value of the 'error' field MUST be set 1105 to 2 ("Public key incompatible with the group configuration"). 1107 * The KDC verifies the PoP evidence contained in the 1108 'client_cred_verify' field. Application profiles of this 1109 specification MUST specify the exact approaches used to verify the 1110 PoP evidence, and MUST specify which of those approaches is used 1111 in which case (REQ20). 1113 If the PoP evidence does not pass verification, the handler MUST 1114 respond with a 4.01 (Unauthorized) error message. The response 1115 MUST have Content-Format set to application/ace-groupcomm+cbor and 1116 is formatted as defined in Section 4. The value of the 'error' 1117 field MUST be set to 3 ("Invalid Proof-of-Possession evidence"). 1119 If no public key is included in the 'client_cred' field, the handler 1120 checks if one public key is already associated to the received access 1121 token (see Section 4.3 for an example) and to the group identified by 1122 GROUPNAME. 1124 If an eligible public key for the Client is neither present in the 1125 'client_cred' field nor already stored, it is RECOMMENDED that the 1126 handler stops the processing and responds with a 4.00 (Bad Request) 1127 error message. Applications profiles MAY define alternatives (OPT6). 1129 If all the verifications above succeed, the handler performs the 1130 following actions. 1132 * The handler adds the Client to the list of current members of the 1133 group. 1135 * The handler assigns a name identifier NODENAME to the Client, and 1136 creates a sub-resource to /ace-group/GROUPNAME/ at the KDC (e.g., 1137 "/ace-group/GROUPNAME/nodes/NODENAME"). 1139 * The handler associates the node identifier NODENAME to the access 1140 token and the secure session for the Client. 1142 * If the KDC manages the group members' public keys: 1144 - The handler associates the retrieved Client's public key to the 1145 node identifier NODENAME and to the access token. 1147 - The handler adds the retrieved Client's public key to the 1148 stored list of public keys stored for the group identified by 1149 GROUPNAME. If such list already includes a public key for the 1150 Client, but a different public key is specified in the 1151 'client_cred' field, then the handler MUST replace the old 1152 public key in the list with the one specified in the 1153 'client_cred' field. 1155 * The handler returns a 2.01 (Created) response, containing the 1156 symmetric group keying material, the group policies and the public 1157 keys of the current members of the group, if the KDC manages those 1158 and the Client requested them. 1160 The response message also contains the URI path to the sub-resource 1161 created for that node in a Location-Path CoAP option. The response 1162 MUST have Content-Format application/ace-groupcomm+cbor. The payload 1163 of the response is formatted as a CBOR map, which MUST contain the 1164 following fields and values. 1166 * 'gkty', identifying the key type of the 'key' parameter. The set 1167 of values can be found in the "Key Type" column of the "ACE 1168 Groupcomm Key" Registry. Implementations MUST verify that the key 1169 type matches the application profile being used, if present, as 1170 registered in the "ACE Groupcomm Key" registry. 1172 * 'key', containing the keying material for the group communication, 1173 or information required to derive it. 1175 * 'num', containing the version number of the keying material for 1176 the group communication, formatted as an integer. This is a 1177 strictly monotonic increasing field. The application profile MUST 1178 define the initial version number (REQ23). 1180 The exact format of the 'key' value MUST be defined in applications 1181 of this specification (REQ10), as well as values of 'gkty' accepted 1182 by the application (REQ11). Additionally, documents specifying the 1183 key format MUST register it in the "ACE Groupcomm Key" registry 1184 defined in Section 10.6, including its name, type and application 1185 profile to be used with. 1187 +----------+----------------+---------+-------------------------+ 1188 | Name | Key Type Value | Profile | Description | 1189 +----------+----------------+---------+-------------------------+ 1190 | Reserved | 0 | | This value is reserved | 1191 +----------+----------------+---------+-------------------------+ 1193 Figure 8: Key Type Values 1195 The response SHOULD contain the following parameter: 1197 * 'exp', with value the expiration time of the keying material for 1198 the group communication, encoded as a CBOR unsigned integer. This 1199 field contains a numeric value representing the number of seconds 1200 from 1970-01-01T00:00:00Z UTC until the specified UTC date/time, 1201 ignoring leap seconds, analogous to what specified for NumericDate 1202 in Section 2 of [RFC7519]. Group members MUST stop using the 1203 keying material to protect outgoing messages and retrieve new 1204 keying material at the time indicated in this field. 1206 Optionally, the response MAY contain the following parameters, which, 1207 if included, MUST have the corresponding values: 1209 * 'ace-groupcomm-profile', with value a CBOR integer that MUST be 1210 used to uniquely identify the application profile for group 1211 communication. Applications of this specification MUST register 1212 an application profile identifier and the related value for this 1213 parameter in the "ACE Groupcomm Profile" Registry (REQ15). 1215 * 'pub_keys', MUST be present if 'get_pub_keys' was present in the 1216 request, otherwise it MUST NOT be present. This parameter is a 1217 CBOR array specifying the public keys of the group members, i.e., 1218 of all of them or of the ones selected according to the 1219 'get_pub_keys' parameter in the request. In particular, each 1220 element of the array is a CBOR byte string, which wraps the 1221 original binary representation of a group member's public key. It 1222 is REQUIRED of the application profiles to define the specific 1223 formats of public keys that are acceptable to use in the group 1224 (REQ6). 1226 * 'peer_roles', MUST be present if 'pub_keys' is also present, 1227 otherwise it MUST NOT be present. This parameter is a CBOR array 1228 of n elements, with n the number of public keys included in the 1229 'pub_keys' parameter (at most the number of members in the group). 1230 The i-th element of the array specifies the role (or CBOR array of 1231 roles) that the group member associated to the i-th public key in 1232 'pub_keys' has in the group. In particular, each array element is 1233 encoded as the role element of a scope entry, as defined in 1234 Section 3.1. 1236 * 'peer_identifiers', MUST be present if 'pub_keys' is also present, 1237 otherwise it MUST NOT be present. This parameter is a CBOR array 1238 of n elements, with n the number of public keys included in the 1239 'pub_keys' parameter (at most the number of members in the group). 1240 The i-th element of the array specifies the node identifier that 1241 the group member associated to the i-th public key in 'pub_keys' 1242 has in the group. In particular, the i-th array element is 1243 encoded as a CBOR byte string wrapping the node identifier of the 1244 group member. 1246 * 'group_policies', with value a CBOR map, whose entries specify how 1247 the group handles specific management aspects. These include, for 1248 instance, approaches to achieve synchronization of sequence 1249 numbers among group members. The elements of this field are 1250 registered in the "ACE Groupcomm Policy" Registry. This 1251 specification defines the three elements "Sequence Number 1252 Synchronization Method", "Key Update Check Interval" and 1253 "Expiration Delta", which are summarized in Figure 9. Application 1254 profiles that build on this document MUST specify the exact 1255 content format and default value of included map entries (REQ17). 1257 +--------------+-------+----------|---------------------|------------+ 1258 | Name | CBOR | CBOR | Description | Reference | 1259 | | label | type | | | 1260 |--------------+-------+----------|---------------------|------------| 1261 | Sequence | TBD1 | tstr/int | Method for a re- | [[this | 1262 | Number | | | cipient node to | document]] | 1263 | Synchroniza- | | | synchronize with | | 1264 | tion Method | | | sequence numbers | | 1265 | | | | of a sender node. | | 1266 | | | | Its value is taken | | 1267 | | | | from the 'Value' | | 1268 | | | | column of the | | 1269 | | | | Sequence Number | | 1270 | | | | Synchronization | | 1271 | | | | Method registry | | 1272 | | | | | | 1273 | Key Update | TBD2 | int | Polling interval | [[this | 1274 | Check | | | in seconds, to | document]] | 1275 | Interval | | | check for new | | 1276 | | | | keying material at | | 1277 | | | | the KDC | | 1278 | | | | | | 1279 | Expiration | TBD3 | uint | Number of seconds | [[this | 1280 | Delta | | | from 'exp' until | document]] | 1281 | | | | the specified UTC | | 1282 | | | | date/time after | | 1283 | | | | which group members | | 1284 | | | | MUST stop using the | | 1285 | | | | keying material to | | 1286 | | | | verify incoming | | 1287 | | | | messages. | | 1288 +--------------+-------+----------|---------------------|------------+ 1290 Figure 9: ACE Groupcomm Policies 1292 * 'mgt_key_material', encoded as a CBOR byte string and containing 1293 the administrative keying material to participate in the group 1294 rekeying performed by the KDC. The application profile MUST 1295 define if this field is used, and if used then MUST specify the 1296 exact format and content which depend on the specific rekeying 1297 scheme used in the group. If the usage of 'mgt_key_material' is 1298 indicated and its format defined for a specific key management 1299 scheme, that format must explicitly indicate the key management 1300 scheme itself. If a new rekeying scheme is defined to be used for 1301 an existing 'mgt_key_material' in an existing profile, then that 1302 profile will have to be updated accordingly, especially with 1303 respect to the usage of 'mgt_key_material' related format and 1304 content (REQ22). 1306 Specific application profiles that build on this document MUST 1307 specify the communication protocol that members of the group use to 1308 communicate with each other (REQ13) and how exactly the keying 1309 material is used to protect the group communication (REQ14). 1311 CBOR labels for these fields are defined in Section 7. 1313 4.1.2.2. GET Handler 1315 The GET handler returns the symmetric group keying material for the 1316 group identified by GROUPNAME. 1318 The handler expects a GET request. 1320 The KDC verifies that the group name of the /ace-group/GROUPNAME path 1321 is a subset of the 'scope' stored in the access token associated to 1322 this client. The KDC also verifies that the roles the client is 1323 granted in the group allow it to perform this operation on this 1324 resource (REQ8). If either verification fails, the KDC MUST respond 1325 with a 4.01 (Unauthorized) error message. This response MAY be an AS 1326 Request Creation Hints, as defined in Section 5.3 of 1327 [I-D.ietf-ace-oauth-authz], in which case the content format MUST be 1328 set to application/ace+cbor. 1330 Additionally, the handler verifies that the node is a current member 1331 of the group. If verification fails, the KDC MUST respond with a 1332 4.01 (Unauthorized) error message. The response MUST have Content- 1333 Format set to application/ace-groupcomm+cbor and is formatted as 1334 defined in Section 4. The value of the 'error' field MUST be set to 1335 0 ("Operation permitted only to group members"). 1337 If verification succeeds, the handler returns a 2.05 (Content) 1338 message containing the symmetric group keying material. The payload 1339 of the response is formatted as a CBOR map which MUST contain the 1340 parameters 'gkty', 'key' and 'num' specified in Section 4.1.2.1. 1342 The payload MAY also include the parameters 'ace-groupcomm-profile', 1343 'exp', and 'mgt_key_material' parameters specified in 1344 Section 4.1.2.1. 1346 4.1.3. ace-group/GROUPNAME/pub-key 1348 If the KDC does not maintain public keys for the group, the handler 1349 for any request on this resource returns a 4.05 (Method Not Allowed) 1350 error message. If it does, the rest of this section applies. 1352 This resource implements GET and FETCH handlers. 1354 4.1.3.1. FETCH Handler 1356 The FETCH handler receives identifiers of group members for the group 1357 identified by GROUPNAME and returns the public keys of such group 1358 members. 1360 The handler expects a request with payload formatted as a CBOR map, 1361 that MUST contain the following fields: 1363 * 'get_pub_keys', whose value is encoded as in Section 4.1.2.1 with 1364 the following modification: 1366 - The element 'inclusion_flag' encodes the CBOR simple value True 1367 if the third element 'id_filter' specifies an empty CBOR array, 1368 or if the Client wishes to receive the public keys of the nodes 1369 having their node identifier specified in 'id_filter'. 1370 Instead, this element encodes the CBOR simple value False if 1371 the Client wishes to receive the public keys of the nodes not 1372 having the node identifiers specified in the third element 1373 'id_filter'. 1375 - The array 'role_filter' may be empty, if the Client does not 1376 wish to filter the requested public keys based on the roles of 1377 the group members. 1379 - The array 'id_filter' contains zero or more node identifiers of 1380 group members, for the group identified by GROUPNAME. The 1381 Client indicates that it wishes to receive the public keys of 1382 the nodes having or not having these node identifiers, in case 1383 the 'inclusion_flag' parameter encodes the CBOR simple value 1384 True or False, respectively. The array may be empty, if the 1385 Client does not wish to filter the requested public keys based 1386 on the node identifiers of the group members. 1388 Note that, in case both the 'role_filter' array and the 'id_filter' 1389 array are not empty: 1391 * If the 'inclusion_flag' encodes the CBOR simple value True, the 1392 handler returns the public keys of group members whose roles match 1393 with 'role_filter' and/or having their node identifier specified 1394 in 'id_filter'. 1396 * If the 'inclusion_flag' encodes the CBOR simple value False, the 1397 handler returns the public keys of group members whose roles match 1398 with 'role_filter' and, at the same time, not having their node 1399 identifier specified in 'id_filter'. 1401 Finally, as mentioned in Section 4.1.2.1, both arrays 'role_filter' 1402 and 'id_filter' MUST NOT be both empty. 1404 The specific format of public keys as well as identifiers, roles and 1405 combination of roles of group members MUST be specified by the 1406 application profile (OPT1, REQ2, REQ12). 1408 The KDC verifies that the group name of the /ace-group/GROUPNAME path 1409 is a subset of the 'scope' stored in the access token associated to 1410 this client. The KDC also verifies that the roles the client is 1411 granted in the group allow it to perform this operation on this 1412 resource (REQ8). If either verification fails, the KDC MUST respond 1413 with a 4.01 (Unauthorized) error message. 1415 If verification succeeds, the handler identifies the public keys of 1416 the current group members for which either: 1418 * the role identifier matches with one of those indicated in the 1419 request; note that the request can contain a "combination of 1420 roles", where the handler select all group members who have all 1421 roles included in the combination. 1423 * the node identifier matches with one of those indicated in the 1424 request. 1426 Then, the handler returns a 2.05 (Content) message response with 1427 payload formatted as a CBOR map, containing only the following 1428 parameters from Section 4.1.2.1. 1430 * 'num', which encodes the version number of the current group 1431 keying material. 1433 * 'pub_keys', which encodes the list of public keys of the selected 1434 group members. 1436 * 'peer_roles', which encodes the role (or CBOR array of roles) that 1437 each of the selected group members has in the group. 1439 * 'peer_identifiers', which encodes the node identifier that each of 1440 the selected group members has in the group. 1442 The specific format of public keys as well as of node identifiers of 1443 group members is specified by the application profile (REQ6, REQ12). 1445 If the KDC does not store any public key associated to the specified 1446 node identifiers, the handler returns a response with payload 1447 formatted as a CBOR byte string of zero length. 1449 The handler MAY enforce one of the following policies, in order to 1450 handle possible node identifiers that are included in the 'id_filter' 1451 element of the 'get_pub_keys' parameter of the request but are not 1452 associated to any current group member. Such a policy MUST be 1453 specified by the application profile (REQ16). 1455 * The KDC silently ignores those node identifiers. 1457 * The KDC retains public keys of group members for a given amount of 1458 time after their leaving, before discarding them. As long as such 1459 public keys are retained, the KDC provides them to a requesting 1460 Client. 1462 Note that this resource handler only verifies that the node is 1463 authorized by the AS to access this resource. Nodes that are not 1464 members of the group but are authorized to do signature verifications 1465 on the group messages may be allowed to access this resource, if the 1466 application needs it. 1468 4.1.3.2. GET Handler 1470 The handler expects a GET request. 1472 The KDC performs the same verifications as the FETCH handler in 1473 Section 4.1.3.1, and if successful returns the same response as in 1474 Section 4.1.3.1 but without filtering based on roles or node 1475 identifiers: all the group members' public keys are returned. 1477 Note that this resource handler, as the FETCH handler for the same 1478 resource, only verifies that the node is authorized by the AS to 1479 access this resource. Nodes that are not members of the group but 1480 are authorized to do signature verifications on the group messages 1481 may be allowed to access this resource, if the application needs it. 1483 4.1.4. ace-group/GROUPNAME/policies 1485 This resource implements a GET handler. 1487 4.1.4.1. GET Handler 1489 The handler expects a GET request. 1491 The KDC verifies that the group name of the /ace-group/GROUPNAME path 1492 is a subset of the 'scope' stored in the access token associated to 1493 this client. The KDC also verifies that the roles the client is 1494 granted in the group allow it to perform this operation on this 1495 resource (REQ8). If either verification fails, the KDC MUST respond 1496 with a 4.01 (Unauthorized) error message. 1498 Additionally, the handler verifies that the node is a current member 1499 of the group. If verification fails, the KDC MUST respond with a 1500 4.01 (Unauthorized) error message. The response MUST have Content- 1501 Format set to application/ace-groupcomm+cbor and is formatted as 1502 defined in Section 4. The value of the 'error' field MUST be set to 1503 0 ("Operation permitted only to group members"). 1505 If verification succeeds, the handler returns a 2.05 (Content) 1506 message containing the list of policies for the group identified by 1507 GROUPNAME. The payload of the response is formatted as a CBOR map 1508 including only the parameter 'group_policies' defined in 1509 Section 4.1.2.1 and specifying the current policies in the group. If 1510 the KDC does not store any policy, the payload is formatted as a 1511 zero-length CBOR byte string. 1513 The specific format and meaning of group policies MUST be specified 1514 in the application profile (REQ17). 1516 4.1.5. ace-group/GROUPNAME/num 1518 This resource implements a GET handler. 1520 4.1.5.1. GET Handler 1522 The handler expects a GET request. 1524 The KDC verifies that the group name of the /ace-group/GROUPNAME path 1525 is a subset of the 'scope' stored in the access token associated to 1526 this client. The KDC also verifies that the roles the client is 1527 granted in the group allow it to perform this operation on this 1528 resource (REQ8). If either verification fails, the KDC MUST respond 1529 with a 4.01 (Unauthorized) error message. 1531 Additionally, the handler verifies that the node is a current member 1532 of the group. If verification fails, the KDC MUST respond with a 1533 4.01 (Unauthorized) error message. The response MUST have Content- 1534 Format set to application/ace-groupcomm+cbor and is formatted as 1535 defined in Section 4. The value of the 'error' field MUST be set to 1536 0 ("Operation permitted only to group members"). 1538 If verification succeeds, the handler returns a 2.05 (Content) 1539 message containing an integer that represents the version number of 1540 the symmetric group keying material. This number is incremented on 1541 the KDC every time the KDC updates the symmetric group keying 1542 material, before the new keying material is distributed. This number 1543 is stored in persistent storage. 1545 The payload of the response is formatted as a CBOR integer. 1547 4.1.6. ace-group/GROUPNAME/nodes/NODENAME 1549 This resource implements GET, PUT and DELETE handlers. 1551 4.1.6.1. PUT Handler 1553 The PUT handler is used to get the KDC to produce and return 1554 individual keying material to protect outgoing messages for the node 1555 (identified by NODENAME) for the group identified by GROUPNAME. 1556 Application profiles MAY also use this handler to rekey the whole 1557 group. It is up to the application profiles to specify if this 1558 handler supports renewal of individual keying material, renewal of 1559 the group keying material or both (OPT8). 1561 The handler expects a request with empty payload. In case the 1562 request has a non-empty payload, the KDC MUST respond with a 4.00 1563 (Bad Request) error message. 1565 The KDC verifies that the group name of the /ace-group/GROUPNAME path 1566 is a subset of the 'scope' stored in the access token associated to 1567 the client identified by NODENAME. The KDC also verifies that the 1568 roles the client is granted in the group allow it to perform this 1569 operation on this resource (REQ8). If either verification fails, the 1570 KDC MUST respond with a 4.01 (Unauthorized) error message. 1572 The handler also verifies that the node sending the request and the 1573 node name used in the Uri-Path match. If that is not the case, the 1574 handler responds with a 4.01 (Unauthorized) error response. 1576 Additionally, the handler verifies that the node is a current member 1577 of the group. If the verification fails, the KDC MUST respond with a 1578 4.01 (Unauthorized) error message. The response MUST have Content- 1579 Format set to application/ace-groupcomm+cbor and is formatted as 1580 defined in Section 4. The value of the 'error' field MUST be set to 1581 0 ("Operation permitted only to group members"). 1583 Also, the handler verifies that this operation is consistent with the 1584 set of roles that the node has in the group. If the verification 1585 fails, the KDC MUST respond with a 4.00 (Bad Request) error message. 1586 The response MUST have Content-Format set to application/ace- 1587 groupcomm+cbor and is formatted as defined in Section 4. The value 1588 of the 'error' field MUST be set to 1 ("Request inconsistent with the 1589 current roles"). 1591 If the KDC is currently not able to serve this request, i.e., to 1592 generate new individual keying material for the requesting client, 1593 the KDC MUST respond with a 5.03 (Service Unavailable) error message. 1594 The response MUST have Content-Format set to application/ace- 1595 groupcomm+cbor and is formatted as defined in Section 4. The value 1596 of the 'error' field MUST be set to 4 ("No available node 1597 identifiers"). 1599 If all verifications succeed, the handler returns a 2.05 (Content) 1600 message containing newly-generated keying material for the Client, 1601 and/or, if the application profiles requires it (OPT8), starts the 1602 complete group rekeying. The payload of the response is formatted as 1603 a CBOR map. The specific format of newly-generated individual keying 1604 material for group members, or of the information to derive it, and 1605 corresponding CBOR label, MUST be specified in the application 1606 profile (REQ18) and registered in Section 10.5. 1608 4.1.6.2. GET Handler 1610 The handler expects a GET request. 1612 The KDC verifies that the group name of the /ace-group/GROUPNAME path 1613 is a subset of the 'scope' stored in the access token associated to 1614 the client identified by NODENAME. The KDC also verifies that the 1615 roles the client is granted in the group allow it to perform this 1616 operation on this resource (REQ8). If either verification fails, the 1617 KDC MUST respond with a 4.01 (Unauthorized) error message. 1619 The handler also verifies that the node sending the request and the 1620 node name used in the Uri-Path match. If that is not the case, the 1621 handler responds with a 4.01 (Unauthorized) error response. 1623 Additionally, the handler verifies that the node is a current member 1624 of the group. If verification fails, the KDC MUST respond with a 1625 4.01 (Unauthorized) error message. The response MUST have Content- 1626 Format set to application/ace-groupcomm+cbor and is formatted as 1627 defined in Section 4. The value of the 'error' field MUST be set to 1628 0 ("Operation permitted only to group members"). 1630 If verification succeeds, the handler returns a 2.05 (Content) 1631 message containing both the group keying material and the individual 1632 keying material for the Client, or information enabling the Client to 1633 derive it. The payload of the response is formatted as a CBOR map. 1634 The format for the group keying material is the same as defined in 1635 the response of Section 4.1.2.2. The specific format of individual 1636 keying material for group members, or of the information to derive 1637 it, and corresponding CBOR label, MUST be specified in the 1638 application profile (REQ18) and registered in Section 10.5. 1640 Optionally, the KDC can make the sub-resource at ace- 1641 group/GROUPNAME/nodes/NODENAME also Observable [RFC7641] for the 1642 associated node. In case the KDC removes that node from the group 1643 without having been explicitly asked for it, this allows the KDC to 1644 send an unsolicited 4.04 (Not Found) response to the node as a 1645 notification of eviction from the group (see Section 5). 1647 Note that the node could have been observing also the resource at 1648 ace-group/GROUPNAME, in order to be informed of changes in the keying 1649 material. In such a case, this method would result in largely 1650 overlapping notifications received for the resource at ace-group/ 1651 GROUPNAME and the sub-resource at ace-group/GROUPNAME/nodes/NODENAME. 1653 In order to mitigate this, a node that supports the No-Response 1654 option [RFC7967] can use it when starting the observation of the sub- 1655 resource at ace-group/GROUPNAME/nodes/NODENAME. In particular, the 1656 GET observation request can also include the No-Response option, with 1657 value set to 2 (Not interested in 2.xx responses). 1659 4.1.6.3. DELETE Handler 1661 The DELETE handler removes the node identified by NODENAME from the 1662 group identified by GROUPNAME. 1664 The handler expects a request with method DELETE (and empty payload). 1666 The handler verifies that the group name of the /ace-group/GROUPNAME 1667 path is a subset of the 'scope' stored in the access token associated 1668 to the client identified by NODENAME. If the verification fails, the 1669 KDC MUST respond with a 4.01 (Unauthorized) error message. 1671 The handler also verifies that the node sending the request and the 1672 node name used in the Uri-Path match. If that is not the case, the 1673 handler responds with a 4.01 (Unauthorized) error response. 1675 Additionally, the handler verifies that the node is a current member 1676 of the group. If verification fails, the KDC MUST respond with a 1677 4.01 (Unauthorized) error message. The response MUST have Content- 1678 Format set to application/ace-groupcomm+cbor and is formatted as 1679 defined in Section 4. The value of the 'error' field MUST be set to 1680 0 ("Operation permitted only to group members"). 1682 If verification succeeds, the handler removes the client from the 1683 group identified by GROUPNAME. That includes removing the public key 1684 of the client if the KDC keep tracks of that, and possibly removing 1685 the evicted node from the list of observers of the resource at ace- 1686 group/GROUPNAME (if observable). Then, the handler deletes the sub- 1687 resource nodes/NODENAME and returns a 2.02 (Deleted) message with 1688 empty payload. 1690 4.1.7. ace-group/GROUPNAME/nodes/NODENAME/pub-key 1692 This resource implements a POST handler, if the KDC stores the public 1693 key of group members. If the KDC does not store the public keys of 1694 group members, the handler does not implement any method, and every 1695 request returns a 4.05 Method Not Allowed error. 1697 4.1.7.1. POST Handler 1699 The POST handler is used to replace the stored public key of this 1700 client (identified by NODENAME) with the one specified in the request 1701 at the KDC, for the group identified by GROUPNAME. 1703 The handler expects a POST request with payload as specified in 1704 Section 4.1.2.1, with the difference that it includes only the 1705 parameters 'client_cred', 'cnonce' and 'client_cred_verify'. In 1706 particular, the PoP evidence included in 'client_cred_verify' is 1707 computed in the same way considered in Section 4.1.2.1 and defined by 1708 the specific application profile (REQ20), with a newly generated N_C 1709 nonce and the previously received N_S. It is REQUIRED of the 1710 application profiles to define the specific formats of public keys 1711 that are acceptable to use in the group (REQ6). 1713 The handler verifies that the group name GROUPNAME is a subset of the 1714 'scope' stored in the access token associated to the client 1715 identified by NODENAME. The KDC also verifies that the roles the 1716 client is granted in the group allow it to perform this operation on 1717 this resource (REQ8). If either verification fails, the KDC MUST 1718 respond with a 4.01 (Unauthorized) error message. 1720 The handler also verifies that the node sending the request and the 1721 node name used in the Uri-Path match. If that is not the case, the 1722 handler responds with a 4.01 (Unauthorized) error response. 1724 Additionally, the handler verifies that the node is a current member 1725 of the group. If the verification fails, the KDC MUST respond with a 1726 4.01 (Unauthorized) error message. The response MUST have Content- 1727 Format set to application/ace-groupcomm+cbor and is formatted as 1728 defined in Section 4. The value of the 'error' field MUST be set to 1729 0 ("Operation permitted only to group members"). 1731 Also, the handler verifies that this operation is consistent with the 1732 set of roles that the node has in the group. If the verification 1733 fails, the KDC MUST respond with a 4.00 (Bad Request) error message. 1734 The response MUST have Content-Format set to application/ace- 1735 groupcomm+cbor and is formatted as defined in Section 4. The value 1736 of the 'error' field MUST be set to 1 ("Request inconsistent with the 1737 current roles") 1738 If the request is not formatted correctly (i.e., required fields non 1739 received or received with incorrect format), the handler MUST respond 1740 with a 4.00 (Bad Request) error message. If the request contains 1741 unknown or non-expected fields present, the handler MUST silently 1742 ignore them and continue processing. Application profiles MAY define 1743 optional or mandatory payload formats for specific error cases 1744 (OPT5). 1746 If the KDC cannot retrieve the 'kdcchallenge' associated to this 1747 Client (see Section 3.3), the KDC MUST respond with a 4.00 Bad 1748 Request error response, which MUST also have Content-Format 1749 application/ace-groupcomm+cbor. The payload of the error response is 1750 a CBOR map including a newly generated 'kdcchallenge' value. This is 1751 specified in the 'kdcchallenge' parameter, whose CBOR label is 1752 defined in Section 7. In such a case the KDC MUST store the newly 1753 generated value as the 'kdcchallenge' value associated to this 1754 Client, possibly replacing the currently stored value. 1756 Otherwise, the handler checks that the public key specified in the 1757 'client_cred' field is valid for the group identified by GROUPNAME. 1758 That is, the handler checks that the public key is encoded according 1759 to the format used in the group, is intended for the public key 1760 algorithm used in the group, and is aligned with the possible 1761 associated parameters used in the group. If that cannot be 1762 successfully verified, the handler MUST respond with a 4.00 (Bad 1763 Request) error message. The response MUST have Content-Format set to 1764 application/ace-groupcomm+cbor and is formatted as defined in 1765 Section 4. The value of the 'error' field MUST be set to 2 ("Public 1766 key incompatible with the group configuration"). 1768 Otherwise, the handler verifies the PoP evidence contained in the 1769 'client_cred_verify' field of the request, by using the public key 1770 specified in the 'client_cred' field, as well as the same way 1771 considered in Section 4.1.2.1 and defined by the specific application 1772 profile (REQ20). If the PoP evidence does not pass verification, the 1773 handler MUST respond with a 4.01 (Unauthorized) error message. The 1774 response MUST have Content-Format set to application/ace- 1775 groupcomm+cbor and is formatted as defined in Section 4. The value 1776 of the 'error' field MUST be set to 3 ("Invalid Proof-of-Possession 1777 evidence"). 1779 If verification succeeds, the handler performs the following actions. 1781 * The handler associates the public key from the 'client_cred' field 1782 of the request to the node identifier NODENAME and to the access 1783 token associated to the node identified by NODENAME. 1785 * In the stored list of group members' public keys for the group 1786 identified by GROUPNAME, the handler replaces the public key of 1787 the node identified by NODENAME with the public key specified in 1788 the 'client_cred' field of the request. 1790 Then, the handler replies with a 2.04 (Changed) response, which does 1791 not include a payload. 1793 4.2. Retrieval of Group Names and URIs 1795 In case the joining node only knows the group identifier of the group 1796 it wishes to join or about which it wishes to get update information 1797 from the KDC, the node can contact the KDC to request the 1798 corresponding group name and joining resource URI. The node can 1799 request several group identifiers at once. It does so by sending a 1800 CoAP FETCH request to the /ace-group endpoint at the KDC formatted as 1801 defined in Section 4.1.1.1. 1803 Figure 10 gives an overview of the exchanges described above, and 1804 Figure 11 shows an example. 1806 Client KDC 1807 | | 1808 |-------- Group Name and URI Retrieval Request: -------->| 1809 | FETCH /ace-group | 1810 | | 1811 |<-Group Name and URI Retrieval Response: 2.05 (Content)-| 1812 | | 1814 Figure 10: Message Flow of Group Name and URI Retrieval Request- 1815 Response 1817 Request: 1819 Header: FETCH (Code=0.05) 1820 Uri-Host: "kdc.example.com" 1821 Uri-Path: "ace-group" 1822 Content-Format: "application/ace-groupcomm+cbor" 1823 Payload (in CBOR diagnostic notation): 1824 { "gid": [01, 02] } 1826 Response: 1828 Header: Content (Code=2.05) 1829 Content-Format: "application/ace-groupcomm+cbor" 1830 Payload (in CBOR diagnostic notation): 1831 { "gid": [01, 02], "gname": ["group1", "group2"], 1832 "guri": ["ace-group/g1", "ace-group/g2"] } 1834 Figure 11: Example of Group Name and URI Retrieval Request-Response 1836 4.3. Joining Exchange 1838 Figure 12 gives an overview of the Joining exchange between Client 1839 and KDC, when the Client first joins a group, while Figure 13 shows 1840 an example. 1842 Client KDC 1843 | | 1844 |----- Joining Request: POST /ace-group/GROUPNAME ------>| 1845 | | 1846 |<--------- Joining Response: 2.01 (Created) ----------- | 1847 | Location-Path = "/ace-group/GROUPNAME/nodes/NODENAME" | 1849 Figure 12: Message Flow of First Exchange for Group Joining 1851 Request: 1853 Header: POST (Code=0.02) 1854 Uri-Host: "kdc.example.com" 1855 Uri-Path: "ace-group" 1856 Uri-Path: "g1" 1857 Content-Format: "application/ace-groupcomm+cbor" 1858 Payload (in CBOR diagnostic notation, 1859 with PUB_KEY and POP_EVIDENCE being CBOR byte strings): 1860 { "scope": << [ "group1", ["sender", "receiver"] ] >> , 1861 "get_pub_keys": [true, ["sender"], []], "client_cred": PUB_KEY 1862 "cnonce": h'6df49c495409a9b5', "client_cred_verify": POP_EVIDENCE } 1864 Response: 1866 Header: Created (Code=2.01) 1867 Content-Format: "application/ace-groupcomm+cbor" 1868 Location-Path: "kdc.example.com" 1869 Location-Path: "g1" 1870 Location-Path: "nodes" 1871 Location-Path: "c101" 1872 Payload (in CBOR diagnostic notation, 1873 with KEY being a CBOR byte strings): 1874 { "gkty": 13, "key": KEY, "num": 12, "exp": 1609459200, 1875 "pub_keys": [ PUB_KEY1, PUB_KEY2 ], 1876 "peer_roles": ["sender", ["sender", "receiver"]], 1877 "peer_identifiers": [ ID1, ID2 ] } 1879 Figure 13: Example of First Exchange for Group Joining 1881 If not previously established, the Client and the KDC MUST first 1882 establish a pairwise secure communication channel (REQ19). This can 1883 be achieved, for instance, by using a transport profile of ACE. The 1884 Joining exchange MUST occur over that secure channel. The Client and 1885 the KDC MAY use that same secure channel to protect further pairwise 1886 communications that must be secured. 1888 The secure communication protocol is REQUIRED to establish the secure 1889 channel between Client and KDC by using the proof-of-possession key 1890 bound to the access token. As a result, the proof-of-possession to 1891 bind the access token to the Client is performed by using the proof- 1892 of-possession key bound to the access token for establishing secure 1893 communication between the Client and the KDC. 1895 To join the group, the Client sends a CoAP POST request to the /ace- 1896 group/GROUPNAME endpoint at the KDC, where GROUPNAME is the group 1897 name of the group to join, formatted as specified in Section 4.1.2.1. 1898 This group name is the same as in the scope entry corresponding to 1899 that group, specified in the 'scope' parameter of the Authorization 1900 Request/Response, or it can be retrieved from it. Note that, in case 1901 of successful joining, the Client will receive the URI to retrieve 1902 group keying material and to leave the group in the Location-Path 1903 option of the response. 1905 If the node is joining a group for the first time, and the KDC 1906 maintains the public keys of the group members, the Client is 1907 REQUIRED to send its own public key and proof-of-possession (PoP) 1908 evidence ("client_cred" and "client_cred_verify" in Section 4.1.2.1). 1909 The request is accepted only if both public key is provided and the 1910 PoP evidence is successfully verified. If a node re-joins a group 1911 with the same access token and the same public key, it can omit to 1912 send the public key and the PoP evidence, or just omit the PoP 1913 evidence, and the KDC will be able to retrieve its public key 1914 associated to its token for that group (if the key has been 1915 discarded, the KDC will reply with 4.00 Bad Request, as specified in 1916 Section 4.1.2.1). If a node re-joins a group but wants to update its 1917 own public key, it needs to send both its public key and the PoP 1918 evidence. 1920 If the application requires backward security, the KDC MUST generate 1921 new group keying material and securely distribute it to all the 1922 current group members, upon a new node's joining the group. To this 1923 end, the KDC uses the message format of the response defined in 1924 Section 4.1.2.2. Application profiles may define alternative ways of 1925 retrieving the keying material, such as sending separate requests to 1926 different resources at the KDC (Section 4.1.2.2, Section 4.1.3.2, 1927 Section 4.1.4.1). The KDC MUST increment the version number of the 1928 current keying material, before distributing the newly generated 1929 keying material to the group. After that, the KDC SHOULD store the 1930 distributed keying material in persistent storage. 1932 4.4. Retrieval of Updated Keying Material 1934 When any of the following happens, a node MUST stop using the owned 1935 group keying material to protect outgoing messages, and SHOULD stop 1936 using it to decrypt and verify incoming messages. 1938 * Upon expiration of the keying material, according to what 1939 indicated by the KDC with the 'exp' parameter in a Joining 1940 Response, or to a pre-configured value. 1942 * Upon receiving a notification of revoked/renewed keying material 1943 from the KDC, possibly as part of an update of the keying material 1944 (rekeying) triggered by the KDC. 1946 * Upon receiving messages from other group members without being 1947 able to retrieve the keying material to correctly decrypt them. 1948 This may be due to rekeying messages previously sent by the KDC, 1949 that the Client was not able to receive or decrypt. 1951 In either case, if it wants to continue participating in the group 1952 communication, the node has to request the latest keying material 1953 from the KDC. To this end, the Client sends a CoAP GET request to 1954 the /ace-group/GROUPNAME/nodes/NODENAME endpoint at the KDC, 1955 formatted as specified in Section 4.1.6.2. 1957 Note that policies can be set up, so that the Client sends a Key Re- 1958 Distribution request to the KDC only after a given number of received 1959 messages could not be decrypted (because of failed decryption 1960 processing or inability to retrieve the necessary keying material). 1962 It is application dependent and pertaining to the particular message 1963 exchange (e.g., [I-D.ietf-core-oscore-groupcomm]) to set up these 1964 policies for instructing clients to retain incoming messages and for 1965 how long (OPT4). This allows clients to possibly decrypt such 1966 messages after getting updated keying material, rather than just 1967 consider them non valid messages to discard right away. 1969 The same Key Distribution Request could also be sent by the Client 1970 without being triggered by a failed decryption of a message, if the 1971 Client wants to be sure that it has the latest group keying material. 1972 If that is the case, the Client will receive from the KDC the same 1973 group keying material it already has in memory. 1975 Figure 14 gives an overview of the exchange described above, while 1976 Figure 15 shows an example. 1978 Client KDC 1979 | | 1980 |------------------ Key Distribution Request: --------------->| 1981 | GET ace-group/GROUPNAME/nodes/NODENAME | 1982 | | 1983 |<-------- Key Distribution Response: 2.05 (Content) ---------| 1984 | | 1986 Figure 14: Message Flow of Key Distribution Request-Response 1988 Request: 1990 Header: GET (Code=0.01) 1991 Uri-Host: "kdc.example.com" 1992 Uri-Path: "ace-group" 1993 Uri-Path: "g1" 1994 Uri-Path: "nodes" 1995 Uri-Path: "c101" 1996 Payload: - 1998 Response: 2000 Header: Content (Code=2.05) 2001 Content-Format: "application/ace-groupcomm+cbor" 2002 Payload (in CBOR diagnostic notation, 2003 with KEY and IND_KEY being CBOR byte strings, 2004 and "ind-key" the profile-specified label 2005 for individual keying material): 2006 { "gkty": 13, "key": KEY, "num": 12, "ind-key": IND_KEY } 2008 Figure 15: Example of Key Distribution Request-Response 2010 Alternatively, the re-distribution of keying material can be 2011 initiated by the KDC, which e.g.,: 2013 * Can make the ace-group/GROUPNAME resource Observable [RFC7641], 2014 and send notifications to observer Clients when the keying 2015 material is updated. 2017 In case the KDC deletes the group identified by GROUPNAME, this 2018 also allows the KDC to send an unsolicited 4.04 (Not Found) 2019 response to each observer group member, as a notification of group 2020 termination. The response MUST have Content-Format set to 2021 application/ace-groupcomm+cbor and is formatted as defined in 2022 Section 4. The value of the 'error' field MUST be set to 6 2023 ("Group deleted"). 2025 * Can send the payload of the Key Distribution Response in one or 2026 multiple multicast POST requests to the members of the group, 2027 using secure rekeying schemes such as [RFC2093][RFC2094][RFC2627]. 2029 * Can send unicast POST requests to each Client over a secure 2030 channel, with the same payload as the Key Distribution Response. 2031 When sending such requests, the KDC can target the URI path 2032 provided by the intended recipient upon joining the group, as 2033 specified in the 'control_uri' parameter of the Joining Request 2034 (see Section 4.1.2.1). 2036 * Can act as a publisher in a pub-sub scenario, and update the 2037 keying material by publishing on a specific topic on a broker, 2038 which all the members of the group are subscribed to. 2040 Note that these methods of KDC-initiated key distribution have 2041 different security properties and require different security 2042 associations. 2044 4.5. Requesting a Change of Keying Material 2046 Beside possible expiration, the client may need to communicate to the 2047 KDC its need for the keying material to be renewed, e.g., due to 2048 exhaustion of AEAD nonces, if AEAD is used for protecting group 2049 communication. Depending on the application profile (OPT8), this can 2050 result in renewal of individual keying material, group keying 2051 material, or both. 2053 For example, if the Client uses an individual key to protect outgoing 2054 traffic and has to renew it, the node may request a new one, or new 2055 input material to derive it, without renewing the whole group keying 2056 material. 2058 To this end, the client performs a Key Renewal Request/Response 2059 exchange with the KDC, i.e., it sends a CoAP PUT request to the /ace- 2060 group/GROUPNAME/nodes/NODENAME endpoint at the KDC, where GROUPNAME 2061 is the group name and NODENAME is its node name, and formatted as 2062 defined in Section 4.1.6.2. 2064 Figure 16 gives an overview of the exchange described above, while 2065 Figure 17 shows an example. 2067 Client KDC 2068 | | 2069 |------------------ Key Renewal Request: -------------->| 2070 | PUT ace-group/GROUPNAME/nodes/NODENAME | 2071 | | 2072 |<-------- Key Renewal Response: 2.05 (Content) --------| 2073 | | 2075 Figure 16: Message Flow of Key Renewal Request-Response 2077 Request: 2079 Header: PUT (Code=0.03) 2080 Uri-Host: "kdc.example.com" 2081 Uri-Path: "ace-group" 2082 Uri-Path: "g1" 2083 Uri-Path: "nodes" 2084 Uri-Path: "c101" 2085 Payload: - 2087 Response: 2089 Header: Content (Code=2.05) 2090 Content-Format: "application/ace-groupcomm+cbor" 2091 Payload (in CBOR diagnostic notation, with IND_KEY being 2092 a CBOR byte string, and "ind-key" the profile-specified 2093 label for individual keying material): 2094 { "ind-key": IND_KEY } 2096 Figure 17: Example of Key Renewal Request-Response 2098 Note the difference between the Key Distribution Request and the Key 2099 Renewal Request: while the first one only triggers distribution (the 2100 renewal might have happened independently, e.g., because of 2101 expiration), the second one triggers the KDC to produce new 2102 individual keying material for the requesting node. 2104 4.6. Retrieval of Public Keys and Roles for Group Members 2106 In case the KDC maintains the public keys of group members, a node in 2107 the group can contact the KDC to request public keys and roles of 2108 either all group members or a specified subset, by sending a CoAP GET 2109 or FETCH request to the /ace-group/GROUPNAME/pub-key endpoint at the 2110 KDC, where GROUPNAME is the group name, and formatted as defined in 2111 Section 4.1.3.2 and Section 4.1.3.1. 2113 Figure 18 and Figure 20 give an overview of the exchanges described 2114 above, while Figure 19 and Figure 21 show an example for each 2115 exchange. 2117 Client KDC 2118 | | 2119 |--Public Key Request: GET /ace-group/GROUPNAME/pub-key->| 2120 | | 2121 |<--------- Public Key Response: 2.05 (Content) ---------| 2122 | | 2124 Figure 18: Message Flow of Public Key Exchange to Request All 2125 Members Public Keys 2127 Request: 2129 Header: GET (Code=0.01) 2130 Uri-Host: "kdc.example.com" 2131 Uri-Path: "ace-group" 2132 Uri-Path: "g1" 2133 Uri-Path: "pub-key" 2134 Payload: - 2136 Response: 2138 Header: Content (Code=2.05) 2139 Content-Format: "application/ace-groupcomm+cbor" 2140 Payload (in CBOR diagnostic notation): 2141 { "num": 5, 2142 "pub_keys": [ PUB_KEY1, PUB_KEY2, PUB_KEY3 ], 2143 "peer_roles": ["sender", ["sender", "receiver"], "receiver"], 2144 "peer_identifiers": [ ID1, ID2, ID3 ] } 2146 Figure 19: Example of Public Key Exchange to Request All Members 2147 Public Keys 2149 Client KDC 2150 | | 2151 |-Public Key Request: FETCH /ace-group/GROUPNAME/pub-key->| 2152 | | 2153 |<--------- Public Key Response: 2.05 (Created) ----------| 2154 | | 2156 Figure 20: Message Flow of Public Key Exchange to Request 2157 Specific Members Public Keys 2159 Request: 2161 Header: FETCH (Code=0.05) 2162 Uri-Host: "kdc.example.com" 2163 Uri-Path: "ace-group" 2164 Uri-Path: "g1" 2165 Uri-Path: "pub-key" 2166 Content-Format: "application/ace-groupcomm+cbor" 2167 Payload: 2168 { "get_pub_keys": [true, [], [ ID3 ]] } 2170 Response: 2172 Header: Content (Code=2.05) 2173 Content-Format: "application/ace-groupcomm+cbor" 2174 Payload (in CBOR diagnostic notation): 2175 { "pub_keys": [ PUB_KEY3 ], 2176 "peer_roles": [ "receiver" ], 2177 "peer_identifiers": [ ID3 ] } 2179 Figure 21: Example of Public Key Exchange to Request Specific 2180 Members Public Keys 2182 4.7. Update of Public Key 2184 In case the KDC maintains the public keys of group members, a node in 2185 the group can contact the KDC to upload a new public key to use in 2186 the group, and replace the currently stored one. 2188 To this end, the Client performs a Public Key Update Request/Response 2189 exchange with the KDC, i.e., it sends a CoAP POST request to the 2190 /ace-group/GROUPNAME/nodes/NODENAME/pub-key endpoint at the KDC, 2191 where GROUPNAME is the group name and NODENAME is its node name. 2193 The request is formatted as specified in Section 4.1.7.1. 2195 Figure Figure 22 gives an overview of the exchange described above, 2196 while Figure 23 shows an example. 2198 Client KDC 2199 | | 2200 |-------------- Public Key Update Request: ---------------------->| 2201 | POST ace-group/GROUPNAME/nodes/NODENAME/pub-key | 2202 | | 2203 |<------- Public Key Update Response: 2.04 (Changed) -------------| 2204 | | 2206 Figure 22: Message Flow of Public Key Update Request-Response 2207 Request: 2209 Header: POST (Code=0.02) 2210 Uri-Host: "kdc.example.com" 2211 Uri-Path: "ace-group" 2212 Uri-Path: "g1" 2213 Uri-Path: "nodes" 2214 Uri-Path: "c101" 2215 Uri-Path: "pub-key" 2216 Content-Format: "application/ace-groupcomm+cbor" 2217 Payload (in CBOR diagnostic notation, with PUB_KEY 2218 and POP_EVIDENCE being CBOR byte strings): 2219 { "client_cred": PUB_KEY, "cnonce": h'9ff7684414affcc8', 2220 "client_cred_verify": POP_EVIDENCE } 2222 Response: 2224 Header: Changed (Code=2.04) 2225 Payload: - 2227 Figure 23: Example of Public Key Update Request-Response 2229 If the application requires backward security, the KDC MUST generate 2230 new group keying material and securely distribute it to all the 2231 current group members, upon a group member updating its own public 2232 key. To this end, the KDC uses the message format of the response 2233 defined in Section 4.1.2.2. Application profiles may define 2234 alternative ways of retrieving the keying material, such as sending 2235 separate requests to different resources at the KDC (Section 4.1.2.2, 2236 Section 4.1.3.2, Section 4.1.4.1). The KDC MUST increment the 2237 version number of the current keying material, before distributing 2238 the newly generated keying material to the group. After that, the 2239 KDC SHOULD store the distributed keying material in persistent 2240 storage. 2242 Additionally, after updating its own public key, a group member MAY 2243 send a number of the later requests including an identifier of the 2244 updated public key, to signal nodes that they need to retrieve it. 2245 How that is done depends on the group communication protocol used, 2246 and therefore is application profile specific (OPT10). 2248 4.8. Retrieval of Group Policies 2250 A node in the group can contact the KDC to retrieve the current group 2251 policies, by sending a CoAP GET request to the /ace-group/GROUPNAME/ 2252 policies endpoint at the KDC, where GROUPNAME is the group name, and 2253 formatted as defined in Section 4.1.4.1 2254 Figure 24 gives an overview of the exchange described above, while 2255 Figure 25 shows an example. 2257 Client KDC 2258 | | 2259 |-Policies Request: GET ace-group/GROUPNAME/policies ->| 2260 | | 2261 |<--------- Policies Response: 2.05 (Content) ---------| 2262 | | 2264 Figure 24: Message Flow of Policies Request-Response 2266 Request: 2268 Header: GET (Code=0.01) 2269 Uri-Host: "kdc.example.com" 2270 Uri-Path: "ace-group" 2271 Uri-Path: "g1" 2272 Uri-Path: "policies" 2273 Payload: - 2275 Response: 2277 Header: Content (Code=2.05) 2278 Content-Format: "application/ace-groupcomm+cbor" 2279 Payload(in CBOR diagnostic notation): 2280 { "group_policies": {"exp-delta": 120} } 2282 Figure 25: Example of Policies Request-Response 2284 4.9. Retrieval of Keying Material Version 2286 A node in the group can contact the KDC to request information about 2287 the version number of the symmetric group keying material, by sending 2288 a CoAP GET request to the /ace-group/GROUPNAME/num endpoint at the 2289 KDC, where GROUPNAME is the group name, formatted as defined in 2290 Section 4.1.5.1. In particular, the version is incremented by the 2291 KDC every time the group keying material is renewed, before it's 2292 distributed to the group members. 2294 Figure 26 gives an overview of the exchange described above, while 2295 Figure 27 shows an example. 2297 Client KDC 2298 | | 2299 |---- Version Request: GET ace-group/GROUPNAME/num ---->| 2300 | | 2301 |<--------- Version Response: 2.05 (Content) -----------| 2302 | | 2304 Figure 26: Message Flow of Version Request-Response 2306 Request: 2308 Header: GET (Code=0.01) 2309 Uri-Host: "kdc.example.com" 2310 Uri-Path: "ace-group" 2311 Uri-Path: "g1" 2312 Uri-Path: "num" 2313 Payload: - 2315 Response: 2317 Header: Content (Code=2.05) 2318 Content-Format: text/plain 2319 Payload(in CBOR diagnostic notation): 2320 13 2322 Figure 27: Example of Version Request-Response 2324 4.10. Group Leaving Request 2326 A node can actively request to leave the group. In this case, the 2327 Client sends a CoAP DELETE request to the endpoint /ace- 2328 group/GROUPNAME/nodes/NODENAME at the KDC, where GROUPNAME is the 2329 group name and NODENAME is its node name, formatted as defined in 2330 Section 4.1.6.3 2332 Alternatively, a node may be removed by the KDC, without having 2333 explicitly asked for it. This is further discussed in Section 5. 2335 5. Removal of a Node from the Group 2337 This section describes the different scenarios according to which a 2338 node ends up being removed from the group. 2340 If the application requires forward security, the KDC MUST generate 2341 new group keying material and securely distribute it to all the 2342 current group members but the leaving node, using the message format 2343 of the Key Distribution Response (see Section 4.4). Application 2344 profiles may define alternative message formats. The KDC MUST 2345 increment the version number of the current keying material, before 2346 distributing the newly generated keying material to the group. After 2347 that, the KDC SHOULD store the distributed keying material in 2348 persistent storage. 2350 Note that, after having left the group, a node may wish to join it 2351 again. Then, as long as the node is still authorized to join the 2352 group, i.e., it still has a valid access token, it can request to re- 2353 join the group directly to the KDC without needing to retrieve a new 2354 access token from the AS. This means that the KDC might decide to 2355 keep track of nodes with valid access tokens, before deleting all 2356 information about the leaving node. 2358 A node may be evicted from the group in the following cases. 2360 1. The node explicitly asks to leave the group, as defined in 2361 Section 4.10. 2363 2. The node has been found compromised or is suspected so. 2365 3. The node's authorization to be a group member is not valid 2366 anymore, either because the access token has expired, or it has 2367 been revoked. If the AS provides Token introspection (see 2368 Section 5.9 of [I-D.ietf-ace-oauth-authz]), the KDC can 2369 optionally use it and check whether the node is still authorized 2370 for that group in that role. 2372 In either case, once aware that a node is not authorized anymore, 2373 the KDC has to remove the unauthorized node from the list of 2374 group members, if the KDC keeps track of that. 2376 Furthermore, in case of forced eviction, the KDC removes the public 2377 key of the evicted node if the KDC keep tracks of that, and possibly 2378 removes the evicted node from the list of observers of the resource 2379 at ace-group/GROUPNAME (if observable). 2381 Then, the KDC deletes the sub-resource ace-group/GROUPNAME/nodes/ 2382 NODENAME associated to the evicted node. After that, the KDC MAY 2383 explicitly inform the evicted node, by means of the following 2384 methods. 2386 * If the evicted node implements the 'control_uri' resource 2387 specified in Section 4.1.2.1, the KDC sends a DELETE request, 2388 targeting the URI specified in the 'control_uri' parameter of the 2389 Joining Request (see Section 4.1.2.1). 2391 * If the evicted node is observing its associated sub-resource at 2392 ace-group/GROUPNAME/nodes/NODENAME (see Section 4.1.6.2), the KDC 2393 sends an unsolicited 4.04 (Not Found) response, which does not 2394 include the Observe option and indicates that the observed 2395 resource has been deleted (see Section 3.2 of [RFC7641]). 2397 The response MUST have Content-Format set to application/ace- 2398 groupcomm+cbor and is formatted as defined in Section 4. The 2399 value of the 'error' field MUST be set to 5 ("Group membership 2400 terminated"). 2402 Consistently, the KDC also removes the node's entry from the list 2403 of observers of the sub-resource. 2405 6. Extended Scope Format 2407 This section defines an extended format of binary encoded scope, 2408 which additionally specifies the semantics used to express the same 2409 access control information from the corresponding original scope. 2411 As also discussed in Section 3.2, this enables a Resource Server to 2412 unambiguously process a received access token, also in case the 2413 Resource Server runs multiple applications or application profiles 2414 that involve different scope semantics. 2416 The extended format is intended only for the 'scope' claim of access 2417 tokens, for the cases where the claim takes as value a CBOR byte 2418 string. That is, the extended format does not apply to the 'scope' 2419 parameter included in ACE messages, i.e., the Authorization Request 2420 and Authorization Response exchanged between the client and the 2421 Authorization Server (see Sections 5.8.1 and 5.8.2 of 2422 [I-D.ietf-ace-oauth-authz]), the AS Request Creation Hints message 2423 from the Resource Server (see Section 5.3 of 2424 [I-D.ietf-ace-oauth-authz]), and the Introspection Response from the 2425 Authorization Server (see Section 5.9.2 of 2426 [I-D.ietf-ace-oauth-authz]). 2428 The value of the 'scope' claim following the extended format is 2429 composed as follows. Given the original scope using a semantics SEM 2430 and encoded as a CBOR byte string, the corresponding extended scope 2431 is encoded as a tagged CBOR byte string, wrapping a CBOR sequence 2432 [RFC8742] of two elements. In particular: 2434 * The first element of the sequence is a CBOR integer, and 2435 identifies the semantics SEM used for this scope. The value of 2436 this element has to be taken from the "Value" column of the "ACE 2437 Scope Semantics" registry defined in Section 10.12 of this 2438 specification. 2440 When defining a new semantics for a binary scope, it is up to the 2441 applications and application profiles to define and register the 2442 corresponding integer identifier (REQ24). 2444 * The second element of the sequence is the original scope using the 2445 semantics SEM, encoded as a CBOR byte string. 2447 Finally, the CBOR byte string wrapping the CBOR sequence is tagged, 2448 and identified by the CBOR tag TBD_TAG "ACE Extended Scope Format", 2449 defined in Section 10.11 of this specification. 2451 The resulting tagged CBOR byte string is used as value of the 'scope' 2452 claim of the access token. 2454 The usage of the extended scope format is not limited to application 2455 profiles of this specification or to applications based on group 2456 communication. Rather, it is generally applicable to any application 2457 and application profile where access control information in the 2458 access token is expressed as a binary encoded scope. 2460 Figure 28 and Figure 29 build on the examples in Section 3.2, and 2461 show the corresponding extended scopes. 2463 gname = tstr 2465 permissions = uint . bits roles 2467 roles = &( 2468 Requester: 1, 2469 Responder: 2, 2470 Monitor: 3, 2471 Verifier: 4 2472 ) 2474 scope_entry = AIF_Generic 2476 scope = << [ + scope_entry ] >> 2478 semantics = int 2480 ; This defines an array, the elements 2481 ; of which are to be used in a CBOR Sequence: 2482 sequence = [semantics, scope] 2484 extended_scope = #6.TBD_TAG(<< sequence >>) 2486 Figure 28: Example CDLL definition of scope, using the default 2487 Authorization Information Format 2489 gname = tstr 2491 role = tstr 2493 scope_entry = [ gname , ? ( role / [ 2*role ] ) ] 2495 scope = << [ + scope_entry ] >> 2497 semantics = int 2499 ; This defines an array, the elements 2500 ; of which are to be used in a CBOR Sequence: 2501 sequence = [semantics, scope] 2503 extended_scope = #6.TBD_TAG(<< sequence >>) 2505 Figure 29: CDLL definition of scope, using as example group name 2506 encoded as tstr and role as tstr 2508 7. ACE Groupcomm Parameters 2510 This specification defines a number of fields used during the second 2511 part of the message exchange, after the ACE Token POST exchange. The 2512 table below summarizes them, and specifies the CBOR key to use 2513 instead of the full descriptive name. 2515 Note that the media type application/ace-groupcomm+cbor MUST be used 2516 when these fields are transported. 2518 +=======================+======+================+==================+ 2519 | Name | CBOR | CBOR Type | Reference | 2520 | | Key | | | 2521 +=======================+======+================+==================+ 2522 | error | TBD | int | Section 4 | 2523 +-----------------------+------+----------------+------------------+ 2524 | error_description | TBD | text string | Section 4 | 2525 +-----------------------+------+----------------+------------------+ 2526 | scope | TBD | byte string | Section 4.1.2.1 | 2527 +-----------------------+------+----------------+------------------+ 2528 | get_pub_keys | TBD | array / simple | Section 4.1.2.1, | 2529 | | | value null | Section 4.1.3.1 | 2530 +-----------------------+------+----------------+------------------+ 2531 | client_cred | TBD | byte string | Section 4.1.2.1 | 2532 +-----------------------+------+----------------+------------------+ 2533 | cnonce | TBD | byte string | Section 4.1.2.1 | 2534 +-----------------------+------+----------------+------------------+ 2535 | client_cred_verify | TBD | byte string | Section 4.1.2.1 | 2536 +-----------------------+------+----------------+------------------+ 2537 | pub_keys_repos | TBD | text string | Section 4.1.2.1 | 2538 +-----------------------+------+----------------+------------------+ 2539 | control_uri | TBD | text string | Section 4.1.2.1 | 2540 +-----------------------+------+----------------+------------------+ 2541 | gkty | TBD | integer / text | Section 4.1.2.1 | 2542 | | | string | | 2543 +-----------------------+------+----------------+------------------+ 2544 | key | TBD | see "ACE | Section 4.1.2.1 | 2545 | | | Groupcomm Key" | | 2546 | | | Registry | | 2547 +-----------------------+------+----------------+------------------+ 2548 | num | TBD | int | Section 4.1.2.1 | 2549 +-----------------------+------+----------------+------------------+ 2550 | ace-groupcomm-profile | TBD | int | Section 4.1.2.1 | 2551 +-----------------------+------+----------------+------------------+ 2552 | exp | TBD | int | Section 4.1.2.1 | 2553 +-----------------------+------+----------------+------------------+ 2554 | pub_keys | TBD | array | Section 4.1.2.1 | 2555 +-----------------------+------+----------------+------------------+ 2556 | peer_roles | TBD | array | Section 4.1.2.1 | 2557 +-----------------------+------+----------------+------------------+ 2558 | peer_identifiers | TBD | array | Section 4.1.2.1 | 2559 +-----------------------+------+----------------+------------------+ 2560 | group_policies | TBD | map | Section 4.1.2.1 | 2561 +-----------------------+------+----------------+------------------+ 2562 | mgt_key_material | TBD | byte string | Section 4.1.2.1 | 2563 +-----------------------+------+----------------+------------------+ 2564 | sign_info | TBD | array | Section 4.1.2.1 | 2565 +-----------------------+------+----------------+------------------+ 2566 | gid | TBD | array | Section 4.1.1.1 | 2567 +-----------------------+------+----------------+------------------+ 2568 | gname | TBD | array of text | Section 4.1.1.1 | 2569 | | | strings | | 2570 +-----------------------+------+----------------+------------------+ 2571 | guri | TBD | array of text | Section 4.1.1.1 | 2572 | | | strings | | 2573 +-----------------------+------+----------------+------------------+ 2574 | kdcchallenge | TBD | byte string | Section 4.1.7.1 | 2575 +-----------------------+------+----------------+------------------+ 2577 Table 1 2579 8. ACE Groupcomm Error Identifiers 2581 This specification defines a number of values that the KDC can 2582 include as error identifiers, in the 'error' field of an error 2583 response with Content-Format application/ace-groupcomm+cbor. 2585 +=======+======================================================+ 2586 | Value | Description | 2587 +=======+======================================================+ 2588 | 0 | Operation permitted only to group members | 2589 +-------+------------------------------------------------------+ 2590 | 1 | Request inconsistent with the current roles | 2591 +-------+------------------------------------------------------+ 2592 | 2 | Public key incompatible with the group configuration | 2593 +-------+------------------------------------------------------+ 2594 | 3 | Invalid proof-of-possession evidence | 2595 +-------+------------------------------------------------------+ 2596 | 4 | No available node identifiers | 2597 +-------+------------------------------------------------------+ 2598 | 5 | Group membership terminated | 2599 +-------+------------------------------------------------------+ 2600 | 6 | Group deleted | 2601 +-------+------------------------------------------------------+ 2603 Table 2 2605 9. Security Considerations 2607 When a Client receives a message from a sender for the first time, it 2608 needs to have a mechanism in place to avoid replay, e.g., 2609 Appendix B.2 of [RFC8613]. In case the Client rebooted and lost the 2610 security state used to protect previous communication with that 2611 sender, such a mechanism is useful for the recipient to be on the 2612 safe side. 2614 Besides, if the KDC has renewed the group keying material, and the 2615 time interval between the end of the rekeying process and the joining 2616 of the Client is sufficiently small, that Client is also on the safe 2617 side, since replayed older messages protected with the previous 2618 keying material will not be accepted. 2620 The KDC must renew the group keying material upon its expiration. 2622 The KDC should renew the keying material upon group membership 2623 change, and should provide it to the current group members through 2624 the rekeying scheme used in the group. 2626 The KDC should renew the group keying material after rebooting, even 2627 in the case where all keying material is stored in persistent 2628 storage. However, if the KDC relies on Observe responses to notify 2629 the group of renewed keying material, after rebooting the KDC will 2630 have lost all the current ongoing Observations with the group 2631 members, and the previous keying material will be used to protect 2632 messages in the group anyway. The KDC will rely on each node 2633 requesting updates of the group keying material to establish the new 2634 keying material in the nodes, or, if implemented, it can push the 2635 update to the nodes in the group using the 'control_uri' resource. 2637 The KDC may enforce a rekeying policy that takes into account the 2638 overall time required to rekey the group, as well as the expected 2639 rate of changes in the group membership. 2641 That is, the KDC may not rekey the group at every membership change, 2642 for instance if members' joining and leaving occur frequently and 2643 performing a group rekeying takes too long. The KDC may rekey the 2644 group after a minimum number of group members have joined or left 2645 within a given time interval, or after maximum amount of time since 2646 the last rekeying was completed, or yet during predictable network 2647 inactivity periods. 2649 However, this would result in the KDC not constantly preserving 2650 backward and forward security. Newly joining group members could be 2651 able to access the keying material used before their joining, and 2652 thus could access past group communications. Also, until the KDC 2653 performs a group rekeying, the newly leaving nodes would still be 2654 able to access upcoming group communications that are protected with 2655 the keying material that has not yet been updated. 2657 The KDC needs to have a mechanism in place to detect DoS attacks from 2658 nodes constantly initiating rekey events (for example by updating 2659 their public key), such as removing these nodes from the group. 2661 The KDC also needs to have a congestion control mechanism in place to 2662 avoid network congestion when the KDC renews the group keying 2663 material; CoAP and Observe give guidance on such mechanisms, see 2664 Section 4.7 of [RFC7252] and Section 4.5.1 of [RFC7641]. 2666 9.1. Update of Keying Material 2668 A group member can receive a message shortly after the group has been 2669 rekeyed, and new keying material has been distributed by the KDC. In 2670 the following two cases, this may result in misaligned keying 2671 material between the group members. 2673 In the first case, the sender protects a message using the old keying 2674 material. However, the recipient receives the message after having 2675 received the new keying material, hence not being able to correctly 2676 process it. A possible way to ameliorate this issue is to preserve 2677 the old, recent, keying material for a maximum amount of time defined 2678 by the application. By doing so, the recipient can still try to 2679 process the received message using the old retained keying material. 2680 Note that a former (compromised) group member can take advantage of 2681 this by sending messages protected with the old retained keying 2682 material. Therefore, a conservative application policy should not 2683 admit the storage of old keying material. 2685 In the second case, the sender protects a message using the new 2686 keying material, but the recipient receives that request before 2687 having received the new keying material. Therefore, the recipient 2688 would not be able to correctly process the request and hence discards 2689 it. If the recipient receives the new keying material shortly after 2690 that and the application at the sender endpoint performs 2691 retransmissions, the former will still be able to receive and 2692 correctly process the message. In any case, the recipient should 2693 actively ask the KDC for an updated keying material according to an 2694 application-defined policy, for instance after a given number of 2695 unsuccessfully decrypted incoming messages. 2697 A node that has left the group should not expect any of its outgoing 2698 messages to be successfully processed, if received after its leaving, 2699 due to a possible group rekeying occurred before the message 2700 reception. 2702 9.2. Block-Wise Considerations 2704 If the block-wise options [RFC7959] are used, and the keying material 2705 is updated in the middle of a block-wise transfer, the sender of the 2706 blocks just changes the keying material to the updated one and 2707 continues the transfer. As long as both sides get the new keying 2708 material, updating the keying material in the middle of a transfer 2709 will not cause any issue. Otherwise, the sender will have to 2710 transmit the message again, when receiving an error message from the 2711 recipient. 2713 Compared to a scenario where the transfer does not use block-wise, 2714 depending on how fast the keying material is changed, the nodes might 2715 consume a larger amount of the network bandwidth resending the blocks 2716 again and again, which might be problematic. 2718 10. IANA Considerations 2720 This document has the following actions for IANA. 2722 10.1. Media Type Registrations 2724 This specification registers the 'application/ace-groupcomm+cbor' 2725 media type for messages of the protocols defined in this document 2726 following the ACE exchange and carrying parameters encoded in CBOR. 2727 This registration follows the procedures specified in [RFC6838]. 2729 Type name: application 2731 Subtype name: ace-groupcomm+cbor 2733 Required parameters: N/A 2735 Optional parameters: N/A 2737 Encoding considerations: Must be encoded as CBOR map containing the 2738 protocol parameters defined in [this document]. 2740 Security considerations: See Section 9 of this document. 2742 Interoperability considerations: n/a 2744 Published specification: [this document] 2746 Applications that use this media type: The type is used by 2747 authorization servers, clients and resource servers that support the 2748 ACE groupcomm framework as specified in [this document]. 2750 Fragment identifier considerations: N/A 2752 Additional information: N/A 2754 Person & email address to contact for further information: 2755 iesg@ietf.org (mailto:iesg@ietf.org) 2757 Intended usage: COMMON 2759 Restrictions on usage: None 2761 Author: Francesca Palombini francesca.palombini@ericsson.com 2762 (mailto:francesca.palombini@ericsson.com) 2764 Change controller: IESG 2766 10.2. CoAP Content-Formats Registry 2768 This specification registers the following entry to the "CoAP 2769 Content-Formats" registry, within the "CoRE Parameters" registry: 2771 Media Type: application/ace-groupcomm+cbor 2773 Encoding: - 2775 ID: TBD 2776 Reference: [this document] 2778 10.3. OAuth Parameters Registry 2780 The following registrations are done for the OAuth Parameters 2781 Registry following the procedure specified in Section 11.2 of 2782 [RFC6749]: 2784 * Parameter name: sign_info 2786 * Parameter usage location: client-rs request, rs-client response 2788 * Change Controller: IESG 2790 * Specification Document(s): [[This specification]] 2792 * Parameter name: kdcchallenge 2794 * Parameter usage location: rs-client response 2796 * Change Controller: IESG 2798 * Specification Document(s): [[This specification]] 2800 10.4. OAuth Parameters CBOR Mappings Registry 2802 The following registrations are done for the OAuth Parameters CBOR 2803 Mappings Registry following the procedure specified in Section 8.10 2804 of [I-D.ietf-ace-oauth-authz]: 2806 * Name: sign_info 2808 * CBOR Key: TBD (range -256 to 255) 2810 * Value Type: Simple value Null / array 2812 * Reference: [[This specification]] 2814 * Name: kdcchallenge 2816 * CBOR Key: TBD (range -256 to 255) 2818 * Value Type: Byte string 2820 * Reference: [[This specification]] 2822 10.5. ACE Groupcomm Parameters Registry 2824 This specification establishes the "ACE Groupcomm Parameters" IANA 2825 Registry. The Registry has been created to use the "Expert Review" 2826 registration procedure [RFC8126]. Expert review guidelines are 2827 provided in Section 10.14. 2829 The columns of this Registry are: 2831 * Name: This is a descriptive name that enables easier reference to 2832 the item. The name MUST be unique. It is not used in the 2833 encoding. 2835 * CBOR Key: This is the value used as CBOR key of the item. These 2836 values MUST be unique. The value can be a positive integer, a 2837 negative integer, or a string. 2839 * CBOR Type: This contains the CBOR type of the item, or a pointer 2840 to the registry that defines its type, when that depends on 2841 another item. 2843 * Reference: This contains a pointer to the public specification for 2844 the item. 2846 This Registry has been initially populated by the values in 2847 Section 7. The Reference column for all of these entries refers to 2848 sections of this document. 2850 10.6. ACE Groupcomm Key Registry 2852 This specification establishes the "ACE Groupcomm Key" IANA Registry. 2853 The Registry has been created to use the "Expert Review" registration 2854 procedure [RFC8126]. Expert review guidelines are provided in 2855 Section 10.14. 2857 The columns of this Registry are: 2859 * Name: This is a descriptive name that enables easier reference to 2860 the item. The name MUST be unique. It is not used in the 2861 encoding. 2863 * Key Type Value: This is the value used to identify the keying 2864 material. These values MUST be unique. The value can be a 2865 positive integer, a negative integer, or a text string. 2867 * Profile: This field may contain one or more descriptive strings of 2868 application profiles to be used with this item. The values should 2869 be taken from the Name column of the "ACE Groupcomm Profile" 2870 Registry. 2872 * Description: This field contains a brief description of the keying 2873 material. 2875 * References: This contains a pointer to the public specification 2876 for the format of the keying material, if one exists. 2878 This Registry has been initially populated by the values in Figure 8. 2879 The specification column for all of these entries will be this 2880 document. 2882 10.7. ACE Groupcomm Profile Registry 2884 This specification establishes the "ACE Groupcomm Profile" IANA 2885 Registry. The Registry has been created to use the "Expert Review" 2886 registration procedure [RFC8126]. Expert review guidelines are 2887 provided in Section 10.14. It should be noted that, in addition to 2888 the expert review, some portions of the Registry require a 2889 specification, potentially a Standards Track RFC, to be supplied as 2890 well. 2892 The columns of this Registry are: 2894 * Name: The name of the application profile, to be used as value of 2895 the profile attribute. 2897 * Description: Text giving an overview of the application profile 2898 and the context it is developed for. 2900 * CBOR Value: CBOR abbreviation for the name of this application 2901 profile. Different ranges of values use different registration 2902 policies [RFC8126]. Integer values from -256 to 255 are 2903 designated as Standards Action. Integer values from -65536 to 2904 -257 and from 256 to 65535 are designated as Specification 2905 Required. Integer values greater than 65535 are designated as 2906 Expert Review. Integer values less than -65536 are marked as 2907 Private Use. 2909 * Reference: This contains a pointer to the public specification of 2910 the abbreviation for this application profile, if one exists. 2912 10.8. ACE Groupcomm Policy Registry 2914 This specification establishes the "ACE Groupcomm Policy" IANA 2915 Registry. The Registry has been created to use the "Expert Review" 2916 registration procedure [RFC8126]. Expert review guidelines are 2917 provided in Section 10.14. It should be noted that, in addition to 2918 the expert review, some portions of the Registry require a 2919 specification, potentially a Standards Track RFC, to be supplied as 2920 well. 2922 The columns of this Registry are: 2924 * Name: The name of the group communication policy. 2926 * CBOR label: The value to be used to identify this group 2927 communication policy. Key map labels MUST be unique. The label 2928 can be a positive integer, a negative integer or a string. 2929 Integer values between 0 and 255 and strings of length 1 are 2930 designated as Standards Track Document required. Integer values 2931 from 256 to 65535 and strings of length 2 are designated as 2932 Specification Required. Integer values greater than 65535 and 2933 strings of length greater than 2 are designated as expert review. 2934 Integer values less than -65536 are marked as private use. 2936 * CBOR type: the CBOR type used to encode the value of this group 2937 communication policy. 2939 * Description: This field contains a brief description for this 2940 group communication policy. 2942 * Reference: This field contains a pointer to the public 2943 specification providing the format of the group communication 2944 policy, if one exists. 2946 This registry will be initially populated by the values in Figure 9. 2948 10.9. Sequence Number Synchronization Method Registry 2950 This specification establishes the "Sequence Number Synchronization 2951 Method" IANA Registry. The Registry has been created to use the 2952 "Expert Review" registration procedure [RFC8126]. Expert review 2953 guidelines are provided in Section 10.14. It should be noted that, 2954 in addition to the expert review, some portions of the Registry 2955 require a specification, potentially a Standards Track RFC, to be 2956 supplied as well. 2958 The columns of this Registry are: 2960 * Name: The name of the sequence number synchronization method. 2962 * Value: The value to be used to identify this sequence number 2963 synchronization method. 2965 * Description: This field contains a brief description for this 2966 sequence number synchronization method. 2968 * Reference: This field contains a pointer to the public 2969 specification describing the sequence number synchronization 2970 method. 2972 10.10. Interface Description (if=) Link Target Attribute Values 2973 Registry 2975 This specification registers the following entry to the "Interface 2976 Description (if=) Link Target Attribute Values Registry" registry, 2977 within the "CoRE Parameters" registry: 2979 * Attribute Value: ace.group 2981 * Description: The 'ace group' interface is used to provision keying 2982 material and related information and policies to members of a 2983 group using the Ace framework. 2985 * Reference: [This Document] 2987 10.11. CBOR Tags Registry 2989 This specification registers the following entry to the "CBOR Tags" 2990 registry: 2992 * Tag : TBD_TAG 2994 * Data Item: byte string 2996 * Semantics: Extended ACE scope format, including the identifier of 2997 the used scope semantics. 2999 * Reference: [This Document] 3001 10.12. ACE Scope Semantics 3003 This specification establishes the "ACE Scope Semantics" IANA 3004 Registry. The Registry has been created to use the "Expert Review" 3005 registration procedure [RFC8126]. Expert review guidelines are 3006 provided in Section 10.14. It should be noted that, in addition to 3007 the expert review, some portions of the Registry require a 3008 specification, potentially a Standards Track RFC, to be supplied as 3009 well. 3011 The columns of this Registry are: 3013 * Value: The value to be used to identify this scope semantics. The 3014 value MUST be unique. The value can be a positive integer or a 3015 negative integer. Integer values between 0 and 255 are designated 3016 as Standards Track Document required. Integer values from 256 to 3017 65535 are designated as Specification Required. Integer values 3018 greater than 65535 are designated as expert review. Integer 3019 values less than -65536 are marked as private use. 3021 * Description: This field contains a brief description of the scope 3022 semantics. 3024 * Reference: This field contains a pointer to the public 3025 specification defining the scope semantics, if one exists. 3027 10.13. ACE Groupcomm Errors 3029 This specification establishes the "ACE Groupcomm Errors" IANA 3030 Registry. The Registry has been created to use the "Expert Review" 3031 registration procedure [RFC8126]. Expert review guidelines are 3032 provided in Section 10.14. It should be noted that, in addition to 3033 the expert review, some portions of the Registry require a 3034 specification, potentially a Standards Track RFC, to be supplied as 3035 well. 3037 The columns of this Registry are: 3039 * Value: The value to be used to identify the error. The value MUST 3040 be unique. The value can be a positive integer or a negative 3041 integer. Integer values between 0 and 255 are designated as 3042 Standards Track Document required. Integer values from 256 to 3043 65535 are designated as Specification Required. Integer values 3044 greater than 65535 are designated as expert review. Integer 3045 values less than -65536 are marked as private use. 3047 * Description: This field contains a brief description of the error. 3049 * Reference: This field contains a pointer to the public 3050 specification defining the error, if one exists. 3052 This Registry has been initially populated by the values in 3053 Section 8. The Reference column for all of these entries refers to 3054 this document. 3056 10.14. Expert Review Instructions 3058 The IANA Registries established in this document are defined as 3059 expert review. This section gives some general guidelines for what 3060 the experts should be looking for, but they are being designated as 3061 experts for a reason so they should be given substantial latitude. 3063 Expert reviewers should take into consideration the following points: 3065 * Point squatting should be discouraged. Reviewers are encouraged 3066 to get sufficient information for registration requests to ensure 3067 that the usage is not going to duplicate one that is already 3068 registered and that the point is likely to be used in deployments. 3069 The zones tagged as private use are intended for testing purposes 3070 and closed environments, code points in other ranges should not be 3071 assigned for testing. 3073 * Specifications are required for the standards track range of point 3074 assignment. Specifications should exist for specification 3075 required ranges, but early assignment before a specification is 3076 available is considered to be permissible. Specifications are 3077 needed for the first-come, first-serve range if they are expected 3078 to be used outside of closed environments in an interoperable way. 3079 When specifications are not provided, the description provided 3080 needs to have sufficient information to identify what the point is 3081 being used for. 3083 * Experts should take into account the expected usage of fields when 3084 approving point assignment. The fact that there is a range for 3085 standards track documents does not mean that a standards track 3086 document cannot have points assigned outside of that range. The 3087 length of the encoded value should be weighed against how many 3088 code points of that length are left, the size of device it will be 3089 used on, and the number of code points left that encode to that 3090 size. 3092 11. References 3094 11.1. Normative References 3096 [COSE.Algorithms] 3097 IANA, "COSE Algorithms", 3098 . 3101 [COSE.Header.Parameters] 3102 IANA, "COSE Header Parameters", 3103 . 3106 [I-D.ietf-ace-aif] 3107 Bormann, C., "An Authorization Information Format (AIF) 3108 for ACE", Work in Progress, Internet-Draft, draft-ietf- 3109 ace-aif-03, 24 June 2021, 3110 . 3113 [I-D.ietf-ace-oauth-authz] 3114 Seitz, L., Selander, G., Wahlstroem, E., Erdtman, S., and 3115 H. Tschofenig, "Authentication and Authorization for 3116 Constrained Environments (ACE) using the OAuth 2.0 3117 Framework (ACE-OAuth)", Work in Progress, Internet-Draft, 3118 draft-ietf-ace-oauth-authz-43, 10 July 2021, 3119 . 3122 [I-D.ietf-core-oscore-groupcomm] 3123 Tiloca, M., Selander, G., Palombini, F., Mattsson, J. P., 3124 and J. Park, "Group OSCORE - Secure Group Communication 3125 for CoAP", Work in Progress, Internet-Draft, draft-ietf- 3126 core-oscore-groupcomm-12, 12 July 2021, 3127 . 3130 [I-D.ietf-cose-rfc8152bis-algs] 3131 Schaad, J., "CBOR Object Signing and Encryption (COSE): 3132 Initial Algorithms", Work in Progress, Internet-Draft, 3133 draft-ietf-cose-rfc8152bis-algs-12, 24 September 2020, 3134 . 3137 [I-D.ietf-cose-rfc8152bis-struct] 3138 Schaad, J., "CBOR Object Signing and Encryption (COSE): 3139 Structures and Process", Work in Progress, Internet-Draft, 3140 draft-ietf-cose-rfc8152bis-struct-15, 1 February 2021, 3141 . 3144 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 3145 Requirement Levels", BCP 14, RFC 2119, 3146 DOI 10.17487/RFC2119, March 1997, 3147 . 3149 [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", 3150 RFC 6749, DOI 10.17487/RFC6749, October 2012, 3151 . 3153 [RFC6838] Freed, N., Klensin, J., and T. Hansen, "Media Type 3154 Specifications and Registration Procedures", BCP 13, 3155 RFC 6838, DOI 10.17487/RFC6838, January 2013, 3156 . 3158 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 3159 Application Protocol (CoAP)", RFC 7252, 3160 DOI 10.17487/RFC7252, June 2014, 3161 . 3163 [RFC7967] Bhattacharyya, A., Bandyopadhyay, S., Pal, A., and T. 3164 Bose, "Constrained Application Protocol (CoAP) Option for 3165 No Server Response", RFC 7967, DOI 10.17487/RFC7967, 3166 August 2016, . 3168 [RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for 3169 Writing an IANA Considerations Section in RFCs", BCP 26, 3170 RFC 8126, DOI 10.17487/RFC8126, June 2017, 3171 . 3173 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 3174 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 3175 May 2017, . 3177 [RFC8610] Birkholz, H., Vigano, C., and C. Bormann, "Concise Data 3178 Definition Language (CDDL): A Notational Convention to 3179 Express Concise Binary Object Representation (CBOR) and 3180 JSON Data Structures", RFC 8610, DOI 10.17487/RFC8610, 3181 June 2019, . 3183 [RFC8742] Bormann, C., "Concise Binary Object Representation (CBOR) 3184 Sequences", RFC 8742, DOI 10.17487/RFC8742, February 2020, 3185 . 3187 [RFC8747] Jones, M., Seitz, L., Selander, G., Erdtman, S., and H. 3188 Tschofenig, "Proof-of-Possession Key Semantics for CBOR 3189 Web Tokens (CWTs)", RFC 8747, DOI 10.17487/RFC8747, March 3190 2020, . 3192 [RFC8949] Bormann, C. and P. Hoffman, "Concise Binary Object 3193 Representation (CBOR)", STD 94, RFC 8949, 3194 DOI 10.17487/RFC8949, December 2020, 3195 . 3197 11.2. Informative References 3199 [I-D.ietf-ace-dtls-authorize] 3200 Gerdes, S., Bergmann, O., Bormann, C., Selander, G., and 3201 L. Seitz, "Datagram Transport Layer Security (DTLS) 3202 Profile for Authentication and Authorization for 3203 Constrained Environments (ACE)", Work in Progress, 3204 Internet-Draft, draft-ietf-ace-dtls-authorize-18, 4 June 3205 2021, . 3208 [I-D.ietf-ace-mqtt-tls-profile] 3209 Sengul, C. and A. Kirby, "Message Queuing Telemetry 3210 Transport (MQTT)-TLS profile of Authentication and 3211 Authorization for Constrained Environments (ACE) 3212 Framework", Work in Progress, Internet-Draft, draft-ietf- 3213 ace-mqtt-tls-profile-12, 11 May 2021, 3214 . 3217 [I-D.ietf-ace-oscore-profile] 3218 Palombini, F., Seitz, L., Selander, G., and M. Gunnarsson, 3219 "OSCORE Profile of the Authentication and Authorization 3220 for Constrained Environments Framework", Work in Progress, 3221 Internet-Draft, draft-ietf-ace-oscore-profile-19, 6 May 3222 2021, . 3225 [I-D.ietf-core-coap-pubsub] 3226 Koster, M., Keranen, A., and J. Jimenez, "Publish- 3227 Subscribe Broker for the Constrained Application Protocol 3228 (CoAP)", Work in Progress, Internet-Draft, draft-ietf- 3229 core-coap-pubsub-09, 30 September 2019, 3230 . 3233 [I-D.ietf-core-groupcomm-bis] 3234 Dijk, E., Wang, C., and M. Tiloca, "Group Communication 3235 for the Constrained Application Protocol (CoAP)", Work in 3236 Progress, Internet-Draft, draft-ietf-core-groupcomm-bis- 3237 04, 12 July 2021, . 3240 [RFC2093] Harney, H. and C. Muckenhirn, "Group Key Management 3241 Protocol (GKMP) Specification", RFC 2093, 3242 DOI 10.17487/RFC2093, July 1997, 3243 . 3245 [RFC2094] Harney, H. and C. Muckenhirn, "Group Key Management 3246 Protocol (GKMP) Architecture", RFC 2094, 3247 DOI 10.17487/RFC2094, July 1997, 3248 . 3250 [RFC2627] Wallner, D., Harder, E., and R. Agee, "Key Management for 3251 Multicast: Issues and Architectures", RFC 2627, 3252 DOI 10.17487/RFC2627, June 1999, 3253 . 3255 [RFC7519] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token 3256 (JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015, 3257 . 3259 [RFC7641] Hartke, K., "Observing Resources in the Constrained 3260 Application Protocol (CoAP)", RFC 7641, 3261 DOI 10.17487/RFC7641, September 2015, 3262 . 3264 [RFC7959] Bormann, C. and Z. Shelby, Ed., "Block-Wise Transfers in 3265 the Constrained Application Protocol (CoAP)", RFC 7959, 3266 DOI 10.17487/RFC7959, August 2016, 3267 . 3269 [RFC8259] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 3270 Interchange Format", STD 90, RFC 8259, 3271 DOI 10.17487/RFC8259, December 2017, 3272 . 3274 [RFC8392] Jones, M., Wahlstroem, E., Erdtman, S., and H. Tschofenig, 3275 "CBOR Web Token (CWT)", RFC 8392, DOI 10.17487/RFC8392, 3276 May 2018, . 3278 [RFC8613] Selander, G., Mattsson, J., Palombini, F., and L. Seitz, 3279 "Object Security for Constrained RESTful Environments 3280 (OSCORE)", RFC 8613, DOI 10.17487/RFC8613, July 2019, 3281 . 3283 Appendix A. Requirements on Application Profiles 3285 This section lists the requirements on application profiles of this 3286 specification,for the convenience of application profile designers. 3288 * REQ1: If the value of the GROUPNAME URI path and the group name in 3289 the access token scope (gname in Section 3.2) don't match, specify 3290 the mechanism to map the GROUPNAME value in the URI to the group 3291 name (REQ1) (see Section 4.1). 3293 * REQ2: Specify the encoding and value of roles, for scope entries 3294 of 'scope' (see Section 3.1). 3296 * REQ3: If used, specify the acceptable values for 'sign_alg' (see 3297 Section 3.3). 3299 * REQ4: If used, specify the acceptable values for 'sign_parameters' 3300 (see Section 3.3). 3302 * REQ5: If used, specify the acceptable values for 3303 'sign_key_parameters' (see Section 3.3). 3305 * REQ6: Specify the acceptable formats for encoding public keys and, 3306 if used, the acceptable values for 'pub_key_enc' (see 3307 Section 3.3). 3309 * REQ7: Register a Resource Type for the root url-path, which is 3310 used to discover the correct url to access at the KDC (see 3311 Section 4.1). 3313 * REQ8: Define what operations (e.g., CoAP methods) are allowed on 3314 each resource, for each role defined in REQ2 (see Section 3.3). 3316 * REQ9: Specify the exact encoding of group identifier (see 3317 Section 4.1.1.1). 3319 * REQ10: Specify the exact format of the 'key' value (see 3320 Section 4.1.2.1). 3322 * REQ11: Specify the acceptable values of 'gkty' (see 3323 Section 4.1.2.1). 3325 * REQ12: Specify the format of the identifiers of group members (see 3326 Section 4.1.2.1). 3328 * REQ13: Specify the communication protocol the members of the group 3329 must use (e.g., multicast CoAP). 3331 * REQ14: Specify the security protocol the group members must use to 3332 protect their communication (e.g., group OSCORE). This must 3333 provide encryption, integrity and replay protection. 3335 * REQ15: Specify and register the application profile identifier 3336 (see Section 4.1.2.1). 3338 * REQ16: Specify policies at the KDC to handle ids that are not 3339 included in 'get_pub_keys' (see Section 4.1.3.1). 3341 * REQ17: If used, specify the format and content of 'group_policies' 3342 and its entries. Specify the policies default values (see 3343 Section 4.1.2.1). 3345 * REQ18: Specify the format of newly-generated individual keying 3346 material for group members, or of the information to derive it, 3347 and corresponding CBOR label (see Section 4.1.6.2). 3349 * REQ19: Specify how the communication is secured between Client and 3350 KDC. Optionally, specify tranport profile of ACE 3351 [I-D.ietf-ace-oauth-authz] to use between Client and KDC (see 3352 Section 4.3. 3354 * REQ20: Specify the exact approaches used to compute and verify the 3355 PoP evidence to include in 'client_cred_verify', and which of 3356 those approaches is used in which case (see Section 4.1.2.1). 3358 * REQ21: Specify how the nonce N_S is generated, if the token was 3359 not posted (e.g., if it is used directly to validate TLS instead). 3361 * REQ22: Specify if 'mgt_key_material' used, and if yes specify its 3362 format and content (see Section 4.1.2.1). If the usage of 3363 'mgt_key_material' is indicated and its format defined for a 3364 specific key management scheme, that format must explicitly 3365 indicate the key management scheme itself. If a new rekeying 3366 scheme is defined to be used for an existing 'mgt_key_material' in 3367 an existing profile, then that profile will have to be updated 3368 accordingly, especially with respect to the usage of 3369 'mgt_key_material' related format and content. 3371 * REQ23: Define the initial value of the 'num' parameter (see 3372 Section 4.1.2.1). 3374 * REQ24: Specify and register the identifier of newly defined 3375 semantics for binary scopes (see Section 6). 3377 * OPT1: Optionally, specify the negotiation of parameter values for 3378 signature algorithm and signature keys, if 'sign_info' is not used 3379 (see Section 3.3). 3381 * OPT2: Optionally, specify the additional parameters used in the 3382 Token Post exchange (see Section 3.3). 3384 * OPT3: Optionally, specify the encoding of 'pub_keys_repos' if the 3385 default is not used (see Section 4.1.2.1). 3387 * OPT4: Optionally, specify policies that instruct clients to retain 3388 messages and for how long, if they are unsuccessfully decrypted 3389 (see Section 4.4). This makes it possible to decrypt such 3390 messages after getting updated keying material. 3392 * OPT5: Optionally, specify possible or required payload formats for 3393 specific error cases. 3395 * OPT6: Optionally, specify the behavior of the handler in case of 3396 failure to retrieve a public key for the specific node (see 3397 Section 4.1.2.1). 3399 * OPT7: Optionally, specify CBOR values to use for abbreviating 3400 identifiers of roles in the group or topic (see Section 3.1). 3402 * OPT8: Optionally, specify for the KDC to perform group rekeying 3403 (together or instead of renewing individual keying material) when 3404 receiving a Key Renewal Request (see Section 4.5). 3406 * OPT9: Optionally, specify the functionalities implemented at the 3407 'control_uri' resource hosted at the Client, including message 3408 exchange encoding and other details (see Section 4.1.2.1). 3410 * OPT10: Optionally, specify how the identifier of the sender's 3411 public key is included in the group request (see Section 4.7). 3413 * OPT11: Optionally, specify additional identifiers of error types, 3414 as values of the 'error' field in an error response from the KDC. 3416 Appendix B. Extensibility for Future COSE Algorithms 3418 As defined in Section 8.1 of [I-D.ietf-cose-rfc8152bis-algs], future 3419 algorithms can be registered in the "COSE Algorithms" Registry 3420 [COSE.Algorithms] as specifying none or multiple COSE capabilities. 3422 To enable the seamless use of such future registered algorithms, this 3423 section defines a general, agile format for each 'sign_info_entry' of 3424 the 'sign_info' parameter in the Token Post response, see 3425 Section 3.3.1. 3427 If any of the currently registered COSE algorithms is considered, 3428 using this general format yields the same structure of 3429 'sign_info_entry' defined in this document, thus ensuring retro- 3430 compatibility. 3432 B.1. Format of 'sign_info_entry' 3434 The format of each 'sign_info_entry' (see Section 3.3.1) is 3435 generalized as follows. Given N the number of elements of the 3436 'sign_parameters' array, i.e., the number of COSE capabilities of the 3437 signature algorithm, then: 3439 * 'sign_key_parameters' is replaced by N elements 'sign_capab_i', 3440 each of which is a CBOR array. 3442 * The i-th array following 'sign_parameters', i.e., 'sign_capab_i' 3443 (i = 0, ..., N-1), is the array of COSE capabilities for the 3444 algorithm capability specified in 'sign_parameters'[i]. 3446 sign_info_entry = 3447 [ 3448 id : gname / [ + gname ], 3449 sign_alg : int / tstr, 3450 sign_parameters : [ alg_capab_1 : any, 3451 alg_capab_2 : any, 3452 ..., 3453 alg_capab_N : any], 3454 sign_capab_1 : [ any ], 3455 sign_capab_2 : [ any ], 3456 ..., 3457 sign_capab_N : [ any ], 3458 pub_key_enc = int / nil 3459 ] 3461 gname = tstr 3463 Figure 30: 'sign_info_entry' with general format 3465 Appendix C. Document Updates 3467 RFC EDITOR: PLEASE REMOVE THIS SECTION. 3469 C.1. Version -04 to -05 3471 * Updated uppercase/lowercase URI segments for KDC resources. 3473 * Supporting single Access Token for multiple groups/topics. 3475 * Added 'control_uri' parameter in the Joining Request. 3477 * Added 'peer_roles' parameter to support legal requesters/ 3478 responders. 3480 * Clarification on stopping using owned keying material. 3482 * Clarification on different reasons for processing failures, 3483 related policies, and requirement OPT4. 3485 * Added a KDC sub-resource for group members to upload a new public 3486 key. 3488 * Possible group rekeying following an individual Key Renewal 3489 Request. 3491 * Clarified meaning of requirement REQ3; added requirement OPT8. 3493 * Editorial improvements. 3495 C.2. Version -03 to -04 3497 * Revised RESTful interface, as to methods and parameters. 3499 * Extended processing of joining request, as to check/retrieval of 3500 public keys. 3502 * Revised and extended profile requirements. 3504 * Clarified specific usage of parameters related to signature 3505 algorithms/keys. 3507 * Included general content previously in draft-ietf-ace-key- 3508 groupcomm-oscore 3510 * Registration of media type and content format application/ace- 3511 group+cbor 3513 * Editorial improvements. 3515 C.3. Version -02 to -03 3517 * Exchange of information on the signature algorithm and related 3518 parameters, during the Token POST (Section 3.3). 3520 * Restructured KDC interface, with new possible operations 3521 (Section 4). 3523 * Client PoP signature for the Joining Request upon joining 3524 (Section 4.1.2.1). 3526 * Revised text on group member removal (Section 5). 3528 * Added more profile requirements (Appendix A). 3530 C.4. Version -01 to -02 3532 * Editorial fixes. 3534 * Distinction between transport profile and application profile 3535 (Section 1.1). 3537 * New parameters 'sign_info' and 'pub_key_enc' to negotiate 3538 parameter values for signature algorithm and signature keys 3539 (Section 3.3). 3541 * New parameter 'type' to distinguish different Key Distribution 3542 Request messages (Section 4.1). 3544 * New parameter 'client_cred_verify' in the Key Distribution Request 3545 to convey a Client signature (Section 4.1). 3547 * Encoding of 'pub_keys_repos' (Section 4.1). 3549 * Encoding of 'mgt_key_material' (Section 4.1). 3551 * Improved description on retrieval of new or updated keying 3552 material (Section 6). 3554 * Encoding of 'get_pub_keys' in Public Key Request (Section 7.1). 3556 * Extended security considerations (Sections 10.1 and 10.2). 3558 * New "ACE Public Key Encoding" IANA Registry (Section 11.2). 3560 * New "ACE Groupcomm Parameters" IANA Registry (Section 11.3), 3561 populated with the entries in Section 8. 3563 * New "Ace Groupcomm Request Type" IANA Registry (Section 11.4), 3564 populated with the values in Section 9. 3566 * New "ACE Groupcomm Policy" IANA Registry (Section 11.7) populated 3567 with two entries "Sequence Number Synchronization Method" and "Key 3568 Update Check Interval" (Section 4.2). 3570 * Improved list of requirements for application profiles 3571 (Appendix A). 3573 C.5. Version -00 to -01 3574 * Changed name of 'req_aud' to 'audience' in the Authorization 3575 Request (Section 3.1). 3577 * Defined error handling on the KDC (Sections 4.2 and 6.2). 3579 * Updated format of the Key Distribution Response as a whole 3580 (Section 4.2). 3582 * Generalized format of 'pub_keys' in the Key Distribution Response 3583 (Section 4.2). 3585 * Defined format for the message to request leaving the group 3586 (Section 5.2). 3588 * Renewal of individual keying material and methods for group 3589 rekeying initiated by the KDC (Section 6). 3591 * CBOR type for node identifiers in 'get_pub_keys' (Section 7.1). 3593 * Added section on parameter identifiers and their CBOR keys 3594 (Section 8). 3596 * Added request types for requests to a Join Response (Section 9). 3598 * Extended security considerations (Section 10). 3600 * New IANA registries "ACE Groupcomm Key Registry", "ACE Groupcomm 3601 Profile Registry", "ACE Groupcomm Policy Registry" and "Sequence 3602 Number Synchronization Method Registry" (Section 11). 3604 * Added appendix about requirements for application profiles of ACE 3605 on group communication (Appendix A). 3607 Acknowledgments 3609 The following individuals were helpful in shaping this document: 3610 Christian Amsuess, Carsten Bormann, Rikard Hoeglund, Ben Kaduk, John 3611 Mattsson, Daniel Migault, Jim Schaad, Ludwig Seitz, Goeran Selander 3612 and Peter van der Stok. 3614 The work on this document has been partly supported by VINNOVA and 3615 the Celtic-Next project CRITISEC; by the H2020 project SIFIS-Home 3616 (Grant agreement 952652); and by the EIT-Digital High Impact 3617 Initiative ACTIVE. 3619 Authors' Addresses 3620 Francesca Palombini 3621 Ericsson AB 3622 Torshamnsgatan 23 3623 SE-16440 Stockholm Kista 3624 Sweden 3626 Email: francesca.palombini@ericsson.com 3628 Marco Tiloca 3629 RISE AB 3630 Isafjordsgatan 22 3631 SE-16440 Stockholm Kista 3632 Sweden 3634 Email: marco.tiloca@ri.se