idnits 2.17.1 draft-friel-acme-subdomains-02.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 (March 06, 2020) is 1505 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: September 7, 2020 T. Hollebeek 6 DigiCert 7 M. Richardson 8 Sandelman Software Works 9 March 06, 2020 11 ACME for Subdomains 12 draft-friel-acme-subdomains-02 14 Abstract 16 This document outlines how ACME can be used by a client to obtain a 17 certificate for a subdomain identifier from a certificate authority. 18 The client has fulfilled a challenge against a parent domain but does 19 not need to fulfil a challenge against the explicit subdomain as 20 certificate authority policy allows issuance of the subdomain 21 certificate without explicit subdomain ownership proof. 23 Status of This Memo 25 This Internet-Draft is submitted in full conformance with the 26 provisions of BCP 78 and BCP 79. 28 Internet-Drafts are working documents of the Internet Engineering 29 Task Force (IETF). Note that other groups may also distribute 30 working documents as Internet-Drafts. The list of current Internet- 31 Drafts is at https://datatracker.ietf.org/drafts/current/. 33 Internet-Drafts are draft documents valid for a maximum of six months 34 and may be updated, replaced, or obsoleted by other documents at any 35 time. It is inappropriate to use Internet-Drafts as reference 36 material or to cite them other than as "work in progress." 38 This Internet-Draft will expire on September 7, 2020. 40 Copyright Notice 42 Copyright (c) 2020 IETF Trust and the persons identified as the 43 document authors. All rights reserved. 45 This document is subject to BCP 78 and the IETF Trust's Legal 46 Provisions Relating to IETF Documents 47 (https://trustee.ietf.org/license-info) in effect on the date of 48 publication of this document. Please review these documents 49 carefully, as they describe your rights and restrictions with respect 50 to this document. Code Components extracted from this document must 51 include Simplified BSD License text as described in Section 4.e of 52 the Trust Legal Provisions and are provided without warranty as 53 described in the Simplified BSD License. 55 Table of Contents 57 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 58 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 2 59 3. ACME Workflow and Identifier Requirements . . . . . . . . . . 3 60 4. ACME Issuance of Subdomain Certificates . . . . . . . . . . . 4 61 4.1. Pre-Authorization . . . . . . . . . . . . . . . . . . . . 4 62 4.2. Illustrative Call Flow . . . . . . . . . . . . . . . . . 5 63 4.3. newOrder and newAuthz Handling . . . . . . . . . . . . . 6 64 4.4. Examples . . . . . . . . . . . . . . . . . . . . . . . . 7 65 5. Resource Enhancements . . . . . . . . . . . . . . . . . . . . 8 66 5.1. Authorization Object . . . . . . . . . . . . . . . . . . 8 67 5.2. Directory Object Metadata . . . . . . . . . . . . . . . . 8 68 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 8 69 6.1. Authorization Object Fields Registry . . . . . . . . . . 8 70 6.2. Directory Object Metadata Fields Registry . . . . . . . . 8 71 7. Security Considerations . . . . . . . . . . . . . . . . . . . 9 72 8. Informative References . . . . . . . . . . . . . . . . . . . 9 73 Appendix A. ACME Server Policy Considerations . . . . . . . . . 9 74 A.1. CA Browser Forum Baseline Requirements Extracts . . . . . 10 75 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 10 77 1. Introduction 79 ACME [RFC8555] defines a protocol that a certificate authority (CA) 80 and an applicant can use to automate the process of domain name 81 ownership validation and X.509 (PKIX) certificate issuance. This 82 document outlines how ACME can be used to issue subdomain 83 certificates, without requiring the ACME client to explicitly fulfil 84 an ownership challenge against the subdomain identifiers - the ACME 85 client need only fulfil an ownership challenge against a parent 86 domain identifier. 88 2. Terminology 90 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 91 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 92 "OPTIONAL" in this document are to be interpreted as described in BCP 93 14 [RFC2119] [RFC8174] when, and only when, they appear in all 94 capitals, as shown here. 96 The following terms are used in this document: 98 o CA: Certificate Authority 100 o CSR: Certificate Signing Request 102 o FQDN: Fully Qualified Domain Name 104 3. ACME Workflow and Identifier Requirements 106 A typical ACME workflow for issuance of certificates is as follows: 108 1. client POSTs a newOrder request that contains a set of 109 "identifiers" 111 2. server replies with a set of "authorizations" and a "finalize" 112 URI 114 3. client sends POST-as-GET requests to retrieve the 115 "authorizations", with the downloaded "authorization" object(s) 116 containing the "identifier" that the client must prove control of 118 4. client proves control over the "identifier" in the 119 "authorization" object by completing the specified challenge, for 120 example, by publishing a DNS TXT record 122 5. client POSTs a CSR to the "finalize" API 124 6. server replies with an updated order object that includes a 125 "certificate" URI 127 7. client sends POST-as-GET request to the "certificate" URI to 128 download the certificate 130 ACME places the following restrictions on "identifiers": 132 o section 7.1.4: the only type of "identifier" defined by the ACME 133 specification is a fully qualified domain name: "The only type of 134 identifier defined by this specification is a fully qualified 135 domain name (type: "dns"). The domain name MUST be encoded in the 136 form in which it would appear in a certificate." 138 o Section 7.4: the "identifier" in the CSR request must match the 139 "identifier" in the newOrder request: "The CSR MUST indicate the 140 exact same set of requested identifiers as the initial newOrder 141 request." 143 o Sections 8.3: the "identifier", or FQDN, in the "authorization" 144 object must be used when fulfilling challenges via HTTP: 146 "Construct a URL by populating the URL template ... where the 147 domain field is set to the domain name being verified" 149 o Section 8.4: the "identifier", or FQDN, in the "authorization" 150 object must be used when fulfilling challenges via DNS: "The 151 client constructs the validation domain name by prepending the 152 label "_acme-challenge" to the domain name being validated." 154 ACME does not mandate that the "identifier" in a newOrder request 155 matches the "identifier" in "authorization" objects. 157 4. ACME Issuance of Subdomain Certificates 159 As noted in the previous section, ACME does not mandate that the 160 "identifier" in a newOrder request matches the "identifier" in 161 "authorization" objects. This means that the ACME specification does 162 not preclude an ACME server processing newOrder requests and issuing 163 certificates for a subdomain without requiring a challenge to be 164 fulfilled against that explicit subdomain. 166 ACME server policy could allow issuance of certificates for a 167 subdomain to a client where the client only has to fulfil an 168 authorization challenge for a parent domain of that subdomain. This 169 allows a flow where a client proves ownership of, for example, 170 "example.com" and then successfully obtains a certificate for 171 "sub.example.com". 173 ACME server policy is out of scope of this document, however some 174 commentary is provided in Appendix A. 176 4.1. Pre-Authorization 178 The standard ACME workflow has authorization objects created 179 reactively in response to a certificate order. ACME also allows for 180 pre-authorization, where clients obtain authorization for an 181 identifier proactively, outside of the context of a specific 182 issuance. This document allows for both workflows, and Section 4.3 183 outlines how the ACME server handles newOrder and newAuthz requests 184 for both workflows. 186 It may make sense to use the ACME pre-authorization flow for the 187 subdomain use case, however, that is an operator implementation and 188 deployment decision. With the ACME pre-authorization flow, the 189 client could pre-authorize for the parent domain once, and then issue 190 multiple newOrder requests for certificates for multiple subdomains. 192 4.2. Illustrative Call Flow 194 The call flow illustrated here uses the ACME pre-authorization flow. 195 The call flow also illustrates the DNS-based proof of ownership 196 mechanism, but the subdomain workflow is equally valid for HTTP based 197 proof of ownership. 199 +--------+ +------+ +-----+ 200 | Client | | ACME | | DNS | 201 +--------+ +------+ +-----+ 202 | | | 203 STEP 1: Pre-Authorization of parent domain 204 | | | 205 | POST /newAuthz | | 206 | "example.com" | | 207 |--------------------->| | 208 | | | 209 | 201 authorizations | | 210 |<---------------------| | 211 | | | 212 | Publish DNS TXT | | 213 | "example.com" | | 214 |--------------------------------->| 215 | | | 216 | POST /challenge | | 217 |--------------------->| | 218 | | Verify | 219 | |---------->| 220 | 200 status=valid | | 221 |<---------------------| | 222 | | | 223 | Delete DNS TXT | | 224 | "example.com" | | 225 |--------------------------------->| 226 | | | 227 STEP 2: Place order for subdomain 228 | | | 229 | POST /newOrder | | 230 | "sub.example.com" | | 231 |--------------------->| | 232 | | | 233 | 201 status=ready | | 234 |<---------------------| | 235 | | | 236 | POST /finalize | | 237 | CSR "sub.example.com"| | 238 |--------------------->| | 239 | | | 240 | 200 OK status=valid | | 241 |<---------------------| | 242 | | | 243 | POST /certificate | | 244 |--------------------->| | 245 | | | 246 | 200 OK | | 247 | PKI "sub.example.com"| | 248 |<---------------------| | 250 4.3. newOrder and newAuthz Handling 252 Servers may consider validation of a parent domain sufficient 253 authorization for a subdomain. If a server has such a policy and a 254 client is already authorized for the parent domain then: 256 o If the client submits a newAuthz request for a subdomain: The 257 server MUST return status 200 (OK) response. The response body is 258 the existing authorization object for the parent domain with 259 status set to "valid". 261 o If the client submits a newOrder request for a subdomain: The 262 server MUST return a 201 (Created) response. The response body is 263 an order object with status set to "ready" and links to the 264 unexpired authorizations against the parent domain. 266 If a server has such a policy and a client is not authorized for the 267 parent domain then: 269 o If the client submits a newAuthz request for a subdomain: The 270 server MUST return a status 201 (Created) response. The response 271 body is a newly created authorization object for the parent domain 272 with status set to "pending". 274 o If the client submits a newOrder request for a subdomain: The 275 server MUST return a status 201 (Created) response. The response 276 body is an order object with status set to "pending" and links to 277 newly created authorizations objects against the parent domain. 279 [[ TODO: This section documents a change from RFC8555 section 7.4.1 280 which states "Note that because the identifier in a pre-authorization 281 request is the exact identifier to be included in the authorization 282 object, pre-authorization cannot be used to authorize issuance of 283 certificates containing wildcard domain names." 285 Additionally, 200 response code is used here in one scenario instead 286 of a 201 response. However, this is arguably an under-specification 287 in RFC8555, and has been reported in https://www.rfc- 288 editor.org/errata/eid5861. 290 These two items need a review. ]] 292 4.4. Examples 294 In order to illustrate subdomain behaviour, let us assume that a 295 client wishes to get certificates for subdomain identifiers 296 "sub0.example.com", "sub1.example.com" and "sub2.example.com" under 297 parent domain "example.com", and CA policy allows certificate 298 issuance of these subdomain identifiers while only requiring the 299 client to fulfil an ownership challenge for parent domain 300 "example.com". Let us also assume that the client has not yet proven 301 ownership of parent domain "example.com". 303 1. The client POSTs a newOrder request for identifier 304 "sub0.example.com" 306 The server creates an authorization object for identifier 307 "example.com". The server replies with a 201 (Created) response. 308 The response body is an order object with status set to "pending" 309 and a link to newly created authorization object against the 310 parent domain "example.com". Therefore, the server is 311 instructing the client to fulfil a challenge against domain 312 identifier "example.com" in order to obtain a certificate 313 including identifier "sub0.example.com". 315 The client completes the challenge for "example.com", POSTs a CSR 316 to the order finalize URI, and downloads the certificate. 318 2. The client POSTs a newOrder request for identifier 319 "sub1.example.com" 321 The server replies with a 201 (Created) response. The response 322 body is an order object with status set to "ready" and a link to 323 the unexpired authorization against the parent domain 324 "example.com". 326 The client POSTs a CSR to the order finalize URI, and downloads 327 the certificate. 329 3. The client POSTs a newAuthz request for identifier 330 "sub2.example.com" 332 The server replies with a 200 (OK) response. The response body 333 is the previously created authorization object for "example.com" 334 with status set to "valid". 336 5. Resource Enhancements 338 This document defines enhancements to the authorization and directory 339 objects. 341 5.1. Authorization Object 343 If an ACME server allows issuance of certificates for subdomains of a 344 parent domain, then the authorization object for the parent domain 345 MUST include the optional "basedomain" field, with a value of true. 347 The structure of an ACME authorization resource is enhanced to 348 include the following optional field: 350 basedomain (optional, boolean): This field MUST be present and true 351 for authorizations where ACME server policy allows certificates to to 352 be issued for subdomains of the identifier in the authorization 353 object without explicit authorization of the subdomain 355 5.2. Directory Object Metadata 357 An ACME server can advertise support of issuance of subdomain 358 certificates by including the boolean field 359 "implicitSubdomainAuthorization" in its "ACME Directory Metadata 360 Fields" registry. If not specified, then no default value is 361 assumed. If an ACME server supports issuance of subdomain 362 certificates, it can indicate this by including this field with a 363 value of "true". 365 6. IANA Considerations 367 6.1. Authorization Object Fields Registry 369 The following field is added to the "ACME Authorization Object 370 Fields" registry defined in ACME [RFC8555]. 372 +------------+-----------------+--------------+-----------+ 373 | Field Name | Field Type | Configurable | Reference | 374 +------------+-----------------+--------------+-----------+ 375 | basedomain | boolean | false | RFC XXXX | 376 +------------+-----------------+--------------+-----------+ 378 6.2. Directory Object Metadata Fields Registry 380 The following field is added to the "ACME Directory Metadata Fields" 381 registry defined in ACME [RFC8555]. 382 +---------------------+--------+-------+ | Field Name | Field Type | 383 Reference | +---------------------+--------+-------+ | 384 implicitSubdomainAuthorization | boolean | RFC XXXX | 385 +---------------------+--------+-------+ 387 7. Security Considerations 389 [[TODO]] 391 8. Informative References 393 [CAB] CA/Browser Forum, "Baseline Requirements for the Issuance 394 and Management of Publicly-Trusted Certificates", n.d., 395 . 397 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 398 Requirement Levels", BCP 14, RFC 2119, 399 DOI 10.17487/RFC2119, March 1997, 400 . 402 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 403 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 404 May 2017, . 406 [RFC8555] Barnes, R., Hoffman-Andrews, J., McCarney, D., and J. 407 Kasten, "Automatic Certificate Management Environment 408 (ACME)", RFC 8555, DOI 10.17487/RFC8555, March 2019, 409 . 411 Appendix A. ACME Server Policy Considerations 413 The ACME specification does not mandate any specific ACME server or 414 CA policies, or any specific use cases for issuance of certificates. 415 For example, an ACME server could be used: 417 o to issue Web PKI certificates where the ACME server must comply 418 with CA/Browser [CAB] Baseline Requirements. 420 o as a Private CA for issuance of certificates within an 421 organisation. The organisation could enforce whatever policies 422 they desire on the ACME server. 424 o for issuance of IoT device certificates. There are currently no 425 IoT device certificate policies that are generally enforced across 426 the industry. Organsations issuing IoT device certificates can 427 enforce whatever policies they desire on the ACME server. 429 ACME server policy could specify whether: 431 o issuance of subdomain certificates is allowed based on proof of 432 ownership of a parent domain 434 o whether DNS based proof of ownership, or HTTP based proof of 435 ownership, or both, are allowed 437 ACME server policy specification is exlpicitly out of scope of this 438 document. 440 A.1. CA Browser Forum Baseline Requirements Extracts 442 The CA/Browser Forum Baseline Requirements [CAB] allow issuance of 443 subdomain certificates where authorization is only required for a 444 parent domain. Baseline Requirements version 1.6.5 states: 446 o Section: "1.6.1 Definitions": Authorization Domain Name: The 447 Domain Name used to obtain authorization for certificate issuance 448 for a given FQDN. The CA may use the FQDN returned from a DNS 449 CNAME lookup as the FQDN for the purposes of domain validation. 450 If the FQDN contains a wildcard character, then the CA MUST remove 451 all wildcard labels from the left most portion of requested FQDN. 452 The CA may prune zero or more labels from left to right until 453 encountering a Base Domain Name and may use any one of the 454 intermediate values for the purpose of domain validation. 456 o Section: "3.2.2.4.7 DNS Change": Once the FQDN has been validated 457 using this method, the CA MAY also issue Certificates for other 458 FQDNs that end with all the labels of the validated FQDN. This 459 method is suitable for validating Wildcard Domain Names. 461 Authors' Addresses 463 Owen Friel 464 Cisco 466 Email: ofriel@cisco.com 468 Richard Barnes 469 Cisco 471 Email: rlb@ipv.sx 473 Tim Hollebeek 474 DigiCert 476 Email: tim.hollebeek@digicert.com 477 Michael Richardson 478 Sandelman Software Works 480 Email: mcr+ietf@sandelman.ca