Internet-Draft ACME-SUBDOMAINS October 2021
Friel, et al. Expires 28 April 2022 [Page]
Workgroup:
Network Working Group
Internet-Draft:
draft-ietf-acme-subdomains-00
Published:
Intended Status:
Standards Track
Expires:
Authors:
O. Friel
Cisco
R. Barnes
Cisco
T. Hollebeek
DigiCert
M. Richardson
Sandelman Software Works

ACME for Subdomains

Abstract

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.

Status of This Memo

This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79.

Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet-Drafts is at https://datatracker.ietf.org/drafts/current/.

Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress."

This Internet-Draft will expire on 28 April 2022.

▲

Table of Contents

1. Introduction

ACME [RFC8555] defines a protocol that a certification authority (CA) and an applicant can use to automate the process of domain name ownership validation and X.509v3 (PKIX) [RFC5280] certificate issuance. 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.

2. 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 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.

The following terms are defined in DNS Terminology [RFC8499] and are reproduced here:

The following terms are defined in the CA/Browser Forum Baseline Requirements [CAB] version 1.7.1 and are reproduced here:

The following additional terms are used in this document:

3. ACME Workflow and Identifier Requirements

A typical ACME workflow for issuance of certificates is as follows:

  1. client POSTs a newOrder request that contains a set of "identifiers"
  2. server replies with a set of "authorizations" and a "finalize" URI
  3. 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
  4. 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
  5. client POSTs a CSR to the "finalize" API
  6. server replies with an updated order object that includes a "certificate" URI
  7. client sends POST-as-GET request to the "certificate" URI to download the certificate

ACME places the following restrictions on "identifiers":

ACME does not mandate that the "identifier" in a newOrder request matches the "identifier" in "authorization" objects.

4. 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 Section 7.1.

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.

4.1. 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.

4.2. Authorization Object

ACME [RFC8555] 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:

domainNamespace (optional, boolean):  This field MUST be present
   and true for authorizations where ACME server policy allows
   certificates to be issued for any Domain Name in the Domain
   Namespace subordinate to the ADN specified in the 'identifier'
   field of the authorization object.

The following example shows an authorization object for the ADN example.org where the authorization covers the Domain Namespace subordinate to example.org.

   {
     "status": "valid",
     "expires": "2015-03-01T14:09:07.99Z",

     "identifier": {
       "type": "dns",
       "value": "example.org"
     },

     "challenges": [
       {
         "url": "https://example.com/acme/chall/prV_B7yEyA4",
         "type": "http-01",
         "status": "valid",
         "token": "DGyRejmCefe7v4NfDGDKfA",
         "validated": "2014-12-01T12:05:58.16Z"
       }
     ],

     "domainNamespace": true
   }

If the "domainNamespace" field is not included, then the assumed default value is false.

4.3. 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 [RFC8555] section 7.4.1 defines the "identifier" object for newAuthz requests. One additional field for the "identifier" object is defined:

domainNamespace (optional, boolean): An ACME client sets this flag
   to indicate to the server that it is requesting an authorization
   for the Domain Namespace subordinate to the specified ADN
   identifier value

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.

     "payload": base64url({
       "identifier": {
         "type": "dns",
         "value": "example.org",
         "domainNamespace": true
       }
     })

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.

4.4. 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:

domainNamespace (optional, string): This is the parent ADN of a
   Domain Namespace that the requested identifier belongs to. The
   client MUST have DNS control over the parent ADN.

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.

"payload": base64url({
       "identifiers": [
         { "type": "dns",
           "value": "foo.bar.example.org",
           "domainNamespace": "bar.example.org"  }
       ],
       "notBefore": "2016-01-01T00:04:00+04:00",
       "notAfter": "2016-01-08T00:04:00+04:00"
     })

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.

"payload": base64url({
       "identifiers": [
         { "type": "dns",
           "value": "foo.bar.example.org",
           "domainNamespace": "example.org"  }
       ],
       "notBefore": "2016-01-01T00:04:00+04:00",
       "notAfter": "2016-01-08T00:04:00+04:00"
     })

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.

4.5. 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:

