commit 35df48b189f513a456c90b5418ddab027079d507 Author: Nick Mathewson nickm@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. **/
/*