Admin Interface for the OSCORE Group Manager

1.1. Terminology

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.¶

Readers are expected to be familiar with the terms and concepts from the following specifications.¶

• CDDL [RFC8610], CBOR [RFC8949] and COSE [RFC9052][RFC9053].¶

• The CoAP protocol [RFC7252], also in group communication scenarios [I-D.ietf-core-groupcomm-bis]. These especially include the following concepts.¶

  • "application group", as a set of CoAP nodes that share a common set of resources.¶
  • "security group", as a set of CoAP nodes that share the same security material, and use it to protect and verify exchanged messages.¶

• The OSCORE [RFC8613] and Group OSCORE [I-D.ietf-core-oscore-groupcomm] security protocols. These especially include the following concepts.¶

  • Group Manager, as the entity responsible for a set of OSCORE groups where communications among members are secured using Group OSCORE. An OSCORE group is used as a security group for one or many application groups.¶
  • Authentication credential, as the set of information associated with an entity, including that entity's public key and parameters associated with the public key. Examples of authentication credentials are CBOR Web Tokens (CWTs) and CWT Claims Sets (CCSs) [RFC8392], X.509 certificates [RFC5280], and C509 certificates [I-D.ietf-cose-cbor-encoded-cert].¶
• The ACE framework for authentication and authorization [RFC9200]. The terminology for entities in the considered architecture is defined in OAuth 2.0 [RFC6749]. In particular, this includes Client (C), Resource Server (RS), and Authorization Server (AS).¶
• The management of keying material for groups in ACE [I-D.ietf-ace-key-groupcomm] and specifically for OSCORE groups [I-D.ietf-ace-key-groupcomm-oscore]. These include the concept of group-membership resource hosted by the Group Manager that new members access to join the OSCORE group, and that current members can access to retrieve updated keying material.¶

Note that the term "endpoint" is used here following its OAuth definition, aimed at denoting resources such as /token and /introspect at the AS, and /authz-info at the RS. This document does not use the CoAP definition of "endpoint", which is "An entity participating in the CoAP protocol".¶

This document also refers to the following terminology:¶

• Administrator: entity responsible for creating, configuring, and deleting OSCORE groups at a Group Manager.¶
• Group name: stable and invariant name of an OSCORE group. The group name MUST be unique under the same Group Manager, and MUST include only characters that are valid for a URI path segment.¶

• Group-collection resource: a single-instance resource hosted by the Group Manager. An Administrator accesses a group-collection resource to retrieve the list of existing OSCORE groups, or to create a new OSCORE group, under that Group Manager.¶

  As an example, this document uses /manage as the url-path of the group-collection resource; implementations are not required to use this name, and can define their own instead.¶

• Group-configuration resource: a resource hosted by the Group Manager, associated with an OSCORE group under that Group Manager. A group-configuration resource is identifiable with the invariant group name of the respective OSCORE group. An Administrator accesses a group-configuration resource to retrieve or change the configuration of the respective OSCORE group, or to delete that group.¶

  The url-path to a group-configuration resource has GROUPNAME as last segment, with GROUPNAME the invariant group name assigned upon its creation. Building on the considered url-path of the group-collection resource, this document uses /manage/GROUPNAME as the url-path of a group-configuration resource; implementations are not required to use this same construct, and can define their own instead.¶

• Admin resource: a group-collection resource or a group-configuration resource hosted by the Group Manager.¶

2.1. Managing OSCORE Groups

Figure 1 shows the resources of a Group Manager available to an Administrator.¶

The Group Manager exports a single group-collection resource, with resource type "core.osc.gcoll" registered in Section 10.3 of this document. The interface for the group-collection resource defined in Section 6 allows the Administrator to:¶

• Retrieve the list of existing OSCORE groups.¶
• Retrieve a list of existing OSCORE groups matching with specified filter criteria.¶
• Create a new OSCORE group, specifying its invariant group name and, optionally, its configuration.¶

The Group Manager exports one group-configuration resource for each of its OSCORE groups. Each group-configuration resource has resource type "core.osc.gconf" registered in Section 10.3 of this document, and is identified by the group name specified upon creating the OSCORE group. The interface for a group-configuration resource defined in Section 6 allows the Administrator to:¶

• Retrieve the complete current configuration of the OSCORE group.¶
• Retrieve part of the current configuration of the OSCORE group, by applying filter criteria.¶
• Overwrite the current configuration of the OSCORE group.¶
• Selectively update only part of the current configuration of the OSCORE group.¶
• Delete the OSCORE group.¶

2.2. Collection Representation

A collection of group configurations is represented as a Link Format document [RFC6690] containing the list of corresponding group-configuration resources.¶

Each group configuration is represented as a link, which specifies the URI of the group-configuration resource as link target, and the link target attribute 'rt' (Resource Type) with value "core.osc.gconf".¶

2.3. Discovery

The Administrator can discover group-collection resources from a Resource Directory [RFC9176] or from .well-known/core, by using the resource type "core.osc.gcoll".¶

The Administrator can discover group-configuration resources for the group-collection resource as specified in Section 6.1 and Section 6.2.¶

3.1. On Using Group Name Patterns

Having the object identifier ("Toid") specialized as a pattern confers a number of advantages.¶

• When relying on wildcard patterns and complex patterns, the encoded scope can be compact in size while allowing the Administrator to operate on large pools of group names.¶
• When relying on wildcard patterns and complex patterns, the Administrator and the AS do not need to know the exact group names for requesting and issuing an Access Token, respectively (see Section 4). In turn, the Group Manager can effectively take the final decision about the name to assign to an OSCORE group, upon its creation (see Section 6.3).¶

4.1. Multiple Administrators for the Same OSCORE Group

In addition to a "main" primary Administrator responsible for an OSCORE group at the Group Manager, it is also possible to have "assistant" secondary Administrators that are effectively authorized to perform some operations on the same OSCORE group.¶

With respect to the main Administrator, such assistant Administrators are expected to have fewer permissions to perform administrative operations related to the OSCORE group at the Group Manager. For example, they may not be authorized to create an OSCORE group, or to delete an OSCORE group and its configuration.¶

In case the main Administrator of an OSCORE group is dismissed or relinquishes its role, one of the assistant Administrators can be "promoted" and become main Administrator for that OSCORE group. Practically, this requires that the access policies associated with the promoted Administrator are updated accordingly at the Authorization Server. Also, the promoted Administrator has to request from the Authorization Server a new Access Token and to upload it to the Group Manager. If allowed by the used transport profile of ACE, this process can efficiently enforce a dynamic update of access rights, thus preserving the current secure association between the promoted Administrator and the Group Manager.¶

If an Administrator is not sure about being the only Administrator responsible for an OSCORE group, then it is RECOMMENDED that the Administrator ensures to have a recent representation of the group-configuration resource associated with the OSCORE group before overwriting (see Section 6.6), updating (see Section 6.7), or deleting (see Section 6.8) the group configuration. This can be achieved in the following ways.¶

• The Administrator performs a regular polling of the group configuration, by sending a GET request to the corresponding group-configuration resource (see Section 6.4).¶
• If the group-configuration resource associated with the OSCORE group is Observable, then the Administrator subscribes to that resource by using CoAP Observe [RFC7641]. The Observation request is a GET request sent to the group-configuration resource (see Section 6.4). In such a case, the Group Manager will also send a 4.04 (Not Found) response in case another Administrator deletes the group-configuration resource, as a result of deleting the associated OSCORE group and its configuration.¶

