diff --git a/draft-ietf-acme-onion.xml b/draft-ietf-acme-onion.xml index 5d9db4b..611940e 100644 --- a/draft-ietf-acme-onion.xml +++ b/draft-ietf-acme-onion.xml @@ -56,7 +56,7 @@ it requires special consideration to validate control of one such that ACME could be used on ".onion" Special-Use Domain Names. In order to allow ACME to be utilised to issue certificates to ".onion" Special-Use Domain Names this document - specifies challenges suitable to validate control of these Special-Use Domain Names. Additionally this document + specifies challenges suitable to validate control of these Special-Use Domain Names. Additionally, this document defines an alternative to the DNS Certification Authority Authorization (CAA) Resource Record that can be used with ".onion" Special-Use Domain Names. @@ -74,9 +74,9 @@ Identifier defines the "dns" identifier type. This identifier type MUST be used when requesting a certificate for a ".onion" Special-Use Domain Name. The value of identifier - MUST be the textual representation as defined in §3. The value - MAY include subdomain labels. Version 2 addresses MUST NOT be used as these are - now considered insecure. + MUST be the textual representation as defined in + . The value MAY include + subdomain labels. Version 2 addresses MUST NOT be used as these are now considered insecure. Example identifiers: { @@ -94,9 +94,9 @@
Identifier Validation Challenges - The CA/Browser Forum Baseline Requirements §B.2 define methods accepted by - the CA industry for validation of ".onion" Special-Use Domain Names. This document incorporates these methods - into ACME challenges. + The CA/Browser Forum Baseline Requirements () + define methods accepted by the CA industry for validation of ".onion" Special-Use Domain Names. + This document incorporates these methods into ACME challenges.
Existing challenges
@@ -106,26 +106,29 @@
Existing "http-01" Challenge - The "http-01" challenge is defined as in §8.3 may be used to validate a ".onion" - Special-Use Domain Names, with the modifications defined in this standard. - The ACME server SHOULD follow redirects; note that these may be redirects to non ".onion" - services, and the server SHOULD honour these. + The "http-01" challenge is defined as in can be used to validate a + ".onion" Special-Use Domain Names, with the modifications defined in this standard. + The ACME server SHOULD follow redirects; note that these MAY be redirects to + non ".onion" services, and the server SHOULD honour these.
Existing "tls-alpn-01" Challenge - The "tls-alpn-01" challenge is defined as in may be used to validate a ".onion" + The "tls-alpn-01" challenge is defined as in can be used to validate a ".onion" Special-Use Domain Names, with the modifications defined in this standard.
New "onion-csr-01" Challenge The two methods already defined in ACME and allowed by the CA/BF do not allow issuance of wildcard - certificates. This new validation method incorporates the specially signed CSR (as defined by - § B.2.b) into ACME to allow for the issuance of wildcard certificates. + certificates. A ".onion" Special-Use Domain Name can have subdomains (just like any other domain in the DNS), + and a site operator may find it useful to have one certificate for all virtual hosts on their site. + This new validation method incorporates the specially signed CSR (as defined by + ) into ACME to allow for the issuance of + wildcard certificates. To this end a new challenge type called "onion-csr-01" is defined, with the following fields:
type (required, string)
-
The string "onion-csr-01"
+
The string onion-csr-01
nonce (required, string)
A Base64 encoded nonce, including padding characters. It MUST contain at least 64 bits of entropy. It MUST NOT be valid for more @@ -146,10 +149,10 @@ following additional extension attributes and signing it with the private key of the ".onion" Special-Use Domain Name:
    -
  • A caSigningNonce attribute containing the nonce provided in the challenge. This MUST - be raw bytes, and not the base64 encoded value provided in the challenge object.
    • -
  • An applicantSigningNonce containing a nonce generated by the client. This MUST have at - least 64 bits of entropy. This MUST be raw bytes.
    • +
  • A caSigningNonce attribute containing the nonce provided in the challenge. This + MUST be raw bytes, and not the base64 encoded value provided in the challenge object.
    • +
  • An applicantSigningNonce containing a nonce generated by the client. This MUST + have at least 64 bits of entropy. This MUST be raw bytes.
These additional attributes have the following format @@ -179,7 +182,7 @@ applicantSigningNonce ATTRIBUTE ::= { The public key presented in this CSR MUST be the public key corresponding to the ".onion" Special-Use Domain Name being validated. It MUST NOT be the same public key presented in the CSR to finalize the order. - Client respond with the following object to validate the challenge + Client respond with the following object to validate the challenge:
csr (required, string)
@@ -224,23 +227,28 @@ Content-Type: application/jose+json it will use to connect these services will not be able to obtain a certificate using http-01 or tls-alpn-01, nor enforce CAA with any validation method. 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 use (as per INTRO-AUTH) to authenticate itself when - retrieving the hidden service descriptor. + Ed25519 public key it will use (as per + ) to + authenticate itself when retrieving the hidden service descriptor.
authKey (optional, object)
The Ed25519 public key encoded as per .
ACME servers MUST NOT use the same public key with multiple hidden services. ACME servers MAY re-use public keys for re-validation of the same hidden service. - There is no method to communicate to the CA that client authentication is required; instead the ACME server - MUST attempt to calculate its CLIENT-ID as per FIRST-LAYER-CLIENT-BEHAVIOR. - If no "auth-client" line in the first layer hidden service descriptor matches the computed client-id then the server - MUST assume that the hidden service does not require client authentication and proceed accordingly. + There is no method to communicate to the CA that client authentication is necessary; instead the ACME server + MUST attempt to calculate its CLIENT-ID as per + . + If no auth-client line in the first layer hidden service descriptor matches the computed client-id + then the server MUST assume that the hidden service does not require client authentication and + proceed accordingly. In the case the Ed25519 public key is novel to the client it will have to resign and republish its hidden service descriptor. It SHOULD wait some (indeterminate) amount of time for the new descriptor to propagate the Tor hidden service directory servers, before proceeding with responding to the challenge. - This should take no more than a few minutes. CAs MUST NOT expire challenges before a reasonable - time to allow publication of the new descriptor (this document suggests at least 30 minutes). + This should take no more than a few minutes. This specification does not set a fixed time as changes in the + operation of the Tor network can affect this propagation time in the future. ACME servers + MUST NOT expire challenges before a reasonable time to allow publication of the new descriptor - + this document suggests at least 30 minutes however it is entirely up to operator preference.
@@ -253,18 +261,19 @@ Content-Type: application/jose+json
Certification Authority Authorization (CAA) - ".onion" Special-Use Domain Name are not part of the DNS, and as such a variation on CAA is required - to allow restrictions to be placed on certificate issuance. + ".onion" Special-Use Domain Name are not part of the DNS, and as such a variation on CAA + is necessary to allow restrictions to be placed on certificate issuance. To this end a new field is added to the second layer hidden service descriptor - § 2.5.2.2. with the following format: + + with the following format: "caa" SP flags SP tag SP value NL [Any number of times] - The contents of "flag", "tag", and "value" are as per § 4.1.1. Multiple CAA records may - be present, as is the case in 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 ".onion" Special-Use Domain Name. - A hidden service's second layer descriptor using CAA may look something like the following: + The contents of "flag", "tag", and "value" are as per . + Multiple CAA records MAY be present, as is the case in 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 ".onion" Special-Use Domain Name. + A hidden service's second layer descriptor using CAA could look something like the following: create2-formats 2 single-onion-service @@ -276,18 +285,18 @@ introduction-point AwAGsAk5nSMpAhRqhMHbTFCTSlfhP8f5PqUhe6DatgMgk7kSL3KHCZUZ3C6tX
Relevant Resource Record Set 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 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 CAA records on the "onion" Special-Use TLD, as it - does not exist in any form except as described in , so implementors must not look here - either. - Instead all subdomains under a ".onion" Special-Use Domain Name share the same CAA record set. That is all of - these share a CAA record set with "a.onion": + there is in the DNS there is no 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 CAA records on the "onion" Special-Use TLD, + as it does not exist in any form except as described in , so implementors + MUST not look here either. + Instead all subdomains under a ".onion" Special-Use Domain Name share the same CAA record set. That is, + all of these share a CAA record set with "a.onion":
  • b.a.onion
  • c.a.onion
  • e.d.a.onion
- But these do not: + but these do not:
  • b.c.onion
  • c.d.onion
    • @@ -296,49 +305,51 @@ introduction-point AwAGsAk5nSMpAhRqhMHbTFCTSlfhP8f5PqUhe6DatgMgk7kSL3KHCZUZ3C6tX
When to check CAA - If the hidden service has client authentication enabled then it will be impossible for the CAA to decrypt - the second layer descriptor to read the CAA records until the CAAs public key has been added to first layer - descriptor. To this end a CA SHOULD wait until the client responds to an authorization, and - treat this as indication that their public key has been added and that the CA will be able to decrypt the - second layer descriptor. + If the hidden service has client authentication enabled then it will be impossible for the ACME server to + decrypt the second layer descriptor to read the CAA records until the ACME server's public key has been added + to the first layer descriptor. To this end an ACME server SHOULD wait until the client responds + to an authorization before checking CAA, and treat this response as indication that their public key has been + added and that the ACME server will be able to decrypt the second layer descriptor.
Preventing mis-issuance by unknown CAs - As the CAA records are in the second layer descriptor and in the case of a hidden service requiring client - authentication it is impossible to read them without the hidden service trusting a CA's public key, a method is - required to signal that there are CAA records present (but not reveal their contents, which may disclose - unwanted information about the hidden service operator). + In the case of a hidden service requiring client authentication it is impossible to read them without the + hidden service trusting a ACME server's public key - as the CAA records are in the second layer descriptor. + A method is necessary to signal that there are CAA records present (but not reveal their contents which + - in certain circumstances - would disclose unwanted information about the hidden service operator). To this end a new field is added to the first layer hidden service descriptor - § 2.5.1.2. with the following format: + + with the following format: "caa-critical" NL [At most once] - If a CA encounters this flag it MUST NOT proceed with issuance until it can decrypt and - parse the CAA records from the second layer descriptor. + If an ACME server encounters this flag it MUST NOT proceed with issuance until it can decrypt + and parse the CAA records from the second layer descriptor.
Alternative in-band presentation of CAA - A CA may not be willing to operate the infrastructure required to fetch, decode, and verify Tor hidden service - descriptors in order to check CAA records. To this end a method to signal CAA policies in-band of ACME is defined. - If a hidden service does use this method to provide CAA records to a CA it SHOULD still publish - CAA records if its CAA record set includes "iodef", "contactemail", or "contactphone" so that this information - is still publicly accessible. A hidden service operator MAY also not wish to publish a CAA - record set in its service descriptor to avoid revealing information about the service operator. - If a CA receives a validly signed CAA record set in the finalize request it need not check the CAA set in - the hidden service descriptor and can proceed with issuance on the basis of the client provided CAA record set - only. A CA, however, is not required to do anything with the client provided record set, and is free to always - fetch the record set from the service descriptor. + An ACME server might be unwilling to operate the infrastructure required to fetch, decode, and verify Tor + hidden service descriptors in order to check CAA records. To this end a method to signal CAA policies in-band + of ACME is defined. + 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 includes "iodef", "contactemail", or "contactphone" so that + this information is still publicly accessible. A hidden service operator MAY also not wish to + publish a CAA record set in its service descriptor to avoid revealing information about the service operator. + If an ACME server receives a validly signed CAA record set in the finalize request it need not check the CAA + set in the hidden service descriptor and can proceed with issuance on the basis of the client provided CAA + record set only. An ACME server MAY ignore the client provided record set, and is free to + always fetch the record set from the service descriptor. 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 Name in the order.
onionCAA (optional, dictionary of objects)
- The CAA record set for each ".onion" Special-Use Domain Name in the order. The key is the ".onion" Special-Use - Domain Name, and the value is an object with the following fields. + The CAA record set for each ".onion" Special-Use Domain Name in the order. The key is the ".onion" + Special-Use Domain Name, and the value is an object with the following fields.
- The contents of the "onionCAA" object are: + The contents of the values of the "onionCAA" object are:
caa (required, string or null)
@@ -348,7 +359,7 @@ introduction-point AwAGsAk5nSMpAhRqhMHbTFCTSlfhP8f5PqUhe6DatgMgk7kSL3KHCZUZ3C6tX
expiry (required, integer)
The Unix timestamp at which this CAA record set will expire. This SHOULD NOT be more than - 8 hours in the future. CAs MUST process this as at least a 64-bit integer to ensure + 8 hours in the future. ACME servers MUST process this as at least a 64-bit integer to ensure functionality beyond 2038.
signature (required, string)
@@ -363,19 +374,19 @@ introduction-point AwAGsAk5nSMpAhRqhMHbTFCTSlfhP8f5PqUhe6DatgMgk7kSL3KHCZUZ3C6tX Where "|" is the ASCII character 0x7C, and expiry is the expiry field as a decimal string with no leading zeros.
- CAs requiring in-band CAA - If a CA does not support fetching a service's CAA record set from its service descriptor it, and the - ACME client does not provide an "onionCAA" object in its finalize request the CA MUST respond - with an "onionCAARequired" error to indicate this. + ACME servers requiring in-band CAA + 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 provide an "onionCAA" object in its finalize request the ACME server + MUST respond with an "onionCAARequired" error to indicate this. Additionally, a new field is defined in the directory "meta" object to signal this.
inBandOnionCAARequired (optional, boolean)
- If true, the CA requires the client to provide the CAA record set in the finalize request. - If false or absent the CA does not require the client to provide the CAA record set is this manner. -
+ If true, the ACME server requires the client to provide the CAA record set in the finalize request. + If false or absent the ACME server does not require the client to provide the CAA record set is this + manner.
- A directory of such a CA may look like + A directory of such a CA could look like HTTP/1.1 200 OK Content-Type: application/json @@ -402,7 +413,7 @@ Content-Type: application/json caa 128 issue "test.acmeforonions.org; validationmethods=onion-csr-01" caa 0 iodef "mailto:example@example.com" - The following would be submitted to the CA's finalize endpoint + The following would be submitted to the ACME server's finalize endpoint POST /acme/order/TOlocE8rfgo/finalize Host: example.com @@ -437,7 +448,7 @@ Content-Type: application/jose+json
Validation Methods Per this document, one new entry has been added to the "ACME Validation Methods" registry defined in - §9.7.8. This entry is defined below: + . This entry is defined below: New entries @@ -461,7 +472,7 @@ Content-Type: application/jose+json
Error Types Per this document, one new entry has been added to the "ACME Error Types" registry defined in - §9.7.8. This entry is defined below: + . This entry is defined below:
New entries @@ -484,7 +495,7 @@ Content-Type: application/jose+json
Directory Metadata Fields Per this document, one new entry has been added to the "ACME Directory Metadata Fields" registry defined in - §9.7.8. This entry is defined below: + . This entry is defined below:
New entries @@ -507,6 +518,10 @@ Content-Type: application/jose+json
Security Considerations +
+ Security of the "onion-csr-01" challenge + The security considerations of apply to issuance using the CSR method. +
Use of "dns" identifier type The re-use of the "dns" identifier type for a Special-Use Domain Name not actually in the DNS infrastructure @@ -516,21 +531,21 @@ Content-Type: application/jose+json Special-Use Domain Names, as CAs would not be able to resolve the identifier in the DNS.
"http-01" Challenge - The CA would follow the procedure set out in §8.3 which specifies that the CA - should "Dereference the URL using an HTTP GET request". Given that ".onion" Special-Use Domain Names require + The CA would follow the procedure set out in which specifies that + the CA should "Dereference the URL using an HTTP GET request". Given that ".onion" Special-Use Domain Names require special handling to dereference, this de-referencing will fail, disallowing issuance.
"tls-alpn-01" Challenge - The CA would follow the procedure set out in §3 which specifies that the CA - "resolves the domain name being validated and chooses one of the IP addresses returned for validation". + The CA would follow the procedure set out in which specifies that the + CA "resolves the domain name being validated and chooses one of the IP addresses returned for validation". Given that ".onion" Special-Use Domain Names are not resolvable to IP addresses, this de-referencing will fail, disallowing issuance.
"dns-01" Challenge - The CA would follow the procedure set out in §8.4 which specifies that the CA - should "query for TXT records for the validation domain name". + The CA would follow the procedure set out in which specifies that + the CA should "query for TXT records for the validation domain name". Given that ".onion" Special-Use Domain Names are not present in the DNS infrastructure, this query will fail, disallowing issuance.
@@ -538,23 +553,35 @@ Content-Type: application/jose+json
Key Authorization with "onion-csr-01" The "onion-csr-01" challenge does not make use of the key authorization string defined in - §8.1. This does not weaken the integrity of authorizations. - The key authorization exists to ensure that whilst an attacker observing the validation channel may observe + . This does not weaken the integrity of authorizations. + The key authorization exists to ensure that whilst an attacker observing the validation channel can observe the correct validation response, they cannot compromise the integrity of authorizations as the response can only be used with the account key for which it was generated. As the validation channel for this challenge is ACME itself, and ACME already requires that the request be signed by the account, the key authorization is - not required. + not necessary.
Use of Tor for non ".onion" domains An ACME server MUST NOT utilise Tor for the validation of non ".onion" domains, due to the - risk of possible exit hijacking. + risk of exit hijacking. +
+
+ Redirects with "http-01" + A site MAY redirect to another site when completing validation using the "http-01" challenge. + This redirect can be to either another ".onion" Special-Use Domain Name, or to a domain in the public DNS. + A site operator SHOULD consider the privacy implications of redirecting to a non ".onion" + site - namely that the ACME server operator will then be able to learn information about the site redirected to + that they would not if accessed via a ".onion" Special-Use Domain Name, such as its IP address. If the site + redirected to is on the same or an adjacent host to the ".onion" Special-Use Domain Name this reveals + information was otherwise designed to protect. + 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 of exit hijacking.
Security of CAA records The second layer descriptor is signed, encrypted and MACed in a way that only a party with access to the secret key of the hidden service could manipulate what is published there. For more information about this - process see § 2.5.3. + process see .
In-band CAA @@ -569,9 +596,9 @@ Content-Type: application/jose+json
Anonymity of the ACME client - ACME clients requesting certificates for ".onion" Special-Use Domain Names may expose the existence of a - hidden service on the host to unintended parties - even when features such as ECH - are utilised, as the IP addresses of ACME servers are generally + ACME clients requesting certificates for ".onion" Special-Use Domain Names can inadvertently expose the + existence of a hidden service on the host requesting certificates to unintended parties - even when features + such as ECH are utilised, as the IP addresses of 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 alleviate this, preferring a hidden service endpoint if the CA provides such a service. @@ -606,7 +633,7 @@ Content-Type: application/jose+json - + Tor Rendezvous Specification - Version 3 @@ -615,7 +642,7 @@ Content-Type: application/jose+json - + Baseline Requirements for the Issuance and Management of Publicly-Trusted Certificates @@ -646,7 +673,7 @@ Content-Type: application/jose+json The reasons for utilising the "dns" identifier type in ACME and not defining a new identifier type for ".onion" s may not seem obvious at first glance. After all, ".onion" Special-Use Domain Names are not part of the DNS infrastructure and as such why should they use the "dns" identifier type? - The CA/Browser Forum Baseline Requirements §B.2.a.ii define, and this standard allows, + defines, and this standard allows, using the "http-01" or "tls-alpn-01" validation methods already present in ACME (with some considerations). Given the situation of a web server placed behind a Tor terminating proxy (as per the setup suggested by the Tor project ), existing ACME tooling can be blind to the fact that a