idnits 2.17.1 draft-friel-acme-subdomains-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 (October 23, 2019) is 1644 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) No issues found here. Summary: 0 errors (**), 0 flaws (~~), 1 warning (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group O. Friel 3 Internet-Draft R. Barnes 4 Intended status: Standards Track Cisco 5 Expires: April 25, 2020 T. Hollebeek 6 DigiCert 7 October 23, 2019 9 ACME for Subdomains 10 draft-friel-acme-subdomains-00 12 Abstract 14 This document outlines how ACME can be used by a client to obtain a 15 certificate for a subdomain identifier from a certificate authority. 16 The client has fulfilled a challenge against a parent domain but does 17 not need to fulfil a challenge against the explicit subdomain as 18 certificate authority policy allows issuance of the subdomain 19 certificate without explicit subdomain ownership proof. 21 Status of This Memo 23 This Internet-Draft is submitted in full conformance with the 24 provisions of BCP 78 and BCP 79. 26 Internet-Drafts are working documents of the Internet Engineering 27 Task Force (IETF). Note that other groups may also distribute 28 working documents as Internet-Drafts. The list of current Internet- 29 Drafts is at https://datatracker.ietf.org/drafts/current/. 31 Internet-Drafts are draft documents valid for a maximum of six months 32 and may be updated, replaced, or obsoleted by other documents at any 33 time. It is inappropriate to use Internet-Drafts as reference 34 material or to cite them other than as "work in progress." 36 This Internet-Draft will expire on April 25, 2020. 38 Copyright Notice 40 Copyright (c) 2019 IETF Trust and the persons identified as the 41 document authors. All rights reserved. 43 This document is subject to BCP 78 and the IETF Trust's Legal 44 Provisions Relating to IETF Documents 45 (https://trustee.ietf.org/license-info) in effect on the date of 46 publication of this document. Please review these documents 47 carefully, as they describe your rights and restrictions with respect 48 to this document. Code Components extracted from this document must 49 include Simplified BSD License text as described in Section 4.e of 50 the Trust Legal Provisions and are provided without warranty as 51 described in the Simplified BSD License. 53 Table of Contents 55 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 56 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 2 57 3. ACME Workflow and Identifier Requirements . . . . . . . . . . 3 58 4. ACME Issuance of Subdomain Certificates . . . . . . . . . . . 4 59 4.1. newOrder and newAuthz Handling . . . . . . . . . . . . . 5 60 4.2. Examples . . . . . . . . . . . . . . . . . . . . . . . . 6 61 5. Directory Object Metadata Fields Registry . . . . . . . . . . 7 62 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 7 63 7. Security Considerations . . . . . . . . . . . . . . . . . . . 8 64 8. Informative References . . . . . . . . . . . . . . . . . . . 8 65 Appendix A. CA Browser Forum Baseline Requirements . . . . . . . 8 66 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 8 68 1. Introduction 70 ACME [RFC8555] defines a protocol that a certificate authority (CA) 71 and an applicant can use to automate the process of domain name 72 ownership validation and X.509 (PKIX) certificate issuance. The 73 protocol is rich and flexible and enables multiple use cases that are 74 not immediately obvious from reading the specification. 76 This document explicitly outlines how ACME can be used to issue 77 subdomain certificates, without requiring the ACME client to 78 explicitly fulfil an ownership challenge against the subdomain 79 identifiers - the ACME client need only fulfil an ownership challenge 80 against a parent domain identifier. 82 2. Terminology 84 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 85 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 86 "OPTIONAL" in this document are to be interpreted as described in BCP 87 14 [RFC2119] [RFC8174] when, and only when, they appear in all 88 capitals, as shown here. 90 The following terms are used in this document: 92 o CA: Certificate Authority 94 o CSR: Certificate Signing Request 96 o FQDN: Fully Qualified Domain Name 98 3. ACME Workflow and Identifier Requirements 100 A typical ACME workflow for issuance of certificates is as follows: 102 1. client POSTs a newOrder request that contains a set of 103 "identifiers" 105 2. server replies with a set of "authorizations" and a "finalize" 106 URI 108 3. client sends POST-as-GET requests to retrieve the 109 "authorizations", with the downloaded "authorization" object(s) 110 containing the "identifier" that the client must prove control of 112 4. client proves control over the "identifier" in the 113 "authorization" object by completing the specified challenge, for 114 example, by publishing a DNS TXT record 116 5. client POSTs a CSR to the "finalize" API 118 6. server replies with an updated order object that includes a 119 "certificate" URI 121 7. client sends POST-as-GET request to the "certificate" URI to 122 download the certificate 124 ACME places the following restrictions on "identifiers": 126 o section 7.1.4: the only type of "identifier" defined by the ACME 127 specification is a fully qualified domain name: "The only type of 128 identifier defined by this specification is a fully qualified 129 domain name (type: "dns"). The domain name MUST be encoded in the 130 form in which it would appear in a certificate." 132 o Section 7.4: the "identifier" in the CSR request must match the 133 "identifier" in the newOrder request: "The CSR MUST indicate the 134 exact same set of requested identifiers as the initial newOrder 135 request." 137 o Sections 8.3: the "identifier", or FQDN, in the "authorization" 138 object must be used when fulfilling challenges via HTTP: 139 "Construct a URL by populating the URL template ... where the 140 domain field is set to the domain name being verified" 142 o Section 8.4: the "identifier", or FQDN, in the "authorization" 143 object must be used when fulfilling challenges via DNS: "The 144 client constructs the validation domain name by prepending the 145 label "_acme-challenge" to the domain name being validated." 147 ACME does not mandate that the "identifier" in a newOrder request 148 matches the "identifier" in "authorization" objects. 150 4. ACME Issuance of Subdomain Certificates 152 As noted in the previous section, ACME does not mandate that the 153 "identifier" in a newOrder request matches the "identifier" in 154 "authorization" objects. This means that the ACME specification does 155 not preclude an ACME server processing newOrder requests and issuing 156 certificates for a subdomain without requiring a challenge to be 157 fulfilled against that explicit subdomain. ACME server policy could 158 allow issuance of certificates for a subdomain to a client where the 159 client only has to fulfil an authorization challenge for the parent 160 domain. The relevant sections from current CA/Browser baseline 161 requirements are given in section Appendix A. 163 This allows a flow where a client proves ownership of, for example, 164 "example.com" and then successfully obtains a certificate for 165 "sub.example.com". The ACME pre-authorization flow makes most sense 166 for this use case, and that is what is illustrated in the following 167 call flow. 169 The client could pre-authorize for the parent domain once, and then 170 issue multiple newOrder requests for certificates for multiple 171 subdomains. This call flow illustrates the client only placing one 172 newOrder request. 174 The call flow illustrates the DNS-based proof of ownership mechanism, 175 but the subdomain workflow is equally valid for HTTP based proof of 176 ownership. 178 +--------+ +------+ +-----+ 179 | Client | | ACME | | DNS | 180 +--------+ +------+ +-----+ 181 | | | 182 STEP 1: Pre-Authorization of parent domain 183 | | | 184 | POST /newAuthz | | 185 | "example.com" | | 186 |--------------------->| | 187 | | | 188 | 201 authorizations | | 189 |<---------------------| | 190 | | | 191 | Publish DNS TXT | | 192 | "example.com" | | 193 |--------------------------------->| 194 | | | 195 | POST /challenge | | 196 |--------------------->| | 197 | | Verify | 198 | |---------->| 199 | 200 status=valid | | 200 |<---------------------| | 201 | | | 202 | Delete DNS TXT | | 203 | "example.com" | | 204 |--------------------------------->| 205 | | | 206 STEP 2: Place order for subdomain 207 | | | 208 | POST /newOrder | | 209 | "sub.example.com" | | 210 |--------------------->| | 211 | | | 212 | 201 status=ready | | 213 |<---------------------| | 214 | | | 215 | POST /finalize | | 216 | CSR "sub.example.com"| | 217 |--------------------->| | 218 | | | 219 | 200 OK status=valid | | 220 |<---------------------| | 221 | | | 222 | POST /certificate | | 223 |--------------------->| | 224 | | | 225 | 200 OK | | 226 | PKI "sub.example.com"| | 227 |<---------------------| | 229 4.1. newOrder and newAuthz Handling 231 Servers may consider validation of a parent domain sufficient 232 authorization for a subdomain. If a server has such a policy and a 233 client is already authorized for the parent domain then: 235 o If the client submits a newAuthz request for a subdomain: The 236 server MUST return status 200 (OK) response. The response body is 237 the existing authorization object for the parent domain with 238 status set to "valid". 240 o If the client submits a newOrder request for a subdomain: The 241 server MUST return a 201 (Created) response. The response body is 242 an order object with status set to "ready" and links to the 243 unexpired authorizations against the parent domain. 245 If a server has such a policy and a client is not authorized for the 246 parent domain then: 248 o If the client submits a newAuthz request for a subdomain: The 249 server MUST return a status 201 (Created) response. The response 250 body is a newly created authorization object for the parent domain 251 with status set to "pending". 253 o If the client submits a newOrder request for a subdomain: The 254 server MUST return a status 201 (Created) response. The response 255 body is an order object with status set to "pending" and links to 256 newly created authorizations objects against the parent domain. 258 [[ TODO: This section documents a change from RFC8555, which states 259 that the identifier in the newAuthz request MUST match that in the 260 authorization object. 262 Additionally, 200 response code is used here in one scenario instead 263 of a 201 response. However, this is arguably an under-specification 264 in RFC8555, and has been reported in https://www.rfc- 265 editor.org/errata/eid5861. 267 These two items need a review. ]] 269 4.2. Examples 271 In order to illustrate subdomain behaviour, let us assume that a 272 client wishes to get certificates for subdomain identifiers 273 "sub0.example.com", "sub1.example.com" and "sub2.example.com" under 274 parent domain "example.com", and CA policy allows certificate 275 issuance of these subdomain identifiers while only requiring the 276 client to fulfil an ownership challenge for parent domain 277 "example.com". Let us also assume that the client has not yet proven 278 ownership of parent domain "example.com". 280 1. The client POSTs a newOrder request for identifier 281 "sub0.example.com" 283 The server creates an authorization object for identifier 284 "example.com". The server replies with a 201 (Created) response. 285 The response body is an order object with status set to "pending" and 286 a link to newly created authorization object against the parent 287 domain "example.com". Therefore, the server is instructing the 288 client to fulfil a challenge against domain identifier "example.com" 289 in order to obtain a certificate including identifier 290 "sub0.example.com". 292 The client completes the challenge for "example.com", POSTs a CSR to 293 the order finalize URI, and downloads the certificate. 295 1. The client POSTs a newOrder request for identifier 296 "sub1.example.com" 298 The server replies with a 201 (Created) response. The response body 299 is an order object with status set to "ready" and a link to the 300 unexpired authorization against the parent domain "example.com". 302 The client POSTs a CSR to the order finalize URI, and downloads the 303 certificate. 305 1. The client POSTs a newAuthz request for identifier 306 "sub2.example.com" 308 The server replies with a 200 (OK) response. The response body is 309 the previously created authorization object for "example.com" with 310 status set to "valid". 312 5. Directory Object Metadata Fields Registry 314 [[ TODO: is this required? ]] 316 An ACME server can advertise support of issuance of subdomain 317 certificates by including the boolean field 318 "implicitSubdomainAuthorization" in its "ACME Directory Metadata 319 Fields" registry. If not specified, then no default value is 320 assumed. If an ACME server supports issuance of subdomain 321 certificates, it can indicate this by including this field with a 322 value of "true". 324 +--------------------------------+------------+-----------+ 325 | Field Name | Field Type | Reference | 326 +--------------------------------+------------+-----------+ 327 | implicitSubdomainAuthorization | boolean | RFC XXXX | 328 +--------------------------------+------------+-----------+ 330 6. IANA Considerations 332 [[TODO: register implicitSubdomainAuthorization? ]] 334 7. Security Considerations 336 [[TODO]] 338 8. Informative References 340 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 341 Requirement Levels", BCP 14, RFC 2119, 342 DOI 10.17487/RFC2119, March 1997, 343 . 345 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 346 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 347 May 2017, . 349 [RFC8555] Barnes, R., Hoffman-Andrews, J., McCarney, D., and J. 350 Kasten, "Automatic Certificate Management Environment 351 (ACME)", RFC 8555, DOI 10.17487/RFC8555, March 2019, 352 . 354 Appendix A. CA Browser Forum Baseline Requirements 356 The CA/Browser Forum Baseline Requirements version 1.6.5 states: 358 o Section: "1.6.1 Definitions": Authorization Domain Name: The 359 Domain Name used to obtain authorization for certificate issuance 360 for a given FQDN. The CA may use the FQDN returned from a DNS 361 CNAME lookup as the FQDN for the purposes of domain validation. 362 If the FQDN contains a wildcard character, then the CA MUST remove 363 all wildcard labels from the left most portion of requested FQDN. 364 The CA may prune zero or more labels from left to right until 365 encountering a Base Domain Name and may use any one of the 366 intermediate values for the purpose of domain validation. 368 o Section: "3.2.2.4.7 DNS Change": Once the FQDN has been validated 369 using this method, the CA MAY also issue Certificates for other 370 FQDNs that end with all the labels of the validated FQDN. This 371 method is suitable for validating Wildcard Domain Names. 373 Authors' Addresses 375 Owen Friel 376 Cisco 378 Email: ofriel@cisco.com 379 Richard Barnes 380 Cisco 382 Email: rlb@ipv.sx 384 Tim Hollebeek 385 DigiCert 387 Email: tim.hollebeek@digicert.com