If the Administrator gains knowledge that the group configuration has changed compared to the latest known representation, then the Administrator might hold the execution of writing or deletion operation on the group-configuration resource, and first attempt checking with other Administrators responsible for the same OSCORE group about the changes they have made.¶

5.1. Group Configuration Representation

The group configuration representation is a CBOR map, which includes configuration properties and status properties.¶

5.2. Default Values

This section defines the default values that the Group Manager refers to for configuration and status parameters.¶

The Group Manager MAY choose different default values instead of those recommended in this section. A possible reason is to ensure that each of those are consistent with what the Group Manager supports, e.g., in terms of signature algorithm and format of authentication credentials used in the OSCORE group.¶

This ensures that the Group Manager is able to perform the operations defined in [I-D.ietf-ace-key-groupcomm-oscore], as to its interactions with joining nodes and current group members for an OSCORE group (see Section 14 of [I-D.ietf-ace-key-groupcomm-oscore]).¶

6.1. Retrieve the Full List of Group Configurations

This operation MUST be supported by the Group Manager and an Administrator.¶

The Administrator can send a GET request to the group-collection resource, in order to retrieve a list of the existing OSCORE groups at the Group Manager. This is returned as a list of links to the corresponding group-configuration resources.¶

The Group Manager MUST prepare the list L to include in the response as follows. For each group-configuration resource R:¶

1. The Group Manager considers the group name GROUPNAME of the OSCORE group associated with R.¶
2. The Group Manager retrieves the stored Access Token for the Administrator. Then, it checks whether GROUPNAME matches with the group name pattern specified in any scope entry of the 'scope' claim in the Access Token.¶
3. The link to the group-configuration resource R is added to the list L only in case of a positive match.¶

An example of message exchange is shown below.¶

=> 0.01 GET
   Uri-Path: manage

<= 2.05 Content
   Content-Format: 40 (application/link-format)

   Payload:

   <coap://[2001:db8::ab]/manage/gp1>;rt="core.osc.gconf",
   <coap://[2001:db8::ab]/manage/gp2>;rt="core.osc.gconf",
   <coap://[2001:db8::ab]/manage/gp3>;rt="core.osc.gconf"

6.2. Retrieve a List of Group Configurations by Filters

This operation MUST be supported by the Group Manager and MAY be supported by an Administrator.¶

The Administrator can send a FETCH request to the group-collection resource, in order to retrieve a list of the existing OSCORE groups that fully match a set of specified filter criteria. This is returned as a list of links to the corresponding group-configuration resources.¶

The filter criteria are specified in the request payload as a CBOR map, whose possible entries are specified in Section 5.1 and use the same abbreviations defined in Section 7.¶

Entry values are the ones admitted for the corresponding labels in the POST request for creating a group configuration (see Section 6.3), with the exception that the parameter 'group_name' (if present) can also be encoded as a tagged CBOR data item, specifying a group name pattern with the semantics signaled by the CBOR tag.¶

In such a case, the parameter 'group_name' expresses a group name pattern in the same way as a complex pattern Toid does in a scope entry (see Section 3). In particular, the filter criterion is satisfied by any group name that matches with the group name pattern specified by the parameter 'group_name' in the payload of the FETCH request.¶

The Group Manager MUST prepare the list L to include in the response as follows.¶

1. The Group Manager prepares a preliminary version of the list L, as specified in Section 6.1 for the processing of a GET request to the group-collection resource.¶
2. The Group Manager applies the filter criteria specified in the FETCH request to the list L from the previous step. The result is the list L to include in the response.¶

An example of message exchange is shown below.¶

=> 0.05 FETCH
   Uri-Path: manage
   Content-Format: CT_TBD (application/ace-groupcomm+cbor)

   Payload:

   {
       "group_mode" : true,
       "gp_enc_alg" : 10,
             "hkdf" : 5
   }

<= 2.05 Content
   Content-Format: 40 (application/link-format)

   Payload:

   <coap://[2001:db8::ab]/manage/gp1>;rt="core.osc.gconf",
   <coap://[2001:db8::ab]/manage/gp2>;rt="core.osc.gconf",
   <coap://[2001:db8::ab]/manage/gp3>;rt="core.osc.gconf"

The following, additional example considers a request payload that uses both configuration parameters and status parameters as filter criteria. In particular, the following is assumed.¶

• In the URI of every group-configuration resource, the path component is /manage/GROUPNAME, where GROUPNAME is the group name of the associated OSCORE group.¶
• The Group Manager hosts four group-configuration resources, for the OSCORE groups with names "gp4", "gp5", "gp6", and "foo". All the OSCORE groups use the AEAD Algorithm AES-CCM-16-64-128 (COSE algorithm encoding: 10). Also, all the OSCORE groups are currently active, except for "gp6".¶

=> 0.05 FETCH
   Uri-Path: manage
   Content-Format: CT_TBD (application/ace-groupcomm+cbor)

   Payload:

   {
       "gp_enc_alg" : 10,
       "group_name" : 21065("^gp[0-9]*$"),
           "active" : true
   }

<= 2.05 Content
   Content-Format: 40 (application/link-format)

   Payload:

   <coap://[2001:db8::ab]/manage/gp4>;rt="core.osc.gconf",
   <coap://[2001:db8::ab]/manage/gp5>;rt="core.osc.gconf"

6.3. Create a New Group Configuration

This operation MUST be supported by the Group Manager and an Administrator.¶

The Administrator can send a POST request to the group-collection resource, in order to create a new OSCORE group at the Group Manager. The request MUST specify the intended group name GROUPNAME, and MAY specify the intended group title together with pieces of information concerning the group configuration.¶

The request payload is a CBOR map, whose possible entries are specified in Section 5.1 and use the same abbreviations defined in Section 7. In particular:¶

• The payload MAY include any of the configuration parameters defined in Section 5.1.1.¶
• The payload MUST include the status parameter 'group_name' defined in Section 5.1.2 and specifying the intended group name encoded as a CBOR text string.¶
• The payload MAY include any of the status parameters 'active', 'group_description', 'max_stale_sets', 'exp', 'gid_reuse', 'app_groups', 'group_policies', and 'as_uri' defined in Section 5.1.2.¶
• The payload MUST NOT include any of the status parameters 'rt', 'ace_groupcomm_profile', and 'joining_uri' defined in Section 5.1.2.¶

Consistently with what is defined at step 4 of Section 4, the Group Manager MUST check whether the group name specified in the 'group_name' parameter matches with the group name pattern specified in any scope entry of the 'scope' claim in the stored Access Token for the Administrator. In case of a positive match, the Group Manager MUST check whether the permission set in the found scope entry specifies the permission "Create".¶

If the verification above fails (i.e., there are no matching scope entries specifying the "Create" permission), the Group Manager MUST reply with a 4.03 (Forbidden) error response.¶

