idnits 2.17.1 draft-friel-acme-subdomains-03.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 09, 2020) is 1288 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 12, 2021 T. Hollebeek 6 DigiCert 7 M. Richardson 8 Sandelman Software Works 9 October 09, 2020 11 ACME for Subdomains 12 draft-friel-acme-subdomains-03 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 certification 18 authority. The client has fulfilled a challenge against a parent 19 domain but does not need to fulfil a challenge against the explicit 20 subdomain as certificate 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 April 12, 2021. 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. Open Items . . . . . . . . . . . . . . . . . . . . . . . . . 4 61 5. ACME Issuance of Subdomain Certificates . . . . . . . . . . . 5 62 5.1. Pre-Authorization . . . . . . . . . . . . . . . . . . . . 5 63 5.2. Illustrative Call Flow . . . . . . . . . . . . . . . . . 6 64 5.3. newOrder and newAuthz Handling . . . . . . . . . . . . . 7 65 5.4. Examples . . . . . . . . . . . . . . . . . . . . . . . . 8 66 6. Resource Enhancements . . . . . . . . . . . . . . . . . . . . 9 67 6.1. Authorization Object . . . . . . . . . . . . . . . . . . 9 68 6.2. Directory Object Metadata . . . . . . . . . . . . . . . . 9 69 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 9 70 7.1. Authorization Object Fields Registry . . . . . . . . . . 9 71 7.2. Directory Object Metadata Fields Registry . . . . . . . . 9 72 8. Security Considerations . . . . . . . . . . . . . . . . . . . 10 73 8.1. ACME Server Policy Considerations . . . . . . . . . . . . 11 74 9. Informative References . . . . . . . . . . . . . . . . . . . 11 75 Appendix A. CA Browser Forum Baseline Requirements Extracts . . 12 76 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 12 78 1. Introduction 80 ACME [RFC8555] defines a protocol that a certification authority (CA) 81 and an applicant can use to automate the process of domain name 82 ownership validation and X.509v3 (PKIX) [RFC5280] certificate 83 issuance. This document outlines how ACME can be used to issue 84 subdomain certificates, without requiring the ACME client to 85 explicitly fulfil an ownership challenge against the subdomain 86 identifiers - the ACME client need only fulfil an ownership challenge 87 against a parent domain identifier. 89 2. Terminology 91 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 92 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 93 "OPTIONAL" in this document are to be interpreted as described in BCP 94 14 [RFC2119] [RFC8174] when, and only when, they appear in all 95 capitals, as shown here. 97 The following terms are defined in the CA/Browser Baseline 98 Requirements [CAB] and are reproduced here: 100 o Base Domain Name: The portion of an applied-for FQDN that is the 101 first domain name node left of a registry-controlled or public 102 suffix plus the registry-controlled or public suffix (e.g. 103 "example.co.uk" or "example.com"). For FQDNs where the right-most 104 domain name node is a gTLD having ICANN Specification 13 in its 105 registry agreement, the gTLD itself may be used as the Base Domain 106 Name. 108 o Domain Name: The label assigned to a node in the Domain Name 109 System 111 o Domain Namespace: The set of all possible Domain Names that are 112 subordinate to a single node in the Domain Name System 114 The following terms are used in this document: 116 o CA: Certification Authority 118 o CSR: Certificate Signing Request 120 o FQDN: Fully Qualified Domain Name 122 o Parent Domain: a node in the Domain Name System that has a Domain 123 Name 125 o Subdomain: a Domain Name that is in the Domain Namespace of a 126 given Parent Domain 128 3. ACME Workflow and Identifier Requirements 130 A typical ACME workflow for issuance of certificates is as follows: 132 1. client POSTs a newOrder request that contains a set of 133 "identifiers" 135 2. server replies with a set of "authorizations" and a "finalize" 136 URI 138 3. client sends POST-as-GET requests to retrieve the 139 "authorizations", with the downloaded "authorization" object(s) 140 containing the "identifier" that the client must prove that they 141 control 143 4. client proves control over the "identifier" in the 144 "authorization" object by completing the specified challenge, for 145 example, by publishing a DNS TXT record 147 5. client POSTs a CSR to the "finalize" API 149 6. server replies with an updated order object that includes a 150 "certificate" URI 152 7. client sends POST-as-GET request to the "certificate" URI to 153 download the certificate 155 ACME places the following restrictions on "identifiers": 157 o section 7.1.4: the only type of "identifier" defined by the ACME 158 specification is a fully qualified domain name: "The only type of 159 identifier defined by this specification is a fully qualified 160 domain name (type: "dns"). The domain name MUST be encoded in the 161 form in which it would appear in a certificate." 163 o Section 7.4: the "identifier" in the CSR request must match the 164 "identifier" in the newOrder request: "The CSR MUST indicate the 165 exact same set of requested identifiers as the initial newOrder 166 request." 168 o Sections 8.3: the "identifier", or FQDN, in the "authorization" 169 object must be used when fulfilling challenges via HTTP: 170 "Construct a URL by populating the URL template ... where the 171 domain field is set to the domain name being verified" 173 o Section 8.4: the "identifier", or FQDN, in the "authorization" 174 object must be used when fulfilling challenges via DNS: "The 175 client constructs the validation domain name by prepending the 176 label "_acme-challenge" to the domain name being validated." 178 ACME does not mandate that the "identifier" in a newOrder request 179 matches the "identifier" in "authorization" objects. 181 4. Open Items 183 1. Does the client need a mechanism to indicate that they want to 184 authorize a parent domain and not the explicit subdomain 185 identifier? Or a mechanism to indicate that they are happy to 186 authorize against a choice of identifiers? E.g. for 187 foo1.foo2.bar.example.com, should the client be able to specify 188 anywhere from 1 to 4 identifiers they are willing to fulfil 189 challenges for? 191 2. Does the server need a mechanism to provide a choice of 192 identifiers to the client and let the client chose which 193 challenge to fulfil? E.g. for foo1.foo2.bar.example.com, should 194 the server be able to specify anywhere from 1 to 4 identifiers 195 that the client can pick from to fulfil? 197 Both 1 and 2 would require changes to the JSON object definitions. 198 For 1, each identifier in the newOrder or newAuthz requests would 199 need a child array of alternative identifiers the client is willing 200 to fulfil. For 2, the current order object contains a set of 201 authorizations that must all be completed, the authorization object 202 contains a single identifier that all challenges are against, so 203 therefore its not possible for the server to give the client a choice 204 of identifiers to pick from. 206 This document does not currently define how 1 or 2 could be 207 accomplished. This document merely defines how a client can submit a 208 newOrder / newAuthz for one identifier (e.g. 209 foo1.foo2.bar.example.com), and the server to choose a parent 210 identifier (e.g. example.com) that it requires challenge fulfilment 211 on, and specify that identifier in the authorization object. 213 5. ACME Issuance of Subdomain Certificates 215 As noted in the previous section, ACME does not mandate that the 216 "identifier" in a newOrder request matches the "identifier" in 217 "authorization" objects. This means that the ACME specification does 218 not preclude an ACME server processing newOrder requests and issuing 219 certificates for a subdomain without requiring a challenge to be 220 fulfilled against that explicit subdomain. 222 ACME server policy could allow issuance of certificates for a 223 subdomain to a client where the client only has to fulfil an 224 authorization challenge for a parent domain of that subdomain. This 225 allows a flow where a client proves ownership of, for example, 226 "example.org" and then successfully obtains a certificate for 227 "sub.example.org". 229 ACME server policy is out of scope of this document, however some 230 commentary is provided in Section 8.1. 232 5.1. Pre-Authorization 234 The standard ACME workflow has authorization objects created 235 reactively in response to a certificate order. ACME also allows for 236 pre-authorization, where clients obtain authorization for an 237 identifier proactively, outside of the context of a specific 238 issuance. This document allows for both workflows, and Section 5.3 239 outlines how the ACME server handles newOrder and newAuthz requests 240 for both workflows. 242 It may make sense to use the ACME pre-authorization flow for the 243 subdomain use case, however, that is an operator implementation and 244 deployment decision. With the ACME pre-authorization flow, the 245 client could pre-authorize for the parent domain once, and then issue 246 multiple newOrder requests for certificates for multiple subdomains. 248 5.2. Illustrative Call Flow 250 The call flow illustrated here uses the ACME pre-authorization flow. 251 The call flow also illustrates the DNS-based proof of ownership 252 mechanism, but the subdomain workflow is equally valid for HTTP based 253 proof of ownership. 255 +--------+ +------+ +-----+ 256 | Client | | ACME | | DNS | 257 +--------+ +------+ +-----+ 258 | | | 259 STEP 1: Pre-Authorization of parent domain 260 | | | 261 | POST /newAuthz | | 262 | "example.org" | | 263 |--------------------->| | 264 | | | 265 | 201 authorizations | | 266 |<---------------------| | 267 | | | 268 | Publish DNS TXT | | 269 | "example.org" | | 270 |--------------------------------->| 271 | | | 272 | POST /challenge | | 273 |--------------------->| | 274 | | Verify | 275 | |---------->| 276 | 200 status=valid | | 277 |<---------------------| | 278 | | | 279 | Delete DNS TXT | | 280 | "example.org" | | 281 |--------------------------------->| 282 | | | 283 STEP 2: Place order for subdomain 284 | | | 285 | POST /newOrder | | 286 | "sub.example.org" | | 287 |--------------------->| | 288 | | | 289 | 201 status=ready | | 290 |<---------------------| | 291 | | | 292 | POST /finalize | | 293 | CSR "sub.example.org"| | 294 |--------------------->| | 295 | | | 296 | 200 OK status=valid | | 297 |<---------------------| | 298 | | | 299 | POST /certificate | | 300 |--------------------->| | 301 | | | 302 | 200 OK | | 303 | PKI "sub.example.org"| | 304 |<---------------------| | 306 5.3. newOrder and newAuthz Handling 308 Servers may consider validation of a parent domain sufficient 309 authorization for a subdomain. If a server has such a policy and a 310 client is already authorized for the parent domain then: 312 o If the client submits a newAuthz request for a subdomain: The 313 server MUST return status 200 (OK) response. The response body is 314 the existing authorization object for the parent domain with 315 status set to "valid". 317 o If the client submits a newOrder request for a subdomain: The 318 server MUST return a 201 (Created) response. The response body is 319 an order object with status set to "ready" and links to the 320 unexpired authorizations against the parent domain. 322 If a server has such a policy and a client is not authorized for the 323 parent domain then: 325 o If the client submits a newAuthz request for a subdomain: The 326 server MUST return a status 201 (Created) response. The response 327 body is a newly created authorization object for the parent domain 328 with status set to "pending". 330 o If the client submits a newOrder request for a subdomain: The 331 server MUST return a status 201 (Created) response. The response 332 body is an order object with status set to "pending" and links to 333 newly created authorizations objects against the parent domain. 335 5.4. Examples 337 In order to illustrate subdomain behaviour, let us assume that a 338 client wishes to get certificates for subdomain identifiers 339 "sub0.example.org", "sub1.example.org" and "sub2.example.org" under 340 parent domain "example.org", and CA policy allows certificate 341 issuance of these subdomain identifiers while only requiring the 342 client to fulfil an ownership challenge for parent domain 343 "example.org". Let us also assume that the client has not yet proven 344 ownership of parent domain "example.org". 346 1. The client POSTs a newOrder request for identifier 347 "sub0.example.org" 349 The server creates an authorization object for identifier 350 "example.org". The server replies with a 201 (Created) response. 351 The response body is an order object with status set to "pending" 352 and a link to newly created authorization object against the 353 parent domain "example.org". Therefore, the server is 354 instructing the client to fulfil a challenge against domain 355 identifier "example.org" in order to obtain a certificate 356 including identifier "sub0.example.org". 358 The client completes the challenge for "example.org", POSTs a CSR 359 to the order finalize URI, and downloads the certificate. 361 2. The client POSTs a newOrder request for identifier 362 "sub1.example.org" 364 The server replies with a 201 (Created) response. The response 365 body is an order object with status set to "ready" and a link to 366 the unexpired authorization against the parent domain 367 "example.org". 369 The client POSTs a CSR to the order finalize URI, and downloads 370 the certificate. 372 3. The client POSTs a newAuthz request for identifier 373 "sub2.example.org" 375 The server replies with a 200 (OK) response. The response body 376 is the previously created authorization object for "example.org" 377 with status set to "valid". 379 6. Resource Enhancements 381 This document defines enhancements to the authorization and directory 382 objects. 384 6.1. Authorization Object 386 If an ACME server allows issuance of certificates for subdomains of a 387 parent domain, then the authorization object for the parent domain 388 MUST include the optional "includeSubDomains" field, with a value of 389 true. 391 The structure of an ACME authorization resource is enhanced to 392 include the following optional field: 394 includeSubDomains (optional, boolean): This field MUST be present and 395 true for authorizations where ACME server policy allows certificates 396 to to be issued for subdomains of the identifier in the authorization 397 object without explicit authorization of the subdomain 399 6.2. Directory Object Metadata 401 An ACME server can advertise support of issuance of subdomain 402 certificates by including the boolean field 403 "includeSubDomainsAuthorization" in its "ACME Directory Metadata 404 Fields" registry. If not specified, then no default value is 405 assumed. If an ACME server supports issuance of subdomain 406 certificates, it can indicate this by including this field with a 407 value of "true". 409 7. IANA Considerations 411 7.1. Authorization Object Fields Registry 413 The following field is added to the "ACME Authorization Object 414 Fields" registry defined in ACME [RFC8555]. 416 +-------------------+------------+--------------+-----------+ 417 | Field Name | Field Type | Configurable | Reference | 418 +-------------------+------------+--------------+-----------+ 419 | includeSubDomains | boolean | false | RFC XXXX | 420 +-------------------+------------+--------------+-----------+ 422 7.2. Directory Object Metadata Fields Registry 424 The following field is added to the "ACME Directory Metadata Fields" 425 registry defined in ACME [RFC8555]. 427 +--------------------------------+------------+-----------+ 428 | Field Name | Field Type | Reference | 429 +--------------------------------+------------+-----------+ 430 | includeSubDomainsAuthorization | boolean | RFC XXXX | 431 +--------------------------------+------------+-----------+ 433 8. Security Considerations 435 This document documents enhancements to ACME [RFC8555] that optimize 436 the protocol flows for issuance of certificates for subdomains. The 437 underlying goal of ACME for Subdomains remains the same as that of 438 ACME: managing certificates that attest to identifier/key bindings 439 for these subdomains. Thus, ACME for Subdomains has the same two 440 security goals as ACME: 442 1. Only an entity that controls an identifier can get an 443 authorization for that identifier 445 2. Once authorized, an account key's authorizations cannot be 446 improperly used by another account 448 ACME for Subdomains makes no changes to: 450 o account or account key management 452 o ACME channel establishment, security mechanisms or threat model 454 o Validation channel establishment, security mechanisms or threat 455 model 457 Therefore, all Security Considerations in ACME in the following areas 458 are equally applicable to ACME for Subdomains: 460 o Threat Model 462 o Integrity of Authorizations 464 o Denial-of-Service Considerations 466 o Server-Side Request Forgery 468 o CA Policy Considerations 470 Some additional comments on ACME server opicy are given in the 471 following section. 473 8.1. ACME Server Policy Considerations 475 The ACME for Subdomains and the ACME specifications do not mandate 476 any specific ACME server or CA policies, or any specific use cases 477 for issuance of certificates. For example, an ACME server could be 478 used: 480 o to issue Web PKI certificates where the ACME server must comply 481 with CA/Browser Forum [CAB] Baseline Requirements. 483 o as a Private CA for issuance of certificates within an 484 organisation. The organisation could enforce whatever policies 485 they desire on the ACME server. 487 o for issuance of IoT device certificates. There are currently no 488 IoT device certificate policies that are generally enforced across 489 the industry. Organsations issuing IoT device certificates can 490 enforce whatever policies they desire on the ACME server. 492 ACME server policy could specify whether: 494 o issuance of subdomain certificates is allowed based on proof of 495 ownership of a parent domain 497 o issuance of subdomain certificates is allowed, but only for a 498 specific set of parent domains 500 o whether DNS based proof of ownership, or HTTP based proof of 501 ownership, or both, are allowed 503 ACME server policy specification is exlpicitly out of scope of this 504 document. For reference, extracts from CA/Browser Forum Baseline 505 Requirements are given in the appendices. 507 9. Informative References 509 [CAB] CA/Browser Forum, "Baseline Requirements for the Issuance 510 and Management of Publicly-Trusted Certificates", n.d., 511 . 514 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 515 Requirement Levels", BCP 14, RFC 2119, 516 DOI 10.17487/RFC2119, March 1997, 517 . 519 [RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., 520 Housley, R., and W. Polk, "Internet X.509 Public Key 521 Infrastructure Certificate and Certificate Revocation List 522 (CRL) Profile", RFC 5280, DOI 10.17487/RFC5280, May 2008, 523 . 525 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 526 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 527 May 2017, . 529 [RFC8555] Barnes, R., Hoffman-Andrews, J., McCarney, D., and J. 530 Kasten, "Automatic Certificate Management Environment 531 (ACME)", RFC 8555, DOI 10.17487/RFC8555, March 2019, 532 . 534 Appendix A. CA Browser Forum Baseline Requirements Extracts 536 The CA/Browser Forum Baseline Requirements [CAB] allow issuance of 537 subdomain certificates where authorization is only required for a 538 parent domain. Baseline Requirements version 1.7.1 states: 540 o Section: "1.6.1 Definitions": Authorization Domain Name: The 541 Domain Name used to obtain authorization for certificate issuance 542 for a given FQDN. The CA may use the FQDN returned from a DNS 543 CNAME lookup as the FQDN for the purposes of domain validation. 544 If the FQDN contains a wildcard character, then the CA MUST remove 545 all wildcard labels from the left most portion of requested FQDN. 546 The CA may prune zero or more labels from left to right until 547 encountering a Base Domain Name and may use any one of the 548 intermediate values for the purpose of domain validation. 550 o Section: "3.2.2.4.6 Agreed-Upon Change to Website": Once the FQDN 551 has been validated using this method, the CA MAY also issue 552 Certificates for other FQDNs that end with all the labels of the 553 validated FQDN. This method is suitable for validating Wildcard 554 Domain Names. 556 o Section: "3.2.2.4.7 DNS Change": Once the FQDN has been validated 557 using this method, the CA MAY also issue Certificates for other 558 FQDNs that end with all the labels of the validated FQDN. This 559 method is suitable for validating Wildcard Domain Names. 561 Authors' Addresses 563 Owen Friel 564 Cisco 566 Email: ofriel@cisco.com 567 Richard Barnes 568 Cisco 570 Email: rlb@ipv.sx 572 Tim Hollebeek 573 DigiCert 575 Email: tim.hollebeek@digicert.com 577 Michael Richardson 578 Sandelman Software Works 580 Email: mcr+ietf@sandelman.ca