microsandbox_network/

network.rs

//! `SmoltcpNetwork` — orchestration type that ties [`NetworkConfig`] to the
//! smoltcp engine.
//!
//! This is the networking analog to `PassthroughFs`/`MemFs` on the filesystem side — the single
//! type the runtime creates from config, wires into the VM builder, and starts
//! the networking stack.

use std::net::{Ipv4Addr, Ipv6Addr, UdpSocket};
use std::sync::Arc;
use std::thread::JoinHandle;

use ipnetwork::{Ipv4Network, Ipv6Network};
use microsandbox_protocol::{ENV_HOST_ALIAS, ENV_NET, ENV_NET_IPV4, ENV_NET_IPV6};
use msb_krun::backends::net::NetBackend;

use crate::backend::SmoltcpBackend;
use crate::config::NetworkConfig;
use crate::shared::{DEFAULT_QUEUE_CAPACITY, SharedState};
use crate::stack::{self, GatewayIps, PollLoopConfig};
use crate::tls::state::TlsState;

//--------------------------------------------------------------------------------------------------
// Constants
//--------------------------------------------------------------------------------------------------

/// Maximum sandbox slot value. Limited by MAC/IPv6 encoding (16 bits = 65535).
/// The default IPv4 pool (172.16.0.0/12 with /30 blocks) supports 262144 slots,
/// but MAC and IPv6 derivation only encode the low 16 bits, so 65535 is the
/// effective maximum.
const MAX_SLOT: u64 = u16::MAX as u64;

//--------------------------------------------------------------------------------------------------
// Types
//--------------------------------------------------------------------------------------------------

/// The networking engine. Created from [`NetworkConfig`] by the runtime.
///
/// Owns the smoltcp poll thread and provides:
/// - [`take_backend()`](Self::take_backend) — the `NetBackend` for `VmBuilder::net()`
/// - [`guest_env_vars()`](Self::guest_env_vars) — `MSB_NET*` env vars for the guest
/// - [`ca_cert_pem()`](Self::ca_cert_pem) — CA certificate for TLS interception
pub struct SmoltcpNetwork {
    config: NetworkConfig,
    shared: Arc<SharedState>,
    backend: Option<SmoltcpBackend>,
    poll_handle: Option<JoinHandle<()>>,

    // Resolved from config + slot.
    guest_mac: [u8; 6],
    gateway_mac: [u8; 6],
    mtu: u16,
    // IPv4 / IPv6 are `Some` when active for this sandbox: the user supplied
    // an explicit address, or the host has a route for that family.
    guest_ipv4: Option<Ipv4Addr>,
    gateway_ipv4: Option<Ipv4Addr>,
    guest_ipv6: Option<Ipv6Addr>,
    gateway_ipv6: Option<Ipv6Addr>,

    // TLS state (if enabled). Created in new(), used for ca_cert_pem().
    tls_state: Option<Arc<TlsState>>,
}

/// Handle for installing host-side termination behavior into the network stack.
#[derive(Clone)]
pub struct TerminationHandle {
    shared: Arc<SharedState>,
}

/// Read-only view of aggregate network byte counters.
#[derive(Clone)]
pub struct MetricsHandle {
    shared: Arc<SharedState>,
}

//--------------------------------------------------------------------------------------------------
// Methods
//--------------------------------------------------------------------------------------------------

impl SmoltcpNetwork {
    /// Create from user config + sandbox slot (for IP/MAC derivation).
    ///
    /// Each address family is enabled when either the user supplied an
    /// explicit address or the host kernel has a route for that family;
    /// otherwise the corresponding `guest_*`/`gateway_*` fields stay `None`
    /// and the family is omitted from the smoltcp interface, env vars, and
    /// downstream consumers.
    ///
    /// # Panics
    ///
    /// Panics if `slot` exceeds the address pool capacity (65535 for MAC/IPv6,
    /// 524287 for IPv4).
    pub fn new(config: NetworkConfig, slot: u64) -> Self {
        Self::new_with_routes(config, slot, host_has_ipv4_route(), host_has_ipv6_route())
    }

