Tor

The high-level interface to the Tor implementation. Basic usage, for using Tor as a mechanism for connecting to Internet services anonymously:

main :: IO ()
main =
  do tor <- startTor systemNetworkStack defaultTorOptions
     addrs <- torResolveName tor "hostname.com"
     case addrs of
       [] -> ...
       ((x, _):_) ->
         do sock <- torConnect tor x 80
            torWrite sock ...
            resp <- torRead sock 1024
            ...

HaLVM users should initialize a HaNS network stack, and use that instead of systemNetworkStack, above.

Setup and initialization

data Tor

A handle to the current Tor system state.

startTor :: HasBackend s => TorNetworkStack ls s -> TorOptions -> IO Tor

Start up the underlying Tor system, given a network stack to operate in and some setup options.

Options

module Tor.Options

Functions for Tor entrance nodes

data TorAddress

An abstract data type representing either an address or an address processing error, used in a variety of Tor protocols.

Constructors

Hostname String

A hostname, as usual.

IP4 String

An IP4 address, as 'a.b.c.d', in decimal

IP6 String

An IP6 adddress, as '[...]', in usual hex form

TransientError String

A transient error occurred when performing some action. Try again.

NontransientError String

A non-transient error occurred when performing some action. Do not try again, or you will annoy the dragon.

Instances

Eq TorAddress

Ord TorAddress

Show TorAddress

data RelayEndReason

A reason that someone might want to end a relay.

Constructors

ReasonMisc

ReasonResolveFailed

ReasonConnectionRefused

ReasonExitPolicy TorAddress Word32

ReasonDestroyed

ReasonDone

ReasonTimeout

ReasonNoRoute

ReasonHibernating

ReasonInternal

ReasonResourceLimit

ReasonConnectionReset

ReasonTorProtocol

ReasonNotDirectory

Instances

Eq RelayEndReason

Show RelayEndReason

Exception RelayEndReason

torResolveName :: Tor -> HostName -> IO [(TorAddress, Word32)]

Resolve the given host name, anonymously. This routine will create a new circuit unless torMaxCircuits has been reached, at which point it will re-use an existing circuit.

data TorSocket

A socket for communicating with a server, anonymously, via Tor.

torConnect :: Tor -> TorAddress -> Word16 -> IO TorSocket

Connect to the given address via Tor. The TorAddress should be one of the IP4 or IP6 variants, rather than a hostname or an error. The result will be the built circuit. This will throw exceptions if failures occur during the building process.

torClose :: TorSocket -> RelayEndReason -> IO ()

Close a Tor socket. This will notify the other end of the connection that you are done, so you should be sure you really don't need to do any more reading before calling this. At this point, this implementation does not support a half-closed option.

torWrite :: TorSocket -> ByteString -> IO ()

Write the given ByteString to the given Tor socket. Blocks until the entire ByteString has been written out to the network. Will throw an error if the socket has been closed.

torRead :: TorSocket -> Int -> IO ByteString

Read the given number of bytes from the socket. Blocks until either the entire buffer has been read or the socket closes for some reason. Will throw an error if the socket was closed before the read starts.