Automated Certificate Management Environment (ACME) Scoped DNS Challenges

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 20 February 2025.¶

Copyright Notice

Copyright (c) 2024 IETF Trust and the persons identified as the document authors. All rights reserved.¶

This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Revised BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Revised BSD License.¶

Table of Contents

1. Introduction

The dns-01 challenge specified in section 8.4 of [RFC8555] requires that ACME clients validate the domain under the _acme-challenge label for the TXT record. This label creates several limitations in domain validation.¶

First, the _acme-challenge label does not specify if the authorization is intended for a specific host, a wildcard domain, or a domain and all of its subdomains. Consequently, domain owners who may be delegating or provisioning authorization labels for a domain must concede control over the domain and all subdomains, violating the principle of least privilege.¶

Furthermore, since each domain only has a single authorization label, it creates an impediment limiting the number of other entities domain validation can be delegated to. Delegating authorization to an entity requires the use of CNAME records, which can only used once per DNS name (or in this case, once per authorization label). This limitation requires operators to pick a single ACME challenge solver for their domain name.¶

In multi-region deployments, where separate availability zones serve the same content, and dependencies across them are avoided, operators need a way to obtain a separate certificate per zone, for the same domain name. Similarly, in cases of zero-downtime migration, two different setups of the infrastructure may coexist for a long period of time, and both need access to valid certificates.¶

This document specifies two new challenge types. dns-02 and dns-account-01, which aim to address these deficiencies.¶

This work follows all recommendations set forth in "Domain Control Validation using DNS" [I-D.draft-ietf-dnsop-domain-verification-techniques].¶

This RFC does not intend to deprecate the dns-01 challenge specified in [RFC8555]. Since these new challenges do not modify any pre-existing challenges, the ability to complete the dns-02 or dns-account-01 challenge requires ACME server operators to deploy new changes to their codebase. This makes adopting and using these challenges an opt-in process.¶

2. Conventions and Definitions

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

3. DNS-02 Challenge

When the identifier being validated is a domain name, the client can prove control of that domain by provisioning a TXT resource record containing a designated value for a specific validation domain name.¶

• type (required, string): The string "dns-02".¶
• token (required, string): A random value that uniquely identifies the challenge. This value MUST have at least 128 bits of entropy. It MUST NOT contain any characters outside the base64url alphabet, including padding characters ("="). See [RFC4086] for additional information on additional requirements for secure randomness.¶

{
    "type": "dns-02",
    "url": "https://example.com/acme/chall/i00MGYwLWIx",
    "status": "pending",
    "token": "ODE4OWY4NTktYjhmYS00YmY1LTk5MDgtZTFjYTZmNjZlYTUx"
}

A client can fulfill this challenge by performing the following steps:¶

• Construct a key authorization [RFC8555], Section 8.1 from the token value provided in the challenge and the client's account key¶
• Compute the SHA-256 digest [FIPS180-4] of the key authorization¶

• Construct the validation domain name by specifying the scope for the domain name being validated:¶

  "_acme-" || <SCOPE> || "-challenge"
  

  ¶

  • SCOPE is¶

    • "host" if the associated authorization applies only to the specific host name and no labels beneath it¶
    • "wildcard" if the associated authorization is for a wildcard domain and contains the wildcard field set to true ([RFC8555], Section 7.1.4)¶
    • "domain" if the authorization is for both the host and all subdomains by containing the subdomainAuthAllowed field set to true ([RFC9444], Section 4.1).¶
  • The "||" operator indicates concatenation of strings¶

• Provision a DNS TXT record with the base64url digest value under the constructed domain validation name¶

  For example, if the domain name being validated is the wildcard of *.example.org then the client would provision the following DNS record:¶

  _acme-wildcard-challenge.example.org 300 IN TXT "LoqXcYV8...jxAjEuX0.9jg46WB3...fm21mqTI"
  

  ¶

  (In the above, "..." indicates that the token and the JWK thumbprint in the key authorization have been truncated to fit on the page.)¶

• Respond to the ACME server with an empty object ({}) to acknowledge that the challenge can be validated by the server¶

  POST /acme/chall/Rg5dV14Gh1Q
  Host: example.com
  Content-Type: application/jose+json
  
  {
    "protected": base64url({
      "alg": "ES256",
      "kid": "https://example.com/acme/acct/evOfKhNU60wg",
      "nonce": "SS2sSl1PtspvFZ08kNtzKd",
      "url": "https://example.com/acme/chall/Rg5dV14Gh1Q"
    }),
    "payload": base64url({}),
    "signature": "Q1bURgJoEslbD1c5...3pYdSMLio57mQNN4"
  }
  

  ¶

On receiving a response, the server constructs and stores the key authorization from the challenge token value.¶

To validate the dns-02 challenge, the server performs the following steps:¶

• Compute the SHA-256 digest [FIPS180-4] of the stored key authorization¶
• Compute the validation domain name with the scope of the associated authorization similar to the client¶
• Query for TXT records for the validation domain name¶
• Verify that the contents of one of the TXT records match the digest value¶

