Skip to content
Snippets Groups Projects
Select Git revision
  • main default protected
1 result
Blame Permalink
README.markdown 12.71 KiB

Onion x509

This repository contains a set of command-line utilities for bridging the gap between Onion services and x509.

Everything in this repository should be considered experimental.

Installation

Please install this tool using Go's own package management tool:

$ go get github.com/ahf/onion-x509/cmd/onion-x509

Usage

  1. The first thing we have to do is to create a new Onion Service using Tor. The easiest way to achieve this is to let Tor do all the work for us.

    We add the following two lines to an empty torrc file:

    HiddenServiceDir onion-service-test/
HiddenServicePort 80 127.0.0.1:80

    We start Tor with our new configuration file:

    $ tor -f torrc
Nov 25 01:13:13.023 [notice] Tor 0.4.1.6 running on Linux with Libevent 2.1.11-stable, OpenSSL 1.1.1d, Zlib 1.2.11, Liblzma 5.2.4, and Libzstd 1.4.4.
Nov 25 01:13:13.024 [notice] Tor can't help you if you use it wrong! Learn how to be safe at https://www.torproject.org/download/download#warning
Nov 25 01:13:13.024 [warn] Tor was compiled with zstd 1.4.3, but is running with zstd 1.4.4. For safety, we'll avoid using advanced zstd functionality.
Nov 25 01:13:13.024 [notice] Read configuration file "/home/user/torrc".
Nov 25 01:13:13.026 [warn] Path for HiddenServiceDir (onion-service-test/) is relative and will resolve to /home/user/onion-service-test/. Is this what you wanted?
Nov 25 01:13:13.026 [notice] Opening Socks listener on 127.0.0.1:9050
Nov 25 01:13:13.026 [notice] Opened Socks listener on 127.0.0.1:9050
Nov 25 01:13:13.000 [notice] Parsing GEOIP IPv4 file /usr/share/tor/geoip.
Nov 25 01:13:13.000 [notice] Parsing GEOIP IPv6 file /usr/share/tor/geoip6.
Nov 25 01:13:13.000 [notice] Bootstrapped 0% (starting): Starting
Nov 25 01:13:13.000 [notice] Starting with guard context "default"
Nov 25 01:13:14.000 [notice] Bootstrapped 5% (conn): Connecting to a relay
Nov 25 01:13:14.000 [notice] Bootstrapped 10% (conn_done): Connected to a relay
Nov 25 01:13:14.000 [notice] Bootstrapped 14% (handshake): Handshaking with a relay
Nov 25 01:13:14.000 [notice] Bootstrapped 15% (handshake_done): Handshake with a relay done
Nov 25 01:13:14.000 [notice] Bootstrapped 20% (onehop_create): Establishing an encrypted directory connection
Nov 25 01:13:14.000 [notice] Bootstrapped 25% (requesting_status): Asking for networkstatus consensus
Nov 25 01:13:14.000 [notice] Bootstrapped 30% (loading_status): Loading networkstatus consensus
Nov 25 01:13:14.000 [notice] Bootstrapped 45% (requesting_descriptors): Asking for relay descriptors
Nov 25 01:13:14.000 [notice] I learned some more directory information, but not enough to build a circuit: We need more microdescriptors: we have 4610/6080, and can only build 54% of likely paths. (We have 82% of guards bw, 79% of midpoint bw, and 82% of exit bw = 54% of path bw.)
Nov 25 01:13:14.000 [notice] Bootstrapped 71% (loading_descriptors): Loading relay descriptors
Nov 25 01:13:15.000 [notice] Bootstrapped 75% (enough_dirinfo): Loaded enough directory info to build circuits
Nov 25 01:13:15.000 [notice] Bootstrapped 80% (ap_conn): Connecting to a relay to build circuits
Nov 25 01:13:15.000 [notice] Bootstrapped 85% (ap_conn_done): Connected to a relay to build circuits
Nov 25 01:13:15.000 [notice] Bootstrapped 89% (ap_handshake): Finishing handshake with a relay to build circuits
Nov 25 01:13:15.000 [notice] Bootstrapped 90% (ap_handshake_done): Handshake finished with a relay to build circuits
Nov 25 01:13:15.000 [notice] Bootstrapped 95% (circuit_create): Establishing a Tor circuit
Nov 25 01:13:15.000 [notice] Bootstrapped 100% (done): Done

    We can now stop Tor again using ctrl+c.

  2. Tor should have created a new directory for us in our current working directory:

    $ ls -l onion-service-test
total 16
drwx------ 2 user user 4096 Nov 25 01:13 authorized_clients
-rw------- 1 user user   63 Nov 25 01:13 hostname
-rw------- 1 user user   64 Nov 25 01:13 hs_ed25519_public_key
-rw------- 1 user user   96 Nov 25 01:13 hs_ed25519_secret_key

    These files are what makes up a Tor onion service. If we try to read the hostname file it will reveal the hostname of the newly generated onion service:

    $ cat onion-service-test/hostname 
