[or-cvs] Merge doc patches and a bugfix from Mark Melahn
Nick Mathewson
nickm at seul.org
Sat Jul 23 01:17:30 UTC 2005
Update of /home/or/cvsroot/control/java/net/freehaven/tor/control
In directory moria:/tmp/cvs-serv13464/java/net/freehaven/tor/control
Modified Files:
EventHandler.java TorControlConnection1.java
Log Message:
Merge doc patches and a bugfix from Mark Melahn
Index: EventHandler.java
===================================================================
RCS file: /home/or/cvsroot/control/java/net/freehaven/tor/control/EventHandler.java,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -d -r1.4 -r1.5
--- EventHandler.java 11 Jul 2005 19:14:18 -0000 1.4
+++ EventHandler.java 23 Jul 2005 01:17:27 -0000 1.5
@@ -12,34 +12,63 @@
public interface EventHandler {
/**
* Invoked when a circuit's status has changed.
- * See TorControlCommands.CIRC_STATUS_* for possible status codes.
+ * Possible values for <b>status</b> are:
+ * <ul>
+ * <li>"LAUNCHED" : circuit ID assigned to new circuit</li>
+ * <li>"BUILT" : all hops finished, can now accept streams</li>
+ * <li>"EXTENDED" : one more hop has been completed</li>
+ * <li>"FAILED" : circuit closed (was not built)</li>
+ * <li>"CLOSED" : circuit closed (was built)</li>
+ * </ul>
+ *
+ * <b>circID</b> is the alphanumeric identifier of the affected circuit,
+ * and <b>path</b> is a comma-separated list of alphanumeric ServerIDs.
*/
public void circuitStatus(String status, String circID, String path);
/**
* Invoked when a stream's status has changed.
- * See TorControlCommands.STREAM_STATUS_* for possible status codes.
+ * Possible values for <b>status</b> are:
+ * <ul>
+ * <li>"NEW" : New request to connect</li>
+ * <li>"NEWRESOLVE" : New request to resolve an address</li>
+ * <li>"SENTCONNECT" : Sent a connect cell along a circuit</li>
+ * <li>"SENTRESOLVE" : Sent a resolve cell along a circuit</li>
+ * <li>"SUCCEEDED" : Received a reply; stream established</li>
+ * <li>"FAILED" : Stream failed and not retriable.</li>
+ * <li>"CLOSED" : Stream closed</li>
+ * <li>"DETACHED" : Detached from circuit; still retriable.</li>
+ * </ul>
+ *
+ * <b>streamID</b> is the alphanumeric identifier of the affected stream,
+ * and its <b>target</b> is specified as address:port.
*/
public void streamStatus(String status, String streamID, String target);
/**
* Invoked when the status of a connection to an OR has changed.
- * See TorControlCommands.OR_CONN_STATUS_* for possible status codes.
+ * Possible values for <b>status</b> are ["LAUNCHED" | "CONNECTED" | "FAILED" | "CLOSED"].
+ * <b>orName</b> is the alphanumeric identifier of the OR affected.
*/
public void orConnStatus(String status, String orName);
/**
- * Invoked once per second with the number of bytes read an written in
- * the last secone.
+ * Invoked once per second. <b>read</b> and <b>written</b> are
+ * the number of bytes read and written, respectively, in
+ * the last second.
*/
public void bandwidthUsed(long read, long written);
/**
- * Invoked whenever Tor learns about new ORs.
+ * Invoked whenever Tor learns about new ORs. The <b>orList</b> object
+ * contains the alphanumeric ServerIDs associated with the new ORs.
*/
public void newDescriptors(java.util.List orList);
/**
* Invoked when Tor logs a message.
+ * <b>severity</b> is one of ["DEBUG" | "INFO" | "NOTICE" | "WARN" | "ERR"],
+ * and <b>msg</b> is the message string.
*/
public void message(String severity, String msg);
/**
- * Invoked in an unspecified handler.
+ * Invoked when an unspecified message is received.
+ * <type> is the message type, and <msg> is the message string.
*/
public void unrecognized(String type, String msg);
Index: TorControlConnection1.java
===================================================================
RCS file: /home/or/cvsroot/control/java/net/freehaven/tor/control/TorControlConnection1.java,v
retrieving revision 1.6
retrieving revision 1.7
diff -u -d -r1.6 -r1.7
--- TorControlConnection1.java 20 Jul 2005 22:48:34 -0000 1.6
+++ TorControlConnection1.java 23 Jul 2005 01:17:27 -0000 1.7
@@ -13,7 +13,9 @@
import java.util.Map;
import java.util.StringTokenizer;
-/** DOCDOC */
+/** Extends the TorControlConnection class to implement Version 1
+* of the TC protocol, as specified in control-spec.txt.
+*/
public class TorControlConnection1 extends TorControlConnection
implements TorControlCommands
{
@@ -211,8 +213,26 @@
}
}
- /** Change the values of the configuration options stored in
- * 'kvList'. (The format is "key value"). */
+ /** Changes the values of the configuration options stored in
+ * <b>kvList</b>. Each list element in <b>kvList</b> is expected to be
+ * String of the format "key value".
+ *
+ * Tor behaves as though it had just read each of the key-value pairs
+ * from its configuration file. Keywords with no corresponding values have
+ * their configuration values reset to their defaults. setConf is
+ * all-or-nothing: if there is an error in any of the configuration settings,
+ * Tor sets none of them.
+ *
+ * When a configuration option takes multiple values, or when multiple
+ * configuration keys form a context-sensitive group (see getConf below), then
+ * setting any of the options in a setConf command is taken to reset all of
+ * the others. For example, if two ORBindAddress values are configured, and a
+ * command arrives containing a single ORBindAddress value, the new
+ * command's value replaces the two old values.
+ *
+ * To remove all settings for a given option entirely (and go back to its
+ * default value), include a String in <b>kvList</b> containing the key and no value.
+ */
public void setConf(Collection kvList) throws IOException {
if (kvList.size() == 0)
return;
@@ -229,16 +249,39 @@
sendAndWaitForResponse(b.toString(), null);
}
+ /** Sets <b>w</b> as the PrintWriter for debugging output,
+ * which writes out all messages passed between Tor and the controller.
+ * Outgoing messages are preceded by "\>\>" and incoming messages are preceded
+ * by "\<\<"
+ */
public void setDebugging(java.io.PrintWriter w) {
if (w instanceof java.io.PrintWriter)
debugOutput = (java.io.PrintWriter) w;
else
debugOutput = new java.io.PrintWriter(w, true);
}
+
+ /** Sets <b>s</b> as the PrintStream for debugging output,
+ * which writes out all messages passed between Tor and the controller.
+ * Outgoing messages are preceded by "\>\>" and incoming messages are preceded
+ * by "\<\<"
+ */
public void setDebugging(java.io.PrintStream s) {
debugOutput = new java.io.PrintWriter(s, true);
}
-
+
+ /** Requests the values of the configuration variables listed in <b>keys</b>.
+ * Results are returned as a list of ConfigEntry objects.
+ *
+ * If an option appears multiple times in the configuration, all of its
+ * key-value pairs are returned in order.
+ *
+ * Some options are context-sensitive, and depend on other options with
+ * different keywords. These cannot be fetched directly. Currently there
+ * is only one such option: clients should use the "HiddenServiceOptions"
+ * virtual keyword to get all HiddenServiceDir, HiddenServicePort,
+ * HiddenServiceNodes, and HiddenServiceExcludeNodes option settings.
+ */
public List getConf(Collection keys) throws IOException {
StringBuffer sb = new StringBuffer("GETCONF");
for (Iterator it = keys.iterator(); it.hasNext(); ) {
@@ -256,7 +299,15 @@
}
return result;
}
-
+
+ /** Request that the server inform the client about interesting events.
+ * Each element of <b>events</b> is one of the following Strings:
+ * ["CIRC" | "STREAM" | "ORCONN" | "BW" | "DEBUG" |
+ * "INFO" | "NOTICE" | "WARN" | "ERR" | "NEWDESC" | "ADDRMAP"] .
+ *
+ * Any events not listed in the <b>events</b> are turned off; thus, calling
+ * setEvents with an empty <b>events</b> argument turns off all event reporting.
+ */
public void setEvents(List events) throws IOException {
StringBuffer sb = new StringBuffer("SETEVENTS");
for (Iterator it = events.iterator(); it.hasNext(); ) {
@@ -271,21 +322,78 @@
sb.append("\r\n");
sendAndWaitForResponse(sb.toString(), null);
}
-
+
+
+ /** Authenticates the controller to the Tor server.
+ *
+ * By default, the current Tor implementation trusts all local users, and
+ * the controller can authenticate itself by calling authenticate(new byte[0]).
+ *
+ * If the 'CookieAuthentication' option is true, Tor writes a "magic cookie"
+ * file named "control_auth_cookie" into its data directory. To authenticate,
+ * the controller must send the contents of this file in <b>auth</b>.
+ *
+ * If the 'HashedControlPassword' option is set, <b>auth</b> must contain the salted
+ * hash of a secret password. The salted hash is computed according to the
+ * S2K algorithm in RFC 2440 (OpenPGP), and prefixed with the s2k specifier.
+ * This is then encoded in hexadecimal, prefixed by the indicator sequence
+ * "16:".
+ *
+ * You can generate the salt of a password by calling
+ * 'tor --hash-password <password>'
+ * or by using the provided PasswordDigest class.
+ * To authenticate under this scheme, the controller sends Tor the original
+ * secret that was used to generate the password.
+ */
public void authenticate(byte[] auth) throws IOException {
String cmd = "AUTHENTICATE " + Bytes.hex(auth) + "\r\n";
sendAndWaitForResponse(cmd, null);
}
+ /** Instructs the server to write out its configuration options into its torrc.
+ */
public void saveConf() throws IOException {
sendAndWaitForResponse("SAVECONF\r\n", null);
}
+ /** Sends a signal from the controller to the Tor server.
+ * <b>signal</b> is one of the following Strings:
+ * <ul>
+ * <li>"RELOAD" or "HUP" : Reload config items, refetch directory</li>
+ * <li>"SHUTDOWN" or "INT" : Controlled shutdown: if server is an OP, exit immediately.
+ * If it's an OR, close listeners and exit after 30 seconds</li>
+ * <li>"DUMP" or "USR1" : Dump stats: log information about open connections and circuits</li>
+ * <li>"DEBUG" or "USR2" : Debug: switch all open logs to loglevel debug</li>
+ * <li>"HALT" or "TERM" : Immediate shutdown: clean up and exit now</li>
+ * </ul>
+ */
public void signal(String signal) throws IOException {
- String cmd = "AUTHENTICATE " + signal + "\r\n";
+ String cmd = "SIGNAL" + signal + "\r\n";
sendAndWaitForResponse(cmd, null);
}
-
+ /** Tells the Tor server that future SOCKS requests for connections to a set of original
+ * addresses should be replaced with connections to the specified replacement
+ * addresses. Each element of <b>kvLines</b> is a String of the form
+ * "old-address new-address". This function returns the new address mapping.
+ *
+ * The client may decline to provide a body for the original address, and
+ * instead send a special null address ("0.0.0.0" for IPv4, "::0" for IPv6, or
+ * "." for hostname), signifying that the server should choose the original
+ * address itself, and return that address in the reply. The server
+ * should ensure that it returns an element of address space that is unlikely
+ * to be in actual use. If there is already an address mapped to the
+ * destination address, the server may reuse that mapping.
+ *
+ * If the original address is already mapped to a different address, the old
+ * mapping is removed. If the original address and the destination address
+ * are the same, the server removes any mapping in place for the original
+ * address.
+ *
+ * Mappings set by the controller last until the Tor process exits:
+ * they never expire. If the controller wants the mapping to last only
+ * a certain time, then it must explicitly un-map the address when that
+ * time has elapsed.
+ */
public Map mapAddresses(Collection kvLines) throws IOException {
StringBuffer sb = new StringBuffer("MAPADDRESS");
for (Iterator it = kvLines.iterator(); it.hasNext(); ) {
@@ -305,7 +413,37 @@
}
return result;
}
-
+
+ /** Queries the Tor server for keyed values that are not stored in the torrc
+ * configuration file. Returns a map of keys to values.
+ *
+ * Recognized keys include:
+ * <ul>
+ * <li>"version" : The version of the server's software, including the name
+ * of the software. (example: "Tor 0.0.9.4")</li>
+ * <li>"desc/id/<OR identity>" or "desc/name/<OR nickname>" : the latest server
+ * descriptor for a given OR, NUL-terminated. If no such OR is known, the
+ * corresponding value is an empty string.</li>
+ * <li>"network-status" : a space-separated list of all known OR identities.
+ * This is in the same format as the router-status line in directories;
+ * see tor-spec.txt for details.</li>
+ * <li>"addr-mappings/all"</li>
+ * <li>"addr-mappings/config"</li>
+ * <li>"addr-mappings/cache"</li>
+ * <li>"addr-mappings/control" : a space-separated list of address mappings, each
+ * in the form of "from-address=to-address". The 'config' key
+ * returns those address mappings set in the configuration; the 'cache'
+ * key returns the mappings in the client-side DNS cache; the 'control'
+ * key returns the mappings set via the control interface; the 'all'
+ * target returns the mappings set through any mechanism.</li>
+ * <li>"circuit-status" : A series of lines as for a circuit status event. Each line is of the form:
+ * "CircuitID CircStatus Path"</li>
+ * <li>"stream-status" : A series of lines as for a stream status event. Each is of the form:
+ * "StreamID StreamStatus CircID Target"</li>
+ * <li>"orconn-status" : A series of lines as for an OR connection status event. Each is of the
+ * form: "ServerID ORStatus"</li>
+ * </ul>
+ */
public Map getInfo(Collection keys) throws IOException {
StringBuffer sb = new StringBuffer("GETINFO");
for (Iterator it = keys.iterator(); it.hasNext(); ) {
@@ -330,41 +468,96 @@
}
return m;
}
-
+
+ /** An extendCircuit request takes one of two forms: either the <b>circID</b> is zero, in
+ * which case it is a request for the server to build a new circuit according
+ * to the specified path, or the <b>circID</b> is nonzero, in which case it is a
+ * request for the server to extend an existing circuit with that ID according
+ * to the specified <b>path</b>.
+ *
+ * If successful, returns the Circuit ID of the (maybe newly created) circuit.
+ */
public String extendCircuit(String circID, String path) throws IOException {
ArrayList lst = sendAndWaitForResponse(
"EXTENDCIRCUIT "+circID+" "+path+"\r\n", null);
return ((ReplyLine)lst.get(0)).msg;
}
-
+
+ /** Informs the Tor server that the stream specified by <b>streamID</b> should be
+ * associated with the circuit specified by <b>circID</b>.
+ *
+ * Each stream may be associated with
+ * at most one circuit, and multiple streams may share the same circuit.
+ * Streams can only be attached to completed circuits (that is, circuits that
+ * have sent a circuit status "BUILT" event or are listed as built in a
+ * getInfo circuit-status request).
+ *
+ * If <b>circID</b> is 0, responsibility for attaching the given stream is
+ * returned to Tor.
+ *
+ * By default, Tor automatically attaches streams to
+ * circuits itself, unless the configuration variable
+ * "__LeaveStreamsUnattached" is set to "1". Attempting to attach streams
+ * via TC when "__LeaveStreamsUnattached" is false may cause a race between
+ * Tor and the controller, as both attempt to attach streams to circuits.
+ */
public void attachStream(String streamID, String circID)
throws IOException {
sendAndWaitForResponse("ATTACHSTREAM "+streamID+" "+circID+"\r\n", null);
}
- /** Tell Tor about the server descriptor in 'desc' */
+ /** Tells Tor about the server descriptor in <b>desc</b>.
+ *
+ * The descriptor, when parsed, must contain a number of well-specified
+ * fields, including fields for its nickname and identity.
+ */
+ // More documentation here on format of desc?
+ // No need for return value? control-spec.txt says reply is merely "250 OK" on success...
public String postDescriptor(String desc) throws IOException {
ArrayList lst = sendAndWaitForResponse("+POSTDESCRIPTOR\r\n", desc);
return ((ReplyLine)lst.get(0)).msg;
}
- /** Tell Tor to change the target of the stream identified by 'streamID'
- * to 'address'.
+ /** Tells Tor to change the exit address of the stream identified by <b>streamID</b>
+ * to <b>address</b>. No remapping is performed on the new provided address.
+ *
+ * To be sure that the modified address will be used, this event must be sent
+ * after a new stream event is received, and before attaching this stream to
+ * a circuit.
*/
public void redirectStream(String streamID, String address) throws IOException {
sendAndWaitForResponse("REDIRECTSTREAM "+streamID+" "+address+"\r\n",
null);
}
- /** Tell Tor to close the stream identified by 'streamID'.
- */
+ /** Tells Tor to close the stream identified by <b>streamID</b>.
+ * <b>reason</b> should be one of the Tor RELAY_END reasons given in tor-spec.txt, as a decimal:
+ * <ul>
+ * <li>1 -- REASON_MISC (catch-all for unlisted reasons)</li>
+ * <li>2 -- REASON_RESOLVEFAILED (couldn't look up hostname)</li>
+ * <li>3 -- REASON_CONNECTREFUSED (remote host refused connection)</li>
+ * <li>4 -- REASON_EXITPOLICY (OR refuses to connect to host or port)</li>
+ * <li>5 -- REASON_DESTROY (Circuit is being destroyed)</li>
+ * <li>6 -- REASON_DONE (Anonymized TCP connection was closed)</li>
+ * <li>7 -- REASON_TIMEOUT (Connection timed out, or OR timed out while connecting)</li>
+ * <li>8 -- (unallocated)</li>
+ * <li>9 -- REASON_HIBERNATING (OR is temporarily hibernating)</li>
+ * <li>10 -- REASON_INTERNAL (Internal error at the OR)</li>
+ * <li>11 -- REASON_RESOURCELIMIT (OR has no resources to fulfill request)</li>
+ * <li>12 -- REASON_CONNRESET (Connection was unexpectedly reset)</li>
+ * <li>13 -- REASON_TORPROTOCOL (Sent when closing connection because of Tor protocol violations)</li>
+ * </ul>
+ *
+ * Tor may hold the stream open for a while to flush any data that is pending.
+ */
public void closeStream(String streamID, byte reason)
throws IOException {
sendAndWaitForResponse("CLOSESTREAM "+streamID+" "+reason+"\r\n",null);
}
- /** Tell Tor to close the circuit identified by 'streamID'.
- */
+ /** Tells Tor to close the circuit identified by <b>circID</b>.
+ * If <b>ifUnused</b> is true, do not close the circuit unless it is unused.
+ */
public void closeCircuit(String circID, boolean ifUnused) throws IOException {
sendAndWaitForResponse("CLOSECIRCUIT "+circID+
(ifUnused?" IFUNUSED":"")+"\r\n", null);
More information about the tor-commits
mailing list