idnits 2.17.1 draft-ietf-ace-oscore-gm-admin-05.txt: -(3): Line appears to be too long, but this could be caused by non-ascii characters in UTF-8 encoding -(2599): Line appears to be too long, but this could be caused by non-ascii characters in UTF-8 encoding 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: ---------------------------------------------------------------------------- == There are 6 instances of lines with non-ascii characters in the document. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- == There are 8 instances of lines with non-RFC2606-compliant FQDNs in the document. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (7 March 2022) is 781 days in the past. Is this intentional? -- Found something which looks like a code comment -- if you have code sections in the document, please surround them with '' and '' lines. Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Missing Reference: 'Toid' is mentioned on line 415, but not defined == Missing Reference: 'Tperm' is mentioned on line 415, but not defined == Outdated reference: A later version (-07) exists of draft-ietf-ace-aif-06 == Outdated reference: A later version (-18) exists of draft-ietf-ace-key-groupcomm-15 == Outdated reference: A later version (-16) exists of draft-ietf-ace-key-groupcomm-oscore-13 == Outdated reference: A later version (-06) exists of draft-ietf-core-coral-04 == Outdated reference: A later version (-11) exists of draft-ietf-core-groupcomm-bis-06 == Outdated reference: A later version (-21) exists of draft-ietf-core-oscore-groupcomm-14 ** 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' == Outdated reference: A later version (-08) exists of draft-amsuess-core-cachable-oscore-04 == Outdated reference: A later version (-09) exists of draft-ietf-cose-cbor-encoded-cert-03 == Outdated reference: A later version (-15) exists of draft-tiloca-core-oscore-discovery-11 -- Obsolete informational reference (is this intentional?): RFC 6347 (Obsoleted by RFC 9147) Summary: 1 error (**), 0 flaws (~~), 14 warnings (==), 4 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 ACE Working Group M. Tiloca 3 Internet-Draft R. Höglund 4 Intended status: Standards Track RISE AB 5 Expires: 8 September 2022 P. van der Stok 6 Consultant 7 F. Palombini 8 Ericsson AB 9 7 March 2022 11 Admin Interface for the OSCORE Group Manager 12 draft-ietf-ace-oscore-gm-admin-05 14 Abstract 16 Group communication for CoAP can be secured using Group Object 17 Security for Constrained RESTful Environments (Group OSCORE). A 18 Group Manager is responsible to handle the joining of new group 19 members, as well as to manage and distribute the group keying 20 material. This document defines a RESTful admin interface at the 21 Group Manager, that allows an Administrator entity to create and 22 delete OSCORE groups, as well as to retrieve and update their 23 configuration. The ACE framework for Authentication and 24 Authorization is used to enforce authentication and authorization of 25 the Administrator at the Group Manager. Protocol-specific transport 26 profiles of ACE are used to achieve communication security, proof-of- 27 possession and server authentication. 29 Discussion Venues 31 This note is to be removed before publishing as an RFC. 33 Discussion of this document takes place on the Authentication and 34 Authorization for Constrained Environments Working Group mailing list 35 (ace@ietf.org), which is archived at 36 https://mailarchive.ietf.org/arch/browse/ace/. 38 Source for this draft and an issue tracker can be found at 39 https://github.com/ace-wg/ace-oscore-gm-admin. 41 Status of This Memo 43 This Internet-Draft is submitted in full conformance with the 44 provisions of BCP 78 and BCP 79. 46 Internet-Drafts are working documents of the Internet Engineering 47 Task Force (IETF). Note that other groups may also distribute 48 working documents as Internet-Drafts. The list of current Internet- 49 Drafts is at https://datatracker.ietf.org/drafts/current/. 51 Internet-Drafts are draft documents valid for a maximum of six months 52 and may be updated, replaced, or obsoleted by other documents at any 53 time. It is inappropriate to use Internet-Drafts as reference 54 material or to cite them other than as "work in progress." 56 This Internet-Draft will expire on 8 September 2022. 58 Copyright Notice 60 Copyright (c) 2022 IETF Trust and the persons identified as the 61 document authors. All rights reserved. 63 This document is subject to BCP 78 and the IETF Trust's Legal 64 Provisions Relating to IETF Documents (https://trustee.ietf.org/ 65 license-info) in effect on the date of publication of this document. 66 Please review these documents carefully, as they describe your rights 67 and restrictions with respect to this document. Code Components 68 extracted from this document must include Revised BSD License text as 69 described in Section 4.e of the Trust Legal Provisions and are 70 provided without warranty as described in the Revised BSD License. 72 Table of Contents 74 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 75 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 5 76 2. Group Administration . . . . . . . . . . . . . . . . . . . . 7 77 2.1. Managing OSCORE Groups . . . . . . . . . . . . . . . . . 7 78 2.2. Collection Representation . . . . . . . . . . . . . . . . 9 79 2.3. Discovery . . . . . . . . . . . . . . . . . . . . . . . . 9 80 3. Format of Scope . . . . . . . . . . . . . . . . . . . . . . . 9 81 4. Getting Access to the Group Manager . . . . . . . . . . . . . 13 82 5. Group Configurations . . . . . . . . . . . . . . . . . . . . 17 83 5.1. Group Configuration Representation . . . . . . . . . . . 17 84 5.1.1. Configuration Properties . . . . . . . . . . . . . . 17 85 5.1.2. Status Properties . . . . . . . . . . . . . . . . . . 19 86 5.2. Default Values . . . . . . . . . . . . . . . . . . . . . 21 87 5.2.1. Configuration Parameters . . . . . . . . . . . . . . 21 88 5.2.2. Status Parameters . . . . . . . . . . . . . . . . . . 21 89 6. Interactions with the Group Manager . . . . . . . . . . . . . 22 90 6.1. Retrieve the Full List of Group Configurations . . . . . 22 91 6.2. Retrieve a List of Group Configurations by Filters . . . 23 92 6.3. Create a New Group Configuration . . . . . . . . . . . . 25 93 6.4. Retrieve a Group Configuration . . . . . . . . . . . . . 31 94 6.5. Retrieve Part of a Group Configuration by Filters . . . . 33 95 6.6. Overwrite a Group Configuration . . . . . . . . . . . . . 36 96 6.6.1. Effects on Joining Nodes . . . . . . . . . . . . . . 39 97 6.6.2. Effects on the Group Members . . . . . . . . . . . . 40 98 6.7. Selective Update of a Group Configuration . . . . . . . . 42 99 6.7.1. Effects on Joining Nodes . . . . . . . . . . . . . . 46 100 6.7.2. Effects on the Group Members . . . . . . . . . . . . 47 101 6.8. Delete a Group Configuration . . . . . . . . . . . . . . 47 102 6.8.1. Effects on the Group Members . . . . . . . . . . . . 48 103 7. ACE Groupcomm Error Identifiers . . . . . . . . . . . . . . . 49 104 8. Security Considerations . . . . . . . . . . . . . . . . . . . 49 105 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 49 106 9.1. ACE Groupcomm Parameters . . . . . . . . . . . . . . . . 50 107 9.2. ACE Groupcomm Errors . . . . . . . . . . . . . . . . . . 51 108 9.3. Resource Types . . . . . . . . . . . . . . . . . . . . . 51 109 9.4. Group OSCORE Admin Permissions . . . . . . . . . . . . . 51 110 9.5. AIF . . . . . . . . . . . . . . . . . . . . . . . . . . . 52 111 9.6. CoAP Content-Format . . . . . . . . . . . . . . . . . . . 53 112 9.7. ACE Scope Semantics . . . . . . . . . . . . . . . . . . . 53 113 9.8. Expert Review Instructions . . . . . . . . . . . . . . . 54 114 10. References . . . . . . . . . . . . . . . . . . . . . . . . . 54 115 10.1. Normative References . . . . . . . . . . . . . . . . . . 54 116 10.2. Informative References . . . . . . . . . . . . . . . . . 57 117 Appendix A. Document Updates . . . . . . . . . . . . . . . . . . 59 118 A.1. Version -04 to -05 . . . . . . . . . . . . . . . . . . . 59 119 A.2. Version -03 to -04 . . . . . . . . . . . . . . . . . . . 60 120 A.3. Version -02 to -03 . . . . . . . . . . . . . . . . . . . 60 121 A.4. Version -01 to -02 . . . . . . . . . . . . . . . . . . . 60 122 A.5. Version -00 to -01 . . . . . . . . . . . . . . . . . . . 60 123 Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . 61 124 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 61 126 1. Introduction 128 The Constrained Application Protocol (CoAP) [RFC7252] can be used in 129 group communication environments where messages are also exchanged 130 over IP multicast [I-D.ietf-core-groupcomm-bis]. Applications 131 relying on CoAP can achieve end-to-end security at the application 132 layer by using Object Security for Constrained RESTful Environments 133 (OSCORE) [RFC8613], and especially Group OSCORE 134 [I-D.ietf-core-oscore-groupcomm] in group communication scenarios. 136 When group communication for CoAP is protected with Group OSCORE, 137 nodes are required to explicitly join the correct OSCORE group. To 138 this end, a joining node interacts with a Group Manager (GM) entity 139 responsible for that group, and retrieves the required keying 140 material to securely communicate with other group members using Group 141 OSCORE. 143 The method in [I-D.ietf-ace-key-groupcomm-oscore] specifies how nodes 144 can join an OSCORE group through the respective Group Manager. Such 145 a method builds on the ACE framework for Authentication and 146 Authorization [I-D.ietf-ace-oauth-authz], so ensuring a secure 147 joining process as well as authentication and authorization of 148 joining nodes (clients) at the Group Manager (resource server). 150 In some deployments, the application running on the Group Manager may 151 know when a new OSCORE group has to be created, as well as how it 152 should be configured and later on updated or deleted, e.g., based on 153 the current application state or on pre-installed policies. In this 154 case, the Group Manager application can create and configure OSCORE 155 groups when needed, by using a local application interface. However, 156 this requires the Group Manager to be application-specific, which in 157 turn leads to error prone deployments and is poorly flexible. 159 In other deployments, a separate Administrator entity, such as a 160 Commissioning Tool, is directly responsible for creating and 161 configuring the OSCORE groups at a Group Manager, as well as for 162 maintaining them during their whole lifetime until their deletion. 163 This allows the Group Manager to be agnostic of the specific 164 applications using secure group communication. 166 This document specifies a RESTful admin interface at the Group 167 Manager, intended for an Administrator as a separate entity external 168 to the Group Manager and its application. The interface allows the 169 Administrator to create and delete OSCORE groups, as well as to 170 configure and update their configuration. 172 Interaction examples are provided, in Link Format [RFC6690] and CBOR 173 [RFC8949], as well as in CoRAL [I-D.ietf-core-coral]. While all the 174 CoRAL examples show the CoRAL textual serialization format, its 175 binary serialization format is used on the wire. 177 [ NOTE: 179 The reported CoRAL examples are based on the textual representation 180 used until version -03 of [I-D.ietf-core-coral]. These will be 181 revised to use the CBOR diagnostic notation instead. 183 ] 184 The ACE framework is used to ensure authentication and authorization 185 of the Administrator (client) at the Group Manager (resource server). 186 In order to achieve communication security, proof-of-possession and 187 server authentication, the Administrator and the Group Manager 188 leverage protocol-specific transport profiles of ACE, such as 189 [I-D.ietf-ace-oscore-profile][I-D.ietf-ace-dtls-authorize]. These 190 include also possible forthcoming transport profiles that comply with 191 the requirements in Appendix C of [I-D.ietf-ace-oauth-authz]. 193 1.1. Terminology 195 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 196 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 197 "OPTIONAL" in this document are to be interpreted as described in BCP 198 14 [RFC2119] [RFC8174] when, and only when, they appear in all 199 capitals, as shown here. 201 Readers are expected to be familiar with the terms and concepts from 202 the following specifications: 204 * CBOR [RFC8949] and COSE 205 [I-D.ietf-cose-rfc8152bis-struct][I-D.ietf-cose-rfc8152bis-algs]. 207 * The CoAP protocol [RFC7252], also in group communication scenarios 208 [I-D.ietf-core-groupcomm-bis]. These include the concepts of: 210 - "application group", as a set of CoAP nodes that share a common 211 set of resources; and of 213 - "security group", as a set of CoAP nodes that share the same 214 security material, and use it to protect and verify exchanged 215 messages. 217 * The OSCORE [RFC8613] and Group OSCORE 218 [I-D.ietf-core-oscore-groupcomm] security protocols. These 219 especially include the concepts of: 221 - Group Manager, as the entity responsible for a set of OSCORE 222 groups where communications among members are secured using 223 Group OSCORE. An OSCORE group is used as security group for 224 one or many application groups. 226 - Authentication credential, as the set of information associated 227 with an entity, including that entity's public key and 228 parameters associated with the public key. Examples of 229 authentication credentials are CBOR Web Tokens (CWTs) and CWT 230 Claims Sets (CCSs) [RFC8392], X.509 certificates [RFC7925] and 231 C509 certificates [I-D.ietf-cose-cbor-encoded-cert]. 233 * The ACE framework for authentication and authorization 234 [I-D.ietf-ace-oauth-authz]. The terminology for entities in the 235 considered architecture is defined in OAuth 2.0 [RFC6749]. In 236 particular, this includes Client (C), Resource Server (RS), and 237 Authorization Server (AS). 239 * The management of keying material for groups in ACE 240 [I-D.ietf-ace-key-groupcomm] and specifically for OSCORE groups 241 [I-D.ietf-ace-key-groupcomm-oscore]. These include the concept of 242 group-membership resource hosted by the Group Manager, that new 243 members access to join the OSCORE group, while current members can 244 access to retrieve updated keying material. 246 Note that, unless otherwise indicated, the term "endpoint" is used 247 here following its OAuth definition, aimed at denoting resources such 248 as /token and /introspect at the AS, and /authz-info at the RS. This 249 document does not use the CoAP definition of "endpoint", which is "An 250 entity participating in the CoAP protocol". 252 This document also refers to the following terminology. 254 * Administrator: entity responsible to create, configure and delete 255 OSCORE groups at a Group Manager. 257 * Group name: stable and invariant name of an OSCORE group. The 258 group name MUST be unique under the same Group Manager, and MUST 259 include only characters that are valid for a URI path segment. 261 * Group-collection resource: a single-instance resource hosted by 262 the Group Manager. An Administrator accesses a group-collection 263 resource to retrieve the list of existing OSCORE groups, or to 264 create a new OSCORE group, under that Group Manager. 266 As an example, this document uses /manage as the url-path of the 267 group-collection resource; implementations are not required to use 268 this name, and can define their own instead. 270 * Group-configuration resource: a resource hosted by the Group 271 Manager, associated with an OSCORE group under that Group Manager. 272 A group-configuration resource is identifiable with the invariant 273 group name of the respective OSCORE group. An Administrator 274 accesses a group-configuration resource to retrieve or change the 275 configuration of the respective OSCORE group, or to delete that 276 group. 278 The url-path to a group-configuration resource has GROUPNAME as 279 last segment, with GROUPNAME the invariant group name assigned 280 upon its creation. Building on the considered url-path of the 281 group-collection resource, this document uses /manage/GROUPNAME as 282 the url-path of a group-configuration resource; implementations 283 are not required to use this name, and can define their own 284 instead. 286 * Admin endpoint: an endpoint at the Group Manager associated with 287 the group-collection resource or to a group-configuration resource 288 hosted by that Group Manager. 290 2. Group Administration 292 With reference to the ACE framework and the terminology defined in 293 OAuth 2.0 [RFC6749]: 295 * The Group Manager acts as Resource Server (RS). It provides one 296 single group-collection resource, and one group-configuration 297 resource per existing OSCORE group. Each of those is exported by 298 a distinct admin endpoint. 300 * The Administrator acts as Client (C), and requests to access the 301 group-collection resource and group-configuration resources, by 302 accessing the respective admin endpoint at the Group Manager. 304 * The Authorization Server (AS) authorizes the Administrator to 305 access the group-collection resource and group-configuration 306 resources at a Group Manager. Multiple Group Managers can be 307 associated with the same AS. 309 The authorized access for an Administrator can be limited to 310 performing only a subset of operations, according to what is 311 allowed by the authorization information in the Access Token 312 issued to that Administrator (see Section 3 and Section 4). The 313 AS can authorize multiple Administrators to access the group- 314 collection resource and the (same) group-configuration resources 315 at the Group Manager. 317 The AS MAY release Access Tokens to the Administrator for other 318 purposes than accessing admin endpoints of registered Group 319 Managers. 321 2.1. Managing OSCORE Groups 323 Figure 1 shows the resources of a Group Manager available to an 324 Administrator. 326 ___ 327 Group / \ 328 Collection \___/ 329 \ 330 \____________________ 331 \___ \___ \___ 332 / \ / \ ... / \ Group 333 \___/ \___/ \___/ Configurations 335 Figure 1: Resources of a Group Manager 337 The Group Manager exports a single group-collection resource, with 338 resource type "core.osc.gcoll" defined in Section 9.3 of this 339 document. The interface for the group-collection resource defined in 340 Section 6 allows the Administrator to: 342 * Retrieve the list of existing OSCORE groups. 344 * Retrieve the list of existing OSCORE groups matching with 345 specified filter criteria. 347 * Create a new OSCORE group, specifying its invariant group name 348 and, optionally, its configuration. 350 The Group Manager exports one group-configuration resource for each 351 of its OSCORE groups. Each group-configuration resource has resource 352 type "core.osc.gconf" defined in Section 9.3 of this document, and is 353 identified by the group name specified upon creating the OSCORE 354 group. The interface for a group-configuration resource defined in 355 Section 6 allows the Administrator to: 357 * Retrieve the complete current configuration of the OSCORE group. 359 * Retrieve part of the current configuration of the OSCORE group, by 360 applying filter criteria. 362 * Overwrite the current configuration of the OSCORE group. 364 * Selectively update only part of the current configuration of the 365 OSCORE group. 367 * Delete the OSCORE group. 369 2.2. Collection Representation 371 A list of group configurations is represented as a document 372 containing the corresponding group-configuration resources in the 373 list. Each group-configuration is represented as a link, where the 374 link target is the URI of the group-configuration resource. 376 The list can be represented as a Link Format document [RFC6690] or a 377 CoRAL document [I-D.ietf-core-coral]. 379 In the former case, the link to each group-configuration resource 380 specifies the link target attribute 'rt' (Resource Type), with value 381 "core.osc.gconf" defined in Section 9.3 of this document. 383 In the latter case, the CoRAL document specifies the group- 384 configuration resources in the list as top-level elements. In 385 particular, the link to each group-configuration resource has 386 http://coreapps.org/core.osc.gcoll#item as relation type. 388 2.3. Discovery 390 The Administrator can discover the group-collection resource from a 391 Resource Directory, for instance [I-D.ietf-core-resource-directory] 392 and [I-D.hartke-t2trg-coral-reef], or from .well-known/core, by using 393 the resource type "core.osc.gcoll" defined in Section 9.3 of this 394 document. 396 The Administrator can discover group-configuration resources for the 397 group-collection resource as specified in Section 6.1 and 398 Section 6.2. 400 3. Format of Scope 402 This section defines the exact format and encoding of scope to use, 403 in order to express authorization information for the Administrator 404 (see Section 4). 406 To this end, this document uses the Authorization Information Format 407 (AIF) [I-D.ietf-ace-aif], and defines the following AIF specific data 408 model AIF-OSCORE-GROUPCOMM-ADMIN. 410 With reference to the generic AIF model 412 AIF-Generic = [* [Toid, Tperm]] 414 the value of the CBOR byte string used as scope encodes the CBOR 415 array [* [Toid, Tperm]], where each [Toid, Tperm] element corresponds 416 to one scope entry. 418 Then, for each scope entry, the following applies. 420 * The object identifier ("Toid") is specialized as a CBOR text 421 string, specifying a wildcard pattern P for the scope entry. The 422 pattern P is intended as a template for group names. 424 * The permission set ("Tperm") is specialized as a CBOR unsigned 425 integer with value Q. This specifies the permissions that the 426 Administrator has to perform operations on the admin endpoints at 427 the Group Manager, as pertaining to any OSCORE group whose name 428 matches with the wildcard pattern P. The value Q is computed as 429 follows. 431 - Each permission in the permission set is converted into the 432 corresponding numeric identifier X from the "Value" column of 433 the "Group OSCORE Admin Permissions" registry, for which this 434 document defines the entries in Figure 2. 436 - The set of N numbers is converted into the single value Q, by 437 taking each numeric identifier X_1, X_2, ..., X_N to the power 438 of two, and then computing the inclusive OR of the binary 439 representations of all the power values. 441 In general, a single permission can be associated with multiple 442 different operations that are possible to be performed when 443 interacting with the Group Manager. For example, the "List" 444 permission allows the Administrator to retrieve a list of group 445 configurations (see Section 6.1) or only a subset of that 446 according to specified filter criteria (see Section 6.2), by 447 issuing a GET or FETCH request to the group-collection resource, 448 respectively. 450 +--------+-------+----------------------------------------+ 451 | Name | Value | Description | 452 +========+=======+========================================+ 453 | List | 0 | Retrieve list of group configurations | 454 +--------+-------+----------------------------------------+ 455 | Create | 1 | Create new group configurations | 456 +--------+-------+----------------------------------------+ 457 | Read | 2 | Retrieve group configurations | 458 +--------+-------+----------------------------------------+ 459 | Write | 3 | Change group configurations | 460 +--------+-------+----------------------------------------+ 461 | Delete | 4 | Delete group configurations | 462 +--------+-------+----------------------------------------+ 464 Figure 2: Numeric identifier of permissions on the admin 465 endpoints at a Group Manager 467 The CDDL [RFC8610] definition of the AIF-OSCORE-GROUPCOMM-ADMIN data 468 model and the format of scope using such a data model is as follows: 470 AIF-OSCORE-GROUPCOMM-ADMIN = AIF-Generic 472 pattern = tstr ; wilcard pattern of group names 473 permission_set = uint . bits permissions 474 permissions = &( 475 List: 0, 476 Create: 1, 477 Read: 2, 478 Write: 3, 479 Delete: 4 480 ) 482 scope_entry = AIF-OSCORE-GROUPCOMM-ADMIN 484 scope = << [ + scope_entry ] >> 486 By relying on the scope format defined above and given an OSCORE 487 group G1 created by a "main" Administrator, then a second "assistant" 488 Administrator can be effectively authorized to perform some 489 operations on G1, in spite of not being the group creator. 491 Furthermore, having the object identifier ("Toid") specialized as a 492 wildcard pattern displays a number of advantages. 494 * The encoded scope can be compact in size, while allowing the 495 Administrator to operate on large pools of group names. 497 * The Administrator and the AS do not need to know exact group names 498 when requesting and issuing an Access Token, respectively (see 499 Section 4). In turn, the Group Manager can effectively take the 500 final decision about the name to assign to an OSCORE group, upon 501 its creation (see Section 6.3). 503 * The Administrator may have established a secure communication 504 association with the Group Manager based on a first Access Token 505 T1, and then created an OSCORE group G. Following the 506 invalidation of T1 (e.g., due to expiration) and the establishment 507 of a new secure communication association with the Group Manager 508 based on a new Access Token T2, the Administrator can seamlessly 509 perform authorized operations on the previously created group G. 511 When using the scope format defined in this section, the permission 512 set ("Tperm") of each scope entry MUST include the "List" permission 513 in order for the scope to be considered valid. That is, for each 514 scope entry, the unsigned integer Q MUST be odd. Therefore, an 515 Administrator is always allowed to retrieve a list of existing group 516 configurations. The exact elements included in the returned list are 517 determined by the Group Manager, based on the group name patterns 518 specified in the scope entries of the Administrator's Access Token, 519 as well as on possible filter criteria specified in the request from 520 the Administrator. 522 [ NOTE: 524 There is a potential follow-up building on this. 526 An ACE Client might want to interact with the same Group Manager to 527 be both Administrator for some groups and member for some other 528 groups. 530 In order to keep a single Access Token per Client, the scope would 531 have to generally include some "admin" scope entries as per the AIF 532 data model defined in this document, together with some "user" scope 533 entries as per the AIF data model defined in 534 [I-D.ietf-ace-key-groupcomm-oscore]. 536 In the scope entries of the former type, the least significant bit of 537 the Tperm integer and denoting the "List" admin permission is always 538 set to 1 (see above). In the scope entries of the latter type, the 539 least significant bit of the Tperm integer is reserved and always 0 540 (see [I-D.ietf-ace-key-groupcomm-oscore]). 542 Therefore, "admin" and "user" scope entries can unambiguously coexist 543 in the same 'scope' claim and Authorization Request/Response 544 parameter, and can be easily distinguished by checking the least 545 significant bit of the Tperm integer. 547 In turn, this would require to accordingly revise the scope format 548 and the ACE scope semantics integer defined in this document, in 549 order to denote the certain presence of "admin" scope entries and the 550 optional additional presence of "user" scope entries, within a same 551 scope claim/parameter. 553 ] 555 Future specifications that define new permissions on the admin 556 endpoints at the Group Manager MUST register a corresponding numeric 557 identifier in the "Group OSCORE Admin Permissions" registry defined 558 in Section 9.4 of this document. 560 4. Getting Access to the Group Manager 562 All communications between the involved entities rely on the CoAP 563 protocol and MUST be secured. 565 In particular, communications between the Administrator and the Group 566 Manager leverage protocol-specific transport profiles of ACE to 567 achieve communication security, proof-of-possession and server 568 authentication. To this end, the AS may explicitly signal the 569 specific transport profile to use, consistently with requirements and 570 assumptions defined in the ACE framework [I-D.ietf-ace-oauth-authz]. 572 With reference to the AS, communications between the Administrator 573 and the AS (/token endpoint) as well as between the Group Manager and 574 the AS (/introspect endpoint) can be secured by different means, for 575 instance using DTLS [RFC6347][I-D.ietf-tls-dtls13] or OSCORE 576 [RFC8613]. Further details on how the AS secures communications 577 (with the Administrator and the Group Manager) depend on the 578 specifically used transport profile of ACE, and are out of the scope 579 of this document. 581 The format and encoding of scope defined in Section 3 of this 582 document MUST be used, for both the 'scope' claim in the Access 583 Token, as well as for the 'scope' parameter in the Authorization 584 Request and Authorization Response exchanged with the AS (see 585 Sections 5.8.1 and 5.8.2 of [I-D.ietf-ace-oauth-authz]). 587 Furthermore, the AS MAY use the extended format of scope defined in 588 Section 7 of [I-D.ietf-ace-key-groupcomm] for the 'scope' claim of 589 the Access Token. In such a case, the first element of the CBOR 590 sequence [RFC8742] MUST be the CBOR integer with value SEM_ID_TBD, 591 defined in Section 9.7 of this document. This indicates that the 592 second element of the CBOR sequence, as conveying the actual access 593 control information, follows the scope semantics defined in Section 3 594 of this document. 596 In order to get access to the Group Manager for managing OSCORE 597 groups, an Administrator performs the following steps. 599 1. The Administrator requests an Access Token from the AS, in order 600 to access the group-collection and group-configuration resources 601 on the Group Manager. To this end, it sends to the AS an 602 Authorization Request as defined in Section 5.8.1 of 603 [I-D.ietf-ace-oauth-authz]. The Administrator will start or 604 continue using secure communications with the Group Manager, 605 according to the response from the AS. 607 2. The AS processes the Authorization Request as defined in 608 Section 5.8.2 of [I-D.ietf-ace-oauth-authz], especially verifying 609 that the Administrator is authorized to obtain the requested 610 permissions, or possibly a subset of those. 612 With reference to the scope format specified in Section 3, the AS 613 builds the value of the 'scope' claim to include in the Access 614 Token as follows. 616 1. The AS initializes three empty sets of scope entries, namely 617 S1, S2 and S3. 619 2. For each scope entry E in the 'scope' parameter of the 620 Authorization Request, the AS performs the following actions. 622 * In its access policies related to administrative 623 operations at the Group Manager for the Administrator, the 624 AS determines every group name superpattern P*, such that 625 every group name matching with the wildcard pattern P of 626 the scope entry E matches also with P*. 628 * If no superpatterns are found, the AS proceeds with the 629 next scope entry, if any. Otherwise, the AS computes 630 Tperm* as the union of the permission sets associated with 631 the superpatterns found at the previous step. That is, 632 Tperm* is the inclusive OR of the binary representations 633 of the Tperm values associated with the found 634 superpatterns and encoding the corresponding permission 635 sets as per Section 3. 637 * The AS adds to the set S1 a scope entry, such that its 638 Toid is the same as in the scope entry E, while its Tperm 639 is the AND of Tperm* with the Tperm in the scope entry E. 641 3. For each scope entry E in the 'scope' parameter of the 642 Authorization Request, the AS performs the following actions. 644 * In its access policies related to administrative 645 operations at the Group Manager for the Administrator, the 646 AS determines every group name subpattern P*, such that: 647 i) the wildcard pattern P of the scope entry E is 648 different from P*; and ii) every group name matching with 649 P* also matches with P. 651 * If no subpatterns are found, the AS proceeds with the next 652 scope entry, if any. Otherwise, for each found subpattern 653 P*, the AS adds to the set S2 a scope entry, such that its 654 Toid is the same as in the subpattern P*, while its Tperm 655 is the AND of the Tperm from the subpattern P* with the 656 Tperm in the scope entry E. 658 4. For each scope entry E in the 'scope' parameter of the 659 Authorization Request, the AS performs the following actions. 661 * For each group name pattern P* in its access policies 662 related to administrative operations at the Group Manager 663 for the Administrator, the AS performs the following 664 actions. 666 - The AS attempts to determine a crosspattern P** such 667 that: i) in the previous step, P** was not identified 668 as a superpattern or subpattern for the pattern P of 669 the scope entry E; ii) every group name matching with 670 P** also matches with both P and P*. 672 - If no crosspattern is built, the AS proceeds with the 673 next pattern in its access policies related to 674 administrative operations at the Group Manager for the 675 Administrator, if any. Otherwise, the AS adds to the 676 set S3 a scope entry, such that its Toid is the same as 677 in the crosspattern P**, while its Tperm is the AND of 678 the Tperm from the pattern P* and the Tperm in the 679 scope entry E. 681 5. If the sets S1, S2 and S3 are all empty, the Authorization 682 Request has not been successfully verified, and the AS 683 returns an error response as per Section 5.8.3 of 684 [I-D.ietf-ace-oauth-authz]. Otherwise, the AS uses the scope 685 entries in the sets S1, S2 and S3 as the scope entries for 686 the 'scope' claim to include in the Access Token, as per the 687 format defined in Section 3. 689 The AS MUST include the 'scope' parameter in the Authorization 690 Response defined in Section 5.8.2 of [I-D.ietf-ace-oauth-authz], 691 when the value included in the Access Token differs from the one 692 specified by the Administrator in the Authorization Response. In 693 such a case, the second element of each scope entry specifies a 694 set of permissions that the Administrator actually has to perform 695 operations at the Group Manager, encoded as specified in 696 Section 3. 698 3. The Administrator transfers authentication and authorization 699 information to the Group Manager by posting the obtained Access 700 Token, according to the used profile of ACE, such as 701 [I-D.ietf-ace-dtls-authorize] and [I-D.ietf-ace-oscore-profile]. 702 After that, the Administrator must have a secure communication 703 association established with the Group Manager, before performing 704 any administrative operation on that Group Manager. Possible 705 ways to provide secure communication are DTLS 706 [RFC6347][I-D.ietf-tls-dtls13] and OSCORE [RFC8613]. The 707 Administrator and the Group Manager maintain the secure 708 association, to support possible future communications. 710 4. Consistently with what is allowed by the authorization 711 information in the Access Token, the Administrator performs 712 administrative operations at the Group Manager, as described in 713 Section 6. These include retrieving a list of existing OSCORE 714 groups, creating new OSCORE groups, retrieving and changing 715 OSCORE group configurations, and removing OSCORE groups. 716 Messages exchanged among the Administrator and the Group Manager 717 are specified in Section 6. 719 Upon receiving a request from the Administrator targeting the 720 group-configuration resource or a group-collection resource, the 721 Group Manager MUST check that it is storing a valid Access Token 722 for that Administrator. If this is not the case, the Group 723 Manager MUST reply with a 4.01 (Unauthorized) error response. 725 If the request targets the group-configuration resource 726 associated to a group with name GROUPNAME, the Group Manager MUST 727 check that it is storing a valid Access Token from that 728 Administrator, such that the 'scope' claim specified in the 729 Access Token has the format defined in Section 3 and includes a 730 scope entry where: 732 * The group name GROUPNAME matches with the wildcard pattern 733 specified in the scope entry; and 735 * The permission set specified in the scope entry allows the 736 Administrator to perform the requested operation on the 737 targeted group-configuration resource. 739 Further details are defined separately for each operation 740 specified in Section 6. 742 In case the Group Manager stores a valid Access Token but the 743 verifications above fail, the Group Manager MUST reply with a 744 4.03 (Forbidden) error response. This response MAY be an AS 745 Request Creation Hints, as defined in Section 5.3 of 746 [I-D.ietf-ace-oauth-authz], in which case the Content-Format MUST 747 be set to application/ace+cbor. 749 If the request is not formatted correctly (e.g., required fields 750 are not present or are not encoded as expected), the Group 751 Manager MUST reply with a 4.00 (Bad Request) error response. 753 5. Group Configurations 755 A group configuration consists of a set of parameters. 757 5.1. Group Configuration Representation 759 The group configuration representation is a CBOR map which MUST 760 include configuration properties and status properties. 762 5.1.1. Configuration Properties 764 The CBOR map MUST include the following configuration parameters, 765 whose CBOR abbreviations are defined in Section 9.1 of this document. 767 * 'hkdf', which specifies the HKDF Algorithm used in the OSCORE 768 group, encoded as a CBOR text string or a CBOR integer. Possible 769 values are the same ones admitted for the 'hkdf' parameter of the 770 Group_OSCORE_Input_Material object, defined in Section 6.4 of 771 [I-D.ietf-ace-key-groupcomm-oscore]. 773 * 'cred_fmt', which specifies the format of authentication 774 credentials used in the OSCORE group, encoded as a CBOR integer. 775 Possible values are the same ones admitted for the 'cred_fmt' 776 parameter of the Group_OSCORE_Input_Material object, defined in 777 Section 6.4 of [I-D.ietf-ace-key-groupcomm-oscore]. 779 * 'group_mode', encoded as a CBOR simple value. Its value is "true" 780 (0xf5) if the OSCORE group uses the group mode of Group OSCORE 781 [I-D.ietf-core-oscore-groupcomm], or "false" (0xf4) otherwise. 783 * 'sign_enc_alg', which is formatted as follows. If the 784 configuration parameter 'group_mode' has value "false" (0xf4), 785 this parameter has as value the CBOR simple value "null" (0xf6). 786 Otherwise, this parameter specifies the Signature Encryption 787 Algorithm used in the OSCORE group to encrypt messages protected 788 with the group mode, encoded as a CBOR text string or a CBOR 789 integer. Possible values are the same ones admitted for the 790 'sign_enc_alg' parameter of the Group_OSCORE_Input_Material 791 object, defined in Section 6.4 of 792 [I-D.ietf-ace-key-groupcomm-oscore]. 794 * 'sign_alg', which is formatted as follows. If the configuration 795 parameter 'group_mode' has value "false" (0xf4), this parameter 796 has as value the CBOR simple value "null" (0xf6). Otherwise, this 797 parameter specifies the Signature Algorithm used in the OSCORE 798 group, encoded as a CBOR text string or a CBOR integer. Possible 799 values are the same ones admitted for the 'sign_alg' parameter of 800 the Group_OSCORE_Input_Material object, defined in Section 6.4 of 801 [I-D.ietf-ace-key-groupcomm-oscore]. 803 * 'sign_params', which is formatted as follows. If the 804 configuration parameter 'group_mode' has value "false" (0xf4), 805 this parameter has as value the CBOR simple value "null" (0xf6). 806 Otherwise, this parameter specifies the additional parameters for 807 the Signature Algorithm used in the OSCORE group, encoded as a 808 CBOR array. Possible formats and values are the same ones 809 admitted for the 'sign_params' parameter of the 810 Group_OSCORE_Input_Material object, defined in Section 6.4 of 811 [I-D.ietf-ace-key-groupcomm-oscore]. 813 * 'pairwise_mode', encoded as a CBOR simple value. Its value is 814 "true" (0xf5) if the OSCORE group uses the pairwise mode of Group 815 OSCORE [I-D.ietf-core-oscore-groupcomm], or "false" (0xf4) 816 otherwise. 818 * 'alg', which is formatted as follows. If the configuration 819 parameter 'pairwise_mode' has value "false" (0xf4), this parameter 820 has as value the CBOR simple value "null" (0xf6). Otherwise, this 821 parameter specifies the AEAD Algorithm used in the OSCORE group to 822 encrypt messages protected with the pairwise mode, encoded as a 823 CBOR text string or a CBOR integer. Possible values are the same 824 ones admitted for the 'alg' parameter of the 825 Group_OSCORE_Input_Material object, defined in Section 6.4 of 826 [I-D.ietf-ace-key-groupcomm-oscore]. 828 * 'ecdh_alg', which is formatted as follows. If the configuration 829 parameter 'pairwise_mode' has value "false" (0xf4), this parameter 830 has as value the CBOR simple value "null" (0xf6). Otherwise, this 831 parameter specifies the Pairwise Key Agreement Algorithm used in 832 the OSCORE group, encoded as a CBOR text string or a CBOR integer. 833 Possible values are the same ones admitted for the 'ecdh_alg' 834 parameter of the Group_OSCORE_Input_Material object, defined in 835 Section 6.4 of [I-D.ietf-ace-key-groupcomm-oscore]. 837 * 'ecdh_params', which is formatted as follows. If the 838 configuration parameter 'pairwise_mode' has value "false" (0xf4), 839 this parameter has as value the CBOR simple value "null" (0xf6). 840 Otherwise, this parameter specifies the parameters for the 841 Pairwise Key Agreement Algorithm used in the OSCORE group, encoded 842 as a CBOR array. Possible formats and values are the same ones 843 admitted for the 'ecdh_params' parameter of the 844 Group_OSCORE_Input_Material object, defined in Section 6.4 of 845 [I-D.ietf-ace-key-groupcomm-oscore]. 847 The CBOR map MAY include the following configuration parameters, 848 whose CBOR abbreviations are defined in Section 9.1 of this document. 850 * 'det_req', encoded as a CBOR simple value. Its value is "true" 851 (0xf5) if the OSCORE group uses deterministic requests as defined 852 in [I-D.amsuess-core-cachable-oscore], or "false" (0xf4) 853 otherwise. This parameter MUST NOT be present if the 854 configuration parameter 'group_mode' has value "false" (0xf4). 856 * 'det_hash_alg', encoded as a CBOR integer or text string. If 857 present, this parameter specifies the Hash Algorithm used in the 858 OSCORE group when producing deterministic requests, as defined in 859 [I-D.amsuess-core-cachable-oscore]. This parameter takes values 860 from the "Value" column of the "COSE Algorithms" Registry 861 [COSE.Algorithms]. 863 This parameter MUST NOT be present if the configuration parameter 864 'det_req' is not present or if it is present with value "false" 865 (0xf4). If the configuration parameter 'det_req' is present with 866 value "true" (0xf5) and 'det_hash_alg' is not present, the choice 867 of the Hash Algorithm to use when producing deterministic requests 868 is left to the Group Manager. 870 5.1.2. Status Properties 872 The CBOR map MUST include the following status parameters: 874 * 'rt', with value the resource type "core.osc.gconf" associated 875 with group-configuration resources, encoded as a CBOR text string. 877 * 'active', encoding the CBOR simple value "true" (0xf5) if the 878 OSCORE group is currently active, or the CBOR simple value "false" 879 (0xf4) otherwise. This parameter is defined in Section 9.1 of 880 this document. 882 * 'group_name', with value the group name of the OSCORE group 883 encoded as a CBOR text string. This parameter is defined in 884 Section 9.1 of this document. 886 * 'group_title', with value either a human-readable description of 887 the OSCORE group encoded as a CBOR text string, or the CBOR simple 888 value "null" (0xf6) if no description is specified. This 889 parameter is defined in Section 9.1 of this document. 891 * 'ace-groupcomm-profile', defined in Section 4.3.1 of 892 [I-D.ietf-ace-key-groupcomm], with value "coap_group_oscore_app" 893 defined in Section 25.5 of [I-D.ietf-ace-key-groupcomm-oscore] 894 encoded as a CBOR integer. 896 * 'exp', defined in Section 4.3.1 of [I-D.ietf-ace-key-groupcomm]. 898 * 'app_groups', with value a list of names of application groups, 899 encoded as a CBOR array. Each element of the array is a CBOR text 900 string, specifying the name of an application group using the 901 OSCORE group as security group (see Section 2.1 of 902 [I-D.ietf-core-groupcomm-bis]). 904 * 'joining_uri', with value the URI of the group-membership resource 905 for joining the newly created OSCORE group as per Section 6.2 of 906 [I-D.ietf-ace-key-groupcomm-oscore], encoded as a CBOR text 907 string. This parameter is defined in Section 9.1 of this 908 document. 910 The CBOR map MAY include the following status parameters: 912 * 'group_policies', defined in Section 4.3.1 of 913 [I-D.ietf-ace-key-groupcomm], and consistent with the format and 914 content defined in Section 6.4 of 915 [I-D.ietf-ace-key-groupcomm-oscore]. 917 * 'max_stale_sets', defined in Section 9.1 of this document and 918 encoded as a CBOR unsigned integer, with value strictly greater 919 than 1. With reference to Section 2.2.1 of 920 [I-D.ietf-ace-key-groupcomm-oscore], this parameter specifies N, 921 i.e., the maximum number of sets of stale OSCORE Sender IDs that 922 the Group Manager stores in the collection associated with the 923 group. 925 * 'as_uri', defined in Section 9.1 of this document, specifies the 926 URI of the Authorization Server associated with the Group Manager 927 for the OSCORE group, encoded as a CBOR text string. Candidate 928 group members will have to obtain an Access Token from that 929 Authorization Server, before starting the joining process with the 930 Group Manager to join the OSCORE group (see Sections 4 and 6 of 931 [I-D.ietf-ace-key-groupcomm-oscore]). 933 5.2. Default Values 935 This section defines the default values that the Group Manager 936 assumes for configuration and status parameters. 938 5.2.1. Configuration Parameters 940 For each configuration parameter, the Group Manager MUST use a pre- 941 configured default value, if none is specified by the Administrator. 942 In particular: 944 * For 'group_mode', the Group Manager SHOULD use the CBOR simple 945 value "true" (0xf5). 947 * If 'group_mode' has value "true" (0xf5), the Group Manager SHOULD 948 use the same default values defined in Section 23.2 of 949 [I-D.ietf-ace-key-groupcomm-oscore] for the parameters 950 'sign_enc_alg', 'sign_alg' and 'sign_params'. 952 * If 'group_mode' has value "true" (0xf5), the Group Manager SHOULD 953 use the CBOR simple value "false" (0xf4) for the parameter 954 'det_req'. 956 * If 'det_req' has value "true" (0xf5), the Group Manager SHOULD use 957 SHA-256 (COSE algorithm encoding: -16) as default value for the 958 parameter 'det_hash_alg'. 960 * For 'pairwise_mode', the Group Manager SHOULD use the CBOR simple 961 value "false" (0xf4). 963 * If 'pairwise_mode' has value "true" (0xf5), the Group Manager 964 SHOULD use the same default values defined in Section 23.3 of 965 [I-D.ietf-ace-key-groupcomm-oscore] for the parameters 'alg', 966 'ecdh_alg' and 'ecdh_params'. 968 * For any other configuration parameter, the Group Manager SHOULD 969 use the same default values defined in Section 23.1 of 970 [I-D.ietf-ace-key-groupcomm-oscore]. 972 5.2.2. Status Parameters 974 For the following status parameters, the Group Manager MUST use a 975 pre-configured default value, if none is specified by the 976 Administrator. In particular: 978 * For 'active', the Group Manager SHOULD use the CBOR simple value 979 "false" (0xf4). 981 * For 'group_title', the Group Manager SHOULD use the CBOR simple 982 value "null" (0xf6). 984 * For 'app_groups', the Group Manager SHOULD use the empty CBOR 985 array. 987 * For 'group_policies', the Group Manager SHOULD use the default 988 values defined in Section 6.4 of 989 [I-D.ietf-ace-key-groupcomm-oscore]. 991 6. Interactions with the Group Manager 993 This section describes the operations available on the group- 994 collection resource and the group-configuration resources. 996 When custom CBOR is used, the Content-Format in messages containing a 997 payload is set to application/ace-groupcomm+cbor, defined in 998 Section 11.2 of [I-D.ietf-ace-key-groupcomm]. Furthermore, the entry 999 labels defined in Section 9.1 of this document MUST be used, when 1000 specifying the corresponding configuration and status parameters. 1002 6.1. Retrieve the Full List of Group Configurations 1004 The Administrator can send a GET request to the group-collection 1005 resource, in order to retrieve a list of the existing OSCORE groups 1006 at the Group Manager. This is returned as a list of links to the 1007 corresponding group-configuration resources. 1009 The Group Manager MUST prepare the list L to include in the response 1010 as follows. For each group-configuration resource R: 1012 1. The Group Manager considers the group name GROUPNAME of the 1013 OSCORE group associated to R. 1015 2. The Group Manager retrieves the stored Access Token for the 1016 Administrator. Then, it checks whether GROUPNAME matches with 1017 the group name pattern specified in any scope entry of the 1018 'scope' claim in the Access Token. 1020 3. The link to the group-configuration resource R is added to the 1021 list L only in case of a positive match. 1023 Example in Link Format: 1025 => 0.01 GET 1026 Uri-Path: manage 1028 <= 2.05 Content 1029 Content-Format: 40 (application/link-format) 1031 ;rt="core.osc.gconf", 1032 ;rt="core.osc.gconf", 1033 ;rt="core.osc.gconf" 1035 Example in CoRAL: 1037 => 0.01 GET 1038 Uri-Path: manage 1040 <= 2.05 Content 1041 Content-Format: TBD1 (application/coral+cbor) 1043 #using 1044 #base 1045 item 1046 item 1047 item 1049 6.2. Retrieve a List of Group Configurations by Filters 1051 The Administrator can send a FETCH request to the group-collection 1052 resource, in order to retrieve a list of the existing OSCORE groups 1053 that fully match a set of specified filter criteria. This is 1054 returned as a list of links to the corresponding group-configuration 1055 resources. 1057 When custom CBOR is used, the set of filter criteria is specified in 1058 the request payload as a CBOR map, whose possible entries are 1059 specified in Section 5.1 and use the same abbreviations defined in 1060 Section 9.1. Entry values are the ones admitted for the 1061 corresponding labels in the POST request for creating a group 1062 configuration (see Section 6.3). A valid request MUST NOT include 1063 the same entry multiple times. 1065 When CoRAL is used, the filter criteria are specified in the request 1066 payload with top-level elements, each of which corresponds to an 1067 entry specified in Section 5.1, with the exception of the 1068 'app_groups' status parameter. If names of application groups are 1069 used as filter criteria, each element of the 'app_groups' array from 1070 the status properties is included as a separate element with name 1071 'app_group'. With the exception of the 'app_group' element, a valid 1072 request MUST NOT include the same element multiple times. Element 1073 values are the ones admitted for the corresponding labels in the POST 1074 request for creating a group configuration (see Section 6.3). 1076 The Group Manager MUST prepare the list L to include in the response 1077 as follows. 1079 1. The Group Manager prepares a preliminary version of the list L, 1080 as specified in Section 6.1 for the processing of a GET request 1081 to the group-collection resource. 1083 2. The Group Manager applies the filter criteria specified in the 1084 FETCH request to the list L from the previous step. The result 1085 is the list L to include in the response. 1087 Example in custom CBOR and Link Format: 1089 => 0.05 FETCH 1090 Uri-Path: manage 1091 Content-Format: TBD2 (application/ace-groupcomm+cbor) 1093 { 1094 "group_mode" : true, 1095 "sign_enc_alg" : 10, 1096 "hkdf" : 5 1097 } 1099 <= 2.05 Content 1100 Content-Format: 40 (application/link-format) 1102 ;rt="core.osc.gconf", 1103 ;rt="core.osc.gconf", 1104 ;rt="core.osc.gconf" 1106 Example in CoRAL: 1108 => 0.05 FETCH 1109 Uri-Path: manage 1110 Content-Format: TBD1 (application/coral+cbor) 1112 group_mode true 1113 sign_enc_alg 10 1114 hkdf 5 1116 <= 2.05 Content 1117 Content-Format: TBD1 (application/coral+cbor) 1119 #using 1120 #base 1121 item 1122 item 1123 item 1125 6.3. Create a New Group Configuration 1127 The Administrator can send a POST request to the group-collection 1128 resource, in order to create a new OSCORE group at the Group Manager. 1129 The request MUST specify the intended group name GROUPNAME, and MAY 1130 specify the intended group title together with pieces of information 1131 concerning the group configuration. 1133 When custom CBOR is used, the request payload is a CBOR map, whose 1134 possible entries are specified in Section 5.1 and use the same 1135 abbreviations defined in Section 9.1. 1137 When CoRAL is used, each element of the request payload corresponds 1138 to an entry specified in Section 5.1, with the exception of the 1139 'app_groups' status parameter (see below). 1141 In particular: 1143 * The payload MAY include any of the configuration parameter defined 1144 in Section 5.1.1. 1146 * The payload MUST include the status parameter 'group_name' defined 1147 in Section 5.1.2 and specifying the intended group name. 1149 * The payload MAY include any of the status parameter 'group_title', 1150 'max_stale_sets', 'exp', 'app_groups, 'group_policies', 'as_uri' 1151 and 'active' defined in Section 5.1.2. 1153 When CoRAL is used, each element of the 'app_groups' array from 1154 the status properties is included as a separate element with name 1155 'app_group'. 1157 * The payload MUST NOT include any of the status parameter 'rt', 1158 'ace-groupcomm-profile' and 'joining_uri' defined in 1159 Section 5.1.2. 1161 Consistently with what is defined at step 4 of Section 4, the Group 1162 Manager MUST check whether the group name specified in the 1163 'group_name' parameter matches with the group name pattern specified 1164 in any scope entry of the 'scope' claim in the stored Access Token 1165 for the Administrator. In case of a positive match, the Group 1166 Manager MUST check whether the permission set in the found scope 1167 entry specifies the permission "Create". 1169 If the verification above fails (i.e., there are no matching scope 1170 entries specifying the "Create" permission), the Group Manager MUST 1171 reply with a 4.03 (Forbidden) error response. The response MUST have 1172 Content-Format set to application/ace-groupcomm+cbor and is formatted 1173 as defined in Section 4.1.2 of [I-D.ietf-ace-key-groupcomm]. 1175 Otherwise, if any of the following occurs, the Group Manager MUST 1176 respond with a 4.00 (Bad Request) response. 1178 * Any of the received parameters is specified multiple times, with 1179 the exception of the 'app_group' element when using CoRAL. 1181 * Any of the received parameters is not recognized, or not valid, or 1182 not consistent with respect to other related parameters. 1184 * The Group Manager does not trust the Authorization Server with URI 1185 specified in the 'as_uri' parameter, and has no alternative 1186 Authorization Server to consider for the OSCORE group to create. 1188 After a successful processing of the POST request, the Group Manager 1189 performs the following actions. 1191 If the 'group_name' parameter specifies the group name of an already 1192 existing OSCORE group, the Group Manager MUST find an alternative 1193 name for the new OSCORE group to create. Note that the final 1194 decision about the name assigned to the new OSCORE group is always of 1195 the Group Manager, which may have more constraints than the 1196 Administrator can be aware of, possibly beyond the availability of 1197 suggested names. 1199 If the Group Manager has selected a name GROUPNAME different from the 1200 name GROUPNAME* indicated in the parameter 'group_name' of the 1201 request, then the following conditions MUST hold. 1203 * The chosen name GROUPNAME is available to assign; and 1204 * If GROUPNAME* matches with the group name pattern of certain scope 1205 entries from the 'scope' claim in the stored Access Token for the 1206 Administrator, then the chosen group name GROUPNAME also matches 1207 with each of those group name patterns. 1209 If the Group Manager does not find any group name for which both the 1210 above conditions hold, the Group Manager MUST respond with a 5.03 1211 (Service Unavailable) response. 1213 Otherwise, the Group Manager creates a new group-configuration 1214 resource, accessible to the Administrator at /manage/GROUPNAME, where 1215 GROUPNAME is the name of the OSCORE group as either indicated in the 1216 parameter 'group_name' of the request or uniquely assigned by the 1217 Group Manager. 1219 The value of the status parameter 'rt' is set to "core.osc.gconf". 1220 The values of other parameters specified in the request are used as 1221 group configuration information for the newly created OSCORE group. 1222 For each parameter not specified in the request, the Group Manager 1223 MUST use default values as specified in Section 5.2. 1225 After that, the Group Manager creates a new group-membership resource 1226 accessible at ace-group/GROUPNAME to nodes that want to join the 1227 OSCORE group, as specified in Section 6.2 of 1228 [I-D.ietf-ace-key-groupcomm-oscore]. Note that such group 1229 membership-resource comprises a number of sub-resources intended to 1230 current group members, as defined in Section 4.1 of 1231 [I-D.ietf-ace-key-groupcomm] and Section 5 of 1232 [I-D.ietf-ace-key-groupcomm-oscore]. 1234 From then on, the Group Manager will rely on the current group 1235 configuration to build the Joining Response message defined in 1236 Section 6.4 of [I-D.ietf-ace-key-groupcomm-oscore], when handling the 1237 joining of a new group member. Furthermore, the Group Manager 1238 generates the following pieces of information, and assigns them to 1239 the newly created OSCORE group. 1241 * The OSCORE Master Secret. 1243 * The OSCORE Master Salt (optionally). 1245 * The Group ID, used as OSCORE ID Context, which MUST be unique 1246 within the set of OSCORE groups under the Group Manager. 1248 Finally, the Group Manager replies to the Administrator with a 2.01 1249 (Created) response. The Location-Path option MUST be included in the 1250 response, indicating the location of the just created group- 1251 configuration resource. The response MUST NOT include a Location- 1252 Query option. 1254 The response payload specifies the parameters 'group_name', 1255 'joining_uri' and 'as_uri', from the status properties of the newly 1256 created OSCORE group (see Section 5.1), as detailed below. 1258 When custom CBOR is used, the response payload is a CBOR map, where 1259 entries use the same abbreviations defined in Section 9.1. When 1260 CoRAL is used, the response payload includes one element for each 1261 specified parameter. 1263 * 'group_name', with value the group name of the OSCORE group. This 1264 value can be different from the group name possibly specified by 1265 the Administrator in the POST request, and reflects the final 1266 choice of the Group Manager as 'group_name' status property for 1267 the OSCORE group. This parameter MUST be included. 1269 * 'joining_uri', with value the URI of the group-membership resource 1270 for joining the newly created OSCORE group. This parameter MUST 1271 be included. 1273 * 'as_uri', with value the URI of the Authorization Server 1274 associated with the Group Manager for the newly created OSCORE 1275 group. This parameter MUST be included if specified in the status 1276 properties of the group. This value can be different from the URI 1277 possibly specified by the Administrator in the POST request, and 1278 reflects the final choice of the Group Manager as 'as_uri' status 1279 property for the OSCORE group. 1281 If the POST request did not specify certain parameters and the Group 1282 Manager used default values different from the ones recommended in 1283 Section 5.2, then the response payload MUST include also those 1284 parameters, specifying the values chosen by the Group Manager for the 1285 current group configuration. 1287 The Group Manager can register the link to the group-membership 1288 resource with URI specified in 'joining_uri' to a Resource Directory 1289 [I-D.ietf-core-resource-directory][I-D.hartke-t2trg-coral-reef], as 1290 defined in Section 2 of [I-D.tiloca-core-oscore-discovery]. The 1291 Group Manager considers the current group configuration when 1292 specifying additional information for the link to register. 1294 Alternatively, the Administrator can perform the registration in the 1295 Resource Directory on behalf of the Group Manager, acting as 1296 Commissioning Tool. The Administrator considers the following when 1297 specifying additional information for the link to register. 1299 * The name of the OSCORE group MUST take the value specified in 1300 'group_name' from the 2.01 (Created) response. 1302 * The names of the application groups using the OSCORE group MUST 1303 take the values possibly specified by the elements of the 1304 'app_groups' parameter (when custom CBOR is used) or by the 1305 different 'app_group' elements (when CoRAL is used) in the POST 1306 request. 1308 * If also registering a related link to the Authorization Server 1309 associated with the OSCORE group, the related link MUST have as 1310 link target the URI in 'as_uri' from the 2.01 (Created) response, 1311 if the 'as_uri' parameter was included in the response. 1313 * Every other information element describing the current group 1314 configuration MUST take the value that the Administrator specified 1315 in the POST request. If a certain parameter was not specified in 1316 the POST request, the Administrator MUST use either the value 1317 specified in the the 2.01 (Created) response, if the Group Manager 1318 specified one, or the corresponding default value recommended in 1319 Section 5.2.1 otherwise. 1321 Note that, compared to the Group Manager, the Administrator is less 1322 likely to remain closely aligned with possible changes and updates 1323 that would require a prompt update to the registration in the 1324 Resource Directory. This applies especially to the address of the 1325 Group Manager, as well as the URI of the group-membership resource or 1326 of the Authorization Server associated with the Group Manager. 1328 Therefore, it is RECOMMENDED that registrations of links to group- 1329 membership resources in the Resource Directory are made (and possibly 1330 updated) directly by the Group Manager, rather than by the 1331 Administrator. 1333 Example in custom CBOR: 1335 => 0.02 POST 1336 Uri-Path: manage 1337 Content-Format: TBD2 (application/ace-groupcomm+cbor) 1339 { 1340 "sign_enc_alg" : 10, 1341 "hkdf" : 5, 1342 "pairwise_mode" : true, 1343 "active" : true, 1344 "group_name" : "gp4", 1345 "group_title" : "rooms 1 and 2", 1346 "app_groups": : ["room1", "room2"], 1347 "as_uri" : "coap://as.example.com/token" 1348 } 1350 <= 2.01 Created 1351 Location-Path: manage 1352 Location-Path: gp4 1353 Content-Format: TBD2 (application/ace-groupcomm+cbor) 1355 { 1356 "group_name" : "gp4", 1357 "joining_uri" : "coap://[2001:db8::ab]/ace-group/gp4/", 1358 "as_uri" : "coap://as.example.com/token" 1359 } 1361 Example in CoRAL: 1363 => 0.02 POST 1364 Uri-Path: manage 1365 Content-Format: TBD1 (application/coral+cbor) 1367 #using 1368 sign_enc_alg 10 1369 hkdf 5 1370 pairwise_mode true 1371 active true 1372 group_name "gp4" 1373 group_title "rooms 1 and 2" 1374 app_group "room1" 1375 app_group "room2" 1376 as_uri 1378 <= 2.01 Created 1379 Location-Path: manage 1380 Location-Path: gp4 1381 Content-Format: TBD1 (application/coral+cbor) 1383 #using 1384 group_name "gp4" 1385 joining_uri 1386 as_uri 1388 6.4. Retrieve a Group Configuration 1390 The Administrator can send a GET request to the group-configuration 1391 resource manage/GROUPNAME associated with an OSCORE group with group 1392 name GROUPNAME, in order to retrieve the complete current 1393 configuration of that group. 1395 Consistently with what is defined at step 4 of Section 4, the Group 1396 Manager MUST check whether GROUPNAME matches with the group name 1397 pattern specified in any scope entry of the 'scope' claim in the 1398 stored Access Token for the Administrator. In case of a positive 1399 match, the Group Manager MUST check whether the permission set in the 1400 found scope entry specifies the permission "Read". 1402 If the verification above fails (i.e., there are no matching scope 1403 entries specifying the "Read" permission), the Group Manager MUST 1404 reply with a 4.03 (Forbidden) error response. The response MUST have 1405 Content-Format set to application/ace-groupcomm+cbor and is formatted 1406 as defined in Section 4.1.2 of [I-D.ietf-ace-key-groupcomm]. 1408 Otherwise, after a successful processing of the GET request, the 1409 Group Manager replies to the Administrator with a 2.05 (Content) 1410 response. The response has as payload the representation of the 1411 group configuration as specified in Section 5.1. The exact content 1412 of the payload reflects the current configuration of the OSCORE 1413 group. This includes both configuration properties and status 1414 properties. 1416 When custom CBOR is used, the response payload is a CBOR map, whose 1417 possible entries are specified in Section 5.1 and use the same 1418 abbreviations defined in Section 9.1. 1420 When CoRAL is used, the response payload includes one element for 1421 each entry specified in Section 5.1, with the exception of the 1422 'app_groups' status parameter. That is, each element of the 1423 'app_groups' array from the status properties is included as a 1424 separate element with name 'app_group'. 1426 Example in custom CBOR: 1428 => 0.01 GET 1429 Uri-Path: manage 1430 Uri-Path: gp4 1432 <= 2.05 Content 1433 Content-Format: TBD2 (application/ace-groupcomm+cbor) 1435 { 1436 "hkdf" : 5, 1437 "cred_fmt" : 33, 1438 "group_mode" : true, 1439 "sign_enc_alg" : 10, 1440 "sign_alg" : -8, 1441 "sign_params" : [[1], [1, 6]], 1442 "pairwise_mode" : true, 1443 "alg" : 10, 1444 "ecdh_alg" : -27, 1445 "ecdh_params" : [[1], [1, 6]], 1446 "rt" : "core.osc.gconf", 1447 "active" : true, 1448 "group_name" : "gp4", 1449 "group_title" : "rooms 1 and 2", 1450 "ace-groupcomm-profile" : "coap_group_oscore_app", 1451 "max_stale_sets" : 3, 1452 "exp" : 1360289224, 1453 "app_groups": : ["room1", "room2"], 1454 "joining_uri" : "coap://[2001:db8::ab]/ace-group/gp4/", 1455 "as_uri" : "coap://as.example.com/token" 1456 } 1458 Example in CoRAL: 1460 => 0.01 GET 1461 Uri-Path: manage 1462 Uri-Path: gp4 1464 <= 2.05 Content 1465 Content-Format: TBD1 (application/coral+cbor) 1467 #using 1468 hkdf 5 1469 cred_fmt 33 1470 group_mode true 1471 sign_enc_alg 10 1472 sign_alg -8 1473 sign_params.alg_capab.key_type 1 1474 sign_params.key_type_capab.key_type 1 1475 sign_params.key_type_capab.curve 6 1476 pairwise_mode true 1477 alg 10 1478 ecdh_alg -27 1479 ecdh_params.alg_capab.key_type 1 1480 ecdh_params.key_type_capab.key_type 1 1481 ecdh_params.key_type_capab.curve 6 1482 rt "core.osc.gconf", 1483 active true 1484 group_name "gp4" 1485 group_title "rooms 1 and 2" 1486 ace-groupcomm-profile "coap_group_oscore_app" 1487 max_stale_sets 3 1488 exp 1360289224 1489 app_group "room1" 1490 app_group "room2" 1491 joining_uri 1492 as_uri 1494 6.5. Retrieve Part of a Group Configuration by Filters 1496 The Administrator can send a FETCH request to the group-configuration 1497 resource manage/GROUPNAME associated with an OSCORE group with group 1498 name GROUPNAME, in order to retrieve part of the current 1499 configuration of that group. 1501 When custom CBOR is used, the request payload is a CBOR map, which 1502 contains the following fields: 1504 * 'conf_filter', defined in Section 9.1 of this document and encoded 1505 as a CBOR array. Each element of the array specifies one 1506 requested configuration parameter or status parameter of the 1507 current group configuration (see Section 5.1), using the 1508 corresponding abbreviation defined in Section 9.1. 1510 When CoRAL is used, the request payload includes one element for each 1511 requested configuration parameter or status parameter of the current 1512 group configuration (see Section 5.1). All the specified elements 1513 have no value. 1515 The Group Manager MUST perform the same authorization checks defined 1516 for the processing of a GET request to a group-configuration resource 1517 in Section 6.4. That is, the Group Manager MUST verify that the 1518 Administrator has been granted a "Read" permission applicable to the 1519 targeted group-configuration resource. 1521 After a successful processing of the FETCH request, the Group Manager 1522 replies to the Administrator with a 2.05 (Content) response. The 1523 response has as payload a partial representation of the group 1524 configuration (see Section 5.1). The exact content of the payload 1525 reflects the current configuration of the OSCORE group, and is 1526 limited to the configuration properties and status properties 1527 requested by the Administrator in the FETCH request. 1529 The response payload includes the requested configuration parameters 1530 and status parameters, and is formatted as in the response payload of 1531 a GET request to a group-configuration resource (see Section 6.4). 1533 Example in custom CBOR: 1535 => 0.05 FETCH 1536 Uri-Path: manage 1537 Uri-Path: gp4 1538 Content-Format: TBD2 (application/ace-groupcomm+cbor) 1540 { 1541 "conf_filter" : ["sign_enc_alg", 1542 "hkdf", 1543 "pairwise_mode", 1544 "active", 1545 "group_title", 1546 "app_groups"] 1547 } 1549 <= 2.05 Content 1550 Content-Format: TBD2 (application/ace-groupcomm+cbor) 1552 { 1553 "sign_enc_alg" : 10, 1554 "hkdf" : 5, 1555 "pairwise_mode" : true, 1556 "active" : true, 1557 "group_title" : "rooms 1 and 2", 1558 "app_groups": : ["room1", "room2"] 1559 } 1561 Example in CoRAL: 1563 => 0.05 FETCH 1564 Uri-Path: manage 1565 Uri-Path: gp4 1566 Content-Format: TBD1 (application/coral+cbor) 1568 #using 1569 sign_enc_alg 1570 hkdf 1571 pairwise_mode 1572 active 1573 group_title 1574 app_groups 1576 <= 2.05 Content 1577 Content-Format: TBD1 (application/coral+cbor) 1579 #using 1580 sign_enc_alg 10 1581 hkdf 5 1582 pairwise_mode true 1583 active true 1584 group_title "rooms 1 and 2" 1585 app_group "room1" 1586 app_group "room2" 1588 6.6. Overwrite a Group Configuration 1590 The Administrator can send a PUT request to the group-configuration 1591 resource associated with an OSCORE group, in order to overwrite the 1592 current configuration of that group with a new one. The payload of 1593 the request has the same format of the POST request defined in 1594 Section 6.3, with the exception that the configuration parameters 1595 'group_mode' and 'pairwise_mode' as well as the status parameter 1596 'group_name' MUST NOT be included. 1598 The error handling for the PUT request is the same as for the POST 1599 request defined in Section 6.3, with the following difference in 1600 terms of authorization checks. 1602 Consistently with what is defined at step 4 of Section 4, the Group 1603 Manager MUST check whether GROUPNAME matches with the group name 1604 pattern specified in any scope entry of the 'scope' claim in the 1605 stored Access Token for the Administrator. In case of a positive 1606 match, the Group Manager MUST check whether the permission set in the 1607 found scope entry specifies the permission "Write". 1609 If the verification above fails (i.e., there are no matching scope 1610 entries specifying the "Write" permission), the Group Manager MUST 1611 reply with a 4.03 (Forbidden) error response. The response MUST have 1612 Content-Format set to application/ace-groupcomm+cbor and is formatted 1613 as defined in Section 4.1.2 of [I-D.ietf-ace-key-groupcomm]. 1615 If no error occurs and the PUT request is successfully processed, the 1616 Group Manager performs the following actions. 1618 First, the Group Manager updates the group-configuration resource, 1619 consistently with the values indicated in the PUT request from the 1620 Administrator. For each parameter not specified in the PUT request, 1621 the Group Manager MUST use default values as specified in 1622 Section 5.2. 1624 If a new value N' is specified for the 'max_stale_sets' status 1625 parameter and N' is smaller than the current value N, the Group 1626 Manager preserves the (up to) N' most recent sets in the collection 1627 of sets of stale OSCORE Sender IDs associated with the group, and 1628 deletes any possible older set from the collection (see Section 2.2.1 1629 of [I-D.ietf-ace-key-groupcomm-oscore]). 1631 From then on, the Group Manager relies on the latest updated 1632 configuration to build the Joining Response message defined in 1633 Section 6.4 of [I-D.ietf-ace-key-groupcomm-oscore], when handling the 1634 joining of a new group member. Similarly, the Group Manager relies 1635 on the new group configuration when building responses specifying 1636 (part of) the group configuration to a current group member. For 1637 instance, this applies when a group member retrieves from the Group 1638 Manager the updated group keying material (see Section 8 of 1639 [I-D.ietf-ace-key-groupcomm-oscore]) or the current group status (see 1640 Section 16 of [I-D.ietf-ace-key-groupcomm-oscore]). 1642 Then, the Group Manager replies to the Administrator with a 2.04 1643 (Changed) response. The payload of the response has the same format 1644 of the 2.01 (Created) response defined in Section 6.3. 1646 If the PUT request did not specify certain parameters and the Group 1647 Manager used default values different from the ones recommended in 1648 Section 5.2, then the response payload MUST include also those 1649 parameters, specifying the values chosen by the Group Manager for the 1650 current group configuration. 1652 If the link to the group-membership resource was registered in the 1653 Resource Directory [I-D.ietf-core-resource-directory], the GM is 1654 responsible to refresh the registration, as defined in Section 3 of 1655 [I-D.tiloca-core-oscore-discovery]. 1657 Alternatively, the Administrator can update the registration in the 1658 Resource Directory on behalf of the Group Manager, acting as 1659 Commissioning Tool. The Administrator considers the following when 1660 specifying additional information for the link to update. 1662 * The name of the OSCORE group MUST take the value specified in 1663 'group_name' from the 2.04 (Changed) response. 1665 * The names of the application groups using the OSCORE group MUST 1666 take the values possibly specified by the elements of the 1667 'app_groups' parameter (when custom CBOR is used) or by the 1668 different 'app_group' elements (when CoRAL is used) in the PUT 1669 request. 1671 * If also registering a related link to the Authorization Server 1672 associated with the OSCORE group, the related link MUST have as 1673 link target the URI in 'as_uri' from the 2.04 (Changed) response, 1674 if the 'as_uri' parameter was included in the response. 1676 * Every other information element describing the current group 1677 configuration MUST take the value that the Administrator specified 1678 in the PUT request. If a certain parameter was not specified in 1679 the PUT request, the Administrator MUST use either the value 1680 specified in the the 2.04 (Changed) response, if the Group Manager 1681 specified one, or the corresponding default value recommended in 1682 Section 5.2.1 otherwise. 1684 As discussed in Section 6.3, it is RECOMMENDED that registrations of 1685 links to group-membership resources in the Resource Directory are 1686 made (and possibly updated) directly by the Group Manager, rather 1687 than by the Administrator. 1689 Example in custom CBOR: 1691 => 0.03 PUT 1692 Uri-Path: manage 1693 Uri-Path: gp4 1694 Content-Format: TBD2 (application/ace-groupcomm+cbor) 1696 { 1697 "sign_enc_alg" : 11, 1698 "hkdf" : 5 1699 } 1701 <= 2.04 Changed 1702 Content-Format: TBD2 (application/ace-groupcomm+cbor) 1704 { 1705 "group_name" : "gp4", 1706 "joining_uri" : "coap://[2001:db8::ab]/ace-group/gp4/", 1707 "as_uri" : "coap://as.example.com/token" 1708 } 1710 Example in CoRAL: 1712 => 0.03 PUT 1713 Uri-Path: manage 1714 Uri-Path: gp4 1715 Content-Format: TBD1 (application/coral+cbor) 1717 #using 1718 sign_enc_alg 11 1719 hkdf 5 1721 <= 2.04 Changed 1722 Content-Format: TBD1 (application/coral+cbor) 1724 #using 1725 group_name "gp4" 1726 joining_uri 1727 as_uri 1729 6.6.1. Effects on Joining Nodes 1731 After having overwritten a group configuration, if the value of the 1732 status parameter 'active' is changed from "true" (0xf5) to "false" 1733 (0xf4), the Group Manager MUST stop admitting new members in the 1734 OSCORE group. In particular, until the status parameter 'active' is 1735 changed back to "true" (0xf5), the Group Manager MUST respond to a 1736 Joining Request with a 5.03 (Service Unavailable) response, as 1737 defined in Section 6.3 of [I-D.ietf-ace-key-groupcomm-oscore]. 1739 If the value of the status parameter 'active' is changed from "false" 1740 (0xf4) to "true" (0xf5), the Group Manager resumes admitting new 1741 members in the OSCORE group, by processing their Joining Requests 1742 (see Section 6.3 of [I-D.ietf-ace-key-groupcomm-oscore]). 1744 6.6.2. Effects on the Group Members 1746 After having overwritten a group configuration, the Group Manager 1747 informs the members of the OSCORE group, over the pairwise secure 1748 communication channels established when joining the group (see 1749 Section 6 of [I-D.ietf-ace-key-groupcomm-oscore]). 1751 To this end, the Group Manager can individually target the 1752 'control_uri' URI of each group member (see Section 4.3.1 of 1753 [I-D.ietf-ace-key-groupcomm]), if provided by the intended recipient 1754 upon joining the OSCORE group (see Section 6.2 of 1755 [I-D.ietf-ace-key-groupcomm-oscore]). To this end, messages sent by 1756 the Group Manager to each group member MUST have Content-Format set 1757 to application/ace-groupcomm+cbor, and MUST be formatted as the 1758 Joining Response defined in Section 6.4 of 1759 [I-D.ietf-ace-key-groupcomm-oscore], with the following differences. 1761 * Only the parameters 'gkty', 'key', 'num', 'exp' and 'ace- 1762 groupcomm-profile' are present. 1764 * The 'key' parameter includes only the parameters 'hkdf', 1765 'cred_fmt', 'sign_enc_alg', 'sign_alg', 'sign_params', 'alg', 1766 'ecdh_alg' and 'ecdh_params', with values reflecting the new 1767 configuration of the OSCORE group. 1769 Alternatively, group members can subscribe for updates to the group- 1770 membership resource of the OSCORE group, e.g., by using CoAP Observe 1771 [RFC7641]. 1773 If the value of the status parameter 'active' is changed from "true" 1774 (0xf5) to "false" (0xf4): 1776 * The Group Manager MUST stop accepting requests for new individual 1777 keying material from current group members (see Section 9 of 1778 [I-D.ietf-ace-key-groupcomm-oscore]). In particular, until the 1779 status parameter 'active' is changed back to "true" (0xf5), the 1780 Group Manager MUST respond to a Key Renewal Request with a 5.03 1781 (Service Unavailable) response, as defined in Section 9 of 1782 [I-D.ietf-ace-key-groupcomm-oscore]. 1784 * The Group Manager MUST stop accepting updated authentication 1785 credentials uploaded by current group members (see Section 11 of 1786 [I-D.ietf-ace-key-groupcomm-oscore]). In particular, until the 1787 status parameter 'active' is changed back to "true" (0xf5), the 1788 Group Manager MUST respond to a Public Key Update Request with a 1789 5.03 (Service Unavailable) response, as defined in Section 11 of 1790 [I-D.ietf-ace-key-groupcomm-oscore]. 1792 Every group member, upon learning that the OSCORE group has been 1793 deactivated (i.e., 'active' has value "false" (0xf4)), SHOULD stop 1794 communicating in the group. 1796 Every group member, upon learning that the OSCORE group has been 1797 reactivated (i.e., 'active' has value "true" (0xf5) again), can 1798 resume communicating in the group. 1800 Every group member, upon receiving updated values for 'hkdf', 1801 'sign_enc_alg' and 'alg', MUST either: 1803 * Leave the OSCORE group (see Section 18 of 1804 [I-D.ietf-ace-key-groupcomm-oscore]), e.g., if not supporting the 1805 indicated new algorithms; or 1807 * Use the new parameter values, and accordingly re-derive the OSCORE 1808 Security Context for the OSCORE group (see Section 2 of 1809 [I-D.ietf-core-oscore-groupcomm]). 1811 Every group member, upon receiving updated values for 'cred_fmt', 1812 'sign_alg', 'sign_params', 'ecdh_alg' and 'ecdh_params' MUST either: 1814 * Leave the OSCORE group, e.g., if not supporting the indicated new 1815 format, algorithms, parameters and encoding; or 1817 * Leave the OSCORE group and rejoin it (see Section 6 of 1818 [I-D.ietf-ace-key-groupcomm-oscore]). When rejoining the group, a 1819 new authentication credential in the indicated format used in the 1820 OSCORE group MUST be provided to the Group Manager. The 1821 authentication credential as well as the included public key MUST 1822 be compatible with the indicated algorithms and parameters. 1824 * Use the new parameter values, and, if required, perform the 1825 following actions. 1827 - Provide the Group Manager with a new authentication credential 1828 to use in the OSCORE group (see Section 11 of 1829 [I-D.ietf-ace-key-groupcomm-oscore]). The new authentication 1830 credential MUST be in the indicated format used in the OSCORE 1831 group. The new authentication credential as well as the 1832 included public key MUST be compatible with the indicated 1833 algorithms and parameters. 1835 - Retrieve from the Group Manager the new Group Manager's 1836 authentication credential (see Section 12 of 1837 [I-D.ietf-ace-key-groupcomm-oscore]). The new Group Manager's 1838 authentication credential is in the indicated format used in 1839 the OSCORE group. The new authentication credential as well as 1840 the included public key are compatible with the indicated 1841 algorithms and parameters. 1843 6.7. Selective Update of a Group Configuration 1845 The Administrator can send a PATCH/iPATCH request [RFC8132] to the 1846 group-configuration resource associated with an OSCORE group, in 1847 order to update the value of only part of the group configuration. 1849 The request payload has the same format of the PUT request defined in 1850 Section 6.6, with the difference that it MAY also specify names of 1851 application groups to be removed from or added to the 'app_groups' 1852 status parameter. The names of such application groups are provided 1853 as defined below. 1855 * When custom CBOR is used, the CBOR map in the request payload 1856 includes the field 'app_groups_diff'. This field MUST NOT be 1857 present multiple times, and it is encoded as a CBOR array 1858 including the following two elements. 1860 - The first element is a CBOR array, namely 'app_groups_del'. 1861 Each of its elements is a CBOR text string, with value the name 1862 of an application group to remove from the 'app_groups' status 1863 parameter. 1865 - The second element is a CBOR array, namely 'app_groups_add'. 1866 Each of its elements is a CBOR text string, with value the name 1867 of an application group to add to the 'app_groups' status 1868 parameter. 1870 The CDDL definition [RFC8610] of the CBOR array 'app_groups_diff' 1871 formatted as in the response from the Group Manager is provided 1872 below. 1874 app-group-name = tstr 1875 name-patch = [* app-group-name] 1876 app_groups_diff = [app_groups_del: name-patch, 1877 app_groups_add: name-patch] 1879 Figure 3: CDDL definition of the 'app_groups_diff' field 1881 The Group Manager MUST respond with a 4.00 (Bad Request) response, in 1882 case both the inner CBOR arrays 'app_groups_del' and 'app_groups_add' 1883 are empty, or in case the 'app_groups_diff' field occurs more than 1884 once. 1886 The Group Manager MUST respond with a 4.00 (Bad Request) response, in 1887 case the CBOR map in the request payload includes both the 1888 'app_groups' field and the 'app_groups_diff' field. 1890 * When CoRAL is used, the request payload includes the following 1891 top-level elements. 1893 - 'app_group_del', with value a text string specifying the name 1894 of an application group to remove from the 'app_groups' status 1895 parameter. This element can be included multiple times. 1897 - 'app_group_add', with value a text string specifying the name 1898 of an application group to add to the 'app_groups' status 1899 parameter. This element can be included multiple times. 1901 The Group Manager MUST respond with a 4.00 (Bad Request) response, 1902 in case the request payload includes both any 'app_group' element 1903 as well as any 'app_group_del' and/or 'app_group_add' element. 1905 The error handling for the PATCH/iPATCH request is the same as for 1906 the PUT request defined in Section 6.6, with the following additions. 1908 * The set of group configuration parameters to update MUST NOT be 1909 empty. That is, the Group Manager MUST respond with a 4.00 (Bad 1910 Request) response, if the request payload includes an empty CBOR 1911 map (when custom CBOR is used) or no elements (when CoRAL is 1912 used). 1914 * If the Request-URI does not point to an existing group- 1915 configuration resource, the Group Manager MUST NOT create a new 1916 resource, and MUST respond with a 4.04 (Not Found) response. 1918 * When applying the specified updated values would yield an 1919 inconsistent group configuration, the Group Manager MUST respond 1920 with a 4.09 (Conflict) response. 1922 The response, MAY include the current representation of the group 1923 configuration resource, like when responding to a GET request as 1924 defined in Section 6.4. Otherwise, the response SHOULD include a 1925 diagnostic payload with additional information for the 1926 Administrator to recognize the source of the conflict. 1928 * When the request uses specifically the iPATCH method, the Group 1929 Manager MUST respond with a 4.00 (Bad Request) response, in case: 1931 - When custom CBOR is used, the CBOR map includes the parameter 1932 'app_groups_diff'; or 1934 - When CoRAL is used, any element 'app_group_del' and/or 1935 'app_group_add' is included. 1937 Furthermore, the Group Manager MUST perform the same authorization 1938 checks defined for the processing of a PUT request to a group- 1939 configuration resource in Section 6.6. That is, the Group Manager 1940 MUST verify that the Administrator has been granted a "Write" 1941 permission applicable to the targeted group-configuration resource. 1943 If no error occurs and the PATCH/iPATCH request is successfully 1944 processed, the Group Manager performs the following actions. 1946 First, the Group Manager updates the group-configuration resource, 1947 consistently with the values indicated in the PATCH/iPATCH request 1948 from the Administrator. 1950 Unlike for the PUT request defined in Section 6.6, the Group Manager 1951 does not alter the value of configuration parameters and status 1952 parameters for which updated values are not specified in the request 1953 payload. In particular, the Group Manager does not assign possible 1954 default values to those parameters. 1956 Special processing occurs when updating the 'app_groups' status 1957 parameter by difference, as defined below. The Administrator should 1958 not expect the Group Manager to add or delete names of application 1959 group names according to any particular order. 1961 * If the name of an application group to add (delete) is specified 1962 multiple times, the Group Manager considers it only once for 1963 addition to (deletion from) the 'app_groups' status parameter. 1965 * If the name of an application group to delete is not present in 1966 the 'app_groups' status parameter before any change is applied, 1967 the Group Manager ignores that name. 1969 * If the name of an application group to add is already present in 1970 the 'app_groups' status parameter before any change is applied, 1971 the Group Manager ignores that name. 1973 * When custom CBOR is used, the Group Manager: 1975 - Deletes from the 'app_groups' status parameter the names of the 1976 application groups specified in the inner 'app_groups_del' CBOR 1977 array of the 'app_groups_diff' field. 1979 - Adds to the 'app_groups' status parameter the names of the 1980 application groups specified in the inner 'app_groups_add' CBOR 1981 array of the 'app_groups_diff' field. 1983 * When CoRAL is used, the Group Manager: 1985 - Deletes from the 'app_groups' status parameter the names of the 1986 application groups specified in the different 'app_group_del' 1987 elements. 1989 - Adds to the 'app_groups' status parameter the names of the 1990 application groups specified in the different 'app_group_add' 1991 elements. 1993 After having updated the group-configuration resource, from then on 1994 the Group Manager relies on the new group configuration to build the 1995 Joining Response message defined in Section 6.4 of 1996 [I-D.ietf-ace-key-groupcomm-oscore], when handling the joining of a 1997 new group member. Similarly, the Group Manager relies on the new 1998 group configuration when building responses specifying (part of) the 1999 group configuration to a current group member. For instance, this 2000 applies when a group member retrieves from the Group Manager the 2001 updated group keying material (see Section 8 of 2002 [I-D.ietf-ace-key-groupcomm-oscore]) or the current group status (see 2003 Section 16 of [I-D.ietf-ace-key-groupcomm-oscore]). 2005 Finally, the Group Manager replies to the Administrator with a 2.04 2006 (Changed) response. The payload of the response has the same format 2007 of the 2.01 (Created) response defined in Section 6.3. 2009 The same considerations as for the PUT request defined in Section 6.6 2010 hold also in this case, with respect to refreshing a possible 2011 registration of the link to the group-membership resource in the 2012 Resource Directory [I-D.ietf-core-resource-directory]. 2014 Example in custom CBOR: 2016 => 0.06 PATCH 2017 Uri-Path: manage 2018 Uri-Path: gp4 2019 Content-Format: TBD2 (application/ace-groupcomm+cbor) 2021 { 2022 "sign_enc_alg" : 10, 2023 "app_groups_diff" : [["room1"], 2024 ["room3", "room4"]] 2025 } 2027 <= 2.04 Changed 2028 Content-Format: TBD2 (application/ace-groupcomm+cbor) 2030 { 2031 "group_name" : "gp4", 2032 "joining_uri" : "coap://[2001:db8::ab]/ace-group/gp4/", 2033 "as_uri" : "coap://as.example.com/token" 2034 } 2036 Example in CoRAL: 2038 => 0.06 PATCH 2039 Uri-Path: manage 2040 Uri-Path: gp4 2041 Content-Format: TBD1 (application/coral+cbor) 2043 #using 2044 sign_enc_alg 10 2045 app_group_del "room1" 2046 app_group_add "room3" 2047 app_group_add "room4" 2049 <= 2.04 Changed 2050 Content-Format: TBD1 (application/coral+cbor) 2052 #using 2053 group_name "gp4" 2054 joining_uri 2055 as_uri 2057 6.7.1. Effects on Joining Nodes 2059 After having selectively updated part of a group configuration, the 2060 effects on candidate joining nodes are the same as defined in 2061 Section 6.6.1 for the case of group configuration overwriting. 2063 6.7.2. Effects on the Group Members 2065 After having selectively updated part of a group configuration, the 2066 effects on the current group members are the same as defined in 2067 Section 6.6.2 for the case of group configuration overwriting. 2069 6.8. Delete a Group Configuration 2071 The Administrator can send a DELETE request to the group- 2072 configuration resource, in order to delete that OSCORE group. 2074 Consistently with what is defined at step 4 of Section 4, the Group 2075 Manager MUST check whether GROUPNAME matches with the group name 2076 pattern specified in any scope entry of the 'scope' claim in the 2077 stored Access Token for the Administrator. In case of a positive 2078 match, the Group Manager MUST check whether the permission set in the 2079 found scope entry specifies the permission "Delete". 2081 If the verification above fails (i.e., there are no matching scope 2082 entries specifying the "Delete" permission), the Group Manager MUST 2083 reply with a 4.03 (Forbidden) error response. The response MUST have 2084 Content-Format set to application/ace-groupcomm+cbor and is formatted 2085 as defined in Section 4.1.2 of [I-D.ietf-ace-key-groupcomm]. 2087 Otherwise, the Group Manager continues processing the request, which 2088 would be successful only on an inactive OSCORE group. That is, the 2089 DELETE request actually yields a successful deletion of the OSCORE 2090 group, only if the corresponding status parameter 'active' has 2091 current value "false" (0xf4). The Administrator can ensure that, by 2092 first performing an update of the group-configuration resource 2093 associated with the OSCORE group (see Section 6.6), and setting the 2094 corresponding status parameter 'active' to "false" (0xf4). 2096 If, upon receiving the DELETE request, the current value of the 2097 status parameter 'active' is "true" (0xf5), the Group Manager MUST 2098 respond with a 4.09 (Conflict) response. The response MUST have 2099 Content-Format set to application/ace-groupcomm+cbor and is formatted 2100 as defined in Section 4.1.2 of [I-D.ietf-ace-key-groupcomm]. The 2101 value of the 'error' field MUST be set to 8 ("Group currently 2102 active"). 2104 After a successful processing of the DELETE request, the Group 2105 Manager performs the following actions. 2107 First, the Group Manager deletes the OSCORE group and deallocates 2108 both the group-configuration resource as well as the group-membership 2109 resource associated with that group. 2111 Then, the Group Manager replies to the Administrator with a 2.02 2112 (Deleted) response. 2114 Example: 2116 => 0.04 DELETE 2117 Uri-Path: manage 2118 Uri-Path: gp4 2120 <= 2.02 Deleted 2122 6.8.1. Effects on the Group Members 2124 After having deleted an OSCORE group, the Group Manager can inform 2125 the group members by means of the following two methods. When 2126 contacting a group member, the Group Manager uses the pairwise secure 2127 communication association established with that member during its 2128 joining process (see Section 6 of 2129 [I-D.ietf-ace-key-groupcomm-oscore]). 2131 * The Group Manager sends an individual request message to each 2132 group member, targeting the respective resource used to perform 2133 the group rekeying process (see Section 20.1 of 2134 [I-D.ietf-ace-key-groupcomm-oscore]). The Group Manager uses the 2135 same format of the Joining Response message in Section 6.4 of 2136 [I-D.ietf-ace-key-groupcomm-oscore], where only the parameters 2137 'gkty', 'key' and 'ace-groupcomm-profile' are present, and the 2138 'key' parameter is the empty CBOR map. 2140 * A group member may subscribe for updates to the group-membership 2141 resource associated with the OSCORE group. In particular, if this 2142 relies on CoAP Observe [RFC7641], a group member would receive a 2143 4.04 (Not Found) notification response from the Group Manager, 2144 since the group-configuration resource has been deallocated upon 2145 deleting the OSCORE group (see Section 6.1 of 2146 [I-D.ietf-ace-key-groupcomm]). The response MUST have Content- 2147 Format set to application/ace-groupcomm+cbor and is formatted as 2148 defined in Section 4.1.2 of [I-D.ietf-ace-key-groupcomm]. The 2149 value of the 'error' field MUST be set to 5 ("Group deleted"). 2151 When being informed about the deletion of the OSCORE group, a group 2152 member deletes the OSCORE Security Context that it stores as 2153 associated with that group, and possibly deallocates any dedicated 2154 control resource intended for the Group Manager that it has for that 2155 group. 2157 7. ACE Groupcomm Error Identifiers 2159 In addition to what is defined in Section 9 of 2160 [I-D.ietf-ace-key-groupcomm], this document defines a new value that 2161 the Group Manager can include as error identifiers, in the 'error' 2162 field of an error response with Content-Format application/ace- 2163 groupcomm+cbor. 2165 +-------+------------------------+ 2166 | Value | Description | 2167 +-------+------------------------+ 2168 | 10 | Group currently active | 2169 +-------+------------------------+ 2171 Figure 4: ACE Groupcomm Error Identifiers 2173 A Client supporting the 'error' parameter (see Sections 4.1.2 and 8 2174 of [I-D.ietf-ace-key-groupcomm]) and able to understand the specified 2175 error may use that information to determine what actions to take 2176 next. If it is included in the error response and supported by the 2177 Client, the 'error_description' parameter may provide additional 2178 context. In particular, the following guidelines apply. 2180 * In case of error 10, the Client should stop sending the request in 2181 question to the Group Manager, until the group becomes inactive. 2182 As per this document, this error is relevant only for the 2183 Administrator, if it tries to delete a group without having set 2184 its status to inactive first (see Section 6.8). In such a case, 2185 the Administrator should take the expected course of actions, and 2186 set the group status to inactive first (see Section 6.6 and 2187 Section 6.7), before proceeding with the group deletion. 2189 8. Security Considerations 2191 Security considerations are inherited from the ACE framework for 2192 Authentication and Authorization [I-D.ietf-ace-oauth-authz], and from 2193 the specific transport profile of ACE used between the Administrator 2194 and the Group Manager, such as [I-D.ietf-ace-dtls-authorize] and 2195 [I-D.ietf-ace-oscore-profile]. 2197 9. IANA Considerations 2199 RFC Editor: Please replace "[[this document]]" with the RFC number of 2200 this document and delete this paragraph. 2202 This document has the following actions for IANA. 2204 9.1. ACE Groupcomm Parameters 2206 IANA is asked to register the following entries in the "ACE Groupcomm 2207 Parameters" registry defined in Section 11.7 of 2208 [I-D.ietf-ace-key-groupcomm]. 2210 +-----------------+----------+--------------+-------------------+ 2211 | Name | CBOR Key | CBOR Type | Reference | 2212 +-----------------+----------+--------------+-------------------+ 2213 | hkdf | TBD | tstr / int | [[this document]] | 2214 +-----------------+----------+--------------+-------------------+ 2215 | cred_fmt | TBD | int | [[this document]] | 2216 +-----------------+----------+--------------+-------------------+ 2217 | group_mode | TBD | simple value | [[this document]] | 2218 +-----------------+----------+--------------+-------------------+ 2219 | sign_enc_alg | TBD | tstr / int / | [[this document]] | 2220 | | | simple value | | 2221 +-----------------+----------+--------------+-------------------+ 2222 | sign_alg | TBD | tstr / int / | [[this document]] | 2223 | | | simple value | | 2224 +-----------------+----------+--------------+-------------------+ 2225 | sign_params | TBD | array / | [[this document]] | 2226 | | | simple value | | 2227 +-----------------+----------+--------------+-------------------+ 2228 | pairwise_mode | TBD | simple value | [[this document]] | 2229 +-----------------+----------+--------------+-------------------+ 2230 | alg | TBD | tstr / int / | [[this document]] | 2231 | | | simple value | | 2232 +-----------------+----------+--------------+-------------------+ 2233 | ecdh_alg | TBD | tstr / int / | [[this document]] | 2234 | | | simple value | | 2235 +-----------------+----------+--------------+-------------------+ 2236 | ecdh_params | TBD | array / | [[this document]] | 2237 | | | simple value | | 2238 +-----------------+----------+--------------+-------------------+ 2239 | det_req | TBD | simple value | [[this document]] | 2240 +-----------------+----------+--------------+-------------------+ 2241 | det_hash_alg | TBD | tstr / int | [[this document]] | 2242 +-----------------+----------+--------------+-------------------+ 2243 | active | TBD | simple value | [[this document]] | 2244 +-----------------+----------+--------------+-------------------+ 2245 | group_name | TBD | tstr | [[this document]] | 2246 +-----------------+----------+--------------+-------------------+ 2247 | group_title | TBD | tstr / | [[this document]] | 2248 | | | simple value | | 2249 +-----------------+----------+--------------+-------------------+ 2250 | app_groups | TBD | array | [[this document]] | 2251 +-----------------+----------+--------------+-------------------+ 2252 | joining_uri | TBD | tstr | [[this document]] | 2253 +-----------------+----------+--------------+-------------------+ 2254 | max_stale_sets | TBD | uint | [[this document]] | 2255 +-----------------+----------+--------------+-------------------+ 2256 | as_uri | TBD | tstr | [[this document]] | 2257 +-----------------+----------+--------------+-------------------+ 2258 | conf_filter | TBD | array | [[this document]] | 2259 +-----------------+----------+--------------+-------------------+ 2260 | app_groups_diff | TBD | array | [[this document]] | 2261 +-----------------+----------+--------------+-------------------+ 2263 Figure 5: ACE Groupcomm Parameters 2265 9.2. ACE Groupcomm Errors 2267 IANA is asked to register the following entry in the "ACE Groupcomm 2268 Errors" registry defined in Section 11.13 of 2269 [I-D.ietf-ace-key-groupcomm]. 2271 * Value: 10 2273 * Description: Group currently active. 2275 * Reference: [[This document]] 2277 9.3. Resource Types 2279 IANA is asked to enter the following values in the "Resource Type 2280 (rt=) Link Target Attribute Values" registry within the "Constrained 2281 Restful Environments (CoRE) Parameters" registry group. 2283 +----------------+------------------------------+-------------------+ 2284 | Value | Description | Reference | 2285 +----------------+------------------------------+-------------------+ 2286 | core.osc.gcoll | Group-collection resource | [[this document]] | 2287 | | of an OSCORE Group Manager | | 2288 | | | | 2289 | core.osc.gconf | Group-configuration resource | [[this document]] | 2290 | | of an OSCORE Group Manager | | 2291 +----------------+------------------------------+-------------------+ 2293 9.4. Group OSCORE Admin Permissions 2295 This document establishes the IANA "Group OSCORE Admin Permissions" 2296 registry. The registry has been created to use the "Expert Review" 2297 registration procedure [RFC8126]. Expert review guidelines are 2298 provided in Section 9.8. 2300 This registry includes the possible permissions that Administrators 2301 can have to perform operations on an OSCORE Group Manager, each in 2302 combination with a numeric identifier. These numeric identifiers are 2303 used to express authorization information about performing 2304 administrative operations concerning OSCORE groups under the control 2305 of the Group Manager, as specified in Section 3 of [[this document]]. 2307 The columns of this registry are: 2309 * Name: A value that can be used in documents for easier 2310 comprehension, to identify a possible permission that 2311 Administrators can perform when interacting with an OSCORE Group 2312 Manager. 2314 * Value: The numeric identifier for this permission. Integer values 2315 greater than 65535 are marked as "Private Use", all other values 2316 use the registration policy "Expert Review" [RFC8126]. 2318 Note that, in general, a single permission can be associated with 2319 multiple different operations that are possible to be performed 2320 when interacting with the Group Manager. 2322 * Description: This field contains a brief description of the 2323 permission. 2325 * Reference: This contains a pointer to the public specification for 2326 the permission. 2328 This registry will be initially populated by the values in Figure 2. 2330 The Reference column for all of these entries will be [[this 2331 document]]. 2333 9.5. AIF 2335 For the media-types application/aif+cbor and application/aif+json 2336 defined in Section 5.1 of [I-D.ietf-ace-aif], IANA is requested to 2337 register the following entries for the two media-type parameters Toid 2338 and Tperm, in the respective sub-registry defined in Section 5.2 of 2339 [I-D.ietf-ace-aif] within the "MIME Media Type Sub-Parameter" 2340 registry group. 2342 * Name: oscore-group-name-pattern 2344 * Description/Specification: wildcard pattern of OSCORE group names 2346 * Reference: [[This document]] 2347 * Name: oscore-group-admin-permissions 2349 * Description/Specification: permission(s) to perform administrative 2350 operations at the OSCORE Group Manager 2352 * Reference: [[This document]] 2354 9.6. CoAP Content-Format 2356 IANA is asked to register the following entries to the "CoAP Content- 2357 Formats" registry within the "Constrained RESTful Environments (CoRE) 2358 Parameters" registry group. 2360 * Media Type: application/aif+cbor;Toid="oscore-group-name- 2361 pattern",Tperm="oscore-group-admin-permissions" 2363 * Encoding: - 2365 * ID: TBD 2367 * Reference: [[This document]] 2369 * Media Type: application/aif+json;Toid="oscore-group-name- 2370 pattern",Tperm="oscore-group-admin-permissions" 2372 * Encoding: - 2374 * ID: TBD 2376 * Reference: [[This document]] 2378 9.7. ACE Scope Semantics 2380 IANA is asked to register the following entry in the "ACE Scope 2381 Semantics" registry defined in Section 11.12 of 2382 [I-D.ietf-ace-key-groupcomm]. 2384 * Value: SEM_ID_TBD 2386 * Description: Permissions to perform administrative operations at 2387 the ACE Group Manager for Group OSCORE. 2389 * Reference: [[This document]] 2391 9.8. Expert Review Instructions 2393 The IANA registry established in this document is defined as "Expert 2394 Review". This section gives some general guidelines for what the 2395 experts should be looking for, but they are being designated as 2396 experts for a reason so they should be given substantial latitude. 2398 Expert reviewers should take into consideration the following points: 2400 * Clarity and correctness of registrations. Experts are expected to 2401 check the clarity of purpose and use of the requested entries. 2402 Experts should inspect the entry for the considered permission, to 2403 verify the correctness of its description against the permission 2404 as intended in the specification that defined it. Expert should 2405 consider requesting an opinion on the correctness of registered 2406 parameters from the Authentication and Authorization for 2407 Constrained Environments (ACE) Working Group and the Constrained 2408 RESTful Environments (CoRE) Working Group. 2410 Entries that do not meet these objective of clarity and 2411 completeness should not be registered. 2413 * Duplicated registration and point squatting should be discouraged. 2414 Reviewers are encouraged to get sufficient information for 2415 registration requests to ensure that the usage is not going to 2416 duplicate one that is already registered and that the point is 2417 likely to be used in deployments. 2419 * Experts should take into account the expected usage of permissions 2420 when approving point assignment. Given a 'Value' V as code point, 2421 the length of the encoding of (2^(V+1) - 1) should be weighed 2422 against the usage of the entry, considering the resources and 2423 capabilities of devices it will be used on. Additionally, given a 2424 'Value' V as code point, the length of the encoding of (2^(V+1) - 2425 1) should be weighed against how many code points resulting in 2426 that encoding length are left, and the resources and capabilities 2427 of devices it will be used on. 2429 * Specifications are recommended. When specifications are not 2430 provided, the description provided needs to have sufficient 2431 information to verify the points above. 2433 10. References 2435 10.1. Normative References 2437 [COSE.Algorithms] 2438 IANA, "COSE Algorithms", 2439 . 2442 [I-D.ietf-ace-aif] 2443 Bormann, C., "An Authorization Information Format (AIF) 2444 for ACE", Work in Progress, Internet-Draft, draft-ietf- 2445 ace-aif-06, 4 March 2022, 2446 . 2449 [I-D.ietf-ace-key-groupcomm] 2450 Palombini, F. and M. Tiloca, "Key Provisioning for Group 2451 Communication using ACE", Work in Progress, Internet- 2452 Draft, draft-ietf-ace-key-groupcomm-15, 23 December 2021, 2453 . 2456 [I-D.ietf-ace-key-groupcomm-oscore] 2457 Tiloca, M., Park, J., and F. Palombini, "Key Management 2458 for OSCORE Groups in ACE", Work in Progress, Internet- 2459 Draft, draft-ietf-ace-key-groupcomm-oscore-13, 7 March 2460 2022, . 2463 [I-D.ietf-ace-oauth-authz] 2464 Seitz, L., Selander, G., Wahlstroem, E., Erdtman, S., and 2465 H. Tschofenig, "Authentication and Authorization for 2466 Constrained Environments (ACE) using the OAuth 2.0 2467 Framework (ACE-OAuth)", Work in Progress, Internet-Draft, 2468 draft-ietf-ace-oauth-authz-46, 8 November 2021, 2469 . 2472 [I-D.ietf-ace-oscore-profile] 2473 Palombini, F., Seitz, L., Selander, G., and M. Gunnarsson, 2474 "OSCORE Profile of the Authentication and Authorization 2475 for Constrained Environments Framework", Work in Progress, 2476 Internet-Draft, draft-ietf-ace-oscore-profile-19, 6 May 2477 2021, . 2480 [I-D.ietf-core-coral] 2481 Amsüss, C. and T. Fossati, "The Constrained RESTful 2482 Application Language (CoRAL)", Work in Progress, Internet- 2483 Draft, draft-ietf-core-coral-04, 25 October 2021, 2484 . 2487 [I-D.ietf-core-groupcomm-bis] 2488 Dijk, E., Wang, C., and M. Tiloca, "Group Communication 2489 for the Constrained Application Protocol (CoAP)", Work in 2490 Progress, Internet-Draft, draft-ietf-core-groupcomm-bis- 2491 06, 7 March 2022, . 2494 [I-D.ietf-core-oscore-groupcomm] 2495 Tiloca, M., Selander, G., Palombini, F., Mattsson, J. P., 2496 and J. Park, "Group OSCORE - Secure Group Communication 2497 for CoAP", Work in Progress, Internet-Draft, draft-ietf- 2498 core-oscore-groupcomm-14, 7 March 2022, 2499 . 2502 [I-D.ietf-cose-rfc8152bis-algs] 2503 Schaad, J., "CBOR Object Signing and Encryption (COSE): 2504 Initial Algorithms", Work in Progress, Internet-Draft, 2505 draft-ietf-cose-rfc8152bis-algs-12, 24 September 2020, 2506 . 2509 [I-D.ietf-cose-rfc8152bis-struct] 2510 Schaad, J., "CBOR Object Signing and Encryption (COSE): 2511 Structures and Process", Work in Progress, Internet-Draft, 2512 draft-ietf-cose-rfc8152bis-struct-15, 1 February 2021, 2513 . 2516 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 2517 Requirement Levels", BCP 14, RFC 2119, 2518 DOI 10.17487/RFC2119, March 1997, 2519 . 2521 [RFC6690] Shelby, Z., "Constrained RESTful Environments (CoRE) Link 2522 Format", RFC 6690, DOI 10.17487/RFC6690, August 2012, 2523 . 2525 [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", 2526 RFC 6749, DOI 10.17487/RFC6749, October 2012, 2527 . 2529 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 2530 Application Protocol (CoAP)", RFC 7252, 2531 DOI 10.17487/RFC7252, June 2014, 2532 . 2534 [RFC7641] Hartke, K., "Observing Resources in the Constrained 2535 Application Protocol (CoAP)", RFC 7641, 2536 DOI 10.17487/RFC7641, September 2015, 2537 . 2539 [RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for 2540 Writing an IANA Considerations Section in RFCs", BCP 26, 2541 RFC 8126, DOI 10.17487/RFC8126, June 2017, 2542 . 2544 [RFC8132] van der Stok, P., Bormann, C., and A. Sehgal, "PATCH and 2545 FETCH Methods for the Constrained Application Protocol 2546 (CoAP)", RFC 8132, DOI 10.17487/RFC8132, April 2017, 2547 . 2549 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2550 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 2551 May 2017, . 2553 [RFC8610] Birkholz, H., Vigano, C., and C. Bormann, "Concise Data 2554 Definition Language (CDDL): A Notational Convention to 2555 Express Concise Binary Object Representation (CBOR) and 2556 JSON Data Structures", RFC 8610, DOI 10.17487/RFC8610, 2557 June 2019, . 2559 [RFC8613] Selander, G., Mattsson, J., Palombini, F., and L. Seitz, 2560 "Object Security for Constrained RESTful Environments 2561 (OSCORE)", RFC 8613, DOI 10.17487/RFC8613, July 2019, 2562 . 2564 [RFC8742] Bormann, C., "Concise Binary Object Representation (CBOR) 2565 Sequences", RFC 8742, DOI 10.17487/RFC8742, February 2020, 2566 . 2568 [RFC8949] Bormann, C. and P. Hoffman, "Concise Binary Object 2569 Representation (CBOR)", STD 94, RFC 8949, 2570 DOI 10.17487/RFC8949, December 2020, 2571 . 2573 10.2. Informative References 2575 [I-D.amsuess-core-cachable-oscore] 2576 Amsüss, C. and M. Tiloca, "Cacheable OSCORE", Work in 2577 Progress, Internet-Draft, draft-amsuess-core-cachable- 2578 oscore-04, 6 March 2022, . 2581 [I-D.hartke-t2trg-coral-reef] 2582 Hartke, K., "Resource Discovery in Constrained RESTful 2583 Environments (CoRE) using the Constrained RESTful 2584 Application Language (CoRAL)", Work in Progress, Internet- 2585 Draft, draft-hartke-t2trg-coral-reef-04, 9 May 2020, 2586 . 2589 [I-D.ietf-ace-dtls-authorize] 2590 Gerdes, S., Bergmann, O., Bormann, C., Selander, G., and 2591 L. Seitz, "Datagram Transport Layer Security (DTLS) 2592 Profile for Authentication and Authorization for 2593 Constrained Environments (ACE)", Work in Progress, 2594 Internet-Draft, draft-ietf-ace-dtls-authorize-18, 4 June 2595 2021, . 2598 [I-D.ietf-core-resource-directory] 2599 Amsüss, C., Shelby, Z., Koster, M., Bormann, C., and P. V. 2600 D. Stok, "CoRE Resource Directory", Work in Progress, 2601 Internet-Draft, draft-ietf-core-resource-directory-28, 7 2602 March 2021, . 2605 [I-D.ietf-cose-cbor-encoded-cert] 2606 Mattsson, J. P., Selander, G., Raza, S., Höglund, J., and 2607 M. Furuhed, "CBOR Encoded X.509 Certificates (C509 2608 Certificates)", Work in Progress, Internet-Draft, draft- 2609 ietf-cose-cbor-encoded-cert-03, 10 January 2022, 2610 . 2613 [I-D.ietf-tls-dtls13] 2614 Rescorla, E., Tschofenig, H., and N. Modadugu, "The 2615 Datagram Transport Layer Security (DTLS) Protocol Version 2616 1.3", Work in Progress, Internet-Draft, draft-ietf-tls- 2617 dtls13-43, 30 April 2021, . 2620 [I-D.tiloca-core-oscore-discovery] 2621 Tiloca, M., Amsuess, C., and P. V. D. Stok, "Discovery of 2622 OSCORE Groups with the CoRE Resource Directory", Work in 2623 Progress, Internet-Draft, draft-tiloca-core-oscore- 2624 discovery-11, 7 March 2022, 2625 . 2628 [RFC6347] Rescorla, E. and N. Modadugu, "Datagram Transport Layer 2629 Security Version 1.2", RFC 6347, DOI 10.17487/RFC6347, 2630 January 2012, . 2632 [RFC7925] Tschofenig, H., Ed. and T. Fossati, "Transport Layer 2633 Security (TLS) / Datagram Transport Layer Security (DTLS) 2634 Profiles for the Internet of Things", RFC 7925, 2635 DOI 10.17487/RFC7925, July 2016, 2636 . 2638 [RFC8392] Jones, M., Wahlstroem, E., Erdtman, S., and H. Tschofenig, 2639 "CBOR Web Token (CWT)", RFC 8392, DOI 10.17487/RFC8392, 2640 May 2018, . 2642 Appendix A. Document Updates 2644 RFC EDITOR: PLEASE REMOVE THIS SECTION. 2646 A.1. Version -04 to -05 2648 * Defined format of scope based on a new AIF data model. 2650 * Specified authorization checks at the Group Manager. 2652 * Revised resource handlers based on the new scope format. 2654 * Renamed 'pub_key_enc' to 'cred_fmt'. 2656 * Mandatory to include 'group_name' in the group creation request. 2658 * Suggesting a used 'group_name' results in a new name, not in an 2659 error. 2661 * Distinction between authentication credentials and public keys. 2663 * More details on informing group members about changes in the group 2664 configuration. 2666 * Revised order of sections; editorial improvements. 2668 A.2. Version -03 to -04 2670 * Clarifications on what to do in case of enhanced error responses. 2672 * Clarifications on handling default values for group parameters. 2674 * New configuration parameters to support OSCORE deterministic 2675 requests. 2677 * IANA considerations - Use RFC8126 terminology. 2679 * Author's change of address. 2681 * Editorial improvements. 2683 A.3. Version -02 to -03 2685 * Aligned new and old parameters to core-groupcomm-oscore and ace- 2686 key-groupcomm-oscore. 2688 * Removed 'cs_key_params' and 'ecdh_key_params' to avoid redundant 2689 COSE capabilities of key types, consistently with draft-ietf-ace- 2690 key-groupcomm-oscore. 2692 * Revised examples and side effects due to parameter changes. 2694 * New error type "Group currently active". 2696 A.4. Version -01 to -02 2698 * Admit multiple Administrators and limited access to admin 2699 resources. 2701 * Early design considerations for defining the format of scope. 2703 * Additional error handling, using also error types. 2705 * Selective update of group-configuration resources with PATCH/ 2706 iPATCH. 2708 * Editorial improvements. 2710 A.5. Version -00 to -01 2712 * Names of application groups as status parameter. 2714 * Parameters related to the pairwise mode of Group OSCORE. 2716 * Defined FETCH for group-configuration resources. 2718 * Policies on registration of links to the Resource Directory. 2720 * Added resource type for group-configuration resources. 2722 * Fixes, clarifications and editorial improvements. 2724 Acknowledgments 2726 Klaus Hartke provided substantial contribution in defining the 2727 resource model based on group collection and group configurations, as 2728 well as the interactions with the Group Manager using CoRAL. 2730 The authors sincerely thank Christian Amsuess, Carsten Bormann and 2731 Jim Schaad for their comments and feedback. 2733 The work on this document has been partly supported by VINNOVA and 2734 the Celtic-Next project CRITISEC; and by the H2020 project SIFIS-Home 2735 (Grant agreement 952652). 2737 Authors' Addresses 2739 Marco Tiloca 2740 RISE AB 2741 Isafjordsgatan 22 2742 SE-16440 Stockholm Kista 2743 Sweden 2744 Email: marco.tiloca@ri.se 2746 Rikard Höglund 2747 RISE AB 2748 Isafjordsgatan 22 2749 SE-16440 Stockholm Kista 2750 Sweden 2751 Email: rikard.hoglund@ri.se 2753 Peter van der Stok 2754 Consultant 2755 Phone: +31-492474673 (Netherlands), +33-966015248 (France) 2756 Email: stokcons@bbhmail.nl 2757 Francesca Palombini 2758 Ericsson AB 2759 Torshamnsgatan 23 2760 SE-16440 Stockholm Kista 2761 Sweden 2762 Email: francesca.palombini@ericsson.com