Tor.Circuit

Low-level routines for generating, extending, and destroying circuits. We strongly recommend not using this module unless you have a very good reason. You should probably just use the high-level Tor module or the CircuitManager module instead.

High-level type for Tor circuits that originate at the current

data OriginatedCircuit

A circuit that originates with this node

createCircuit :: MVar TorRNG -> TorOptions -> TorLink -> RouterDesc -> Word32 -> IO OriginatedCircuit

Create a new one-hop circuit across the given link. The router description given must be the router description for the given link, or the handshake will fail. The Word32 argument is the circuit id to use. The result is the new, one-hop circuit or a thrown exception. If you care about anonymity, you should extend this circuit a few times before trying to make any connections.

destroyCircuit :: OriginatedCircuit -> DestroyReason -> IO ()

Destroy a circuit, and all the streams and computations running through it.

extendCircuit :: OriginatedCircuit -> RouterDesc -> IO ()

Extend the extant circuit to the given router. This is purely side-effecting, although it may thrw an error if an error occurs during the extension process.

High-level type and operations on circuits that are passing through

data TransverseCircuit s

A handle for a circuit that orginated elsewhere, and is either passing through or exiting at this node.

acceptCircuit :: HasBackend s => TorNetworkStack ls s -> TorOptions -> RouterDesc -> Credentials -> RouterDB -> TorLink -> MVar TorRNG -> IO (Maybe (TransverseCircuit s))

Accept a circuit from someone who just connected to us.

destroyTransverse :: TorNetworkStack ls s -> TransverseCircuit s -> DestroyReason -> IO ()

Destroy a circuit that is transiting us.

Name resolution support.

resolveName :: OriginatedCircuit -> String -> IO [(TorAddress, Word32)]

Resolve the given hostname, anonymously. The result is a list of addresses associated with that hostname, and the TTL for those values.

Tor sockets.

data TorSocket

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

Constructors

TorSocket

Fields

tsCircuit :: OriginatedCircuit

tsStreamId :: Word16

tsState :: MVar (Maybe RelayEndReason)

tsReadWindow :: MVar Int

tsInChan :: Chan (Either RelayEndReason ByteString)

tsLeftover :: MVar ByteString

connectToHost :: OriginatedCircuit -> TorAddress -> Word16 -> IO TorSocket

Connect to the given address and port through the given circuit. The result is a connection that can be used to read, write, and close the connection. (This is equivalent to calling connectToHost' with True, True, and False for the extra arguments.)

connectToHost' :: OriginatedCircuit -> TorAddress -> Word16 -> Bool -> Bool -> Bool -> IO TorSocket

Connect to the given address and port through the given circuit. The result is a connection that can be used to read, write, and close the connection. The booleans determine if an IPv4 connection is OK, an IPv6 connection is OK, and whether IPv6 is preferred, respectively.

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.

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.

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.

Miscellaneous routines, mostly exported for testing.

type CryptoData = (EncryptionState, Context SHA1)

A shorthand for the pair of encryption and hashing state used by Tor. Note, because it's easy to forget, that the encryption state is updated on every cell that passes through the system, but the hashing state is only updated on cells that are destined for us.

type Curve25519Pair = (PublicKey, SecretKey)

A handy shorthand for a public and private Curve25519 pair.

data EncryptionState

The current state of an encryptor.

Instances

Eq EncryptionState

Show EncryptionState

startTAPHandshake :: RouterDesc -> TorRNG -> (TorRNG, (PrivateNumber, ByteString))

Perform the first step in a TAP handshake, generating a private value and the public cell body to send to the other side.

advanceTAPHandshake :: PrivateKey -> Word32 -> ByteString -> TorRNG -> (TorRNG, (TorCell, CryptoData, CryptoData))

Given our information and the public value provided by the other side, compute both the shared secret and our public value to send back to the originator.

completeTAPHandshake :: PrivateNumber -> ByteString -> Either String (CryptoData, CryptoData)

Given the private number generated before and the server's response, generate the shared secret and the appropriate crypto data.

startNTorHandshake :: RouterDesc -> TorRNG -> (TorRNG, Maybe (Curve25519Pair, ByteString))

Start an NTor handshake by generating a local Curve25519 pair and a public value to send to the server.

advanceNTorHandshake :: RouterDesc -> SecretKey -> Word32 -> ByteString -> TorRNG -> (TorRNG, Either String (TorCell, CryptoData, CryptoData))

As a server, accept the client's public value, generate the shared encryption state from that value, and generate a response to the client they can use to generate the same values.

completeNTorHandshake :: RouterDesc -> Curve25519Pair -> ByteString -> Either String (CryptoData, CryptoData)

Complete the NTor handhsake using the server's public value.

generate25519 :: MonadRandom m => m Curve25519Pair

Generate a new Curve25519 key pair.