www.bamsoftware.com/git/champa.git

Champa – general-purpose proxy through an AMP cache David Fifield [e-mail] Public domain

Champa is a pair of programs—champa-client and champa-server—that implements a proxy tunnel over an AMP cache, with the goal of circumventing Internet censorship. It is not limited to tunneling HTTP; it encodes data into HTTP requests that satisfy the requirements of AMP.

AMP ("Accelerated Mobile Pages") is a framework for mobile web pages. AMP pages are written in a restricted subset of HTML. An AMP cache is a cache and proxy for AMP HTML pages: it forwards HTTP requests from a client to an origin server, and relays HTTP responses back to the client, while enforcing the requirement that responses be written in AMP HTML. Champa transforms a specialized AMP cache proxy into a general-purpose proxy.

Access through an AMP cache normally exposes the domain name of the origin server in the hostname of the URL by which the cache is accessed. To hide the origin server from an observer, the champa-client supports domain fronting to make it appear to an external observer that you are accessing a different domain. When you run champa-client, you provide both the URL of an AMP cache

As of 2021, there is really only one option for an AMP cache, Google AMP Cache at https://cdn.ampproject.org/. When you run champa-client, you will therefore always use the -cache https://cdn.ampproject.org/ option, along with a -front option specifying a Google domain for domain fronting.

Champa is an application-layer tunnel that runs in userspace. It doesn't provide a TUN/TAP interface; it only connects a local TCP port to a remote TCP port by way of an AMP cache tunnel DNS resolver. It does not itself provide a SOCKS or HTTP proxy interface, but you can get the same effect by running a proxy on the tunnel server and having the tunnel forward to the proxy.

Tunnel server

The server end of the tunnel must be run on a publicly accessible server, outside the censor's zone of control. champa-server is a plaintext HTTP server. It is meant to listen on localhost, behind a reverse web proxy that can provide TLS to incoming traffic, such as Apache or Nginx.

Compile champa-server:

tunnel-server$ cd champa-server
tunnel-server$ go build

Generate a keypair that will be used for end-to-end confidentiality and integrity with tunnel clients. The server needs to keep a copy of the private key. Each clients needs a copy of the public key.

tunnel-server$ ./champa-server -gen-key -privkey-file server.key -pubkey-file server.pub
privkey written to server.key
pubkey  written to server.pub

Run champa-server. In this example 127.0.0.1:8080 is the port that the HTTP server will listen on. 127.0.0.1:7001 is the TCP address to which incoming tunneled connection will be forwarded—this can be a proxy server, for example.

tunnel-server$ ./champa-server -privkey-file server.key 127.0.0.1:8080 127.0.0.1:7001

Next, you need to configure a reverse web proxy to connect champa-server's HTTP port to the outside world. Below are instructions for how to do this using Apache and Nginx on Debian. The examples assume that you have already installed a web server and configured it to answer requests for the domain example.com. Clients will access the server at the URL https://example.com/champa/ (through an AMP cache).

Apache reverse proxy

For general information on configuring a reverse proxy with Apache, see https://httpd.apache.org/docs/current/howto/reverse_proxy.html#simple.

Configure the server to use TLS, if it does not already. You can do this using Certbot:

tunnel-server$ apt install python3-certbot-apache
tunnel-server$ certbot

Enable the proxy_http Apache module. Although not required, you probably also want to enable the http2 module.

tunnel-server$ a2enmod proxy_http http2

Find the <VirtualHost> directive, and add a new <Location> directive with the path prefix you want to reserve for Champa traffic (here, "/champa/"). Add ProxyPass and ProxyPassReverse directives pointing to champa-server's HTTP listening port. You may also want to disable logging for requests under the path prefix.

<VirtualHost *:443>
	ServerName example.com
	<Location "/champa/">
		ProxyPass http://127.0.0.1:8080/
		ProxyPassReverse http://127.0.0.1:8080/
		SetEnv nolog
	</Location>
	CustomLog ${APACHE_LOG_DIR}/access.log combined env=!nolog
</VirtualHost>

Restart Apache:

tunnel-server$ apache2ctl restart

Nginx reverse proxy

For general information on configuring a reverse proxy with Nginx, see https://docs.nginx.com/nginx/admin-guide/web-server/reverse-proxy/#passing-a-request-to-a-proxied-server.

Configure the server to use TLS, if it does not already. You can do this using Certbot:

tunnel-server$ apt install python3-certbot-nginx
tunnel-server$ certbot

Find the server directive, and add a new location directive with the path prefix you want to reserve for Champa traffic (here, /champa/). Add a proxy_pass directive pointing to champa-server's HTTP listening port. The trailing slash in the URL after proxy_pass is important. You may also want to disable logging for requests under the path prefix. Add http2 to the listen directives, if it is not there already.

server {
	server_name example.com;
	location /champa/ {
		proxy_pass http://127.0.0.1:8080/;
		proxy_redirect default;
		access_log off;
	}
	listen [::]:443 ssl http2 ipv6only=on; # managed by Certbot
	listen 443 ssl http2; # managed by Certbot
}

Restart Nginx:

tunnel-server$ nginx -s reload

Tunnel client

Compile champa-client:

tunnel-client$ cd champa-client
tunnel-client$ go build

Copy the server's public key (server.pub) to the client. You don't need the private key (server.key) on the client.

Run champa-client.

tunnel-client$ ./champa-client -pubkey-file server.pub -cache https://cdn.ampproject.org/ -front www.google.com https://example.com/champa/ 127.0.0.1:7000

The champa-client command line requires five pieces of information:

• -pubkey-file server.pub The server's public key.
• -cache https://cdn.ampproject.org/ The URL of the AMP cache to proxy through.
• -front www.google.com The externally visible domain name to use when connecting to the AMP cache. You can use a Google-operated domain here.
• https://example.com/champa/ The URL of the tunnel server.
• 127.0.0.1:7000 The local TCP port that will receive connections and forward them through the tunnel.

In this example, connections to 127.0.0.1:7000 on the tunnel client will be tunneled through the AMP cache at https://cdn.ampproject.org/ with www.google.com as a domain front, arriving at the tunnel server at https://example.com/champa/, which will then forward the tunneled connections to its own 127.0.0.1:7001.

How to make a proxy

Champa is only a tunnel: it connects a local TCP port to a remote TCP port in a hard-to-detect way. What you connect to those ports is your choice, but generally it will be some kind of proxy.

Ncat HTTP proxy

Ncat has a simple built-in HTTP/HTTPS proxy, good for testing. Be aware that Ncat's proxy isn't intended for use by untrusted clients; it won't prevent them from connecting to localhost ports on the tunnel server, for example.

tunnel-server$ ncat -l -k --proxy-type http 127.0.0.1 7001
tunnel-server$ ./champa-server -privkey-file server.key 127.0.0.1:8080 127.0.0.1:7001

On the client, have the tunnel client listen on 127.0.0.1:7000, and configure your applications to use 127.0.0.1:7000 as an HTTP proxy.

tunnel-client$ ./champa-client -pubkey-file server.pub -cache https://cdn.ampproject.org/ -front www.google.com https://example.com/champa/ 127.0.0.1:7000
tunnel-client$ curl --proxy http://127.0.0.1:7000/ https://wtfismyip.com/text