Skip to content

HTTPS Certificates

Creating HTTPS Certificates for Testing and Development

When connecting to the resulting onions over HTTP/SSL, you will be using wildcard self-signed SSL certificates - you will encounter many "broken links" which are due to the SSL certificate not being valid.

This is expected and proper behaviour; there are currently three ways to address this.

Install mkcert

The best solution for development purposes is to install mkcert onto the machine which will be running Onionspray and configure your own personal Certificate Authority for the certificates that you will need.

You can then add set ssl_mkcert 1 to configurations, and your mkcert root certificate will be used to sign the resulting onion certificates. You can install that certificate into your local copy of Tor Browser; of course it will not work for anyone else.

Visit /hello-onion/ URLs

The old solution was/is much more manual: Onionspray will use OpenSSL to create certificates, and then, for any onion - eg: www.a2s3c4d5e6f7g8h9.onion - Onionspray provides a fixed url:

  • https://www.a2s3c4d5e6f7g8h9.onion/hello-onion/

... which (/hello-onion/) is internally served by the NGINX proxy and provides a stable, fixed URL for SSL certificate acceptance; inside TorBrowser another effective solution is to open all the broken links, images and resources "in a new Tab" and accept the certificate there.

In production, of course, one would expect to use an SSL EV certificate to provide identity and assurance to an onion site, rendering these issues moot.

Buy a HTTPS Certificate from HARICA or Digicert

See below.

Buying a HTTPS Certificate from a Certificate Authority

If you choose to buy an Onion HTTPS certificate from (e.g.) HARICA, what will happen, and what will you need to do?

You will need to create a CSR (Certificate Signing Request)

I chose to buy:

  • A Server Certificate.
  • With Domain-Level (DV) Trust.
  • With a reasonable duration.
  • Using the in-browser generated CSR.
  • Using the ECDSA algorithm at 256 bits.
  • Important: remember the password!
  • Important: download the private key!

The HARICA website provides an in-browser method of generating a CSR, if you are not already familiar. Make sure to generate a good passphrase, and remember it, because you will need it soon. Also: make sure to download the privateKey.pem file that is offered, and keep it in a safe place.

If you manually create the CSR on the server, you'll use the 'onionaddress.key' file generated by openssl.

You will need to prove ownership of the site, to the CA

For example: HARICA will tell you that you need to post a secret key at a particular URL on your onion site; the message will read something like:

Place the file FILENAME to http://ONIONADDRESS.onion/.well-known/pki-validation/

... and they will offer you a file to download.

Download this file, and open it with a text editor; the content will be a long secret string, like THISISAREALLYLONGHEXADECIMALSECRET.

Add a line to your Onionspray configuration, substituting the values where necessary:

set ssl_proof_csv /.well-known/pki-validation/FILENAME,THISISAREALLYLONGHEXADECIMALSECRET

Then do something like:

onionspray config projectname.conf && onionspray nxreload projectname

... to install the URL handlers.

HARICA has a process of validation which involves generating an onion-csr. You won't need to add anything to your configuration.

Optional: what if you have multiple Onion addresses?

You can put multiple path,value strings into ssl_proof_csv, space-separated; use trailing backslashes to put entries onto separate lines:

set ssl_proof_csv \
    /.well-known/pki-validation/key1,value1 \
    /.well-known/pki-validation/key2,value2 \
    /.well-known/pki-validation/key3,value3

Optional: what if your multiple "proof" URLs all have the SAME pathname?

The ssl_proof_csv hack works if all the proof URLs are different; but if Digicert (or whomever) were to give you the same pathname (e.g. /.well-known/pki-validation/fileauth.txt) for all of the onions, what do you do?

Answer: you use "splicing". If you have onion addresses named xxxxxxxxxxxxxxxx and yyyyyyyyyyyyyyyy, then you can create files:

  • templates/nginx-site-xxxxxxxxxxxxxxxx.onion.conf
  • templates/nginx-site-yyyyyyyyyyyyyyyy.onion.conf

... and into each put something similar to the following incantation; customise as necessary:

    location = "/.well-known/pki-validation/fileauth.txt" {
      return 200 "RESPECTIVE-PROOF-STRING-GOES-HERE";
    }

... then when you next onionspray config and onionspray nxreload, that code should be spliced into the correct configuration for each onion.

You will need to install the certificates for your project

For each certificate, HARICA will offer you several files to download; download the "PEM Bundle" file and copy it to your Onionspray server. Also: copy the privateKey.pem file (mentioned above) to the Onionspray server.

Next, change Directory into ~/onionspray/projects/PROJECTNAME.d/ssl.d; you should see your development certificates, which will look like:

$ ls
ONIONADDRESS.onion.cert
ONIONADDRESS.onion.pem

There are two steps to installation:

  • Step 1: copy the PEM Bundle file from HARICA, on top of ONIONADDRESS.onion.cert
  • Step 2: unlock and extract (or rename) the private key, by doing:
    openssl ec -in privateKey.pem -out ONIONADDRESS.onion.pem

... and typing in the password that you chose during the CSR setup, earlier; if you chose to use RSA as the algorithm, you will need to use openssl rsa ... instead.

If you manually created the CSR, then rename the 'onionaddress.key' file the CSR generated to onionaddress.onion.pem.

Then: change directory back to the Onionspray directory, and do onionspray nxreload projectname, and test it.