If the group configuration to be created would include parameter values that prevent the Group Manager from performing the operations defined in [I-D.ietf-ace-key-groupcomm-oscore] (e.g., due to the Group Manager not supporting a format of authentication credentials), the Group Manager MUST respond with a 5.03 (Service Unavailable) response. The response MUST have Content-Format set to application/concise-problem-details+cbor [RFC9290] and is formatted as defined in Section 4.1.2 of [I-D.ietf-ace-key-groupcomm]. Within the Custom Problem Detail entry 'ace-groupcomm-error', the value of the 'error-id' field MUST be set to 12 ("Unsupported group configuration"), and the 'detail' field SHOULD be included in order to provide additional context.¶

Otherwise, if any of the following occurs, the Group Manager MUST respond with a 4.00 (Bad Request) response.¶

• Any of the received parameters is not recognized, or not valid, or not consistent with respect to other related parameters. In particular, the value of the status parameter 'exp' (if present) is not valid if the indicated expiration date is not in the future.¶
• The Group Manager does not trust the Authorization Server with URI specified in the 'as_uri' parameter, and has no alternative Authorization Server to consider for the OSCORE group to create.¶

After a successful processing of the POST request, the Group Manager performs the following actions.¶

If the 'group_name' parameter specifies the group name of an already existing OSCORE group, the Group Manager MUST try to determine an alternative name for the new OSCORE group to create.¶

In addition to that, the final decision about the name assigned to the new OSCORE group is always of the Group Manager, which may have more constraints than the Administrator can be aware of, possibly beyond the availability of suggested names. For example, the Group Manager may specifically want to use a randomized character string as the name of a newly created group.¶

If the Group Manager has selected a name GROUPNAME different from the name GROUPNAME* indicated in the parameter 'group_name' of the request, then the following conditions MUST hold.¶

• The chosen name GROUPNAME is available to assign; and¶
• With reference to the 'scope' claim in the stored Access Token for the Administrator, let us define PERM* as the union of the permission sets associated with the scope entries such that GROUPNAME* matches with the specified group name pattern. Also, let us define PERM as the union of the permission sets associated with the scope entries such that GROUPNAME matches with the specified group name pattern. Then, PERM and PERM* MUST be equal.¶

If the Group Manager does not manage to determine a group name for which both the above conditions hold, the Group Manager MUST respond with a 5.03 (Service Unavailable) response. The response MUST have Content-Format set to application/concise-problem-details+cbor [RFC9290] and is formatted as defined in Section 4.1.2 of [I-D.ietf-ace-key-groupcomm]. Within the Custom Problem Detail entry 'ace-groupcomm-error', the value of the 'error-id' field MUST be set to 11 ("Unable to determine a group name").¶

Otherwise, the Group Manager creates a new group-configuration resource, accessible to the Administrator at /manage/GROUPNAME, where GROUPNAME is the name of the OSCORE group as either indicated in the parameter 'group_name' of the request or uniquely assigned by the Group Manager. The group-collection resource is also accordingly updated.¶

The operation of creating the new group-configuration resource and accordingly updating the group-collection resource MUST be atomic.¶

The value of the status parameter 'rt' is set to "core.osc.gconf". The values of other parameters specified in the request are used as group configuration information for the newly created OSCORE group.¶

If the request specifies the parameter 'gid_reuse' encoding the CBOR simple value true (0xf5) and the Group Manager does not support the reassignment of OSCORE Group ID values (see Section 3.2.1.1 of [I-D.ietf-core-oscore-groupcomm] and Section 11 of [I-D.ietf-ace-key-groupcomm-oscore]), then the Group Manager sets the value of the 'gid_reuse' status parameter in the group-configuration resource to the CBOR simple value false (0xf4).¶

For each parameter not specified in the request, the Group Manager refers to the default values specified in Section 5.2.¶

After that, the Group Manager creates a new group-membership resource accessible at /ace-group/GROUPNAME to nodes that want to join the OSCORE group, as specified in Section 6.1 of [I-D.ietf-ace-key-groupcomm-oscore]. Note that such group membership-resource comprises a number of sub-resources intended to current group members, as defined in Section 4.1 of [I-D.ietf-ace-key-groupcomm] and Section 8 of [I-D.ietf-ace-key-groupcomm-oscore].¶

From then on, the Group Manager will rely on the current group configuration to build the Join Response message defined in Section 6.3 of [I-D.ietf-ace-key-groupcomm-oscore], when handling the joining of a new group member. Furthermore, the Group Manager generates the following pieces of information, and assigns them to the newly created OSCORE group:¶

• The OSCORE Master Secret.¶
• The OSCORE Master Salt (optionally).¶
• The Group ID, used as OSCORE ID Context, which MUST be unique within the set of OSCORE groups under the Group Manager.¶

Finally, the Group Manager replies to the Administrator with a 2.01 (Created) response. The Location-Path option MUST be included in the response, indicating the location of the just created group-configuration resource. The response MUST NOT include a Location-Query option.¶

The response payload specifies the parameters 'group_name', 'joining_uri', and 'as_uri', from the status properties of the newly created OSCORE group (see Section 5.1), as detailed below.¶

The response payload is a CBOR map, where entries use the same abbreviations defined in Section 7.¶

• 'group_name', with value the group name of the OSCORE group. This value can be different from the group name possibly specified by the Administrator in the POST request, and reflects the final choice of the Group Manager as 'group_name' status property for the OSCORE group. This parameter MUST be included.¶
• 'joining_uri', with value the URI of the group-membership resource for joining the newly created OSCORE group. This parameter MUST be included.¶
• 'as_uri', with value the URI of the Authorization Server associated with the Group Manager for the newly created OSCORE group. This parameter MUST be included. Its value can be different from the URI possibly specified by the Administrator in the POST request, and reflects the final choice of the Group Manager as 'as_uri' status property for the OSCORE group.¶

If the POST request specified the parameter 'gid_reuse' encoding the CBOR simple value true (0xf5) but the Group Manager has set the value of the 'gid_reuse' status parameter in the group-configuration resource to the CBOR simple value false (0xf4), then the response payload MUST include also the parameter 'gid_reuse' encoding the CBOR simple value false (0xf4).¶

If the POST request did not specify certain parameters and the Group Manager used default values different from the ones recommended in Section 5.2, then the response payload MUST also include those parameters, specifying the values chosen by the Group Manager for the current group configuration.¶

The Group Manager can register the link to the group-membership resource with URI specified in 'joining_uri' to a Resource Directory [RFC9176], as defined in Section 2 of [I-D.tiloca-core-oscore-discovery]. The Group Manager considers the current group configuration when specifying additional information for the link to register.¶

Alternatively, the Administrator can perform the registration in the Resource Directory on behalf of the Group Manager, acting as Commissioning Tool. The Administrator considers the following when specifying additional information for the link to register.¶

• The name of the OSCORE group MUST take the value specified in 'group_name' from the 2.01 (Created) response.¶
• The names of the application groups using the OSCORE group MUST take the values possibly specified by the elements of the 'app_groups' parameter in the POST request.¶
• If also registering a related link to the Authorization Server associated with the OSCORE group, the related link MUST have as link target the URI in 'as_uri' from the 2.01 (Created) response.¶

