Wicklight protocol design

2023-02-03 golang coding proxy tls

Wicklight protocol design


This document specifies Wicklight protocol. Wicklight is a common HTTP(s) proxy with probe-resistant.

Copyright (c) 2023 Elliot Chen. All rights reserved.

1. Introduction

Wicklight should also be Probe-Resistance and Traffic-Analysis-Resistance. It also supports UDP proxy with an additional client.

1.1. Conventions and Terminology

The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “NOT RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.

2. Protocol Overview

The wicklight protocol is similar to the traditional HTTP CONNECT Proxy in HTTP/1.1 [RFC2626] and HTTP/2 [RFC7540].

The server MUST be compatible with traditional HTTP/1.1 or HTTP/2 proxy clients. With a specific wicklight client, additional features can be enabled, including 0-RTT and UDP transport.

2.1. TCP Tunnel

Wicklight transport TCP traffics similar to the traditional HTTP CONNECT Proxy. However, it enables 0-RTT, probe-resistant, and padding features.

0-RTT: Unlike traditional HTTP proxies, the client sends the data right after sending the first CONNECT request to the server. If the server refuses to proxy the traffic, it will close the connection directly.

Probe-resistant: To hide the fact of an HTTP proxy server, the server will only send the Proxy-Authenticate head in the response when the host (URL) is in an allowlist. Otherwise, all traffic will be forwarded to a normal backend server. Note that Proxy-Authenticate indicates that the server handles the proxy traffic and requires the client to send an authentication token (usually a base64 [RFC4648] of username:password).

Padding: the request and response can use a Proxy-Padding head to send random padding. The padding is a random base64-encoded string. Its length should be large than 16 and less than 512.

2.2. UDP Tunnel

Wicklight can also be used to proxy UDP traffics. The client must send a Proxy-UDP: udp header in the CONNECT request. Also, the url must be set to wickproxy.udp. When the server receives such a CONNECT request, the whole connection is used to transport UDP traffics.

All UDP packets are transported over the original HTTP CONNECT connection bidirectionally. The UDP packets are first encoded into a UDP associated packet similar in Socks5 [RFC1928]:

| LEN(4) | RSV(2) | FRAG(1) | ATYP(1) | DST.ADDR(VAR) | DST.PORT(2) |   DATA(VAR) | 
  • LEN is four big-encoding bytes that equal to the length of the following parts
  • RSV must be 0x0000
  • FLAG must be 0x00
  • ATYP is one byte:
    • IP V4 address: ‘0x01’
    • DOMAINNAME: ‘0x03’
    • IP V6 address: ‘0x04’
  • DST.ADDR is the destination host, the same as the socks5 protocol
  • DST.PORT is the desired destination port
  • DATA is the actual data

3. HTTP Header Considerations

Wicklight introduces two additional HTTP Headers:

  • Proxy-UDP is used to infer a UDP associate proxy
  • Proxy-Padding is used to add random paddings

Other related HTTP Headers include:

  • Proxy-Connection: Keep-Alive to allow the server not to close the connection.
  • Proxy-Authorization to encode the authentication information
  • Proxy-Authenticate notifies the client to send a Proxy-Authorization header.

4. Security Considerations

The wicklight protocol MUST be encapsulated by the TLS [RFC8446] protocol or wicktls protocol to guarantee security.

The wicklight protocol MUST use the HTTP basic authentication and MUST NOT use anonymous mode.