A project to standardise extensions to the ACME protocol to allow its use for issuing TLS certificates to Tor hidden services.
As it currently stands the CA/Browser Forum Baseline Requirements Appendix B allow for the issuance of TLS certificates to .onion domains, however it is not widely implemented and no CA supports automated issuance of certificates to .onion domains.
As of January 2023 only DigiCert and HARICA offer TLS certificates to .onion domains. DigiCert only offer EV certificates (expensive and no possibility of automatic renewal), and HARICA offer no automated process for any of their certificates. The goal of this project is to standardise how ACME can be used to issue certificates to .onion domains automatically, and to get CAs to implement the eventual standard.
We'd love to hear it! Head over to GitHub and file an issue; or if email is more your thing you can reach me at q@as207960.net.
This project has necessitated the creation of other libraries and tools to support it, these include:
A CA issuing non publicly trusted certificates to .onion domains is provided to assist client developers in implementing this standard.
The CA implements ACME v2, along with the extensions defined in this standard. The ACME directory is available
at https://acme.api.acmeforonions.org/directory
. It is also available over Tor at http://acme.api.35ukth27shac6ef2n3brtcjoft3yg64qxjkadvkx7ueytjolzvbyvnqd.onion/directory
.
Client implementations that already support the http-01
and tls-alpn-01
challenges
(such as Certbot) will be able to work with this CA without modification. Consider the case of having a Tor
hidden service on the domain 5anebu2glyc235wbbop3m2ukzlaptpkq333vdtdvcjpigyb7x2i2m2qd.onion
with
the Tor software setup to redirect port 80 requests to port 8080 on the local machine. The following command
can be used to obtain a certificate for this domain:
certbot certonly --server https://acme.api.acmeforonions.org/directory --standalone --http-01-port 8080 --http-01-address 127.0.0.1 -d 5anebu2glyc235wbbop3m2ukzlaptpkq333vdtdvcjpigyb7x2i2m2qd.onion
Or if the hidden service is already pointing at an Nginx server the following can be used:
certbot certonly --server https://acme.api.acmeforonions.org/directory --nginx -d 5anebu2glyc235wbbop3m2ukzlaptpkq333vdtdvcjpigyb7x2i2m2qd.onion
The onion-csr-01
challenge, and http-01
and tls-alpn-01
challenges against
hidden services requiring authentication will require additional work to implement in clients.
onion-csr-01
plugin
We have written a plugin for Certbot that implements the onion-csr-01
challenge.
The plugin is available on PyPi. It can be used as follows:
certbot certonly --server https://acme.api.acmeforonions.org/directory --authenticator onion-csr --onion-csr-hs-dir /var/lib/tor/example_hs/ -d 5anebu2glyc235wbbop3m2ukzlaptpkq333vdtdvcjpigyb7x2i2m2qd.onion
The CA will check CAA records for the domain being issued a certificate. Our identifying domain name for CAA is
test.acmeforonions.org
.
A fork of Tor implementing the CAA extensions to the hidden service descriptor is available on GitHub. A hidden service with CAA records in its descriptor is available at znkiu4wogurrktkqqid2efdg4nvztm7d2jydqenrzeclfgv3byevnbid.onion; this can be used to test client implementations that shouldn't care about CAA ignore it correctly, and to test CAA validators against.
All certificates issued are logged to Certificate Transparency logs. The current logs in use are:
The validity of certificates issued by the CA can be checked with the OCSP responder at
http://ocsp.api.acmeforonions.org
. It is also available over Tor at http://ocsp.api.35ukth27shac6ef2n3brtcjoft3yg64qxjkadvkx7ueytjolzvbyvnqd.onion
.
The root of the certificate chain is the AS207960 Test CA (ECDSA P-384; C = GB, ST = Cymru, O = AS207960
Cyfyngedig, OU = AS207960 Department of Random Numbers, CN = AS207960 Test CA
).
Download as PEM. crt.sh.
Certificate: Data: Version: 3 (0x2) Serial Number: 11:3f:28:0b:18:01:00:c2:ee:94:96:b4:11:f6:b6:e4:a8:f0:4e:03 Signature Algorithm: ecdsa-with-SHA512 Issuer: C = GB, ST = Cymru, O = AS207960 Cyfyngedig, OU = AS207960 Department of Random Numbers, CN = AS207960 Test CA Validity Not Before: Jun 8 16:39:59 2021 GMT Not After : May 27 16:39:59 2071 GMT Subject: C = GB, ST = Cymru, O = AS207960 Cyfyngedig, OU = AS207960 Department of Random Numbers, CN = AS207960 Test CA Subject Public Key Info: Public Key Algorithm: id-ecPublicKey Public-Key: (384 bit) pub: 04:e8:f8:71:4d:4e:20:e7:d9:6c:97:d4:05:fb:9d: a3:2f:3d:3e:ac:bd:88:ad:69:6e:f1:2c:9d:2c:60: 2f:34:dc:a3:7a:67:6f:bf:5e:d3:ff:1c:08:39:1e: 7d:47:0c:24:29:9d:e0:17:8c:1d:f9:4c:c4:f0:d4: c0:90:e1:4e:5f:63:99:f8:f9:63:45:9d:5c:81:3c: 03:f7:b9:7f:0c:1f:4b:b7:a3:23:29:0d:5e:3b:cb: a5:59:fa:8a:66:06:59 ASN1 OID: secp384r1 NIST CURVE: P-384 X509v3 extensions: X509v3 Subject Key Identifier: FD:A0:A9:78:D0:AE:85:E7:31:E8:0B:51:4D:D8:E0:24:34:73:15:7E X509v3 Authority Key Identifier: keyid:FD:A0:A9:78:D0:AE:85:E7:31:E8:0B:51:4D:D8:E0:24:34:73:15:7E X509v3 Basic Constraints: critical CA:TRUE X509v3 Key Usage: critical Digital Signature, Certificate Sign, CRL Sign Signature Algorithm: ecdsa-with-SHA512 30:64:02:30:6f:96:05:a2:d1:18:94:12:a6:85:9b:7e:56:26: c5:84:4e:2c:fe:e5:59:f6:fa:08:cd:ce:f4:19:54:a3:14:af: 5b:d5:8f:f9:a7:fc:ed:73:31:99:e2:09:66:cc:19:07:02:30: 32:27:0d:80:a0:9b:d4:30:54:c1:2a:76:da:6a:b9:3e:b4:5e: dc:43:aa:f1:a7:09:5e:6a:3a:35:9f:fc:29:75:b6:27:fa:0d: 6e:19:9b:b2:c2:5f:a4:ef:3e:a9:7b:98 -----BEGIN CERTIFICATE----- MIICsTCCAjigAwIBAgIUET8oCxgBAMLulJa0Efa25KjwTgMwCgYIKoZIzj0EAwQw gYYxCzAJBgNVBAYTAkdCMQ4wDAYDVQQIDAVDeW1ydTEcMBoGA1UECgwTQVMyMDc5 NjAgQ3lmeW5nZWRpZzEuMCwGA1UECwwlQVMyMDc5NjAgRGVwYXJ0bWVudCBvZiBS YW5kb20gTnVtYmVyczEZMBcGA1UEAwwQQVMyMDc5NjAgVGVzdCBDQTAgFw0yMTA2 MDgxNjM5NTlaGA8yMDcxMDUyNzE2Mzk1OVowgYYxCzAJBgNVBAYTAkdCMQ4wDAYD VQQIDAVDeW1ydTEcMBoGA1UECgwTQVMyMDc5NjAgQ3lmeW5nZWRpZzEuMCwGA1UE CwwlQVMyMDc5NjAgRGVwYXJ0bWVudCBvZiBSYW5kb20gTnVtYmVyczEZMBcGA1UE AwwQQVMyMDc5NjAgVGVzdCBDQTB2MBAGByqGSM49AgEGBSuBBAAiA2IABOj4cU1O IOfZbJfUBfudoy89Pqy9iK1pbvEsnSxgLzTco3pnb79e0/8cCDkefUcMJCmd4BeM HflMxPDUwJDhTl9jmfj5Y0WdXIE8A/e5fwwfS7ejIykNXjvLpVn6imYGWaNjMGEw HQYDVR0OBBYEFP2gqXjQroXnMegLUU3Y4CQ0cxV+MB8GA1UdIwQYMBaAFP2gqXjQ roXnMegLUU3Y4CQ0cxV+MA8GA1UdEwEB/wQFMAMBAf8wDgYDVR0PAQH/BAQDAgGG MAoGCCqGSM49BAMEA2cAMGQCMG+WBaLRGJQSpoWbflYmxYROLP7lWfb6CM3O9BlU oxSvW9WP+af87XMxmeIJZswZBwIwMicNgKCb1DBUwSp22mq5PrRe3EOq8acJXmo6 NZ/8KXW2J/oNbhmbssJfpO8+qXuY -----END CERTIFICATE-----
All certificates are issued by the AS207960 Onion CA intermediate certificate (ECDSA P-256; C = GB, ST =
Cymru, O = AS207960 Cyfyngedig, OU = AS207960 Department of Random Numbers, CN = AS207960 Onion CA
).
Download as PEM. crt.sh.
Certificate: Data: Version: 3 (0x2) Serial Number: 4098 (0x1002) Signature Algorithm: ecdsa-with-SHA512 Issuer: C = GB, ST = Cymru, O = AS207960 Cyfyngedig, OU = AS207960 Department of Random Numbers, CN = AS207960 Test CA Validity Not Before: Mar 18 18:14:52 2023 GMT Not After : Mar 15 18:14:52 2033 GMT Subject: C = GB, ST = Cymru, O = AS207960 Cyfyngedig, OU = AS207960 Department of Random Numbers, CN = AS207960 Onion CA Subject Public Key Info: Public Key Algorithm: id-ecPublicKey Public-Key: (256 bit) pub: 04:11:33:d9:55:87:61:37:70:51:0c:6b:ce:62:d2: e0:1c:83:0a:db:d4:64:4f:08:3a:d7:6a:ab:68:25: 7d:51:8b:06:15:34:2d:05:20:92:67:82:6b:8f:dc: 3f:82:20:d9:bf:88:f9:c6:5f:cc:98:6f:8e:37:6e: fe:a0:73:07:cb ASN1 OID: prime256v1 NIST CURVE: P-256 X509v3 extensions: X509v3 Subject Key Identifier: F9:E0:AD:E4:3E:8A:45:05:97:91:48:95:26:2E:5E:B5:1C:A1:9C:19 X509v3 Authority Key Identifier: keyid:FD:A0:A9:78:D0:AE:85:E7:31:E8:0B:51:4D:D8:E0:24:34:73:15:7E X509v3 Basic Constraints: critical CA:TRUE, pathlen:0 X509v3 Key Usage: critical Digital Signature, Certificate Sign, CRL Sign X509v3 Name Constraints: critical Permitted: DNS:onion Signature Algorithm: ecdsa-with-SHA512 30:64:02:30:2d:53:7f:45:fb:b5:4e:43:cf:24:a8:a7:ce:2a: bf:d0:5b:89:ba:68:3c:28:cd:1e:fe:5f:4d:80:2e:84:c6:64: 06:41:12:49:35:e0:71:17:a6:bc:02:67:50:b2:1a:74:02:30: 5d:42:9d:47:bc:f6:2d:02:b6:d8:c2:a4:7a:41:72:85:76:36: 0d:cc:dc:81:86:95:02:a0:cb:9d:b8:48:ab:bc:53:a2:9c:1c: 02:90:62:f8:6a:eb:75:a6:12:08:94:5e -----BEGIN CERTIFICATE----- MIICnTCCAiSgAwIBAgICEAIwCgYIKoZIzj0EAwQwgYYxCzAJBgNVBAYTAkdCMQ4w DAYDVQQIDAVDeW1ydTEcMBoGA1UECgwTQVMyMDc5NjAgQ3lmeW5nZWRpZzEuMCwG A1UECwwlQVMyMDc5NjAgRGVwYXJ0bWVudCBvZiBSYW5kb20gTnVtYmVyczEZMBcG A1UEAwwQQVMyMDc5NjAgVGVzdCBDQTAeFw0yMzAzMTgxODE0NTJaFw0zMzAzMTUx ODE0NTJaMIGHMQswCQYDVQQGEwJHQjEOMAwGA1UECAwFQ3ltcnUxHDAaBgNVBAoM E0FTMjA3OTYwIEN5ZnluZ2VkaWcxLjAsBgNVBAsMJUFTMjA3OTYwIERlcGFydG1l bnQgb2YgUmFuZG9tIE51bWJlcnMxGjAYBgNVBAMMEUFTMjA3OTYwIE9uaW9uIENB MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEETPZVYdhN3BRDGvOYtLgHIMK29Rk Twg612qraCV9UYsGFTQtBSCSZ4Jrj9w/giDZv4j5xl/MmG+ON27+oHMHy6N/MH0w HQYDVR0OBBYEFPngreQ+ikUFl5FIlSYuXrUcoZwZMB8GA1UdIwQYMBaAFP2gqXjQ roXnMegLUU3Y4CQ0cxV+MBIGA1UdEwEB/wQIMAYBAf8CAQAwDgYDVR0PAQH/BAQD AgGGMBcGA1UdHgEB/wQNMAugCTAHggVvbmlvbjAKBggqhkjOPQQDBANnADBkAjAt U39F+7VOQ88kqKfOKr/QW4m6aDwozR7+X02ALoTGZAZBEkk14HEXprwCZ1CyGnQC MF1CnUe89i0CttjCpHpBcoV2Ng3M3IGGlQKgy524SKu8U6KcHAKQYvhq63WmEgiU Xg== -----END CERTIFICATE-----
With thanks to the Open Technology Fund for funding the work going into this standard.