h35bxybaetjwnen332fvrvfyuixkpmpoppvermckng65aosadimpdpqd.onion

    Both hs_ed25519_secret_key and hs_ed25519_public_key are binary files, but let us take a look at the hs_ed25519_public_key using the hexdump utility:

    $ hexdump -C onion-service-test/hs_ed25519_public_key
00000000  3d 3d 20 65 64 32 35 35  31 39 76 31 2d 70 75 62  |== ed25519v1-pub|
00000010  6c 69 63 3a 20 74 79 70  65 30 20 3d 3d 00 00 00  |lic: type0 ==...|
00000020  3e fa 1b e0 20 24 d3 66  91 bb de 8b 58 d4 b8 a2  |>... $.f....X...|
00000030  2e a7 b1 ee 7b ea 48 b0  4a 69 bd d0 3a 40 1a 18  |....{.H.Ji..:@..|
00000040

    The interesting part of this file is the last 32 bytes: 3e fa 1b e0 20 24 d3 66 91 bb de 8b 58 d4 b8 a2 2e a7 b1 ee 7b ea 48 b0 4a 69 bd d0 3a 40 1a 18. This is the 32 byte ed25519 public key, which is also the value that is used to compute the onion service address found in the hostname file.

    The hs_ed25519_secret_key file contains the secret key, but we are not going to reveal that one in this document. This file should, as the name implies, remain secret.

  3. We can now use the onion-x509 tool to generate an x509 Certificate Authority using the files generated by Tor for our new onion service:

    $ onion-x509 ca create --secret-key onion-service-test/hs_ed25519_secret_key \
                       --output onion-ca.pem \
                       --organization "Test Onion CA" \
                       --country DK \
                       --locality Copenhagen
2019/11/25 01:28:38 Loading ed25519 keys from onion-service-test/hs_ed25519_secret_key
2019/11/25 01:28:38 Loaded ed25519 keys for h35bxybaetjwnen332fvrvfyuixkpmpoppvermckng65aosadimpdpqd.onion
2019/11/25 01:28:38 Creating CA certificate
2019/11/25 01:28:38 Saving Certificate Authority to onion-ca.pem

    The tool have now created the onion-ca.pem file for us, which contains the PEM-encoded CA certificate:

    $ cat onion-ca.pem
-----BEGIN CERTIFICATE-----
MIIBtzCCAWmgAwIBAgIRAKupDZqRM7jwJ2MKPw3W34kwBQYDK2VwMFsxCzAJBgNV
BAYTAkRLMQkwBwYDVQQIEwAxEzARBgNVBAcTCkNvcGVuaGFnZW4xCTAHBgNVBAkT
ADEJMAcGA1UEERMAMRYwFAYDVQQKEw1UZXN0IE9uaW9uIENBMB4XDTE5MTEyNTAx
MjgzOFoXDTI5MTEyMjAxMjgzOFowWzELMAkGA1UEBhMCREsxCTAHBgNVBAgTADET
MBEGA1UEBxMKQ29wZW5oYWdlbjEJMAcGA1UECRMAMQkwBwYDVQQREwAxFjAUBgNV
BAoTDVRlc3QgT25pb24gQ0EwKjAFBgMrZXADIQA++hvgICTTZpG73otY1LiiLqex
7nvqSLBKab3QOkAaGKNCMEAwDgYDVR0PAQH/BAQDAgKEMB0GA1UdJQQWMBQGCCsG
AQUFBwMCBggrBgEFBQcDATAPBgNVHRMBAf8EBTADAQH/MAUGAytlcANBAKeyrOuv
FU09Ca8wrHf5Vxt+ePdaePm3galzfe8hKjgk4qtRgAAWM3JshPePEeCbF8/Ppmwu
vHiMatXFzXLobQo=
-----END CERTIFICATE-----

    Using the OpenSSL command-line tool we can inspect this certificate:

    $ openssl x509 -text -noout -in onion-ca.pem
Certificate:
    Data:
        Version: 3 (0x2)
        Serial Number:
            ab:a9:0d:9a:91:33:b8:f0:27:63:0a:3f:0d:d6:df:89
        Signature Algorithm: ED25519
        Issuer: C = DK, ST = , L = Copenhagen, street = , postalCode = , O = Test Onion CA
        Validity
            Not Before: Nov 25 01:28:38 2019 GMT
            Not After : Nov 22 01:28:38 2029 GMT
        Subject: C = DK, ST = , L = Copenhagen, street = , postalCode = , O = Test Onion CA
        Subject Public Key Info:
            Public Key Algorithm: ED25519
                ED25519 Public-Key:
                pub:
                    3e:fa:1b:e0:20:24:d3:66:91:bb:de:8b:58:d4:b8:
                    a2:2e:a7:b1:ee:7b:ea:48:b0:4a:69:bd:d0:3a:40:
                    1a:18
        X509v3 extensions:
            X509v3 Key Usage: critical
                Digital Signature, Certificate Sign
            X509v3 Extended Key Usage: 
                TLS Web Client Authentication, TLS Web Server Authentication
            X509v3 Basic Constraints: critical
                CA:TRUE
    Signature Algorithm: ED25519
         a7:b2:ac:eb:af:15:4d:3d:09:af:30:ac:77:f9:57:1b:7e:78:
         f7:5a:78:f9:b7:81:a9:73:7d:ef:21:2a:38:24:e2:ab:51:80:
         00:16:33:72:6c:84:f7:8f:11:e0:9b:17:cf:cf:a6:6c:2e:bc:
         78:8c:6a:d5:c5:cd:72:e8:6d:0a

    If we take a look in the Subject Public Key Info section of the OpenSSL output, we can see that the public key used for this certificate is the same ed25519 public key as our onion service uses which we extracted with hexdump from the hs_ed25519_public_key file in the previous step.

  4. Using our newly created Certificate Authority, we can now begin to create x509 certificates for our onion services:

    $ onion-x509 cert create --secret-key onion-service-test/hs_ed25519_secret_key \
                         --ca onion-ca.pem \
                         --output onion-cert.pem \
                         --hostnames "www.@, @" \
                         --organization "Test Certificate"
2019/11/25 01:39:09 Loading ed25519 keys from onion-service-test/hs_ed25519_secret_key
2019/11/25 01:39:09 Loaded ed25519 keys for h35bxybaetjwnen332fvrvfyuixkpmpoppvermckng65aosadimpdpqd.onion
2019/11/25 01:39:09 Loading Certificate Authority from onion-ca.pem
2019/11/25 01:39:09 Generating ed25519 keys for our certificate
2019/11/25 01:39:09 Saving ed25519 secret key to onion-cert-secret-key.pem
2019/11/25 01:39:09 Creating certificate
2019/11/25 01:39:09 Saving certificate to onion-cert.pem

    The newly created onion-cert.pem and onion-cert-secret-key.pem are together with the onion-ca.pem file the files you have to use when setting up your TLS enabled services (for example to nginx for a webserver).

    We can take a look at the content of our newly created certificate:

    $ openssl x509 -text -noout -in onion-cert.pem
Certificate:
    Data:
        Version: 3 (0x2)
        Serial Number:
            94:12:ab:f1:ef:40:cf:6b:64:96:e6:be:10:c5:b5:0f
        Signature Algorithm: ED25519
        Issuer: C = DK, ST = , L = Copenhagen, street = , postalCode = , O = Test Onion CA
        Validity
            Not Before: Nov 25 01:39:09 2019 GMT
            Not After : Nov 24 01:39:09 2021 GMT
        Subject: C = , ST = , L = , street = , postalCode = , O = Test Certificate
        Subject Public Key Info:
            Public Key Algorithm: ED25519
                ED25519 Public-Key:
                pub:
                    cd:78:ef:e0:78:ff:65:20:94:fa:2f:fc:63:b3:98:
                    6e:fe:b2:25:c7:9b:a9:c8:8a:6b:aa:87:ce:8f:d7:
                    d7:53
        X509v3 extensions:
            X509v3 Key Usage: critical
                Digital Signature
            X509v3 Extended Key Usage: 
                TLS Web Client Authentication, TLS Web Server Authentication
            X509v3 Basic Constraints: critical
                CA:FALSE
            X509v3 Subject Alternative Name: 
                DNS:www.h35bxybaetjwnen332fvrvfyuixkpmpoppvermckng65aosadimpdpqd.onion, DNS:h35bxybaetjwnen332fvrvfyuixkpmpoppvermckng65aosadimpdpqd.onion
    Signature Algorithm: ED25519
         78:8d:6a:80:40:5d:42:8d:b9:b6:e6:f4:46:af:5e:2f:f2:c3:
         d2:56:c7:50:32:a7:9c:39:2d:b8:c5:35:da:ff:52:99:c5:0b:
         9e:b1:8a:21:9b:68:f6:31:24:f5:ce:16:37:8d:dc:e6:ec:ae:
         0b:04:c3:f4:57:4c:c1:b1:01:07

    As we can see in this output, the "issuer" of our certificate is the "Test Onion CA" that we created in the previous step. We can also see that the @s used in the --hostnames parameter to our onion-x509 cert command have been expanded to the onion address of our onion service.

    We now have everything we need to setup an Onion service with TLS certificates that are signed using the identity key of the onion service.

Test Site

One can have a look at https://fxqcrxx5qj4aw7xllakk2qiux26dksiqjydyeb4gfq3f7wfs65yooaad.onion/ -- it is setup using this tool, but do note that Tor Browser currently doesn't work with it.

Authors