WireGuard Android

To build the WireGuard Android application from source, clone the repository including all submodules and use the Gradle wrapper to assemble a release build. macOS users may require flock(1) to complete the build process.

$ git clone --recurse-submodules https://git.zx2c4.com/wireguard-android
$ cd wireguard-android
$ ./gradlew assembleRelease

You can embed the WireGuard tunnel library into your own Android project via Maven Central. The library requires Java 8+ support, so you must enable library desugaring in your Gradle configuration.

implementation 'com.wireguard.android:tunnel:$wireguardTunnelVersion'

Because the WireGuard tunnel library uses Java 8 features, you must configure your build.gradle to support desugaring. Set the sourceCompatibility and targetCompatibility to JavaVersion.VERSION_17 (or your required version) and enable coreLibraryDesugaring.

compileOptions {
    sourceCompatibility JavaVersion.VERSION_17
    targetCompatibility JavaVersion.VERSION_17
    coreLibraryDesugaringEnabled = true
}

dependencies {
    coreLibraryDesugaring "com.android.tools:desugar_jdk_libs:2.0.3"
}

The TunnelManager class is the primary interface for managing the lifecycle and state of WireGuard tunnels. It mediates between the ConfigStore (persistent storage) and the Backend (the actual VPN engine).

Key capabilities include:

• Creating and Deleting Tunnels: Adding new configurations or removing existing ones.
• State Control: Bringing tunnels UP or DOWN.
• Configuration Management: Loading, saving, and renaming tunnel configurations.
• Observability: Providing access to an observable list of tunnels and their real-time statistics.

Use wgGetConfig to retrieve the current WireGuard configuration settings from an active tunnel.

Parameters:

• tunnelHandle (int32): The unique handle returned by wgTurnOn.

Returns:

• A pointer to a C-style string (*C.char) containing the current settings. Note: The caller is responsible for managing the memory of the returned string according to C conventions.

Use wgTurnOn to initialize a WireGuard device using a provided TUN file descriptor. This function sets up the device, applies initial settings, starts the UAPI listener for management, and brings the interface up.

Parameters:

• interfaceName (string): The name of the network interface.
• tunFd (int32): The file descriptor of the existing TUN device.
• settings (string): The initial WireGuard configuration settings (UAPI format).

Returns:

• An int32 representing a unique tunnelHandle if successful, or -1 if an error occurs.

Use wgVersion to retrieve the version of the WireGuard library used in the current build.

Returns:

• A pointer to a C-style string (*C.char) containing the version information. Returns "unknown" if the version cannot be determined.

You can programmatically control whether a tunnel is active or modify its settings.

• setTunnelState(tunnel, state): Transitions a tunnel to the requested Tunnel.State (e.g., UP or DOWN).
• setTunnelConfig(tunnel, config): Updates the configuration for an existing tunnel.
• setTunnelName(tunnel, name): Renames a tunnel. This handles the necessary backend and storage updates to ensure consistency.
• getTunnelStatistics(tunnel): Retrieves real-time Statistics for the specified tunnel.

Use create to add a new tunnel and delete to remove one.

• create(name, config): Creates a new tunnel with the specified name and config. Throws IllegalArgumentException if the name is invalid or already exists.
• delete(tunnel): Removes the specified ObservableTunnel. If the tunnel is currently UP, it is first brought DOWN via the backend before deletion.

Use wgTurnOff to shut down a running WireGuard tunnel and release its resources. This closes the UAPI listener and the underlying WireGuard device.

Parameters:

• tunnelHandle (int32): The unique handle returned by a previous call to wgTurnOn.

The FileConfigStore is an implementation of the ConfigStore interface that persists WireGuard tunnel configurations as files in the application's internal files directory. It uses a wg-quick-style format, where each tunnel is stored in a .conf file named after the tunnel.

Key behaviors:

• File Naming: Tunnels are identified by a name, which corresponds to a file named {name}.conf.
• Format: Configurations are serialized using Config.toWgQuickString() and stored as UTF-8 encoded text.
• Enumeration: Calling enumerate() returns a set of all tunnel names currently stored (by stripping the .conf suffix from existing files).