How schwabe/ics-openvpn works
Project Type and Purpose
• This is a full-stack Android application: an open-source OpenVPN client for Android (API level 14+).
• It combines a native VPN engine (C/C++), a Java core service layer exposing AIDL APIs, and a rich Android UI.
• Additional modules include sample apps (remoteExample) demonstrating AIDL control and a TLS external certificate provider (tlsexternalcertprovider).
File-Structure Analysis
• Top-level folders:
• main/ – the main OpenVPN Android app
• remoteExample/ – sample app showing external control via AIDL
• tlsexternalcertprovider/ – sample app implementing ExternalCertificateProvider AIDL
• Inside main/:
• src/main/cpp/ – native engine and third-party libs (openvpn3, lzo, lz4, mbedtls, openssl, jniglue, ovpnutil)
• src/main/java/de/blinkt/openvpn/core/ – Java VPN service, config parser, thread management, JNI wrappers
• src/main/java/de/blinkt/openvpn/api/ – AIDL interface definitions and API entry points
• src/main/java/de/blinkt/openvpn/activities & fragments – UI screens and user workflows
• src/main/aidl/ – AIDL files defining the external service contracts
• src/skeleton/ – plugin skeleton for extensibility
• src/test/ & src/testui/ – unit and UI tests
• Build & config:
• Gradle (Kotlin DSL) scripts, CMakeLists.txt, NDK configuration, AndroidManifest.xml, ProGuard rules.
Key Technologies
• Android SDK & APIs (VpnService, Notification, Intent system, UI toolkit)
• Java/Kotlin for core service and UI
• JNI bridge (jniglue.c/.h) connecting Java to native C/C++
• Native engine: OpenVPN core, LZO/LZ4 compression, mbedtls/OpenSSL crypto
• AIDL for cross-process control (ConnectVPN, DisconnectVPN, PauseVPN, ResumeVPN)
• Gradle, CMake, NDK for multi-platform native builds
Main Components
a. Android OS Framework
• VPNService API (platform)
• Notification manager, Intent dispatcher
b. Application Layers
1. UI Layer
– Activities/Fragments (MainActivity, Settings*, LogWindow, FileSelect, TileService)
– Interacts with the Java core via Intents and bound service calls
2. Java Core Service Layer
– OpenVPNService & OpenVPNStatusService (extends VpnService)
– AIDL API implementation (de.blinkt.openvpn.api.*)
– ConfigParser, ProfileManager, TrafficHistory, LogFileHandler
– JNI wrappers to native engine (NativeUtils, OpenVPNThread)
3. JNI Bridge
– jniglue.c / osslutil.cpp
– Marshals data and control commands between Java and C++
4. Native VPN Engine
– openvpn3 code, openvpn-config parser, ovpnutil
– Compression libs: lzo, lz4
– Crypto libs: mbedtls, OpenSSL
5. Storage & Assets
– .ovpn profile files (private storage), SharedPreferences, SQLite or file-based storage
c. External Modules (Show as separate but connected)
– remoteExample app (binds to AIDL API)
– tlsexternalcertprovider service (implements ExternalCertificateProvider AIDL)
Relationships & Data Flows
• UI <→ binds to → Java Core Service (via Context.bindService / AIDL)
• UI ↔ Intents → Core Service (start/pause/resume via Broadcast receivers)
• Java Core Service ↔ JNI → Native Engine (start/stop VPN tunnels)
• Native Engine ↔ Android VPNService → Kernel TUN interface (packet I/O)
• Java Core Service ↔ Storage (load/save profiles and logs)
• External Apps ↔ AIDL → Java Core Service (remote control)
• External Certificate Provider ↔ AIDL → Java Core Service (on-demand cert selection)
Architectural Patterns & Principles
• Layered architecture: UI → Service → Native engine
• Adapter pattern: JNI glue adapts Java calls to C APIs
• Observer pattern: StatusListener callbacks in Java for UI updates
• Modularization: separate native libs, Java core, UI, sample extensions
• Dependency inversion: high-level modules (UI, API) depend on abstractions (AIDL, interfaces)