Using Tor script to create a Tor network hidden service with vanity .onion address and export a service to the internet

Tor is not hidden

“In our experiments we collected 173667 unique .onion addresses in all using a single Amazon EC2 instances in 1 hour and found 4857 hidden web services online.”

Hidden Service Discovery

If you were to create a brand-new Tor v3 address, its address is not inherently public, but you might have little time before you’re discovered:

Bots & Crawlers: Hours to a day. Automated services scanning .onion addresses might identify the service pretty quickly.
Public Discovery (like human users or public listings): Days to weeks, depending on whether the address is actively shared or found.

This is just an estimate, and the actual time can vary based on scanning frequency, network traffic, and how indexed your .onion address becomes.

Tor to host an .onion service

Now, with the warnings in place, we can begin.

The purpose of this repo/post is to give someone a chance to test out hosting an .onion hidden service.

You can use this to quickly share a service to a friend, client, or even your future self.

A Tor hidden service does not need your server to have open ports or port forwarding - because it does not accept direct inbound connections from the public internet. Instead, both the client and the hidden service connect outbound to the Tor network, establishing circuits to special relays called introduction and rendezvous points. All communication is routed through these Tor relays, so as long as your server can make outbound connections to the Tor network, it can host a hidden service!

Tor Hidden Service Tutorial

This Intro
1-up Tor Script
1. Changes the Script makes
Vanity Name Creation
What Service to put on Tor
Torrc is important
The 1-up Tor Script uses two directories
Browsers that find an onion service
Want to know more?
Uninstall

1-up-tor-onion-address script

The 1-up-tor-onion-address.sh script sets up one service that will be available through a Tor .onion address.

This service is only available through the Tor network

This is intended as a demonstration. I hope you’re able to learn and enjoy using.

SOURCE: github.com/marcusholtz/tor-hidden-service

Download and run with:

  
wget https://github.com/MarcusHoltz/tor-hidden-service/archive/refs/heads/main.zip -O tor-hidden-service-repo.zip && unzip tor-hidden-service-repo.zip && rm tor-hidden-service-repo.zip && cd tor-hidden-service-main && chmod +x 1-up-tor-onion-address.sh && ./1-up-tor-onion-address.sh

Script Requirements

The 1-up-tor-onion-address.sh script will need sudo.

Sudo is required to set all of the directory permissions correctly.

You will then need docker installed to generate a vanity address and run the docker-compose.yml file that starts up Tor.

The 1-up-tor-onion-address.sh script is only intended to prepare the environment we’re using with Docker.

Changes the Script makes

The 1-up-tor-onion-address.sh script sets up two directories, a file, and optionally a vanity address.

Two Directories

You need sudo privs for:

tor_config/vanity_keys/

and

tor_data/

Those directories store the keys that are used for your .onion address. Kept safe from any normal user.

A file: torrc

A torrc file contains all the settings Tor uses.

You need sudo privs for:

tor_config/torrc

By changing this file we can tell Tor what services we want to serve on a Tor Hidden Service and where to find the corresponding .onion address.

Vanity Name Creation

A vanity address is an onion address that starts with a pre-chosen number of characters, usually a meaningful name related to a specific Onion Service.

For instance, one might try to generate an onion address for the mysitename website and end up with something looking like this:

mysitenameyx4fi3l6x2gyzmtmgxjyqyorj9qsb5r543izcwymle.onion

This has some advantages:

It is easy for Onion Services users to know which site they are about to access.
It has some branding appeal to site owners.
It is easy for Onion Services operators to debug their logs and know which services have errors.
Anyone else is very unlikely to come up with the exact key from the example above, but they may be able to find a similar key - one beginng with the same few letters.
- The longer the vanity name length, the less likly it is to have a forgery made.

Vanity Name Length

You can only pick something, at max, 7 characters.

Why?

Let’s say you were running this on a Raspberry Pi 2B….

Take a look at the approximate generation time per character for a Raspberry Pi 2B below:

Approximate Generation Time per Character Count Chart

Vanity Characters : Approximate Generation Time
: <1 second
: <1 second
: 1 second
: 30 seconds
: 16 minutes
: 8.5 hours
: 11.5 days
: 1 year
: 32 years
: 1,024 years
: 32,768 years
: 1 million years

Example vanities

So now that we know our upper limit on the amount of letters we can have, take a look at some examples….

Click to expand and take a look at the 6 character example vanities below:

6 character example vanity .onion domains

- 123456 - nopers - online - system - search - office - forums - mobile - garden - nature - movies - photos - social - future - people - estate - energy - income - browse - create - report - global - agency - potato - attack - wisdom - stream - viewer - status - screen - sector - survey - secure - signal - source - remote - direct - little - jazzed - dazzle - danger - school - family

How is the vanity generated

Thanks to the work on the cathugger/mkp224o repository, we’re able to generate vanity address for tor onion v3 (ed25519) hidden services.

Specifically, the 1-up-tor-onion-address.sh script will run: docker run ghcr.io/cathugger/mkp224o:master -n 3 <your_vanity_name>
It will generate 3 .onion addresses that begin with your vanity name, allowing you to select a favorite.
The .onion address will be in tor_config/vanity_keys/

