Netlib TorNetLayer

Abstract: This page describes the TorNetLayer implementation and its Java packages.

Introduction

The TorNetLayer implementation of [Netlib NetLayer] tunnels TCP/IP network traffic through the [Tor] anonymity network. This is used to anonymize the client (IP address). To find out more read here: [Tor]

Get a TorNetLayer Instance

To start TorNetLayer you have to retrieve an instance

    NetLayer torNetLayer = NetFactory.getInstance().getNetLayerById(NetLayerIDs.TOR);

or you explicitely create a new instance

    NetLayer torNetLayer = new TorNetLayer(...);

TorNetLayer Startup

The startup needs some time depending on your network connection speed and some random parameters. In some situations this takes up to 5 minutes.

All state changes will be logged in INFO level by the TorNetLayer. The following states are currently implemented:

• New or clean (0%)
• Consensus document (Tor router overview) will be loaded (10%)
• Router descriptors (Tor router details) will be loaded (30%)
• Initial circuits to Tor exit nodes will be established (60%)
• Ready for use (100%)

It is possible to retrieve the current state from the API:

    NetLayerStatus status = torNetLayer.getStatus();

Or you simply wait until the startup is finished by:

    torNetLayer.waitUntilReady();

Using TorNetLayer

You can use the TorNetLayer (class org.silvertunnel_ng.netlib.layer.tor.TorNetLayer) in the same way as every other [NetLayer]: see the [Netlib Tools] documentation for details.

Special Hostnames

To address a server in the Internet, IP addresses or hostnames are used with TorNetLayer (as with the most other NetLayers). Some special hostnames are recognized by the TorNetLayer to trigger special features:

• []real-hostname.[]tor-exit-node-digest.exit:

  • this is used to address the real-hostname, but it enforces TorNetLayer to use the specified tor-exit-node-digest as exit node instead of a randomly selected exit node (the IP address of the used exit node becomes visible to the server)
  • tor-exit-node-digest is the hex-encoded digest of that node's public key
  • the syntax []tor-exit-node-digest.exit (without leading real hostname) and the usage of the nickname instead of digest are intentionally not supported by TorNetLayer, even if these variants are part of the address-spec.txt Tor specification
  • example URL with such hostname
    • accessing http://httptest.silvertunnel.org/httptest/bigtest.jsp with exit node chaoscomputerclub10 (which has hex-encoded digest 11A0239FC6668705F68842811318B669C636F86E):
      http://httptest.silvertunnel.org.11A0239FC6668705F68842811318B669C636F86E.exit/httptest/bigtest.jsp

• []hidden-service-digest.onion:

  • the digest is the first eighty bits of a SHA1 hash of the identity key for a hidden service, encoded in base32
  • example URL with such hostname:
    • hidden service of the Tor project:
      http://duskgytldkxiuqc6.onion/

Clearing the state of TorNetLayer

Sometimes you want to enforce get a new Tor exit node (i.e. a fresh identity) from TorNetLayer. To enforce this just call:

    torNetLayer.clear();

Tor Hidden Services

Using the Tor network you can publish a TCP based server (e.g. a HTTP web server, SSH server, ...) without revealing your IP address to its users. This is called hidden service. Hidden services are identified by a special hostname that ends with .onion. Example hidden service of the Tor project: http://duskgytldkxiuqc6.onion/

Interesting detail: because you don't use any public address, you can run a hidden service from behind your firewall or NAT.

More about hidden services: Tor: Hidden Service Protocol

Client-Side Access to a Hidden Service

Client-side access is quite easy with TorNetLayer: just do the same to access a hidden service as you would do to access a normal service. The TorNetLayer recognizes the hidden service by the special .onion domain name and handles such requests accordingly.

Server-side Publishing of a Hidden Service

Server-side access is a bit tricky - you should understand the Tor: Hidden Service Protocol concepts.

First, to publish a hidden service you need a private+public key that identifies the hidden service. Such a key pair is usually stored in a directory with two files:

/dir/to/the/hidden/service/
    hostname             # file that contains the public .onion hostname of the hidden service - the client needs this information
    private_key          # file that contains the private hidden service key in PEM ASCII format - this is the secret of the server

These files are compatible with the same files of the original Tor software, i.e. you can exchange such a directory between original Tor and silvertunnel.org Netlib. In Java with TorNetLayer, we store the information of such a directory in an object of class TorHiddenServicePrivateNetAddress. To create, to read or to write such a directory you can use the methods of TorNetLayerUtil.

If you have the key, you can create/publish a hidden service: read [Netlib Howto Publish a Tor Hidden Service] to find out the details.

Attention: The current server-side implementation for hidden services is still very new - please report bugs to our Forum.

---

Top: [Netlib], Next: [Netlib TorNetLayer Implementation Details] (can be skipped), [Netlib NetAddressNameService]