• As to every other information element describing the current group configuration, the following applies.¶

  • If a certain parameter was specified in the POST request, the Administrator MUST use either the value specified in the 2.01 (Created) response, if the Group Manager specified one, or the value specified in the POST request otherwise.¶
  • If a certain parameter was not specified in the POST request, the Administrator MUST use either the value specified in the 2.01 (Created) response, if the Group Manager specified one, or the corresponding default value recommended in Section 5.2.1 otherwise.¶

Note that, compared to the Group Manager, the Administrator is less likely to remain closely aligned with possible changes and updates that would require a prompt update to the registration in the Resource Directory. This applies especially to the address of the Group Manager, as well as the URI of the group-membership resource or of the Authorization Server associated with the Group Manager.¶

Therefore, it is RECOMMENDED that registrations of links to group-membership resources in the Resource Directory are made (and possibly updated) directly by the Group Manager, rather than by the Administrator.¶

An example of message exchange is shown below.¶

=> 0.02 POST
   Uri-Path: manage
   Content-Format: CT_TBD (application/ace-groupcomm+cbor)

   Payload:

   {
            "gp_enc_alg" : 10,
                  "hkdf" : 5,
         "pairwise_mode" : true,
                "active" : true,
            "group_name" : "gp4",
     "group_description" : "rooms 1 and 2",
            "app_groups" : ["room1", "room2"],
                "as_uri" : "coap://as.example.com/token"
   }

<= 2.01 Created
   Location-Path: manage
   Location-Path: gp4
   Content-Format: CT_TBD (application/ace-groupcomm+cbor)

   Payload:

   {
      "group_name" : "gp4",
     "joining_uri" : "coap://[2001:db8::ab]/ace-group/gp4/",
          "as_uri" : "coap://as.example.com/token"
   }

6.4. Retrieve a Group Configuration

This operation MUST be supported by the Group Manager and an Administrator.¶

The Administrator can send a GET request to the group-configuration resource manage/GROUPNAME associated with an OSCORE group with group name GROUPNAME, in order to retrieve the complete current configuration of that group.¶

Consistently with what is defined at step 4 of Section 4, the Group Manager MUST check whether GROUPNAME matches with the group name pattern specified in any scope entry of the 'scope' claim in the stored Access Token for the Administrator. In case of a positive match, the Group Manager MUST check whether the permission set in the found scope entry specifies the permission "Read".¶

If the verification above fails (i.e., there are no matching scope entries specifying the "Read" permission), the Group Manager MUST reply with a 4.03 (Forbidden) error response.¶

Otherwise, after a successful processing of the GET request, the Group Manager replies to the Administrator with a 2.05 (Content) response. The response has as payload the representation of the group configuration as specified in Section 5.1. The exact content of the payload reflects the current configuration of the OSCORE group. This includes both configuration properties and status properties.¶

The response payload is a CBOR map, whose possible entries are specified in Section 5.1 and use the same abbreviations defined in Section 7.¶

An example of message exchange is shown below.¶

=> 0.01 GET
   Uri-Path: manage
   Uri-Path: gp4

<= 2.05 Content
   Content-Format: CT_TBD (application/ace-groupcomm+cbor)

   Payload:

   {
                      "hkdf" : 5,
                  "cred_fmt" : 33,
                "group_mode" : true,
                "gp_enc_alg" : 10,
                  "sign_alg" : -8,
               "sign_params" : [[1], [1, 6]],
             "pairwise_mode" : true,
                       "alg" : 10,
                  "ecdh_alg" : -27,
               "ecdh_params" : [[1], [1, 6]],
                   "det_req" : false,
                        "rt" : "core.osc.gconf",
                    "active" : true,
                "group_name" : "gp4",
         "group_description" : "rooms 1 and 2",
     "ace_groupcomm_profile" : "coap_group_oscore_app",
            "max_stale_sets" : 3,
                       "exp" : 1360289224,
                 "gid_reuse" : false,
                "app_groups" : ["room1", "room2"],
               "joining_uri" : "coap://[2001:db8::ab]/ace-group/gp4/",
                    "as_uri" : "coap://as.example.com/token"
   }

6.5. Retrieve Part of a Group Configuration by Filters

This operation MUST be supported by the Group Manager and MAY be supported by an Administrator.¶

The Administrator can send a FETCH request to the group-configuration resource manage/GROUPNAME associated with an OSCORE group with group name GROUPNAME, in order to retrieve part of the current configuration of that group.¶

The request payload is a CBOR map, which contains the following field:¶

• 'conf_filter', encoded as a CBOR array. Each element of the array specifies one requested configuration parameter or status parameter of the current group configuration (see Section 5.1), encoded with the corresponding CBOR abbreviation defined in Section 7.¶

The Group Manager MUST perform the same authorization checks defined for the processing of a GET request to a group-configuration resource in Section 6.4. That is, the Group Manager MUST verify that the Administrator has been granted a "Read" permission applicable to the targeted group-configuration resource.¶

After a successful processing of the FETCH request, the Group Manager replies to the Administrator with a 2.05 (Content) response. The response has as payload a partial representation of the group configuration (see Section 5.1). The exact content of the payload reflects the current configuration of the OSCORE group, and is limited to the configuration properties and status properties requested by the Administrator in the FETCH request.¶

The response payload includes the requested configuration parameters and status parameters, and is formatted as in the response payload of a GET request to a group-configuration resource (see Section 6.4). If the request payload specifies a parameter that is not included in the group configuration, then the response payload MUST NOT include a corresponding parameter.¶

An example of message exchange is shown below.¶

=> 0.05 FETCH
   Uri-Path: manage
   Uri-Path: gp4
   Content-Format: CT_TBD (application/ace-groupcomm+cbor)

   Payload:

   {
     "conf_filter" : ["gp_enc_alg",
                      "hkdf",
                      "pairwise_mode",
                      "active",
                      "group_description",
                      "app_groups"]
   }

<= 2.05 Content
   Content-Format: CT_TBD (application/ace-groupcomm+cbor)

   Payload:

   {
            "gp_enc_alg" : 10,
                  "hkdf" : 5,
         "pairwise_mode" : true,
                "active" : true,
     "group_description" : "rooms 1 and 2",
            "app_groups" : ["room1", "room2"]
   }

6.6. Overwrite a Group Configuration

This operation MAY be supported by the Group Manager and an Administrator.¶

The Administrator can send a PUT request to the group-configuration resource manage/GROUPNAME associated with an OSCORE group with group name GROUPNAME, in order to overwrite the current configuration of that group with a new one.¶

The payload of the request has the same format of the POST request defined in Section 6.3, with the exception that the configuration parameters 'group_mode' and 'pairwise_mode' as well as the status parameters 'group_name' and 'gid_reuse' MUST NOT be included.¶

The error handling for the PUT request is the same as for the POST request defined in Section 6.3, with the following difference in terms of authorization checks.¶

Consistently with what is defined at step 4 of Section 4, the Group Manager MUST check whether GROUPNAME matches with the group name pattern specified in any scope entry of the 'scope' claim in the stored Access Token for the Administrator. In case of a positive match, the Group Manager MUST check whether the permission set in the found scope entry specifies the permission "Write".¶

If the verification above fails (i.e., there are no matching scope entries specifying the "Write" permission), the Group Manager MUST reply with a 4.03 (Forbidden) error response.¶

