mirror of
https://github.com/cbeuw/Cloak.git
synced 2024-11-05 21:20:45 +00:00
100 lines
7.8 KiB
Markdown
100 lines
7.8 KiB
Markdown
# Cloak
|
|
|
|
|
|
|
|
Cloak is a universal pluggable transport that obfuscates proxy traffic as legitimate HTTPS traffic, disguises the proxy server as a normal web server, multiplexes traffic through multiple TCP connections and provide multi-user usage control.
|
|
|
|
Cloak eliminates any "fingerprints" exposed by traditional proxy protocol designs which can be identified by adversaries through deep packet inspection. If a non-Cloak program or an unauthorised Cloak user (such as an adversary's prober) attempts to connect to Cloak server, it will serve as a transparent proxy between said machine and an ordinary website, so that to any unauthorised third party, a host running Cloak server is indistinguishable from an innocent web server.
|
|
|
|
Since Cloak is transparent, it can be used in conjunction with any proxy software that tunnels traffic through TCP, such as Shadowsocks, OpenVPN and Tor. Multiple proxy servers can be running on the same server host machine and Cloak will act as a dispatcher, bridging clients with their desired proxy end.
|
|
|
|
Cloak multiplexes traffic through multiple underlying TCP connections which reduces head-of-line blocking and eliminates TCP handshake overhead.
|
|
|
|
Cloak provides multi-user support, allowing multiple clients to connect to the proxy server on the same port (443 by default). It also provides QoS controls for individual users such as data usage limit and bandwidth control.
|
|
|
|
**Cloak 2.x is not compatible with legacy Cloak 1.x's protocol, configuration file or database file. Cloak 1.x protocol has critical cryptographic flaws regarding encrypting stream headers. Using Cloak 1.x is strongly discouraged**
|
|
|
|
This project is based on [GoQuiet](https://github.com/cbeuw/GoQuiet). Through multiplexing, Cloak provides a siginifcant reduction in webpage loading time compared to GoQuiet (from 10% to 50%+, depending on the amount of content on the webpage, see [benchmarks](https://github.com/cbeuw/Cloak/wiki/Web-page-loading-benchmarks)).
|
|
|
|
## Build
|
|
If you are not using the experimental go mod support, make sure you `go get` the following dependencies:
|
|
```
|
|
github.com/boltdb/bolt
|
|
github.com/cbeuw/ratelimit
|
|
github.com/gorilla/mux
|
|
github.com/sirupsen/logrus
|
|
golang.org/x/crypto
|
|
```
|
|
Then run `make client` or `make server`. Output binary will be in `build` folder.
|
|
|
|
## Configuration
|
|
|
|
### Server
|
|
`RedirAddr` is the redirection address and port when the incoming traffic is not from a Cloak client. It should correspond to the IP record of the `ServerName` field set in `ckclient.json`.
|
|
|
|
`ProxyBook` is a nested JSON section which defines the address of different proxy server ends. For instance, if OpenVPN server is listening on 127.0.0.1:1194, the pair should be `"openvpn":"127.0.0.1:1194"`. There can be multiple pairs. You can add any other proxy server in a similar fashion, as long as the name matches the `ProxyMethod` in the client config exactly (case-sensitive).
|
|
|
|
`PrivateKey` is the static curve25519 Diffie-Hellman private key encoded in base64.
|
|
|
|
`AdminUID` is the UID of the admin user in base64.
|
|
|
|
`BypassUID` is a list of UIDs that are authorised without any bandwidth or credit limit restrictions
|
|
|
|
`DatabasePath` is the path to userinfo.db. If userinfo.db doesn't exist in this directory, Cloak will create one automatically. **If Cloak is started as a Shadowsocks plugin and Shadowsocks is started with its working directory as / (e.g. starting ss-server with systemctl), you need to set this field as an absolute path to a desired folder. If you leave it as default then Cloak will attempt to create userinfo.db under /, which it doesn't have the permission to do so and will raise an error. See Issue #13.**
|
|
|
|
### Client
|
|
`UID` is your UID in base64.
|
|
|
|
`PublicKey` is the static curve25519 public key, given by the server admin.
|
|
|
|
`ProxyMethod` is the name of the proxy method you are using.
|
|
|
|
`EncryptionMethod` is the name of the encryption algorithm you want Cloak to use. Note: Cloak isn't intended to provide data encryption. The point of encryption is to hide fingerprints of proxy protocols. If the proxy protocol is already fingerprint-less, which is the case for Shadowsocks, this field can be left as `plain`. Options are `plain`, `aes-gcm` and `chacha20-poly1305`.
|
|
|
|
`ServerName` is the domain you want to make your ISP or firewall think you are visiting.
|
|
|
|
`NumConn` is the amount of underlying TCP connections you want to use. The default of 4 should be appropriate for most people. Setting it too high will hinder the performance.
|
|
|
|
`BrowserSig` is the browser you want to **appear** to be using. It's not relevant to the browser you are actually using. Currently, `chrome` and `firefox` are supported.
|
|
|
|
## Setup
|
|
### For the administrator of the server
|
|
|
|
0. Set up the underlying proxy server. Note that if you are using OpenVPN, you must change the protocol to TCP as Cloak does not support UDP
|
|
1. Download [the latest release](https://github.com/cbeuw/Cloak/releases) or clone and build this repo.
|
|
2. Run ck-server -k. The base64 string before the comma is the **public** key to be given to users, the one after the comma is the **private** key to be kept secret
|
|
3. Run `ck-server -u`. This will be used as the AdminUID
|
|
4. Copy example_config/ckserver.json into a desired location. Change `PrivateKey` to the private key you just obtained; change `AdminUID` to the UID you just obtained.
|
|
5. Configure your underlying proxy server so that they all listen on localhost. Edit `ProxyBook` in the configuration file accordingly
|
|
6. [Configure the proxy program.](https://github.com/cbeuw/Cloak/wiki/Underlying-proxy-configuration-guides) Run `sudo ck-server -c <path to ckserver.json>`. ck-server needs root privilege because it binds to a low numbered port (443). Alternatively you can follow https://superuser.com/a/892391 to avoid granting ck-server root privilege unnecessarily.
|
|
|
|
#### To add users
|
|
##### Unrestricted users
|
|
Run `ck-server -u` and add the UID into the `BypassUID` field in `ckserver.json`
|
|
|
|
##### Users subject to bandwidth and credit controls
|
|
1. On your client, run `ck-client -s <IP of the server> -l <A local port> -a <AdminUID> -c <path-to-ckclient.json>` to enter admin mode
|
|
2. Visit https://cbeuw.github.io/Cloak-panel (Note: this is a static site, there is no backend and all data entered into this site are processed between your browser and the Cloak API endpoint you specified. Alternatively you can download the repo at https://github.com/cbeuw/Cloak-panel and host it on your own web server).
|
|
3. Type in 127.0.0.1:<the port you entered in step 1> as the API Base, and click `List`.
|
|
4. You can add in more users by clicking the `+` panel
|
|
|
|
Note: the user database is persistent as it's in-disk. You don't need to add the users again each time you start ck-server.
|
|
|
|
### Instructions for clients
|
|
**Android client is available here: https://github.com/cbeuw/Cloak-android**
|
|
|
|
0. Install and configure the proxy client based on the server
|
|
1. Download [the latest release](https://github.com/cbeuw/Cloak/releases) or clone and build this repo.
|
|
2. Obtain the public key and your UID from the administrator of your server
|
|
3. Copy example_config/ckclient.json into a location of your choice. Enter the `UID` and `PublicKey` you have obtained. Set `ProxyMethod` to match exactly the corresponding entry in `ProxyBook` on the server end
|
|
4. [Configure the proxy program.](https://github.com/cbeuw/Cloak/wiki/Underlying-proxy-configuration-guides) Run `ck-client -c <path to ckclient.json> -s <ip of your server>`
|
|
|
|
## Support me
|
|
If you find this project useful, donations are greatly appreciated!
|
|
|
|
[](https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=SAUYKGSREP8GL&source=url)
|
|
|
|
BTC: `bc1q59yvpnh0356qq9vf0j2y7hx36t9ysap30spx9h`
|
|
|
|
ETH: `0x8effF29a8F9bD38A367580527AC303972c92b60c`
|