[tor-commits] [obfsproxy/master] Add detailed file-level documentation.
nickm at torproject.org
nickm at torproject.org
Mon Dec 12 15:49:48 UTC 2011
commit fec1360c7a20e7d06b7c12946e7ffd10286a67db
Author: George Kadianakis <desnacked at 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"
More information about the tor-commits
mailing list