If the group-configuration resource targeted by the PUT request does not currently exist, then the Group Manager MUST NOT create the resource and MUST reply with a 4.04 (Not Found) error response.¶

If the updated group configuration would include parameter values that prevent the Group Manager from performing the operations defined in [I-D.ietf-ace-key-groupcomm-oscore] (e.g., due to the Group Manager not supporting a format of authentication credentials), the Group Manager MUST respond with a 5.03 (Service Unavailable) response. The response MUST have Content-Format set to application/concise-problem-details+cbor [RFC9290] and is formatted as defined in Section 4.1.2 of [I-D.ietf-ace-key-groupcomm]. Within the Custom Problem Detail entry 'ace-groupcomm-error', the value of the 'error-id' field MUST be set to 12 ("Unsupported group configuration"), and the 'detail' field SHOULD be included in order to provide additional context.¶

If no error occurs and the PUT request is successfully processed, the Group Manager performs the following actions.¶

First, the Group Manager updates the group-configuration resource, consistently with the values indicated in the PUT request from the Administrator. When doing so, the configuration parameters 'group_mode' and 'pairwise_mode' as well as the status parameters 'group_name' and 'gid_reuse' MUST remain unchanged.¶

For each other parameter not specified in the PUT request, the Group Manager MUST use default values as specified in Section 5.2. Note that the default value recommended for the status parameter 'active' is the CBOR simple value false (0xf4). Therefore, if the Administrator intends to preserve the current status of the group as active, then the payload of the PUT request has to include the parameter 'active' specifying the CBOR simple value true (0xf5).¶

When updating the group-configuration resource, the corresponding group-membership resource is also accordingly updated. The overwriting of such two resources MUST be atomic.¶

If a new value N' is specified for the 'max_stale_sets' status parameter and N' is smaller than the current value N, the Group Manager preserves the (up to) N' most recent sets of stale OSCORE Sender IDs associated with the group, and deletes any possible older set (see Section 7.1 of [I-D.ietf-ace-key-groupcomm-oscore]).¶

From then on, the Group Manager relies on the latest updated configuration to build the Join Response message defined in Section 6.3 of [I-D.ietf-ace-key-groupcomm-oscore], when handling the joining of a new group member. Similarly, the Group Manager relies on the new group configuration when building responses specifying (part of) the group configuration to a current group member. For instance, this applies when a group member retrieves from the Group Manager the updated group keying material (see Section 9.1 of [I-D.ietf-ace-key-groupcomm-oscore]) or the current group status (see Section 9.9 of [I-D.ietf-ace-key-groupcomm-oscore]).¶

Then, the Group Manager replies to the Administrator with a 2.04 (Changed) response. The payload of the response has the same format of the 2.01 (Created) response defined in Section 6.3.¶

If the PUT request did not specify certain parameters and the Group Manager used default values different from the ones recommended in Section 5.2, then the response payload MUST include also those parameters, specifying the values chosen by the Group Manager for the current group configuration.¶

If the link to the group-membership resource was registered in the Resource Directory [RFC9176], the Group Manager is responsible to refresh the registration, as defined in Section 3 of [I-D.tiloca-core-oscore-discovery].¶

Alternatively, the Administrator can update the registration in the Resource Directory on behalf of the Group Manager, acting as Commissioning Tool. The Administrator considers the following when specifying additional information for the link to update.¶

• The name of the OSCORE group MUST take the value specified in 'group_name' from the 2.04 (Changed) response.¶
• The names of the application groups using the OSCORE group MUST take the values possibly specified by the elements of the 'app_groups' parameter in the PUT request.¶
• If also registering a related link to the Authorization Server associated with the OSCORE group, the related link MUST have as link target the URI in 'as_uri' from the 2.04 (Changed) response.¶

• As to every other information element describing the current group configuration, the following applies.¶

  • If a certain parameter was specified in the PUT request, the Administrator MUST use either the value specified in the 2.04 (Changed) response, if the Group Manager specified one, or the value specified in the PUT request otherwise.¶
  • If a certain parameter was not specified in the PUT request, the Administrator MUST use either the value specified in the 2.04 (Changed) response, if the Group Manager specified one, or the corresponding default value recommended in Section 5.2.1 otherwise.¶

As discussed in Section 6.3, it is RECOMMENDED that registrations of links to group-membership resources in the Resource Directory are made (and possibly updated) directly by the Group Manager, rather than by the Administrator.¶

An example of message exchange is shown below.¶

=> 0.03 PUT
   Uri-Path: manage
   Uri-Path: gp4
   Content-Format: CT_TBD (application/ace-groupcomm+cbor)

   Payload:

   {
       "gp_enc_alg" : 11,
             "hkdf" : 5
   }

<= 2.04 Changed
   Content-Format: CT_TBD (application/ace-groupcomm+cbor)

   Payload:

   {
      "group_name" : "gp4",
     "joining_uri" : "coap://[2001:db8::ab]/ace-group/gp4/",
          "as_uri" : "coap://as.example.com/token"
   }

6.7. Selective Update of a Group Configuration

This operation MAY be supported by the Group Manager and an Administrator.¶

The Administrator can send a PATCH/iPATCH request [RFC8132] to the group-configuration resource manage/GROUPNAME associated with an OSCORE group with group name GROUPNAME, in order to update the value of only part of the group configuration.¶

The request payload has the same format of the PUT request defined in Section 6.6, with the difference that it MAY also specify names of application groups to be removed from or added to the 'app_groups' status parameter. The names of such application groups are provided as defined below.¶

The CBOR map in the request payload includes the field 'app_groups_diff', whose CBOR abbreviation is defined in Section 7. This field is encoded as a CBOR array including the following two elements.¶

• The first element is a CBOR array, namely 'app_groups_del'. Each of its elements is a CBOR text string, with value the name of an application group to remove from the 'app_groups' status parameter.¶
• The second element is a CBOR array, namely 'app_groups_add'. Each of its elements is a CBOR text string, with value the name of an application group to add to the 'app_groups' status parameter.¶

The CDDL definition [RFC8610] of the CBOR array 'app_groups_diff' formatted as in the request from the Administrator is provided below.¶

   app-group-name = tstr
   name-patch = [* app-group-name]
   app_groups_diff = [app_groups_del: name-patch,
                      app_groups_add: name-patch]

The Group Manager MUST respond with a 4.00 (Bad Request) response in case: both the inner CBOR arrays 'app_groups_del' and 'app_groups_add' are empty; or the CBOR map in the request payload includes both the 'app_groups' field and the 'app_groups_diff' field.¶

The error handling for the PATCH/iPATCH request is the same as for the PUT request defined in Section 6.6, with the following additions.¶

• The set of group configuration parameters to update MUST NOT be empty. That is, the Group Manager MUST respond with a 4.00 (Bad Request) response, if the request payload includes an empty CBOR map.¶
• If the Request-URI does not point to an existing group-configuration resource, the Group Manager MUST NOT create a new resource, and MUST respond with a 4.04 (Not Found) response.¶

• When applying the specified updated values would yield an inconsistent group configuration, the Group Manager MUST respond with a 4.09 (Conflict) response.¶

  The response MAY include the current representation of the group configuration resource, like when responding to a GET request as defined in Section 6.4. Otherwise, the response SHOULD include a diagnostic payload with additional information for the Administrator to recognize the source of the conflict.¶

