Certificates for Onion Services page
Description
Onionspray's HTTPS Certificates page is outdatedspecific, and something broader is needed.
Tasks
-
Existing documentation: -
Update Onionspray's HTTPS Certificates page to reflect the current procedures: -
Updates from the CA-related commands (onionspray#76 (closed)). -
Improve the instructions to make test certificates.
-
-
-
New documentation: -
Create new documentation page in the Ecosystem docs under the Checklist document or into a HOWTO/Guides section in the web docs. -
Move the non-Onionspray specific sections to a broader scope. -
Add document version (or last updated date). -
References: -
Certificate proposals page. -
Onionmine. -
BadSSL But Onion · Wiki · The Tor Project / Applications and to PieroV's Onion Tests. -
Faulty Onions. -
Onionsec: -
OnionSec repository. -
OnionSec UI repository. As of 2025-10-8, this repository is not yet public. -
ACME for Onions. -
Certificate's maximum validity period accepted by browsers. -
Note about certificates going to public CT Logs upon issuance.
-
-
Requirements/recommendations/examples: -
Example with OpenSSL and RSA 4096. -
Check whether wildcard SANs can be always added, regardless the user asked for a single-domain cert (confirm whether it's harmless to leave the wildcard in the CSR, even if a single-domain cert is purchased) (onionmine#39 (closed)). -
Mention the requirement for Subjet Alt Names in .onion certificates. References: -
Explain the chosen openssloptions.
-
-
Validating certificates: -
Using OpenSSL. -
Using GnuTLS.
-
-
Observability: monitoring certificates: -
Manually ("the simplest way to monitor certificates is to manually check and track it's expiration date" etc). -
Using Onionprobe. -
Through CT Logs.
-
-
Security: -
Security levels. -
Explain about chosen algorithms, hash functions etc: why, for .onion, ECDSA is recommended over RSA (answer: performance, since other metrics are negligible considering the communication is already happening over .onion); why SHA-384overSHA-512; etc. -
Note on using in-browser TLS keys/CSR generation tools.
-
-
Webserver support: -
Instructions for Apache. -
Instructions for NGINX. -
Instructions for Lighttpd.
-
-
Consider making it a general certificates page, not just for HTTPS or TLS. If that's the case, it's better moving it to the apps/basesection.
-
-
Add references to this new page/documentation into: -
The HTTPS section in the Onionsite checklist. -
Onionspray's HTTPS Certificates page. -
Onion Plan's Certificate proposals page. -
Onionmine docs (tutorial and usage pages). -
Onionspray Ansible Role. -
A Forum post announcing the page, asking people to review and send merge requests.
-
Time estimation
- Complexity: very small (0.5 day)
- Uncertainty: low (x1.1)
- Reference (adapted)
Edited by Silvio Rhatto