Documentation

This documentation is for ArkC V0.2.


Prerequisite:

  1. ArkC Client and ArkC Server, functional
  2. If you want to manage ArkC Client with GUI on Windows, ArkC-Client-GUI-dotnet (https://github.com/projectarkc/arkc-server-udptransmit)
  3. If you need to transmit data via GAE, MEEK-client and MEEK-server, adapted and published on https://github.com/projectarkc/meek/
  4. If you need to transmit data via GAE, a compatible deployment of MEEK-relay (E.g. Google App Engine project) (Same link above)
  5. If you need to form a multiple-server network, ArkC-UDP-Transmit https://github.com/projectarkc/arkc-server-udptransmit/)

In this version, any private certificate should be in the form of PEM without encryption, while any public certificate should be in the form of ssh-rsa. A recommended form is that generated with [-kg|–keygen] option.

For the configuration file, we use JSON format, where no comments are allowed.


Usage of ArkC Server

Command line

arkcserver [-h] [-v] [-t] [[--get-meek] | [-kg|--keygen] | [-c|--config] <Path of the config Json file, default = config.json>]

Detailed explanation of each option:

 -h, --help      show help message and exit
 -v, --verbose   show detailed logs
 -vv             show debug logs
 -kg, --keygen   Generate a key string and quit, overriding other options
 --get-meek      Download meek to home directory, overriding normal options
 -c CONFIG, --config CONFIG
                 specify a configuration files, required for ArkC to start
 -t              use transmit server mode
 -ep, --use-external-proxy
use an external proxy server or handler running locally,e.g. polipo, for better performance. Use this option to support other types of proxy other than HTTP, or use authentication at client-end proxy. Fall back to in-built python proxy server otherwise.

Here is a config sample:

{
    "local_cert_path": "testfiles/server",
    "clients": [
        ["testfiles/client1.pub", <sha1 of client1's private key>],
        ["testfiles/client2.pub", <sha1 of client2's private key>]
    ]
}

For a full list of settings:

Index name Value Type & Description Required / Default
udp_port int, UDP / DNS listening port (0.0.0.0:)53
proxy_port int, local/external proxy port 8100(local)/8123(ext)
local_cert_path str, path of server private key REQUIRED
central_cert_path str, path of central server’s public key REQUIRED if using transmit mode
clients list, (path of client pub, sha1 of client pri) pairs, like above REQUIRED
pt_exec str, command line of pluggable transport executable “obfs4proxy”
obfs_level integer, obfs level 0~3 0
meek_url str, URL of meek’s GAE destination https://arkc-reflect1.appspot.com/
socks_proxy list, (host, port) None (Unused)

Please note that by default, udp_port is set to port 53 for compatibility with DNS protocol, thus root privillege is required for ArkC Server to start.

Explanation of the settings:

When transmit mode is off, obfs_level is set to 0:

  1. When ArkC Server starts, it listens at udp_port, with UDP socket for incoming requests. Server parses these requests as DNS packets and respond with “domain not found”. These requests notify the server with: IP, Remote_Port, Client public key SHA-1.
  2. Server authenticates the request with stored client key data loaded via clients list, after request contents are deciphered with server’s private key, loaded via local_cert_path.
  3. Server connects to the client and exchanges authentication data. If socks_proxy is set, it connects to the client via (one of) the proxy(s).
  4. It forwards transparently all data from the client to the set proxy_port where either an HTTP proxy is running (if no [-ep]) or a socks/HTTP/others service is listening, on TCP.

When obfs_level is set to 3:

In step 2, after authentication, server starts meek-client and connect to the client side (meek-server) via it. Meek-client is loaded from pt_exec. The URL (where MEEK service is running) is set with meek_url.

In this version MEEK doesn’t work with socksproxy, though it’s possible.

obfs_level = 1 or 2 should start obfs4proxy, but due to DNS length limit it is not yet supported.

When transmit mode is on:

In Step 1, server treats all packets as UDP packets and try to verify them with central server’s public key, loaded via central_cert_path.


Usage of ArkC-Client

Command Line:

arkcclient [-h] [-v] [-vv] [[-kg|--keygen] | [--get-meek] | [-c|--config CONFIG]] [-fs|--frequent-swap] [-pn] [-v6 IPV6]

Explanation of every options:

 -h, --help           show help message and exit
 -v                   show detailed logs
 -vv                  show debug logs
 -kg, --keygen        Generate a key string and quit, overriding other options

 --get-meek           Download meek to home directory, overriding normal options

 -c CONFIG, --config CONFIG
                      Specify a configuration files, REQUIRED for ArkC Client to start

 -fs, --frequent-swap Use frequent connection swapping
 -pn, --public-addr   Disable UPnP when you have public network IP address
 (or NAT has been manually configured)

 -v6 IPV6             Include your IPv6 address, use this option to use and specify your IPv6 address (only use it if you have one)

A config sample:

{
    "local_cert":"client.pem",
    "remote_cert":"server.pub",
    "local_cert_pub":"client.pub",
    "control_domain":"testing.arkc.org",
    "dns_servers": [
            ["8.8.8.8", 53]
         ]
}

Detailed meaning:

Index name Value Type & Description Required / Default
local_host str, proxy listening address “127.0.0.1”
local_port integer, proxy port 8001
remote_host str, listening host “0.0.0.0”
remote_port integer, listening port random between 20000 and 60000
number integer, how many connections to request (max. 100) 3
local_cert str, path of client private key REQUIRED
local_cert_pub str, path of client public key REQUIRED
remote_cert str, path of server public key REQUIRED
control_domain str, the (postfix) domain to request (with NS record set) REQUIRED
dns_server list, servers to send dns query to [] (use system resolver)
debug_ip str, IPv4 address of the client  for debug use), overrides query None
pt_exec str, command line of PT executable “obfs4proxy”
obfs_level integer, obfs leve 0~3, the same as server side 0

When Client starts:

  1. Connect to api.ipify.org to get the IP address in public network (unless debug_ip set).
  2. Attempt UPnP mapping with remote_port (unless using [-pn]).
  3. Send DNS query of a domain ends with control_domain (***.***.***.control_domain), to designated servers (random picked form dns_server).
  4. Listen to local_port for incoming browser requests and remote_port for server connections (or use meek-server, if set obfs_level and pt_exec).