• When the request uses specifically the iPATCH method, the Group Manager MUST respond with a 4.00 (Bad Request) response, in case the CBOR map includes the parameter 'app_groups_diff'.¶

Furthermore, the Group Manager MUST perform the same authorization checks defined for the processing of a PUT request to a group-configuration resource in Section 6.6. That is, the Group Manager MUST verify that the Administrator has been granted a "Write" permission applicable to the targeted group-configuration resource.¶

If the updated group configuration would include parameter values that prevent the Group Manager from performing the operations defined in [I-D.ietf-ace-key-groupcomm-oscore] (e.g., due to the Group Manager not supporting a format of authentication credentials), the Group Manager MUST respond with a 5.03 (Service Unavailable) response. The response MUST have Content-Format set to application/concise-problem-details+cbor [RFC9290] and is formatted as defined in Section 4.1.2 of [I-D.ietf-ace-key-groupcomm]. Within the Custom Problem Detail entry 'ace-groupcomm-error', the value of the 'error-id' field MUST be set to 12 ("Unsupported group configuration"), and the 'detail' field SHOULD be included in order to provide additional context.¶

If no error occurs and the PATCH/iPATCH request is successfully processed, the Group Manager performs the following actions.¶

First, the Group Manager updates the group-configuration resource, consistently with the values indicated in the PATCH/iPATCH request from the Administrator. The corresponding group-membership resource is also accordingly updated.¶

The operation of updating the group-configuration resource and accordingly updating the group-membership resource MUST be atomic.¶

Unlike for the PUT request defined in Section 6.6, the Group Manager does not alter the value of configuration parameters and status parameters for which updated values are not specified in the request payload. In particular, the Group Manager does not assign possible default values to those parameters.¶

Special processing occurs when updating the 'app_groups' status parameter by difference, as defined below. The Administrator should not expect the Group Manager to add or delete names of application group names according to any particular order.¶

• If the name of an application group to add (delete) is specified multiple times, the Group Manager considers it only once for addition to (deletion from) the 'app_groups' status parameter.¶
• If the name of an application group to delete is not present in the 'app_groups' status parameter before any change is applied, the Group Manager ignores that name.¶
• If the name of an application group to add is already present in the 'app_groups' status parameter before any change is applied, the Group Manager ignores that name.¶
• The Group Manager deletes from the 'app_groups' status parameter the names of the application groups specified in the inner 'app_groups_del' CBOR array of the 'app_groups_diff' field.¶
• The Group Manager adds to the 'app_groups' status parameter the names of the application groups specified in the inner 'app_groups_add' CBOR array of the 'app_groups_diff' field.¶

After having updated the group-configuration resource, from then on the Group Manager relies on the new group configuration to build the Join Response message defined in Section 6.3 of [I-D.ietf-ace-key-groupcomm-oscore], when handling the joining of a new group member. Similarly, the Group Manager relies on the new group configuration when building responses specifying (part of) the group configuration to a current group member. For instance, this applies when a group member retrieves from the Group Manager the updated group keying material (see Section 9.1 of [I-D.ietf-ace-key-groupcomm-oscore]) or the current group status (see Section 9.9 of [I-D.ietf-ace-key-groupcomm-oscore]).¶

Finally, the Group Manager replies to the Administrator with a 2.04 (Changed) response. The payload of the response has the same format of the 2.01 (Created) response defined in Section 6.3.¶

The same considerations as for the PUT request defined in Section 6.6 hold also in this case, with respect to refreshing a possible registration of the link to the group-membership resource in the Resource Directory [RFC9176].¶

An example of message exchange is shown below.¶

=> 0.06 PATCH
   Uri-Path: manage
   Uri-Path: gp4
   Content-Format: CT_TBD (application/ace-groupcomm+cbor)

   Payload:

   {
          "gp_enc_alg" : 10,
     "app_groups_diff" : [["room1"],
                          ["room3", "room4"]]
   }

<= 2.04 Changed
   Content-Format: CT_TBD (application/ace-groupcomm+cbor)

   Payload:

   {
      "group_name" : "gp4",
     "joining_uri" : "coap://[2001:db8::ab]/ace-group/gp4/",
          "as_uri" : "coap://as.example.com/token"
   }

6.8. Delete a Group Configuration

This operation MUST be supported by the Group Manager and an Administrator.¶

The Administrator can send a DELETE request to the group-configuration resource manage/GROUPNAME associated with an OSCORE group with group name GROUPNAME, in order to delete that OSCORE group.¶

Consistently with what is defined at step 4 of Section 4, the Group Manager MUST check whether GROUPNAME matches with the group name pattern specified in any scope entry of the 'scope' claim in the stored Access Token for the Administrator. In case of a positive match, the Group Manager MUST check whether the permission set in the found scope entry specifies the permission "Delete".¶

If the verification above fails (i.e., there are no matching scope entries specifying the "Delete" permission), the Group Manager MUST reply with a 4.03 (Forbidden) error response.¶

Otherwise, the Group Manager continues processing the request, which would be successful only on an inactive OSCORE group. That is, the DELETE request actually yields a successful deletion of the OSCORE group only if the corresponding status parameter 'active' has current value false (0xf4). The Administrator can ensure that, by first performing an update of the group-configuration resource associated with the OSCORE group (see Section 6.6), and setting the corresponding status parameter 'active' to false (0xf4).¶

If, upon receiving the DELETE request, the current value of the status parameter 'active' is true (0xf5), the Group Manager MUST respond with a 4.09 (Conflict) response. The response MUST have Content-Format set to application/concise-problem-details+cbor [RFC9290] and is formatted as defined in Section 4.1.2 of [I-D.ietf-ace-key-groupcomm]. Within the Custom Problem Detail entry 'ace-groupcomm-error', the value of the 'error-id' field MUST be set to 10 ("Group currently active").¶

After a successful processing of the DELETE request, the Group Manager performs the following actions.¶

First, the Group Manager deletes the OSCORE group, deallocates both the group-configuration resource as well as the group-membership resource associated with that group, and accordingly updates the group-collection resource.¶

The operation of deleting the group-configuration resource and the corresponding group-membership resource, as well as of accordingly updating the group-collection resource MUST be atomic.¶

Then, the Group Manager replies to the Administrator with a 2.02 (Deleted) response.¶

An example of message exchange is shown below.¶

=> 0.04 DELETE
   Uri-Path: manage
   Uri-Path: gp4

<= 2.02 Deleted

9.1. Change of Group Configuration

With respect to changing group configurations, the following security considerations hold.¶

• A change of the current group configuration (see Section 6.6 and Section 6.7) might result in generating and distributing new group keying material, consistently with the newly enforced algorithms and related parameters. In such a case, the Group Manager can perform a group rekeying as per Section 11 of [I-D.ietf-ace-key-groupcomm-oscore], or provide the new group keying material together with the new group configuration as per Section 6.6 and Section 6.7 of this document.¶

  After gaining knowledge of the new group configuration, current group members may also leave the OSCORE group and rejoin it, hence obtaining the new group configuration parameters and the up-to-date group keying material. When this happens, the Group Manager SHOULD NOT repeatedly rekey the group upon the re-join of every current group member, each of which is identifiable by means of the secure association that it has with the Group Manager.¶

  Shortly following an update of group configuration, the Group Manager SHOULD prioritize the re-join of such current group members before processing Join Requests from new group members.¶

