circuit

Details

Circuits are channels through the Tor network through which data is written and received.

Circuits have a few jobs:

• Get a valid path of relays through the Tor network (circuits received some path_constraints, but it’s up to each circuit to build it’s own path)
• Build the path by extending the circuit one hop at a time
• Derive shared key material for each node on the path
• Encrypt outgoing cells and decrypt incoming cells
• Process incoming control cells to manage circuit state
• Initiate new stream connections
• Process incoming data cells and pass data to associated streams
• Do some flow-control management
• Handle different ways of circuit tear-down depending on the current state and why a circuit is being torn down

class circuit.circuit.Circuit(cid, path_constraints)

Bases: object

writeData(data, stream_id)

Put a tuple of (data, stream_id) on this circuit’s write_queue.

Called by stream’s when they want to write data to this circuit.

Warning

writeData() requires that data can fit in a single relay cell. The caller should take care to split data into properly sized chunks.

Parameters:

• data (str) – data string to write to this circuit
• stream_id (int) – id of the stream writing this data

recvCell(cell)

Put the incoming cell on this circuit’s read_queue to be processed.

Called be a connection when it receives a cell addressed to this circuit.

Parameters:cell (cell) – incoming cell that was received from the network

writeCell(cell)

Write a cell to this circuit’s connection.

Parameters:cell (cell) – cell to write to this circuit’s connection

canHandleRequest(request)

Return True if this circuit can (probably/possibly) handle the request.

If this circuit is pending we may not have a relay exit relay whose exit policy we can check, so make a guess and return True if the request is of the same type as this circuit. Always return True if this request is a host type request (this is probably wrong). If the circuit is open and we do have an exit policy to check, then return whether or not this circuit’s exit relay’s exit policy claims to support this request.

Parameters:request (oppy.util.exitrequest.ExitRequest) – the request to check if this circuit can handle Returns:bool True if this circuit thinks it can handle the request, False otherwise

unregisterStream(stream)

Unregister stream from this circuit.

Remove the stream from this circuit’s stream map and send a RelayEndCell. If the number of streams on this circuit drops to zero, check with the circuit manager to see if this circuit should be destroyed. If so, tear down the circuit.

Parameters:stream (oppy.stream.stream.Stream) – stream to unregister

initiateStream(stream)

Initiate a new stream by sending a RelayBeginCell.

Create the begin cell, encrypt it, and immediately write it to this circuit’s connection.

Parameters:stream (oppy.stream.stream.Stream) – stream on behalf of which we’re sending a RelayBeginCell

registerStream(stream)

Register the new stream on this circuit.

Set the stream’s stream_id and add it to this circuit’s stream map.

Parameters:stream (oppy.stream.stream.Stream) – stream to add to this circuit

sendStreamSendMe(stream_id)

Send a stream-level RelaySendMe cell with its stream_id equal to stream_id.

Construct the send me cell, encrypt it, and immediately write it to this circuit’s connection.

Parameters:stream_id (int) – stream_id to use in the RelaySendMeCell

destroyCircuitProtocolViolation(cell)

Destroy a circuit because the Tor protocol was violated.

Send a DestroyCell and close the circuit.

Parameters:cell (cell) – received cell that violated the Tor protocol.

destroyCircuitFromRelay(cell)

Called when a DestroyCell is received from a relay on this circuit’s path.

Immediately close the circuit. We don’t need to send a DestroyCell in this case.

Parameters:cell (cell) – either the DestroyCell or the RelayTruncatedCell that was received.

destroyCircuitFromManager()

Called by the circuit manager when it decides to destroy this circuit.

Send a destroy cell and notify this circuit’s connection that this circuit is now closed.

destroyCircuitFromConnection()

Called when a connection closes this circuit (usually because the connection went down).

Primarily called when we lose the TLS connection to our connection object. Do a ‘hard’ destroy and immediately close all associated streams. Do not send a destroy cell.