From 2587fa09f9d0304a4ba575d1d3aeae665d1cb0a6 Mon Sep 17 00:00:00 2001 From: Roger Dingledine Date: Sat, 11 Jun 2005 06:07:22 +0000 Subject: [PATCH] move more docs into our code svn:r4406 --- src/or/buffers.c | 17 ++++++++++++++ src/or/connection.c | 2 +- src/or/or.h | 56 +++++++++++++++++++++++++++++++++++++++------ 3 files changed, 67 insertions(+), 8 deletions(-) diff --git a/src/or/buffers.c b/src/or/buffers.c index 7fdbcc81b7..41de4e87fd 100644 --- a/src/or/buffers.c +++ b/src/or/buffers.c @@ -477,6 +477,23 @@ read_to_buf_tls_impl(tor_tls *tls, size_t at_most, buf_t *buf, char *next) } /** As read_to_buf, but reads from a TLS connection. + * + * Using TLS on OR connections complicates matters in two ways. + * + * First, a TLS stream has its own read buffer independent of the + * connection's read buffer. (TLS needs to read an entire frame from + * the network before it can decrypt any data. Thus, trying to read 1 + * byte from TLS can require that several KB be read from the network + * and decrypted. The extra data is stored in TLS's decrypt buffer.) + * Because the data hasn't been read by Tor (it's still inside the TLS), + * this means that sometimes a connection "has stuff to read" even when + * poll() didn't return POLLIN. The tor_tls_get_pending_bytes function is + * used in connection.c to detect TLS objects with non-empty internal + * buffers and read from them again. + * + * Second, the TLS stream's events do not correspond directly to network + * events: sometimes, before a TLS stream can read, the network must be + * ready to write -- or vice versa. */ int read_to_buf_tls(tor_tls *tls, size_t at_most, buf_t *buf) { int r; diff --git a/src/or/connection.c b/src/or/connection.c index 40979f2ce2..92c560fed8 100644 --- a/src/or/connection.c +++ b/src/or/connection.c @@ -1094,7 +1094,7 @@ static int connection_read_to_buf(connection_t *conn, int *max_to_read) { pending = tor_tls_get_pending_bytes(conn->tls); if (pending) { /* XXXX If we have any pending bytes, read them now. This *can* - * take us over our read alotment, but really we shouldn't be + * take us over our read allotment, but really we shouldn't be * believing that SSL bytes are the same as TCP bytes anyway. */ int r2 = read_to_buf_tls(conn->tls, pending, conn->inbuf); if (r2<0) { diff --git a/src/or/or.h b/src/or/or.h index 426856d298..da422075f0 100644 --- a/src/or/or.h +++ b/src/or/or.h @@ -182,21 +182,23 @@ typedef enum { #define _CONN_TYPE_MIN 3 /** Type for sockets listening for OR connections. */ #define CONN_TYPE_OR_LISTENER 3 -/** Type for OR-to-OR or OP-to-OR connections. */ +/** A bidirectional TLS connection transmitting a sequence of cells. + * May be from an OR to an OR, or from an OP to an OR. */ #define CONN_TYPE_OR 4 -/** Type for connections from final OR to chosen destination. */ +/** A TCP connection from an onion router to a stream's destination. */ #define CONN_TYPE_EXIT 5 /** Type for sockets listening for SOCKS connections. */ #define CONN_TYPE_AP_LISTENER 6 -/** Type for SOCKS connections to OP. */ +/** A SOCKS proxy connection from the user application to the onion + * proxy. */ #define CONN_TYPE_AP 7 /** Type for sockets listening for HTTP connections to the directory server. */ #define CONN_TYPE_DIR_LISTENER 8 /** Type for HTTP connections to the directory server. */ #define CONN_TYPE_DIR 9 -/** Type for connections to local dnsworker processes. */ +/** Connection from the main process to a DNS worker process. */ #define CONN_TYPE_DNSWORKER 10 -/** Type for connections to local cpuworker processes. */ +/** Connection from the main process to a CPU worker process. */ #define CONN_TYPE_CPUWORKER 11 /** Type for listenting for connections from user interface process */ #define CONN_TYPE_CONTROL_LISTENER 12 @@ -538,8 +540,26 @@ typedef struct buf_t buf_t; typedef struct socks_request_t socks_request_t; #define CONNECTION_MAGIC 0x7C3C304Eu + /** Description of a connection to another host or process, and associated - * data. */ + * data. + * + * A connection is named based on what it's connected to -- an "OR + * connection" has an onion router on the other end, an "OP connection" + * (nearly obsolete) has an onion proxy on the other end, an "exit + * connection" has a website or other server on the other end, and an + * "AP connection" has an application proxy (and thus a user) on the + * other end. + * + * Every connection has a type and a state. Connections never change + * their type, but can go through many state changes in their lifetime. + * + * Every connection has two associated input and output buffers. + * Listeners don't use them. For non-listener connections, incoming + * data is appended to conn->inbuf, and outgoing data is taken from + * conn->outbuf. Connections differ primarily in the functions called + * to fill and drain these buffers. + */ struct connection_t { uint32_t magic; /**< For memory debugging: must equal CONNECTION_MAGIC. */ @@ -816,7 +836,29 @@ typedef struct { } cpath_build_state_t; #define CIRCUIT_MAGIC 0x35315243u -/** Struct for a path (circuit) through the onion routing network. */ + +/** + * A circuit is a path over the onion routing + * network. Applications can connect to one end of the circuit, and can + * create exit connections at the other end of the circuit. AP and exit + * connections have only one circuit associated with them (and thus these + * connection types are closed when the circuit is closed), whereas + * OR connections multiplex many circuits at once, and stay standing even + * when there are no circuits running over them. + * + * A circuit_t structure fills two roles. First, a circuit_t links two + * connections together: either an edge connection and an OR connection, + * or two OR connections. (When joined to an OR connection, a circuit_t + * affects only cells sent to a particular circID on that connection. When + * joined to an edge connection, a circuit_t affects all data.) + + * Second, a circuit_t holds the cipher keys and state for sending data + * along a given circuit. At the OP, it has a sequence of ciphers, each + * of which is shared with a single OR along the circuit. Separate + * ciphers are used for data going "forward" (away from the OP) and + * "backward" (towards the OP). At the OR, a circuit has only two stream + * ciphers: one for data going forward, and one for data going backward. + */ struct circuit_t { uint32_t magic; /**< For memory debugging: must equal CIRCUIT_MAGIC. */