wireguard-fpga - Full-throttle, wire-speed hardware implementation

项目说明

<!--
SPDX-FileCopyrightText: 2026 Chili.CHIPS*ba

SPDX-License-Identifier: BSD-3-Clause
-->

![NLnet Foundation]()
![GitHub stars]()

Wireguard FPGA

Private Networks (VPNs) are the central and indispensable component of Internet security. They comprise a set of technologies that connect geographically dispersed, heterogeneous networks through encrypted tunnels, creating the impression of a homogenous private 网络 on the public shared physical medium.

<img width="20%", src="0.doc/artwork/wireguardfpga.hex.svg">
<img width="16%", src="0.doc/artwork/ethernet-cable.png">
<img width="20%", src="0.doc/artwork/wireguardfpga.hex.svg">

With traditional solutions (such as OpenVPN / IPSec) starting to run out of steam, Wireguard is increasingly coming to the forefront as a modern, secure data tunneling and encryption method, one that's also easier to manage than the incumbents. Both software and hardware implementations of Wireguard already exist. However, the software performance is far below the speed of wire. The existing hardware approaches are both prohibitively expensive and based on proprietary, closed-源码 IP blocks and tools.

This project aims to bridge these gaps with an open-source, FPGA-based implementation of Wireguard. It puts to work multiple open-源码 technologies:

⭐ PipelineC HLS-like

⭐ PeakRDL CSR

⭐ RISC-V CPU

⭐ VProc CoSim

⭐ OpenXC7 PNR

⭐ SV2V System HDL con

and taps into ⭐ open-源码 IP library in order to compose a coherent hardware-software SOC for secure networking.

A Glimpse into History

We ha to the Blackwire project, which is a 100Gbps hardware implementation of Wireguard switch based on AMD/Xilinx-proprietary Al PC-accelerator card (SmartNIC form-factor), and implementable only with proprietary toolchain.

While working on the _Blackwire_, we ha multiple sections, and focused on the no for _Balanced Binary Tree Search_ of IP tables. However, the _Blackwire_ hardware platform is expensive and priced out of reach of most educational institutions. Its gateware is written in SpinalHDL, a nice and powerfull but a niche HDL, which has not taken roots in the industry. While _Blackwire_ is now released to open-源码, that decision came from their financial hardship -- It was originaly meant for sale. Moreover, the company behind it is subject to disputes and obligations that bring into question the legality of ownership over the codebase they "donated" to the open 源码 community.

Back to the Future

To make the hardware Wireguard truly accessible in the genuine spirit of open-源码 mo, this project implements it:
- for an inexpensi platform with four 1000Base-T ports
- in a self-sufficient way, i.e. w/o requiring PC host
- using a commodity Artix7 FPGA
- which is supported by open-源码 tools
- and with all gateware written in the ubiquitous / System

References

[Ref1] Wireguard implementations in software:
- Netbird
- Tailscale
- Linux Kernel

[Ref2] 100Gbps _Blackwire_ Wireguard

[Ref3] Corundum, open-源码 FPGA-NIC platform

[Ref4] ChaCha20-Poly1305 open-源码 Crypto RTL

[Ref5] Cookie Cutter SOC

[Ref6] RISC-V ISS

[Ref7] 10Gbps Ethernet Switch

[Ref8] OpenXC7 open-源码 tools for Xilinx Series7

[Ref9] Alex's Ethernet Stack

[Ref10] High-performance Switches and Routers

[Ref11] Amina's ADASEC-SDN

[Ref12] opencryptohw

[Ref13] Pypeline Native Sim

Project Outline

Scope

The Phase1 (This!) is primarily Proof of Concept, i.e. not full-featured, and definitely not a deployable product. It is en as a mere on-ramp, a springboard for future build-up and optimizations.

The Phase2 continuation project is therefore also in the plans, to maximize efficiency and o useability, such as by increasing the number of channels, facilitating management with 界面 apps, or something else as identified by the community feedback.

Recognized Challenges