domainNamespace (optional, bool): Indicates if an ACME server
   supports authorization of Domain Namespaces.

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".

5. Illustrative Call Flow

The call flow illustrated here uses the ACME pre-authorization flow using DNS-based proof of ownership.

+--------+                   +------+     +-----+
| Client |                   | ACME |     | DNS |
+--------+                   +------+     +-----+
    |                            |           |
 STEP 1: Pre-Authorization of parent domain
    |                            |           |
    | POST /newAuthz             |           |
    | "example.org"              |           |
    |--------------------------->|           |
    |                            |           |
    | 201 authorizations         |           |
    |<---------------------------|           |
    |                            |           |
    | Publish DNS TXT            |           |
    | "example.org"              |           |
    |--------------------------------------->|
    |                            |           |
    | POST /challenge            |           |
    |--------------------------->|           |
    |                            | Verify    |
    |                            |---------->|
    | 200 status=valid           |           |
    |<---------------------------|           |
    |                            |           |
    | Delete DNS TXT             |           |
    | "example.org"              |           |
    |--------------------------------------->|
    |                            |           |
 STEP 2: Place order for sub1.example.org
    |                            |           |
    | POST /newOrder             |           |
    | "sub1.example.org"         |           |
    |--------------------------->|           |
    |                            |           |
    | 201 status=ready           |           |
    |<---------------------------|           |
    |                            |           |
    | POST /finalize             |           |
    | CSR SAN "sub1.example.org" |           |
    |--------------------------->|           |
    |                            |           |
    | 200 OK status=valid        |           |
    |<---------------------------|           |
    |                            |           |
    | POST /certificate          |           |
    |--------------------------->|           |
    |                            |           |
    | 200 OK                     |           |
    | PEM SAN "sub1.example.org" |           |
    |<---------------------------|           |
    |                            |           |
 STEP 3: Place order for sub2.example.org
    |                            |           |
    | POST /newOrder             |           |
    | "sub2.example.org"         |           |
    |--------------------------->|           |
    |                            |           |
    | 201 status=ready           |           |
    |<---------------------------|           |
    |                            |           |
    | POST /finalize             |           |
    | CSR SAN "sub2.example.org" |           |
    |--------------------------->|           |
    |                            |           |
    | 200 OK status=valid        |           |
    |<---------------------------|           |
    |                            |           |
    | POST /certificate          |           |
    |--------------------------->|           |
    |                            |           |
    | 200 OK                     |           |
    | PEM SAN "sub2.example.org" |           |
    |<---------------------------|           |

   POST /acme/new-authz HTTP/1.1
   Host: example.com
   Content-Type: application/jose+json

   {
     "protected": base64url({
       "alg": "ES256",
       "kid": "https://example.com/acme/acct/evOfKhNU60wg",
       "nonce": "uQpSjlRb4vQVCjVYAyyUWg",
       "url": "https://example.com/acme/new-authz"
     }),
     "payload": base64url({
       "identifier": {
         "type": "dns",
         "value": "example.org",
         "domainNamespace": true
       }
     }),
     "signature": "nuSDISbWG8mMgE7H...QyVUL68yzf3Zawps"
   }

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".

   {
     "status": "pending",
     "expires": "2015-03-01T14:09:07.99Z",

     "identifier": {
       "type": "dns",
       "value": "example.org"
     },

     "challenges": [
       {
         "url": "https://example.com/acme/chall/prV_B7yEyA4",
         "type": "http-01",
         "status": "pending",
         "token": "DGyRejmCefe7v4NfDGDKfA",
         "validated": "2014-12-01T12:05:58.16Z"
       }
     ],

     "domainNamespace": true
   }

   POST /acme/new-order HTTP/1.1
   Host: example.com
   Content-Type: application/jose+json

   {
     "protected": base64url({
       "alg": "ES256",
       "kid": "https://example.com/acme/acct/evOfKhNU60wg",
       "nonce": "5XJ1L3lEkMG7tR6pA00clA",
       "url": "https://example.com/acme/new-order"
     }),
     "payload": base64url({
       "identifiers": [
         { "type": "dns", "value": "sub1.example.org" }
       ],
       "notBefore": "2016-01-01T00:04:00+04:00",
       "notAfter": "2016-01-08T00:04:00+04:00"
     }),
     "signature": "H6ZXtGjTZyUnPeKn...wEA4TklBdh3e454g"
   }

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.

   HTTP/1.1 201 Created
   Replay-Nonce: MYAuvOpaoIiywTezizk5vw
   Link: <https://example.com/acme/directory>;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.

   POST /acme/new-order HTTP/1.1
   Host: example.com
   Content-Type: application/jose+json

   {
     "protected": base64url({
       "alg": "ES256",
       "kid": "https://example.com/acme/acct/evOfKhNU60wg",
       "nonce": "5XJ1L3lEkMG7tR6pA00clA",
       "url": "https://example.com/acme/new-order"
     }),
     "payload": base64url({
       "identifiers": [
         { "type": "dns", "value": "sub2.example.org" }
       ],
       "notBefore": "2016-01-01T00:04:00+04:00",
       "notAfter": "2016-01-08T00:04:00+04:00"
     }),
     "signature": "H6ZXtGjTZyUnPeKn...wEA4TklBdh3e454g"
   }

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.

   HTTP/1.1 201 Created
   Replay-Nonce: MYAuvOpaoIiywTezizk5vw
   Link: <https://example.com/acme/directory>;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.

