commit fec1360c7a20e7d06b7c12946e7ffd10286a67db Author: George Kadianakis desnacked@gmail.com Date: Mon Dec 12 11:36:17 2011 +0100

Add detailed file-level documentation. --- Doxyfile | 2 +- src/crypt.c | 2 + src/main.c | 5 +-- src/managed.c | 8 ++++++ src/network.c | 55 ++++++++++++++++++++++++++++++++++++++++++++++ src/obfs_main.c | 3 ++ src/protocol.c | 10 ++++++-- src/protocols/dummy.h | 3 ++ src/protocols/obfs2.c | 19 +++++++++++++++- src/protocols/obfs2.h | 17 ++++++++++++++ src/sha256.c | 6 ++-- src/socks.c | 58 +++++++++++++++++++++++++++++++----------------- src/util.c | 6 +++++ 13 files changed, 162 insertions(+), 32 deletions(-)

diff --git a/Doxyfile b/Doxyfile index a479ab2..b2e21c1 100644 --- a/Doxyfile +++ b/Doxyfile @@ -1118,7 +1118,7 @@ PERLMOD_MAKEVAR_PREFIX = # evaluate all C-preprocessor directives found in the sources and include # files.

-ENABLE_PREPROCESSING = YES +ENABLE_PREPROCESSING = NO

# If the MACRO_EXPANSION tag is set to YES Doxygen will expand all macro # names in the source code. If set to NO (the default) only conditional diff --git a/src/crypt.c b/src/crypt.c index b8240be..e70ec29 100644 --- a/src/crypt.c +++ b/src/crypt.c @@ -6,6 +6,8 @@ * \file crypt.c * \headerfile crypt.h * \brief Cryptographic functions. + * + * \details Most functions here are wrappers of OpenSSL functions. **/

#include "util.h" diff --git a/src/main.c b/src/main.c index e03daf0..76158e0 100644 --- a/src/main.c +++ b/src/main.c @@ -8,11 +8,10 @@ * \brief Entry point of obfsproxy. Does command-line parsing, and * switches into 'external' or 'managed' proxy mode. * - * (Practically, obfs_main.c is the actual entry point of obfsproxy, - * but all it does is call obfs_main().) + * \details Practically, obfs_main.c is the actual entry point of + * obfsproxy, but all it really does is call obfs_main(). **/

- #include "util.h"

#include "container.h" diff --git a/src/managed.c b/src/managed.c index 71658dc..d70c1cf 100644 --- a/src/managed.c +++ b/src/managed.c @@ -6,6 +6,14 @@ * \file managed.c * \headerfile managed.h * \brief Implements the 'managed proxy' mode of obfsproxy. + * + * \details This is an implementation of managed proxies according to + * the 180-pluggable-transport.txt specification. The entry point is + * launch_managed_proxy() where a managed_proxy_t instance is created + * to represent our managed proxy. We read and validate the + * environment variables that tor should have prepared for us, launch + * the appropriate listeners, and finally kickstart libevent to start + * accepting connections. **/

#include "util.h" diff --git a/src/network.c b/src/network.c index 5c3cedf..3ede3ab 100644 --- a/src/network.c +++ b/src/network.c @@ -8,6 +8,61 @@ * \brief Networking side of obfspoxy. Creates listeners, accepts * connections, reads/writes data, and calls transport callbacks when * applicable. + * + * \details Terminology: + * + * A <em>connection</em> is a bidirectional communications channel, + * usually backed by a network socket, and represented in this layer + * by a conn_t, wrapping a libevent bufferevent. + * + * A <em>circuit</em> is a <b>pair</b> of connections, referred to as the + * <em>upstream</em> and <em>downstream</em> connections. A circuit + * is represented by a circuit_t. The upstream connection of a + * circuit communicates in cleartext with the higher-level program + * that wishes to make use of our obfuscation service. The + * downstream connection commmunicates in an obfuscated fashion with + * the remote peer that the higher-level client wishes to contact. + * + * A <em>listener</em> is a listening socket bound to a particular + * obfuscation protocol, represented in this layer by a listener_t + * and its config_t. Connecting to a listener creates one + * connection of a circuit, and causes this program to initiate the + * other connection (possibly after receiving in-band instructions + * about where to connect to). A listener is said to be a + * <em>client</em> listener if connecting to it creates the + * <b>upstream</b> connection, and a <em>server</em> listener if + * connecting to it creates the <b>downstream</b> connection. + * + * There are two kinds of client listeners: a <em>simple</em> client + * listener always connects to the same remote peer every time it + * needs to initiate a downstream connection; a <em>socks</em> + * client listener can be told to connect to an arbitrary remote + * peer using the SOCKS protocol (version 4 or 5). + * + * The diagram below might help demonstrate the relationship between + * connections and circuits: + * + *\verbatim + downstream + + 'circuit_t C' 'conn_t CD' 'conn_t SD' 'circuit_t S' + +-----------+ +-----------+ + upstream ----|obfsproxy c|-------------|obfsproxy s|---- upstream + | +-----------+ +-----------+ | + 'conn_t CU'| |'conn_t SU' + +------------+ +--------------+ + | Tor Client | | Tor Bridge | + +------------+ +--------------+ + + \endverbatim + * + * In the above diagram, <b>obfsproxy c</b> is the client-side + * obfsproxy, and <b>obfsproxy s</b> is the server-side + * obfsproxy. <b>conn_t CU</b> is the Client's Upstream connection, + * the communication channel between tor and obfsproxy. <b>conn_t + * CD</b> is the Client's Downstream connection, the communication + * channel between obfsproxy and the remote peer. These two + * connections form <b>circuit_t C</b>. **/

