Standalone Outline cordova plugin forked from: https://github.com/Jigsaw-Code/outline-client

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.

• ../third_party/badvpn:
  • built upon Psiphon's fork of badvpn.
  • starting point: https://github.com/mei3am/ps/tree/master/Android/badvpn
  • Outline-specific changes mostly confined to tun2socks/tun2socks.c and marked with // ==== OUTLINE ==== (like Psiphon-specific changes)

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.