OmniEPDG Architecture & Call Flows
This document describes the internal architecture of OmniEPDG, its protocol interfaces, UE state machines, and detailed message sequence diagrams for key procedures. OmniEPDG supports two operational modes: GTP mode (full 3GPP tunneling via PGW) and Simple VPN mode (local breakout with TUN interface). See the Operations Guide for a high-level comparison.
System Architecture
OmniEPDG is built on Erlang/OTP and implements the 3GPP ePDG (evolved Packet Data Gateway) network function. It bridges untrusted WiFi access to the mobile core network, allowing UEs to make and receive VoWiFi calls.
GTP Mode Architecture
In GTP mode, subscriber traffic is tunneled through a PGW using GTPv2-C for session control and the Linux kernel GTP-U module for the user plane.
Simple VPN Mode Architecture
In Simple VPN mode, subscriber traffic is routed locally through a Linux TUN interface. No PGW or GTP infrastructure is required. The Diameter S6b, GTPv2-C, and GTP-U components are replaced by the Simple VPN subsystem.
Supervisor Tree
OmniEPDG uses a one-for-all supervisor strategy, meaning if any child process crashes, all children are restarted. The supervisor conditionally starts different child processes depending on the operational mode.
Processes started in both modes:
| Process | Role | Description |
|---|---|---|
aaa_diameter_swx | Diameter SWx Client | Connects to the HSS for authentication and subscriber profile operations |
aaa_diameter_swm | Diameter SWm (Internal) | Routes Diameter EAP and session messages between the ePDG and AAA FSMs |
epdg_diameter_swm | SWm ePDG Handler | Handles the ePDG side of internal SWm Diameter signaling |
GTP mode additional processes:
| Process | Role | Description |
|---|---|---|
aaa_diameter_s6b | Diameter S6b Server | Accepts connections from the PGW for session authorization |
epdg_gtpc_s2b | GTPv2-C Client | Sends Create/Delete Session requests to the PGW over S2b |
gtp_u_kmod | GTP-U Kernel Handler | Manages GTP-U PDP contexts in the Linux kernel module |
Simple VPN mode additional processes:
| Process | Role | Description |
|---|---|---|
simple_vpn_supervisor | VPN Subsystem Supervisor | Supervises the IP pool and route manager processes |
simple_vpn_pool | IP Pool Manager | Allocates and releases IPv4 addresses from the configured CIDR pool using ETS |
simple_vpn_route | Route Manager | Creates the omniepdg0 TUN interface and manages per-subscriber host routes |
Per-UE State Machines
For each active subscriber (identified by IMSI), OmniEPDG creates two state machine instances:
- ePDG UE FSM (
epdg_ue_fsm) - Manages the subscriber's session lifecycle from the ePDG perspective: authentication, GTP tunnel creation, and teardown coordination - AAA UE FSM (
aaa_ue_fsm) - Manages the AAA-side signaling: Diameter SWx exchanges with the HSS and S6b exchanges with the PGW
Both FSMs are implemented as Erlang gen_statem processes with state function callback mode.
ePDG UE FSM States
The ePDG UE FSM tracks a subscriber's session from initial authentication request through active tunnel state to teardown. The FSM behavior diverges at the authenticated state based on the operational mode.
GTP Mode FSM
In GTP mode, tunnel establishment goes through GTPv2-C Create Session to the PGW, and teardown involves GTPv2-C Delete Session, PGW-initiated Delete Bearer, and HSS-initiated deregistration flows.
Simple VPN Mode FSM
In Simple VPN mode, the FSM takes a shortcut at the authenticated state. Instead of sending a GTPv2-C Create Session Request, the FSM allocates an IP address from the local pool, creates a host route on the TUN interface, and transitions directly to active. The GTP-specific teardown states (wait_create_session_resp, wait_delete_session_resp, dereg_pgw_wait_cancel, dereg_net_wait_s2b_delete) are not used.
ePDG UE FSM State Reference
| State | Mode | Description | Waiting For |
|---|---|---|---|
new | Both | Initial state. No active session. | Auth request from UE |
wait_auth_resp | Both | Authentication request sent via SWm DER. | SWm DEA with auth vectors or error |
authenticating | Both | Auth vectors received, EAP exchange in progress. | Location update / auth completion |
authenticated | Both | Authentication complete, subscriber profile downloaded. | Tunnel request from UE |
wait_create_session_resp | GTP | GTPv2-C Create Session Request sent to PGW. | Create Session Response from PGW |
active | Both | Tunnel/route operational. Subscriber traffic is flowing. | Teardown trigger |
wait_delete_session_resp | GTP | GTPv2-C Delete Session Request sent to PGW (UE-initiated teardown). | Delete Session Response from PGW |
wait_swm_sta | Both | SWm Session Termination Request sent. | SWm STA from AAA |
dereg_pgw_wait_cancel | GTP | PGW-initiated deregistration. Cancel Location sent to UE. | Cancel Location Result |
dereg_net_wait_cancel | GTP | Network/HSS-initiated deregistration. Cancel Location sent to UE. | Cancel Location Result |
dereg_net_wait_s2b_delete | GTP | Network-initiated deregistration. S2b Delete Session sent to PGW. | Delete Session Response |
AAA UE FSM States
The AAA UE FSM manages the Diameter signaling toward the HSS (SWx) and PGW (S6b) on behalf of each subscriber.
AAA UE FSM State Reference
| State | Description | Waiting For |
|---|---|---|
new | Initial state. No active AAA session. | Diameter auth request |
wait_swx_maa | SWx MAR sent to HSS for EAP-AKA vectors. | SWx MAA from HSS |
wait_swx_saa | SWx SAR sent to HSS for server assignment. | SWx SAA from HSS |
authenticated | Both ePDG and PGW sessions may be active. Tracks dual session state. | Session events |
auth_wait_swx_saa | SWx SAR sent for PGW update or user deregistration. | SWx SAA from HSS |
dereg_net_wait_s6b_asa | HSS-initiated deregistration. S6b ASR sent to PGW. | S6b ASA from PGW |
dereg_net_wait_swm_asa | S6b teardown complete. SWm ASR sent to ePDG. | SWm ASA from ePDG |
Call Flows
GTP Mode: Successful Session Establishment
This sequence shows a complete successful session from EAP-AKA authentication through to an active GTP tunnel.
GTP Mode: UE-Initiated Session Teardown
When the UE disconnects (e.g., switches from WiFi to cellular or user hangs up).
GTP Mode: PGW-Initiated Session Teardown
When the PGW terminates the session (e.g., policy violation, timeout, or administrative action).
GTP Mode: Network (HSS) Initiated Deregistration
When the HSS revokes a subscriber's registration (e.g., subscription change, fraud detection, or administrative action).
GTP Mode: HSS Profile Push and Re-Authentication
When the HSS pushes an updated subscriber profile, OmniEPDG triggers re-authentication on both the ePDG (SWm) and PGW (S6b) sessions per 3GPP TS 29.273 Section 8.1.2.3.3.
Simple VPN Mode: Successful Session Establishment
In Simple VPN mode, the session establishment is shorter. After EAP-AKA authentication, the ePDG FSM allocates an IP from the local pool and sets up a host route on the TUN interface, bypassing all PGW interaction. If skip_sar is enabled, the SAR/SAA exchange with the HSS is also skipped.
Simple VPN Mode: UE-Initiated Session Teardown
When the UE disconnects in Simple VPN mode, the FSM releases the allocated IP address and removes the host route.
Diameter Application IDs
| Application ID | Interface | Vendor ID | Description | Reference |
|---|---|---|---|---|
| 16777265 | SWx | 10415 (3GPP) | ePDG ↔ HSS authentication and subscriber management | 3GPP TS 29.273 |
| 16777272 | S6b | 10415 (3GPP) | AAA ↔ PGW session authorization | 3GPP TS 29.273 |
Diameter Result Codes
OmniEPDG maps Diameter result codes to internal cause values for cross-protocol error propagation.
Standard Result Codes
| Result Code | Name | Meaning |
|---|---|---|
| 2001 | DIAMETER_SUCCESS | Operation completed successfully |
| 2002 | DIAMETER_LIMITED_SUCCESS | Operation partially successful |
3GPP Experimental Result Codes
| Result Code | Name | Meaning | Reference |
|---|---|---|---|
| 4181 | DIAMETER_AUTHENTICATION_DATA_UNAVAILABLE | HSS temporarily cannot provide auth data | 3GPP TS 29.273 |
| 5001 | DIAMETER_ERROR_USER_UNKNOWN | Subscriber IMSI not found in HSS | 3GPP TS 29.273 |
| 5002 | DIAMETER_UNKNOWN_SESSION_ID | Session not found (used for stale STR/AAR) | RFC 6733 |
| 5003 | DIAMETER_AUTHORIZATION_REJECTED | Subscriber not authorized for service | 3GPP TS 29.273 |
| 5004 | DIAMETER_ERROR_ROAMING_NOT_ALLOWED | Roaming restrictions apply | 3GPP TS 29.273 |
| 5005 | DIAMETER_MISSING_AVP | Required AVP missing from message | RFC 6733 |
| 5012 | DIAMETER_UNABLE_TO_COMPLY | Generic processing failure | RFC 6733 |
| 5420 | DIAMETER_ERROR_UNKNOWN_EPS_SUBSCRIPTION | No EPS subscription found | 3GPP TS 29.273 |
| 5421 | DIAMETER_ERROR_RAT_NOT_ALLOWED | Access technology not permitted | 3GPP TS 29.273 |
| 5422 | DIAMETER_ERROR_EQUIPMENT_UNKNOWN | Device IMEI not recognized | 3GPP TS 29.273 |
GTPv2-C Cause Codes (GTP Mode Only)
OmniEPDG handles the following GTPv2-C cause codes in Create/Delete Session responses from the PGW. Codes 1-15 are informational, 16-63 indicate success, and 64+ indicate errors. See 3GPP TS 29.274 Section 8.4.
Success Causes
| Code | Name | Description |
|---|---|---|
| 16 | Request Accepted | Operation completed successfully |
| 17 | Request Accepted Partially | Partial success |
| 18 | New PDN Type (Network Preference) | PDN type changed due to network preference |
| 19 | New PDN Type (Single Address Bearer) | PDN type changed due to single address bearer restriction |
Error Causes (Selected)
| Code | Name | Description |
|---|---|---|
| 64 | Context Not Found | Session context not found on PGW |
| 73 | No Resources Available | PGW resource exhaustion |
| 78 | Missing or Unknown APN | Requested APN not configured on PGW |
| 82 | Denied in RAT | Access technology not permitted |
| 84 | All Dynamic Addresses Occupied | IP address pool exhausted on PGW |
| 92 | User Authentication Failed | Authentication failure at PGW |
| 93 | APN Access Denied | Subscriber not authorized for APN |
| 96 | IMSI/IMEI Not Known | Subscriber identity not recognized |
| 109 | Invalid Peer | Peer validation failed |
| 113 | APN Congestion | APN overloaded |
| 120 | GTP-C Entity Congestion | PGW control plane overloaded |
NAI Format
OmniEPDG identifies subscribers using the Network Access Identifier (NAI) format defined in 3GPP TS 23.003 Section 19:
<prefix><IMSI>@nai.epc.mnc<MNC>.mcc<MCC>.3gppnetwork.org
Identity Prefix and Authentication Type
The NAI prefix determines the EAP authentication method per 3GPP TS 23.003:
| Prefix | Authentication Type | Description |
|---|---|---|
0 | EAP-AKA | Standard AKA authentication (most common for WiFi calling) |
6 | EAP-AKA' | Enhanced AKA authentication with network binding |
OmniEPDG automatically selects the authentication method based on the UE's identity prefix. Most UEs use prefix 0 (EAP-AKA) for WiFi calling.
OmniEPDG extracts the IMSI from the NAI by parsing everything between the prefix and the @ symbol. The IMSI is then used as the primary key for all per-subscriber state machines and signaling operations.
Cryptographic Algorithms
OmniEPDG implements cryptographic algorithms per 3GPP TS 33.402 and RFC 7296 (IKEv2).
IKEv2 Encryption Algorithms
| Algorithm | ID | Key Size | Status | Reference |
|---|---|---|---|---|
| AES-CBC | 12 | 128, 192, 256 bits | Supported (default: 256) | RFC 3602 |
| AES-GCM-16 | 20 | 128, 192, 256 bits | Supported | RFC 5282 |
| AES-GCM-12 | 19 | 128, 192, 256 bits | Supported | RFC 5282 |
| AES-GCM-8 | 18 | 128, 192, 256 bits | Supported | RFC 5282 |
| 3DES | 3 | 192 bits | Supported (legacy) | RFC 2451 |
IKEv2 Integrity Algorithms
| Algorithm | ID | Key Size | ICV Size | Status | Reference |
|---|---|---|---|---|---|
| HMAC-SHA2-256-128 | 12 | 256 bits | 128 bits | Supported (default) | RFC 4868 |
| HMAC-SHA2-384-192 | 13 | 384 bits | 192 bits | Supported | RFC 4868 |
| HMAC-SHA2-512-256 | 14 | 512 bits | 256 bits | Supported | RFC 4868 |
| AES-XCBC-96 | 5 | 128 bits | 96 bits | Supported | RFC 3566 |
| HMAC-SHA1-96 | 2 | 160 bits | 96 bits | Supported (legacy) | RFC 2404 |
| HMAC-MD5-96 | 1 | 128 bits | 96 bits | Supported (legacy) | RFC 2403 |
AES-XCBC-96 (AUTH_AES_XCBC_96) is required by some handsets — notably certain Samsung VoWiFi clients — which offer it as their only integrity transform. It is implemented per RFC 3566 with the variable-key handling and SKEYSEED nonce truncation defined in RFC 4434 and RFC 7296 Section 2.14.
IKEv2 PRF Algorithms
| Algorithm | ID | Output Size | Status | Reference |
|---|---|---|---|---|
| PRF-HMAC-SHA2-256 | 5 | 256 bits | Supported (default) | RFC 4868 |
| PRF-HMAC-SHA2-384 | 6 | 384 bits | Supported | RFC 4868 |
| PRF-HMAC-SHA2-512 | 7 | 512 bits | Supported | RFC 4868 |
| PRF-AES128-XCBC | 4 | 128 bits | Supported | RFC 4434 |
| PRF-HMAC-SHA1 | 2 | 160 bits | Supported (legacy) | RFC 2104 |
| PRF-HMAC-MD5 | 1 | 128 bits | Supported (legacy) | RFC 2104 |
When PRF-AES128-XCBC is negotiated, SKEYSEED is derived from only the first 64 bits of each of Ni and Nr (per RFC 7296 Section 2.14), while the full nonces feed the prf+ key expansion.
IKEv2 Diffie-Hellman Groups
| Group | ID | Size | Status | Reference |
|---|---|---|---|---|
| MODP-2048 | 14 | 2048 bits | Supported (default) | RFC 3526 |
| MODP-1024 | 2 | 1024 bits | Supported (legacy) | RFC 2409 |
| MODP-1536 | 5 | 1536 bits | Supported | RFC 3526 |
| MODP-3072 | 15 | 3072 bits | Supported | RFC 3526 |
| MODP-4096 | 16 | 4096 bits | Supported | RFC 3526 |
| ECP-256 | 19 | 256 bits | Supported | RFC 5903 |
| ECP-384 | 20 | 384 bits | Supported | RFC 5903 |
| ECP-521 | 21 | 521 bits | Supported | RFC 5903 |
| Curve25519 | 31 | 256 bits | Supported | RFC 8031 |
| Curve448 | 32 | 448 bits | Supported | RFC 8031 |
ESP (Child SA) Algorithms
The ESP tunnel algorithms are negotiated from the SA proposal the UE offers in IKE_AUTH (and in CREATE_CHILD_SA on rekey). OmniEPDG selects a transform the UE actually offered and derives the Child SA keys with the matching key and ICV sizes — it does not force a fixed suite.
| Type | Algorithms | Notes |
|---|---|---|
| Encryption | AES-CBC-128 / 192 / 256 | Cipher follows the negotiated key length |
| Integrity | HMAC-SHA2-256-128, HMAC-SHA2-384-192, HMAC-SHA2-512-256, AES-XCBC-96, HMAC-SHA1-96 | AES-XCBC-96 ICV is 12 bytes (vs 16 for HMAC-SHA2-256-128) |
Fallback (only when the UE's proposal cannot be parsed):
- Encryption: AES-CBC-256 (32-byte key, 16-byte IV)
- Integrity: HMAC-SHA2-256-128 (32-byte key, 16-byte ICV)
EAP-AKA Cryptographic Functions
| Function | Algorithm | Reference |
|---|---|---|
| MK derivation | SHA-1 | RFC 4187 Section 7 |
| PRF+ key expansion | FIPS 186-2 PRF (SHA-1) | RFC 4187 Appendix D |
| AT_MAC | HMAC-SHA1-128 | RFC 4187 Section 10.15 |
| Milenage (f1-f5) | AES-128 | 3GPP TS 35.206 |
EAP-AKA' Cryptographic Functions
| Function | Algorithm | Reference |
|---|---|---|
| CK'/IK' derivation | HMAC-SHA-256 | RFC 5448 Section 3.3 |
| MK derivation | SHA-256 | RFC 5448 Section 3.4 |
| AT_MAC | HMAC-SHA256-128 | RFC 5448 Section 3.1 |
3GPP Compliance
OmniEPDG implements all mandatory cryptographic algorithms specified in 3GPP TS 33.402 Section 8:
| Requirement | Algorithm | Status |
|---|---|---|
| IKEv2 Encryption (mandatory) | AES-CBC-128 | ✓ Supported |
| IKEv2 Integrity (mandatory) | HMAC-SHA2-256-128 | ✓ Supported (default) |
| IKEv2 PRF (mandatory) | PRF-HMAC-SHA-256 | ✓ Supported (default) |
| IKEv2 DH (mandatory) | Group 14 (MODP-2048) | ✓ Supported (default) |
| ESP Encryption (mandatory) | AES-CBC-128/256 | ✓ Supported |
| ESP Integrity (mandatory) | HMAC-SHA2-256-128 | ✓ Supported (default) |
| EAP-AKA | RFC 4187 | ✓ Implemented |
| EAP-AKA' | RFC 5448 | ✓ Implemented |
Beyond the mandatory set, OmniEPDG also supports the AES-XCBC integrity and PRF transforms (RFC 3566 / RFC 4434) for interoperability with handsets that offer them exclusively — for example certain Samsung VoWiFi clients, which propose AES-CBC-256 / AUTH_AES_XCBC_96 / PRF_AES128_XCBC / MODP-2048 and will not fall back to HMAC-SHA2.
PDP Address Types (GTP Mode Only)
OmniEPDG supports the following PDP address types as defined in 3GPP TS 29.274 Section 8.14. In Simple VPN mode, only IPv4 addresses are allocated from the local pool.
| Type | Description | GTPv2-C PAA Format |
|---|---|---|
| IPv4 | IPv4-only bearer | 4-byte IPv4 address |
| IPv6 | IPv6-only bearer | 1-byte prefix length + 16-byte IPv6 address |
| IPv4v6 | Dual-stack bearer | 1-byte prefix length + 16-byte IPv6 + 4-byte IPv4 |