idnits 2.17.1 draft-yusef-acme-3rd-party-device-attestation-01.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** There are 39 instances of too long lines in the document, the longest one being 7 characters in excess of 72. == There are 2 instances of lines with non-RFC2606-compliant FQDNs in the document. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == The document doesn't use any RFC 2119 keywords, yet seems to have RFC 2119 boilerplate text. == The document seems to contain a disclaimer for pre-RFC5378 work, but was first submitted on or after 10 November 2008. The disclaimer is usually necessary only for documents that revise or obsolete older RFCs, and that take significant amounts of text from those RFCs. If you can contact all authors of the source material and they are willing to grant the BCP78 rights to the IETF Trust, you can and should remove the disclaimer. Otherwise, the disclaimer is needed and you can ignore this comment. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (January 16, 2019) is 1898 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) -- Looks like a reference, but probably isn't: '01' on line 271 -- Looks like a reference, but probably isn't: '02' on line 282 -- Looks like a reference, but probably isn't: '03' on line 288 -- Looks like a reference, but probably isn't: '04' on line 246 -- Looks like a reference, but probably isn't: '05' on line 250 -- Looks like a reference, but probably isn't: '06' on line 254 == Missing Reference: 'JWT' is mentioned on line 217, but not defined -- Looks like a reference, but probably isn't: '07' on line 254 -- Looks like a reference, but probably isn't: '08' on line 257 == Missing Reference: 'CSR' is mentioned on line 223, but not defined -- Looks like a reference, but probably isn't: '09' on line 257 -- Looks like a reference, but probably isn't: '10' on line 260 -- Looks like a reference, but probably isn't: '11' on line 260 -- Looks like a reference, but probably isn't: '2' on line 239 -- Looks like a reference, but probably isn't: '3' on line 243 == Unused Reference: 'RFC6749' is defined on line 375, but no explicit reference was found in the text Summary: 1 error (**), 0 flaws (~~), 7 warnings (==), 14 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 ACME Working Group R. Shekh-Yusef 3 Internet-Draft Avaya 4 Intended status: Standards Track January 16, 2019 5 Expires: July 20, 2019 7 Third-Party Device Attestation for ACME 8 draft-yusef-acme-3rd-party-device-attestation-01 10 Abstract 12 This document defines a Third-Party Device Attestation for ACME 13 mechanism to allow the ACME CA to delegate some of its authentication 14 and authorization functions to a separate trusted entity, to automate 15 the issuance of certificates to devices. 17 Status of This Memo 19 This Internet-Draft is submitted in full conformance with the 20 provisions of BCP 78 and BCP 79. 22 Internet-Drafts are working documents of the Internet Engineering 23 Task Force (IETF). Note that other groups may also distribute 24 working documents as Internet-Drafts. The list of current Internet- 25 Drafts is at https://datatracker.ietf.org/drafts/current/. 27 Internet-Drafts are draft documents valid for a maximum of six months 28 and may be updated, replaced, or obsoleted by other documents at any 29 time. It is inappropriate to use Internet-Drafts as reference 30 material or to cite them other than as "work in progress." 32 This Internet-Draft will expire on July 20, 2019. 34 Copyright Notice 36 Copyright (c) 2019 IETF Trust and the persons identified as the 37 document authors. All rights reserved. 39 This document is subject to BCP 78 and the IETF Trust's Legal 40 Provisions Relating to IETF Documents 41 (https://trustee.ietf.org/license-info) in effect on the date of 42 publication of this document. Please review these documents 43 carefully, as they describe your rights and restrictions with respect 44 to this document. Code Components extracted from this document must 45 include Simplified BSD License text as described in Section 4.e of 46 the Trust Legal Provisions and are provided without warranty as 47 described in the Simplified BSD License. 49 This document may contain material from IETF Documents or IETF 50 Contributions published or made publicly available before November 51 10, 2008. The person(s) controlling the copyright in some of this 52 material may not have granted the IETF Trust the right to allow 53 modifications of such material outside the IETF Standards Process. 54 Without obtaining an adequate license from the person(s) controlling 55 the copyright in such materials, this document may not be modified 56 outside the IETF Standards Process, and derivative works of it may 57 not be created outside the IETF Standards Process, except to format 58 it for publication as an RFC or to translate it into languages other 59 than English. 61 Table of Contents 63 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 64 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3 65 2. Overview . . . . . . . . . . . . . . . . . . . . . . . . . . 3 66 2.1. Entities . . . . . . . . . . . . . . . . . . . . . . . . 3 67 2.2. Use Case . . . . . . . . . . . . . . . . . . . . . . . . 3 68 2.3. Initial Trust . . . . . . . . . . . . . . . . . . . . . . 4 69 2.4. Protocol Flow . . . . . . . . . . . . . . . . . . . . . . 5 70 3. Identifier Type . . . . . . . . . . . . . . . . . . . . . . . 7 71 4. Applying for a Certificate . . . . . . . . . . . . . . . . . 7 72 5. ACME Challenge . . . . . . . . . . . . . . . . . . . . . . . 7 73 6. Complete Authorization . . . . . . . . . . . . . . . . . . . 8 74 7. Device Access Token . . . . . . . . . . . . . . . . . . . . . 8 75 8. Security Considerations . . . . . . . . . . . . . . . . . . . 8 76 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 9 77 10. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 9 78 11. Normative References . . . . . . . . . . . . . . . . . . . . 9 79 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 9 81 1. Introduction 83 ACME [I-D.ietf-acme-acme] is a mechanism for automating certificate 84 management on the Internet. It enables administrative entities to 85 prove effective control over resources like domain names, and 86 automates the process of generating and issuing certificates. 88 Proving effective control over a device requires an attestation from 89 a third-party who has authority over the device. 91 This document defines a Third-Party Device Attestation for ACME 92 mechanism to allow the ACME CA to delegate some of its authentication 93 and authorization functions to a separate trusted entity, to automate 94 the issuance of certificates to devices. 96 1.1. Terminology 98 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 99 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 100 document are to be interpreted as described in [RFC2119]. 102 2. Overview 104 2.1. Entities 106 Device: this is an IP device, e.g. SIP phone, that is manufactured 107 by a Device Authority. 109 Device Authority: this is the Third-Party Device manufacturer that 110 has authority over the Device. 112 Client: this is a server that has authority over a domain and deploys 113 a Device and automatically obtains a certificate for it from ACME CA 114 with the Client's domain as an identifier. 116 ACME CA: this is the Certificate Authority (CA), e.g. Let's Encrypt, 117 that has a trust relationship with the above Device Authority, that 118 issues the certificate. 120 2.2. Use Case 122 Some devices come from the factory with a self-signed certificate 123 with the MAC of the device as the certificate identifier, and the 124 details of the certificates stored in a server in the cloud that acts 125 as the authority for these devices. 127 These self-signed certificates are used to authenticate the device 128 during a bootstrapping process, but are generally not useful to allow 129 the device to authenticate to other services the device interacts 130 with. 132 The use case is that the Client wants to deploy a Device manufactured 133 by a Device Authority and wants to be able to automatically obtain a 134 certificate for the Device from ACME CA with an identifier controlled 135 by the Client. 137 For example, if vendor.com is configured as a trusted entity on ACME 138 server, and if a device from vendor.com is being deployed by 139 customer.com, and customer.com requires the device to obtain an ACME 140 certificate, this mechanism allows the automatic issuance of 141 certificate to the device with a non-domain identifier, e.g. MAC, 142 based on attestation from vendor.com, and with the customer.com 143 identifier based on an existing Client account with the ACME server. 145 2.3. Initial Trust 147 This architecture assumes a trust relationship between the ACME CA 148 and the Third-Party Device Authority, which means that the ACME CA is 149 willing to accept the attestation of the Third-Party Device Authority 150 for particular types of identifiers as sufficient proof to issue a 151 certificate to a device with a non-domain identifier. 153 The following figure describes the various elements, the relationship 154 between these elements, and the OAuth role of each element. 156 OAuth AS OAuth RS 157 +-----------+ +-----------+ 158 | Device | | | 159 +------------>| Authority |<------------------------->| ACME CA | 160 | | | | | 161 | +-----------+ +-----------+ 162 | ^ 163 | | 164 | | 165 | | 166 +------+ | 167 |Device| | 168 +------+ | 169 | 170 | 171 | 172 | 173 +-----------+ 174 | | 175 | Client | 176 | | 177 +-----------+ 178 OAuth Client 180 The Device trusts the Device Authority. 182 The Device Authority and ACME CA trust each other. 184 The Client has an account with the Device Authority and is able to 185 claim devices manufactured by the Device Authority. The Client has 186 an account with ACME CA and able to request certificates for its 187 domain. 189 2.4. Protocol Flow 191 The following figure provides an overview of the interaction between 192 the ACME Client and ACME Server, as defined in [I-D.ietf-acme-acme], 193 with few changes to allow the Client to obtain an end entity 194 certificate for a Device based on an attestation from a Device 195 Authority: 197 Client Device Authority ACME CA 198 (customer.com) (as.vendor.com) (acme.com) 199 | | | 200 | [01] POST /new-order [kid=customer.com, url=vendor.com, identifier={mac}] 201 |------------------------------------------------------------------------>| 202 | | | 203 | [02] 201 | 204 | [authorizations=vendor.com/acme/authz/1234, | 205 | finalize=customer.com/acme/order/asdf/finalize] | 206 |<------------------------------------------------------------------------| 207 | | | 208 | [03] POST /vendor.com/acme/authz/1234 | 209 |------------------------------------------------------------------------>| 210 | | | 211 | [04] 401 Unauthorized [Link: as.vendor.com] | 212 |<------------------------------------------------------------------------| 213 | | | 214 | [05] Use OAuth to obtain a device JWT | 215 |<==================================>| | 216 | | | 217 | [06] POST /vendor.com/acme/authz/1234 [JWT] | 218 |------------------------------------------------------------------------>| 219 | | | 220 | | [07] 200 [status=valid] | 221 |<------------------------------------------------------------------------| 222 | | | 223 | [08] POST /customer.com/acme/order/asdf/finalize [CSR] | 224 |------------------------------------------------------------------------>| 225 | | | 226 | [09] 200 [certificate=customer.com/acme/cert/asdf] | 227 |<------------------------------------------------------------------------| 228 | | | 229 | [10] GET /customer.com/acme/cert/asdf | 230 |------------------------------------------------------------------------>| 231 | | | 232 | [11] 200 [certificate] | 233 |<------------------------------------------------------------------------| 234 | | | 235 In Step [01] the Client starts the process with a POST request, as 236 per [I-D.ietf-acme-acme], but the header contains a "kid" with the 237 Client domain and "url" with the AS URL. 239 In Step [2] the server replies with the authorization URL, as per 240 [I-D.ietf-acme-acme], but the authorization url contains the AS, and 241 the finalize URL points to the Client. 243 In Step [3] the Client starts the authorization process with an empty 244 payload, as per [I-D.ietf-acme-acme]. 246 In Step [04] the server indicates to the Client that it needs to 247 redirect the device to the AS to authenticate, and obtain an access 248 token. 250 Step [05] is out of scope for this document, which covers the 251 interaction between the Client, the Device, and the AS, to obtain an 252 access token for a device. 254 In Steps [06] and [07] the Client completes the authorization process 255 using the JWT obtained from the AS. 257 In Steps [08] and [09] the Client finalizes the process by sending 258 the CSR request to the server, as per [I-D.ietf-acme-acme]. 260 In Steps [10] and [11] the client downloads the certificate from the 261 server, as per [I-D.ietf-acme-acme]. 263 3. Identifier Type 265 This document introduces the new identifier type that will be used to 266 identify the device applying for a certificate with the ACME server, 267 e.g. { "type": "mac", "value": "112233445566" } 269 4. Applying for a Certificate 271 The process starts, step [01], when the Client sends a POST request 272 to the "/acme/new-order" resource on the ACME server. 274 The request object carries a protected header that contains a "kid" 275 with the Client domain and "url" with the Device Authority URL. The 276 request object carries a payload with the MAC identifier, as defined 277 above, that identifies the device that will be issued a certificate. 279 The signature carried in the request object is issued using the 280 Client account with the ACME server. 282 The ACME server responds with a 201, step [02] with an authorization 283 url that contains the Device Authority URL, and finalize ulr that 284 contains the Client URL. 286 5. ACME Challenge 288 In step [03] the Client starts the authorization process by sending a 289 POST request to the authorization URL with an empty body. In 290 response, the server replies with a 401 Unauthorized as defined in 291 [I-D.ietf-oauth-distributed]: 293 401 Unauthorized 294 WWW-Authenticate: Bearer error="invalid_token" 295 Link: 296 ;rel="oauth_server_metadata_uri" 297 ;requested_token_type="urn:ietf:params:oauth:token-type:jwt" 299 The WWW-Authenticate header includes an error parameter with the 300 value of "invalid_token" to indicate that a token is needed to 301 complete this request. 303 The Link header provides the details of the AS server and the type of 304 the token that the client must obtain for this request to be 305 processed by the server. 307 6. Complete Authorization 309 After obtaining the access token, the client completes the 310 authorization process by sending a POST request to the authorization 311 URL with the access token in the payload of the JWS object. 313 7. Device Access Token 315 The Device Authority must issue a device access token, in the form of 316 a JWT, to allow the Client to request the ACME CA to issue an end 317 entity certificate. 319 The payload of the JWT must include the following claims: 321 iss: contains the device authority url, e.g. as.vendor.com 323 sub: contains the device mac address. 325 aud: contains the Client domain, e.g. customer.com, and ACME CA url, 326 e.g. acme.com 328 The following is an example of a device access token: 330 Header: 331 { 332 "alg": "ES256", 333 "typ": "JWT" 334 } 336 Body: 337 { 338 "iss" : "as.vendor.com", 339 "sub": "112233445566", // Device MAC address 340 "aud" : ["custmer.com", "acme.com"] 341 } 343 8. Security Considerations 345 TODO 347 9. IANA Considerations 349 TODO 351 10. Acknowledgments 353 The author would like to thank Dick Hardt for his reviews and 354 valuable feedback on the pre-published version of this draft. 356 The author would like to thank Ilari Liusvaara and Ryan Sleevi for 357 their careful review and feedback. 359 11. Normative References 361 [I-D.ietf-acme-acme] 362 Barnes, R., Hoffman-Andrews, J., McCarney, D., and J. 363 Kasten, "Automatic Certificate Management Environment 364 (ACME)", https://datatracker.ietf.org/doc/draft-ietf- 365 acme-acme/, April 2018. 367 [I-D.ietf-oauth-distributed] 368 Hardt, D., Campbell, B., and N. Sakimura, "Distributed 369 OAuth", https://datatracker.ietf.org/doc/draft-ietf- 370 oauth-distributed/, October 2018. 372 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 373 Requirement Levels", RFC 2119, March 1997. 375 [RFC6749] Hardt, D., "The OAuth 2.0 Authorization Framework", 376 RFC 6749, October 2012. 378 Author's Address 380 Rifaat Shekh-Yusef 381 Avaya 382 250 Sidney Street 383 Belleville, Ontario 384 Canada 386 Phone: +1-613-967-5176 387 EMail: rifaat.ietf@gmail.com