Draft: draft-ietf-ace-key-groupcomm

Commentary: I do n't agree , the text for GET ace - group / GROUPNAME / nodes / NODENAME specifically says : Which means that IND KEY does not have to be in the KEY .. in this example I explicitly wanted to have it outside of key because it shows that it can happen ( even if in OSCORE it does not ) . 
 getpubkeys is encoded as [ [ ] , [ ] ] , where the first array contains roles and second contains ids . right now section 4.1.2.1 says " if the first array is empty , the node is requesting all pub keys . This makes sense for the joining exchange . But for the FETCH to getpubkeys , it makes it so that it is impossible for a node to just request ids , without caring about roles ... should we make it so that if getpubkeys = null it 's requesting for all pub keys , and if the first array is empty it means it 's requesting for no role ? 
 OLD scope is the byte string specified in the ' scope parameter above ' . NEW scope is the byte string specified in the ' scope ' parameter above , if present , or the default scope if omitted . 
 OLD : The handler extracts the granted scope from the access token , and checks the requested one against the token one . NEW : The handler extracts the granted scope from the access token , and checks the requested one against the token one . If the requested one is not a subset of the token one , the MUST respond with a 4.01 ( Unauthorized ) error message . 
 OLD : 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 ] . NEW : The ' kdcchallenge ' parameter is an OPTIONAL parameter of the Token Post response message ( see Section 5.8.1 of [ I - D.ietf - ace - oauth - authz ] ) . 
 by application profiles in the Token POST request and response 
 in the IANA Media Type registration 
 OLD : Can make the ace - group / GROUPNAME / nodes / NODENAME resource Observable [ RFC7641 ] , and send notifications to Clients when the keying material is updated . NEW : Can make the ace - group / GROUPNAME resource Observable [ RFC7641 ] , and send notifications to Clients when the keying material is updated . 
 compare to 4.1.3.1 . and delete duplicate text . " GET requests are served just like FETCH requests but without any filtering " 
 on application profiles to specify what operations/(resource + method ) are allowed for each role . add in each section that this is allowed for the specific role that the node has , checked against the table above . 
 change from 4.00 to 4.01 ( also in other sections ) 
 add motivation . Clarify what is different from a simple ace token post request response . 
 1 ' reqcnf ' , as defined in Section 3.1 of [ I - D.ietf - ace - oauth - params ] , optionally containing the public key or a reference to the public key of the  , if it wishes to communicate that to the AS . As in [ I - D.ietf - ace - oauth - authz ] , these parameters are included in the payload , which is formatted as a CBOR map . The Content - Format " application / ace+cbor " defined in Section 8.14 of [ I - D.ietf - ace - oauth - authz ] is used . 2 OLD : ' accesstoken ' , containing the proof - of - possession access token . ' cnf ' if symmetric keys are used , not present if asymmetric keys are used . This parameter is defined in Section 3.2 of [ I - D.ietf - ace - oauth - params ] and contains the symmetric proof - of- possession key that the Client is supposed to use with the KDC . ' rscnf ' if asymmetric keys are used , not present if symmetric keys are used . This parameter is defined in Section 3.2 of [ I - D.ietf - ace - oauth - params ] and contains information about the public key of the KDC . ' expiresin ' , contains the lifetime in seconds of the access token . This parameter MAY be omitted if the application defines how the expiration time is communicated to the  via other means , or if it establishes a default value . Additionally , the Authorization Response MAY contain the following parameters , which , if included , MUST have the corresponding values : NEW : Note that ' expires_in ' MAY be omitted if the application defines how the expiration time is communicated to the  via other means , or if it establishes a default value . OLD : ' 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 Section 3.1 . If this parameter is not present the granted scope is equal to the one requested in Section 3.1 } . NEW : ' scope ' has the same format and encoding of ' scope ' in the Authorization Request , defined in Section 3.1 . If this parameter is not present the granted scope is equal to the one requested in Section 3.1 } . DEL : Other additional parameters as defined in [ I - D.ietf - ace - oauth - authz ] , if necessary . As in [ I - D.ietf - ace - oauth - authz ] , these parameters are included in the payload , which is formatted as a CBOR map . The Content - Format " application / ace+cbor " is used . 
 of message exchange in 4.x