• Following the enforcement of a new group configuration, a group member might not deem it conducive to a sufficient security level (e.g., in terms of security algorithms and related parameters). In such a case, it is RECOMMENDED that the group member leaves the group.¶

• A change of the current group configuration, possibly also requiring a group rekeying, might result in temporarily preventing communications among some group members altogether, until they have aligned themselves to the new group configuration. This is especially the case for a change of group configuration affecting the security algorithms and related parameters used in the group.¶

  Furthermore, a change of group configuration might interfere with ongoing, extended exchanges between group members, especially Block-Wise transfers [RFC7959][RFC9177] and the transmission of Observe notifications for ongoing Observations [RFC7641].¶

  A group configuration (possibly together with the group keying material) may have been updated while a Block-Wise transfer is ongoing between two group members. This will result in blocks being resent, if the block sender and recipient are not yet both aligned with the new group configuration (and group keying material), in which case the block recipient would reply with an error message.¶

  After a change of group configuration, a group member MUST terminate an ongoing Observation if the new group configuration would not have allowed to compute exactly the Observe request associated with the ongoing Observation. This occurs, for example, when the new group configuration specifies a signature algorithm different from the one used in the group when the Observe request was protected.¶

9.2. Group Manager

In addition to what is discussed in Section 10.1 of [I-D.ietf-ace-key-groupcomm], a compromised Group Manager would allow an adversary to also monitor the group configurations specified by an Administrator, or to enforce group configurations different from the specified ones, which can result in communications in the OSCORE groups not attaining the originally intended security level.¶

Although this is undesirable, it is not worse than the control that the adversary would gain on the group keying material through the compromised Group Manager (see Section 10.1 of [I-D.ietf-ace-key-groupcomm]).¶

Unlike what is defined in Section 10.2 of [I-D.ietf-ace-key-groupcomm] with respect to renewing the group keying material, the Group Manager does not have to change the group configurations of the OSCORE groups it is responsible for, after having experienced a reboot.¶

9.3. Administrators

If multiple Administrators are responsible for the same OSCORE group, they are expected to be aware of each other and of their shared responsibility, as well as to be aligned on what is in the best interest of the OSCORE group and its secure operation. It is out of the scope of this document to define how different Administrators are appointed as responsible for an OSCORE group, and how they achieve and maintain such an alignment with each other.¶

A compromised Administrator may collude with unauthorized parties. Within the extent of the granted access rights, the compromised Administrator may leak group configurations, change them in such a way that communications in the OSCORE groups do not attain the originally intended security level, or delete OSCORE groups altogether thus impeding their secure operation.¶

When an Administrator is found compromised, the pertaining Access Tokens MUST be revoked by the Authorization Server. A possible way for the Authorization Server to notify the affected Group Managers about such revoked Access Tokens is defined in [I-D.ietf-ace-revoked-token-notification].¶

10.1. ACE Groupcomm Parameters

IANA is asked to register the following entries in the "ACE Groupcomm Parameters" registry defined in Section 11.7 of [I-D.ietf-ace-key-groupcomm].¶

Name: hkdf
CBOR Key: -1
CBOR Type: tstr / int
Reference: [RFC-XXXX]

Name: cred_fmt
CBOR Key: -2
CBOR Type: int
Reference: [RFC-XXXX]

Name: group_mode
CBOR Key: -3
CBOR Type: simple value
Reference: [RFC-XXXX]

Name: gp_enc_alg
CBOR Key: -4
CBOR Type: tstr / int / simple value
Reference: [RFC-XXXX]

Name: sign_alg
CBOR Key: -5
CBOR Type: tstr / int / simple value
Reference: [RFC-XXXX]

Name: sign_params
CBOR Key: -6
CBOR Type: array / simple value
Reference: [RFC-XXXX]

Name: pairwise_mode
CBOR Key: -7
CBOR Type: simple value
Reference: [RFC-XXXX]

Name: alg
CBOR Key: -8
CBOR Type: tstr / int / simple value
Reference: [RFC-XXXX]

Name: ecdh_alg
CBOR Key: -9
CBOR Type: tstr / int / simple value
Reference: [RFC-XXXX]

Name: ecdh_params
CBOR Key: -10
CBOR Type: array / simple value
Reference: [RFC-XXXX]

Name: det_req
CBOR Key: -25
CBOR Type: simple value
Reference: [RFC-XXXX]

Name: det_hash_alg
CBOR Key: -26
CBOR Type: tstr / int
Reference: [RFC-XXXX]

Name: rt
CBOR Key: -11
CBOR Type: tstr
Reference: [RFC-XXXX]

Name: active
CBOR Key: -12
CBOR Type: simple value
Reference: [RFC-XXXX]

Name: group_name
CBOR Key: -13
CBOR Type: tstr / #6.<uint>(any)
Reference: [RFC-XXXX]

Name: group_description
CBOR Key: -14
CBOR Type: tstr / simple value
Reference: [RFC-XXXX]

Name: max_stale_sets
CBOR Key: -15
CBOR Type: uint
Reference: [RFC-XXXX]

Name: gid_reuse
CBOR Key: -16
CBOR Type: simple value
Reference: [RFC-XXXX]

Name: app_groups
CBOR Key: -17
CBOR Type: array
Reference: [RFC-XXXX]

Name: joining_uri
CBOR Key: -18
CBOR Type: tstr
Reference: [RFC-XXXX]

Name: as_uri
CBOR Key: -19
CBOR Type: tstr
Reference: [RFC-XXXX]

Name: conf_filter
CBOR Key: -27
CBOR Type: array
Reference: [RFC-XXXX]

Name: app_groups_diff
CBOR Key: -28
CBOR Type: array
Reference: [RFC-XXXX]

10.2. ACE Groupcomm Errors

IANA is asked to register the following entry in the "ACE Groupcomm Errors" registry defined in Section 11.12 of [I-D.ietf-ace-key-groupcomm].¶

Value: 10
Description: Group currently active
Reference: [RFC-XXXX]

Value: 11
Description: Unable to determine a group name
Reference: [RFC-XXXX]

Value: 12
Description: Unsupported group configuration
Reference: [RFC-XXXX]

10.3. Resource Types

IANA is asked to enter the following values in the "Resource Type (rt=) Link Target Attribute Values" registry within the "Constrained Restful Environments (CoRE) Parameters" registry group.¶

Value: core.osc.gcoll
Description: Group-collection resource of an OSCORE Group Manager
Reference: [RFC-XXXX]

Value: core.osc.gconf
Description: Group-configuration resource of an OSCORE Group Manager
Reference: [RFC-XXXX]

10.4. Group OSCORE Admin Permissions

This document establishes the IANA "Group OSCORE Admin Permissions" registry. The registry has been created to use the "Expert Review" registration procedure [RFC8126]. Expert review guidelines are provided in Section 10.5.¶

This registry includes the possible permissions that Administrators can have to perform operations on an OSCORE Group Manager, each in combination with a numeric identifier. These numeric identifiers are used to express authorization information about performing administrative operations concerning OSCORE groups under the control of the Group Manager, as specified in Section 3 of [RFC-XXXX].¶

