tor_proto/client/circuit/
padding.rs

1//! Definitions for circuit padding.
2//!
3//! This module defines the API for a circuit padder, which is divided into two parts:
4//! a [`PaddingController`] and [`PaddingEventStream`].
5//!
6//! When the `circ-padding` feature is enabled, the [`PaddingController`] is used
7//! to tell a set of padding machines about incoming and outgoing
8//! traffic to a circuit hop,
9//! and the [`PaddingEventStream`] is used to decide when to send padding to that hop.
10//!
11//! When `circ-padding` is not enabled, both types are empty, and do nothing.
12//!
13//! # Padding event semantics
14//!
15//! Our events here are fairly tightly coupled
16//! to the semantics provided by [`maybenot`].
17//!
18//! In brief, `maybenot` assumes:
19//!   * That incoming traffic arrives on a queue,
20//!     then is decrypted and sorted into "normal" and "padding".
21//!   * That outgoing traffic (normal or padding) is placed onto a queue,
22//!     and then eventually sent.
23//!
24//! For each of these cases, the circuit/tunnnel reactor
25//! needs to call an appropriate method on [`PaddingController`]
26//! to inform each hop's padding machines about the event.
27//!
28//! See the [`maybenot`] documentation for more information about when,
29//! exactly, each method needs to be invoked.
30//!
31//! # Design considerations
32//!
33//! We expect that a substantial fraction of all circuit hops
34//! will require padding in some form.
35//! Because of this, we've taken some effort to optimize the
36//! storage overhead of our padding state.
37//!
38//! [`maybenot`]: https://docs.rs/maybenot/latest/maybenot/index.html
39
40cfg_if::cfg_if! {
41    if #[cfg(feature = "circ-padding")] {
42        mod maybenot_padding;
43        use maybenot_padding as padding_impl;
44        pub(crate) use maybenot_padding::{Replace, Bypass};
45    } else {
46        mod no_padding;
47        use no_padding as padding_impl;
48    }
49}
50
51// These types are made public using the super-experimental circ-padding-manual feature.
52//
53// TODO circpad: When we stabilize padding support, we should probably rename these,
54// since they are not exclusively for circuits: They can also be used to send padding to
55// padding on channels.
56#[cfg(feature = "circ-padding-manual")]
57pub use maybenot_padding::{CircuitPadder, CircuitPadderConfig, CircuitPadderConfigError};
58
59pub(crate) use padding_impl::{
60    PaddingController, PaddingEvent, PaddingEventStream, QueuedCellPaddingInfo, SendPadding,
61    StartBlocking, new_padding,
62};
tor_proto/client/circuit/padding.rs

tor_proto/client/circuit/
padding.rs
