ACME for Subdomains

Introduction ACME 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) certificate issuance. 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 a parent domain identifier.

Terminology 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 when, and only when, they appear in all capitals, as shown here. The following terms are defined in DNS Terminology and are reproduced here:

Label: An ordered list of zero or more octets that makes up a portion of a domain name. Using graph theory, a label identifies one node in a portion of the graph of all possible domain names.
Domain Name: An ordered list of one or more labels.
Subdomain: "A domain is a subdomain of another domain if it is contained within that domain. This relationship can be tested by seeing if the subdomain's name ends with the containing domain's name." (Quoted from , Section 3.1) For example, in the host name "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".
Fully-Qualified Domain Name (FQDN): This is often just a clear way of saying the same thing as "domain name of a node", as outlined above. However, the term is ambiguous. Strictly speaking, a fully-qualified domain name would include every label, including the zero-length label of the root: such a name would be written "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 . In this document, names are often written relative to the root.

The following additional terms are used in this document:

Certification Authority (CA): An organization that is responsible for the creation, issuance, revocation, and management of Certificates. The term applies equally to both Roots CAs and Subordinate CAs
CSR: Certificate Signing Request
Parent Domain: a domain is a parent domain of a subdomain if it contains that subdomain, as per the definition of subdomain. For example, for the host name "nnn.mmm.example.com", both "mmm.example.com" and "example.com" are parent domains of "nnn.mmm.example.com".

ACME Workflow and Identifier Requirements A typical ACME workflow for issuance of certificates is as follows:

client POSTs a newOrder request that contains a set of "identifiers"
server replies with a set of "authorizations" and a "finalize" URI
client sends POST-as-GET requests to retrieve the "authorizations", with the downloaded "authorization" object(s) containing the "identifier" that the client must prove that they control, and a set of associated "challenges", one of which the the client must fulfil
client proves control over the "identifier" in the "authorization" object by completing one of the specified challenges, for example, by publishing a DNS TXT record
client POSTs a CSR to the "finalize" API
server replies with an updated order object that includes a "certificate" URI
client sends POST-as-GET request to the "certificate" URI to download the certificate

ACME places the following restrictions on "identifiers":

section 7.1.3: The authorizations required are dictated by server policy; there may not be a 1:1 relationship between the order identifiers and the authorizations required.
section 7.1.4: the only type of "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."
section 7.4: the "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."
section 8.3: the "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"
section 8.4: the "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.

ACME Issuance of Subdomain Certificates As noted in the previous section, ACME 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 a parent domain of that subdomain. This allows a flow where a client proves ownership of, for example, "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 . 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.

ACME Challenge Type ACME for subdomains is restricted for use with "dns-01" challenges. If a server policy allows a client to fulfill a challenge against a parent domain of a requested certificate FQDN identifier, then the server MUST issue a "dns-01" challenge against that parent domain.

Authorization Object ACME section 7.1.4 defines the authorization object. When ACME server policy allows authorization for subdomains subordinate to an domain, the server indicates this by including the "subdomains" flag in the authorization object for that domain identifier: The following example shows an authorization object for the domain example.org where the authorization covers the subdomains subordinate to example.org. If the "subdomains" field is not included, then the assumed default value is false.

Pre-Authorization The standard ACME workflow has authorization objects created reactively in response to a certificate order. ACME also allows for pre-authorization, where clients obtain authorization for an identifier proactively, outside of the context of a specific issuance. With the ACME pre-authorization flow, a client can pre-authorize for a domain once, and then issue multiple newOrder requests for certificates with identifiers in the subdomains subordinate to that domain. ACME section 7.4.1 defines the "identifier" object for newAuthz requests. One additional field for the "identifier" object is defined: Clients include the flag in the "identifier" object of newAuthz requests to indicate that they are requesting a subdomain authorization. In the following example newAuthz payload, the client is requesting pre-authorization for the subdomains subordinate to example.org. If the server is willing to allow a single authorization for the subdomains, and there is not an existing authorization object for the identifier, then it will create an authorization object and include the "subdomains" flag with value of true. If the server policy does not allow creation of subdomain authorizations subordinate to that domain, the server can create an authorization object for the indicated identifier, and include the "subdomains" flag with value of false. In both scenarios, handling of the pre-authorization follows the process documented in ACME section 7.4.1.

