0.0.1 • Published 6 years ago

outline-plugin v0.0.1

Weekly downloads
1
License
Apache 2.0
Repository
-
Last release
6 years ago

cordova-plugin-outline

This Cordova plugin provides the ability to start a system-wide VPN, connected to a local Shadowsocks client.

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 local Shadowsocks server.

shadowsocks-libev

Android update instructions

The client code is https://github.com/shadowsocks/shadowsocks-libev, is compiled to a native shared library using the same process as https://github.com/shadowsocks/shadowsocks-android.

libss-local.so is built with the help of https://github.com/shadowsocks/shadowsocks-android.

It should be refreshed periodically; a script is included to do so, e.g.:

./update-shadowsocks-libev.sh 2.6.3

Upon successful completion, the script stages a commit including the new binary.

Apple update instructions

We use a custom framework dependency, Shadowsocks, that implements shadowsocks-libev. To update it see ../third_party/shadowsocks-libev/apple/README.md.

tun2socks

Android update instructions

ndk-build -C ../third_party/badvpn APP_BUILD_SCRIPT=Android.mk NDK_PROJECT_PATH=`pwd` NDK_APPLICATION_MK=`pwd`/../third_party/badvpn/Application.mk
cp libs/armeabi-v7a/libtun2socks.so android/libs/armeabi-v7a/libtun2socks.so
cp libs/x86/libtun2socks.so android/libs/x86/libtun2socks.so

For debug builds, which enable asserts and improved backtraces, append NDK_DEBUG=1.

Apple update instructions

We use a custom framework dependency, PacketProcesor, that implements tun2socks. To update it see ../third_party/Potatso/README.md

Target Platforms

This plugin supports Android, iOS, and macOS.

Android

This plugin targets Android devices running Lollipop (API 21), or higher.

Apple

This plugin targets Apple devices running iOS 9.0+ and macOS/OS X 10.11.

Javascript API

// Represents a Shadowsocks server configuration.
interface ShadowsocksServerConfig {
  method?: string;
  password?: string;
  host?: string;
  port?: number;
  name?: string;
}

declare namespace cordova.plugins.outline {

  export var Log: {

    // Initializes the error reporting framework with the supplied credentials.
    initialize(apiKey: string): Promise<void>;

    // Sends previously captured logs and events to the error reporting framework.
    // Associates the report to the provided unique identifier.
    send(uuid: string): Promise<void>;
  }

  // Represents a VPN connection to a proxy through the plugin.
  export class Connection {

    // Creates a new instance with |serverConfig|.
    // A sequential ID will be generated if |id| is absent.
    constructor(serverConfig: ShadowsocksServerConfig, id?: string);

    // Starts the VPN service, and tunnels all the traffic to a local Shadowsocks
    // server as dictated by its configuration. If there is another running
    // instance, broadcasts a disconnect event and stops the running connection.
    // In such case, restarts tunneling while preserving the VPN connection.
    start(): Promise<void>;


    // Stops the connection and VPN service.
    stop(): Promise<void>;

    // Returns whether the connection instance is active.
    isRunning(): Promise<boolean>;

    // Returns whether the connection is reachable by attempting to establish
    // a socket to the IP and port specified in |config|.
    isReachable(): Promise<boolean>;

    // Sets a listener, to be called when the VPN connection status changes.
    onStatusChange(listener: (status: ConnectionStatus) => void): void;
  }
}

Android Code Sources

We have used as a starting point open source code from Psiphon, specifically their fork of badvpn.

Additional Apple Dependencies

We use the Carthage dependency manager to fetch Sentry Cocoa, CocoaLumberjack, and CocoaAsyncSocket.

To upgrade the Carthage dependencies:

  • Install Carthage by running brew install carthage.
  • Update the framework's version in Cartfile (e.g. github "getsentry/sentry-cocoa" "x.y.z").
  • Run carthage update. This will fetch the frameworks for macOS and iOS.
  • Copy the frameworks to the cordova-plugin-outline/apple/lib (e.g. cp -R Carthage/Build/iOS/Sentry.framework cordova-plugin-outline/apple/lib/Sentry/ios/)
  • Add Cartfile and Cartfile.resolved to git and commit the changes.