Hesham/wireguard-android
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

tunnel: document more public API from backend package

Browse Source 
Signed-off-by: Harsh Shandilya <me@msfjarvis.dev>
This commit is contained in:
Harsh Shandilya 2020-09-16 16:12:59 +05:30 committed by Jason A. Donenfeld
parent 2f088938c6
commit ff7d7e0edd
6 changed files with 174 additions and 1 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

5
tunnel/src/main/java/com/wireguard/android/backend/Backend.java
View File

@ -30,6 +30,7 @@ public interface Backend {
*
* @param tunnel The tunnel to examine the state of.
* @return The state of the tunnel.
* @throws Exception Exception raised when retrieving tunnel's state.
*/
Tunnel.State getState(Tunnel tunnel) throws Exception;
@ -39,6 +40,7 @@ public interface Backend {
*
* @param tunnel The tunnel to retrieve statistics for.
* @return The statistics for the tunnel.
* @throws Exception Exception raised when retrieving statistics.
*/
Statistics getStatistics(Tunnel tunnel) throws Exception;
@ -46,7 +48,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;
@ -59,6 +61,7 @@ public interface Backend {
* {@code TOGGLE}.
* @param config The configuration for this tunnel, may be null if state is {@code DOWN}.
* @return The updated state of the tunnel.
* @throws Exception Exception raised while changing state.
*/
Tunnel.State setState(Tunnel tunnel, Tunnel.State state, @Nullable Config config) throws Exception;
}

23
tunnel/src/main/java/com/wireguard/android/backend/BackendException.java
View File

@ -7,24 +7,47 @@ 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,

54
tunnel/src/main/java/com/wireguard/android/backend/GoBackend.java
View File

@ -34,6 +34,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";
@ -44,11 +48,22 @@ 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.
*
* @param cb Callback to be invoked
*/
public static void setAlwaysOnCallback(final AlwaysOnCallback cb) {
alwaysOnCallback = cb;
}
@ -65,6 +80,11 @@ 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) {
@ -75,11 +95,23 @@ 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();
@ -124,11 +156,26 @@ 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);
@ -260,6 +307,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();
}
@ -293,6 +344,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;

47
tunnel/src/main/java/com/wireguard/android/backend/Statistics.java
View File

@ -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,70 @@ 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 +97,11 @@ 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()) {

9
tunnel/src/main/java/com/wireguard/android/backend/Tunnel.java
View File

@ -36,11 +36,20 @@ 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;
}

37
tunnel/src/main/java/com/wireguard/android/util/ModuleLoader.java
View File

@ -31,6 +31,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 {
@ -43,6 +47,15 @@ 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");
@ -50,10 +63,23 @@ 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");
@ -113,10 +139,21 @@ 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();
}