Draft: draft-ietf-ace-key-groupcomm

Commentary: Following up on IETF113 discussion , I think that the " extended scope format " can be vastly simplified by using : Rather than specifying a new format and registry for scopes , the scopes within an audience that employs this mechanism would be disambiguated just like file formats . ( They have common properties : Everybody assumes that their semantics are known from the context , but in the odd case they are not , eg . because an audience is used with different kinds of scopes ) . Rather than becoming the extended scope could just be which , if TAGFORTHESESEMANTICS is allocated following the recommendations of cbor - file - magic ( I guess it 'd forego using the self - describing tag around it ) equivalent to prefixing the encoded scope with 5 bytes specific to that tag . In particular , if for the scopes ' semantics a content format is allocated ( and there is already 290 for AIF with the default ) , the tag is even already allocated , and if other AIF generalizations allocate their own content format , they also get the tag automatically . The only down side I see is that the scope claims might grow in size , depending on the precise numbers allocated . But for example , if a 1 + 1 tag were chosen for the current TBDTAG , depending on the length of the inner encoding , this might already be just as good or even better . 
 Thanks for the good observation and input , I think it would be a good change ! When the " extended scope format " was to -ace - key - groupcomm , the registration of one tag only and of on - demand semantics integers ended up preferred , compared to opening for the registration of multiple CBOR tags . But on the other hand I think all you 've mentioned was not around yet :-) Yes , TAGFORTHESESEMANTICS would be from the 4 - byte range , and there is no need to further use the tag . Yes , if scope uses exactly Generic AIF , the value of TAGFORTHESESEMANTICS is = +290 . Some guideline and pointer to -cbor - file - magic can be for a more general case not relying on AIF . Yes , for example the document -ace - key - groupcomm - oscore is defining the new data model AIF - OSCORE - GROUPCOMM [ 0 ] and registering a corresponding content - format , so it would also automatically have the corresponding value for its TAGFORTHESESEMANTICS . I think it 's more likely to be even better . [ 0 ] As also discussed at IETF 113 , that same data model would cover both the " user " scope entries defined in -ace - key - groupcomm - oscore and the " admin " scope entries defined in -ace - oscore - gm - admin , as possible to coexist in the same scope claim . The type of the different scope entries is distinguishable thanks to the least significant bit in their Tperm value , which would also have this meaning already from the revised definition of the data model .
The terms and concepts described in the ACE framework I-D.ietf-
ace-oauth-authz and in the Authorization Information Format (AIF)
I-D.ietf-ace-aif to express authorization information.  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 terms and concepts described in the ACE framework RFC9200 and
in the Authorization Information Format (AIF) RFC9237 to express
authorization information.  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 terms and concepts described in CBOR RFC8949 and COSE I-
D.ietf-cose-rfc8152bis-struct I-D.ietf-cose-rfc8152bis-algs I-
D.ietf-cose-countersign.
The terms and concepts described in CBOR RFC8949 and COSE RFC9053
I-D.ietf-cose-countersign.
The same security group might be associated to multiple
application groups.  Also, the same application group can be
associated to multiple security groups.  Further details and
considerations on the mapping between the two types of group are
out of the scope of this document.
The same security group might be associated with multiple
application groups.  Also, the same application group can be
associated with multiple security groups.  Further details and
considerations on the mapping between the two types of group are
out of the scope of this document.
Transport profile, to indicate a profile of ACE as per
Section 5.8.4.3 of I-D.ietf-ace-oauth-authz.  A transport profile
specifies the communication protocol and communication security
protocol between an ACE Client and Resource Server, as well as
proof-of-possession methods, if it supports proof-of-possession
access tokens, etc.  Transport profiles of ACE include, for
instance, I-D.ietf-ace-oscore-profile, I-D.ietf-ace-dtls-authorize
and I-D.ietf-ace-mqtt-tls-profile.
Transport profile, to indicate a profile of ACE as per
Section 5.8.4.3 of RFC9200.  A transport profile specifies the
communication protocol and communication security protocol between
an ACE Client and Resource Server, as well as proof-of-possession
methods, if it supports proof-of-possession access tokens, etc.
Transport profiles of ACE include, for instance, RFC9203, RFC9202
and I-D.ietf-ace-mqtt-tls-profile.
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 RFC7925 and C509 certificates I-
D.ietf-cose-cbor-encoded-cert.
Allowing a group member to retrieve public keys of other group
members (sec-key-retrieval) and to provide an updated public key
(update-pub-key).
Allowing a group member to retrieve authentication credentials of
other group members (sec-key-retrieval) and to provide an updated
authentication credential (update-pub-key).
This exchange and the following secure communications between the
Client and the KDC MUST occur in accordance with the transport
profile of ACE used between Client and KDC, such as the DTLS
transport profile I-D.ietf-ace-dtls-authorize and OSCORE transport
profile I-D.ietf-ace-oscore-profile of ACE.
This exchange and the following secure communications between the
Client and the KDC MUST occur in accordance with the transport
profile of ACE used between Client and KDC, such as the DTLS
transport profile RFC9202 and OSCORE transport profile RFC9203 of
ACE.
This section describes in detail the format of messages exchanged by
the participants when a node requests access to a given group.  This
exchange is based on ACE I-D.ietf-ace-oauth-authz.
As defined in I-D.ietf-ace-oauth-authz, the Client requests the AS
for the authorization to join the group through the KDC (see ssec-
authorization-request).  If the request is approved and authorization
is granted, the AS provides the Client with a proof-of-possession
access token and parameters to securely communicate with the KDC (see
ssec-authorization-response).
This section describes in detail the format of messages exchanged by
the participants when a node requests access to a given group.  This
exchange is based on ACE RFC9200.
As defined in RFC9200, the Client requests the AS for the
authorization to join the group through the KDC (see ssec-
authorization-request).  If the request is approved and authorization
is granted, the AS provides the Client with a proof-of-possession
access token and parameters to securely communicate with the KDC (see
ssec-authorization-response).
The transport profile of ACE also defines a number of details such as
the communication and security protocols used with the KDC (see
Appendix C of I-D.ietf-ace-oauth-authz).
The transport profile of ACE also defines a number of details such as
the communication and security protocols used with the KDC (see
Appendix C of RFC9200).
The Authorization Request sent from the Client to the AS is defined
in Section 5.8.1 of I-D.ietf-ace-oauth-authz and MAY contain the
following parameters, which, if included, MUST have format and value
as specified below.
The Authorization Request sent from the Client to the AS is defined
in Section 5.8.1 of RFC9200 and MAY contain the following parameters,
which, if included, MUST have format and value as specified below.
If the AIF format is used, each scope entry is encoded as
specified in I-D.ietf-ace-aif.  The object identifier "Toid"
corresponds to the group name and MUST be encoded as a CBOR
text string.  The permission set "Tperm" indicates the roles
that the Client wishes to take in the group.
If the AIF format is used, each scope entry is encoded as per
RFC9237.  If a scope entry expresses a set of roles to take in
a group as per this document, the object identifier "Toid"
specifies the group name and MUST be encoded as a CBOR text
string, while the permission set "Tperm" specifies the roles
that the Client wishes to take in the group.
Optionally, as second element, the role or CBOR array of
roles that the Client wishes to take in the group.  This
element is optional since roles may have been pre-assigned
to the Client, as associated to its verifiable identity
credentials.  Alternatively, the application may have
defined a single, well-known role for the target resource(s)
and audience(s).
Optionally, as second element, the role or CBOR array of
roles that the Client wishes to take in the group.  This
element is optional since roles may have been pre-assigned
to the Client, as associated with its verifiable identity
credentials.  Alternatively, the application may have
defined a single, well-known role for the target resource(s)
and audience(s).
If the application profile uses the AIF format, it is also
REQUIRED to register its specific instance of "Toid" and "Tperm",
as well as the corresponding Media Type and Content-Format, as per
the guidelines in I-D.ietf-ace-aif (REQ2).
If the application profile uses the AIF format, it is also
REQUIRED to register its specific instance of "Toid" and "Tperm",
as well as the corresponding Media Type and Content-Format, as per
the guidelines in RFC9237 (REQ2).
As defined in I-D.ietf-ace-oauth-authz, other additional parameters
can be included if necessary.
The AS processes the Authorization Request as defined in
Section 5.8.2 of I-D.ietf-ace-oauth-authz, especially verifying that
the Client is authorized to access the specified groups with the
requested roles, or possibly a subset of those.
In case of successful verification, the Authorization Response sent
from the AS to the Client is also defined in Section 5.8.2 of I-
D.ietf-ace-oauth-authz.  Note that the parameter 'expires_in' MAY be
omitted if the application defines how the expiration time is
communicated to the Client via other means, or if it establishes a
default value.
As defined in RFC9200, other additional parameters can be included if
necessary.
The AS processes the Authorization Request as defined in
Section 5.8.2 of RFC9200, especially verifying that the Client is
authorized to access the specified groups with the requested roles,
or possibly a subset of those.
In case of successful verification, the Authorization Response sent
from the AS to the Client is also defined in Section 5.8.2 of
RFC9200.  Note that the parameter 'expires_in' MAY be omitted if the
application defines how the expiration time is communicated to the
Client via other means, or if it establishes a default value.
a scope claim (see for example 'scope' registered in Section 8.14
of I-D.ietf-ace-oauth-authz for CWT).
a scope claim (see for example 'scope' registered in Section 8.14
of RFC9200 for CWT).
When receiving an Authorization Request from a Client that was
previously authorized, and for which the AS still owns a valid non-
expired access token, the AS MAY reply with that token.  Note that it
is up to application profiles of ACE to make sure that re-posting the
same token does not cause re-use of keying material between nodes
(for example, that is done with the use of random nonces in I-D.ietf-
ace-oscore-profile).
The Client sends a Token Transfer Request to the KDC, i.e., a CoAP
POST request including the access token and targeting the authz-info
endpoint (see Section 5.10.1 of I-D.ietf-ace-oauth-authz).
Note that this request deviates from the one defined in I-D.ietf-ace-
oauth-authz, since it allows to ask the KDC for additional
information concerning the public keys used in the group to ensure
source authentication, as well as for possible additional group
parameters.
The joining node MAY ask for this information from the KDC through
the same Token Transfer Request.  In this case, the message MUST have
Content-Format set to application/ace+cbor defined in Section 8.16 of
I-D.ietf-ace-oauth-authz, and the message payload MUST be formatted
as a CBOR map, which MUST include the access token.  The CBOR map MAY
additionally include the following parameter, which, if included,
MUST have format and value as specified below.
'sign_info' defined in sign-info, specifying the CBOR simple value
'null' (0xf6) to request information about the signature
algorithm, signature algorithm parameters, signature key
parameters and about the exact encoding of public keys used in the
groups that the Client has been authorized to join.
When receiving an Authorization Request from a Client that was
previously authorized, and for which the AS still owns a valid non-
expired access token, the AS MAY reply with that token.  Note that it
is up to application profiles of ACE to make sure that re-posting the
same token does not cause re-use of keying material between nodes
(for example, that is done with the use of random nonces in RFC9203).
The Client sends a Token Transfer Request to the KDC, i.e., a CoAP
POST request including the access token and targeting the authz-info
endpoint (see Section 5.10.1 of RFC9200).
Note that this request deviates from the one defined in RFC9200,
since it allows to ask the KDC for additional information concerning
the authentication credentials used in the group to ensure source
authentication, as well as for possible additional group parameters.
The joining node MAY ask for this information from the KDC through
the same Token Transfer Request.  In this case, the message MUST have
Content-Format set to application/ace+cbor defined in Section 8.16 of
RFC9200, and the message payload MUST be formatted as a CBOR map,
which MUST include the access token.  The CBOR map MAY additionally
include the following parameter, which, if included, MUST have format
and value as specified below.
'sign_info' defined in sign-info, specifying the CBOR simple value
"null" (0xf6) to request information about the signature
algorithm, signature algorithm parameters, signature key
parameters and about the exact format of authentication
credentials used in the groups that the Client has been authorized
to join.
The Token Transfer Response MUST have Content-Format "application/
ace+cbor", and its payload is a CBOR map.  Note that this deviates
from what is defined in the ACE framework, where the response from
the authz-info endpoint is defined as conveying no payload (see
Section 5.10.1 of I-D.ietf-ace-oauth-authz).
If the access token contains a role that requires the Client to send
its own public key to the KDC when joining the group, the CBOR map
MUST include the parameter 'kdcchallenge' defined in kdcchallenge,
specifying a dedicated challenge N_S generated by the KDC.
The Token Transfer Response MUST have Content-Format "application/
ace+cbor", and its payload is a CBOR map.  Note that this deviates
from what is defined in the ACE framework, where the response from
the authz-info endpoint is defined as conveying no payload (see
Section 5.10.1 of RFC9200).
If the access token contains a role that requires the Client to send
its own authentication credential to the KDC when joining the group,
the CBOR map MUST include the parameter 'kdcchallenge' defined in
kdcchallenge, specifying a dedicated challenge N_S generated by the
KDC.
The KDC MUST store the 'kdcchallenge' value associated to the Client
at least until it receives a Joining Request from it (see ssec-key-
distribution-exchange), to be able to verify the PoP evidence
provided during the join process, and thus that the Client possesses
its own private key.
The same 'kdcchallenge' value MAY be reused several times by the
Client, to generate a new PoP evidence, e.g., in case the Client
provides the Group Manager with a new public key while being a group
member (see update-pub-key), or joins a different group where it
intends to use a different public key.  Therefore, it is RECOMMENDED
that the KDC keeps storing the 'kdcchallenge' value after the first
join is processed as well.  If the KDC has already discarded the
'kdcchallenge' value, that will trigger an error response with a
newly generated 'kdcchallenge' value that the Client can use to
restart the join process, as specified in ssec-key-distribution-
exchange.
The KDC MUST store the 'kdcchallenge' value associated with the
Client at least until it receives a Join Request from it (see ssec-
key-distribution-exchange), to be able to verify the PoP evidence
provided during the join process, and thus that the Client possesses
its own private key.
The same 'kdcchallenge' value MAY be reused several times by the
Client, to generate a new PoP evidence, e.g., in case the Client
provides the Group Manager with a new authentication credential while
being a group member (see update-pub-key), or joins a different group
where it intends to use a different authentication credential.
Therefore, it is RECOMMENDED that the KDC keeps storing the
'kdcchallenge' value after the first join is processed as well.  If
the KDC has already discarded the 'kdcchallenge' value, that will
trigger an error response with a newly generated 'kdcchallenge' value
that the Client can use to restart the join process, as specified in
ssec-key-distribution-exchange.
If allowed by the used transport profile of ACE, the Client may
provide the Access Token to the KDC by other means than the Token
Transfer Request.  An example is the DTLS transport profile of ACE,
where the Client can provide the access token to the KDC during the
secure session establishment (see Section 3.3.2 of I-D.ietf-ace-dtls-
authorize).
The 'sign_info' parameter is an OPTIONAL parameter of the request and
response messages exchanged between the Client and the authz-info
endpoint at the RS (see Section 5.10.1. of I-D.ietf-ace-oauth-authz).
This parameter allows the Client and the RS to exchange information
about a signature algorithm and about public keys to accordingly use
for signature verification.  Its exact semantics and content are
application specific.
In this specification and in application profiles building on it,
this parameter is used to exchange information about the signature
algorithm and about public keys to be used with it, in the groups
indicated by the transferred acces token as per its 'scope' claim
(see ssec-authorization-response).
When used in the Token Transfer Request sent to the KDC (see token-
post), the 'sign_info' parameter specifies the CBOR simple value
'null' (0xf6).  This is done to ask for information about the
signature algorithm and about the public keys used in the groups that
the Client has been authorized to join - or to have a more restricted
interaction as per its granted roles (e.g., the Client is an external
signature verifier).
When used in the following Token Transfer Response from the KDC (see
token-post), the 'sign_info' parameter is a CBOR array of one or more
elements.  The number of elements is at most the number of groups
that the Client has been authorized to join - or to have a more
restricted interaction (see above).  Each element contains
information about signing parameters and about public keys for one or
more groups, and is formatted as follows.
The first element 'id' is a group name or an array of group names,
associated to groups for which the next four elements apply.  In
the following, each specified group name is referred to as
'gname'.
The second element 'sign_alg' is an integer or a text string if
the POST request included the 'sign_info' parameter with value the
CBOR simple value 'null' (0xf6), and indicates the signature
algorithm used in the groups identified by the 'gname' values.  It
is REQUIRED of the application profiles to define specific values
that this parameter can take (REQ3), selected from the set of
signing algorithms of the COSE Algorithms registry
COSE.Algorithms.
If allowed by the used transport profile of ACE, the Client may
provide the Access Token to the KDC by other means than the Token
Transfer Request.  An example is the DTLS transport profile of ACE,
where the Client can provide the access token to the KDC during the
secure session establishment (see Section 3.3.2 of RFC9202).
The 'sign_info' parameter is an OPTIONAL parameter of the request and
response messages exchanged between the Client and the authz-info
endpoint at the RS (see Section 5.10.1. of RFC9200).
This parameter allows the Client and the RS to exchange information
about a signature algorithm and about authentication credentials to
accordingly use for signature verification.  Its exact semantics and
content are application specific.
In this specification and in application profiles building on it,
this parameter is used to exchange information about the signature
algorithm and about authentication credentials to be used with it, in
the groups indicated by the transferred acces token as per its
'scope' claim (see ssec-authorization-response).
When used in the Token Transfer Request sent to the KDC (see token-
post), the 'sign_info' parameter specifies the CBOR simple value
"null" (0xf6).  This is done to ask for information about the
signature algorithm and about the authentication credentials used in
the groups that the Client has been authorized to join - or to have a
more restricted interaction as per its granted roles (e.g., the
Client is an external signature verifier).
When used in the following Token Transfer Response from the KDC (see
token-post), the 'sign_info' parameter is a CBOR array of one or more
elements.  The number of elements is at most the number of groups
that the Client has been authorized to join - or to have a more
restricted interaction (see above).  Each element contains
information about signing parameters and about authentication
credentials for one or more groups, and is formatted as follows.
The first element 'id' is a group name or an array of group names,
associated with groups for which the next four elements apply.  In
the following, each specified group name is referred to as
'gname'.
The second element 'sign_alg' is an integer or a text string if
the POST request included the 'sign_info' parameter with value the
CBOR simple value "null" (0xf6), and indicates the signature
algorithm used in the groups identified by the 'gname' values.  It
is REQUIRED of the application profiles to define specific values
that this parameter can take (REQ3), selected from the set of
signing algorithms of the COSE Algorithms registry
COSE.Algorithms.
The fifth element 'pub_key_enc' parameter is either a CBOR integer
indicating the encoding of public keys used in the groups
identified by the 'gname' values, or has value the CBOR simple
value 'null' (0xf6) indicating that the KDC does not act as
repository of public keys for group members.  Its acceptable
integer values are taken from the 'Label' column of the "COSE
Header Parameters" registry COSE.Header.Parameters.  It is
REQUIRED of the application profiles to define specific values to
use for this parameter, consistently with the acceptable formats
of public keys (REQ6).
This format is consistent with every signature algorithm currently
defined in I-D.ietf-cose-rfc8152bis-algs, i.e., with algorithms that
have only the COSE key type as their COSE capability. sec-future-
cose-algs describes how the format of each 'sign_info_entry' can be
generalized for possible future registered algorithms having a
different set of COSE capabilities.
The 'kdcchallenge' parameter is an OPTIONAL parameter of response
message returned from the authz-info endpoint at the RS, as defined
in Section 5.10.1 of I-D.ietf-ace-oauth-authz.  This parameter
contains a challenge generated by the RS and provided to the Client.
In this specification and in application profiles building on it, the
Client may use this challenge to prove possession of its own private
key in the Joining Request (see the 'client_cred_verify' parameter in
gid-post).
The fifth element 'cred_fmt' parameter is either a CBOR integer
indicating the format of authentication credentials used in the
groups identified by the 'gname' values, or has value the CBOR
simple value "null" (0xf6) indicating that the KDC does not act as
repository of authentication credentials for group members.  Its
acceptable integer values are taken from the 'Label' column of the
"COSE Header Parameters" registry COSE.Header.Parameters.  It is
REQUIRED of the application profiles to define specific values to
use for this parameter, consistently with the acceptable formats
of authentication credentials (REQ6).
This format is consistent with every signature algorithm currently
defined in RFC9053, i.e., with algorithms that have only the COSE key
type as their COSE capability. sec-future-cose-algs describes how the
format of each 'sign_info_entry' can be generalized for possible
future registered algorithms having a different set of COSE
capabilities.
The 'kdcchallenge' parameter is an OPTIONAL parameter of response
message returned from the authz-info endpoint at the RS, as defined
in Section 5.10.1 of RFC9200.  This parameter contains a challenge
generated by the RS and provided to the Client.
In this specification and in application profiles building on it, the
Client may use this challenge to prove possession of its own private
key in the Join Request (see the 'client_cred_verify' parameter in
gid-post).
As most important operation after trasferring the access token to the
KDC, the Client can perform a "Joining" exchange with the KDC, by
specifying the group it requests to join (see ssec-key-distribution-
exchange).  Then, the KDC verifies the access token and that the
Client is authorized to join the specified group.  If so, the KDC
provides the Client with the keying material to securely communicate
with the other members of the group.
As most important operation after trasferring the access token to the
KDC, the Client can perform a Join Request-Response exchange with the
KDC, by specifying the group it requests to join (see ssec-key-
distribution-exchange).  Then, the KDC verifies the access token and
that the Client is authorized to join the specified group.  If so,
the KDC provides the Client with the keying material to securely
communicate with the other members of the group.
This resource is created only in case the KDC acts as repository
of public keys for group members.
A Client can access this resource in order to retrieve the public
keys of other group members, in addition to when joining the
group.  That is, the Client can retrieve the public keys of all
the current group members, or a subset of them by specifying
filter criteria.  These operations are described in sec-key-
retrieval-all and sec-key-retrieval, respectively.
ace-group/GROUPNAME/kdc-pub-key : this resource is invariant once
established, and contains the public key of the KDC for the group
with name GROUPNAME.
This resource is created only in case the KDC has an associated
public key and this is required for the correct group operation.
It is REQUIRED of application profiles to define whether the KDC
has such an associated public key (REQ8).
A Client can interact with this resource in order to retrieve the
current public key of the KDC, in addition to when joining the
group.
This resource is created only in case the KDC acts as repository
of authentication credentials for group members.
A Client can access this resource in order to retrieve the
authentication credentials of other group members, in addition to
when joining the group.  That is, the Client can retrieve the
authentication credentials of all the current group members, or a
subset of them by specifying filter criteria.  These operations
are described in sec-key-retrieval-all and sec-key-retrieval,
respectively.
ace-group/GROUPNAME/kdc-cred : this resource is invariant once
established, and contains the authentication credential of the KDC
for the group with name GROUPNAME.
This resource is created only in case the KDC has an associated
authentication credential and this is required for the correct
group operation.  It is REQUIRED of application profiles to define
whether the KDC has such an associated authentication credential
(REQ8).
A Client can interact with this resource in order to retrieve the
current authentication credential of the KDC, in addition to when
joining the group.
A Client can access this resource in order to upload at the KDC a
new public key to use in the group.  This operation is described
in update-pub-key.
This resource is not created if the group member does not have
individual public keying material to use in the group, or if the
KDC does not store the public keys of group members.
A Client can access this resource in order to upload at the KDC a
new authentication credential to use in the group.  This operation
is described in update-pub-key.
This resource is not created if the group member does not have an
authentication credential to use in the group, or if the KDC does
not store the authentication credentials of group members.
FETCH request to ace-group/ , in order to retrieve group names
associated to group identifiers.
GET and FETCH requests to ace-group/GROUPNAME/pub-key , in order
to retrieve the public keys of all the other group members (GET)
or only some of them by filtering (FETCH).  While retrieving
public keys remains possible by using GET requests, retrieval by
filtering allows to greatly limit the size of exchanged messages.
FETCH request to ace-group/ , in order to retrieve group names
associated with group identifiers.
GET and FETCH requests to ace-group/GROUPNAME/creds , in order to
retrieve the authentication credentials of all the other group
members (GET) or only some of them by filtering (FETCH).  While
retrieving authentication credentials remains possible by using
GET requests, retrieval by filtering allows to greatly limit the
size of exchanged messages.
GET request to ace-group/GROUPNAME/kdc-pub-key , in order to
retrieve the current public key of the KDC, in addition to when
joining the group.  This is relevant only if the KDC has an
associated public key and this is required for the correct group
operation.
GET request to ace-group/GROUPNAME/nodes/NODENAME, in order to
retrieve the current group keying material and individual keying
material.  The former can also be retrieved through a GET request
to ace-group/GROUPNAME/ (see above).  The latter would not be
possible to re-obtain as a group member.
GET request to ace-group/GROUPNAME/kdc-cred , in order to retrieve
the current authentication credential of the KDC, in addition to
when joining the group.  This is relevant only if the KDC has an
associated authentication credential and this is required for the
correct group operation.
GET request to ace-group/GROUPNAME/nodes/NODENAME , in order to
retrieve the current group keying material and individual keying
material.  The former can also be retrieved through a GET request
to ace-group/GROUPNAME/ (see above).  The latter would not be
possible to re-obtain as a group member.
PUT request to ace-group/GROUPNAME/nodes/NODENAME , in order to
ask for new individual keying material.  The Client would have to
alternatively re-join the group through a POST request to ace-
group/GROUPNAME/ (see above).  Furthermore, depending on its roles
in the group or on the application profile of this specification,
the Client might simply not be associated to any individual keying
material.
POST request to ace-group/GROUPNAME/nodes/NODENAME/pub-key , in
order to provide the KDC with a new public key.  The Client would
have to alternatively re-join the group through a POST request to
ace-group/GROUPNAME/ (see above).  Furthermore, depending on its
roles in the group, the Client might simply not have an associated
public key to provide.
PUT request to ace-group/GROUPNAME/nodes/NODENAME , in order to
ask for new individual keying material.  The Client would have to
alternatively re-join the group through a POST request to ace-
group/GROUPNAME/ (see above).  Furthermore, depending on its roles
in the group or on the application profile of this specification,
the Client might simply not be associated with any individual
keying material.
POST request to ace-group/GROUPNAME/nodes/NODENAME/cred , in order
to provide the KDC with a new authentication credential.  The
Client would have to alternatively re-join the group through a
POST request to ace-group/GROUPNAME/ (see above).  Furthermore,
depending on its roles in the group, the Client might simply not
have an associated authentication credential to provide.
In case the KDC stores a valid access token but the verifications
above fail, the KDC MUST reply with a 4.03 (Forbidden) error
response.  This response MAY be an AS Request Creation Hints, as
defined in Section 5.3 of I-D.ietf-ace-oauth-authz, in which case the
Content-Format MUST be set to application/ace+cbor.
In case the KDC stores a valid access token but the verifications
above fail, the KDC MUST reply with a 4.03 (Forbidden) error
response.  This response MAY be an AS Request Creation Hints, as
defined in Section 5.3 of RFC9200, in which case the Content-Format
MUST be set to application/ace+cbor.
If the KDC does not find any group associated to the specified group
identifiers, the handler returns a response with payload formatted as
a CBOR byte string of zero length.
If the KDC does not find any group associated with the specified
group identifiers, the handler returns a response with payload
formatted as a CBOR byte string of zero length.
The POST handler processes the Joining Request sent by a Client to
join a group, and returns a Joining Response as successful result of
the joining process (see ssec-key-distribution-exchange).  At a high
level, the POST handler adds the Client to the list of current group
members, adds the public key of the Client to the list of the group
members' public keys, and returns the symmetric group keying material
for the group identified by GROUPNAME.
The POST handler processes the Join Request sent by a Client to join
a group, and returns a Join Response as successful result of the
joining process (see ssec-key-distribution-exchange).  At a high
level, the POST handler adds the Client to the list of current group
members, adds the authentication credential of the Client to the list
of the group members' authentication credentials, and returns the
symmetric group keying material for the group identified by
GROUPNAME.
'get_pub_keys', if the Client wishes to receive the public keys of
the current group members from the KDC.  This parameter may be
included in the Joining Request if the KDC stores the public keys
of the group members, while it is not useful to include it if the
Client obtains those public keys through alternative means, e.g.,
from the AS.  Note that including this parameter might result in a
following Joining Response of large size, which can be
inconvenient for resource-constrained devices.
If the Client wishes to retrieve the public keys of all the
current group members, the 'get_pub_keys' parameter MUST encode
the CBOR simple value 'null' (0xf6).  Otherwise, the
'get_pub_keys' parameter MUST encode a non-empty CBOR array,
containing the following three elements formatted as defined
below.
The first element, namely 'inclusion_flag', encodes the CBOR
simple value True.  That is, the Client indicates that it
wishes to receive the public keys of all group members having
their node identifier specified in the third element of the
'get_pub_keys' array, namely 'id_filter' (see below).
The second element, namely 'role_filter', is a non-empty CBOR
array.  Each element of the array contains one role or a
combination of roles for the group identified by GROUPNAME.
That is, when the Joining Request includes a non-Null
'get_pub_keys' parameter, the Client filters public keys based
on node identifiers.
In particular, the Client indicates that it wishes to retrieve
the public keys of all the group members having any of the
single roles, or at least all of the roles indicated in any
combination of roles.  For example, the array ["role1",
"role2+role3"] indicates that the Client wishes to receive the
public keys of all group members that have at least "role1" or
at least both "role2" and "role3".
The third element, namely 'id_filter', is an empty CBOR array.
That is, when the Joining Request includes a non-Null
'get_pub_keys' parameter, the Client does not filter public
keys based on node identifiers.
In fact, when first joining the group, the Client is not
expected or capable to express a filter based on node
identifiers of other group members.  Instead, when already a
group member and sending a Joining Request to re-join, the
Client is not expected to include the 'get_pub_keys' parameter
in the Joining Request altogether, since it can rather retrieve
public keys associated to specific group identifiers as defined
in sec-key-retrieval.
The CDDL definition RFC8610 of 'get_pub_keys' is given in cddl-ex-
getpubkeys, using as example encoding: node identifier encoded as
a CBOR byte string; role identifier encoded as a CBOR text string,
and combination of roles encoded as a CBOR array of roles.
'get_creds', if the Client wishes to receive the authentication
credentials of the current group members from the KDC.  This
parameter may be included in the Join Request if the KDC stores
the authentication credentials of the group members, while it is
not useful to include it if the Client obtains those
authentication credentials through alternative means, e.g., from
the AS.  Note that including this parameter might result in a
following Join Response of large size, which can be inconvenient
for resource-constrained devices.
If the Client wishes to retrieve the authentication credentials of
all the current group members, the 'get_creds' parameter MUST
encode the CBOR simple value "null" (0xf6).  Otherwise, the
'get_creds' parameter MUST encode a non-empty CBOR array,
containing the following three elements formatted as defined
below.
The first element, namely 'inclusion_flag', encodes the CBOR
simple value "true" (0xf5).  That is, the Client indicates that
it wishes to receive the authentication credentials of all
group members having their node identifier specified in the
third element of the 'get_creds' array, namely 'id_filter' (see
below).
The second element, namely 'role_filter', is a non-empty CBOR
array.  Each element of the array contains one role or a
combination of roles for the group identified by GROUPNAME.
That is, when the Join Request includes a non-Null 'get_creds'
parameter, the Client filters authentication credentials based
on node identifiers.
In particular, the Client indicates that it wishes to retrieve
the authentication credentials of all the group members having
any of the single roles, or at least all of the roles indicated
in any combination of roles.  For example, the array ["role1",
"role2+role3"] indicates that the Client wishes to receive the
authentication credentials of all group members that have at
least "role1" or at least both "role2" and "role3".
The third element, namely 'id_filter', is an empty CBOR array.
That is, when the Join Request includes a non-Null 'get_creds'
parameter, the Client does not filter authentication
credentials based on node identifiers.
In fact, when first joining the group, the Client is not
expected or capable to express a filter based on node
identifiers of other group members.  Instead, when already a
group member and sending a Join Request to re-join, the Client
is not expected to include the 'get_creds' parameter in the
Join Request altogether, since it can rather retrieve
authentication credentials associated with specific group
identifiers as defined in sec-key-retrieval.
The CDDL definition RFC8610 of 'get_creds' is given in cddl-ex-
getpubkeys, using as example encoding: node identifier encoded as
a CBOR byte string; role identifier encoded as a CBOR text string,
and combination of roles encoded as a CBOR array of roles.
Note that, for this handler, 'inclusion_flag' is always set to
true, the array of roles 'role_filter' is always non-empty, while
the array of node identifiers 'id_filter' is always empty.
However, this is not necessarily the case for other handlers using
the 'get_pub_keys' parameter.
'client_cred', encoded as a CBOR byte string, with value the
original binary representation of the Client's public key.  This
parameter is used if the KDC is managing (collecting from/
distributing to the Client) the public keys of the group members,
and if the Client's role in the group will require for it to send
messages to one or more group members.  It is REQUIRED of the
application profiles to define the specific formats that are
acceptable to use for encoding public keys in the group (REQ6).
Note that, for this handler, 'inclusion_flag' is always set to
true, the array of roles 'role_filter' is always non-empty, while
the array of node identifiers 'id_filter' is always empty.
However, this is not necessarily the case for other handlers using
the 'get_creds' parameter.
'client_cred', encoded as a CBOR byte string, with value the
original binary representation of the Client's authentication
credential.  This parameter is used if the KDC is managing
(collecting from/distributing to the Client) the authentication
credentials of the group members, and if the Client's role in the
group will require for it to send messages to one or more group
members.  It is REQUIRED of the application profiles to define the
specific formats that are acceptable to use for authentication
credentials in the group (REQ6).
'client_cred_verify', encoded as a CBOR byte string.  This
parameter MUST be present if the 'client_cred' parameter is
present and no public key associated to the Client's token can be
retrieved for that group.
'client_cred_verify', encoded as a CBOR byte string.  This
parameter MUST be present if the 'client_cred' parameter is
present and no authentication credential associated with the
Client's token can be retrieved for that group.
A possible type of PoP evidence is a signature, that the Client
computes by using its own private key, whose corresponding public
key is specified in the 'client_cred' parameter.  Application
profiles of this specification MUST specify the exact approaches
used to compute the PoP evidence to include in
'client_cred_verify', and MUST specify which of those approaches
is used in which case (REQ14).
'pub_keys_repos', which can be present if the format of the
Client's public key in the 'client_cred' parameter is a
certificate.  In such a case, this parameter has as value the URI
of the certificate.  This parameter is encoded as a CBOR text
string.  Alternative specific encodings of this parameter MAY be
defined in applications of this specification (OPT6).
A possible type of PoP evidence is a signature, that the Client
computes by using its own private key, whose corresponding public
key is specified in the authentication credential carried in the
'client_cred' parameter.  Application profiles of this
specification MUST specify the exact approaches used to compute
the PoP evidence to include in 'client_cred_verify', and MUST
specify which of those approaches is used in which case (REQ14).
'creds_repo', which can be present if the format of the Client's
authentication credential in the 'client_cred' parameter is a
certificate.  In such a case, this parameter has as value the URI
of the certificate.  This parameter is encoded as a CBOR text
string.  Alternative specific encodings of this parameter MAY be
defined in applications of this specification (OPT6).
If 'control_uri' is specified in the Joining Request, the Client
acts as a CoAP server and hosts a resource at this specific URI.
The KDC MAY use this URI to send CoAP requests to the Client
(acting as CoAP server in this exchange), for example for one-to-
one provisioning of new group keying material when performing a
group rekeying (see update-keys), or to inform the Client of its
removal from the group sec-node-removal.
If 'control_uri' is specified in the Join Request, the Client acts
as a CoAP server and hosts a resource at this specific URI.  The
KDC MAY use this URI to send CoAP requests to the Client (acting
as CoAP server in this exchange), for example for one-to-one
provisioning of new group keying material when performing a group
rekeying (see update-keys), or to inform the Client of its removal
from the group sec-node-removal.
The handler considers the scope specified in the access token
associated to the Client, and checks the scope entry related to the
group with name GROUPNAME associated to the endpoint.  In particular,
the handler checks whether the set of roles specified in that scope
entry includes all the roles that the Client wishes to have in the
group as per the Joining Request.  If this is not the case, the KDC
MUST reply with a 4.03 (Forbidden) error response.
If the KDC manages the group members' public keys, the handler checks
if one is included in the 'client_cred' field.  If so, the KDC
retrieves the public key and performs the following actions.
If the access token was provided through a Token Transfer Request
(see token-post) but the KDC cannot retrieve the 'kdcchallenge'
associated to this Client (see token-post), the KDC MUST reply
with a 4.00 Bad Request error response, which MUST also have
Content-Format application/ace-groupcomm+cbor.  The payload of the
error response is a CBOR map including a newly generated
'kdcchallenge' value.  This is specified in the 'kdcchallenge'
parameter.
The KDC checks the public key to be valid for the group identified
by GROUPNAME.  That is, it checks that the public key is encoded
according to the format used in the group, is intended for the
public key algorithm used in the group, and is aligned with the
possible associated parameters used in the group.
If this verification fails, the handler MUST reply with a 4.00
(Bad Request) error response.  The response MUST have Content-
Format set to application/ace-groupcomm+cbor and is formatted as
defined in key-distr.  The value of the 'error' field MUST be set
to 2 ("Public key incompatible with the group configuration").
The handler considers the scope specified in the access token
associated with the Client, and checks the scope entry related to the
group with name GROUPNAME associated with the endpoint.  In
particular, the handler checks whether the set of roles specified in
that scope entry includes all the roles that the Client wishes to
have in the group as per the Join Request.  If this is not the case,
the KDC MUST reply with a 4.03 (Forbidden) error response.
If the KDC manages the group members' authentication credentials, the
handler checks if one is included in the 'client_cred' field.  If so,
the KDC retrieves the authentication credential and performs the
following actions.
If the access token was provided through a Token Transfer Request
(see token-post) but the KDC cannot retrieve the 'kdcchallenge'
associated with this Client (see token-post), the KDC MUST reply
with a 4.00 Bad Request error response, which MUST also have
Content-Format application/ace-groupcomm+cbor.  The payload of the
error response is a CBOR map including a newly generated
'kdcchallenge' value.  This is specified in the 'kdcchallenge'
parameter.
The KDC checks the authentication credential to be valid for the
group identified by GROUPNAME.  That is, it checks that the
authentication credential has the format used in the group, is
intended for the public key algorithm used in the group, and is
aligned with the possible associated parameters used in the group.
If this verification fails, the handler MUST reply with a 4.00
(Bad Request) error response.  The response MUST have Content-
Format set to application/ace-groupcomm+cbor and is formatted as
defined in key-distr.  The value of the 'error' field MUST be set
to 2 ("Authentication credential incompatible with the group
configuration").
If no public key is included in the 'client_cred' field, the handler
checks if a public key is already associated to the received access
token and to the group identified by GROUPNAME (see also ssec-key-
distribution-exchange).  Note that the same joining node may use
different public keys in different groups, and all those public keys
would be associate to the same access token.
If an eligible public key for the Client is neither present in the
'client_cred' field nor retrieved from the stored ones at the KDC, it
is RECOMMENDED that the handler stops the processing and replies with
a 4.00 (Bad Request) error response.  Applications profiles MAY
define alternatives (OPT8).
If, regardless the reason, the KDC replies with a 4.00 (Bad Request)
error response, this response MAY have Content-Format set to
application/ace-groupcomm+cbor and have a CBOR map as payload.  For
instance, the CBOR map can include a 'sign_info' parameter formatted
as 'sign_info_res' defined in sign-info, with the 'pub_key_enc'
element set to the CBOR simple value 'null' (0xf6) if the Client sent
its own public key and the KDC is not set to store public keys of the
group members.
If no authentication credential is included in the 'client_cred'
field, the handler checks if an authentication credential is already
associated with the received access token and to the group identified
by GROUPNAME (see also ssec-key-distribution-exchange).  Note that
the same joining node may use different authentication credentials in
different groups, and all those authentication credentials would be
associated with the same access token.
If an eligible authentication credential for the Client is neither
present in the 'client_cred' field nor retrieved from the stored ones
at the KDC, it is RECOMMENDED that the handler stops the processing
and replies with a 4.00 (Bad Request) error response.  Applications
profiles MAY define alternatives (OPT8).
If, regardless the reason, the KDC replies with a 4.00 (Bad Request)
error response, this response MAY have Content-Format set to
application/ace-groupcomm+cbor and have a CBOR map as payload.  For
instance, the CBOR map can include a 'sign_info' parameter formatted
as 'sign_info_res' defined in sign-info, with the 'cred_fmt' element
set to the CBOR simple value "null" (0xf6) if the Client sent its own
authentication credential and the KDC is not set to store
authentication credentials of the group members.
The handler associates the retrieved Client's public key to the
tuple composed of the node name NODENAME, the group name
GROUPNAME and the received access token.
The handler adds the retrieved Client's public key to the
stored list of public keys stored for the group identified by
GROUPNAME.  If such list already includes a public key for the
Client, but a different public key is specified in the
'client_cred' field, then the handler MUST replace the old
public key in the list with the one specified in the
'client_cred' field.
The handler returns a successful Joining Response as defined
below, containing the symmetric group keying material; the group
policies; and the public keys of the current members of the group,
if the KDC manages those and the Client requested them.
The Joining Response MUST have response code 2.01 (Created) if the
Client has been added to the list of group members in this joining
exchange (see above), or 2.04 (Changed) otherwise, i.e., if the
Client is re-joining the group without having left it.
The Joining Response message MUST include the Location-Path CoAP
option, specifying the URI path to the sub-resource associated to the
Client, i.e. "/ace-group/GROUPNAME/nodes/NODENAME".
The Joining Response message MUST have Content-Format application/
ace-groupcomm+cbor.  The payload of the response is formatted as a
CBOR map, which MUST contain the following fields and values.
The handler associates the retrieved Client's authentication
credential to the tuple composed of the node name NODENAME, the
group name GROUPNAME and the received access token.
The handler adds the retrieved Client's authentication
credential to the stored list of authentication credentials
stored for the group identified by GROUPNAME.  If such list
already includes an authentication credential for the Client,
but a different authentication credential is specified in the
'client_cred' field, then the handler MUST replace the old
authentication credential in the list with the one specified in
the 'client_cred' field.
The handler returns a successful Join Response as defined below,
containing the symmetric group keying material; the group
policies; and the authentication credentials of the current
members of the group, if the KDC manages those and the Client
requested them.
The Join Response MUST have response code 2.01 (Created) if the
Client has been added to the list of group members in this join
exchange (see above), or 2.04 (Changed) otherwise, i.e., if the
Client is re-joining the group without having left it.
The Join Response message MUST include the Location-Path CoAP option,
specifying the URI path to the sub-resource associated with the
Client, i.e. "/ace-group/GROUPNAME/nodes/NODENAME".
The Join Response message MUST have Content-Format application/ace-
groupcomm+cbor.  The payload of the response is formatted as a CBOR
map, which MUST contain the following fields and values.
'pub_keys', MUST be present if 'get_pub_keys' was present in the
request, otherwise it MUST NOT be present.  This parameter is a
CBOR array specifying the public keys of the group members, i.e.,
of all of them or of the ones selected according to the
'get_pub_keys' parameter in the request.  In particular, each
element of the array is a CBOR byte string, with value the
original binary representation of a group member's public key.  It
is REQUIRED of the application profiles to define the specific
formats of public keys that are acceptable to use in the group
(REQ6).
'peer_roles', MUST be present if 'pub_keys' is also present,
otherwise it MUST NOT be present.  This parameter is a CBOR array
of n elements, with n the number of public keys included in the
'pub_keys' parameter (at most the number of members in the group).
The i-th element of the array specifies the role (or CBOR array of
roles) that the group member associated to the i-th public key in
'pub_keys' has in the group.  In particular, each array element is
encoded as the role element of a scope entry, as defined in ssec-
authorization-request.
'peer_identifiers', MUST be present if 'pub_keys' is also present,
otherwise it MUST NOT be present.  This parameter is a CBOR array
of n elements, with n the number of public keys included in the
'pub_keys' parameter (at most the number of members in the group).
The i-th element of the array specifies the node identifier that
the group member associated to the i-th public key in 'pub_keys'
has in the group.  In particular, the i-th array element is
encoded as a CBOR byte string, with value the node identifier of
the group member.
'creds', MUST be present if 'get_creds' was present in the
request, otherwise it MUST NOT be present.  This parameter is a
CBOR array specifying the authentication credentials of the group
members, i.e., of all of them or of the ones selected according to
the 'get_creds' parameter in the request.  In particular, each
element of the array is a CBOR byte string, with value the
original binary representation of a group member's authentication
credential.  It is REQUIRED of the application profiles to define
the specific formats of authentication credentials that are
acceptable to use in the group (REQ6).
'peer_roles', MUST be present if 'creds' is also present,
otherwise it MUST NOT be present.  This parameter is a CBOR array
of n elements, with n the number of authentication credentials
included in the 'creds' parameter (at most the number of members
in the group).  The i-th element of the array specifies the role
(or CBOR array of roles) that the group member associated with the
i-th authentication credential in 'creds' has in the group.  In
particular, each array element is encoded as the role element of a
scope entry, as defined in ssec-authorization-request.
'peer_identifiers', MUST be present if 'creds' is also present,
otherwise it MUST NOT be present.  This parameter is a CBOR array
of n elements, with n the number of authentication credentials
included in the 'creds' parameter (at most the number of members
in the group).  The i-th element of the array specifies the node
identifier that the group member associated with the i-th
authentication credential in 'creds' has in the group.  In
particular, the i-th array element is encoded as a CBOR byte
string, with value the node identifier of the group member.
'kdc_cred', encoded as a CBOR byte string, with value the original
binary representation of the KDC's public key.  This parameter is
used if the KDC has an associated public key and this is required
for the correct group operation.  It is REQUIRED of application
profiles to define whether the KDC has a public key and if this
has to be provided through the 'kdc_cred' parameter (REQ8).
In such a case, the KDC's public key MUST have the same format
used for the public keys of the group members.  It is REQUIRED of
the application profiles to define the specific formats that are
acceptable to use for encoding public keys in the group (REQ6).
'kdc_cred', encoded as a CBOR byte string, with value the original
binary representation of the KDC's authentication credential.
This parameter is used if the KDC has an associated authentication
credential and this is required for the correct group operation.
It is REQUIRED of application profiles to define whether the KDC
has an authentication credential and if this has to be provided
through the 'kdc_cred' parameter (REQ8).
In such a case, the KDC's authentication credential MUST have the
same format used for the authentication credentials of the group
members.  It is REQUIRED of the application profiles to define the
specific formats that are acceptable to use for the authentication
credentials in the group (REQ6).
A possible type of PoP evidence is a signature, that the KDC
computes by using its own private key, whose corresponding public
key is specified in the 'kdc_cred' parameter.  Application
profiles of this specification MUST specify the exact approaches
used by the KDC to compute the PoP evidence to include in
'kdc_cred_verify', and MUST specify which of those approaches is
used in which case (REQ21).
A possible type of PoP evidence is a signature, that the KDC
computes by using its own private key, whose corresponding public
key is specified in the authentication credential carried in the
'kdc_cred' parameter.  Application profiles of this specification
MUST specify the exact approaches used by the KDC to compute the
PoP evidence to include in 'kdc_cred_verify', and MUST specify
which of those approaches is used in which case (REQ21).
Application profiles of this specification MAY define a default group
rekeying scheme, to refer to in case the 'rekeying_scheme' parameter
is not included in the Joining Response (OPT9).
Application profiles of this specification MAY define a default group
rekeying scheme, to refer to in case the 'rekeying_scheme' parameter
is not included in the Join Response (OPT9).
In more advanced group rekeying schemes, the administrative keying
material can be composed of multiple keys organized, for instance,
into a logical tree hierarchy, whose root key is the only
administrative key shared by all the group members.  In such a
case, each group member is exclusively associated to one leaf key
in the hierarchy, and owns only the administrative keys from the
associated leaf key all the way up along the path to the root key.
That is, different group members can be provided with a different
subset of the overall administrative keying material.
In more advanced group rekeying schemes, the administrative keying
material can be composed of multiple keys organized, for instance,
into a logical tree hierarchy, whose root key is the only
administrative key shared by all the group members.  In such a
case, each group member is exclusively associated with one leaf
key in the hierarchy, and owns only the administrative keys from
the associated leaf key all the way up along the path to the root
key.  That is, different group members can be provided with a
different subset of the overall administrative keying material.
If 'control_group_uri' is included in the Joining Response, the
Clients supporting this parameter act as CoAP servers, host a
resource at this specific URI, and listen to the specified
addressing information.
If 'control_group_uri' is included in the Join Response, the
Clients supporting this parameter act as CoAP servers, host a
resource at this specific URI, and listen to the specified
addressing information.
If the Joining Response includes the 'kdc_cred_verify' parameter, the
Client verifies the conveyed PoP evidence and considers the group
joining unsuccessful in case of failed verification.  Application
profiles of this specification MUST specify the exact approaches used
by the Client to verify the PoP evidence in 'kdc_cred_verify', and
MUST specify which of those approaches is used in which case (REQ21).
If the Join Response includes the 'kdc_cred_verify' parameter, the
Client verifies the conveyed PoP evidence and considers the group
joining unsuccessful in case of failed verification.  Application
profiles of this specification MUST specify the exact approaches used
by the Client to verify the PoP evidence in 'kdc_cred_verify', and
MUST specify which of those approaches is used in which case (REQ21).
fig-key-distr-join gives an overview of the Joining exchange between
Client and KDC, when the Client first joins a group, while fig-key-
distr-join-2 shows an example.
If not previously established, the Client and the KDC MUST first
establish a pairwise secure communication channel (REQ24).  This can
be achieved, for instance, by using a transport profile of ACE.  The
Joining exchange MUST occur over that secure channel.  The Client and
the KDC MAY use that same secure channel to protect further pairwise
communications that must be secured.
fig-key-distr-join gives an overview of the join exchange between
Client and KDC, when the Client first joins a group, while fig-key-
distr-join-2 shows an example.
If not previously established, the Client and the KDC MUST first
establish a pairwise secure communication channel (REQ24).  This can
be achieved, for instance, by using a transport profile of ACE.  The
join exchange MUST occur over that secure channel.  The Client and
the KDC MAY use that same secure channel to protect further pairwise
communications that must be secured.
If the node is joining a group for the first time, and the KDC
maintains the public keys of the group members, the Client is
REQUIRED to send its own public key and proof-of-possession (PoP)
evidence in the Joining Request (see the 'client_cred' and
'client_cred_verify' parameters in gid-post).  The request is
accepted only if both public key is provided and the PoP evidence is
successfully verified.
If a node re-joins a group as authorized by the same access token and
using the same public key, it can omit the public key and the PoP
evidence, or just the PoP evidence, from the Joining Request.  Then,
the KDC will be able to retrieve the node's public key associated to
the access token for that group.  If the public key has been
discarded, the KDC replies with 4.00 (Bad Request) error response, as
specified in gid-post.  If a node re-joins a group but wants to
update its own public key, it needs to include both its public key
and the PoP evidence in the Joining Request like when it joined the
group for the first time.
If the node is joining a group for the first time, and the KDC
maintains the authentication credentials of the group members, the
Client is REQUIRED to send its own authentication credential and
proof-of-possession (PoP) evidence in the Join Request (see the
'client_cred' and 'client_cred_verify' parameters in gid-post).  The
request is accepted only if both the authentication credential is
provided and the PoP evidence is successfully verified.
If a node re-joins a group as authorized by the same access token and
using the same authentication credential, it can omit the
authentication credential and the PoP evidence, or just the PoP
evidence, from the Join Request.  Then, the KDC will be able to
retrieve the node's authentication credential associated with the
access token for that group.  If the authentication credential has
been discarded, the KDC replies with 4.00 (Bad Request) error
response, as specified in gid-post.  If a node re-joins a group but
wants to update its own authentication credential, it needs to
include both its authentication credential and the PoP evidence in
the Join Request like when it joined the group for the first time.
Each of the following parameters specified in gid-post MUST also be
included in the payload of the response, if they are included in the
payload of the Joining Responses sent for the group:
'rekeying_scheme', 'mgt_key_material'.
Each of the following parameters specified in gid-post MUST also be
included in the payload of the response, if they are included in the
payload of the Join Responses sent for the group: 'rekeying_scheme',
'mgt_key_material'.
fig-retrieve-key-material gives an overview of the Joining exchange
between Client and KDC, when the Client first joins a group, while
fig-retrieve-key-material-2 shows an example.
fig-retrieve-key-material gives an overview of the join exchange
between Client and KDC, when the Client first joins a group, while
fig-retrieve-key-material-2 shows an example.
The FETCH handler receives identifiers of group members for the group
identified by GROUPNAME and returns the public keys of such group
members.
'get_pub_keys', whose value is encoded as in gid-post with the
following modifications.
The arrays 'role_filter' and 'id_filter' MUST NOT both be
empty, i.e., in CBOR diagnostic notation: [ bool, [ ], [ ] ].
If the 'get_pub_keys' parameter has such a format, the request
MUST be considered malformed, and the KDC MUST reply with a
4.00 (Bad Request) error response.
Note that a group member can retrieve the public keys of all
the current group members by sending a GET request to the same
KDC resource instead (see sec-key-retrieval-all).
The element 'inclusion_flag' encodes the CBOR simple value True
if the third element 'id_filter' specifies an empty CBOR array,
or if the Client wishes to receive the public keys of the nodes
having their node identifier specified in 'id_filter' (i.e,
selection by inclusive filtering).  Instead, this element
encodes the CBOR simple value False if the Client wishes to
receive the public keys of the nodes not having the node
identifiers specified in the third element 'id_filter' (i.e.,
selection by exclusive filtering).
The array 'role_filter' can be empty, if the Client does not
wish to filter the requested public keys based on the roles of
the group members.
The array 'id_filter' contains zero or more node identifiers of
group members, for the group identified by GROUPNAME.  The
Client indicates that it wishes to receive the public keys of
the nodes having or not having these node identifiers, in case
the 'inclusion_flag' element encodes the CBOR simple value True
or False, respectively.  The array 'id_filter' may be empty, if
the Client does not wish to filter the requested public keys
based on the node identifiers of the group members.
If the 'inclusion_flag' encodes the CBOR simple value True, the
handler returns the public keys of group members whose roles match
with 'role_filter' and/or having their node identifier specified
in 'id_filter'.
If the 'inclusion_flag' encodes the CBOR simple value False, the
handler returns the public keys of group members whose roles match
with 'role_filter' and, at the same time, not having their node
identifier specified in 'id_filter'.
The specific format of public keys as well as identifiers, roles and
combination of roles of group members MUST be specified by It is
REQUIRED of application profiles of this specification (REQ1, REQ6,
REQ25).
The FETCH handler receives identifiers of group members for the group
identified by GROUPNAME and returns the authentication credentials of
such group members.
'get_creds', whose value is encoded as in gid-post with the
following modifications.
The arrays 'role_filter' and 'id_filter' MUST NOT both be
empty, i.e., in CBOR diagnostic notation: [ bool, [ ], [ ] ].
If the 'get_creds' parameter has such a format, the request
MUST be considered malformed, and the KDC MUST reply with a
4.00 (Bad Request) error response.
Note that a group member can retrieve the authentication
credentials of all the current group members by sending a GET
request to the same KDC resource instead (see sec-key-
retrieval-all).
The element 'inclusion_flag' encodes the CBOR simple value
"true" (0xf5) if the third element 'id_filter' specifies an
empty CBOR array, or if the Client wishes to receive the
authentication credentials of the nodes having their node
identifier specified in 'id_filter' (i.e, selection by
inclusive filtering).  Instead, this element encodes the CBOR
simple value "false" (0xf4) if the Client wishes to receive the
authentication credentials of the nodes not having the node
identifiers specified in the third element 'id_filter' (i.e.,
selection by exclusive filtering).
The array 'role_filter' can be empty, if the Client does not
wish to filter the requested authentication credentials based
on the roles of the group members.
The array 'id_filter' contains zero or more node identifiers of
group members, for the group identified by GROUPNAME.  The
Client indicates that it wishes to receive the authentication
credentials of the nodes having or not having these node
identifiers, in case the 'inclusion_flag' element encodes the
CBOR simple value "true" (0xf5) or "false" (0xf4),
respectively.  The array 'id_filter' may be empty, if the
Client does not wish to filter the requested authentication
credentials based on the node identifiers of the group members.
If the 'inclusion_flag' encodes the CBOR simple value "true"
(0xf5), the handler returns the authentication credentials of
group members whose roles match with 'role_filter' and/or having
their node identifier specified in 'id_filter'.
If the 'inclusion_flag' encodes the CBOR simple value "false"
(0xf4), the handler returns the authentication credentials of
group members whose roles match with 'role_filter' and, at the
same time, not having their node identifier specified in
'id_filter'.
The specific format of authentication credentials as well as
identifiers, roles and combination of roles of group members MUST be
specified by application profiles of this specification (REQ1, REQ6,
REQ25).
'pub_keys', which encodes the list of public keys of the selected
group members.
'creds', which encodes the list of authentication credentials of
the selected group members.
The specific format of public keys as well as of node identifiers of
group members is specified by the application profile (REQ6, REQ25).
If the KDC does not store any public key associated to the specified
node identifiers, the handler returns a response with payload
formatted as a CBOR byte string of zero length.
The handler MAY enforce one of the following policies, in order to
handle possible node identifiers that are included in the 'id_filter'
element of the 'get_pub_keys' parameter of the request but are not
associated to any current group member.  Such a policy MUST be
specified by the application profile (REQ26).
The KDC retains public keys of group members for a given amount of
time after their leaving, before discarding them.  As long as such
public keys are retained, the KDC provides them to a requesting
Client.
If the KDC adopts this policy, the application profile MUST also
specify the amount of time during which the KDC retains the public
key of a former group member after its leaving, possibly on a per-
member basis.
The specific format of authentication credentials as well as of node
identifiers of group members is specified by the application profile
(REQ6, REQ25).
If the KDC does not store any authentication credential associated
with the specified node identifiers, the handler returns a response
with payload formatted as a CBOR byte string of zero length.
The handler MAY enforce one of the following policies, in order to
handle possible node identifiers that are included in the 'id_filter'
element of the 'get_creds' parameter of the request but are not
associated with any current group member.  Such a policy MUST be
specified by the application profile (REQ26).
The KDC retains authentication credentials of group members for a
given amount of time after their leaving, before discarding them.
As long as such authentication credentials are retained, the KDC
provides them to a requesting Client.
If the KDC adopts this policy, the application profile MUST also
specify the amount of time during which the KDC retains the
authentication credential of a former group member after its
leaving, possibly on a per-member basis.
In case the KDC maintains the public keys of group members, a node in
the group can contact the KDC to request the public keys, roles and
node identifiers of a specified subset of group members, by sending a
CoAP FETCH request to the /ace-group/GROUPNAME/pub-key endpoint at
the KDC, where GROUPNAME is the group name, and formatted as defined
in pubkey-fetch.
In case the KDC maintains the authentication credentials of group
members, a node in the group can contact the KDC to request the
authentication credentials, roles and node identifiers of a specified
subset of group members, by sending a CoAP FETCH request to the /ace-
group/GROUPNAME/creds endpoint at the KDC, where GROUPNAME is the
group name, and formatted as defined in pubkey-fetch.
If all verifications succeed, the KDC replies with a 2.05 (Content)
response as in the FETCH handler in pubkey-fetch, but specifying in
the payload the public keys of all the group members, together with
their roles and node identifiers.
In case the KDC maintains the public keys of group members, a group
or an external signature verifier can contact the KDC to request the
public keys, roles and node identifiers of all the current group
members, by sending a CoAP GET request to the /ace-group/GROUPNAME/
pub-key endpoint at the KDC, where GROUPNAME is the group name.
If all verifications succeed, the KDC replies with a 2.05 (Content)
response as in the FETCH handler in pubkey-fetch, but specifying in
the payload the authentication credentials of all the group members,
together with their roles and node identifiers.
In case the KDC maintains the authentication credentials of group
members, a group or an external signature verifier can contact the
KDC to request the authentication credentials, roles and node
identifiers of all the current group members, by sending a CoAP GET
request to the /ace-group/GROUPNAME/creds endpoint at the KDC, where
GROUPNAME is the group name.
If all verifications succeed, the handler returns a 2.05 (Content)
message containing the KDC's public key together with a proof-of-
possession (PoP) evidence.  The response MUST have Content-Format set
to application/ace-groupcomm+cbor.  The payload of the response is a
CBOR map, which includes the following fields.
The 'kdc_cred' parameter, specifying the KDC's public key.  This
parameter is encoded like the 'kdc_cred' parameter in the Joining
Response (see gid-post).
The 'kdc_nonce' parameter, specifying a nonce generated by the
KDC.  This parameter is encoded like the 'kdc_nonce' parameter in
the Joining Response (see gid-post).
The 'kdc_cred_verify' parameter, specifying a PoP evidence
computed by the KDC.  This parameter is encoded like the
'kdc_cred_verify' parameter in the Joining Response (see gid-
post).
The PoP evidence is computed over the nonce specified in the
'kdc_nonce' parameter and taken as PoP input, by means of the same
method used when preparing the Joining Response (see gid-post).
Application profiles of this specification MUST specify the exact
approaches used by the KDC to compute the PoP evidence to include
in 'kdc_cred_verify', and MUST specify which of those approaches
is used in which case (REQ21).
If all verifications succeed, the handler returns a 2.05 (Content)
message containing the KDC's authentication credential together with
a proof-of-possession (PoP) evidence.  The response MUST have
Content-Format set to application/ace-groupcomm+cbor.  The payload of
the response is a CBOR map, which includes the following fields.
The 'kdc_cred' parameter, specifying the KDC's authentication
credential.  This parameter is encoded like the 'kdc_cred'
parameter in the Join Response (see gid-post).
The 'kdc_nonce' parameter, specifying a nonce generated by the
KDC.  This parameter is encoded like the 'kdc_nonce' parameter in
the Join Response (see gid-post).
The 'kdc_cred_verify' parameter, specifying a PoP evidence
computed by the KDC.  This parameter is encoded like the
'kdc_cred_verify' parameter in the Join Response (see gid-post).
The PoP evidence is computed over the nonce specified in the
'kdc_nonce' parameter and taken as PoP input, by means of the same
method used when preparing the Join Response (see gid-post).
Application profiles of this specification MUST specify the exact
approaches used by the KDC to compute the PoP evidence to include
in 'kdc_cred_verify', and MUST specify which of those approaches
is used in which case (REQ21).
In case the KDC has an associated public key as required for the
correct group operation, a group member or an external signature
verifier can contact the KDC to request the KDC's public key, by
sending a CoAP GET request to the /ace-group/GROUPNAME/kdc-pub-key
endpoint at the KDC, where GROUPNAME is the group name.
Upon receiving the 2.05 (Content) response, the Client retrieves the
KDC's public key from the 'kdc_cred' parameter, and MUST verify the
proof-of-possession (PoP) evidence specified in the 'kdc_cred_verify'
parameter.  In case of successful verification of the PoP evidence,
the Client MUST store the obtained KDC's public key and replace the
currently stored one.
The PoP evidence is verified by means of the same method used when
processing the Joining Response (see gid-post).  Application profiles
of this specification MUST specify the exact approaches used by the
Client to verify the PoP evidence in 'kdc_cred_verify', and MUST
specify which of those approaches is used in which case (REQ21).
In case the KDC has an associated authentication credential as
required for the correct group operation, a group member or an
external signature verifier can contact the KDC to request the KDC's
authentication credential, by sending a CoAP GET request to the /ace-
group/GROUPNAME/kdc-cred endpoint at the KDC, where GROUPNAME is the
group name.
Upon receiving the 2.05 (Content) response, the Client retrieves the
KDC's authentication credential from the 'kdc_cred' parameter, and
MUST verify the proof-of-possession (PoP) evidence specified in the
'kdc_cred_verify' parameter.  In case of successful verification of
the PoP evidence, the Client MUST store the obtained KDC's
authentication credential and replace the currently stored one.
The PoP evidence is verified by means of the same method used when
processing the Join Response (see gid-post).  Application profiles of
this specification MUST specify the exact approaches used by the
Client to verify the PoP evidence in 'kdc_cred_verify', and MUST
specify which of those approaches is used in which case (REQ21).
Upon expiration of the keying material, according to what
indicated by the KDC with the 'exp' parameter in a Joining
Response, or to a pre-configured value.
Upon expiration of the keying material, according to what
indicated by the KDC with the 'exp' parameter in a Join Response,
or to a pre-configured value.
A Client may ask the KDC for new, individual keying material.  For
instance, this can be due to the expiration of such individual keying
material, or to the exhaustion of AEAD nonces, if an AEAD encryption
algorithm is used for protecting communications in the group.  An
example of individual keying material can simply be an individual
encryption key associated to the Client.  Hence, the Client may ask
for a new individual encryption key, or for new input material to
derive it.
To this end, the Client performs a Key Renewal Request/Response
exchange with the KDC, i.e., it sends a CoAP PUT request to the /ace-
group/GROUPNAME/nodes/NODENAME endpoint at the KDC, where GROUPNAME
is the group name and NODENAME is its node name, and formatted as
defined in node-get.
A Client may ask the KDC for new, individual keying material.  For
instance, this can be due to the expiration of such individual keying
material, or to the exhaustion of AEAD nonces, if an AEAD encryption
algorithm is used for protecting communications in the group.  An
example of individual keying material can simply be an individual
encryption key associated with the Client.  Hence, the Client may ask
for a new individual encryption key, or for new input material to
derive it.
To this end, the Client performs a Key Renewal Request-Response
exchange with the KDC, i.e., it sends a CoAP PUT request to the /ace-
group/GROUPNAME/nodes/NODENAME endpoint at the KDC, where GROUPNAME
is the group name and NODENAME is its node name, and formatted as
defined in node-get.
The POST handler is used to replace the stored public key of this
Client (identified by NODENAME) with the one specified in the request
at the KDC, for the group identified by GROUPNAME.
The POST handler is used to replace the stored authentication
credential of this Client (identified by NODENAME) with the one
specified in the request at the KDC, for the group identified by
GROUPNAME.
The handler expects a POST request with payload as specified in gid-
post, with the difference that it includes only the parameters
'client_cred', 'cnonce' and 'client_cred_verify'.  In particular, the
PoP evidence included in 'client_cred_verify' is computed in the same
way considered in gid-post and defined by the specific application
profile (REQ14), with a newly generated N_C nonce and the previously
received N_S.  It is REQUIRED of the application profiles to define
the specific formats of public keys that are acceptable to use in the
group (REQ6).
The handler expects a POST request with payload as specified in gid-
post, with the difference that it includes only the parameters
'client_cred', 'cnonce' and 'client_cred_verify'.  In particular, the
PoP evidence included in 'client_cred_verify' is computed in the same
way considered in gid-post and defined by the specific application
profile (REQ14), with a newly generated N_C nonce and the previously
received N_S.  It is REQUIRED of the application profiles to define
the specific formats of authentication credentials that are
acceptable to use in the group (REQ6).
If the KDC cannot retrieve the 'kdcchallenge' associated to this
Client (see token-post), the KDC MUST reply with a 4.00 (Bad Request)
error response, which MUST also have Content-Format application/ace-
groupcomm+cbor.  The payload of the error response is a CBOR map
including a newly generated 'kdcchallenge' value.  This is specified
in the 'kdcchallenge' parameter.  In such a case the KDC MUST store
the newly generated value as the 'kdcchallenge' value associated to
this Client, possibly replacing the currently stored value.
Otherwise, the handler checks that the public key specified in the
'client_cred' field is valid for the group identified by GROUPNAME.
That is, the handler checks that the public key is encoded according
to the format used in the group, is intended for the public key
algorithm used in the group, and is aligned with the possible
associated parameters used in the group.  If that cannot be
successfully verified, the handler MUST reply with a 4.00 (Bad
Request) error response.  The response MUST have Content-Format set
to application/ace-groupcomm+cbor and is formatted as defined in key-
distr.  The value of the 'error' field MUST be set to 2 ("Public key
incompatible with the group configuration").
Otherwise, the handler verifies the PoP evidence contained in the
'client_cred_verify' field of the request, by using the public key
specified in the 'client_cred' field, as well as the same way
considered in gid-post and defined by the specific application
profile (REQ14).  If the PoP evidence does not pass verification, the
handler MUST reply with a 4.00 (Bad Request) error response.  The
response MUST have Content-Format set to application/ace-
groupcomm+cbor and is formatted as defined in key-distr.  The value
of the 'error' field MUST be set to 3 ("Invalid Proof-of-Possession
evidence").
The handler associates the public key from the 'client_cred' field
of the request to the node identifier NODENAME and to the access
token associated to the node identified by NODENAME.
In the stored list of group members' public keys for the group
identified by GROUPNAME, the handler replaces the public key of
the node identified by NODENAME with the public key specified in
the 'client_cred' field of the request.
In case the KDC maintains the public keys of group members, a node in
the group can contact the KDC to upload a new public key to use in
the group, and replace the currently stored one.
To this end, the Client performs a Public Key Update Request/Response
exchange with the KDC, i.e., it sends a CoAP POST request to the
/ace-group/GROUPNAME/nodes/NODENAME/pub-key endpoint at the KDC,
where GROUPNAME is the group name and NODENAME is its node name.
If the KDC cannot retrieve the 'kdcchallenge' associated with this
Client (see token-post), the KDC MUST reply with a 4.00 (Bad Request)
error response, which MUST also have Content-Format application/ace-
groupcomm+cbor.  The payload of the error response is a CBOR map
including a newly generated 'kdcchallenge' value.  This is specified
in the 'kdcchallenge' parameter.  In such a case the KDC MUST store
the newly generated value as the 'kdcchallenge' value associated with
this Client, possibly replacing the currently stored value.
Otherwise, the handler checks that the authentication credential
specified in the 'client_cred' field is valid for the group
identified by GROUPNAME.  That is, the handler checks that the
authentication credential is encoded according to the format used in
the group, is intended for the public key algorithm used in the
group, and is aligned with the possible associated parameters used in
the group.  If that cannot be successfully verified, the handler MUST
reply with a 4.00 (Bad Request) error response.  The response MUST
have Content-Format set to application/ace-groupcomm+cbor and is
formatted as defined in key-distr.  The value of the 'error' field
MUST be set to 2 ("Authentication Credential incompatible with the
group configuration").
Otherwise, the handler verifies the PoP evidence contained in the
'client_cred_verify' field of the request, by using the
authentication credential specified in the 'client_cred' field, as
well as the same way considered in gid-post and defined by the
specific application profile (REQ14).  If the PoP evidence does not
pass verification, the handler MUST reply with a 4.00 (Bad Request)
error response.  The response MUST have Content-Format set to
application/ace-groupcomm+cbor and is formatted as defined in key-
distr.  The value of the 'error' field MUST be set to 3 ("Invalid
Proof-of-Possession evidence").
The handler associates the authentication credential from the
'client_cred' field of the request to the node identifier NODENAME
and to the access token associated with the node identified by
NODENAME.
In the stored list of group members' authentication credentials
for the group identified by GROUPNAME, the handler replaces the
authentication credential of the node identified by NODENAME with
the authentication credential specified in the 'client_cred' field
of the request.
In case the KDC maintains the authentication credentials of group
members, a node in the group can contact the KDC to upload a new
authentication credential to use in the group, and replace the
currently stored one.
To this end, the Client performs an Authentication Credential Update
Request-Response exchange with the KDC, i.e., it sends a CoAP POST
request to the /ace-group/GROUPNAME/nodes/NODENAME/cred endpoint at
the KDC, where GROUPNAME is the group name and NODENAME is its node
name.
Additionally, after updating its own public key, a group member MAY
send a number of requests including an identifier of the updated
public key, to notify other group members that they have to retrieve
it.  How this is done depends on the group communication protocol
used, and therefore is application profile specific (OPT13).
Additionally, after updating its own authentication credential, a
group member MAY send a number of requests including an identifier of
the updated authentication credential, to notify other group members
that they have to retrieve it.  How this is done depends on the group
communication protocol used, and therefore is application profile
specific (OPT13).
The Client's authorization to be a group member with the current
roles is not valid anymore, i.e., the access token has expired or
has been revoked.  If the AS provides token introspection (see
Section 5.9 of I-D.ietf-ace-oauth-authz), the KDC can optionally
use it and check whether the Client is still authorized.
The Client's authorization to be a group member with the current
roles is not valid anymore, i.e., the access token has expired or
has been revoked.  If the AS provides token introspection (see
Section 5.9 of RFC9200), the KDC can optionally use it and check
whether the Client is still authorized.
In case of forced eviction, i.e., for cases 2 and 3 above, the KDC
deletes the public key of the removed Client, if it acts as
repository of public keys for group members.
In case of forced eviction, i.e., for cases 2 and 3 above, the KDC
deletes the authentication credential of the removed Client, if it
acts as repository of authentication credentials for group
members.
If the evicted Client implements the 'control_uri' resource
specified in gid-post, the KDC sends a DELETE request,
targeting the URI specified in the 'control_uri' parameter of
the Joining Request (see gid-post).
If the evicted Client implements the 'control_uri' resource
specified in gid-post, the KDC sends a DELETE request,
targeting the URI specified in the 'control_uri' parameter of
the Join Request (see gid-post).
A rekeying message may include additional information, depending on
the rekeying scheme used in the group, the reason that has triggered
the rekeying process and the specific target group members.  In
particular, if the group rekeying is performed due to one or multiple
Clients that have joined the group and the KDC acts as repository of
public keys of the group members, then a rekeying message MAY also
include the public keys that those Clients use in the group, together
with the roles and node identifier that the corresponding Client has
in the group.  It is RECOMMENDED to specify this information by means
of the parameters 'pub_keys', 'peer_roles' and 'peer_identifiers',
like done in the Joining Response message (see gid-post).
A rekeying message may include additional information, depending on
the rekeying scheme used in the group, the reason that has triggered
the rekeying process and the specific target group members.  In
particular, if the group rekeying is performed due to one or multiple
Clients that have joined the group and the KDC acts as repository of
authentication credentials of the group members, then a rekeying
message MAY also include the authentication credentials that those
Clients use in the group, together with the roles and node identifier
that the corresponding Client has in the group.  It is RECOMMENDED to
specify this information by means of the parameters 'creds',
'peer_roles' and 'peer_identifiers', like done in the Join Response
message (see gid-post).
This is the approach taken by the basic "Point-to-Point" group
rekeying scheme, that the KDC can explicitly signal in the Joining
Response (see gid-post), through the 'rekeying_scheme' parameter
specifying the value 0.
This is the approach taken by the basic "Point-to-Point" group
rekeying scheme, that the KDC can explicitly signal in the Join
Response (see gid-post), through the 'rekeying_scheme' parameter
specifying the value 0.
If a target group member specified a URI in the 'control_uri'
parameter of the Joining Request upon joining the group (see gid-
post), the KDC can provide that group member with the new group
keying material by sending a unicast POST request to that URI.
A Client that does not plan to observe the ace-group/GROUPNAME
resource at the KDC SHOULD provide a URI in the 'control_uri'
parameter of the Joining Request upon joining the group.
If the KDC has to send a rekeying message to a target group member,
but this did not include the 'control_uri' parameter in the Joining
Request and is not a registered observer for the ace-group/GROUPNAME
resource, then that target group member would not be able to
participate to the group rekeying.  Later on, after having repeatedly
failed to successfully exchange secure messages in the group, that
group member can retrieve the current group keying material from the
KDC, by sending a GET request to ace-group/GROUPNAME or ace-
group/GROUPNAME/nodes/NODENAME (see gid-get and node-get,
respectively).
If a target group member specified a URI in the 'control_uri'
parameter of the Join Request upon joining the group (see gid-
post), the KDC can provide that group member with the new group
keying material by sending a unicast POST request to that URI.
A Client that does not plan to observe the ace-group/GROUPNAME
resource at the KDC SHOULD provide a URI in the 'control_uri'
parameter of the Join Request upon joining the group.
If the KDC has to send a rekeying message to a target group member,
but this did not include the 'control_uri' parameter in the Join
Request and is not a registered observer for the ace-group/GROUPNAME
resource, then that target group member would not be able to
participate to the group rekeying.  Later on, after having repeatedly
failed to successfully exchange secure messages in the group, that
group member can retrieve the current group keying material from the
KDC, by sending a GET request to ace-group/GROUPNAME or ace-
group/GROUPNAME/nodes/NODENAME (see gid-get and node-get,
respectively).
When one of these group rekeying schemes is used, the KDC provides a
number of related information to a Client joining the group in the
Joining Response message (see gid-post).  In particular,
'rekeying_scheme' identifies the rekeying scheme used in the group
(if no default can be assumed); 'control_group_uri', if present,
specifies a URI with a multicast address where the KDC will send the
rekeying messages for that group; 'mgt_key_material' specifies a
subset of the administrative keying material intended for that
particular joining Client to have, as used to protect the rekeying
messages sent to the group when intended also to that joining Client.
When one of these group rekeying schemes is used, the KDC provides a
number of related information to a Client joining the group in the
Join Response message (see gid-post).  In particular,
'rekeying_scheme' identifies the rekeying scheme used in the group
(if no default can be assumed); 'control_group_uri', if present,
specifies a URI with a multicast address where the KDC will send the
rekeying messages for that group; 'mgt_key_material' specifies a
subset of the administrative keying material intended for that
particular joining Client to have, as used to protect the rekeying
messages sent to the group when intended also to that joining Client.
Over multicast - In this case, the KDC simply sends a rekeying
message as a CoAP request addressed to the multicast URI specified
in the 'control_group_uri' parameter of the Joining Response (see
gid-post).
Over multicast - In this case, the KDC simply sends a rekeying
message as a CoAP request addressed to the multicast URI specified
in the 'control_group_uri' parameter of the Join Response (see
gid-post).
Through a pub-sub communication model - In this case, the KDC acts
as publisher and publishes each rekeying message to a specific
"rekeying topic", which is associated to the group and is hosted
at a broker server.  Following their group joining, the group
members subscribe to the rekeying topic at the broker, thus
receiving the group rekeying messages as they are published by the
KDC.
In order to make such message delivery more efficient, the
rekeying topic associated to a group can be further organized into
subtopics.  For instance, the KDC can use a particular subtopic to
address a particular set of target group members during the
rekeying process, as possibly aligned to a similar organization of
the administrative keying material (e.g., a key hierarchy).
The setup of rekeying topics at the broker as well as the
discovery of the topics at the broker for group members are
application specific.  A possible way is for the KDC to provide
such information in the Joining Response message (see gid-post),
by means of a new parameter analogous to 'control_group_uri' and
specifying the URI(s) of the rekeying topic(s) that a group member
has to subscribe to at the broker.
Through a pub-sub communication model - In this case, the KDC acts
as publisher and publishes each rekeying message to a specific
"rekeying topic", which is associated with the group and is hosted
at a broker server.  Following their group joining, the group
members subscribe to the rekeying topic at the broker, thus
receiving the group rekeying messages as they are published by the
KDC.
In order to make such message delivery more efficient, the
rekeying topic associated with a group can be further organized
into subtopics.  For instance, the KDC can use a particular
subtopic to address a particular set of target group members
during the rekeying process, as possibly aligned to a similar
organization of the administrative keying material (e.g., a key
hierarchy).
The setup of rekeying topics at the broker as well as the
discovery of the topics at the broker for group members are
application specific.  A possible way is for the KDC to provide
such information in the Join Response message (see gid-post), by
means of a new parameter analogous to 'control_group_uri' and
specifying the URI(s) of the rekeying topic(s) that a group member
has to subscribe to at the broker.
Then, the KDC can protect the rekeying message as defined below.  The
used encryption algorithm which SHOULD be the same one used to
protect communications in the group.  The method defined below
assumes that the following holds for the management keying material
specified in the 'mgt_key_material' parameter of the Joining Response
(see gid-post).
Then, the KDC can protect the rekeying message as defined below.  The
used encryption algorithm which SHOULD be the same one used to
protect communications in the group.  The method defined below
assumes that the following holds for the management keying material
specified in the 'mgt_key_material' parameter of the Join Response
(see gid-post).
COUNT, as a 1-byte unsigned integer associated to the used
encryption key.  Its value is set to 0 when starting to perform
a new group rekeying instance, and is incremented after each
use of the encryption key.
COUNT, as a 1-byte unsigned integer associated with the used
encryption key.  Its value is set to 0 when starting to perform
a new group rekeying instance, and is incremented after each
use of the encryption key.
If source authentication of messages exchanged in the group is also
ensured by means of signatures, then rekeying messages MUST be signed
using the same signature algorithm and related parameters.  Also, the
KDC's public key used for signature verification MUST me provided in
the Joining Response through the 'kdc_cred' parameter, together with
the corresponding proof-of-possession (PoP) evidence in the
'kdc_cred_verify' parameter.
If source authentication of messages exchanged in the group is not
ensured by means of signatures, then the KDC MUST provide its public
key together with a corresponding PoP evidence as part of the
management keying material specified in the 'mgt_key_material'
parameter of the Joining Response (see gid-post).  It is RECOMMENDED
to specify this information by using the same format and encoding
used for the parameters 'kdc_cred', 'kdc_nonce' and 'kdc_cred_verify'
in the Joining Response.  It is up to separate documents profiling
the use of the group rekeying scheme to specify such details.
If source authentication of messages exchanged in the group is also
ensured by means of signatures, then rekeying messages MUST be signed
using the same signature algorithm and related parameters.  Also, the
KDC's authentication credential including the public key to use for
signature verification MUST me provided in the Join Response through
the 'kdc_cred' parameter, together with the corresponding proof-of-
possession (PoP) evidence in the 'kdc_cred_verify' parameter.
If source authentication of messages exchanged in the group is not
ensured by means of signatures, then the KDC MUST provide its
authentication credential together with a corresponding PoP evidence
as part of the management keying material specified in the
'mgt_key_material' parameter of the Join Response (see gid-post).  It
is RECOMMENDED to specify this information by using the same format
and encoding used for the parameters 'kdc_cred', 'kdc_nonce' and
'kdc_cred_verify' in the Join Response.  It is up to separate
documents profiling the use of the group rekeying scheme to specify
such details.
The extended format is intended only for the 'scope' claim of access
tokens, for the cases where the claim takes as value a CBOR byte
string.  That is, the extended format does not apply to the 'scope'
parameter included in ACE messages, i.e., the Authorization Request
and Authorization Response exchanged between the Client and the
Authorization Server (see Sections 5.8.1 and 5.8.2 of I-D.ietf-ace-
oauth-authz), the AS Request Creation Hints message from the Resource
Server (see Section 5.3 of I-D.ietf-ace-oauth-authz), and the
Introspection Response from the Authorization Server (see
Section 5.9.2 of I-D.ietf-ace-oauth-authz).
The first element of the sequence is a CBOR integer, and
identifies the semantics SEM used for this scope.  The value of
this element has to be taken from the "Value" column of the "ACE
Scope Semantics" registry defined in iana-scope-semantics of this
specification.
When defining a new semantics for a binary scope, it is up to the
applications and application profiles to define and register the
corresponding integer identifier (REQ28).
The second element of the sequence is the original scope using the
semantics SEM, encoded as a CBOR byte string.
Finally, the CBOR byte string wrapping the CBOR sequence is tagged,
and identified by the CBOR tag TBD_TAG "ACE Extended Scope Format",
defined in iana-cbor-tags of this specification.
The extended format is intended only for the 'scope' claim of access
tokens, for the cases where the claim takes as value a CBOR byte
string.  That is, the extended format does not apply to the 'scope'
parameter included in ACE messages, i.e., the Authorization Request
and Authorization Response exchanged between the Client and the
Authorization Server (see Sections 5.8.1 and 5.8.2 of RFC9200), the
AS Request Creation Hints message from the Resource Server (see
Section 5.3 of RFC9200), and the Introspection Response from the
Authorization Server (see Section 5.9.2 of RFC9200).
The value of the 'scope' claim following the extended format is
composed as follows.  Given the original scope using a semantics SEM
and encoded as a CBOR byte string, the corresponding extended scope
consists of the same CBOR byte string enclosed by a CBOR tag RFC8949,
whose tag number identifies the semantics SEM.
Applications and application profiles using the extended format of
scope have to specify which CBOR tag from CBOR.Tags is used for
identifying the scope semantics, or to register a new CBOR tag if a
suitable one does not exist already (REQ28).  In case there is an
already existing, suitable CBOR tag, a new CBOR tag should not be
registered in order to avoid codepoint squatting.
If the binary encoded scope uses a semantics associated with a
registered CoAP Content-Format CoAP.Content.Formats, then a suitable
CBOR tag associated with that CoAP Content-Format would already be
registered, as defined in Section 4.3 of RFC9277.
This is especially relevant when the binary encoded scope uses the
AIF format.  That is, it is expected that the definition of an AIF
specific data model comes together with the registration of CoAP
Content-Formats for the relevant combinations of its Toid and Tperm
values.  As discussed above, this yields the automatic registration
of the CBOR tags associated with those CoAP Content-Formats.
'scope', 'gkty', 'key', 'num', 'exp', 'gid', 'gname', 'guri',
'pub_keys', 'peer_identifiers', 'ace_groupcomm_profile',
'control_uri', 'rekeying_scheme'.
'get_pub_keys'.  That is, not supporting this parameter would
yield the inconvenient and undesirable behavior where: i) the
Client does not ask for the other group members' public keys upon
joining the group (see ssec-key-distribution-exchange); and ii)
later on as a group member, the Client only retrieves the public
keys of all group members (see sec-key-retrieval-all).
'scope', 'gkty', 'key', 'num', 'exp', 'gid', 'gname', 'guri',
'creds', 'peer_identifiers', 'ace_groupcomm_profile',
'control_uri', 'rekeying_scheme'.
'get_creds'.  That is, not supporting this parameter would yield
the inconvenient and undesirable behavior where: i) the Client
does not ask for the other group members' authentication
credentials upon joining the group (see ssec-key-distribution-
exchange); and ii) later on as a group member, the Client only
retrieves the authentication credentials of all group members (see
sec-key-retrieval-all).
'client_cred', 'cnonce', 'client_cred_verify'.  These parameters
are relevant for a Client that has a public key to use in a joined
group.
'kdcchallenge'.  This parameter is relevant for a Client that has
a public key to use in a joined group and that provides the access
token to the KDC through a Token Transfer Request (see token-
post).
'pub_keys'repo'.  This parameter is relevant for a Client that has
a public key to use in a joined group and that makes it available
from a key repository different than the KDC.
'client_cred', 'cnonce', 'client_cred_verify'.  These parameters
are relevant for a Client that has an authentication credential to
use in a joined group.
'kdcchallenge'.  This parameter is relevant for a Client that has
an authentication credential to use in a joined group and that
provides the access token to the KDC through a Token Transfer
Request (see token-post).
'creds_repo'.  This parameter is relevant for a Client that has an
authentication credential to use in a joined group and that makes
it available from a key repository different than the KDC.
'peer_roles'.  This parameter is relevant for a Client that has to
know about the roles of other group members, especially when
retrieving and handling their corresponding public keys.
'kdc_nonce', 'kdc_cred', 'kdc_cred_verify'.  These parameters are
relevant for a Client that joins a group for which, as per the
used application profile of this specification, the KDC has an
associated public key and this is required for the correct group
operation.
'peer_roles'.  This parameter is relevant for a Client that has to
know about the roles of other group members, especially when
retrieving and handling their corresponding authentication
credentials.
'kdc_nonce', 'kdc_cred', 'kdc_cred_verify'.  These parameters are
relevant for a Client that joins a group for which, as per the
used application profile of this specification, the KDC has an
associated authentication credential and this is required for the
correct group operation.
'control_group_uri'.  This parameter is relevant for a Client that
supports the hosting of local resources each associated to a group
(hence acting as CoAP server) and the reception of one-to-many
requests sent to those resources by the KDC (e.g., over IP
multicast), targeting multiple members of the corresponding group.
Examples of related management operations that the KDC can perform
by this means are the eviction of group members and the execution
of a group rekeying process through an advanced rekeying scheme,
such as based on one-to-many rekeying messages.
'control_group_uri'.  This parameter is relevant for a Client that
supports the hosting of local resources each associated with a
group (hence acting as CoAP server) and the reception of one-to-
many requests sent to those resources by the KDC (e.g., over IP
multicast), targeting multiple members of the corresponding group.
Examples of related management operations that the KDC can perform
by this means are the eviction of group members and the execution
of a group rekeying process through an advanced rekeying scheme,
such as based on one-to-many rekeying messages.
In case of error 2, the Client has to obtain or self-generate a
different asymmetric key pair, as aligned to the publick key
algorithms, parameters and encoding used in the targeted group.
After that, the Client should provide its new consistent public
key to the KDC.
In case of error 2, the Client has to obtain or self-generate a
different asymmetric key pair, as aligned to the publick key
algorithms and parameters used in the targeted group.  After that,
the Client should provide the KDC with its new authentication
credential, consistent with the format used in the targeted group
and including the new public key.
Security considerations are inherited from the ACE framework I-
D.ietf-ace-oauth-authz, and from the specific transport profile of
ACE used between the Clients and the KDC, e.g., I-D.ietf-ace-dtls-
authorize and I-D.ietf-ace-oscore-profile.
Security considerations are inherited from the ACE framework RFC9200,
and from the specific transport profile of ACE used between the
Clients and the KDC, e.g., RFC9202 and RFC9203.
The attacker can build erroneous associations between node
identifiers and group members' public keys.
The attacker can build erroneous associations between node
identifiers and group members' authentication credentials.
Encoding considerations: Must be encoded as CBOR map containing the
protocol parameters defined in [this document].
Applications that use this media type: The type is used by
Authorization Servers, Clients and Resource Servers that support the
ACE groupcomm framework as specified in [this document].
Encoding considerations: Must be encoded as CBOR map containing the
protocol parameters defined in [RFC-XXXX].
Applications that use this media type: The type is used by
Authorization Servers, Clients and Resource Servers that support the
ACE groupcomm framework as specified in [RFC-XXXX].
IANA is asked to register the following entries in the "OAuth
Parameters CBOR Mappings" registry following the procedure specified
in Section 8.10 of I-D.ietf-ace-oauth-authz.
IANA is asked to register the following entries in the "OAuth
Parameters CBOR Mappings" registry following the procedure specified
in Section 8.10 of RFC9200.
IANA is asked to register the following entry in the "CBOR Tags"
registry.
Semantics: Extended ACE scope format, including the identifier of
the used scope semantics.
This specification establishes the "ACE Scope Semantics" IANA
registry.  The registry has been created to use the "Expert Review"
registration procedure RFC8126.  Expert review guidelines are
provided in review.  It should be noted that, in addition to the
expert review, some portions of the registry require a specification,
potentially a Standards Track RFC, to be supplied as well.
Value: The value to be used to identify this scope semantics.  The
value MUST be unique.  The value can be a positive integer or a
negative integer.  Integer values between 0 and 255 are designated
as Standards Track Document required.  Integer values from 256 to
65535 are designated as Specification Required.  Integer values
greater than 65535 are designated as expert review.  Integer
values less than -65536 are marked as private use.
Description: This field contains a brief description of the scope
semantics.
Reference: This field contains a pointer to the public
specification defining the scope semantics, if one exists.