Frigidaire Network Switch User & Service Manual PDF

WireGuard: Next Generation Kernel Network Tunnel www.wireguard.com Jason A. Donenfeld jason@zx2c4.com Draft Revision Abstract WireGuard is a secure network tunnel, operating at layer 3, implemented as a kernel virtual network interface for Linux, which aims to replace both IPsec for most use cases, as well as popular user space and/or TLS-based solutions like OpenVPN, while being more secure, more performant, and easier to use. The virtual tunnel interface is based on a proposed fundamental principle of secure tunnels: an association between a peer public key and a tunnel source IP address.

It uses a single round trip key exchange, based on NoiseIK, and handles all session creation transparently to the user using a novel timer state machine mechanism. Short pre-shared static keys—Curve25519 points—are used for mutual authentication in the style of OpenSSH. The protocol provides strong perfect forward secrecy in addition to a high degree of identity hiding. Transport speed is accomplished using ChaCha20Poly1305 authenticated-encryption for encapsulation of packets in UDP. An improved take on IP-binding cookies is used for mitigating denial of service attacks, improving greatly on IKEv2 and DTLS’s cookie mechanisms to add encryption and authentication.

The overall design allows for allocating no resources in response to received packets, and from a systems perspective, there are multiple interesting Linux implementation techniques for queues and parallelism. Finally, WireGuard can be simply implemented for Linux in less than 4,000 lines of code, making it easily audited and verified. Permanent ID of this document: 4846ada1492f5d92198df154f48c3d54205657bc . Static link: wireguard.com/papers/wireguard .pdf . Date: June 1, 2020. This is draft revision e2da747 . A version of this paper appears in Proceedings of the Network and Distributed System Security Symposium, NDSS 2017 . Copyright © 2015–2020 Jason A. Donenfeld. All Rights Reserved. 1

Стр. 1

Contents 1 Introduction & Motivation 3 2 Cryptokey Routing 4 2.1 Endpoints & Roaming . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 3 Send/Receive Flow 5 4 Basic Usage 6 5 Protocol & Cryptography 7 5.1 Silence is a Virtue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 5.2 Optional Pre-shared Symmetric Key Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 5.3 Denial of Service Mitigation & Cookies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 5.4 Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

9 5.4.1 Protocol Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 5.4.2 First Message: Initiator to Responder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 5.4.3 Second Message: Responder to Initiator . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 5.4.4 Cookie MACs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 5.4.5 Transport Data Key Derivation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 5.4.6 Subsequent Messages: Transport Data Messages . . . . . . . . . . . . . . . . . . . . . . . 12 5.4.7 Under Load: Cookie Reply Message . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . 13 6 Timers & Stateless UX 13 6.1 Preliminaries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 6.2 Transport Message Limits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 6.3 Key Rotation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 6.4 Handshake Initiation Retransmission . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 6.5 Passive Keepalive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 6.6 Interaction with Cookie Reply System . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . 15 7 Linux Kernel Implementation 15 7.1 Queuing System . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 7.2 Softirq & Parallelism . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 7.3 RTNL-based Virtual Interface & Containerization . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 7.4 Data Structures and Primitives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 7.5 FIB Considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 7.6 Potential Userspace Implementations . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . 18 8 Performance 18 9 Conclusion 18 10 Acknowledgments 19 2

Стр. 2

1 Introduction & Motivation In Linux, the standard solution for encrypted tunnels is IPsec, which uses the Linux transform (“xfrm”) layer. Users fill in a kernel structure determining which ciphersuite and key, or other transforms such as compression, to use for which selector of packets traversing the subsystem. Generally a user space daemon is responsible for updating these data structures based on the results of a key exchange, generally done with IKEv2 [ 13 ], itself a complicated protocol with much choice and malleability. The complexity, as well as the sheer amount of code, of this solution is considerable.

