2 * Copyright (c) 2017-2019, The Tor Project, Inc. */
3 /* See LICENSE for licensing information */
6 * \file circuitpadding.h
7 * \brief Header file for circuitpadding.c.
10 #ifndef TOR_CIRCUITPADDING_H
11 #define TOR_CIRCUITPADDING_H
13 #include "src/trunnel/circpad_negotiation.h"
14 #include "lib/evloop/timers.h"
17 struct origin_circuit_t
;
21 * Signed error return with the specific property that negative
22 * values mean error codes of various semantics, 0 means success,
23 * and positive values are unused.
25 * XXX: Tor uses this concept a lot but just calls it int. Should we move
26 * this somewhere centralized? Where?
28 typedef int signed_error_t
;
31 * These constants specify the types of events that can cause
32 * transitions between state machine states.
34 * Note that SENT and RECV are relative to this endpoint. For
35 * relays, SENT means packets destined towards the client and
36 * RECV means packets destined towards the relay. On the client,
37 * SENT means packets destined towards the relay, where as RECV
38 * means packets destined towards the client.
41 /* A non-padding cell was received. */
42 CIRCPAD_EVENT_NONPADDING_RECV
= 0,
43 /* A non-padding cell was sent. */
44 CIRCPAD_EVENT_NONPADDING_SENT
= 1,
45 /* A padding cell (RELAY_COMMAND_DROP) was sent. */
46 CIRCPAD_EVENT_PADDING_SENT
= 2,
47 /* A padding cell was received. */
48 CIRCPAD_EVENT_PADDING_RECV
= 3,
49 /* We tried to schedule padding but we ended up picking the infinity bin
50 * which means that padding was delayed infinitely */
51 CIRCPAD_EVENT_INFINITY
= 4,
52 /* All histogram bins are empty (we are out of tokens) */
53 CIRCPAD_EVENT_BINS_EMPTY
= 5,
54 /* just a counter of the events above */
55 CIRCPAD_EVENT_LENGTH_COUNT
= 6
57 #define CIRCPAD_NUM_EVENTS ((int)CIRCPAD_EVENT_LENGTH_COUNT+1)
59 /** Boolean type that says if we decided to transition states or not */
61 CIRCPAD_STATE_UNCHANGED
= 0,
62 CIRCPAD_STATE_CHANGED
= 1
65 /** The type for the things in histogram bins (aka tokens) */
66 typedef uint32_t circpad_hist_token_t
;
68 /** The type for histogram indexes (needs to be negative for errors) */
69 typedef int8_t circpad_hist_index_t
;
71 /** The type for absolute time, from monotime_absolute_usec() */
72 typedef uint64_t circpad_time_t
;
74 /** The type for timer delays, in microseconds */
75 typedef uint32_t circpad_delay_t
;
78 * An infinite padding cell delay means don't schedule any padding --
79 * simply wait until a different event triggers a transition.
81 * This means that the maximum delay we can scedule is UINT32_MAX-1
82 * microseconds, or about 4300 seconds (1.25 hours).
83 * XXX: Is this enough if we want to simulate light, intermittent
84 * activity on an onion service?
86 #define CIRCPAD_DELAY_INFINITE (UINT32_MAX)
89 * Macro to clarify when we're checking the infinity bin.
91 * Works with either circpad_state_t or circpad_machine_runtime_t
93 #define CIRCPAD_INFINITY_BIN(mi) ((mi)->histogram_len-1)
96 * These constants form a bitfield that specifies when a state machine
97 * should be applied to a circuit.
99 * If any of these elements is set, then the circuit will be tested against
100 * that specific condition. If an element is unset, then we don't test it.
101 * (E.g. If neither NO_STREAMS or STREAMS are set, then we will not care
102 * whether a circuit has streams attached when we apply a state machine)
104 * The helper function circpad_circuit_state() converts circuit state
105 * flags into this more compact representation.
108 /* Only apply machine if the circuit is still building */
109 CIRCPAD_CIRC_BUILDING
= 1<<0,
110 /* Only apply machine if the circuit is open */
111 CIRCPAD_CIRC_OPENED
= 1<<1,
112 /* Only apply machine if the circuit has no attached streams */
113 CIRCPAD_CIRC_NO_STREAMS
= 1<<2,
114 /* Only apply machine if the circuit has attached streams */
115 CIRCPAD_CIRC_STREAMS
= 1<<3,
116 /* Only apply machine if the circuit still allows RELAY_EARLY cells */
117 CIRCPAD_CIRC_HAS_RELAY_EARLY
= 1<<4,
118 /* Only apply machine if the circuit has depleted its RELAY_EARLY cells
120 CIRCPAD_CIRC_HAS_NO_RELAY_EARLY
= 1<<5
121 } circpad_circuit_state_t
;
123 /** Bitmask that says "apply this machine to all states" */
124 #define CIRCPAD_STATE_ALL \
125 (CIRCPAD_CIRC_BUILDING|CIRCPAD_CIRC_OPENED| \
126 CIRCPAD_CIRC_STREAMS|CIRCPAD_CIRC_NO_STREAMS| \
127 CIRCPAD_CIRC_HAS_RELAY_EARLY|CIRCPAD_CIRC_HAS_NO_RELAY_EARLY)
130 * A compact circuit purpose bitfield mask that allows us to compactly
131 * specify which circuit purposes a machine should apply to.
133 * The helper function circpad_circ_purpose_to_mask() converts circuit
134 * purposes into bit positions in this bitmask.
136 typedef uint32_t circpad_purpose_mask_t
;
138 /** Bitmask that says "apply this machine to all purposes". */
139 #define CIRCPAD_PURPOSE_ALL (0xFFFFFFFF)
142 * This type specifies all of the conditions that must be met before
143 * a client decides to initiate padding on a circuit.
145 * A circuit must satisfy every sub-field in this type in order
146 * to be considered to match the conditions.
148 typedef struct circpad_machine_conditions_t
{
149 /** Only apply the machine *if* the circuit has at least this many hops */
150 unsigned min_hops
: 3;
152 /** Only apply the machine *if* vanguards are enabled */
153 unsigned requires_vanguards
: 1;
156 * This machine is ok to use if reduced padding is set in consensus
157 * or torrc. This machine will still be applied even if reduced padding
158 * is not set; this flag only acts to exclude machines that don't have
159 * it set when reduced padding is requested. Therefore, reduced padding
160 * machines should appear at the lowest priority in the padding machine
161 * lists (aka first in the list), so that non-reduced padding machines
162 * for the same purpose are given a chance to apply when reduced padding
163 * is not requested. */
164 unsigned reduced_padding_ok
: 1;
166 /** Only apply the machine *if* the circuit's state matches any of
167 * the bits set in this bitmask. */
168 circpad_circuit_state_t state_mask
;
170 /** Only apply a machine *if* the circuit's purpose matches one
171 * of the bits set in this bitmask */
172 circpad_purpose_mask_t purpose_mask
;
174 } circpad_machine_conditions_t
;
177 * Token removal strategy options.
179 * The WTF-PAD histograms are meant to specify a target distribution to shape
180 * traffic towards. This is accomplished by removing tokens from the histogram
181 * when either padding or non-padding cells are sent.
183 * When we see a non-padding cell at a particular time since the last cell, you
184 * remove a token from the corresponding delay bin. These flags specify
185 * which bin to choose if that bin is already empty.
188 /** Don't remove any tokens */
189 CIRCPAD_TOKEN_REMOVAL_NONE
= 0,
191 * Remove from the first non-zero higher bin index when current is zero.
192 * This is the recommended strategy from the Adaptive Padding paper. */
193 CIRCPAD_TOKEN_REMOVAL_HIGHER
= 1,
194 /** Remove from the first non-zero lower bin index when current is empty. */
195 CIRCPAD_TOKEN_REMOVAL_LOWER
= 2,
196 /** Remove from the closest non-zero bin index when current is empty. */
197 CIRCPAD_TOKEN_REMOVAL_CLOSEST
= 3,
198 /** Remove from the closest bin by time value (since bins are
199 * exponentially spaced). */
200 CIRCPAD_TOKEN_REMOVAL_CLOSEST_USEC
= 4,
201 /** Only remove from the exact bin corresponding to this delay. If
202 * the bin is 0, simply do nothing. Don't pick another bin. */
203 CIRCPAD_TOKEN_REMOVAL_EXACT
= 5
207 * Distribution types supported by circpad_distribution_sample().
209 * These can be used instead of histograms for the inter-packet
210 * timing distribution, or to specify a distribution on the number
211 * of cells that can be sent while in a specific state of the state
214 * Each distribution takes up to two parameters which are described below. */
216 /* No probability distribution is used */
217 CIRCPAD_DIST_NONE
= 0,
218 /* Uniform distribution: param1 is lower bound and param2 is upper bound */
219 CIRCPAD_DIST_UNIFORM
= 1,
220 /* Logistic distribution: param1 is Mu, param2 is sigma. */
221 CIRCPAD_DIST_LOGISTIC
= 2,
222 /* Log-logistic distribution: param1 is Alpha, param2 is 1.0/Beta */
223 CIRCPAD_DIST_LOG_LOGISTIC
= 3,
224 /* Geometric distribution: param1 is 'p' (success probability) */
225 CIRCPAD_DIST_GEOMETRIC
= 4,
226 /* Weibull distribution: param1 is k, param2 is Lambda */
227 CIRCPAD_DIST_WEIBULL
= 5,
228 /* Generalized Pareto distribution: param1 is sigma, param2 is xi */
229 CIRCPAD_DIST_PARETO
= 6
230 } circpad_distribution_type_t
;
233 * Distribution information.
235 * This type specifies a specific distribution above, as well as
236 * up to two parameters for that distribution. The specific
237 * per-distribution meaning of these parameters is specified
238 * in circpad_distribution_sample().
240 typedef struct circpad_distribution_t
{
241 circpad_distribution_type_t type
;
244 } circpad_distribution_t
;
246 /** State number type. Represents current state of state machine. */
247 typedef uint16_t circpad_statenum_t
;
248 #define CIRCPAD_STATENUM_MAX (UINT16_MAX)
250 /** A histogram is used to sample padding delays given a machine state. This
251 * constant defines the maximum histogram width (i.e. the max number of bins).
253 * The current limit is arbitrary and could be raised if there is a need,
254 * however too many bins will be hard to serialize in the future.
256 * Memory concerns are not so great here since the corresponding histogram and
257 * histogram_edges arrays are global and not per-circuit.
259 * If we ever upgrade this to a value that can't be represented by 8-bits we
260 * also need to upgrade circpad_hist_index_t.
262 #define CIRCPAD_MAX_HISTOGRAM_LEN (100)
265 * A state of a padding state machine. The information here are immutable and
266 * represent the initial form of the state; it does not get updated as things
267 * happen. The mutable information that gets updated in runtime are carried in
268 * a circpad_machine_runtime_t.
270 * This struct describes the histograms and parameters of a single
271 * state in the adaptive padding machine. Instances of this struct
272 * exist in global circpad machine definitions that come from torrc
275 typedef struct circpad_state_t
{
277 * If a histogram is used for this state, this specifies the number of bins
278 * of this histogram. Histograms must have at least 2 bins.
280 * In particular, the following histogram:
285 * 9 | | | +---------+
288 * 6 +----+ Bin+-----+ | +---------------+
290 * | Bin| | Bin | Bin | Bin #4 | Bin #5 |
291 * | #0 | | #2 | #3 | | (infinity bin)|
294 * 0 +----+----+-----+-----+---------+---------------+
295 * 0 100 200 350 500 1000 ∞ microseconds
297 * would be specified the following way:
299 * histogram[] = { 6, 10, 6, 7, 9, 6 }
300 * histogram_edges[] = { 0, 100, 200, 350, 500, 1000 }
302 * The final bin is called the "infinity bin" and if it's chosen we don't
303 * schedule any padding. The infinity bin is strange because its lower edge
304 * is the max value of possible non-infinite delay allowed by this histogram,
305 * and its upper edge is CIRCPAD_DELAY_INFINITE. You can tell if the infinity
306 * bin is chosen by inspecting its bin index or inspecting its upper edge.
308 * If a delay probability distribution is used for this state, this is set
310 circpad_hist_index_t histogram_len
;
311 /** The histogram itself: an array of uint16s of tokens, whose
312 * widths are exponentially spaced, in microseconds.
314 * This array must have histogram_len elements that are strictly
315 * monotonically increasing. */
316 circpad_hist_token_t histogram
[CIRCPAD_MAX_HISTOGRAM_LEN
];
317 /* The histogram bin edges in usec.
319 * Each element of this array specifies the left edge of the corresponding
320 * bin. The rightmost edge is always infinity and is not specified in this
323 * This array must have histogram_len elements. */
324 circpad_delay_t histogram_edges
[CIRCPAD_MAX_HISTOGRAM_LEN
+1];
325 /** Total number of tokens in this histogram. This is a constant and is *not*
326 * decremented every time we spend a token. It's used for initializing and
327 * refilling the histogram. */
328 uint32_t histogram_total_tokens
;
331 * Represents a delay probability distribution (aka IAT distribution). It's a
332 * parametrized way of encoding inter-packet delay information in
333 * microseconds. It can be used instead of histograms.
335 * If it is used, token_removal below must be set to
336 * CIRCPAD_TOKEN_REMOVAL_NONE.
338 * Start_usec, range_sec, and rtt_estimates are still applied to the
339 * results of sampling from this distribution (range_sec is used as a max).
341 circpad_distribution_t iat_dist
;
342 /* If a delay probability distribution is used, this is used as the max
343 * value we can sample from the distribution. However, RTT measurements and
344 * dist_added_shift gets applied on top of this value to derive the final
346 circpad_delay_t dist_max_sample_usec
;
347 /* If a delay probability distribution is used and this is set, we will add
348 * this value on top of the value sampled from the IAT distribution to
349 * derive the final padding delay (We also add the RTT measurement if it's
351 circpad_delay_t dist_added_shift_usec
;
354 * The length dist is a parameterized way of encoding how long this
355 * state machine runs in terms of sent padding cells or all
356 * sent cells. Values are sampled from this distribution, clamped
357 * to max_len, and then start_len is added to that value.
359 * It may be specified instead of or in addition to
360 * the infinity bins and bins empty conditions. */
361 circpad_distribution_t length_dist
;
362 /** A minimum length value, added to the output of length_dist */
363 uint16_t start_length
;
364 /** A cap on the length value that can be sampled from the length_dist */
367 /** Should we decrement length when we see a nonpadding packet?
368 * XXX: Are there any machines that actually want to set this to 0? There may
369 * not be. OTOH, it's only a bit.. */
370 unsigned length_includes_nonpadding
: 1;
373 * This is an array that specifies the next state to transition to upon
374 * receipt an event matching the indicated array index.
376 * This aborts our scheduled packet and switches to the state
377 * corresponding to the index of the array. Tokens are filled upon
380 * States are allowed to transition to themselves, which means re-schedule
381 * a new padding timer. They are also allowed to temporarily "transition"
382 * to the "IGNORE" and "CANCEL" pseudo-states. See #defines below
383 * for details on state behavior and meaning.
385 circpad_statenum_t next_state
[CIRCPAD_NUM_EVENTS
];
388 * If true, estimate the RTT from this relay to the exit/website and add that
389 * to start_usec for use as the histogram bin 0 start delay.
391 * Right now this is only supported for relay-side state machines.
393 unsigned use_rtt_estimate
: 1;
395 /** This specifies the token removal strategy to use upon padding and
396 * non-padding activity. */
397 circpad_removal_t token_removal
;
401 * The start state for this machine.
403 * In the original WTF-PAD, this is only used for transition to/from
404 * the burst state. All other fields are not used. But to simplify the
405 * code we've made it a first-class state. This has no performance
406 * consequences, but may make naive serialization of the state machine
407 * large, if we're not careful about how we represent empty fields.
409 #define CIRCPAD_STATE_START 0
412 * The burst state for this machine.
414 * In the original Adaptive Padding algorithm and in WTF-PAD
415 * (https://www.freehaven.net/anonbib/cache/ShWa-Timing06.pdf and
416 * https://www.cs.kau.se/pulls/hot/thebasketcase-wtfpad/), the burst
417 * state serves to detect bursts in traffic. This is done by using longer
418 * delays in its histogram, which represent the expected delays between
419 * bursts of packets in the target stream. If this delay expires without a
420 * real packet being sent, the burst state sends a padding packet and then
421 * immediately transitions to the gap state, which is used to generate
422 * a synthetic padding packet train. In this implementation, this transition
423 * needs to be explicitly specified in the burst state's transition events.
425 * Because of this flexibility, other padding mechanisms can transition
426 * between these two states arbitrarily, to encode other dynamics of
429 #define CIRCPAD_STATE_BURST 1
432 * The gap state for this machine.
434 * In the original Adaptive Padding algorithm and in WTF-PAD, the gap
435 * state serves to simulate an artificial packet train composed of padding
436 * packets. It does this by specifying much lower inter-packet delays than
437 * the burst state, and transitioning back to itself after padding is sent
438 * if these timers expire before real traffic is sent. If real traffic is
439 * sent, it transitions back to the burst state.
441 * Again, in this implementation, these transitions must be specified
442 * explicitly, and other transitions are also permitted.
444 #define CIRCPAD_STATE_GAP 2
447 * End is a pseudo-state that causes the machine to go completely
448 * idle, and optionally get torn down (depending on the
449 * value of circpad_machine_spec_t.should_negotiate_end)
451 * End MUST NOT occupy a slot in the machine state array.
453 #define CIRCPAD_STATE_END CIRCPAD_STATENUM_MAX
456 * "Ignore" is a pseudo-state that means "do not react to this
459 * "Ignore" MUST NOT occupy a slot in the machine state array.
461 #define CIRCPAD_STATE_IGNORE (CIRCPAD_STATENUM_MAX-1)
464 * "Cancel" is a pseudo-state that means "cancel pending timers,
465 * but remain in your current state".
467 * Cancel MUST NOT occupy a slot in the machine state array.
469 #define CIRCPAD_STATE_CANCEL (CIRCPAD_STATENUM_MAX-2)
472 * Since we have 3 pseudo-states, the max state array length is
473 * up to one less than cancel's statenum.
475 #define CIRCPAD_MAX_MACHINE_STATES (CIRCPAD_STATE_CANCEL-1)
478 * Mutable padding machine info.
480 * This structure contains mutable information about a padding
481 * machine. The mutable information must be kept separate because
482 * it exists per-circuit, where as the machines themselves are global.
483 * This separation is done to conserve space in the circuit structure.
485 * This is the per-circuit state that changes regarding the global state
486 * machine. Some parts of it are optional (ie NULL).
488 * XXX: Play with layout to minimize space on x64 Linux (most common relay).
490 typedef struct circpad_machine_runtime_t
{
491 /** The callback pointer for the padding callbacks.
493 * These timers stick around the machineinfo until the machineinfo's circuit
494 * is closed, at which point the timer is cancelled. For this reason it's
495 * safe to assume that the machineinfo exists if this timer gets
497 tor_timer_t
*padding_timer
;
499 /** The circuit for this machine */
500 struct circuit_t
*on_circ
;
502 /** A mutable copy of the histogram for the current state.
503 * NULL if remove_tokens is false for that state */
504 circpad_hist_token_t
*histogram
;
505 /** Length of the above histogram.
506 * XXX: This field *could* be removed at the expense of added
507 * complexity+overhead for reaching back into the immutable machine
508 * state every time we need to inspect the histogram. It's only a byte,
509 * though, so it seemed worth it.
511 circpad_hist_index_t histogram_len
;
512 /** Remove token from this index upon sending padding */
513 circpad_hist_index_t chosen_bin
;
515 /** Stop padding/transition if this many cells sent */
516 uint64_t state_length
;
517 #define CIRCPAD_STATE_LENGTH_INFINITE UINT64_MAX
519 /** A scaled count of padding packets sent, used to limit padding overhead.
520 * When this reaches UINT16_MAX, we cut it and nonpadding_sent in half. */
521 uint16_t padding_sent
;
522 /** A scaled count of non-padding packets sent, used to limit padding
523 * overhead. When this reaches UINT16_MAX, we cut it and padding_sent in
525 uint16_t nonpadding_sent
;
528 * EWMA estimate of the RTT of the circuit from this hop
529 * to the exit end, in microseconds. */
530 circpad_delay_t rtt_estimate_usec
;
533 * The last time we got an event relevant to estimating
534 * the RTT. Monotonic time in microseconds since system
537 circpad_time_t last_received_time_usec
;
540 * The time at which we scheduled a non-padding packet,
541 * or selected an infinite delay.
543 * Monotonic time in microseconds since system start.
544 * This is 0 if we haven't chosen a padding delay.
546 circpad_time_t padding_scheduled_at_usec
;
548 /** What state is this machine in? */
549 circpad_statenum_t current_state
;
552 * True if we have scheduled a timer for padding.
554 * This is 1 if a timer is pending. It is 0 if
555 * no timer is scheduled. (It can be 0 even when
556 * padding_was_scheduled_at_usec is non-zero).
558 unsigned is_padding_timer_scheduled
: 1;
561 * If this is true, we have seen full duplex behavior.
562 * Stop updating the RTT.
564 unsigned stop_rtt_update
: 1;
566 /** Max number of padding machines on each circuit. If changed,
567 * also ensure the machine_index bitwith supports the new size. */
568 #define CIRCPAD_MAX_MACHINES (2)
569 /** Which padding machine index was this for.
570 * (make sure changes to the bitwidth can support the
571 * CIRCPAD_MAX_MACHINES define). */
572 unsigned machine_index
: 1;
574 } circpad_machine_runtime_t
;
576 /** Helper macro to get an actual state machine from a machineinfo */
577 #define CIRCPAD_GET_MACHINE(machineinfo) \
578 ((machineinfo)->on_circ->padding_machine[(machineinfo)->machine_index])
581 * This specifies a particular padding machine to use after negotiation.
583 * The constants for machine_num_t are in trunnel.
584 * We want to be able to define extra numbers in the consensus/torrc, though.
586 typedef uint8_t circpad_machine_num_t
;
588 /** Global state machine structure from the consensus */
589 typedef struct circpad_machine_spec_t
{
590 /** Global machine number */
591 circpad_machine_num_t machine_num
;
593 /** Which machine index slot should this machine go into in
594 * the array on the circuit_t */
595 unsigned machine_index
: 1;
597 /** Send a padding negotiate to shut down machine at end state? */
598 unsigned should_negotiate_end
: 1;
600 // These next three fields are origin machine-only...
601 /** Origin side or relay side */
602 unsigned is_origin_side
: 1;
604 /** Which hop in the circuit should we send padding to/from?
605 * 1-indexed (ie: hop #1 is guard, #2 middle, #3 exit). */
606 unsigned target_hopnum
: 3;
608 /** This machine only kills fascists if the following conditions are met. */
609 circpad_machine_conditions_t conditions
;
611 /** How many padding cells can be sent before we apply overhead limits?
612 * XXX: Note that we can only allow up to 64k of padding cells on an
613 * otherwise quiet circuit. Is this enough? It's 33MB. */
614 uint16_t allowed_padding_count
;
616 /** Padding percent cap: Stop padding if we exceed this percent overhead.
617 * 0 means no limit. Overhead is defined as percent of total traffic, so
618 * that we can use 0..100 here. This is the same definition as used in
620 uint8_t max_padding_percent
;
622 /** State array: indexed by circpad_statenum_t */
623 circpad_state_t
*states
;
626 * Number of states this machine has (ie: length of the states array).
627 * XXX: This field is not needed other than for safety. */
628 circpad_statenum_t num_states
;
629 } circpad_machine_spec_t
;
631 void circpad_new_consensus_params(const networkstatus_t
*ns
);
634 * The following are event call-in points that are of interest to
635 * the state machines. They are called during cell processing. */
636 void circpad_deliver_unrecognized_cell_events(struct circuit_t
*circ
,
637 cell_direction_t dir
);
638 void circpad_deliver_sent_relay_cell_events(struct circuit_t
*circ
,
639 uint8_t relay_command
);
640 void circpad_deliver_recognized_relay_cell_events(struct circuit_t
*circ
,
641 uint8_t relay_command
,
642 crypt_path_t
*layer_hint
);
644 /** Cell events are delivered by the above delivery functions */
645 void circpad_cell_event_nonpadding_sent(struct circuit_t
*on_circ
);
646 void circpad_cell_event_nonpadding_received(struct circuit_t
*on_circ
);
647 void circpad_cell_event_padding_sent(struct circuit_t
*on_circ
);
648 void circpad_cell_event_padding_received(struct circuit_t
*on_circ
);
650 /** Internal events are events the machines send to themselves */
652 circpad_internal_event_infinity(circpad_machine_runtime_t
*mi
);
654 circpad_internal_event_bins_empty(circpad_machine_runtime_t
*);
655 circpad_decision_t
circpad_internal_event_state_length_up(
656 circpad_machine_runtime_t
*);
658 /** Machine creation events are events that cause us to set up or
659 * tear down padding state machines. */
660 void circpad_machine_event_circ_added_hop(struct origin_circuit_t
*on_circ
);
661 void circpad_machine_event_circ_built(struct origin_circuit_t
*circ
);
662 void circpad_machine_event_circ_purpose_changed(struct origin_circuit_t
*circ
);
663 void circpad_machine_event_circ_has_streams(struct origin_circuit_t
*circ
);
664 void circpad_machine_event_circ_has_no_streams(struct origin_circuit_t
*circ
);
666 circpad_machine_event_circ_has_no_relay_early(struct origin_circuit_t
*circ
);
668 void circpad_machines_init(void);
669 void circpad_machines_free(void);
671 void circpad_machine_states_init(circpad_machine_spec_t
*machine
,
672 circpad_statenum_t num_states
);
674 void circpad_circuit_free_all_machineinfos(struct circuit_t
*circ
);
676 bool circpad_padding_is_from_expected_hop(struct circuit_t
*circ
,
677 crypt_path_t
*from_hop
);
679 /** Serializaton functions for writing to/from torrc and consensus */
680 char *circpad_machine_spec_to_string(const circpad_machine_spec_t
*machine
);
681 const circpad_machine_spec_t
*circpad_string_to_machine(const char *str
);
683 /* Padding negotiation between client and middle */
684 signed_error_t
circpad_handle_padding_negotiate(struct circuit_t
*circ
,
685 struct cell_t
*cell
);
686 signed_error_t
circpad_handle_padding_negotiated(struct circuit_t
*circ
,
688 crypt_path_t
*layer_hint
);
689 signed_error_t
circpad_negotiate_padding(struct origin_circuit_t
*circ
,
690 circpad_machine_num_t machine
,
691 uint8_t target_hopnum
,
693 bool circpad_padding_negotiated(struct circuit_t
*circ
,
694 circpad_machine_num_t machine
,
698 MOCK_DECL(circpad_decision_t
,
699 circpad_machine_schedule_padding
,(circpad_machine_runtime_t
*));
701 MOCK_DECL(circpad_decision_t
,
702 circpad_machine_spec_transition
, (circpad_machine_runtime_t
*mi
,
703 circpad_event_t event
));
705 circpad_decision_t
circpad_send_padding_cell_for_callback(
706 circpad_machine_runtime_t
*mi
);
708 #ifdef CIRCUITPADDING_PRIVATE
709 STATIC circpad_delay_t
710 circpad_machine_sample_delay(circpad_machine_runtime_t
*mi
);
713 circpad_machine_reached_padding_limit(circpad_machine_runtime_t
*mi
);
715 STATIC circpad_delay_t
716 circpad_histogram_bin_to_usec(const circpad_machine_runtime_t
*mi
,
717 circpad_hist_index_t bin
);
719 STATIC
const circpad_state_t
*
720 circpad_machine_current_state(const circpad_machine_runtime_t
*mi
);
722 STATIC
void circpad_machine_remove_token(circpad_machine_runtime_t
*mi
);
724 STATIC circpad_hist_index_t
circpad_histogram_usec_to_bin(
725 const circpad_machine_runtime_t
*mi
,
728 STATIC circpad_machine_runtime_t
*circpad_circuit_machineinfo_new(
729 struct circuit_t
*on_circ
,
731 STATIC
void circpad_machine_remove_higher_token(circpad_machine_runtime_t
*mi
,
732 circpad_delay_t target_bin_us
);
733 STATIC
void circpad_machine_remove_lower_token(circpad_machine_runtime_t
*mi
,
734 circpad_delay_t target_bin_us
);
735 STATIC
void circpad_machine_remove_closest_token(circpad_machine_runtime_t
*mi
,
736 circpad_delay_t target_bin_us
,
738 STATIC
void circpad_machine_setup_tokens(circpad_machine_runtime_t
*mi
);
740 MOCK_DECL(STATIC signed_error_t
,
741 circpad_send_command_to_hop
,(struct origin_circuit_t
*circ
, uint8_t hopnum
,
742 uint8_t relay_command
, const uint8_t *payload
,
743 ssize_t payload_len
));
745 STATIC circpad_delay_t
746 histogram_get_bin_upper_bound(const circpad_machine_runtime_t
*mi
,
747 circpad_hist_index_t bin
);
749 #ifdef TOR_UNIT_TESTS
750 extern smartlist_t
*origin_padding_machines
;
751 extern smartlist_t
*relay_padding_machines
;
754 register_padding_machine(circpad_machine_spec_t
*machine
,
755 smartlist_t
*machine_list
);