    fn new_with_routes(
        config: NetworkConfig,
        slot: u64,
        host_has_ipv4: bool,
        host_has_ipv6: bool,
    ) -> Self {
        assert!(
            slot <= MAX_SLOT,
            "sandbox slot {slot} exceeds address pool capacity (max {MAX_SLOT})"
        );

        let guest_mac = config
            .interface
            .mac
            .unwrap_or_else(|| derive_guest_mac(slot));
        let gateway_mac = derive_gateway_mac(slot);
        let mtu = config.interface.mtu.unwrap_or(1500);

        let guest_ipv4 = config.interface.ipv4_address.or_else(|| {
            host_has_ipv4.then(|| {
                derive_guest_ipv4(
                    config
                        .interface
                        .ipv4_pool
                        .unwrap_or_else(default_guest_ipv4_pool),
                    slot,
                )
            })
        });
        let gateway_ipv4 = guest_ipv4.map(gateway_from_guest_ipv4);
        let guest_ipv6 = config.interface.ipv6_address.or_else(|| {
            host_has_ipv6.then(|| {
                derive_guest_ipv6(
                    config
                        .interface
                        .ipv6_pool
                        .unwrap_or_else(default_guest_ipv6_pool),
                    slot,
                )
            })
        });
        let gateway_ipv6 = guest_ipv6.map(gateway_from_guest_ipv6);

        let queue_capacity = config
            .max_connections
            .unwrap_or(DEFAULT_QUEUE_CAPACITY)
            .max(DEFAULT_QUEUE_CAPACITY);
        let shared = Arc::new(SharedState::new(queue_capacity));
        let backend = SmoltcpBackend::new(shared.clone());

        let tls_state = if config.tls.enabled {
            Some(Arc::new(TlsState::new(
                config.tls.clone(),
                config.secrets.clone(),
            )))
        } else {
            None
        };

        Self {
            config,
            shared,
            backend: Some(backend),
            poll_handle: None,
            guest_mac,
            gateway_mac,
            mtu,
            guest_ipv4,
            gateway_ipv4,
            guest_ipv6,
            gateway_ipv6,
            tls_state,
        }
    }

    /// Get the gateway IPs for virtio-net configuration and domain-based policy rules.
    fn gateway_ips(&self) -> GatewayIps {
        GatewayIps {
            ipv4: self.gateway_ipv4,
            ipv6: self.gateway_ipv6,
        }
    }

    /// Start the smoltcp poll thread.
    ///
    /// Must be called before VM boot. Requires a tokio runtime handle for
    /// spawning proxy tasks, DNS resolution, and published port listeners.
    pub fn start(&mut self, tokio_handle: tokio::runtime::Handle) {
        let shared = self.shared.clone();
        let poll_config = PollLoopConfig {
            gateway_mac: self.gateway_mac,
            guest_mac: self.guest_mac,
            gateway: self.gateway_ips(),
            guest_ipv4: self.guest_ipv4,
            guest_ipv6: self.guest_ipv6,
            mtu: self.mtu as usize,
        };
        let network_policy = self.config.policy.clone();
        let dns_config = self.config.dns.clone();
        let tls_state = self.tls_state.clone();
        let published_ports = self.config.ports.clone();
        let max_connections = self.config.max_connections;
        let secrets = Arc::new(self.config.secrets.clone());

        self.poll_handle = Some(
            std::thread::Builder::new()
                .name("smoltcp-poll".into())
                .spawn(move || {
                    stack::smoltcp_poll_loop(
                        shared,
                        poll_config,
                        network_policy,
                        dns_config,
                        tls_state,
                        published_ports,
                        max_connections,
                        tokio_handle,
                        secrets,
                    );
                })
                .expect("failed to spawn smoltcp poll thread"),
        );
    }

    /// Take the `NetBackend` for `VmBuilder::net()`. One-shot.
    pub fn take_backend(&mut self) -> Box<dyn NetBackend + Send> {
        Box::new(self.backend.take().expect("backend already taken"))
    }

    /// Guest MAC address for `VmBuilder::net().mac()`.
    pub fn guest_mac(&self) -> [u8; 6] {
        self.guest_mac
    }

    /// Generate `MSB_NET*` environment variables for the guest.
    ///
    /// The guest init (`agentd`) reads these to configure the network
    /// interface via ioctls + netlink.
    pub fn guest_env_vars(&self) -> Vec<(String, String)> {
        let mut vars = vec![
            (
                ENV_NET.into(),
                format!(
                    "iface=eth0,mac={},mtu={}",
                    format_mac(self.guest_mac),
                    self.mtu,
                ),
            ),
            (ENV_HOST_ALIAS.into(), crate::HOST_ALIAS.into()),
        ];

        if let (Some(guest), Some(gateway)) = (self.guest_ipv4, self.gateway_ipv4) {
            vars.push((
                ENV_NET_IPV4.into(),
                format!("addr={guest}/30,gw={gateway},dns={gateway}"),
            ));
        }

        if let (Some(guest), Some(gateway)) = (self.guest_ipv6, self.gateway_ipv6) {
            vars.push((
                ENV_NET_IPV6.into(),
                format!("addr={guest}/64,gw={gateway},dns={gateway}"),
            ));
        }

        // Auto-expose secret placeholders as environment variables.
        for secret in &self.config.secrets.secrets {
            vars.push((secret.env_var.clone(), secret.placeholder.clone()));
        }

        vars
    }

