idnits 2.17.1 draft-ietf-ace-oscore-gm-admin-01.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- == 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 (November 02, 2020) is 1271 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) -- Looks like a reference, but probably isn't: '1' on line 945 -- Looks like a reference, but probably isn't: '6' on line 945 == Outdated reference: A later version (-18) exists of draft-ietf-ace-key-groupcomm-10 == Outdated reference: A later version (-16) exists of draft-ietf-ace-key-groupcomm-oscore-09 == Outdated reference: A later version (-46) exists of draft-ietf-ace-oauth-authz-35 == Outdated reference: A later version (-19) exists of draft-ietf-ace-oscore-profile-13 -- Possible downref: Normative reference to a draft: ref. 'I-D.ietf-cbor-7049bis' == Outdated reference: A later version (-06) exists of draft-ietf-core-coral-03 == Outdated reference: A later version (-11) exists of draft-ietf-core-groupcomm-bis-02 == Outdated reference: A later version (-21) exists of draft-ietf-core-oscore-groupcomm-10 ** Downref: Normative reference to an Informational draft: draft-ietf-cose-rfc8152bis-algs (ref. 'I-D.ietf-cose-rfc8152bis-algs') == Outdated reference: A later version (-15) exists of draft-ietf-cose-rfc8152bis-struct-14 -- Possible downref: Normative reference to a draft: ref. 'I-D.ietf-cose-rfc8152bis-struct' == Outdated reference: A later version (-18) exists of draft-ietf-ace-dtls-authorize-14 == Outdated reference: A later version (-28) exists of draft-ietf-core-resource-directory-25 == Outdated reference: A later version (-43) exists of draft-ietf-tls-dtls13-38 == Outdated reference: A later version (-15) exists of draft-tiloca-core-oscore-discovery-07 -- Obsolete informational reference (is this intentional?): RFC 6347 (Obsoleted by RFC 9147) Summary: 1 error (**), 0 flaws (~~), 14 warnings (==), 7 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. Hoeglund 4 Intended status: Standards Track RISE AB 5 Expires: May 6, 2021 P. van der Stok 6 Consultant 7 F. Palombini 8 K. Hartke 9 Ericsson AB 10 November 02, 2020 12 Admin Interface for the OSCORE Group Manager 13 draft-ietf-ace-oscore-gm-admin-01 15 Abstract 17 Group communication for CoAP can be secured using Group Object 18 Security for Constrained RESTful Environments (Group OSCORE). A 19 Group Manager is responsible to handle the joining of new group 20 members, as well as to manage and distribute the group key material. 21 This document defines a RESTful admin interface at the Group Manager, 22 that allows an Administrator entity to create and delete OSCORE 23 groups, as well as to retrieve and update their configuration. The 24 ACE framework for Authentication and Authorization is used to enforce 25 authentication and authorization of the Administrator at the Group 26 Manager. Protocol-specific transport profiles of ACE are used to 27 achieve communication security, proof-of-possession and server 28 authentication. 30 Status of This Memo 32 This Internet-Draft is submitted in full conformance with the 33 provisions of BCP 78 and BCP 79. 35 Internet-Drafts are working documents of the Internet Engineering 36 Task Force (IETF). Note that other groups may also distribute 37 working documents as Internet-Drafts. The list of current Internet- 38 Drafts is at https://datatracker.ietf.org/drafts/current/. 40 Internet-Drafts are draft documents valid for a maximum of six months 41 and may be updated, replaced, or obsoleted by other documents at any 42 time. It is inappropriate to use Internet-Drafts as reference 43 material or to cite them other than as "work in progress." 45 This Internet-Draft will expire on May 6, 2021. 47 Copyright Notice 49 Copyright (c) 2020 IETF Trust and the persons identified as the 50 document authors. All rights reserved. 52 This document is subject to BCP 78 and the IETF Trust's Legal 53 Provisions Relating to IETF Documents 54 (https://trustee.ietf.org/license-info) in effect on the date of 55 publication of this document. Please review these documents 56 carefully, as they describe your rights and restrictions with respect 57 to this document. Code Components extracted from this document must 58 include Simplified BSD License text as described in Section 4.e of 59 the Trust Legal Provisions and are provided without warranty as 60 described in the Simplified BSD License. 62 Table of Contents 64 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 65 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 4 66 2. Group Administration . . . . . . . . . . . . . . . . . . . . 6 67 2.1. Getting Access to the Group Manager . . . . . . . . . . . 6 68 2.2. Managing OSCORE Groups . . . . . . . . . . . . . . . . . 7 69 2.3. Collection Representation . . . . . . . . . . . . . . . . 8 70 2.4. Discovery . . . . . . . . . . . . . . . . . . . . . . . . 8 71 3. Group Configurations . . . . . . . . . . . . . . . . . . . . 9 72 3.1. Group Configuration Representation . . . . . . . . . . . 9 73 3.1.1. Configuration Properties . . . . . . . . . . . . . . 9 74 3.1.2. Status Properties . . . . . . . . . . . . . . . . . . 11 75 3.2. Default Values . . . . . . . . . . . . . . . . . . . . . 12 76 3.2.1. Configuration Parameters . . . . . . . . . . . . . . 12 77 3.2.2. Status Parameters . . . . . . . . . . . . . . . . . . 12 78 4. Interactions with the Group Manager . . . . . . . . . . . . . 13 79 4.1. Retrieve the Full List of Groups Configurations . . . . . 13 80 4.2. Retrieve a List of Group Configurations by Filters . . . 14 81 4.3. Create a New Group Configuration . . . . . . . . . . . . 15 82 4.4. Retrieve a Group Configuration . . . . . . . . . . . . . 20 83 4.5. Retrieve Part of a Group Configuration by Filters . . . . 22 84 4.6. Overwrite a Group Configuration . . . . . . . . . . . . . 24 85 4.6.1. Effects on Joining Nodes . . . . . . . . . . . . . . 26 86 4.6.2. Effects on the Group Members . . . . . . . . . . . . 27 87 4.7. Delete a Group Configuration . . . . . . . . . . . . . . 28 88 4.7.1. Effects on the Group Members . . . . . . . . . . . . 29 89 5. Security Considerations . . . . . . . . . . . . . . . . . . . 29 90 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 30 91 6.1. ACE Groupcomm Parameters Registry . . . . . . . . . . . . 30 92 6.2. Resource Types . . . . . . . . . . . . . . . . . . . . . 32 93 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 32 94 7.1. Normative References . . . . . . . . . . . . . . . . . . 32 95 7.2. Informative References . . . . . . . . . . . . . . . . . 34 96 Appendix A. Document Updates . . . . . . . . . . . . . . . . . . 35 97 A.1. Version -00 to -01 . . . . . . . . . . . . . . . . . . . 35 98 Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . 35 99 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 36 101 1. Introduction 103 The Constrained Application Protocol (CoAP) [RFC7252] can be used in 104 group communication environments where messages are also exchanged 105 over IP multicast [I-D.ietf-core-groupcomm-bis]. Applications 106 relying on CoAP can achieve end-to-end security at the application 107 layer by using Object Security for Constrained RESTful Environments 108 (OSCORE) [RFC8613], and especially Group OSCORE 109 [I-D.ietf-core-oscore-groupcomm] in group communication scenarios. 111 When group communication for CoAP is protected with Group OSCORE, 112 nodes are required to explicitly join the correct OSCORE group. To 113 this end, a joining node interacts with a Group Manager (GM) entity 114 responsible for that group, and retrieves the required key material 115 to securely communicate with other group members using Group OSCORE. 117 The method in [I-D.ietf-ace-key-groupcomm-oscore] specifies how nodes 118 can join an OSCORE group through the respective Group Manager. Such 119 a method builds on the ACE framework for Authentication and 120 Authorization [I-D.ietf-ace-oauth-authz], so ensuring a secure 121 joining process as well as authentication and authorization of 122 joining nodes (clients) at the Group Manager (resource server). 124 In some deployments, the application running on the Group Manager may 125 know when a new OSCORE group has to be created, as well as how it 126 should be configured and later on updated or deleted, e.g. based on 127 the current application state or on pre-installed policies. In this 128 case, the Group Manager application can create and configure OSCORE 129 groups when needed, by using a local application interface. However, 130 this requires the Group Manager to be application-specific, which in 131 turn leads to error prone deployments and is poorly flexible. 133 In other deployments, a separate Administrator entity, such as a 134 Commissioning Tool, is directly responsible for creating and 135 configuring the OSCORE groups at a Group Manager, as well as for 136 maintaining them during their whole lifetime until their deletion. 137 This allows the Group Manager to be agnostic of the specific 138 applications using secure group communication. 140 This document specifies a RESTful admin interface at the Group 141 Manager, intended for an Administrator as a separate entity external 142 to the Group Manager and its application. The interface allows the 143 Administrator to create and delete OSCORE groups, as well as to 144 configure and update their configuration. 146 Interaction examples are provided, in Link Format [RFC6690] and CBOR 147 [I-D.ietf-cbor-7049bis], as well as in CoRAL [I-D.ietf-core-coral]. 148 While all the CoRAL examples use the CoRAL textual serialization 149 format, the CBOR or JSON [RFC8259] binary serialization format is 150 used when sending such messages on the wire. 152 The ACE framework is used to ensure authentication and authorization 153 of the Administrator (client) at the Group Manager (resource server). 154 In order to achieve communication security, proof-of-possession and 155 server authentication, the Administrator and the Group Manager 156 leverage protocol-specific transport profiles of ACE, such as 157 [I-D.ietf-ace-oscore-profile][I-D.ietf-ace-dtls-authorize]. These 158 include also possible forthcoming transport profiles that comply with 159 the requirements in Appendix C of [I-D.ietf-ace-oauth-authz]. 161 1.1. Terminology 163 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 164 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 165 "OPTIONAL" in this document are to be interpreted as described in BCP 166 14 [RFC2119] [RFC8174] when, and only when, they appear in all 167 capitals, as shown here. 169 Readers are expected to be familiar with the terms and concepts from 170 the following specifications: 172 o CBOR [I-D.ietf-cbor-7049bis] and COSE 173 [I-D.ietf-cose-rfc8152bis-struct][I-D.ietf-cose-rfc8152bis-algs]. 175 o The CoAP protocol [RFC7252], also in group communication scenarios 176 [I-D.ietf-core-groupcomm-bis]. These include the concepts of: 178 * "application group", as a set of CoAP nodes that share a common 179 set of resources; and of 181 * "security group", as a set of CoAP nodes that share the same 182 security material, and use it to protect and verify exchanged 183 messages. 185 o The OSCORE [RFC8613] and Group OSCORE 186 [I-D.ietf-core-oscore-groupcomm] security protocols. These 187 include the concept of Group Manager, as the entity responsible 188 for a set of OSCORE groups where communications among members are 189 secured using Group OSCORE. An OSCORE group is used as security 190 group for one or many application groups. 192 o The ACE framework for authentication and authorization 193 [I-D.ietf-ace-oauth-authz]. The terminology for entities in the 194 considered architecture is defined in OAuth 2.0 [RFC6749]. In 195 particular, this includes Client (C), Resource Server (RS), and 196 Authorization Server (AS). 198 o The management of keying material for groups in ACE 199 [I-D.ietf-ace-key-groupcomm] and specifically for OSCORE groups 200 [I-D.ietf-ace-key-groupcomm-oscore]. These include the concept of 201 group-membership resource hosted by the Group Manager, that new 202 members access to join the OSCORE group, while current members can 203 access to retrieve updated keying material. 205 Note that, unless otherwise indicated, the term "endpoint" is used 206 here following its OAuth definition, aimed at denoting resources such 207 as /token and /introspect at the AS, and /authz-info at the RS. This 208 document does not use the CoAP definition of "endpoint", which is "An 209 entity participating in the CoAP protocol". 211 This document also refers to the following terminology. 213 o Administrator: entity responsible to create, configure and delete 214 OSCORE groups at a Group Manager. 216 o Group name: stable and invariant name of an OSCORE group. The 217 group name MUST be unique under the same Group Manager, and MUST 218 include only characters that are valid for a URI path segment. 220 o Group-collection resource: a single-instance resource hosted by 221 the Group Manager. An Administrator accesses a group-collection 222 resource to create a new OSCORE group, or to retrieve the list of 223 existing OSCORE groups, under that Group Manager. As an example, 224 this document uses /manage as the url-path of the group-collection 225 resource; implementations are not required to use this name, and 226 can define their own instead. 228 o Group-configuration resource: a resource hosted by the Group 229 Manager, associated to an OSCORE group under that Group Manager. 230 A group-configuration resource is identifiable with the invariant 231 group name of the respective OSCORE group. An Administrator 232 accesses a group-configuration resource to retrieve or update the 233 configuration of the respective OSCORE group, or to delete that 234 group. The url-path to a group-configuration resource has 235 GROUPNAME as last segment, with GROUPNAME the invariant group name 236 assigned upon its creation. Building on the considered url-path 237 of the group-collection resource, this document uses /manage/ 238 GROUPNAME as the url-path of a group-configuration resource; 239 implementations are not required to use this name, and can define 240 their own instead. 242 o Admin endpoint: an endpoint at the Group Manager associated to the 243 group-collection resource or to a group-configuration resource 244 hosted by that Group Manager. 246 2. Group Administration 248 With reference to the ACE framework and the terminology defined in 249 OAuth 2.0 [RFC6749]: 251 o The Group Manager acts as Resource Server (RS). It provides one 252 single group-collection resource, and one group-configuration 253 resource per existing OSCORE group. Each of those is exported by 254 a distinct admin endpoint. 256 o The Administrator acts as Client (C), and requests to access the 257 group-collection resource and group-configuration resources, by 258 accessing the respective admin endpoint at the Group Manager. 260 o The Authorization Server (AS) authorizes the Administrator to 261 access the group-collection resource and group-configuration 262 resources at a Group Manager. Multiple Group Managers can be 263 associated to the same AS. The AS MAY release Access Tokens to 264 the Administrator for other purposes than accessing admin 265 endpoints of registered Group Managers. 267 2.1. Getting Access to the Group Manager 269 All communications between the involved entities rely on the CoAP 270 protocol and MUST be secured. 272 In particular, communications between the Administrator and the Group 273 Manager leverage protocol-specific transport profiles of ACE to 274 achieve communication security, proof-of-possession and server 275 authentication. To this end, the AS may explicitly signal the 276 specific transport profile to use, consistently with requirements and 277 assumptions defined in the ACE framework [I-D.ietf-ace-oauth-authz]. 279 With reference to the AS, communications between the Administrator 280 and the AS (/token endpoint) as well as between the Group Manager and 281 the AS (/introspect endpoint) can be secured by different means, for 282 instance using DTLS [RFC6347][I-D.ietf-tls-dtls13] or OSCORE 283 [RFC8613]. Further details on how the AS secures communications 284 (with the Administrator and the Group Manager) depend on the 285 specifically used transport profile of ACE, and are out of the scope 286 of this specification. 288 In order to get access to the Group Manager for managing OSCORE 289 groups, an Administrator performs the following steps. 291 1. The Administrator requests an Access Token from the AS, in order 292 to access the group-collection and group-configuration resources 293 on the Group Manager. The Administrator will start or continue 294 using secure communications with the Group Manager, according to 295 the response from the AS. 297 2. The Administrator transfers authentication and authorization 298 information to the Group Manager by posting the obtained Access 299 Token, according to the used profile of ACE, such as 300 [I-D.ietf-ace-dtls-authorize] and [I-D.ietf-ace-oscore-profile]. 301 After that, the Administrator must have secure communication 302 established with the Group Manager, before performing any admin 303 operation on that Group Manager. Possible ways to provide secure 304 communication are DTLS [RFC6347][I-D.ietf-tls-dtls13] and OSCORE 305 [RFC8613]. The Administrator and the Group Manager maintain the 306 secure association, to support possible future communications. 308 3. The Administrator performs admin operations at the Group Manager, 309 as described in the following sections. These include the 310 retrieval of the existing OSCORE groups, the creation of new 311 OSCORE groups, the update and retrieval of OSCORE group 312 configurations, and the removal of OSCORE groups. Messages 313 exchanged among the Administrator and the Group Manager are 314 specified in Section 4. 316 2.2. Managing OSCORE Groups 318 Figure 1 shows the resources of a Group Manager available to an 319 Administrator. 321 ___ 322 Group / \ 323 Collection \___/ 324 \ 325 \____________________ 326 \___ \___ \___ 327 / \ / \ ... / \ Group 328 \___/ \___/ \___/ Configurations 330 Figure 1: Resources of a Group Manager 332 The Group Manager exports a single group-collection resource, with 333 resource type "core.osc.gcoll" defined in Section 6.2 of this 334 specification. The interface for the group-collection resource 335 defined in Section 4 allows the Administrator to: 337 o Retrieve the complete list of existing OSCORE groups. 339 o Retrieve a partial list of existing OSCORE groups, by applying 340 filter criteria. 342 o Create a new OSCORE group, specifying its invariant group name 343 and, optionally, its configuration. 345 The Group Manager exports one group-configuration resource for each 346 of its OSCORE groups. Each group-configuration resource has resource 347 type "core.osc.gconf" defined in Section 6.2 of this specification, 348 and is identified by the group name specified upon creating the 349 OSCORE group. The interface for a group-configuration resource 350 defined in Section 4 allows the Administrator to: 352 o Retrieve the complete current configuration of the OSCORE group. 354 o Retrieve part of the current configuration of the OSCORE group, by 355 applying filter criteria. 357 o Overwrite the current configuration of the OSCORE group. 359 o Delete the OSCORE group. 361 2.3. Collection Representation 363 A list of group configurations is represented as a document 364 containing the corresponding group-configuration resources in the 365 list. Each group-configuration is represented as a link, where the 366 link target is the URI of the group-configuration resource. 368 The list can be represented as a Link Format document [RFC6690] or a 369 CoRAL document [I-D.ietf-core-coral]. 371 In the former case, the link to each group-configuration resource 372 specifies the link target attribute 'rt' (Resource Type), with value 373 "core.osc.gconf" defined in Section 6.2 of this specification. 375 In the latter case, the CoRAL document specifies the group- 376 configuration resources in the list as top-level elements. In 377 particular, the link to each group-configuration resource has 378 http://coreapps.org/core.osc.gcoll#item as relation type. 380 2.4. Discovery 382 The Administrator can discover the group-collection resource from a 383 Resource Directory, for instance [I-D.ietf-core-resource-directory] 384 and [I-D.hartke-t2trg-coral-reef], or from .well-known/core, by using 385 the resource type "core.osc.gcoll" defined in Section 6.2 of this 386 specification. 388 The Administrator can discover group-configuration resources for the 389 group-collection resource as specified in Section 4.1 and 390 Section 4.2. 392 3. Group Configurations 394 A group configuration consists of a set of parameters. 396 3.1. Group Configuration Representation 398 The group configuration representation is a CBOR map which MUST 399 include configuration properties and status properties. 401 3.1.1. Configuration Properties 403 The CBOR map MUST include the following configuration parameters: 405 o 'hkdf', defined in Section 6.1 of this document, specifies the 406 HKDF algorithm used in the OSCORE group, encoded as a CBOR text 407 string or a CBOR integer. Possible values are the same ones 408 admitted for the 'hkdf' parameter of the "OSCORE Security Context 409 Parameters" registry, defined in Section 3.2.1 of 410 [I-D.ietf-ace-oscore-profile]. 412 o 'alg', defined in Section 6.1 of this document, specifies the AEAD 413 algorithm used in the OSCORE group, encoded as a CBOR text string 414 or a CBOR integer. Possible values are the same ones admitted for 415 the 'alg' parameter of the "OSCORE Security Context Parameters" 416 registry, defined in Section 3.2.1 of 417 [I-D.ietf-ace-oscore-profile]. 419 o 'cs_alg', defined in Section 6.1 of this document, specifies the 420 countersignature algorithm used in the OSCORE group, encoded as a 421 CBOR text string or a CBOR integer. Possible values are the same 422 ones admitted for the 'cs_alg' parameter of the "OSCORE Security 423 Context Parameters" registry, defined in Section 6.4 of 424 [I-D.ietf-ace-key-groupcomm-oscore]. 426 o 'cs_params', defined in Section 6.1 of this document, specifies 427 the additional parameters for the countersignature algorithm used 428 in the OSCORE group, encoded as a CBOR array. Possible formats 429 and values are the same ones admitted for the 'cs_params' 430 parameter of the "OSCORE Security Context Parameters" registry, 431 defined in Section 6.4 of [I-D.ietf-ace-key-groupcomm-oscore]. 433 o 'cs_key_params', defined in Section 6.1 of this document, 434 specifies the additional parameters for the key used with the 435 countersignature algorithm in the OSCORE group, encoded as a CBOR 436 array. Possible formats and values are the same ones admitted for 437 the 'cs_key_params' parameter of the "OSCORE Security Context 438 Parameters" registry, defined in Section 6.4 of 439 [I-D.ietf-ace-key-groupcomm-oscore]. 441 o 'cs_key_enc', defined in Section 6.1 of this document, specifies 442 the encoding of the public keys of group members, encoded as a 443 CBOR integer. Possible values are the same ones admitted for the 444 'cs_key_enc' parameter of the "OSCORE Security Context Parameters" 445 registry, defined in Section 6.4 of 446 [I-D.ietf-ace-key-groupcomm-oscore]. 448 o 'pairwise_mode', defined in Section 6.1 of this document and 449 encoded as a CBOR simple value. Its value is True if the OSCORE 450 group supports the pairwise mode of Group OSCORE 451 [I-D.ietf-core-oscore-groupcomm], or False otherwise. 453 o 'ecdh_alg', defined in Section 6.1 of this document and formatted 454 as follows. If the configuration parameter 'pairwise_mode' has 455 value False, this parameter has as value the CBOR simple value 456 Null. Otherwise, this parameter specifies the ECDH algorithm used 457 in the OSCORE group, encoded as a CBOR text string or a CBOR 458 integer. Possible values are the same ones admitted for the 459 'ecdh_alg' parameter of the "OSCORE Security Context Parameters" 460 registry, defined in Section 6.4 of 461 [I-D.ietf-ace-key-groupcomm-oscore]. 463 o 'ecdh_params', defined in Section 6.1 of this document and 464 formatted as follows. If the configuration parameter 465 'pairwise_mode' has value False, this parameter has as value the 466 CBOR simple value Null. Otherwise, this parameter specifies the 467 parameters for the ECDH algorithm used in the OSCORE group, 468 encoded as a CBOR array. Possible formats and values are the same 469 ones admitted for the 'ecdh_params' parameter of the "OSCORE 470 Security Context Parameters" registry, defined in Section 6.4 of 471 [I-D.ietf-ace-key-groupcomm-oscore]. 473 o 'ecdh_key_params', defined in Section 6.1 of this document and 474 formatted as follows. If the configuration parameter 475 'pairwise_mode' has value False, this parameter has as value the 476 CBOR simple value Null. Otherwise, this parameter specifies the 477 additional parameters for the key used with the ECDH algorithm in 478 the OSCORE group, encoded as a CBOR array. Possible formats and 479 values are the same ones admitted for the 'ecdh_key_params' 480 parameter of the "OSCORE Security Context Parameters" registry, 481 defined in Section 6.4 of [I-D.ietf-ace-key-groupcomm-oscore]. 483 3.1.2. Status Properties 485 The CBOR map MUST include the following status parameters: 487 o 'rt', with value the resource type "core.osc.gconf" associated to 488 group-configuration resources, encoded as a CBOR text string. 490 o 'active', encoding the CBOR simple value True if the OSCORE group 491 is currently active, or the CBOR simple value False otherwise. 492 This parameter is defined in Section 6.1 of this specification. 494 o 'group_name', with value the group name of the OSCORE group 495 encoded as a CBOR text string. This parameter is defined in 496 Section 6.1 of this specification. 498 o 'group_title', with value either a human-readable description of 499 the OSCORE group encoded as a CBOR text string, or the CBOR simple 500 value Null if no description is specified. This parameter is 501 defined in Section 6.1 of this specification. 503 o 'ace-groupcomm-profile', defined in Section 4.1.2.1 of 504 [I-D.ietf-ace-key-groupcomm], with value "coap_group_oscore_app" 505 defined in Section 21.3 of [I-D.ietf-ace-key-groupcomm-oscore] 506 encoded as a CBOR integer. 508 o 'exp', defined in Section 4.1.2.1 of [I-D.ietf-ace-key-groupcomm]. 510 o 'app_groups', with value a list of names of application groups, 511 encoded as a CBOR array. Each element of the array is a CBOR text 512 string, specifying the name of an application group using the 513 OSCORE group as security group (see Section 2.1 of 514 [I-D.ietf-core-groupcomm-bis]). 516 o 'joining_uri', with value the URI of the group-membership resource 517 for joining the newly created OSCORE group as per Section 6.2 of 518 [I-D.ietf-ace-key-groupcomm-oscore], encoded as a CBOR text 519 string. This parameter is defined in Section 6.1 of this 520 specification. 522 The CBOR map MAY include the following status parameters: 524 o 'group_policies', defined in Section 4.1.2.1 of 525 [I-D.ietf-ace-key-groupcomm], and consistent with the format and 526 content defined in Section 6.4 of 527 [I-D.ietf-ace-key-groupcomm-oscore]. 529 o 'as_uri', defined in Section 6.1 of this document, specifies the 530 URI of the Authorization Server associated to the Group Manager 531 for the OSCORE group, encoded as a CBOR text string. Candidate 532 group members will have to obtain an Access Token from that 533 Authorization Server, before starting the joining process with the 534 Group Manager to join the OSCORE group (see Section 4 and 535 Section 6 of [I-D.ietf-ace-key-groupcomm-oscore]). 537 3.2. Default Values 539 This section defines the default values that the Group Manager 540 assumes for configuration and status parameters. 542 3.2.1. Configuration Parameters 544 For each configuration parameter, the Group Manager MUST use a pre- 545 configured default value, if none is specified by the Administrator. 546 In particular: 548 o For 'pairwise_mode', the Group Manager SHOULD use the CBOR simple 549 value False. 551 o If 'pairwise_mode' has value True, the Group Manager SHOULD use 552 the same default values defined in Section 19 of 553 [I-D.ietf-ace-key-groupcomm-oscore] for the parameters 'ecdh_alg', 554 'ecdh_params' and 'ecdh_key_params'. 556 o For any other configuration parameter, the Group Manager SHOULD 557 use the same default values defined in Section 19 of 558 [I-D.ietf-ace-key-groupcomm-oscore]. 560 3.2.2. Status Parameters 562 For the following status parameters, the Group Manager MUST use a 563 pre-configured default value, if none is specified by the 564 Administrator. In particular: 566 o For 'active', the Group Manager SHOULD use the CBOR simple value 567 False. 569 o For 'group_title', the Group Manager SHOULD use the CBOR simple 570 value Null. 572 o For 'app_groups', the Group Manager SHOULD use the empty CBOR 573 array. 575 4. Interactions with the Group Manager 577 This section describes the operations available on the group- 578 collection resource and the group-configuration resources. 580 When custom CBOR is used, the Content-Format in messages containing a 581 payload is set to application/ace-groupcomm+cbor, defined in 582 Section 8.2 of [I-D.ietf-ace-key-groupcomm]. Furthermore, the entry 583 labels defined in Section 6.1 of this document MUST be used, when 584 specifying the corresponding configuration and status parameters. 586 4.1. Retrieve the Full List of Groups Configurations 588 The Administrator can send a GET request to the group-collection 589 resource, in order to retrieve the complete list of the existing 590 OSCORE groups at the Group Manager. This is returned as a list of 591 links to the corresponding group-configuration resources. 593 Example in Link Format: 595 => 0.01 GET 596 Uri-Path: manage 598 <= 2.05 Content 599 Content-Format: 40 (application/link-format) 601 ;rt="core.osc.gconf", 602 ;rt="core.osc.gconf", 603 ;rt="core.osc.gconf" 605 Example in CoRAL: 607 => 0.01 GET 608 Uri-Path: manage 610 <= 2.05 Content 611 Content-Format: TBD1 (application/coral+cbor) 613 #using 614 #base 615 item 616 item 617 item 619 4.2. Retrieve a List of Group Configurations by Filters 621 The Administrator can send a FETCH request to the group-collection 622 resource, in order to retrieve the list of the existing OSCORE groups 623 that fully match a set of specified filter criteria. This is 624 returned as a list of links to the corresponding group-configuration 625 resources. 627 When custom CBOR is used, the set of filter criteria is specified in 628 the request payload as a CBOR map, whose possible entries are 629 specified in Section 3.1 and use the same abbreviations defined in 630 Section 6.1. Entry values are the ones admitted for the 631 corresponding labels in the POST request for creating a group 632 configuration (see Section 4.3). A valid request MUST NOT include 633 the same entry multiple times. 635 When CoRAL is used, the filter criteria are specified in the request 636 payload with top-level elements, each of which corresponds to an 637 entry specified in Section 3.1, with the exception of the 'app_names' 638 status parameter. If names of application groups are used as filter 639 criteria, each element of the 'app_groups' array from the status 640 properties is included as a separate element with name 'app_group'. 641 With the exception of the 'app_group' element, a valid request MUST 642 NOT include the same element multiple times. Element values are the 643 ones admitted for the corresponding labels in the POST request for 644 creating a group configuration (see Section 4.3). 646 Example in custom CBOR and Link Format: 648 => 0.05 FETCH 649 Uri-Path: manage 650 Content-Format: TBD2 (application/ace-groupcomm+cbor) 652 { 653 "alg" : 10, 654 "hkdf" : 5 655 } 657 <= 2.05 Content 658 Content-Format: 40 (application/link-format) 660 ;rt="core.osc.gconf", 661 ;rt="core.osc.gconf", 662 ;rt="core.osc.gconf" 664 Example in CoRAL: 666 => 0.05 FETCH 667 Uri-Path: manage 668 Content-Format: TBD1 (application/coral+cbor) 670 alg 10 671 hkdf 5 673 <= 2.05 Content 674 Content-Format: TBD1 (application/coral+cbor) 676 #using 677 #base 678 item 679 item 680 item 682 4.3. Create a New Group Configuration 684 The Administrator can send a POST request to the group-collection 685 resource, in order to create a new OSCORE group at the Group Manager. 686 The request MAY specify the intended group name GROUPNAME and group 687 title, and MAY specify pieces of information concerning the group 688 configuration. 690 When custom CBOR is used, the request payload is a CBOR map, whose 691 possible entries are specified in Section 3.1 and use the same 692 abbreviations defined in Section 6.1. 694 When CoRAL is used, each element of the request payload corresponds 695 to an entry specified in Section 3.1, with the exception of the 696 'app_names' status parameter (see below). 698 In particular: 700 o The payload MAY include any of the configuration parameter defined 701 in Section 3.1.1. 703 o The payload MAY include any of the status parameter 'group_name', 704 'group_title', 'exp', 'app_groups, 'group_policies', 'as_uri' and 705 'active' defined in Section 3.1.2. 707 * When CoRAL is used, each element of the 'app_groups' array from 708 the status properties is included as a separate element with 709 name 'app_group'. 711 o The payload MUST NOT include any of the status parameter 'rt', 712 'ace-groupcomm-profile' and 'joining_uri' defined in 713 Section 3.1.2. 715 If any of the following occurs, the Group Manager MUST respond with a 716 4.00 (Bad Request) response, which MAY include additional information 717 to clarify what went wrong. 719 o Any of the received parameters is specified multiple times, with 720 the exception of the 'app_group' element when using CoRAL. 722 o Any of the received parameters is not recognized, or not valid, or 723 not consistent with respect to other related parameters. 725 o The 'group_name' parameter specifies the group name of an already 726 existing OSCORE group. 728 o The Group Manager does not trust the Authorization Server with URI 729 specified in the 'as_uri' parameter, and has no alternative 730 Authorization Server to consider for the OSCORE group to create. 732 After a successful processing of the request above, the Group Manager 733 performs the following actions. 735 First, the Group Manager creates a new group-configuration resource, 736 accessible to the Administrator at /manage/GROUPNAME, where GROUPNAME 737 is the name of the OSCORE group as either indicated in the parameter 738 'group_name' of the request or uniquely assigned by the Group 739 Manager. Note that the final decision about the name assigned to the 740 OSCORE group is of the Group Manager, which may have more constraints 741 than the Administrator can be aware of, possibly beyond the 742 availability of suggested names. 744 The value of the status parameter 'rt' is set to "core.osc.gconf". 745 The values of other parameters specified in the request are used as 746 group configuration information for the newly created OSCORE group. 747 For each configuration parameter not specified in the request, the 748 Group Manager MUST use default values as specified in Section 3.2. 750 After that, the Group Manager creates a new group-membership resource 751 accessible at ace-group/GROUPNAME to nodes that want to join the 752 OSCORE group, as specified in Section 6.2 of 753 [I-D.ietf-ace-key-groupcomm-oscore]. Note that such group 754 membership-resource comprises a number of sub-resources intended to 755 current group members, as defined in Section 4.1 of 756 [I-D.ietf-ace-key-groupcomm] and Section 5 of 757 [I-D.ietf-ace-key-groupcomm-oscore]. 759 From then on, the Group Manager will rely on the current group 760 configuration to build the Joining Response message defined in 761 Section 6.4 of [I-D.ietf-ace-key-groupcomm-oscore], when handling the 762 joining of a new group member. Furthermore, the Group Manager 763 generates the following pieces of information, and assigns them to 764 the newly created OSCORE group. 766 o The OSCORE Master Secret. 768 o The OSCORE Master Salt (optionally). 770 o The Group ID, used as OSCORE ID Context, which MUST be unique 771 within the set of OSCORE groups under the Group Manager. 773 Finally, the Group Manager replies to the Administrator with a 2.01 774 (Created) response. The Location-Path option MUST be included in the 775 response, indicating the location of the just created group- 776 configuration resource. The response MUST NOT include a Location- 777 Query option. 779 The response payload specifies the parameters 'group_name', 780 'joining_uri' and 'as_uri', from the status properties of the newly 781 created OSCORE group (see Section 3.1), as detailed below. 783 When custom CBOR is used, the response payload is a CBOR map, where 784 entries use the same abbreviations defined in Section 6.1. When 785 CoRAL is used, the response payload includes one element for each 786 specified parameter. 788 o 'group_name', with value the group name of the OSCORE group. This 789 value can be different from the group name possibly specified by 790 the Administrator in the POST request, and reflects the final 791 choice of the Group Manager as 'group_name' status property for 792 the OSCORE group. This parameter MUST be included. 794 o 'joining_uri', with value the URI of the group-membership resource 795 for joining the newly created OSCORE group. This parameter MUST 796 be included. 798 o 'as_uri', with value the URI of the Authorization Server 799 associated to the Group Manager for the newly created OSCORE 800 group. This parameter MUST be included if specified in the status 801 properties of the group. This value can be different from the URI 802 possibly specified by the Administrator in the POST request, and 803 reflects the final choice of the Group Manager as 'as_uri' status 804 property for the OSCORE group. 806 The Group Manager can register the link to the group-membership 807 resource with URI specified in 'joining_uri' to a Resource Directory 808 [I-D.ietf-core-resource-directory][I-D.hartke-t2trg-coral-reef], as 809 defined in Section 2 of [I-D.tiloca-core-oscore-discovery]. The 810 Group Manager considers the current group configuration when 811 specifying additional information for the link to register. 813 Alternatively, the Administrator can perform the registration in the 814 Resource Directory on behalf of the Group Manager, acting as 815 Commissioning Tool. The Administrator considers the following when 816 specifying additional information for the link to register. 818 o The name of the OSCORE group MUST take the value specified in 819 'group_name' from the 2.01 (Created) response above. 821 o The names of the application groups using the OSCORE group MUST 822 take the values possibly specified by the elements of the 823 'app_groups' parameter (when custom CBOR is used) or by the 824 different 'app_group' elements (when CoRAL is used) in the POST 825 request above. 827 o If present, parameters describing the cryptographic algorithms 828 used in the OSCORE group MUST follow the values that the 829 Administrator specified in the POST request above, or the 830 corresponding default values specified in Section 3.2.1 otherwise. 832 o If also registering a related link to the Authorization Server 833 associated to the OSCORE group, the related link MUST have as link 834 target the URI in 'as_uri' from the 2.01 (Created) response above, 835 if the 'as_uri' parameter was included in the response. 837 Note that, compared to the Group Manager, the Administrator is less 838 likely to remain closely aligned with possible changes and updates 839 that would require a prompt update to the registration in the 840 Resource Directory. This applies especially to the address of the 841 Group Manager, as well as the URI of the group-membership resource or 842 of the Authorization Server associated to the Group Manager. 844 Therefore, it is RECOMMENDED that registrations of links to group- 845 membership resources in the Resource Directory are made (and possibly 846 updated) directly by the Group Manager, rather than by the 847 Administrator. 849 Example in custom CBOR: 851 => 0.02 POST 852 Uri-Path: manage 853 Content-Format: TBD2 (application/ace-groupcomm+cbor) 855 { 856 "alg" : 10, 857 "hkdf" : 5, 858 "pairwise_mode" : True, 859 "active" : True, 860 "group_title" : "rooms 1 and 2", 861 "app_groups": : ["room1", "room2"], 862 "as_uri" : "coap://as.example.com/token" 863 } 865 <= 2.01 Created 866 Location-Path: manage 867 Location-Path: gp4 868 Content-Format: TBD2 (application/ace-groupcomm+cbor) 870 { 871 "group_name" : "gp4", 872 "joining_uri" : "coap://[2001:db8::ab]/ace-group/gp4/", 873 "as_uri" : "coap://as.example.com/token" 874 } 876 Example in CoRAL: 878 => 0.02 POST 879 Uri-Path: manage 880 Content-Format: TBD1 (application/coral+cbor) 882 #using 883 alg 10 884 hkdf 5 885 pairwise_mode True 886 active True 887 group_title "rooms 1 and 2" 888 app_group "room1" 889 app_group "room2" 890 as_uri 892 <= 2.01 Created 893 Location-Path: manage 894 Location-Path: gp4 895 Content-Format: TBD1 (application/coral+cbor) 897 #using 898 group_name "gp4" 899 joining_uri 900 as_uri 902 4.4. Retrieve a Group Configuration 904 The Administrator can send a GET request to the group-configuration 905 resource manage/GROUPNAME associated to an OSCORE group with group 906 name GROUPNAME, in order to retrieve the complete current 907 configuration of that group. 909 After a successful processing of the request above, the Group Manager 910 replies to the Administrator with a 2.05 (Content) response. The 911 response has as payload the representation of the group configuration 912 as specified in Section 3.1. The exact content of the payload 913 reflects the current configuration of the OSCORE group. This 914 includes both configuration properties and status properties. 916 When custom CBOR is used, the response payload is a CBOR map, whose 917 possible entries are specified in Section 3.1 and use the same 918 abbreviations defined in Section 6.1. 920 When CoRAL is used, the response payload includes one element for 921 each entry specified in Section 3.1, with the exception of the 922 'app_names' status parameter. That is, each element of the 923 'app_groups' array from the status properties is included as a 924 separate element with name 'app_group'. 926 Example in custom CBOR: 928 => 0.01 GET 929 Uri-Path: manage 930 Uri-Path: gp4 932 <= 2.05 Content 933 Content-Format: TBD2 (application/ace-groupcomm+cbor) 935 { 936 "alg" : 10, 937 "hkdf" : 5, 938 "cs_alg" : -8, 939 "cs_params" : [[1], [1, 6]], 940 "cs_key_params" : [1, 6], 941 "cs_key_enc" : 1, 942 "pairwise_mode" : True, 943 "ecdh_alg" : -27, 944 "ecdh_params" : [[1], [1, 6]], 945 "ecdh_key_params" : [1, 6], 946 "rt" : "core.osc.gconf", 947 "active" : True, 948 "group_name" : "gp4", 949 "group_title" : "rooms 1 and 2", 950 "ace-groupcomm-profile" : "coap_group_oscore_app", 951 "exp" : "1360289224", 952 "app_groups": : ["room1", "room2"], 953 "joining_uri" : "coap://[2001:db8::ab]/ace-group/gp4/", 954 "as_uri" : "coap://as.example.com/token" 955 } 957 Example in CoRAL: 959 => 0.01 GET 960 Uri-Path: manage 961 Uri-Path: gp4 963 <= 2.05 Content 964 Content-Format: TBD1 (application/coral+cbor) 966 #using 967 alg 10 968 hkdf 5 969 cs_alg -8 970 cs_params.alg_capab.key_type 1 971 cs_params.key_type_capab.key_type 1 972 cs_params.key_type_capab.curve 6 973 cs_key_params.key_type 1 974 cs_key_params.curve 6 975 cs_key_enc 1 976 pairwise_mode True 977 ecdh_alg -27 978 ecdh_params.alg_capab.key_type 1 979 ecdh_params.key_type_capab.key_type 1 980 ecdh_params.key_type_capab.curve 6 981 ecdh_key_params.key_type 1 982 ecdh_key_params.curve 6 983 rt "core.osc.gconf", 984 active True 985 group_name "gp4" 986 group_title "rooms 1 and 2" 987 ace-groupcomm-profile "coap_group_oscore_app" 988 exp "1360289224" 989 app_group "room1" 990 app_group "room2" 991 joining_uri 992 as_uri 994 4.5. Retrieve Part of a Group Configuration by Filters 996 The Administrator can send a FETCH request to the group-configuration 997 resource manage/GROUPNAME associated to an OSCORE group with group 998 name GROUPNAME, in order to retrieve part of the current 999 configuration of that group. 1001 When custom CBOR is used, the request payload is a CBOR map, which 1002 contains the following fields: 1004 o 'conf_filter', defined in Section 6.1 of this document and encoded 1005 as a CBOR array. Each element of the array specifies one 1006 requested configuration parameter or status parameter of the 1007 current group configuration (see Section 3.1), using the 1008 corresponding abbreviation defined in Section 6.1. 1010 When CoRAL is used, the request payload includes one element for each 1011 requested configuration parameter or status parameter of the current 1012 group configuration (see Section 3.1). All the specified elements 1013 have no value. 1015 After a successful processing of the request above, the Group Manager 1016 replies to the Administrator with a 2.05 (Content) response. The 1017 response has as payload a partial representation of the group 1018 configuration (see Section 3.1). The exact content of the payload 1019 reflects the current configuration of the OSCORE group, and is 1020 limited to the configuration properties and status properties 1021 requested by the Administrator in the FETCH request. 1023 The response payload includes the requested configuration parameters 1024 and status parameters, and is formatted as in the response payload of 1025 a GET request to a group-configuration resource (see Section 4.4). 1027 Example in custom CBOR: 1029 => 0.05 FETCH 1030 Uri-Path: manage 1031 Uri-Path: gp4 1032 Content-Format: TBD2 (application/ace-groupcomm+cbor) 1034 { 1035 "conf_filter" : ["alg", 1036 "hkdf", 1037 "pairwise_mode", 1038 "active", 1039 "group_title", 1040 "app_groups"] 1041 } 1043 <= 2.05 Content 1044 Content-Format: TBD2 (application/ace-groupcomm+cbor) 1046 { 1047 "alg" : 10, 1048 "hkdf" : 5, 1049 "pairwise_mode" : True, 1050 "active" : True, 1051 "group_title" : "rooms 1 and 2", 1052 "app_groups": : ["room1", "room2"] 1053 } 1055 Example in CoRAL: 1057 => 0.05 FETCH 1058 Uri-Path: manage 1059 Uri-Path: gp4 1060 Content-Format: TBD1 (application/coral+cbor) 1062 #using 1063 alg 1064 hkdf 1065 pairwise_mode 1066 active 1067 group_title 1068 app_groups 1070 <= 2.05 Content 1071 Content-Format: TBD1 (application/coral+cbor) 1073 #using 1074 alg 10 1075 hkdf 5 1076 pairwise_mode True 1077 active True 1078 group_title "rooms 1 and 2" 1079 app_group "room1" 1080 app_group "room2" 1082 4.6. Overwrite a Group Configuration 1084 The Administrator can send a PUT request to the group-configuration 1085 resource associated to an OSCORE group, in order to overwrite the 1086 current configuration of that group with a new one. The payload of 1087 the request has the same format of the POST request defined in 1088 Section 4.3, with the exception of the status parameter 'group_name' 1089 that MUST NOT be included. 1091 The error handling for the PUT request is the same as for the POST 1092 request defined in Section 4.3. If no error occurs, the Group 1093 Manager performs the following actions. 1095 First, the Group Manager updates the configuration of the OSCORE 1096 group, consistently with the values indicated in the PUT request from 1097 the Administrator. For each parameter not specified in the PUT 1098 request, the Group Manager MUST use the default value as specified in 1099 Section 3.2. From then on, the Group Manager relies on the latest 1100 updated configuration to build the Joining Response message defined 1101 in Section 6.4 of [I-D.ietf-ace-key-groupcomm-oscore], when handling 1102 the joining of a new group member. 1104 Then, the Group Manager replies to the Administrator with a 2.04 1105 (Changed) response. The payload of the response has the same format 1106 of the 2.01 (Created) response defined in Section 4.3. 1108 If the link to the group-membership resource was registered in the 1109 Resource Directory (see [I-D.ietf-core-resource-directory]), the GM 1110 is responsible to refresh the registration, as defined in Section 3 1111 of [I-D.tiloca-core-oscore-discovery]. 1113 Alternatively, the Administrator can update the registration in the 1114 Resource Directory on behalf of the Group Manager, acting as 1115 Commissioning Tool. The Administrator considers the following when 1116 specifying additional information for the link to update. 1118 o The name of the OSCORE group MUST take the value specified in 1119 'group_name' from the 2.04 (Changed) response above. 1121 o The names of the application groups using the OSCORE group MUST 1122 take the values possibly specified by the elements of the 1123 'app_groups' parameter (when custom CBOR is used) or by the 1124 different 'app_group' elements (when CoRAL is used) in the PUT 1125 request above. 1127 o If present, parameters describing the cryptographic algorithms 1128 used in the OSCORE group MUST follow the values that the 1129 Administrator specified in the PUT request above, or the 1130 corresponding default values as specified in Section 3.2.1 1131 otherwise. 1133 o If also registering a related link to the Authorization Server 1134 associated to the OSCORE group, the related link MUST have as link 1135 target the URI in 'as_uri' from the 2.04 (Changed) response above, 1136 if the 'as_uri' parameter was included in the response. 1138 As discussed in Section 4.3, it is RECOMMENDED that registrations of 1139 links to group-membership resources in the Resource Directory are 1140 made (and possibly updated) directly by the Group Manager, rather 1141 than by the Administrator. 1143 Example in custom CBOR: 1145 => PUT 1146 Uri-Path: manage 1147 Uri-Path: gp4 1148 Content-Format: TBD2 (application/ace-groupcomm+cbor) 1150 { 1151 "alg" : 11 , 1152 "hkdf" : 5 1153 } 1155 <= 2.04 Changed 1156 Content-Format: TBD2 (application/ace-groupcomm+cbor) 1158 { 1159 "group_name" : "gp4", 1160 "joining_uri" : "coap://[2001:db8::ab]/ace-group/gp4/", 1161 "as_uri" : "coap://as.example.com/token" 1162 } 1164 Example in CoRAL: 1166 => PUT 1167 Uri-Path: manage 1168 Uri-Path: gp4 1169 Content-Format: TBD1 (application/coral+cbor) 1171 #using 1172 alg 11 1173 hkdf 5 1175 <= 2.04 Changed 1176 Content-Format: TBD1 (application/coral+cbor) 1178 #using 1179 group_name "gp4" 1180 joining_uri 1181 as_uri 1183 4.6.1. Effects on Joining Nodes 1185 If the value of the status parameter 'active' is changed from True to 1186 False, the Group Manager MUST stop admitting new members in the 1187 OSCORE group. In particular, upon receiving a Joining Request (see 1188 Section 6.3 of [I-D.ietf-ace-key-groupcomm-oscore]), the Group 1189 Manager MUST respond with a 5.03 (Service Unavailable) response to 1190 the joining node, and MAY include additional information to clarify 1191 what went wrong. 1193 If the value of the status parameter 'active' is changed from False 1194 to True, the Group Manager resumes admitting new members in the 1195 OSCORE group, by processing their Joining Requests (see Section 6.3 1196 of [I-D.ietf-ace-key-groupcomm-oscore]). 1198 4.6.2. Effects on the Group Members 1200 After having updated a group configuration, the Group Manager informs 1201 the members of the OSCORE group, over the pairwise secure 1202 communication channels established when joining the group (see 1203 Section 6 of [I-D.ietf-ace-key-groupcomm-oscore]). 1205 To this end, the Group Manager can individually target the 1206 'control_path' URI of each group member (see Section 4.1.2.1 of 1207 [I-D.ietf-ace-key-groupcomm]), if provided by the intended recipient 1208 upon joining the OSCORE group (see Section 6.2 of 1209 [I-D.ietf-ace-key-groupcomm-oscore]). Alternatively, group members 1210 can subscribe for updates to the group-membership resource of the 1211 OSCORE group, e.g. by using CoAP Observe [RFC7641]. 1213 Every group member, upon learning that the OSCORE group has been 1214 deactivated (i.e. 'active' has value False), SHOULD stop 1215 communicating in the group. 1217 Every group member, upon learning that the OSCORE group has been 1218 reactivated (i.e. 'active' has value True again), can resume 1219 communicating in the group. 1221 Every group member, upon learning that the OSCORE group has stopped 1222 supporting the pairwise mode of Group OSCORE (i.e. 'pairwise_mode' 1223 has value False), SHOULD stop using the pairwise mode to process 1224 messages in the group. 1226 Every group member, upon learning that the OSCORE group has resumed 1227 supporting the pairwise mode of Group OSCORE (i.e. 'pairwise_mode' 1228 has value True again), can resume using the pairwise mode to process 1229 messages in the group. 1231 Every group member, upon receiving updated values for 'alg' and 1232 'hkdf', MUST either: 1234 o Leave the OSCORE group (see Section 16 of 1235 [I-D.ietf-ace-key-groupcomm-oscore]), e.g. if not supporting the 1236 indicated new algorithms; or 1238 o Use the new parameter values, and accordingly re-derive the OSCORE 1239 Security Context for the OSCORE group (see Section 2 of 1240 [I-D.ietf-core-oscore-groupcomm]). 1242 Every group member, upon receiving updated values for 'cs_alg', 1243 'cs_params', 'cs_key_params', 'cs_key_enc', 'ecdh_alg', 'ecdh_params' 1244 and 'ecdh_key_params' MUST either: 1246 o Leave the OSCORE group, e.g. if not supporting the indicated new 1247 algorithm, parameters and encoding; or 1249 o Leave the OSCORE group and rejoin it (see Section 6 of 1250 [I-D.ietf-ace-key-groupcomm-oscore]), providing the Group Manager 1251 with a public key which is compatible with the indicated new 1252 algorithm, parameters and encoding; or 1254 o Use the new parameter values, and, if required, provide the Group 1255 Manager with a new public key to use in the OSCORE group, as 1256 compatible with the indicated parameters (see Section 11 of 1257 [I-D.ietf-ace-key-groupcomm-oscore]). 1259 4.7. Delete a Group Configuration 1261 The Administrator can send a DELETE request to the group- 1262 configuration resource, in order to delete that OSCORE group. The 1263 deletion would be successful only on an inactive OSCORE group. 1265 That is, the DELETE request actually yields a successful deletion of 1266 the OSCORE group, only if the corresponding status parameter 'active' 1267 has current value False. The Administrator can ensure that, by first 1268 performing an update of the group-configuration resource associated 1269 to the OSCORE group (see Section 4.6), and setting the corresponding 1270 status parameter 'active' to False. 1272 If, upon receiving the DELETE request, the current value of the 1273 status parameter 'active' is True, the Group Manager MUST respond 1274 with a 4.09 (Conflict) response, which MAY include additional 1275 information to clarify what went wrong. 1277 After a successful processing of the request above, the Group Manager 1278 performs the following actions. 1280 First, the Group Manager deletes the OSCORE group and deallocates 1281 both the group-configuration resource as well as the group-membership 1282 resource associated to that group. 1284 Then, the Group Manager replies to the Administrator with a 2.02 1285 (Deleted) response. 1287 Example: 1289 => DELETE 1290 Uri-Path: manage 1291 Uri-Path: gp4 1293 <= 2.02 Deleted 1295 4.7.1. Effects on the Group Members 1297 After having deleted an OSCORE group, the Group Manager can inform 1298 the group members by means of the following two methods. When 1299 contacting a group member, the Group Manager uses the pairwise secure 1300 communication association established with that member during its 1301 joining process (see Section 6 of 1302 [I-D.ietf-ace-key-groupcomm-oscore]). 1304 o The Group Manager sends an individual request message to each 1305 group member, targeting the respective resource used to perform 1306 the group rekeying process (see Section 18 of 1307 [I-D.ietf-ace-key-groupcomm-oscore]). The Group Manager uses the 1308 same format of the Joining Response message in Section 6.4 of 1309 [I-D.ietf-ace-key-groupcomm-oscore], where only the parameters 1310 'gkty', 'key', and 'ace-groupcomm-profile' are present, and the 1311 'key' parameter is empty. 1313 o A group member may subscribe for updates to the group-membership 1314 resource associated to the OSCORE group. In particular, if this 1315 relies on CoAP Observe [RFC7641], a group member would receive a 1316 4.04 (Not Found) notification response from the Group Manager, 1317 since the group-configuration resource has been deallocated upon 1318 deleting the OSCORE group. 1320 When being informed about the deletion of the OSCORE group, a group 1321 member deletes the OSCORE Security Context that it stores as 1322 associated to that group, and possibly deallocates any dedicated 1323 control resource intended for the Group Manager that it has for that 1324 group. 1326 5. Security Considerations 1328 Security considerations are inherited from the ACE framework for 1329 Authentication and Authorization [I-D.ietf-ace-oauth-authz], and from 1330 the specific transport profile of ACE used between the Administrator 1331 and the Group Manager, such as [I-D.ietf-ace-dtls-authorize] and 1332 [I-D.ietf-ace-oscore-profile]. 1334 6. IANA Considerations 1336 This document has the following actions for IANA. 1338 6.1. ACE Groupcomm Parameters Registry 1340 IANA is asked to register the following entries in the "ACE Groupcomm 1341 Parameters" Registry defined in Section 8.5 of 1342 [I-D.ietf-ace-key-groupcomm]. 1344 +-----------------+----------+--------------+-------------------+ 1345 | Name | CBOR Key | CBOR Type | Reference | 1346 +-----------------+----------+--------------+-------------------+ 1347 | | | | | 1348 | hkdf | TBD | tstr / int | [[this document]] | 1349 | | | | | 1350 | alg | TBD | tstr / int | [[this document]] | 1351 | | | | | 1352 | cs_alg | TBD | tstr / int | [[this document]] | 1353 | | | | | 1354 | cs_params | TBD | array | [[this document]] | 1355 | | | | | 1356 | cs_key_params | TBD | array | [[this document]] | 1357 | | | | | 1358 | cs_key_enc | TBD | int | [[this document]] | 1359 | | | | | 1360 | pairwise_mode | TBD | simple value | [[this document]] | 1361 | | | | | 1362 | ecdh_alg | TBD | tstr / int / | [[this document]] | 1363 | | | simple value | | 1364 | | | | | 1365 | ecdh_params | TBD | array / | [[this document]] | 1366 | | | simple value | | 1367 | | | | | 1368 | ecdh_key_params | TBD | array / | [[this document]] | 1369 | | | simple value | | 1370 | | | | | 1371 | active | TBD | simple value | [[this document]] | 1372 | | | | | 1373 | group_name | TBD | tstr | [[this document]] | 1374 | | | | | 1375 | group_title | TBD | tstr / | [[this document]] | 1376 | | | simple value | | 1377 | | | | | 1378 | app_groups | TBD | array | [[this document]] | 1379 | | | | | 1380 | joining_uri | TBD | tstr | [[this document]] | 1381 | | | | | 1382 | as_uri | TBD | tstr | [[this document]] | 1383 | | | | | 1384 | conf_filter | TBD | array | [[this document]] | 1385 | | | | | 1386 +-----------------+----------+--------------+-------------------+ 1388 6.2. Resource Types 1390 IANA is asked to enter the following values into the Resource Type 1391 (rt=) Link Target Attribute Values subregistry within the Constrained 1392 Restful Environments (CoRE) Parameters registry defined in [RFC6690]. 1394 +----------------+------------------------------+-------------------+ 1395 | Value | Description | Reference | 1396 +----------------+------------------------------+-------------------+ 1397 | | | | 1398 | core.osc.gcoll | Group-collection resource | [[this document]] | 1399 | | of an OSCORE Group Manager | | 1400 | | | | 1401 | core.osc.gconf | Group-configuration resource | [[this document]] | 1402 | | of an OSCORE Group Manager | | 1403 | | | | 1404 +----------------+------------------------------+-------------------+ 1406 7. References 1408 7.1. Normative References 1410 [COSE.Algorithms] 1411 IANA, "COSE Algorithms", 1412 . 1415 [COSE.Elliptic.Curves] 1416 IANA, "COSE Elliptic Curves", 1417 . 1420 [COSE.Key.Types] 1421 IANA, "COSE Key Types", 1422 . 1425 [I-D.ietf-ace-key-groupcomm] 1426 Palombini, F. and M. Tiloca, "Key Provisioning for Group 1427 Communication using ACE", draft-ietf-ace-key-groupcomm-10 1428 (work in progress), November 2020. 1430 [I-D.ietf-ace-key-groupcomm-oscore] 1431 Tiloca, M., Park, J., and F. Palombini, "Key Management 1432 for OSCORE Groups in ACE", draft-ietf-ace-key-groupcomm- 1433 oscore-09 (work in progress), November 2020. 1435 [I-D.ietf-ace-oauth-authz] 1436 Seitz, L., Selander, G., Wahlstroem, E., Erdtman, S., and 1437 H. Tschofenig, "Authentication and Authorization for 1438 Constrained Environments (ACE) using the OAuth 2.0 1439 Framework (ACE-OAuth)", draft-ietf-ace-oauth-authz-35 1440 (work in progress), June 2020. 1442 [I-D.ietf-ace-oscore-profile] 1443 Palombini, F., Seitz, L., Selander, G., and M. Gunnarsson, 1444 "OSCORE Profile of the Authentication and Authorization 1445 for Constrained Environments Framework", draft-ietf-ace- 1446 oscore-profile-13 (work in progress), October 2020. 1448 [I-D.ietf-cbor-7049bis] 1449 Bormann, C. and P. Hoffman, "Concise Binary Object 1450 Representation (CBOR)", draft-ietf-cbor-7049bis-16 (work 1451 in progress), September 2020. 1453 [I-D.ietf-core-coral] 1454 Hartke, K., "The Constrained RESTful Application Language 1455 (CoRAL)", draft-ietf-core-coral-03 (work in progress), 1456 March 2020. 1458 [I-D.ietf-core-groupcomm-bis] 1459 Dijk, E., Wang, C., and M. Tiloca, "Group Communication 1460 for the Constrained Application Protocol (CoAP)", draft- 1461 ietf-core-groupcomm-bis-02 (work in progress), November 1462 2020. 1464 [I-D.ietf-core-oscore-groupcomm] 1465 Tiloca, M., Selander, G., Palombini, F., and J. Park, 1466 "Group OSCORE - Secure Group Communication for CoAP", 1467 draft-ietf-core-oscore-groupcomm-10 (work in progress), 1468 November 2020. 1470 [I-D.ietf-cose-rfc8152bis-algs] 1471 Schaad, J., "CBOR Object Signing and Encryption (COSE): 1472 Initial Algorithms", draft-ietf-cose-rfc8152bis-algs-12 1473 (work in progress), September 2020. 1475 [I-D.ietf-cose-rfc8152bis-struct] 1476 Schaad, J., "CBOR Object Signing and Encryption (COSE): 1477 Structures and Process", draft-ietf-cose-rfc8152bis- 1478 struct-14 (work in progress), September 2020. 1480 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1481 Requirement Levels", BCP 14, RFC 2119, 1482 DOI 10.17487/RFC2119, March 1997, 1483 . 1485 [RFC6690] Shelby, Z., "Constrained RESTful Environments (CoRE) Link 1486 Format", RFC 6690, DOI 10.17487/RFC6690, August 2012, 1487 . 1489 [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", 1490 RFC 6749, DOI 10.17487/RFC6749, October 2012, 1491 . 1493 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 1494 Application Protocol (CoAP)", RFC 7252, 1495 DOI 10.17487/RFC7252, June 2014, 1496 . 1498 [RFC7641] Hartke, K., "Observing Resources in the Constrained 1499 Application Protocol (CoAP)", RFC 7641, 1500 DOI 10.17487/RFC7641, September 2015, 1501 . 1503 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 1504 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 1505 May 2017, . 1507 [RFC8613] Selander, G., Mattsson, J., Palombini, F., and L. Seitz, 1508 "Object Security for Constrained RESTful Environments 1509 (OSCORE)", RFC 8613, DOI 10.17487/RFC8613, July 2019, 1510 . 1512 7.2. Informative References 1514 [I-D.hartke-t2trg-coral-reef] 1515 Hartke, K., "Resource Discovery in Constrained RESTful 1516 Environments (CoRE) using the Constrained RESTful 1517 Application Language (CoRAL)", draft-hartke-t2trg-coral- 1518 reef-04 (work in progress), May 2020. 1520 [I-D.ietf-ace-dtls-authorize] 1521 Gerdes, S., Bergmann, O., Bormann, C., Selander, G., and 1522 L. Seitz, "Datagram Transport Layer Security (DTLS) 1523 Profile for Authentication and Authorization for 1524 Constrained Environments (ACE)", draft-ietf-ace-dtls- 1525 authorize-14 (work in progress), October 2020. 1527 [I-D.ietf-core-resource-directory] 1528 Shelby, Z., Koster, M., Bormann, C., Stok, P., and C. 1529 Amsuess, "CoRE Resource Directory", draft-ietf-core- 1530 resource-directory-25 (work in progress), July 2020. 1532 [I-D.ietf-tls-dtls13] 1533 Rescorla, E., Tschofenig, H., and N. Modadugu, "The 1534 Datagram Transport Layer Security (DTLS) Protocol Version 1535 1.3", draft-ietf-tls-dtls13-38 (work in progress), May 1536 2020. 1538 [I-D.tiloca-core-oscore-discovery] 1539 Tiloca, M., Amsuess, C., and P. Stok, "Discovery of OSCORE 1540 Groups with the CoRE Resource Directory", draft-tiloca- 1541 core-oscore-discovery-07 (work in progress), November 1542 2020. 1544 [RFC6347] Rescorla, E. and N. Modadugu, "Datagram Transport Layer 1545 Security Version 1.2", RFC 6347, DOI 10.17487/RFC6347, 1546 January 2012, . 1548 [RFC8259] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 1549 Interchange Format", STD 90, RFC 8259, 1550 DOI 10.17487/RFC8259, December 2017, 1551 . 1553 Appendix A. Document Updates 1555 RFC EDITOR: PLEASE REMOVE THIS SECTION. 1557 A.1. Version -00 to -01 1559 o Names of application groups as status parameter. 1561 o Parameters related to the pairwise mode of Group OSCORE. 1563 o Defined FETCH for group-configuration resources. 1565 o Policies on registration of links to the Resource Directory. 1567 o Added resource type for group-configuration resources. 1569 o Fixes, clarifications and editorial improvements. 1571 Acknowledgments 1573 The authors sincerely thank Christian Amsuess, Carsten Bormann and 1574 Jim Schaad for their comments and feedback. 1576 The work on this document has been partly supported by VINNOVA and 1577 the Celtic-Next project CRITISEC; and by the H2020 project SIFIS-Home 1578 (Grant agreement 952652). 1580 Authors' Addresses 1582 Marco Tiloca 1583 RISE AB 1584 Isafjordsgatan 22 1585 Kista SE-16440 Stockholm 1586 Sweden 1588 Email: marco.tiloca@ri.se 1590 Rikard Hoeglund 1591 RISE AB 1592 Isafjordsgatan 22 1593 Kista SE-16440 Stockholm 1594 Sweden 1596 Email: rikard.hoglund@ri.se 1598 Peter van der Stok 1599 Consultant 1601 Phone: +31-492474673 (Netherlands), +33-966015248 (France) 1602 Email: consultancy@vanderstok.org 1603 URI: www.vanderstok.org 1605 Francesca Palombini 1606 Ericsson AB 1607 Torshamnsgatan 23 1608 Kista SE-16440 Stockholm 1609 Sweden 1611 Email: francesca.palombini@ericsson.com 1613 Klaus Hartke 1614 Ericsson AB 1615 Torshamnsgatan 23 1616 Kista SE-16440 Stockholm 1617 Sweden 1619 Email: klaus.hartke@ericsson.com