Can’t I just use my own .onion address

Yes! The 1-up-tor-onion-address.sh script will prompt you to use your own, you just have to provide the path.

Instructions for Using Bringing Your Own Vanity Tor Address:

Make sure you have all of your files for your .onion address in the same directory:
- hostname - Contains your .onion address
- hs_ed25519_secret_key - Your private key
- hs_ed25519_public_key - Your public key
After the 1-up-tor-onion-address.sh script completes, verify your hidden service is correct:

sudo cat tor_data/hidden_service/hostname

What Service to put on Tor

You will also need a service to provide to the .onion address.

This can be anything. It can be another docker container, a python web server on your laptop, your favorite IoT device, whatever!

You will just need to give The 1-up-tor-onion-address.sh script:

The IP or Hostname of the service you’re sending to the Tor network.
The Port for the service to forward over the .onion address.
ONLY ONE SERVICE!!! –> tor_data/hidden_service/

This script is designed for demonstration and as such, there’s only one service designed into the script. You can always make multiple services on the same .onion address with different ports, or a new .onion address for every service. But today, only one service.

Sample Service

If you really dont have anything to use as a service, you can create a quick HTTP server with bash:

Creates an HTTP server using netcat
Server will respond on port 5432
Exit the netcat command with: ctrl + c

  
echo -e "HTTP/1.1 200 OK\r\nContent-Type: text/html\r\n\r\n<p>Works for me</p><p>$(date)</p>" | nc -l -p 5432

Add an & on the end to the command - to let it run in the background.

Exit from the background with: kill $(ps -ef | grep [5]432 | awk '{print $2}')

Torrc is important

The torrc file lets you define HiddenServiceDir and HiddenServicePort directives, these tell Tor where to store your service you’re sending to the Tor network’s keys and what ports to forward, making your .onion site accessible.

The 1-up-tor-onion-address.sh script uses two directories

File permissions are critical for Tor hidden services:

Directories need 700 permissions (drwx——)
Key files need 600 permissions (-rw——-)
The docker container will adjusts these permissions for you

The Tor user (not root) must own all these files inside the container

Browsers that find an onion service

Use Brave Browser
Use Tor Browser

Want to know more?

Want to know more about the 1-up-tor-onion-address.sh script? How about a breakdown of the script’s logic!

Take a look at the flow of the 1-up-tor-onion-address.sh script

┌───────────────────────┐
│    check_sudo()       │
│  - Verify privileges  │
└──────────┬────────────┘
           ▼
┌───────────────────────┐
│ create_directories()  │
│  - tor_config/        │
│  - tor_data/          │
└──────────┬────────────┘
           ▼
┌───────────────────────┐
│  set_permissions()    │
│  - 755 config         │
│  - 700 data           │
└──────────┬────────────┘
           ▼
┌───────────────────────┐
│get_network_settings() │
│  - Collect:           │
│    • HOST_IP          │
│    • HOST_PORT        │
│    • VIRTUAL_PORT     │
└──────────┬────────────┘
           ▼
┌───────────────────────┐
│setup_vanity_address() │
└──────────┬────────────┘
           ├────────────────────────────┐
           ▼                            ▼
┌───────────────────────┐      ┌───────────────────────┐
│  Generate New Address │      │  Use Existing Keys    │
│  - mkp224o Docker     │      │  - Validate dir       │
│  - vanity name input  │      │  - Verify key files   │
└──────────┬────────────┘      └──────────┬────────────┘
           ▼                              ▼
┌───────────────────────┐      ┌───────────────────────┐
│  Select From Generated│      │ Copy Existing Keys    │
│  - Display options    │      │  - hostname           │
│  - Validate selection │      │  - secret_key         │
└──────────┬────────────┘      └──────────┬────────────┘
           └────────────┬─────────────────┘
                        ▼
┌─────────────────────────────────────────┐
│      setup_hidden_service_dir()         │
│  - Create hidden_service/               │
│  - Set 700 permissions                  │
└──────────┬──────────────────────────────┘
           ▼
┌───────────────────────┐
│   create_torrc()      │
│  - HiddenServicePort  │
│  - DataDirectory      │
└──────────┬────────────┘
           ▼
┌───────────────────────┐
│  finalize_setup()     │
│  - Set file perms     │
│  - Display hostname   │
│  - Run instructions   │
└───────────────────────┘

Uninstall

How do you stop the Tor network now that you’ve let it onto your computer? You’ve let Skynet spread!!!

Go get a high-density polyethylene (HDPE) container. HDPE is a commonly used plastic for robust, leak-proof containers.
Fill this up to the brim with high octane gasoline.
Dowse your computer in as much gas as possible.
Now your computer will run faster, but the Tor network is still on it.
Should we:

uninstall the work we did
kill Tor with fire

To uninstall, delete the directory (tor-hidden-service-main) you created for this demonstration (you may have to use sudo) and run the following to remove the docker container:

  
 docker stop $(docker ps -a | grep tor-hidden-service | awk '{print $1}') 2>/dev/null && docker rm $(docker ps -a | grep tor-hidden-service | awk '{print $1}') 2>/dev/null

Tor network hidden service with vanity .onion address using Docker