cordova-plugin-tun2socks-udp-associate

cordova-plugin-tun2socks-udp-associate

(This is a fork of Xmader/cordova-plugin-tun2socks#xmader-udp. Original repo: UWNetworksLab/cordova-plugin-tun2socks)

This Cordova plugin provides the ability to start a system-wide VPN for Android devices.

We use tun2socks as an adapter; it receives all of the device’s traffic through the VPN network interface (TUN) and forwards it to a SOCKS server.

To handle DNS resolution, we use the UDP associate feature of SOCKS v5 proxy to intercept DNS queries over UDP.

Tested to work with socks5.js running on localhost.

Table of Contents

• Installation
• Re-building the .so
• Target Devices
• Javascript API
• Code Sources

Installation

Run the following commands on the root of your Cordova project folder:

$ npm i cordova-plugin-tun2socks-udp-associate -S

$ cordova plugin add cordova-plugin-tun2socks-udp-associate

$ cordova prepare android

Re-building the .so

$ ndk-build -C android

Pre-built binaries for "armeabi-v7a", "arm64-v8a", "x86" and "x86_64" are included.

Target Devices

This plugin targets Android devices running Lollipop (API 21), or higher. This requirement stems from calling addDisallowedApplication, a VPNService.Builder API introduced in version 21, which allows the specified application's traffic to bypass the VPN.

Javascript API

start(socksServerAddress:string) : Promise<string>;

Starts the VPN service, and tunnels all the traffic to the SOCKS5 server at socksServerAddress. Restarts tunneling while preserving the VPN connection if called when the plugin is already running.

stop(): Promise<string>;

Stops the VPN service.

onDisconnect(): Promise<string>;

Sets a success callback on the returned promise, to be called if the VPN service gets revoked or disconnected.

deviceSupportsPlugin(): Promise<Boolean>;

Retruns true if the device runs the minimum required version for the plugin to function properly.

Code Sources

We re-use and have used as a starting point open source code from Psiphon, specifically https://github.com/mei3am/ps.

• src/android:
• starting point: https://github.com/mei3am/ps/tree/master/Android/app
• Android/app/src/main/java/ca/psiphon/PsiphonTunnel.java -> src/android/org/uproxy/tun2socks/Tunnel.java
• Android/app/src/main/java/com/psiphon3/psiphonlibrary/TunnelManager.java -> src/android/org/uproxy/tun2socks/TunnelManager.java
• Android/app/src/main/java/com/psiphon3/psiphonlibrary/TunnelVpnService.java -> src/android/org/uproxy/tun2socks/TunnelVpnService.java
• src/badvpn:
• built upon Psiphon's fork of badvpn.
• starting point: https://github.com/mei3am/ps/tree/master/Android/badvpn
• uProxy-specific changes mostly confined to tun2socks/tun2socks.c and marked with // ==== UPROXY ==== (like Psiphon-specific changes)
• src/android/libs/jsocks.jar:
• http://jsocks.sourceforge.net/