idnits 2.17.1 draft-ietf-ace-oscore-profile-11.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 : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (June 18, 2020) is 1402 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 (-46) exists of draft-ietf-ace-oauth-authz-33 == Outdated reference: A later version (-16) exists of draft-ietf-ace-oauth-params-13 ** Obsolete normative reference: RFC 8152 (Obsoleted by RFC 9052, RFC 9053) -- Obsolete informational reference (is this intentional?): RFC 7231 (Obsoleted by RFC 9110) Summary: 1 error (**), 0 flaws (~~), 3 warnings (==), 3 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 ACE Working Group F. Palombini 3 Internet-Draft Ericsson AB 4 Intended status: Standards Track L. Seitz 5 Expires: December 20, 2020 Combitech 6 G. Selander 7 Ericsson AB 8 M. Gunnarsson 9 RISE 10 June 18, 2020 12 OSCORE profile of the Authentication and Authorization for Constrained 13 Environments Framework 14 draft-ietf-ace-oscore-profile-11 16 Abstract 18 This memo specifies a profile for the Authentication and 19 Authorization for Constrained Environments (ACE) framework. It 20 utilizes Object Security for Constrained RESTful Environments 21 (OSCORE) to provide communication security, server authentication, 22 and proof-of-possession for a key owned by the client and bound to an 23 OAuth 2.0 access token. 25 Status of This Memo 27 This Internet-Draft is submitted in full conformance with the 28 provisions of BCP 78 and BCP 79. 30 Internet-Drafts are working documents of the Internet Engineering 31 Task Force (IETF). Note that other groups may also distribute 32 working documents as Internet-Drafts. The list of current Internet- 33 Drafts is at https://datatracker.ietf.org/drafts/current/. 35 Internet-Drafts are draft documents valid for a maximum of six months 36 and may be updated, replaced, or obsoleted by other documents at any 37 time. It is inappropriate to use Internet-Drafts as reference 38 material or to cite them other than as "work in progress." 40 This Internet-Draft will expire on December 20, 2020. 42 Copyright Notice 44 Copyright (c) 2020 IETF Trust and the persons identified as the 45 document authors. All rights reserved. 47 This document is subject to BCP 78 and the IETF Trust's Legal 48 Provisions Relating to IETF Documents 49 (https://trustee.ietf.org/license-info) in effect on the date of 50 publication of this document. Please review these documents 51 carefully, as they describe your rights and restrictions with respect 52 to this document. Code Components extracted from this document must 53 include Simplified BSD License text as described in Section 4.e of 54 the Trust Legal Provisions and are provided without warranty as 55 described in the Simplified BSD License. 57 Table of Contents 59 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 60 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3 61 2. Protocol Overview . . . . . . . . . . . . . . . . . . . . . . 4 62 3. Client-AS Communication . . . . . . . . . . . . . . . . . . . 6 63 3.1. C-to-AS: POST to token endpoint . . . . . . . . . . . . . 6 64 3.2. AS-to-C: Access Token . . . . . . . . . . . . . . . . . . 8 65 3.2.1. OSCORE_Security_Context Object . . . . . . . . . . . 13 66 4. Client-RS Communication . . . . . . . . . . . . . . . . . . . 17 67 4.1. C-to-RS: POST to authz-info endpoint . . . . . . . . . . 18 68 4.1.1. The Nonce 1 Parameter . . . . . . . . . . . . . . . . 19 69 4.2. RS-to-C: 2.01 (Created) . . . . . . . . . . . . . . . . . 19 70 4.2.1. The Nonce 2 Parameter . . . . . . . . . . . . . . . . 21 71 4.3. OSCORE Setup . . . . . . . . . . . . . . . . . . . . . . 21 72 4.4. Access rights verification . . . . . . . . . . . . . . . 22 73 5. Secure Communication with AS . . . . . . . . . . . . . . . . 22 74 6. Discarding the Security Context . . . . . . . . . . . . . . . 23 75 7. Security Considerations . . . . . . . . . . . . . . . . . . . 24 76 8. Privacy Considerations . . . . . . . . . . . . . . . . . . . 25 77 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 25 78 9.1. ACE OAuth Profile Registry . . . . . . . . . . . . . . . 25 79 9.2. OAuth Parameters Registry . . . . . . . . . . . . . . . . 26 80 9.3. OAuth Parameters CBOR Mappings Registry . . . . . . . . . 26 81 9.4. OSCORE Security Context Parameters Registry . . . . . . . 26 82 9.5. CWT Confirmation Methods Registry . . . . . . . . . . . . 27 83 9.6. JWT Confirmation Methods Registry . . . . . . . . . . . . 28 84 9.7. Expert Review Instructions . . . . . . . . . . . . . . . 28 85 10. References . . . . . . . . . . . . . . . . . . . . . . . . . 29 86 10.1. Normative References . . . . . . . . . . . . . . . . . . 29 87 10.2. Informative References . . . . . . . . . . . . . . . . . 30 88 Appendix A. Profile Requirements . . . . . . . . . . . . . . . . 30 89 Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . 31 90 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 31 92 1. Introduction 94 This memo specifies a profile of the ACE framework 95 [I-D.ietf-ace-oauth-authz]. In this profile, a client and a resource 96 server use CoAP [RFC7252] to communicate. The client uses an access 97 token, bound to a key (the proof-of-possession key) to authorize its 98 access to the resource server. Note that this profile uses a 99 symmetric-crypto-based scheme, where the symmetric secret is used as 100 input material for keying material derivation. In order to provide 101 communication security, proof of possession, and server 102 authentication the client and resource server use Object Security for 103 Constrained RESTful Environments (OSCORE) [RFC8613]. Note that the 104 proof of possession is not done by a dedicated protocol element, but 105 rather occurs implicitly, based on knowledge of the security keying 106 material. 108 OSCORE specifies how to use CBOR Object Signing and Encryption (COSE) 109 [RFC8152] to secure CoAP messages. Note that OSCORE can be used to 110 secure CoAP messages, as well as HTTP and combinations of HTTP and 111 CoAP; a profile of ACE similar to the one described in this document, 112 with the difference of using HTTP instead of CoAP as communication 113 protocol, could be specified analogously to this one. 115 1.1. Terminology 117 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 118 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 119 "OPTIONAL" in this document are to be interpreted as described in BCP 120 14 [RFC2119] [RFC8174] when, and only when, they appear in all 121 capitals, as shown here. 123 Certain security-related terms such as "authentication", 124 "authorization", "confidentiality", "(data) integrity", "message 125 authentication code", and "verify" are taken from [RFC4949]. 127 RESTful terminology follows HTTP [RFC7231]. 129 Terminology for entities in the architecture is defined in OAuth 2.0 130 [RFC6749], such as client (C), resource server (RS), and 131 authorization server (AS). It is assumed in this document that a 132 given resource on a specific RS is associated to a unique AS. 134 Concise Data Definition Language (CDDL) [RFC8610] is used in this 135 specification. 137 Note that the term "endpoint" is used here, as in 138 [I-D.ietf-ace-oauth-authz], following its OAuth definition, which is 139 to denote resources such as token and introspect at the AS and authz- 140 info at the RS. The CoAP [RFC7252] definition, which is "An entity 141 participating in the CoAP protocol" is not used in this memo. 143 2. Protocol Overview 145 This section gives an overview on how to use the ACE Framework 146 [I-D.ietf-ace-oauth-authz] to secure the communication between a 147 client and a resource server using OSCORE [RFC8613]. The parameters 148 needed by the client to negotiate the use of this profile with the 149 authorization server, as well as OSCORE setup process, are described 150 in detail in the following sections. 152 The RS maintains a collection of OSCORE Security Contexts with 153 associated authorization information for all the clients that it is 154 communicating with. The authorization information is maintained as 155 policy that's used as input to processing requests from those 156 clients. 158 This profile requires a client to retrieve an access token from the 159 AS for the resource it wants to access on a RS, using the token 160 endpoint, as specified in section 5.6 of [I-D.ietf-ace-oauth-authz]. 161 To determine the AS in charge of a resource hosted at the RS, the 162 client C MAY send an initial Unauthorized Resource Request message to 163 the RS. The RS then denies the request and sends the address of its 164 AS back to the client C as specified in section 5.1 of 165 [I-D.ietf-ace-oauth-authz]. The access token request and response 166 MUST be confidentiality-protected and ensure authenticity. This 167 profile RECOMMENDS the use of OSCORE between client and AS, but other 168 protocols (such as TLS or DTLS) can be used as well. 170 Once the client has retrieved the access token, it generates a nonce 171 N1 and posts both the token and N1 to the RS using the authz-info 172 endpoint and mechanisms specified in section 5.8 of 173 [I-D.ietf-ace-oauth-authz] and Content-Format = application/ace+cbor. 174 Note that, as specified in the ACE framework, the authz-info endpoint 175 is not a protected resource, so there is no cryptographic protection 176 to this request. 178 If the access token is valid, the RS replies to this request with a 179 2.01 (Created) response with Content-Format = application/ace+cbor, 180 which contains a nonce N2 in a CBOR map. Moreover, the server 181 concatenates the input salt, N1, and N2 to obtain the Master Salt of 182 the OSCORE Security Context (see section 3 of [RFC8613]). The RS 183 then derives the complete Security Context associated with the 184 received token from it plus the parameters received in the access 185 token from the AS, following section 3.2 of [RFC8613]. 187 After receiving the nonce N2, the client concatenates the input salt, 188 N1 and N2 to obtain the Master Salt of the OSCORE Security Context 189 (see section 3 of [RFC8613]). The client then derives the complete 190 Security Context from the nonces plus the parameters received from 191 the AS. 193 Finally, the client sends a request protected with OSCORE to the RS. 194 If the request verifies, the server stores the complete Security 195 Context state that is ready for use in protecting messages, and uses 196 it in the response, and in further communications with the client, 197 until token expiration. This Security Context is discarded when a 198 token (whether the same or different) is used to successfully derive 199 a new Security Context for that client. 201 The use of random nonces during the exchange prevents the reuse of an 202 AEAD nonces/key pair for two different messages. This situation 203 might occur when client and RS derive a new Security Context from an 204 existing (non-expired) access token, as might occur when either party 205 has just rebooted. Instead, by using random nonces as part of the 206 Master Salt, the request to the authz-info endpoint posting the same 207 token results in a different Security Context, by OSCORE 208 construction, since even though the Master Secret, Sender ID and 209 Recipient ID are the same, the Master Salt is different (see 210 Section 3.2.1 of [RFC8613]). Therefore, the main requirement for the 211 nonces is that they have a good amount of randomness. If random 212 nonces were not used, a node re-using a non-expired old token would 213 be susceptible to on-path attackers provoking the creation of OSCORE 214 messages using old AEAD keys and nonces. 216 After the whole message exchange has taken place, the client can 217 contact the AS to request an update of its access rights, sending a 218 similar request to the token endpoint that also includes an 219 identifier so that the AS can find the correct OSCORE security 220 material it has previously shared with the Client. This specific 221 identifier, which [I-D.ietf-ace-oauth-authz] encodes as a bstr, is 222 formatted to include two OSCORE identifiers, namely ID context and 223 client ID, that are necessary to determine the correct OSCORE 224 Security Context. 226 An overview of the profile flow for the OSCORE profile is given in 227 Figure 1. 229 C RS AS 230 | [-- Resource Request --->] | | 231 | | | 232 | [<---- AS Request ------] | | 233 | Creation Hints | | 234 | | | 235 | ----- POST /token ----------------------------> | 236 | | | 237 | <---------------------------- Access Token ----- | 238 | + Access Information | 239 | ---- POST /authz-info ---> | | 240 | (access_token, N1) | | 241 | | | 242 | <--- 2.01 Created (N2) --- | | 243 | | | 244 /Sec Context /Sec Context | 245 Derivation/ Derivation/ | 246 | | | 247 | ---- OSCORE Request -----> | | 248 | | | 249 | <--- OSCORE Response ----- | | 250 | | | 251 | ---- OSCORE Request -----> | | 252 | | | 253 | <--- OSCORE Response ----- | | 254 | ... | | 256 Figure 1: Protocol Overview 258 3. Client-AS Communication 260 The following subsections describe the details of the POST request 261 and response to the token endpoint between client and AS. 262 Section 3.2 of [RFC8613] defines how to derive a Security Context 263 based on a shared master secret and a set of other parameters, 264 established between client and server, which the client receives from 265 the AS in this exchange. The proof-of-possession key (pop-key) 266 included in the response from the AS MUST be used as master secret in 267 OSCORE. 269 3.1. C-to-AS: POST to token endpoint 271 The client-to-AS request is specified in Section 5.6.1 of 272 [I-D.ietf-ace-oauth-authz]. 274 The client must send this POST request to the token endpoint over a 275 secure channel that guarantees authentication, message integrity and 276 confidentiality (see Section 5). 278 An example of such a request, with payload in CBOR diagnostic 279 notation without the tag and value abbreviations is reported in 280 Figure 2 282 Header: POST (Code=0.02) 283 Uri-Host: "as.example.com" 284 Uri-Path: "token" 285 Content-Format: "application/ace+cbor" 286 Payload: 287 { 288 "req_aud" : "tempSensor4711", 289 "scope" : "read" 290 } 292 Figure 2: Example C-to-AS POST /token request for an access token 293 bound to a symmetric key. 295 If the client wants to update its access rights without changing an 296 existing OSCORE Security Context, it MUST include in its POST request 297 to the token endpoint a req_cnf object. The req_cnf MUST include a 298 kid field carrying a bstr-wrapped CBOR array object containing the 299 client's identifier (assigned as discussed in Section 3.2) and the 300 context identifier (if assigned as discussed in Section 3.2). The 301 CBOR array is defined in Figure 3, and follows the notation of 302 [RFC8610]. These identifiers, together with other information such 303 as audience, can be used by the AS to determine the shared secret 304 bound to the proof-of-possession token and therefore MUST identify a 305 symmetric key that was previously generated by the AS as a shared 306 secret for the communication between the client and the RS. The AS 307 MUST verify that the received value identifies a proof-of-possession 308 key that has previously been issued to the requesting client. If 309 that is not the case, the Client-to-AS request MUST be declined with 310 the error code 'invalid_request' as defined in Section 5.6.3 of 311 [I-D.ietf-ace-oauth-authz]. 313 kid_arr = [ 314 clientId, 315 ?IdContext 316 ] 318 kid = bstr .cbor kid_arr 320 Figure 3: CDDL Notation of kid for Update of Access Rights 322 An example of such a request, with payload in CBOR diagnostic 323 notation without the tag and value abbreviations is reported in 324 Figure 4 326 Header: POST (Code=0.02) 327 Uri-Host: "as.example.com" 328 Uri-Path: "token" 329 Content-Format: "application/ace+cbor" 330 Payload: 331 { 332 "req_aud" : "tempSensor4711", 333 "scope" : "write", 334 "req_cnf" : { 335 "kid" : << ["myclient","contextid1"] >> 336 } 338 Figure 4: Example C-to-AS POST /token request for updating rights to 339 an access token bound to a symmetric key. 341 3.2. AS-to-C: Access Token 343 After verifying the POST request to the token endpoint and that the 344 client is authorized to obtain an access token corresponding to its 345 access token request, the AS responds as defined in section 5.6.2 of 346 [I-D.ietf-ace-oauth-authz]. If the client request was invalid, or 347 not authorized, the AS returns an error response as described in 348 section 5.6.3 of [I-D.ietf-ace-oauth-authz]. 350 The AS can signal that the use of OSCORE is REQUIRED for a specific 351 access token by including the "profile" parameter with the value 352 "coap_oscore" in the access token response. This means that the 353 client MUST use OSCORE towards all resource servers for which this 354 access token is valid, and follow Section 4.3 to derive the security 355 context to run OSCORE. Usually it is assumed that constrained 356 devices will be pre-configured with the necessary profile, so that 357 this kind of profile negotiation can be omitted. 359 Moreover, the AS MUST send the following data: 361 o a master secret 363 o a server identifier 365 o a client identifier 367 Additionally, the AS MAY send the following data, in the same 368 response. 370 o a context identifier 372 o an AEAD algorithm 374 o an HKDF algorithm 376 o a salt 378 o the OSCORE version number 380 The OSCORE_Security_Context is a CBOR map object, defined in 381 Section 3.2.1. This object is transported in the 'cnf' parameter of 382 the access token response as defined in Section 3.2 of 383 [I-D.ietf-ace-oauth-params], as the value of a field named 'osc', 384 registered in Section 9.5 and Section 9.6. The master secret MUST be 385 communicated as the 'ms' field in the 'osc' field in the 'cnf' 386 parameter of the access token response as defined in Section 3.2 of 387 [I-D.ietf-ace-oauth-params]. The AEAD algorithm may be included as 388 the 'alg' parameter in the OSCORE_Security_Context; the HKDF 389 algorithm may be included as the 'hkdf' parameter of the 390 OSCORE_Security_Context, a salt may be included as the 'salt' 391 parameter of the OSCORE_Security_Context, and the OSCORE version 392 number may be included as the 'version' parameter of the 393 OSCORE_Security_Context. 395 The same parameters MUST be included as part of the access token. 396 This profile RECOMMENDS the use of CBOR web token (CWT) as specified 397 in [RFC8392]. If the token is a CWT, the same 398 OSCORE_Security_Context structure defined above MUST be placed in the 399 'osc' field of the 'cnf' claim of this token. The access token MUST 400 be encrypted, since it will be transferred from the client to the RS 401 over an unprotected channel. 403 The AS MUST also assign an identifier to the RS (serverId), and to 404 the client (clientId), and MAY assign an identifier to the context 405 (contextId). These identifiers are then used as Sender ID, Recipient 406 ID and ID Context in the OSCORE context as described in section 3.1 407 of [RFC8613]. Applications need to consider that these identifiers 408 are sent in the clear and may reveal information about the endpoints, 409 as mentioned in section 12.8 of [RFC8613]. The pair (client 410 identifier, context identifier) MUST be unique in the set of all 411 clients for a single RS. Moreover, clientId, serverId and (when 412 assigned) contextId MUST be included in the OSCORE_Security_Context, 413 as defined in Section 3.2.1. 415 We assume in this document that a resource is associated to one 416 single AS, which makes it possible for the AS to enforce uniqueness 417 of identifiers for each client requesting a particular resource to a 418 RS. If this is not the case, collisions of identifiers may occur at 419 the RS, in which case the RS needs to have a mechanism in place to 420 disambiguate identifiers or mitigate the effect of the collisions. 422 Moreover, implementers of this specification need to be aware that if 423 other authentication mechanisms are used to set up OSCORE between the 424 same client and RS, that do not rely on AS assigning identifiers, 425 collisions may happen and need to be mitigated. A mitigation example 426 would be to use distinct namespaces of identifiers for different 427 authentication mechanisms. 429 Note that in Section 4.3 C sets the Sender ID of its Security Context 430 to the clientId value received and the Recipient ID to the serverId 431 value, and RS does the opposite. 433 Figure 5 shows an example of an AS response, with payload in CBOR 434 diagnostic notation without the tag and value abbreviations. The 435 access token has been truncated for readability. 437 Header: Created (Code=2.01) 438 Content-Type: "application/ace+cbor" 439 Payload: 440 { 441 "access_token" : h'a5037674656d7053656e73 ... 442 (remainder of access token (CWT) omitted for brevity)', 443 "profile" : "coap_oscore", 444 "expires_in" : "3600", 445 "cnf" : { 446 "osc" : { 447 "alg" : "AES-CCM-16-64-128", 448 "clientId" : h'00', 449 "serverId" : h'01', 450 "ms" : h'f9af838368e353e78888e1426bd94e6f' 451 } 452 } 453 } 455 Figure 5: Example AS-to-C Access Token response with OSCORE profile. 457 Figure 6 shows an example CWT, containing the necessary OSCORE 458 parameters in the 'cnf' claim, in CBOR diagnostic notation without 459 tag and value abbreviations. 461 { 462 "aud" : "tempSensorInLivingRoom", 463 "iat" : "1360189224", 464 "exp" : "1360289224", 465 "scope" : "temperature_g firmware_p", 466 "cnf" : { 467 "osc" : { 468 "alg" : "AES-CCM-16-64-128", 469 "clientId" : h'00', 470 "serverId" : h'01', 471 "ms" : h'f9af838368e353e78888e1426bd94e6f' 472 } 473 } 475 Figure 6: Example CWT with OSCORE parameters. 477 The same CWT token as in Figure 6, using the value abbreviations 478 defined in [I-D.ietf-ace-oauth-authz] and [RFC8747] and encoded in 479 CBOR is shown in Figure 7. 481 NOTE TO THE RFC EDITOR: before publishing, it should be checked (and 482 in case fixed) that the values used below (which are not yet 483 registered) are the final values registered in IANA. 485 A5 # map(5) 486 03 # unsigned(3) 487 76 # text(22) 488 74656D7053656E736F72496E4C6976696E67526F6F6D 489 # "tempSensorInLivingRoom" 490 06 # unsigned(6) 491 1A 5112D728 # unsigned(1360189224) 492 04 # unsigned(4) 493 1A 51145DC8 # unsigned(1360289224) 494 09 # unsigned(9) 495 78 18 # text(24) 496 74656D70657261747572655F67206669726D776172655F70 497 # "temperature_g firmware_p" 498 08 # unsigned(8) 499 A1 # map(1) 500 04 # unsigned(4) 501 A4 # map(4) 502 05 # unsigned(5) 503 0A # unsigned(10) 504 02 # unsigned(2) 505 46 # bytes(6) 506 636C69656E74 # "client" 507 03 # unsigned(3) 508 46 # bytes(6) 509 736572766572 # "server" 510 01 # unsigned(1) 511 50 # bytes(16) 512 F9AF838368E353E78888E1426BD94E6F 513 # "\xF9\xAF\x83\x83h\xE3S\xE7 514 \x88\x88\xE1Bk\xD9No" 516 Figure 7: Example CWT with OSCORE parameters. 518 If the client has requested an update to its access rights using the 519 same OSCORE Security Context, which is valid and authorized, the AS 520 MUST omit the 'cnf' parameter in the response, and MUST carry the 521 client identifier and the context identifier (if it was set and 522 included in the initial access token response by the AS) in the 'kid' 523 field in the 'cnf' parameter of the token, with the same structure 524 defined in Figure 3. These identifiers need to be included in the 525 token in order for the RS to identify the previously generated 526 Security Context. 528 Figure 8 shows an example of such an AS response, with payload in 529 CBOR diagnostic notation without the tag and value abbreviations. 530 The access token has been truncated for readability. 532 Header: Created (Code=2.01) 533 Content-Type: "application/ace+cbor" 534 Payload: 535 { 536 "access_token" : h'a5037674656d7053656e73 ... 537 (remainder of access token (CWT) omitted for brevity)', 538 "profile" : "coap_oscore", 539 "expires_in" : "3600" 540 } 542 Figure 8: Example AS-to-C Access Token response with OSCORE profile, 543 for update of access rights. 545 Figure 9 shows an example CWT, containing the necessary OSCORE 546 parameters in the 'cnf' claim for update of access rights, in CBOR 547 diagnostic notation without tag and value abbreviations. 549 { 550 "aud" : "tempSensorInLivingRoom", 551 "iat" : "1360189224", 552 "exp" : "1360289224", 553 "scope" : "temperature_h", 554 "cnf" : { 555 "kid" : h'43814100' 556 } 557 } 559 Figure 9: Example CWT with OSCORE parameters for update of access 560 rights. 562 3.2.1. OSCORE_Security_Context Object 564 An OSCORE_Security_Context is an object that represents part or all 565 of an OSCORE Security Context, i.e., the local set of information 566 elements necessary to carry out the cryptographic operations in 567 OSCORE (Section 3.1 of [RFC8613]). In particular, the 568 OSCORE_Security_Context object is defined to be serialized and 569 transported between nodes, as specified by this document, but can 570 also be used by other specifications if needed. The 571 OSCORE_Security_Context object can either be encoded as a JSON object 572 or as a CBOR map. The set of common parameters that can appear in an 573 OSCORE_Security_Context object can be found in the IANA "OSCORE 574 Security Context Parameters" registry (Section 9.4), defined for 575 extensibility, and is specified below. All parameters are optional. 576 Table 1 provides a summary of the OSCORE_Security_Context parameters 577 defined in this section. 579 +-----------+-------+----------------+--------------+---------------+ 580 | name | CBOR | CBOR type | registry | description | 581 | | label | | | | 582 +-----------+-------+----------------+--------------+---------------+ 583 | version | 0 | int | | OSCORE | 584 | | | | | Version | 585 | | | | | | 586 | ms | 1 | bstr | | OSCORE Master | 587 | | | | | Secret value | 588 | | | | | | 589 | clientId | 2 | bstr | | OSCORE Sender | 590 | | | | | ID value of | 591 | | | | | the client, | 592 | | | | | OSCORE | 593 | | | | | Recipient ID | 594 | | | | | value of the | 595 | | | | | server | 596 | | | | | | 597 | serverId | 3 | bstr | | OSCORE Sender | 598 | | | | | ID value of | 599 | | | | | the server, | 600 | | | | | OSCORE | 601 | | | | | Recipient ID | 602 | | | | | value of the | 603 | | | | | client | 604 | | | | | | 605 | hkdf | 4 | tstr / int | COSE | OSCORE HKDF | 606 | | | | Algorithm | value | 607 | | | | Values | | 608 | | | | (HMAC-based) | | 609 | | | | | | 610 | alg | 5 | tstr / int | COSE | OSCORE AEAD | 611 | | | | Algorithm | Algorithm | 612 | | | | Values | value | 613 | | | | (AEAD) | | 614 | | | | | | 615 | salt | 6 | bstr | | OSCORE Master | 616 | | | | | Salt value | 617 | | | | | | 618 | contextId | 7 | bstr | | OSCORE ID | 619 | | | | | Context value | 620 +-----------+-------+----------------+--------------+---------------+ 622 Table 1: OSCORE_Security_Context Parameters 624 version: This parameter identifies the OSCORE Version number, which 625 is an int. For more information about this field, see section 5.4 626 of [RFC8613]. In JSON, the "version" value is an integer. In 627 CBOR, the "version" type is int, and has label 0. 629 ms: This parameter identifies the OSCORE Master Secret value, which 630 is a byte string. For more information about this field, see 631 section 3.1 of [RFC8613]. In JSON, the "ms" value is a Base64 632 encoded byte string. In CBOR, the "ms" type is bstr, and has 633 label 1. 635 clientId: This parameter identifies a client identifier as a byte 636 string. This identifier is used as OSCORE Sender ID in the client 637 and OSCORE Recipient ID in the server. For more information about 638 this field, see section 3.1 of [RFC8613]. In JSON, the "clientId" 639 value is a Base64 encoded byte string. In CBOR, the "clientId" 640 type is bstr, and has label 2. 642 serverId: This parameter identifies a server identifier as a byte 643 string. This identifier is used as OSCORE Sender ID in the server 644 and OSCORE Recipient ID in the client. For more information about 645 this field, see section 3.1 of [RFC8613]. In JSON, the "serverId" 646 value is a Base64 encoded byte string. In CBOR, the "serverId" 647 type is bstr, and has label 3. 649 hkdf: This parameter identifies the OSCORE HKDF Algorithm. For more 650 information about this field, see section 3.1 of [RFC8613]. The 651 values used MUST be registered in the IANA "COSE Algorithms" 652 registry and MUST be HMAC-based HKDF algorithms. The value can 653 either be the integer or the text string value of the HMAC-based 654 HKDF algorithm in the "COSE Algorithms" registry. In JSON, the 655 "hkdf" value is a case-sensitive ASCII string or an integer. In 656 CBOR, the "hkdf" type is tstr or int, and has label 4. 658 alg: This parameter identifies the OSCORE AEAD Algorithm. For more 659 information about this field, see section 3.1 of [RFC8613] The 660 values used MUST be registered in the IANA "COSE Algorithms" 661 registry and MUST be AEAD algorithms. The value can either be the 662 integer or the text string value of the HMAC-based HKDF algorithm 663 in the "COSE Algorithms" registry. In JSON, the "alg" value is a 664 case-sensitive ASCII string or an integer. In CBOR, the "alg" 665 type is tstr or int, and has label 5. 667 salt: This parameter identifies the OSCORE Master Salt value, which 668 is a byte string. For more information about this field, see 669 section 3.1 of [RFC8613]. In JSON, the "salt" value is a Base64 670 encoded byte string. In CBOR, the "salt" type is bstr, and has 671 label 6. 673 contextId: This parameter identifies the security context as a byte 674 string. This identifier is used as OSCORE ID Context. For more 675 information about this field, see section 3.1 of [RFC8613]. In 676 JSON, the "contextID" value is a Base64 encoded byte string. In 677 CBOR, the "contextID" type is bstr, and has label 7. 679 An example of JSON OSCORE_Security_Context is given in Figure 10. 681 "osc" : { 682 "alg" : "AES-CCM-16-64-128", 683 "clientId" : b64'AA', 684 "serverId" : b64'AQ', 685 "ms" : b64'+a+Dg2jjU+eIiOFCa9lObw' 686 } 688 Figure 10: Example JSON OSCORE_Security_Context object 690 The CDDL grammar describing the CBOR OSCORE_Security_Context object 691 is: 693 OSCORE_Security_Context = { 694 ? 0 => int, ; version 695 ? 1 => bstr, ; ms 696 ? 2 => bstr, ; clientId 697 ? 3 => bstr, ; serverId 698 ? 4 => tstr / int, ; hkdf 699 ? 5 => tstr / int, ; alg 700 ? 6 => bstr, ; salt 701 ? 7 => bstr, ; contextId 702 * int / tstr => any 703 } 705 4. Client-RS Communication 707 The following subsections describe the details of the POST request 708 and response to the authz-info endpoint between client and RS. The 709 client generates a nonce N1, and posts it together with the token 710 that includes the materials (e.g., OSCORE parameters) received from 711 the AS to the RS. The RS then generates a nonce N2, and uses 712 Section 3.2 of [RFC8613] to derive a security context based on a 713 shared master secret and the two nonces, established between client 714 and server. The nonces are encoded as CBOR bstr if CBOR is used, and 715 as Base64 string if JSON is used. This security context is used to 716 protect all future communication between client and RS using OSCORE, 717 as long as the access token is valid. 719 Note that the RS and client authenticates themselves by generating 720 the shared OSCORE Security Context using the pop-key as master 721 secret. An attacker posting a valid token to the RS will not be able 722 to generate a valid OSCORE context and thus not be able to prove 723 possession of the pop-key. 725 4.1. C-to-RS: POST to authz-info endpoint 727 The client MUST generate a nonce value very unlikely to have been 728 previously used with the same input keying material. This profile 729 RECOMMENDS to use a 64-bit long random number as nonce's value. The 730 client MUST store the nonce N1 as long as the response from the RS is 731 not received and the access token related to it is still valid. The 732 client MUST use CoAP and the Authorization Information resource as 733 described in section 5.8.1 of [I-D.ietf-ace-oauth-authz] to transport 734 the token and N1 to the RS. 736 Note that the use of the payload and the Content-Format is different 737 from what described in section 5.8.1 of [I-D.ietf-ace-oauth-authz], 738 which only transports the token without any CBOR wrapping. In this 739 profile, the client MUST wrap the token and N1 in a CBOR map. The 740 client MUST use the Content-Format "application/ace+cbor" defined in 741 section 8.14 of [I-D.ietf-ace-oauth-authz]. The client MUST include 742 the access token using the "access_token" parameter and N1 using the 743 'nonce1' parameter defined in Section 4.1.1. 745 The authz-info endpoint is not protected, nor are the responses from 746 this resource. 748 The access token MUST be encrypted, since it is transferred from the 749 client to the RS over an unprotected channel. 751 Note that a client may be required to re-POST the access token in 752 order to complete a request, since an RS may delete a stored access 753 token (and associated Security Context) at any time, for example due 754 to all storage space being consumed. This situation is detected by 755 the client when it receives an AS Request Creation Hints response. 756 Reposting the same access token will result in deriving a new OSCORE 757 Security Context to be used with the RS, as different nonces will be 758 used. 760 Figure 11 shows an example of the request sent from the client to the 761 RS, with payload in CBOR diagnostic notation without the tag and 762 value abbreviations. The access token has been truncated for 763 readability. 765 Header: POST (Code=0.02) 766 Uri-Host: "rs.example.com" 767 Uri-Path: "authz-info" 768 Content-Format: "application/ace+cbor" 769 Payload: 770 { 771 "access_token": h'a5037674656d7053656e73 ... 772 (remainder of access token (CWT) omitted for brevity)', 773 "nonce1": h'018a278f7faab55a' 774 } 776 Figure 11: Example C-to-RS POST /authz-info request using CWT 778 If the client has already posted a valid token, has already 779 established a security association with the RS, and wants to update 780 its access rights, the client can do so by posting the new token 781 (retrieved from the AS and containing the update of access rights) to 782 the /authz-info endpoint. The client MUST protect the request using 783 the OSCORE Security Context established during the first token 784 exchange. The client MUST only send the access token in the payload, 785 no nonce is sent. After proper verification (see Section 4.2), the 786 RS will replace the old token with the new one, maintaining the same 787 Security Context. 789 4.1.1. The Nonce 1 Parameter 791 This parameter MUST be sent from the client to the RS, together with 792 the access token, if the ace profile used is coap_oscore. The 793 parameter is encoded as a byte string for CBOR-based interactions, 794 and as a string (Base64 encoded binary) for JSON-based interactions. 795 This parameter is registered in Section 9.2. 797 4.2. RS-to-C: 2.01 (Created) 799 The RS MUST follow the procedures defined in section 5.8.1 of 800 [I-D.ietf-ace-oauth-authz]: the RS must verify the validity of the 801 token. If the token is valid, the RS must respond to the POST 802 request with 2.01 (Created). If the token is valid but is associated 803 to claims that the RS cannot process (e.g., an unknown scope), or if 804 any of the expected parameters in the 'osc' is missing (e.g., any of 805 the mandatory parameters from the AS), or if any parameters received 806 in the 'osc' is unrecognized, the RS must respond with an error 807 response code equivalent to the CoAP code 4.00 (Bad Request). In the 808 latter two cases, the RS may provide additional information in the 809 error response, in order to clarify what went wrong. The RS may make 810 an introspection request to validate the token before responding to 811 the POST request to the authz-info endpoint. 813 Additionally, the RS MUST generate a nonce N2 very unlikely to have 814 been previously used with the same input keying material, and send it 815 within the 2.01 (Created) response. The payload of the 2.01 816 (Created) response MUST be a CBOR map containing the 'nonce2' 817 parameter defined in Section 4.2.1, set to N2. This profile 818 RECOMMENDS to use a 64-bit long random number as nonce's value. The 819 RS MUST use the Content-Format "application/ace+cbor" defined in 820 section 8.14 of [I-D.ietf-ace-oauth-authz]. 822 Figure 12 shows an example of the response sent from the RS to the 823 client, with payload in CBOR diagnostic notation without the tag and 824 value abbreviations. 826 Header: Created (Code=2.01) 827 Content-Format: "application/ace+cbor" 828 Payload: 829 { 830 "nonce2": h'25a8991cd700ac01' 831 } 833 Figure 12: Example RS-to-C 2.01 (Created) response 835 As specified in section 5.8.3 of [I-D.ietf-ace-oauth-authz], the RS 836 must notify the client with an error response with code 4.01 837 (Unauthorized) for any long running request before terminating the 838 session, when the access token expires. 840 If the RS receives the token in a OSCORE protected message, it means 841 that the client is requesting an update of access rights. The RS 842 MUST discard any nonce in the request, if any was sent. The RS MUST 843 check that the "kid" of the "cnf" parameter of the new access token 844 matches the OSCORE Security Context used to protect the message. If 845 that's the case, the RS MUST discard the old token and associate the 846 new token to the Security Context identified by "kid". The RS MUST 847 respond with a 2.01 (Created) response protected with the same 848 Security Context, with no payload. If any verification fails, the RS 849 MUST respond with a 4.01 (Unauthorized) error response. 851 As specified in section 5.8.1 of [I-D.ietf-ace-oauth-authz], when 852 receiving an updated access token with updated authorization 853 information from the client (see Section 3.1), it is recommended that 854 the RS overwrites the previous token, that is only the latest 855 authorization information in the token received by the RS is valid. 856 This simplifies for the RS to keep track of authorization information 857 for a given client. 859 4.2.1. The Nonce 2 Parameter 861 This parameter MUST be sent from the RS to the Client if the ace 862 profile used is coap_oscore. The parameter is encoded as a byte 863 string for CBOR-based interactions, and as a string (Base64 encoded 864 binary) for JSON-based interactions. This parameter is registered in 865 Section 9.2 867 4.3. OSCORE Setup 869 Once receiving the 2.01 (Created) response from the RS, following the 870 POST request to authz-info endpoint, the client MUST extract the CBOR 871 bstr nonce N2 from the 'nonce2' parameter in the CBOR map in the 872 payload of the response. Then, the client MUST set the Master Salt 873 of the Security Context created to communicate with the RS to the 874 concatenation of salt, N1, and N2, in this order: Master Salt = 875 salt | N1 | N2, where | denotes byte string concatenation, where salt 876 was received from the AS in Section 3.2, and where N1 and N2 are the 877 two nonces encoded as CBOR bstr. The client MUST set the Master 878 Secret, Sender ID and Recipient ID from the parameters received from 879 the AS in Section 3.2. The client MUST set the AEAD Algorithm, ID 880 Context, HKDF, and OSCORE Version from the parameters received from 881 the AS in Section 3.2, if present. In case these parameters are 882 omitted, the default values are used as described in sections 3.2 and 883 5.4 of [RFC8613]. After that, the client MUST derive the complete 884 Security Context following section 3.2.1 of [RFC8613]. From this 885 point on, the client MUST use this Security Context to communicate 886 with the RS when accessing the resources as specified by the 887 authorization information. 889 If any of the expected parameters is missing (e.g., any of the 890 mandatory parameters from the AS, the client MUST stop the exchange, 891 and MUST NOT derive the Security Context. The client MAY restart the 892 exchange, to get the correct security material. 894 The client then uses this Security Context to send requests to RS 895 using OSCORE. 897 After sending the 2.01 (Created) response, the RS MUST set the Master 898 Salt of the Security Context created to communicate with the client 899 to the concatenation of salt, N1, and N2, in this order: Master Salt 900 = salt | N1 | N2, where | denotes byte string concatenation, where 901 salt was received from the AS in Section 4.2, and where N1 and N2 are 902 the two nonces encoded as CBOR bstr. The RS MUST set the Master 903 Secret, Sender ID and Recipient ID from the parameters, received from 904 the AS and forwarded by the client in the access token in Section 4.1 905 after validation of the token as specified in Section 4.2. The RS 906 MUST set the AEAD Algorithm, ID Context, HKDF, and OSCORE Version 907 from the parameters received from the AS and forwarded by the client 908 in the access token in Section 4.1 after validation of the token as 909 specified in Section 4.2, if present. In case these parameters are 910 omitted, the default values are used as described in sections 3.2 and 911 5.4 of [RFC8613]. After that, the RS MUST derive the complete 912 Security Context following section 3.2.1 of [RFC8613], and MUST 913 associate this Security Context with the authorization information 914 from the access token. 916 The RS then uses this Security Context to verify requests and send 917 responses to C using OSCORE. If OSCORE verification fails, error 918 responses are used, as specified in section 8 of [RFC8613]. 919 Additionally, if OSCORE verification succeeds, the verification of 920 access rights is performed as described in section Section 4.4. The 921 RS MUST NOT use the Security Context after the related token has 922 expired, and MUST respond with a unprotected 4.01 (Unauthorized) 923 error message to requests received that correspond to a Security 924 Context with an expired token. 926 4.4. Access rights verification 928 The RS MUST follow the procedures defined in section 5.8.2 of 929 [I-D.ietf-ace-oauth-authz]: if an RS receives an OSCORE-protected 930 request from a client, then the RS processes it according to 931 [RFC8613]. If OSCORE verification succeeds, and the target resource 932 requires authorization, the RS retrieves the authorization 933 information using the access token associated to the Security 934 Context. The RS then must verify that the authorization information 935 covers the resource and the action requested. 937 The response code must be 4.01 (Unauthorized) in case the client has 938 a valid token associated with that Security Context, but the Security 939 Context has not been used before, as the proof-of-possession in this 940 profile is performed by both parties verifying that they have 941 established the same Security Context. 943 5. Secure Communication with AS 945 As specified in the ACE framework (section 5.7 of 946 [I-D.ietf-ace-oauth-authz]), the requesting entity (RS and/or client) 947 and the AS communicates via the introspection or token endpoint. The 948 use of CoAP and OSCORE ([RFC8613]) for this communication is 949 RECOMMENDED in this profile, other protocols (such as HTTP and DTLS 950 or TLS) MAY be used instead. 952 If OSCORE is used, the requesting entity and the AS are expected to 953 have pre-established security contexts in place. How these security 954 contexts are established is out of scope for this profile. 956 Furthermore the requesting entity and the AS communicate through the 957 introspection endpoint as specified in section 5.7 of 958 [I-D.ietf-ace-oauth-authz] and through the token endpoint as 959 specified in section 5.6 of [I-D.ietf-ace-oauth-authz]. 961 6. Discarding the Security Context 963 There are a number of scenarios where a client or RS needs to discard 964 the OSCORE security context, and acquire a new one. 966 The client MUST discard the current Security Context associated with 967 an RS when: 969 o the Sequence Number space ends. 971 o the access token associated with the context expires. 973 o the client receives a number of 4.01 Unauthorized responses to 974 OSCORE requests using the same Security Context. The exact number 975 needs to be specified by the application. 977 o the client receives a new nonce in the 2.01 (Created) response 978 (see Section 4.2) to a POST request to the authz-info endpoint, 979 when re-posting a (non-expired) token associated to the existing 980 context. 982 The RS MUST discard the current Security Context associated with a 983 client when: 985 o the Sequence Number space ends. 987 o the access token associated with the context expires. 989 o the client has successfully replaced the current security context 990 with a newer one by posting an access token to the unprotected 991 /authz-info endpoint at the RS, e.g., by re-posting the same 992 token, as specified in Section 4.1. 994 Whenever one more access token is successfully posted to the RS, and 995 a new Security Context is derived between the client and RS, messages 996 in transit that were protected with the previous Security Context 997 might not pass verification, as the old context is discarded. That 998 means that messages sent shortly before the client posts one more 999 access token to the RS might not successfully reach the destination. 1000 Analogously, implementations may want to cancel CoAP observations at 1001 the RS registered before the Security Context is replaced, or 1002 conversely they will need to implement a mechanism to ensure that 1003 those observation are to be protected with the newly derived Security 1004 Context. 1006 7. Security Considerations 1008 This document specifies a profile for the Authentication and 1009 Authorization for Constrained Environments (ACE) framework 1010 [I-D.ietf-ace-oauth-authz]. Thus the general security considerations 1011 from the framework also apply to this profile. 1013 Furthermore the general security considerations of OSCORE [RFC8613] 1014 also apply to this specific use of the OSCORE protocol. 1016 OSCORE is designed to secure point-to-point communication, providing 1017 a secure binding between the request and the response(s). Thus the 1018 basic OSCORE protocol is not intended for use in point-to-multipoint 1019 communication (e.g., multicast, publish-subscribe). Implementers of 1020 this profile should make sure that their usecase corresponds to the 1021 expected use of OSCORE, to prevent weakening the security assurances 1022 provided by OSCORE. 1024 Since the use of nonces in the exchange guarantees uniqueness of AEAD 1025 keys and nonces, it is REQUIRED that nonces are not reused with the 1026 same input keying material even in case of re-boots. This document 1027 RECOMMENDS the use of 64 bit random nonces. Considering the birthday 1028 paradox, the average collision for each nonce will happen after 2^32 1029 messages, which is considerably more token provisionings than 1030 expected for intended applications. If applications use something 1031 else, such as a counter, they need to guarantee that reboot and loss 1032 of state on either node does not provoke re-use. If that is not 1033 guaranteed, nodes are susceptible to re-use of AEAD (nonces, keys) 1034 pairs, especially since an on-path attacker can cause the client to 1035 use an arbitrary nonce for Security Context establishment by 1036 replaying client-to-server messages. 1038 This profile recommends that the RS maintains a single access token 1039 for a client. The use of multiple access tokens for a single client 1040 increases the strain on the resource server as it must consider every 1041 access token and calculate the actual permissions of the client. 1042 Also, tokens indicating different or disjoint permissions from each 1043 other may lead the server to enforce wrong permissions. If one of 1044 the access tokens expires earlier than others, the resulting 1045 permissions may offer insufficient protection. Developers should 1046 avoid using multiple access tokens for a client. 1048 8. Privacy Considerations 1050 This document specifies a profile for the Authentication and 1051 Authorization for Constrained Environments (ACE) framework 1052 [I-D.ietf-ace-oauth-authz]. Thus the general privacy considerations 1053 from the framework also apply to this profile. 1055 As this document uses OSCORE, thus the privacy considerations from 1056 [RFC8613] apply here as well. 1058 An unprotected response to an unauthorized request may disclose 1059 information about the resource server and/or its existing 1060 relationship with the client. It is advisable to include as little 1061 information as possible in an unencrypted response. When an OSCORE 1062 Security Context already exists between the client and the resource 1063 server, more detailed information may be included. 1065 Although encrypted, the token is sent in the clear to the authz-info 1066 endpoint, so if a client uses the same single token from multiple 1067 locations with multiple Resource Servers, it can risk being tracked 1068 by the token's value. 1070 The nonces exchanged in the request and response to the authz-info 1071 endpoint are also sent in the clear, so using random nonces is best 1072 for privacy (as opposed to, e.g., a counter, that might leak some 1073 information about the client). 1075 The AS is the party tasked of assigning the identifiers used in 1076 OSCORE, which are privacy sensitive (see Section 12.8 of [RFC8613]), 1077 and which could reveal information about the client, or may be used 1078 for correlating requests from one client. 1080 Note that some information might still leak after OSCORE is 1081 established, due to observable message sizes, the source, and the 1082 destination addresses. 1084 9. IANA Considerations 1086 Note to RFC Editor: Please replace all occurrences of "[[this 1087 specification]]" with the RFC number of this specification and delete 1088 this paragraph. 1090 9.1. ACE OAuth Profile Registry 1092 The following registration is done for the ACE OAuth Profile Registry 1093 following the procedure specified in section 8.7 of 1094 [I-D.ietf-ace-oauth-authz]: 1096 o Profile name: coap_oscore 1097 o Profile Description: Profile for using OSCORE to secure 1098 communication between constrained nodes using the Authentication 1099 and Authorization for Constrained Environments framework. 1100 o Profile ID: TBD (value between 1 and 255) 1101 o Change Controller: IESG 1102 o Specification Document(s): [[this specification]] 1104 9.2. OAuth Parameters Registry 1106 The following registrations are done for the OAuth Parameters 1107 Registry following the procedure specified in section 11.2 of 1108 [RFC6749]: 1110 o Parameter name: nonce1 1111 o Parameter usage location: token request 1112 o Change Controller: IESG 1113 o Specification Document(s): [[this specification]] 1115 o Parameter name: nonce2 1116 o Parameter usage location: token response 1117 o Change Controller: IESG 1118 o Specification Document(s): [[this specification]] 1120 9.3. OAuth Parameters CBOR Mappings Registry 1122 The following registrations are done for the OAuth Parameters CBOR 1123 Mappings Registry following the procedure specified in section 8.9 of 1124 [I-D.ietf-ace-oauth-authz]: 1126 o Name: nonce1 1127 o CBOR Key: TBD1 1128 o Value Type: bstr 1129 o Reference: [[this specification]] 1131 o Name: nonce2 1132 o CBOR Key: TBD2 1133 o Value Type: IESG 1134 o Reference: [[this specification]] 1136 9.4. OSCORE Security Context Parameters Registry 1138 It is requested that IANA create a new registry entitled "OSCORE 1139 Security Context Parameters" registry. The registry is to be created 1140 as Expert Review Required. Guidelines for the experts is provided 1141 Section 9.7. It should be noted that in addition to the expert 1142 review, some portions of the registry require a specification, 1143 potentially on standards track, be supplied as well. 1145 The columns of the registry are: 1147 name The JSON name requested (e.g., "ms"). Because a core goal of 1148 this specification is for the resulting representations to be 1149 compact, it is RECOMMENDED that the name be short. This name is 1150 case sensitive. Names may not match other registered names in a 1151 case-insensitive manner unless the Designated Experts determine 1152 that there is a compelling reason to allow an exception. The name 1153 is not used in the CBOR encoding. 1154 CBOR label The value to be used to identify this algorithm. Map key 1155 labels MUST be unique. The label can be a positive integer, a 1156 negative integer or a string. Integer values between -256 and 255 1157 and strings of length 1 are designated as Standards Track Document 1158 required. Integer values from -65536 to -257 and from 256 to 1159 65535 and strings of length 2 are designated as Specification 1160 Required. Integer values greater than 65535 and strings of length 1161 greater than 2 are designated as expert review. Integer values 1162 less than -65536 are marked as private use. 1163 CBOR Type This field contains the CBOR type for the field. 1164 registry This field denotes the registry that values may come from, 1165 if one exists. 1166 description This field contains a brief description for the field. 1167 specification This contains a pointer to the public specification 1168 for the field if one exists 1170 This registry will be initially populated by the values in Table 1. 1171 The specification column for all of these entries will be this 1172 document and [RFC8613]. 1174 9.5. CWT Confirmation Methods Registry 1176 The following registration is done for the CWT Confirmation Methods 1177 Registry following the procedure specified in section 7.2.1 of 1178 [RFC8747]: 1180 o Confirmation Method Name: "osc" 1181 o Confirmation Method Description: OSCORE_Security_Context carrying 1182 the parameters for using OSCORE per-message security with implicit 1183 key confirmation 1184 o Confirmation Key: TBD (value between 4 and 255) 1185 o Confirmation Value Type(s): map 1186 o Change Controller: IESG 1187 o Specification Document(s): Section 3.2.1 of [[this specification]] 1189 9.6. JWT Confirmation Methods Registry 1191 The following registration is done for the JWT Confirmation Methods 1192 Registry following the procedure specified in section 6.2.1 of 1193 [RFC7800]: 1195 o Confirmation Method Value: "osc" 1196 o Confirmation Method Description: OSCORE_Security_Context carrying 1197 the parameters for using OSCORE per-message security with implicit 1198 key confirmation 1199 o Change Controller: IESG 1200 o Specification Document(s): Section 3.2.1 of [[this specification]] 1202 9.7. Expert Review Instructions 1204 The IANA registry established in this document is defined to use the 1205 Expert Review registration policy. This section gives some general 1206 guidelines for what the experts should be looking for, but they are 1207 being designated as experts for a reason so they should be given 1208 substantial latitude. 1210 Expert reviewers should take into consideration the following points: 1212 o Point squatting should be discouraged. Reviewers are encouraged 1213 to get sufficient information for registration requests to ensure 1214 that the usage is not going to duplicate one that is already 1215 registered and that the point is likely to be used in deployments. 1216 The zones tagged as private use are intended for testing purposes 1217 and closed environments. Code points in other ranges should not 1218 be assigned for testing. 1219 o Specifications are required for the standards track range of point 1220 assignment. Specifications should exist for specification 1221 required ranges, but early assignment before a specification is 1222 available is considered to be permissible. Specifications are 1223 needed for the first-come, first-serve range if they are expected 1224 to be used outside of closed environments in an interoperable way. 1225 When specifications are not provided, the description provided 1226 needs to have sufficient information to identify what the point is 1227 being used for. 1228 o Experts should take into account the expected usage of fields when 1229 approving point assignment. The fact that there is a range for 1230 standards track documents does not mean that a standards track 1231 document cannot have points assigned outside of that range. The 1232 length of the encoded value should be weighed against how many 1233 code points of that length are left, the size of device it will be 1234 used on, and the number of code points left that encode to that 1235 size. 1237 10. References 1239 10.1. Normative References 1241 [I-D.ietf-ace-oauth-authz] 1242 Seitz, L., Selander, G., Wahlstroem, E., Erdtman, S., and 1243 H. Tschofenig, "Authentication and Authorization for 1244 Constrained Environments (ACE) using the OAuth 2.0 1245 Framework (ACE-OAuth)", draft-ietf-ace-oauth-authz-33 1246 (work in progress), February 2020. 1248 [I-D.ietf-ace-oauth-params] 1249 Seitz, L., "Additional OAuth Parameters for Authorization 1250 in Constrained Environments (ACE)", draft-ietf-ace-oauth- 1251 params-13 (work in progress), April 2020. 1253 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1254 Requirement Levels", BCP 14, RFC 2119, 1255 DOI 10.17487/RFC2119, March 1997, 1256 . 1258 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 1259 Application Protocol (CoAP)", RFC 7252, 1260 DOI 10.17487/RFC7252, June 2014, 1261 . 1263 [RFC8152] Schaad, J., "CBOR Object Signing and Encryption (COSE)", 1264 RFC 8152, DOI 10.17487/RFC8152, July 2017, 1265 . 1267 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 1268 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 1269 May 2017, . 1271 [RFC8392] Jones, M., Wahlstroem, E., Erdtman, S., and H. Tschofenig, 1272 "CBOR Web Token (CWT)", RFC 8392, DOI 10.17487/RFC8392, 1273 May 2018, . 1275 [RFC8610] Birkholz, H., Vigano, C., and C. Bormann, "Concise Data 1276 Definition Language (CDDL): A Notational Convention to 1277 Express Concise Binary Object Representation (CBOR) and 1278 JSON Data Structures", RFC 8610, DOI 10.17487/RFC8610, 1279 June 2019, . 1281 [RFC8613] Selander, G., Mattsson, J., Palombini, F., and L. Seitz, 1282 "Object Security for Constrained RESTful Environments 1283 (OSCORE)", RFC 8613, DOI 10.17487/RFC8613, July 2019, 1284 . 1286 10.2. Informative References 1288 [RFC4949] Shirey, R., "Internet Security Glossary, Version 2", 1289 FYI 36, RFC 4949, DOI 10.17487/RFC4949, August 2007, 1290 . 1292 [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", 1293 RFC 6749, DOI 10.17487/RFC6749, October 2012, 1294 . 1296 [RFC7231] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 1297 Protocol (HTTP/1.1): Semantics and Content", RFC 7231, 1298 DOI 10.17487/RFC7231, June 2014, 1299 . 1301 [RFC7800] Jones, M., Bradley, J., and H. Tschofenig, "Proof-of- 1302 Possession Key Semantics for JSON Web Tokens (JWTs)", 1303 RFC 7800, DOI 10.17487/RFC7800, April 2016, 1304 . 1306 [RFC8747] Jones, M., Seitz, L., Selander, G., Erdtman, S., and H. 1307 Tschofenig, "Proof-of-Possession Key Semantics for CBOR 1308 Web Tokens (CWTs)", RFC 8747, DOI 10.17487/RFC8747, March 1309 2020, . 1311 Appendix A. Profile Requirements 1313 This section lists the specifications on this profile based on the 1314 requirements on the framework, as requested in Appendix C of 1315 [I-D.ietf-ace-oauth-authz]. 1317 o Optionally define new methods for the client to discover the 1318 necessary permissions and AS for accessing a resource, different 1319 from the one proposed in: Not specified 1320 o Optionally specify new grant types: Not specified 1321 o Optionally define the use of client certificates as client 1322 credential type: Not specified 1323 o Specify the communication protocol the client and RS the must use: 1324 CoAP 1325 o Specify the security protocol the client and RS must use to 1326 protect their communication: OSCORE 1327 o Specify how the client and the RS mutually authenticate: 1328 Implicitly by possession of a common OSCORE security context 1329 o Specify the proof-of-possession protocol(s) and how to select one, 1330 if several are available. Also specify which key types (e.g., 1331 symmetric/asymmetric) are supported by a specific proof-of- 1332 possession protocol: OSCORE algorithms; pre-established symmetric 1333 keys 1335 o Specify a unique ace_profile identifier: coap_oscore 1336 o If introspection is supported: Specify the communication and 1337 security protocol for introspection: HTTP/CoAP (+ TLS/DTLS/OSCORE) 1338 o Specify the communication and security protocol for interactions 1339 between client and AS: HTTP/CoAP (+ TLS/DTLS/OSCORE) 1340 o Specify how/if the authz-info endpoint is protected, including how 1341 error responses are protected: Not protected. 1342 o Optionally define other methods of token transport than the authz- 1343 info endpoint: Not defined 1345 Acknowledgments 1347 The authors wish to thank Jim Schaad and Marco Tiloca for the input 1348 on this memo. Special thanks to the responsible area director 1349 Benjamin Kaduk for his extensive review and contributed text. Ludwig 1350 Seitz worked on this document as part of the CelticNext projects 1351 CyberWI, and CRITISEC with funding from Vinnova. 1353 Authors' Addresses 1355 Francesca Palombini 1356 Ericsson AB 1358 Email: francesca.palombini@ericsson.com 1360 Ludwig Seitz 1361 Combitech 1362 Djaeknegatan 31 1363 Malmoe 211 35 1364 Sweden 1366 Email: ludwig.seitz@combitech.se 1368 Goeran Selander 1369 Ericsson AB 1371 Email: goran.selander@ericsson.com 1373 Martin Gunnarsson 1374 RISE 1375 Scheelevagen 17 1376 Lund 22370 1377 Sweden 1379 Email: martin.gunnarsson@ri.se