# openvpn/openvpn3 architecture

> Architecture diagram of the GitHub repository openvpn/openvpn3, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/openvpn/openvpn3
- Repository: https://github.com/openvpn/openvpn3

## Overview

##### 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

## Diagram (Mermaid)

```mermaid
graph TB
    %% User-land Layer
    subgraph "User-land"
        direction TB
        CLI["ovpncli Wrapper (C++ main)"]:::api
        JNI["JNI/Java Wrapper"]:::api
        API["Client Public API"]:::api
    end

    %% Protocol Core Layer
    subgraph "Protocol Core"
        direction TB
        CC["Control Channel"]:::core
        DC["Data Channel"]:::core
        FR["Framing"]:::core
        BF["Buffering"]:::core
    end

    %% Crypto & Compression
    subgraph "Crypto & Compression"
        direction TB
        CRYPTOLIB["Crypto Library"]:::crypto
        OPENSSL["OpenSSL Backend"]:::crypto
        MBEDTLS["mbedTLS Backend"]:::crypto
        APPLECRYPTO["AppleCrypto Backend"]:::crypto
        COMPRESS["Compression"]:::crypto
    end

    %% Transport Abstraction
    subgraph "Transport"
        direction TB
        ASIO["ASIO Sockets"]:::transport
        UDPTCP["UDP/TCP Transport"]:::transport
        WS["WebSockets"]:::transport
        HTTPP["HTTP Proxy"]:::transport
        DCOINT["DCO Integration"]:::transport
    end

    %% TUN Interface
    subgraph "TUN Interface"
        direction TB
        TUNBUILDER["Tun Builder & Setup"]:::tun
        TUNIO["Tun I/O"]:::tun
        LINUXTUN["Linux TUN Client"]:::tun
        WIN_TUN["Windows TUN Client"]:::tun
        MAC_TUN["macOS TUN Client"]:::tun
    end

    %% Platform Abstraction
    subgraph "Platform Abstraction"
        direction TB
        NETCONF["Network Configuration"]:::platform
        INIT["Initialization Engine"]:::platform
        LOG["Logging Framework"]:::platform
    end

    %% Kernel Land
    subgraph "Kernel Land"
        direction TB
        VIRTUN["Virtual TUN Device (Kernel)"]:::kernel
        DCOKERNEL["DCO Kernel Module"]:::kernel
    end

    %% Control Flow & Data Flow
    CLI -->|"Control"| API
    JNI -->|"Control"| API
    API -->|"Control"| CC
    CC -- "TLS Handshake" --> OPENSSL
    CC -- "TLS Handshake" --> MBEDTLS
    CC -- "TLS Handshake" --> APPLECRYPTO
    CC -->|"Control"| CRYPTOLIB
    DC -->|"Control"| BF
    DC -->|"Control"| FR
    DC -->|"Control"| CRYPTOLIB
    CRYPTOLIB -->|"calls"| OPENSSL
    CRYPTOLIB -->|"calls"| MBEDTLS
    CRYPTOLIB -->|"calls"| APPLECRYPTO
    COMPRESS -->|"Data"| DC
    BF -->|"Data"| DC
    FR -->|"Data"| DC
    DC -->|"Data"| ASIO
    ASIO -- "UDP/TCP" --> UDPTCP
    ASIO -- "WebSocket" --> WS
    HTTPP -->|"Control"| UDPTCP
    DCOINT -->|"Control"| DCOKERNEL
    DC -.->|"Outbound Data Flow Step 1-8"| TUNIO
    TUNIO -->|"Writes Packets"| VIRTUN
    VIRTUN -->|"Inject Packet"| Kernel
    VIRTUN -->|"Offload"| DCOKERNEL

    %% Click Events
    click CLI "https://github.com/openvpn/openvpn3/blob/master/client/ovpncli.cpp"
    click API "https://github.com/openvpn/openvpn3/blob/master/client/ovpncli.hpp"
    click JNI "https://github.com/openvpn/openvpn3/blob/master/javacli/Main.java"
    click JNI "https://github.com/openvpn/openvpn3/blob/master/javacli/Client.java"
    click JNI "https://github.com/openvpn/openvpn3/blob/master/javacli/OpenVPNClientThread.java"
    click CC "https://github.com/openvpn/openvpn3/blob/master/openvpn/ssl/protostack.hpp"
    click CC "https://github.com/openvpn/openvpn3/blob/master/openvpn/ssl/customcontrolchannel.hpp"
    click DC "https://github.com/openvpn/openvpn3/blob/master/openvpn/transport/pktstream.hpp"
    click DC "https://github.com/openvpn/openvpn3/blob/master/openvpn/reliable/relcommon.hpp"
    click FR "https://github.com/openvpn/openvpn3/blob/master/openvpn/frame/frame.hpp"
    click FR "https://github.com/openvpn/openvpn3/blob/master/openvpn/frame/frame_init.hpp"
    click BF "https://github.com/openvpn/openvpn3/blob/master/openvpn/buffer/buffer.hpp"
    click BF "https://github.com/openvpn/openvpn3/blob/master/openvpn/buffer/bufcomposed.hpp"
    click CRYPTOLIB "https://github.com/openvpn/openvpn3/blob/master/openvpn/crypto/cryptochoose.hpp"
    click CRYPTOLIB "https://github.com/openvpn/openvpn3/blob/master/openvpn/crypto/cipher.hpp"
    click OPENSSL "https://github.com/openvpn/openvpn3/blob/master/openvpn/openssl/crypto/api.hpp"
    click OPENSSL "https://github.com/openvpn/openvpn3/blob/master/openvpn/openssl/ssl/sslctx.hpp"
    click MBEDTLS "https://github.com/openvpn/openvpn3/blob/master/openvpn/mbedtls/crypto/api.hpp"
    click MBEDTLS "https://github.com/openvpn/openvpn3/blob/master/openvpn/mbedtls/ssl/sslctx.hpp"
    click APPLECRYPTO "https://github.com/openvpn/openvpn3/blob/master/openvpn/applecrypto/crypto/api.hpp"
    click APPLECRYPTO "https://github.com/openvpn/openvpn3/blob/master/openvpn/applecrypto/ssl/sslctx.hpp"
    click ASIO "https://github.com/openvpn/openvpn3/blob/master/openvpn/asio/asiocontext.hpp"
    click ASIO "https://github.com/openvpn/openvpn3/blob/master/openvpn/asio/asioboundsock.hpp"
    click UDPTCP "https://github.com/openvpn/openvpn3/blob/master/openvpn/transport/client/udpcli.hpp"
    click UDPTCP "https://github.com/openvpn/openvpn3/blob/master/openvpn/transport/client/tcpcli.hpp"
    click WS "https://github.com/openvpn/openvpn3/blob/master/openvpn/ws/websocket.hpp"
    click WS "https://github.com/openvpn/openvpn3/blob/master/openvpn/ws/httpcli.hpp"
    click HTTPP "https://github.com/openvpn/openvpn3/blob/master/openvpn/http/request.hpp"
    click HTTPP "https://github.com/openvpn/openvpn3/blob/master/openvpn/http/reply.hpp"
    click DCOINT "https://github.com/openvpn/openvpn3/blob/master/openvpn/dco/ovpndcocli.hpp"
    click DCOINT "https://github.com/openvpn/openvpn3/blob/master/openvpn/dco/korekey.hpp"
    click TUNBUILDER "https://github.com/openvpn/openvpn3/blob/master/openvpn/tun/builder/client.hpp"
    click TUNBUILDER "https://github.com/openvpn/openvpn3/blob/master/openvpn/tun/builder/setup.hpp"
    click TUNIO "https://github.com/openvpn/openvpn3/blob/master/openvpn/tun/tunio.hpp"
    click TUNIO "https://github.com/openvpn/openvpn3/blob/master/openvpn/tun/tunlog.hpp"
    click LINUXTUN "https://github.com/openvpn/openvpn3/blob/master/openvpn/tun/linux/client/tuncli.hpp"
    click LINUXTUN "https://github.com/openvpn/openvpn3/blob/master/openvpn/tun/linux/client/tunsetup.hpp"
    click WIN_TUN "https://github.com/openvpn/openvpn3/blob/master/openvpn/tun/win/client/tuncli.hpp"
    click WIN_TUN "https://github.com/openvpn/openvpn3/blob/master/openvpn/tun/win/client/wintun.hpp"
    click MAC_TUN "https://github.com/openvpn/openvpn3/blob/master/openvpn/tun/mac/client/tuncli.hpp"
    click MAC_TUN "https://github.com/openvpn/openvpn3/blob/master/openvpn/tun/mac/client/tunsetup.hpp"
    click NETCONF "https://github.com/openvpn/openvpn3/blob/master/openvpn/netconf/linux/route.hpp"
    click NETCONF "https://github.com/openvpn/openvpn3/blob/master/openvpn/netconf/enumiface.hpp"
    click INIT "https://github.com/openvpn/openvpn3/blob/master/openvpn/init/initprocess.hpp"
    click INIT "https://github.com/openvpn/openvpn3/blob/master/openvpn/init/engineinit.hpp"
    click LOG "https://github.com/openvpn/openvpn3/blob/master/openvpn/log/logger.hpp"
    click LOG "https://github.com/openvpn/openvpn3/blob/master/openvpn/log/logbase.hpp"
    click DCOKERNEL "https://github.com/openvpn/openvpn3/blob/master/openvpn/dco/ovpn-dco.h"
    click DCOKERNEL "https://github.com/openvpn/openvpn3/blob/master/openvpn/dco/ovpndcowincli.hpp"

    %% Styles
    classDef api fill:#D0E8FF,stroke:#004080
    classDef core fill:#DFFFE0,stroke:#008000
    classDef crypto fill:#FFE8CC,stroke:#FF8000
    classDef transport fill:#E8D0FF,stroke:#800080
    classDef tun fill:#F5E1D0,stroke:#A0522D
    classDef platform fill:#F0F0F0,stroke:#606060
    classDef kernel fill:#D0D0D0,stroke:#404040
```
