idnits 2.17.1 draft-tiloca-ace-group-oscore-profile-01.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** There are 46 instances of too long lines in the document, the longest one being 2 characters in excess of 72. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (November 04, 2019) is 1634 days in the past. Is this intentional? -- Found something which looks like a code comment -- if you have code sections in the document, please surround them with '' and '' lines. Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Outdated reference: A later version (-03) exists of draft-dijk-core-groupcomm-bis-01 == Outdated reference: A later version (-16) exists of draft-ietf-ace-key-groupcomm-oscore-02 == Outdated reference: A later version (-46) exists of draft-ietf-ace-oauth-authz-25 == Outdated reference: A later version (-16) exists of draft-ietf-ace-oauth-params-05 == Outdated reference: A later version (-19) exists of draft-ietf-ace-oscore-profile-08 == Outdated reference: A later version (-21) exists of draft-ietf-core-oscore-groupcomm-05 ** Downref: Normative reference to an Informational RFC: RFC 5869 ** Obsolete normative reference: RFC 8152 (Obsoleted by RFC 9052, RFC 9053) == Outdated reference: A later version (-18) exists of draft-ietf-ace-dtls-authorize-08 == Outdated reference: A later version (-17) exists of draft-ietf-ace-mqtt-tls-profile-02 == Outdated reference: A later version (-43) exists of draft-ietf-tls-dtls13-33 == Outdated reference: A later version (-15) exists of draft-tiloca-core-oscore-discovery-03 -- Obsolete informational reference (is this intentional?): RFC 5246 (Obsoleted by RFC 8446) -- Obsolete informational reference (is this intentional?): RFC 6347 (Obsoleted by RFC 9147) Summary: 3 errors (**), 0 flaws (~~), 11 warnings (==), 4 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 ACE Working Group M. Tiloca 3 Internet-Draft R. Hoeglund 4 Intended status: Standards Track L. Seitz 5 Expires: May 7, 2020 RISE AB 6 F. Palombini 7 Ericsson AB 8 November 04, 2019 10 Group OSCORE Profile of the Authentication and Authorization for 11 Constrained Environments Framework 12 draft-tiloca-ace-group-oscore-profile-01 14 Abstract 16 This document specifies a profile for the Authentication and 17 Authorization for Constrained Environments (ACE) framework. The 18 profile uses Object Security for Constrained RESTful Environments 19 (OSCORE) and/or Group OSCORE to provide communication security 20 between a Client and (a group of) Resource Server(s). Furthermore, 21 the profile uses (Group) OSCORE to provide server authentication, and 22 OSCORE to achieve proof-of-possession for a key owned by the Client 23 and bound to an OAuth 2.0 Access Token. Also, the profile provides 24 proof-of-group-membership for the Client, by securely binding the 25 pre-established Group OSCORE Security Context to the pairwise OSCORE 26 Security Context newly established with the Resource Server. 28 Status of This Memo 30 This Internet-Draft is submitted in full conformance with the 31 provisions of BCP 78 and BCP 79. 33 Internet-Drafts are working documents of the Internet Engineering 34 Task Force (IETF). Note that other groups may also distribute 35 working documents as Internet-Drafts. The list of current Internet- 36 Drafts is at https://datatracker.ietf.org/drafts/current/. 38 Internet-Drafts are draft documents valid for a maximum of six months 39 and may be updated, replaced, or obsoleted by other documents at any 40 time. It is inappropriate to use Internet-Drafts as reference 41 material or to cite them other than as "work in progress." 43 This Internet-Draft will expire on May 7, 2020. 45 Copyright Notice 47 Copyright (c) 2019 IETF Trust and the persons identified as the 48 document authors. All rights reserved. 50 This document is subject to BCP 78 and the IETF Trust's Legal 51 Provisions Relating to IETF Documents 52 (https://trustee.ietf.org/license-info) in effect on the date of 53 publication of this document. Please review these documents 54 carefully, as they describe your rights and restrictions with respect 55 to this document. Code Components extracted from this document must 56 include Simplified BSD License text as described in Section 4.e of 57 the Trust Legal Provisions and are provided without warranty as 58 described in the Simplified BSD License. 60 Table of Contents 62 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 63 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 5 64 2. Protocol Overview . . . . . . . . . . . . . . . . . . . . . . 6 65 2.1. Pre-Conditions . . . . . . . . . . . . . . . . . . . . . 8 66 2.2. Access Token Retrieval . . . . . . . . . . . . . . . . . 8 67 2.3. Access Token Posting . . . . . . . . . . . . . . . . . . 9 68 2.4. Secure Communication . . . . . . . . . . . . . . . . . . 10 69 3. Client-AS Communication . . . . . . . . . . . . . . . . . . . 10 70 3.1. C-to-AS: POST to Token Endpoint . . . . . . . . . . . . . 11 71 3.1.1. 'context_id' Parameter . . . . . . . . . . . . . . . 13 72 3.1.2. 'salt' Parameter . . . . . . . . . . . . . . . . . . 14 73 3.1.3. 'client_cred' Parameter . . . . . . . . . . . . . . . 14 74 3.1.4. 'client_cred_verify' Parameter . . . . . . . . . . . 14 75 3.2. AS-to-C: Access Token . . . . . . . . . . . . . . . . . . 14 76 3.2.1. Client Credential Claim . . . . . . . . . . . . . . . 19 77 4. Client-RS Communication . . . . . . . . . . . . . . . . . . . 20 78 4.1. C-to-RS POST to authz-info Endpoint . . . . . . . . . . . 21 79 4.2. RS-to-C: 2.01 (Created) . . . . . . . . . . . . . . . . . 21 80 4.3. OSCORE Setup - Client Side . . . . . . . . . . . . . . . 22 81 4.4. OSCORE Setup - Resource Server Side . . . . . . . . . . . 23 82 4.5. Access Rights Verification . . . . . . . . . . . . . . . 25 83 5. Secure Communication with the AS . . . . . . . . . . . . . . 26 84 6. Discarding the Security Context . . . . . . . . . . . . . . . 26 85 7. CBOR Mappings . . . . . . . . . . . . . . . . . . . . . . . . 27 86 8. Security Considerations . . . . . . . . . . . . . . . . . . . 27 87 9. Privacy Considerations . . . . . . . . . . . . . . . . . . . 27 88 10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 28 89 10.1. ACE Profile Registry . . . . . . . . . . . . . . . . . . 28 90 10.2. OAuth Parameters Registry . . . . . . . . . . . . . . . 28 91 10.3. OAuth Parameters CBOR Mappings Registry . . . . . . . . 29 92 10.4. CBOR Web Token Claims Registry . . . . . . . . . . . . . 30 94 11. References . . . . . . . . . . . . . . . . . . . . . . . . . 30 95 11.1. Normative References . . . . . . . . . . . . . . . . . . 30 96 11.2. Informative References . . . . . . . . . . . . . . . . . 32 97 Appendix A. Profile Requirements . . . . . . . . . . . . . . . . 33 98 Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . 34 99 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 34 101 1. Introduction 103 A number of applications rely on a group communication model, where a 104 Client can access a resource shared by multiple Resource Servers at 105 once, e.g. over IP multicast. Typical examples are switching of 106 luminaries, actuators control, and distribution of software updates. 107 Secure communication in the group can be achieved by sharing a set of 108 key material, which is typically provided upon joining the group. 110 For some instances of such applications, it may be just fine to 111 enforce access control in a straightforward and plain fashion. That 112 is, it is assumed that any Client authorized to join the group and to 113 get the group key material, is also implicitly authorized as a group 114 member to perform any action at any resource of any Server in the 115 group. An example of an application where such implicit 116 authorization might be used is a lighting scenario, where the 117 lightbulbs are the Servers, while the user account on an app on the 118 user's phone is the Client. In this case, it might be fine to not 119 require additional authorization evidence from any user account, if 120 it is acceptable that any current group member is also authorized to 121 switch on and off any light, or to check their status. 123 However, in different instances of such applications, the approach 124 above is not desirable, as different group members are intended to 125 have different access rights to resources of other group members. 126 For instance, a more fine-grained authorization approach is required 127 in the two following use cases. 129 As a first case, an application provides control of smart locks 130 acting as Servers in the group, where: a first type of Client, e.g. a 131 user account of a child, is allowed to only query the status of the 132 smart locks; whereas a second type of Client, e.g. a user account of 133 a parent, is allowed to both query and change the status of the smart 134 locks. Further similar applications concern the enforcement of 135 different sets of permissions in groups with sensor/actuator devices, 136 e.g. thermostats, acting as Servers. In some settings, some group 137 members may even be intended as servers only, hence they must be 138 prevented from acting as Clients altogether and from accessing 139 resources at other Servers. For example, in a group of lightbulbs, 140 typically none of them should be able to switch on and off other 141 lightbulbs in the group. 143 As a second case, building automation scenarios often rely on Servers 144 that, under different circumstances, enforce different level of 145 priority for processing received commands. For instance, BACnet 146 deployments consider multiple classes of Clients, e.g. a normal light 147 switch (C1) and an emergency fire panel (C2). Then, a C1 Client is 148 not allowed to override a command from a C2 Client, until the latter 149 relinquishes control at its higher priority. That is: i) only C2 150 Clients should be able to adjust the minimum required level of 151 priority on the Servers, so rightly locking out C1 Clients if needed; 152 and ii) when a Server is set to accept only high-priority commands, 153 only C2 Clients should be able to perform such commands otherwise 154 allowed also to C1 Clients. Given the different maximum authority of 155 different Clients, fine-grained access control would effectively 156 limit the execution of high- and emergency-priority commands only to 157 devices that are in fact authorized to do so. Besides, it would 158 prevent a misconfigured or compromised device from initiating a high- 159 priority command and lock out normal control. 161 Hence, in the cases discussed above, being a legitimate group member 162 and having obtained the group key material is not supposed to imply 163 any particular access rights. Thus, a more fine-grained access 164 control model has to be enforced, e.g. by using the Authentication 165 and Authorization for Constrained Environments (ACE) framework 166 [I-D.ietf-ace-oauth-authz]. That is, a Client has to first obtain 167 authorization credentials in the form of an Access Token, and post it 168 to the Resource Server(s) in the group before accessing the intended 169 resources. 171 The ACE framework delegates to separate profile documents how to 172 secure communications between the Client and the Resource Server. 173 However each of the current profiles of ACE defined in 174 [I-D.ietf-ace-oscore-profile] [I-D.ietf-ace-dtls-authorize] 175 [I-D.ietf-ace-mqtt-tls-profile] admits a single security protocol 176 that cannot be used to protect group messages sent over IP multicast. 178 This document specifies a profile of ACE, where a Client uses CoAP 179 [RFC7252] to communicate to a single Resource Server, or CoAP over IP 180 multicast [RFC7390][I-D.dijk-core-groupcomm-bis] to communicate to 181 multiple Resource Servers that are members of a group and share a 182 common set of resources. This profile uses two complementary 183 security protocols to provide secure communication between the Client 184 and the Resource Server(s). 186 That is, this document defines the use of either Object Security for 187 Constrained RESTful Environments (OSCORE) [RFC8613] or Group OSCORE 188 [I-D.ietf-core-oscore-groupcomm] to protect unicast requests 189 addressed to a single Resource Server, as well as possible responses. 190 Additionally, it defines the use of Group OSCORE to protect multicast 191 requests sent to a group of Resource Servers, as well as possible 192 individual responses. The Client and the Resource Servers need to 193 have already joined an OSCORE group, for instance by using the 194 approach defined in [I-D.ietf-ace-key-groupcomm-oscore], which is 195 also based on ACE. 197 The Client authorizes its access to the Resource Server by using an 198 Access Token, which is bound to a key (the proof-of-possession key). 199 This profile uses OSCORE to achieve proof of possession, and OSCORE 200 or Group OSCORE to achieve server authentication. Furthermore, this 201 profile provides proof of Client's membership to the correct OSCORE 202 group, by securely binding the pre-established Group OSCORE Security 203 Context to the pairwise OSCORE Security Context newly established 204 between the Client and the Resource Server. 206 OSCORE specifies how to use CBOR Object Signing and Encryption (COSE) 207 [RFC8152] to secure CoAP messages. Group OSCORE builds on OSCORE to 208 support group communication, and ensures source authentication by 209 means of digital countersignatures embedded in protected messages. 211 1.1. Terminology 213 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 214 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 215 "OPTIONAL" in this document are to be interpreted as described in BCP 216 14 [RFC2119] [RFC8174] when, and only when, they appear in all 217 capitals, as shown here. 219 Readers are expected to be familiar with the terms and concepts 220 related to the CoAP protocol [RFC7252], as well as related to the 221 protection and processing of CoAP messages through OSCORE [RFC8613], 222 also in group communication scenarios through Group OSCORE 223 [I-D.ietf-core-oscore-groupcomm]. These include the concept of Group 224 Manager, as the entity responsible for a set of groups where 225 communications among members are secured with Group OSCORE. 227 This document also refers to "pairwise OSCORE Security Context", i.e. 228 an OSCORE Security Context established between only one Client and 229 one Resource Server, and used to communicate with OSCORE [RFC8613]. 231 Readers are expected to be familiar with the terms and concepts 232 described in the ACE framework for authentication and authorization 233 [I-D.ietf-ace-oauth-authz], as well as in the OSCORE profile of ACE 234 [I-D.ietf-ace-oscore-profile]. The terminology for entities in the 235 considered architecture is defined in OAuth 2.0 [RFC6749]. In 236 particular, this includes Client (C), Resource Server (RS), and 237 Authorization Server (AS). 239 Note that, unless otherwise indicated, the term "endpoint" is used 240 here following its OAuth definition, aimed at denoting resources such 241 as /token and /introspect at the AS, and /authz-info at the RS. This 242 document does not use the CoAP definition of "endpoint", which is "An 243 entity participating in the CoAP protocol". 245 2. Protocol Overview 247 This section provides an overview on how to use the ACE framework for 248 authentication and authorization [I-D.ietf-ace-oauth-authz] to secure 249 communications between a Client and a (set of) Resource Server(s) 250 using OSCORE [RFC8613] and/or Group OSCORE 251 [I-D.ietf-core-oscore-groupcomm]. 253 An overview of the protocol flow for this profile is shown in 254 Figure 1. In the figure, it is assumed that C, RS1 and RS2 have 255 previously joined an OSCORE group with Group Identifier (gid) 256 "abcd0000", and got assigned Sender ID (sid) "0", "1" and "2" in the 257 group, respectively. It is also assumed that both RS1 and RS2 are 258 associated with the same AS. For simplicity, the figure does not 259 show the preliminary phase where C, R1 and R2 join the OSCORE group. 261 C RS1 RS2 AS 262 | [--- Resource Request --->] | | | 263 | | | | 264 | [<--- AS Information -----] | | | 265 | | | | 266 |-------- POST /token -------------------------------------------------->| 267 | (aud: RS1, sid: 0, gid: abcd0000, ... ) | | 268 | | | | 269 |<---------------------------------- Access Token + RS Information ------| 270 | | (aud: RS1, sid: 0, gid: abcd0000, ... ) | 271 |---- POST /authz-info ------>| | | 272 | (access_token, N1) | | | 273 | | | | 274 |<--- 2.01 Created (N2) ------| | | 275 | | | | 276 /Pairwise OSCORE Sec /Pairwise OSCORE Sec | | 277 Context Derivation/ Context Derivation/ | | 278 | | | | 279 |-------- POST /token -------------------------------------------------->| 280 | (aud: RS2, sid: 0, gid: abcd0000, ... ) | | 281 | | | | 282 |<---------------------------------- Access Token + RS Information ------| 283 | | (aud: RS2, sid: 0, gid: abcd0000, ... ) | 284 | | | | 285 |----- POST /authz-info ------------------->| | 286 | (access_token, N1') | | | 287 | | | | 288 |<--- 2.01 Created (N2') -------------------| | 289 | | | | 290 /Pairwise OSCORE Sec | /Pairwise OSCORE Sec | 291 Context Derivation/ | Context Derivation/ | 292 | | | | 293 |------ OSCORE Request ------->| | | 294 | ?(abcd0000, N1, N2) | | | 295 | | | | 296 |<----- OSCORE Response -------| | | 297 | | | | 298 |-- Group OSCORE Request --+-->| | | 299 | (kid: 0, gid: abcd0000) \--------------->| | 300 | | | | 301 |<--- Group OSCORE Response ---| | | 302 | (kid: 1) | | | 303 | | | | 304 |<--- Group OSCORE Response ----------------| | 305 | (kid: 2) | | | 306 | ... | | | 308 Figure 1: Protocol Overview. 310 2.1. Pre-Conditions 312 Using Group OSCORE requires both the Client and the Resource Servers 313 to have previously joined an OSCORE group. This especially includes 314 the derivation of the Group OSCORE Security Context and the 315 assignment of unique Sender IDs to use in the group. Nodes may join 316 the OSCORE group through the respective Group Manager by using the 317 approach defined in [I-D.ietf-ace-key-groupcomm-oscore], which is 318 also based on ACE. 320 As a pre-requisite for this profile, the Client has to have 321 successfully joined the OSCORE group where also the Resource Servers 322 (RSs) are members. Depending on the limited information initially 323 available, the Client may have to first discover the exact OSCORE 324 group used by the RSs for the resources of interest, e.g. by using 325 the approach defined in [I-D.tiloca-core-oscore-discovery]. 327 2.2. Access Token Retrieval 329 This profile requires that the Client retrieves an Access Token from 330 the AS for the resource(s) it wants to access on each of the RSs, 331 using the /token endpoint, as specified in Section 5.6 of 332 [I-D.ietf-ace-oauth-authz]. In a general case, it can be assumed 333 that different RSs are associated to different ASs, even if the RSs 334 are members of a same OSCORE group. 336 In the Access Token request to the AS, the Client MUST include the 337 Group Identifier of the OSCORE group and its own Sender ID in that 338 group. The AS MUST include these pieces of information in the Access 339 Token and in the Access Token response to the Client. 341 Furthermore, in the Access Token request to the AS, the Client MUST 342 also include: its own public key, associated to the private signing 343 key used in the OSCORE group; and a signature computed with such 344 private key, over a quantity uniquely related to the secure 345 communication association between the Client and the AS. Finally, 346 the AS MUST include the public key indicated by the client in the 347 Access Token. 349 To gain knowledge of the AS in charge of a resource hosted at a RS, 350 the Client MAY first send an initial Unauthorized Resource Request 351 message to that RS. Then, the RS denies the request and replies to 352 the Client by specifying the address of its AS, as defined in 353 Section 5.1 of [I-D.ietf-ace-oauth-authz]. The Access Token request 354 and response MUST be confidentiality-protected and ensure 355 authenticity. This profile RECOMMENDS the use of OSCORE between the 356 Client and the AS, but TLS [RFC5246][RFC8446] or DTLS 357 [RFC6347][I-D.ietf-tls-dtls13] MAY be used additionally or instead. 359 2.3. Access Token Posting 361 After having retrieved the Access Token from the AS, the Client 362 generates a nonce N1 and posts both the Access Token and N1 to the 363 RS, using the /authz-info endpoint and mechanisms specified in 364 Section 5.8 of [I-D.ietf-ace-oauth-authz] and Content-Format = 365 application/ace+cbor. 367 If the Access Token is valid, the RS replies to this POST request 368 with a 2.01 (Created) response with Content-Format = application/ 369 ace+cbor, which contains a nonce N2 in a CBOR map. Also, the RS sets 370 the ID Context in the pairwise OSCORE Security Context (see Section 3 371 of [RFC8613]) to the Group Identifier of the OSCORE group specified 372 in the Access Token, concatenated with N1 concatenated with N2. 374 Then, the RS derives the complete pairwise OSCORE Security Context 375 associated with the received Access Token, following Section 3.2 of 376 [RFC8613]. During the derivation process, the RS uses the ID Context 377 above, the nonces N1 and N2, and the parameters in the Access Token. 378 The derivation process uses also the Master Secret of the OSCORE 379 group, that the RS knows as a group member, as well as the Sender ID 380 of the Client in the OSCORE group, which is specified in the Access 381 Token. This ensures that the pairwise OSCORE Security Context is 382 securely bound to the Group OSCORE Security Context of the OSCORE 383 group. 385 Finally, the RS stores the association between i) the authorization 386 information from the Access Token; and ii) the Group Identifier of 387 the OSCORE group together with the Sender ID and the public key of 388 the Client in that group. 390 After having received the nonce N2, the Client sets the ID Context in 391 its pairwise OSCORE Security Context (see Section 3 of [RFC8613]) to 392 the Group Identifier of the OSCORE group concatenated with N1 393 concatenated with N2. Then, the Client derives the complete pairwise 394 OSCORE Security Context, following Section 3.2 of [RFC8613]. During 395 the derivation process, the Client uses the ID Context above, the 396 nonces N1 and N2, plus the parameters received from the AS. The 397 derivation process uses also the Master Secret of the OSCORE group, 398 that the Client knows as a group member, as well as its own Sender ID 399 in the OSCORE group. 401 When the Client communicates with the RS using the pairwise OSCORE 402 Security Context, the RS achieves proof-of-possession of the 403 credentials bound to the Access Token. Also, the RS verifies that 404 the Client is a legitimate member of the OSCORE group. 406 Finally, when the Client communicates with the RS using the Group 407 OSCORE Security Context, the RS verifies that the Client is the exact 408 group member with the same Sender ID associated to the Access Token. 409 This occurs when verifying a request protected with Group OSCORE, 410 since it embeds a countersignature computed also over the Client's 411 Sender ID included in the message. 413 2.4. Secure Communication 415 The Client can send a request protected with OSCORE to the RS. This 416 message may contain the ID Context value, i.e. the Group Identifier 417 of the OSCORE group concatenated with N1 concatenated with N2. If 418 the request is correctly verified, then the RS stores the pairwise 419 OSCORE Security Context, and uses it to protect the possible 420 response, as well as further communications with the Client, until 421 the Access Token expires. This pairwise OSCORE Security Context is 422 discarded if the same Access Token is re-used to successfully derive 423 a new pairwise OSCORE Security Context. Once the Client has received 424 a valid secure response, it does not continue to include the ID 425 Context value in following requests. 427 As discussed in Section 2 of [I-D.ietf-ace-oscore-profile], the use 428 of random nonces N1 and N2 during the exchange between the Client and 429 the RS prevents the reuse of AEAD nonces and keys with different 430 messages, in case of re-derivation of the pairwise OSCORE Security 431 Context both for Clients and Resource Servers from an old non-expired 432 Access Token, e.g. in case of reboot of either the Client or the RS. 434 Furthermore, the Client can send a request protected with Group 435 OSCORE [I-D.ietf-core-oscore-groupcomm]. This can be a unicast 436 request addressed to the RS, or a multicast request addressed to the 437 OSCORE group where the RS is also a member. To this end, the Client 438 uses the Group OSCORE Security Context already established upon 439 joining the OSCORE group, e.g. by using the approach defined in 440 [I-D.ietf-ace-key-groupcomm-oscore]. The RS may send a response back 441 to the Client, protecting it by means of the same Group OSCORE 442 Security Context. 444 3. Client-AS Communication 446 This section details the Access Token POST Request that the Client 447 sends to the /token endpoint of the AS, as well as the related Access 448 Token response. 450 Section 3.2 of [RFC8613] defines how to derive a pairwise OSCORE 451 Security Context based on a shared Master Secret and a set of other 452 parameters, established between the OSCORE client and server. 454 The Client receives these pieces of information from the AS during 455 the exchange described in this section. In particular, the proof-of- 456 possession key (pop-key) provisioned by the AS MUST be used to build 457 the Master Secret in OSCORE (see Section 4.3 and Section 4.4). 459 3.1. C-to-AS: POST to Token Endpoint 461 The Client-to-AS request is specified in Section 5.6.1 of 462 [I-D.ietf-ace-oauth-authz]. The Client MUST send this POST request 463 to the /token endpoint over a secure channel that guarantees 464 authentication, message integrity and confidentiality. 466 The POST request is formatted as the analogous Client-to-AS request 467 in the OSCORE profile of ACE (see Section 3.1 of 468 [I-D.ietf-ace-oscore-profile]), with the following additional 469 parameters that MUST be included in the payload. 471 o 'context_id', defined in Section 3.1.1 of this specification. 472 This parameter includes the Group ID of the OSCORE group that the 473 Client has previously joined and wants to use to communicate with 474 the RS. 476 o 'salt', defined in Section 3.1.2 of this specification. This 477 parameter includes the Sender ID that the Client has received in 478 the OSCORE group, whose identifier is indicated in the 479 'context_id' parameter above, upon previously joining it. That 480 is, its value is the Sender ID that the Client uses to communicate 481 in the OSCORE group, whereas it does not relate to the Sender ID 482 to be assigned for use in the pairwise OSCORE Security Context 483 with the RS. 485 o 'client_cred', defined in Section 3.1.3 of this specification. 486 This parameter includes the public key associated to the signing 487 private key that the Client uses in the OSCORE group, whose 488 identifier is indicated in the 'context_id' parameter above. 490 o 'client_cred_verify', defined in Section 3.1.4 of this 491 specification. This parameter includes a signature computed by 492 the Client, by using the private key associated to the public key 493 in the 'client_cred' parameter above. This allows the AS to 494 verify that the Client indeed owns the private key associated to 495 the public key in 'client_cred', as its alleged identity 496 credential within the OSCORE group. The information to be signed 497 MUST be the byte representation of a quantity that uniquely 498 represents the secure communication association between the Client 499 and the AS. It is RECOMMENDED that the Client considers the 500 following as information to sign. 502 * If the Client and the AS communicate over (D)TLS, the 503 information to sign is an exporter value computed as defined in 504 Section 7.5 of [RFC8446], for which a common exporter label has 505 to be agreed between the Client and the AS. 507 * If the Client and the AS communicate over OSCORE, the 508 information to sign is the output PRK of a HKDF-Extract step 509 [RFC5869], i.e. PRK = HMAC-Hash(salt, IKM). In particular, 510 'salt' takes (x1 | x2), where x1 is the ID Context of the 511 OSCORE Security Context between the Client and the AS, x2 is 512 the Sender ID of the Client in that Context, and | denotes byte 513 string concatenation. Also, 'IKM' is the OSCORE Master Secret 514 of the OSCORE Security Context between the Client and the AS. 515 The HKDF MUST be one of the HMAC-based HKDF [RFC5869] 516 algorithms defined for COSE [RFC8152]. HKDF SHA-256 is 517 mandatory to implement. 519 An example of such a request, in CBOR diagnostic notation without the 520 tag and value abbreviations is reported in Figure 2. 522 Header: POST (Code=0.02) 523 Uri-Host: "as.example.com" 524 Uri-Path: "token" 525 Content-Format: "application/ace+cbor" 526 Payload: 527 { 528 "audience" : "tempSensor4711", 529 "scope" : "read", 530 "salt" : h'00', 531 "context_id" : h'abcd0000', 532 "client_cred" : { 533 "COSE_Key" : { 534 "kty" : EC2, 535 "crv" : P-256, 536 "x" : h'd7cc072de2205bdc1537a543d53c60a6acb62eccd890c7fa 537 27c9e354089bbe13', 538 "y" : h'f95e1d4b851a2cc80fff87d8e23f22afb725d535e515d020 539 731e79a3b4e47120' 540 } 541 }, 542 "client_cred_verify" : h'...' 543 } 545 Figure 2: Example C-to-AS POST /token request for an Access Token 546 bound to a symmetric key. 548 Later on, the Client may want to update its current access rights, 549 without changing the existing pairwise OSCORE Security Context with 550 the RS. In this case, like in the OSCORE profile of ACE (see 551 Section 3.1 of [I-D.ietf-ace-oscore-profile]), the Client MUST 552 include in its POST request to the /token endpoint a req_cnf object, 553 where the 'kid' field carries the Client's identifier, that was 554 assigned by the AS as per Section 3.2. That is, the Client's 555 identifier is the value of the 'clientId' parameter in the OSCORE 556 Security Context object of the 'cnf' parameter, in the AS-to-C Access 557 Token response providing the original Access Token (see Section 3.2). 559 The AS can use this identifier to determine the shared secret for 560 preparing the proof-of-possession Access Token. Therefore, the 561 received value MUST identify a symmetric key that was previously 562 generated by the AS, as a shared secret for communications between 563 the Client and the RS. In particular, the AS MUST verify that the 564 received value identifies a proof-of-possession key and Access Token 565 that have previously been issued to the requesting Client. If that 566 is not the case, the Client-to-AS request MUST be declined with the 567 error code 'invalid_request', as defined in Section 5.6.3 of 568 [I-D.ietf-ace-oauth-authz]. 570 This POST request for updating the rights of an Access Token MUST NOT 571 include the parameters 'salt', 'context_id', 'client_cred' and 572 'client_cred_verify'. 574 An example of such a request, in CBOR diagnostic notation without the 575 tag and value abbreviations is reported in Figure 3. 577 Header: POST (Code=0.02) 578 Uri-Host: "as.example.com" 579 Uri-Path: "token" 580 Content-Format: "application/ace+cbor" 581 Payload: 582 { 583 "audience" : "tempSensor4711", 584 "scope" : "read", 585 "req_cnf" : { 586 "kid" : 'myclient' 587 } 588 } 590 Figure 3: Example C-to-AS POST /token request for updating rights to 591 an Access Token bound to a symmetric key. 593 3.1.1. 'context_id' Parameter 595 The 'context_id' parameter is an OPTIONAL parameter of the Access 596 Token request message defined in Section 5.6.1. of 597 [I-D.ietf-ace-oauth-authz]. This parameter provides a value that the 598 Client wishes to use with the RS as a hint for a security context. 599 Its exact content is profile specific. 601 3.1.2. 'salt' Parameter 603 The 'salt' parameter is an OPTIONAL parameter of the Access Token 604 request message defined in Section 5.6.1. of 605 [I-D.ietf-ace-oauth-authz]. This parameter provides a value that the 606 Client wishes to use as salt with the RS, for deriving cryptographic 607 key material. Its exact content is profile specific. 609 3.1.3. 'client_cred' Parameter 611 The 'client_cred' parameter is an OPTIONAL parameter of the Access 612 Token request message defined in Section 5.6.1. of 613 [I-D.ietf-ace-oauth-authz]. This parameter provides an asymmetric 614 key that the Client wishes to use as its own public key, but which is 615 not used as proof-of-possession key. 617 This parameter follows the syntax of the 'cnf' claim from Section 3.1 618 of [I-D.ietf-ace-cwt-proof-of-possession] when including Value Type 619 "COSE_Key" (1) and specifying an asymmetric key. Alternative Value 620 Types defined in future specifications are fine to consider if 621 indicating a non-encrypted asymmetric key. 623 3.1.4. 'client_cred_verify' Parameter 625 The 'client_cred_verify' parameter is an OPTIONAL parameter of the 626 Access Token request message defined in Section 5.6.1. of 627 [I-D.ietf-ace-oauth-authz]. This parameter provides a signature 628 computed by the Client to prove the possession of its own private 629 key. 631 3.2. AS-to-C: Access Token 633 After having verified the POST request to the /token endpoint and 634 that the Client is authorized to obtain an Access Token corresponding 635 to its Access Token request, the AS MUST verify the signature in the 636 'client_cred_verify' parameter, by using the public key specified in 637 the 'client_cred' parameter. If the verification fails, the AS 638 considers the Client request invalid. The AS does not perform this 639 operation when asked to update a previously released Access Token. 641 If all verifications are successful, the AS responds as defined in 642 Section 5.6.2 of [I-D.ietf-ace-oauth-authz]. If the Client request 643 was invalid, or not authorized, the AS returns an error response as 644 described in Section 5.6.3 of [I-D.ietf-ace-oauth-authz]. 646 The AS can signal that the use of OSCORE and Group OSCORE is REQUIRED 647 for a specific Access Token by including the 'profile' parameter with 648 the value "coap_group_oscore" in the Access Token response. This 649 means that the Client MUST use OSCORE and/or Group OSCORE towards all 650 the Resource Servers for which this Access Token is valid. 652 In particular, the Client MUST follow Section 4.3 to derive the 653 pairwise OSCORE Security Context to use for communications with the 654 RS. Additionally, the Client has already established the related 655 Group OSCORE Security Context to communicate with members of the 656 OSCORE group, upon previously joining that group. 658 Usually, it is assumed that constrained devices will be pre- 659 configured with the necessary profile, so that this kind of profile 660 negotiation can be omitted. 662 The Access Token response to the Client is analogous to the one in 663 the OSCORE profile of ACE, as described in Section 3.2 of 664 [I-D.ietf-ace-oscore-profile]. In particular, the AS provides also 665 the following additional information in the OSCORE_Security_Context 666 object, which is defined in Section 3.2.1 of 667 [I-D.ietf-ace-oscore-profile] and included in the 'cnf' parameter 668 (see Section 3.2 of [I-D.ietf-ace-oauth-params]) of the Access Token 669 response. 671 o The 'salt' field in the OSCORE_Security_Context object MUST be 672 present. The field MUST contain the value of the 'salt' parameter 673 from the Access Token request received from the Client. 675 o The 'contextId' field in the OSCORE_Security_Context object MUST 676 be present. The field MUST contain the value of the 'context_id' 677 parameter from the Access Token request received from the Client. 679 The same parameters MUST be included as metadata of the issued Access 680 Token. This profile RECOMMENDS the use of CBOR web tokens (CWT) as 681 specified in [RFC8392]. If the Access Token is a CWT, the same 682 OSCORE_Security_Context structure considered above MUST be placed in 683 the 'cnf' claim of the Access Token. 685 Furthermore, the AS MUST include also the public key of the client 686 specified in the 'client_cred' parameter of the Token Request as 687 metadata of the issued Access Token. If the Access Token is a CWT, 688 the content of the 'client_cred' parameter MUST be placed in the 689 'client_cred' claim of the Access Token, defined in Section 3.2.1 of 690 this specification. 692 As discussed in Section 3.2 of [I-D.ietf-ace-oscore-profile], 693 collisions of client identifiers may appear in the RS, in case a 694 resource is associated to multiple ASs. In such a case, the RS needs 695 to have a mechanism in place to disambiguate identifiers or mitigate 696 the effect of their collision. 698 Figure 4 shows an example of such an AS response, in CBOR diagnostic 699 notation without the tag and value abbreviations. 701 Header: Created (Code=2.01) 702 Content-Type: "application/ace+cbor" 703 Payload: 704 { 705 "access_token" : h'a5037674656d7053656e73 ...' 706 (remainder of access token omitted for brevity), 707 "profile" : "coap_group_oscore", 708 "expires_in" : 3600, 709 "cnf" : { 710 "OSCORE_Security_Context" : { 711 "alg" : "AES-CCM-16-64-128", 712 "clientId" : b64'qA', 713 "serverId" : b64'Qg', 714 "ms" : h'f9af838368e353e78888e1426bd94e6f', 715 "salt" : h'00', 716 "context_id" : h'abcd0000' 717 } 718 } 719 } 721 Figure 4: Example AS-to-C Access Token response with the Group OSCORE 722 profile. 724 Figure 5 shows an example CWT, containing the necessary OSCORE 725 parameters in the 'cnf' claim, in CBOR diagnostic notation without 726 tag and value abbreviations. 728 { 729 "aud" : "tempSensorInLivingRoom", 730 "iat" : "1360189224", 731 "exp" : "1360289224", 732 "scope" : "temperature_g firmware_p", 733 "cnf" : { 734 "OSCORE_Security_Context" : { 735 "alg" : "AES-CCM-16-64-128", 736 "clientId" : 'client', 737 "serverId" : 'server', 738 "ms" : h'f9af838368e353e78888e1426bd94e6f', 739 "salt" : h'00', 740 "context_id" : h'abcd0000' 741 }, 742 "client_cred" : { 743 "COSE_Key" : { 744 "kty" : EC2, 745 "crv" : P-256, 746 "x" : h'd7cc072de2205bdc1537a543d53c60a6acb62eccd890c7fa 747 27c9e354089bbe13', 748 "y" : h'f95e1d4b851a2cc80fff87d8e23f22afb725d535e515d020 749 731e79a3b4e47120' 750 } 751 } 752 } 754 Figure 5: Example CWT with OSCORE parameters (CBOR diagnostic 755 notation). 757 The same CWT as in Figure 5 and encoded in CBOR is shown in Figure 6, 758 using the value abbreviations defined in [I-D.ietf-ace-oauth-authz] 759 and [I-D.ietf-ace-cwt-proof-of-possession], and with 12 as value 760 abbreviation for the 'client_cred' claim. 762 NOTE: it should be checked (and in case fixed) that the values used 763 below (which are not yet registered) are the final values registered 764 in IANA. 766 A5 # map(5) 767 03 # unsigned(3) 768 76 # text(22) 769 74656D7053656E736F72496E4C6976696E67526F6F6D 770 # "tempSensorInLivingRoom" 771 06 # unsigned(6) 772 1A 5112D728 # unsigned(1360189224) 773 04 # unsigned(4) 774 1A 51145DC8 # unsigned(1360289224) 775 09 # unsigned(9) 776 78 18 # text(24) 777 74656D70657261747572655F67206669726D776172655F70 778 # "temperature_g firmware_p" 779 08 # unsigned(8) 780 A1 # map(1) 781 04 # unsigned(4) 782 A6 # map(6) 783 05 # unsigned(5) 784 0A # unsigned(10) 785 02 # unsigned(2) 786 46 # bytes(6) 787 636C69656E74 # "client" 788 03 # unsigned(3) 789 46 # bytes(6) 790 736572766572 # "server" 791 01 # unsigned(1) 792 50 # bytes(16) 793 F9AF838368E353E78888E1426BD94E6F 794 06 # unsigned(6) 795 41 # bytes(1) 796 00 797 07 # unsigned(7) 798 44 # bytes(4) 799 ABCD0000 800 0C # unsigned(12) 801 A1 # map(1) 802 01 # unsigned(1) 803 A4 # map(4) 804 01 # unsigned(1) 805 02 # unsigned(2) 806 20 # negative(0) 807 01 # unsigned(1) 808 21 # negative(1) 809 58 20 # bytes(32) 810 D7CC072DE2205BDC1537A543D53C60A6ACB62ECCD890C7FA27C9 811 E354089BBE13 812 22 # negative(2) 813 58 20 # bytes(32) 814 F95E1D4B851A2CC80FFF87D8E23F22AFB725D535E515D020731E 815 79A3B4E47120 817 Figure 6: Example CWT with OSCORE parameters. 819 If the Client has requested an update to its access rights with 820 reference to the same pairwise OSCORE Security Context, which is 821 valid and authorized, the AS MUST omit the 'cnf' parameter in the 822 Access Token response, MUST omit the 'client_cred' claim in the 823 Access Token, and MUST include the Client identifier in the 'kid' 824 field of the 'cnf' claim of the Access Token. The Client identifier 825 needs to be provisioned, in order for the RS to identify the 826 previously generated pairwise OSCORE Security Context. 828 Figure 7 shows an example of such an AS response, in CBOR diagnostic 829 notation without the tag and value abbreviations. 831 Header: Created (Code=2.01) 832 Content-Type: "application/ace+cbor" 833 Payload: 834 { 835 "access_token" : h'a5037674656d7053656e73 ...' 836 (remainder of access token omitted for brevity), 837 "profile" : "coap_group_oscore", 838 "expires_in" : 3600 839 } 841 Figure 7: Example AS-to-C Access Token response with the Group OSCORE 842 profile, for update of access rights. 844 Figure 8 shows an example CWT, containing the necessary OSCORE 845 parameters in the 'cnf' claim for update of access rights, in CBOR 846 diagnostic notation without tag and value abbreviations. 848 { 849 "aud" : "tempSensorInLivingRoom", 850 "iat" : "1360189224", 851 "exp" : "1360289224", 852 "scope" : "temperature_h", 853 "cnf" : { 854 "kid" : b64'qA' 855 } 856 } 858 Figure 8: Example CWT with OSCORE parameters for update of access 859 rights. 861 3.2.1. Client Credential Claim 863 The 'client_cred' claim provides an asymmetric key that the Client 864 owning the Access Token wishes to use as its own public key, but 865 which is not used as proof-of-possession key. 867 This parameter follows the syntax of the 'cnf' claim from Section 3.1 868 of [I-D.ietf-ace-cwt-proof-of-possession] when including Value Type 869 "COSE_Key" (1) and specifying an asymmetric key. Alternative Value 870 Types defined in future specifications are fine to consider if 871 indicating a non-encrypted asymmetric key. 873 4. Client-RS Communication 875 This section details the POST request and response to the /authz-info 876 endpoint between the Client and the RS. With respect to the 877 exchanged messages and their content, the Client and the RS perform 878 as defined in Section 4 of the OSCORE profile of ACE 879 [I-D.ietf-ace-oscore-profile]. 881 That is, the Client generates a nonce N1 and posts it to the RS, 882 together with the Access Token that includes the material provisioned 883 by the AS. Then, the RS generates a nonce N2, and derives a pairwise 884 OSCORE Security Context as described Section 3.2 of [RFC8613]. In 885 particular, it uses the two nonces established with the Client and 886 two shared secrets, together with additional pieces of information 887 specified in the Access Token. 889 The proof-of-possession required to bind the Access Token to the 890 Client is implicitly performed by generating the pairwise OSCORE 891 Security Context using the pop-key as part of the OSCORE Master 892 Secret, for both the Client and the RS. In addition, the derivation 893 of the pairwise OSCORE Security Context takes as input also 894 information related to the OSCORE group, i.e. the Master Secret and 895 Group Identifier of the group, as well as the Sender ID of the Client 896 in the group. Hence, the derived pairwise OSCORE Security Context is 897 also securely bound to the Group OSCORE Security Context of the 898 OSCORE Group. 900 Therefore, an attacker using a stolen Access Token cannot generate a 901 valid pairwise OSCORE Security Context and thus cannot prove 902 possession of the pop-key. Also, if a Client legitimately owns an 903 Access Token but has not joined the OSCORE group, that Client cannot 904 generate a valid pairwise OSCORE Security Context either, since it 905 lacks the Master Secret used in the OSCORE group. 907 Finally, a Client C1 is supposed to obtain a valid Access Token from 908 the AS, as including the public key associated to its own signing key 909 used in the OSCORE group, together with its own Sender ID in that 910 OSCORE group (see Section 3.1). This makes it possible for the RS 911 receiving an Access Token to verify with the Group Manager of that 912 OSCORE group whether such a Client has indeed that Sender ID and that 913 public key in the OSCORE group. 915 As a consequence, a different Client C2, also member of the same 916 OSCORE group, is not able to impersonate C1, by: i) getting a valid 917 Access Token, specifying the Sender ID of C1 and a different (made- 918 up) public key; ii) successfully posting the Access Token to RS; and 919 then iii) using only the pairwise OSCORE Security Context to 920 communicate with RS to legitimately perform authorized actions, while 921 blaming C1 for the consequences. 923 4.1. C-to-RS POST to authz-info Endpoint 925 The Client MUST generate a nonce N1 and post it to the /authz-info 926 endpoint of the RS together with the Access Token, as defined in 927 Section 4.1 of the OSCORE profile of ACE 928 [I-D.ietf-ace-oscore-profile]. 930 The same recommendations, considerations and behaviors defined in 931 Section 4.1 of [I-D.ietf-ace-oscore-profile] hold for this 932 specification. 934 4.2. RS-to-C: 2.01 (Created) 936 The RS MUST verify the validity of the Access Token as defined in 937 Section 4.2 of the OSCORE profile of ACE 938 [I-D.ietf-ace-oscore-profile], with the following additions. 940 o The RS checks that the OSCORE_Security_Context object in the 'cnf' 941 claim of the Access Token includes the 'salt' parameter. 943 o The RS checks that the OSCORE_Security_Context object in the 'cnf' 944 claim of the Access Token includes the 'context_id' parameter. 945 Also, the RS checks that the value of the 'context_id' parameter 946 coincides with the one of the group identifier of the OSCORE group 947 associated to the resources targeted by the scope in the Access 948 Token. 950 o The RS checks that the 'client_cred' claim is included in the 951 Access Token, unless this is intended to update and supersede an 952 active Access Token for that same Client. The RS considers the 953 content of the 'client_cred' claim (if present) as the public key 954 associated to the signing private key that the Client uses in the 955 OSCORE group, which is identified by the 'context_id' parameter 956 above. The RS MAY additionally request the Group Manager of the 957 OSCORE group for the public key of that Client, as described in 958 [I-D.ietf-ace-key-groupcomm-oscore]. In such a case, the RS MUST 959 check that the key retrieved from the Group Manager matches the 960 one retrieved from the 'client_cred' claim. 962 If any of the checks above fails, the RS MUST consider the Access 963 Token non valid, and MUST respond to the Client with an error 964 response code equivalent to the CoAP code 4.00 (Bad Request). 966 If the Access Token is valid and further checks on its content are 967 successful, the RS MUST generate a nonce N2 and include it in the 968 2.01 (Created) response to the Client, as defined in Section 4.2 of 969 the OSCORE profile of ACE [I-D.ietf-ace-oscore-profile]. 971 Further recommendations, considerations and behaviors defined in 972 Section 4.2 of [I-D.ietf-ace-oscore-profile] hold for this 973 specification. 975 4.3. OSCORE Setup - Client Side 977 Once having received the 2.01 (Created) response from the RS, 978 following the POST request to the authz-info endpoint, the Client 979 MUST extract the nonce N2 from the 'cnonce' parameter and the client 980 identifier from the 'clientId' parameter (if present) in the CBOR map 981 in the payload of the response. 983 Note that, if present in the 2.01 (Created) response, the 'clientId' 984 parameter supersedes the analogous parameter possibly provided by the 985 AS to C in Section 3.2. Also, note that this identifier is used by C 986 as Sender ID in the pairwise OSCORE Security Context to be 987 established with the RS, and is different as well as unrelated to the 988 Sender ID of C in the OSCORE group. 990 Then, the Client performs the following actions, in order to set up 991 and fully derive the pairwise OSCORE Security Context for 992 communicating with the RS. 994 o The Client MUST set the ID Context of the pairwise OSCORE Security 995 Context as the concatenation of: the Group Identifier GID of the 996 OSCORE group; the nonce N1; and the nonce N2. The concatenation 997 occurs in this order: ID Context = GID | N1 | N2, where | denotes 998 byte string concatenation. 1000 o The Client MUST set the Master Salt of the pairwise OSCORE 1001 Security Context as the concatenation of MSalt, N1, N2 and GMSalt, 1002 where: i) MSalt is the Sender ID that the Client has in the OSCORE 1003 group; while ii) GMSalt is the (optional) Master Salt in the Group 1004 OSCORE Security Context, which is known to the Client as a member 1005 of the OSCORE group. The concatenation occurs in this order: 1006 Master Salt = MSalt | N1 | N2 | GMSalt, where | denotes byte 1007 string concatenation. 1009 o The Client MUST set the Master Secret of the pairwise OSCORE 1010 Security Context to the concatenation of MSec and GMSec, where: i) 1011 MSec is the value of the 'ms' parameter in the 1012 OSCORE_Security_Context object of the 'cnf' parameter, received 1013 from the AS in Section 3.2; while ii) GMSec is the Master Secret 1014 of the Group OSCORE Security Context, which is known to the Client 1015 as a member of the OSCORE group. 1017 o The Client MUST set the Recipient ID as indicated in the 1018 corresponding parameter received from the AS in Section 3.2, i.e. 1019 to the value of the 'serverId' parameter in the 1020 OSCORE_Security_Context object of the 'cnf' parameter. 1022 o The Client MUST set the AEAD Algorithm, HKDF, and Replay Window as 1023 indicated in the corresponding parameters received from the AS in 1024 Section 3.2, if present in the OSCORE_Security_Context object of 1025 the 'cnf' parameter. In case these parameters are omitted, the 1026 default values are used as described in Section 3.2 of [RFC8613]. 1028 o The client MUST set the Sender ID as indicated in the 'clientId' 1029 parameter from the 2.01 (Created) response, if present. 1030 Otherwise, the Client MUST set the Sender ID as indicated in the 1031 response from the AS in Section 3.2, i.e. to the value of the 1032 'clientId' parameter in the OSCORE_Security_Context object of the 1033 'cnf' parameter. 1035 Finally, the client MUST derive the complete pairwise OSCORE Security 1036 Context following Section 3.2.1 of [RFC8613]. 1038 From then on, when communicating with the RS to access the resources 1039 as specified by the authorization information, the Client MUST use 1040 the newly established pairwise OSCORE Security Context or the Group 1041 OSCORE Security Context of the OSCORE Group where both the Client and 1042 the RS are members. 1044 If any of the expected parameters is missing (e.g. any of the 1045 mandatory parameters from the AS, or 'clientId' both from the AS and 1046 in the 2.01 (Created) response from the RS), the Client MUST stop the 1047 exchange, and MUST NOT derive the pairwise OSCORE Security Context. 1048 The Client MAY restart the exchange, to get the correct security 1049 material. 1051 Then, the Client uses this pairwise OSCORE Security Context to send 1052 requests to RS protected with OSCORE. In the first request sent to 1053 the RS, the Client MAY include the kid context if the application 1054 needs to, with value the ID Context, i.e. GID concatenated with N1 1055 concatenated with N2. Besides, the Client uses the Group OSCORE 1056 Security Context for protecting unicast requests to the RS, or 1057 multicast requests to the OSCORE group including also the RS. 1059 4.4. OSCORE Setup - Resource Server Side 1061 After validation of the Access Token as defined in Section 4.2 and 1062 after sending the 2.01 (Created) response, the RS performs the 1063 following actions, in order to set up and fully derive the pairwise 1064 OSCORE Security Context created to communicate with the Client. 1066 o The RS MUST set the ID Context of the pairwise OSCORE Security 1067 Context as the concatenation of: the Group Identifier GID of the 1068 OSCORE group; the nonce N1; and the nonce N2. The concatenation 1069 occurs in this order: ID Context = GID | N1 | N2, where | denotes 1070 byte string concatenation. 1072 o The RS MUST set the Master Salt of the pairwise OSCORE Security 1073 Context as the concatenation of MSalt, N1, N2 and GMSalt, where: 1074 i) MSalt is the Sender ID that the Client has in the OSCORE group, 1075 as specified in the 'salt' parameter in the 1076 OSCORE_Security_Context object of the 'cnf' claim, included in the 1077 Access Token received from the Client (see Section 4.1); while ii) 1078 GMSalt is the (optional) Master Salt in the Group OSCORE Security 1079 Context, which is known to the RS as a member of the OSCORE group. 1080 The concatenation occurs in this order: Master Salt = MSalt | N1 | 1081 N2 | GMSalt, where | denotes byte string concatenation. 1083 o The RS MUST set the Master Secret of the pairwise OSCORE Security 1084 Context to the concatenation of MSec and GMSec, where: i) MSec is 1085 the value of the 'ms' parameter in the OSCORE_Security_Context 1086 object of the 'cnf' claim, included in the Access Token received 1087 from the Client (see Section 4.1); while ii) GMSec is the Master 1088 Secret of the Group OSCORE Security Context, which is known to the 1089 RS as a member of the OSCORE group. 1091 o The RS MUST set the Sender ID of the pairwise OSCORE Security 1092 Context from the corresponding parameter received from the Client 1093 in the Access Token (see Section 4.1), i.e. to the value of the 1094 'serverId' parameter in the OSCORE_Security_Context object of the 1095 'cnf' claim. 1097 o The RS MUST set the Recipient ID of the pairwise OSCORE Security 1098 Context from either what it indicated in the 2.01 (Created) 1099 response if included (see Section 4.2 of 1100 [I-D.ietf-ace-oscore-profile]), or from the corresponding 1101 parameter received from the Client in the Access Token (see 1102 Section 4.1), i.e. to the value of the 'clientId' parameter in the 1103 OSCORE_Security_Context object of the 'cnf' claim. 1105 o The RS MUST set the AEAD Algorithm, HKDF, and Replay Window from 1106 the corresponding parameters received from the Client in the 1107 Access Token (see Section 4.1), if present in the 1108 OSCORE_Security_Context object of the 'cnf' claim. In case these 1109 parameters are omitted, the default values are used as described 1110 in Section 3.2 of [RFC8613]. 1112 Finally, the RS MUST derive the complete pairwise OSCORE Security 1113 Context following Section 3.2.1 of [RFC8613]. 1115 Once having completed the derivation above, the RS MUST associate the 1116 authorization information from the Access Token with the just 1117 established pairwise OSCORE Security Context. 1119 Furthermore, the RS MUST associate the authorization information from 1120 the Access Token with the tuple (GID, MSalt, PKey), where GID is the 1121 Group Identifier of the OSCORE Group, while MSalt and PKey are the 1122 Sender ID and the public key that the Client has in that OSCORE 1123 group, respectively. The RS MUST keep this association up-to-date 1124 over time. 1126 Then, the RS uses this pairwise OSCORE Security Context to verify 1127 requests from and send responses to the Client protected with OSCORE, 1128 when this Security Context is used. If OSCORE verification fails, 1129 error responses are used, as specified in Section 8 of [RFC8613]. 1130 Besides, the RS uses the Group OSCORE Security Context to verify 1131 (multicast) requests from and send responses to the Client protected 1132 with Group OSCORE. If Group OSCORE verification fails, error 1133 responses are used, as specified in Section 6 of 1134 [I-D.ietf-core-oscore-groupcomm]. Additionally, for every incoming 1135 request, if OSCORE or Group OSCORE verification succeeds, the 1136 verification of access rights is performed as described in 1137 Section 4.5. 1139 After the expiration of the Access Token related to a pairwise OSCORE 1140 Security Context and to a Group OSCORE Security Context, the RS MUST 1141 NOT use the pairwise OSCORE Security Context and MUST respond with an 1142 unprotected 4.01 (Unauthorized) error message. Also, if the Client 1143 uses the Group OSCORE Security Context to send a request for any 1144 resource intended for OSCORE group members and that requires an 1145 active Access Token, the RS MUST respond with a 4.01 (Unauthorized) 1146 error message protected with the Group OSCORE Security Context. 1148 4.5. Access Rights Verification 1150 The RS MUST follow the procedures defined in Section 5.8.2 of 1151 [I-D.ietf-ace-oauth-authz]. If an RS receives an OSCORE-protected 1152 request from a Client, the RS processes it according to [RFC8613]. 1153 If an RS receives a Group OSCORE-protected request from a Client, the 1154 RS processes it according to [I-D.ietf-core-oscore-groupcomm]. 1156 If the OSCORE or Group OSCORE verification succeeds, and the target 1157 resource requires authorization, the RS retrieves the authorization 1158 information from the Access Token associated to the pairwise OSCORE 1159 Security Context and to the Group OSCORE Security Context. Then, the 1160 RS MUST verify that the authorization information covers the resource 1161 and the action requested by the Client. 1163 The response code MUST be 4.01 (Unauthorized) in case the Client has 1164 not used either of the two Security Contexts associated with the 1165 Access Token, or if the RS has no valid Access Token for the Client. 1166 If the RS has an Access Token for the Client but not for the resource 1167 that was requested, the RS MUST reject the request with a 4.03 1168 (Forbidden). If the RS has an Access Token for the Client but it 1169 does not cover the action that was requested on the resource, the RS 1170 MUST reject the request with a 4.05 (Method Not Allowed). 1172 5. Secure Communication with the AS 1174 As specified in the ACE framework (Section 5.7 of 1175 [I-D.ietf-ace-oauth-authz]), the requesting entity (RS and/or Client) 1176 and the AS communicate via the /introspection or /token endpoint. 1177 The use of CoAP and OSCORE for this communication is RECOMMENDED in 1178 this profile. Other protocols (such as HTTP and DTLS or TLS) MAY be 1179 used instead. 1181 If OSCORE is used, the requesting entity and the AS are expected to 1182 have pre-established security contexts in place. How these security 1183 contexts are established is out of the scope of this profile. 1184 Furthermore the requesting entity and the AS communicate using OSCORE 1185 ([RFC8613]) through the /introspection endpoint as specified in 1186 Section 5.7 of [I-D.ietf-ace-oauth-authz], and through the /token 1187 endpoint as specified in Section 5.6 of [I-D.ietf-ace-oauth-authz]. 1189 6. Discarding the Security Context 1191 The Client and the RS MUST follow what is defined in Section 6 of 1192 [I-D.ietf-ace-oscore-profile] about discarding the pairwise OSCORE 1193 Security Context. 1195 As members of an OSCORE Group, the Client and the RS may 1196 independently leave the group or be forced to, e.g. if compromised or 1197 suspected so. Upon leaving the OSCORE group, the Client or RS also 1198 discards the Group OSCORE Security Context, which may anyway be 1199 renewed by the Group Manager through a group rekeying process (see 1200 Section 2.1 of [I-D.ietf-core-oscore-groupcomm]). 1202 The Client or RS can acquire a new Group OSCORE Security Context, by 1203 re-joining the OSCORE group, e.g. by using the approach defined in 1204 [I-D.ietf-ace-key-groupcomm-oscore]. In such a case, the Client 1205 SHOULD request a new Access Token and post it to the RS, in order to 1206 establish a new pairwise OSCORE Security Context and bind it to the 1207 Group OSCORE Security Context obtained upon re-joining the group. 1209 7. CBOR Mappings 1211 The new parameters and claims defined in this document MUST be mapped 1212 to CBOR types as specified in Figure 9, using the given integer 1213 abbreviation for the map key. 1215 /--------------------+----------+------------\ 1216 | Parameter name | CBOR Key | Value Type | 1217 |--------------------+----------+------------| 1218 | context_id | TBD1 | bstr | 1219 | salt | TBD2 | bstr | 1220 | client_cred | TBD3 | map | 1221 | client_cred_verify | TBD4 | bstr | 1222 \--------------------+----------+------------/ 1224 Figure 9: CBOR mappings for new parameters. 1226 8. Security Considerations 1228 This document specifies a profile for the Authentication and 1229 Authorization for Constrained Environments (ACE) framework 1230 [I-D.ietf-ace-oauth-authz]. Thus the general security considerations 1231 from the ACE framework also apply to this profile. 1233 This specification inherits the security considerations from the 1234 OSCORE profile of ACE [I-D.ietf-ace-oscore-profile]. Also, the 1235 general security considerations about OSCORE [RFC8613] hold for this 1236 document, as to the specific use of OSCORE according to this profile. 1238 Furthermore, the general security considerations about Group OSCORE 1239 [I-D.ietf-core-oscore-groupcomm] hold for this document, as to the 1240 specific use of Group OSCORE according to this profile. 1242 Group OSCORE is designed to secure point-to-point as well as point- 1243 to-multipoint communications, providing a secure binding between a 1244 single request and multiple corresponding responses. In particular, 1245 Group OSCORE fulfills the same security requirements of OSCORE, for 1246 group requests and responses. To ensure source authentication of 1247 messages, Group OSCORE uses digital countersignatures that group 1248 members embed in their own transmitted messages. 1250 9. Privacy Considerations 1252 This document specifies a profile for the Authentication and 1253 Authorization for Constrained Environments (ACE) framework 1254 [I-D.ietf-ace-oauth-authz]. Thus the general privacy considerations 1255 from the ACE framework also apply to this profile. 1257 As this profile uses OSCORE and Group OSCORE, the privacy 1258 considerations from [RFC8613] and [I-D.ietf-core-oscore-groupcomm] 1259 apply to this document as well. 1261 This profile also inherits the privacy considerations from the OSCORE 1262 profile of ACE [I-D.ietf-ace-oscore-profile]. 1264 10. IANA Considerations 1266 This document has the following actions for IANA. 1268 10.1. ACE Profile Registry 1270 IANA is asked to enter the following value into the "ACE Profile" 1271 Registry defined in Section 8.7 of [I-D.ietf-ace-oauth-authz]. 1273 o Profile name: coap_group_oscore 1275 o Profile Description: Profile to secure communications between 1276 constrained nodes using the Authentication and Authorization for 1277 Constrained Environments framework by: i) establishing a Pairwise 1278 OSCORE Security Context and enabling OSCORE communication between 1279 two members of an OSCORE group; ii) enabling authentication and 1280 fine-grained authorization of members of an OSCORE group, that use 1281 a pre-established Group OSCORE Security Context to communicate 1282 with Group OSCORE. 1284 o Profile ID: TBD (value between 1 and 255) 1286 o Change Controller: IESG 1288 o Specification Document(s): [[this document]] 1290 10.2. OAuth Parameters Registry 1292 IANA is asked to enter the following values into the "OAuth 1293 Parameters" Registry defined in Section 11.2 of [RFC6749]. 1295 o Name: "context_id" 1297 o Parameter Usage Location: token request 1299 o Change Controller: IESG 1301 o Reference: Section 3.1.1 of [[this document]] 1303 o Name: "salt" 1304 o Parameter Usage Location: token request 1306 o Change Controller: IESG 1308 o Reference: Section 3.1.2 of [[this document]] 1310 o Name: "client_cred" 1312 o Parameter Usage Location: token request 1314 o Change Controller: IESG 1316 o Reference: Section 3.1.3 of [[this document]] 1318 o Name: "client_cred_verify" 1320 o Parameter Usage Location: token request 1322 o Change Controller: IESG 1324 o Reference: Section 3.1.4 of [[this document]] 1326 10.3. OAuth Parameters CBOR Mappings Registry 1328 IANA is asked to enter the following values into the "OAuth 1329 Parameters CBOR Mappings" Registry defined in Section 8.9 of 1330 [I-D.ietf-ace-oauth-authz]. 1332 o Name: "context_id" 1334 o CBOR Key: TBD1 1336 o Change Controller: IESG 1338 o Reference: Section 3.1.1 of [[this document]] 1340 o Name: "salt" 1342 o CBOR Key: TBD2 1344 o Change Controller: IESG 1346 o Reference: Section 3.1.2 of [[this document]] 1348 o Name: "client_cred" 1350 o CBOR Key: TBD3 1351 o Change Controller: IESG 1353 o Reference: Section 3.1.3 of [[this document]] 1355 o Name: "client_cred_verify" 1357 o CBOR Key: TBD4 1359 o Change Controller: IESG 1361 o Reference: Section 3.1.4 of [[this document]] 1363 10.4. CBOR Web Token Claims Registry 1365 IANA is asked to enter the following values into the "CBOR Web Token 1366 Claims" Registry defined in Section 9.1 of [RFC8392]. 1368 o Claim Name: "client_cred" 1370 o Claim Description: Client Credential 1372 o JWT Claim Name: "N/A" 1374 o Claim Key: TBD5 1376 o Claim Value Type(s): map 1378 o Change Controller: IESG 1380 o Specification Document(s): Section 3.2.1 of [[this document]] 1382 11. References 1384 11.1. Normative References 1386 [I-D.dijk-core-groupcomm-bis] 1387 Dijk, E., Wang, C., and M. Tiloca, "Group Communication 1388 for the Constrained Application Protocol (CoAP)", draft- 1389 dijk-core-groupcomm-bis-01 (work in progress), July 2019. 1391 [I-D.ietf-ace-cwt-proof-of-possession] 1392 Jones, M., Seitz, L., Selander, G., Erdtman, S., and H. 1393 Tschofenig, "Proof-of-Possession Key Semantics for CBOR 1394 Web Tokens (CWTs)", draft-ietf-ace-cwt-proof-of- 1395 possession-11 (work in progress), October 2019. 1397 [I-D.ietf-ace-key-groupcomm-oscore] 1398 Tiloca, M., Park, J., and F. Palombini, "Key Management 1399 for OSCORE Groups in ACE", draft-ietf-ace-key-groupcomm- 1400 oscore-02 (work in progress), July 2019. 1402 [I-D.ietf-ace-oauth-authz] 1403 Seitz, L., Selander, G., Wahlstroem, E., Erdtman, S., and 1404 H. Tschofenig, "Authentication and Authorization for 1405 Constrained Environments (ACE) using the OAuth 2.0 1406 Framework (ACE-OAuth)", draft-ietf-ace-oauth-authz-25 1407 (work in progress), October 2019. 1409 [I-D.ietf-ace-oauth-params] 1410 Seitz, L., "Additional OAuth Parameters for Authorization 1411 in Constrained Environments (ACE)", draft-ietf-ace-oauth- 1412 params-05 (work in progress), March 2019. 1414 [I-D.ietf-ace-oscore-profile] 1415 Palombini, F., Seitz, L., Selander, G., and M. Gunnarsson, 1416 "OSCORE profile of the Authentication and Authorization 1417 for Constrained Environments Framework", draft-ietf-ace- 1418 oscore-profile-08 (work in progress), July 2019. 1420 [I-D.ietf-core-oscore-groupcomm] 1421 Tiloca, M., Selander, G., Palombini, F., and J. Park, 1422 "Group OSCORE - Secure Group Communication for CoAP", 1423 draft-ietf-core-oscore-groupcomm-05 (work in progress), 1424 July 2019. 1426 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1427 Requirement Levels", BCP 14, RFC 2119, 1428 DOI 10.17487/RFC2119, March 1997, 1429 . 1431 [RFC5869] Krawczyk, H. and P. Eronen, "HMAC-based Extract-and-Expand 1432 Key Derivation Function (HKDF)", RFC 5869, 1433 DOI 10.17487/RFC5869, May 2010, 1434 . 1436 [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", 1437 RFC 6749, DOI 10.17487/RFC6749, October 2012, 1438 . 1440 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 1441 Application Protocol (CoAP)", RFC 7252, 1442 DOI 10.17487/RFC7252, June 2014, 1443 . 1445 [RFC8152] Schaad, J., "CBOR Object Signing and Encryption (COSE)", 1446 RFC 8152, DOI 10.17487/RFC8152, July 2017, 1447 . 1449 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 1450 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 1451 May 2017, . 1453 [RFC8392] Jones, M., Wahlstroem, E., Erdtman, S., and H. Tschofenig, 1454 "CBOR Web Token (CWT)", RFC 8392, DOI 10.17487/RFC8392, 1455 May 2018, . 1457 [RFC8613] Selander, G., Mattsson, J., Palombini, F., and L. Seitz, 1458 "Object Security for Constrained RESTful Environments 1459 (OSCORE)", RFC 8613, DOI 10.17487/RFC8613, July 2019, 1460 . 1462 11.2. Informative References 1464 [I-D.ietf-ace-dtls-authorize] 1465 Gerdes, S., Bergmann, O., Bormann, C., Selander, G., and 1466 L. Seitz, "Datagram Transport Layer Security (DTLS) 1467 Profile for Authentication and Authorization for 1468 Constrained Environments (ACE)", draft-ietf-ace-dtls- 1469 authorize-08 (work in progress), April 2019. 1471 [I-D.ietf-ace-mqtt-tls-profile] 1472 Sengul, C., Kirby, A., and P. Fremantle, "MQTT-TLS profile 1473 of ACE", draft-ietf-ace-mqtt-tls-profile-02 (work in 1474 progress), November 2019. 1476 [I-D.ietf-tls-dtls13] 1477 Rescorla, E., Tschofenig, H., and N. Modadugu, "The 1478 Datagram Transport Layer Security (DTLS) Protocol Version 1479 1.3", draft-ietf-tls-dtls13-33 (work in progress), October 1480 2019. 1482 [I-D.tiloca-core-oscore-discovery] 1483 Tiloca, M., Amsuess, C., and P. Stok, "Discovery of OSCORE 1484 Groups with the CoRE Resource Directory", draft-tiloca- 1485 core-oscore-discovery-03 (work in progress), July 2019. 1487 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 1488 (TLS) Protocol Version 1.2", RFC 5246, 1489 DOI 10.17487/RFC5246, August 2008, 1490 . 1492 [RFC6347] Rescorla, E. and N. Modadugu, "Datagram Transport Layer 1493 Security Version 1.2", RFC 6347, DOI 10.17487/RFC6347, 1494 January 2012, . 1496 [RFC7390] Rahman, A., Ed. and E. Dijk, Ed., "Group Communication for 1497 the Constrained Application Protocol (CoAP)", RFC 7390, 1498 DOI 10.17487/RFC7390, October 2014, 1499 . 1501 [RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol 1502 Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018, 1503 . 1505 Appendix A. Profile Requirements 1507 This appendix lists the specifications on this profile based on the 1508 requirements of the ACE framework, as requested in Appendix C of 1509 [I-D.ietf-ace-oauth-authz]. 1511 o (Optional) discovery process of how the Client finds the right AS 1512 for an RS it wants to send a request to: Not specified. 1514 o Communication protocol the Client and the RS must use: CoAP. 1516 o Security protocol(s) the Client and RS must use: OSCORE, i.e. 1517 establishment of a pairwise OSCORE Security Context and exchange 1518 of secure messages; and/or Group OSCORE, i.e. exchange of secure 1519 messages by using a pre-established Group OSCORE Security Context. 1521 o How the Client and the RS mutually authenticate: Implicitly by 1522 possession of a common OSCORE Security Context (when using 1523 OSCORE); and/or explicitly, by possession of a common Group OSCORE 1524 Security Context and usage of digital countersignatures (when 1525 using Group OSCORE). 1527 o Content-format of the protocol messages: "application/ace+cbor". 1529 o Proof-of-Possession protocol(s) and how to select one; which key 1530 types (e.g. symmetric/asymmetric) supported: OSCORE algorithms; 1531 pre-established symmetric keys. 1533 o profile identifier: coap_group_oscore 1535 o (Optional) how the RS talks to the AS for introspection: HTTP/CoAP 1536 (+ TLS/DTLS/OSCORE). 1538 o How the client talks to the AS for requesting a token: HTTP/CoAP 1539 (+ TLS/DTLS/OSCORE). 1541 o How/if the authz-info endpoint is protected: Security protocol 1542 above. 1544 o (Optional) other methods of token transport than the authz-info 1545 endpoint: no. 1547 Acknowledgments 1549 The authors sincerely thank Dave Robin, Jim Schaad and Goeran 1550 Selander for their comments and feedback. 1552 The work on this document has been partly supported by VINNOVA and 1553 the Celtic-Next project CRITISEC. 1555 Authors' Addresses 1557 Marco Tiloca 1558 RISE AB 1559 Isafjordsgatan 22 1560 Kista SE-16440 Stockholm 1561 Sweden 1563 Email: marco.tiloca@ri.se 1565 Rikard Hoeglund 1566 RISE AB 1567 Isafjordsgatan 22 1568 Kista SE-16440 Stockholm 1569 Sweden 1571 Email: rikard.hoglund@ri.se 1573 Ludwig Seitz 1574 RISE AB 1575 Scheelevagen 17 1576 Lund SE-22370 Lund 1577 Sweden 1579 Email: ludwig.seitz@ri.se 1580 Francesca Palombini 1581 Ericsson AB 1582 Torshamnsgatan 23 1583 Kista SE-16440 Stockholm 1584 Sweden 1586 Email: francesca.palombini@ericsson.com