The columns of this registry are:¶

• Name: A value that can be used in documents for easier comprehension, to identify a possible permission that Administrators can perform when interacting with an OSCORE Group Manager.¶

• Value: The numeric identifier for this permission. Integer values greater than 65535 are marked as "Private Use", all other values use the registration policy "Expert Review" (see Section 4.5 of [RFC8126]).¶

  Note that, in general, a single permission can be associated with multiple different operations that are possible to be performed when interacting with the Group Manager.¶

• Description: This field contains a brief description of the permission.¶
• Reference: This contains a pointer to the public specification for the permission.¶

This registry will be initially populated by the values in Table 1. The Reference column for all of these entries will be [RFC-XXXX].¶

10.5. Expert Review Instructions

The IANA registry established in this document is defined as "Expert Review". This section gives some general guidelines for what the experts should be looking for, but they are being designated as experts for a reason, so they should be given substantial latitude.¶

Expert reviewers should take into consideration the following points:¶

• Clarity and correctness of registrations. Experts are expected to check the clarity of purpose and use of the requested entries. Experts should inspect the entry for the considered permission, to verify the correctness of its description against the permission as intended in the specification that defined it. Expert should consider requesting an opinion on the correctness of registered parameters from the Authentication and Authorization for Constrained Environments (ACE) Working Group and the Constrained RESTful Environments (CoRE) Working Group.¶

  Entries that do not meet these objective of clarity and completeness should not be registered.¶

• Duplicated registration and point squatting should be discouraged. Reviewers are encouraged to get sufficient information for registration requests to ensure that the usage is not going to duplicate one that is already registered and that the point is likely to be used in deployments.¶
• Experts should take into account the expected usage of permissions when approving point assignment. Given a 'Value' V as code point, the length of the encoding of (2^V+1 - 1) should be weighed against the usage of the entry, considering the resources and capabilities of devices it will be used on. Additionally, given a 'Value' V as code point, the length of the encoding of (2^V+1 - 1) should be weighed against how many code points resulting in that encoding length are left, and the resources and capabilities of devices it will be used on.¶
• Specifications are recommended. When specifications are not provided, the description provided needs to have sufficient information to verify the points above.¶

B.1. Version -10 to -11

• Early mentioned that issued Access Tokens can have other purposes.¶
• Added example of array of scope entries.¶
• Removed moot paragraph about the benefits of group name patterns.¶
• Use of CBOR tag 21065 to indicate a regular expression.¶
• Renamed 'group_title' as 'group_description'.¶
• Added a second example of FETCH to the group-collection resource.¶
• Avoiding accidental deactivation of a group when updating it.¶
• Avoid alternative ways to create a group configuration resource.¶
• RFC 9290 is used instead of the custom format for error responses.¶
• Added integer abbreviations for the new entries in the "ACE Groupcomm Parameters" registry.¶
• Editorial fixes and improvements.¶

B.2. Version -09 to -10

• Consistent use of 4.03 (Forbidden) error responses.¶
• Removed moot, remnant statements from when CoRAL was used.¶
• Clarified how the Group Manager may attempt to determine an alternative group name upon creating a new group.¶
• Made explicit what parameters cannot change when overwriting a group configuration.¶
• Improved guidelines to the Group Manager on selecting an alternative group name.¶
• Improved guidelines to Administrators receiving an error after trying to create a new group.¶
• Changed description of error 11 from "No available group names" to "Unable to determine a group name".¶
• Editorial fixes and improvements.¶

B.3. Version -08 to -09

• Removed use of CoRAL.¶
• Use of the pairwise mode changed to true by default.¶
• Clarified effects on group members after a group configuration change.¶
• Renamed "Signature Encryption Algorithm" to "Group Encryption Algorithm".¶
• Renamed "sign_enc_alg" to "gp_enc_alg".¶
• Fixes and editorial improvements.¶

B.4. Version -07 to -08

• Consistency of parameter names.¶
• More details on consistency of message payload.¶
• New section on multiple, concurrent Administrators.¶
• Specified atomicity of write operations.¶
• Clarified effects of configuration overwriting on group members.¶
• New ACE Groupcomm Error on unsupported configuration.¶
• Possible reason to deviate from default parameter values.¶
• Added security considerations.¶
• CoRAL examples use CBOR diagnostic notation and Packed CBOR.¶
• Various clarifications and editorial improvements.¶

B.5. Version -06 to -07

• Alignment with renaming in draft-ietf-ace-key-groupcomm.¶
• Updated signaling of semantics for binary encoded scopes.¶
• Split between parameter registration and their CBOR abbreviations.¶
• Classified parameters as must/should/may be supported.¶
• New error code "No available group names" and related guidelines.¶
• Fixes in the examples.¶
• Editorial improvements.¶

B.6. Version -05 to -06

• Use and extend the same AIF data model AIF-OSCORE-GROUPCOMM defined in [I-D.ietf-ace-key-groupcomm-oscore].¶
• Revised Client-AS interaction, based on the used AIF data model.¶
• Categorized operations at the Group Manager as required and optional to support.¶
• Added status parameter 'gid_reuse', on reassigning OSCORE Group IDs upon group rekeying.¶
• Clarifications on the group name ultimately chosen by the Group Manager.¶
• Moved the detailed processing of group name patterns at the AS to an Appendix, as an example.¶
• Editorial improvements.¶

B.7. Version -04 to -05

• Defined format of scope based on a new AIF data model.¶
• Specified authorization checks at the Group Manager.¶
• Revised resource handlers based on the new scope format.¶
• Renamed 'pub_key_enc' to 'cred_fmt'.¶
• Mandatory to include 'group_name' in the group creation request.¶
• Suggesting a used 'group_name' results in a new name, not in an error.¶
• Distinction between authentication credentials and public keys.¶
• More details on informing group members about changes in the group configuration.¶
• Revised order of sections; editorial improvements.¶

B.8. Version -03 to -04

• Clarifications on what to do in case of enhanced error responses.¶
• Clarifications on handling default values for group parameters.¶
• New configuration parameters to support OSCORE deterministic requests.¶
• IANA considerations - Use RFC8126 terminology.¶
• Author's change of address.¶
• Editorial improvements.¶

B.9. Version -02 to -03

• Aligned new and old parameters to core-groupcomm-oscore and ace-key-groupcomm-oscore.¶
• Removed 'cs_key_params' and 'ecdh_key_params' to avoid redundant COSE capabilities of key types, consistently with draft-ietf-ace-key-groupcomm-oscore.¶
• Revised examples and side effects due to parameter changes.¶
• New error type "Group currently active".¶

B.10. Version -01 to -02

• Admit multiple Administrators and limited access to admin resources.¶
• Early design considerations for defining the format of scope.¶
• Additional error handling, using also error types.¶
• Selective update of group-configuration resources with PATCH/iPATCH.¶
• Editorial improvements.¶

B.11. Version -00 to -01

• Names of application groups as status parameter.¶
• Parameters related to the pairwise mode of Group OSCORE.¶
• Defined FETCH for group-configuration resources.¶
• Policies on registration of links to the Resource Directory.¶
• Added resource type for group-configuration resources.¶
• Fixes, clarifications and editorial improvements.¶