mirror of
https://gitlab.torproject.org/tpo/core/tor.git
synced 2024-11-20 10:12:15 +01:00
Document control.c
svn:r2700
This commit is contained in:
Nick Mathewson
parent
3236ee3127
commit
2cacb4e0f9
125
src/or/control.c
125
src/or/control.c
@ -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 @@ static const char *CONTROL_COMMANDS[] = {
|
||||
"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_setevents(connection_t *conn, uint16_t len,
|
||||
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 @@ static void update_global_event_mask(void)
|
||||
}
|
||||
}
|
||||
|
||||
/** 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 @@ send_control_message(connection_t *conn, uint16_t type, uint16_t len,
|
||||
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_error(connection_t *conn, uint16_t error, const char *message)
|
||||
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 @@ send_control_event(uint16_t event, uint16_t len, const char *body)
|
||||
}
|
||||
}
|
||||
|
||||
/** 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 @@ handle_control_setconf(connection_t *conn, uint16_t len,
|
||||
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 @@ handle_control_getconf(connection_t *conn, uint16_t body_len,
|
||||
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 @@ static int handle_control_setevents(connection_t *conn, uint16_t len,
|
||||
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 @@ static int handle_control_authenticate(connection_t *conn, uint16_t len,
|
||||
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 @@ int connection_control_finished_flushing(connection_t *conn) {
|
||||
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 @@ int connection_control_process_inbuf(connection_t *conn) {
|
||||
}
|
||||
|
||||
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 @@ int connection_control_process_inbuf(connection_t *conn) {
|
||||
goto again;
|
||||
}
|
||||
|
||||
/* Okay, we're willing to process the command. */
|
||||
switch(command_type)
|
||||
{
|
||||
case CONTROL_CMD_SETCONF:
|
||||
@ -363,7 +432,10 @@ int connection_control_process_inbuf(connection_t *conn) {
|
||||
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 @@ int control_event_circuit_status(circuit_t *circ, circuit_status_event_t tp)
|
||||
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 @@ int control_event_stream_status(connection_t *conn, stream_status_event_t tp)
|
||||
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 @@ int control_event_or_conn_status(connection_t *conn,or_conn_status_event_t tp)
|
||||
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 @@ int control_event_bandwidth_used(uint32_t n_read, uint32_t n_written)
|
||||
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 @@ void control_event_logmsg(int severity, const char *msg)
|
||||
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];
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user