6. IANA Considerations

6.1. Authorization Object Fields Registry

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

    +-----------------+------------+--------------+-----------+
    | Field Name      | Field Type | Configurable | Reference |
    +-----------------+------------+--------------+-----------+
    | domainNamespace | boolean    | false        | RFC XXXX  |
    +-----------------+------------+--------------+-----------+

6.2. Directory Object Metadata Fields Registry

The following field is added to the "ACME Directory Metadata Fields" registry defined in ACME [RFC8555].

     +-----------------+------------+-----------+
     | Field Name      | Field Type | Reference |
     +-----------------+------------+-----------+
     | domainNamespace | boolean    | RFC XXXX  |
     +-----------------+------------+-----------+

7. Security Considerations

This document documents enhancements to ACME [RFC8555] that optimize the protocol flows for issuance of certificates for subdomains. The underlying goal of ACME for Subdomains remains the same as that of ACME: managing certificates that attest to identifier/key bindings for these subdomains. Thus, ACME for Subdomains has the same two security goals as ACME:

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

ACME for Subdomains makes no changes to:

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

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

7.1. 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 [CAB] 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.

8. Informative References

[CAB]
CA/Browser Forum, "Baseline Requirements for the Issuance and Management of Publicly-Trusted Certificates", n.d., <https://cabforum.org/wp-content/uploads/CA-Browser-Forum-BR-1.7.1.pdf>.
[RFC0819]
Su, Z. and J. Postel, "The Domain Naming Convention for Internet User Applications", RFC 819, DOI 10.17487/RFC0819, , <https://www.rfc-editor.org/info/rfc819>.
[RFC1034]
Mockapetris, P., "Domain names - concepts and facilities", STD 13, RFC 1034, DOI 10.17487/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, , <https://www.rfc-editor.org/info/rfc2119>.
[RFC5280]
Cooper, D., Santesson, S., Farrell, S., Boeyen, S., Housley, R., and W. Polk, "Internet X.509 Public Key Infrastructure Certificate and Certificate Revocation List (CRL) Profile", RFC 5280, DOI 10.17487/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, , <https://www.rfc-editor.org/info/rfc8174>.
[RFC8499]
Hoffman, P., Sullivan, A., and K. Fujiwara, "DNS Terminology", BCP 219, RFC 8499, DOI 10.17487/RFC8499, , <https://www.rfc-editor.org/info/rfc8499>.
[RFC8555]
Barnes, R., Hoffman-Andrews, J., McCarney, D., and J. Kasten, "Automatic Certificate Management Environment (ACME)", RFC 8555, DOI 10.17487/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:

Authors' Addresses

Owen Friel
Cisco
Richard Barnes
Cisco
Tim Hollebeek
DigiCert
Michael Richardson
Sandelman Software Works