Draft: draft-ietf-ace-key-groupcomm

Commentary: Includes all review comments from  , following discussion at IETF106 .
Profiles that use group communication can build on this document, by
defining a number of details such as the exact group communication
protocol and security protocols used.  The specific list of details a
profile needs to define is in req.
Profiles that use group communication can build on this document, by
defining a number of details such as the exact group communication
protocol and security protocols used.  The specific list of details a
profile needs to define is shown in req.
Authorization Server (AS): same as AS in the ACE Framework; it
enforces access policies, and knows if a node is allowed to join
the group with write and/or read rights.
Key Distribution Center (KDC): maintains the keying material to
protect group communications, and provides it to Clients
authorized to join the group.  During the first part of the
exchange (sec-auth), it takes the role of the RS in the ACE
Framework.  During the second part (key-distr), which is not based
on the ACE Framework, it distributes the keying material.  In
addition, it provides the latest keying material to group members
when requested.  If required by the application, the KDC renews
and re-distributes the keying material in the group when
membership changes.
Authorization Server (AS): same as AS in the ACE Framework; it
enforces access policies, and knows if a node is allowed to join a
given group with write and/or read rights.
Key Distribution Center (KDC): maintains the keying material to
protect group communications, and provides it to Clients
authorized to join a given group.  During the first part of the
exchange (sec-auth), it takes the role of the RS in the ACE
Framework.  During the second part (key-distr), which is not based
on the ACE Framework, it distributes the keying material.  In
addition, it provides the latest keying material to group members
when requested or, if required by the application, when membership
changes.
fig-flow provides a high level overview of the message flow for a
node joining a group communication setting.
fig-flow provides a high level overview of the message flow for a
node joining a group communication setting, which can be expanded as
follows.
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 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.
The joining node and the KDC maintain the secure association, to
support possible future communications.  These especially include
key management operations, such as retrieval of updated keying
material or participation to a group rekeying process.
The payload of the 2.01 response is a CBOR map, which MUST include
the parameter 'rsnonce' defined in Section rsnonce, specifying a
dedicated nonce N_S generated by the KDC.  The Client may use this
nonce for proving possession of its own private key (see the
'client_cred_verify' parameter in key-distr).
Optionally, if they were included in the request, the AS MAY include
the 'sign_info' parameter as well as the 'pub_key_enc' parameter
defined in sign-info and pub-key-enc of this specification,
respectively.
The payload of the 2.01 response is a CBOR map, which MUST include
the parameter 'rsnonce' defined in Section rsnonce, specifying a
dedicated nonce N_S generated by the KDC.  The Client may use this
nonce for proving 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).
Optionally, if they were included in the request, the KDC MAY include
the 'sign_info' parameter as well as the 'pub_key_enc' parameter
defined in sign-info and pub-key-enc of this specification,
respectively.
The 'pub_key_enc' parameter MUST be present if the POST request
included the 'pub_key_enc' parameter with value Null.  If present,
the 'pub_key_enc' parameter of the 2.01 (Created) response is a CBOR
integer, indicating the encoding of public keys used in the group.
Its acceptable values are taken from the "CWT Confirmation Method"
Registry defined in I-D.ietf-ace-cwt-proof-of-possession.  It is
REQUIRED of the application profiles to define specific values to use
for this parameter (REQ6).
The 'pub_key_enc' parameter MUST be present if the POST request
included the 'pub_key_enc' parameter with value Null.  If present,
the 'pub_key_enc' parameter of the 2.01 (Created) response is either
a CBOR integer indicating the encoding of public keys used in the
group, 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 I-D.ietf-ace-cwt-proof-of-possession.  It is
REQUIRED of the application profiles to define specific values to use
for this parameter (REQ6).
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).
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/cbor.
TODO: Do we need to define a new Content-Format cbor+ace-groupcomm?
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.
'client_cred', with value the public key or certificate of the
Client, encoded as a CBOR byte string.  If the KDC is managing
(collecting from/distributing to the Client) the public keys of
the group members, this field contains the public key of the
Client.  The default encoding for public keys is COSE Keys.
Alternative specific encodings of this parameter MAY be defined in
applications of this specification (OPT1).
'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).
'client_cred_verify', encoded as a CBOR byte string.  This
parameter MUST be present if the 'client_cred' parameter is
present.  This parameter contains a signature computed by the
Client over N_S concatenated with N_C, where N_S is the nonce
received from the KDC in the 'rsnonce' parameter of the 2.01
(Created) response to the token POST request (see token-post),
while N_C is the nonce generated by the Client and specified in
the 'cnonce' parameter above.  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.
'pub_keys_repos', can be present if a certificate is present in
the 'client_cred' field, with value a list of public key
repositories storing the certificate of the Client.  This
parameter is encoded as a CBOR array of CBOR text strings, each of
which specifies the URI of a key repository.
If the request is not formatted correctly (e.g. unknown fields
present), the handler MUST respond with 4.00 (Bad Request) error
message.
'kty', identifying the key type of the 'key' parameter.  The set
of values can be found in the "Key Type" column of the "ACE
Groupcomm Key" Registry.  Implementations MUST verify that the key
type matches the application profile being used, if present, as
registered in the "ACE Groupcomm Key" registry.
'client_cred_verify', encoded as a CBOR byte string.  This
parameter MUST be present if the 'client_cred' parameter is
present.  This parameter contains a signature computed by the
Client over N_S concatenated with N_C, where N_S is the nonce
received from the KDC in the 'rsnonce' parameter of the 2.01
(Created) response to the token POST request (see token-post),
while N_C is the nonce generated by the Client and specified in
the 'cnonce' parameter above.  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 nonce 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.
'pub_keys_repos', can be present if a certificate is present in
the 'client_cred' field, with value the URI of the certificate of
the Client.  This parameter is encoded as a CBOR text string.
Alternative specific encodings of this parameter MAY be defined in
applications of this specification (OPT3).
The handler verifies that the group identifier of the /ace-group/gid
path is a subset of the 'scope' stored in the access token associated
to this client.  If verification fails, the KDC MUST respond with a
the 'sign_info' and 'pub_key_enc' parameter, formatted as
'sign_info_res' and 'pub_key_enc_res' in the payload of the 2.01
(Created) response to the Token Post as defined in token-post.  Note
that in this case, the content format MUST be set to application/
ace+cbor.
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 4.00 (Bad Request) error message.  The
response MAY contain a CBOR map in the payload with ace-
groupcomm+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 KDC stores the group members' public keys, the handler
verifies that one public key can be retrieved for the joining node,
either from the 'client_cred' field, or from the KDC previous
knowledge of it.  In particular, the KDC checks that such public key
has an accepted format for the group identified by "gid", i.e. it is
encoded as expected and is compatible with the signature algorithm
and possible associated parameters.  If that cannot be verified, it
is RECOMMENDED that the handler stops the joining process and
responds with 4.00 (Bad Request) error message.  Applications
profiles MAY define alternatives (OPT5).
If the signature contained in "client_cred_verify" does not pass
verification, the handler MUST respond with 4.00 (Bad Request) error
message.
'gkty', identifying the key type of the 'key' parameter.  The set
of values can be found in the "Key Type" column of the "ACE
Groupcomm Key" Registry.  Implementations MUST verify that the key
type matches the application profile being used, if present, as
registered in the "ACE Groupcomm Key" registry.
'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.
The exact format of the 'key' value MUST be defined in applications
of this specification (REQ7), as well as accepted values of 'kty' 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.
'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.
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.
'profile', with value a CBOR integer that MUST be used to uniquely
identify the application profile for group communication.  The
value MUST be registered in the "ACE Groupcomm Profile" Registry.
'ace-groupcomm-profile', with value a CBOR integer that MUST be
used to uniquely identify the application profile for group
communication.  Applications of this specification MUST register
an application profile identifier and the related value for this
parameter in the "ACE Groupcomm Profile" Registry (REQ12).
MAY be defined in applications of this specification (OPT2).  The
specific format of the identifiers of group members MUST be
specified in the application profile (REQ8).
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).
'group_policies', with value a CBOR map, whose entries specify how
the group handles specific management aspects.  These include, for
instance, approaches to achieve synchronization of sequence
numbers among group members.  The elements of this field are
registered in the "ACE Groupcomm Policy" Registry.  This
specification defines the two elements "Sequence Number
Synchronization Method" and "Key Update Check Interval", which are
summarized in fig-ACE-Groupcomm-Policies.  Application profiles
that build on this document MUST specify the exact content format
of included map entries (REQ9).
'mgt_key_material', encoded as a CBOR byte string and containing
the administrative keying material to participate in the group
rekeying performed by the KDC.  The exact format and content
depend on the specific rekeying scheme used in the group, which
MAY be specified in the application profile (OPT3).
Specific application profiles that build on this document MUST
specify how exactly the keying material is used to protect the group
communication (REQ10).
'group_policies', with value a CBOR map, whose entries specify how
the group handles specific management aspects.  These include, for
instance, approaches to achieve synchronization of sequence
numbers among group members.  The elements of this field are
registered in the "ACE Groupcomm Policy" Registry.  This
specification defines the two elements "Sequence Number
Synchronization Method" and "Key Update Check Interval", which are
summarized in fig-ACE-Groupcomm-Policies.  Application profiles
that build on this document MUST specify the exact content format
of included map entries (REQ14).
'mgt_key_material', encoded as a CBOR byte string and containing
the administrative keying material to participate in the group
rekeying performed by the KDC.  The application profile MUST
define if this field is used, and if used then MUST specify the
exact format and content which depend on the specific rekeying
scheme used in the group.  If the usage of 'mgt_key_material' is
indicated and its format defined for a specific key management
scheme, that format must explicitly indicate the key management
scheme itself.  If a new rekeying scheme is defined to be used for
an existing 'mgt_key_material' in an existing profile, then that
profile will have to be updated accordingly, especially with
respect to the usage of 'mgt_key_material' related format and
content (REQ18).
Specific application profiles that build on this document MUST
specify the communication protocol that members of the group use to
communicate with each other (REQ10) and how exactly the keying
material is used to protect the group communication (REQ11).
If verification succeeds, the handler returns a 2.05 (Content)
message containing the symmetric group keying material, the group
policies and all the public keys of the current members of the group.
The payload of the response is formatted as a CBOR map which MUST
contain the parameters 'kty','key' and 'num' specified in gid-post.
The payload MAY also include the parameters 'profile', 'exp' and
'mgt_key_material' parameters specified in gid-post.
The POST handler receives identifiers of group members for the group
identified by "gid" and returns the public keys of such group
members.
The handler verifies that the group identifier of the /ace-group/gid
path 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.  The KDC MAY set the payload with
the 'sign_info' and 'pub_key_enc' parameter, formatted as
'sign_info_res' and 'pub_key_enc_res' in the payload of the 2.01
(Created) response to the Token Post as defined in token-post.  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 payload MAY also include the parameters 'ace-groupcomm-profile',
'exp' and 'mgt_key_material' parameters specified in gid-post.
This resource implements GET and FETCH handlers.
The FETCH handler receives identifiers of group members for the group
identified by "gid" and returns the public keys of such group
members.
'get_pub_keys', whose value is a non-empty CBOR array.  Each
element of the array is the identifier of a group member for the
group identified by "gid".  The specific format of public keys as
well as identifiers of group members MUST be specified by the
application profile (REQ11, REQ8).
The handler verifies that the 'get_pub_keys' parameter is not an
empty CBOR Array.  If verification fails, the KDC MUST treat the
request as malformed and respond with a 4.00 (Bad Request) error
message.
'get_pub_keys', whose value is a non-empty CBOR array.  Each
element of the array is the identifier of a group member for the
group identified by "gid".  The specific format of public keys as
well as identifiers of group members MUST be specified by the
application profile (OPT1, REQ9).
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 "gid".  The payload of the response is
formatted as a CBOR map containing only the 'pub_keys' parameter from
gid-post, which encodes the list of public keys of all the group
members including the respective member identifiers.  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 (REQ11, REQ8).
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 "gid".  The payload of the response is
formatted as a CBOR map containing only the 'pub_keys' parameter from
gid-post, which encodes the list of public keys of all the group
members including the respective member identifiers.  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).
The specific format and meaning of group policies MUST be specified
in the application profile (REQ13).
The specific format and meaning of group policies MUST be specified
in the application profile (REQ14).
The POST handler removes the node from the group, for the group
identified by "gid".
This resource implements GET, PUT and DELETE handlers.
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 "node") for the group identified by "gid".
The handler expects a request with empty payload.
If verification succeeds, the handler returns a 2.05 (Content)
message containing newly-generated individual keying material for the
Client, or information enabling the Client to derive it.  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 identifier of the /ace-group/gid
path is a subset of the 'scope' stored in the access token associated
to this client, identified by "node".  If verification fails, the KDC
MUST respond with a 4.01 (Unauthorized) error message.
If verification succeeds, the handler returns a 2.05 (Content)
message containing both the group keying material and the individual
keying material for the Client, or information enabling the Client to
derive it.  The payload of the response is formatted as a CBOR map.
The format for the group keying material is the same as defined in
the response of gid-get.  The specific format of 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 DELETE handler removes the node (identified by "node") from the
group, for the group identified by "gid".  If the node sending the
request and the node name used in the Uri-Path do not match, the
handler responds with a 4.01 (Unauthorized) error response.
TODO: Check the previous sentence.
If verification succeeds, the handler removes the client from the
group identified by "gid", for specific roles if roles were specified
in the 'scope' field, or for all roles.  That includes removing the
public key of the client if the KDC keep tracks of that.  Then, the
handler returns a 2.05 (Content) message with empty payload.
If verification succeeds, the handler returns a 2.05 (Content)
message containing newly-generated individual keying material for the
Client, or information enabling the Client to derive it.  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 (REQ14) and registered in iana-
reg.
If verification succeeds, the handler removes the client from the
group identified by "gid", for specific roles if roles were specified
in the 'scope' field, or for all roles.  That includes removing the
public key of the client if the KDC keep tracks of that.  Then, the
handler delete the sub-resource /node and returns a 2.02 (Deleted)
message with empty payload.
If not previously established, the Client and the KDC MUST first
establish a pairwise secure communication channel (REQ15).  This can
be achieved, for instance, by using a transport profile of ACE.  The
Joining exchange MUST occur over that secure channel.  The Client and
the KDC MAY use that same secure channel to protect further pairwise
communications that must be secured.
If not previously established, the Client and the KDC MUST first
establish a pairwise secure communication channel (REQ16).  This can
be achieved, for instance, by using a transport profile of ACE.  The
Joining exchange MUST occur over that secure channel.  The Client and
the KDC MAY use that same secure channel to protect further pairwise
communications that must be secured.
To join the group, the Client sends a CoAP POST request to the /ace-
group/gid endpoint at the KDC, where gid is the group identifier of
the group to join, formatted as specified in gid-post.  This group
identifier is the same as the 'scope' value of the Authorization
Request/Response, or it can be retrieved from it.
To join the group, the Client sends a CoAP POST request to the /ace-
group/gid endpoint at the KDC, where gid is the group identifier of
the group to join, formatted as specified in gid-post.  This group
identifier is the same as the 'scope' value 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.
The Client may need to request the latest group keying material also
upon receiving messages from other group members without being able
to retrieve the material to correctly decrypt them.  This may be due
to a previous update of the group keying material (rekeying)
triggered by the KDC, that the Client was not able to receive or
decrypt.  To this end, the Client sends a CoAP GET request to the
/ace-group/gid endpoint at the KDC, formatted as specified in gid-
get.
The Client may need to request the latest group keying material also
upon receiving messages from other group members without being able
to retrieve the material to correctly decrypt them.  This may be due
to a previous update of the group keying material (rekeying)
triggered by the KDC, that the Client was not able to receive or
decrypt.  To this end, the Client sends a CoAP GET request to the
/ace-group/gid/node endpoint at the KDC, formatted as specified in
node-get.
Can make the ace-group/gid resource Observable, and send
notifications to Clients when the keying material is updated.
Can make the ace-group/gid/node resource Observable, and send
notifications to Clients when the keying material is updated.
Beside possible expiration and depending on what part of the keying
material is no longer eligible to be used, the client may need to
communicate to the KDC its need for that part to be renewed.  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, that is a CoAP GET request to the
/ace-group/gid/node endpoint at the KDC, where gid is the group
identifier, and formatted as defined in node-get.
Beside possible expiration and depending on what part of the keying
material is no longer eligible to be used, the client may need to
communicate to the KDC its need for that part to be renewed.  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, that is a CoAP PUT request to the
/ace-group/gid/node endpoint at the KDC, where gid is the group
identifier and node 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 of either all
group members or a specified subset, by sending a CoAP GET or POST
request to the /ace-group/gid/pub-key endpoint at the KDC, where gid
is the group identifier, and formatted as defined in pubkey-get and
pubkey-post.
In case the KDC maintains the public keys of group members, a node in
the group can contact the KDC to request public keys of either all
group members or a specified subset, by sending a CoAP GET or FETCH
request to the /ace-group/gid/pub-key endpoint at the KDC, where gid
is the group identifier, and formatted as defined in pubkey-get and
pubkey-fetch.
This specification defines a number of fields used during the second
part of the message exchange, after the ACE Token POST exchange.  The
table below summarizes them, and specifies the CBOR key to use
instead of the full descriptive name.
This specification defines a number of fields used during the second
part of the message exchange, after the ACE Token POST exchange.  The
table below summarizes them, and specifies the CBOR key to use
instead of the full descriptive name.  Note that the media type ace-
groupcomm+cbor MUST be used when these fields are transported.
This specification registers the 'application/ace-groupcomm+cbor'
media type for messages of the protocols defined in this document
following the ACE exchange and carrying parameters encoded in CBOR.
This registration follows the procedures specified in RFC6838.
Encoding considerations: Must be encoded as CBOR map containing the
protocol parameters defined in [this document].
Security considerations: See sec-cons of this document.
Applications that use this media type: The type is used by
authorization servers, clients and resource servers that support the
ACE groupcomm framework as specified in [this document].
This Registry has been initially populated by the values in kty.  The
specification column for all of these entries will be this document.
This Registry has been initially populated by the values in gkty.
The specification column for all of these entries will be this
document.