tor-ctrl-onion: explore onion services `ADD_ONION` `DEL_ONION`

[nyxnor]

This create ephemeral onion services that never touch disk. It would be very helpful to facilitate the commands to be used in short.

[nyxnor]

this is worth a script tor-ctrl-onion. Much to learn.

Check SETEVENTS HS_DESC and create a service, it will appear in the line HS_DESC CREATED HOSTNAMEwithoutdotonion

[nyxnor]

It is possible to specify a lot of parameters, which can be done with tor-ctrl, but tor-ctrl-onion will default to the most secure, leaving the user choic for port and client auth.

  The syntax is:

    "ADD_ONION" SP KeyType ":" KeyBlob
            [SP "Flags=" Flag *("," Flag)]
            [SP "MaxStreams=" NumStreams]
            1*(SP "Port=" VirtPort ["," Target])
            *(SP "ClientAuth=" ClientName [":" ClientBlob]) CRLF
            *(SP "ClientAuthV3=" V3Key) CRLF

This can be default tor-ctrl ADD_ONION NEW:BEST

• KeyType="NEW" / ; The server should generate a key of algorithm KeyBlob
• KeyBlob="BEST" / ; The server should generate a key using the "best" supported algorithm (KeyType == "NEW"). [As of 0.4.2.3-alpha, ED25519-V3 is used]

Port is specified as VirtPort ["," Target], so user just needs to use at least one virtual port, or if none, default to 80? Port=80. The target if empty is mapped to the same port on host 127.0.0.1 TCP, as explained on the tor manual.

ClientAuthV3 should be filled manually? If you want to generate a key pair:

openssl genpkey -algorithm x25519 -out /tmp/k1.prv.pem
grep -v " PRIVATE KEY" /tmp/k1.prv.pem | base64pem -d | tail -c 32 | base32 | sed "s/=//g" > /tmp/k1.prv.key
openssl pkey -in /tmp/k1.prv.pem -pubout | grep -v " PUBLIC KEY" | base64pem -d | tail -c 32 | base32 | sed "s/=//g" > /tmp/k1.pub.key
client_pub_key=$(cat /tmp/k1.pub.key)
client_priv_key=$(cat /tmp/k1.prv.key)

ClientAuthV3=base32encodedclientpubkey

As we close the control connection by sending QUIT, unless -w is specified, we should detach the onion to not terminate when the connection closes:

Flags=Detach.

Result tor-ctrl ADD_ONION NEW:BEST Port=80 ClientAuthV3=base32encodedclientpubkey Flags=Detach

[nyxnor]

Flags:

• Detach - reloading (HUP) tor does not kill the detached onion, but restarting (SHUTDOW=INT or HALT=TERM) does.
• DiscardPK - private key not printed and therefore impossible to recreate key pair, this is THE ephemeral service

What onionshare-cli does with the --permanent flag is to save the contents of the private key to a json formatted file.

Ephemeral

Once created the new Onion Service will remain active until either:

• the Onion Service is removed via "DEL_ONION",
• the server terminates,
• the control connection that originated the "ADD_ONION" command is closed. It is possible to override disabling the Onion Service on control connection close by specifying the "Detach" flag.

1. DEL_ONION Needs to use the onion service id to delete it if intended
2. The server terminates if receiving an INT or TERM signal, which happens when the tor daemon stops or restart
3. This happens if not run with the tor-crl -w wait flag to not close the connection of if using the controller's flag Detach

General

Create a service:

tor-ctrl ADD_ONION NEW:BEST Port=80 Flags=Detach

Create an ephemeral service:

tor-ctrl ADD_ONION NEW:BEST Port=80 Flags=Detach,DiscardPK

List detached services:

tor-ctrl GETINFO onions/detached

Service ID is printed without .onion. 250-ServiceID=somehostname Private key is printed on the same format that would be used to restore it 250-PrivateKey=ED25519-V3:someprivatekey so to restore, the user would use:

tor-ctrl ADD_ONION ED25519-V3:someprivatekey Port=80 Flags=Detach

[nyxnor]

## Create service listening on port 80 by default
## tor-ctrl-onion -A
#tor-ctrl ADD_ONION NEW:BEST Port=80

## Create service listening on port 8080 (detached)
## tor-ctrl-onion -A -l 8080
#tor-ctrl ADD_ONION NEW:BEST Port=8080

