Internet DRAFT - draft-ietf-acme-scoped-dns-challenges
draft-ietf-acme-scoped-dns-challenges
Automated Certificate Management Environment A. A. Chariton
Internet-Draft Independent Contributor
Intended status: Standards Track A. A. Omidi
Expires: 19 August 2024 Spirl
J. Kasten
F. Loukos
S. A. Janikowski
Google
16 February 2024
Automated Certificate Management Environment (ACME) Scoped DNS
Challenges
draft-ietf-acme-scoped-dns-challenges-00
Abstract
This document outlines a new challenge for the ACME protocol,
enabling an ACME client to answer a domain control validation
challenge from an ACME server using a DNS resource linked to the ACME
Account ID. This allows multiple systems or environments to handle
challenge-solving for a single domain.
About This Document
This note is to be removed before publishing as an RFC.
The latest revision of this draft can be found at
https://aaomidi.github.io/draft-ietf-acme-scoped-dns-challenges.
Status information for this document may be found at
https://datatracker.ietf.org/doc/draft-ietf-acme-scoped-dns-
challenges/.
Discussion of this document takes place on the WG Working Group
mailing list (mailto:acme@ietf.org), which is archived at
https://datatracker.ietf.org/wg/acme/about/. Subscribe at
https://www.ietf.org/mailman/listinfo/acme/.
Source for this draft and an issue tracker can be found at
https://github.com/aaomidi/draft-ietf-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.
Chariton, et al. Expires 19 August 2024 [Page 1]
Internet-Draft ACME-SCOPED-DNS-CHALLENGES February 2024
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 19 August 2024.
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 . . . . . . . . . . . . . . . . . . . . . . . . 3
1.1. DNS-02 . . . . . . . . . . . . . . . . . . . . . . . . . 4
1.2. DNS-ACCOUNT-01 . . . . . . . . . . . . . . . . . . . . . 4
2. Conventions and Definitions . . . . . . . . . . . . . . . . . 4
3. DNS-02 Challenge . . . . . . . . . . . . . . . . . . . . . . 4
3.1. Errors . . . . . . . . . . . . . . . . . . . . . . . . . 6
4. DNS-ACCOUNT-01 Challenge . . . . . . . . . . . . . . . . . . 7
4.1. Errors . . . . . . . . . . . . . . . . . . . . . . . . . 9
4.2. Implementation Considerations . . . . . . . . . . . . . . 9
5. Security Considerations . . . . . . . . . . . . . . . . . . . 9
5.1. DNS-ACCOUNT-01 . . . . . . . . . . . . . . . . . . . . . 10
6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 10
6.1. ACME Validation Method . . . . . . . . . . . . . . . . . 10
7. References . . . . . . . . . . . . . . . . . . . . . . . . . 10
7.1. Normative References . . . . . . . . . . . . . . . . . . 10
7.2. Informative References . . . . . . . . . . . . . . . . . 11
Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . 12
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 12
Chariton, et al. Expires 19 August 2024 [Page 2]
Internet-Draft ACME-SCOPED-DNS-CHALLENGES February 2024
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.
Chariton, et al. Expires 19 August 2024 [Page 3]
Internet-Draft ACME-SCOPED-DNS-CHALLENGES February 2024
1.1. DNS-02
The dns-02 challenge adds onto dns-01 by introducing a scoping
mechanism to the domain authorization label. This allows for the
client to specify if the intended domain validation is for a specific
host, a wildcard domain, or a domain and all of its subdomains.
1.2. DNS-ACCOUNT-01
The dns-account-01 challenge leverages the ACME Account Resource URL
to present an account-unique stable challenge to an ACME server.
This challenge allows any domain name to delegate its domain
validation to more than one service through unique per ACME account
DNS records.
With this new challenge, domain validation of the same DNS name can
be done through different authorization labels. Since these
authorization labels will depend on the ACME account KID ([RFC8555],
Section 6.2), any number of them can be generated in advance. This
allows all required CNAME records for domain validation delegation to
be constructed statically.
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.
Chariton, et al. Expires 19 August 2024 [Page 4]
Internet-Draft ACME-SCOPED-DNS-CHALLENGES February 2024
{
"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
o "host" if the associated authorization applies only to the
specific host name and no labels beneath it
o "wildcard" if the associated authorization is for a wildcard
domain and contains the wildcard field set to true
([RFC8555], Section 7.1.4)
o "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.)
Chariton, et al. Expires 19 August 2024 [Page 5]
Internet-Draft ACME-SCOPED-DNS-CHALLENGES February 2024
* 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 similiar 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".
3.1. Errors
The server SHOULD follow the guidelines set in [RFC8555], Section 6.7
for error conditions that occur during challenge validation.
Chariton, et al. Expires 19 August 2024 [Page 6]
Internet-Draft ACME-SCOPED-DNS-CHALLENGES February 2024
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_RESOURCE_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_RESOURCE_URL is defined in [RFC8555], Section 7.3 as
the value in the Location header field
- SCOPE is
o "host" if the associated authorization applies only to the
specific host name and no labels beneath it
Chariton, et al. Expires 19 August 2024 [Page 7]
Internet-Draft ACME-SCOPED-DNS-CHALLENGES February 2024
o "wildcard" if the associated authorization is for a wildcard
domain and contains the wildcard field set to true
([RFC8555], Section 7.1.4)
o "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/evOfKhNU60wg",
"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:
Chariton, et al. Expires 19 August 2024 [Page 8]
Internet-Draft ACME-SCOPED-DNS-CHALLENGES February 2024
* 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".
4.1. Errors
The server SHOULD follow the guidelines set in [RFC8555], Section 6.7
for error conditions that occur during challenge validation.
If the server is unable to find a TXT record for the validation
domain name, it SHOULD include the account URL it used to construct
the validation domain name in the problem document. Clients MUST NOT
use or rely on the presence of this field to construct the validation
domain name.
4.2. Implementation Considerations
As this challenge creates strong dependency on the kid account
identifier, the server SHOULD ensure that the account identifier is
not changed during the lifetime of the account.
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].
Chariton, et al. Expires 19 August 2024 [Page 9]
Internet-Draft ACME-SCOPED-DNS-CHALLENGES February 2024
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]).
5.1. DNS-ACCOUNT-01
To allow for seamless account key rollover without the label
changing, the dynamic part of the label depends on the ACME account
and not the account key. This allows for long-lived labels, without
the security considerations of keeping the account key static.
In terms of the construction of the account label prepended to the
domain name, there is no need for a cryptographic hash. The goal is
to simply create a long-lived and statistically distinct label of
minimal size. SHA-256 was chosen due to its existing use in the
dns-01 challenge ([RFC8555], Section 8.1).
The first 10 bytes were picked as a tradeoff: the value needs to be
short enough to stay lower than the size limits for DNS ([RFC1035],
Section 2.3.4), long enough to provide sufficient probability of
collision avoidance across ACME accounts, and just the right size to
have Base32 require no padding. As the algorithm is used for a
uniform distribution of inputs, and not for integrity, we do not
consider the trimming a security issue.
6. IANA Considerations
6.1. ACME Validation Method
The "ACME Validation Methods" registry is to be updated to include
the following entries:
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
7.1. Normative References
Chariton, et al. Expires 19 August 2024 [Page 10]
Internet-Draft ACME-SCOPED-DNS-CHALLENGES February 2024
[FIPS180-4]
National Institute of Standards and Technology, "Secure
Hash Standard (SHS)", August 2015,
<https://csrc.nist.gov/publications/detail/fips/180/4/
final>.
[RFC1035] Mockapetris, P., "Domain names - implementation and
specification", STD 13, RFC 1035, DOI 10.17487/RFC1035,
November 1987, <https://www.rfc-editor.org/rfc/rfc1035>.
[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/rfc/rfc2119>.
[RFC4086] Eastlake 3rd, D., Schiller, J., and S. Crocker,
"Randomness Requirements for Security", BCP 106, RFC 4086,
DOI 10.17487/RFC4086, June 2005,
<https://www.rfc-editor.org/rfc/rfc4086>.
[RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data
Encodings", RFC 4648, DOI 10.17487/RFC4648, October 2006,
<https://www.rfc-editor.org/rfc/rfc4648>.
[RFC6234] Eastlake 3rd, D. and T. Hansen, "US Secure Hash Algorithms
(SHA and SHA-based HMAC and HKDF)", RFC 6234,
DOI 10.17487/RFC6234, May 2011,
<https://www.rfc-editor.org/rfc/rfc6234>.
[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/rfc/rfc8174>.
[RFC8555] Barnes, R., Hoffman-Andrews, J., McCarney, D., and J.
Kasten, "Automatic Certificate Management Environment
(ACME)", RFC 8555, DOI 10.17487/RFC8555, March 2019,
<https://www.rfc-editor.org/rfc/rfc8555>.
[RFC8659] Hallam-Baker, P., Stradling, R., and J. Hoffman-Andrews,
"DNS Certification Authority Authorization (CAA) Resource
Record", RFC 8659, DOI 10.17487/RFC8659, November 2019,
<https://www.rfc-editor.org/rfc/rfc8659>.
7.2. Informative References
[I-D.draft-ietf-dnsop-domain-verification-techniques]
Sahib, S. K., Huque, S., Wouters, P., and E. Nygren,
"Domain Control Validation using DNS", Work in Progress,
Chariton, et al. Expires 19 August 2024 [Page 11]
Internet-Draft ACME-SCOPED-DNS-CHALLENGES February 2024
Internet-Draft, draft-ietf-dnsop-domain-verification-
techniques-03, 17 October 2023,
<https://datatracker.ietf.org/doc/html/draft-ietf-dnsop-
domain-verification-techniques-03>.
[RFC9444] Friel, O., Barnes, R., Hollebeek, T., and M. Richardson,
"Automated Certificate Management Environment (ACME) for
Subdomains", RFC 9444, DOI 10.17487/RFC9444, August 2023,
<https://www.rfc-editor.org/rfc/rfc9444>.
Acknowledgments
Authors' Addresses
Antonios A. Chariton
Independent Contributor
Email: daknob@daknob.net
Amir A. Omidi
Spirl
Email: amir@aaomidi.com
James Kasten
Google
Email: jdkasten@google.com
Fotis Loukos
Google
Email: fotisl@google.com
Stanislaw A. Janikowski
Google
Email: stanwise@google.com
Chariton, et al. Expires 19 August 2024 [Page 12]