RFC 9444 | ACME for Subdomains | August 2023 |
Friel, et al. | Standards Track | [Page] |
This document specifies how Automated Certificate Management Environment (ACME) can be used by a client to obtain a certificate for a subdomain identifier from a certification authority. Additionally, this document specifies how a client can fulfill a challenge against an ancestor domain but may not need to fulfill a challenge against the explicit subdomain if certification authority policy allows issuance of the subdomain certificate without explicit subdomain ownership proof.¶
This is an Internet Standards Track document.¶
This document is a product of the Internet Engineering Task Force (IETF). It represents the consensus of the IETF community. It has received public review and has been approved for publication by the Internet Engineering Steering Group (IESG). Further information on Internet Standards is available in Section 2 of RFC 7841.¶
Information about the current status of this document, any errata, and how to provide feedback on it may be obtained at https://www.rfc-editor.org/info/rfc9444.¶
Copyright (c) 2023 IETF Trust and the persons identified as the document authors. All rights reserved.¶
This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Revised BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Revised BSD License.¶
ACME [RFC8555] defines a protocol that a certification authority (CA) and an applicant can use to automate the process of domain name ownership validation and X.509v3 (PKIX) [RFC5280] certificate issuance. The CA is the ACME server and the applicant is the ACME client, and the client uses the ACME protocol to request certificate issuance from the server. This document outlines how ACME can be used to issue subdomain certificates without requiring the ACME client to explicitly fulfill an ownership challenge against the subdomain identifiers -- the ACME client need only fulfill an ownership challenge against an ancestor domain identifier.¶
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.¶
The following terms are defined in "DNS Terminology" [RFC8499] and are reproduced here:¶
www.example.net.
(note the terminating dot). But, because every
name eventually shares the common root, names are often written
relative to the root (such as www.example.net
) and are still
called "fully qualified". This term first appeared in [RFC0819].
In this document, names are often written relative to the root.¶
The following definition for "subdomain" is taken from "DNS Terminology" [RFC8499] and reproduced here; however, the definition is ambiguous and is further clarified below:¶
nnn.mmm.example.com
, both mmm.example.com
and
nnn.mmm.example.com
are subdomains of example.com
. Note that
the comparisons here are done on whole labels; that is,
ooo.example.com
is not a subdomain of oo.example.com
.¶
The definition is ambiguous as it appears to allow a subdomain to include the given domain. That is, mmm.example.com
ends with mmm.example.com
and thus is a subdomain of itself. This document interprets the first sentence of the above definition as meaning "a domain is a subdomain of a different domain if it is contained within that different domain". A domain cannot be a subdomain of itself. For example, mmm.example.com
is not a subdomain of mmm.example.com
.¶
The following additional terms are used in this document:¶
nnn.mmm.example.com
, both mmm.example.com
and example.com
are ancestor domains of nnn.mmm.example.com
. However, nnn.mmm.example.com
is not an ancestor domain of nnn.mmm.example.com
. Note that the comparisons here are done on whole labels; that is, oo.example.com
is not an ancestor domain of ooo.example.com
.¶
[RFC8555] defines the following object types that are used in this document:¶
ACME [RFC8555], Section 6.3 introduces the following term which is used in this document:¶
A typical ACME workflow for issuance of certificates is as follows:¶
identifiers
field of the ACME order object.¶
finalize
URI.¶
identifier
that the client must prove that they control, and a set of links to associated challenge objects, one of which the client must fulfill.¶
identifier
in the authorization object by completing one of the specified challenges, for example, by publishing a DNS TXT record.¶
finalize
API.¶
certificate
URI.¶
certificate
URI to download the certificate.¶
ACME places the following restrictions on identifiers
:¶
identifier
defined by the ACME specification is an FQDN: "The only type of identifier defined by this specification is a fully qualified domain name (type: "dns"). The domain name MUST be encoded in the form in which it would appear in a certificate."¶
identifier
in the CSR request must match the identifier
in the newOrder request: "The CSR MUST indicate the exact same set of requested identifiers as the initial newOrder request."¶
identifier
, or FQDN, in the authorization object must be used when fulfilling challenges via HTTP: "Construct a URL by populating the URL template ... where the domain
field is set to the domain name being verified."¶
identifier
, or FQDN, in the authorization object must be used when fulfilling challenges via DNS: "The client constructs the validation domain name by prepending the label "_acme-challenge" to the domain name being validated."¶
ACME does not mandate that the identifier
in a newOrder request matches the identifier
in authorization objects.¶
The ACME base document [RFC8555] only specifies the "dns" identifier type. Additional identifiers may be defined and registered in the IANA [ACME-Identifier-Types] registry. For example, [RFC8738] specifies the "ip" identifier type. This document is only relevant for the "dns" identifier type.¶
Note that ACME supports multiple different validation methods that can be used to fulfill challenges and prove ownership of identifiers. Validation methods are registered in the IANA [ACME-Validation-Methods] registry. This document does not mandate use of any particular validation method or methods. ACME server policy dictates which validation methods are supported. See Section 7.3 for more information on ACME server policy.¶
As noted in the previous section, ACME [RFC8555] does not mandate that the identifier
in a newOrder request matches the identifier
in authorization objects. This means that the ACME specification does not preclude an ACME server processing newOrder requests and issuing certificates for a subdomain without requiring a challenge to be fulfilled against that explicit subdomain.¶
ACME server policy could allow issuance of certificates for a subdomain to a client where the client only has to fulfill an authorization challenge for an ancestor domain of that subdomain. For example, this allows for a flow where a client proves ownership of example.org
and then successfully obtains a certificate for sub.example.org
.¶
ACME server policy is out of scope of this document; however, some commentary is provided in Section 7.3.¶
Clients need a mechanism to instruct the ACME server that they are requesting authorization for all subdomains subordinate to the specified domain, as opposed to just requesting authorization for an explicit domain identifier. Clients need a mechanism to do this in both newAuthz and newOrder requests. ACME servers need a mechanism to indicate to clients that authorization objects are valid for all subdomains under the specified domain. These are described in this section.¶
Clients need a mechanism to optionally indicate to servers whether or not they are authorized to fulfill challenges against an ancestor domain for a given identifier. For example, if a client places an order for an identifier foo.bar.example.org
and is authorized to fulfill a challenge against the ancestor domains bar.example.org
or example.org
, then the client needs a mechanism to indicate control over the ancestor domains to the ACME server.¶
In order to accomplish this, this document defines a new ancestorDomain
field for the identifier that is included in order objects.¶
ancestorDomain
(optional, string):This field specifies an ancestor domain of the identifier that the client has DNS control over and is capable of fulfilling challenges against. Based on server policy, the server can choose to issue a challenge against any ancestor domain of the identifier up to and including the specified ancestorDomain
and create a corresponding authorization object against the chosen identifier.¶
In the following example of a newOrder payload, the client requests a certificate for identifier foo.bar.example.org
and indicates that it can fulfill a challenge against the ancestor domain bar.example.org
. The server can then choose to issue a challenge against either foo.bar.example.org
or bar.example.org
identifiers.¶
"payload": base64url({ "identifiers": [ { "type": "dns", "value": "foo.bar.example.org", "ancestorDomain": "bar.example.org" } ], "notBefore": "2023-09-01T00:04:00+04:00", "notAfter": "2023-09-08T00:04:00+04:00" })¶
In the following example of a newOrder payload, the client requests a certificate for identifier foo.bar.example.org
and indicates that it can fulfill a challenge against the ancestor domain example.org
. The server can then choose to issue a challenge against any one of foo.bar.example.org
, bar.example.org
, or example.org
identifiers.¶
"payload": base64url({ "identifiers": [ { "type": "dns", "value": "foo.bar.example.org", "ancestorDomain": "example.org" } ], "notBefore": "2023-09-01T00:04:00+04:00", "notAfter": "2023-09-08T00:04:00+04:00" })¶
If the client is unable to fulfill authorizations against an ancestor domain, the client should not include the ancestorDomain
field.¶
Server newOrder handling generally follows the process documented in ACME (Section 7.4 of [RFC8555]). If the server is willing to allow subdomain authorizations for the domain specified in ancestorDomain
, then it creates an authorization object against that ancestor domain and includes the subdomainAuthAllowed
flag with a value of true.¶
If the server policy does not allow creation of subdomain authorizations against that ancestor domain, then it can create an authorization object for the indicated identifier value and SHOULD NOT include the subdomainAuthAllowed
flag. As the client requested a subdomain authorization for the ancestor domain and not for the indicated identifier, there is no need for the server to include the subdomainAuthAllowed
flag in the authorization object for the indicated identifier.¶
This document defines a new subdomainAuthAllowed
ACME directory metadata field. An ACME server can advertise support for authorization of subdomains by including the subdomainAuthAllowed
boolean flag in its "ACME Directory Metadata Fields" registry:¶
subdomainAuthAllowed
(optional, bool):If not specified, then the assumed default value is false. If an ACME server supports authorization of subdomains, it can indicate this by including this field with a value of "true".¶
The call flow illustrated here uses the ACME pre-authorization flow using DNS-based proof of ownership.¶
+--------+ +------+ +-----+ | Client | | ACME | | DNS | +--------+ +------+ +-----+ | | | Step 1: Pre-authorization of ancestor domain. | | | | POST /newAuthz | | | "example.org" | | |--------------------------->| | | | | | 201 authorizations | | |<---------------------------| | | | | | Publish DNS TXT | | | "example.org" | | |--------------------------------------->| | | | | POST /challenge | | |--------------------------->| | | | Verify | | |---------->| | 200 status=valid | | |<---------------------------| | | | | | Delete DNS TXT | | | "example.org" | | |--------------------------------------->| | | | Step 2: Place order for sub1.example.org. | | | | POST /newOrder | | | "sub1.example.org" | | |--------------------------->| | | | | | 201 status=ready | | |<---------------------------| | | | | | POST /finalize | | | CSR SAN "sub1.example.org" | | |--------------------------->| | | | | | 200 OK status=valid | | |<---------------------------| | | | | | POST /certificate | | |--------------------------->| | | | | | 200 OK | | | PEM SAN "sub1.example.org" | | |<---------------------------| | | | | Step 3: Place order for sub2.example.org. | | | | POST /newOrder | | | "sub2.example.org" | | |--------------------------->| | | | | | 201 status=ready | | |<---------------------------| | | | | | POST /finalize | | | CSR SAN "sub2.example.org" | | |--------------------------->| | | | | | 200 OK status=valid | | |<---------------------------| | | | | | POST /certificate | | |--------------------------->| | | | | | 200 OK | | | PEM SAN "sub2.example.org" | | |<---------------------------| |¶
Step 1: Pre-authorization of ancestor domain.¶
The client sends a newAuthz request for the ancestor domain and includes the subdomainAuthAllowed
flag in the identifier object.¶
The server creates and returns an authorization object for the identifier that includes the subdomainAuthAllowed
flag. The object is initially in "pending" state.¶
{ "status": "pending", "expires": "2023-09-01T14:09:07.99Z", "identifier": { "type": "dns", "value": "example.org" }, "challenges": [ { "url": "https://example.com/acme/chall/prV_B7yEyA4", "type": "dns-01", "status": "pending", "token": "DGyRejmCefe7v4NfDGDKfA", "validated": "2023-08-01T12:05:58.16Z" } ], "subdomainAuthAllowed": true }¶
The example illustrates the client completing a DNS challenge by publishing a DNS TXT record. The client then posts to the challenge resource to inform the server that it can validate the challenge.¶
Once the server validates the challenge by checking the DNS TXT record, the server will transition the authorization object and associated challenge object status to "valid".¶
The call flow above illustrates the ACME server replying to the client's challenge with status of "valid" after the ACME server has validated the DNS challenge. However, the validation flow may take some time. If this is the case, the ACME server may reply to the client's challenge immediately with a status of "processing" and the client will then need to poll the authorization resource to see when it is finalized. Refer to Section 7.5.1 of [RFC8555] for more details.¶
Step 2: The client places a newOrder for sub1.example.org
.¶
The client sends a newOrder request to the server and includes the subdomain identifier. Note that the identifier is a subdomain of the ancestor domain that has been pre-authorized in Step 1. The client does not need to include the subdomainAuthAllowed
field in the identifier
object, as it has already pre-authorized the ancestor domain.¶
As an authorization object already exists for the ancestor domain, the server replies with an order object with a status of "ready" that includes a link to the existing "valid" authorization object.¶
The client can proceed to finalize the order by posting a CSR to the finalize
resource. The client can then download the certificate for sub1.example.org
.¶
Step 3: The client places a newOrder for sub2.example.org
.¶
The client sends a newOrder request to the server and includes the subdomain identifier. Note that the identifier is a subdomain of the ancestor domain that has been pre-authorized in Step 1. The client does not need to include the subdomainAuthAllowed
field in the identifier
object, as it has already pre-authorized the ancestor domain.¶
As an authorization object already exists for the ancestor domain, the server replies with an order object with a status of "ready" that includes a link to the existing "valid" authorization object.¶
The client can proceed to finalize the order by posting a CSR to the finalize
resource. The client can then download the certificate for sub2.example.org
.¶
The following field has been added to the "ACME Directory Metadata Fields" registry defined in [RFC8555].¶
Field Name | Field Type | Reference |
---|---|---|
subdomainAuthAllowed | boolean | RFC 9444 |
This document specifies enhancements to ACME [RFC8555] that optimize the protocol flows for issuance of certificates for subdomains. The underlying goal of ACME for Subdomains remains the same as that of ACME: managing certificates that attest to identifier/key bindings for these subdomains. Thus, ACME for Subdomains has the same two security goals as ACME:¶
ACME for Subdomains makes no changes to:¶
Therefore, all Security Considerations in ACME in the following areas are equally applicable to ACME for Subdomains:¶
The only exception is that in order to satisfy goal (1) above, this document assumes that control over a domain may imply control over a subdomain; therefore, authorization for certificate issuance for the former may imply authorization for certificate issuance for the latter. In many ecosystems, this is a safe assumption, especially because control over the domain can often be leveraged to successfully demonstrate control over subdomains anyway, for example, by temporarily modifying DNS for the subdomain to point to a server the ancestor domain owner controls, rendering the distinction moot. For example, the CA/Browser Forum Baseline Requirements may consider control of an ancestor domain sufficient for issuance of certificates for subdomains, but only if specific processes and procedures are used for validating ownership of the ancestor domain.¶
In ecosystems where control of an ancestor domain may not imply control over subdomains or authorization for issuance of certificates for subdomains, a more complicated threat analysis and server policy might be needed.¶
Some additional comments on ACME server policy are given later in this section.¶
There may be scenarios were a client wishes to deactivate an authorization object for an ancestor domain or deactivate its account completely. For example, a client may want to do this if an account key is compromised or if an authorization object covering domains subordinate to an ancestor domain is no longer needed. The client can deactivate an authorization using the mechanism specified in [RFC8555], Section 7.5.2 and can deactivate an account using the mechanism specified in [RFC8555], Section 7.3.6.¶
The [RFC8499] definition of a subdomain is reproduced in Section 2. When comparing domains to determine if one is a subdomain of the other, it is important to compare entire labels and not rely on a string prefix match. Relying on string prefix matches may yield incorrect results.¶
The ACME for Subdomains and the ACME specifications do not mandate any specific ACME server or CA policies, or any specific use cases for issuance of certificates. For example, an ACME server could be used:¶
ACME server policy could specify whether:¶
The CA policy considerations listed in [RFC8555], Section 10.5 are equally applicable here. These include, but are not limited to:¶
For domain names:¶
Refer to [RFC8555], Section 10.5 for more CA policy considerations.¶
ACME server policy specification is explicitly out of scope of this document.¶