# iWAN protocol profile
This reference describes the interoperable wire behavior implemented by
OpeniWAN. It is based on independent analysis and authorized testing, not a
vendor specification. See [Protocol Provenance](PROTOCOL_PROVENANCE.md) for
evidence requirements and unresolved areas.
Numeric fields are unsigned unless stated otherwise. Byte order is named
explicitly; text bytes use ASCII.
## Standard datagrams
The standard header is eight bytes:
```text
Signed controls append:
```text
MD5(exact_header || ASCII("mw"))
```
The 16-byte signature covers only the header.
| `0x11` | `OPEN_REJECT` |
| `0x12` | `OPEN_ACK` |
| `0x13` | `OPEN` |
| `0x14` | `DATA` |
| `0x15` | `ECHO_REQUEST` |
| `0x16` | `ECHO_RESPONSE` |
| `0x17` | `CLOSE` |
| `0x18` | `DATA_ENCRYPTED` |
| `0x19` | `DATA_DUP` |
| `0x20` | `DATA_ENC_DUP` |
| `0x22` | `IP_FRAGMENT` |
| `0x23` | `DATA_IPV6` |
| `0x24` | `IP_FRAGMENT_IPV6` |
| `0x28` | `SEGMENT_ROUTING` |
| `0x29` | `PING_REQUEST` |
| `0x2a` | `PING_RESPONSE` |
Encryption values are `NONE=0`, `XOR=1`, and `AES=2`.
## Authentication
Each TLV is `type:u8 | total_length:u8 | value`:
```text
01 USERNAME 02 PASSWORD 03 MTU 04 IP
05 DNS 06 GATEWAY 07 NETMASK 08 ENCRYPT
09 DUP_PKT 0a LINK 0f AUTH_VERIFY
10 ERR_MSG
```
The generic parser tolerates a final one- or two-byte suffix, although
conforming senders should not emit one. `NETMASK` and `DUP_PKT` are parsed but
do not change the active session.
An `OPEN` body is ordered as MTU, USERNAME, PASSWORD, ENCRYPT, optional LINK,
and optional nonzero AUTH_VERIFY. Credentials use Java US-ASCII replacement
behavior. Password wrapping is:
```text
wire = AES-128-ECB(key, block)
```
The session key after authentication is:
```text
AUTH_VERIFY may be omitted by the response; when present, it must match.
## Session data
- `NONE` is identity.
- `XOR` repeats the first eight bytes of the 16-byte session key.
- `AES` is AES-128-ECB with zero padding and no authenticated integrity.
- The traditional transmit path selects `DATA` or `DATA_ENCRYPTED` without
inspecting the IP version.
- `DATA_DUP` is plain and `DATA_ENC_DUP` is encrypted.
- Only encrypted data classes are session-decrypted.
Traditional fragments use a big-endian ID and a little-endian packed word.
The receiver combines exactly two fragments by EOP order, ignores offsets,
retains at most 256 pending groups, and expires them after 100 ms.
## Heartbeat, ping, and close
The traditional heartbeat body is 20 bytes, all little-endian:
```text
Requests are sent every two seconds. Ten misses or more than 20 seconds
without a valid response ends the session.
Ping is exactly 24 bytes with `session_id=0xffff`, `token=0xffffffff`, and no
body. A persistent session sends a 24-byte signed close. Receivers also accept
the eight-byte close used by temporary authentication probes.
## Segment Routing
An SR datagram is:
```text
sr_header || inner_standard_header || inner_payload
```
The SR header is:
```text
Link count is `1..6`, link IDs are `1..0x00ffffff`, and outer algorithms are
none, AES-128, and AES-256. Outbound paths reverse controller order and begin
at `next_id = link_count - 1`; returned paths use controller order and require
`next_id=0`.
Outer AES encrypts only bytes after the inner eight-byte header. It uses a raw
UTF-8 key prefix, AES-ECB-NoPadding, and zero padding recorded in the SR
header. IPv6 disables inner session encryption.
Fragmentation is available only when both encryption layers are off and
produces exactly two fragments. SR fragment IDs are little-endian. The SR
reassembler waits for gaps, ignores duplicate offsets, and rejects overlaps;
it retains at most 16 groups and 262144 bytes for two seconds.
Monitor packets use an unencrypted SR envelope, an unsigned inner echo header,
and a 40-byte body containing the traditional delay fields, `"SRID"`, a
big-endian SR ID, marker bytes, flags, and counters. The period is one second
and the peer-down threshold is five seconds.
## Managed HTTP
Managed discovery starts with `POST /lookup` against the primary lookup
service, then its fallback. Each service receives two attempts before a
seven-day cache is considered. The request uses `serviceType: "fgb"`; the
resolved service type is read from `data.type` and must be `serverlist`,
`saas`, or `controller`.
Controller domains post to the exact authentication URL returned by lookup.
The domain remains in the JSON body. `credential` selects password login and
`oidc` selects OAuth Authorization Code with PKCE S256.
Lookup, controller authentication, `/config`, and keepalive share a canonical
HMAC request with the actual method, decoded path, decoded and sorted query,
lowercase SHA-256 body digest, Unix timestamp, and lowercase 16-byte nonce.
Every retry receives a fresh timestamp, nonce, and signature.
Configuration requests use mobile API version 4 and this body shape:
```json
{
"domain": "active-domain",
"type": "client-platform",
"oem_name": "panabit",
"app_version": "compatibility-identifier",
"device_id": "device-id",
"userName": "optional",
"posture_version": 7
}
```
The wire compatibility identifier currently sent in `app_version` is
`2.3.0`; it is independent of the OpeniWAN package version. Android, iOS,
macOS, and Windows use their corresponding controller platform value. Linux
and other desktop Unix targets use `android` because the controller schema
has no Linux value.
Traditional controller lines are nested under `serverlist.serverlist`; SR
groups use the mutually exclusive top-level `sites` member. Each traditional
line may carry credentials associated with its server ID. SR credentials
belong to the selected entry's ingress.
Controller `passWord` is standard Base64 containing:
```text
The AES-256-GCM key and associated data are:
```text
```
The controller `app_id` selects the signing/decryption secret. The decoder
requires the exact nonce and tag sizes and authenticates the associated data.
Credential login probes ingresses, authenticates the selected line with a
temporary OPEN, and closes it. OIDC login obtains configuration and chooses
credentials by the selected server or SR ingress. Every persistent connection
then performs a fresh OPEN before creating TUN.
A posture object with a nonzero version triggers `/posture/evaluate`. Versions
encoded as integers or decimal strings are normalized. Access requires a true
local gate and an acknowledgement other than `DENY`.
Keepalive uses mobile API version 3, bearer authentication, five-second
connect/read timeouts, and one retry except after HTTP 401. Each attempt is
signed independently over the same serialized body.
## Known boundaries
The profile does not define:
- authoritative `DUP_PKT` scheduling;
- other-platform use of `NETMASK`;
- the preferred server construction of `OPEN_REJECT`;
- vendor names for SR monitor bits or marker `0x79`;
- relay-side SR path mutation;
- deployment-specific nested `/config` policy schemas;
- whether production servers require signed `CLOSE`;
- server-side duplicate suppression.
Changes in these areas require reproducible interoperability evidence and an
update to this reference.