1) HW/SW partitioning, interface, interactions and workload distribution
- While, contrary to _Blackwire_, we don’t rely on an external PC connected via PCIE, we will still have an on-chip RISC-V CPU with intricate hardware interface and significant Embedded Software component that controls the backbone of wire-speed datapath

2) HW/SW co-de, integration and debugging
- Standard simulation is impractical for the project of this size and complexity. We therefore intend to put to test and good use the very promissing new VProc ISS [Ref6]
- It’s also impractical and expensive to provide full test systems with real traffic generators and checkers to all de. We therefore plan to rent some space for a central lab that will host two test systems, then provide remote access to all de

3) Real-life, at-speed testing
4) Extent of open-源码 tools support for System and all needed FPGA primitives and IP functions
5) QOR of the (still maturing) open-源码 tools
- _Blackwire_ used commercial, AMD/Xilinx-proprietary toolchain, as well as high-end Alveo U50 FPGA silicon. Even then, they ran into multiple timing closure, utilization and routing congestion challenges.
6) Financial resources
- Given that this is a complex, multi-disciplinary de, the a funding may not be sufficient to bring it to completion. _Blackwire_, despite a larger allocated budget, ended up with funding crisis and abrupt cessation of de.

Design Blueprint (WIP)

HW/SW Partitioning

Since the WireGuard node essentially functions as an IP router with WireGuard 协议 support, we ha to design the system according to a two-layer architecture: a control plane responsible for managing IP routing processes and executing the WireGuard 协议 (managing remote peers, sessions, and keys), and a data plane that will perform IP routing and cryptography processes at wire speed. The control plane will be implemented as software running on a soft CPU, while the data plane will be fully implemented in RTL on an FPGA.

In the HW/SW partitioning diagram, we can observe two types of 网络 traffic: control traffic, which originates from the control plane and goes toward the external 网络 (and vice versa), and data traffic, which arrives from the external 网络 and, after processing in the data plane, returns to the external 网络. Specifically, control traffic represents WireGuard 协议 handshake messages, while data traffic consists of end-user traffic, either encrypted or in plaintext, depending on the perspective.

Hardware Architecture and Theory of Operation

The hardware architecture essentially follows the HW/SW partitioning and consists of two domains: a soft CPU for the control plane and RTL for the data plane.

The soft CPU is equipped with a Boot ROM and a DDR3 SDRAM controller for interfacing with off-chip memory. External memory is exclusively used for control plane processes and does not store packets. The connection between the control and data planes is established through a CSR-based HAL.

The data plane consists of several IP cores, including data plane 引擎 (DPE) and supporting components, which are listed and explained in the direction of 网络 traffic propagation:

_PHY Controller_ - initial configuration of Realtek PHYs and monitoring link activity (link up/down events)

_1G MAC_ - execution of the 1G Ethernet 协议 (framing, flow control, FCS, etc.)

_Rx FIFOs_ - clock domain crossing, bus width con, and store & forward packet handling

_Per-Packet Round Robin Multiplexer_ - ser Rx FIFOs on a per-packet basis using a round-robin algorithm

_Header Parser_ - extraction of WireGuard-related information from packet headers (IP addresses, UDP ports, WireGuard message type, peer ID, etc.)

_Wireguard/UDP Packet Disassembler_ - decapsulation of the payload from the Wireguard data packet for decryption of tunneled traffic

_ChaCha20-Poly1305 Decryptor_ - decryption and authentication of tunneled traffic

_IP Lookup Engine_ - routing/forwarding table lookup, mapping packets to the appropriate WireGuard peer, and making packet accept/reject decisions

_ChaCha20-Poly1305 Encryptor_ - encryption and authentication of traffic to be tunneled

_Wireguard/UDP Packet Assembler_ - encapsulation of the encrypted packet into a WireGuard data packet for tunneling to the remote peer

_Per-Packet Demultiplexer_ - forwarding packets to Tx FIFOs based on packet type and destination

_Tx FIFOs_ - clock domain crossing, bus width con, and store & forward packet handling

_ChaCha20-Poly1305 Encryptor/Decryptor_ are using RFC7539's AEAD (Authenticated Encryption Authenticated Data) construction based on ChaCha20 for symmetric encryption and Poly1305 for authentication.

