shadowsocks-android Documentation

File: README.md Copy Chapter

[Shadowsocks](https://shadowsocks.org) for Android Copy Chapter

for Android & Chrome OS (beta)

for Android TV (beta)

PREREQUISITES Copy Section

• JDK 11+
• Android SDK
  • Android NDK
• Rust with Android targets installed using rustup target add armv7-linux-androideabi aarch64-linux-android i686-linux-android x86_64-linux-android

BUILD Copy Section

You can check whether the latest commit builds under UNIX environment by checking Travis status.

• Install prerequisites
• Clone the repo using git clone --recurse-submodules <repo> or update submodules using git submodule update --init --recursive
• Build it using Android Studio or gradle script

CONTRIBUTING Copy Section

If you are interested in contributing or getting involved with this project, please read the CONTRIBUTING page for more information. The page can be found here.

[TRANSLATE](https://discourse.shadowsocks.org/t/poeditor-translation-main-thread/30) Copy Section

OPEN SOURCE LICENSES Copy Chapter

<li>redsocks: [APL 2.0](https://github.com/shadowsocks/redsocks/blob/shadowsocks-android/README)</li>
<li>libevent: [BSD](https://github.com/shadowsocks/libevent/blob/master/LICENSE)</li>
<li>tun2socks: [BSD](https://github.com/shadowsocks/badvpn/blob/shadowsocks-android/COPYING)</li>
<li>shadowsocks-rust: [MIT](https://github.com/shadowsocks/shadowsocks-rust/blob/master/LICENSE)</li>
<li>libsodium: [ISC](https://github.com/jedisct1/libsodium/blob/master/LICENSE)</li>
<li>OpenSSL: [OpenSSL License](https://www.openssl.org/source/license-openssl-ssleay.txt)</li>

LICENSE Copy Section

Copyright (C) 2017 by Max Lv <[email protected]>
Copyright (C) 2017 by Mygod Studio <[email protected]>

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program. If not, see http://www.gnu.org/licenses/.

File: plugin/README.md Copy Chapter

shadowsocks-android plugin framework

Documentation | Change log

Support library for easier development on shadowsocks
plugin for Android. Also includes some
useful resources to easily get consistent styling with the main app.

Official plugins Copy Chapter

These are some plugins ready to use on shadowsocks-android.

• v2ray
• kcptun
• simple-obfs

Developer's guide Copy Chapter

This library is designed with Java interoperability in mind so theoretically you can use this
library with other languages and/or build tools but there isn't documentation for that yet. This
guide is written for Scala + SBT. Contributions are welcome.

Package name Copy Section

There are no arbitrary restrictions/requirements on package name, component name and content
provider authority, but you're suggested to follow the format in this documentations. For package
name, use com.github.shadowsocks.plugin.$PLUGIN_ID if it only contains a single plugin to
prevent duplicated plugins. In some places hyphens are not accepted, for example package name. In
that case, hyphens - should be changed into underscores _. For example, the package name for
obfs-local would probably be com.github.shadowsocks.plugin.obfs_local.

Add dependency Copy Section

First you need to add this library to your dependencies.
This library is written mostly in Kotlin but can also work with Java-only projects:

implementation 'com.github.shadowsocks:plugin:$LATEST_VERSION'

Native binary configuration Copy Section

First you need to get your native binary compiling on Android platform.

• Sample project for C;
• Sample project for Go.

In addition to functionalities of a normal plugin, it has to support these additional options:

• __android_vpn: VPN mode.
  In this case, the plugin should pass all file descriptors that needs protecting from VPN connections (i.e. its traffic will not be forwarded through the VPN) through an ancillary message to ./protect_path.

Implement a binary provider Copy Section

You just need to implement two or three methods. For example for v2ray:

class BinaryProvider : NativePluginProvider() {
    override fun populateFiles(provider: PathProvider) {
        provider.addPath("v2ray", 0b111101101)
        // add additional files here
    }

  // remove this method to disable fast mode, read more in the documentation
    override fun getExecutable() = context!!.applicationInfo.nativeLibraryDir + "/libv2ray.so"

    override fun openFile(uri: Uri): ParcelFileDescriptor = when (uri.path) {
        "/v2ray" -> ParcelFileDescriptor.open(File(getExecutable()), ParcelFileDescriptor.MODE_READ_ONLY)
        // handle additional files here
        else -> throw FileNotFoundException()
    }
}

Then add it to your manifest:

<manifest>
    ...
    <application>
        ...
        
            
                <action android:name="com.github.shadowsocks.plugin.ACTION_NATIVE_PLUGIN"/>
            
            
                <action android:name="com.github.shadowsocks.plugin.ACTION_NATIVE_PLUGIN"/>
                <data android:scheme="plugin"
                      android:host="com.github.shadowsocks"
                      android:path="/$PLUGIN_ID"/>
            
            <meta-data android:name="com.github.shadowsocks.plugin.id"
                       android:value="$PLUGIN_ID"/>
            
            <meta-data android:name="com.github.shadowsocks.plugin.default_config"
                       android:value="dummy=default;plugin=options"/>
            
            <meta-data android:name="com.github.shadowsocks.plugin.executable_path"
                       android:value="$PATH_TO_EXECUTABLE_RELATIVE_TO_NATIVE_LIB_DIR"/>
        
        ...
    </application>
</manifest>

Add user interfaces Copy Section

You should add to your plugin app a configuration activity or a help activity or both if you're
going to use ConfigurationActivity.fallbackToManualEditor.

Configuration activity

This is used if found instead of a manual input dialog when user clicks "Configure..." in the main
app. This gives you maximum freedom of the user interface. To implement this, you need to extend
ConfigurationActivity and you will get current options via
onInitializePluginOptions(PluginOptions) and you can invoke saveChanges(PluginOptions) or
discardChanges() before finish() or fallbackToManualEditor(). Then add it to your manifest:

<manifest>
    ...
    <application>
        ...
        <activity android:name=".ConfigActivity">
            
                <action android:name="com.github.shadowsocks.plugin.ACTION_CONFIGURE"/>
                <category android:name="android.intent.category.DEFAULT"/>
                <data android:scheme="plugin"
                      android:host="com.github.shadowsocks"
                      android:path="/$PLUGIN_ID"/>
            
        </activity>
        ...
    </application>
</manifest>

Help activity/callback

This is started when user taps "?" in manual editor. To implement this, you need to extend
HelpCallback if you want a simple dialog with help message as CharSequence or HelpActivity
if you want to provide custom user interface, implement the required methods, then add it to your
manifest:

<manifest>
    ...
    <application>
        ...
        <activity android:name=".HelpActivity">
            
                <action android:name="com.github.shadowsocks.plugin.ACTION_HELP"/>
                <category android:name="android.intent.category.DEFAULT"/>
                <data android:scheme="plugin"
                      android:host="com.github.shadowsocks"
                      android:path="/$PLUGIN_ID"/>
            
        </activity>
        ...
    </application>
</manifest>

Great. Now your plugin is ready to use.