    /// CA certificate PEM bytes if TLS interception is enabled.
    ///
    /// Write to the runtime mount before VM boot so the guest can trust it.
    pub fn ca_cert_pem(&self) -> Option<Vec<u8>> {
        self.tls_state.as_ref().map(|s| s.ca_cert_pem())
    }

    /// Host-trusted CA bundle to ship into the guest, if
    /// [`NetworkConfig::trust_host_cas`] is enabled.
    ///
    /// Returned PEM may concatenate CAs that the Mozilla root bundle in
    /// the guest already trusts; duplicates are harmless and saved the
    /// cost of computing a delta. Returns `None` when the host store is
    /// empty or the feature is disabled.
    pub fn host_cas_cert_pem(&self) -> Option<Vec<u8>> {
        if !self.config.trust_host_cas {
            return None;
        }
        crate::tls::host_cas::collect_host_cas()
    }

    /// Create a handle for wiring runtime termination into the network stack.
    pub fn termination_handle(&self) -> TerminationHandle {
        TerminationHandle {
            shared: self.shared.clone(),
        }
    }

    /// Create a handle for reading aggregate network byte counters.
    pub fn metrics_handle(&self) -> MetricsHandle {
        MetricsHandle {
            shared: self.shared.clone(),
        }
    }
}

impl TerminationHandle {
    /// Install the termination hook.
    pub fn set_hook(&self, hook: Arc<dyn Fn() + Send + Sync>) {
        self.shared.set_termination_hook(hook);
    }
}

impl MetricsHandle {
    /// Total guest -> runtime bytes observed at the virtio-net boundary.
    pub fn tx_bytes(&self) -> u64 {
        self.shared.tx_bytes()
    }

    /// Total runtime -> guest bytes observed at the virtio-net boundary.
    pub fn rx_bytes(&self) -> u64 {
        self.shared.rx_bytes()
    }
}

//--------------------------------------------------------------------------------------------------
// Functions
//--------------------------------------------------------------------------------------------------

/// Derive a guest MAC address from the sandbox slot.
///
/// Format: `02:ms:bx:SS:SS:02` where SS:SS encodes the slot.
fn derive_guest_mac(slot: u64) -> [u8; 6] {
    let s = slot.to_be_bytes();
    [0x02, 0x6d, 0x73, s[6], s[7], 0x02]
}

/// Derive a gateway MAC address from the sandbox slot.
///
/// Format: `02:ms:bx:SS:SS:01`.
fn derive_gateway_mac(slot: u64) -> [u8; 6] {
    let s = slot.to_be_bytes();
    [0x02, 0x6d, 0x73, s[6], s[7], 0x01]
}

/// Derive a guest IPv4 address from the sandbox slot.
///
/// Pool: `172.16.0.0/12` by default. Each slot gets a `/30` block (4 IPs).
/// Guest is at offset +2 in the block.
fn derive_guest_ipv4(pool: Ipv4Network, slot: u64) -> Ipv4Addr {
    assert!(
        pool.prefix() <= 30,
        "IPv4 pool {pool} must be large enough to contain at least one /30 block"
    );

    let capacity = 1u64 << (30 - pool.prefix());
    assert!(
        slot < capacity,
        "sandbox slot {slot} exceeds IPv4 pool {pool} capacity ({capacity} /30 blocks)"
    );

    let base = u32::from(pool.network());
    let offset = (slot as u32) * 4 + 2; // +2 = guest within /30
    Ipv4Addr::from(base + offset)
}

/// Gateway IPv4 from guest IPv4: guest - 1 (offset +1 in the /30 block).
fn gateway_from_guest_ipv4(guest: Ipv4Addr) -> Ipv4Addr {
    Ipv4Addr::from(u32::from(guest) - 1)
}

