A pure-userspace IKEv2 + EAP-TLS + ESP-in-UDP client for 3GPP ePDG gateways (VoWiFi), in Rust.
Everything runs over ordinary UDP sockets — no raw sockets, no kernel IPsec, no privileges — driven by a
carrier-bundle style configuration. Verified live against T-Mobile's production ePDG (ns.sipgeo.t-mobile.com).
- IKEv2 initiator (RFC 7296) with EAP-only authentication (RFC 5998), NAT-T (RFC 3948), IKE fragmentation (RFC 7383), cookies, INFORMATIONAL (DPD / DELETE), CREATE_CHILD_SA rekeys, NAT-T keepalives.
- EAP-TLS (RFC 5216) over OpenSSL — the ePDG's EAP server only negotiates
TLS_RSA_WITH_AES_128_CBC_SHA, which rustls cannot offer (seedocs/DESIGN.md§9.3), so the TLS engine is theopensslcrate. - Tunnel-mode ESP (RFC 4303) encapsulated in UDP/4500, anti-replay window, AES-256-CBC + HMAC-SHA2-256-128.
- Inner IP stack = smoltcp 0.14 over the ESP data plane (a
Medium::Ipdevice: the tunnel-mode ESP payload is the IP packet): IPv4/IPv6, inner UDP sockets (EpdgTunnel::bind_udp), inner TCP connections and listeners (EpdgTunnel::connect_tcp/listen_tcp: blockingInnerTcpStream/InnerTcpListenerover smoltcp TCP sockets, a small listen backlog, graceful close with a reaper, and the MSS of every SYN clamped to the wire MTU so no segment is ever fragmented —docs/DESIGN.md§11.2), a DNS resolver over the assigned servers (EpdgTunnel::resolve), IPv4 fragmentation/reassembly, ICMP echo replies; a small shim (ipstack::frag) fragments and reassembles IPv6 for the wire MTU, which smoltcp 0.14 cannot do onMedium::Ip. - Mobility and liveness (
docs/DESIGN.md§17): the egress route is watched (or reported by the caller throughEpdgTunnel::network_changed()); an address change rebinds the outer socket — same SAs, same keys, new 5-tuple — and announces it with MOBIKEUPDATE_SA_ADDRESSES(RFC 4555) or, against a gateway without MOBIKE, with the RFC 7296 §2.23 dynamic address update, tolerating a 30 s outage — retransmission exhaustion included — before giving up. A DPD-independent one-way-traffic probe notices a gateway that stopped answering, even when nothing was ever received, a slower idle probe covers a registration that never transmits at all, and an unrecoverable tunnel fails every inner socket — UDP receivers and blocked TCP reads, writes, accepts and connects alike — withNotConnectedat once, so the SIP transport above closes its connection instead of hanging. (Acting on that close — rebuilding the tunnel — is the embedder's job; seedocs/DESIGN.md§17.6 for how the chain continues there.) - Crypto for IKE/ESP via RustCrypto (
aes/cbc/hmac/sha2) andnum-bigintMODP DH, behind a transform registry (crypto::registry) so more algorithms can be added without touching protocol code.
- Rust 1.85+ (edition 2024).
- OpenSSL 3 development files (macOS:
brew install openssl@3; Linux:libssl-dev). Or build with--features vendoredto compile OpenSSL from source.
Config::from_plist_bundle / from_plist_files takes the decoded carrier bundle (imsCommonCredentials, CBRoot.TechSettings
with the IKE / ChildSAs / ExtraConfigurationAttributeRequest blocks), the individual-credentials dictionary
(imsIndividualCredentials, subscriberId), and the client certificate + private key as DER (from_plist_files
reads PEM files and converts them once via epdg::pem; nothing downstream sees PEM). See
tests/fixtures/ for the exact shape and docs/DESIGN.md §2 for the field mapping ($subscriber-id substitution,
transform names, CFG attribute order, defaults taken from the AOSP reference client).
use epdg::{Config, EpdgTunnel};
let cfg = Config::from_plist_files(&bundle, &creds, &cert, &key)?;
let tunnel = EpdgTunnel::connect(&cfg)?; // IKE_SA_INIT → IKE_AUTH/EAP-TLS → child SA
let info = tunnel.info(); // inner addresses, DNS, P-CSCF, SPIs, suites
let pcscf = tunnel.resolve("ueb2bprod.pc.t-mobile.com", Duration::from_secs(5))?; // AAAA then A via the tunnel DNS
let sock = tunnel.bind_udp(0)?; // an inner UDP endpoint (smoltcp socket)
sock.send_to((pcscf[0], 5060).into(), &sip_register)?; // source address picked by smoltcp per family
let reply = sock.recv_timeout(Duration::from_secs(5))?; // Option<UdpDatagram { src, dst, payload }>
tunnel.close()?; // INFORMATIONAL DELETE(IKE), stops all threadsepdg::NetStack (DESIGN.md §16) is one synchronous, object-safe socket/DNS abstraction implemented by both the host
OS stack (StdNetStack: std::net sockets + the libc resolver) and the tunnel (EpdgTunnel: inner UDP and TCP sockets +
the smoltcp DNS socket over the gateway-assigned servers). Application code — a SIP client, say — is written once against
&dyn NetStack / Arc<dyn NetStack> and runs unchanged on either:
use std::time::Duration;
use epdg::{EpdgTunnel, NetStack, StdNetStack};
/// Resolve `host`, send `payload` to its first address on `port`, return the reply.
fn ping(stack: &dyn NetStack, host: &str, port: u16, payload: &[u8]) -> std::io::Result<Option<Vec<u8>>> {
let addrs = stack.resolve(host, Duration::from_secs(5))?; // this stack's resolver; IP literals are immediate
let sock = stack.bind_udp(0)?; // ephemeral port
println!("{} {} -> {}:{port}", stack.name(), sock.local_addr(), addrs[0]);
sock.send_to((addrs[0], port).into(), payload)?;
Ok(sock.recv_timeout(Duration::from_secs(5))?.map(|(_peer, data)| data))
}
let os = StdNetStack::new(); // dual-stack [::] (or 0.0.0.0 without IPv6)
ping(&os, "localhost", 5060, b"OPTIONS ...")?;
let tunnel = EpdgTunnel::connect(&cfg)?;
ping(&tunnel, "ueb2bprod.pc.t-mobile.com", 5060, b"OPTIONS ...")?; // same code, inside the tunnellocal_addrs() gives the addresses the stack sources traffic from (SIP Via/Contact): the tunnel's inner addresses, or
for the OS stack the bind address / the route-selected egress address per family. TCP (connect_tcp, listen_tcp,
TcpStreamLike shared between a reader and a writer thread, StreamIo as Read + Write for TLS) works on both: over
the tunnel it is smoltcp's TCP driven by the inner stack's thread (DESIGN.md §11.2), with the same error kinds as the
OS (TimedOut, ConnectionRefused, ConnectionReset, BrokenPipe, AddrInUse). Crate errors are mapped to
io::Error by netstack::to_io (Timeout → TimedOut, Closed → NotConnected).
CLI (stable path — handy for per-application firewall rules):
cargo build --bin epdg-connect
RUST_LOG=info ./target/debug/epdg-connect # connect, resolve the P-CSCF over the tunnel, DPD, hold, DELETE
./target/debug/epdg-connect --hold 30 --rebind-after 8 # force one address update 8 s into the hold and prove it landed
./target/debug/epdg-connect --tcp-probe # also open one inner TCP connection to the P-CSCF (TCP-PROBE line)
./target/debug/epdg-connect probe-tls <ClientHello hex> # diagnostic: see which TLS suite the EAP server pickscargo test # 354 offline unit tests + the live test
EPDG_SKIP_LIVE=1 cargo test # skip the live test
RUST_LOG=debug cargo test --test live_tmobile -- --nocapture # live: hex dumps of every IKE datagramThe inner stack is tested offline with an in-process two-stack loopback (ipstack::stack::tests): two InnerStacks
on different IPv6 /64s (+ a v4 /32 each) whose device sinks feed each other — UDP both ways with exact endpoints,
off-prefix routing, 3000-byte IPv4 and IPv6 datagrams fragmented at the wire MTU 1280 and reassembled, ICMP echo,
bursts and fire-and-forget sends, resolve() against a tiny in-process DNS server on the far stack's port 53, timeouts,
port allocation, queue bounds, shutdown semantics, and inner TCP: connect/accept and echo over both families, 100 KiB
each way with every segment exactly wire-sized (MSS clamped, nothing fragmented) and the writer held back by the
window, the listen backlog, lost SYN-ACKs and duplicate SYNs, the reaper, timeouts, and a close failing every blocked
TCP call at once — even while the stack thread is stuck in a slow send. The NetStack abstraction runs one generic UDP
exercise and one generic TCP exercise (plus the write-timeout contract TLS relies on) over both backends (loopback
StdNetStacks and the two-stack loopback), and the libc resolver against localhost only.
tests/live_tmobile.rs drives target/debug/epdg-connect (stable path, so one firewall rule keeps working across rebuilds; set EPDG_LIVE_INPROCESS=1 to run the tunnel inside the test process instead). It connects to the T-Mobile PROD ePDG with the credentials of the activation config named by EPDG_ACTIVATION_CONFIG (without it, the revoked fixture credentials in tests/fixtures/, which fail with AUTHENTICATION_FAILED at IKE_AUTH #1; scripts/pull-activation-config.sh pulls a current config off a debuggable device over adb — the certificate is reissued monthly), asserts an inner address,
resolves ueb2bprod.pc.t-mobile.com through &dyn NetStack (smoltcp DNS over ESP — proves ESP in both directions and covers the tunnel's NetStack implementation),
runs a DPD, observes NAT-T keepalives, and tears down cleanly. It also passes --tcp-probe, which opens one inner TCP
connection to the resolved P-CSCF on the port of the config's pcscf-address and prints TCP-PROBE ok local=… peer=… in=<ms> or TCP-PROBE-FAILED <reason> — printed by the test, never asserted, since whether the P-CSCF accepts TCP
there is not known. It needs UDP egress on 500/4500; a per-application firewall (e.g. Little Snitch) must allow the
test binary or target/debug/epdg-connect.
--rebind-after SECS (off by default) exercises the mobility path without touching the network: that far into the
hold it calls EpdgTunnel::force_address_update(), which makes the path monitor rebind the outer socket to a fresh
source port on the same address and announce it exactly as a handover would (MOBIKE UPDATE_SA_ADDRESSES + NAT-D;
the gateway sees a NAT rebinding — DESIGN.md §17.9). It then checks that the gateway followed the move — DPD over the
new 5-tuple and ESP arriving after it — printing ADDRESS-UPDATE, POST-MOVE DPD and POST-MOVE ESP rx lines, or an
ADDRESS-UPDATE-FAILED <reason> line, and exiting non-zero if any of that fails. live_tmobile_address_update is the
live test that drives it. Because it goes through the production mobility path it also carries its risk: a gateway that
ignores or rejects the update ends the tunnel within the 30 s no-route grace, exactly as a real handover would, so it
is a diagnostic knob rather than something to run under a registration you need.
config · crypto (traits, AES-CBC, HMAC-SHA2, MODP DH, registry) · ike (header/payload/message/fragment codecs,
keys, auth, nat, transport, session::IkeInitiator sans-I/O state machine) · eap (packet, tls) · esp (codec, replay)
· ipstack (device::EspDevice — smoltcp Medium::Ip device over ESP; stack::InnerStack — Interface + SocketSet
- the single stack thread,
InnerUdpSocket,InnerTcpStream/InnerTcpListener,resolve) ·tunnel(threads: rx demux, stack, keepalive, DPD/rekey timers;EpdgTunnelfacade) ·netstack(NetStack/UdpSocketLike/TcpStreamLike/TcpListenerLiketraits,StdNetStack, the tunnel implementations). Design contract and the byte-level facts mirrored from the AOSP client:docs/DESIGN.md,docs/AOSP_FACTS*.md.
Threading of the inner stack (DESIGN.md §11): only the epdg-stack thread drives smoltcp (Interface::poll), behind
one mutex + condvar. The ESP rx thread decapsulates and pushes the inner IP packet (push_rx, bounded queue,
drop-oldest); send_to / bind_udp / resolve hold the lock only to enqueue and then notify; received datagrams
reach InnerUdpSocket::recv_timeout through a bounded channel without touching the lock, and a blocked TCP call parks on
a separate event counter the stack thread bumps after each poll that moved packets (so a close wakes it at once). smoltcp's compile-time
limits are raised through Cargo features (8 addresses, 4 routes, 4 DNS servers, 8 DNS results, 8 KiB
fragmentation/reassembly buffers); child.inner_mtu (default 1280) is the wire MTU, child.inner_mtu_stack (default
16384) the MTU smoltcp sees — the device fragments outbound packets to the wire MTU and push_rx reassembles inbound
IPv6 fragment sets (DESIGN.md §11.1).
- The ePDG's EAP-TLS server negotiates only
TLS_RSA_WITH_AES_128_CBC_SHA(TLS 1.2, no EMS); the server certificate is a public DigiCert cert fornsp.epc.mnc260.mcc310.pub.3gppnetwork.org(validation is off by default per the bundle'sValidateRemoteCertificate=false, but can be enabled with a CA bundle). - It returns no
P_CSCF_IP*_ADDRESSconfig attributes; resolve the P-CSCF hostname over the assigned tunnel DNS. - NAT_DETECTION_SOURCE_IP is deliberately hashed over
192.0.2.0(as the AOSP client does) so the gateway always selects UDP-encapsulated ESP — the only kind a userspace client can carry. - smoltcp 0.14 has no IPv6 fragmentation or reassembly on
Medium::Ip(itsproto-ipv6-fragmentationfeature only covers 6LoWPAN) and would answer an inbound IPv6 Fragment header with an ICMPv6 Parameter Problem — fatal for SIP, whose 200 OK / NOTIFY arrive IPv6-fragmented from the P-CSCF.ipstack::fragtherefore fragments on the way out and reassembles on the way in around the device (DESIGN.md §11.1);send_toaccepts payloads up toinner_mtu_stack - 48(v6) /- 28(v4). smoltcp also sets DF on every IPv4 packet it emits, so the shim ignores DF.