From e097d644172ccbf4377eaf3b5ee082034e02329b Mon Sep 17 00:00:00 2001
From: Nick Mathewson <nickm@torproject.org>
Date: Fri, 23 Sep 2022 15:42:03 -0400
Subject: [PATCH] A basic configuration type for a bridge.

This type goes in tor-guardmgr, since that's where decisions about
circuits' first hops are made.

There are a lot of "todo"s here for us to resolve.
---
 crates/tor-guardmgr/Cargo.toml           |  7 +++-
 crates/tor-guardmgr/semver.md            |  2 ++
 crates/tor-guardmgr/src/bridge.rs        | 15 +++++++++
 crates/tor-guardmgr/src/bridge/config.rs | 41 ++++++++++++++++++++++++
 crates/tor-guardmgr/src/lib.rs           |  2 ++
 5 files changed, 66 insertions(+), 1 deletion(-)
 create mode 100644 crates/tor-guardmgr/semver.md
 create mode 100644 crates/tor-guardmgr/src/bridge.rs
 create mode 100644 crates/tor-guardmgr/src/bridge/config.rs

diff --git a/crates/tor-guardmgr/Cargo.toml b/crates/tor-guardmgr/Cargo.toml
index 4bf7d1603..57cd52db2 100644
--- a/crates/tor-guardmgr/Cargo.toml
+++ b/crates/tor-guardmgr/Cargo.toml
@@ -12,7 +12,12 @@ categories = ["network-programming", "cryptography"]
 repository = "https://gitlab.torproject.org/tpo/core/arti.git/"
 
 [features]
-default = []
+default = ["bridge-client"]
+
+# Support for using bridges as a client. Note that this is not the same as
+# other crates' pt-client feature, since here we are not concerned with
+# pluggable transports necessarily.
+bridge-client = []
 
 # Enable testing-only APIs.  APIs under this feature are not
 # covered by semver.
diff --git a/crates/tor-guardmgr/semver.md b/crates/tor-guardmgr/semver.md
new file mode 100644
index 000000000..31f4f364e
--- /dev/null
+++ b/crates/tor-guardmgr/semver.md
@@ -0,0 +1,2 @@
+MODIFIED: New APIs (not implemented) for bridges.
+
diff --git a/crates/tor-guardmgr/src/bridge.rs b/crates/tor-guardmgr/src/bridge.rs
new file mode 100644
index 000000000..ba7226b5c
--- /dev/null
+++ b/crates/tor-guardmgr/src/bridge.rs
@@ -0,0 +1,15 @@
+//! Code to configure and manage a set of bridge relays.
+//!
+//! A bridge relay, or "bridge" is a tor relay not listed as part of Tor
+//! directory, in order to prevent censors from blocking it.  Instead, clients
+//! learn about bridges out-of-band, and contact them either directly or via a
+//! pluggable transport.
+//!
+//! When a client is configured to use bridges, it uses them in place of its
+//! regular set of guards in building the first hop of its circuits.
+//
+// TODO pt-client: Put this whole module behind a "bridge" feature?
+
+mod config;
+
+pub use config::Bridge;
diff --git a/crates/tor-guardmgr/src/bridge/config.rs b/crates/tor-guardmgr/src/bridge/config.rs
new file mode 100644
index 000000000..d2afbcae6
--- /dev/null
+++ b/crates/tor-guardmgr/src/bridge/config.rs
@@ -0,0 +1,41 @@
+//! Configuration logic and types for bridges.
+#![allow(dead_code)] // TODO pt-client: remove.
+
+use tor_linkspec::ChannelMethod;
+use tor_llcrypto::pk::{ed25519::Ed25519Identity, rsa::RsaIdentity};
+
+/// A relay not listed on the main tor network, used for anticensorship.
+///
+/// This object represents a bridge as configured by the user or by software
+/// running on the user's behalf.
+#[derive(Debug, Clone)]
+// TODO pt-client: Derive builder and associated config types.
+pub struct Bridge {
+    // TODO pt-client: I am not sold on this exact representation for Bridge; it
+    // needs to be something like this, but not necessarily this exact set of
+    // members.
+    //
+    /// Address and transport via which the bridge can be reached, and
+    /// the parameters for those transports.
+    addrs: ChannelMethod,
+
+    /// The RSA identity of the bridge.
+    rsa_id: RsaIdentity,
+
+    /// The Ed25519 identity of the bridge.
+    ed_id: Option<Ed25519Identity>,
+}
+// TODO pt-client: when implementing deserialization for this type, make sure
+// that it can accommodate a large variety of possible configurations methods,
+// and check that the toml looks okay.  For discussion see
+// https://gitlab.torproject.org/tpo/core/arti/-/merge_requests/704/diffs#note_2835271
+
+// TODO pt-client Additionally, make sure that Bridge can be deserialized from a string,
+// when that string is a "bridge" line.
+
+// TODO pt-client We want a "list of bridges'" configuration type
+//
+// TODO pt-client we want a "should we use bridges at this moment"
+// configuration object.
+//
+// (These last two might be part of the same configuration type.)
diff --git a/crates/tor-guardmgr/src/lib.rs b/crates/tor-guardmgr/src/lib.rs
index c4634c52d..db29292b7 100644
--- a/crates/tor-guardmgr/src/lib.rs
+++ b/crates/tor-guardmgr/src/lib.rs
@@ -153,6 +153,8 @@ use tor_netdir::{params::NetParameters, NetDir, Relay};
 use tor_persist::{DynStorageHandle, StateMgr};
 use tor_rtcompat::Runtime;
 
+#[cfg(feature = "bridge-client")]
+pub mod bridge;
 mod daemon;
 mod dirstatus;
 mod err;