fn default_guest_ipv4_pool() -> Ipv4Network {
    Ipv4Network::new(Ipv4Addr::new(172, 16, 0, 0), 12)
        .expect("default IPv4 pool must be a valid network")
}

/// Derive a guest IPv6 address from the sandbox slot.
///
/// Pool: `fd42:6d73:62::/48`. Each slot gets a `/64` prefix.
/// Guest is `::2` in its prefix.
fn derive_guest_ipv6(pool: Ipv6Network, slot: u64) -> Ipv6Addr {
    assert!(
        pool.prefix() <= 64,
        "IPv6 pool {pool} must be large enough to contain at least one /64 prefix"
    );

    let capacity = 1u128 << (64 - pool.prefix());
    assert!(
        (slot as u128) < capacity,
        "sandbox slot {slot} exceeds IPv6 pool {pool} capacity ({capacity} /64 prefixes)"
    );

    let base = u128::from(pool.network());
    let offset = (slot as u128) << 64;
    Ipv6Addr::from(base + offset + 2)
}

/// Gateway IPv6 from guest IPv6: `::1` in the same prefix.
fn gateway_from_guest_ipv6(guest: Ipv6Addr) -> Ipv6Addr {
    let segs = guest.segments();
    Ipv6Addr::new(segs[0], segs[1], segs[2], segs[3], 0, 0, 0, 1)
}

fn default_guest_ipv6_pool() -> Ipv6Network {
    Ipv6Network::new(Ipv6Addr::new(0xfd42, 0x6d73, 0x0062, 0, 0, 0, 0, 0), 48)
        .expect("default IPv6 pool must be a valid network")
}

/// Format a MAC address as `xx:xx:xx:xx:xx:xx`.
fn format_mac(mac: [u8; 6]) -> String {
    format!(
        "{:02x}:{:02x}:{:02x}:{:02x}:{:02x}:{:02x}",
        mac[0], mac[1], mac[2], mac[3], mac[4], mac[5]
    )
}

/// Returns true if the host kernel can select an IPv4 route.
///
/// `UdpSocket::connect` performs a local routing-table lookup against the
/// TEST-NET-1 (`192.0.2.1`) address; it does not send packets or wait on
/// the network.
fn host_has_ipv4_route() -> bool {
    UdpSocket::bind((Ipv4Addr::UNSPECIFIED, 0))
        .and_then(|socket| socket.connect((Ipv4Addr::new(192, 0, 2, 1), 443)))
        .is_ok()
}

/// Returns true if the host kernel can select an IPv6 route. Probes a
/// `2001:db8::/32` documentation address via `UdpSocket::connect` (no packet
/// is sent).
fn host_has_ipv6_route() -> bool {
    UdpSocket::bind((Ipv6Addr::UNSPECIFIED, 0))
        .and_then(|socket| socket.connect((Ipv6Addr::new(0x2001, 0x0db8, 0, 0, 0, 0, 0, 1), 443)))
        .is_ok()
}

