idnits 2.17.1 draft-seitz-ace-ocsoap-profile-00.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 (July 1, 2016) is 2855 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Missing Reference: 'I-D.ietf-ace-actors' is mentioned on line 116, but not defined == Unused Reference: 'I-D.gerdes-ace-actors' is defined on line 334, but no explicit reference was found in the text == Outdated reference: A later version (-06) exists of draft-selander-ace-object-security-04 == Outdated reference: A later version (-14) exists of draft-selander-ace-cose-ecdhe-02 == Outdated reference: A later version (-07) exists of draft-ietf-ace-actors-03 == Outdated reference: A later version (-24) exists of draft-ietf-cose-msg-14 -- Obsolete informational reference (is this intentional?): RFC 7231 (Obsoleted by RFC 9110) Summary: 0 errors (**), 0 flaws (~~), 7 warnings (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 ACE Working Group L. Seitz 3 SICS Swedish ICT 4 Internet-Draft July 1, 2016 5 Intended Status: Standards Track 6 Expires: January 2, 2017 8 OSCOAP profile of ACE 9 draft-seitz-ace-ocsoap-profile-00 11 Abstract 13 This memo specifies a profile for the ACE framework for 14 Authentication and Authorization. It utilizes Object Security of 15 CoAP (OSCOAP) and Ephemeral Diffie-Hellman over COSE (EDHOC) to 16 provide communication security, server authentication, and proof-of- 17 possession for a key owned by the client and bound to an OAuth 2.0 18 access token. 20 Status of this Memo 22 This Internet-Draft is submitted to IETF in full conformance with the 23 provisions of BCP 78 and BCP 79. 25 Internet-Drafts are working documents of the Internet Engineering 26 Task Force (IETF), its areas, and its working groups. Note that 27 other groups may also distribute working documents as 28 Internet-Drafts. 30 Internet-Drafts are draft documents valid for a maximum of six months 31 and may be updated, replaced, or obsoleted by other documents at any 32 time. It is inappropriate to use Internet-Drafts as reference 33 material or to cite them other than as "work in progress". 35 The list of current Internet-Drafts can be accessed at 36 http://www.ietf.org/1id-abstracts.html 38 The list of Internet-Draft Shadow Directories can be accessed at 39 http://www.ietf.org/shadow.html 41 Copyright and License Notice 43 Copyright (c) 2016 IETF Trust and the persons identified as the 44 document authors. All rights reserved. 46 This document is subject to BCP 78 and the IETF Trust's Legal 47 Provisions Relating to IETF Documents 48 (http://trustee.ietf.org/license-info) in effect on the date of 49 publication of this document. Please review these documents 50 carefully, as they describe your rights and restrictions with respect 51 to this document. Code Components extracted from this document must 52 include Simplified BSD License text as described in Section 4.e of 53 the Trust Legal Provisions and are provided without warranty as 54 described in the Simplified BSD License. 56 Table of Contents 58 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 59 1.1 Terminology . . . . . . . . . . . . . . . . . . . . . . . . 3 60 2. Client to Resource Server . . . . . . . . . . . . . . . . . . . 4 61 2.1. Signalling the use of OSCOAP . . . . . . . . . . . . . . . 4 62 2.2. Key establishment for OSCOAP . . . . . . . . . . . . . . . 4 63 2.3. Securing the Resource Request . . . . . . . . . . . . . . . 6 64 2.4. Securing the Resource Server Response . . . . . . . . . . . 6 65 3. Client to Authorization Server . . . . . . . . . . . . . . . . 6 66 4. Resource Server to Authorization Server . . . . . . . . . . . . 6 67 5. Security Considerations . . . . . . . . . . . . . . . . . . . . 7 68 6. Privacy Considerations . . . . . . . . . . . . . . . . . . . . 7 69 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 7 70 8. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 7 71 9. References . . . . . . . . . . . . . . . . . . . . . . . . . . 7 72 9.1 Normative References . . . . . . . . . . . . . . . . . . . 7 73 9.2 Informative References . . . . . . . . . . . . . . . . . . 8 74 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 9 76 1. Introduction 78 This memo specifies a profile of the ACE framework [I-D.ietf-ace- 79 oauth-authz]. In this profile, a client and a resource server use 80 CoAP to communicate. The client uses an access token, bound to a key 81 (the proof-of-possession key) to authorize its access to the resource 82 server. In order to provide communication security, proof of 83 possession, and server authentication they use Object Security of 84 CoAP (OSCOAP) [I-D.selander-ace-object-security] and Ephemeral 85 Diffie-Hellman Over COSE (EDHOC) [I-D.selander-ace-cose-ecdhe]. 86 Optionally the client and the resource server may also use CoAP and 87 OSCOAP to communicate with the authorization server. The use of 88 EDHOC in this profile in addition to OSCOAP, provides perfect forward 89 secrecy (PFS) and the initial proof-of-possession, which ties the 90 proof-of-possession key to an OSCOAP security context. 92 OSCOAP specifies how to use CBOR Object Signing and Encryption (COSE) 93 [I-D.ietf-cose-msg] to secure CoAP messages. In order to provide 94 replay and reordering protection OSCOAP also introduces sequence 95 numbers that are used together with COSE. EDHOC specifies an 96 authenticated Diffie-Hellman protocol that allows two parties that 97 wish to use OSCOAP to establish a shared secret key with perfect 98 forward secrecy. 100 1.1 Terminology 102 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 103 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 104 document are to be interpreted as described in [RFC2119]. These 105 words may also appear in this document in lowercase, absent their 106 normative meanings. 108 Certain security-related terms such as "authentication", 109 "authorization", "confidentiality", "(data) integrity", "message 110 authentication code", and "verify" are taken from [RFC4949]. 112 Since we describe exchanges as RESTful protocol interactions HTTP 113 [RFC7231] offers useful terminology. 115 Terminology for entities in the architecture is defined in OAuth 2.0 116 [RFC6749] and [I-D.ietf-ace-actors], such as client (C), resource 117 server (RS), and authorization server (AS). 119 Note that the term "endpoint" is used here following its OAuth 120 definition, which is to denote resources such as /token and 121 /introspect at the AS and /authz-info at the RS. The CoAP [RFC7252] 122 definition, which is "An entity participating in the CoAP protocol" 123 is not used in this memo. 125 2. Client to Resource Server 127 The use of OSCOAP for arbitrary CoAP messages is specified in [I- 128 D.selander-ace-object-security]. This section defines the specific 129 uses and their purpose for securing the communication between a 130 client and a resource server, and the parameters for to negotiating 131 the use of this profile with the token endpoint at the authorization 132 server as specified in section 6 of the ACE framework [I-D.ietf-ace- 133 oauth-authz]. 135 2.1. Signalling the use of OSCOAP 137 A client requesting a token at an AS via the /token endpoint MAY 138 signal a preference for using OSCOAP by including the "profile" 139 parameter with the value "coap_oscoap" in it's access token request. 140 This follows the message formats specified in section 6.1 of the ACE 141 framework. 143 The AS responding to a successful access token request as defined in 144 section 6.2 of the ACE framework can signal that the use of OSCOAP is 145 REQUIRED for a specific access token by including the "profile" 146 parameter with the value "coap_oscoap" in the access token response. 147 This means that the client MUST use OSCOAP towards all resource 148 servers for which this access token is valid. 150 The error response procedures defined in section 6.3 of the ACE 151 framework are unchanged by this profile. 153 Note the the client and the authorization server MAY OPTIONALLY use 154 OSCOAP to protect the interaction via the /token endpoint. See 155 section 3 for details. 157 2.2. Key establishment for OSCOAP Section 3.2 of OSCOAP [I-D.selander- 158 ace-object-security] defines how to derive a security context based 159 on a pre-shared secret established between client and server. If the 160 proof-of-possession key is a symmetric key, it MAY be directly used 161 as shared secret with OSCOAP. 163 However to provide forward secrecy and mutual authentication in the 164 case of pre-established raw public keys or with X.509 certificates it 165 is RECOMMENDED to use EDHOC [I-D.selander-ace-cose-ecdhe] to generate 166 the initial shared key. EDHOC MUST be used as follows: 168 When the client sends the access token to the RS using the /authz- 169 info endpoint as specified in section 8.1 of the ACE framework, this 170 message MUST carry message_1 of the EDHOC protocol in the CoAP 171 payload, and the access token MUST be included in the COSE 172 unprotected header of message_1 as a CBOR map with the key 173 'access_token'. 175 When the RS responds to this token submission request, if the access 176 token was valid the payload of the CoAP response MUST contain 177 message_2 of the EDHOC protocol. If the token was not valid, the 178 error response defined in the ACE framework is not modified. If the 179 EDHOC message_1 was not valid the RS MUST respond with error code 180 4.01 (Unauthorized). 182 In the case of EDHOC being used with symmetric pop-keys, the protocol 183 in section 3.4 of [I-D.selander-ace-cose-ecdhe] MUST be used. If the 184 pop-key is asymmetric, the RS MUST also use an asymmetric key for 185 authentication. This key is known to the client through the access 186 token response (see section 6.2 of the ACE framework). In this case 187 the protocol in section 3.5 of [I-D.selander-ace-cose-ecdhe] MUST be 188 used. 190 Note that if the OSCOAP profile is used, the /authz-info endpoint at 191 the Resource Server MUST be prepared to process and generate the 192 protocol messages of the EDHOC protocol as specified above. Hence 193 the use of EDHOC does not add any additional roundtrips to the ACE 194 message exchange. 196 Figure 1 illustrates the message exchanges for using EDHOC on the 197 authz-info endpoint. 198 Resource 199 Client Server 200 | | 201 | | 202 A: +-------->| Header: POST (Code=0.02) 203 | POST | Uri-Path:"authz-info" 204 | | Content-Type: application/cose+cbor 205 | | Payload: EDHOC message_1 + access token 206 | | 207 B: |<--------+ Header: 2.04 Changed 208 | | Content-Type: application/cose+cbor 209 | 2.05 | Payload: EDHOC message_2 210 | | 212 Figure 1: Key establishment with EDHOC via the authz-info endpoint 214 Figure 2 shows an example of message_1 with an access token embedded 215 in the unprotected header. 217 997( 218 [ 219 / protected / h'a201260444c150d41c', 220 / 'alg' : 'ES256', 'kid' : 'kid_c' / 222 / unprotected / {'access_token' : h'4a5015df6864286979'}, 223 / payload / h'83381a0c582fa120a50102024103200121582098f 224 50a4ff6c05861c8860d13a638ea56c3f5ad7590bbfbf054e1c7b4d9 225 1d628022f5', 226 / signature / h'eae868ecc1276883766c5dc5ba5b8dca25dab3c 227 2e56a51ce5705b793914348e14eea4aee6e0c9f09db4ef3ddeca8f3 228 506cd1a98a8fb64327be470355c9657ce0' 229 ] 230 ) 232 Figure 2: EDHOC message_1 with an access token 234 2.3. Securing the Resource Request 236 When the client wishes to send a request to the RS, it uses the steps 237 defined in section 6 of OSCOAP [I-D.selander-ace-object-security] to 238 generate an OSCOAP message out of the unsecured CoAP message. 240 2.4. Securing the Resource Server Response 242 When a RS responds to a client's request, it uses the steps defined 243 in section 6 of OSCOAP [I-D.selander-ace-object-security] to generate 244 an OSCOAP message out of the unsecured CoAP message. 246 3. Client to Authorization Server 248 As specified in the ACE framework section 5 [I-D.ietf-ace-oauth- 249 authz], the Client and AS can also use CoAP instead of HTTP to 250 communicate via the token endpoint. This section specifies how to 251 use OSCOAP between Client and AS together with CoAP. The use of 252 OSCOAP for this communication is OPTIONAL in this profile, other 253 security protocols (such as DTLS) MAY be used instead. 255 The client and the AS are expected to have pre-established 256 credentials (e.g. raw public keys). How these credentials are 257 established is out of scope for this profile. Furthermore the client 258 and the AS communicate using CoAP through the token endpoint as 259 specified in section 6 of [I-D.ietf-ace-oauth-authz]. At first point 260 of contact, prior to making the token request and response, the 261 client and the AS MUST perform an EDHOC exchange with the pre- 262 established credentials to create forward secret keying material for 263 use with OSCOAP. Subsequent requests and the responses MUST be 264 protected with OSCOAP. 266 4. Resource Server to Authorization Server 268 As specified in the ACE framework section 5 [I-D.ietf-ace-oauth- 269 authz], the RS and AS can also use CoAP instead of HTTP to 270 communicate via the introspection endpoint. This section specifies 271 how to use OSCOAP between RS and AS together with CoAP. The use of 272 OSCOAP for this communication is OPTIONAL in this profile, other 273 security protocols (such as DTLS) MAY be used instead. 275 The RS and the AS are expected to have pre-established credentials 276 (e.g. symmetric keys). How these credentials are established is out 277 of scope for this profile. Furthermore the RS and the AS communicate 278 using CoAP through the introspection endpoint as specified in section 279 7 of [I-D.ietf-ace-oauth-authz]. At first point of contact, prior to 280 making the introspection request and response, the RS and the AS MUST 281 perform an EDHOC exchange with the pre-established credentials to 282 create forward secret keying material for use with OSCOAP. 283 Subsequent requests and the responses MUST be protected with OSCOAP. 285 5. Security Considerations 287 TBD. 289 6. Privacy Considerations 291 TBD. 293 7. IANA Considerations 295 FIXME: PoP alg: OSCOAP 297 8. Acknowledgements 299 The author wishes to thank Goeran Selander and Francesca Palombini 300 for the input on this memo. 302 9. References 304 9.1 Normative References 306 [I-D.selander-ace-object-security] Selander, G., Mattsson J., 307 Palombini F., and L. Seitz. "Object Security of CoAP 308 (OSCOAP)", draft-selander-ace-object-security-04 (work in 309 progress), March 2016. 311 [I-D.selander-ace-cose-ecdhe] Selander, G., Mattsson J., 312 and F. Palombini. "Ephemeral Diffie-Hellman Over COSE 313 (EDHOC)", draft-selander-ace-cose-ecdhe-02 (work in 314 progress), June 2016. 316 [I-D.ietf-ace-oauth-authz] Seitz, L., Selander, G., 317 Wahlstroem, E., Erdtmann, S., and H. Tschofenig. 318 "Authentication and Authorization for Constrained 319 Environments (ACE)", drart-ietf-ace-oauth-authz-02 (work 320 in progress), June 2016. 322 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 323 Requirement Levels", BCP 14, RFC 2119, DOI 324 10.17487/RFC2119, March 1997, . 327 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 328 Application Protocol (CoAP)", RFC 7252, DOI 329 10.17487/RFC7252, June 2014, . 332 9.2 Informative References 334 [I-D.gerdes-ace-actors] 335 Gerdes, S., Seitz, L., G. Selander, and C. Bormann (ed). 336 "An Arhitecture for Authorization in Constrained 337 Environments", draft-ietf-ace-actors-03 (work in 338 progress), March 2016. 340 [I-D.ietf-cose-msg] Schaad, J., "CBOR Object Signing and 341 Encryption (COSE)", draft-ietf-cose-msg-14 (work in 342 progress), June 2016. 344 [RFC4949] Shirey, R., "Internet Security Glossary, Version 2", FYI 345 36, RFC 4949, DOI 10.17487/RFC4949, August 2007, 346 . 348 [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", 349 RFC 6749, DOI 10.17487/RFC6749, October 2012, 350 . 352 [RFC7231] Fielding, R., Ed., and J. Reschke, Ed., "Hypertext 353 Transfer Protocol (HTTP/1.1): Semantics and Content", 354 RFC 7231, DOI 10.17487/RFC7231, June 2014, 355 . 357 Author's Address 359 Ludwig Seitz 360 SICS Swedish ICT AB 361 Scheelevagen 17 362 22370 Lund 363 SWEDEN 364 EMail: ludwig@sics.se