Wicktls protocol design

Abstract

This document specifies Wicktls protocol. Wicktls allows building a tunnel based on an SSL/TLS connection with strong traffic reshaping.

Copyright Notice

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

1. Introduction

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.

1.2. Entities

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 token followed by one or multiple chunk(s). The server MUST also send data in one or multiple chunk(s).

client --> server: token || chunk || chunk || ...
server --> client: chunk || chunk || ...

The 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 salt. The salt MUST be “wicktls-v1”.
• cmd is one byte:
  • TCP: cmd = 0x00
  • UDP: cmd = 0x01
  • other values are invalid.

The chunk is in the following format:

chunk: opt (1 byte) || packet len (2 byte) || 
       data len (2 byte) || data || padding

• opt is 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.
• packet len is the size of data and padding
• data len is the size of data

The 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 chunk 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 data len. 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 chunk with opt = 0x01. Then, the receiver MUST send an empty chunk immediately.

The 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 chunk with 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 chunk MAY 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 ["http/1.1"] or ["h2", "http/1.1"].

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 token contains a wrong SHA256 digest or the cmd in token is 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.