//--------------------------------------------------------------------------------------------------
// Tests
//--------------------------------------------------------------------------------------------------

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn derive_addresses_slot_0() {
        assert_eq!(derive_guest_mac(0), [0x02, 0x6d, 0x73, 0x00, 0x00, 0x02]);
        assert_eq!(derive_gateway_mac(0), [0x02, 0x6d, 0x73, 0x00, 0x00, 0x01]);
        assert_eq!(
            derive_guest_ipv4(default_guest_ipv4_pool(), 0),
            Ipv4Addr::new(172, 16, 0, 2)
        );
        assert_eq!(
            gateway_from_guest_ipv4(Ipv4Addr::new(172, 16, 0, 2)),
            Ipv4Addr::new(172, 16, 0, 1)
        );
    }

    #[test]
    fn derive_addresses_slot_1() {
        assert_eq!(
            derive_guest_ipv4(default_guest_ipv4_pool(), 1),
            Ipv4Addr::new(172, 16, 0, 6)
        );
        assert_eq!(
            gateway_from_guest_ipv4(Ipv4Addr::new(172, 16, 0, 6)),
            Ipv4Addr::new(172, 16, 0, 5)
        );
    }

    #[test]
    fn derive_addresses_custom_ipv4_pool() {
        let pool = "172.31.240.0/24".parse::<Ipv4Network>().unwrap();
        assert_eq!(derive_guest_ipv4(pool, 0), Ipv4Addr::new(172, 31, 240, 2));
        assert_eq!(
            derive_guest_ipv4(pool, 63),
            Ipv4Addr::new(172, 31, 240, 254)
        );
    }

    #[test]
    fn derive_ipv6_slot_0() {
        assert_eq!(
            derive_guest_ipv6(default_guest_ipv6_pool(), 0),
            "fd42:6d73:62:0::2".parse::<Ipv6Addr>().unwrap()
        );
        assert_eq!(
            gateway_from_guest_ipv6(derive_guest_ipv6(default_guest_ipv6_pool(), 0)),
            "fd42:6d73:62:0::1".parse::<Ipv6Addr>().unwrap()
        );
    }

    #[test]
    fn derive_addresses_custom_ipv6_pool() {
        let pool = "fd7a:115c:a1e0:100::/56".parse::<Ipv6Network>().unwrap();
        assert_eq!(
            derive_guest_ipv6(pool, 0),
            "fd7a:115c:a1e0:100::2".parse::<Ipv6Addr>().unwrap()
        );
        assert_eq!(
            derive_guest_ipv6(pool, 3),
            "fd7a:115c:a1e0:103::2".parse::<Ipv6Addr>().unwrap()
        );
    }

    #[test]
    fn format_mac_address() {
        assert_eq!(
            format_mac([0x02, 0x6d, 0x73, 0x00, 0x00, 0x01]),
            "02:6d:73:00:00:01"
        );
    }

    #[test]
    fn guest_env_vars_includes_ipv4_when_host_has_v4_route() {
        let net = SmoltcpNetwork::new_with_routes(NetworkConfig::default(), 0, true, false);
        let vars = net.guest_env_vars();

        assert_eq!(vars.len(), 3);
        assert_eq!(vars[0].0, ENV_NET);
        assert!(vars[0].1.contains("iface=eth0"));
        assert_eq!(vars[1].0, ENV_HOST_ALIAS);
        assert_eq!(vars[1].1, crate::HOST_ALIAS);
        assert_eq!(vars[2].0, ENV_NET_IPV4);
        assert!(vars[2].1.contains("/30"));
    }

    #[test]
    fn guest_env_vars_includes_ipv6_when_host_has_v6_route() {
        let net = SmoltcpNetwork::new_with_routes(NetworkConfig::default(), 0, true, true);
        let vars = net.guest_env_vars();

        assert_eq!(vars.len(), 4);
        assert_eq!(vars[0].0, ENV_NET);
        assert_eq!(vars[1].0, ENV_HOST_ALIAS);
        assert_eq!(vars[2].0, ENV_NET_IPV4);
        assert_eq!(vars[3].0, ENV_NET_IPV6);
        assert!(vars[3].1.contains("/64"));
    }

    #[test]
    fn guest_env_vars_omit_ipv6_without_host_route() {
        let net = SmoltcpNetwork::new_with_routes(NetworkConfig::default(), 0, true, false);
        let vars = net.guest_env_vars();

        assert!(!vars.iter().any(|(k, _)| k == ENV_NET_IPV6));
    }

    #[test]
    fn guest_env_vars_omit_ipv4_without_host_route() {
        let net = SmoltcpNetwork::new_with_routes(NetworkConfig::default(), 0, false, true);
        let vars = net.guest_env_vars();

        assert_eq!(vars.len(), 3);
        assert_eq!(vars[0].0, ENV_NET);
        assert_eq!(vars[1].0, ENV_HOST_ALIAS);
        assert_eq!(vars[2].0, ENV_NET_IPV6);
    }

    #[test]
    fn explicit_ipv6_address_overrides_missing_host_v6_route() {
        let mut config = NetworkConfig::default();
        config.interface.ipv6_address = Some("fd42:6d73:62:99::2".parse().unwrap());
        let net = SmoltcpNetwork::new_with_routes(config, 0, true, false);
        let vars = net.guest_env_vars();

        let v6 = vars
            .iter()
            .find(|(k, _)| k == ENV_NET_IPV6)
            .expect("explicit ipv6 should publish env var even without host route");
        assert!(v6.1.contains("fd42:6d73:62:99::2/64"));
    }

    #[test]
    fn neither_family_active_emits_only_base_env_vars() {
        let net = SmoltcpNetwork::new_with_routes(NetworkConfig::default(), 0, false, false);
        let vars = net.guest_env_vars();

        assert_eq!(vars.len(), 2);
        assert_eq!(vars[0].0, ENV_NET);
        assert_eq!(vars[1].0, ENV_HOST_ALIAS);
    }
}