[tor-commits] [tor/master] Module docs for channel.c and channeltls.c

[nickm at torproject.org]

commit 35df48b189f513a456c90b5418ddab027079d507
Author: Nick Mathewson <nickm at torproject.org>
Date:   Mon Oct 17 14:23:53 2016 -0400

    Module docs for channel.c and channeltls.c
---
 src/or/channel.c    | 26 ++++++++++++++++++++++++++
 src/or/channeltls.c | 22 ++++++++++++++++++++++
 2 files changed, 48 insertions(+)

diff --git a/src/or/channel.c b/src/or/channel.c
index 6a78b21..f547aea 100644
--- a/src/or/channel.c
+++ b/src/or/channel.c
@@ -8,6 +8,32 @@
  * transfer cells from Tor instance to Tor instance.
  * Currently, there is only one implementation of the channel abstraction: in
  * channeltls.c.
+ *
+ * Channels are a higher-level abstraction than or_connection_t: In general,
+ * any means that two Tor relays use to exchange cells, or any means that a
+ * relay and a client use to exchange cells, is a channel.
+ *
+ * Channels differ from pluggable transports in that they do not wrap an
+ * underlying protocol over which cells are transmitted: they <em>are</em> the
+ * underlying protocol.
+ *
+ * This module defines the generic parts of the channel_t interface, and
+ * provides the machinery necessary for specialized implementations to be
+ * created.  At present, there is one specialized implementation in
+ * channeltls.c, which uses connection_or.c to send cells over a TLS
+ * connection.
+ *
+ * Every channel implementation is responsible for being able to transmit
+ * cells that are added to it with channel_write_cell() and related functions,
+ * and to receive incoming cells with the channel_queue_cell() and related
+ * functions.  See the channel_t documentation for more information.
+ *
+ * When new cells arrive on a channel, they are passed to cell handler
+ * functions, which can be set by channel_set_cell_handlers()
+ * functions. (Tor's cell handlers are in command.c.)
+ *
+ * Tor flushes cells to channels from relay.c in
+ * channel_flush_from_first_active_circuit().
  **/
 
 /*
diff --git a/src/or/channeltls.c b/src/or/channeltls.c
index 9c2411e..09cca95 100644
--- a/src/or/channeltls.c
+++ b/src/or/channeltls.c
@@ -6,6 +6,28 @@
  *
  * \brief A concrete subclass of channel_t using or_connection_t to transfer
  * cells between Tor instances.
+ *
+ * This module fills in the various function pointers in channel_t, to
+ * implement the channel_tls_t channels as used in Tor today.  These channels
+ * are created from channel_tls_connect() and
+ * channel_tls_handle_incoming(). Each corresponds 1:1 to or_connection_t
+ * object, as implemented in connection_or.c.  These channels transmit cells
+ * to the underlying or_connection_t by calling
+ * connection_or_write_*_cell_to_buf(), and receive cells from the underlying
+ * or_connection_t when connection_or_process_cells_from_inbuf() calls
+ * channel_tls_handle_*_cell().
+ *
+ * Here we also implement the server (responder) side of the v3+ Tor link
+ * handshake, which uses CERTS and AUTHENTICATE cell to negotiate versions,
+ * exchange expected and observed IP and time information, and bootstrap a
+ * level of authentication higher than we have gotten on the raw TLS
+ * handshake.
+ *
+ * NOTE: Since there is currently only one type of channel, there are probably
+ * more than a few cases where functionality that is currently in
+ * channeltls.c, connection_or.c, and channel.c ought to be divided up
+ * differently.  The right time to do this is probably whenever we introduce
+ * our next channel type.
  **/
 
 /*