Draft: draft-ietf-ace-key-groupcomm

Commentary: Implements  's review :
Mailing list commentary: Section 1 para 1 - I have a vague memory of deciding that we were going to become CBOR only with this document per the argument from Carsten . I did not find this in the minutes so this could easily be some other document that I am thinking of . Section 2 - I have a problem with Figure 1 in terms of what is labeled as an RS . The text below calls the KDC and and not the . Section 2 - update DTLS reference Section 2 - I think you might want the last sentence to refer to step 3 rather than section - The pointer to the section has already been provided but pointing back to the figure makes a degree of sense . Section 2 - KDC - This is the first time that I have heard about the fact that this is a two part protocol - You should tell me about the phases before you get here . Section 2 - " Leaving or removing " this is a sentence which does not read well . ( Also why is this current when no other line is . ) Section 2 - You should probably have a numbered item that corresponds to the secure group communication line in the picture . Section 3 - The content format application / ace+cbor is not defined by the transport profiles but by the framework . Section 3.1 - Given that a role is defined as a tstr , that format is not usable if one wishes to assign an integer abbreviation per OPT7 . Section 3.1 - the " Other additional " seems to be a strange thing to have in this list because it does not match the lead in paragraph . Section 3.1 - Is there a reason that a gid is a bstr and not a tstr . I assume that this is the same as GROUPNAME which much be a text string to be in a url - path . Section 3.2 - s / non expired / non - expired/ Section 3.2 - the def of scope seems odd because it is not well defined if it would be the same as the requested scope . ( AS response ) Section 3.2 - the text w/ scope can be simplified to the scope that the AS grants access to and skip the last sentence . Section 3.2 - ditto w/ above on " other additional " Section 3.3 - s / request necessary information / request information/ Section 3.3 - Am I supposed to know why I care about public keys at this point ? Section 3.3 - last sentence of the text implies that signinfo and pubkeyenc are required . Last sentence of para 2 needs to be re - written Section 3.3 - should identify what signinfo is for . Section 3.3 - are you imposing a new requirement that the token be validated prior to returning the response to a token post ? As I remember it , this is not required to happen prior to the response being returned just before access is granted . ( I.e. you can validate the token in parallel ) ( After successful verification ... ) Section 3.3 - " payload of response deviates " I do n't believe that this is a true statement . However , you should state at tis point how it deviates if you believe it does . I assume that you mean that there is a payload as oppose to no payload . Section 3.3 - You would not be able to reuse the same kdcchallenge value with a different key . It would not have any way of being associated with that key and would look like somebody else was attempting to use the value . Section 3.3 - s / were included in the request / are included in the request/ present tense . Section 3.3 - Do you really mean to say " request includes pubkeyenc " , " response does not include pubkeyenc " ? That seems to be wrong in the general case . Also seems to say the same thing about ' signinfo ' . Also seems to contradict the next paragraph . Section 3.3 - The forward reference for signinfo is incorrect - it should be 3.3.1 . ( I also do n't know if you need this two paragraphs in a row . ) Same paragraph - group identifier or group name ? You need to do a detailed pass through the document and look at every instance of this string and either make it an identifier or a name and perhaps add these to the terminology section so that one can quickly look back to distinguish them . Perhaps you should be using context identifier rather than group identifier just to make it clearer the difference between what goes into the different locations . The problem with that is it is OSCORE specific so it may not work well . Section 3.3 - last paragraph - should this be referring to applications or profiles ? -- really a global question . Consider - is the OSCORE profile attached to a specific application or to a set of unknown applications ? Section 3.3.1 - s / one ore more / one or more/ Section 3.3.1 - s / is lower or at most equal to / is at most/ - also what happen if the response would include zero elements ? You asked and nothing needs to be returned ? Section 3.3.1 - second bullet - kill the " if included " text . This is covered above . Section 3.3.1 - s / signinfo / signinfo/ Section 3.3.1 - This is looking really complicated and I do n't know why you do n't just simplify it down to a single request / response pair . Define a value for use when the server either does not know or does not want to share a value and so forth . The size of data if signinfo were to be omitted is almost the same size as if it where present so that does not seem to be much of a win . Making the answer one byte longer for adding the pubkeyencres field does not seem to be a huge problem for a one - time message . Section 3.3.1 - The first paragraph implies that pubkeyenc would be in the reply but do n't have any information about what that would look like . See also previous item . Section 3.3.3 - s/((/(/ Section 4 - why are you calling this the first exchange with the KDC - who was I talking to in section 3 ? Section 4 - are the policies new or just retrieved ? May want to swap order . Section 4 - are we still specifying a group to join or is that implicit in the URL ? Tell me how it is specified ? Section 4 - I do n't think that the ( re- ) is helping understanding here . Section 4 - what type of individual key is being obtained in bullet 2 - how is this different than getting the current keying material ? Section 4 - Who is enforcing the policies ? Just retrieve the policies . Section 4 - I do n't think the e.g. in getting public keys serves a purpose here . Section 4 - I am not sure what the " at hand " is supposed to be providing . /for the requested group identifier/ Section 4.1 - do we want to make the if value be a dot tree ? Section 4.1 - The bullet for /ace - group seems to indicate that the name is fixed which is the opposite of what the previous paragraph says . I find this confusing . I really find it confusing that this document is specifying a url - path name is being specified , and the oscore document immediately uses a different value . Section 4.1 - what does it mean for a sub - resource to be " fixed " . Does that mean it never changes ? Section 4.1 - a brief description of what is in the resource would be helpful here . " pub - key : this resource contains the public keys of all group members . The resource supports the GET and FETCH methods . " Section 4.1 - Yes but what is a NODENAME and why do I care about it ? Section 4.1.2.1 - It would be useful in the first paragraph to re - iterate that this is the " join " operation The current description seems to be really odd . Section 4.1.2.1 - getpubkeys - One consideration that needs to be highlighted for a constrained device is that this may result in a large return value and it may be better to get them only as needed . Section 4.1.2.1 - It would be nice to be able to use getpubkeys with a filter so that only responders are returned . Section 4.1.2.1 - ' clientcred ' the description of when this field is used does not seem to include a server which only responds to an individual . It could be said in that case that it is not sending messages " to the group " but only to a member of the group . Section 4.1.2.1 - ' conce ' why bother pointing to ACE for a description of this document . This is not a framework message so I am not sure why this is interesting . Section 4.1.2.1 - Which scope is being used , the one in this message ( assuming it exists ) or the one in the token ? If the message does not have one then what happens ? Deterministic encoding ? Section 4.1.2.1 - s / token is not being posted / token was not posted/ Section 4.1.2.1 - formatting - the follow on paragraph to ' clientcredverify ' should be indented a level Section 4.1.2.1 - You missed the merge of signinfo and pubkeyenc in the error handling paragraph . Section 4.1.2.1 - What is the reasoning behind returning the signinfores field if the group is not in the scope . This is not related to the failure in any way . Seems more like this would return a pointer to the AS rather than anything else . Section 4.1.2.1 - How much can I just ignore rather than error ? If you send me a public key and I do n't care about it why can I not just ignore that fact and go forward ? I both agree and disagree with the idea that erroring on unknown fields is the correct way to proceed . Section 4.1.2.1 /succed / succeeded/ Section 4.1.2.1 - ( para before bullet ) I do n't like the idea that if you send me a public key , I would use the stored one before looking at the one that is in the join message . This seems to be backwards behavior . Note the paragraph following the bullets is saying exactly the opposite thing a this one is . Section 4.1.2.1 - I am not clear on the following situation : Key P1 is associated with groupX , I do a second join and send key P1 but have a cred verify that would fail . Am I expected to detect this and error or say that because you have already verified P1 it does not matter ? Section 4.1.2.1 - both bullets are talking about failed verification - kill the redundancy . Section 4.1.2.1 - ' num ' the rule on the initial value of num should be put into a section about setting up a group not here . Section 4.1.2.1 - ' num ' vs ' ctx - num ' should be harmonized . Section 4.1.2.1 - exp_delta should specify a default if it is not in the message . I there a reason that this is not a policy for the group ? Section 4.1.2.2 - Ditto to above on the field being returned in the event of 4.01 Section 4.1.2.2 - I do n't understand the need for ' gkty ' as that I should know from the join and it should never change in the life of the group . I would also expect that ' exp ' is something that at least SHOULD be included as that does change and is useful to have . Section 4.1.2.2 - Is the ' key ' value expected to be modified for the requester ? Section 4.1.3.1 - What is the reason for having a map in this request type . Why not just have the array itself ? Section 4.1.3.1 - Looks like a formatting error 2 paragraphs after figure 7 Section 4.1.3.1 - The text on the first selection criteria has me really messed up because I am not sure that Section 4.1.3.1 - If not storing keys , should this return either resource not found or not supported as an error code instead of an empty response ? Section 4.1.3.1 - s / resource handlers only verify / resource handler only verifies/ Unless you move it up one level . Section 4.1.4.1 - can we get rid of the map ? Section 4.1.6.1 - I have no idea from the text why I would use this method . Section 4.1.6.3 - para 2 - the first sentence does not make any sense to me . How could the handler accept a request for a node does not match " NODENAME " as that is the url - path ? Section 4.2 - " retrieve individual or group keying material " What individual material ? Section 4.3 - /target the URI path possibly provided by/ This text either needs to be a definitive method or some type of alternative method needs to be provided . Section 4.3 - I am worried about congestion in more places than just for Observe . If a server is sending lots of messages out to clients on a one - to - one basis it could easily flood the network . Section 4.4 - What does the first sentence even mean ? It seems to be almost a circular argument . Section 4.4 - I find the title of 4.4 to be somewhat misleading . As far as I can tell this is only talking about one type of renewal , but even that is not clear to me . Section 4.4 - Why would it require an error in the event that a full rekey is going to be done by the server , ca n't it just do the full renewal and return the answer to the PUT ? Section 4.5 - Is the second paragraph in the wrong place ? I do n't really care what the client does only what the server does . Section 4.6 - /After distributing the new group keying material/ This should be done before doing that - it should also be committed long term storage if one expects the KDC to restart w/o a forced rekey event . And even then it potentially should have a new context number . Section 5 - see previous comment Section 5 - Does the use of the DELETE method to inform a client that it is no longer part of the group imply that a different control path is needed for every group that the client joins ? I do n't know that I was expecting that . Section 7 - / end of the rekeying process and the next loss of security state/ This is not what I was trying to get at and it makes no sense to me . The question is the interval between the end of the last rekey process and the client joining the group . If that is small enough then replay will not work . Section 7 /the Observations up to that point/ this does not make any sense . You can lose who I currently doing the observation but you have already tossed all of the observations themselves even without a reboot . Section 7 - I do n't understand the conditions you have laid out for doing delayed rekeying I would expect that it is a minimum number OR a maximum interval . But I do n't think that is what this says . Section 7 - This is a tic that I am trying to stop in my own writing . Look at all instances of " In fact , " and they can probably be removed . The other one that I use a lot is " Actually , " Section 7 - s / initiating rekeys / initiating rekey events/ Section 7.1 - Para 2 - it would not be a second try as the KID context field would be different in general .
The full procedure can be separated in two phases: the first follows
the ACE framework, between Client, AS and KDC.  The second part is
the key distribution between Client and KDC.  After the two phases
the Client is able to participate in the group communication, via a
Dispatcher entity.
Leaving or removing a current group member from the group (sec-
node-removal).
Retrieval of keying material by a group member (update-keys and
new-keys).
Allowing a group member to leave the group (sec-node-removal).
Evicting a group member from the group (sec-node-removal).
Allowing a group member to retrieve keying material (update-keys
and new-keys).
The joining node requests an Access Token from the AS, in order to
access a specific group-membership resource on the KDC and hence
join the associated group.  The joining node will start or
continue using a secure communication association with the KDC,
according to the response from the AS.
The joining node transfers authentication and authorization
information to the KDC, by posting the obtained Access Token to
the /authz-info endpoint at the KDC.  After that, a joining node
MUST have a secure communication association established with the
KDC, before starting to join a group under that KDC.  Possible
ways to provide a secure communication association are DTLS
RFC6347 and OSCORE RFC8613.
The joining node requests an Access Token from the AS, in order to
access a specific group-membership resource on the KDC and hence
join the associated group.  This exchange between Client and AS
MUST be secured, as specified by the transport profile of ACE used
between Client and KDC.  The joining node will start or continue
using a secure communication association with the KDC, according
to the response from the AS.
The joining node transfers authentication and authorization
information to the KDC, by posting the obtained Access Token to
the /authz-info endpoint at the KDC.  This exchange, and all
further communications between the Client and the KDC, MUST occur
over the secure channel established as a result of the transport
profile of ACE used between Client and KDC.  After that, a joining
node MUST have a secure communication association established with
the KDC, before starting to join a group under that KDC.  Possible
ways to provide a secure communication association are DTLS
RFC6347 and OSCORE RFC8613.
The exchange of Authorization Request and Authorization Response
between Client and AS MUST be secured, as specified by the transport
profile of ACE used between Client and KDC.
The Joining Request and Joining Response, and all further
communications between the Client and the KDC MUST be sent over the
secure channel established as a result of the transport profile of
ACE used between Client and KDC.
All communications between a Client and the other group members MUST
be secured using the keying material provided in key-distr.
The joining node can communicate securely with the other group
members, using the keying material provided in step 3.
Communications between the Client and the AS MUST be secured, as
defined by the transport profile of ACE used.  The Content-Format
used in the messages is the one specified by the used transport
profile of ACE (e.g. application/ace+cbor for the first two messages
and application/cwt for the third message, depending on the format of
the access token).  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).
Communications between the Client and the AS MUST be secured, as
defined by the transport profile of ACE used.  The Content-Format
used in the message is the one indicated by the used transport
profile of ACE.  For example, this can be application/ace+cbor for
the first two messages and application/cwt for the third message,
which are defined in the ACE framework.  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).
By default, each entry is encoded as specified by I-D.bormann-
core-ace-aif.  It is up to the application profiles to define and
register Toid and Tperm to fit the use case.  The object
identifier Toid corresponds to the group name, while the
permission set Tperm indicates 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).  Note that, if applicable in the application use
cases, the application profile can define a format for the role
as the one defined in I-D.bormann-core-ace-aif.
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).
The CDDL definition RFC8610 of scope, using as example group
identifier encoded as byte string and role identifier as text
string, is given in cddl-ex.
An example of CDDL definition RFC8610 of scope using the format
above, with group name and role identifiers encoded as text
strings is given in cddl-ex.
Other additional parameters as defined in I-D.ietf-ace-oauth-authz,
can be included if necessary.
'scope' containing the granted scope, if different from the scope
requested by the client.  This parameter has the same format and
encoding of 'scope' in the Authorization Request, defined in ssec-
authorization-request.
'scope' containing the scope the AS grants access to.  This
parameter has the same format and encoding of 'scope' in the
Authorization Request, defined in ssec-authorization-request.
Other additional parameters as defined in I-D.ietf-ace-oauth-authz,
if necessary.
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).
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).
'sign_info' defined in sign-info.
'pub_key_enc' defined in pub-key-enc, encoding the CBOR simple
value Null, to require information on the exact encoding of public
keys used in the group.
Optionally, the Client might want to request information concerning
the public keys in the group, as well as concerning the algorithm and
related parameters for computing signatures in the group.  In such a
case, the joining node MAY ask for that information to the KDC in
this same request.  To this end, it sends the CoAP POST request to
the /authz-info endpoint using the Content-Format "application/
ace+cbor".
The payload of the message MUST be formatted as a CBOR map including
the access token.
'sign_info' defined in sign-info, encoding the CBOR simple value
Null to require information about the signature algorithm,
signature algorithm parameters, signature key parameters and on
the exact encoding of public keys used in the group.
The payload of the 2.01 response is a CBOR map.  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 Section kdcchallenge, specifying
a dedicated challenge N_S generated by the KDC.  The Client uses this
challenge to prove possession of its own private key (see the
'client_cred_verify' parameter in key-distr).  Note that the payload
format of the response deviates from the default as defined in the
ACE framework (see Section 5.8.1 of I-D.ietf-ace-oauth-authz).
The payload of the 2.01 response is a CBOR map.  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 Section kdcchallenge, specifying
a dedicated challenge N_S generated by the KDC.  The Client uses this
challenge to prove possession of its own private key (see the
'client_cred_verify' parameter in key-distr).  Note that the payload
format of the response deviates from the one defined in the ACE
framework (see Section 5.8.1 of I-D.ietf-ace-oauth-authz), which has
no payload.
If either of 'sign_info' or 'pub_key_enc' were included in the
request, the KDC MAY include the 'sign_info' parameter defined in
sign-info, optionally including the 'pub_key_enc' parameter pub-key-
enc.
The 'sign_info' parameter MUST be present if the POST request
included the 'sign_info' parameter and/or the pub_key_enc with value
Null.  The encoding of the 'sign_info' parameter in the response is
defined in pub-key-enc.  Note that the field 'id' takes the value of
the group identifier for which the 'sign_info' applies to, in this
specification.
If 'sign_info' is included in the request, the KDC MAY include the
'sign_info' parameter defined in sign-info, with the same encoding.
Note that the field 'id' takes the value of the group name for which
the 'sign_info' applies to.
Applications of this specification MAY define alternative specific
negotiations of parameter values for signature algorithm and
signature keys, if 'sign_info' and 'pub_key_enc' are not used (OPT2).
Applications of this specification MAY define alternative specific
negotiations of parameter values for signature algorithm and
signature keys, if 'sign_info' is not used (OPT2).
The 'sign_info' parameter of the 2.01 (Created) response is a CBOR
array of one ore more elements.  The number of elements is lower or
at most equal to the number of groups the client has been authorized
to join.  Each element contains information about signing parameters
and keys for one or more group or topic and is formatted as follows.
The 'sign_info' parameter of the 2.01 (Created) response is a CBOR
array of one or more elements.  The number of elements is at most the
number of groups the client has been authorized to join.  Each
element contains information about signing parameters and keys for
one or more group or topic and is formatted as follows.
The second element 'sign_alg' is an integer or a text string if
the POST request included the 'sign_info' parameter with value
Null, and indicates the signature algorithm used in the group
identified by 'gid'.  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 the POST request did not include the
'sing_info' parameter, this element is encoded as the CBOR simple
value Null.
The second element 'sign_alg' is an integer or a text string if
the POST request included the 'sign_info' parameter with value
Null, and indicates the signature algorithm used in the group
identified by 'gname'.  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 the POST request did not include the
'sign_info' parameter, this element is encoded as the CBOR simple
value Null.
The fourth element 'sign_key_parameters' is a CBOR array
indicating the parameters of the key used with the signature
algorithm.  Its content depends on the value of 'sign_alg'.  It is
REQUIRED of the application profiles to define the possible values
and structure for the elements of this parameter (REQ5).  If the
POST request did not include the 'sing_info' parameter, this
element is encoded as the CBOR simple value Null.
The fifth element 'pub_key_enc' parameter is optional and MUST
only be present if the POST request included the 'pub_key_enc'
parameter with value Null.  If present, it is either a CBOR
integer indicating the encoding of public keys used in the group
identified by 'gid', or has value Null indicating that the KDC
does not act as repository of public keys for group members.  Its
acceptable values are taken from the "CWT Confirmation Method"
Registry defined in RFC8747.  It is REQUIRED of the application
profiles to define specific values to use for this parameter
(REQ6).
The fourth element 'sign_key_parameters' is a CBOR array
indicating the parameters of the key used with the signature
algorithm.  Its content depends on the value of 'sign_alg'.  It is
REQUIRED of the application profiles to define the possible values
and structure for the elements of this parameter (REQ5).  If the
POST request did not include the 'sign_info' parameter, this
element is encoded as the CBOR simple value Null.
The fifth element 'pub_key_enc' parameter is either a CBOR integer
indicating the encoding of public keys used in the group
identified by 'gname', or has value Null indicating that the KDC
does not act as repository of public keys for group members.  Its
acceptable values are taken from the "CWT Confirmation Method"
Registry defined in RFC8747.  It is REQUIRED of the application
profiles to define specific values to use for this parameter
(REQ6).
The CDDL notation RFC8610 of the 'sign_info' parameter formatted as
in the response is given below, with gid formatted as a bstr (note
that gid can be encoded differently, see REQ1).
The 'pub_key_enc' parameter is an OPTIONAL parameter of the Token
Post response message defined in Section 5.1.2. of I-D.ietf-ace-
oauth-authz.  This parameter contains information about the exact
encoding of public keys to be used between the Client and the RS.
Its exact content is application specific.
In this specification and in application profiles building on it,
this parameter is used to ask the KDC information about the encoding
of public keys used in the group.
The CDDL notation RFC8610 of the 'pub_key_enc' parameter formatted as
in the request is given below.
The 'kdcchallenge' parameter is an OPTIONAL parameter of the Token
Post response message defined in Section 5.1.2. of I-D.ietf-ace-
oauth-authz.  This parameter contains a challenge generated by the
KDC and provided to the Client.  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 key-distr).
This section defines the interface available at the KDC.  Moreover,
this section specifies how the clients can use this interface to join
a group, leave a group, retrieve new keying material or policies.
During the first exchange with the KDC ("Joining"), the Client sends
a request to the KDC, specifying the group it wishes to join (see
ssec-key-distribution-exchange).  Then, the KDC verifies the access
token and that the Client is authorized to join that group.  If so,
it provides the Client with the keying material to securely
communicate with the other members of the group.  Whenever used, the
Content-Format in messages containing a payload is set to
application/ace-groupcomm+cbor, as defined in content-type.
The Client can (re-)get the current keying material, for cases
such as expiration, loss or suspected mismatch, due to e.g. reboot
or missed group rekeying.  This is described in update-keys.
The Client can (re-)get the public keys of other group members,
e.g. if it is aware of new nodes joining the group after itself.
This is described in sec-key-retrieval.
The Client can (re-)get the policies currently enforced in the
group.  This is described in policies.
The Client can (re-)get the version number of the keying material
currently used in the group.  This is described in key-version.
Upon receiving a request from a Client, the KDC MUST check that it is
storing a valid access token from that Client for the group
identifier associated to the endpoint.  If that is not the case, i.e.
the KDC does not store a valid access token or this is not valid for
that Client for the group identifier at hand, the KDC MUST respond to
the Client with a 4.01 (Unauthorized) error message.
The CDDL notation RFC8610 of the 'sign_info' parameter formatted as
in the response is given below, with gname formatted as a bstr (note
that gname can be encoded differently, see REQ1).
The 'kdcchallenge' parameter is an OPTIONAL parameter of the Token
Post response message defined in Section 5.1.2. of I-D.ietf-ace-
oauth-authz.  This parameter contains a challenge generated by the
KDC and provided to the Client.  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 key-distr).
This section defines the interface available at the KDC.  Moreover,
this section specifies how the clients can use this interface to join
a group, leave a group, retrieve the group policies or the new keying
material.
During the first exchange with the KDC ("Joining") after posting the
Token, the Client sends a request to the KDC, specifying the group it
wishes to join (see ssec-key-distribution-exchange).  Then, the KDC
verifies the access token and that the Client is authorized to join
that group.  If so, it provides the Client with the keying material
to securely communicate with the other members of the group.
Whenever used, the Content-Format in messages containing a payload is
set to application/ace-groupcomm+cbor, as defined in content-type.
The Client can get the current keying material, for cases such as
expiration, loss or suspected mismatch, due to e.g. reboot or
missed group rekeying.  This is described in update-keys.
The Client can get the public keys of other group members.  This
is described in sec-key-retrieval.
The Client can get the group policies.  This is described in
policies.
The Client can get the version number of the keying material
currently used in the group.  This is described in key-version.
Upon receiving a request from a Client, the KDC MUST check that it is
storing a valid access token from that Client for the group name
associated to the endpoint.  If that is not the case, i.e. the KDC
does not store a valid access token or this is not valid for that
Client for the group name, the KDC MUST respond to the Client with a
4.01 (Unauthorized) error message.
The KDC is configured with the following resources.  Note that the
root url-path "ace-group" given here are default names:
implementations are not required to use these names, and can define
their own instead.  The Interface Description (if=) Link Target
Attribute value ace-group is registered (if-ace-group) and can be
used to describe this interface.
The KDC is configured with the following resources.  Note that the
root url-path "ace-group" given here are default names:
implementations are not required to use these names, and can define
their own instead.  The Interface Description (if=) Link Target
Attribute value ace.group is registered (if-ace-group) and can be
used to describe this interface.
The POST handler 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 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".  Note that the
group joining exchange is done by the client via this operation, as
described in ssec-key-distribution-exchange.
'get_pub_keys', if the Client wishes to receive the public keys of
the other nodes in the group from the KDC.  The value is an empty
CBOR array.  This parameter may be present if the KDC stores the
public keys of the nodes in the group and distributes them to the
Client; it is useless to have here if the set of public keys of
the members of the group is known in another way, e.g. it was
provided by the AS.
'client_cred', with value the public key or certificate of the
Client, encoded as a CBOR byte string.  This field contains the
public key of the Client.  This field 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 the group.  The default
encoding for public keys is COSE Keys.  Alternative specific
encodings of this parameter MAY be defined in applications of this
specification (OPT1 in req).
The first array contains zero or more roles (or combination of
roles) of group members for the group identified by
"GROUPNAME".  The Client indicates that it wishes to receive
the public keys of all nodes having these roles.  If empty, it
means the client wishes to receive the public keys of all
nodes.
The second array is empty.
The CDDL definition RFC8610 of 'get_pub_keys' is given in cddl-ex-
getpubkeys using as example encoding: node identifier encoded as
byte string, role identifier as text string, and combination of
roles encoded as a CBOR array of roles.  Note that the array ids
is empty for this handler, but is not necessarily empty for the
value of "get_pub_keys" received by the handler of FETCH to ace-
group/GROUPNAME/pub-key (see pubkey-fetch).
'client_cred', with value the public key or certificate of the
Client, encoded as a CBOR byte string.  This field contains the
public key of the Client.  This field 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.
The default encoding for public keys is COSE Keys.  Alternative
specific encodings of this parameter MAY be defined in
applications of this specification (OPT1 in req).
If the token is not being posted (e.g. if it is used directly to
validate TLS instead), it is REQUIRED of the specific profile to
define how the challenge N_S is generated (REQ17).  The Client
computes the signature by using its own private key, whose
corresponding public key is either directly specified in the
'client_cred' parameter or included in the certificate specified in
the 'client_cred' parameter.
If the token was not posted (e.g. if it is used directly to
validate TLS instead), it is REQUIRED of the specific profile to
define how the challenge N_S is generated (REQ17).  The Client
computes the signature by using its own private key, whose
corresponding public key is either directly specified in the
'client_cred' parameter or included in the certificate specified
in the 'client_cred' parameter.
If the request is not formatted correctly (e.g. unknown, not-expected
fields present, or expected fields with incorrect format), the
handler MUST respond with a 4.00 (Bad Request) error message.  The
response MAY contain a CBOR map in the payload with ace+cbor format,
e.g. it could send back "pub_key_enc" set to Null if the Client sent
its own public key and the KDC is not set to store public keys of the
group members.  Application profiles MAY define optional or mandatory
payload formats for specific error cases (OPT6).
If the request is not formatted correctly (i.e. required fields non
received or received with incorrect format), the handler MUST respond
with a 4.00 (Bad Request) error message.  The response MAY contain a
CBOR map in the payload with ace+cbor format, e.g. it could send back
'sign_info_res' with 'pub_key_enc' set to Null if the Client sent its
own public key and the KDC is not set to store public keys of the
group members.  If the request contained unknown or non-expected
fields present, the handler MUST silently drop them and continue
processing.  Application profiles MAY define optional or mandatory
payload formats for specific error cases (OPT6).
If no public key is included in the 'client_cred' field, the handler
checks if one public key is already associated to the access token
received (see ssec-key-distribution-exchange for an example) and to
the group identified by "GROUPNAME".  If that is not the case, the
handler responds with a 4.00 Bad Request error response.
'num', containing the version number of the keying material for
the group communication, formatted as an integer.  The initial
version MUST be set to 0 at the KDC.  This is a strictly monotonic
increasing field.
'num', containing the version number of the keying material for
the group communication, formatted as an integer.  This is a
strictly monotonic increasing field.  The application profile MUST
define the initial version number (REQ19).
The first array contains zero or more roles (or combination of
roles) of group members for the group identified by
"GROUPNAME".
The second array contains zero or more identifiers of group
members for the group identified by "GROUPNAME".
The CDDL definition RFC8610 of 'get_pub_keys' is given in cddl-ex-
getpubkeys using as example encoding: node identifier encoded as byte
string, role identifier as text string, and combination of roles
encoded as a CBOR array of roles.  Note that the empty array is not
valid for this handler, but is valid for the value of "get_pub_keys"
received by the handler of POST to ace-group/GROUPNAME (see gid-
post).
The second array contains zero or more identifiers of group
members for the group identified by "GROUPNAME".  The Client
indicates that it wishes to receive the public keys of all
nodes having these identifiers.
The handler only accept a request from the node that matches the
"NODENAME" used in Uri-Path, and that is part of the "GROUPNAME"
group: the handler verifies that the group identifier "GROUPNAME" is
a subset of the 'scope' stored in the access token associated to this
client, and that this client is identified by "NODENAME".  If
verification fails, the KDC MUST respond with a 4.01 (Unauthorized)
error message.
The handler only accept a request from the node that matches the
"NODENAME" used in Uri-Path, and that is part of the "GROUPNAME"
group: the handler verifies that the group name "GROUPNAME" is a
subset of the 'scope' stored in the access token associated to this
client, and that this client is identified by "NODENAME".  If
verification fails, the KDC MUST respond with a 4.01 (Unauthorized)
error message.
The handler verifies that the group identifier GROUPNAME is a subset
of the 'scope' stored in the access token associated to this client.
If verification fails, the KDC MUST respond with a 4.01
(Unauthorized) error message.
If the request is not formatted correctly (e.g. unknown, not-expected
fields present, or expected fields with incorrect format), the
handler MUST respond with a 4.00 (Bad Request) error message.
Application profiles MAY define optional or mandatory payload formats
for specific error cases (OPT6).
The handler verifies that the group name GROUPNAME is a subset of the
'scope' stored in the access token associated to this client.  If
verification fails, the KDC MUST respond with a 4.01 (Unauthorized)
error message.
If the request is not formatted correctly (i.e. required fields non
received or received with incorrect format), the handler MUST respond
with a 4.00 (Bad Request) error message.  If the request contained
unknown or non-expected fields present, the handler MUST silently
drop them and continue processing.  Application profiles MAY define
optional or mandatory payload formats for specific error cases
(OPT6).
To join the group, the Client sends a CoAP POST request to the /ace-
group/GROUPNAME endpoint at the KDC, where GROUPNAME is the group
identifier of the group to join, formatted as specified in gid-post.
This group identifier is the same as in the scope entry corresponding
to that group, specified in the 'scope' parameter of the
Authorization Request/Response, or it can be retrieved from it.  Note
that, in case of successful joining, the Client will receive the URI
to retrieve individual or group keying material and to leave the
group in the Location-Path option of the response.
To join the group, the Client sends a CoAP POST request to the /ace-
group/GROUPNAME endpoint at the KDC, where GROUPNAME is the group
name of the group to join, formatted as specified in gid-post.  This
group name is the same as in the scope entry corresponding to that
group, specified in the 'scope' parameter of the Authorization
Request/Response, or it can be retrieved from it.  Note that, in case
of successful joining, the Client will receive the URI to retrieve
individual or group keying material and to leave the group in the
Location-Path option of the response.
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 identifier and NODENAME is the node's name, and
formatted as defined in node-get.
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 the node's name, and formatted as
defined in node-get.
In case the KDC maintains the public keys of group members, a node in
the group can contact the KDC to request public keys and roles of
either all group members or a specified subset, by sending a CoAP GET
or FETCH request to the /ace-group/GROUPNAME/pub-key endpoint at the
KDC, where GROUPNAME is the group identifier, and formatted as
defined in pubkey-get and pubkey-fetch.
In case the KDC maintains the public keys of group members, a node in
the group can contact the KDC to request public keys and roles of
either all group members or a specified subset, by sending a CoAP GET
or 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-get and pubkey-fetch.
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 identifier and NODENAME is the node's name.
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 the node's name.
A node in the group can contact the KDC to request information about
the version number of the symmetric group keying material, by sending
a CoAP GET request to the /ace-group/GROUPNAME/ctx-num endpoint at
the KDC, where GROUPNAME is the group identifier, formatted as
defined in num-get.  In particular, the version is incremented by the
KDC every time the group keying material is renewed.
A node in the group can contact the KDC to request information about
the version number of the symmetric group keying material, by sending
a CoAP GET request to the /ace-group/GROUPNAME/num endpoint at the
KDC, where GROUPNAME is the group name, formatted as defined in num-
get.  In particular, the version is incremented by the KDC every time
the group keying material is renewed.