ACME for Subdomains
Cisco
ofriel@cisco.com
Cisco
rlb@ipv.sx
DigiCert
tim.hollebeek@digicert.com
Sandelman Software Works
mcr+ietf@sandelman.ca
This document outlines how ACME can be used by a client to obtain a certificate for a subdomain identifier from a certification authority. The client has fulfilled a challenge against a parent domain but does not need to fulfill a challenge against the explicit subdomain as certificate policy allows issuance of the subdomain certificate without explicit subdomain ownership proof.
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 terms are defined in the CA/Browser Forum Baseline Requirements version 1.7.1 and are reproduced here:
- Authorization Domain Name (ADN): The Domain Name used to obtain authorization for certificate issuance for a given FQDN. The CA may use the FQDN returned from a DNS CNAME lookup as the FQDN for the purposes of domain validation. If the FQDN contains a wildcard character, then the CA MUST remove all wildcard labels from the left most portion of requested FQDN. The CA may prune zero or more labels from left to right until encountering a Base Domain Name and may use any one of the intermediate values for the purpose of domain validation
- Base Domain Name: The portion of an applied-for FQDN that is the first domain name node left of a registry-controlled or public suffix plus the registry-controlled or public suffix (e.g. "example.co.uk" or "example.com"). For FQDNs where the right-most domain name node is a gTLD having ICANN Specification 13 in its registry agreement, the gTLD itself may be used as the Base Domain Name.
- 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
- Domain Namespace: The set of all possible Domain Names that are subordinate to a single node in the Domain Name System
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 a Domain Namespace subordinate to a given ADN, as opposed to just requesting authorization for an explicit ADN 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 an entire Domain Namespace. 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 ADN of a requested certificate FQDN identifier, then the server MUST issue a "dns-01" challenge against that parent ADN.
Authorization Object
ACME section 7.1.4 defines the authorization object. When ACME server policy allows authorization for Domain Namespaces subordinate to an ADN, the server indicates this by including the "domainNamespace" flag in the authorization object for that ADN identifier:
The following example shows an authorization object for the ADN example.org where the authorization covers the Domain Namespace subordinate to example.org.
If the "domainNamespace" 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 parent ADN once, and then issue multiple newOrder requests for certificates with identifiers in the Domain Namespace subordinate to that ADN.
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 Domain Namespace authorization. In the following example newAuthz payload, the client is requesting pre-authorization for the Domain Namespace subordinate to example.org.
If the server is willing to allow a single authorization for the Domain Namespace, and there is not an existing authorization object for the identifier, then it will create an authorization object and include the "domainNamespace" flag with value of true. If the server policy does not allow creation of Domain Namespace authorizations subordinate to that ADN, the server can create an authorization object for the indicated identifier, and include the "domainNamespace" 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 ADNs 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 ADNs bar.example.org or example.org, then the client needs a mechanism to indicate control over the parent ADNs to the ACME server.
This can be achieved by adding an optional field "domainNamespace" to the "identifiers" field in the order object:
This field specifies the ADN of the Domain Namespace 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 in the Domain Namespace up to and including the specified "domainNamespace", 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 ADN and the Domain Namespace subordinate to 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 ADN and the Domain Namespace subordinate to 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 ADNs, the client should not include the "domainNamespace" field.
Server newOrder handling generally follows the process documented ACME section 7.4. If the server is willing to allow Domain Namespace authorizations for the ADN specified in "domainNamespace", then it creates an authorization object against that ADN and includes the "domainNamespace" flag with a value of true. If the server policy does not allow creation of Domain Namespace authorizations against that ADN, then it can create an authorization object for the indicated identifier value, and include the "domainNamespace" flag with value of false.
Directory Object Metadata
An ACME server can advertise support for authorization of Domain Namespaces 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 Domain Namespaces, 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 Domain Namespace
The client sends a newAuthz request for the parent ADN of the Domain Namespace including the "domainNamespace" flag in the identifier object.
The server creates and returns an authorization object for the identifier including the "domainNamespace" 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".
-
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 in the Domain Namespace that has been pre-authorised in step 1. The client does not need to include the "domainNamespace" field in the "identifier" object as it has already pre-authorized the Domain Namespace.
As an authorization object already exists for the parent ADN of the Domain Namespace, the server replies with an order object with a status of "valid" that includes a link to the existing "valid" authorization object.
;rel="index"
Location: https://example.com/acme/order/TOlocE8rfgo
{
"status": "valid",
"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 in the Domain Namespace that has been pre-authorised in step 1. The client does not need to include the "domainNamespace" field in the "identifier" object as it has already pre-authorized the Domain Namespace.
As an authorization object already exists for the parent ADN of the Domain Namespace, the server replies with an order object with a status of "valid" that includes a link to the existing "valid" authorization object.
;rel="index"
Location: https://example.com/acme/order/TOlocE8rfgo
{
"status": "valid",
"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. For reference, extracts from CA/Browser Forum Baseline Requirements are given in the appendices.
Informative References
Baseline Requirements for the Issuance and Management of Publicly-Trusted Certificates
CA/Browser Forum
n.d.
Automatic Certificate Management Environment (ACME)
Public Key Infrastructure using X.509 (PKIX) certificates are used for a number of purposes, the most significant of which is the authentication of domain names. Thus, certification authorities (CAs) in the Web PKI are trusted to verify that an applicant for a certificate legitimately represents the domain name(s) in the certificate. As of this writing, this verification is done through a collection of ad hoc mechanisms. This document describes a protocol that a CA and an applicant can use to automate the process of verification and certificate issuance. The protocol also provides facilities for other certificate management functions, such as certificate revocation.
Internet X.509 Public Key Infrastructure Certificate and Certificate Revocation List (CRL) Profile
This memo profiles the X.509 v3 certificate and X.509 v2 certificate revocation list (CRL) for use in the Internet. An overview of this approach and model is provided as an introduction. The X.509 v3 certificate format is described in detail, with additional information regarding the format and semantics of Internet name forms. Standard certificate extensions are described and two Internet-specific extensions are defined. A set of required certificate extensions is specified. The X.509 v2 CRL format is described in detail along with standard and Internet-specific extensions. An algorithm for X.509 certification path validation is described. An ASN.1 module and examples are provided in the appendices. [STANDARDS-TRACK]
Key words for use in RFCs to Indicate Requirement Levels
In many standards track documents several words are used to signify the requirements in the specification. These words are often capitalized. This document defines these words as they should be interpreted in IETF documents. This document specifies an Internet Best Current Practices for the Internet Community, and requests discussion and suggestions for improvements.
Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words
RFC 2119 specifies common key words that may be used in protocol specifications. This document aims to reduce the ambiguity by clarifying that only UPPERCASE usage of the key words have the defined special meanings.
DNS Terminology
The Domain Name System (DNS) is defined in literally dozens of different RFCs. The terminology used by implementers and developers of DNS protocols, and by operators of DNS systems, has sometimes changed in the decades since the DNS was first defined. This document gives current definitions for many of the terms used in the DNS in a single document.
This document obsoletes RFC 7719 and updates RFC 2308.
Domain names - concepts and facilities
This RFC is the revised basic definition of The Domain Name System. It obsoletes RFC-882. This memo describes the domain style names and their used for host address look up and electronic mail forwarding. It discusses the clients and servers in the domain name system and the protocol used between them.
The Domain Naming Convention for Internet User Applications
This RFC is an attempt to clarify the generalization of the Domain Naming Convention, the Internet Naming Convention, and to explore the implications of its adoption for Internet name service and user applications.
CA Browser Forum Baseline Requirements Extracts
The CA/Browser Forum Baseline Requirements allow issuance of subdomain certificates where authorization is only required for a parent domain. Baseline Requirements version 1.7.1 states:
- Section: "1.6.1 Definitions": Authorization Domain Name: The Domain Name used to obtain authorization for certificate issuance for a given FQDN. The CA may use the FQDN returned from a DNS CNAME lookup as the FQDN for the purposes of domain validation. If the FQDN contains a wildcard character, then the CA MUST remove all wildcard labels from the left most portion of requested FQDN. The CA may prune zero or more labels from left to right until encountering a Base Domain Name and may use any one of the intermediate values for the purpose of domain validation.
- Section: "3.2.2.4.6 Agreed-Upon Change to Website": Once the FQDN has been validated using this method, the CA MAY also issue Certificates for other FQDNs that end with all the labels of the validated FQDN. This method is suitable for validating Wildcard Domain Names.
- Section: "3.2.2.4.7 DNS Change": Once the FQDN has been validated using this method, the CA MAY also issue Certificates for other FQDNs that end with all the labels of the validated FQDN. This method is suitable for validating Wildcard Domain Names.