If all the above verifications succeed, then the validation is successful. If no DNS record is found, or DNS record and response payload do not pass these checks, then the server MUST fail the validation and mark the challenge as invalid.¶

The client SHOULD de-provision the resource record(s) provisioned for this challenge once the challenge is complete, i.e., once the "status" field of the challenge has the value "valid" or "invalid".¶

4. DNS-ACCOUNT-01 Challenge

When the identifier being validated is a domain name, the client can prove control of that domain by provisioning a TXT resource record containing a designated value for a specific validation domain name.¶

• type (required, string): The string "dns-account-01".¶
• token (required, string): A random value that uniquely identifies the challenge. This value MUST have at least 128 bits of entropy. It MUST NOT contain any characters outside the base64url alphabet, including padding characters ("="). See [RFC4086] for additional information on additional requirements for secure randomness.¶

{
    "type": "dns-account-01",
    "url": "https://example.com/acme/chall/i00MGYwLWIx",
    "status": "pending",
    "token": "ODE4OWY4NTktYjhmYS00YmY1LTk5MDgtZTFjYTZmNjZlYTUx"
}

A client can fulfill this challenge by performing the following steps:¶

• Construct a key authorization [RFC8555], Section 8.1 from the token value provided in the challenge and the client's account key¶
• Compute the SHA-256 digest [FIPS180-4] of the key authorization¶

• Construct the validation domain name by prepending the following two labels to the domain name being validated:¶

  "_" || base32(SHA-256(<ACCOUNT_URL>)[0:10]) || "._acme-" || <SCOPE> || "-challenge"
  

  ¶
  • SHA-256 is the SHA hashing operation defined in [RFC6234]¶
  • [0:10] is the operation that selects the first ten bytes (bytes 0 through 9 inclusive) from the previous SHA-256 operation¶
  • base32 is the operation defined in [RFC4648]¶
  • ACCOUNT_URL is defined in [RFC8555], Section 7.3 as the value in the Location header field¶

  • SCOPE is¶

    • "host" if the associated authorization applies only to the specific host name and no labels beneath it¶
    • "wildcard" if the associated authorization is for a wildcard domain and contains the wildcard field set to true ([RFC8555], Section 7.1.4)¶
    • "domain" if the authorization is for both the host and all subdomains by containing the subdomainAuthAllowed field set to true ([RFC9444], Section 4.1).¶
  • The "||" operator indicates concatenation of strings¶

• Provision a DNS TXT record with the base64url digest value under the constructed domain validation name¶

  For example, if the domain name being validated is *.example.org, and the account URL of https://example.com/acme/acct/ExampleAccount then the client would provision the following DNS record:¶

  _ujmmovf2vn55tgye._acme-wildcard-challenge.example.org 300 IN TXT "LoqXcYV8...jxAjEuX0.9jg46WB3...fm21mqTI"
  

  ¶

  (In the above, "..." indicates that the token and the JWK thumbprint in the key authorization have been truncated to fit on the page.)¶

• Respond to the ACME server with an empty object ({}) to acknowledge that the challenge can be validated by the server¶

  POST /acme/chall/Rg5dV14Gh1Q
  Host: example.com
  Content-Type: application/jose+json
  
  {
    "protected": base64url({
      "alg": "ES256",
      "kid": "https://example.com/acme/acct/ExampleAccount",
      "nonce": "SS2sSl1PtspvFZ08kNtzKd",
      "url": "https://example.com/acme/chall/Rg5dV14Gh1Q"
    }),
    "payload": base64url({}),
    "signature": "Q1bURgJoEslbD1c5...3pYdSMLio57mQNN4"
  }
  

  ¶

On receiving this response, the server validates the message and constructs and stores the key authorization from the challenge token value and the current client account key.¶

To validate the dns-account-01 challenge, the server performs the following steps:¶

• Compute the SHA-256 digest [FIPS180-4] of the stored key authorization¶
• Compute the validation domain name with the KID value in the JWS message¶
• Query for TXT records for the validation domain name¶
• Verify that the contents of one of the TXT records match the digest value¶

If all the above verifications succeed, then the validation is successful. If no DNS record is found, or DNS record and response payload do not pass these checks, then the server MUST fail the validation and mark the challenge as invalid.¶

The client SHOULD de-provision the resource record(s) provisioned for this challenge once the challenge is complete, i.e., once the "status" field of the challenge has the value "valid" or "invalid".¶

5. Security Considerations

These challenges follow the recommendations set out in "Domain Control Validation using DNS" [I-D.draft-ietf-dnsop-domain-verification-techniques] for supporting multiple intermediates within the context of [RFC8555].¶

In both dns-account-01 and dns-02, the same security considerations apply for the integrity of authorizations ([RFC8555], Section 10.2) and DNS security ([RFC8555], Section 11.2) as in the original specification for dns-01. They both differ from dns-01 in that the challenges are scoped to the particular name being validated without relying upon CAA ([RFC8659]).¶

6. IANA Considerations

label: dns-02
identifier-type: dns
ACME: Y
Reference: This document

label: dns-account-01
identifier-type: dns
ACME: Y
Reference: This document

7. References

Acknowledgments

Authors' Addresses