WireGuard® is an extremely simple yet fast and modern VPN that utilizes state-of-the-art cryptography. It aims to be faster, simpler, leaner, and more useful than IPsec, while avoiding the massive headache. It intends to be considerably more performant than OpenVPN. WireGuard is designed as a general purpose VPN for running on embedded interfaces and super computers alike, fit for many different circumstances. Initially released for the Linux kernel, it is now cross-platform and widely deployable. It is currently under heavy development, but already it might be regarded as the most secure, easiest to use, and simplest VPN solution in the industry.
Simple & Easy-to-use
Minimal Attack Surface
Well Defined & Thoroughly Considered
If you're interested in the internal inner workings, you might be interested in the brief summary of the protocol, or go more in depth by reading the technical whitepaper, which goes into more detail on the protocol, cryptography, and fundamentals. If you intend to implement WireGuard for a new platform, please read the cross-platform notes.
WireGuard securely encapsulates IP packets over UDP. You add a WireGuard interface, configure it with your private key and your peers' public keys, and then you send packets across it. All issues of key distribution and pushed configurations are out of scope of WireGuard; these are issues much better left for other layers, lest we end up with the bloat of IKE or OpenVPN. In contrast, it more mimics the model of SSH and Mosh; both parties have each other's public keys, and then they're simply able to begin exchanging packets through the interface.
Simple Network Interface
WireGuard works by adding a network interface (or multiple), like
wg3, etc). This network interface can then be configured normally using
ip-address(8), with routes for it added and removed using
ip-route(8), and so on with all the ordinary networking utilities. The specific WireGuard aspects of the interface are configured using the
wg(8) tool. This interface acts as a tunnel interface.
WireGuard associates tunnel IP addresses with public keys and remote endpoints. When the interface sends a packet to a peer, it does the following:
- This packet is meant for 192.168.30.8. Which peer is that? Let me look... Okay, it's for peer
ABCDEFGH. (Or if it's not for any configured peer, drop the packet.)
- Encrypt entire IP packet using peer
ABCDEFGH's public key.
- What is the remote endpoint of peer
ABCDEFGH? Let me look... Okay, the endpoint is UDP port 53133 on host 188.8.131.52.
- Send encrypted bytes from step 2 over the Internet to 184.108.40.206:53133 using UDP.
When the interface receives a packet, this happens:
- I just got a packet from UDP port 7361 on host 220.127.116.11. Let's decrypt it!
- It decrypted and authenticated properly for peer
LMNOPQRS. Okay, let's remember that peer
LMNOPQRS's most recent Internet endpoint is 18.104.22.168:7361 using UDP.
- Once decrypted, the plain-text packet is from 192.168.43.89. Is peer
LMNOPQRSallowed to be sending us packets as 192.168.43.89?
- If so, accept the packet on the interface. If not, drop it.
Behind the scenes there is much happening to provide proper privacy, authenticity, and perfect forward secrecy, using state-of-the-art cryptography.
At the heart of WireGuard is a concept called Cryptokey Routing, which works by associating public keys with a list of tunnel IP addresses that are allowed inside the tunnel. Each network interface has a private key and a list of peers. Each peer has a public key. Public keys are short and simple, and are used by peers to authenticate each other. They can be passed around for use in configuration files by any out-of-band method, similar to how one might send their SSH public key to a friend for access to a shell server.
For example, a server computer might have this configuration:
[Interface] PrivateKey = yAnz5TF+lXXJte14tji3zlMNq+hd2rYUIgJBgB3fBmk= ListenPort = 51820 [Peer] PublicKey = xTIBA5rboUvnH4htodjb6e697QjLERt1NAB4mZqp8Dg= AllowedIPs = 10.192.122.3/32, 10.192.124.1/24 [Peer] PublicKey = TrMvSoP4jYQlY6RIzBgbssQqY3vxI2Pi+y71lOWWXX0= AllowedIPs = 10.192.122.4/32, 192.168.0.0/16 [Peer] PublicKey = gN65BkIKy1eCE9pP1wdc8ROUtkHLF2PfAqYdyYBz6EA= AllowedIPs = 10.10.10.230/32
And a client computer might have this simpler configuration:
[Interface] PrivateKey = gI6EdUSYvn8ugXOt8QQD6Yc+JyiZxIhp3GInSWRfWGE= ListenPort = 21841 [Peer] PublicKey = HIgo9xNzJMWLKASShiTqIybxZ0U3wGLiUeJ1PKf8ykw= Endpoint = 22.214.171.124:51820 AllowedIPs = 0.0.0.0/0
In the server configuration, each peer (a client) will be able to send packets to the network interface with a source IP matching his corresponding list of allowed IPs. For example, when a packet is received by the server from peer
gN65BkIK..., after being decrypted and authenticated, if its source IP is 10.10.10.230, then it's allowed onto the interface; otherwise it's dropped.
In the server configuration, when the network interface wants to send a packet to a peer (a client), it looks at that packet's destination IP and compares it to each peer's list of allowed IPs to see which peer to send it to. For example, if the network interface is asked to send a packet with a destination IP of 10.10.10.230, it will encrypt it using the public key of peer
gN65BkIK..., and then send it to that peer's most recent Internet endpoint.
In the client configuration, its single peer (the server) will be able to send packets to the network interface with any source IP (since 0.0.0.0/0 is a wildcard). For example, when a packet is received from peer
HIgo9xNz..., if it decrypts and authenticates correctly, with any source IP, then it's allowed onto the interface; otherwise it's dropped.
In the client configuration, when the network interface wants to send a packet to its single peer (the server), it will encrypt packets for the single peer with any destination IP address (since 0.0.0.0/0 is a wildcard). For example, if the network interface is asked to send a packet with any destination IP, it will encrypt it using the public key of the single peer
HIgo9xNz..., and then send it to the single peer's most recent Internet endpoint.
In other words, when sending packets, the list of allowed IPs behaves as a sort of routing table, and when receiving packets, the list of allowed IPs behaves as a sort of access control list.
This is what we call a Cryptokey Routing Table: the simple association of public keys and allowed IPs.
Any combination of IPv4 and IPv6 can be used, for any of the fields. WireGuard is fully capable of encapsulating one inside the other if necessary.
Because all packets sent on the WireGuard interface are encrypted and authenticated, and because there is such a tight coupling between the identity of a peer and the allowed IP address of a peer, system administrators do not need complicated firewall extensions, such as in the case of IPsec, but rather they can simply match on "is it from this IP? on this interface?", and be assured that it is a secure and authentic packet. This greatly simplifies network management and access control, and provides a great deal more assurance that your iptables rules are actually doing what you intended for them to do.
The client configuration contains an initial endpoint of its single peer (the server), so that it knows where to send encrypted data before it has received encrypted data. The server configuration doesn't have any initial endpoints of its peers (the clients). This is because the server discovers the endpoint of its peers by examining from where correctly authenticated data originates. If the server itself changes its own endpoint, and sends data to the clients, the clients will discover the new server endpoint and update the configuration just the same. Both client and server send encrypted data to the most recent IP endpoint for which they authentically decrypted data. Thus, there is full IP roaming on both ends.
Ready for Containers
WireGuard sends and receives encrypted packets using the network namespace in which the WireGuard interface was originally created. This means that you can create the WireGuard interface in your main network namespace, which has access to the Internet, and then move it into a network namespace belonging to a Docker container as that container's only interface. This ensures that the only possible way that container is able to access the network is through a secure encrypted WireGuard tunnel.
Consider glancing at the commands & quick start for a good idea of how WireGuard is used in practice. There is also a description of the protocol, cryptography, & key exchange, in addition to the technical whitepaper, which provides the most detail.
About The Project
Work in Progress
WireGuard is not yet complete. You should not rely on this code. It has not undergone proper degrees of security auditing and the protocol is still subject to change. We're working toward a stable 1.0 release, but that time has not yet come. There are experimental snapshots tagged with "0.0.YYYYMMDD", but these should not be considered real releases and they may contain security vulnerabilities (which would not be eligible for CVEs, since this is pre-release snapshot software). If you are packaging WireGuard, you must keep up to date with the snapshots.
However, if you're interested in helping out, we could really use your help and we readily welcome any form of feedback and review. There's currently quite a bit of work to do on the project todo list, and the more folks testing this out, the better.
Get involved in the WireGuard development discussion by joining the mailing list. This is where all development activities occur. Submit patches using
git-send-email, similar to the style of LKML. You may also discuss development related activity on
#wireguard on Freenode.
Contact the Team
WireGuard is hosted in the ZX2C4 Git Repository. You may clone the repository via:
$ git clone https://git.zx2c4.com/WireGuard
$ git clone git://git.zx2c4.com/WireGuard
Alternatively, if you have push access, you may clone via SSH:
$ git clone ssh://email@example.com/WireGuard
The kernel module is released under the GPLv2, as is Linux. Other sub-projects are licensed under MIT, Apache 2.0, or GPL, depending.