Administrators have a completely separate set of firewalling semantics and secure labeling for IPsec packets. While separating the key exchange layer from the transport encryption— or transformation—layer is a wise separation from a semantic viewpoint, and similarly while separating the transformation layer from the interface layer is correct from a networking viewpoint, this strictly correct layering approach increases complexity and makes correct implementation and deployment prohibitive. WireGuard does away with these layering separations.

Instead of the complexity of IPsec and the xfrm layers, WireGuard simply gives a virtual interface— wg0 for example—which can then be administered using the standard ip(8) and ifconfig(8) utilities. After configuring the interface with a private key (and optionally a pre-shared symmetric key as explained in section 5.2 ) and the various public keys of peers with whom it will communicate securely, the tunnel simply works. Key exchanges, connections, disconnections, reconnections, discovery, and so forth happen behind the scenes transparently and reliably, and the administrator does not need to worry about these details.

In other words, from the perspective of administration, the WireGuard interface appears to be stateless . Firewall rules can then be configured using the ordinary infrastructure for firewalling interfaces, with the guarantee that packets coming from a WireGuard interface will be authenticated and encrypted. Simple and straightforward, WireGuard is much less prone to catastrophic failure and misconfiguration than IPsec. It is important to stress, however, that the layering of IPsec is correct and sound ; everything is in the right place with IPsec, to academic perfection.

But, as often happens with correctness of abstraction, there is a profound lack of usability, and a verifiably safe implementation is very difficult to achieve. WireGuard, in contrast, starts from the basis of flawed layering violations and then attempts to rectify the issues arising from this conflation using practical engineering solutions and cryptographic techniques that solve real world problems. On the other end of the spectrum is OpenVPN, a user space TUN/TAP based solution that uses TLS.

By virtue of it being in user space, it has very poor performance—since packets must be copied multiple times between kernel space and user space—and a long-lived daemon is required; OpenVPN appears far from stateless to an administrator. While TUN/TAP interfaces (say, tun0 ) have similar wg0 -like benefits as described above, OpenVPN is also enormously complex, supporting the entire plethora of TLS functionality, which exposes quite a bit of code to potential vulnerabilities.

OpenVPN is right to be implemented in user space, since ASN.1 and x509 parsers in the kernel have historically been quite problematic (CVE-2008-1673, CVE-2016-2053), and adding a TLS stack would only make that issue worse. TLS also brings with it an enormous state machine, as well as a less clear association between source IP addresses and public keys. For key distribution, WireGuard draws inspiration from OpenSSH, for which common uses include a very simple approach toward key management. Through a diverse set of out-of-band mechanisms, two peers generally exchange their static public keys.

Sometimes it is simple as PGP-signed email, and other times it is a complicated key distribution mechanism using LDAP and certificate authorities. Importantly, for the most part OpenSSH key distribution is entirely agnostic. WireGuard follows suit. Two WireGuard peers exchange their public keys through some unspecified mechanism, and afterward they are able to communicate. In other words, WireGuard’s attitude toward key distribution is that this is the wrong layer to address that particular problem, and so the interface is simple enough that any key distribution solution can be used with it.

As an additional advantage, public keys are only 32 bytes long and can be easily represented in Base64 encoding in 44 characters, which is useful for transferring keys through a variety of different mediums. Finally, WireGuard is cryptographically opinionated. It intentionally lacks cipher and protocol agility. If holes are found in the underlying primitives, all endpoints will be required to update. As shown by the continuing torrent of SSL/TLS vulnerabilities, cipher agility increases complexity monumentally.

