Wicktls protocol design
This document specifies Wicktls protocol. Wicktls allows building a tunnel based on an SSL/TLS connection with strong traffic reshaping.
Copyright (c) 2022 Elliot Chen. All rights reserved.
The primary goal of Wicktls is to build a security tunnel based on an SSL/TLS connection. It should also be Probe-Resistance and Traffic-Analysis-Resistance.
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.
The following terms are used:
client: The endpoint initiating the TLS connection.
server: The endpoint handling TLS connection.
connection: A transport-layer connection between two endpoints.
endpoint: Either the client or server of the connection.
handshake: An initial negotiation between the client and server that establishes the parameters of their subsequent interactions within TLS.
sender: The endpoint to send data. It can be a client or a server.
receiver: The endpoint to receiver data. It can be a client or a server.
peer: An endpoint. When discussing a particular endpoint, “peer” refers to the endpoint that is not the primary subject of discussion.
user: the endpoint that wants to proxy TCP or UDP data.
outbound: the endpoint that receives the TCP/UDP data.
Wicktls client receives TCP/UDP data from a valid user. Then, it encodes the date in the Wicktls protocol and sends the data to the server. It also receives TCP/UDP data from a server, decodes data, and sends it to a user. It MUST listen to a TCP address, known by the users, and MAY listen to the same address for UDP protocol.
Wicktls server receives Wicktls protocol from a client. It decodes data and sends it to an outbound. The server also receives data from the outbound, encodes data with Wicktls protocol, and sends it to the client. It MUST listen to a TCP address, known by the client.
Outbound can be any TCP/UDP server. It is usually a web server, a DNS server or a proxy server (such as Shadowsocks).
2. Protocol Overview
2.1. Stream Overview
Wicktls uses a Big-Ending encode. A Wicktls connection MUST be established based on a valid SSL/TLS connection. All Wicktls data MUST be transmitted within an SSL/TLS connection.
The Wicktls client and server MUST proxy TCP streams for all valid users. They MAY proxy UDP diagrams. Users and clients must share a password. The client MAY store multiple passwords. A password is a string.
Wicktls starts with the client sending a
by one or multiple
chunk(s). The server MUST also send data in
one or multiple
client --> server: token || chunk || chunk || ... server --> client: chunk || chunk || ...
token is a 5 byte message.
token: sha256(password || "wicktls-v1")[:4] || `cmd`
- The first 4 bytes are the Sha256 of the password and a
saltMUST be “wicktls-v1”.
cmdis one byte:
- TCP: cmd = 0x00
- UDP: cmd = 0x01
- other values are invalid.
chunk is in the following format:
chunk: opt (1 byte) || packet len (2 byte) || data len (2 byte) || data || padding
optis used for traffic reshaping.
- The Least Significant Byte (LSB) of
opt= 0x00, empty
- LSB of
opt= 0x01, the receiver must send an empty chunk when receiving this chunk. An empty chunk is a chunk whose data length is 0.
- The Least Significant Byte (LSB) of
packet lenis the size of
data lenis the size of
packet len MUST be shorter than 16384 bytes. The
data len MUST be shorter than 16384 - 256 bytes. The padding
length SHOULD be in [16, 256].
Except for the first chunk, each chunk SHOULD be contained by a
SSL/TLS Record Protocol. The
token and the first
MUST be sent in the same Record Protocol.
2.2. TCP Transmission
The Wicktls client and server MUST proxy TCP streams. The
cmd of the TCP tunnel MUST be 0x00.
The sender MUST fragment the TCP stream to fit the
Then, the sender sends chunks that contain TCP streams.
The receiver MUST read data from chunks continuously. Then, it rebuilds the TCP stream and sends data to the user or outbound.
2.2. UDP Assistant
UDP packets are transmitted through the Wicktls connection.
The Wicktls client and server MAY proxy UDP data. The
cmd of the TCP tunnel MUST be 0x01.
UDP packet MUST be carried by one
chunk. The endpoints
MUST NOT fragment UDP packets.
2.3. Traffic Reshaping
To obfuscate traffic characteristics, a Wicktls client and server SHOULD perform traffic reshaping. Wicktls contains three types of traffic reshaping.
- Fragment. The Wicktls endpoints MAY fragment TCP streams into several
chunk. UDP packets MUST NOT be fragmented.
- Padding. The Wicktls endpoints MAY pad the
chunk. The padding length MUST be in [0, 256].
- Empty chunk. The Wicktls endpoints MAY send a
opt= 0x01. Then, the receiver MUST send an empty
data len in an empty
chunk MUST be 0. The empty chunk
MUST contain a padding longer than 1 byte. When an endpoint
receives an empty
chunk, it MUST NOT send a
opt = 0x01.
2.3.1. TLS-in-TLS Traffic Reshaping
To obfuscate TLS-in-TLS traffic, a Wicktls client or server MAY use the following strategy.
- Fragment. For the first 3 packets, a Wicktls client or server MAY fragment them if the length is large than 300 (classic length of a ClientHello record).
- Padding. a Wicktls client or server MAY pad the first 3 packets. The padding length MAY be randomly in [16, 128].
- Empty chunk. For the first 3 packets, the
chunkMAY be marked as
opt== 0x01 with a possibility larger than 0.2.
2.3.2. Full Traffic Reshaping
To provide the best traffic reshaping effect, a Wicktls client or server MAY use the following strategy.
- Fragment. A Wicktls client or server MAY fragment all TCP packets.
- Padding. A Wicktls client or server MAY packet all chunks. length MAY be randomly in [0, 128].
- Empty chunk. A Wicktls client or server MAY mark
opt= 0x01, with a possibility larger than 0.3.
However, the full traffic reshaping may reduce the throughput and increase the delay.
3. Security Considerations
3.1. SSL/TLS Requirements
The security of Wicklts protocol is provided by SSL/TLS. The SSL/TLS version must be larger than TLSv1_2. The SSL/TLS connection SHOULD use the secure ciphers commonly used by browsers and major servers.
The SSL/TLS should also provide a fake ALPN, Wicktls endpoints MAY use
3.2. Fallback Model
The Wicktls server SHOULD be Probe-Resistance. It MUST behave like a common web server.
- If the client sends an error ClientHello (usually not a TLS protocol), the Wicktls server MAY relay all data to an HTTPS server.
- If the
tokencontains a wrong SHA256 digest or the
tokenis invalid, the Wicktls server MAY relay all data to an HTTP server.
The Wicktls server MAY relay data to multiple fallback servers depending on the ALPN protocol. For example, it MAY fall back to an HTTP/1.1 server if ALPN is “http/1.1”. It MAY fall back to an HTTP/2 server if ALPN is “h2”.
3.3. TLS-in-TLS Analysis
It is common to proxy HTTPS traffic through Wicktls protocol. As a result, an internal TLS is established within the Wicktls connection. The Wicktls client and server SHOULD adopt traffic reshaping to fragment and padding at least TLS Handshake data.