RFC 9203
The Object Security for Constrained RESTful Environments (OSCORE) Profile of the Authentication and Authorization for Constrained Environments (ACE) Framework
RFC 9203: The OSCORE Profile of ACE Framework 🎀
okay bestie, this one is the OSCORE profile of the ACE framework, and it's giving secure IoT vibes 🦋 It was written by F. Palombini (Ericsson AB), L. Seitz (Combitech), G. Selander (Ericsson AB), and M. Gunnarsson (RISE). It's a Standards Track document, so it's a real Internet Standard and not just someone's opinion 💅 It's dated August 2022, it's ISSN 2070-1721, and it doesn't list anything it obsoletes or updates. The full title is The Object Security for Constrained RESTful Environments (OSCORE) Profile of the Authentication and Authorization for Constrained Environments (ACE) Framework.
Abstract ✨
okay so this doc specifies a profile for the Authentication and Authorization for Constrained Environments (ACE) framework 🌸 It uses Object Security for Constrained RESTful Environments (OSCORE) to give communication security and proof-of-possession for a key that the client owns and that's bound to an OAuth 2.0 access token 🔐 literally the main character of the whole setup 👑
Status of This Memo 📜
This is an Internet Standards Track document. ✨
This document is a product of the Internet Engineering Task Force (IETF) 🌈 It represents the consensus of the IETF community. It went through public review and got approved for publication by the Internet Engineering Steering Group (IESG). If you want more info on Internet Standards, check out Section 2 of RFC 7841 🧚
Info about the current status of this document, any errata, and how to give feedback on it lives at https://www.rfc-editor.org/info/rfc9203 💜
Copyright Notice ©️
Copyright (c) 2022 IETF Trust and the persons identified as the document authors. All rights reserved. 🎀
This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) as they stand on the date this document was published. Please actually read these, ngl, because they explain your rights and restrictions with respect to this document 🙈 Code Components pulled out of this document have to include the Revised BSD License text, as described in Section 4.e of the Trust Legal Provisions. They're also provided without warranty, as described in the Revised BSD License 💅
Table of Contents 🗂️
1. Introduction
1.1. Terminology
2. Protocol Overview
3. Client-AS Communication
3.1. C-to-AS: POST to Token Endpoint
3.2. AS-to-C: Access Token
3.2.1. The OSCORE_Input_Material
4. Client-RS Communication
4.1. C-to-RS: POST to authz-info Endpoint
4.1.1. The Nonce 1 Parameter
4.1.2. The ace_client_recipientid Parameter
4.2. RS-to-C: 2.01 (Created)
4.2.1. The Nonce 2 Parameter
4.2.2. The ace_server_recipientid Parameter
4.3. OSCORE Setup
4.4. Access Rights Verification
5. Secure Communication with AS
6. Discarding the Security Context
7. Security Considerations
8. Privacy Considerations
9. IANA Considerations
9.1. ACE Profile Registry
9.2. OAuth Parameters Registry
9.3. OAuth Parameters CBOR Mappings Registry
9.4. OSCORE Security Context Parameters Registry
9.5. CWT Confirmation Methods Registry
9.6. JWT Confirmation Methods Registry
9.7. Expert Review Instructions
10. References
10.1. Normative References
10.2. Informative References
Appendix A. Profile Requirements
Acknowledgments
Authors' Addresses1. Introduction 🌸
okay so this document specifies the coap_oscore profile of the ACE framework [RFC9200] 💖 In this profile, a client (C) and a resource server (RS) talk to each other using the Constrained Application Protocol (CoAP) [RFC7252] ✨ The client uses an access token, which is bound to a symmetric key (the proof-of-possession (PoP) key), to get access to the resource server 🔐
Note that this profile uses a symmetric-crypto-based scheme, where the symmetric secret is used as input material for keying material derivation. It's giving efficiency 💅 To provide communication security and PoP, the client and resource server use Object Security for Constrained RESTful Environments (OSCORE) as defined in [RFC8613] 🦋 Note that the PoP is not achieved through a dedicated protocol element. Instead, it happens after the first message exchange using OSCORE, which is lowkey so clever 🧚
OSCORE specifies how to use CBOR Object Signing and Encryption (COSE) [RFC9052] [RFC9053] to secure CoAP messages 🎀 Note that OSCORE can secure CoAP messages, as well as HTTP and combinations of HTTP and CoAP. A profile of ACE that's similar to this one, but uses HTTP instead of CoAP as the communication protocol, could be specified in the same way. Bestie, that's a whole future vibe 🌈
1.1. Terminology 📖
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here. 🫶
Certain security-related terms, such as "authentication", "authorization", "confidentiality", "(data) integrity", "Message Authentication Code (MAC)", "Hash-based Message Authentication Code (HMAC)", and "verify", are taken from [RFC4949] 🔥
RESTful terminology follows HTTP [RFC9110] 🍓
Readers are expected to already know the terms and concepts defined in OSCORE [RFC8613], like "security context" and "Recipient ID" 🧚
Terminology for entities in the architecture is defined in OAuth 2.0 [RFC6749], like client (C), resource server (RS), and authorization server (AS). In this document, it's assumed that a given resource on a specific RS is associated with a unique AS 👑
Concise Binary Object Representation (CBOR) [RFC8949] and Concise Data Definition Language (CDDL) [RFC8610] are used in this document. The CDDL predefined type names, especially "bstr" for CBOR byte strings and "tstr" for CBOR text strings, get used a LOT here 💀
Quick note on "endpoint": it's used the way [RFC9200] uses it, following its OAuth definition, which means resources like token and introspect at the AS, and authz-info at the RS. The CoAP definition, which is "[a]n entity participating in the CoAP protocol" [RFC7252], is not used in this document 🙈
Throughout this document, examples for CBOR data items are written in CBOR extended diagnostic notation, as defined in Section 8 of [RFC8949] and Appendix G of [RFC8610] ("diagnostic notation"), unless noted otherwise. We often add diagnostic notation comments to give a textual version of the numeric parameter names and values 🌈
In this document, "base64-encoded" means URL-Safe base64 encoding (see Section 5 of [RFC4648]) without padding ✨
Part 1 of 8 done, bestie! 💖 More parts coming soon 🦋
2. Protocol Overview ✨
okay so this section is the big picture, bestie 🦋 It shows how to use the ACE Framework [RFC9200] to lock down the chat between a client and a resource server using OSCORE [RFC8613]. The parameters the client needs to agree on this profile with the AS, plus the whole OSCORE setup process, get the full breakdown in the sections that follow 💅
The RS keeps a whole collection of OSCORE security contexts, with authorization info attached for every client it's talking to 🫶 That info is stored as policy, and the RS uses that policy as input when it processes requests from those clients. Main character energy, honestly 👑
This profile needs a client to grab an access token from the AS for whatever resource it wants on an RS. It does this by sending an access token request to the token endpoint, as specified in Section 5.8 of [RFC9200]. The access token request and response MUST be confidentiality protected and ensure authenticity 🔐 Using OSCORE between the client and AS is RECOMMENDED in this profile, since it means the client has fewer libraries to support 🧚 Other protocols that meet the security requirements in Section 5 of [RFC9200] MAY be used instead, like TLS [RFC8446] or DTLS [RFC9147] 🌈
Once the client has the access token, it makes a nonce N1, as defined in this document (see Section 4.1.1) 🎀 It also generates its own OSCORE Recipient ID, ID1 (see Section 3.1 of [RFC8613]), for use with the keying material tied to the RS. Then it posts the token, N1, and its Recipient ID to the RS at the authz-info endpoint, using the mechanisms in Section 5.8 of [RFC9200] and Content-Format = application/ace+cbor ✨ Heads up: the communication with the authz-info endpoint isn't protected, except when you're updating access rights 🙈
If the access token is valid, the RS replies with a 2.01 (Created) response that has Content-Format = application/ace+cbor. That reply carries a nonce N2 and the RS's newly generated OSCORE Recipient ID, ID2, for use with the keying material tied to the client 🍓 The server then concatenates the input salt from the token, N1, and N2 to get the Master Salt of the OSCORE security context (see Section 3 of [RFC8613]). From that Master Salt, the RS derives the full security context for the token. The inputs are the OSCORE Recipient ID the client generated (which becomes its OSCORE Sender ID), its own OSCORE Recipient ID, and the parameters it got from the AS in the access token, all following Section 3.2 of [RFC8613] 💖
The client does the same kind of thing once it gets N2. It concatenates the input salt, N1, and N2 to get the Master Salt of the OSCORE security context. Then it derives the complete security context from that Master Salt, the OSCORE Recipient ID the RS generated (which becomes its OSCORE Sender ID), its own OSCORE Recipient ID, and the parameters it got from the AS 🦋
Finally, the client starts talking to the RS by sending a request protected with OSCORE 💌 If the server verifies the request successfully, it stores the complete security context, which is now ready to protect messages. It uses that context in the response and in further communication with the client, until the token gets deleted (for example, because it expired) 🫧 That security context gets thrown out when a token (the same one or a different one) successfully derives a new security context for that client 🗑️
Here's why N1 and N2 matter so much 🔥 Using them during the exchange stops an AEAD nonce/key pair from being reused for two different messages. Reuse could happen when the client and RS derive a new security context from an existing, non-expired access token, which might happen when either party has just rebooted. That could wreck both confidentiality and integrity, and nobody wants that bestie 😭 By putting the exchanged nonces N1 and N2 into the Master Salt, posting the same token to the authz-info endpoint gives a different security context, thanks to how OSCORE is built. Even though the Master Secret, Sender ID, and Recipient ID stay the same, the Master Salt is different (see Section 3.2.1 of [RFC8613]). If the nonces were reused, a node reusing an old, non-expired token would be open to on-path attackers who could trigger the creation of an OSCORE message using an old AEAD key and nonce 🚨
Warning: if the nonces ever got reused, an on-path attacker could push a node into making an OSCORE message with an old AEAD key and nonce. Keep N1 and N2 fresh, always 💀
After the whole message exchange is done, the client can ask the AS for an update to its access rights 🧚 It sends a similar request to the token endpoint, but this one also includes an identifier so the AS can find the right OSCORE Input Material it shared with the client earlier. That identifier is a byte string that the AS assigns so it's unique among its OSCORE Input Materials. It isn't used as input material for deriving the full OSCORE security context, so don't mix those up 🙅♀️
Here's the profile flow for the OSCORE profile in Figure 1. The message names match [RFC9200] whenever they apply 🎀
C RS AS
| | |
| ----- POST /token ----------------------------> |
| | |
| <---------------------------- Access Token ----- |
| + Access Information |
| ---- POST /authz-info ---> | |
| (access_token, N1, ID1) | |
| | |
| <- 2.01 Created (N2, ID2)- | |
| | |
/Sec Context /Sec Context |
derivation/ derivation/ |
| | |
| ---- OSCORE Request -----> | |
| | |
| /proof-of-possession |
| Sec Context storage/ |
| | |
| <--- OSCORE Response ----- | |
| | |
/proof-of-possession | |
Sec Context storage/ | |
| | |
| ---- OSCORE Request -----> | |
| | |
| <--- OSCORE Response ----- | |
| | |
| ... | |Figure 1: Protocol Overview
3. Client-AS Communication 🌸
The following subsections go through the details of the POST request and response to the token endpoint between the client and AS 💜 Section 3.2 of [RFC8613] explains how to derive a security context from a shared Master Secret and a set of other parameters. Those are set up between the client and server, and the client gets them from the AS in this exchange. The PoP key included in the response from the AS MUST be used as a Master Secret in OSCORE 🔑
3.1. C-to-AS: POST to Token Endpoint ✨
The client-to-AS request is specified in Section 5.8.1 of [RFC9200] 📮
The client must send this POST request to the token endpoint over a secure channel that guarantees authentication, message integrity, and confidentiality (see Section 5) 🔒
Here's an example of that request in Figure 2 💅
Header: POST (Code=0.02)
Uri-Host: "as.example.com"
Uri-Path: "token"
Content-Format: application/ace+cbor
Payload:
{
/ audience / 5 : "tempSensor4711",
/ scope / 9 : "read"
}Figure 2: Example C-to-AS POST /token Request for an Access Token Bound to a Symmetric Key
If the client wants to update its access rights without changing an existing OSCORE security context, it MUST include a req_cnf object in its POST request to the token endpoint. The kid field carries a CBOR byte string holding the OSCORE Input Material identifier (assigned as discussed in Section 3.2) 🦋 That identifier, together with other info like audience (see Section 5.8.1 of [RFC9200]), lets the AS work out the shared secret bound to the proof-of-possession token. So it MUST identify a symmetric key that the AS previously generated as a shared secret for the communication between the client and the RS. The AS MUST verify that the received value identifies a proof-of-possession key that was previously issued to the requesting client. If that isn't the case, the client-to-AS request MUST be declined with the error code invalid_request, as defined in Section 5.8.3 of [RFC9200] 🚫
Here's an example of that request in Figure 3 🌈
Header: POST (Code=0.02)
Uri-Host: "as.example.com"
Uri-Path: "token"
Content-Format: application/ace+cbor
Payload:
{
/ audience / 5 : "tempSensor4711",
/ scope / 9 : "write",
/ req_cnf / 4 : {
/ kid / 3 : h'01'
}
}Figure 3: Example C-to-AS POST /token Request for Updating Rights to an Access Token Bound to a Symmetric Key
3.2. AS-to-C: Access Token 🎀
okay so once the AS gets that POST to the token endpoint, it checks that the request is legit and that the client is actually allowed to get a token for what it asked for 💅. If everything checks out, it replies the way Section 5.8.2 of [RFC9200] describes. If the request was invalid or the client isn't authorized, the AS sends back an error response as described in Section 5.8.3 of [RFC9200] 🙈
the AS can flag that OSCORE is REQUIRED for one specific access token by including the ace_profile parameter with the value coap_oscore in the response 🔥. That means the client MUST use OSCORE with every resource server that token is valid for, and it follows Section 4.3 to derive the security context it needs to run OSCORE 🫶. Usually constrained devices come preconfigured with the right profile anyway, so this signaling can be skipped 🧚
the AS MUST also send these two things:
- a Master Secret
- an identifier of the OSCORE Input Material
and the AS MAY send these extras in that same response:
- a context identifier
- an AEAD algorithm
- an HMAC-based key derivation function (HKDF) algorithm [RFC5869]. It is specified by the HMAC algorithm value; see Section 3.1 of [RFC9053].
- a salt
- the OSCORE version number
all of this data rides along in the OSCORE_Input_Material 🦋. The OSCORE_Input_Material is a CBOR map object, defined in Section 3.2.1. It gets transported in the cnf parameter of the access token response, as defined in Section 3.2 of [RFC9201], as the value of a field named osc, which is registered in Sections 9.5 and 9.6 💜
the AS MAY assign an identifier to the context (the context identifier) 🌸. This identifier gets used as ID Context in the OSCORE context, as described in Section 3.1 of [RFC8613]. If one is assigned, these parameters MUST be communicated as the contextId field in the OSCORE_Input_Material. Bestie, the app needs to keep in mind that this identifier is sent in the clear and may reveal information about the endpoints, as mentioned in Section 12.8 of [RFC8613] 😭
the Master Secret and the identifier of the OSCORE_Input_Material MUST be communicated as the ms and id fields in the osc field in the cnf parameter of the access token response 👑. If included, the following also get sent: the AEAD algorithm in the alg parameter of the OSCORE_Input_Material, the HKDF algorithm in the hkdf parameter, a salt in the salt parameter, and the OSCORE version in the version parameter 🍓
the same parameters MUST be included in the claims associated with the access token ✨. The OSCORE Master Secret MUST be encrypted by the authorization server so that only the resource server can decrypt it (see Section 6.1 of [RFC9200]) 🔐. Using a CBOR Web Token (CWT) protected with COSE_Encrypt/COSE_Encrypt0 as specified in [RFC8392] is RECOMMENDED in this profile, no cap 💅. If the token is a CWT, the same OSCORE_Input_Material structure defined above MUST be placed in the osc field of the cnf claim of this token 🎀
the AS MUST send a different OSCORE_Input_Material (and therefore different access tokens) to different authorized clients, so the RS can tell clients apart 👯♀️. It's giving main character energy for sure 🌈
Figure 4 shows an example of an AS response. The access token has been truncated for readability 🦋.
Header: Created (Code=2.01)
Content-Type: application/ace+cbor
Payload:
{
/ access_token / 1 : h'8343a1010aa2044c53/...
(remainder of access token (CWT) omitted for brevity)/',
/ ace_profile / 38 : / coap_oscore / 2,
/ expires_in / 2 : 3600,
/ cnf / 8 : {
/ osc / 4 : {
/ id / 0 : h'01',
/ ms / 2 : h'f9af838368e353e78888e1426bd94e6f'
}
}
}Figure 4: Example AS-to-C Access Token Response with an OSCORE Profile
Figure 5 shows an example CWT Claims Set, including the relevant OSCORE parameters in the cnf claim 🧁.
{
/ aud / 3 : "tempSensorInLivingRoom",
/ iat / 6 : 1360189224,
/ exp / 4 : 1360289224,
/ scope / 9 : "temperature_g firmware_p",
/ cnf / 8 : {
/ osc / 4 : {
/ id / 0 : h'01',
/ ms / 2 : h'f9af838368e353e78888e1426bd94e6f'
}
}
}Figure 5: Example CWT Claims Set with OSCORE Parameters
The same CWT Claims Set as in Figure 5, using the value abbreviations defined in [RFC9200] and [RFC8747] and encoded in CBOR, is shown in Figure 6 🤓. The bytes in hexadecimal are in the first column, and their CBOR meaning is after the # sign in the second column, so it's easier to read 💖.
A5 # map(5)
03 # unsigned(3)
76 # text(22)
74656D7053656E736F72496E4C6976696E67526F6F6D
# "tempSensorInLivingRoom"
06 # unsigned(6)
1A 5112D728 # unsigned(1360189224)
04 # unsigned(4)
1A 51145DC8 # unsigned(1360289224)
09 # unsigned(9)
78 18 # text(24)
74656D70657261747572655F67206669726D776172655F70
# "temperature_g firmware_p"
08 # unsigned(8)
A1 # map(1)
04 # unsigned(4)
A2 # map(2)
00 # unsigned(0)
41 # bytes(1)
01
02 # unsigned(2)
50 # bytes(16)
F9AF838368E353E78888E1426BD94E6FFigure 6: Example CWT Claims Set with OSCORE Parameters Using CBOR Encoding
if the client has asked for an update to its access rights using the same OSCORE security context, and that context is valid and authorized, the AS MUST omit the cnf parameter in the response and MUST carry the OSCORE Input Material identifier in the kid field in the cnf claim of the token 🔄. This identifier needs to be in the token so the RS can figure out which OSCORE Input Material to use 🫠
Figure 7 shows an example of that kind of AS response. The access token has been truncated for readability 🌷.
Header: Created (Code=2.01)
Content-Type: application/ace+cbor
Payload:
{
/ access_token / 1 : h'8343a1010aa2044c53/ ...
(remainder of access token (CWT) omitted for brevity)/',
/ ace_profile / 38 : / coap_oscore / 2,
/ expires_in / 2 : 3600
}Figure 7: Example AS-to-C Access Token Response with an OSCORE Profile for the Update of Access Rights
Figure 8 shows an example CWT Claims Set that contains the necessary OSCORE parameters in the cnf claim for the update of access rights 🦄.
{
/ aud / 3 : "tempSensorInLivingRoom",
/ iat / 6 : 1360189224,
/ exp / 4 : 1360289224,
/ scope / 9 : "temperature_h",
/ cnf / 8 : {
/ kid / 3 : h'01'
}
}Figure 8: Example CWT Claims Set with OSCORE Parameters for the Update of Access Rights
3.2.1. The OSCORE_Input_Material ✨
okay so the OSCORE_Input_Material is an object 🎀 that holds the input material for deriving an OSCORE security context. That's the local set of info you need to do the crypto ops in OSCORE (Section 3.1 of [RFC8613]). It's defined to be serialized and sent between nodes the way this document describes, but other specifications can totally use it too if they need to 💅. It can be encoded as either a JSON object or a CBOR map 🦋.
The common parameters live in the IANA "OSCORE Security Context Parameters" registry (Section 9.4). It's built for extensibility, and the starter set defined in this document is listed below. All parameters are optional 🫶. Table 1 gives you the summary:
+===========+=======+==========+===================+===============+
| name | CBOR | CBOR | registry | description |
| | label | type | | |
+===========+=======+==========+===================+===============+
| id | 0 | byte | | OSCORE Input |
| | | string | | Material |
| | | | | identifier |
+-----------+-------+----------+-------------------+---------------+
| version | 1 | unsigned | | OSCORE |
| | | integer | | version |
+-----------+-------+----------+-------------------+---------------+
| ms | 2 | byte | | OSCORE Master |
| | | string | | Secret value |
+-----------+-------+----------+-------------------+---------------+
| hkdf | 3 | text | [COSE.Algorithms] | OSCORE HKDF |
| | | string / | values (HMAC- | value |
| | | integer | based) | |
+-----------+-------+----------+-------------------+---------------+
| alg | 4 | text | [COSE.Algorithms] | OSCORE AEAD |
| | | string / | values (AEAD) | Algorithm |
| | | integer | | value |
+-----------+-------+----------+-------------------+---------------+
| salt | 5 | byte | | an input to |
| | | string | | OSCORE Master |
| | | | | Salt value |
+-----------+-------+----------+-------------------+---------------+
| contextId | 6 | byte | | OSCORE ID |
| | | string | | Context value |
+-----------+-------+----------+-------------------+---------------+Table 1: OSCORE_Input_Material Parameters 📋
Here's the breakdown, parameter by parameter 🌸:
id: identifies the OSCORE_Input_Material and is encoded as a byte string. In JSON, the id value is a base64-encoded byte string. In CBOR, the id type is a byte string, and it has label 0.version: identifies the OSCORE version number, which is an unsigned integer. For more info, see Section 5.4 of [RFC8613]. In JSON, the version value is an integer. In CBOR, the version type is an integer, and it has label 1.ms: identifies the OSCORE Master Secret value, which is a byte string. For more info, see Section 3.1 of [RFC8613]. In JSON, the ms value is a base64-encoded byte string. In CBOR, the ms type is a byte string, and it has label 2.hkdf: identifies the OSCORE HKDF Algorithm. For more info, see Section 3.1 of [RFC8613]. The values used MUST be registered in the IANA "COSE Algorithms" registry (see [COSE.Algorithms]) and MUST be HMAC-based HKDF algorithms (see Section 3.1 of [RFC9053]). The value can be either the integer or the text-string value of the HMAC-based HKDF algorithm in the "COSE Algorithms" registry. In JSON, the hkdf value is a case-sensitive ASCII string or an integer. In CBOR, the hkdf type is a text string or integer, and it has label 3. 🔥alg: identifies the OSCORE AEAD Algorithm. For more info, see Section 3.1 of [RFC8613]. The values used MUST be registered in the IANA "COSE Algorithms" registry (see [COSE.Algorithms]) and MUST be AEAD algorithms. The value can be either the integer or the text-string value of the HMAC-based HKDF algorithm in the "COSE Algorithms" registry. In JSON, the alg value is a case-sensitive ASCII string or an integer. In CBOR, the alg type is a text string or integer, and it has label 4. 🔥salt: identifies an input to the OSCORE Master Salt value, which is a byte string. For more info, see Section 3.1 of [RFC8613]. In JSON, the salt value is a base64-encoded byte string. In CBOR, the salt type is a byte string, and it has label 5.contextId: identifies the security context as a byte string. This identifier is used as OSCORE ID Context. For more info, see Section 3.1 of [RFC8613]. In JSON, the contextID value is a base64-encoded byte string. In CBOR, the contextID type is a byte string, and it has label 6. 🧚
Here's an example of JSON OSCORE_Input_Material 🍓:
"osc" : {
"alg" : "AES-CCM-16-64-128",
"id" : "AQ",
"ms" : "-a-Dg2jjU-eIiOFCa9lObw"
}Figure 9: Example JSON OSCORE_Input_Material
And this is the CDDL grammar for the CBOR OSCORE_Input_Material, shown in Figure 10 💜:
OSCORE_Input_Material = {
? 0 => bstr, ; id
? 1 => int, ; version
? 2 => bstr, ; ms
? 3 => tstr / int, ; hkdf
? 4 => tstr / int, ; alg
? 5 => bstr, ; salt
? 6 => bstr, ; contextId
* (int / tstr) => any
}Figure 10: CDDL Grammar of the OSCORE_Input_Material
4. Client-RS Communication ✨
The next few subsections are all about the POST request and response to the authz-info endpoint between the client and the RS 🦋. Here's the flow: the client generates a nonce N1 and an identifier ID1 that is unique in the sets of its own Recipient IDs. It then posts those, together with the token (which carries the materials, like OSCORE parameters, it got from the AS), over to the RS 💖. The RS generates its own nonce N2 and an identifier ID2 that is unique in the sets of its own Recipient IDs. Then it uses Section 3.2 of [RFC8613] to derive a security context from a shared Master Secret, the two exchanged nonces, and the two identifiers, which gets established between the client and server ✨. The exchanged nonces and identifiers are encoded as a CBOR byte string if CBOR is used, and as a base64 string if JSON is used. This security context protects all future communication between the client and RS using OSCORE, as long as the access token is valid 🔐.
Note that the RS and client authenticate each other by generating the shared OSCORE security context using the PoP key as the Master Secret. Lowkey the most important part of this whole thing 👑. An attacker who posts a valid token to the RS still won't be able to generate a valid OSCORE security context, so they won't be able to prove possession of the PoP key 💀. Also, the mutual authentication is only achieved after the client has successfully verified a response from the RS that's protected with the generated OSCORE security context 🙈.
4.1. C-to-RS: POST to authz-info Endpoint 🎀
okay bestie, step one is the client making a nonce value N1 🥹. It has to be very unlikely to have been used before with the same input keying material, so the client MUST generate it that way. ngl a 64-bit long random number is RECOMMENDED here in this profile, and it's giving reliable 💅. The client MUST store N1 for as long as the RS hasn't responded and the related access token is still valid (as far as the client knows) 📦.
The client also makes its own Recipient ID, ID1, for the OSCORE security context it's setting up with the RS 🧚. Generating its own ID means ID1 can't collide with any of the client's other Recipient IDs, and it also can't collide with any other ID1 if the client is running this exchange with a different RS at the same time. Iconic planning 👑.
The client MUST use CoAP and the authorization information resource, as described in Section 5.8.1 of [RFC9200], to send the token, N1, and ID1 to the RS 🦋.
Now here's the twist. The payload and Content-Format work differently from Section 5.8.1 of [RFC9200], which only sends the token with no CBOR wrapping at all 🙈. In this profile, the client MUST wrap the token, N1, and ID1 in a CBOR map 🎁. The client MUST use the Content-Format application/ace+cbor, defined in Section 8.16 of [RFC9200]. Then the client MUST include the access token under the access_token parameter, N1 under the nonce1 parameter (defined in Section 4.1.1), and ID1 under the ace_client_recipientid parameter (defined in Section 4.1.2) 💜.
The communication with the authz-info endpoint does not have to be protected, except in the update of access rights case we'll get to below 🔐.
Also, a client may be required to repost the access token to finish a request. That happens because an RS can delete a stored access token (and its security context) at any time, for example when all the storage space is used up 💀. The client notices this when it gets an AS Request Creation Hints response. Reposting the same access token gives you a brand-new OSCORE security context, because different nonces get exchanged, so it's a whole fresh start 🌸.
A client can also repost the token just to update its OSCORE security context 🔄. In that case, the client and the RS swap newly generated nonces, renegotiate identifiers, and derive new keying material. They might keep the same identifiers or renew them during renegotiation, whichever they decide ✨.
Figure 11 shows an example of the request from the client to the RS. The access token is truncated so it's easier to read 👀.
Header: POST (Code=0.02)
Uri-Host: "rs.example.com"
Uri-Path: "authz-info"
Content-Format: application/ace+cbor
Payload:
{
/ access_token / 1 : h'8343a1010aa2044c53/...
(remainder of access token (CWT) omitted for brevity)/',
/ nonce1 / 40 : h'018a278f7faab55a',
/ ace_client_recipientid / 43 : h'1645'
}Figure 11: Example C-to-RS POST /authz-info Request Using CWT 🧾
Last one in this bit: say the client already posted a valid token, already has a security association with the RS, and wants to update its access rights 🪄. It can do that by posting the new token (the one from the AS that has the updated access rights) to the /authz-info endpoint. The client MUST protect this request using the OSCORE security context from the first token exchange 🔒. The client MUST only send the access_token field in the CBOR map in the payload, and no nonce or identifier gets sent 🙅♀️. After proper verification (see Section 4.2), the RS replaces the old token with the new one and keeps the same security context. Main character energy 👑.
4.1.1. The Nonce 1 Parameter ✨
The nonce1 parameter MUST be sent from the client to the RS, together with the access token, if the ACE profile in use is coap_oscore and the message is not an update of access rights protected with an existing OSCORE security context 🧁. For CBOR-based interactions it's encoded as a byte string, and for JSON-based interactions it's a string (base64-encoded binary) 💖. This parameter is registered in Section 9.2.
4.1.2. The ace_client_recipientid Parameter ✨
The ace_client_recipientid parameter MUST be sent from the client to the RS, together with the access token, if the ACE profile in use is coap_oscore and the message is not an update of access rights protected with an existing OSCORE security context 🌈. Same encoding deal as before: a byte string for CBOR-based interactions, and a base64-encoded string for JSON-based interactions 🫶. This parameter is registered in Section 9.2.
4.2. RS-to-C: 2.01 (Created) 🌷
The RS MUST follow the procedures in Section 5.8.1 of [RFC9200], and that means the RS must verify that the token is valid 🕵️♀️. If the token is valid, the RS must answer the POST with 2.01 (Created) ✅. But if the token is valid and tied to claims the RS can't process (like an unknown scope), or if any of the expected parameters are missing (like any mandatory parameter from the AS, or ID1), or if any parameters in the osc field aren't recognized, the RS must respond with an error code equivalent to CoAP 4.00 (Bad Request) 🙅♀️. In the last two cases, the RS may add extra info to the error response so the client knows what went wrong 🧠. The RS may also make an introspection request (see Section 5.9.1 of [RFC9200]) to validate the token before it answers the POST to the authz-info endpoint 🔍.
Next, the RS MUST generate a nonce N2 that's very unlikely to have been used before with the same input keying material and its own Recipient ID, ID2 🎯. The RS makes sure ID2 doesn't collide with any of its Recipient IDs. The RS MUST ensure that ID2 is different from the value received in the ace_client_recipientid parameter 🙌. The RS sends N2 and ID2 back inside the 2.01 (Created) response. The payload of that 2.01 (Created) response MUST be a CBOR map that holds the nonce2 parameter (defined in Section 4.2.1), set to N2, and the ace_server_recipientid parameter (defined in Section 4.2.2), set to ID2 🎀. A 64-bit long random number is RECOMMENDED as the nonce's value in this profile 🍓. The RS MUST use the Content-Format application/ace+cbor, defined in Section 8.16 of [RFC9200] 💌.
Figure 12 shows an example of the response from the RS to the client 🧚♀️.
Header: Created (Code=2.01)
Content-Format: application/ace+cbor
Payload:
{
/ nonce2 / 42 : h'25a8991cd700ac01',
/ ace_server_recipientid / 44 : h'0000'
}Figure 12: Example RS-to-C 2.01 (Created) Response 🧾
As Section 5.8.3 of [RFC9200] says, the RS must tell the client with a 4.01 (Unauthorized) error response for any long running request before ending the session, once the access token expires ⏰.
Now the update case 🔄. If the RS receives the token in an OSCORE-protected message, that means the client wants an update of access rights 🪄. The RS MUST ignore any nonce and identifiers in that request, if any were sent 🙈. The RS MUST check that the kid in the cnf claim of the new access token matches the identifier of the OSCORE Input Material for the context that protected the message 🔎. If it does match, the RS MUST overwrite the old token and link the new token to the security context identified by the kid value in the cnf claim 💫. The RS MUST respond with a 2.01 (Created) response, protected with that same security context, and with no payload 🔐. If any verification fails, the RS MUST respond with a 4.01 (Unauthorized) error response 🚫.
And as Section 5.8.1 of [RFC9200] puts it, when the RS gets an updated access token with updated authorization information from the client (see Section 3.1), it is recommended that the RS overwrites the previous token. That way only the latest authorization information in the token is valid. This makes life a lot simpler for the RS when it's tracking authorization information for a given client 🧹✨.
4.2.1. The Nonce 2 Parameter ✨
The nonce2 parameter MUST be sent from the RS to the client if the ACE profile in use is coap_oscore and the message is not a response to an update of access rights protected with an existing OSCORE security context 🌸. For CBOR-based interactions it's a byte string, and for JSON-based interactions it's a base64-encoded string 🫶. This parameter is registered in Section 9.2.
4.2.2. The ace_server_recipientid Parameter ✨
The ace_server_recipientid parameter MUST be sent from the RS to the client if the ACE profile in use is coap_oscore and the message is not a response to an update of access rights protected with an existing OSCORE security context 🦋. Same encoding as before: a byte string for CBOR-based interactions, and a base64-encoded string for JSON-based interactions 💜. This parameter is registered in Section 9.2.
4.3. OSCORE Setup ✨
Okay so once the 2.01 (Created) response comes back from the RS after your POST to the authz-info endpoint, the client MUST extract the bstr nonce N2 from the nonce2 parameter in the CBOR map in that response's payload. 🎀 Then the client MUST set the Master Salt of the security context it's building for the RS to the concatenation of salt, N1, and N2, in this order: Master Salt = salt | N1 | N2. The | just means byte string concatenation. The salt is the CBOR byte string the AS sent back in Section 3.2, and N1 and N2 are both encoded as CBOR byte strings. Here's a worked example of building the Master Salt with CBOR encoding 🍓
N1, N2, and input salt expressed in CBOR diagnostic notation:
nonce1 = h'018a278f7faab55a'
nonce2 = h'25a8991cd700ac01'
input salt = h'f9af838368e353e78888e1426bd94e6f'
N1, N2, and input salt as CBOR encoded byte strings:
nonce1 = 0x48018a278f7faab55a
nonce2 = 0x4825a8991cd700ac01
input salt = 0x50f9af838368e353e78888e1426bd94e6f
Master Salt = 0x50 f9af838368e353e78888e1426bd94e6f
48 018a278f7faab55a 48 25a8991cd700ac01Figure 13: Example of Master Salt Construction Using CBOR Encoding
If you're using JSON instead of CBOR, the Master Salt of the security context is the base64 encoding of the concatenation of those same parameters, with each one prefixed by its size, encoded in 1 byte. 💅 With JSON, the nonces and input salt have a maximum size of 255 bytes. Figure 14 shows the base64 version of the same idea ✨
N1, N2, and input salt values:
nonce1 = 0x018a278f7faab55a (8 bytes)
nonce2 = 0x25a8991cd700ac01 (8 bytes)
input salt = 0xf9af838368e353e78888e1426bd94e6f (16 bytes)
Input to base64 encoding: 0x10 f9af838368e353e78888e1426bd94e6f
08 018a278f7faab55a 08 25a8991cd700ac01
Master Salt = b64'EPmvg4No41PniIjhQmvZTm8IAYonj3+qtVoIJaiZHNcArAE='Figure 14: Example of Master Salt Construction Using Base64 Encoding
Now the client's other settings. The client MUST set the Sender ID to the ace_server_recipientid received in Section 4.2, and set the Recipient ID to the ace_client_recipientid sent in Section 4.1. 🦋 The client MUST set the Master Secret from the parameter received from the AS in Section 3.2. The client MUST also set the AEAD algorithm, ID Context, HKDF, and OSCORE version from the parameters the AS sent in Section 3.2, if they're present. If an optional parameter is left out, the default value SHALL be used, as described in Sections 3.2 and 5.4 of [RFC8613]. After all that, the client MUST derive the complete security context following Section 3.2.1 of [RFC8613]. From this point on, the client MUST use this security context to talk to the RS when accessing the resources the authorization information covers. 🫶
If any of the expected parameters are missing (for example, any of the mandatory parameters from the AS or the RS), or if ace_client_recipientid equals ace_server_recipientid (which would make the Sender and Recipient Keys derived equal too; see Section 3.3 of [RFC8613]), then the client MUST stop the exchange and MUST NOT derive the security context. 😭 The client MAY restart the exchange to get the correct security material.
The client then uses this security context to send requests to the RS using OSCORE. 🌈
Now for the RS side. After sending the 2.01 (Created) response, the RS MUST set the Master Salt of the security context created to communicate with the client to the concatenation of salt, N1, and N2, the same way as described above. Figure 13 has the CBOR example and Figure 14 has the base64 one. The RS MUST set the Sender ID from the ace_client_recipientid received in Section 4.1, and set the Recipient ID from the ace_server_recipientid sent in Section 4.2. 🧚 The RS MUST set the Master Secret from the parameter it got from the AS, which the client forwarded in the access token in Section 4.1, but only after validating the token as specified in Section 4.2. The RS MUST also set the AEAD algorithm, ID Context, HKDF, and OSCORE version from those same AS parameters forwarded in the access token in Section 4.1, after token validation as specified in Section 4.2, if they're present. If an optional parameter is omitted, the default value SHALL be used, as described in Sections 3.2 and 5.4 of [RFC8613]. Then the RS MUST derive the complete security context following Section 3.2.1 of [RFC8613], and MUST associate this security context with the authorization information from the access token. 👑
The RS then uses this security context to verify requests and send responses to the client using OSCORE. If OSCORE verification fails, error responses are used, as specified in Section 8 of [RFC8613]. If OSCORE verification succeeds, the verification of access rights is performed as described in Section 4.4. The RS MUST NOT use the security context after the related token has expired. It MUST respond with an unprotected 4.01 (Unauthorized) error message to requests that correspond to a security context with an expired token. 💀
One more thing, because it's kinda important 🙈 The ID Context can be assigned by the AS, and it gets communicated and set in both the RS and the client after the exchange in this profile is done. Later on, the client and RS can update their ID Context by running a mechanism like the one defined in Appendix B.2 of [RFC8613], as long as they both support it and are configured to do so. In that case, the ID Context in the OSCORE security context won't match the contextId parameter of the corresponding OSCORE_Input_Material. Running Appendix B.2 updates the keying material in the security contexts of the client and RS. You can get the same result by having the client repost the access token to the unprotected /authz-info endpoint at the RS, as described in Section 4.1, just without updating the ID Context. 🔥
4.4. Access Rights Verification
The RS MUST follow the procedures defined in Section 5.8.2 of [RFC9200]. So if an RS gets an OSCORE-protected request from a client, it processes that request according to [RFC8613]. If OSCORE verification succeeds and the target resource requires authorization, the RS retrieves the authorization information using the access token associated with the security context. The RS then must verify that the authorization information covers the resource and the action requested. 👀
5. Secure Communication with AS
As the ACE framework specifies (Section 5.9 of [RFC9200]), the requesting entity (the RS and/or the client) and the AS communicate via the introspection or token endpoint. Using CoAP and OSCORE [RFC8613] for this communication is RECOMMENDED in this profile. 🌸 Other protocols that fulfil the security requirements defined in Section 5 of [RFC9200] (such as HTTP and DTLS or TLS) MAY be used instead.
If OSCORE is used, the requesting entity and the AS are expected to have preestablished security contexts in place. How those security contexts get established is out of scope for this profile. ✨ Furthermore, the requesting entity and the AS communicate through the introspection endpoint as specified in Section 5.9 of [RFC9200], and through the token endpoint as specified in Section 5.8 of [RFC9200].
6. Discarding the Security Context
There are a number of scenarios where a client or RS needs to throw out the OSCORE security context and get a new one. 🦋
The client MUST discard the current security context associated with an RS when any of the following happens:
- the sequence number space ends.
- the access token associated with the context becomes invalid, for example due to expiration.
- the client receives a number of 4.01 Unauthorized responses to OSCORE requests using the same security context. The exact number needs to be specified by the application.
- the client receives a new nonce in the 2.01 (Created) response (see Section 4.2) to a POST request to the authz-info endpoint, when reposting a (non-expired) token associated to the existing context.
The RS MUST discard the current security context associated with a client when any of the following happens:
- the sequence number space ends.
- the access token associated with the context expires.
- the client has successfully replaced the current security context with a newer one by posting an access token to the unprotected /authz-info endpoint at the RS, e.g., by reposting the same token, as specified in Section 4.1.
Whenever one more access token is successfully posted to the RS, and a new security context is derived between the client and RS, messages in transit that were protected with the previous security context might not pass verification, since the old context is discarded. 😬 That means messages sent shortly before the client posts one more access token to the RS might not successfully reach their destination. Similarly, implementations may want to cancel CoAP observations at the RS that were registered before the security context was replaced. Otherwise they'll need to build a mechanism that makes sure those observations are protected with the newly derived security context. 💜
7. Security Considerations 🛡️
okay bestie, this doc is a profile for the ACE framework [RFC9200], so the general security considerations from that framework apply here too 🔒
the general security considerations of OSCORE [RFC8613] also apply to this specific way of using OSCORE 🔐
as we said earlier, the proof of possession in this profile happens when both parties check that they've set up the same security context (see Section 4.3). that means both the OSCORE request and the OSCORE response have to pass verification ✅ RS authentication needs two things: the client has to trust the AS, and the OSCORE response from the RS has to pass verification 💖
OSCORE is built for point-to-point communication 🎯 it gives you a secure binding between the request and the response(s). so the basic OSCORE protocol is not meant for point-to-multipoint communication (like multicast or publish-subscribe) 🙅♀️ implementers of this profile should double-check that their use case fits what OSCORE is meant for, so they don't weaken the security assurances OSCORE gives 🫶
okay, the nonces part is SO important 😭 since nonces N1 and N2 used during the exchange are what keep AEAD keys and nonces unique, it is REQUIRED that the exchanged nonces are not reused with the same input keying material, even after reboots 🚨 using 64-bit random nonces is RECOMMENDED in this document 🎲 with the birthday paradox in mind, the average collision for each nonce happens after 2^32 messages, which is way more token provisionings than you'd expect for intended applications 💅 if applications use something else, like a counter, they have to guarantee that a reboot or loss of state on either node can't cause reuse. if that isn't guaranteed, nodes are open to reuse of AEAD (nonce, key) pairs 💀 this is especially risky because an on-path attacker can make a previously exchanged client nonce N1 get used for security context establishment, just by replaying the matching client-to-server message 👀
in this profile, it is RECOMMENDED that the RS keeps a single access token for each client 🎀 using multiple access tokens for one client makes the resource server work harder, since it has to look at every access token and work out the client's actual permissions 😩 also, tokens with different or disjoint permissions might make the server enforce the wrong permissions 🙈 and if one token expires earlier than the others, the leftover permissions may not protect things well enough. developers SHOULD avoid using multiple access tokens for the same client 🚫
if a single OSCORE Input Material is used with multiple RSs, those RSs can impersonate the client to one of the other RSs, and impersonate another RS to the client 👻 if a Master Secret is used with several clients, the clients can impersonate an RS to one of the other clients 🥴 similarly, if symmetric keys are used to integrity protect the token between the AS and RS, and the token can be used with multiple RSs, the RSs can impersonate the AS to one of the other RSs 😱 and if the token key is used for any other communication between the RSs and AS, the RSs can impersonate each other to the AS 💜
8. Privacy Considerations 🦋
this doc is a profile for the ACE framework [RFC9200], so the general privacy considerations from the framework apply here too 🌸
since this doc uses OSCORE, the privacy considerations from [RFC8613] apply here as well ✨
an unprotected response to an unauthorized request might leak info about the resource server and/or its existing relationship with the client 👀 it's advisable to include as little information as possible in an unencrypted response 🤫 when an OSCORE security context already exists between the client and the resource server, more detailed info can be included 💖
the token is sent in the clear to the authz-info endpoint, so if a client uses the same single token from multiple locations with multiple resource servers, it can get tracked by the token's value, even when the access token is encrypted 🕵️♀️
the nonces exchanged in the request and response to the authz-info endpoint are also sent in the clear, so random nonces are the best for privacy (as opposed to, e.g., a counter, which could leak info about the client) 🎲✨
the identifiers used in OSCORE, negotiated between the client and RS, are privacy sensitive (see Section 12.8 of [RFC8613]) and could reveal info about the client, or be used to correlate requests from one client 🫣
ngl some info might still leak after OSCORE is set up, because of observable message sizes and the source and destination addresses 🙈
9. IANA Considerations 📋
9.1. ACE Profile Registry
the following registration has been made in the "ACE Profiles" registry, following the procedure in Section 8.8 of [RFC9200] 🍓
Name: coap_oscore
Description: Profile for using OSCORE to secure communication
between constrained nodes using the Authentication and
Authorization for Constrained Environments framework.
CBOR Value: 2
Reference: RFC 92039.2. OAuth Parameters Registry
the following registrations have been made in the "OAuth Parameters" registry [IANA.OAuthParameters], following the procedure in Section 11.2 of [RFC6749] 🧚
Parameter name: nonce1
Parameter usage location: client-rs request
Change Controller: IETF
Specification Document(s): RFC 9203
Parameter name: nonce2
Parameter usage location: rs-client response
Change Controller: IETF
Specification Document(s): RFC 9203
Parameter name: ace_client_recipientid
Parameter usage location: client-rs request
Change Controller: IETF
Specification Document(s): RFC 9203
Parameter name: ace_server_recipientid
Parameter usage location: rs-client response
Change Controller: IETF
Specification Document(s): RFC 92039.3. OAuth Parameters CBOR Mappings Registry
the following registrations have been made in the "OAuth Parameters CBOR Mappings" registry, following the procedure in Section 8.10 of [RFC9200] 💜
Name: nonce1
CBOR Key: 40
Value Type: bstr
Reference: RFC 9203
Name: nonce2
CBOR Key: 42
Value Type: bstr
Reference: RFC 9203
Name: ace_client_recipientid
CBOR Key: 43
Value Type: bstr
Reference: RFC 9203
Name: ace_server_recipientid
CBOR Key: 44
Value Type: bstr
Reference: RFC 92039.4. OSCORE Security Context Parameters Registry
IANA made a brand-new registry called "OSCORE Security Context Parameters" 🎀 the registration procedure depends on the range of CBOR label values, following [RFC8126]. guidelines for the experts are in Section 9.7 👑
the columns of the registry are:
- Name: the JSON name requested (e.g.,
"ms"). because a core goal of this doc is for the resulting representations to be compact, it is RECOMMENDED that the name be short 🍰 this name is case sensitive. names may not match other registered names in a case-insensitive manner unless the designated experts decide there's a compelling reason to allow an exception. the name is not used in the CBOR encoding. - CBOR Label: the value used to identify this name. Map key labels MUST be unique 🔑 the label can be a positive integer, a negative integer, or a string. integer values between
-256and255, and strings of length1, are designated as Standards Track document required. integer values from-65536to-257, and from256to65535, and strings of length2, are designated as Specification Required. integer values greater than65535, and strings of length greater than2, are designated as Expert Review. integer values less than-65536are marked as Private Use 🌈 - CBOR Type: the CBOR type for the field 🧁
- Registry: the registry that values may come from, if one exists 🗂️
- Description: a brief description of the field ✏️
- Reference: a pointer to the public specification for the field, if one exists 🔗
this registry has been initially populated by the values in Table 1. the Reference column for all of these entries is this document ✨
9.5. CWT Confirmation Methods Registry
the following registration has been made in the "CWT Confirmation Methods" registry [IANA.CWTConfirmationMethods], following the procedure in Section 7.2.1 of [RFC8747] 🦄
Confirmation Method Name: osc
Confirmation Method Description: OSCORE_Input_Material carrying the
parameters for using OSCORE per-message security with implicit key
confirmation
JWT Confirmation Method Name: osc
Confirmation Key: 4
Confirmation Value Type(s): map
Change Controller: IETF
Specification Document(s): Section 3.2.1 of RFC 92039.6. JWT Confirmation Methods Registry
the following registration has been made in the "JWT Confirmation Methods" registry [IANA.JWTConfirmationMethods], following the procedure in Section 6.2.1 of [RFC7800] 🌷
Confirmation Method Value: osc
Confirmation Method Description: OSCORE_Input_Material carrying the
parameters for using OSCORE per-message security with implicit key
confirmation
Change Controller: IETF
Specification Document(s): Section 3.2.1 of RFC 92039.7. Expert Review Instructions
the IANA registry set up in this doc uses the Expert Review registration policy 🧐 this section gives some general guidelines for what the experts should look for, but they were picked as experts for a reason, so they get substantial latitude 👑
expert reviewers should take these points into consideration:
- Point squatting should be discouraged. reviewers are encouraged to get enough info for registration requests to make sure the usage won't duplicate one that's already registered, and that the point is likely to be used in deployments 🔍 the zones tagged as Private Use are meant for testing and closed environments. code points in other ranges should not be assigned for testing 🧪
- Specifications are required for the Standards Track range of point assignment. specifications should exist for specification required ranges, but early assignment before a specification is available is considered permissible 📄 specifications are needed for the First Come First Served range if they're expected to be used outside closed environments in an interoperable way 🌍 when specifications aren't provided, the description needs enough info to identify what the point is being used for 💬
- Experts should take into account the expected usage of fields when approving point assignment. the fact that there's a range for Standards Track documents doesn't mean a Standards Track document can't have points assigned outside that range 🙅♀️ the length of the encoded value should be weighed against how many code points of that length are left, the size of the device it'll be used on, and the number of code points left that encode to that size 📏
10. References 📚
10.1. Normative References
okay bestie, these are the ones you NEED to have read before the spec makes any sense 📚🫶
[COSE.Algorithms] IANA, "COSE Algorithms", <https://www.iana.org/assignments/cose>.
[IANA.CWTConfirmationMethods] IANA, "CWT Confirmation Methods", <https://www.iana.org/assignments/cwt>.
[IANA.JWTConfirmationMethods] IANA, "JWT Confirmation Methods", <https://www.iana.org/assignments/jwt>.
[IANA.OAuthParameters] IANA, "OAuth Parameters", <https://www.iana.org/assignments/oauth-parameters>.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997, <https://www.rfc-editor.org/info/rfc2119>. 🎀
[RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data Encodings", RFC 4648, DOI 10.17487/RFC4648, October 2006, <https://www.rfc-editor.org/info/rfc4648>. 🍓
[RFC5869] Krawczyk, H. and P. Eronen, "HMAC-based Extract-and-Expand Key Derivation Function (HKDF)", RFC 5869, DOI 10.17487/RFC5869, May 2010, <https://www.rfc-editor.org/info/rfc5869>. 🔑
[RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained Application Protocol (CoAP)", RFC 7252, DOI 10.17487/RFC7252, June 2014, <https://www.rfc-editor.org/info/rfc7252>. 🦋
[RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, May 2017, <https://www.rfc-editor.org/info/rfc8174>. 💅
[RFC8392] Jones, M., Wahlstroem, E., Erdtman, S., and H. Tschofenig, "CBOR Web Token (CWT)", RFC 8392, DOI 10.17487/RFC8392, May 2018, <https://www.rfc-editor.org/info/rfc8392>. 🧚
[RFC8610] Birkholz, H., Vigano, C., and C. Bormann, "Concise Data Definition Language (CDDL): A Notational Convention to Express Concise Binary Object Representation (CBOR) and JSON Data Structures", RFC 8610, DOI 10.17487/RFC8610, June 2019, <https://www.rfc-editor.org/info/rfc8610>. ✨
[RFC8613] Selander, G., Mattsson, J., Palombini, F., and L. Seitz, "Object Security for Constrained RESTful Environments (OSCORE)", RFC 8613, DOI 10.17487/RFC8613, July 2019, <https://www.rfc-editor.org/info/rfc8613>. 🌸
[RFC8949] Bormann, C. and P. Hoffman, "Concise Binary Object Representation (CBOR)", STD 94, RFC 8949, DOI 10.17487/RFC8949, December 2020, <https://www.rfc-editor.org/info/rfc8949>. 💜
[RFC9052] Schaad, J., "CBOR Object Signing and Encryption (COSE): Structures and Process", STD 96, RFC 9052, DOI 10.17487/RFC9052, August 2022, <https://www.rfc-editor.org/info/rfc9052>. 🔐
[RFC9053] Schaad, J., "CBOR Object Signing and Encryption (COSE): Initial Algorithms", RFC 9053, DOI 10.17487/RFC9053, August 2022, <https://www.rfc-editor.org/info/rfc9053>. ⭐
[RFC9200] Seitz, L., Selander, G., Wahlstroem, E., Erdtman, S., and H. Tschofenig, "Authentication and Authorization for Constrained Environments Using the OAuth 2.0 Framework (ACE-OAuth)", RFC 9200, DOI 10.17487/RFC9200, August 2022, <https://www.rfc-editor.org/info/rfc9200>. 👑
[RFC9201] Seitz, L., "Additional OAuth Parameters for Authentication and Authorization for Constrained Environments (ACE)", RFC 9201, DOI 10.17487/RFC9201, August 2022, <https://www.rfc-editor.org/info/rfc9201>. 🌈
10.2. Informative References
these ones are the extra reading, like the "if you want to go deeper" section 🙈
[RFC4949] Shirey, R., "Internet Security Glossary, Version 2", FYI 36, RFC 4949, DOI 10.17487/RFC4949, August 2007, <https://www.rfc-editor.org/info/rfc4949>.
[RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", RFC 6749, DOI 10.17487/RFC6749, October 2012, <https://www.rfc-editor.org/info/rfc6749>.
[RFC7800] Jones, M., Bradley, J., and H. Tschofenig, "Proof-of-Possession Key Semantics for JSON Web Tokens (JWTs)", RFC 7800, DOI 10.17487/RFC7800, April 2016, <https://www.rfc-editor.org/info/rfc7800>.
[RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for Writing an IANA Considerations Section in RFCs", BCP 26, RFC 8126, DOI 10.17487/RFC8126, June 2017, <https://www.rfc-editor.org/info/rfc8126>.
[RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018, <https://www.rfc-editor.org/info/rfc8446>.
[RFC8747] Jones, M., Seitz, L., Selander, G., Erdtman, S., and H. Tschofenig, "Proof-of-Possession Key Semantics for CBOR Web Tokens (CWTs)", RFC 8747, DOI 10.17487/RFC8747, March 2020, <https://www.rfc-editor.org/info/rfc8747>.
[RFC9110] Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke, Ed., "HTTP Semantics", STD 97, RFC 9110, DOI 10.17487/RFC9110, June 2022, <https://www.rfc-editor.org/info/rfc9110>.
[RFC9147] Rescorla, E., Tschofenig, H., and N. Modadugu, "The Datagram Transport Layer Security (DTLS) Protocol Version 1.3", RFC 9147, DOI 10.17487/RFC9147, April 2022, <https://www.rfc-editor.org/info/rfc9147>.
Appendix A. Profile Requirements
this is the checklist where the profile ticks off what the ACE framework asked for, so here we go ✅💖
This section lists the specifications of this profile based on the requirements of the framework, as requested in Appendix C of [RFC9200].
- Optionally, define new methods for the client to discover the necessary permissions and AS for accessing a resource, different from the one proposed in [RFC9200]: Not specified
- Optionally, specify new grant types: Not specified
- Optionally, define the use of client certificates as client credential type: Not specified
- Specify the communication protocol the client and RS must use:
CoAP - Specify the security protocol the client and RS must use to protect their communication:
OSCORE - Specify how the client and the RS mutually authenticate: Implicitly by possession of a common OSCORE security context. Note that the mutual authentication is not completed before the client has verified an OSCORE response using this security context. 🫣
- Specify the proof-of-possession protocol(s) and how to select one, if several are available. Also specify which key types (e.g., symmetric/asymmetric) are supported by a specific proof-of-possession protocol: OSCORE algorithms; preestablished symmetric keys
- Specify a unique ace_profile identifier:
coap_oscore - If introspection is supported, specify the communication and security protocol for introspection: HTTP/CoAP (+ TLS/DTLS/OSCORE)
- Specify the communication and security protocol for interactions between client and AS: HTTP/CoAP (+ TLS/DTLS/OSCORE)
- Specify if/how the authz-info endpoint is protected, including how error responses are protected: Not protected
- Optionally, define methods of token transport other than the authz-info endpoint: Not defined
Acknowledgments
big thank-yous to everyone who made this happen 🫶🌸
The authors wish to thank Jim Schaad and Marco Tiloca for the substantial input to this document, as well as Carsten Bormann, Elwyn Davies, Linda Dunbar, Roman Danyliw, Martin Duke, Lars Eggert, Murray Kucherawy, and Zaheduzzaman Sarker for their reviews and feedback. Special thanks to the responsible area director Benjamin Kaduk for his extensive review and contributed text. Ludwig Seitz worked on this document as part of the CelticNext projects CyberWI and CRITISEC with funding from Vinnova. The work on this document has been partly supported also by the H2020 project SIFIS-Home (Grant agreement 952652).
Authors' Addresses
meet the people behind the spec 🦋✨
Francesca Palombini
Ericsson AB
Email: francesca.palombini@ericsson.com
Ludwig Seitz
Combitech
Djäknegatan 31
SE-211 35 Malmö
Sweden
Email: ludwig.seitz@combitech.com
Göran Selander
Ericsson AB
Email: goran.selander@ericsson.com
Martin Gunnarsson
RISE
Scheelevägen 17
SE-22370 Lund
Sweden
Email: martin.gunnarsson@ri.se📦 where this page comes from
- ietf: rfc9203 2022-08
- 💖 girlified by claude-haiku-5-5 on : a language model's rewrite of the original, under its terms