How openvpn/openvpn3 works
Project Type and Purpose
• OpenVPN 3 is a C++ class library implementing an OpenVPN client (no server).
• It provides a minimal command-line wrapper (ovpncli) and a rich API (client/ovpncli.hpp) consumed by OpenVPN Connect apps across platforms.
High-Level File-Structure Analysis
• Top-level:
• client/ + javacli/: CLI wrappers
• openvpn/: core protocol implementation (submodules: tun, transport, ssl, crypto, compress, buffer, netconf, etc.)
• deps/ + cmake/ + scripts/ + CMakeLists.txt: build & dependency management
• test/: unit and integration tests
• Architectural patterns:
• Layered design: platform-abstraction (ASIO, Apple, Linux, Windows), protocol core, API/wrapper
• Modular subsystems: Control Channel, Data Channel, Crypto backends, TUN interface
Key Components
• CLI Layer
• ovpncli wrapper (C++ main)
• JNI/Java wrapper in javacli/
• Client API Layer
• client/ovpncli.hpp – public API entry‐points
• Configuration parsing, credential handling
• Core Protocol Library
• Control Channel (TLS handshake & option exchange)
• Data Channel (packet encapsulation, reliability, fragmentation)
• Compression (compress/…), Buffering (buffer/…), Packet framing (frame/…)
• Crypto Subsystems
• OpenSSL, mbedTLS, AppleCrypto, native crypto backends under openvpn/crypto, openvpn/openssl, openvpn/mbedtls, openvpn/applecrypto
• Transport Abstraction
• UDP/TCP sockets via ASIO (openvpn/asio/…)
• WebSockets (ws/…), HTTP proxy (http/…, proxy/…)
• DCO (data channel offload) integration (dco/…)
• TUN Interface Abstraction
• Tun builder & client layers (tun/…), platform specifics (tun/linux/…, tun/win/…, tun/mac/…)
• Platform & System Integrations
• Network config (netconf/…), System init (init/…), Logging (log/…)
• OS kernel components: virtual TUN device, kernel DCO module
Relationships & Interactions
• CLI → Client API → Core Library
• Core Library ↔ Crypto → Transport
• Core Library ↔ Compression/Buffer/Frame
• Core Library ↔ TUN Abstraction ↔ OS Kernel (virtual NIC)
• Platform Abstraction (ASIO, netconf, init) underlies transports and tun
Architectural Patterns & Principles
• Layered modularity: each subsystem communicates via well-defined interfaces
• Dependency inversion: core logic depends on abstract interfaces (e.g., socket, tun), implemented per platform
• Single Responsibility: separate modules for crypto, compression, framing, transport, tun, configuration
Control Flow for Packets From/To TUN
a. Packet From TUN → Outbound Path
1. OS kernel delivers IP packet via virtual TUN interface
2. Tun client abstraction reads packet (tun/io.cpp)
3. Buffering & framing (buffer/…, frame/…)
4. Data Channel module:
– Reliability layer (reliable/…)
– Fragmentation & sequencing (transport/pktstream.hpp)
5. Compression (if enabled)
6. Encryption into TLS record via Crypto backend
7. Send via ASIO UDP socket → Network
8. (If DCO present) offload crypto & transport to kernel DCO module
b. Packet From Network → Inbound Path
1. ASIO UDP socket receives TLS record
2. Decrypt via Crypto backend (OpenSSL/mbedTLS)
3. Decompression (if enabled)
4. Reassembly & de-fragmentation (Data Channel reliability)
5. Buffer & frame extraction
6. Tun client abstraction writes packet back to TUN (tun/client/tuncli.cpp)
7. OS kernel injects packet into virtual network interface