[tor-commits] [obfsproxy/master] Add some more content to the architecture doc

[nickm at torproject.org]

commit d8f3f69dc761140a34653aff3b1db8c6925809f9
Author: Nick Mathewson <nickm at torproject.org>
Date:   Thu Dec 29 11:10:29 2011 -0500

    Add some more content to the architecture doc
---
 doc/obfsproxy_architecture.txt |   65 ++++++++++++++++++++++++++-------------
 1 files changed, 43 insertions(+), 22 deletions(-)

diff --git a/doc/obfsproxy_architecture.txt b/doc/obfsproxy_architecture.txt
index 19809e6..299eb7d 100644
--- a/doc/obfsproxy_architecture.txt
+++ b/doc/obfsproxy_architecture.txt
@@ -1,26 +1,42 @@
-                           Obfsproxy Architecture
+                         Obfsproxy Architecture
+
+                           George Kadianakis
+                             Nick Mathewson
 
 
 1. Top Level View
 
    obfsproxy is a pluggable transports proxy written in C. It's
-   compliant to the pluggable transports specification [0], and its
+   compliant to the Tor pluggable transports specification [0], and its
    modular architecture allows it to support multiple pluggable
    transports.
 
-   # It supports two modes of operation, the 'external proxy' mode and
-   # the 'managed proxy' mode. When used as an 'external proxy', the
-   # user configures obfsproxy using the command-line. When used as a
-   # 'managed proxy', obfsproxy can be configured by another application
-   # using the managed proxy configuration protocol defined in the
-   # pluggable transports specification [0].
+   It supports two modes of operation, the 'external proxy' mode and
+   the 'managed proxy' mode. When used as an 'external proxy', the
+   user configures obfsproxy using the command-line. When used as a
+   'managed proxy', obfsproxy can be configured by another application
+   using the managed proxy configuration protocol defined in the
+   pluggable transports specification [0].
+
+   While designed for use with Tor, it should be suitable for
+   integration with other protocols as well.
+
+   Note also that although obfsproxy is designed to support multiple
+   protocols and obfuscation mechanisms, it is NOT required (or
+   intended) that every pluggable transport for Tor be implemented as a
+   module for obfsproxy.  The point of pluggable transports [0] after
+   all, is that not every obfuscation mechanism should or can be part of
+   the same program.
 
 2. Modularity
 
-   obfsproxy uses callbacks and object-oriented programming principles
-   to achieve modularity. This way, a developer who is interested in
-   writing a pluggable transport doesn't need to know obfsproxy's code
-   inside out.
+   obfsproxy tries to isolate its modules using callbacks and
+   vtable-based object-oriented programming principles.  This way, a
+   developer who is interested in writing a pluggable transport doesn't
+   need to know obfsproxy's code inside out.
+
+   obfsproxy outsources its networking and cryptography functionality to
+   Libevent 2.x and OpenSSL respectively.
 
 2.1. Callbacks
 
@@ -47,6 +63,11 @@
    Developers that make good use of obfsproxy's callbacks and OOP,
    should be able to implement most pluggable transports.
 
+   The implementation uses the standard OOP-in-C trick of having a
+   subclass's type be a structure that includes the parent class's
+   structure as its first member, and having polymorphic functions be
+   implemented as an explicit vtable structure of function pointers.
+
 3. Codebase tour
 
    This section does a short introduction into some areas of obfsproxy's
@@ -65,22 +86,22 @@
    and 'downstream' connections. 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
+   communicates in an obfuscated fashion with the remote peer that the
    higher-level client wishes to contact.
 
    The diagram below might help demonstrate the relationship between
    connections and circuits:
 
-                                      downstream
+                                   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  |
-              +------------+                              +--------------+
+       'circuit_t C'        'conn_t CD'      'conn_t SD'      'circuit_t S'
+                     +-----------+          +-----------+
+     upstream    ----|obfsproxy c|----------|obfsproxy s|----    upstream
+                 |   +-----------+    ^      +-----------+   |
+      'conn_t CU'|                    |                     |'conn_t SU'
+           +------------+           Sent over       +--------------+
+           | Tor Client |           the net         |  Tor Bridge  |
+           +------------+                           +--------------+
 
    In the above diagram, "obfsproxy c" is the client-side obfsproxy, and
    "obfsproxy s" is the server-side obfsproxy. "conn_t CU" is the