TorController (SelekTOR Java Documentation)
Date: 2018-05-25

client

## Class TorController

- java.lang.Object
- - lib.ClientProcess
  - - client.TorProcess
    - - client.TorController

-     public class TorController
      extends TorProcess

  Author:
    Alistair Neil

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static int` | `EVENT_ABORTED`
    `static int` | `EVENT_CIRCUIT_BUILT`
    `static int` | `EVENT_CIRCUIT_CHANGED`
    `static int` | `EVENT_CIRCUIT_FAILED`
    `static int` | `EVENT_CIRCUITS_BUILT`
    `static int` | `EVENT_CIRCUITS_FAILED`
    `static int` | `EVENT_LATENCY_DONE`
    `static int` | `EVENT_TESTING_DONE`
    `static long` | `LATENCY_FAIL`
    `static int` | `NODE_EXIT`
    `static int` | `NODE_GUARD`
    `static int` | `NODE_MIDDLE`
    `static int` | `STATUS_BOOTING`
    `static int` | `STATUS_CIRCUIT_CREATION`
    `static int` | `STATUS_DEAD`
    `static int` | `STATUS_IDLE`
    `static int` | `STATUS_LATENCY_CHECKING`
    `static int` | `STREAM_IP`

    - ### Fields inherited from class client.TorProcess

      `EMPTYSTRING, LOG_DEBUG, LOG_INFO, LOG_NOTICE, TOR_BOOT_ERROR, TOR_BOOT_FATAL, TOR_BOOT_TIMEOUT, TOR_BOOTED, TOR_BRIDGE, TOR_CLOCK_ERROR, TOR_DIRINFO_STALE, TOR_MESSAGE, TOR_NEWCIRC, TOR_NOEXITS, TOR_NOHOP0, TOR_NONET_ACTIVITY, TOR_NOROUTE, TOR_RESTARTED, TOR_STOPPED`

    - ### Fields inherited from class lib.ClientProcess

      `CLIENT_RUNNING, CLIENT_STOPPED, CLIENT_TIMEDOUT`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `TorController(java.lang.String clientpath, java.lang.String configfolder)` Constructor

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `abortActions()` Abort all current actions
    `void` | `abortLatencyCheck()` Abort latency checking
    `void` | `activateCircuit(java.lang.String hops)` Activate given circuit, does not block
    `void` | `activateNodes(java.lang.String fingers, int nocircs)` Set the csv list of exit node fingers to be used by tor, a single exit node may also be specified, this does not block
    `void` | `activateNodesBlocking(java.lang.String fingers, int nocircs)` Set the csv list of exit node fingers to be used by tor, a single exit node may also be specified, this blocks
    `void` | `closeCircuit(java.lang.String id)` Close a circuit with ID
    `void` | `closeCircuitsExcept(java.lang.String id, boolean filtered)` Close open circuits except circuit specified by id
    `void` | `controllerEventFired(int event, java.lang.Object data)` Handle for controllerEventFired should be overridden by parent class
    `java.net.Socket` | `createSocks4aSocket(java.lang.String socksaddr, int socksport, java.lang.String remotehost, int remoteport)` Create a Socks4a socket Taken from Wikipedia SOCKS4a is a simple extension to SOCKS4 protocol that allows a client that cannot resolve the destination host's domain name to specify it.
    `java.net.Socket` | `createTorSocketToURL(java.lang.String url, boolean nowww)` Create a socks4a socket to this URL on this tor connection, if nowww is true then remove www.
    `void` | `doLatencyCheck(int timeout)` Triggers a socks latency check, EVENT_LATENCY_CHECK is fired on completion
    `void` | `enablePredictiveCircuits(boolean enabled)` Enable/Disable predictive circuit building
    `java.util.ArrayList<java.lang.String>` | `getActiveStreams()` Get list of active streams
    `java.lang.String` | `getBestHops()` Get best hops
    `long` | `getBestLatency()` Get best latency
    `java.util.HashMap<java.lang.String,TorCircuit>` | `getBuiltCircuits(boolean filtered)` Get built circuits
    `java.lang.String` | `getCountryFromIP(java.lang.String ip)` Attempts to return the Country associated with an ip address
    `java.lang.String` | `getEntryGuardsAsCSV()` Get entry guards chosen by tor client
    `java.lang.String` | `getEntryNodes()` Get configured entry nodes
    `java.lang.String` | `getEventMessage(int event)` Get textual representation on an event
    `java.util.ArrayList<java.lang.String>` | `getInfo(java.lang.String property)` Get tor status information for a given property.
    `long` | `getLatency()` Get current latency
    `TorCircuit` | `getLatestCircuit()` Get the latest circuit
    `int` | `getStatus()` Get current status
    `long` | `getTorLatency(int timeout)` Returns measured latency for the active circuit without creating a stream, this blocks so be careful
    `boolean` | `haveValidEntryNode()`
    `boolean` | `isIdle()` Convenience test for idle status
    `void` | `loadConf()` Load configuration file
    `java.util.ArrayList<java.lang.String>` | `resetConf(java.lang.String property)` reset a tor configuration property
    `void` | `saveConf()` Save configuration file
    `java.util.ArrayList<java.lang.String>` | `sendCommand(java.lang.String command)` Send a command to tor client
    `java.util.ArrayList<java.lang.String>` | `setConf(java.lang.String property)` Set a tor configuration property
    `void` | `setEntryNodes(java.lang.String fingers)` Set entry nodes
    `void` | `setStatus(int status)` Set status flag
    `void` | `setTestingURL(java.lang.String url)` Set the url used for latency checking
    `java.util.ArrayList<java.lang.String>` | `signal(java.lang.String cmd)` Send signal to tor
    `void` | `start()` Start tor controller process and issue the TOR_BOOTED event
    `void` | `start(int bootevent)` Start tor controller process and issue the given event
    `void` | `stop()` Stop the tor controller process completely
    `void` | `testNode(java.lang.String finger)` Test specified node, non blocking
    `void` | `torProcessEventFired(int event, java.lang.String data)` Tor process event
    `boolean` | `verifyControlComms()` Verify we have comms on the control socket

    - ### Methods inherited from class client.TorProcess

      `clearCLIOption, clearStdout, clearTorrcOption, clientProcessEventFired, createDataFolder, createDefaultConfig, deleteCacheData, deleteConfigFile, getBridges, getCacheAge, getCachedDataFolder, getClientLocation, getCLIOptionBool, getCLIOptions, getCLIOptionsAsString, getConfigFilePath, getControlPort, getDataFolder, getListenPort, getOwnershipID, getSecret, getTorrcOption, getTorrcOptionsAsString, getVersion, setBoolTorOption, setBridges, setCachedDataFolder, setCLIOption, setControlPassword, setExternalArgs, setGeoIP4, setGeoIP6, setInitialBootEvent, setListenPort, setLogLevel, setMaxHistory, setOwnershipID, setSilentBootEnabled, setStdoutTextArea, setTorrcOption, startProcess, validateBridges, validateHostPort`

    - ### Methods inherited from class lib.ClientProcess

      `getClientStatus, getProcess, sendMessage, setStartupDelay, setStartupTimeout, start, stopProcess`

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

    - #### EVENT_CIRCUITS_BUILT

          public static final int EVENT_CIRCUITS_BUILT

      See Also:
        Constant Field Values

    - #### EVENT_CIRCUITS_FAILED

          public static final int EVENT_CIRCUITS_FAILED

      See Also:
        Constant Field Values

    - #### EVENT_CIRCUIT_BUILT

          public static final int EVENT_CIRCUIT_BUILT

      See Also:
        Constant Field Values

    - #### EVENT_CIRCUIT_FAILED

          public static final int EVENT_CIRCUIT_FAILED

      See Also:
        Constant Field Values

    - #### EVENT_LATENCY_DONE

          public static final int EVENT_LATENCY_DONE

      See Also:
        Constant Field Values

    - #### EVENT_TESTING_DONE

          public static final int EVENT_TESTING_DONE

      See Also:
        Constant Field Values

    - #### EVENT_CIRCUIT_CHANGED

          public static final int EVENT_CIRCUIT_CHANGED

      See Also:
        Constant Field Values

    - #### EVENT_ABORTED

          public static final int EVENT_ABORTED

      See Also:
        Constant Field Values

    - #### STATUS_DEAD

          public static final int STATUS_DEAD

      See Also:
        Constant Field Values

    - #### STATUS_BOOTING

          public static final int STATUS_BOOTING

      See Also:
        Constant Field Values

    - #### STATUS_IDLE

          public static final int STATUS_IDLE

      See Also:
        Constant Field Values

    - #### STATUS_CIRCUIT_CREATION

          public static final int STATUS_CIRCUIT_CREATION

      See Also:
        Constant Field Values

    - #### STATUS_LATENCY_CHECKING

          public static final int STATUS_LATENCY_CHECKING

      See Also:
        Constant Field Values

    - #### LATENCY_FAIL

          public static final long LATENCY_FAIL

      See Also:
        Constant Field Values

    - #### STREAM_IP

          public static final int STREAM_IP

      See Also:
        Constant Field Values

    - #### NODE_GUARD

          public static final int NODE_GUARD

      See Also:
        Constant Field Values

    - #### NODE_MIDDLE

          public static final int NODE_MIDDLE

      See Also:
        Constant Field Values

    - #### NODE_EXIT

          public static final int NODE_EXIT

      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### TorController

          public TorController(java.lang.String clientpath,
                               java.lang.String configfolder)

      Constructor
      Parameters:
        `clientpath` - Path to Tor client
        `configfolder` - Location of configuration file torrc

  - ### Method Detail

    - #### torProcessEventFired

          public final void torProcessEventFired(int event,
                                                 java.lang.String data)

      Tor process event
      Overrides:
        `torProcessEventFired` in class `TorProcess`
      Parameters:
        `event` -
        `data` -

    - #### getEventMessage

          public java.lang.String getEventMessage(int event)

      Description copied from class: `TorProcess`
      Get textual representation on an event
      Overrides:
        `getEventMessage` in class `TorProcess`
      Returns:
        Event as text

    - #### controllerEventFired

          public void controllerEventFired(int event,
                                           java.lang.Object data)

      Handle for controllerEventFired should be overridden by parent class
      Parameters:
        `event` -
        `data` -

    - #### setStatus

          public void setStatus(int status)

      Set status flag
      Parameters:
        `status` -

    - #### getStatus

          public int getStatus()

      Get current status
      Returns:
        status integer constant, see defined status constants

    - #### isIdle

          public boolean isIdle()

      Convenience test for idle status
      Returns:
        true if idle

    - #### stop

          public final void stop()

      Stop the tor controller process completely

    - #### start

          public final void start()

      Start tor controller process and issue the TOR_BOOTED event

    - #### start

          public final void start(int bootevent)

      Start tor controller process and issue the given event
      Parameters:
        `bootevent` -

    - #### abortActions

          public final void abortActions()

      Abort all current actions

    - #### abortLatencyCheck

          public final void abortLatencyCheck()

      Abort latency checking

    - #### saveConf

          public void saveConf()

      Save configuration file

    - #### loadConf

          public void loadConf()

      Load configuration file

    - #### getCountryFromIP

          public java.lang.String getCountryFromIP(java.lang.String ip)

      Attempts to return the Country associated with an ip address
      Parameters:
        `ip` -
      Returns:
        Country or null if not found

    - #### setTestingURL

          public void setTestingURL(java.lang.String url)

      Set the url used for latency checking
      Parameters:
        `url` -

    - #### enablePredictiveCircuits

          public void enablePredictiveCircuits(boolean enabled)

      Enable/Disable predictive circuit building
      Parameters:
        `enabled` -

    - #### getInfo

          public final java.util.ArrayList<java.lang.String> getInfo(java.lang.String property)

      Get tor status information for a given property. See TOR control-spec documentation for valid properties
      Parameters:
        `property` -
      Returns:
        Arraylist containg the result of the command

    - #### closeCircuit

          public final void closeCircuit(java.lang.String id)

      Close a circuit with ID
      Parameters:
        `id` -

    - #### setConf

          public final java.util.ArrayList<java.lang.String> setConf(java.lang.String property)

      Set a tor configuration property
      Parameters:
        `property` -
      Returns:
        Arraylist containg the result of the command

    - #### resetConf

          public final java.util.ArrayList<java.lang.String> resetConf(java.lang.String property)

      reset a tor configuration property
      Parameters:
        `property` -
      Returns:
        Arraylist containing the result of the command

    - #### signal

          public final java.util.ArrayList<java.lang.String> signal(java.lang.String cmd)

      Send signal to tor
      Parameters:
        `cmd` -
      Returns:
        Arraylist containing the result of the command

    - #### getEntryGuardsAsCSV

          public java.lang.String getEntryGuardsAsCSV()

      Get entry guards chosen by tor client
      Returns:
        entry guards as comma separated fingerprints

    - #### doLatencyCheck

          public final void doLatencyCheck(int timeout)

      Triggers a socks latency check, EVENT_LATENCY_CHECK is fired on completion
      Parameters:
        `timeout` -

    - #### getLatency

          public final long getLatency()

      Get current latency
      Returns:
        latency in ms as long

    - #### getTorLatency

          public long getTorLatency(int timeout)

      Returns measured latency for the active circuit without creating a stream, this blocks so be careful
      Parameters:
        `timeout` -
      Returns:
        latency

    - #### closeCircuitsExcept

          public void closeCircuitsExcept(java.lang.String id,
                                          boolean filtered)

      Close open circuits except circuit specified by id
      Parameters:
        `id` -
        `filtered` -

    - #### getActiveStreams

          public final java.util.ArrayList<java.lang.String> getActiveStreams()

      Get list of active streams
      Returns:
        active streams as a list

    - #### activateNodes

          public final void activateNodes(java.lang.String fingers,
                                          int nocircs)

      Set the csv list of exit node fingers to be used by tor, a single exit node may also be specified, this does not block
      Parameters:
        `fingers` -
        `nocircs` -

    - #### activateCircuit

          public final void activateCircuit(java.lang.String hops)

      Activate given circuit, does not block
      Parameters:
        `hops` -

    - #### setEntryNodes

          public void setEntryNodes(java.lang.String fingers)

      Set entry nodes
      Parameters:
        `fingers` -

    - #### getEntryNodes

          public java.lang.String getEntryNodes()

      Get configured entry nodes
      Returns:
        entry nodes in CSV format

    - #### activateNodesBlocking

          public void activateNodesBlocking(java.lang.String fingers,
                                            int nocircs)

      Set the csv list of exit node fingers to be used by tor, a single exit node may also be specified, this blocks
      Parameters:
        `fingers` -
        `nocircs` -

    - #### haveValidEntryNode

          public boolean haveValidEntryNode()

    - #### testNode

          public void testNode(java.lang.String finger)

      Test specified node, non blocking
      Parameters:
        `finger` -

    - #### getBestLatency

          public final long getBestLatency()

      Get best latency
      Returns:
        best latency value in ms as long

    - #### getBestHops

          public final java.lang.String getBestHops()

      Get best hops
      Returns:
        hops info as string

    - #### getBuiltCircuits

          public final java.util.HashMap<java.lang.String,TorCircuit> getBuiltCircuits(boolean filtered)

      Get built circuits
      Parameters:
        `filtered` - Filter out unwanted circuits
      Returns:
        HashMap of built circuits keyed to their circuit id

    - #### verifyControlComms

          public final boolean verifyControlComms()

      Verify we have comms on the control socket
      Returns:
        true if its good

    - #### getLatestCircuit

          public final TorCircuit getLatestCircuit()

      Get the latest circuit
      Returns:
        circuit

    - #### sendCommand

          public final java.util.ArrayList<java.lang.String> sendCommand(java.lang.String command)

      Send a command to tor client
      Parameters:
        `command` -
      Returns:
        Arraylist containing the result of the command

    - #### createTorSocketToURL

          public java.net.Socket createTorSocketToURL(java.lang.String url,
                                                      boolean nowww)

      Create a socks4a socket to this URL on this tor connection, if nowww is true then remove www. from domain
      Parameters:
        `url` -
        `nowww` -
      Returns:
        socket

    - #### createSocks4aSocket

          public java.net.Socket createSocks4aSocket(java.lang.String socksaddr,
                                                     int socksport,
                                                     java.lang.String remotehost,
                                                     int remoteport)

      Create a Socks4a socket Taken from Wikipedia SOCKS4a is a simple extension to SOCKS4 protocol that allows a client that cannot resolve the destination host's domain name to specify it. The client should set the first three bytes of DSTIP to NULL and the last byte to a non-zero value. (This corresponds to IP address 0.0.0.x, with x nonzero, an inadmissible destination address and thus should never occur if the client can resolve the domain name.) Following the NULL byte terminating USERID, the client must send the destination domain name and terminate it with another NULL byte. This is used for both "connect" and "bind" requests. Client to SOCKS server: field 1: SOCKS version number, 1 byte, must be 0x04 for this version field 2: command code, 1 byte: 0x01 = establish a TCP/IP stream connection 0x02 = establish a TCP/IP port binding field 3: network byte order port number, 2 bytes field 4: deliberate invalid IP address, 4 bytes, first three must be 0x00 and the last one must not be 0x00 field 5: the user ID string, variable length, terminated with a null (0x00) field 6: the domain name of the host we want to contact, variable length, terminated with a null (0x00) Server to SOCKS client: field 1: null byte field 2: status, 1 byte: 0x5a = request granted 0x5b = request rejected or failed 0x5c = request failed because client is not running identd (or not reachable from the server) 0x5d = request failed because client's identd could not confirm the user ID string in the request field 3: network byte order port number, 2 bytes field 4: network byte order IP address, 4 bytes A server using protocol SOCKS4A must check the DSTIP in the request packet. If it represents address 0.0.0.x with nonzero x, the server must read in the domain name that the client sends in the packet. The server should resolve the domain name and make connection to the destination host if it can.
      Parameters:
        `socksaddr` - Socks ip address
        `socksport` - Socks port
        `remotehost` - Remote host
        `remoteport` - Remote port
      Returns:
        Socket