commit cdbd5c0af85775522845a54468492770c54b4cb4 Author: George Kadianakis desnacked@riseup.net Date: Thu Jan 10 12:28:17 2019 +0200
Add top-level file documentation for circuitpadding.c --- src/core/or/circuitpadding.c | 38 ++++++++++++++++++++++++++++++++++++++ src/core/or/circuitpadding.h | 3 ++- 2 files changed, 40 insertions(+), 1 deletion(-)
diff --git a/src/core/or/circuitpadding.c b/src/core/or/circuitpadding.c index ee26558bc..4c0736fff 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 4680c6be4..6559f916d 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;