WireGuard Android Library

Simplify the integration of WireGuard VPN in your Android applications with this library. This library provides a clean API to manage VPN connections, handle configurations, and monitor tunnel states.

---

Features

• Lightweight & Fast: Minimal overhead with seamless integration.
• Comprehensive API: Start, stop, and monitor VPN connections effortlessly.
• State Broadcasts: Easily observe and react to connection state changes.
• Cross-Language Support: Examples provided in both Kotlin and Java.
• Customizable: Option to directly include the library source for deeper customization.

---

Installation

Option 1: Using JitPack Dependency

This library is available via JitPack. Add the repository and dependency to your project:

Gradle Groovy

allprojects {
    repositories {
        ...
        maven { url 'https://jitpack.io' }
    }
}

dependencies {
    implementation 'com.github.CodeWithTamim:WGAndroidLib:1.0.1'
}

Gradle Kotlin DSL

repositories {
   ...
   maven("https://jitpack.io")
}

dependencies {
   implementation("com.github.CodeWithTamim:WGAndroidLib:1.0.1")
}

Option 2: Importing the WireGuard Module

For advanced users who want more control or customization, you can directly include the WireGuard module in your project using Android Studio.

1. Clone the repository:

   git clone https://github.com/CodeWithTamim/WGAndroidLib.git

2. In Android Studio, follow these steps:

   • Go to File > New > Import Module.
   • Select the wireguard module folder from the cloned repository.
   • Click Finish to add the module to your project.

3. Add the module as a dependency in your app's build.gradle (Groovy) or build.gradle.kts (Kotlin DSL):

Gradle Groovy

dependencies {
    implementation project(':wireguard')
}

Gradle Kotlin DSL

dependencies {
    implementation(project(":wireguard"))
}

---

Setup

1. Configure the Application Class

Create an Application class to configure a notification channel for VPN usage:

Kotlin Example

class TunnelApplication : Application() {
    override fun onCreate() {
        super.onCreate()
        createNotificationChannel()
    }

    private fun createNotificationChannel() {
        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
            val manager = NotificationManagerCompat.from(this)
            val channel = NotificationChannel(
                CHANNEL_ID,
                CHANNEL_NAME,
                NotificationManager.IMPORTANCE_HIGH
            )
            manager.createNotificationChannel(channel)
        }
    }
}

Java Example

public class TunnelApplication extends Application {
    @Override
    public void onCreate() {
        super.onCreate();
        createNotificationChannel();
    }

    private void createNotificationChannel() {
        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
            NotificationManager manager = (NotificationManager) getSystemService(Context.NOTIFICATION_SERVICE);
            NotificationChannel channel = new NotificationChannel(
                CHANNEL_ID,
                CHANNEL_NAME,
                NotificationManager.IMPORTANCE_HIGH
            );
            manager.createNotificationChannel(channel);
        }
    }
}

2. Add Required Permissions

Add these permissions to your AndroidManifest.xml file:

<uses-permission android:name="android.permission.FOREGROUND_SERVICE_SPECIAL_USE" />
<uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.POST_NOTIFICATIONS" />

3. Register Services

Declare the required services in AndroidManifest.xml:

<service
    android:name="com.nasahacker.wireguard.service.TunnelService"
    android:exported="true"
    android:foregroundServiceType="specialUse"
    android:permission="android.permission.FOREGROUND_SERVICE" />

<service
    android:name="com.wireguard.android.backend.GoBackend$VpnService"
    android:exported="true"
    android:permission="android.permission.BIND_VPN_SERVICE">
    <intent-filter>
        <action android:name="android.net.VpnService" />
    </intent-filter>
</service>

---

Usage

Initialize the Service Manager

Kotlin Example

ServiceManager.init(this, R.drawable.notification_icon)

Java Example

ServiceManager.init(this, R.drawable.notification_icon);

Prepare for VPN Connection

Kotlin

if (!ServiceManager.isPreparedForConnection(context)) {
    ServiceManager.prepareForConnection(activity)
}

Java

if (!ServiceManager.isPreparedForConnection(context)) {
    ServiceManager.prepareForConnection(activity);
}

Start the VPN

Kotlin

val config = TunnelConfig(
    Interface("10.0.0.1/24", "privateKey", 51820),
    Peer("publicKey", listOf("0.0.0.0/0"), "endpoint:51820")
)
ServiceManager.startTunnel(context, config, blockedApps = listOf("com.example.app"))

Java

TunnelConfig config = new TunnelConfig(
    new Interface("10.0.0.1/24", "privateKey", 51820),
    new Peer("publicKey", Arrays.asList("0.0.0.0/0"), "endpoint:51820")
);
ServiceManager.startTunnel(context, config, Arrays.asList("com.example.app"));

Stop the VPN

Kotlin

ServiceManager.stopTunnel(context)

Java

ServiceManager.stopTunnel(context);

---

Listen for Tunnel State Changes

Register a broadcast receiver to listen for state changes:

Kotlin Example

val receiver = object : BroadcastReceiver() {
    override fun onReceive(context: Context?, intent: Intent?) {
        val state = intent?.getStringExtra("TUNNEL_STATE")
        // Handle state change: CONNECTED, DISCONNECTED, CONNECTING
    }
}
context.registerReceiver(receiver, IntentFilter("TUNNEL_STATE_ACTION"))

Java Example

BroadcastReceiver receiver = new BroadcastReceiver() {
    @Override
    public void onReceive(Context context, Intent intent) {
        String state = intent.getStringExtra("TUNNEL_STATE");
        // Handle state change: CONNECTED, DISCONNECTED, CONNECTING
    }
};
context.registerReceiver(receiver, new IntentFilter("TUNNEL_STATE_ACTION"));

---

Tunnel Configurations

Define configurations for the VPN connection using the TunnelConfig model.

Kotlin Example

val config = TunnelConfig(
    Interface("10.0.0.1/24", "privateKey", 51820),
    Peer("publicKey", listOf("0.0.0.0/0"), "endpoint:51820")
)

Java Example

TunnelConfig config = new TunnelConfig(
    new Interface("10.0.0.1/24", "privateKey", 51820),
    new Peer("publicKey", Arrays.asList("0.0.0.0/0"), "endpoint:51820")
);

---

Tunnel States

The library supports these tunnel states:

• CONNECTED: VPN is active and connected.
• DISCONNECTED: VPN is stopped.
• CONNECTING: VPN is in the process of connecting.

States are broadcasted by the service and can be used to update your UI.

---

Acknowledgments

This library is based on the WireGuard Android project. Special thanks to the WireGuard team for their incredible work.

---

License

This project is licensed under the Apache 2.0 License. See the LICENSE file for details.

---

Developed by Tamim Hossain.