ACME for .onion domains

A project to standardise extensions to the ACME protocol to allow its use for issuing TLS certificates to Tor hidden services.

IETF datatracker Read the current working draft Diff with the last submission

Background

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.

I have a suggestion/question

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.

Other output work of this project

This project has necessitated the creation of other libraries and tools to support it, these include:

torrosion - A Tor library for Rust
Björn - Components for building an ACME CA

Reference CA

A CA issuing non publicly trusted certificates to .onion domains is provided to assist client developers in implementing this standard.

ACME

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.

Certbot `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

CAA

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.

Certificate Transparency

All certificates issued are logged to Certificate Transparency logs. The current logs in use are:

https://ct.googleapis.com/testtube
https://ct.googleapis.com/logs/crucible
https://ct.googleapis.com/logs/eu1/solera2024
https://ct.googleapis.com/logs/eu1/solera2025h1
https://ct.googleapis.com/logs/eu1/solera2025h2
https://dodo.ct.comodo.com

OCSP

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.

Chain of trust

Root certificate

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

Intermediate 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-----

Acknowledgements

With thanks to the Open Technology Fund for funding the work going into this standard.