Shadowsocks-NaCl is a Native Client port of shadowsocks, provides high performance crypto and network relay on web browser which support Native Client.
Note: This port of shadowsocks is for Web App developers ONLY, NOT for the end user. For end user, use shadowsocks-chromeapp instead.
Build
- Download and install Native Client SDK.
- Set environment variable
NACL_SDK_ROOT
to SDK path (e.g.,~/nacl_sdk/pepper_47
). - Checkout webports, a.k.a. naclports.
- Follow the instructions in
webports/README.md
to install webports. - Build and install OpenSSL to Native Client SDK. (e.g.,
$ NACL_ARCH=pnacl make openssl
) - For webports branch below
pepper_47
: Update libsodium in webports from0.4.5
to1.0.3
since ChaCha20 was added in0.6.0
. You may change the content ofwebports/src/ports/libsodium/pkg_info
toNAME=libsodium VERSION=1.0.3 URL=https://github.com/jedisct1/libsodium/releases/download/1.0.3/libsodium-1.0.3.tar.gz LICENSE=ISC SHA1=e44ed485842966d4e2d8f58e74a5fd78fbfbe4b0
- Build and install libsodium to Native Client SDK. (e.g.,
$ NACL_ARCH=pnacl make libsodium
) - Clone this repository and use
$ make
to build.
Usage
You can use Shadowsocks-NaCl JavaScript API to communicate with native client module. You just need include
src/shadowsocks.js
into your webapp page, initialize it, and use it.Initialize
You can initialize Shadowsocks-NaCl JavaScript API like this:
var shadowsocks = new Shadowsocks('path/to/nmf');
It will return a
Shadowsocks
object, then you can invoke API commands or add event listeners.Events
Raw Native Client Progress Events
This type of events includes
loadstart
, progress
, error
, abort
, load
, loadend
and crash
, they indicates the native client module load status, see native client document for more information.Raw Native Client Message Event
message
is the raw native client message event, all shadowsocks command call rely on this event, typically you don't need to listen on this event. If you really want, see native client document for more information.Shadowsocks status event
status
is the shadowsocks status event. All runtime information, like server listen state, link error message, will be passed to the callback of status
event, in an object form like: { type: 'status', level: 'foo', message: 'bar' }
.level
in object could be one of the success
, info
, warning
or danger
, and the message
could be a string or an object.Profile
Profile is a JavaScript object, it can be passed to API
connect
directly.{
server: "example.com", // Domain/IP Address in string form
server_port: 8388, // Value must be a number
local_port: 1080, // Value must be a number
method: "aes-256-cfb", // Value must be a string and in supported cipher list
password: "password", // Value must be a string
timeout: 300, // Value in seconds and must be a number
one_time_auth: false // Value must be a boolean, optional, default to false
}
API
shadowsocks.addEventListener(event, callback, context)
Add an event listener, context is an optionalthis
for callback.shadowsocks.on(event, callback, context)
Alias ofshadowsocks.addEventListener(event, callback, context)
shadowsocks.removeEventListener(event, callback, context)
Remove an event listener,event
,callback
,context
must be the same one of which passed toaddEventListener
.shadowsocks.off(event, callback, context)
Alias ofshadowsocks.removeEventListener(event, callback, context)
shadowsocks.load()
Load shadowsocks native client module. After invoke, it will trigger progress events.shadowsocks.unload()
Unload shadowsocks native client module. It will also clear all registered event listeners.shadowsocks.getElement()
Return the native client<embed>
element.shadowsocks.connect(profile, callback, context)
Connect to a server,callback
will be called with argument 0.shadowsocks.disconnect(callback, context)
Disconnect from a server,callback
will be called with argument 0.shadowsocks.sweep(callback, context)
Sweep timeout connection from connection pool, the native client module cannot do sweep automatically, so you must sweep it by yourself.Typically, you should invoke this function repeatedly in fixed time (could same astimeout
in profile).Thecallback
function will be called with argument 0.shadowsocks.version(callback, context)
callback
function will be called with the native client module version in string form.Ifcallback
is not specified, it will log version string into console.shadowsocks.listCipher(callback, context)
callback
function will be called with the array of supported cipher name in string form.
Test flight
A Chromium App is provided to help testing and debugging.
You can open
chrome://extensions/
, check Developer Mode
, click Load Unpacked Extension
, select the root directory of this project.
You will find a new App named
Shadowsocks NaCl Test flight
in chrome://extensions/
, click Inspect views: background page
will open a developer tools window and you can try above-mentioned command here.
from https://github.com/nekolab/shadowsocks-nacl