aboutsummaryrefslogtreecommitdiffstatshomepage
diff options
context:
space:
mode:
authorHarsh Shandilya <me@msfjarvis.dev>2020-04-09 14:54:03 +0530
committerHarsh Shandilya <me@msfjarvis.dev>2020-04-09 14:54:03 +0530
commitf0afd2da5b7ad18846caf514f2ab40c8754381ad (patch)
treec3b991d6a53a010a300d9f4666fc9c97c17c4042
parentstrings: sync translations (diff)
downloadwireguard-android-refactor/tunnel-module-docs.tar.xz
wireguard-android-refactor/tunnel-module-docs.zip
tunnel: document backend packagerefactor/tunnel-module-docs
Signed-off-by: Harsh Shandilya <me@msfjarvis.dev>
-rw-r--r--tunnel/src/main/java/com/wireguard/android/backend/Backend.java2
-rw-r--r--tunnel/src/main/java/com/wireguard/android/backend/BackendException.java20
-rw-r--r--tunnel/src/main/java/com/wireguard/android/backend/GoBackend.java46
-rw-r--r--tunnel/src/main/java/com/wireguard/android/backend/Statistics.java40
-rw-r--r--tunnel/src/main/java/com/wireguard/android/backend/Tunnel.java8
-rw-r--r--tunnel/src/main/java/com/wireguard/android/util/ModuleLoader.java32
6 files changed, 147 insertions, 1 deletions
diff --git a/tunnel/src/main/java/com/wireguard/android/backend/Backend.java b/tunnel/src/main/java/com/wireguard/android/backend/Backend.java
index 4c18d98b..e98b3576 100644
--- a/tunnel/src/main/java/com/wireguard/android/backend/Backend.java
+++ b/tunnel/src/main/java/com/wireguard/android/backend/Backend.java
@@ -46,7 +46,7 @@ public interface Backend {
* Determine version of underlying backend.
*
* @return The version of the backend.
- * @throws Exception
+ * @throws Exception Exception raised while retrieving version.
*/
String getVersion() throws Exception;
diff --git a/tunnel/src/main/java/com/wireguard/android/backend/BackendException.java b/tunnel/src/main/java/com/wireguard/android/backend/BackendException.java
index 5552b3ee..f153c2d6 100644
--- a/tunnel/src/main/java/com/wireguard/android/backend/BackendException.java
+++ b/tunnel/src/main/java/com/wireguard/android/backend/BackendException.java
@@ -7,24 +7,44 @@ package com.wireguard.android.backend;
import com.wireguard.util.NonNullForAll;
+/**
+ * A subclass of {@link Exception} that encapsulates the reasons for a failure originating in
+ * implementations of {@link Backend}.
+ */
@NonNullForAll
public final class BackendException extends Exception {
private final Object[] format;
private final Reason reason;
+ /**
+ * Public constructor for BackendException.
+ * @param reason The {@link Reason} which caused this exception to be thrown
+ * @param format Format string values used when converting exceptions to user-facing strings.
+ */
public BackendException(final Reason reason, final Object... format) {
this.reason = reason;
this.format = format;
}
+ /**
+ * Get the format string values associated with the instance.
+ * @return Array of {@link Object} for string formatting purposes
+ */
public Object[] getFormat() {
return format;
}
+ /**
+ * Get the reason for this exception.
+ * @return Associated {@link Reason} for this exception.
+ */
public Reason getReason() {
return reason;
}
+ /**
+ * Enum class containing all known reasons for why a {@link BackendException} might be thrown.
+ */
public enum Reason {
UNKNOWN_KERNEL_MODULE_NAME,
WG_QUICK_CONFIG_ERROR_CODE,
diff --git a/tunnel/src/main/java/com/wireguard/android/backend/GoBackend.java b/tunnel/src/main/java/com/wireguard/android/backend/GoBackend.java
index c859323b..83373b58 100644
--- a/tunnel/src/main/java/com/wireguard/android/backend/GoBackend.java
+++ b/tunnel/src/main/java/com/wireguard/android/backend/GoBackend.java
@@ -33,6 +33,10 @@ import java.util.concurrent.TimeoutException;
import androidx.annotation.Nullable;
import androidx.collection.ArraySet;
+/**
+ * Implementation of {@link Backend} that uses the wireguard-go userspace implementation to provide
+ * WireGuard tunnels.
+ */
@NonNullForAll
public final class GoBackend implements Backend {
private static final String TAG = "WireGuard/GoBackend";
@@ -43,11 +47,19 @@ public final class GoBackend implements Backend {
@Nullable private Tunnel currentTunnel;
private int currentTunnelHandle = -1;
+ /**
+ * Public constructor for GoBackend.
+ * @param context An Android {@link Context}
+ */
public GoBackend(final Context context) {
SharedLibraryLoader.loadSharedLibrary(context, "wg-go");
this.context = context;
}
+ /**
+ * Set a {@link AlwaysOnCallback} to be invoked when {@link VpnService} is started by the
+ * system's Always-On VPN mode.
+ */
public static void setAlwaysOnCallback(final AlwaysOnCallback cb) {
alwaysOnCallback = cb;
}
@@ -64,6 +76,10 @@ public final class GoBackend implements Backend {
private static native String wgVersion();
+ /**
+ * Method to get the names of running tunnels.
+ * @return A set of string values denoting names of running tunnels.
+ */
@Override
public Set<String> getRunningTunnelNames() {
if (currentTunnel != null) {
@@ -74,11 +90,21 @@ public final class GoBackend implements Backend {
return Collections.emptySet();
}
+ /**
+ * Get the associated {@link State} for a given {@link Tunnel}.
+ * @param tunnel The tunnel to examine the state of.
+ * @return {@link State} associated with the given tunnel.
+ */
@Override
public State getState(final Tunnel tunnel) {
return currentTunnel == tunnel ? State.UP : State.DOWN;
}
+ /**
+ * Get the associated {@link Statistics} for a given {@link Tunnel}.
+ * @param tunnel The tunnel to retrieve statistics for.
+ * @return {@link Statistics} associated with the given tunnel.
+ */
@Override
public Statistics getStatistics(final Tunnel tunnel) {
final Statistics stats = new Statistics();
@@ -123,11 +149,24 @@ public final class GoBackend implements Backend {
return stats;
}
+ /**
+ * Get the version of the underlying wireguard-go library.
+ * @return {@link String} value of the version of the wireguard-go library.
+ */
@Override
public String getVersion() {
return wgVersion();
}
+ /**
+ * Change the state of a given {@link Tunnel}, optionally applying a given {@link Config}.
+ * @param tunnel The tunnel to control the state of.
+ * @param state The new state for this tunnel. Must be {@code UP}, {@code DOWN}, or
+ * {@code TOGGLE}.
+ * @param config The configuration for this tunnel, may be null if state is {@code DOWN}.
+ * @return {@link State} of the tunnel after state changes are applied.
+ * @throws Exception Exception raised while changing tunnel state.
+ */
@Override
public State setState(final Tunnel tunnel, State state, @Nullable final Config config) throws Exception {
final State originalState = getState(tunnel);
@@ -249,6 +288,10 @@ public final class GoBackend implements Backend {
context.startService(new Intent(context, VpnService.class));
}
+ /**
+ * Callback for {@link GoBackend} that is invoked when {@link VpnService} is started by the
+ * system's Always-On VPN mode.
+ */
public interface AlwaysOnCallback {
void alwaysOnTriggered();
}
@@ -282,6 +325,9 @@ public final class GoBackend implements Backend {
}
}
+ /**
+ * {@link android.net.VpnService} implementation for {@link GoBackend}
+ */
public static class VpnService extends android.net.VpnService {
@Nullable private GoBackend owner;
diff --git a/tunnel/src/main/java/com/wireguard/android/backend/Statistics.java b/tunnel/src/main/java/com/wireguard/android/backend/Statistics.java
index b4e01e76..fa498a25 100644
--- a/tunnel/src/main/java/com/wireguard/android/backend/Statistics.java
+++ b/tunnel/src/main/java/com/wireguard/android/backend/Statistics.java
@@ -14,6 +14,9 @@ import com.wireguard.util.NonNullForAll;
import java.util.HashMap;
import java.util.Map;
+/**
+ * Class representing transfer statistics for a {@link Tunnel} instance.
+ */
@NonNullForAll
public class Statistics {
private final Map<Key, Pair<Long, Long>> peerBytes = new HashMap<>();
@@ -22,31 +25,64 @@ public class Statistics {
Statistics() {
}
+ /**
+ * Add a peer and its current data usage to the internal map.
+ * @param key A WireGuard public key bound to a particular peer
+ * @param rx The received traffic for the {@link com.wireguard.config.Peer} referenced by
+ * the provided {@link Key}. This value is in bytes
+ * @param tx The transmitted traffic for the {@link com.wireguard.config.Peer} referenced by
+ * the provided {@link Key}. This value is in bytes.
+ */
void add(final Key key, final long rx, final long tx) {
peerBytes.put(key, Pair.create(rx, tx));
lastTouched = SystemClock.elapsedRealtime();
}
+ /**
+ * Check if the statistics are stale, indicating the need for the {@link Backend} to update them.
+ * @return boolean indicating if the current statistics instance has stale values.
+ */
public boolean isStale() {
return SystemClock.elapsedRealtime() - lastTouched > 900;
}
+ /**
+ * Get the received traffic (in bytes) for the {@link com.wireguard.config.Peer} referenced by
+ * the provided {@link Key}
+ * @param peer A {@link Key} representing a {@link com.wireguard.config.Peer}.
+ * @return a long representing the number of bytes received by this peer.
+ */
public long peerRx(final Key peer) {
if (!peerBytes.containsKey(peer))
return 0;
return peerBytes.get(peer).first;
}
+ /**
+ * Get the transmitted traffic (in bytes) for the {@link com.wireguard.config.Peer} referenced by
+ * the provided {@link Key}
+ * @param peer A {@link Key} representing a {@link com.wireguard.config.Peer}.
+ * @return a long representing the number of bytes transmitted by this peer.
+ */
public long peerTx(final Key peer) {
if (!peerBytes.containsKey(peer))
return 0;
return peerBytes.get(peer).second;
}
+ /**
+ * Get the list of peers being tracked by this instance.
+ * @return An array of {@link Key} instances representing WireGuard
+ * {@link com.wireguard.config.Peer}s
+ */
public Key[] peers() {
return peerBytes.keySet().toArray(new Key[0]);
}
+ /**
+ * Get the total received traffic by all the peers being tracked by this instance
+ * @return a long representing the number of bytes received by the peers being tracked.
+ */
public long totalRx() {
long rx = 0;
for (final Pair<Long, Long> val : peerBytes.values()) {
@@ -55,6 +91,10 @@ public class Statistics {
return rx;
}
+ /**
+ * Get the total transmitted traffic by all the peers being tracked by this instance
+ * @return a long representing the number of bytes transmitted by the peers being tracked.
+ */
public long totalTx() {
long tx = 0;
for (final Pair<Long, Long> val : peerBytes.values()) {
diff --git a/tunnel/src/main/java/com/wireguard/android/backend/Tunnel.java b/tunnel/src/main/java/com/wireguard/android/backend/Tunnel.java
index a9761929..4740c80d 100644
--- a/tunnel/src/main/java/com/wireguard/android/backend/Tunnel.java
+++ b/tunnel/src/main/java/com/wireguard/android/backend/Tunnel.java
@@ -36,11 +36,19 @@ public interface Tunnel {
*/
void onStateChange(State newState);
+ /**
+ * Enum class to represent all possible states of a {@link Tunnel}.
+ */
enum State {
DOWN,
TOGGLE,
UP;
+ /**
+ * Get the state of a {@link Tunnel}
+ * @param running boolean indicating if the tunnel is running.
+ * @return State of the tunnel based on whether or not it is running.
+ */
public static State of(final boolean running) {
return running ? UP : DOWN;
}
diff --git a/tunnel/src/main/java/com/wireguard/android/util/ModuleLoader.java b/tunnel/src/main/java/com/wireguard/android/util/ModuleLoader.java
index 8f7749e1..b360572a 100644
--- a/tunnel/src/main/java/com/wireguard/android/util/ModuleLoader.java
+++ b/tunnel/src/main/java/com/wireguard/android/util/ModuleLoader.java
@@ -37,6 +37,10 @@ import java.util.Map;
import androidx.annotation.Nullable;
+/**
+ * Class that implements the logic for downloading and loading signed, prebuilt modules for
+ * WireGuard into the running kernel.
+ */
@NonNullForAll
@SuppressWarnings("MagicNumber")
public class ModuleLoader {
@@ -49,6 +53,14 @@ public class ModuleLoader {
private final File tmpDir;
private final String userAgent;
+ /**
+ * Public constructor for ModuleLoader
+ * @param context A {@link Context} instance.
+ * @param rootShell A {@link RootShell} instance used to run elevated commands required for module
+ * loading.
+ * @param userAgent A {@link String} that represents the User-Agent string used for connections
+ * to the upstream server.
+ */
public ModuleLoader(final Context context, final RootShell rootShell, final String userAgent) {
moduleDir = new File(context.getCacheDir(), "kmod");
tmpDir = new File(context.getCacheDir(), "tmp");
@@ -56,10 +68,21 @@ public class ModuleLoader {
this.userAgent = userAgent;
}
+ /**
+ * Check whether a WireGuard module is already loaded into the kernel.
+ * @return boolean indicating if WireGuard is already enabled in the kernel.
+ */
public static boolean isModuleLoaded() {
return new File("/sys/module/wireguard").exists();
}
+ /**
+ * Download the correct WireGuard module for the device
+ * @return {@link OsConstants}.EXIT_SUCCESS if everything succeeds, ENOENT otherwise.
+ * @throws IOException if the remote hash list was not found or empty.
+ * @throws RootShellException if {@link RootShell} has a failure executing elevated commands.
+ * @throws NoSuchAlgorithmException if SHA256 algorithm is not available in device JDK.
+ */
public Integer download() throws IOException, RootShellException, NoSuchAlgorithmException {
final List<String> output = new ArrayList<>();
rootShell.run(output, "sha256sum /proc/version|cut -d ' ' -f 1");
@@ -119,10 +142,19 @@ public class ModuleLoader {
return OsConstants.EXIT_SUCCESS;
}
+ /**
+ * Load the downloaded module. ModuleLoader#download must be called before this.
+ * @throws IOException if {@link RootShell} has a failure executing elevated commands.
+ * @throws RootShellException if {@link RootShell} has a failure executing elevated commands.
+ */
public void loadModule() throws IOException, RootShellException {
rootShell.run(null, String.format("insmod \"%s/wireguard-$(sha256sum /proc/version|cut -d ' ' -f 1).ko\"", moduleDir.getAbsolutePath()));
}
+ /**
+ * Check if the module might already exist in the app's data.
+ * @return boolean indicating whether downloadable module might exist already.
+ */
public boolean moduleMightExist() {
return moduleDir.exists() && moduleDir.isDirectory();
}