Merge pull request rust-bitcoin#147 from nyonson/traffic-stats-interface

Rework traffic stats

Author: nyonson

proxy/Cargo.toml

@@ -14,7 +14,7 @@ spec = "config_spec.toml"
 bitcoin = { version = "0.32.4" }
 tokio = { version = "1", features = ["full"] }
 hex = { package = "hex-conservative", version = "0.2.0" }
-bip324 = { path = "../protocol", features = ["tokio"] }
+bip324 = { version = "0.10.0", path = "../protocol", features = ["tokio"] }
 configure_me = "0.4.0"
 log = "0.4.8"
 env_logger = "0.10"

traffic/CHANGELOG.md

@@ -0,0 +1,8 @@
+# Changelog
+
+## v0.1.0
+
+Initial release.
+
+* The heart of the API is the sans-io `TrafficShaper`.
+* I/O driving wrappers are also exposed `io::ShapedProtocol` and `futures::ShapedProtocol`.

traffic/README.md

@@ -3,7 +3,7 @@
 A traffic analysis resistance layer for BIP-324 encrypted bitcoin connections. Decoy packet and padding strategies are used to obscure communication patterns, attempting to make it harder for network observers to analyze bitcoin peer-to-peer communication patterns. The library follows a *sans I/O* design, but provides I/O drivers for easy entry points.
 
 * **High-level I/O** - `io::ShapedProtocol` (sync) and `futures::ShapedProtocol` (async) handle the complete encrypted connection life-cycle with automatic traffic shaping, including handshake, padding, and decoy generation.
-* **Lower-level components** - `TrafficShaper` manages the timing and generation of traffic obfuscation.
+* **Lower-level components** - `TrafficShaper` manages the timing and generation of traffic obfuscation. It can be used directly if the caller wishes to drive the I/O themselves.
 
 ## Feature Flags
 
@@ -20,17 +20,20 @@ When using the `tokio` feature, the effective MSRV may be higher depending on th
 
 The BIP-324 specification defines *decoy packets* as the primary mechanism for hiding the shape of encrypted traffic. Even with encryption, bitcoin p2p traffic patterns can be highly distinctive to a third party observer. Transactions and blocks have characteristic sizes, message exchanges follow predictable patterns (like initial handshake sequences, pings and pongs), and the timing between messages can reveal protocol state machines. Also, a new block propagates about every ten minutes. An observer monitoring encrypted traffic could potentially identify bitcoin nodes, track transaction propagation, or infer network topology.
 
-This library uses decoy packets in two complementary ways. The first is *padding*, where the library immediately follows genuine packet sends with a decoy packet. This makes it hard for observers to determine where one message ends and another begins. And the second is consistent *background noise*. A separate thread (or task) continuously sends decoy packets, attempting to prevent traffic analysis based on communication patterns and timing.
+This library uses decoy packets in two complementary ways, *packet padding* and *cover traffic*. Padding is where the library immediately follows a genuine packet send with a decoy packet. This makes it hard for observers to determine where one message ends and another begins, hiding the genuine packet size. Cover traffic is decoys continuously sent by a separate thread (or task) attempting to prevent traffic analysis based on communication patterns.
 
 The goal is not to make bitcoin traffic completely unidentifiable, that maybe impossible, but rather to significantly increase the computational and analytical costs for observers. This creates a game of economic tradeoffs, how much bandwidth and processing power should nodes spend on decoy bytes versus how much effort observers must expend to identify bitcoin traffic? The ideal strategies would use minimal decoy bytes to impose maximum analysis costs on observers. Finding these efficient strategies remains an open research area, but even simple random noise raises the bar for passive network surveillance.
 
+*No hard analysis has been done yet on the effectiveness of the following strategies to hide bitcoin p2p channel shape.*
+
 ### Padding Strategies
 
 * `Disabled` - No padding, genuine packet sizes only (default).
-* `Random` - Adds randomly sized decoy packet. Pure noise, no hard analysis has been done on how effective this hides bitcoin p2p channel shape.
+* `Random` - Adds randomly sized decoy packet. Pure noise.
+* *TODO* `Fixed` - Pad a message size to its nearest power of two. A mixnet strategy to make all messages look identical and avoid a randomness pattern which leaks information.
 
 ### Decoy Strategies
 
 * `Disabled` - No automatic decoy packets, genuine writes only (default).
