draft-ietf-acme-subdomains-00.txt   draft-ietf-acme-subdomains-01.txt 
Network Working Group O. Friel Network Working Group O. Friel
Internet-Draft R. Barnes Internet-Draft R. Barnes
Intended status: Standards Track Cisco Intended status: Standards Track Cisco
Expires: 28 April 2022 T. Hollebeek Expires: June 20, 2022 T. Hollebeek
DigiCert DigiCert
M. Richardson M. Richardson
Sandelman Software Works Sandelman Software Works
25 October 2021 December 17, 2021
ACME for Subdomains ACME for Subdomains
draft-ietf-acme-subdomains-00 draft-ietf-acme-subdomains-01
Abstract Abstract
This document outlines how ACME can be used by a client to obtain a This document outlines how ACME can be used by a client to obtain a
certificate for a subdomain identifier from a certification certificate for a subdomain identifier from a certification
authority. The client has fulfilled a challenge against a parent authority. The client has fulfilled a challenge against a parent
domain but does not need to fulfill a challenge against the explicit domain but does not need to fulfill a challenge against the explicit
subdomain as certificate policy allows issuance of the subdomain subdomain as certification authority policy allows issuance of the
certificate without explicit subdomain ownership proof. subdomain certificate without explicit subdomain ownership proof.
Status of This Memo Status of This Memo
This Internet-Draft is submitted in full conformance with the This Internet-Draft is submitted in full conformance with the
provisions of BCP 78 and BCP 79. provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet- working documents as Internet-Drafts. The list of current Internet-
Drafts is at https://datatracker.ietf.org/drafts/current/. Drafts is at https://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." material or to cite them other than as "work in progress."
This Internet-Draft will expire on 28 April 2022. This Internet-Draft will expire on June 20, 2022.
Copyright Notice Copyright Notice
Copyright (c) 2021 IETF Trust and the persons identified as the Copyright (c) 2021 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents (https://trustee.ietf.org/ Provisions Relating to IETF Documents
license-info) in effect on the date of publication of this document. (https://trustee.ietf.org/license-info) in effect on the date of
Please review these documents carefully, as they describe your rights publication of this document. Please review these documents
and restrictions with respect to this document. Code Components carefully, as they describe your rights and restrictions with respect
extracted from this document must include Simplified BSD License text to this document. Code Components extracted from this document must
as described in Section 4.e of the Trust Legal Provisions and are include Simplified BSD License text as described in Section 4.e of
provided without warranty as described in the Simplified BSD License. the Trust Legal Provisions and are provided without warranty as
described in the Simplified BSD License.
Table of Contents Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2
2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 2 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 2
3. ACME Workflow and Identifier Requirements . . . . . . . . . . 4 3. ACME Workflow and Identifier Requirements . . . . . . . . . . 4
4. ACME Issuance of Subdomain Certificates . . . . . . . . . . . 5 4. ACME Issuance of Subdomain Certificates . . . . . . . . . . . 5
4.1. ACME Challenge Type . . . . . . . . . . . . . . . . . . . 6 4.1. ACME Challenge Type . . . . . . . . . . . . . . . . . . . 5
4.2. Authorization Object . . . . . . . . . . . . . . . . . . 6 4.2. Authorization Object . . . . . . . . . . . . . . . . . . 6
4.3. Pre-Authorization . . . . . . . . . . . . . . . . . . . . 7 4.3. Pre-Authorization . . . . . . . . . . . . . . . . . . . . 6
4.4. New Orders . . . . . . . . . . . . . . . . . . . . . . . 8 4.4. New Orders . . . . . . . . . . . . . . . . . . . . . . . 7
4.5. Directory Object Metadata . . . . . . . . . . . . . . . . 10 4.5. Directory Object Metadata . . . . . . . . . . . . . . . . 9
5. Illustrative Call Flow . . . . . . . . . . . . . . . . . . . 10 5. Illustrative Call Flow . . . . . . . . . . . . . . . . . . . 9
6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 16 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 15
6.1. Authorization Object Fields Registry . . . . . . . . . . 16 6.1. Authorization Object Fields Registry . . . . . . . . . . 15
6.2. Directory Object Metadata Fields Registry . . . . . . . . 16 6.2. Directory Object Metadata Fields Registry . . . . . . . . 15
7. Security Considerations . . . . . . . . . . . . . . . . . . . 17 7. Security Considerations . . . . . . . . . . . . . . . . . . . 16
7.1. ACME Server Policy Considerations . . . . . . . . . . . . 18 7.1. ACME Server Policy Considerations . . . . . . . . . . . . 17
8. Informative References . . . . . . . . . . . . . . . . . . . 18 8. References . . . . . . . . . . . . . . . . . . . . . . . . . 17
Appendix A. CA Browser Forum Baseline Requirements Extracts . . 19 8.1. Normative References . . . . . . . . . . . . . . . . . . 17
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 20 8.2. Informative References . . . . . . . . . . . . . . . . . 18
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 18
1. Introduction 1. Introduction
ACME [RFC8555] defines a protocol that a certification authority (CA) ACME [RFC8555] defines a protocol that a certification authority (CA)
and an applicant can use to automate the process of domain name and an applicant can use to automate the process of domain name
ownership validation and X.509v3 (PKIX) [RFC5280] certificate ownership validation and X.509v3 (PKIX) [RFC5280] certificate
issuance. This document outlines how ACME can be used to issue issuance. This document outlines how ACME can be used to issue
subdomain certificates, without requiring the ACME client to subdomain certificates, without requiring the ACME client to
explicitly fulfill an ownership challenge against the subdomain explicitly fulfill an ownership challenge against the subdomain
identifiers - the ACME client need only fulfill an ownership identifiers - the ACME client need only fulfill an ownership
challenge against a parent domain identifier. challenge against a parent domain identifier.
2. Terminology 2. Terminology
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
"OPTIONAL" in this document are to be interpreted as described in BCP "OPTIONAL" in this document are to be interpreted as described in
14 [RFC2119] [RFC8174] when, and only when, they appear in all BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all
capitals, as shown here. capitals, as shown here.
The following terms are defined in DNS Terminology [RFC8499] and are The following terms are defined in DNS Terminology [RFC8499] and are
reproduced here: reproduced here:
* Label: An ordered list of zero or more octets that makes up a o Label: An ordered list of zero or more octets that makes up a
portion of a domain name. Using graph theory, a label identifies portion of a domain name. Using graph theory, a label identifies
one node in a portion of the graph of all possible domain names. one node in a portion of the graph of all possible domain names.
* Domain Name: An ordered list of one or more labels. o Domain Name: An ordered list of one or more labels.
* Subdomain: "A domain is a subdomain of another domain if it is o Subdomain: "A domain is a subdomain of another domain if it is
contained within that domain. This relationship can be tested by contained within that domain. This relationship can be tested by
seeing if the subdomain's name ends with the containing domain's seeing if the subdomain's name ends with the containing domain's
name." (Quoted from [RFC1034], Section 3.1) For example, in the name." (Quoted from [RFC1034], Section 3.1) For example, in the
host name "nnn.mmm.example.com", both "mmm.example.com" and host name "nnn.mmm.example.com", both "mmm.example.com" and
"nnn.mmm.example.com" are subdomains of "example.com". Note that "nnn.mmm.example.com" are subdomains of "example.com". Note that
the comparisons here are done on whole labels; that is, the comparisons here are done on whole labels; that is,
"ooo.example.com" is not a subdomain of "oo.example.com". "ooo.example.com" is not a subdomain of "oo.example.com".
* Fully-Qualified Domain Name (FQDN): This is often just a clear way o 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 of saying the same thing as "domain name of a node", as outlined
above. However, the term is ambiguous. Strictly speaking, a above. However, the term is ambiguous. Strictly speaking, a
fully-qualified domain name would include every label, including fully-qualified domain name would include every label, including
the zero-length label of the root: such a name would be written the zero-length label of the root: such a name would be written
"www.example.net." (note the terminating dot). But, because every "www.example.net." (note the terminating dot). But, because every
name eventually shares the common root, names are often written name eventually shares the common root, names are often written
relative to the root (such as "www.example.net") and are still relative to the root (such as "www.example.net") and are still
called "fully qualified". This term first appeared in [RFC0819]. called "fully qualified". This term first appeared in [RFC0819].
In this document, names are often written relative to the root. In this document, names are often written relative to the root.
The following terms are defined in the CA/Browser Forum Baseline
Requirements [CAB] 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: The following additional terms are used in this document:
* Certification Authority (CA): An organization that is responsible o Certification Authority (CA): An organization that is responsible
for the creation, issuance, revocation, and management of for the creation, issuance, revocation, and management of
Certificates. The term applies equally to both Roots CAs and Certificates. The term applies equally to both Roots CAs and
Subordinate CAs Subordinate CAs
* CSR: Certificate Signing Request o CSR: Certificate Signing Request
* Parent Domain: a domain is a parent domain of a subdomain if it o Parent Domain: a domain is a parent domain of a subdomain if it
contains that subdomain, as per the [RFC8499] definition of contains that subdomain, as per the [RFC8499] definition of
subdomain. For example, for the host name "nnn.mmm.example.com", subdomain. For example, for the host name "nnn.mmm.example.com",
both "mmm.example.com" and "example.com" are parent domains of both "mmm.example.com" and "example.com" are parent domains of
"nnn.mmm.example.com". "nnn.mmm.example.com".
3. ACME Workflow and Identifier Requirements 3. ACME Workflow and Identifier Requirements
A typical ACME workflow for issuance of certificates is as follows: A typical ACME workflow for issuance of certificates is as follows:
1. client POSTs a newOrder request that contains a set of 1. client POSTs a newOrder request that contains a set of
skipping to change at page 5, line 10 skipping to change at page 4, line 35
5. client POSTs a CSR to the "finalize" API 5. client POSTs a CSR to the "finalize" API
6. server replies with an updated order object that includes a 6. server replies with an updated order object that includes a
"certificate" URI "certificate" URI
7. client sends POST-as-GET request to the "certificate" URI to 7. client sends POST-as-GET request to the "certificate" URI to
download the certificate download the certificate
ACME places the following restrictions on "identifiers": ACME places the following restrictions on "identifiers":
* [RFC8555] section 7.1.3: The authorizations required are dictated o [RFC8555] section 7.1.3: The authorizations required are dictated
by server policy; there may not be a 1:1 relationship between the by server policy; there may not be a 1:1 relationship between the
order identifiers and the authorizations required. order identifiers and the authorizations required.
* [RFC8555] section 7.1.4: the only type of "identifier" defined by o [RFC8555] section 7.1.4: the only type of "identifier" defined by
the ACME specification is an FQDN: "The only type of identifier the ACME specification is an FQDN: "The only type of identifier
defined by this specification is a fully qualified domain name defined by this specification is a fully qualified domain name
(type: "dns"). The domain name MUST be encoded in the form in (type: "dns"). The domain name MUST be encoded in the form in
which it would appear in a certificate." which it would appear in a certificate."
* [RFC8555] section 7.4: the "identifier" in the CSR request must o [RFC8555] section 7.4: the "identifier" in the CSR request must
match the "identifier" in the newOrder request: "The CSR MUST match the "identifier" in the newOrder request: "The CSR MUST
indicate the exact same set of requested identifiers as the indicate the exact same set of requested identifiers as the
initial newOrder request." initial newOrder request."
* [RFC8555] section 8.3: the "identifier", or FQDN, in the o [RFC8555] section 8.3: the "identifier", or FQDN, in the
"authorization" object must be used when fulfilling challenges via "authorization" object must be used when fulfilling challenges via
HTTP: "Construct a URL by populating the URL template ... where HTTP: "Construct a URL by populating the URL template ... where
the domain field is set to the domain name being verified" the domain field is set to the domain name being verified"
* [RFC8555] section 8.4: the "identifier", or FQDN, in the o [RFC8555] section 8.4: the "identifier", or FQDN, in the
"authorization" object must be used when fulfilling challenges via "authorization" object must be used when fulfilling challenges via
DNS: "The client constructs the validation domain name by DNS: "The client constructs the validation domain name by
prepending the label "_acme-challenge" to the domain name being prepending the label "_acme-challenge" to the domain name being
validated." validated."
ACME does not mandate that the "identifier" in a newOrder request ACME does not mandate that the "identifier" in a newOrder request
matches the "identifier" in "authorization" objects. matches the "identifier" in "authorization" objects.
4. ACME Issuance of Subdomain Certificates 4. ACME Issuance of Subdomain Certificates
skipping to change at page 6, line 16 skipping to change at page 5, line 36
subdomain to a client where the client only has to fulfill an subdomain to a client where the client only has to fulfill an
authorization challenge for a parent domain of that subdomain. This authorization challenge for a parent domain of that subdomain. This
allows a flow where a client proves ownership of, for example, allows a flow where a client proves ownership of, for example,
"example.org" and then successfully obtains a certificate for "example.org" and then successfully obtains a certificate for
"sub.example.org". "sub.example.org".
ACME server policy is out of scope of this document, however some ACME server policy is out of scope of this document, however some
commentary is provided in Section 7.1. commentary is provided in Section 7.1.
Clients need a mechanism to instruct the ACME server that they are Clients need a mechanism to instruct the ACME server that they are
requesting authorization for a Domain Namespace subordinate to a requesting authorization for all subdomains subordinate to the
given ADN, as opposed to just requesting authorization for an specified domain, as opposed to just requesting authorization for an
explicit ADN identifier. Clients need a mechanism to do this in both explicit domain identifier. Clients need a mechanism to do this in
newAuthz and newOrder requests. ACME servers need a mechanism to both newAuthz and newOrder requests. ACME servers need a mechanism
indicate to clients that authorization objects are valid for an to indicate to clients that authorization objects are valid for all
entire Domain Namespace. These are described in this section. subdomains under the specified domain. These are described in this
section.
4.1. ACME Challenge Type 4.1. ACME Challenge Type
ACME for subdomains is restricted for use with "dns-01" challenges. ACME for subdomains is restricted for use with "dns-01" challenges.
If a server policy allows a client to fulfill a challenge against a If a server policy allows a client to fulfill a challenge against a
parent ADN of a requested certificate FQDN identifier, then the parent domain of a requested certificate FQDN identifier, then the
server MUST issue a "dns-01" challenge against that parent ADN. server MUST issue a "dns-01" challenge against that parent domain.
4.2. Authorization Object 4.2. Authorization Object
ACME [RFC8555] section 7.1.4 defines the authorization object. When ACME [RFC8555] section 7.1.4 defines the authorization object. When
ACME server policy allows authorization for Domain Namespaces ACME server policy allows authorization for subdomains subordinate to
subordinate to an ADN, the server indicates this by including the an domain, the server indicates this by including the "subdomains"
"domainNamespace" flag in the authorization object for that ADN flag in the authorization object for that domain identifier:
identifier:
domainNamespace (optional, boolean): This field MUST be present subdomains (optional, boolean): This field MUST be present
and true for authorizations where ACME server policy allows and true for authorizations where ACME server policy allows
certificates to be issued for any Domain Name in the Domain certificates to be issued for any subdomain subordinate to
Namespace subordinate to the ADN specified in the 'identifier' the domain specified in the 'identifier' field of the
field of the authorization object. authorization object.
The following example shows an authorization object for the ADN The following example shows an authorization object for the domain
example.org where the authorization covers the Domain Namespace "example.org" where the authorization covers the subdomains
subordinate to example.org. subordinate to "example.org".
{ {
"status": "valid", "status": "valid",
"expires": "2015-03-01T14:09:07.99Z", "expires": "2015-03-01T14:09:07.99Z",
"identifier": { "identifier": {
"type": "dns", "type": "dns",
"value": "example.org" "value": "example.org"
}, },
"challenges": [ "challenges": [
{ {
"url": "https://example.com/acme/chall/prV_B7yEyA4", "url": "https://example.com/acme/chall/prV_B7yEyA4",
"type": "http-01", "type": "http-01",
"status": "valid", "status": "valid",
"token": "DGyRejmCefe7v4NfDGDKfA", "token": "DGyRejmCefe7v4NfDGDKfA",
"validated": "2014-12-01T12:05:58.16Z" "validated": "2014-12-01T12:05:58.16Z"
} }
], ],
"domainNamespace": true "subdomains": true
} }
If the "domainNamespace" field is not included, then the assumed If the "subdomains" field is not included, then the assumed default
default value is false. value is false.
4.3. Pre-Authorization 4.3. Pre-Authorization
The standard ACME workflow has authorization objects created The standard ACME workflow has authorization objects created
reactively in response to a certificate order. ACME also allows for reactively in response to a certificate order. ACME also allows for
pre-authorization, where clients obtain authorization for an pre-authorization, where clients obtain authorization for an
identifier proactively, outside of the context of a specific identifier proactively, outside of the context of a specific
issuance. With the ACME pre-authorization flow, a client can pre- issuance. With the ACME pre-authorization flow, a client can pre-
authorize for a parent ADN once, and then issue multiple newOrder authorize for a domain once, and then issue multiple newOrder
requests for certificates with identifiers in the Domain Namespace requests for certificates with identifiers in the subdomains
subordinate to that ADN. subordinate to that domain.
ACME [RFC8555] section 7.4.1 defines the "identifier" object for ACME [RFC8555] section 7.4.1 defines the "identifier" object for
newAuthz requests. One additional field for the "identifier" object newAuthz requests. One additional field for the "identifier" object
is defined: is defined:
domainNamespace (optional, boolean): An ACME client sets this flag subdomains (optional, boolean): An ACME client sets this flag
to indicate to the server that it is requesting an authorization to indicate to the server that it is requesting an authorization
for the Domain Namespace subordinate to the specified ADN for the subdomains subordinate to the specified domain
identifier value identifier value
Clients include the flag in the "identifier" object of newAuthz Clients include the flag in the "identifier" object of newAuthz
requests to indicate that they are requesting a Domain Namespace requests to indicate that they are requesting a subdomain
authorization. In the following example newAuthz payload, the client authorization. In the following example newAuthz payload, the client
is requesting pre-authorization for the Domain Namespace subordinate is requesting pre-authorization for the subdomains subordinate to
to example.org. "example.org".
"payload": base64url({ "payload": base64url({
"identifier": { "identifier": {
"type": "dns", "type": "dns",
"value": "example.org", "value": "example.org",
"domainNamespace": true "subdomains": true
} }
}) })
If the server is willing to allow a single authorization for the If the server is willing to allow a single authorization for the
Domain Namespace, and there is not an existing authorization object subdomains, and there is not an existing authorization object for the
for the identifier, then it will create an authorization object and identifier, then it will create an authorization object and include
include the "domainNamespace" flag with value of true. If the server the "subdomains" flag with value of true. If the server policy does
policy does not allow creation of Domain Namespace authorizations not allow creation of subdomain authorizations subordinate to that
subordinate to that ADN, the server can create an authorization domain, the server can create an authorization object for the
object for the indicated identifier, and include the indicated identifier, and include the "subdomains" flag with value of
"domainNamespace" flag with value of false. In both scenarios, false. In both scenarios, handling of the pre-authorization follows
handling of the pre-authorization follows the process documented in the process documented in ACME section 7.4.1.
ACME section 7.4.1.
4.4. New Orders 4.4. New Orders
Clients need a mechanism to optionally indicate to servers whether or Clients need a mechanism to optionally indicate to servers whether or
not they are authorized to fulfill challenges against parent ADNs for not they are authorized to fulfill challenges against parent domains
a given identifier FQDN. For example, if a client places an order for a given identifier FQDN. For example, if a client places an
for an identifier foo.bar.example.org, and is authorized to update order for an identifier "foo.bar.example.org", and is authorized to
DNS TXT records against the parent ADNs bar.example.org or update DNS TXT records against the parent domains "bar.example.org"
example.org, then the client needs a mechanism to indicate control or "example.org", then the client needs a mechanism to indicate
over the parent ADNs to the ACME server. control over the parent domains to the ACME server.
This can be achieved by adding an optional field "domainNamespace" to This can be achieved by adding an optional field "parentDomain" to
the "identifiers" field in the order object: the "identifiers" field in the order object:
domainNamespace (optional, string): This is the parent ADN of a parentDomain (optional, string): This is a parent domain of
Domain Namespace that the requested identifier belongs to. The the requested identifier. The client MUST have DNS
client MUST have DNS control over the parent ADN. control over the parent domain.
This field specifies the ADN of the Domain Namespace that the client This field specifies a parent domain of the identifier that the
has DNS control over, and is capable of fulfilling challenges client has DNS control over, and is capable of fulfilling challenges
against. Based on server policy, the server can choose to issue a against. Based on server policy, the server can choose to issue a
challenge against any parent domain of the identifier in the Domain challenge against any parent domain of the identifier up to and
Namespace up to and including the specified "domainNamespace", and including the specified "parentDomain", and create a corresponding
create a corresponding authorization object against the chosen authorization object against the chosen identifier.
identifier.
In the following example newOrder payload, the client requests a In the following example newOrder payload, the client requests a
certificate for identifier foo.bar.example.org and indicates that it certificate for identifier "foo.bar.example.org" and indicates that
can fulfill a challenge against the parent ADN and the Domain it can fulfill a challenge against the parent domain
Namespace subordinate to bar.example.org. The server can then choose "bar.example.org". The server can then choose to issue a challenge
to issue a challenge against either foo.bar.example.org or against either "foo.bar.example.org" or "bar.example.org"
bar.example.org identifiers. identifiers.
"payload": base64url({ "payload": base64url({
"identifiers": [ "identifiers": [
{ "type": "dns", { "type": "dns",
"value": "foo.bar.example.org", "value": "foo.bar.example.org",
"domainNamespace": "bar.example.org" } "parentDomain": "bar.example.org" }
], ],
"notBefore": "2016-01-01T00:04:00+04:00", "notBefore": "2016-01-01T00:04:00+04:00",
"notAfter": "2016-01-08T00:04:00+04:00" "notAfter": "2016-01-08T00:04:00+04:00"
}) })
In the following example newOrder payload, the client requests a In the following example newOrder payload, the client requests a
certificate for identifier foo.bar.example.org and indicates that it certificate for identifier "foo.bar.example.org" and indicates that
can fulfill a challenge against the parent ADN and the Domain it can fulfill a challenge against the parent domain "example.org".
Namespace subordinate to example.org. The server can then choose to The server can then choose to issue a challenge against any one of
issue a challenge against any one of foo.bar.example.org, "foo.bar.example.org", "bar.example.org" or "example.org"
bar.example.org or example.org identifiers. identifiers.
"payload": base64url({ "payload": base64url({
"identifiers": [ "identifiers": [
{ "type": "dns", { "type": "dns",
"value": "foo.bar.example.org", "value": "foo.bar.example.org",
"domainNamespace": "example.org" } "parentDomain": "example.org" }
], ],
"notBefore": "2016-01-01T00:04:00+04:00", "notBefore": "2016-01-01T00:04:00+04:00",
"notAfter": "2016-01-08T00:04:00+04:00" "notAfter": "2016-01-08T00:04:00+04:00"
}) })
If the client is unable to fulfill authorizations against parent If the client is unable to fulfill authorizations against parent
ADNs, the client should not include the "domainNamespace" field. domain, the client should not include the "parentDomain" field.
Server newOrder handling generally follows the process documented Server newOrder handling generally follows the process documented
ACME section 7.4. If the server is willing to allow Domain Namespace ACME section 7.4. If the server is willing to allow subdomain
authorizations for the ADN specified in "domainNamespace", then it authorizations for the domain specified in "parentDomain", then it
creates an authorization object against that ADN and includes the creates an authorization object against that parent domain and
"domainNamespace" flag with a value of true. If the server policy includes the "subdomains" flag with a value of true. If the server
does not allow creation of Domain Namespace authorizations against policy does not allow creation of subdomain authorizations against
that ADN, then it can create an authorization object for the that parent domain, then it can create an authorization object for
indicated identifier value, and include the "domainNamespace" flag the indicated identifier value, and includes the "subdomains" flag
with value of false. with value of false.
4.5. Directory Object Metadata 4.5. Directory Object Metadata
An ACME server can advertise support for authorization of Domain An ACME server can advertise support for authorization of subdomains
Namespaces by including the following boolean flag in its "ACME by including the following boolean flag in its "ACME Directory
Directory Metadata Fields" registry: Metadata Fields" registry:
domainNamespace (optional, bool): Indicates if an ACME server subdomains (optional, bool): Indicates if an ACME server
supports authorization of Domain Namespaces. supports authorization of subdomains.
If not specified, then no default value is assumed. If an ACME If not specified, then no default value is assumed. If an ACME
server supports authorization of Domain Namespaces, it can indicate server supports authorization of subdomains, it can indicate this by
this by including this field with a value of "true". including this field with a value of "true".
5. Illustrative Call Flow 5. Illustrative Call Flow
The call flow illustrated here uses the ACME pre-authorization flow The call flow illustrated here uses the ACME pre-authorization flow
using DNS-based proof of ownership. using DNS-based proof of ownership.
+--------+ +------+ +-----+ +--------+ +------+ +-----+
| Client | | ACME | | DNS | | Client | | ACME | | DNS |
+--------+ +------+ +-----+ +--------+ +------+ +-----+
| | | | | |
skipping to change at page 12, line 7 skipping to change at page 11, line 13
| 200 OK status=valid | | | 200 OK status=valid | |
|<---------------------------| | |<---------------------------| |
| | | | | |
| POST /certificate | | | POST /certificate | |
|--------------------------->| | |--------------------------->| |
| | | | | |
| 200 OK | | | 200 OK | |
| PEM SAN "sub2.example.org" | | | PEM SAN "sub2.example.org" | |
|<---------------------------| | |<---------------------------| |
* STEP 1: Pre-authorization of Domain Namespace o STEP 1: Pre-authorization of parent domain
The client sends a newAuthz request for the parent ADN of the The client sends a newAuthz request for the parent domain
Domain Namespace including the "domainNamespace" flag in the including the "subdomains" flag in the identifier object.
identifier object.
POST /acme/new-authz HTTP/1.1 POST /acme/new-authz HTTP/1.1
Host: example.com Host: example.com
Content-Type: application/jose+json Content-Type: application/jose+json
{ {
"protected": base64url({ "protected": base64url({
"alg": "ES256", "alg": "ES256",
"kid": "https://example.com/acme/acct/evOfKhNU60wg", "kid": "https://example.com/acme/acct/evOfKhNU60wg",
"nonce": "uQpSjlRb4vQVCjVYAyyUWg", "nonce": "uQpSjlRb4vQVCjVYAyyUWg",
"url": "https://example.com/acme/new-authz" "url": "https://example.com/acme/new-authz"
}), }),
"payload": base64url({ "payload": base64url({
"identifier": { "identifier": {
"type": "dns", "type": "dns",
"value": "example.org", "value": "example.org",
"domainNamespace": true "subdomains": true
} }
}), }),
"signature": "nuSDISbWG8mMgE7H...QyVUL68yzf3Zawps" "signature": "nuSDISbWG8mMgE7H...QyVUL68yzf3Zawps"
} }
The server creates and returns an authorization object for the The server creates and returns an authorization object for the
identifier including the "domainNamespace" flag. The object is identifier including the "subdomains" flag. The object is initially
initially in "pending" state. Once the client completes the in "pending" state.
challenge, the server will transition the authorization object and
associated challenge object status to "valid".
{ {
"status": "pending", "status": "pending",
"expires": "2015-03-01T14:09:07.99Z", "expires": "2015-03-01T14:09:07.99Z",
"identifier": { "identifier": {
"type": "dns", "type": "dns",
"value": "example.org" "value": "example.org"
}, },
"challenges": [ "challenges": [
{ {
"url": "https://example.com/acme/chall/prV_B7yEyA4", "url": "https://example.com/acme/chall/prV_B7yEyA4",
"type": "http-01", "type": "http-01",
"status": "pending", "status": "pending",
"token": "DGyRejmCefe7v4NfDGDKfA", "token": "DGyRejmCefe7v4NfDGDKfA",
"validated": "2014-12-01T12:05:58.16Z" "validated": "2014-12-01T12:05:58.16Z"
} }
], ],
"domainNamespace": true "subdomains": true
} }
* STEP 2: The client places a newOrder for sub1.example.org 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.
o STEP 2: The client places a newOrder for "sub1.example.org"
The client sends a newOrder request to the server and includes the The client sends a newOrder request to the server and includes the
subdomain identifier. Note that the identifier is in the Domain subdomain identifier. Note that the identifier is a subdomain of
Namespace that has been pre-authorised in step 1. The client does the parent domain that has been pre-authorised in step 1. The
not need to include the "domainNamespace" field in the client does not need to include the "subdomains" field in the
"identifier" object as it has already pre-authorized the Domain "identifier" object as it has already pre-authorized the parent
Namespace. domain.
POST /acme/new-order HTTP/1.1 POST /acme/new-order HTTP/1.1
Host: example.com Host: example.com
Content-Type: application/jose+json Content-Type: application/jose+json
{ {
"protected": base64url({ "protected": base64url({
"alg": "ES256", "alg": "ES256",
"kid": "https://example.com/acme/acct/evOfKhNU60wg", "kid": "https://example.com/acme/acct/evOfKhNU60wg",
"nonce": "5XJ1L3lEkMG7tR6pA00clA", "nonce": "5XJ1L3lEkMG7tR6pA00clA",
skipping to change at page 14, line 26 skipping to change at page 13, line 26
"payload": base64url({ "payload": base64url({
"identifiers": [ "identifiers": [
{ "type": "dns", "value": "sub1.example.org" } { "type": "dns", "value": "sub1.example.org" }
], ],
"notBefore": "2016-01-01T00:04:00+04:00", "notBefore": "2016-01-01T00:04:00+04:00",
"notAfter": "2016-01-08T00:04:00+04:00" "notAfter": "2016-01-08T00:04:00+04:00"
}), }),
"signature": "H6ZXtGjTZyUnPeKn...wEA4TklBdh3e454g" "signature": "H6ZXtGjTZyUnPeKn...wEA4TklBdh3e454g"
} }
As an authorization object already exists for the parent ADN of the As an authorization object already exists for the parent domain, the
Domain Namespace, the server replies with an order object with a server replies with an order object with a status of "ready" that
status of "valid" that includes a link to the existing "valid" includes a link to the existing "valid" authorization object.
authorization object.
HTTP/1.1 201 Created HTTP/1.1 201 Created
Replay-Nonce: MYAuvOpaoIiywTezizk5vw Replay-Nonce: MYAuvOpaoIiywTezizk5vw
Link: <https://example.com/acme/directory>;rel="index" Link: <https://example.com/acme/directory>;rel="index"
Location: https://example.com/acme/order/TOlocE8rfgo Location: https://example.com/acme/order/TOlocE8rfgo
{ {
"status": "valid", "status": "ready",
"expires": "2016-01-05T14:09:07.99Z", "expires": "2016-01-05T14:09:07.99Z",
"notBefore": "2016-01-01T00:00:00Z", "notBefore": "2016-01-01T00:00:00Z",
"notAfter": "2016-01-08T00:00:00Z", "notAfter": "2016-01-08T00:00:00Z",
"identifiers": [ "identifiers": [
{ "type": "dns", "value": "sub1.example.org" } { "type": "dns", "value": "sub1.example.org" }
], ],
"authorizations": [ "authorizations": [
"https://example.com/acme/authz/PAniVnsZcis" "https://example.com/acme/authz/PAniVnsZcis"
], ],
"finalize": "https://example.com/acme/order/TOlocrfgo/finalize" "finalize": "https://example.com/acme/order/TOlocrfgo/finalize"
} }
The client can proceed to finalize the order and download the The client can proceed to finalize the order and download the
certificate for sub1.example.org. certificate for "sub1.example.org".
* STEP 3: The client places a newOrder for sub2.example.org o STEP 3: The client places a newOrder for "sub2.example.org"
The client sends a newOrder request to the server and includes the The client sends a newOrder request to the server and includes the
subdomain identifier. Note that the identifier is in the Domain subdomain identifier. Note that the identifier is a subdomain of
Namespace that has been pre-authorised in step 1. The client does the parent domain that has been pre-authorised in step 1. The
not need to include the "domainNamespace" field in the client does not need to include the "subdomains" field in the
"identifier" object as it has already pre-authorized the Domain "identifier" object as it has already pre-authorized the parent
Namespace. domain.
POST /acme/new-order HTTP/1.1 POST /acme/new-order HTTP/1.1
Host: example.com Host: example.com
Content-Type: application/jose+json Content-Type: application/jose+json
{ {
"protected": base64url({ "protected": base64url({
"alg": "ES256", "alg": "ES256",
"kid": "https://example.com/acme/acct/evOfKhNU60wg", "kid": "https://example.com/acme/acct/evOfKhNU60wg",
"nonce": "5XJ1L3lEkMG7tR6pA00clA", "nonce": "5XJ1L3lEkMG7tR6pA00clA",
skipping to change at page 15, line 38 skipping to change at page 14, line 38
"payload": base64url({ "payload": base64url({
"identifiers": [ "identifiers": [
{ "type": "dns", "value": "sub2.example.org" } { "type": "dns", "value": "sub2.example.org" }
], ],
"notBefore": "2016-01-01T00:04:00+04:00", "notBefore": "2016-01-01T00:04:00+04:00",
"notAfter": "2016-01-08T00:04:00+04:00" "notAfter": "2016-01-08T00:04:00+04:00"
}), }),
"signature": "H6ZXtGjTZyUnPeKn...wEA4TklBdh3e454g" "signature": "H6ZXtGjTZyUnPeKn...wEA4TklBdh3e454g"
} }
As an authorization object already exists for the parent ADN of the As an authorization object already exists for the parent domain, the
Domain Namespace, the server replies with an order object with a server replies with an order object with a status of "ready" that
status of "valid" that includes a link to the existing "valid" includes a link to the existing "valid" authorization object.
authorization object.
HTTP/1.1 201 Created HTTP/1.1 201 Created
Replay-Nonce: MYAuvOpaoIiywTezizk5vw Replay-Nonce: MYAuvOpaoIiywTezizk5vw
Link: <https://example.com/acme/directory>;rel="index" Link: <https://example.com/acme/directory>;rel="index"
Location: https://example.com/acme/order/TOlocE8rfgo Location: https://example.com/acme/order/TOlocE8rfgo
{ {
"status": "valid", "status": "ready",
"expires": "2016-01-05T14:09:07.99Z", "expires": "2016-01-05T14:09:07.99Z",
"notBefore": "2016-01-01T00:00:00Z", "notBefore": "2016-01-01T00:00:00Z",
"notAfter": "2016-01-08T00:00:00Z", "notAfter": "2016-01-08T00:00:00Z",
"identifiers": [ "identifiers": [
{ "type": "dns", "value": "sub1.example.org" } { "type": "dns", "value": "sub1.example.org" }
], ],
"authorizations": [ "authorizations": [
"https://example.com/acme/authz/PAniVnsZcis" "https://example.com/acme/authz/PAniVnsZcis"
], ],
"finalize": "https://example.com/acme/order/ROni7rdde/finalize" "finalize": "https://example.com/acme/order/ROni7rdde/finalize"
} }
The client can proceed to finalize the order and download the The client can proceed to finalize the order and download the
certificate for sub2.example.org. certificate for "sub2.example.org".
6. IANA Considerations 6. IANA Considerations
6.1. Authorization Object Fields Registry 6.1. Authorization Object Fields Registry
The following field is added to the "ACME Authorization Object The following field is added to the "ACME Authorization Object
Fields" registry defined in ACME [RFC8555]. Fields" registry defined in ACME [RFC8555].
+-----------------+------------+--------------+-----------+ +------------+------------+--------------+-----------+
| Field Name | Field Type | Configurable | Reference | | Field Name | Field Type | Configurable | Reference |
+-----------------+------------+--------------+-----------+ +------------+------------+--------------+-----------+
| domainNamespace | boolean | false | RFC XXXX | | subdomains | boolean | false | RFC XXXX |
+-----------------+------------+--------------+-----------+ +------------+------------+--------------+-----------+
6.2. Directory Object Metadata Fields Registry 6.2. Directory Object Metadata Fields Registry
The following field is added to the "ACME Directory Metadata Fields" The following field is added to the "ACME Directory Metadata Fields"
registry defined in ACME [RFC8555]. registry defined in ACME [RFC8555].
+-----------------+------------+-----------+ +------------+------------+-----------+
| Field Name | Field Type | Reference | | Field Name | Field Type | Reference |
+-----------------+------------+-----------+ +------------+------------+-----------+
| domainNamespace | boolean | RFC XXXX | | subdomains | boolean | RFC XXXX |
+-----------------+------------+-----------+ +------------+------------+-----------+
7. Security Considerations 7. Security Considerations
This document documents enhancements to ACME [RFC8555] that optimize This document documents enhancements to ACME [RFC8555] that optimize
the protocol flows for issuance of certificates for subdomains. The the protocol flows for issuance of certificates for subdomains. The
underlying goal of ACME for Subdomains remains the same as that of underlying goal of ACME for Subdomains remains the same as that of
ACME: managing certificates that attest to identifier/key bindings ACME: managing certificates that attest to identifier/key bindings
for these subdomains. Thus, ACME for Subdomains has the same two for these subdomains. Thus, ACME for Subdomains has the same two
security goals as ACME: security goals as ACME:
1. Only an entity that controls an identifier can get an 1. Only an entity that controls an identifier can get an
authorization for that identifier authorization for that identifier
2. Once authorized, an account key's authorizations cannot be 2. Once authorized, an account key's authorizations cannot be
improperly used by another account improperly used by another account
ACME for Subdomains makes no changes to: ACME for Subdomains makes no changes to:
* account or account key management o account or account key management
* ACME channel establishment, security mechanisms or threat model o ACME channel establishment, security mechanisms or threat model
* Validation channel establishment, security mechanisms or threat o Validation channel establishment, security mechanisms or threat
model model
Therefore, all Security Considerations in ACME in the following areas Therefore, all Security Considerations in ACME in the following areas
are equally applicable to ACME for Subdomains: are equally applicable to ACME for Subdomains:
* Threat Model o Threat Model
* Integrity of Authorizations o Integrity of Authorizations
* Denial-of-Service Considerations o Denial-of-Service Considerations
* Server-Side Request Forgery o Server-Side Request Forgery
* CA Policy Considerations o CA Policy Considerations
Some additional comments on ACME server policy are given in the Some additional comments on ACME server policy are given in the
following section. following section.
7.1. ACME Server Policy Considerations 7.1. ACME Server Policy Considerations
The ACME for Subdomains and the ACME specifications do not mandate The ACME for Subdomains and the ACME specifications do not mandate
any specific ACME server or CA policies, or any specific use cases any specific ACME server or CA policies, or any specific use cases
for issuance of certificates. For example, an ACME server could be for issuance of certificates. For example, an ACME server could be
used: used:
* to issue Web PKI certificates where the ACME server must comply o to issue Web PKI certificates where the ACME server must comply
with CA/Browser Forum [CAB] Baseline Requirements. with CA/Browser Forum [CAB] Baseline Requirements.
* as a Private CA for issuance of certificates within an o as a Private CA for issuance of certificates within an
organisation. The organisation could enforce whatever policies organisation. The organisation could enforce whatever policies
they desire on the ACME server. they desire on the ACME server.
* for issuance of IoT device certificates. There are currently no o for issuance of IoT device certificates. There are currently no
IoT device certificate policies that are generally enforced across IoT device certificate policies that are generally enforced across
the industry. Organizations issuing IoT device certificates can the industry. Organizations issuing IoT device certificates can
enforce whatever policies they desire on the ACME server. enforce whatever policies they desire on the ACME server.
ACME server policy could specify whether: ACME server policy could specify whether:
* issuance of subdomain certificates is allowed based on proof of o issuance of subdomain certificates is allowed based on proof of
ownership of a parent domain ownership of a parent domain
* issuance of subdomain certificates is allowed, but only for a o issuance of subdomain certificates is allowed, but only for a
specific set of parent domains specific set of parent domains
* whether DNS based proof of ownership, or HTTP based proof of o whether DNS based proof of ownership, or HTTP based proof of
ownership, or both, are allowed ownership, or both, are allowed
ACME server policy specification is explicitly out of scope of this ACME server policy specification is explicitly out of scope of this
document. For reference, extracts from CA/Browser Forum Baseline document.
Requirements are given in the appendices.
8. Informative References 8. References
8.1. Normative References
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119,
DOI 10.17487/RFC2119, March 1997,
<https://www.rfc-editor.org/info/rfc2119>.
[RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
May 2017, <https://www.rfc-editor.org/info/rfc8174>.
8.2. Informative References
[CAB] CA/Browser Forum, "Baseline Requirements for the Issuance [CAB] CA/Browser Forum, "Baseline Requirements for the Issuance
and Management of Publicly-Trusted Certificates", n.d., and Management of Publicly-Trusted Certificates", n.d.,
<https://cabforum.org/wp-content/uploads/CA-Browser-Forum- <https://cabforum.org/wp-content/uploads/CA-Browser-Forum-
BR-1.7.1.pdf>. BR-1.7.1.pdf>.
[RFC0819] Su, Z. and J. Postel, "The Domain Naming Convention for [RFC0819] Su, Z. and J. Postel, "The Domain Naming Convention for
Internet User Applications", RFC 819, Internet User Applications", RFC 819,
DOI 10.17487/RFC0819, August 1982, DOI 10.17487/RFC0819, August 1982,
<https://www.rfc-editor.org/info/rfc819>. <https://www.rfc-editor.org/info/rfc819>.
[RFC1034] Mockapetris, P., "Domain names - concepts and facilities", [RFC1034] Mockapetris, P., "Domain names - concepts and facilities",
STD 13, RFC 1034, DOI 10.17487/RFC1034, November 1987, STD 13, RFC 1034, DOI 10.17487/RFC1034, November 1987,
<https://www.rfc-editor.org/info/rfc1034>. <https://www.rfc-editor.org/info/rfc1034>.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119,
DOI 10.17487/RFC2119, March 1997,
<https://www.rfc-editor.org/info/rfc2119>.
[RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., [RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S.,
Housley, R., and W. Polk, "Internet X.509 Public Key Housley, R., and W. Polk, "Internet X.509 Public Key
Infrastructure Certificate and Certificate Revocation List Infrastructure Certificate and Certificate Revocation List
(CRL) Profile", RFC 5280, DOI 10.17487/RFC5280, May 2008, (CRL) Profile", RFC 5280, DOI 10.17487/RFC5280, May 2008,
<https://www.rfc-editor.org/info/rfc5280>. <https://www.rfc-editor.org/info/rfc5280>.
[RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
May 2017, <https://www.rfc-editor.org/info/rfc8174>.
[RFC8499] Hoffman, P., Sullivan, A., and K. Fujiwara, "DNS [RFC8499] Hoffman, P., Sullivan, A., and K. Fujiwara, "DNS
Terminology", BCP 219, RFC 8499, DOI 10.17487/RFC8499, Terminology", BCP 219, RFC 8499, DOI 10.17487/RFC8499,
January 2019, <https://www.rfc-editor.org/info/rfc8499>. January 2019, <https://www.rfc-editor.org/info/rfc8499>.
[RFC8555] Barnes, R., Hoffman-Andrews, J., McCarney, D., and J. [RFC8555] Barnes, R., Hoffman-Andrews, J., McCarney, D., and J.
Kasten, "Automatic Certificate Management Environment Kasten, "Automatic Certificate Management Environment
(ACME)", RFC 8555, DOI 10.17487/RFC8555, March 2019, (ACME)", RFC 8555, DOI 10.17487/RFC8555, March 2019,
<https://www.rfc-editor.org/info/rfc8555>. <https://www.rfc-editor.org/info/rfc8555>.
Appendix A. CA Browser Forum Baseline Requirements Extracts
The CA/Browser Forum Baseline Requirements [CAB] 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.
Authors' Addresses Authors' Addresses
Owen Friel Owen Friel
Cisco Cisco
Email: ofriel@cisco.com Email: ofriel@cisco.com
Richard Barnes Richard Barnes
Cisco Cisco
 End of changes. 87 change blocks. 
249 lines changed or deleted 199 lines changed or added

This html diff was produced by rfcdiff 1.48. The latest version is available from http://tools.ietf.org/tools/rfcdiff/