The details of hardware architecture can be found in the README.md in the 1.hw/ directory.

Software Architecture and Theory of Operation

The conceptual class diagram provides an o of the components in the software part of the system without delving into implementation details. The focus is on the WireGuard Agent, which implements the 协议's handshake procedures, along with the following supplementary components:

Cur - an ECDH algorithm implementation for establishing a shared secret using a public-private key pair between two remote parties connected via an insecure channel, such as the Internet

ChaCha20-Poly1305 - an AEAD algorithm implementation for encryption and authentication of static keys and nonce to prevent replay attacks

XChaCha20-Poly1305 - a XAEAD algorithm implementation for encrypting and authenticating nonce in Cookie Replay messages to mitigate potential DoS attacks

BLAKE2s - an implementation of the BLAKE2s hash function for MAC authentication and keyed hashing, per RFC7693

RNG - a random number generator used to initialize the DH key generator and generate peer identifiers

Timer - timers for rekey, retry, and keepali

HKDF - an implementation of the algorithm for expanding the ECDH result

RTC - a real-time clock used to generate the TAI64N timestamp

SipHash - a simple non-cryptographic function used for implementing a hashtable for fast lookup of decrypted static public keys of remote peers

Routing DB Updater - a subsystem for maintaining the cryptokey routing table content and deploying it to the data plane via the HAL/CSR interface

ICMP - implementing basic ICMP 协议 functions (echo request/reply, TTL exceeded, etc.)

CLI - a USB/UART-based command-line interface for configuring the WireGuard node (setting the local IP address, remote peer IP addresses, 网络 addresses, keys, etc.)

HAL/CSR Driver - a CSR-based abstraction for data plane components with an interface for reading/writing the corresponding registers

The details of software architecture can be found in the README.md in the 2.sw/ directory.

HW/SW Working Together as a Coherent System

To illustrate the operation of the system as a whole, we ha a step-by-step analysis of packets processing based on the capture of real WireGuard traffic. The experimental topology consists of four nodes:

10.10.0.2 - the end-user host at site A

10.9.0.1 - WireGuard peer A

10.9.0.2 - WireGuard peer B

10.10.0.1 - the end-user host at site B

The detailed analysis can be found in the README.md in the 1.hw/ directory.

Simulation Test Bench

The Wireguard FPGA test bench aims to have a flexible approach to simulation which allows a common test en to be used whilst selecting between alternative CPU components, one of which uses the _ processor co-simulation element. This allows simulations to be fully HDL, with a RISC- RTL implementation such as picoRV32, IBEX or EDUBOS5, or to co-simulate software using the processor, with a significant speed up in simulation times. The test bench has the following features:

* A _ processor based soc_cpu.VPROC component
* Selectable between this or an RTL softcore
* Can run natively compiled test code
* Can run the application compiled natively with the auto-generated co-sim HAL
* Can run RISC- 代码 using the rv32 RISC-V ISS model
* Uses a C sparse memory model
* An HDL component instantiated in logic gi access to this memory
* An API is provided to _ running code for direct access
* The _udpIpPg VIP_ is used to drive the logic's four ethernet ports in a four port bfm_ethernet block.
* An MDIO sla is also provided that maps *mem_model* memory areas to the registers with instantiated *mem_model* components

The figure below shows an o block diagram of the test bench HDL.

More details on the architecture and usage of the Wireguard test bench can be found in the README.md in the 4.sim directory.

Co-simulation HAL

The Wireguard control and status register harware abstraction layer (HAL) software is auto-generated, as is the CSR RTL, using peakrdl. For co-simulation purposes an additional layer is auto-generated from the same SystemRDL specification using systemrdl-compiler that accompanies the peakrdl tools. This produces two header files that define a common API to the application layer for both the RISC- and the *VProc* based co-simulation en. The details of the HAL generation can be found in the README.md in the 3.build/ directory.

Build process

The details of the build process can be found in the README.md in the 3.build/ directory.

Lab Test and Setup

