Add top-level file documentation for circuitpadding.c

2 files changed, 40 insertions, 1 deletions

diff --git a/src/core/or/circuitpadding.c b/src/core/or/circuitpadding.c
index ee26558bc8..4c0736fff4 100644
--- a/src/core/or/circuitpadding.c
+++ b/src/core/or/circuitpadding.c
@@ -1,6 +1,44 @@
 /* Copyright (c) 2017 The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * \file circuitpadding.c
+ * \brief Circuit-level padding implementation
+ *
+ * \details
+ *
+ * This file implements Tor proposal 254 "Padding Negotiation" which is heavily
+ * inspired by the paper "Toward an Efficient Website Fingerprinting Defense"
+ * by M. Juarez, M. Imani, M. Perry, C. Diaz, M. Wright.
+ *
+ * In particular the code in this file describes mechanisms for clients to
+ * negotiate various types of circuit-level padding from relays.
+ *
+ * Each padding type is described by a state machine (circpad_machine_t), which
+ * is also referred as a "padding machine" in this file.  Currently, these
+ * state machines are hardcoded in the source code (e.g. see
+ * circpad_circ_client_machine_init()), but in the future we will be able to
+ * serialize them in the torrc or the consensus.
+ *
+ * As specified by prop#254, clients can negotiate padding with relays by using
+ * PADDING_NEGOTIATE cells. After successful padding negotiation, padding
+ * machines are assigned to the circuit in their mutable form as a
+ * circpad_machineinfo_t.
+ *
+ * Each state of a padding state machine can be either:
+ * - A histogram that specifies inter-arrival padding delays.
+ * - Or a parametrized probability distribution that specifies inter-arrival
+ *   delays (see circpad_distribution_type_t).
+ *
+ * Padding machines start from the START state and finish with the END
+ * state. They can transition between states using the events in
+ * circpad_event_t.
+ *
+ * When a padding machine reaches the END state, it gets wiped from the circuit
+ * so that other padding machines can take over if needed (see
+ * circpad_machine_transitioned_to_end()).
+ **/
+
 #define CIRCUITPADDING_PRIVATE
 
 #include <math.h>
diff --git a/src/core/or/circuitpadding.h b/src/core/or/circuitpadding.h
index 4680c6be43..6559f916d2 100644
--- a/src/core/or/circuitpadding.h
+++ b/src/core/or/circuitpadding.h
@@ -6,10 +6,11 @@
  * \file circuitpadding.h
  * \brief Header file for circuitpadding.c.
  **/
+
 #ifndef TOR_CIRCUITPADDING_H
 #define TOR_CIRCUITPADDING_H
 
-#include "circpad_negotiation.h"
+#include "src/trunnel/circpad_negotiation.h"
 #include "lib/evloop/timers.h"
 
 typedef struct circuit_t circuit_t;