-* `Random` - Sends randomly sized decoy packets at random intervals. Pure noise, no hard analysis has been done on how effective this hides bitcoin p2p channel shape.
-
+* `Random` - Sends randomly sized decoy packets at random intervals. Pure noise.
+* *TODO* `Mimic` - Instead of hiding the bitcoin p2p traffic, embrace it but send even more bitcoin looking things.This could help break any sort of tracking analysis.

traffic/src/futures.rs

@@ -10,7 +10,9 @@ use bip324::futures::{Protocol, ProtocolReader, ProtocolWriter};
 use bip324::io::{Payload, ProtocolError, ProtocolFailureSuggestion};
 use bip324::{Network, Role};
 
-use crate::{TrafficConfig, TrafficShaper, TrafficStats, DEFAULT_CHECK_INTERVAL_MS};
+use crate::{
+    AtomicTrafficStats, TrafficConfig, TrafficShaper, TrafficStats, DEFAULT_CHECK_INTERVAL_MS,
+};
 
 /// Command sent to the writer task.
 struct WriteCommand {
@@ -26,7 +28,7 @@ where
     R: AsyncRead + Unpin + Send,
 {
     reader: ProtocolReader<R>,
-    stats: Arc<TrafficStats>,
+    stats: Arc<AtomicTrafficStats>,
 }
 
 /// Traffic-shaped async protocol writer half.
@@ -112,17 +114,18 @@ where
     where
         W: AsyncWrite + Unpin + Send + 'static,
     {
-        let stats = Arc::new(TrafficStats::new());
-        let mut shaper = TrafficShaper::new(config, stats.clone());
-        let (garbage, decoys) = shaper.handshake();
+        let stats = Arc::new(AtomicTrafficStats::new());
+        let mut shaper = TrafficShaper::new(config);
+        let (garbage, decoys) = shaper.handshake(&stats);
 
         let protocol = Protocol::new(network, role, garbage, decoys, reader, writer).await?;
         let (protocol_reader, protocol_writer) = protocol.into_split();
         let (write_tx, write_rx) = mpsc::unbounded_channel();
 
+        let stats_clone = stats.clone();
         // Task will run as long as the write_tx isn't dropped.
         tokio::spawn(async move {
-            writer_task(write_rx, protocol_writer, shaper).await;
+            writer_task(write_rx, protocol_writer, shaper, stats_clone).await;
         });
 
         Ok(Self {
@@ -196,12 +199,14 @@ impl ShapedProtocolWriter {
 }
 
 /// Writer task that handles both genuine writes and decoy generation.
-async fn writer_task<W>(
+async fn writer_task<W, R>(
     mut write_rx: mpsc::UnboundedReceiver<WriteCommand>,
     mut writer: ProtocolWriter<W>,
-    mut shaper: TrafficShaper,
+    mut shaper: TrafficShaper<R>,
+    stats: Arc<AtomicTrafficStats>,
 ) where
     W: AsyncWrite + Unpin + Send + 'static,
+    R: rand::Rng,
 {
     let mut decoy_interval =
         tokio::time::interval(Duration::from_millis(DEFAULT_CHECK_INTERVAL_MS));
@@ -213,7 +218,7 @@ async fn writer_task<W>(
                 let mut result = Ok(());
 
                 // First, send decoy packet if padding is enabled.
-                if let Some(decoy) = shaper.pad(&cmd.payload) {
+                if let Some(decoy) = shaper.pad(&cmd.payload, &stats) {
                     if let Err(e) = writer.write(&decoy).await {
                         result = Err(e);
                     }
@@ -232,7 +237,7 @@ async fn writer_task<W>(
 
             // Concurrently send decoys.
             _ = decoy_interval.tick() => {
-                if let Some(decoy) = shaper.decoy() {
+                if let Some(decoy) = shaper.decoy(&stats) {
                     // Ignore write errors for decoys - they're best-effort.
                     let _ = writer.write(&decoy).await;
                 }

traffic/src/io.rs

@@ -1,16 +1,18 @@
 //! Blocking I/O traffic shaping wrapper for BIP-324 protocol.
 
+use core::time::Duration;
 use std::io::{Read, Write};
 use std::sync::atomic::{AtomicBool, Ordering};
 use std::sync::{Arc, Mutex};
 use std::thread;
-use std::time::Duration;
 
 use bip324::io::{Payload, Protocol, ProtocolError, ProtocolReader, ProtocolWriter};
 use bip324::{Network, Role};
 use rand::Rng;
 
-use crate::{TrafficConfig, TrafficShaper, TrafficStats, DEFAULT_CHECK_INTERVAL_MS};
+use crate::{
+    AtomicTrafficStats, TrafficConfig, TrafficShaper, TrafficStats, DEFAULT_CHECK_INTERVAL_MS,
+};
 
 /// Shared writer state protected by a mutex.
 struct WriterState<W, R = rand::rngs::StdRng> {
@@ -24,7 +26,7 @@ where
     R: Read,
 {
     reader: ProtocolReader<R>,
-    stats: Arc<TrafficStats>,
+    stats: Arc<AtomicTrafficStats>,
 }
 
 /// Traffic-shaped protocol writer half.
@@ -33,6 +35,7 @@ where
     W: Write,
 {
     writer_state: Arc<Mutex<WriterState<W>>>,
+    stats: Arc<AtomicTrafficStats>,
     shutdown: Arc<AtomicBool>,
     decoy_handle: Option<thread::JoinHandle<()>>,
 }
@@ -110,9 +113,9 @@ where
         reader: R,
         writer: W,
     ) -> Result<Self, ProtocolError> {
-        let stats = Arc::new(TrafficStats::new());
-        let mut shaper = TrafficShaper::new(config, stats.clone());
-        let (garbage, decoys) = shaper.handshake();
+        let stats = Arc::new(AtomicTrafficStats::new());
+        let mut shaper = TrafficShaper::new(config);
+        let (garbage, decoys) = shaper.handshake(&stats);
 
         let protocol = Protocol::new(network, role, garbage, decoys, reader, writer)?;
         let (protocol_reader, protocol_writer) = protocol.into_split();
@@ -126,23 +129,24 @@ where
         let shutdown = Arc::new(AtomicBool::new(false));
         let writer_state_clone = writer_state.clone();
         let shutdown_clone = shutdown.clone();
+        let stats_clone = stats.clone();
         let decoy_handle = thread::spawn(move || {
-            decoy_thread(writer_state_clone, shutdown_clone);
+            decoy_thread(writer_state_clone, stats_clone, shutdown_clone);
         });
 
         Ok(Self {
             reader: ShapedProtocolReader {
                 reader: protocol_reader,
-                stats,
+                stats: stats.clone(),
             },
             writer: ShapedProtocolWriter {
                 writer_state,
                 shutdown,
                 decoy_handle: Some(decoy_handle),
+                stats,
             },
         })
     }
-
     /// Read a packet from the protocol.
     pub fn read(&mut self) -> Result<Payload, ProtocolError> {
         self.reader.read()
@@ -179,7 +183,7 @@ where
     /// Write a payload with traffic shaping.
     pub fn write(&mut self, payload: &Payload) -> Result<(), ProtocolError> {
         let mut state = self.writer_state.lock().unwrap();
-        if let Some(decoy) = state.shaper.pad(payload) {
+        if let Some(decoy) = state.shaper.pad(payload, &self.stats) {
             state.writer.write(&decoy)?;
         }
         state.writer.write(payload)?;
@@ -202,8 +206,11 @@ where
 }
 
 /// Decoy thread that periodically sends decoy packets.
-fn decoy_thread<W, R>(writer_state: Arc<Mutex<WriterState<W, R>>>, shutdown: Arc<AtomicBool>)
-where
+fn decoy_thread<W, R>(
+    writer_state: Arc<Mutex<WriterState<W, R>>>,
+    stats: Arc<AtomicTrafficStats>,
+    shutdown: Arc<AtomicBool>,
+) where
     W: Write,
     R: Rng,
 {
@@ -218,7 +225,7 @@ where
             Err(_) => continue,
         };
 
-        if let Some(decoy) = state.shaper.decoy() {
+        if let Some(decoy) = state.shaper.decoy(&stats) {
             let _ = state.writer.write(&decoy);
         }
     }