rfc9799.original   rfc9799.txt 
Automated Certificate Management Environment Q. Misell, Ed. Internet Engineering Task Force (IETF) Q Misell, Ed.
Internet-Draft AS207960 Request for Comments: 9799 AS207960
Intended status: Standards Track 14 January 2025 Category: Standards Track June 2025
Expires: 18 July 2025 ISSN: 2070-1721
Automated Certificate Management Environment (ACME) Extensions for Automated Certificate Management Environment (ACME) Extensions for
".onion" Special-Use Domain Names ".onion" Special-Use Domain Names
draft-ietf-acme-onion-07
Abstract Abstract
The document defines extensions to the Automated Certificate This document defines extensions to the Automated Certificate
Management Environment (ACME) to allow for the automatic issuance of Management Environment (ACME) to allow for the automatic issuance of
certificates to Tor hidden services (".onion" Special-Use Domain certificates to Tor Hidden Services (".onion" Special-Use Domain
Names). Names).
Discussion
This note is to be removed before publishing as an RFC.
Source for this draft and an issue tracker can be found at
https://github.com/AS207960/acme-onion.
The project website and a reference implementation can be found at
https://acmeforonions.org.
Status of This Memo Status of This Memo
This Internet-Draft is submitted in full conformance with the This is an Internet Standards Track document.
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 This document is a product of the Internet Engineering Task Force
and may be updated, replaced, or obsoleted by other documents at any (IETF). It represents the consensus of the IETF community. It has
time. It is inappropriate to use Internet-Drafts as reference received public review and has been approved for publication by the
material or to cite them other than as "work in progress." Internet Engineering Steering Group (IESG). Further information on
Internet Standards is available in Section 2 of RFC 7841.
This Internet-Draft will expire on 18 July 2025. Information about the current status of this document, any errata,
and how to provide feedback on it may be obtained at
https://www.rfc-editor.org/info/rfc9799.
Copyright Notice Copyright Notice
Copyright (c) 2025 IETF Trust and the persons identified as the Copyright (c) 2025 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents (https://trustee.ietf.org/ Provisions Relating to IETF Documents
license-info) in effect on the date of publication of this document. (https://trustee.ietf.org/license-info) in effect on the date of
Please review these documents carefully, as they describe your rights publication of this document. Please review these documents
and restrictions with respect to this document. Code Components carefully, as they describe your rights and restrictions with respect
extracted from this document must include Revised BSD License text as to this document. Code Components extracted from this document must
described in Section 4.e of the Trust Legal Provisions and are include Revised BSD License text as described in Section 4.e of the
provided without warranty as described in the Revised BSD License. Trust Legal Provisions and are provided without warranty as described
in the Revised BSD License.
Table of Contents Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 1. Introduction
1.1. Requirements Language . . . . . . . . . . . . . . . . . . 3 1.1. Requirements Language
2. Identifier . . . . . . . . . . . . . . . . . . . . . . . . . 3 2. Identifier
3. Identifier Validation Challenges . . . . . . . . . . . . . . 4 3. Identifier Validation Challenges
3.1. Existing challenges . . . . . . . . . . . . . . . . . . . 4 3.1. Existing Challenges
3.1.1. Existing "dns-01" Challenge . . . . . . . . . . . . . 4 3.1.1. Existing: "dns-01" Challenge
3.1.2. Existing "http-01" Challenge . . . . . . . . . . . . 4 3.1.2. Existing: http-01 Challenge
3.1.3. Existing "tls-alpn-01" Challenge . . . . . . . . . . 4 3.1.3. Existing tls-alpn-01 Challenge
3.2. New "onion-csr-01" Challenge . . . . . . . . . . . . . . 5 3.2. New onion-csr-01 Challenge
4. Client authentication to hidden services . . . . . . . . . . 7 4. Client Authentication to Hidden Services
5. ACME over hidden services . . . . . . . . . . . . . . . . . . 8 5. ACME over Hidden Services
6. Certification Authority Authorization (CAA) . . . . . . . . . 8 6. Certification Authority Authorization (CAA)
6.1. Relevant Resource Record Set . . . . . . . . . . . . . . 9 6.1. Relevant Resource Record Set
6.2. When to check CAA . . . . . . . . . . . . . . . . . . . . 10 6.2. When to Check CAA
6.3. Preventing mis-issuance by unknown CAs . . . . . . . . . 10 6.3. Preventing Mis-Issuance by Unknown CAs
6.4. Alternative in-band presentation of CAA . . . . . . . . . 11 6.4. Alternative In-Band Presentation of CAA
6.4.1. ACME servers requiring in-band CAA . . . . . . . . . 12 6.4.1. ACME Servers Requiring In-Band CAA
6.4.2. Example in-band CAA . . . . . . . . . . . . . . . . . 13 6.4.2. Example In-Band CAA
7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 13 7. IANA Considerations
7.1. Validation Methods . . . . . . . . . . . . . . . . . . . 14 7.1. Validation Methods
7.2. Error Types . . . . . . . . . . . . . . . . . . . . . . . 14 7.2. Error Types
7.3. Directory Metadata Fields . . . . . . . . . . . . . . . . 14 7.3. Directory Metadata Fields
8. Security Considerations . . . . . . . . . . . . . . . . . . . 15 8. Security Considerations
8.1. Security of the "onion-csr-01" challenge . . . . . . . . 15 8.1. Security of the onion-csr-01 Challenge
8.2. Use of "dns" identifier type . . . . . . . . . . . . . . 15 8.2. Use of the "dns" Identifier Type
8.2.1. "http-01" Challenge . . . . . . . . . . . . . . . . . 15 8.2.1. http-01 Challenge
8.2.2. "tls-alpn-01" Challenge . . . . . . . . . . . . . . . 15 8.2.2. tls-alpn-01 Challenge
8.2.3. "dns-01" Challenge . . . . . . . . . . . . . . . . . 15 8.2.3. dns-01 Challenge
8.3. Key Authorization with "onion-csr-01" . . . . . . . . . . 15 8.3. Key Authorization with onion-csr-01
8.4. Use of Tor for non-".onion" domains . . . . . . . . . . . 16 8.4. Use of Tor for Domains That Are Not ".onion"
8.5. Redirects with "http-01" . . . . . . . . . . . . . . . . 16 8.5. Redirects with http-01
8.6. Security of CAA records . . . . . . . . . . . . . . . . . 16 8.6. Security of CAA Records
8.7. In-band CAA . . . . . . . . . . . . . . . . . . . . . . . 16 8.7. In-Band CAA
8.8. Access of the Tor network . . . . . . . . . . . . . . . . 17 8.8. Access of the Tor Network
8.9. Anonymity of the ACME client . . . . . . . . . . . . . . 17 8.9. Anonymity of the ACME Client
8.9.1. Avoid unnecessary certificates . . . . . . . . . . . 17 8.9.1. Avoid Unnecessary Certificates
8.9.2. Obfuscate subscriber information . . . . . . . . . . 17 8.9.2. Obfuscate Subscriber Information
8.9.3. Separate ACME account keys . . . . . . . . . . . . . 17 8.9.3. Separate ACME Account Keys
9. References . . . . . . . . . . . . . . . . . . . . . . . . . 17 9. References
9.1. Normative References . . . . . . . . . . . . . . . . . . 18 9.1. Normative References
9.2. Informative References . . . . . . . . . . . . . . . . . 19 9.2. Informative References
Appendix A. Discussion on the use of the "dns" identifier Appendix A. Discussion on the Use of the "dns" Identifier Type
type . . . . . . . . . . . . . . . . . . . . . . . . . . 19 Acknowledgements
Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 20 Author's Address
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 20
1. Introduction 1. Introduction
The Tor network has the ability to host "Onion Services" [tor-spec] The Tor network has the ability to host "Onion Services" [tor-spec]
only accessible via the Tor network. These services use the ".onion" only accessible via the Tor network. These services use the ".onion"
Special-Use Domain Name [RFC7686] to identify these services. These Special-Use Domain Name [RFC7686] to identify these services. These
can be used as any other domain name could, but do not form part of can be used as any other domain name could, but they do not form part
the DNS infrastructure. of the DNS infrastructure.
The Automated Certificate Management Environment (ACME) [RFC8555] The Automated Certificate Management Environment (ACME) [RFC8555]
defines challenges for validating control of DNS identifiers, and defines challenges for validating control of DNS identifiers, and
whilst a ".onion" Special-Use Domain Name may appear as a DNS name, whilst a ".onion" Special-Use Domain Name may appear as a DNS name,
it requires special consideration to validate control of one such it requires special consideration to validate control of one such
that ACME could be used on ".onion" Special-Use Domain Names. that ACME could be used on ".onion" Special-Use Domain Names.
In order to allow ACME to be utilised to issue certificates to In order to allow ACME to be utilized to issue certificates to
".onion" Special-Use Domain Names this document specifies challenges ".onion" Special-Use Domain Names, this document specifies challenges
suitable to validate control of these Special-Use Domain Names. suitable to validate control of these Special-Use Domain Names.
Additionally, this document defines an alternative to the DNS Additionally, this document defines an alternative to the DNS
Certification Authority Authorization (CAA) Resource Record [RFC8659] Certification Authority Authorization (CAA) Resource Record [RFC8659]
that can be used with ".onion" Special-Use Domain Names. that can be used with ".onion" Special-Use Domain Names.
1.1. Requirements Language 1.1. Requirements Language
The key words MUST, MUST NOT, REQUIRED, SHALL, SHALL NOT, SHOULD, The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
SHOULD NOT, RECOMMENDED, NOT RECOMMENDED, MAY, and OPTIONAL in this "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
document are to be interpreted as described in [BCP14] (RFC2119, "OPTIONAL" in this document are to be interpreted as described in
RFC8174) when, and only when, they appear in all capitals, as shown BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all
here. capitals, as shown here.
2. Identifier 2. Identifier
[RFC8555] defines the "dns" identifier type. This identifier type [RFC8555] defines the "dns" identifier type. This identifier type
MUST be used when requesting a certificate for a ".onion" Special-Use MUST be used when requesting a certificate for a ".onion" Special-Use
Domain Name. The value of identifier MUST be the textual Domain Name. The value of the identifier MUST be the textual
representation as defined in Part Special Hostnames in Tor - ".onion" representation as defined in the "Special Hostnames in Tor - .onion"
of [tor-spec]. The value MAY include subdomain labels. Version 2 section of [tor-spec]. The value MAY include subdomain labels.
addresses [tor-rend-spec-v2] MUST NOT be used as these are now Version 2 addresses [tor-rend-spec-v2] MUST NOT be used as these are
considered insecure. now considered insecure.
Example identifiers (linebreaks have been added for readability Example identifiers (line breaks have been added for readability
only): only):
{ {
"type": "dns", "type": "dns",
"value": "bbcweb3hytmzhn5d532owbu6oqadra5z3ar726v "value": "bbcweb3hytmzhn5d532owbu6oqadra5z3ar726v
q5kgwwn6aucdccrad.onion" q5kgwwn6aucdccrad.onion"
} }
{ {
"type": "dns", "type": "dns",
"value": "www.bbcweb3hytmzhn5d532owbu6oqadra5z3ar726v "value": "www.bbcweb3hytmzhn5d532owbu6oqadra5z3ar726v
q5kgwwn6aucdccrad.onion" q5kgwwn6aucdccrad.onion"
} }
3. Identifier Validation Challenges 3. Identifier Validation Challenges
The CA/Browser Forum Baseline Requirements (Appendix B.2 of The CA/Browser Forum Baseline Requirements define methods accepted by
[cabf-br]) define methods accepted by the CA industry for validation the CA industry for validation of ".onion" Special-Use Domain Names
of ".onion" Special-Use Domain Names. This document incorporates (see Appendix B.2 of [cabf-br]). This document incorporates these
these methods into ACME challenges. methods into ACME challenges.
3.1. Existing challenges 3.1. Existing Challenges
3.1.1. Existing "dns-01" Challenge 3.1.1. Existing: "dns-01" Challenge
The existing "dns-01" challenge MUST NOT be used to validate ".onion" The existing "dns-01" challenge MUST NOT be used to validate ".onion"
Special-Use Domain Names, as these domains are not part of the DNS. Special-Use Domain Names as these domains are not part of the DNS.
3.1.2. Existing "http-01" Challenge 3.1.2. Existing: http-01 Challenge
The "http-01" challenge as defined in Section 8.3 of [RFC8555] MAY be The http-01 challenge, as defined in Section 8.3 of [RFC8555], MAY be
used to validate a ".onion" Special-Use Domain Names, with the used to validate a ".onion" Special-Use Domain Name with the
modifications defined in this document, namely Section 4, and modifications defined in this document, namely those described in
Section 6. Sections 4 and 6.
The ACME server SHOULD follow redirects; note that these MAY be The ACME server SHOULD follow redirects. Note that these MAY be
redirects to non-".onion" services, and the server SHOULD honour redirects to services that are not ".onion" and that the server
these. Clients might use redirects, for example, so that the SHOULD honor these. For example, clients might use redirects so that
response can be provided by a centralized certificate management the response can be provided by a centralized certificate management
server. See Section 10.2 of [RFC8555] for security considerations on server. See Section 10.2 of [RFC8555] for security considerations on
why a server might not want to follow redirects. why a server might not want to follow redirects.
3.1.3. Existing "tls-alpn-01" Challenge 3.1.3. Existing tls-alpn-01 Challenge
The "tls-alpn-01" challenge as defined in [RFC8737] MAY be used to The tls-alpn-01 challenge, as defined in [RFC8737], MAY be used to
validate a ".onion" Special-Use Domain Names, with the modifications validate a ".onion" Special-Use Domain Name with the modifications
defined in this document, namely Section 4, and Section 6. defined in this document, namely those described in Sections 4 and 6.
3.2. New "onion-csr-01" Challenge 3.2. New onion-csr-01 Challenge
Two methods already defined in ACME and allowed by the CA/BF ("http- The two ACME-defined methods allowed by CA/BF described in Sections
01" and "tls-alpn-01") do not allow issuance of wildcard 3.1.2 and 3.1.3 (http-01 and tls-alpn-01) do not allow issuance of
certificates. A ".onion" Special-Use Domain Name can have subdomains wildcard certificates. A ".onion" Special-Use Domain Name can have
(just like any other domain in the DNS), and a site operator may find subdomains (just like any other domain in the DNS), and a site
it useful to have one certificate for all virtual hosts on their operator may find it useful to have one certificate for all virtual
site. This new validation method incorporates the specially signed hosts on their site. This new validation method incorporates the
CSR (as defined by Appendix B.2.b of [cabf-br]) into ACME to allow specially signed Certificate Signing Request (CSR) (as defined by
for the issuance of wildcard certificates. Appendix B.2.b of [cabf-br]) into ACME to allow for the issuance of
wildcard certificates.
To this end a new challenge type called "onion-csr-01" is defined, To this end, a new challenge called onion-csr-01 is defined, with the
with the following fields: following fields:
type (required, string) The string "onion-csr-01" type (required, string): The string onion-csr-01.
nonce (required, string) A Base64 [RFC4648] encoded nonce, including nonce (required, string): A Base64-encoded nonce [RFC4648] including
padding characters. It MUST contain at least 64 bits of entropy. padding characters. It MUST contain at least 64 bits of entropy.
A response generated using this nonce MUST NOT be accepted by the A response generated using this nonce MUST NOT be accepted by the
ACME server if the nonce used was generated by the server more ACME server if the nonce used was generated by the server more
than 30 days ago (as per Appendix B.2.b of [cabf-br]). than 30 days prior (as per Appendix B.2.b of [cabf-br]).
authKey (optional, object) The ACME server's Ed25519 public key authKey (optional, object): The ACME server's Ed25519 public key
encoded as per [RFC8037]. This is further defined in Section 4. encoded as per [RFC8037]. This is further defined in Section 4.
{ {
"type": "onion-csr-01", "type": "onion-csr-01",
"url": "https://acme-server.example.onion/acme/chall/bbc625c5", "url": "https://acme-server.example.onion/acme/chall/bbc625c5",
"status": "pending", "status": "pending",
"nonce": "bI6/MRqV4gw=", "nonce": "bI6/MRqV4gw=",
"authKey": { ... } "authKey": { ... }
} }
An "onion-csr-01" MUST NOT be used to issue certificates for non An onion-csr-01 challenge MUST NOT be used to issue certificates for
".onion" Special-Use Domain Names. Special-Use Domain Names that are not ".onion".
Clients prove control over the key associated with the ".onion" Clients prove control over the key associated with the ".onion"
service by generating a CSR [RFC2986] with the following additional service by generating a Certificate Request (CSR) [RFC2986] with the
extension attributes and signing it with the private key of the following additional extension attributes and signing it with the
".onion" Special-Use Domain Name: private key of the ".onion" Special-Use Domain Name:
* A caSigningNonce attribute containing the nonce provided in the * A caSigningNonce attribute containing the nonce provided in the
challenge. This MUST be raw bytes, and not the base64 encoded challenge. This MUST be raw bytes and not the base64 encoded
value provided in the challenge object. value provided in the challenge object.
* An applicantSigningNonce containing a nonce generated by the * An applicantSigningNonce attribute containing a nonce generated by
client. This MUST have at least 64 bits of entropy. This MUST be the client. This MUST have at least 64 bits of entropy. This
raw bytes. MUST be raw bytes.
These additional attributes have the following format These additional attributes have the following format
cabf OBJECT IDENTIFIER ::= cabf OBJECT IDENTIFIER ::=
{ joint-iso-itu-t(2) international-organizations(23) { joint-iso-itu-t(2) international-organizations(23)
ca-browser-forum(140) } ca-browser-forum(140) }
cabf-caSigningNonce OBJECT IDENTIFIER ::= { cabf 41 } cabf-caSigningNonce OBJECT IDENTIFIER ::= { cabf 41 }
caSigningNonce ATTRIBUTE ::= { caSigningNonce ATTRIBUTE ::= {
skipping to change at page 6, line 37 skipping to change at line 263
} }
The subject of the CSR need not be meaningful and CAs MUST NOT The subject of the CSR need not be meaningful and CAs MUST NOT
validate its contents. The public key presented in this CSR MUST be validate its contents. The public key presented in this CSR MUST be
the public key corresponding to the ".onion" Special-Use Domain Name the public key corresponding to the ".onion" Special-Use Domain Name
being validated. It MUST NOT be the same public key presented in the being validated. It MUST NOT be the same public key presented in the
CSR to finalize the order. CSR to finalize the order.
Clients respond with the following object to validate the challenge: Clients respond with the following object to validate the challenge:
csr (required, string) The CSR in the base64url-encoded version of csr (required, string): The CSR in the base64url-encoded version of
the DER format. (Note: Because this field uses base64url, and the DER format. (Note: Because this field uses base64url, and
does not include headers, it is different from PEM.) does not include headers, it is different from Privacy Enhanced
Mail (PEM).)
POST /acme/chall/bbc625c5 POST /acme/chall/bbc625c5
Host: acme-server.example.onion Host: acme-server.example.onion
Content-Type: application/jose+json Content-Type: application/jose+json
{ {
"protected": base64url({ "protected": base64url({
"alg": "ES256", "alg": "ES256",
"kid": "https://acme-server.example.onion/acme/acct/evOfKhNU60wg", "kid":
"https://acme-server.example.onion/acme/acct/evOfKhNU60wg",
"nonce": "UQI1PoRi5OuXzxuX7V7wL0", "nonce": "UQI1PoRi5OuXzxuX7V7wL0",
"url": "https://acme-server.example.onion/acme/chall/bbc625c5" "url": "https://acme-server.example.onion/acme/chall/bbc625c5"
}), }),
"payload": base64url({ "payload": base64url({
"csr": "MIIBPTCBxAIBADBFMQ...FS6aKdZeGsysoCo4H9P" "csr": "MIIBPTCBxAIBADBFMQ...FS6aKdZeGsysoCo4H9P"
}), }),
"signature": "Q1bURgJoEslbD1c5...3pYdSMLio57mQNN4" "signature": "Q1bURgJoEslbD1c5...3pYdSMLio57mQNN4"
} }
When presented with the CSR the server verifies it in the following When presented with the CSR, the server verifies it in the following
manner: manner:
1. The CSR is a well formatted PKCS#10 request. 1. The CSR is a well formatted PKCS#10 request.
2. The public key in the CSR corresponds to the ".onion" Special-Use 2. The public key in the CSR corresponds to the ".onion" Special-Use
Domain Name being validated. Domain Name being validated.
3. The signature over the CSR validates with the ".onion" Special- 3. The signature over the CSR validates with the ".onion" Special-
Use Domain Name public key. Use Domain Name public key.
4. The caSigningNonce attribute is present and its contents matches 4. The caSigningNonce attribute is present and its contents match
the nonce provided to the client. the nonce provided to the client.
5. The applicantSigningNonce attribute is present and contains at 5. The applicantSigningNonce attribute is present and contains at
least 64 bits of entropy. least 64 bits of entropy.
If all of the above are successful then validation succeeds, If all of the above are successful then validation succeeds,
otherwise it has failed. otherwise it has failed.
4. Client authentication to hidden services 4. Client Authentication to Hidden Services
Some hidden services do not wish to be accessible to the entire Tor Some Hidden Services do not wish to be accessible to the entire Tor
network, and so encrypt their hidden service descriptor with the keys network, and so they encrypt their Hidden Service Descriptor with the
of clients authorized to connect. Without a way for the CA to signal keys of clients authorized to connect. Without a way for the CA to
what key it will use to connect these services will not be able to signal what key it will use to connect, these services will not be
obtain a certificate using http-01 or tls-alpn-01, nor enforce CAA able to obtain a certificate using http-01 or tls-alpn-01, nor
with any validation method. enforce CAA with any validation method.
To this end, an additional field in the challenge object is defined To this end, an additional field in the challenge object is defined
to allow the ACME server to advertise the Ed25519 public key it will to allow the ACME server to advertise the Ed25519 public key it will
use (as per Part "Authentication during the introduction phase" of use (as per the "Authentication during the introduction phase"
[tor-spec]) to authenticate itself when retrieving the hidden service section of [tor-spec]) to authenticate itself when retrieving the
descriptor. Hidden Service Descriptor.
authKey (optional, object) The ACME server's Ed25519 public key authKey (optional, object): The ACME server's Ed25519 public key
encoded as per [RFC8037]. encoded as per [RFC8037].
ACME servers MUST NOT use the same public key with multiple hidden ACME servers MUST NOT use the same public key with multiple Hidden
services. ACME servers MAY re-use public keys for re-validation of Services. ACME servers MAY reuse public keys for re-validation of
the same hidden service. the same Hidden Service.
There is no method to communicate to the CA that client There is no method to communicate to the CA that client
authentication is necessary; instead the ACME server MUST attempt to authentication is necessary; instead, the ACME server MUST attempt to
calculate its CLIENT-ID as per Part "Client Behavior" of [tor-spec]. calculate its CLIENT-ID as per the "Client behavior" section of
If no auth-client line in the first layer hidden service descriptor [tor-spec]. If no auth-client line in the First Layer Hidden Service
matches the computed client-id then the server MUST assume that the Descriptor matches the computed client-id, then the server MUST
hidden service does not require client authentication and proceed assume that the Hidden Service does not require client authentication
accordingly. and proceed accordingly.
In the case the Ed25519 public key is novel to the client it will In the case in which the Ed25519 public key is novel to the client,
have to resign and republish its hidden service descriptor. It MUST it will have to resign and republish its Hidden Service Descriptor.
wait some (indeterminate) amount of time for the new descriptor to It MUST wait some (indeterminate) amount of time for the new
propagate the Tor hidden service directory servers, before proceeding descriptor to propagate the Tor Hidden Service directory servers
with responding to the challenge. This should take no more than a before proceeding with responding to the challenge. This should take
few minutes. This specification does not set a fixed time as changes no more than a few minutes. This specification does not set a fixed
in the operation of the Tor network can affect this propagation time time as changes in the operation of the Tor network can affect this
in the future. ACME servers MUST NOT expire challenges before a propagation time in the future. ACME servers MUST NOT expire
reasonable time to allow publication of the new descriptor - it is challenges before a reasonable time to allow publication of the new
RECOMMENDED the server allow at least 30 minutes; however it is descriptor. It is RECOMMENDED the server allow at least 30 minutes;
entirely up to operator preference. however, it is entirely up to operator preference.
5. ACME over hidden services 5. ACME over Hidden Services
A CA offering certificates to ".onion" Special-Use Domain Names A CA offering certificates to ".onion" Special-Use Domain Names
SHOULD make their ACME server available as a Tor hidden services. SHOULD make their ACME server available as a Tor Hidden Service.
ACME clients SHOULD also support connecting to ACME servers over Tor, ACME clients SHOULD also support connecting to ACME servers over Tor,
regardless of their support of "onion-csr-01", as their existing regardless of their support of onion-csr-01, as their existing
"http-01" and "tls-alpn-01" implementations could be used to obtain http-01 and tls-alpn-01 implementations could be used to obtain
certificates for ".onion" Special-Use Domain Names. certificates for ".onion" Special-Use Domain Names.
6. Certification Authority Authorization (CAA) 6. Certification Authority Authorization (CAA)
".onion" Special-Use Domain Name are not part of the DNS, and as such ".onion" Special-Use Domain Names are not part of the DNS; as such, a
a variation on CAA [RFC8659] is necessary to allow restrictions to be variation on CAA [RFC8659] is necessary to allow restrictions to be
placed on certificate issuance. placed on certificate issuance.
To this end a new field is added to the second layer hidden service To this end, a new field is added to the Second Layer Hidden Service
descriptor as defined in Part "Second layer plaintext format" of Descriptor, as defined in the "Second layer plaintext format" section
[tor-spec] with the following format (defined using the notation from of [tor-spec] with the following format (defined using the notation
Part "Document meta-format" of [tor-spec]): from the "netdoc document meta-format" section of [tor-spec]):
"caa" SP flags SP tag SP value NL "caa" SP flags SP tag SP value NL
[Any number of times] [Any number of times]
The presentation format is provided above purely for the convenience The presentation format is provided above purely for the convenience
of the reader and implementors, the canonical version remains that of the reader and implementors: the canonical version remains that
defined in Section 4.1.1 of [RFC8659], or future updates to the same. defined in Section 4.1.1 of [RFC8659], or future updates to the same.
The contents of "flag", "tag", and "value" are as per Section 4.1.1 The contents of "flags", "tag", and "value" are as per Section 4.1.1
of [RFC8659]. Multiple CAA records MAY be present, as is the case in of [RFC8659]. Multiple CAA records MAY be present, as is the case in
the DNS. CAA records in a hidden service descriptor are to be the DNS. CAA records in a Hidden Service Descriptor are to be
treated the same by CAs as if they had been in the DNS for the treated the same by CAs as if they had been in the DNS for the
".onion" Special-Use Domain Name. ".onion" Special-Use Domain Name.
A hidden service's second layer descriptor using CAA could look A Hidden Service's Second Layer Descriptor using CAA could look
something like the following (additional linebreaks have been added something like the following (additional line breaks have been added
for readability): for readability):
create2-formats 2 create2-formats 2
single-onion-service single-onion-service
caa 128 issue "acmeforonions.example;validationmethods=onion-csr-01" caa 128 issue "acmeforonions.example;validationmethods=onion-csr-01"
caa 0 iodef "mailto:security@example.com" caa 0 iodef "mailto:security@example.com"
introduction-point AwAGsAk5nSMpAhRqhMHbTFCTSlfhP8f5PqUhe6DatgMgk7kSL3 introduction-point AwAGsAk5nSMpAhRqhMHbTFCTSlfhP8f5PqUhe6DatgMgk7kSL3
KHCZUZ3C6tXDeRfM9SyNY0DlgbF8q+QSaGKCs= KHCZUZ3C6tXDeRfM9SyNY0DlgbF8q+QSaGKCs=
... ...
6.1. Relevant Resource Record Set 6.1. Relevant Resource Record Set
In the absence of the possibility for delegation of subdomains from a In the absence of the possibility for delegation of subdomains from a
".onion" Special-Use Domain Name as there is in the DNS there is no ".onion" Special-Use Domain Name, as there is in the DNS, there is no
need, nor indeed any method available, to search up the DNS tree for need, nor indeed any method available, to search up the DNS tree for
a relevant CAA record set. Similarly, it is also impossible to check a relevant CAA record set. Similarly, it is also impossible to check
CAA records on the "onion" Special-Use TLD, as it does not exist in CAA records on the "onion" Special-Use Top-Level Domain (TLD), as it
any form except as described in [RFC7686], so implementors MUST NOT does not exist in any form except as described in [RFC7686];
look here either. therefore, implementors MUST NOT look there either.
Instead all subdomains under a ".onion" Special-Use Domain Name share Instead, all subdomains under a ".onion" Special-Use Domain Name
the same CAA record set. That is, all of these share a CAA record share the same CAA record set. That is, all of these share a CAA
set with "a.onion": record set with "a.onion":
* b.a.onion * b.a.onion
* c.a.onion * c.a.onion
* e.d.a.onion * e.d.a.onion
but these do not: but these do not:
* b.c.onion * b.c.onion
* c.d.onion * c.d.onion
* e.c.d.onion * e.c.d.onion
* a.b.onion * a.b.onion
6.2. When to check CAA 6.2. When to Check CAA
If the hidden service has client authentication enabled then it will If the Hidden Service has client authentication enabled, then it will
be impossible for the ACME server to decrypt the second layer be impossible for the ACME server to decrypt the Second Layer Hidden
descriptor to read the CAA records until the ACME server's public key Service Descriptor to read the CAA records until the ACME server's
has been added to the first layer descriptor. To this end an ACME public key has been added to the First Layer Hidden Service
server MUST wait until the client responds to an authorization before Descriptor. To this end, an ACME server MUST wait until the client
checking CAA, and treat this response as indication that their public responds to an authorization before checking the CAA and treat this
key has been added and that the ACME server will be able to decrypt response as an indication that their public key has been added and
the second layer descriptor. that the ACME server will be able to decrypt the Second Layer Hidden
Service Descriptor.
6.3. Preventing mis-issuance by unknown CAs 6.3. Preventing Mis-Issuance by Unknown CAs
In the case of a hidden service requiring client authentication the In the case of a Hidden Service requiring client authentication, the
CA will be unable to read the hidden service's CAA records without CA will be unable to read the hidden service's CAA records without
the hidden service trusting an ACME server's public key - as the CAA the Hidden Service trusting an ACME server's public key -- as the CAA
records are in the second layer descriptor. A method is necessary to records are in the Second Layer Hidden Service Descriptor. A method
signal that there are CAA records present (but not reveal their is necessary to signal that there are CAA records present (but not
contents which - in certain circumstances - would unwantedly disclose reveal their contents, which, in certain circumstances, would
information about the hidden service operator). unwantedly disclose information about the Hidden Service operator).
To this end a new field is added to the first layer hidden service To this end, a new field is added to the First Layer Hidden Service
descriptor Part "First layer plaintext format" of [tor-spec] with the Descriptor in the "First layer plaintext format" section of
following format (defined using the notation from Part "Document [tor-spec] with the following format (defined using the notation from
meta-format" of [tor-spec]): the "netdoc document meta-format" section of [tor-spec]):
"caa-critical" NL "caa-critical" NL
[At most once] [At most once]
If an ACME server encounters this flag it MUST NOT proceed with If an ACME server encounters this flag, it MUST NOT proceed with
issuance until it can decrypt and parse the CAA records from the issuance until it can decrypt and parse the CAA records from the
second layer descriptor. Second Layer Hidden Service Descriptor.
6.4. Alternative in-band presentation of CAA 6.4. Alternative In-Band Presentation of CAA
An ACME server might be unwilling to operate the infrastructure An ACME server might be unwilling to operate the infrastructure
required to fetch, decode, and verify Tor hidden service descriptors required to fetch, decode, and verify Tor Hidden Service Descriptors
in order to check CAA records. To this end a method to signal CAA in order to check CAA records. To this end a method to signal CAA
policies in-band of ACME is defined. policies in-band of ACME is defined.
If a hidden service does use this method to provide CAA records to an If a Hidden Service does use this method to provide CAA records to an
ACME server it SHOULD still publish CAA records if its CAA record set ACME server, it SHOULD still publish CAA records if its CAA record
includes "iodef", "contactemail", or "contactphone" so that this set includes "iodef", "contactemail", or "contactphone" so that this
information is still publicly accessible. A hidden service operator information is still publicly accessible. Additionally, a Hidden
MAY also not wish to publish a CAA record set in its service Service operator MAY not wish to publish a CAA record set in its
descriptor to avoid revealing information about the service operator. Hidden Service Descriptor to avoid revealing information about the
service operator.
If an ACME server receives a validly signed CAA record set in the If an ACME server receives a validly signed CAA record set in the
finalize request it MAY proceed with issuance on the basis of the finalize request, it MAY proceed with issuance on the basis of the
client provided CAA record set only without checking the CAA set in client-provided CAA record set only, without checking the CAA set in
the hidden service. Alternatively, an ACME server MAY ignore the the Hidden Service. Alternatively, an ACME server MAY ignore the
client provided record set and fetch the record set from the service client provided record set and fetch the record set from the Hidden
descriptor. In any case, the server always MAY fetch the record set Service Descriptor. In any case, the server MAY fetch the record set
from the service descriptor. If an ACME server receives a validly from the Hidden Service Descriptor. If an ACME server receives a
signed CAA record set in the finalize request it need not check the validly signed CAA record set in the finalize request, it need not
CAA set in the hidden service descriptor and can proceed with check the CAA set in the Hidden Service Descriptor and can proceed
issuance on the basis of the client provided CAA record set only. An with issuance on the basis of the client-provided CAA record set
ACME server MAY ignore the client provided record set, and is free to only. An ACME server MAY ignore the client-provided record set and
always fetch the record set from the service descriptor. is free to always fetch the record set from the Hidden Service
Descriptor.
A new field is defined in the ACME finalize endpoint to contain the A new field is defined in the ACME finalize endpoint to contain the
hidden service's CAA record set for each ".onion" Special-Use Domain Hidden Service's CAA record set for each ".onion" Special-Use Domain
Name in the order. Name in the order.
onionCAA (optional, dictionary of objects) The CAA record set for onionCAA (optional, dictionary of objects): The CAA record set for
each ".onion" Special-Use Domain Name in the order. The key is each ".onion" Special-Use Domain Name in the order. The key is
the ".onion" Special-Use Domain Name, and the value is an object the ".onion" Special-Use Domain Name, and the value is an object
with the following fields. with the fields described below.
The contents of the values of the "onionCAA" object are: The contents of the values of the "onionCAA" object are as follows:
caa (required, string or null) The CAA record set as a string, caa (required, string or null): The CAA record set as a string,
encoded in the same way as if was included in the hidden service encoded in the same way as if was included in the Hidden Service
descriptor. If the hidden service does not have a CAA record set Descriptor. If the Hidden Service does not have a CAA record set,
then this MUST be null. then this MUST be null.
expiry (required, integer) The Unix timestamp at which this CAA expiry (required, integer): The Unix timestamp at which this CAA
record set will expire. This SHOULD NOT be more than 8 hours in record set will expire. This SHOULD NOT be more than 8 hours in
the future. ACME servers MUST process this as at least a 64-bit the future. ACME servers MUST process this as at least a 64-bit
integer to ensure functionality beyond 2038. integer to ensure functionality beyond 2038.
signature (required, string) The Ed25519 signature of the CAA record signature (required, string): The Ed25519 signature of the CAA
set using the private key corresponding to the ".onion" Special- record set using the private key corresponding to the ".onion"
Use Domain Name, encoded using base64url. The signature is Special-Use Domain Name, encoded using base64url. The signature
defined below. is defined below.
The data that the signature is calculated over is the concatenation The data that the signature is calculated over is the concatenation
of the following, encoded in UTF-8 [RFC3629]: of the following, encoded in UTF-8 [RFC3629]:
"onion-caa|" || expiry || "|" || caa "onion-caa|" || expiry || "|" || caa
Where "|" is the ASCII character 0x7C, and expiry is the expiry field Where "|" is the ASCII character 0x7C, and expiry is the expiry field
as a decimal string with no leading zeros. If the caa field is null as a decimal string with no leading zeros. If the caa field is null,
it is represented as an empty string in the signature calculation. it is represented as an empty string in the signature calculation.
6.4.1. ACME servers requiring in-band CAA 6.4.1. ACME Servers Requiring In-Band CAA
If an ACME server does not support fetching a service's CAA record If an ACME server does not support fetching a service's CAA record
set from its service descriptor it, and the ACME client does not set from its Hidden Service Descriptor, and the ACME client does not
provide an "onionCAA" object in its finalize request the ACME server provide an "onionCAA" object in its finalize request, the ACME server
MUST respond with an "onionCAARequired" error to indicate this. MUST respond with an "onionCAARequired" error to indicate this.
To support signalling the server's support for fetching CAA record To support signaling the server's support for fetching CAA record
sets over Tor, a new field is defined in the directory "meta" object sets over Tor, a new field is defined in the directory "meta" object
to signal this. to signal this.
inBandOnionCAARequired (optional, boolean) If true, the ACME server inBandOnionCAARequired (optional, boolean): If true, the ACME server
requires the client to provide the CAA record set in the finalize requires the client to provide the CAA record set in the finalize
request. If false or absent the ACME server does not require the request. If false or absent, the ACME server does not require the
client to provide the CAA record set is this manner. client to provide the CAA record set is this manner.
A directory of such a CA could look like A directory of such a CA could look like the following:
HTTP/1.1 200 OK HTTP/1.1 200 OK
Content-Type: application/json Content-Type: application/json
{ {
"newNonce": "https://acme-server.example.onion/acme/new-nonce", "newNonce": "https://acme-server.example.onion/acme/new-nonce",
"newAccount": "https://acme-server.example.onion/acme/new-account", "newAccount": "https://acme-server.example.onion/acme/new-account",
"newOrder": "https://acme-server.example.onion/acme/new-order", "newOrder": "https://acme-server.example.onion/acme/new-order",
"revokeCert": "https://acme-server.example.onion/acme/revoke-cert", "revokeCert": "https://acme-server.example.onion/acme/revoke-cert",
"keyChange": "https://acme-server.example.onion/acme/key-change", "keyChange": "https://acme-server.example.onion/acme/key-change",
"meta": { "meta": {
"termsOfService": "https://acme-server.example.onion/acme/terms/2023-10-13", "termsOfService":
"https://acme-server.example.onion/acme/terms/2023-10-13",
"website": "https://acmeforonions.example/", "website": "https://acmeforonions.example/",
"caaIdentities": ["acmeforonions.example"], "caaIdentities": ["acmeforonions.example"],
"inBandOnionCAARequired": true "inBandOnionCAARequired": true
} }
} }
6.4.2. Example in-band CAA 6.4.2. Example In-Band CAA
Given the following example CAA record set for Given the following example CAA record set for
5anebu2glyc235wbbop3m2ukzlaptpkq333vdtdvcjpigyb7x2i2m2qd.onion 5anebu2glyc235wbbop3m2ukzlaptpkq333vdtdvcjpigyb7x2i2m2qd.onion
(additional linebreaks have been added for readability): (additional line breaks have been added for readability):
caa 128 issue "acmeforonions.example; caa 128 issue "acmeforonions.example;
validationmethods=onion-csr-01" validationmethods=onion-csr-01"
caa 0 iodef "mailto:example@example.com" caa 0 iodef "mailto:example@example.com"
The following would be submitted to the ACME server's finalize The following would be submitted to the ACME server's finalize
endpoint (additional linebreaks have been added for readability): endpoint (additional line breaks have been added for readability):
POST /acme/order/TOlocE8rfgo/finalize POST /acme/order/TOlocE8rfgo/finalize
Host: acme-server.example.onion Host: acme-server.example.onion
Content-Type: application/jose+json Content-Type: application/jose+json
{ {
"protected": base64url({ "protected": base64url({
"alg": "ES256", "alg": "ES256",
"kid": "https://acme-server.example.onion/acme/acct/evOfKhNU60wg", "kid":
"https://acme-server.example.onion/acme/acct/evOfKhNU60wg",
"nonce": "MSF2j2nawWHPxxkE3ZJtKQ", "nonce": "MSF2j2nawWHPxxkE3ZJtKQ",
"url": "https://acme-server.example.onion/acme/order/TOlocE8rfgo/finalize" "url": "https://acme-server.example.onion/acme/order/
TOlocE8rfgo/finalize"
}), }),
"payload": base64url({ "payload": base64url({
"csr": "MIIBPTCBxAIBADBFMQ...FS6aKdZeGsysoCo4H9P", "csr": "MIIBPTCBxAIBADBFMQ...FS6aKdZeGsysoCo4H9P",
"onionCAA": { "onionCAA": {
"5anebu2glyc235wbbop3m2ukzlaptpkq333vdtdvcjpi "5anebu2glyc235wbbop3m2ukzlaptpkq333vdtdvcjpi
gyb7x2i2m2qd.onion": { gyb7x2i2m2qd.onion": {
"caa": "caa 128 issue \"acmeforonions.example; "caa": "caa 128 issue \"acmeforonions.example;
validationmethods=onion-csr-01\"\n validationmethods=onion-csr-01\"\n
caa 0 iodef \"mailto:example@example.com\"", caa 0 iodef \"mailto:example@example.com\"",
"expiry": 1697210719, "expiry": 1697210719,
skipping to change at page 14, line 4 skipping to change at line 601
"expiry": 1697210719, "expiry": 1697210719,
"signature": "u_iP6JZ4JZBrzQUKH6lSrWejjRfeQmkTuehc0_FaaTNP "signature": "u_iP6JZ4JZBrzQUKH6lSrWejjRfeQmkTuehc0_FaaTNP
AV0RVxpUz9r44DRdy6kgy0ofnx18KIhMrP7N1wpxAA==" AV0RVxpUz9r44DRdy6kgy0ofnx18KIhMrP7N1wpxAA=="
} }
} }
}), }),
"signature": "uOrUfIIk5RyQ...nw62Ay1cl6AB" "signature": "uOrUfIIk5RyQ...nw62Ay1cl6AB"
} }
7. IANA Considerations 7. IANA Considerations
7.1. Validation Methods 7.1. Validation Methods
Per this document, one new entry has been added to the "ACME One new entry has been added to the "ACME Validation Methods"
Validation Methods" registry defined in Section 9.7.8 of [RFC8555] registry that was defined in Section 9.7.8 of [RFC8555]
(https://www.iana.org/assignments/acme/acme.xhtml#acme-validation- (<https://www.iana.org/assignments/acme>).
methods). This entry is defined below:
+==============+=================+======+===============+ +==============+=================+======+===============+
| Label | Identifier Type | ACME | Reference | | Label | Identifier Type | ACME | Reference |
+==============+=================+======+===============+ +==============+=================+======+===============+
| onion-csr-01 | dns | Y | This document | | onion-csr-01 | dns | Y | This document |
+--------------+-----------------+------+---------------+ +--------------+-----------------+------+---------------+
Table 1: New entry Table 1: onion-csr-01 Validation Method
7.2. Error Types 7.2. Error Types
Per this document, one new entry has been added to the "ACME Error One new entry has been added to the "ACME Error Types" registry that
Types" registry defined in Section 9.7.8 of [RFC8555] was defined in Section 9.7.4 of [RFC8555]
(https://www.iana.org/assignments/acme/acme.xhtml#acme-error-types). (<https://www.iana.org/assignments/acme>).
This entry is defined below:
+==================+===============================+===========+ +==================+===============================+===========+
| Type | Description | Reference | | Type | Description | Reference |
+==================+===============================+===========+ +==================+===============================+===========+
| onionCAARequired | The CA only supports checking | This | | onionCAARequired | The CA only supports checking | This |
| | CAA for hidden services in- | document | | | the CAA for Hidden Services | document |
| | band, but the client has not | | | | in-band, but the client has | |
| | provided an in-band CAA | | | | not provided an in-band CAA | |
+------------------+-------------------------------+-----------+ +------------------+-------------------------------+-----------+
Table 2: New entry Table 2: onionCAARequired Error Type
7.3. Directory Metadata Fields 7.3. Directory Metadata Fields
Per this document, one new entry has been added to the "ACME One new entry has been added to the "ACME Directory Metadata Fields"
Directory Metadata Fields" registry defined in Section 9.7.8 of registry that was defined in Section 9.7.6 of [RFC8555]
[RFC8555] (https://www.iana.org/assignments/acme/acme.xhtml#acme- (<https://www.iana.org/assignments/acme>).
directory-metadata-fields). This entry is defined below:
+==================+============+===============+ +==================+============+===============+
| Field name | Field type | Reference | | Field name | Field type | Reference |
+==================+============+===============+ +==================+============+===============+
| onionCAARequired | boolean | This document | | onionCAARequired | boolean | This document |
+------------------+------------+---------------+ +------------------+------------+---------------+
Table 3: New entry Table 3: onionCAARequired Metadata Field
8. Security Considerations 8. Security Considerations
8.1. Security of the "onion-csr-01" challenge 8.1. Security of the onion-csr-01 Challenge
The security considerations of [cabf-br] apply to issuance using the The security considerations of [cabf-br] apply to issuance using the
CSR method. Certificate Request method.
8.2. Use of "dns" identifier type 8.2. Use of the "dns" Identifier Type
The re-use of the "dns" identifier type for a Special-Use Domain Name The reuse of the "dns" identifier type for a Special-Use Domain Name
not actually in the DNS infrastructure raises questions regarding its not actually in the DNS infrastructure raises questions regarding its
suitability. The reasons to pursue this path in the first place are suitability. The reasons to pursue this path in the first place are
detailed in Appendix A. It is felt that there is little security detailed in Appendix A. It is felt that there is little security
concern in reuse of the "dns" identifier type with regards the mis- concern in reuse of the "dns" identifier type with regard to the mis-
issuance by CAs that are not aware of ".onion" Special-Use Domain issuance by CAs that are not aware of ".onion" Special-Use Domain
Names, as CAs would not be able to resolve the identifier in the DNS. Names as CAs would not be able to resolve the identifier in the DNS.
8.2.1. "http-01" Challenge 8.2.1. http-01 Challenge
In the absence of knowledge of this document a CA would follow the In the absence of knowledge of this document, a CA would follow the
procedure set out in Section 8.3 of [RFC8555] which specifies that procedure set out in Section 8.3 of [RFC8555], which specifies that
the CA should "Dereference the URL using an HTTP GET request". Given the CA should "Dereference the URL using an HTTP GET request". Given
that ".onion" Special-Use Domain Names require special handling to that ".onion" Special-Use Domain Names require special handling to
dereference, this de-referencing will fail, disallowing issuance. dereference, this dereferencing will fail, disallowing issuance.
8.2.2. "tls-alpn-01" Challenge 8.2.2. tls-alpn-01 Challenge
In the absence of knowledge of this document a CA would follow the In the absence of knowledge of this document, a CA would follow the
procedure set out in Section 3 of [RFC8737] which specifies that the procedure set out in Section 3 of [RFC8737], which specifies that the
CA "resolves the domain name being validated and chooses one of the CA "resolves the domain name being validated and chooses one of the
IP addresses returned for validation". Given that ".onion" Special- IP addresses returned for validation". Given that ".onion" Special-
Use Domain Names are not resolvable to IP addresses, this de- Use Domain Names are not resolvable to IP addresses, this
referencing will fail, disallowing issuance. dereferencing will fail, disallowing issuance.
8.2.3. "dns-01" Challenge 8.2.3. dns-01 Challenge
In the absence of knowledge of this document a CA would follow the In the absence of knowledge of this document, a CA would follow the
procedure set out in Section 8.4 of [RFC8555] which specifies that procedure set out in Section 8.4 of [RFC8555], which specifies that
the CA should "query for TXT records for the validation domain name". the CA should "query for TXT records for the validation domain name".
Given that ".onion" Special-Use Domain Names are not present in the Given that ".onion" Special-Use Domain Names are not present in the
DNS infrastructure, this query will fail, disallowing issuance. DNS infrastructure, this query will fail, disallowing issuance.
8.3. Key Authorization with "onion-csr-01" 8.3. Key Authorization with onion-csr-01
The "onion-csr-01" challenge does not make use of the key The onion-csr-01 challenge does not make use of the key authorization
authorization string defined in Section 8.1 of [RFC8555]. This does string defined in Section 8.1 of [RFC8555]. This does not weaken the
not weaken the integrity of authorizations. integrity of authorizations.
The key authorization exists to ensure that whilst an attacker The key authorization exists to ensure that, whilst an attacker
observing the validation channel can observe the correct validation observing the validation channel can observe the correct validation
response, they cannot compromise the integrity of authorizations as response, they cannot compromise the integrity of authorizations as
the response can only be used with the account key for which it was the response can only be used with the account key for which it was
generated. As the validation channel for this challenge is ACME generated. As the validation channel for this challenge is ACME
itself, and ACME already requires that the request be signed by the itself, and ACME already requires that the request be signed by the
account, the key authorization is not necessary. account, the key authorization is not necessary.
8.4. Use of Tor for non-".onion" domains 8.4. Use of Tor for Domains That Are Not ".onion"
An ACME server MUST NOT utilise Tor for the validation of An ACME server MUST NOT utilize Tor for the validation of domains
non-".onion" domains, due to the risk of exit hijacking that are not ".onion", due to the risk of exit hijacking
[spoiled-onions]. [spoiled-onions].
8.5. Redirects with "http-01" 8.5. Redirects with http-01
A site MAY redirect to another site when completing validation using A site MAY redirect to another site when completing validation using
the "http-01" challenge. This redirect MAY be to either another the http-01 challenge. This redirect MAY be to either another
".onion" Special-Use Domain Name, or to a domain in the public DNS. ".onion" Special-Use Domain Name or a domain in the public DNS. A
A site operator MUST consider the privacy implications of redirecting site operator MUST consider the privacy implications of redirecting
to a non-".onion" site - namely that the ACME server operator will to a site that is not ".onion" -- namely that the ACME server
then be able to learn information about the site redirected to that operator will then be able to learn information about the site they
they would not if accessed via a ".onion" Special-Use Domain Name, were redirected to that they would not have if accessed via a
such as its IP address. If the site redirected to is on the same or ".onion" Special-Use Domain Name, such as its IP address. If the
an adjacent host to the ".onion" Special-Use Domain Name this reveals site redirected to is on the same or an adjacent host to the ".onion"
information Part Tor Rendezvous Specification - Version 3 of Special-Use Domain Name, this reveals information that the "Tor
[tor-spec] was otherwise designed to protect. Rendezvous Specification - Version 3" section of [tor-spec] was
otherwise designed to protect.
If an ACME server receives a redirect to a domain in the public DNS If an ACME server receives a redirect to a domain in the public DNS,
it MUST NOT utilise Tor to make a connection to it, due to the risk it MUST NOT utilize Tor to make a connection to it due to the risk of
of exit hijacking. exit hijacking.
8.6. Security of CAA records 8.6. Security of CAA Records
The second layer descriptor is signed, encrypted and MACed in a way The Second Layer Hidden Service Descriptor is signed, encrypted, and
that only a party with access to the secret key of the hidden service encoded using a Message Authentication Code (MAC) in a way that only
could manipulate what is published there. For more information about a party with access to the secret key of the Hidden Service could
this process see Part "Hidden service descriptors: encryption format" manipulate what is published there. For more information about this
of [tor-spec]. process, see the "Hidden service descriptors: encryption format"
section of [tor-spec].
8.7. In-band CAA 8.7. In-Band CAA
Tor directory servers are inherently untrusted entities, and as such Tor directory servers are inherently untrusted entities. As such,
there is no difference in the security model for accepting CAA there is no difference in the security model for accepting CAA
records directly from the ACME client or fetching them over Tor. records directly from the ACME client or fetching them over Tor: the
There is no difference in the security model between accepting CAA
records directly from the ACME client and fetching them over Tor; the
CAA records are verified using the same hidden service key in either CAA records are verified using the same hidden service key in either
case. case.
8.8. Access of the Tor network 8.8. Access of the Tor Network
The ACME server MUST make its own connection to the hidden service The ACME server MUST make its own connection to the Hidden Service
via the Tor network, and MUST NOT outsource this to a third-party via the Tor network and MUST NOT outsource this to a third-party
service, such as by using Tor2Web. service, such as Tor2Web.
8.9. Anonymity of the ACME client 8.9. Anonymity of the ACME Client
ACME clients requesting certificates for ".onion" Special-Use Domain ACME clients requesting certificates for ".onion" Special-Use Domain
Names not over the Tor network can inadvertently expose to unintended Names not over the Tor network can inadvertently expose the existence
parties the existence of a hidden service on the host requesting of a Hidden Service on the host requesting certificates to unintended
certificates to unintended parties - even when features such as ECH parties; this is true even when features such as Encrypted
[I-D.ietf-tls-esni] are utilised, as the IP addresses of ACME servers ClientHello (ECH) [tls-esni] are utilized, as the IP addresses of
are generally well-known, static, and not used for any other purpose. ACME servers are generally well-known, static, and not used for any
other purpose.
ACME clients SHOULD connect to ACME servers over the Tor network to ACME clients SHOULD connect to ACME servers over the Tor network to
alleviate this, preferring a hidden service endpoint if the CA alleviate this, preferring a Hidden Service endpoint if the CA
provides such a service. provides such a service.
If an ACME client requests a publicly trusted WebPKI certificate it If an ACME client requests a publicly trusted WebPKI certificate, it
will expose the existence of the Hidden Service publicly due to its will expose the existence of the Hidden Service publicly due to its
inclusion in Certificate Transparency logs [RFC9162]. Hidden Service inclusion in Certificate Transparency logs [RFC9162]. Hidden Service
operators MUST consider the privacy implications of this before operators MUST consider the privacy implications of this before
requesting WebPKI certificates. ACME client developers SHOULD warn requesting WebPKI certificates. ACME client developers SHOULD warn
users about the risks of CT logged certificates for hidden services. users about the risks of CT-logged certificates for Hidden Services.
8.9.1. Avoid unnecessary certificates 8.9.1. Avoid Unnecessary Certificates
Not all services will need a publicly trusted WebPKI certificate; for Not all services will need a publicly trusted WebPKI certificate; for
internal or non-public services, operators SHOULD consider using internal or non-public services, operators SHOULD consider using
self-signed or privately-trusted certificates that aren't logged to self-signed or privately trusted certificates that aren't logged to
certificate transparency. certificate transparency.
8.9.2. Obfuscate subscriber information 8.9.2. Obfuscate Subscriber Information
When an ACME client is registering to an ACME server it SHOULD When an ACME client is registering with an ACME server, it SHOULD
provide minimal or obfuscated subscriber details to the CA such as a provide minimal or obfuscated subscriber details to the CA, such as a
pseudonymous email address, if at all possible. pseudonymous email address, if at all possible.
8.9.3. Separate ACME account keys 8.9.3. Separate ACME Account Keys
If a hidden service operator does not want their different hidden If a Hidden Service operator does not want their different Hidden
services to be correlated by a CA they MUST use separate ACME account Services to be correlated by a CA, they MUST use separate ACME
keys for each hidden service. account keys for each Hidden Service.
9. References 9. References
9.1. Normative References
[BCP14] Best Current Practice 14, 9.1. Normative References
<https://www.rfc-editor.org/info/bcp14>.
At the time of writing, this BCP comprises the following:
Bradner, S., "Key words for use in RFCs to Indicate [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, Requirement Levels", BCP 14, RFC 2119,
DOI 10.17487/RFC2119, March 1997, DOI 10.17487/RFC2119, March 1997,
<https://www.rfc-editor.org/info/rfc2119>. <https://www.rfc-editor.org/info/rfc2119>.
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/info/rfc8174>.
[RFC2986] Nystrom, M. and B. Kaliski, "PKCS #10: Certification [RFC2986] Nystrom, M. and B. Kaliski, "PKCS #10: Certification
Request Syntax Specification Version 1.7", RFC 2986, Request Syntax Specification Version 1.7", RFC 2986,
DOI 10.17487/RFC2986, November 2000, DOI 10.17487/RFC2986, November 2000,
<https://www.rfc-editor.org/info/rfc2986>. <https://www.rfc-editor.org/info/rfc2986>.
[RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data
Encodings", RFC 4648, DOI 10.17487/RFC4648, October 2006, Encodings", RFC 4648, DOI 10.17487/RFC4648, October 2006,
<https://www.rfc-editor.org/info/rfc4648>. <https://www.rfc-editor.org/info/rfc4648>.
[RFC7686] Appelbaum, J. and A. Muffett, "The ".onion" Special-Use [RFC7686] Appelbaum, J. and A. Muffett, "The ".onion" Special-Use
Domain Name", RFC 7686, DOI 10.17487/RFC7686, October Domain Name", RFC 7686, DOI 10.17487/RFC7686, October
2015, <https://www.rfc-editor.org/info/rfc7686>. 2015, <https://www.rfc-editor.org/info/rfc7686>.
[RFC8037] Liusvaara, I., "CFRG Elliptic Curve Diffie-Hellman (ECDH) [RFC8037] Liusvaara, I., "CFRG Elliptic Curve Diffie-Hellman (ECDH)
and Signatures in JSON Object Signing and Encryption and Signatures in JSON Object Signing and Encryption
(JOSE)", RFC 8037, DOI 10.17487/RFC8037, January 2017, (JOSE)", RFC 8037, DOI 10.17487/RFC8037, January 2017,
<https://www.rfc-editor.org/info/rfc8037>. <https://www.rfc-editor.org/info/rfc8037>.
[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/info/rfc8174>.
[RFC8555] Barnes, R., Hoffman-Andrews, J., McCarney, D., and J. [RFC8555] Barnes, R., Hoffman-Andrews, J., McCarney, D., and J.
Kasten, "Automatic Certificate Management Environment Kasten, "Automatic Certificate Management Environment
(ACME)", RFC 8555, DOI 10.17487/RFC8555, March 2019, (ACME)", RFC 8555, DOI 10.17487/RFC8555, March 2019,
<https://www.rfc-editor.org/info/rfc8555>. <https://www.rfc-editor.org/info/rfc8555>.
[RFC8659] Hallam-Baker, P., Stradling, R., and J. Hoffman-Andrews, [RFC8659] Hallam-Baker, P., Stradling, R., and J. Hoffman-Andrews,
"DNS Certification Authority Authorization (CAA) Resource "DNS Certification Authority Authorization (CAA) Resource
Record", RFC 8659, DOI 10.17487/RFC8659, November 2019, Record", RFC 8659, DOI 10.17487/RFC8659, November 2019,
<https://www.rfc-editor.org/info/rfc8659>. <https://www.rfc-editor.org/info/rfc8659>.
skipping to change at page 19, line 10 skipping to change at line 843
Environment (ACME) TLS Application-Layer Protocol Environment (ACME) TLS Application-Layer Protocol
Negotiation (ALPN) Challenge Extension", RFC 8737, Negotiation (ALPN) Challenge Extension", RFC 8737,
DOI 10.17487/RFC8737, February 2020, DOI 10.17487/RFC8737, February 2020,
<https://www.rfc-editor.org/info/rfc8737>. <https://www.rfc-editor.org/info/rfc8737>.
[RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO
10646", STD 63, RFC 3629, DOI 10.17487/RFC3629, November 10646", STD 63, RFC 3629, DOI 10.17487/RFC3629, November
2003, <https://www.rfc-editor.org/info/rfc3629>. 2003, <https://www.rfc-editor.org/info/rfc3629>.
[tor-spec] The Tor Project, "Tor Specifications", [tor-spec] The Tor Project, "Tor Specifications",
<https://spec.torproject.org/print.html>. <https://spec.torproject.org>.
[tor-rend-spec-v2] [tor-rend-spec-v2]
The Tor Project, "Tor Rendezvous Specification - Version The Tor Project, "Tor Rendezvous Specification - Version
2", <https://spec.torproject.org/rend-spec-v2>. 2", commit 2437d19c,
<https://spec.torproject.org/rend-spec-v2>.
[cabf-br] CA/Browser Forum, "Baseline Requirements for the Issuance [cabf-br] CA/Browser Forum, "Baseline Requirements for the Issuance
and Management of Publicly-Trusted Certificates", and Management of Publicly-Trusted TLS Server
Certificates", Version 2.0.6, 5 August 2024,
<https://cabforum.org/working-groups/server/baseline- <https://cabforum.org/working-groups/server/baseline-
requirements/documents/CA-Browser-Forum-TLS-BR-2.0.6.pdf>. requirements/documents/CA-Browser-Forum-TLS-BR-2.0.6.pdf>.
9.2. Informative References 9.2. Informative References
[onion-services-setup] [onion-services-setup]
The Tor Project, "Set Up Your Onion Service", The Tor Project, "Set Up Your Onion Service",
<https://community.torproject.org/onion-services/setup/>. <https://community.torproject.org/onion-services/setup/>.
[spoiled-onions] [spoiled-onions]
Winter, P., Köwer, R., Mulazzani, M., Huber, M., Winter, P., Köwer, R., Mulazzani, M., Huber, M.,
Schrittwieser, S., Lindskog, S., and E. Weippl, "Spoiled Schrittwieser, S., Lindskog, S., and E. Weippl, "Spoiled
Onions: Exposing Malicious Tor Exit Relays", Onions: Exposing Malicious Tor Exit Relays", Privacy
Enhancing Technologies (PETS 2014), Lecture Notes in
Computer Science, vol. 8555, pp. 304-331,
DOI 10.1007/978-3-319-08506-7_16, 2014, DOI 10.1007/978-3-319-08506-7_16, 2014,
<https://rdcu.be/d1ZRp>. <https://doi.org/10.1007/978-3-319-08506-7_16>.
[I-D.ietf-tls-esni] [tls-esni] Rescorla, E., Oku, K., Sullivan, N., and C. A. Wood, "TLS
Rescorla, E., Oku, K., Sullivan, N., and C. A. Wood, "TLS
Encrypted Client Hello", Work in Progress, Internet-Draft, Encrypted Client Hello", Work in Progress, Internet-Draft,
draft-ietf-tls-esni-22, 15 September 2024, draft-ietf-tls-esni-25, 14 June 2025,
<https://datatracker.ietf.org/doc/html/draft-ietf-tls- <https://datatracker.ietf.org/doc/html/draft-ietf-tls-
esni-22>. esni-25>.
[RFC9162] Laurie, B., Messeri, E., and R. Stradling, "Certificate [RFC9162] Laurie, B., Messeri, E., and R. Stradling, "Certificate
Transparency Version 2.0", RFC 9162, DOI 10.17487/RFC9162, Transparency Version 2.0", RFC 9162, DOI 10.17487/RFC9162,
December 2021, <https://www.rfc-editor.org/info/rfc9162>. December 2021, <https://www.rfc-editor.org/info/rfc9162>.
Appendix A. Discussion on the use of the "dns" identifier type Appendix A. Discussion on the Use of the "dns" Identifier Type
The reasons for utilising the "dns" identifier type in ACME and not The reasons for utilizing the "dns" identifier type in ACME and not
defining a new identifier type for ".onion"s may not seem obvious at defining a new identifier type for ".onion" may not seem obvious at
first glance. After all, ".onion" Special-Use Domain Names are not first glance. After all, ".onion" Special-Use Domain Names are not
part of the DNS infrastructure and as such why should they use the part of the DNS infrastructure and, as such, why should they use the
"dns" identifier type? "dns" identifier type?
Appendix B.2.a.ii of [cabf-br] defines, and this document allows, Appendix B.2.a.ii of [cabf-br] defines, and this document allows,
using the "http-01" or "tls-alpn-01" validation methods already using the http-01 or tls-alpn-01 validation methods already present
present in ACME (with some considerations). Given the situation of a in ACME (with some considerations). Given the situation of a web
web server placed behind a Tor terminating proxy (as per the setup server placed behind a Tor-terminating proxy (as per the setup
suggested by the Tor project [onion-services-setup]), existing ACME suggested by the Tor project [onion-services-setup]), existing ACME
tooling can be blind to the fact that a ".onion" Special-Use Domain tooling can be blind to the fact that a ".onion" Special-Use Domain
Name is being utilised, as they simply receive an incoming TCP Name is being utilized, as they simply receive an incoming TCP
connection as they would regardless (albeit from the Tor terminating connection as they would regardless (albeit from the Tor-terminating
proxy). proxy).
An example of this would be Certbot placing the ACME challenge An example of this would be Certbot placing the ACME challenge
response file in the webroot of an NGINX web server. Neither Certbot response file in the webroot of an NGINX web server. Neither Certbot
nor NGINX would require any modification to be aware of any special nor NGINX would require any modification to be aware of any special
handling for ".onion" Special-Use Domain Names. handling for ".onion" Special-Use Domain Names.
This does raise some questions regarding security within existing This does raise some questions regarding security within existing
implementations, however the authors believe this is of little implementations; however, the authors believe this is of little
concern, as per Section 8.2. concern, as per Section 8.2.
Acknowledgements Acknowledgements
With thanks to the Open Technology Fund for funding the work that With thanks to the Open Technology Fund for funding the work that
went into this document. went into this document.
The authors also wish to thank the following for their input on this The authors also wish to thank the following for their input on this
document: document:
 End of changes. 160 change blocks. 
384 lines changed or deleted 380 lines changed or added

This html diff was produced by rfcdiff 1.48.