[Author Prev][Author Next][Thread Prev][Thread Next][Author Index][Thread Index]
[or-cvs] Document control.c
Update of /home/or/cvsroot/src/or
In directory moria.mit.edu:/tmp/cvs-serv30335/src/or
Modified Files:
control.c
Log Message:
Document control.c
Index: control.c
===================================================================
RCS file: /home/or/cvsroot/src/or/control.c,v
retrieving revision 1.9
retrieving revision 1.10
diff -u -d -r1.9 -r1.10
--- control.c 7 Nov 2004 11:33:04 -0000 1.9
+++ control.c 7 Nov 2004 21:37:50 -0000 1.10
@@ -2,8 +2,33 @@
/* See LICENSE for licensing information */
/* $Id$ */
+/**
+ * /file control.c
+ *
+ * /brief Implementation for Tor's control-socket interface.
+ */
+
#include "or.h"
+/* Protocol outline: a bidirectional stream, over which each side
+ * sends a series of messages. Each message has a two-byte typecode,
+ * a two-byte length field, and a variable-length body whose length is
+ * given in the length field.
+ *
+ * By default, the server only sends messages in response to client messages.
+ * Every client message gets a message in response. The client may, however,
+ * _request_ that other messages be delivered asynchronously.
+ *
+ *
+ * Every message type is either client-only or server-only, and every
+ * server message type is either synchronous-only (only occurs in
+ * response to a client request) or asynchronous-only (never is an
+ * answer to a client request.
+ *
+ * See control-spec.txt for full details.
+ */
+
+/* Recognized message type codes. */
#define CONTROL_CMD_ERROR 0x0000
#define CONTROL_CMD_DONE 0x0001
#define CONTROL_CMD_SETCONF 0x0002
@@ -14,6 +39,7 @@
#define CONTROL_CMD_AUTHENTICATE 0x0007
#define _CONTROL_CMD_MAX_RECOGNIZED 0x0007
+/* Recognized error codes. */
#define ERR_UNSPECIFIED 0x0000
#define ERR_UNRECOGNIZED_TYPE 0x0001
#define ERR_UNRECOGNIZED_CONFIG_KEY 0x0002
@@ -22,6 +48,7 @@
#define ERR_UNAUTHORIZED_USER 0x0005
#define ERR_FAILED_AUTHENTICATION 0x0006
+/* Recongized asynchonous event types. */
#define _EVENT_MIN 0x0001
#define EVENT_CIRCUIT_STATUS 0x0001
#define EVENT_STREAM_STATUS 0x0002
@@ -30,9 +57,9 @@
#define EVENT_WARNING 0x0005
#define _EVENT_MAX 0x0005
-#define EVENT_IS_INTERESTING(e) (global_event_mask & (1<<(e)))
-
-static const char *CONTROL_COMMANDS[] = {
+/** Array mapping from message type codes to human-readable message
+ * type names. */
+static const char * CONTROL_COMMANDS[] = {
"error",
"done",
"setconf",
@@ -43,9 +70,24 @@
"authenticate",
};
+/** Bitfield: The bit 1<<e is be set if <b>any</b> open control
+ * connection is interested in events of type <b>e</b>. We use this
+ * so that we can decide to skip generating event messages that nobody
+ * is interest in without having to walk over the global connection
+ * list to find out.
+ **/
static uint32_t global_event_mask = 0;
+/** Macro: true if any control connection is interested in events of type
+ * <b>e</b>. */
+#define EVENT_IS_INTERESTING(e) (global_event_mask & (1<<(e)))
+
+/** If we're using cookie-type authentication, how long should our cookies be?
+ */
#define AUTHENTICATION_COOKIE_LEN 32
+
+/** If true, we've set authentication_cookie to a secret code and
+ * stored it to disk. */
static int authentication_cookie_is_set = 0;
static char authentication_cookie[AUTHENTICATION_COOKIE_LEN];
@@ -65,12 +107,16 @@
static int handle_control_authenticate(connection_t *conn, uint16_t len,
const char *body);
+/** Given a possibly invalid message type code <b>cmd</b>, return a
+ * human-readable string equivalent. */
static INLINE const char *
control_cmd_to_string(uint16_t cmd)
{
return (cmd<=_CONTROL_CMD_MAX_RECOGNIZED) ? CONTROL_COMMANDS[cmd] : "Unknown";
}
+/** Set <b>global_event_mask</b> to the bitwise OR of each live control
+ * connection's event_mask field. */
static void update_global_event_mask(void)
{
connection_t **conns;
@@ -86,6 +132,8 @@
}
}
+/** Send a message of type <b>type</b> containing <b>len</b> bytes
+ * from <b>body</b> along the control connection <b>conn</b> */
static void
send_control_message(connection_t *conn, uint16_t type, uint16_t len,
const char *body)
@@ -101,12 +149,15 @@
connection_write_to_buf(body, len, conn);
}
+/** Send a "DONE" message down the control connection <b>conn</b> */
static void
send_control_done(connection_t *conn)
{
send_control_message(conn, CONTROL_CMD_DONE, 0, NULL);
}
+/** Send an error message with error code <b>error</b> and body
+ * <b>message</b> down the connection <b>conn</b> */
static void
send_control_error(connection_t *conn, uint16_t error, const char *message)
{
@@ -119,6 +170,9 @@
send_control_message(conn, CONTROL_CMD_ERROR, (uint16_t)(len+2), buf);
}
+/** Send an 'event' message of event type <b>event</b>, containing
+ * <b>len</b> bytes in <b>body</b> to every control connection that
+ * is interested in it. */
static void
send_control_event(uint16_t event, uint16_t len, const char *body)
{
@@ -135,9 +189,10 @@
}
}
+/** Called when we receive a SETCONF message: parse the body and try
+ * to update our configuration. Reply with a DONE or ERROR message. */
static int
-handle_control_setconf(connection_t *conn, uint16_t len,
- char *body)
+handle_control_setconf(connection_t *conn, uint16_t len, char *body)
{
struct config_line_t *lines=NULL;
or_options_t *options = get_options();
@@ -161,9 +216,10 @@
return 0;
}
+/** Called when we receive a GETCONF message. Parse the request, and
+ * reply with a CONFVALUE or an ERROR message */
static int
-handle_control_getconf(connection_t *conn, uint16_t body_len,
- const char *body)
+handle_control_getconf(connection_t *conn, uint16_t body_len, const char *body)
{
smartlist_t *questions = NULL;
smartlist_t *answers = NULL;
@@ -212,8 +268,10 @@
return 0;
}
-static int handle_control_setevents(connection_t *conn, uint16_t len,
- const char *body)
+/** Called when we get a SETEVENTS message: update conn->event_mask,
+ * and reply with DONE or ERROR. */
+static int
+handle_control_setevents(connection_t *conn, uint16_t len, const char *body)
{
uint16_t event_code;
uint32_t event_mask = 0;
@@ -240,8 +298,12 @@
return 0;
}
-static int handle_control_authenticate(connection_t *conn, uint16_t len,
- const char *body)
+/** Called when we get an AUTHENTICATE message. Check whether the
+ * authentication is valid, and if so, update the connection's state to
+ * OPEN. Reply with DONE or ERROR.
+ */
+static int
+handle_control_authenticate(connection_t *conn, uint16_t len, const char *body)
{
or_options_t *options = get_options();
if (len == AUTHENTICATION_COOKIE_LEN &&
@@ -277,7 +339,9 @@
return 0;
}
-int connection_control_finished_flushing(connection_t *conn) {
+/** Called when <b>conn</b> has no more bytes left on its outbuf. */
+int
+connection_control_finished_flushing(connection_t *conn) {
tor_assert(conn);
tor_assert(conn->type == CONN_TYPE_CONTROL);
@@ -285,7 +349,10 @@
return 0;
}
-int connection_control_process_inbuf(connection_t *conn) {
+/** Called when <b>conn</b> has received more bytes on its inbuf, or has
+ * gotten its socket closed. */
+int
+connection_control_process_inbuf(connection_t *conn) {
uint16_t body_len, command_type;
char *body;
@@ -299,6 +366,7 @@
}
again:
+ /* Try to suck a control message from the buffer. */
switch(fetch_from_buf_control(conn->inbuf, &body_len, &command_type, &body))
{
case -1:
@@ -325,6 +393,7 @@
goto again;
}
+ /* Okay, we're willing to process the command. */
switch(command_type)
{
case CONTROL_CMD_SETCONF:
@@ -363,7 +432,10 @@
goto again; /* There might be more data. */
}
-int control_event_circuit_status(circuit_t *circ, circuit_status_event_t tp)
+/** Something has happened to circuit <b>circ</b>: tell any interested
+ * control connections. */
+int
+control_event_circuit_status(circuit_t *circ, circuit_status_event_t tp)
{
char *path, *msg;
size_t path_len;
@@ -385,7 +457,10 @@
return 0;
}
-int control_event_stream_status(connection_t *conn, stream_status_event_t tp)
+/** Something has happened to the stream associated with AP connection
+ * <b>conn</b>: tell any interested control connections. */
+int
+control_event_stream_status(connection_t *conn, stream_status_event_t tp)
{
char *msg;
size_t len;
@@ -406,7 +481,10 @@
return 0;
}
-int control_event_or_conn_status(connection_t *conn,or_conn_status_event_t tp)
+/** Something has happened to the OR connection <b>conn</b>: tell any
+ * interested control connections. */
+int
+control_event_or_conn_status(connection_t *conn,or_conn_status_event_t tp)
{
char buf[HEX_DIGEST_LEN+3]; /* status, dollar, identity, NUL */
size_t len;
@@ -423,7 +501,10 @@
return 0;
}
-int control_event_bandwidth_used(uint32_t n_read, uint32_t n_written)
+/** A second or more has elapsed: tell any interested control
+ * connections how much bandwidth we used. */
+int
+control_event_bandwidth_used(uint32_t n_read, uint32_t n_written)
{
char buf[8];
@@ -437,7 +518,9 @@
return 0;
}
-void control_event_logmsg(int severity, const char *msg)
+/** We got a log message: tell any interested control connections. */
+void
+control_event_logmsg(int severity, const char *msg)
{
size_t len;
if (severity > LOG_WARN) /* Less important than warning? ignore for now. */
@@ -449,7 +532,11 @@
send_control_event(EVENT_WARNING, (uint16_t)(len+1), msg);
}
-int init_cookie_authentication(void)
+/** Choose a random authentication cookie and write it to disk.
+ * Anybody who can read the cookie from disk will be considered
+ * authorized to use the control connection. */
+int
+init_cookie_authentication(void)
{
char fname[512];