Add top-level file documentation for circuitpadding.c

/* 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>

 * \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;