]> Independent Contributor

daknob@daknob.net

Spirl

amir@aaomidi.com

Google

jdkasten@google.com

Google

fotisl@google.com

Google

stanwise@google.com

Security Automated Certificate Management Environment acme 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. The latest revision of this draft can be found at . Status information for this document may be found at . Discussion of this document takes place on the WG Working Group mailing list (), which is archived at . Subscribe at . Source for this draft and an issue tracker can be found at .

Introduction The dns-01 challenge specified in section 8.4 of 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" . This RFC does not intend to deprecate the dns-01 challenge specified in . 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.

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.

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 (), any number of them can be generated in advance. This allows all required CNAME records for domain validation delegation to be constructed statically.

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

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 for additional information on additional requirements for secure randomness.

A client can fulfill this challenge by performing the following steps: Construct a key authorization from the token value provided in the challenge and the client's account key Compute the SHA-256 digest of the key authorization Construct the validation domain name by specifying the scope for the domain name being validated:

|| "-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 () "domain" if the authorization is for both the host and all subdomains by containing the subdomainAuthAllowed field set to true (). 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:

(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

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

Errors The server SHOULD follow the guidelines set in for error conditions that occur during challenge validation.

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 for additional information on additional requirements for secure randomness.

A client can fulfill this challenge by performing the following steps: Construct a key authorization from the token value provided in the challenge and the client's account key Compute the SHA-256 digest of the key authorization Construct the validation domain name by prepending the following two labels to the domain name being validated:

)[0:10]) || "._acme-" || || "-challenge" ]]>

SHA-256 is the SHA hashing operation defined in [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 ACCOUNT_RESOURCE_URL is defined in 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 () "domain" if the authorization is for both the host and all subdomains by containing the subdomainAuthAllowed field set to true (). 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:

(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

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

Errors The server SHOULD follow the guidelines set in 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.

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.

Security Considerations These challenges follow the recommendations set out in "Domain Control Validation using DNS" for supporting multiple intermediates within the context of . In both dns-account-01 and dns-02, the same security considerations apply for the integrity of authorizations () and DNS security () 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 ().

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 (). 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 (), 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.

IANA Considerations

ACME Validation Method The "ACME Validation Methods" registry is to be updated to include the following entries:

National Institute of Standards and Technology Public Key Infrastructure using X.509 (PKIX) certificates are used for a number of purposes, the most significant of which is the authentication of domain names. Thus, certification authorities (CAs) in the Web PKI are trusted to verify that an applicant for a certificate legitimately represents the domain name(s) in the certificate. As of this writing, this verification is done through a collection of ad hoc mechanisms. This document describes a protocol that a CA and an applicant can use to automate the process of verification and certificate issuance. The protocol also provides facilities for other certificate management functions, such as certificate revocation. In many standards track documents several words are used to signify the requirements in the specification. These words are often capitalized. This document defines these words as they should be interpreted in IETF documents. This document specifies an Internet Best Current Practices for the Internet Community, and requests discussion and suggestions for improvements. RFC 2119 specifies common key words that may be used in protocol specifications. This document aims to reduce the ambiguity by clarifying that only UPPERCASE usage of the key words have the defined special meanings. Security systems are built on strong cryptographic algorithms that foil pattern analysis attempts. However, the security of these systems is dependent on generating secret quantities for passwords, cryptographic keys, and similar quantities. The use of pseudo-random processes to generate secret quantities can result in pseudo-security. A sophisticated attacker may find it easier to reproduce the environment that produced the secret quantities and to search the resulting small set of possibilities than to locate the quantities in the whole of the potential number space. Choosing random quantities to foil a resourceful and motivated adversary is surprisingly difficult. This document points out many pitfalls in using poor entropy sources or traditional pseudo-random number generation techniques for generating such quantities. It recommends the use of truly random hardware techniques and shows that the existing hardware on many systems can be used for this purpose. It provides suggestions to ameliorate the problem when a hardware solution is not available, and it gives examples of how large such quantities need to be for some applications. This document specifies an Internet Best Current Practices for the Internet Community, and requests discussion and suggestions for improvements. Federal Information Processing Standard, FIPS This document describes the commonly used base 64, base 32, and base 16 encoding schemes. It also discusses the use of line-feeds in encoded data, use of padding in encoded data, use of non-alphabet characters in encoded data, use of different encoding alphabets, and canonical encodings. [STANDARDS-TRACK] The Certification Authority Authorization (CAA) DNS Resource Record allows a DNS domain name holder to specify one or more Certification Authorities (CAs) authorized to issue certificates for that domain name. CAA Resource Records allow a public CA to implement additional controls to reduce the risk of unintended certificate mis-issue. This document defines the syntax of the CAA record and rules for processing CAA records by CAs. This document obsoletes RFC 6844. This RFC is the revised specification of the protocol and format used in the implementation of the Domain Name System. It obsoletes RFC-883. This memo documents the details of the domain name client - server communication. Brave Software Salesforce Aiven Akamai Technologies Many application services on the Internet need to verify ownership or control of a domain in the Domain Name System (DNS). The general term for this process is "Domain Control Validation", and can be done using a variety of methods such as email, HTTP/HTTPS, or the DNS itself. This document focuses only on DNS-based methods, which typically involve the application service provider requesting a DNS record with a specific format and content to be visible in the requester's domain. There is wide variation in the details of these methods today. This document proposes some best practices to avoid known problems. This document specifies how Automated Certificate Management Environment (ACME) can be used by a client to obtain a certificate for a subdomain identifier from a certification authority. Additionally, this document specifies how a client can fulfill a challenge against an ancestor domain but may not need to fulfill a challenge against the explicit subdomain if certification authority policy allows issuance of the subdomain certificate without explicit subdomain ownership proof.

Acknowledgments