#include "util.h" diff --git a/src/obfs_main.c b/src/obfs_main.c index f787d69..08399eb 100644 --- a/src/obfs_main.c +++ b/src/obfs_main.c @@ -6,6 +6,9 @@ * \file obfs_main.c * \brief Real entry point of obfsproxy. Immediately calls * main.c:obfs_main(). + * + * \details This all happens so that our unittests binary can link + * against main.c. **/

int obfs_main(int argc, char *argv[]); diff --git a/src/protocol.c b/src/protocol.c index 4abff90..4b97d4e 100644 --- a/src/protocol.c +++ b/src/protocol.c @@ -5,10 +5,14 @@ /** * \file protocol.c * \headerfile protocol.h - * \brief Pluggable transports-related functions. Acts as a wrapper on - * top of transport callbacks and transport-specific option parsing. + * \brief Pluggable transports-related functions. * - * 'Protocol' is a synonym to 'pluggable transport' in obfsproxy code. + * \details Acts as an intermediary between generic obfsproxy code, + * and pluggable transports code. Provides wrappers for + * transport-specific configuration, and callbacks. + * + * Note that in obfsproxy code, 'protocol' is a synonym to 'pluggable + * transport'. **/

#include "util.h" diff --git a/src/protocols/dummy.h b/src/protocols/dummy.h index 150b3ff..b5cb3a6 100644 --- a/src/protocols/dummy.h +++ b/src/protocols/dummy.h @@ -28,6 +28,7 @@ extern const protocol_vtable dummy_vtable; also because, if you're using dummy as a template, you probably will want to extend the generic structures. */

