Lines
81.63 %
Functions
68.12 %
Branches
100 %
//! Configuration logic for onion service reverse proxy.
use derive_deftly::Deftly;
use serde::{Deserialize, Serialize};
use std::{net::SocketAddr, ops::RangeInclusive, str::FromStr, sync::Arc};
use tor_config::ConfigBuildError;
use tor_config::derive::prelude::*;
use tracing::warn;
#[cfg(unix)]
use std::os::unix::net::SocketAddr as UnixSocketAddr;
/// Configuration for a reverse proxy running for one onion service.
#[derive(Clone, Debug, Deftly, Eq, PartialEq)]
#[derive_deftly(TorConfig)]
#[deftly(tor_config(no_default_trait, pre_build = "Self::validate"))]
pub struct ProxyConfig {
/// A list of rules to apply to incoming requests. If no rule
/// matches, we take the DestroyCircuit action.
#[deftly(tor_config(list(element(clone), listtype = "ProxyRuleList"), default = "vec![]"))]
pub(crate) proxy_ports: Vec<ProxyRule>,
//
// TODO: Someday we may want to allow udp, resolve, etc. If we do, it will
// be via another option, rather than adding another subtype to ProxySource.
}
impl ProxyConfigBuilder {
/// Run checks on this ProxyConfig to ensure that it's valid.
fn validate(&self) -> Result<(), ConfigBuildError> {
// Make sure that every proxy pattern is actually reachable.
let mut covered = rangemap::RangeInclusiveSet::<u16>::new();
for rule in self.proxy_ports.access_opt().iter().flatten() {
let range = &rule.source.0;
if covered.gaps(range).next().is_none() {
return Err(ConfigBuildError::Invalid {
field: "proxy_ports".into(),
problem: format!("Port pattern {} is not reachable", rule.source),
});
covered.insert(range.clone());
// Warn about proxy setups that are likely to be surprising.
let mut any_forward = false;
if let ProxyAction::Forward(_, target) = &rule.target {
any_forward = true;
if !target.is_sufficiently_private() {
// TODO: here and below, we might want to someday
// have a mechanism to suppress these warnings,
// or have them show up only when relevant.
// For now they are unconditional.
// See discussion at #1154.
warn!(
"Onion service target {} does not look like a private address. \
Do you really mean to send connections onto the public internet?",
target
);
if !any_forward {
warn!("Onion service is not configured to accept any connections.");
Ok(())
impl ProxyConfig {
/// Find the configured action to use when receiving a request for a
/// connection on a given port.
pub(crate) fn resolve_port_for_begin(&self, port: u16) -> Option<&ProxyAction> {
self.proxy_ports
.iter()
.find(|rule| rule.source.matches_port(port))
.map(|rule| &rule.target)
/// A single rule in a `ProxyConfig`.
///
/// Rules take the form of, "When this pattern matches, take this action."
#[derive(Clone, Debug, Serialize, Deserialize, Eq, PartialEq)]
// TODO: we might someday want to accept structs here as well, so that
// we can add per-rule fields if we need to. We can make that an option if/when
// it comes up, however.
#[serde(from = "ProxyRuleAsTuple", into = "ProxyRuleAsTuple")]
pub struct ProxyRule {
/// Any connections to a port matching this pattern match this rule.
source: ProxyPattern,
/// When this rule matches, we take this action.
target: ProxyAction,
/// Helper type used to (de)serialize ProxyRule.
type ProxyRuleAsTuple = (ProxyPattern, ProxyAction);
impl From<ProxyRuleAsTuple> for ProxyRule {
fn from(value: ProxyRuleAsTuple) -> Self {
Self {
source: value.0,
target: value.1,
impl From<ProxyRule> for ProxyRuleAsTuple {
fn from(value: ProxyRule) -> Self {
(value.source, value.target)
impl ProxyRule {
/// Create a new ProxyRule mapping `source` to `target`.
pub fn new(source: ProxyPattern, target: ProxyAction) -> Self {
Self { source, target }
/// A set of ports to use when checking how to handle a port.
#[derive(Clone, Debug, serde::Deserialize, serde_with::SerializeDisplay, Eq, PartialEq)]
#[serde(try_from = "ProxyPatternAsEnum")]
pub struct ProxyPattern(RangeInclusive<u16>);
/// Representation for a [`ProxyPattern`]. Used while deserializing.
#[derive(serde::Deserialize)]
#[serde(untagged)]
enum ProxyPatternAsEnum {
/// Representation the [`ProxyPattern`] as an integer.
Number(u16),
/// Representation of the [`ProxyPattern`] as a string.
String(String),
impl TryFrom<ProxyPatternAsEnum> for ProxyPattern {
type Error = ProxyConfigError;
fn try_from(value: ProxyPatternAsEnum) -> Result<Self, Self::Error> {
match value {
ProxyPatternAsEnum::Number(port) => Self::one_port(port),
ProxyPatternAsEnum::String(s) => Self::from_str(&s),
impl FromStr for ProxyPattern {
type Err = ProxyConfigError;
fn from_str(s: &str) -> Result<Self, Self::Err> {
use ProxyConfigError as PCE;
if s == "*" {
Ok(Self::all_ports())
} else if let Some((left, right)) = s.split_once('-') {
let left: u16 = left
.parse()
.map_err(|e| PCE::InvalidPort(left.to_string(), e))?;
let right: u16 = right
.map_err(|e| PCE::InvalidPort(right.to_string(), e))?;
Self::port_range(left, right)
} else {
let port = s.parse().map_err(|e| PCE::InvalidPort(s.to_string(), e))?;
Self::one_port(port)
impl std::fmt::Display for ProxyPattern {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
match self.0.clone().into_inner() {
(start, end) if start == end => write!(f, "{}", start),
(1, 65535) => write!(f, "*"),
(start, end) => write!(f, "{}-{}", start, end),
impl ProxyPattern {
/// Return a pattern matching all ports.
pub fn all_ports() -> Self {
Self::check(1, 65535).expect("Somehow, 1-65535 was not a valid pattern")
/// Return a pattern matching a single port.
/// Gives an error if the port is zero.
pub fn one_port(port: u16) -> Result<Self, ProxyConfigError> {
Self::check(port, port)
/// Return a pattern matching all ports between `low` and `high` inclusive.
/// Gives an error unless `0 < low <= high`.
pub fn port_range(low: u16, high: u16) -> Result<Self, ProxyConfigError> {
Self::check(low, high)
/// Return true if this pattern includes `port`.
pub(crate) fn matches_port(&self, port: u16) -> bool {
self.0.contains(&port)
/// If start..=end is a valid pattern, wrap it as a ProxyPattern. Otherwise return
/// an error.
fn check(start: u16, end: u16) -> Result<ProxyPattern, ProxyConfigError> {
match (start, end) {
(_, 0) => Err(PCE::ZeroPort),
(0, n) => Ok(Self(1..=n)),
(low, high) if low > high => Err(PCE::EmptyPortRange),
(low, high) => Ok(Self(low..=high)),
/// An action to take upon receiving an incoming request.
// The variant names (but not the payloads) are part of the metrics schema.
// When changing them, see `doc/dev/MetricsStrategy.md` re schema stability policy.
#[derive(
Clone,
Debug,
Default,
serde_with::DeserializeFromStr,
serde_with::SerializeDisplay,
Eq,
PartialEq,
strum::EnumDiscriminants,
)]
#[strum_discriminants(derive(Hash, strum::EnumIter))] //
#[strum_discriminants(derive(strum::IntoStaticStr), strum(serialize_all = "snake_case"))]
#[strum_discriminants(vis(pub(crate)))]
#[non_exhaustive]
pub enum ProxyAction {
/// Close the circuit immediately with an error.
#[default]
DestroyCircuit,
/// Accept the client's request and forward it, via some encapsulation method,
/// to some target address.
Forward(Encapsulation, TargetAddr),
/// Close the stream immediately with an error.
RejectStream,
/// Ignore the stream request.
IgnoreStream,
/// The address to which we forward an accepted connection.
#[derive(Clone, Debug)]
pub enum TargetAddr {
/// An address that we can reach over the internet.
Inet(SocketAddr),
/// And address for Unix Socket
/// (Only supported on Unix platforms, std::os::unix::net::SocketAddr
/// and ignored on non-Unix platforms Void::void).
// TODO: we need more tests for Unix Socket support
// I will open a issue or just finish it in this MR
// (UnixTests)
Unix(UnixSocketAddr),
impl PartialEq for TargetAddr {
/// Implement equality for TargetAddr,
/// which we can't automatically derived because UnixSocketAddr does not implement Eq.
fn eq(&self, other: &Self) -> bool {
match (self, other) {
(TargetAddr::Inet(a), TargetAddr::Inet(b)) => a == b,
(TargetAddr::Unix(a), TargetAddr::Unix(b)) => a.as_pathname() == b.as_pathname(),
_ => false,
impl Eq for TargetAddr {}
impl TargetAddr {
/// Return true if this target is sufficiently private that we can be
/// reasonably sure that the user has not misconfigured their onion service
/// to relay traffic onto the public network.
fn is_sufficiently_private(&self) -> bool {
use std::net::IpAddr;
match self {
// Unix Socket is private, because it's local
TargetAddr::Unix(_) => true,
TargetAddr::Inet(sa) => match sa.ip() {
IpAddr::V4(ip) => ip.is_loopback() || ip.is_unspecified() || ip.is_private(),
IpAddr::V6(ip) => ip.is_loopback() || ip.is_unspecified(),
},
impl FromStr for TargetAddr {
/// Return true if 's' looks like an attempted IPv4 or IPv6 socketaddr.
fn looks_like_attempted_addr(s: &str) -> bool {
s.starts_with(|c: char| c.is_ascii_digit())
|| s.strip_prefix('[')
.map(|rhs| rhs.starts_with(|c: char| c.is_ascii_hexdigit() || c == ':'))
.unwrap_or(false)
if let Some(path) = s.strip_prefix("unix:") {
return Ok(Self::Unix(UnixSocketAddr::from_pathname(path).map_err(
|e| ProxyConfigError::InvalidUnixAddr {
path: s.to_string(),
source_error: Arc::new(e),
)?));
if let Some(addr) = s.strip_prefix("inet:") {
Ok(Self::Inet(addr.parse().map_err(|e| {
PCE::InvalidTargetAddr(addr.to_string(), e)
})?))
} else if looks_like_attempted_addr(s) {
// We check 'looks_like_attempted_addr' before parsing this.
Ok(Self::Inet(
s.parse()
.map_err(|e| PCE::InvalidTargetAddr(s.to_string(), e))?,
))
Err(PCE::UnrecognizedTargetType(s.to_string()))
impl std::fmt::Display for TargetAddr {
#![allow(clippy::disallowed_methods)]
TargetAddr::Inet(a) => write!(f, "inet:{}", a),
TargetAddr::Unix(p) => match p.as_pathname() {
Some(path) => write!(f, "unix:{}", path.display()),
None => write!(f, "unix:<unnamed>"),
/// The method by which we encapsulate a forwarded request.
/// (Right now, only `Simple` is supported, but we may later support
/// "HTTP CONNECT", "HAProxy", or others.)
#[derive(Clone, Debug, Default, Eq, PartialEq)]
pub enum Encapsulation {
/// Handle a request by opening a local socket to the target address and
/// forwarding the contents verbatim.
/// This does not transmit any information about the circuit origin of the request;
/// only the local port will distinguish one request from another.
Simple,
impl FromStr for ProxyAction {
if s == "destroy" {
Ok(Self::DestroyCircuit)
} else if s == "reject" {
Ok(Self::RejectStream)
} else if s == "ignore" {
Ok(Self::IgnoreStream)
} else if let Some(addr) = s.strip_prefix("simple:") {
Ok(Self::Forward(Encapsulation::Simple, addr.parse()?))
Ok(Self::Forward(Encapsulation::Simple, s.parse()?))
impl std::fmt::Display for ProxyAction {
ProxyAction::DestroyCircuit => write!(f, "destroy"),
ProxyAction::Forward(Encapsulation::Simple, addr) => write!(f, "simple:{}", addr),
ProxyAction::RejectStream => write!(f, "reject"),
ProxyAction::IgnoreStream => write!(f, "ignore"),
/// An error encountered while parsing or applying a proxy configuration.
#[derive(Debug, Clone, thiserror::Error)]
pub enum ProxyConfigError {
/// We encountered a proxy target with an unrecognized type keyword.
#[error("Could not parse onion service target type {0:?}")]
UnrecognizedTargetType(String),
/// A socket address could not be parsed to be invalid.
#[error("Could not parse onion service target address {0:?}")]
InvalidTargetAddr(String, #[source] std::net::AddrParseError),
/// A unix socket address could not be parsed to be invalid.
/// Only supported on Unix platforms.
#[error("Invalid unix socket address:'{path}': '{source_error}'")]
InvalidUnixAddr {
/// The path that was attempted to be parsed as a unix socket address.
path: String,
#[source]
/// The error that was encountered while parsing the unix socket address.
source_error: Arc<std::io::Error>,
/// A socket rule had an source port that couldn't be parsed as a `u16`.
#[error("Could not parse onion service source port {0:?}")]
InvalidPort(String, #[source] std::num::ParseIntError),
/// A socket rule had a zero source port.
#[error("Zero is not a valid port.")]
ZeroPort,
/// A socket rule specified an empty port range.
#[error("Port range is empty.")]
EmptyPortRange,
#[cfg(test)]
mod test {
// @@ begin test lint list maintained by maint/add_warning @@
#![allow(clippy::bool_assert_comparison)]
#![allow(clippy::clone_on_copy)]
#![allow(clippy::dbg_macro)]
#![allow(clippy::mixed_attributes_style)]
#![allow(clippy::print_stderr)]
#![allow(clippy::print_stdout)]
#![allow(clippy::single_char_pattern)]
#![allow(clippy::unwrap_used)]
#![allow(clippy::unchecked_time_subtraction)]
#![allow(clippy::useless_vec)]
#![allow(clippy::needless_pass_by_value)]
#![allow(clippy::string_slice)] // See arti#2571
//! <!-- @@ end test lint list maintained by maint/add_warning @@ -->
use super::*;
#[test]
fn pattern_ok() {
use ProxyPattern as P;
assert_eq!(P::from_str("*").unwrap(), P(1..=65535));
assert_eq!(P::from_str("100").unwrap(), P(100..=100));
assert_eq!(P::from_str("100-200").unwrap(), P(100..=200));
assert_eq!(P::from_str("0-200").unwrap(), P(1..=200));
fn pattern_display() {
assert_eq!(P::all_ports().to_string(), "*");
assert_eq!(P::one_port(100).unwrap().to_string(), "100");
assert_eq!(P::port_range(100, 200).unwrap().to_string(), "100-200");
fn pattern_err() {
assert!(matches!(P::from_str("fred"), Err(PCE::InvalidPort(_, _))));
assert!(matches!(
P::from_str("100-fred"),
Err(PCE::InvalidPort(_, _))
));
assert!(matches!(P::from_str("100-42"), Err(PCE::EmptyPortRange)));
fn target_ok() {
use Encapsulation::Simple;
use ProxyAction as T;
use TargetAddr as A;
assert!(matches!(T::from_str("reject"), Ok(T::RejectStream)));
assert!(matches!(T::from_str("ignore"), Ok(T::IgnoreStream)));
assert!(matches!(T::from_str("destroy"), Ok(T::DestroyCircuit)));
let sa: SocketAddr = "192.168.1.1:50".parse().unwrap();
assert!(
matches!(T::from_str("192.168.1.1:50"), Ok(T::Forward(Simple, A::Inet(a))) if a == sa)
matches!(T::from_str("inet:192.168.1.1:50"), Ok(T::Forward(Simple, A::Inet(a))) if a == sa)
let sa: SocketAddr = "[::1]:999".parse().unwrap();
assert!(matches!(T::from_str("[::1]:999"), Ok(T::Forward(Simple, A::Inet(a))) if a == sa));
matches!(T::from_str("inet:[::1]:999"), Ok(T::Forward(Simple, A::Inet(a))) if a == sa)
/* TODO (#1246)
let pb = PathBuf::from("/var/run/hs/socket");
matches!(T::from_str("unix:/var/run/hs/socket"), Ok(T::Forward(Simple, A::Unix(p))) if p == pb)
*/
fn target_display() {
assert_eq!(T::RejectStream.to_string(), "reject");
assert_eq!(T::IgnoreStream.to_string(), "ignore");
assert_eq!(T::DestroyCircuit.to_string(), "destroy");
assert_eq!(
T::Forward(Simple, A::Inet("192.168.1.1:50".parse().unwrap())).to_string(),
"simple:inet:192.168.1.1:50"
T::Forward(Simple, A::Inet("[::1]:999".parse().unwrap())).to_string(),
"simple:inet:[::1]:999"
T::Forward(Simple, A::Unix("/var/run/hs/socket".into())).to_string(),
"simple:unix:/var/run/hs/socket"
fn target_err() {
T::from_str("sdakljf"),
Err(PCE::UnrecognizedTargetType(_))
T::from_str("inet:hello"),
Err(PCE::InvalidTargetAddr(_, _))
T::from_str("inet:wwww.example.com:80"),
T::from_str("127.1:80"),
T::from_str("inet:127.1:80"),
T::from_str("inet:2130706433:80"),
T::from_str("128.256.cats.and.dogs"),
fn deserialize() {
let ex = r#"{
"proxy_ports": [
[ "443", "127.0.0.1:11443" ],
[ "80", "ignore" ],
[ "*", "destroy" ]
]
}"#;
let bld: ProxyConfigBuilder = serde_json::from_str(ex).unwrap();
let cfg = bld.build().unwrap();
assert_eq!(cfg.proxy_ports.len(), 3);
assert_eq!(cfg.proxy_ports[0].source.0, 443..=443);
assert_eq!(cfg.proxy_ports[1].source.0, 80..=80);
assert_eq!(cfg.proxy_ports[2].source.0, 1..=65535);
cfg.proxy_ports[0].target,
ProxyAction::Forward(Simple, A::Inet("127.0.0.1:11443".parse().unwrap()))
assert_eq!(cfg.proxy_ports[1].target, ProxyAction::IgnoreStream);
assert_eq!(cfg.proxy_ports[2].target, ProxyAction::DestroyCircuit);
fn validation_fail() {
// this should fail; the third pattern isn't reachable.
[ "2-300", "127.0.0.1:11443" ],
[ "301-999", "ignore" ],
[ "30-310", "destroy" ]
match bld.build() {
Err(ConfigBuildError::Invalid { field, problem }) => {
assert_eq!(field, "proxy_ports");
assert_eq!(problem, "Port pattern 30-310 is not reachable");
other => panic!("Expected an Invalid error; got {other:?}"),
// This should work; the third pattern is not completely covered.
[ "302-999", "ignore" ],
assert!(bld.build().is_ok());
fn demo() {
let b: ProxyConfigBuilder = toml::de::from_str(
r#"
proxy_ports = [
[ 80, "127.0.0.1:10080"],
["22", "destroy"],
["265", "ignore"],
# ["1-1024", "unix:/var/run/allium-cepa/socket"], # TODO (#1246))
"#,
)
.unwrap();
let c = b.build().unwrap();
assert_eq!(c.proxy_ports.len(), 3);
c.proxy_ports[0],
ProxyRule::new(
ProxyPattern::one_port(80).unwrap(),
ProxyAction::Forward(
Encapsulation::Simple,
TargetAddr::Inet("127.0.0.1:10080".parse().unwrap())
c.proxy_ports[1],
ProxyPattern::one_port(22).unwrap(),
ProxyAction::DestroyCircuit
c.proxy_ports[2],
ProxyPattern::one_port(265).unwrap(),
ProxyAction::IgnoreStream
c.proxy_ports[3],
ProxyPattern::port_range(1, 1024).unwrap(),
TargetAddr::Unix("/var/run/allium-cepa/socket".into())