OpeniWAN
An independent, open-source Rust implementation of the iWAN client protocol.
OpeniWAN provides a protocol library and command-line client for the
traditional single-path UDP data plane observed in the macOS iWAN client
2.3.0 (230).
[!IMPORTANT] This project is not affiliated with or endorsed by Panabit or any deployment operator. It is an interoperability project, not an official specification or vendor-certified client.
Features
- OPEN, OPENACK, and OPENREJECT authentication with AUTH_VERIFY correlation
- Plaintext, repeating XOR, and legacy AES-128-ECB data modes
- IPv4, IPv6, heartbeat, CLOSE, bounded reconnection, and fragment reassembly
- Native Linux, macOS, and Windows TUN support through the
tuncrate - A route-free local HTTP to internal HTTP or HTTPS reverse proxy with no TUN device
- Strict packet validation, bounded fragment queues, route cleanup, and credential zeroization
- Config-driven OIDC/JWKS login and controller-managed line discovery
- A reusable Rust library plus
ping,auth,connect,decode, andmanagedcommands
Status
Available
- Traditional single-path authentication and UDP tunneling
- Plaintext and repeating XOR data modes
- IPv4, IPv6, IPFRAG, and IPFRAG6 receive paths
- Heartbeat, CLOSE, failure detection, and bounded reconnection
- Route-free local HTTP/1.1 to HTTP or HTTPS reverse proxy
- Config-driven OIDC and compatible Panabit controller flows
serveuserspace DNS with UDP, TCP fallback, and TTL caching
Requires deployment validation
- Legacy AES-128 data mode is implemented but still requires validation against an authorized real endpoint.
Not implemented
- SEGRT/SR multipath packets are recognized and safely discarded.
Production-oriented here means that the implementation has defensive parsing, resource limits, explicit error handling, credential hygiene, cleanup logic, tests, and CI. It does not mean that the project has passed vendor certification. Validate every deployment against an authorized test endpoint.
Installation
OpeniWAN requires Rust 1.88 or newer. Install the CLI from crates.io:
By default, Cargo installs the executable to $HOME/.cargo/bin on Linux and
macOS or %USERPROFILE%\.cargo\bin on Windows. Ensure that directory is on
PATH, then verify the installation:
Build from source
From a repository checkout, build the optimized executable with:
The executable is written to target/release/openiwan (openiwan.exe on
Windows). To install the current checkout into Cargo's binary directory instead:
Contributor checks and development requirements are documented in CONTRIBUTING.md.
Platform notes
Installation does not require elevated privileges. Creating a TUN interface or
changing routes does: run connect, managed connect, and managed all as
root on Linux/macOS or from an elevated terminal on Windows. ping, auth,
decode, serve, managed login, and managed listing do not require elevation.
Windows
Windows 10/11 on x86_64 and ARM64 is supported.
The official signed Wintun 0.14.1 library is embedded in the executable. On the
first TUN connection, OpeniWAN verifies its SHA-256 digest, atomically extracts
it below %LOCALAPPDATA%\openiwan\wintun\0.14.1, verifies its Authenticode
signature while loading it, and reuses the validated file thereafter. No
separate Wintun setup or DLL copy is required.
Usage
Probe an iWAN UDP endpoint:
Authenticate without changing the host network:
If OPENIWAN_PASSWORD is unset, the client securely prompts for the password
without echoing it on Linux, macOS, and Windows. Do not pass passwords directly
on the command line.
Create a tunnel for explicit destination prefixes:
On Windows, run the equivalent command in an elevated terminal without
sudo. The default interface is openiwan0 on Linux and Windows; macOS
automatically allocates an available utunN. Use --tun to override the name
(utunN is required for an explicit macOS name).
--route accepts CIDRs, --route-ip creates host routes, and --route-domain
resolves a domain once before connecting. Unix values are passed to platform
tools as separate arguments, never through a shell; Windows uses the native IP
Helper API. The client rejects default routes and any route containing the
active iWAN endpoint.
Access an HTTP or HTTPS API without changing host routes
Expose one fixed organization HTTP or HTTPS origin on a loopback-only HTTP listener:
A local request for http://127.0.0.1:8080/v1/profile?full=true is sent through
the iWAN userspace TCP/IP stack to
https://api.example.edu/v1/profile?full=true. Methods, queries, streaming
bodies, and end-to-end headers such as Authorization are preserved. For
HTTPS, Host, SNI, and certificate verification continue to use the original
upstream name. An http:// upstream is also accepted and uses plain TCP inside
iWAN without TLS protection.
serve opens no TUN device, invokes no platform route command, and has no route
options. The listener must be a loopback address, and the upstream must be an
HTTP or HTTPS origin without a path, query, or user information. HTTPS uses
system roots by default; repeat --ca-cert organization-ca.pem to add private
roots.
The default --dns-mode auto first queries organization resolvers advertised
by OPENACK or configured by the managed provider through the iWAN userspace
stack. It validates transactions and responses, follows CNAMEs, caches by TTL,
and retries truncated UDP responses over DNS-over-TCP. Because these queries
stay inside iWAN, host-side VPNs and proxies cannot observe them or substitute
Fake-IP answers. Every managed provider must explicitly declare its
organization resolvers; use an empty list when the deployment relies only on
OPENACK DNS attributes:
= []
Manual mode and temporary overrides can pass --dns-server 192.0.2.53.
--dns-mode iwan requires an iWAN resolver. auto uses host DNS only when no
iWAN resolver is available; failure of a configured organization resolver is
fail-closed and does not leak the hostname to the host resolver. Host answers
in 198.18.0.0/15 are rejected instead of causing a useless TCP timeout.
--upstream-ip remains available as an emergency operator override, but normal
production use does not require pre-resolving API addresses.
Managed login and connection
Managed providers are external TOML files so the authentication and controller
parameters can be updated without recompiling. The schema-complete
examples/providers/example.toml is a non-operational template; replace every
placeholder or use a bundled profile before installing the provider as a
protected file:
Fetch and list encrypted line configuration without elevated privileges:
Select a line and connect:
Use all in place of fetch or connect to perform the complete flow. The
access token and decrypted line password are never written to disk. See
Managed Providers for the provider schema, state
layout, and security model. Bundled configurations and deployment-specific
instructions are listed under Provider Profiles.
The default managed state directory is ~/.config/openiwan/managed on Unix and
%APPDATA%\openiwan\managed on Windows.
An existing managed line can run the route-free proxy as well:
Configuration can also be loaded from TOML. require_auth_verify_echo and
xor_key_bytes are required because their values depend on the deployment:
= "192.0.2.10:6001"
= 1400
= "xor"
= 3000
= 3
= true
= 16
= 5000
= 30000
= 250
[]
= 10
= 1000
= 30000
Use openiwan --help or openiwan <command> --help for the complete CLI
reference.
Library
Add OpeniWAN to a Rust project with cargo add openiwan. For a protocol-only
dependency without the default managed-provider and HTTP-proxy features, use
cargo add openiwan --no-default-features.
Packet and TLV codecs live in openiwan::protocol; compatibility cryptography
lives in openiwan::crypto. Applications that already own a TUN device,
virtual interface, or userspace IP stack can implement PacketDevice and use
Client::authenticate, ConnectedSession::run, or the bounded reconnect
helpers. The default managed Cargo feature exposes typed provider, OIDC,
controller, and encrypted-state APIs; disable default features for a
protocol-only dependency.
Programmatic client and cipher construction requires an explicit
require_auth_verify_echo policy and XOR key width. Cipher constructors return
an error unless the width is 8 or 16.
The public API documentation can be built locally with cargo doc --open.
Documentation
- Documentation index
- Wire protocol reference
- Architecture
- Managed providers
- Provider profiles
- Reverse-engineering evidence and limitations
- Security policy
All technical and community documentation is maintained in English. Translated README files are welcome when they remain faithful to this canonical README.
Contributing
Please read CONTRIBUTING.md before opening a pull request. By participating, you agree to follow the Code of Conduct.
Security issues should be reported according to SECURITY.md, not through a public issue.
Security
The traditional iWAN data plane uses MD5, repeating XOR, or AES-ECB. Its control signature is not a modern message authentication code. These mechanisms exist for compatibility and do not provide the confidentiality, integrity, forward secrecy, or peer authentication expected from a modern VPN protocol.
Use OpeniWAN only on authorized networks, preferably inside an additional trusted security layer, and choose a stronger protocol when the endpoint supports one.
License
OpeniWAN is available under the MIT License.