+/** \private \extends config_t */ typedef struct dummy_config_t { config_t super; struct evutil_addrinfo *listen_addr; @@ -35,10 +36,12 @@ typedef struct dummy_config_t { enum listen_mode mode; } dummy_config_t;

+/** \private \extends conn_t */ typedef struct dummy_conn_t { conn_t super; } dummy_conn_t;

+/** \private \extends circuit_t */ typedef struct dummy_circuit_t { circuit_t super; } dummy_circuit_t; diff --git a/src/protocols/obfs2.c b/src/protocols/obfs2.c index de26858..213e36f 100644 --- a/src/protocols/obfs2.c +++ b/src/protocols/obfs2.c @@ -6,9 +6,26 @@ * \file obfs2.c * \headerfile obfs2.h * \brief Implements the 'obfs2' pluggable transport. + * + * \details We track the state of the obfs2 protocol in the + * <b>state</b> member of <b>obfs2_state_t</b>. + * + * The first step of the obfs2 protocol, is to send the handshake + * message (obfs2_handshake()) and move to the initial state which is + * <em>ST_WAIT_FOR_KEY</em>. + * + * During <em>ST_WAIT_FOR_KEY</em>, we are waiting for the key of our + * peer. obfs2_recv() is responsible for picking up the key from our + * peer's handshake message, deriving additional keys out of it + * (init_crypto()), and progressing to the <em>ST_WAIT_FOR_PADDING</em> state. + * + * During <em>ST_WAIT_FOR_PADDING</em>, we are waiting for the amount + * of padding that our peer promised in his handshake message. When we + * receive the padding, we move to the final state <em>ST_OPEN</em> + * and start exchanging data messages with our peer using the derived + * keys. **/

- #include "util.h"

#define PROTOCOL_OBFS2_PRIVATE diff --git a/src/protocols/obfs2.h b/src/protocols/obfs2.h index 6030c79..74b65a1 100644 --- a/src/protocols/obfs2.h +++ b/src/protocols/obfs2.h @@ -74,20 +74,37 @@ typedef struct obfs2_state_t { int padding_left_to_read; } obfs2_state_t;

+/** config_t for obfs2. + * \private \extends config_t + */ typedef struct obfs2_config_t { + /** Base <b>config_t</b>. */ config_t super; + /** Address to listen on. */ struct evutil_addrinfo *listen_addr; + /** Address to connect to. */ struct evutil_addrinfo *target_addr; + /** Listener mode. */ enum listen_mode mode; + /** obfs2 shared secret. */ uchar shared_secret[SHARED_SECRET_LENGTH]; } obfs2_config_t;

+/** conn_t for obfs2. + * \private \extends conn_t + */ typedef struct obfs2_conn_t { + /** Base <b>conn_t</b>. */ conn_t super; } obfs2_conn_t;

+/** circuit_t for obfs2. + * \private \extends circuit_t + */ typedef struct obfs2_circuit_t { + /** Base <b>circuit_t</b>. */ circuit_t super; + /** State of obfs2 for this circuit. */ obfs2_state_t *state; } obfs2_circuit_t;

diff --git a/src/sha256.c b/src/sha256.c index 349cdeb..f6bbd7a 100644 --- a/src/sha256.c +++ b/src/sha256.c @@ -6,9 +6,9 @@ * \headerfile sha256.h * \brief SHA256 implementation by Tom St Denis. * - * This SHA256 implementation is adapted from the public domain one in - * LibTomCrypt, version 1.6. Tor uses it on platforms where OpenSSL - * doesn't have a SHA256. + * \details This SHA256 implementation is adapted from the public + * domain one in LibTomCrypt, version 1.6. Tor uses it on platforms + * where OpenSSL doesn't have a SHA256. **/

#include "util.h" diff --git a/src/socks.c b/src/socks.c index 51c6dff..98cb678 100644 --- a/src/socks.c +++ b/src/socks.c @@ -6,6 +6,43 @@ * \file socks.c * \headerfile socks.h * \brief SOCKS{5,4,4a} server. + * + * \details + * Every <b>circuit_t</b> has a <b>socks_state_t</b> attached + * to it, representing the state of the SOCKS protocol on that + * circuit. + * + * If we are a client using SOCKS, and we haven't completed the SOCKS + * handshake, socks_read_cb() passes all incoming data to + * handle_socks(). On a valid 'Client request' packet, we parse the + * requested address into <b>struct parsereq</b> of + * <b>socks_state_t</b>, and toggle SOCKS' state to ST_HAVE_ADDR. When + * socks_read_cb() notices that we are in ST_HAVE_ADDR, it connects to + * the requested address to set up the proxying tunnel. Upon a + * successful connection, pending_socks_cb() sends back a 'Server + * reply' and sets up the proxying tunnel. + * + * <em>SOCKS5 protocol handshake:</em> + * + * Client ------------------------> Server\n + * Method Negotiation Packet (socks5_handle_negotiation()) + * + * Client <------------------------ Server\n + * Method Negotiation Reply (socks5_do_negotiation()) + * + * Client ------------------------> Server\n + * Client request (socks5_handle_request()) + * + * Client <------------------------ Server\n + * Server reply (socks5_send_reply()) + * + * <em>SOCKS{4,4a} protocol handshake:</em> + * + * Client ------------------------> Server\n + * Client Request (socks4_read_request()) + * + * Client <------------------------ Server\n + * Server reply (socks4_send_reply()) **/

#include "util.h" @@ -17,27 +54,6 @@

#include <event2/buffer.h>

-/** - General SOCKS5 idea: - - Client ------------------------> Server - Method Negotiation Packet - - Client <------------------------ Server - Method Negotiation Reply - - Client ------------------------> Server - Client request - - Client <------------------------ Server - Server reply - - "Method Negotiation Packet" is handled by: socks5_handle_negotiation() - "Method Negotiation Reply" is done by: socks5_do_negotiation() - "Client request" is handled by: socks5_handle_request() - "Server reply" is done by: socks5_send_reply() -*/ -

typedef unsigned char uchar;

diff --git a/src/util.c b/src/util.c index db0dc77..c63a651 100644 --- a/src/util.c +++ b/src/util.c @@ -6,6 +6,12 @@ * \file util.c * \headerfile util.h * \brief Utility functions. + * + * \details Contains: + * - wrappers of malloc() et al. + * - network functions + * - string functions + * - functions used by obfsproxy's logging subsystem **/

#include "util.h"