WireGuard kernel patch that makes WireGuard handshake traffic look like QUIC.
Warning
QUICWireGuard is a legacy project.
Starting from 2026, there is no practical reason to use this project for new deployments.
The project is preserved for historical purposes, existing installations, research, and as a small example of modifying WireGuard directly in the Linux kernel.
For modern deployments, use Amnezia and AmneziaWG instead.
For OpenWrt, I maintain AmneziaWG packages and build scripts here:
https://github.com/karen07/amneziawg-openwrt-package
If your goal is to build a complete network or mesh of OpenWrt routers rather than only a VPN tunnel:
https://github.com/karen07/openwrt-mesh-builder
QUICWireGuard was created in 2024 to solve a simple problem.
WireGuard is a compact, fast and secure VPN protocol, but its UDP handshake has a fixed and easily recognizable structure.
At the time, a simple way to make WireGuard harder to identify was to hide this recognizable handshake behind something that looked like common UDP traffic.
QUIC was a natural candidate because it was already widely used over UDP, especially on port 443.
The idea behind QUICWireGuard was deliberately minimal:
WireGuard handshake
|
v
Add a QUIC-like header
|
v
Send over UDP port 443
Instead of adding another userspace proxy, another tunnel, or a complete transport protocol, QUICWireGuard modifies the Linux kernel implementation of WireGuard directly.
For connections using UDP port 443, it prepends a small QUIC-like header to WireGuard Handshake Initiation and Handshake Response packets.
On reception, this additional header is removed before the packet is passed to the normal WireGuard processing code.
The WireGuard protocol, Noise handshake and cryptography remain unchanged.
The goal was never to implement WireGuard over QUIC.
The goal was much smaller:
Make the WireGuard handshake
less obviously look like WireGuard.
For the threat model of 2024, this was a useful and intentionally simple experiment.
The patch adds a small structure resembling the beginning of a QUIC Initial packet.
It contains fields such as:
Flags
Version
DCID length
DCID
SCID length
SCID
Token length
Data length
The implementation uses UDP port 443 to enable this behavior.
For example:
#define QUIC_PORT 443
#define QUIC_FLAGS 0xC0For Handshake Initiation, a random DCID is generated.
For Handshake Response, a random SCID is generated.
Conceptually:
Standard WireGuard:
UDP
+-- WireGuard Handshake
QUICWireGuard:
UDP
+-- QUIC-like header
+-- WireGuard Handshake
The additional header exists only around the WireGuard handshake packets handled by this patch.
Normal WireGuard data packets are not transported inside QUIC.
QUICWireGuard does not implement the QUIC protocol.
It does not provide:
- QUIC transport
- QUIC streams
- QUIC congestion control
- TLS 1.3 used by QUIC
- HTTP/3
- a QUIC state machine
- WireGuard over a real QUIC connection
It only makes the beginning of a WireGuard connection resemble QUIC traffic.
This distinction is important.
A packet can look similar to QUIC during simple inspection without behaving like a real QUIC connection.
The important change since 2024 is not WireGuard itself.
The threat model changed.
QUICWireGuard was designed against a relatively simple form of protocol detection:
WireGuard has a recognizable handshake
|
v
Change the appearance of the handshake
|
v
Simple WireGuard signature no longer matches
Modern DPI does not need to rely only on a fixed signature at the beginning of a connection.
Traffic classification can use many characteristics of the complete session, including:
- packet sizes
- packet sequences
- packet direction
- timing between packets
- repeated session behavior
- protocol-specific statistical patterns
This means that hiding only the first WireGuard handshake packets is no longer sufficient against modern traffic analysis.
The evolution of AmneziaWG illustrates this change clearly.
Earlier versions focused on removing recognizable WireGuard signatures and protocol mimicry.
AmneziaWG 2.0 extended obfuscation to data traffic by changing packet headers and sizes.
AmneziaWG 3.0 was developed in response to widespread blocking in 2026, when masking individual traffic characteristics was no longer sufficient. It also changes packet sizes, ordering, timing and other session characteristics in order to make statistical classification more difficult.
See the current AmneziaWG documentation:
https://docs.amnezia.org/documentation/amnezia-wg/
So the evolution can be summarized as:
2024
Fixed WireGuard signature
|
v
Hide the handshake
|
v
QUICWireGuard
2026
Classification of the whole session
|
v
Handshake obfuscation alone is not enough
|
v
Use AmneziaWG
QUICWireGuard still has value as a small networking experiment and as an example of how WireGuard can be modified directly in the Linux kernel.
But for a new deployment whose purpose is resistance to modern DPI and VPN blocking, this approach is no longer sufficient.
For modern VPN deployments and censorship-resistant configurations, use Amnezia and AmneziaWG.
https://github.com/karen07/amneziawg-openwrt-package
This is my current AmneziaWG implementation and build system for OpenWrt.
For new OpenWrt VPN deployments, use this project instead of QUICWireGuard.
https://github.com/karen07/openwrt-mesh-builder
If the task is to build and maintain a complete network of multiple OpenWrt routers, use OpenWrt Mesh Builder.
This solves a broader problem than QUICWireGuard: building the network itself rather than only disguising a single WireGuard tunnel.
The original idea, motivation and implementation are described in detail in the article:
The article was written in 2024 and describes the project in the context in which it was originally created.
It remains the main technical and historical documentation for QUICWireGuard.
QUICWireGuard.patch
Patch for the Linux kernel implementation of WireGuard.
linux-auto-install.sh
Build and installation helper for Linux.
openwrt-auto-install.sh
Build and installation helper for OpenWrt.
Warning
QUICWireGuard является устаревшим проектом.
Начиная с 2026 года практического смысла использовать его для новых установок уже нет.
Репозиторий остается доступен для истории, существующих установок, исследований и как небольшой пример модификации WireGuard непосредственно в ядре Linux.
Для новых установок используйте Amnezia и AmneziaWG.
Моя актуальная реализация, пакеты и система сборки AmneziaWG для OpenWrt:
https://github.com/karen07/amneziawg-openwrt-package
Если задача заключается в построении полноценной сети или mesh-сети из OpenWrt-роутеров:
https://github.com/karen07/openwrt-mesh-builder
QUICWireGuard появился в 2024 году как решение простой задачи.
WireGuard является компактным, быстрым и безопасным VPN-протоколом, однако его UDP handshake имеет фиксированную и легко узнаваемую структуру.
На тот момент одним из простых способов усложнить определение WireGuard было скрыть его характерный handshake за заголовком, похожим на распространенный UDP-протокол.
QUIC хорошо подходил для этой задачи, поскольку уже широко использовался поверх UDP, в частности на порту 443.
Идея QUICWireGuard была намеренно минималистичной:
WireGuard handshake
|
v
Добавить QUIC-подобный заголовок
|
v
Отправить через UDP 443
Вместо дополнительного userspace proxy, еще одного туннеля или реализации полноценного транспортного протокола QUICWireGuard изменяет непосредственно WireGuard в ядре Linux.
При работе через UDP-порт 443 к пакетам WireGuard Handshake Initiation и Handshake Response добавляется небольшой QUIC-подобный заголовок.
На принимающей стороне этот заголовок удаляется, после чего пакет передается обычному коду WireGuard.
Сам протокол WireGuard, Noise handshake и криптография при этом не изменяются.
Целью проекта никогда не была реализация WireGuard поверх настоящего QUIC.
Задача была значительно проще:
Сделать WireGuard handshake
менее похожим на WireGuard.
Для threat model 2024 года это был полезный и намеренно простой эксперимент.
Патч добавляет небольшую структуру, похожую на начало QUIC Initial packet.
Она содержит поля:
Flags
Version
DCID length
DCID
SCID length
SCID
Token length
Data length
Этот режим включается при использовании UDP-порта 443.
Например, в патче определены:
#define QUIC_PORT 443
#define QUIC_FLAGS 0xC0Для Handshake Initiation генерируется случайный DCID.
Для Handshake Response генерируется случайный SCID.
Схематично:
Обычный WireGuard:
UDP
+-- WireGuard Handshake
QUICWireGuard:
UDP
+-- QUIC-подобный header
+-- WireGuard Handshake
Дополнительный заголовок используется только для WireGuard handshake-пакетов, которые обрабатывает этот патч.
Обычные WireGuard data packets не передаются внутри QUIC.
QUICWireGuard не реализует протокол QUIC.
В нем нет:
- транспорта QUIC
- QUIC streams
- congestion control QUIC
- TLS 1.3 протокола QUIC
- HTTP/3
- state machine QUIC
- передачи WireGuard внутри настоящего QUIC-соединения
Проект только делает начало WireGuard-соединения похожим на QUIC-трафик.
Это важное различие.
Пакет может выглядеть похожим на QUIC при простом анализе, не являясь при этом частью настоящего QUIC-соединения.
Главное изменение с 2024 года произошло не в самом WireGuard.
Изменился threat model.
QUICWireGuard создавался против относительно простого способа определения протокола:
У WireGuard узнаваемый handshake
|
v
Изменяем внешний вид handshake
|
v
Простая сигнатура WireGuard больше не совпадает
Современному DPI уже не обязательно определять протокол только по фиксированной сигнатуре первых пакетов.
Для классификации может использоваться множество характеристик всей сессии:
- размеры пакетов
- последовательность пакетов
- направление пакетов
- интервалы между пакетами
- повторяемое поведение соединения
- статистические характеристики трафика
Поэтому маскировки только начального WireGuard handshake теперь недостаточно для противодействия современному анализу трафика.
Эволюция AmneziaWG хорошо показывает это изменение.
Ранние версии решали задачу удаления характерных сигнатур WireGuard и мимикрии под другие протоколы.
AmneziaWG 2.0 распространил обфускацию и на передачу данных, изменяя заголовки и размеры пакетов.
AmneziaWG 3.0 появился в ответ на массовые блокировки 2026 года, которые показали, что маскировки отдельных признаков трафика уже недостаточно. В нем изменяются размеры, последовательность и интервалы между пакетами, а также другие характеристики сессии, чтобы усложнить статистическую классификацию.
Актуальная документация AmneziaWG:
https://docs.amnezia.org/ru/documentation/amnezia-wg/
Эволюцию задачи можно представить так:
2024
Фиксированная сигнатура WireGuard
|
v
Скрыть handshake
|
v
QUICWireGuard
2026
Классификация всей сессии
|
v
Одной маскировки handshake уже недостаточно
|
v
AmneziaWG
QUICWireGuard по-прежнему интересен как небольшой networking experiment и как пример того, как WireGuard можно модифицировать непосредственно внутри ядра Linux.
Но для новой установки, основной задачей которой является устойчивость к современному DPI и блокировкам VPN, этого подхода уже недостаточно.
Для современных VPN-установок и работы в условиях блокировок используйте Amnezia и AmneziaWG.
https://github.com/karen07/amneziawg-openwrt-package
Это моя актуальная реализация, пакеты и система сборки AmneziaWG для OpenWrt.
Для новых VPN-установок на OpenWrt следует использовать этот проект вместо QUICWireGuard.
https://github.com/karen07/openwrt-mesh-builder
Если задача заключается в построении и поддержке полноценной сети из нескольких OpenWrt-роутеров, используйте OpenWrt Mesh Builder.
Он решает более широкую задачу: построение всей сети, а не только маскировку одного WireGuard-туннеля.
Исходная идея, мотивация и реализация подробно описаны в статье:
Статья была написана в 2024 году и описывает проект в том контексте, для которого он первоначально создавался.
Она остается основной технической и исторической документацией QUICWireGuard.
GNU Affero General Public License v3.0.
See LICENSE.