idnits 2.17.1 draft-ietf-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 (25 October 2021) is 915 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) -- Obsolete informational reference (is this intentional?): RFC 8499 (Obsoleted by RFC 9499) Summary: 0 errors (**), 0 flaws (~~), 1 warning (==), 2 comments (--). 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: 28 April 2022 T. Hollebeek 6 DigiCert 7 M. Richardson 8 Sandelman Software Works 9 25 October 2021 11 ACME for Subdomains 12 draft-ietf-acme-subdomains-00 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 fulfill 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 28 April 2022. 40 Copyright Notice 42 Copyright (c) 2021 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 (https://trustee.ietf.org/ 47 license-info) in effect on the date of publication of this document. 48 Please review these documents carefully, as they describe your rights 49 and restrictions with respect to this document. Code Components 50 extracted from this document must include Simplified BSD License text 51 as described in Section 4.e of the Trust Legal Provisions and are 52 provided without warranty as described in the Simplified BSD License. 54 Table of Contents 56 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 57 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 2 58 3. ACME Workflow and Identifier Requirements . . . . . . . . . . 4 59 4. ACME Issuance of Subdomain Certificates . . . . . . . . . . . 5 60 4.1. ACME Challenge Type . . . . . . . . . . . . . . . . . . . 6 61 4.2. Authorization Object . . . . . . . . . . . . . . . . . . 6 62 4.3. Pre-Authorization . . . . . . . . . . . . . . . . . . . . 7 63 4.4. New Orders . . . . . . . . . . . . . . . . . . . . . . . 8 64 4.5. Directory Object Metadata . . . . . . . . . . . . . . . . 10 65 5. Illustrative Call Flow . . . . . . . . . . . . . . . . . . . 10 66 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 16 67 6.1. Authorization Object Fields Registry . . . . . . . . . . 16 68 6.2. Directory Object Metadata Fields Registry . . . . . . . . 16 69 7. Security Considerations . . . . . . . . . . . . . . . . . . . 17 70 7.1. ACME Server Policy Considerations . . . . . . . . . . . . 18 71 8. Informative References . . . . . . . . . . . . . . . . . . . 18 72 Appendix A. CA Browser Forum Baseline Requirements Extracts . . 19 73 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 20 75 1. Introduction 77 ACME [RFC8555] defines a protocol that a certification authority (CA) 78 and an applicant can use to automate the process of domain name 79 ownership validation and X.509v3 (PKIX) [RFC5280] certificate 80 issuance. This document outlines how ACME can be used to issue 81 subdomain certificates, without requiring the ACME client to 82 explicitly fulfill an ownership challenge against the subdomain 83 identifiers - the ACME client need only fulfill an ownership 84 challenge against a parent domain identifier. 86 2. Terminology 88 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 89 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 90 "OPTIONAL" in this document are to be interpreted as described in BCP 91 14 [RFC2119] [RFC8174] when, and only when, they appear in all 92 capitals, as shown here. 94 The following terms are defined in DNS Terminology [RFC8499] and are 95 reproduced here: 97 * Label: An ordered list of zero or more octets that makes up a 98 portion of a domain name. Using graph theory, a label identifies 99 one node in a portion of the graph of all possible domain names. 101 * Domain Name: An ordered list of one or more labels. 103 * Subdomain: "A domain is a subdomain of another domain if it is 104 contained within that domain. This relationship can be tested by 105 seeing if the subdomain's name ends with the containing domain's 106 name." (Quoted from [RFC1034], Section 3.1) For example, in the 107 host name "nnn.mmm.example.com", both "mmm.example.com" and 108 "nnn.mmm.example.com" are subdomains of "example.com". Note that 109 the comparisons here are done on whole labels; that is, 110 "ooo.example.com" is not a subdomain of "oo.example.com". 112 * Fully-Qualified Domain Name (FQDN): This is often just a clear way 113 of saying the same thing as "domain name of a node", as outlined 114 above. However, the term is ambiguous. Strictly speaking, a 115 fully-qualified domain name would include every label, including 116 the zero-length label of the root: such a name would be written 117 "www.example.net." (note the terminating dot). But, because every 118 name eventually shares the common root, names are often written 119 relative to the root (such as "www.example.net") and are still 120 called "fully qualified". This term first appeared in [RFC0819]. 121 In this document, names are often written relative to the root. 123 The following terms are defined in the CA/Browser Forum Baseline 124 Requirements [CAB] version 1.7.1 and are reproduced here: 126 * Authorization Domain Name (ADN): The Domain Name used to obtain 127 authorization for certificate issuance for a given FQDN. The CA 128 may use the FQDN returned from a DNS CNAME lookup as the FQDN for 129 the purposes of domain validation. If the FQDN contains a 130 wildcard character, then the CA MUST remove all wildcard labels 131 from the left most portion of requested FQDN. The CA may prune 132 zero or more labels from left to right until encountering a Base 133 Domain Name and may use any one of the intermediate values for the 134 purpose of domain validation 136 * Base Domain Name: The portion of an applied-for FQDN that is the 137 first domain name node left of a registry-controlled or public 138 suffix plus the registry-controlled or public suffix (e.g. 139 "example.co.uk" or "example.com"). For FQDNs where the right-most 140 domain name node is a gTLD having ICANN Specification 13 in its 141 registry agreement, the gTLD itself may be used as the Base Domain 142 Name. 144 * Certification Authority (CA): An organization that is responsible 145 for the creation, issuance, revocation, and management of 146 Certificates. The term applies equally to both Roots CAs and 147 Subordinate CAs 149 * Domain Namespace: The set of all possible Domain Names that are 150 subordinate to a single node in the Domain Name System 152 The following additional terms are used in this document: 154 * Certification Authority (CA): An organization that is responsible 155 for the creation, issuance, revocation, and management of 156 Certificates. The term applies equally to both Roots CAs and 157 Subordinate CAs 159 * CSR: Certificate Signing Request 161 * Parent Domain: a domain is a parent domain of a subdomain if it 162 contains that subdomain, as per the [RFC8499] definition of 163 subdomain. For example, for the host name "nnn.mmm.example.com", 164 both "mmm.example.com" and "example.com" are parent domains of 165 "nnn.mmm.example.com". 167 3. ACME Workflow and Identifier Requirements 169 A typical ACME workflow for issuance of certificates is as follows: 171 1. client POSTs a newOrder request that contains a set of 172 "identifiers" 174 2. server replies with a set of "authorizations" and a "finalize" 175 URI 177 3. client sends POST-as-GET requests to retrieve the 178 "authorizations", with the downloaded "authorization" object(s) 179 containing the "identifier" that the client must prove that they 180 control, and a set of associated "challenges", one of which the 181 the client must fulfil 183 4. client proves control over the "identifier" in the 184 "authorization" object by completing one of the specified 185 challenges, for example, by publishing a DNS TXT record 187 5. client POSTs a CSR to the "finalize" API 189 6. server replies with an updated order object that includes a 190 "certificate" URI 192 7. client sends POST-as-GET request to the "certificate" URI to 193 download the certificate 195 ACME places the following restrictions on "identifiers": 197 * [RFC8555] section 7.1.3: The authorizations required are dictated 198 by server policy; there may not be a 1:1 relationship between the 199 order identifiers and the authorizations required. 201 * [RFC8555] section 7.1.4: the only type of "identifier" defined by 202 the ACME specification is an FQDN: "The only type of identifier 203 defined by this specification is a fully qualified domain name 204 (type: "dns"). The domain name MUST be encoded in the form in 205 which it would appear in a certificate." 207 * [RFC8555] section 7.4: the "identifier" in the CSR request must 208 match the "identifier" in the newOrder request: "The CSR MUST 209 indicate the exact same set of requested identifiers as the 210 initial newOrder request." 212 * [RFC8555] section 8.3: the "identifier", or FQDN, in the 213 "authorization" object must be used when fulfilling challenges via 214 HTTP: "Construct a URL by populating the URL template ... where 215 the domain field is set to the domain name being verified" 217 * [RFC8555] section 8.4: the "identifier", or FQDN, in the 218 "authorization" object must be used when fulfilling challenges via 219 DNS: "The client constructs the validation domain name by 220 prepending the label "_acme-challenge" to the domain name being 221 validated." 223 ACME does not mandate that the "identifier" in a newOrder request 224 matches the "identifier" in "authorization" objects. 226 4. ACME Issuance of Subdomain Certificates 228 As noted in the previous section, ACME does not mandate that the 229 "identifier" in a newOrder request matches the "identifier" in 230 "authorization" objects. This means that the ACME specification does 231 not preclude an ACME server processing newOrder requests and issuing 232 certificates for a subdomain without requiring a challenge to be 233 fulfilled against that explicit subdomain. 235 ACME server policy could allow issuance of certificates for a 236 subdomain to a client where the client only has to fulfill an 237 authorization challenge for a parent domain of that subdomain. This 238 allows a flow where a client proves ownership of, for example, 239 "example.org" and then successfully obtains a certificate for 240 "sub.example.org". 242 ACME server policy is out of scope of this document, however some 243 commentary is provided in Section 7.1. 245 Clients need a mechanism to instruct the ACME server that they are 246 requesting authorization for a Domain Namespace subordinate to a 247 given ADN, as opposed to just requesting authorization for an 248 explicit ADN identifier. Clients need a mechanism to do this in both 249 newAuthz and newOrder requests. ACME servers need a mechanism to 250 indicate to clients that authorization objects are valid for an 251 entire Domain Namespace. These are described in this section. 253 4.1. ACME Challenge Type 255 ACME for subdomains is restricted for use with "dns-01" challenges. 256 If a server policy allows a client to fulfill a challenge against a 257 parent ADN of a requested certificate FQDN identifier, then the 258 server MUST issue a "dns-01" challenge against that parent ADN. 260 4.2. Authorization Object 262 ACME [RFC8555] section 7.1.4 defines the authorization object. When 263 ACME server policy allows authorization for Domain Namespaces 264 subordinate to an ADN, the server indicates this by including the 265 "domainNamespace" flag in the authorization object for that ADN 266 identifier: 268 domainNamespace (optional, boolean): This field MUST be present 269 and true for authorizations where ACME server policy allows 270 certificates to be issued for any Domain Name in the Domain 271 Namespace subordinate to the ADN specified in the 'identifier' 272 field of the authorization object. 274 The following example shows an authorization object for the ADN 275 example.org where the authorization covers the Domain Namespace 276 subordinate to example.org. 278 { 279 "status": "valid", 280 "expires": "2015-03-01T14:09:07.99Z", 282 "identifier": { 283 "type": "dns", 284 "value": "example.org" 285 }, 287 "challenges": [ 288 { 289 "url": "https://example.com/acme/chall/prV_B7yEyA4", 290 "type": "http-01", 291 "status": "valid", 292 "token": "DGyRejmCefe7v4NfDGDKfA", 293 "validated": "2014-12-01T12:05:58.16Z" 294 } 295 ], 297 "domainNamespace": true 298 } 300 If the "domainNamespace" field is not included, then the assumed 301 default value is false. 303 4.3. Pre-Authorization 305 The standard ACME workflow has authorization objects created 306 reactively in response to a certificate order. ACME also allows for 307 pre-authorization, where clients obtain authorization for an 308 identifier proactively, outside of the context of a specific 309 issuance. With the ACME pre-authorization flow, a client can pre- 310 authorize for a parent ADN once, and then issue multiple newOrder 311 requests for certificates with identifiers in the Domain Namespace 312 subordinate to that ADN. 314 ACME [RFC8555] section 7.4.1 defines the "identifier" object for 315 newAuthz requests. One additional field for the "identifier" object 316 is defined: 318 domainNamespace (optional, boolean): An ACME client sets this flag 319 to indicate to the server that it is requesting an authorization 320 for the Domain Namespace subordinate to the specified ADN 321 identifier value 323 Clients include the flag in the "identifier" object of newAuthz 324 requests to indicate that they are requesting a Domain Namespace 325 authorization. In the following example newAuthz payload, the client 326 is requesting pre-authorization for the Domain Namespace subordinate 327 to example.org. 329 "payload": base64url({ 330 "identifier": { 331 "type": "dns", 332 "value": "example.org", 333 "domainNamespace": true 334 } 335 }) 337 If the server is willing to allow a single authorization for the 338 Domain Namespace, and there is not an existing authorization object 339 for the identifier, then it will create an authorization object and 340 include the "domainNamespace" flag with value of true. If the server 341 policy does not allow creation of Domain Namespace authorizations 342 subordinate to that ADN, the server can create an authorization 343 object for the indicated identifier, and include the 344 "domainNamespace" flag with value of false. In both scenarios, 345 handling of the pre-authorization follows the process documented in 346 ACME section 7.4.1. 348 4.4. New Orders 350 Clients need a mechanism to optionally indicate to servers whether or 351 not they are authorized to fulfill challenges against parent ADNs for 352 a given identifier FQDN. For example, if a client places an order 353 for an identifier foo.bar.example.org, and is authorized to update 354 DNS TXT records against the parent ADNs bar.example.org or 355 example.org, then the client needs a mechanism to indicate control 356 over the parent ADNs to the ACME server. 358 This can be achieved by adding an optional field "domainNamespace" to 359 the "identifiers" field in the order object: 361 domainNamespace (optional, string): This is the parent ADN of a 362 Domain Namespace that the requested identifier belongs to. The 363 client MUST have DNS control over the parent ADN. 365 This field specifies the ADN of the Domain Namespace that the client 366 has DNS control over, and is capable of fulfilling challenges 367 against. Based on server policy, the server can choose to issue a 368 challenge against any parent domain of the identifier in the Domain 369 Namespace up to and including the specified "domainNamespace", and 370 create a corresponding authorization object against the chosen 371 identifier. 373 In the following example newOrder payload, the client requests a 374 certificate for identifier foo.bar.example.org and indicates that it 375 can fulfill a challenge against the parent ADN and the Domain 376 Namespace subordinate to bar.example.org. The server can then choose 377 to issue a challenge against either foo.bar.example.org or 378 bar.example.org identifiers. 380 "payload": base64url({ 381 "identifiers": [ 382 { "type": "dns", 383 "value": "foo.bar.example.org", 384 "domainNamespace": "bar.example.org" } 385 ], 386 "notBefore": "2016-01-01T00:04:00+04:00", 387 "notAfter": "2016-01-08T00:04:00+04:00" 388 }) 390 In the following example newOrder payload, the client requests a 391 certificate for identifier foo.bar.example.org and indicates that it 392 can fulfill a challenge against the parent ADN and the Domain 393 Namespace subordinate to example.org. The server can then choose to 394 issue a challenge against any one of foo.bar.example.org, 395 bar.example.org or example.org identifiers. 397 "payload": base64url({ 398 "identifiers": [ 399 { "type": "dns", 400 "value": "foo.bar.example.org", 401 "domainNamespace": "example.org" } 402 ], 403 "notBefore": "2016-01-01T00:04:00+04:00", 404 "notAfter": "2016-01-08T00:04:00+04:00" 405 }) 407 If the client is unable to fulfill authorizations against parent 408 ADNs, the client should not include the "domainNamespace" field. 410 Server newOrder handling generally follows the process documented 411 ACME section 7.4. If the server is willing to allow Domain Namespace 412 authorizations for the ADN specified in "domainNamespace", then it 413 creates an authorization object against that ADN and includes the 414 "domainNamespace" flag with a value of true. If the server policy 415 does not allow creation of Domain Namespace authorizations against 416 that ADN, then it can create an authorization object for the 417 indicated identifier value, and include the "domainNamespace" flag 418 with value of false. 420 4.5. Directory Object Metadata 422 An ACME server can advertise support for authorization of Domain 423 Namespaces by including the following boolean flag in its "ACME 424 Directory Metadata Fields" registry: 426 domainNamespace (optional, bool): Indicates if an ACME server 427 supports authorization of Domain Namespaces. 429 If not specified, then no default value is assumed. If an ACME 430 server supports authorization of Domain Namespaces, it can indicate 431 this by including this field with a value of "true". 433 5. Illustrative Call Flow 435 The call flow illustrated here uses the ACME pre-authorization flow 436 using DNS-based proof of ownership. 438 +--------+ +------+ +-----+ 439 | Client | | ACME | | DNS | 440 +--------+ +------+ +-----+ 441 | | | 442 STEP 1: Pre-Authorization of parent domain 443 | | | 444 | POST /newAuthz | | 445 | "example.org" | | 446 |--------------------------->| | 447 | | | 448 | 201 authorizations | | 449 |<---------------------------| | 450 | | | 451 | Publish DNS TXT | | 452 | "example.org" | | 453 |--------------------------------------->| 454 | | | 455 | POST /challenge | | 456 |--------------------------->| | 457 | | Verify | 458 | |---------->| 459 | 200 status=valid | | 460 |<---------------------------| | 461 | | | 462 | Delete DNS TXT | | 463 | "example.org" | | 464 |--------------------------------------->| 465 | | | 466 STEP 2: Place order for sub1.example.org 467 | | | 468 | POST /newOrder | | 469 | "sub1.example.org" | | 470 |--------------------------->| | 471 | | | 472 | 201 status=ready | | 473 |<---------------------------| | 474 | | | 475 | POST /finalize | | 476 | CSR SAN "sub1.example.org" | | 477 |--------------------------->| | 478 | | | 479 | 200 OK status=valid | | 480 |<---------------------------| | 481 | | | 482 | POST /certificate | | 483 |--------------------------->| | 484 | | | 485 | 200 OK | | 486 | PEM SAN "sub1.example.org" | | 487 |<---------------------------| | 488 | | | 489 STEP 3: Place order for sub2.example.org 490 | | | 491 | POST /newOrder | | 492 | "sub2.example.org" | | 493 |--------------------------->| | 494 | | | 495 | 201 status=ready | | 496 |<---------------------------| | 497 | | | 498 | POST /finalize | | 499 | CSR SAN "sub2.example.org" | | 500 |--------------------------->| | 501 | | | 502 | 200 OK status=valid | | 503 |<---------------------------| | 504 | | | 505 | POST /certificate | | 506 |--------------------------->| | 507 | | | 508 | 200 OK | | 509 | PEM SAN "sub2.example.org" | | 510 |<---------------------------| | 512 * STEP 1: Pre-authorization of Domain Namespace 514 The client sends a newAuthz request for the parent ADN of the 515 Domain Namespace including the "domainNamespace" flag in the 516 identifier object. 518 POST /acme/new-authz HTTP/1.1 519 Host: example.com 520 Content-Type: application/jose+json 522 { 523 "protected": base64url({ 524 "alg": "ES256", 525 "kid": "https://example.com/acme/acct/evOfKhNU60wg", 526 "nonce": "uQpSjlRb4vQVCjVYAyyUWg", 527 "url": "https://example.com/acme/new-authz" 528 }), 529 "payload": base64url({ 530 "identifier": { 531 "type": "dns", 532 "value": "example.org", 533 "domainNamespace": true 534 } 535 }), 536 "signature": "nuSDISbWG8mMgE7H...QyVUL68yzf3Zawps" 537 } 539 The server creates and returns an authorization object for the 540 identifier including the "domainNamespace" flag. The object is 541 initially in "pending" state. Once the client completes the 542 challenge, the server will transition the authorization object and 543 associated challenge object status to "valid". 545 { 546 "status": "pending", 547 "expires": "2015-03-01T14:09:07.99Z", 549 "identifier": { 550 "type": "dns", 551 "value": "example.org" 552 }, 554 "challenges": [ 555 { 556 "url": "https://example.com/acme/chall/prV_B7yEyA4", 557 "type": "http-01", 558 "status": "pending", 559 "token": "DGyRejmCefe7v4NfDGDKfA", 560 "validated": "2014-12-01T12:05:58.16Z" 561 } 562 ], 564 "domainNamespace": true 565 } 567 * STEP 2: The client places a newOrder for sub1.example.org 569 The client sends a newOrder request to the server and includes the 570 subdomain identifier. Note that the identifier is in the Domain 571 Namespace that has been pre-authorised in step 1. The client does 572 not need to include the "domainNamespace" field in the 573 "identifier" object as it has already pre-authorized the Domain 574 Namespace. 576 POST /acme/new-order HTTP/1.1 577 Host: example.com 578 Content-Type: application/jose+json 580 { 581 "protected": base64url({ 582 "alg": "ES256", 583 "kid": "https://example.com/acme/acct/evOfKhNU60wg", 584 "nonce": "5XJ1L3lEkMG7tR6pA00clA", 585 "url": "https://example.com/acme/new-order" 586 }), 587 "payload": base64url({ 588 "identifiers": [ 589 { "type": "dns", "value": "sub1.example.org" } 590 ], 591 "notBefore": "2016-01-01T00:04:00+04:00", 592 "notAfter": "2016-01-08T00:04:00+04:00" 593 }), 594 "signature": "H6ZXtGjTZyUnPeKn...wEA4TklBdh3e454g" 595 } 597 As an authorization object already exists for the parent ADN of the 598 Domain Namespace, the server replies with an order object with a 599 status of "valid" that includes a link to the existing "valid" 600 authorization object. 602 HTTP/1.1 201 Created 603 Replay-Nonce: MYAuvOpaoIiywTezizk5vw 604 Link: ;rel="index" 605 Location: https://example.com/acme/order/TOlocE8rfgo 607 { 608 "status": "valid", 609 "expires": "2016-01-05T14:09:07.99Z", 611 "notBefore": "2016-01-01T00:00:00Z", 612 "notAfter": "2016-01-08T00:00:00Z", 614 "identifiers": [ 615 { "type": "dns", "value": "sub1.example.org" } 616 ], 618 "authorizations": [ 619 "https://example.com/acme/authz/PAniVnsZcis" 620 ], 622 "finalize": "https://example.com/acme/order/TOlocrfgo/finalize" 623 } 625 The client can proceed to finalize the order and download the 626 certificate for sub1.example.org. 628 * STEP 3: The client places a newOrder for sub2.example.org 630 The client sends a newOrder request to the server and includes the 631 subdomain identifier. Note that the identifier is in the Domain 632 Namespace that has been pre-authorised in step 1. The client does 633 not need to include the "domainNamespace" field in the 634 "identifier" object as it has already pre-authorized the Domain 635 Namespace. 637 POST /acme/new-order HTTP/1.1 638 Host: example.com 639 Content-Type: application/jose+json 641 { 642 "protected": base64url({ 643 "alg": "ES256", 644 "kid": "https://example.com/acme/acct/evOfKhNU60wg", 645 "nonce": "5XJ1L3lEkMG7tR6pA00clA", 646 "url": "https://example.com/acme/new-order" 647 }), 648 "payload": base64url({ 649 "identifiers": [ 650 { "type": "dns", "value": "sub2.example.org" } 651 ], 652 "notBefore": "2016-01-01T00:04:00+04:00", 653 "notAfter": "2016-01-08T00:04:00+04:00" 654 }), 655 "signature": "H6ZXtGjTZyUnPeKn...wEA4TklBdh3e454g" 656 } 658 As an authorization object already exists for the parent ADN of the 659 Domain Namespace, the server replies with an order object with a 660 status of "valid" that includes a link to the existing "valid" 661 authorization object. 663 HTTP/1.1 201 Created 664 Replay-Nonce: MYAuvOpaoIiywTezizk5vw 665 Link: ;rel="index" 666 Location: https://example.com/acme/order/TOlocE8rfgo 668 { 669 "status": "valid", 670 "expires": "2016-01-05T14:09:07.99Z", 672 "notBefore": "2016-01-01T00:00:00Z", 673 "notAfter": "2016-01-08T00:00:00Z", 675 "identifiers": [ 676 { "type": "dns", "value": "sub1.example.org" } 677 ], 679 "authorizations": [ 680 "https://example.com/acme/authz/PAniVnsZcis" 681 ], 683 "finalize": "https://example.com/acme/order/ROni7rdde/finalize" 684 } 686 The client can proceed to finalize the order and download the 687 certificate for sub2.example.org. 689 6. IANA Considerations 691 6.1. Authorization Object Fields Registry 693 The following field is added to the "ACME Authorization Object 694 Fields" registry defined in ACME [RFC8555]. 696 +-----------------+------------+--------------+-----------+ 697 | Field Name | Field Type | Configurable | Reference | 698 +-----------------+------------+--------------+-----------+ 699 | domainNamespace | boolean | false | RFC XXXX | 700 +-----------------+------------+--------------+-----------+ 702 6.2. Directory Object Metadata Fields Registry 704 The following field is added to the "ACME Directory Metadata Fields" 705 registry defined in ACME [RFC8555]. 707 +-----------------+------------+-----------+ 708 | Field Name | Field Type | Reference | 709 +-----------------+------------+-----------+ 710 | domainNamespace | boolean | RFC XXXX | 711 +-----------------+------------+-----------+ 713 7. Security Considerations 715 This document documents enhancements to ACME [RFC8555] that optimize 716 the protocol flows for issuance of certificates for subdomains. The 717 underlying goal of ACME for Subdomains remains the same as that of 718 ACME: managing certificates that attest to identifier/key bindings 719 for these subdomains. Thus, ACME for Subdomains has the same two 720 security goals as ACME: 722 1. Only an entity that controls an identifier can get an 723 authorization for that identifier 725 2. Once authorized, an account key's authorizations cannot be 726 improperly used by another account 728 ACME for Subdomains makes no changes to: 730 * account or account key management 732 * ACME channel establishment, security mechanisms or threat model 734 * Validation channel establishment, security mechanisms or threat 735 model 737 Therefore, all Security Considerations in ACME in the following areas 738 are equally applicable to ACME for Subdomains: 740 * Threat Model 742 * Integrity of Authorizations 744 * Denial-of-Service Considerations 746 * Server-Side Request Forgery 748 * CA Policy Considerations 750 Some additional comments on ACME server policy are given in the 751 following section. 753 7.1. ACME Server Policy Considerations 755 The ACME for Subdomains and the ACME specifications do not mandate 756 any specific ACME server or CA policies, or any specific use cases 757 for issuance of certificates. For example, an ACME server could be 758 used: 760 * to issue Web PKI certificates where the ACME server must comply 761 with CA/Browser Forum [CAB] Baseline Requirements. 763 * as a Private CA for issuance of certificates within an 764 organisation. The organisation could enforce whatever policies 765 they desire on the ACME server. 767 * for issuance of IoT device certificates. There are currently no 768 IoT device certificate policies that are generally enforced across 769 the industry. Organizations issuing IoT device certificates can 770 enforce whatever policies they desire on the ACME server. 772 ACME server policy could specify whether: 774 * issuance of subdomain certificates is allowed based on proof of 775 ownership of a parent domain 777 * issuance of subdomain certificates is allowed, but only for a 778 specific set of parent domains 780 * whether DNS based proof of ownership, or HTTP based proof of 781 ownership, or both, are allowed 783 ACME server policy specification is explicitly out of scope of this 784 document. For reference, extracts from CA/Browser Forum Baseline 785 Requirements are given in the appendices. 787 8. Informative References 789 [CAB] CA/Browser Forum, "Baseline Requirements for the Issuance 790 and Management of Publicly-Trusted Certificates", n.d., 791 . 794 [RFC0819] Su, Z. and J. Postel, "The Domain Naming Convention for 795 Internet User Applications", RFC 819, 796 DOI 10.17487/RFC0819, August 1982, 797 . 799 [RFC1034] Mockapetris, P., "Domain names - concepts and facilities", 800 STD 13, RFC 1034, DOI 10.17487/RFC1034, November 1987, 801 . 803 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 804 Requirement Levels", BCP 14, RFC 2119, 805 DOI 10.17487/RFC2119, March 1997, 806 . 808 [RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., 809 Housley, R., and W. Polk, "Internet X.509 Public Key 810 Infrastructure Certificate and Certificate Revocation List 811 (CRL) Profile", RFC 5280, DOI 10.17487/RFC5280, May 2008, 812 . 814 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 815 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 816 May 2017, . 818 [RFC8499] Hoffman, P., Sullivan, A., and K. Fujiwara, "DNS 819 Terminology", BCP 219, RFC 8499, DOI 10.17487/RFC8499, 820 January 2019, . 822 [RFC8555] Barnes, R., Hoffman-Andrews, J., McCarney, D., and J. 823 Kasten, "Automatic Certificate Management Environment 824 (ACME)", RFC 8555, DOI 10.17487/RFC8555, March 2019, 825 . 827 Appendix A. CA Browser Forum Baseline Requirements Extracts 829 The CA/Browser Forum Baseline Requirements [CAB] allow issuance of 830 subdomain certificates where authorization is only required for a 831 parent domain. Baseline Requirements version 1.7.1 states: 833 * Section: "1.6.1 Definitions": Authorization Domain Name: The 834 Domain Name used to obtain authorization for certificate issuance 835 for a given FQDN. The CA may use the FQDN returned from a DNS 836 CNAME lookup as the FQDN for the purposes of domain validation. 837 If the FQDN contains a wildcard character, then the CA MUST remove 838 all wildcard labels from the left most portion of requested FQDN. 839 The CA may prune zero or more labels from left to right until 840 encountering a Base Domain Name and may use any one of the 841 intermediate values for the purpose of domain validation. 843 * Section: "3.2.2.4.6 Agreed-Upon Change to Website": Once the FQDN 844 has been validated using this method, the CA MAY also issue 845 Certificates for other FQDNs that end with all the labels of the 846 validated FQDN. This method is suitable for validating Wildcard 847 Domain Names. 849 * Section: "3.2.2.4.7 DNS Change": Once the FQDN has been validated 850 using this method, the CA MAY also issue Certificates for other 851 FQDNs that end with all the labels of the validated FQDN. This 852 method is suitable for validating Wildcard Domain Names. 854 Authors' Addresses 856 Owen Friel 857 Cisco 859 Email: ofriel@cisco.com 861 Richard Barnes 862 Cisco 864 Email: rlb@ipv.sx 866 Tim Hollebeek 867 DigiCert 869 Email: tim.hollebeek@digicert.com 871 Michael Richardson 872 Sandelman Software Works 874 Email: mcr+ietf@sandelman.ca