Data Fields
circpad_state_t Struct Reference

#include <circuitpadding.h>

Data Fields

circpad_hist_index_t histogram_len
circpad_hist_token_t histogram [CIRCPAD_MAX_HISTOGRAM_LEN]
circpad_delay_t histogram_edges [CIRCPAD_MAX_HISTOGRAM_LEN+1]
uint32_t histogram_total_tokens
circpad_distribution_t iat_dist
circpad_delay_t dist_max_sample_usec
circpad_delay_t dist_added_shift_usec
circpad_distribution_t length_dist
uint16_t start_length
uint64_t max_length
unsigned length_includes_nonpadding: 1
circpad_statenum_t next_state [CIRCPAD_NUM_EVENTS]
unsigned use_rtt_estimate: 1
circpad_removal_t token_removal

Detailed Description

A state of a padding state machine. The information here are immutable and represent the initial form of the state; it does not get updated as things happen. The mutable information that gets updated in runtime are carried in a circpad_machine_runtime_t.

This struct describes the histograms and/or probability distributions, as well as parameters of a single state in the adaptive padding machine. Instances of this struct exist in global circpad machine definitions that come from torrc or the consensus.

Definition at line 294 of file circuitpadding.h.

Field Documentation

◆ dist_added_shift_usec

circpad_delay_t dist_added_shift_usec

Definition at line 370 of file circuitpadding.h.

◆ dist_max_sample_usec

circpad_delay_t dist_max_sample_usec

Definition at line 365 of file circuitpadding.h.

◆ histogram

The histogram itself: an array of uint16s of tokens, whose widths are exponentially spaced, in microseconds.

This array must have histogram_len elements that are strictly monotonically increasing.

Definition at line 335 of file circuitpadding.h.

◆ histogram_edges

Definition at line 343 of file circuitpadding.h.

◆ histogram_len

circpad_hist_index_t histogram_len

If a histogram is used for this state, this specifies the number of bins of this histogram. Histograms must have at least 2 bins.

In particular, the following histogram:


  • 10 | +-—+ 9 | | | +------—+ 8 | | | | | 7 | | | +--—+ | 6 +-—+ Bin+--—+ | +------------—+ 5 | | #1 | | | | | | Bin| | Bin | Bin | Bin #4 | Bin #5 |
    #0 #2 #3 (infinity bin)
    0 +-—+-—+--—+--—+------—+------------—+ 0 100 200 350 500 1000 inf microseconds

would be specified the following way: histogram_len = 6; histogram[] = { 6, 10, 6, 7, 9, 6 } histogram_edges[] = { 0, 100, 200, 350, 500, 1000 }

The final bin is called the "infinity bin" and if it's chosen we don't schedule any padding. The infinity bin is strange because its lower edge is the max value of possible non-infinite delay allowed by this histogram, and its upper edge is CIRCPAD_DELAY_INFINITE. You can tell if the infinity bin is chosen by inspecting its bin index or inspecting its upper edge.

If a delay probability distribution is used for this state, this is set to 0.

Definition at line 329 of file circuitpadding.h.

Referenced by circpad_machine_setup_tokens(), and padding_machine_state_is_valid().

◆ histogram_total_tokens

uint32_t histogram_total_tokens

Total number of tokens in this histogram. This is a constant and is not decremented every time we spend a token. It's used for initializing and refilling the histogram.

Definition at line 347 of file circuitpadding.h.

◆ iat_dist

Represents a delay probability distribution (aka IAT distribution). It's a parametrized way of encoding inter-packet delay information in microseconds. It can be used instead of histograms.

If it is used, token_removal below must be set to CIRCPAD_TOKEN_REMOVAL_NONE.

Start_usec, range_sec, and rtt_estimates are still applied to the results of sampling from this distribution (range_sec is used as a max).

Definition at line 360 of file circuitpadding.h.

Referenced by circpad_distribution_sample_iat_delay(), and circpad_machine_sample_delay().

◆ length_dist

The length dist is a parameterized way of encoding how long this state machine runs in terms of sent padding cells or all sent cells. Values are sampled from this distribution, clamped to max_len, and then start_len is added to that value.

It may be specified instead of or in addition to the infinity bins and bins empty conditions.

Definition at line 380 of file circuitpadding.h.

Referenced by circpad_choose_state_length().

◆ length_includes_nonpadding

unsigned length_includes_nonpadding

Should we decrement length when we see a nonpadding packet? XXX: Are there any machines that actually want to set this to 0? There may not be. OTOH, it's only a bit..

Definition at line 389 of file circuitpadding.h.

◆ max_length

uint64_t max_length

A cap on the length value that can be sampled from the length_dist

Definition at line 384 of file circuitpadding.h.

◆ next_state

circpad_statenum_t next_state[CIRCPAD_NUM_EVENTS]

This is an array that specifies the next state to transition to upon receipt an event matching the indicated array index.

This aborts our scheduled packet and switches to the state corresponding to the index of the array. Tokens are filled upon this transition.

States are allowed to transition to themselves, which means re-schedule a new padding timer. They are also allowed to temporarily "transition" to the "IGNORE" and "CANCEL" pseudo-states. See defines below for details on state behavior and meaning.

Definition at line 404 of file circuitpadding.h.

◆ start_length

uint16_t start_length

A minimum length value, added to the output of length_dist

Definition at line 382 of file circuitpadding.h.

◆ token_removal

circpad_removal_t token_removal

This specifies the token removal strategy to use upon padding and non-padding activity.

Definition at line 416 of file circuitpadding.h.

Referenced by circpad_machine_remove_token(), and circpad_machine_setup_tokens().

◆ use_rtt_estimate

unsigned use_rtt_estimate

If true, estimate the RTT from this relay to the exit/website and add that to start_usec for use as the histogram bin 0 start delay.

Right now this is only supported for relay-side state machines.

Definition at line 412 of file circuitpadding.h.

The documentation for this struct was generated from the following file: