An IP-Transparent Tor Hidden Service Connector

OnionCat creates a transparent IP layer on top of Tor's hidden services. It transmits any kind of IP-based data transparently through the Tor network on a location hidden basis. You can think of it as a point-to-multipoint VPN between hidden services.

OnionCat is a stand-alone application which runs in userland and is a connector between Tor and the local OS. Any protocol which is based on IP can be transmitted. Of course, UDP and TCP (and probably ICMP) are the most important ones but all other protocols can also be forwarded through it. OnionCat is based on IPv6 but the since version 0.1.9 also IPv4 packets are forwarded. In any case the local OS must support IPv6. See OnionCat and IPv4 for configuration of IPv4 transport. OnionCat now also supports TAP devices for bridging virtual machines and it supports IPv6 routing.


OnionCat's main purpose is to allow any user an easy use of hidden services and to allow hidden service providers to provide any type of service. Because OnionCat is IPv6-transparent the client applications may not be configured in any special way (SOCKSifying) because to every hidden service a unique IPv6 address is assigned by OnionCat. It creates an Internet within the Internet with the major advantage of being location hidden! This task is accomplished by resolving an IPv6 address to an .onion URL and then opening a connection to the desired hidden service. Basic Functionality

Most network services like e.g. DNS or SMTP depend on IP addresses and a fully functional name service (DNS). The addressing scheme within Tor is based on .onion URLs (e.g. 5wyqrzbvrdsumnok.onion) which obviously are not IP addresses. Tor connects to hidden services by resolving the special .onion URLs received via SOCKS4a connections. Of course, .onion URLs are not resolved on legacy Internet, and if so it would still not be possibly to send someone e.g. an email because it cannot be resolved to an IP address. There comes OnionCat into play.

  1. We map every unique .onion URL to a unique IPv6 address in deterministic reversible manner. Tor's .onion URLs are an 80 bit long part of the hash of the hidden service's public key. IPv6 addresses have 128 bits so we can choose an 48 bit long prefix and directly put the 80 bit partial hash into the remaining bits of the IPv6 address. We generated the static IPv6 prefix FD87:D87E:EB43::/48 according to RFC4193 ("Unique Local IPv6 Unicast Addresses"). Now we can map e.g. 5wyqrzbvrdsumnok.onion directly to FD87:D87E:EB43:edb1:8e4:3588:e546:35ca.
  2. We create a local TUN device and assign the corresponing IPv6 address to it. On the "other end" of the TUN device OnionCat receives IPv6 packets which a forwarded by the kernel based on the kernel routing table to the TUN device.
  3. OnionCat parses the IPv6 header, reads the destination IPv6 address and converts it back into an .onion URL.
  4. OnionCat opens a SOCKS4a connection to the Tor proxy and requests a connection to the appropriate .onion URL.
  5. After the connection is successfully opened it transparently forwards all IPv6 packets for that specific hidden service through this SOCKS connection. Of course, many connections to different hidden services can be maintained at the same time.
  6. On the other end of the connetion OnionCat must run also. It receives the hidden service connection on a listening TCP socket and forwards all packets to the TUN device, i.e. to the kernel which pushes the packets to the appropriate applications as it always does when receiving packets on devices. This implies that every Tor proxy running OnionCat must also be configured to be a hidden service.

Why Using OnionCat?

OnionCat creates the major advantage of using Tor's hidden services like usual IP hosts on the Internet. You can provide and use any service you could provide on the Internet, SMTP, DNS, HTTP, Torrent, whatever.

Last modified 12 years ago Last modified on Jan 6, 2009, 8:48:45 PM
Note: See TracWiki for help on using the wiki.