Onionservice – Manage Your Onion Services Via CLI Or TUI On Unix-like Operating System With A POSIX Compliant Shell

Echosystem

Onion Services are the Hidden Services of Tor which use onion routing as its base for stablishing private connections. They offer:

• Location hiding – IP address aren’t used, so your location is protected.
• End-to-end authentication – Only the owner of the hs secret key can host the same onion, so no impersonation is possible, no man-in-the-middle.
• End-to-end encryption – Traffic is encrypted from the client to the onion host, no need to trust CAs which are a fallible model.
• NAT punching – On a firewalled network, no need to open ports

For a deeper understanding, read the Rendezvous Specification and Tor design.

Onion Routing tries to solve most of these problems but it is still centralized by the Directory Authorities, and referencing Matt Traudt’s blog post: replacing it for something more distributed is not a trivial task.

On the Tor echosystem, from TPO metrics, comparing only Free and Open Source Operating Systems, Linux dominates on relays by platform and Tor Browser downloads by platform over BSD. Data regarding which operating system the onion service operator can not be easily acquired for obvious reasons. That was on the network level, but know on the user system, even if one chooses a Free and Open Source Operating System, GNU/Linux dominates a big share over *BSD, having a huge impact on the main software used for the kernel (Linux), shell (bash), service manager (systemd).

Goal

The goal of this project is:

• facilitates onion service management, from activating a service to adding client authorization to it, giving the full capabilities of editing files manually would have but with less tipying.
• show the that managing the onion service is much more than just using a webserver with your pages.
• distribution, from the source code level (FOSS) to the effect it takes when it allows anyone to run the code on any operating system, shell or service manager. Mitigation from a single point of failure

Descentralization from a single point of failure:

• Kernel from predominant Linux to also BSD.
• Shell from predominant bash to also any POSIX shell such as ksh, (y,d)ash and zsh (emulating sh).
• Service manager from predominant systemd to also OpenRC.

Editing the tor configuration file (torrc) is not difficult, but automation solves problem of misconfiguration and having:

• less time spent
• complete uniformity
• graphical interface to help newbies

Features

• Enable service – Create directory if not existent (HiddenServiceDir), select onion version (HiddenServiceVersion), custom socket type being unix or tcp, up to two virtual ports, up to two targets (HiddenServicePort).
• Disable service – Remove service configuration from the torrc, the service will not be acessible anymore, but you can enable it again any time you want. Optionally purge the service, deleting its configuration and directory, which will delete its keys permanently.
• Renew service address – Focused on private onion services, if you ever leak its address, you can change its hostname, beware all of your authorized clients will be disconnected and the service keys will be permanently deleted.
• Credentials – Show hostname, clients, torrc block, qrencoded hostname.
• Onion authentication – For v3 onion services only. This depends on client and server side configuration and works with a key pair, the client holds the private key part either generate by him (more safe) or given by the service operator and the onion service operator holds the public part. If any if
  • Server – Generate key pair or add public part, list client names and their public keys from <HiddenServiceDir>/authorized_clients/<client>.auth. If any client is configured, the service will not be acessible without authentication.
  • Client – Generate key pair or add public part, list your <ClientOnionAuthDir>/<SOME_ONION>.auth_private.
• Onion-Location – For public onion services You can redirect your plainnet users to your onion service with this guide for nginx, apache2 and html header attributes.
• Backup – Better be safe.
  • Create – Backup of your torrc lines containing hidden service configuration, all of your directories of HiddenServiceDir and ClientOnionAuthDir. Guide to export the backup to a remote host with scp.
  • Integrate – Integrate hidden serivces lines configuration from torrc and the directories HiddenServiceDir and ClientOnionAuthDir to your current system. This option should be used after creating a backup and importing to the current host. Guide to import backup to the current host with scp.
• OpSec – Operation Security
  • Vanguards – This addon protects against guard discovery and related traffic analysis attacks. A guard discovery attack enables an adversary to determine the guard node(s) that are in use by a Tor client and/or Tor onion service. Once the guard node is known, traffic analysis attacks that can deanonymize an onion service (or onion service user) become easier.
  • Unix socket – Support for enabling an onion service over unix socket to avoid localhost bypasses.
• Web server – Serve files with your hidden service using Nginx or Apache2 web server.
• Usability – There are two dialog boxes compatible with the project, dialog and whiptail.
• Bulk – Some commands can be bulked with all-clients, all-services, [SERV1,SERV2,...] and [CLIENT1,CLIENT2,...], the command will loop the variables and apply the combination.
• Optional – Some commands are optional so less typing. Also they may behave differently depending on how much information was given to be executed and that is expected. They are specified inside <> (e.g. <VIRTPORT2>)
• Fool-proof – The script tries its best to filter invalid commands and incorrect syntax. The commands are not difficult but at first sight may scare you. Don’t worry, if it is invalid, it won’t run to avoid tor daemon failing to reload because of invalid configuration. If an invalid command runs, please open an issue.

Instructions

Setup

Three easy steps to fully this project:

Clone the repository

git clone https://github.com/nyxnor/onionservice.git
cd onionservice

Set custom vars