Mailing list commentary: Hello Francesca , and ACE , I ' ve had a bit of a hard time working through ace - key - groupcomm ( and the associated OSCORE adaption ) ; here 's what I think makes it difficult : ( It may be worth pointing out that my perspective in reading was joining a group as a monitor device , which may explain my points of attention or lack thereof ) Some example exchange ... somewhere would make it easier to digest . I ' m not saying that every step needs one here ( and am aware that I have a tendency to overdo it myself ) , but skimming through examples often allows getting a rough idea much more quickly than having it develop while going through the text . The way groupcomm - specific data is exchanged in the token phase violates the layering of ACE as I see it . The whole section 3 ( Authorization to Join a Group ) should be expressible a few paragraphs . Figure 2 already indicates that ( " Defined in the ACE framework " ) , yet it spans 7 pages . The part where outlines how scope is expressed w / rt groups is good , that needs to be there . Then there are signinfo and kdcchallenge , which are for the next bullet . Apart from that , it largely reads like a repetition of general ACE . That may be justified by the intention to make it usable for readers who did n't go through the rest of ACE before , but then please mark it as such . ( To illustrate : In 3.2 around rscnf I started wondering whether that might apply when asymmetric keys are used in the group because I never had to deal with rscnf , just to realize that it 's some ACE transport profiles that use it . I ' ve only used ACE - OSCORE so far , and sure there 's several generic ACE mechanisms I have n't used , but why is this piece of information occupying my time here ? ) . Join components in the Token phase I understand signinfo and kdcchallenge to be process optimizations that allow joining the group with fewer round - trips . The point they are introduced at does not make this obvious , though -- the reader is right in the middle of going through the ACE part and possibly trying to figure out what they already have implemented and what 's changed here . Frankly , if there were a better way to bundle compressed requests ( " and by the way , of the things I ' m now authorized to see , give me the signinfo " ) or unsolicited responses ( " and by the way , if you tried to register with a public key , you 'd fail because you do n't have a kdcchallenge , so here 's one to get started " ) , I 'd suggest it here , but I do n't have anything written I could refer you to . But from a teaching and understanding point of view , I think that it 'd be better structured about like this : In the very short ACE section , add an item that " Parts of the following group joining process can be rolled into the token exchange . They manifest in a signinfo entry in the token request , and a kdcchallenge in the token response ( which is then an application / ace+cbor representation rather than empty ) . These can be by the parties to save round - trips and are described in detail in appendix X. While it is RECOMMENDED that they are used when adaequate , parties MAY ignore them ( but MUST NOT fail the process just because they find them in a message ) . " Then explain the process from a client not having a kdcchallenge ( or having a stale one , or not even having signinfo ) with the clear separation of ACE tasks and interactions with the protected resource ( the join resource ) . Here may be a place for a note about the option to optimize away the step by using appendix X. Then , in the appendix , use the established knowledge of what signinfo and the challenge do to concisely map the data items piggy - backed on the token exchange into information populating the client 's cache of the groups . On the AIF : The first parameter of the AIF is said to be " the identifier of the specific group or topic " . I suppose the identifier cleanup will make this clearer . As it 's described as a default , how is that overridden , and how does the client know whether it can just construct a scope or has to try first and wait for the KDC to give it a good value in a 4.01 ? 4.1.2.2 GET handler of /ace - group / GROUPNAME : Why MUST requests from authorized ( as per third paragraph ) but non - member ( as per fourth ) clients turned down with 4.00 ? The only reason I can think of to deny that would be running an audit trail of which authorized clients actually joined ( to see when to rekey after a compromise ) , but as that sounds like it 's within range of the permissive side effects a GET could have just as well ( as per RFC7231 Section 4.2.1 ) , so rather than refusing , the GET could just be served and the audit entry created . ( Otherwise , my gut feeling says this should be a 4.01 response as well , but maybe we do n't need to have that discussion in the first place ) . If , of course , the client 's scope is only to get public keys of the group but not the cryptographic material ( as might be for scenarios where there is a verifier ) , then that client would not be allowed to GET that data , and should be 4.01'd no matter whether it has actually joined the group nor not . That case seems not to be covered well in the 4.1.2.2 GET handler description : Neither check ( " group is in scope " , " is a current member " ) really accounts for that . ( The ' signature verifier ' role of -oscore says " does not join [ ... ] as an actual member " , but I would n't count on everyone reading that as " not a member at all " for the purpose of the above paragraph ) . 4.1.3.1 and 4.1.3.2 ( /ace - group / GROUPNAME / pub - key FETCH ): The " The handler verifies that " and " Note that this resource handler " appear to contradict each other ( or the latter overrides the former ) ; it would be easier to understand if they were rolled in one . The former reads like boilerplate text ; I 'd rather see that avoided ( " For all resources , X and Y apply " ) or referenced if the reader ca n't be trusted to read the whole document ( " General authentication requirements per Section X apply . " ) . Defined terminology may help there as well ( " is Authenticated As a group member " , " is Authenticated As the group member identified by NODENAME " in other places ) . 4.1.3.1 and 4.1.3.2 ( /ace - group / GROUPNAME / pub - key GET and FETCH ): The GET text reads like a duplicate of the FETCH text . Ca n't this be a simple " GET requests are served just like FETCH requests but without any filtering " ? GROUPNAME / num : Is there a particular reason this is a dedicated resource and not just accessed through GROUPNAME ? request latest keying material " To this end , the Client sends a CoAP GET request to the /ace - group / GROUPNAME / nodes / NODENAME endpoint at the KDC , formatted as specified in Section 4.1.6.2 . " What 's the purpose of the node observing its own resource rather than the the whole group ? After all , its own keys wo n't change out of the blue , just the group 's material . I ' m a bit uncertain about the change of keys mid - blockwise , but ca n't put a finger on it yet . Do you have any use case examples that 'd help me figure out what such an operation would look like in the first place ? IANA File Extension : Why ? I ' ve only skimmed section 8 . Kind regards Christian
This document expands the ACE framework I-D.ietf-ace-oauth-authz to
define the message exchanges used to request, distribute and renew
the keying material in a group communication scenario, e.g. based on
multicast I-D.ietf-core-groupcomm-bis or on publishing-subscribing I-
D.ietf-core-coap-pubsub.  The ACE framework is based on CBOR RFC7049,
so CBOR is the format used in this specification.  However, using
JSON RFC8259 instead of CBOR is possible, using the conversion method
specified in Sections 4.1 and 4.2 of RFC7049.
"Node name" is the invariant once established identifier of the
node.  It is used in the communication between AS, RS and Client
to identify a member of the group.
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.
The full procedure can be separated in two phases: the first one
follows the ACE framework, between Client, AS and KDC; the second one
is the key distribution between Client and KDC.  After the two phases
are completed, the Client is able to participate in the group
communication, via a Dispatcher entity.
The joining node starts the joining process to become a member of
the group, by accessing the related group-membership resource at
the KDC.  At the end of the joining process, the joining node has
received from the KDC the parameters and keying material to
securely communicate with the other members of the group, and the
KDC has stored the association between the authorization
information from the access token and the secure session with the
client.
The joining node starts the joining process to become a member of
the group, by accessing the related group-membership resource at
the KDC.  At the end of the joining process, the joining node has
received from the KDC the parameters and keying material to
securely communicate with the other members of the group, and the
KDC has stored the association between the authorization
information from the access token and the secure session with the
joining node.
This value is a CBOR byte string, encoding a CBOR array of one or
more entries.
By default, each entry is encoded as specified by I-D.bormann-
core-ace-aif.  The object identifier Toid corresponds to the group
name and MUST be encoded as a tstr.  The permission set Tperm
indicates the roles that the client wishes to take in the group.
It is up to the application profiles to define Tperm (REQ2) and
register Toid and Tperm to fit the use case.  An example of scope
using the AIF format is given in cddl-ex-0.
This value is a CBOR byte string, wrapping a CBOR array of one or
more entries.
By default, each entry is encoded as specified by I-D.ietf-ace-
aif.  The object identifier Toid corresponds to the group name and
MUST be encoded as a tstr.  The permission set Tperm indicates the
roles that the client wishes to take in the group.  It is up to
the application profiles to define Tperm (REQ2) and register Toid
and Tperm to fit the use case.  An example of scope using the AIF
format is given in cddl-ex-0.
'req_cnf', as defined in Section 3.1 of I-D.ietf-ace-oauth-params,
optionally containing the public key or a reference to the public
key of the Client, if it wishes to communicate that to the AS.
Other additional parameters as defined in I-D.ietf-ace-oauth-authz,
can be included if necessary.
As in I-D.ietf-ace-oauth-authz, these parameters are included in the
payload, which is formatted as a CBOR map.  The Content-Format
"application/ace+cbor" defined in Section 8.14 of I-D.ietf-ace-oauth-
authz is used.
'access_token', containing the proof-of-possession access token.
'cnf' if symmetric keys are used, not present if asymmetric keys
are used.  This parameter is defined in Section 3.2 of I-D.ietf-
ace-oauth-params and contains the symmetric proof-of-possession
key that the Client is supposed to use with the KDC.
'rs_cnf' if asymmetric keys are used, not present if symmetric
keys are used.  This parameter is defined in Section 3.2 of I-
D.ietf-ace-oauth-params and contains information about the public
key of the KDC.
'expires_in', contains the lifetime in seconds of the access
token.  This parameter 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.
'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.  If
this parameter is not present the granted scope is equal to the
one requested in ssec-authorization-request}.
Other additional parameters as defined in I-D.ietf-ace-oauth-authz,
if necessary.
As defined in I-D.ietf-ace-oauth-authz, other additional parameters
can be included if necessary.
The Authorization Response sent from the AS to the Client is defined
in Section 5.6.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.
'scope' has the same format and encoding of 'scope' in the
Authorization Request, defined in ssec-authorization-request.  If
this parameter is not present, the granted scope is equal to the
one requested in ssec-authorization-request}.
a scope claim (see for example 'scope' registered in Section 8.13
of I-D.ietf-ace-oauth-authz for CWT).  This claim has the same
encoding as 'scope' parameter above.  Additionally, this claim has
the same value of the 'scope' parameter if the parameter is
present in the message, or it takes the value of 'scope' in the
Authorization Request otherwise.
As in I-D.ietf-ace-oauth-authz, these parameters are included in the
payload, which is formatted as a CBOR map.  The Content-Format
"application/ace+cbor" is used.
a scope claim (see for example 'scope' registered in Section 8.13
of I-D.ietf-ace-oauth-authz for CWT).  This claim has the same
encoding as the 'scope' parameter above.  Additionally, this claim
has the same value of the 'scope' parameter if the parameter is
present in the message, or it takes the value of 'scope' in the
Authorization Request otherwise.
The Client sends a CoAP POST request including the access token to
the KDC, as specified in Section 5.8.1 of I-D.ietf-ace-oauth-authz.
If the specific transport profile of ACE defines it, the Client MAY
use a different endpoint than /authz-info at the KDC to post the
access token to.
Optionally, the Client might want to request encoding information
about the public keys in the group, used for source authentication,
as well as any other group parameters.  The joining node MAY ask for
this information from the KDC in the same message it uses to POST the
token to the RS.
The Client sends a CoAP POST request including the access token to
the KDC, as specified in Section 5.8.1 of I-D.ietf-ace-oauth-authz.
This request differs from the one defined in I-D.ietf-ace-oauth-
authz, because it allows to transport additional encoding information
about the public keys in the group, used for source authentication,
as well as any other group parameters.  The joining node MAY ask for
this information from the KDC in the same message it uses to POST the
token to the RS.
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.
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 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.
The KDC MUST store the 'kdcchallenge' value associated to the Client
at least until it receives a join request from it (see ssec-key-
distribution-exchange), to be able to verify the proof of possession.
The same challenge MAY be reused several times by the Client, to
generate new proof of possessions, e.g. in case of update of the
public key, or to join a different group with a different signing
key, so it is RECOMMENDED that the KDC keeps storing the
'kdcchallenge' after the first join is processed as well.  If the KDC
has already discarded the 'kdcchallenge', that will trigger an error
response with a newly generated 'kdcchallenge' 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 to the Client
at least until it receives a join request from it (see ssec-key-
distribution-exchange), to be able to verify that the Client
possesses its own private key.  The same challenge MAY be reused
several times by the Client, to generate a new proof of possession,
e.g. in case of update of the public key, or to join a different
group with a different signing key, so it is RECOMMENDED that the KDC
keeps storing the 'kdcchallenge' after the first join is processed as
well.  If the KDC has already discarded the 'kdcchallenge', that will
trigger an error response with a newly generated 'kdcchallenge' that
the Client can use to restart the join process, as specified in ssec-
key-distribution-exchange.
Note that the CBOR map specified as payload of the 2.01 (Created)
response may include further parameters, e.g. according to the
signalled transport profile of ACE.
Application profiles of this specification MAY define alternative
specific negotiations of parameter values for signature algorithm and
signature keys, if 'sign_info' is not used (OPT2).
Note that the CBOR map specified as payload of the 2.01 (Created)
response may include further parameters, e.g. according to the
signalled transport profile of ACE.  Application profiles MAY define
the additional parameters to use within this exchange (OPT2b).
Application profiles of this specification MAY define alternative
specific negotiations of parameter values for the signature algorithm
and signature keys, if 'sign_info' is not used (OPT2a).
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 first element 'id' is an identifier of the group or an array
of identifiers for the groups for which this information applies.
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.
The third element 'sign_parameters' is a CBOR array indicating the
parameters of 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 (REQ4).
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).
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 '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 that 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 first element 'id' is a group name or an array of group names
for the group(s) for which this information applies.  Below, 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
Null, and indicates the signature algorithm used in the group(s)
identified by (the set of) '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.
The third element 'sign_parameters' is a CBOR array indicating the
parameters of the signature algorithm used in the group(s)
identified by (the set of) 'gname'.  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 (REQ4).
The fourth element 'sign_key_parameters' is a CBOR array
indicating the parameters of the key used with the signature
algorithm, in the group(s) identified by (the set of) 'gname'.
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).
The fifth element 'pub_key_enc' parameter is either a CBOR integer
indicating the encoding of public keys used in the group(s)
identified by (the set of) '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 '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).
The 'kdcchallenge' parameter is an OPTIONAL parameter of the Token
Post response message defined in Section 5.8.1 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).
The Client can upload a new, updated public key at the KDC.  This
is described in update-pub-key.
If the value of the GROUPNAME URI path and the group name in the
access token scope ('gname' in ssec-authorization-response) do not
match, the KDC MUST implement a mechanism to map the GROUPNAME
value in the URI to the group name, in order to retrieve the right
group (REQ1).  Each resource contains the symmetric group keying
material for that group.  These resources support the GET and POST
methods.
It is REQUIRED of the application profiles of this specification to
define what operations (i.e.  CoAP methods) are allowed on each
resource, for each role defined in ssec-authorization-request
according to REQ2 (REQ7aa).
Note that the KDC only verifies that the node is authorized by the AS
to access this resource.  Nodes that are not members of the group but
are authorized to do signature verifications on the group messages
may be allowed to access this resource, if the application needs it.
'scope', with value the specific resource at the KDC that the
Client is authorized to access, i.e. group or topic identifier,
and role(s).  This value is a CBOR byte string encoding one scope
entry, as defined in ssec-authorization-request.
'scope', with value the specific resource at the KDC that the
Client is authorized to access, i.e. group or topic name, and
role(s).  This value is a CBOR byte string wrapping one scope
entry, as defined in ssec-authorization-request.
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 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).
The first array is non-empty.  Each element of the first array
contains one role or a combination of roles for the group
identified by "GROUPNAME".  The Client indicates that it wishes
to receive the public keys of all group members having any of
the single roles, or at least all of the roles indicated in any
combinations 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".
If the Client wishes to receive all public keys of all group
members, it encodes the 'get_pub_key' parameter as the CBOR simple
value Null.
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.
Note that the second array (array of node identifiers) is empty
for this handler, because the joining node is not expected to
filter based on node identifiers, 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).
Also note that the second array (array of roles) is non-empty for
this handler, but that is not necessarily the case for other
handlers using this parameter: if this array is empty it means
that the client is not filtering public keys based on roles.
Finally, 'get_pub_keys' is never used as an array containing two
empty arrays (in CBOR diagnostic notation: [ [ ], [ ] ] ), so if
this parameter is received as formatted in that way, it has to be
considered malformed.
scope is the byte string specified in the 'scope parameter
above'.
N_S is the challenge received from the KDC in the
'kdcchallenge' parameter of the 2.01 (Created) response to the
token POST request (see token-post).
N_C is the nonce generated by the Client and specified in the
'cnonce' parameter above.
scope is the CBOR byte string either specified in the 'scope'
parameter above, if present, or as a default scope that the
handler is expected to understand, if omitted.
N_S is the challenge received from the KDC in the
'kdcchallenge' parameter of the 2.01 (Created) response to the
token POST request (see token-post), encoded as a CBOR byte
string.
N_C is the nonce generated by the Client and specified in the
'cnonce' parameter above, encoded as a CBOR byte string.
An example of signature input construction to compute
'client_cred_verify' using CBOR encoding is given in fig-client-
cred-input.
The handler extracts the granted scope from the access token, and
checks the requested one against the token one.  If this join message
does not include a 'scope' field, the KDC is expected to understand
which group and role the Client is requesting (e.g. there is only one
the Client has been granted).  If the KDC can not recognize which
scope the Client is requesting, it MUST respond with a 4.00 (Bad
Request) 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.  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).
The handler extracts the granted scope from the access token, and
checks the requested one against the token one.  If the requested one
is not a subset of the token one, the KDC MUST respond with a 4.01
(Unauthorized) error message.  If this join message does not include
a 'scope' field, the KDC is expected to understand which group and
role(s) the Client is requesting (e.g. there is only one the Client
has been granted).  If the KDC can not recognize which scope the
Client is requesting, it MUST respond with a 4.00 (Bad Request) error
message.
The KDC verifies that the group name of the /ace-group/GROUPNAME path
is a subset of the 'scope' stored in the access token associated to
this client.  The KDC also verifies that the roles the client is
granted in the group allow it to perform this operation on this
resource (REQ7aa).  If either verification fails, the KDC MUST
respond with a 4.01 (Unauthorized) error message.  The KDC MAY
respond with an AS Request Creation Hints, as defined in
Section 5.1.2 of I-D.ietf-ace-oauth-authz.  Note that in this case,
the content format MUST be set to application/ace+cbor.
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 content format application/ace+cbor,
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 the token was posted but the KDC cannot retrieve the
'kdcchallenge' associated to this Client (see token-post), the KDC
MUST respond with a 4.00 Bad Request error response, including a
newly generated 'kdcchallenge' in a CBOR map in the payload.  This
error response MUST also have Content-Format "application/ace+cbor".
If the token was posted but the KDC cannot retrieve the
'kdcchallenge' associated to this Client (see token-post), the KDC
MUST respond with a 4.00 Bad Request error response, including a
newly generated 'kdcchallenge' in a CBOR map in the payload.  This
error response MUST also have Content-Format application/ace+cbor.
The exact format of the 'key' value MUST be defined in applications
of this specification (REQ7), as well as accepted values of 'gkty' by
the application (REQ8).  Additionally, documents specifying the key
format MUST register it in the "ACE Groupcomm Key" registry defined
in iana-key, including its name, type and application profile to be
used with.
The exact format of the 'key' value MUST be defined in applications
of this specification (REQ7), as well as values of 'gkty' accepted by
the application (REQ8).  Additionally, documents specifying the key
format MUST register it in the "ACE Groupcomm Key" registry defined
in iana-key, including its name, type and application profile to be
used with.
'pub_keys', may only be present if 'get_pub_keys' was present in
the request.  This parameter is a CBOR byte string, which encodes
the public keys of all the group members paired with the
respective member identifiers.  The default encoding for public
keys is COSE Keys, so the default encoding for 'pub_keys' is a
CBOR byte string wrapping a COSE_KeySet (see I-D.ietf-cose-
rfc8152bis-struct), which contains the public keys of all the
members of the group.  In particular, each COSE Key in the
COSE_KeySet includes the identifier of the corresponding group
member as value of its 'kid' key parameter.  Alternative specific
encodings of this parameter MAY be defined in applications of this
specification (OPT1).  The specific format of the identifiers of
group members MUST be specified in the application profile (REQ9).
'peer_roles', MUST be present if 'pub_keys' is present.  This
parameter is a CBOR array of n elements, with n the number of
members in the group (and number of public keys included in the
'pub_keys' parameter).  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.
'pub_keys', may only be present if 'get_pub_keys' was present in
the request.  This parameter is a CBOR byte string, which encodes
the public keys of all the group members paired with the
respective member identifiers.  The default encoding for public
keys is COSE Keys, so the default encoding for 'pub_keys' is a
CBOR byte string wrapping a COSE_KeySet (see I-D.ietf-cose-
rfc8152bis-struct), which contains the public keys of all the
members of the group.  In particular, each COSE Key in the
COSE_KeySet includes the node identifier of the corresponding
group member as value of its 'kid' key parameter.  Alternative
specific encodings of this parameter MAY be defined in
applications of this specification (OPT1).  The specific format of
the node identifiers of group members MUST be specified in the
application profile (REQ9).
'peer_roles', MUST be present if 'pub_keys' is 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.
If verification succeeds, the handler returns a 2.05 (Content)
message containing the symmetric group keying material.  The payload
of the response is formatted as a CBOR map which MUST contain the
parameters 'gkty','key' and 'num' specified in gid-post.
The KDC verifies that the group name of the /ace-group/GROUPNAME path
is a subset of the 'scope' stored in the access token associated to
this client.  The KDC also verifies that the roles the client is
granted in the group allow it to perform this operation on this
resource (REQ7aa).  If either verification fails, the KDC MUST
respond with a 4.01 (Unauthorized) error message.  The KDC MAY
respond with an AS Request Creation Hints, as defined in
Section 5.1.2 of I-D.ietf-ace-oauth-authz.  Note that in this case
the content format MUST be set to application/ace+cbor.
If verification succeeds, the handler returns a 2.05 (Content)
message containing the symmetric group keying material.  The payload
of the response is formatted as a CBOR map which MUST contain the
parameters 'gkty', 'key' and 'num' specified in 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 first array may be empty, if the Client does not wish to
filter the requested public keys based on roles of group
members.
The second array 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
all nodes having these node identifiers.
As mentioned, both arrays can not be empty at the same time.
the identifier matches with one of those indicated in the request.
the node identifier matches with one of those indicated in the
request.
Then, the handler returns a 2.05 (Content) message response with
payload formatted as a CBOR map, containing only the 'pub_keys' and
'peer_roles' parameters from gid-post.  In particular, 'pub_keys'
encodes the list of public keys of those group members including the
respective member identifiers, while 'peer_roles' encodes their
respective role (or CBOR array of roles) in the group.  The specific
format of public keys as well as of identifiers of group members is
specified by the application profile (OPT1, REQ9).
If the KDC does not store any public key associated with the
specified member identifiers, the handler returns a response with
payload formatted as a CBOR byte string of zero length.
The KDC silently ignores those identifiers.
Then, the handler returns a 2.05 (Content) message response with
payload formatted as a CBOR map, containing only the 'pub_keys' and
'peer_roles' parameters from gid-post.  In particular, 'pub_keys'
encodes the list of public keys of those group members including the
respective member identifiers, while 'peer_roles' encodes their
respective role (or CBOR array of roles) in the group.  The specific
format of public keys as well as of node identifiers of group members
is specified by the application profile (OPT1, REQ9).
If the KDC does not store any public key 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
'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 (REQ13).
The KDC silently ignores those node identifiers.
If verification succeeds, the handler returns a 2.05 (Content)
message containing the public keys of all the current group members,
for the group identified by "GROUPNAME".  The payload of the response
is formatted as a CBOR map, containing only the 'pub_keys' and
'peer_roles' parameters from gid-post.  In particular, 'pub_keys'
encodes the list of public keys of those group members including the
respective member identifiers, while 'peer_roles' encodes their
respective role (or CBOR array of roles) in the group.
If the KDC does not store any public key for the group, the handler
returns a response with payload formatted as a CBOR byte string of
zero length.  The specific format of public keys as well as of
identifiers of group members is specified by the application profile
(OPT1, REQ9).
Note that this resource handler only verifies that the node is
authorized by the AS to access this resource.  Nodes that are not
members of the group but are authorized to do signature verifications
on the group messages may be allowed to access this resource, if the
application needs it.
The KDC performs the same verifications as the FETCH handler in
pubkey-fetch, and if successful returns the same response as in
pubkey-fetch but without filtering based on roles or node
identifiers: all the group members' public keys are returned.
Note that this resource handler, as the FETCH handler for the same
resource, only verifies that the node is authorized by the AS to
access this resource.  Nodes that are not members of the group but
are authorized to do signature verifications on the group messages
may be allowed to access this resource, if the application needs it.
The PUT handler is used to get the KDC to produce and return
individual keying material to protect outgoing messages for the node
(identified by "NODENAME") for the group identified by "GROUPNAME".
Application profiles MAY also use this handler to rekey the whole
group.  (OPT8) It is up to the application profiles to specify if
this handler supports renewal of individual keying material, renewal
of the group keying material or both.
If verification succeeds, the handler returns a 2.05 (Content)
message containing newly-generated keying material for the Client,
and/or, if the application profiles requires it (OPT8), starts the
comprete group rekeying.  The payload of the response is formatted as
a CBOR map.  The specific format of newly-generated individual keying
material for group members, or of the information to derive it, and
corresponding CBOR label, MUST be specified in the application
profile (REQ15) and registered in iana-reg.
The PUT handler is used to get the KDC to produce and return
individual keying material to protect outgoing messages for the node
(identified by "NODENAME") for the group identified by "GROUPNAME".
Application profiles MAY also use this handler to rekey the whole
group.  It is up to the application profiles to specify if this
handler supports renewal of individual keying material, renewal of
the group keying material or both (OPT8).
If verification succeeds, the handler returns a 2.05 (Content)
message containing newly-generated keying material for the Client,
and/or, if the application profiles requires it (OPT8), starts the
complete group rekeying.  The payload of the response is formatted as
a CBOR map.  The specific format of newly-generated individual keying
material for group members, or of the information to derive it, and
corresponding CBOR label, MUST be specified in the application
profile (REQ15) and registered in iana-reg.
The handler verifies that the group name of the /ace-group/GROUPNAME
path is a subset of the 'scope' stored in the access token associated
to this client, identified by "NODENAME".  The KDC also verifies that
the roles the client is granted in the group allow it to perform this
operation on this resource (REQ7aa).  If either verification fails,
the KDC MUST respond with a 4.01 (Unauthorized) error message.
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).
The handler verifies that the group name GROUPNAME is a subset of the
'scope' stored in the access token associated to this client.  The
KDC also verifies that the roles the client is granted in the group
allow it to perform this operation on this resource (REQ7aa).  If
either 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 contains
unknown or non-expected fields present, the handler MUST silently
ignore them and continue processing.  Application profiles MAY define
optional or mandatory payload formats for specific error cases
(OPT6).
Otherwise, the handler checks that the public key specified in the
'client_cred' field has a valid format for the group identified by
"GROUPNAME", i.e. it is encoded as expected and is compatible with
the signature algorithm and possible associated parameters.  If that
cannot be verified, the handler MUST respond with a 4.00 (Bad
Request) error message.  Applications profiles MAY define
alternatives (OPT5).
Otherwise, the handler verifies the signature contained in the
'client_cred_verify' field of the request, using the public key
specified in the 'client_cred' field.  If the signature does not pass
verification, the handler MUST respond with a 4.00 (Bad Request)
error message.  If the KDC cannot retrieve the 'kdcchallenge'
associated to this Client (see token-post), the KDC MUST respond with
a 4.00 Bad Request error respons, including a newly generated
'kdcchallenge' in a CBOR map in the payload the payload.  This error
response MUST also have Content-Format "application/ace+cbor".
Otherwise, the handler checks that the public key specified in the
'client_cred' field has a valid format for the group identified by
"GROUPNAME", i.e. it is encoded as expected and is compatible with
the signature algorithm and possible associated parameters.  If that
cannot be successfully verified, the handler MUST respond with a 4.00
(Bad Request) error message.  Applications profiles MAY define
alternatives (OPT5).
Otherwise, the handler verifies the signature contained in the
'client_cred_verify' field of the request, using the public key
specified in the 'client_cred' field.  If the signature does not pass
verification, the handler MUST respond with a 4.01 (Unauthorized)
error message.  If the KDC cannot retrieve the 'kdcchallenge'
associated to this Client (see token-post), the KDC MUST respond with
a 4.00 Bad Request error response, whose payload is a CBOR map
including a newly generated 'kdcchallenge'.  This error response MUST
also have Content-Format application/ace+cbor.
fig-ace-group-fetch gives an overview of the exchanges described
above.
fig-key-distr-join gives an overview of the Joining exchange between
Client and KDC, when the Client first joins a group.
fig-ace-group-fetch gives an overview of the exchanges described
above, and fig-ace-group-fetch-2 shows an example.
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.
It is application dependent and pertaining to the particular message
exchange (e.g.  I-D.ietf-core-oscore-groupcomm) to set up these
policies, to instruct clients to retain incoming messages and for how
long (OPT4).  This allows clients to possibly decrypt such messages
after getting updated keying material, rather than just consider them
non valid messages to discard right away.
It is application dependent and pertaining to the particular message
exchange (e.g.  I-D.ietf-core-oscore-groupcomm) to set up these
policies for instructing clients to retain incoming messages and for
how long (OPT4).  This allows clients to possibly decrypt such
messages after getting updated keying material, rather than just
consider them non valid messages to discard right away.
fig-key-redistr-req-resp gives an overview of the exchange described
above.
Can make the ace-group/GROUPNAME/nodes/NODENAME resource
Observable RFC7641, and send notifications to Clients when the
keying material is updated.
fig-key-redistr-req-resp gives an overview of the exchange described
above, while fig-key-redistr-req-resp-2 shows an example.
Can make the ace-group/GROUPNAME resource Observable RFC7641, and
send notifications to Clients when the keying material is updated.
Beside possible expiration, the client may need to communicate to the
KDC its need for the keying material to be renewed, e.g. due to
exhaustion of AEAD nonces, if AEAD is used for protecting group
communnication.  Depending on the application profile (OPT8), this
can result in renewal of idividual keying material, group keying
material, or both.  For example, if the Client uses an individual key
to protect outgoing traffic and has to renew it, the node may request
a new one, or new input material to derive it, without renewing the
whole group keying material.
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.
fig-renewal-req-resp gives an overview of the exchange described
above.
Beside possible expiration, the client may need to communicate to the
KDC its need for the keying material to be renewed, e.g. due to
exhaustion of AEAD nonces, if AEAD is used for protecting group
communnication.  Depending on the application profile (OPT8), this
can result in renewal of individual keying material, group keying
material, or both.
For example, if the Client uses an individual key to protect outgoing
traffic and has to renew it, the node may request a new one, or new
input material to derive it, without renewing the whole group keying
material.
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.
fig-renewal-req-resp gives an overview of the exchange described
above, while fig-renewal-req-resp-2 shows an example.
fig-public-key-1 and fig-public-key-2 give an overview of the
exchanges described above.
fig-public-key-1 and fig-public-key-2 give an overview of the
exchanges described above, while fig-public-key-3 and fig-public-
key-4 show an example for each exchange.
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.
Figure fig-pub-key-update-req-resp gives an overview of the exchange
described above.
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.
Figure fig-pub-key-update-req-resp gives an overview of the exchange
described above, while fig-pub-key-update-req-resp-2 shows an
example.
fig-policies gives an overview of the exchange described above.
fig-policies gives an overview of the exchange described above, while
fig-policies-2 shows an example.
fig-version gives an overview of the exchange described above.
fig-version gives an overview of the exchange described above, while
fig-version-2 shows an example.
Note that, after having left the group, a node may wish to join it
again.  Then, as long as the node is still authorized to join the
group, i.e. it still has a valid access token, it can re-request to
join the group directly to the KDC without needing to retrieve a new
access token from the AS.  This means that the KDC might decide to
keep track of nodes with valid access tokens, before deleting all
information about the leaving node.
Note that, after having left the group, a node may wish to join it
again.  Then, as long as the node is still authorized to join the
group, i.e. it still has a valid access token, it can request to re-
join the group directly to the KDC without needing to retrieve a new
access token from the AS.  This means that the KDC might decide to
keep track of nodes with valid access tokens, before deleting all
information about the leaving node.
When a Client receives a message from a sender for the first time, it
needs to have a mechanism in place to avoid replay, e.g.
Appendix B.2 of RFC8613.  In case the Client rebooted and lost the
security state used to protect previous communication with that
sender, such a mechanism is useful for the recipient to be on the
safe side.  Besides, if the KDC has renewed the group keying
material, and the time interval between the end of the rekeying
process and the joining of the Client is sufficiently small, that
Client is also on the safe side, since replayed older messages
protected with the previous keying material will not be accepted.
When a Client receives a message from a sender for the first time, it
needs to have a mechanism in place to avoid replay, e.g.
Appendix B.2 of RFC8613.  In case the Client rebooted and lost the
security state used to protect previous communication with that
sender, such a mechanism is useful for the recipient to be on the
safe side.
Besides, if the KDC has renewed the group keying material, and the
time interval between the end of the rekeying process and the joining
of the Client is sufficiently small, that Client is also on the safe
side, since replayed older messages protected with the previous
keying material will not be accepted.