Add documentation

.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'

.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

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.

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=<proto>://[addr][:port]
+
+        Listens at addr:port with protocol <proto>. 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=<proto>://[<user>:<pass>@]<hostname>[:<port>]
+
+        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=[<path>]
+
+        Saves log to the file at <path>. If <path> is empty, prints to
+        console.
+
+        If this option is not set, no log is saved for privacy.
+
+    --log-net-log=<path>
+
+        Saves NetLog. View at https://netlog-viewer.appspot.com/.
+
+    --ssl-key-log-file=<path>
+
+        Saves SSL keys for Wireshark inspection.