Edit the required variables to fit your system inside .onionrc following the same format from the already defined variables. Note that no variable that refers to a folder end with a trailing “/”. Keep it that way, else it will break. The packages can have different names depending on the operating system, modify accordingly.

Set the default editor of your choice, else it will always fallback to Vi. This is an example using nano, but could be any other editor:

printf "nexport EDITOR="nano"n" >> ~/."${SHELL##*/}"rc && . ~/."${SHELL##*/}"rc

Open the mentioned configuration file:

"${EDITOR:-vi}" .onionrc

## [ EDIT REQUIRED ] (IF NOT DEBIAN)
tor_user="debian-tor" ## [debian-tor|tor]
tor_service="[email protected]" ## [[email protected]|tor.service]
pkg_mngr_install="sudo apt install -y" ## always use the 'yes' flag to be non interactive
web_server="nginx" ## [nginx|apache2]
dialog_box="dialog" ## [dialog|whiptail]
requirements="tor grep sed openssl basez git qrencode pandoc lynx gzip tar python3-stem ${dialog_box} ${web_server}" ## search pkg name for your OS

Edit with sed (use insert option -> sed -i''):

sed "s|tor_user=.*|tor_user="tor"|" .onionrc

Setup the enviroment

Determine the enviromental variable ${ONIONSERVICE_PWD} and add the directory to ${PATH}.

• add the enviromental variable to find the repo-> exporting this variable possibilitate calling it from inside shell scripts.
• add directory to path -> call the scripts from any directory as if they were commands (without indicating the path to them or prepending with the shell name).

For this, you have two options:

• Easy: run from inside the cloned repository and it will use the same path as in${PWD}:

./setup/setup.sh

• Development: set the variable manually using the absolute path without trailing “/” at the end. Favorable for integrating into other projects. Run from any directory (need to specify the path)

./setup/setup.sh -s -p /PATH/TO/ONIONSERVICE/REPO && . ~/."${SHELL##*/}"rc

Usage

The repo is now in your $PATH, if you have setup the environment as described above. This means you can call the scripts as if they were any other command.

Scripts

There are some ways to call the scripts, evaluate the advantages and disadvantages:

Documentation

Take a loot at the documentation inside docs folder. Read:

• any markdown file formatted on the shell:

ls docs/*.md
pandoc "${ONIONSERVICE_PWD}"/docs/CONTRIBUTING.md | lynx -stdin

• the CLI manual:

man onionservice-cli

Portability

Shells

Full compatibility with any POSIX compliant shells: dash, bash, ksh, mksh, yash, ash

The default POSIX shell of your unix-like operating system may vary depending on your system (FreeBSD and NetBSD uses ash, OpenBSD uses ksh, Debian uses dash), but it has a symbolic link leading to it on /usr/bin/sh and/or /bin/sh.

Tweak to be compatible with non-POSIX compliant shells::

• Z SHell (zsh) -> zsh --emulate sh -c onionservice-tui

Operating systems

Works unix-like operating systems, tested by the maintainer mostly on GNU/Linux Debian 11. Work is being done for *bsd systems, sed is using this trick.

Service managers

Currently only systemd is available, planning on implementing SysV, Runit, OpenRC.

Requirements

• General:

  • Unix-like system.
  • any POSIX shells: dash 0.5.4+, bash 2.03+, ksh 88+, mksh R28+, zsh 3.1.9+, yash 2.29+, busybox ash 1.1.3+ etc.
  • systemd (for tor and vanguards control) – for now, different services managers is a goal
  • sudo privileges.
  • blank lines between Hidden Services blocks in the torrc.
  • HiddenServiceDir different path than DataDir – DataDir/services.
  • Path for folders variables must not contain trainling “/” at the end of the variables on .onionrc (Incorrect: ~/onionservice/, Correct: ~/onionservice).

• Packages:

  • tor >= 0.3.5
  • grep >=2.0
  • sed >= 2.0
  • python3-stem >=1.8.0
  • openssl >= 1.1
  • basez >= 1.6.2
  • git >= 2.0
  • qrencode >= 4.1.1
  • pandoc
  • lynx
  • tar
  • gzip

The packages are downloaded when setting up the environment with setup.sh, the packages that are requirements are specified on .onionrc. The absolute minimum you can go to is tor grep sed, and you will be limited to enable, disable and renew services.

Credits

Inspirations

These are projects that inspires OnionService development, each with their own unique characteristic.

• OnionShare CLI possibilitates ephemeral onion services that never touch the disk and can be run on Tails or Whonix easily. It provides onion authentication, focusing on running servers to send and receive files, chat and host a static website. OnionService evolved by watching the sharing capabilities of OnionShare and converting them to shellscript.

• RaspiBlitz provides a ton of bitcoin related services that can be run over tor, so onion services is the choice to access your node from outside LAN. OnionService started by forking Blitz script to remove hardcoded paths.

• TorBox is an easy to use, anonymizing router that creates a separate WiFi that routes the encrypted network data over the Tor network. It also helps configuring bridges and other countermeasures to bypass censorship. OnionService aims to help people on surveillance countries to communicate privately.