This module provides the main interface for establishing secure and anonymous connections with other hosts on the interface using the Tor project. For more information about the Tor network, see: torproject.org

This module is a (partial) implementation of the Tor control protocol. Tor is an internet anonimization network. Whereas historically, Tor is primarily intended for privately browsing the world wide web, the service also supports application oriented P2P communication, to implement communication between applications.

The general idea of the Tor control interface to Tor is that you establish a master connection with the Tor control port, and create new, short-lived connections with the Tor bridge for the communication with the individual peers.

Connect through Tor with explicit port

Connect through Tor on using a specified SOCKS port. Note that you do not need to authorize with the Tor control port for this functionality.

  main = connect 9050 constructDestination worker

  where
    constructDestination =
      SocksAddress (SocksT.SocksAddrDomainName (BS8.pack "www.google.com")) 80

    worker sock =
      -- Now you may use sock to communicate with the remote.
      return ()

Connect through Tor using control port

Connect through Tor and derive the SOCKS port from the Tor configuration. This function will query the Tor control service to find out which SOCKS port the Tor daemon listens at.

  main = withSession withinSession

  where
    constructDestination =
      SocksAddress (SocksT.SocksAddrDomainName (BS8.pack "2a3b4c.onion")) 80

    withinSession :: Socket -> IO ()
    withinSession sock = do
      connect' sock constructDestination worker

    worker sock =
      -- Now you may use sock to communicate with the remote.
      return ()

Mapping

Create a new hidden service, and map remote port 80 to local port 8080.

  main = withSession withinSession

  where
    withinSession :: Socket -> IO ()
    withinSession sock = do
      onion <- mapOnion sock 80 8080
      -- At this point, onion contains the base32 representation of
      -- our hidden service, without the trailing '.onion' part.
      --
      -- Remember that, once we leave this function, the connection with
      -- the Tor control service will be lost and any mappings will be
      -- cleaned up.

Server

Convenience function which creates a hidden service on port 80 that is mapped to a server we create on the fly. Note that because we are mapping the hidden service's port 1:1 with our local port, port 80 must still be available.

  main = withSession withinSession

  where
    withinSession :: Socket -> IO ()
    withinSession sock = do
      onion <- accept sock 80 worker
      -- At this point, onion contains the base32 representation of
      -- our hidden service, without the trailing '.onion' part, and any
      -- incoming connections will be redirected to our worker function.
      --
      -- Once again, when we leave this function, all registered mappings
      -- will be lost.

    worker sock = do
      -- Now you may use sock to communicate with the remote.
      return ()