| Internet-Draft | ACME dns-persist-01 | July 2025 |
| Birge-Lee | Expires 22 January 2026 | [Page] |
This document defines extensions to the Automated Certificate Management Environment (ACME) to allow for domain control validation to be performed using a persistent identifier at a well-known DNS prefix. The value of this DNS record does not need to be changed between renewals, and this method does not require the ACME client to have access to live DNS infrastructure.¶
This note is to be removed before publishing as an RFC.¶
The latest revision of this draft can be found at https://birgelee.github.io/birgelee-acme-dns-persist-01/draft-birgelee-acme-dns-persist.html. Status information for this document may be found at https://datatracker.ietf.org/doc/draft-birgelee-acme-dns-persist/.¶
Discussion of this document takes place on the Automated Certificate Management Environment Working Group mailing list (mailto:acme@ietf.org), which is archived at https://mailarchive.ietf.org/arch/browse/acme/. Subscribe at https://www.ietf.org/mailman/listinfo/acme/.¶
Source for this draft and an issue tracker can be found at https://github.com/birgelee/birgelee-acme-dns-persist-01.¶
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 22 January 2026.¶
Copyright (c) 2025 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.¶
Completion of the ACME dns-01 challenge requires the applicant to upload a randomly-generated token to DNS each time a certificate is requested. A disadvantage of this method is that the ACME client must have access to a live DNS credential and the DNS software serving the zone in question must support automation. Currently, some cloud providers use a workaround of instructing customers to install DNS CNAME records at the "_acme-challenge" label used for the dns-01 challenge.¶
While this effectively delegates the authority to obtain certificates while avoiding providing live DNS credentials to the cloud provider, there are several security and operational disadvantages to this approach. For example, 1) the infrastructure serving the zone used for ACME challenges could be compromised (potentially affecting many domains that all pointed to that same shared infrastructure), 2) CAs need to perform another potentially plaintext DNS lookup to complete the dns-01 challenge, 3) only one CNAME record can exist at a label preventing this technique from delegating control to multiple cloud providers, 4) availability issues with the ACME challenge zone could impact certificate availability, 5) the ACME client needs an additional communication channel to communicate with the ACME challenge zone, 6) a unique CNAME value must be provided to each of a cloud provider's customers otherwise this technique creates a major security breach between customers, 7) a separate DNS zone and automated DNS infrastructure must be provisioned making this technique less practical for smaller operators.¶
The dns-01 challenge when used with a CNAME record does not actually enforce that a client has current control over the domain being validated. It instead enforces that the client at one point in time could put a static record into DNS.¶
This document defines an alternative ACME validation method which relies on a client making a single static DNS change at one point in time which permits domain control validations validations until the record is removed from DNS.¶
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.¶
DNS Persist Validation proves control of a domain using a persistent identifier placed in DNS. The ACME server validates control of the domain name by querying DNS to confirm the presence of a particular identifier.¶
type (required, string): The string "dns-persist-01"¶
GET /acme/authz/1234/1 HTTP/1.1
Host: example.com
¶
HTTP/1.1 200 OK
{
"type": "dns-persist-01",
"url": "https://example.com/acme/authz/1234/1",
"status": "pending"
}
¶
The client constructs the validation domain name by prepending the label "_validation-persist" to the domain name being validated, then provisions a TXT record under that domain.¶
The value of the TXT record MUST have the following format defined in ABNF as per [RFC5234]).¶
txt-record-value = *WSP ca-caa-authorization-domain *WSP ";" *WSP [attribute-list] *WSP
attribute-list = (attribute *WSP ";" *WSP attribute-list) / attribute
attribute = attribute-name *WSP "=" *WSP attribute-value
attribute-name = (ALPHA / DIGIT) *( *("-") (ALPHA / DIGIT))
attribute-value = *(value-char / WSP) value-char *(value-char / WSP)
value-char = %x21-3A / %x3C-7E
¶
In detail:¶
ca-caa-authorization-domain: This refers to a domain name that the CA is authorized to sign on when seen in a CAA record.¶
attribute-list: This is a list of attributes which are put after the ca-caa-authorization-domain.¶
Permitted Attributes and possible values include:¶
accounturi: This attribute MUST be included in the attribute list. The corresponding value MUST be the account uri associated with the ACME account requesting the certificate.¶
persistUntil: This attribute is optional. It contains a unix timestamp after which the record can no longer be used for a DCV check. If a CA checks a dns-persist-01 record and its current timestamp is after the persistUntil, the CA MUST NOT consider the validation completed.¶
Any record that cannot be parsed properly using this ABNF definition, MUST NOT be treated as satisfying the validation method.¶
For example, if a CA was authorized to sign certificates with a CAA identifier of "example-ca.example" and an ACME client with account uri "https://authority.example/acct/123" was requesting a certificate, the following record would satisfy the dns-persist-01 validation method for the domain "example.com"¶
_validation-persist.example.com IN TXT "example-ca.example; accounturi=https://authority.example/acct/123"¶
On receiving a response, the server validates the challenge using the following steps.¶
Queries _validation-persist. prepended to the domain beingvalidated in TXT and ensures it retrieves a DNS NoError response withthe requested TXT record set.¶
The CA then enumerates through the TXT records retrieved to ensure at least one of the records meets the required criteria.¶
The criteria of a TXT record required to complete the dns-persist-01 challenge:¶
The corresponding TXT record adheres to the proper ABNF syntax.¶
The "ca-caa-authorization-domain" is a domain the CA is permitted to use in CAA records per its CPS.¶
The "attribute-list" contains an accounturi attribute and the corresponding value is the accounturi of the ACME client that requested the challenge.¶
If persistUntil is contained in the attribute-list, the current unix timestamp is less than or qual to the timestamp contained in the persistUntil field.¶
The challenge is successful if for at least one TXT record retrieved by the CA, all of the conditions are met. If no DNS record is found, or DNS record and response payload do not pass these checks, then the validation fails.¶
Unlike other ACME challenges, the DNS record used to satisfy "dns-persist-01" does not contain any information that changes on certificate renewal. The intend of the record is that it can be uploaded to DNS once and kept in place to permit all future certificate issuances by authorized ACME clients at authorized CAs. This eliminates the need for an ACME client to have real-time control over critical operational resources associated with a domain while still confirming the intend of the domain owner to authorize a particular certificate request.¶
Because of this, it is encouraged that ACME clients leave the relevant TXT record(s) used to satisfy this challenge in place between validations. A domain owner may even provision such a record before requesting a certificate from a CA as the entirety of the contents of the record can be determined before the certificate request.¶
An ACME client SHOULD check for the record's presents itself before instructing the CA to perform the check to reduce load on the CA and provide more detailed feedback to the user if the challenge is configured incorrectly.¶
TODO Security¶
Within the "Automated Certificate Management Environment (ACME) Protocol" registry, the following entry should be added.¶
Label: dns-persist-01 Identifier Type: dns ACME: Y Reference: draft-birgelee-acme-dns-persist-01¶
TODO acknowledge.¶