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:
      • https://lists.torproject.org/pipermail/tor-project/2024-September/003851.html
      • tpo/applications/tor-browser#42887 (closed)
      • BadSSL But Onion
    • Explain the chosen openssl options.
  • 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-384 over SHA-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/base section.
• 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)