New Orders Clients need a mechanism to optionally indicate to servers whether or not they are authorized to fulfill challenges against parent domains for a given identifier FQDN. For example, if a client places an order for an identifier foo.bar.example.org, and is authorized to update DNS TXT records against the parent domains bar.example.org or example.org, then the client needs a mechanism to indicate control over the parent domains to the ACME server. This can be achieved by adding an optional field "parentDomain" to the "identifiers" field in the order object: This field specifies a parent 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 parent domain of the identifier up to and including the specified "parentDomain", and create a corresponding authorization object against the chosen identifier. In the following example newOrder payload, the client requests a certificate for identifier foo.bar.example.org and indicates that it can fulfill a challenge against the parent domain bar.example.org. The server can then choose to issue a challenge against either foo.bar.example.org or bar.example.org identifiers. In the following example newOrder payload, the client requests a certificate for identifier foo.bar.example.org and indicates that it can fulfill a challenge against the parent 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. If the client is unable to fulfill authorizations against parent domain, the client should not include the "parentDomain" field. Server newOrder handling generally follows the process documented ACME section 7.4. If the server is willing to allow subdomain authorizations for the domain specified in "parentDomain", then it creates an authorization object against that parent domain and includes the "subdomains" flag with a value of true. If the server policy does not allow creation of subdomain authorizations against that parent domain, then it can create an authorization object for the indicated identifier value, and includes the "subdomains" flag with value of false.

Directory Object Metadata An ACME server can advertise support for authorization of subdomains by including the following boolean flag in its "ACME Directory Metadata Fields" registry: If not specified, then no default value is assumed. If an ACME server supports authorization of subdomains, it can indicate this by including this field with a value of "true".

Illustrative Call Flow The call flow illustrated here uses the ACME pre-authorization flow using DNS-based proof of ownership. | | | | | | 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 parent domain The client sends a newAuthz request for the parent domain including the "subdomains" flag in the identifier object.

The server creates and returns an authorization object for the identifier including the "subdomains" flag. The object is initially in "pending" state. Once the client completes the challenge, the server will transition the authorization object and associated challenge object status to "valid". The 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, so the client may need to poll the authorization resource to see when it is finalized.

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 parent domain that has been pre-authorised in step 1. The client does not need to include the "subdomains" field in the "identifier" object as it has already pre-authorized the parent domain.

As an authorization object already exists for the parent domain, the server replies with an order object with a status of "ready" that includes a link to the existing "valid" authorization object. ;rel="index" Location: https://example.com/acme/order/TOlocE8rfgo { "status": "ready", "expires": "2016-01-05T14:09:07.99Z", "notBefore": "2016-01-01T00:00:00Z", "notAfter": "2016-01-08T00:00:00Z", "identifiers": [ { "type": "dns", "value": "sub1.example.org" } ], "authorizations": [ "https://example.com/acme/authz/PAniVnsZcis" ], "finalize": "https://example.com/acme/order/TOlocrfgo/finalize" } ]]> The client can proceed to finalize the order and 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 parent domain that has been pre-authorised in step 1. The client does not need to include the "subdomains" field in the "identifier" object as it has already pre-authorized the parent domain.

As an authorization object already exists for the parent domain, the server replies with an order object with a status of "ready" that includes a link to the existing "valid" authorization object. ;rel="index" Location: https://example.com/acme/order/TOlocE8rfgo { "status": "ready", "expires": "2016-01-05T14:09:07.99Z", "notBefore": "2016-01-01T00:00:00Z", "notAfter": "2016-01-08T00:00:00Z", "identifiers": [ { "type": "dns", "value": "sub1.example.org" } ], "authorizations": [ "https://example.com/acme/authz/PAniVnsZcis" ], "finalize": "https://example.com/acme/order/ROni7rdde/finalize" } ]]> The client can proceed to finalize the order and download the certificate for sub2.example.org.

IANA Considerations

Authorization Object Fields Registry The following field is added to the "ACME Authorization Object Fields" registry defined in ACME .

Directory Object Metadata Fields Registry The following field is added to the "ACME Directory Metadata Fields" registry defined in ACME .

Security Considerations This document documents enhancements to ACME 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:

Only an entity that controls an identifier can get an authorization for that identifier
Once authorized, an account key's authorizations cannot be improperly used by another account

ACME for Subdomains makes no changes to:

account or account key management
ACME channel establishment, security mechanisms or threat model
Validation channel establishment, security mechanisms or threat model

Therefore, all Security Considerations in ACME in the following areas are equally applicable to ACME for Subdomains:

Threat Model
Integrity of Authorizations
Denial-of-Service Considerations
Server-Side Request Forgery
CA Policy Considerations

Some additional comments on ACME server policy are given in the following section.

ACME Server Policy Considerations 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:

to issue Web PKI certificates where the ACME server must comply with CA/Browser Forum Baseline Requirements.
as a Private CA for issuance of certificates within an organisation. The organisation could enforce whatever policies they desire on the ACME server.
for issuance of IoT device certificates. There are currently no IoT device certificate policies that are generally enforced across the industry. Organizations issuing IoT device certificates can enforce whatever policies they desire on the ACME server.

ACME server policy could specify whether:

issuance of subdomain certificates is allowed based on proof of ownership of a parent domain
issuance of subdomain certificates is allowed, but only for a specific set of parent domains
whether DNS based proof of ownership, or HTTP based proof of ownership, or both, are allowed

ACME server policy specification is explicitly out of scope of this document.