The figure illustrates a test topology consisting of two remote hosts, A and B, connected in a using two WireGuard-FPGA nodes interconnected over a public 网络. An additional node in the public 网络 is included to demonstrate traffic encryption. Detailed instructions for configuring the WireGuard-FPGA nodes are provided in README.md in the 6.test/ directory.

---

Project Execution Plan / Tracking

This project in the final wrap up phase. The checkmarks below indicate status. Until all checkmarks are in place, anything you get from here is w/o guaranty -- Use at own risk, as you see fit, and don't blame us if it is not working 🌤️

Take1

Board bring up. In-depth review of Wireguard ecosystem and prior art. Design Blueprint

While the board we're using is low cost, it is also not particularly known in the open-源码 community. We certainly don’t ha experience with it. In this opening take we will build a solid foundation for efficient project execution. Good preparation is crucial for a smooth run. We thus seek to first _understand and document what we will be designing: SOC Architecture, Datapath Microarchitecture, Hardware/Software Partitioning, DV and Strategy_.

Getting a good feel for our Fmax is also a goal of this take. Artix-7 does not support High-Performance (HP) I/O. Consequently, we cannot push its I/O beyond 600MHz, nor its core logic beyond 100 MHz.

[x] ✔ Familiarization with HW platform

- Create our first FPGA program that blinks LEDs
- pinouts and connectivity using simple test routines
- Generate a few Ethernet test patterns

[x] ✔ Familiarization with SW platform

- Initial bring up of embedded CPU within a _cookie-cutter_ SOC, such as [Ref5]
- Design and test a simple SW interface to rudimentary HW Ethernet datapath

[x] ✔ Detailed analysis and comparisons of:

- Wireguard White Papers
- existing implementations in software [Ref1]
- hardware implementation [Ref2]
- cryptographic algorithms used for Wireguard, esp. ChaCha20 for encryption, Poly1305 for authentication [Ref4] and, to a lesser extent, _Cur for key exchange and _blake2_ for hashing

[x] ✔ Identification and assimilation of prior art and building IP blocks, in particular Corundum [Ref3] and, to a lesser extent, _10GE Switch_ [Ref7]

[x] ✔ Architecture/uArch Design. HW/SW Partitioning. Plan

[x] ✔ Creation of sufficient initial documentation for project di across a multi-disciplinary team of half a dozen de

Take2

Implementation of a basic, statically pre-configured Wireguard link

It it in this take that we start creating hardware Datapath and hardening Wireguard encryption protocols, all using and Xilinx primitives.

[x] ✔ Integration of collected RTL blocks into a coherent HW system that implements the basic Wireguard datapath for a handful of manually pre-configured channels.

- Corundum FPGA-based NIC and platform for opensource Ethernet de [Ref3]
- IP Core for ChaCha20-Poly1305 [Ref4] -- Definitely in hardware from the get-go
-
-
-
-