WireGuard uses a variant of Trevor Perrin’s Noise [ 23 ]—which during its development received quite a bit of input from the authors of this paper for the purposes of being used in WireGuard—for a 1-RTT key exchange, with Curve25519 [ 5 ] for ECDH, HKDF [ 15 ] for expansion of ECDH results, RFC7539 [ 17 construction of ChaCha20 [ 3 ] and Poly1305 [ 8 ] for authenticated encryption, and BLAKE2s [ 2 ] for hashing. It has built-in protection against denial of service attacks, using a new crypto-cookie mechanism for IP address attributability.

Similarly opinionated, WireGuard is layer 3-only; as explained below in section 2 , this is the cleanest approach for ensuring authenticity and attributability of the packets. The authors believe that layer 3 is the correct way for bridging multiple IP networks, and the imposition of this onto WireGuard allows for many simplifications, 3

Стр. 3

resulting in a cleaner and more easily implemented protocol. It supports layer 3 for both IPv4 and IPv6, and can encapsulate v4-in-v6 as well as v6-in-v4. WireGuard puts together these principles, focusing on simplicity and an auditable codebase, while still being extremely high-speed and suitable for a modicum of environments. By combining the key exchange and the layer 3 transport encryption into one mechanism and using a virtual interface rather than a transform layer, WireGuard indeed breaks traditional layering principles, in pursuit of a solid engineering solution that is both more practical and more secure.

Along the way, it employs several novel cryptographic and systems solutions to achieve its goals. 2 Cryptokey Routing The fundamental principle of a secure VPN is an association between peers and the IP addresses each is allowed to use as source IPs. In WireGuard, peers are identified strictly by their public key, a 32-byte Curve25519 point. This means that there is a simple association mapping between public keys and a set of allowed IP addresses. Examine the following cryptokey routing table :

Interface Public Key Interface Private Key Listening UDP Port HIgo...8ykw yAnz...fBmk 41414 Configuration 1a Peer Public Key Allowed Source IPs xTIB...p8Dg 10.192.122.3/32 , 10.192.124.0/24 TrMv...WXX0 10.192.122.4/32 , 192.168.0.0/16 gN65...z6EA 10.10.10.230/32 The interface itself has a private key and a UDP port on which it listens (more on that later), followed by a list of peers. Each peer is identified by its public key. Each then has a list of allowed source IPs. When an outgoing packet is being transmitted on a WireGuard interface, wg0 , this table is consulted to determine which public key to use for encryption.

For example, a packet with a destination IP of 10.192.122.4 will be encrypted using the secure session derived from the public key TrMv...WXX0 . Conversely, when wg0 receives an encrypted packet, after decrypting and authenticating it, it will only accept it if its source IP resolves in the table to the public key used in the secure session for decrypting it. For example, if a packet is decrypted from xTIB...qp8D , it will only be allowed if the decrypted packet has a source IP of 10.192.122.3 or in the range of 10.192.124.0 to 10.192.124.255 ; otherwise it is dropped. With this very simple principle, administrators can rely on simple firewall rules.

For example, an incoming packet on interface wg0 with a source IP of 10.10.10.230 may be considered as authentically from the peer with a public key of gN65...Bz6E . More generally, any packets arriving on a WireGuard interface will have a reliably authentic source IP (in addition, of course, to guaranteed perfect forward secrecy of the transport). Do note that this is only possible because WireGuard is strictly layer 3 based. Unlike some common VPN protocols, like L2TP/IPsec, using authenticated identification of peers at a layer 3 level enforces a much cleaner network design.

In the case of a WireGuard peer who wishes to route all traffic through another WireGuard peer, the cryptokey routing table could be configured more simply as: Interface Public Key Interface Private Key Listening UDP Port gN65...z6EA gI6E...fWGE 21841 Configuration 2a Peer Public Key Allowed Source IPs HIgo...8ykw 0.0.0.0/0 Here, the peer authorizes HIgo...f8yk to put packets onto wg0 with any source IP, and all packets that are outgoing on wg0 will be encrypted using the secure session associated with that public key and sent to that peer’s endpoint.

2.1 Endpoints & Roaming Of course, it is important that peers are able to send encrypted WireGuard UDP packets to each other at particular Internet endpoints. Each peer in the cryptokey routing table may optionally pre-specify a known external IP address and UDP port of that peer’s endpoint. The reason it is optional is that if it is not specified 4

Стр. 4