idnits 2.17.1 draft-yusef-acme-3rd-party-device-attestation-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 : ---------------------------------------------------------------------------- ** 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 12, 2019) is 1924 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 270 -- Looks like a reference, but probably isn't: '02' on line 281 -- Looks like a reference, but probably isn't: '03' on line 287 -- Looks like a reference, but probably isn't: '04' on line 245 -- Looks like a reference, but probably isn't: '05' on line 249 -- Looks like a reference, but probably isn't: '06' on line 253 == Missing Reference: 'JWT' is mentioned on line 216, but not defined -- Looks like a reference, but probably isn't: '07' on line 253 -- Looks like a reference, but probably isn't: '08' on line 256 == Missing Reference: 'CSR' is mentioned on line 222, but not defined -- Looks like a reference, but probably isn't: '09' on line 256 -- Looks like a reference, but probably isn't: '10' on line 259 -- Looks like a reference, but probably isn't: '11' on line 259 -- Looks like a reference, but probably isn't: '2' on line 238 -- Looks like a reference, but probably isn't: '3' on line 242 == Unused Reference: 'RFC6749' is defined on line 371, 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 12, 2019 5 Expires: July 16, 2019 7 Third-Party Device Attestation for ACME 8 draft-yusef-acme-3rd-party-device-attestation-00 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 16, 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 a 139 customer.com, and customer.com requires the device to obtain an ACME 140 certificate, this mechanism allows the automatic issuance of 141 certificates to the device with the customer.com identifier based on 142 attestation from vendor.com. 144 2.3. Initial Trust 146 This architecture assumes a trust relationship between the ACME CA 147 and the Third-Party Device Authority, which means that the ACME CA is 148 willing to accept the attestation of the Third-Party Device Authority 149 for particular types of identifiers as sufficient proof to issue a 150 certificate. 152 The following figure describes the various elements, the relationship 153 between these elements, and the OAuth role of each element. 155 OAuth AS OAuth RS 156 +-----------+ +-----------+ 157 | Device | | | 158 +------------>| Authority |<------------------------->| ACME CA | 159 | | | | | 160 | +-----------+ +-----------+ 161 | ^ 162 | | 163 | | 164 | | 165 +------+ | 166 |Device| | 167 +------+ | 168 | 169 | 170 | 171 | 172 +-----------+ 173 | | 174 | Client | 175 | | 176 +-----------+ 177 OAuth Client 179 The Device trusts the Device Authority. 181 The Device Authority and ACME CA trust each other. 183 The Client has an account with the Device Authority and is able to 184 claim devices manufactured by the Device Authority. The Client has 185 an account with ACME CA and able to request certificates for its 186 domain. 188 2.4. Protocol Flow 190 The following figure provides an overview of the interaction between 191 the ACME Client and ACME Server, as defined in [I-D.ietf-acme-acme], 192 with few changes to allow the Client to obtain an end entity 193 certificate for a Device based on an attestation from a Device 194 Authority: 196 Client Device Authority ACME CA 197 (customer.com) (as.vendor.com) (acme.com) 198 | | | 199 | [01] POST /new-order [kid=customer.com, url=vendor.com, identifier={mac}] 200 |------------------------------------------------------------------------>| 201 | | | 202 | [02] 201 | 203 | [authorizations=vendor.com/acme/authz/1234, | 204 | finalize=customer.com/acme/order/asdf/finalize] | 205 |<------------------------------------------------------------------------| 206 | | | 207 | [03] POST /vendor.com/acme/authz/1234 | 208 |------------------------------------------------------------------------>| 209 | | | 210 | [04] 401 Unauthorized [Link: as.vendor.com] | 211 |<------------------------------------------------------------------------| 212 | | | 213 | [05] Use OAuth to obtain a device JWT | 214 |<==================================>| | 215 | | | 216 | [06] POST /vendor.com/acme/authz/1234 [JWT] | 217 |------------------------------------------------------------------------>| 218 | | | 219 | | [07] 200 [status=valid] | 220 |<------------------------------------------------------------------------| 221 | | | 222 | [08] POST /customer.com/acme/order/asdf/finalize [CSR] | 223 |------------------------------------------------------------------------>| 224 | | | 225 | [09] 200 [certificate=customer.com/acme/cert/asdf] | 226 |<------------------------------------------------------------------------| 227 | | | 228 | [10] GET /customer.com/acme/cert/asdf | 229 |------------------------------------------------------------------------>| 230 | | | 231 | [11] 200 [certificate] | 232 |<------------------------------------------------------------------------| 233 | | | 234 In Step [01] the Client starts the process with a POST request, as 235 per [I-D.ietf-acme-acme], but the header contains a "kid" with the 236 Client domain and "url" with the AS URL. 238 In Step [2] the server replies with the authorization URL, as per 239 [I-D.ietf-acme-acme], but the authorization url contains the AS, and 240 the finalize URL points to the Client. 242 In Step [3] the Client starts the authorization process with an empty 243 payload, as per [I-D.ietf-acme-acme]. 245 In Step [04] the server indicates to the Client that it needs to 246 redirect the device to the AS to authenticate, and obtain an access 247 token. 249 Step [05] is out of scope for this document, which covers the 250 interaction between the Client, the Device, and the AS, to obtain an 251 access token for a device. 253 In Steps [06] and [07] the Client completes the authorization process 254 using the JWT obtained from the AS. 256 In Steps [08] and [09] the Client finalizes the process by sending 257 the CSR request to the server, as per [I-D.ietf-acme-acme]. 259 In Steps [10] and [11] the client downloads the certificate from the 260 server, as per [I-D.ietf-acme-acme]. 262 3. Identifier Type 264 This document introduces the new identifier type that will be used to 265 identify the device applying for a certificate with the ACME server, 266 e.g. { "type": "mac", "value": "112233445566" } 268 4. Applying for a Certificate 270 The process starts, step [01], when the Client sends a POST request 271 to the "/acme/new-order" resource on the ACME server. 273 The request object carries a protected header that contains a "kid" 274 with the Client domain and "url" with the Device Authority URL. The 275 request object carries a payload with the MAC identifier, as defined 276 above, that identifies the device that will be issued a certificate. 278 The signature carried in the request object is issued using the 279 Client account with the ACME server. 281 The ACME server responds with a 201, step [02] with an authorization 282 url that contains the Device Authority URL, and finalize ulr that 283 contains the Client URL. 285 5. ACME Challenge 287 In step [03] the Client starts the authorization process by sending a 288 POST request to the authorization URL with an empty body. In 289 response, the server replies with a 401 Unauthorized as defined in 290 [I-D.ietf-oauth-distributed]: 292 401 Unauthorized 293 WWW-Authenticate: Bearer error="invalid_token" 294 Link: 295 ;rel="oauth_server_metadata_uri" 296 ;requested_token_type="urn:ietf:params:oauth:token-type:jwt" 298 The WWW-Authenticate header includes an error parameter with the 299 value of "invalid_token" to indicate that a token is needed to 300 complete this request. 302 The Link header provides the details of the AS server and the type of 303 the token that the client must obtain for this request to be 304 processed by the server. 306 6. Complete Authorization 308 After obtaining the access token, the client completes the 309 authorization process by sending a POST request to the authorization 310 URL with the access token in the payload of the JWS object. 312 7. Device Access Token 314 The Device Authority must issue a device access token, in the form of 315 a JWT, to allow the Client to request the ACME CA to issue an end 316 entity certificate. 318 The payload of the JWT must include the following claims: 320 iss: contains the device authority url, e.g. as.vendor.com 322 sub: contains the device mac address. 324 aud: contains the Client domain, e.g. customer.com, and ACME CA url, 325 e.g. acme.com 327 The following is an example of a device access token: 329 Header: 330 { 331 "alg": "ES256", 332 "typ": "JWT" 333 } 335 Body: 336 { 337 "iss" : "as.vendor.com", 338 "sub": "112233445566", // Device MAC address 339 "aud" : ["custmer.com", "acme.com"] 340 } 342 8. Security Considerations 344 TODO 346 9. IANA Considerations 348 TODO 350 10. Acknowledgments 352 The author would like to thank Dick Hardt for his reviews and 353 valuable feedback on the pre-published version of this draft. 355 11. Normative References 357 [I-D.ietf-acme-acme] 358 Barnes, R., Hoffman-Andrews, J., McCarney, D., and J. 359 Kasten, "Automatic Certificate Management Environment 360 (ACME)", https://datatracker.ietf.org/doc/draft-ietf- 361 acme-acme/, April 2018. 363 [I-D.ietf-oauth-distributed] 364 Hardt, D., Campbell, B., and N. Sakimura, "Distributed 365 OAuth", https://datatracker.ietf.org/doc/draft-ietf- 366 oauth-distributed/, October 2018. 368 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 369 Requirement Levels", RFC 2119, March 1997. 371 [RFC6749] Hardt, D., "The OAuth 2.0 Authorization Framework", 372 RFC 6749, October 2012. 374 Author's Address 376 Rifaat Shekh-Yusef 377 Avaya 378 250 Sidney Street 379 Belleville, Ontario 380 Canada 382 Phone: +1-613-967-5176 383 EMail: rifaat.ietf@gmail.com