- _Cur module for key exchange -- Likely in software at this point
-
- _blake2_ module for hashing (we'll most likely do it in software)
-

[x] ✔ Timing closure. Resolution of FPGA device utilization and routing congestion issues

[x] ✔ Creation of cocoTB DV in the CI/CD en, and representative test cases for datapath simulation

Take3

De and integration of embedded management software (Control Plane)

This work package is about hardware/software codesign and integration. The firmware will run on a soft RISC , inside the FPGA. Our SOC is at this point starting to be customized to Wireguard needs. This work can to some extent go on in parallel with hardware acti of Take2.

[x] ✔ SW design for on-chip processor (Part 1)

- 代码 is to be written in the bare-metal C with, as necessary, a few sections in Assembly
- SW is responsible for configuration and management of hardware blocks
- SW must not participate in the bulk datapath transfers
- SW may howe the low-frequency management packets

[x] ✔ SW design for on-chip processor (Part 2)

- KMM function -- Key Management Module

[x] ✔ HW/SW Integration

Take4

: Session initialization, maintenance, and secure closure

This is about managing the bring-up, maintenance and tear-down of between two devices.

[x] ✔ Session Initialization: Starting the handshake process to establish secure communication with another device

[ ] Session Maintenance: Keeping the session acti the regular exchange of control messages, which allows detection and recovery from problems such as connection interruptions

[ ] Session Closure: Securely close the when communication is no longer needed, ensuring that all temporary keys and sensitive data are deleted

Take5

Testing, Profiling and Porting to OpenXC7

[ ] Functional testing on the real system. Does it work as intended? Bug fixes

[ ] Performance testing. HW/SW profiling, updates and enhancements to ensure the design indeed operates at close to the wire speed on all preconfigured channels

[x] ✔ Porting to openXC7 [Ref8] using SV2V, in the GoCD CI/CD setting

- This is challenging, as openXC7 has thus far been crashing for NES SV

[x] ✔ Timing closure with openXC7

- This is definitely challenging, given that openXC7 is currently without accurate timing-driven STA

[x] ✔ Filing bug tickets with open 源码 de for issues found in their tools, supporting them all the way to the resolution

[x] ✔ Creation and maintenance of an attractive and well-documented Github repo, to entice community interest

[x] ✔ Ongoing documentation updates and CI/CD script maintenance to keep it valid in the light of ine design mutations compared to the original Design Blueprint.

Take6 (time-permitting Bonus)

Flow control module for efficient and stable data management

The objective of this optional deli is to ensure stable and efficient links, thus taking this project one step closer to a deployable product.

[ ] Develop software components for management of data flow within

Closing Notes

TODO

Acknowledgements

We are grateful to NLnet Foundation for their sponsorship of this de activity.

<img src="
<img width="20%" alt="NGI-Entrust-Logo" src="

This project was funded through the NGI0 Entrust Fund, a fund established by NLnet with financial support from the European Commission's Next Generation Internet programme, under the aegis of DG Communications Networks, Content and Technology under grant agreement No 101069594.

The wy's wisdom and contribution made a great deal of difference -- Thank you, we are honored to have you on the project.

If it was not for Julian Kemmerer's unreser helping us move our two cryptography blocks from C to gates, be it by guiding and mentoring, or by doing it himself, the meat of this project would not have been so easily pushed through to hardware using PipelineC. Thank you Mr.OpensourceHLS 🙏.

Public posts:

2025-12-11

2025-10-12

2025-06-07

2025-05-17

2025-01-18

2024-10-27

2024-09-19

#### End of Document

项目信息

开发语言：

Star 数：1363

技术要点

该项目属于黑客技术方向的开源资源，代码结构清晰，适合安全研究人员学习参考。项目围绕Full-throttle, wire-speed hardware implementation of Wireguard VPN, using low-cost Artix7 FPGA with opensource toolchain. If you seek security and privacy, nothing is private in our codebase. Our door is wide open for backdoor scrutiny, be it related to RTL, embedded, build, bitstream or any other aspect of design and delivery package. Bujrum!展开，提供了可运行的实现，对理解相关安全机制、工具原理与攻防技术具有较高的研究价值。

从技术实现角度看，此类项目的核心在于对底层原理的深入理解与工程化落地。开发者在研究过程中可以结合官方文档与社区讨论，梳理项目的初始化流程、核心模块职责与数据流转，逐步掌握其中的技术细节与设计思路。

使用与学习建议

1. 下载源码压缩包，解压到本地环境。

2. 根据项目类型准备对应的运行环境与依赖。

3. 按照 README 中的步骤完成配置与部署。

4. 在隔离的测试环境中运行验证，避免影响生产系统。

免责声明

本资源来源于开源社区，仅供安全研究、技术学习与合法授权范围内的攻防演练使用，请勿用于任何非法或侵害他人权益的用途。使用本项目产生的一切后果由使用者自行承担。

登录后才能参与讨论

下载链接

会员才能下载

登录后开通会员

同分类推荐

暂无同类资源

资源标题	wireguard-fpga - Full-throttle, wire-speed hardware implementation
所属分类	黑客技术
发布作者	admin
发布时间	2026-10-05 22:15:13
下载权限	免费下载
附件数量	2 个下载链接
浏览次数	111
讨论数量	0
主题状态	正常讨论中