diff --git a/.appveyor.yml b/.appveyor.yml index 9d8a443610..6737217647 100644 --- a/.appveyor.yml +++ b/.appveyor.yml @@ -16,7 +16,7 @@ build_script: - bash -c '~/.cargo/bin/sccache -s' - ps: $env:BUILD_NAME="naiveproxy-$env:APPVEYOR_REPO_TAG_NAME-win64" - bash -c 'mkdir $BUILD_NAME' - - bash -c 'cp src/out/Release/naive.exe src/config.json LICENSE $BUILD_NAME' + - bash -c 'cp src/out/Release/naive.exe src/config.json LICENSE USAGE.txt $BUILD_NAME' - bash -c '7z a $BUILD_NAME.zip $BUILD_NAME' test_script: - bash -c './tests/basic.sh src/out/Release/naive' diff --git a/.travis.yml b/.travis.yml index cfad35ab1b..3cf9cade7a 100644 --- a/.travis.yml +++ b/.travis.yml @@ -28,7 +28,7 @@ script: - ./tests/basic.sh src/out/Release/naive - export BUILD_NAME="naiveproxy-$TRAVIS_BRANCH-$TRAVIS_OS_NAME" - mkdir $BUILD_NAME - - cp src/out/Release/naive src/config.json LICENSE $BUILD_NAME + - cp src/out/Release/naive src/config.json LICENSE USAGE.txt $BUILD_NAME - tar cJf $BUILD_NAME.tar.xz $BUILD_NAME deploy: provider: releases diff --git a/README.md b/README.md index 25f8a3d5d8..45c29dade2 100644 --- a/README.md +++ b/README.md @@ -1,20 +1,69 @@ -# NaiveProxy +# NaiveProxy [![Build Status](https://travis-ci.com/klzgrad/naiveproxy.svg?branch=master)](https://travis-ci.com/klzgrad/naiveproxy) [![Build status](https://ci.appveyor.com/api/projects/status/ohpyaf49baihmxa9?svg=true)](https://ci.appveyor.com/project/klzgrad/naiveproxy) A secure, analysis-resistent proxy framework. -The primary security goal is availability in presence of pervasive censorship. Nevertheless, privacy and integrity are simultaneously achieved through implementations of TLS best practices. +The main goal is to improve censorship resistence by reducing distinguishable traffic features. Privacy and integrity are simultaneously achieved through implementations of TLS best practices. -The main attacks considered: +The following attacks are mitigated: * Website fingerprinting / traffic classification: [mitigated](https://arxiv.org/abs/1707.00641) by traffic multiplexing in HTTP/2. * [TLS parameter fingerprinting](https://arxiv.org/abs/1607.01639): defeated by using identical behaviors from [Chromium's network stack](https://www.chromium.org/developers/design-documents/network-stack). * [Active probing](https://ensa.fi/active-probing/): defeated by application fronting, using a common frontend with application-layer routing capability, e.g. HAProxy. * Length-based traffic analysis: mitigated by length padding. -There are three setups: +## Download -* The portable setup doesn't ask you to build any code or run anything client-side, but it is prone to traffic analysis due to lack of length padding. See [Linux Quick HOWTO](https://github.com/klzgrad/naiveproxy/wiki/Linux-Quick-HOWTO). -* The fast setup improves performance by having a client. See "Fast client" in [Linux HOWTO](https://github.com/klzgrad/naiveproxy/wiki/Linux-HOWTO). -* The resistent setup implements length padding upon the fast setup by requiring an extra server. See "Obfuscated tunnel" in [Linux HOWTO](https://github.com/klzgrad/naiveproxy/wiki/Linux-HOWTO). +See [latest release](https://github.com/klzgrad/naiveproxy/releases/latest). -The application is entirely based on Chromium's code base and build system. The master branch contains a minimal set of files that are changed from Chromium stable, for ease of code review. The version branches contain a minimized but still large buildable codebase with the same changes. +Note: On Linux libnss3 must be installed before using the prebuilt binary. + +## Build + +If you don't like to use downloaded binaries, you can build it. + +* Prerequisites: + * Ubuntu (apt-get install): git, python2, ninja-build (>= 1.7), pkg-config, libnss3-dev, ccache (optional) + * MacOS (brew install): git, ninja, ccache (optional) + * Windows ([choco install](https://chocolatey.org/)): git, python2, ninja, visualstudio2017community. See [Chromium's page](https://chromium.googlesource.com/chromium/src/+/master/docs/windows_build_instructions.md#Visual-Studio) for detail on Visual Studio setup requirements. + + +Build it: +``` +git clone https://github.com/klzgrad/naiveproxy.git +cd naiveproxy/src +./get-clang.sh +./build.sh +``` +The build scripts download tools from Google servers with curl. If there is trouble try to set a proxy environment variable for curl, e.g.: `export ALL_PROXY=socks5h://127.0.0.1:1080`. + +Verify: +``` +./out/Release/naive --log & +curl -v --proxy socks5h://127.0.0.1:1080 google.com +``` + +## Setup + +Server setup is required first, see [Server Setup](https://github.com/klzgrad/naiveproxy/wiki/Server-Setup). + +There are three tiers of client setup: + +* The portable setup is clientless: point your browser directly to the server as an HTTPS proxy. You don't need to download, build, or run anything client-side, but this setup is prone to traffic analysis due to lack of obfuscation. +* The fast setup improves performance by running Naive client locally as a SOCKS5 proxy. Point your browser to the address of Naive client. You don't need to run Naive server in this setup. +* The full setup obfuscates traffic by running both Naive client and server. Point your browser to the local SOCKS5 proxy provided by Naive client. + +To run Naive client: +``` +./naive --proxy=https://user:pass@domainname.example +``` +You can also store the config in `config.json`, example: +``` +{ + "proxy": "https://user:pass@domainname.example" +} +``` +Naive client will detect and read from `config.json` by default. The default listening port is 1080 as SOCKS5. + +For more information on parameter usage and Naive server, see USAGE.txt. + +See also [Parameter Tuning](https://github.com/klzgrad/naiveproxy/wiki/Parameter-Tuning) to improve client-side performance. diff --git a/USAGE.txt b/USAGE.txt new file mode 100644 index 0000000000..a93eda6b0f --- /dev/null +++ b/USAGE.txt @@ -0,0 +1,72 @@ +Usage: naive { OPTIONS | [/path/to/config.json] } + +Description: + + naive is a proxy to transport traffic as Chromium traffic. It can be + used as both the client and the server or together. + + There are two ways to specify options. The first is through command + line flags: naive OPTIONS. The second is through a JSON + configuration file. If there are no command line flags or path + specified, it will try to read from "config.json" by default. + + The syntax of config.json fields are mapped exactly to command line + flags, e.g. + + { + "proxy": "https://user:pass@example.org" + } + + is exactly the same as --proxy=https://user:pass@example.org. All + command line flags must have string values in config.json, except if + the flags are boolean then they must have boolean values too. + +Options: + + -h, --help + + Shows help message. + + --version + + Prints version + + --listen=://[addr][:port] + + Listens at addr:port with protocol . Allowed values for + proto: "socks", "http". The default proto is socks. The default + addr is 0.0.0.0. The default port is 1080. + + --proxy=://[:@][:] + + Routes traffic via the proxy server. Allowed values for proto: + "https", "quic". The value of port is inferred from proto if not + specified. If hostname is an IP address, an internal host + resolver rule is setup to resolve "example" to it to make TLS + certificate validation work. + + If this option is not set, connects to origin server directly. + + --padding + + Obfuscates traffic by adding length paddings. + + --host-resolver-rules=... + + This is the same as Chromium's flag of the same name. Google it + as the full description is too technical. + + --log=[] + + Saves log to the file at . If is empty, prints to + console. + + If this option is not set, no log is saved for privacy. + + --log-net-log= + + Saves NetLog. View at https://netlog-viewer.appspot.com/. + + --ssl-key-log-file= + + Saves SSL keys for Wireshark inspection.