## Create service and detach from controller
## tor-ctrl-onion -A -e
#tor-ctrl ADD_ONION NEW:BEST Port=80

## Create service and use client authorization
## tor-ctrl-onion -A -u clientpubkeybase32
#tor-ctrl ADD_ONION NEW:BEST Port=80 Flags=V3Auth ClientAuthV3=clientpubkeybase32

## Delete service
## tor-ctrl-onion -D hostnamestringwithoutdotonion
#tor-ctrl DEL_ONION hostnamestringwithoutdotonion

## List detached services
## tor-ctrl-onion -L
#tor-ctrl GETINFO onions/detached

usage(){
  printf '%s\n' "usage: ${me} [-mzh] [-s socket] [-p password]

  -s [socket]    tor's control socket
                 notice: tcp: [addr:]port: 9051, 127.0.0.1:9051
                 notice: unix: [unix:]path: /run/tor/control, unix:/run/tor/control
                 default: 9051

  -p [pwd]       use password [pwd] instead of Tor's control_auth_cookie
                 default: not used

  -A             add onion
                 default: not set

  -l [virtport,[target]]
                 notice: virtport: The virtual TCP Port for the Onion Service
                 notice: target: The (optional) target for the given VirtPort
                 default: virtport: 80
                 default: target: 127.0.0.1:80

  -u [client_pub_key]
                 client's base32-encoded ed25519 public key

  -e             detach onion service from controller
                 notice: the service will remain active after the control connection closes
                 default: not set

  -i             discard service private key
                 notice: this is irreversible, it will not be possible to recreate the same hostname

  -D [service]   delete onion
                 notice: service is the hostname without '.onion'

  -L             A newline-separated list of the detached services created

  -m             machine mode
                 notice: script informational and warning messages won't be printed to stdout
                 default: not set

  -h             print this help message
"
  exit 1
}

[nyxnor]

Create permanent HiddenService with only the Private key received from ADD_ONION

Convert the private key received from ADD_ONION command to a permanent HiddenService data configuration:

Warning: this will replace the file hs_ed25519_secret_key if running inside a HiddenServiceDir.

echo "ED25519-V3:YOUR_SERVICE_PRIVATE_KEY" > v3_onion_private_key
dd if=v3_onion_private_key bs=1 skip=11 | base64 -d | dd of=hs_ed25519_secret_key bs=1 seek=32

If you just want to test if the output would be the same, do the conversion of an existent service (backup your keys):

echo "ED25519-V3:$(dd if=hs_ed25519_secret_key bs=1 skip=32 | base64 | tr -d "\n")" > v3_onion_private_key
dd if=v3_onion_private_key bs=1 skip=11 | base64 -d | dd of=hs_ed25519_secret_key bs=1 seek=32

So the only necessary program is a base64 converter, available on Debian by installing basez, and on OpenBSD as base64, not regarding dd which is posix, see man.

[nyxnor]

all possible options were implemented, except one for now which is MaxStreams=integer combined with Flags=MaxStreamsCloseCircuit, but this can be done also.

also haven't implemented NonAnonymous

Tor instances can either be in anonymous hidden service mode, or non-anonymous single onion service mode. All hidden services on the same tor instance have the same anonymity. To guard against unexpected loss of anonymity, Tor checks that the ADD_ONION "NonAnonymous" flag matches the current hidden service anonymity mode. The hidden service anonymity mode is configured using the Tor options HiddenServiceSingleHopMode and HiddenServiceNonAnonymousMode. If both these options are 1, the "NonAnonymous" flag must be provided to ADD_ONION. If both these options are 0 (the Tor default), the flag must NOT be provided.

[nyxnor]

everything is complete

[nyxnor]

Why ephemeral onion services that can not be recreated later by using the flag DiscardPK? Why not just have the key saved to a file, written to disk? Why not a torrc configuration?

The tor client connected to an onion service is the most anonymous as one can be with Tor. Clients are ephemeral, connection is lost, they are not logged in an account, the circuit changes, he is ephemeral by default.

The clients needs fixed onion services to be able to connect to multiple times, even after days. This means the server needs to constantly be online, leaving a trace on the network if internet or electricity is cut on that part of the server location if there is no generator, power source, or other source of internet.

The more time the service is available, the less "hidden" it becomes. Watch this video http://c7hqkpkpemu6e7emz5b4vyz7idjgdvgaaa3dyimmeojqbgpea3xqjoid.onion/watch?v=PPVTl8qHKsE - time 30:14