driver: introduce new module for talking with kernel driver

Signed-off-by: Jason A. Donenfeld <Jason@zx2c4.com>

5 files changed, 31 insertions, 9 deletions

diff --git a/docs/adminregistry.md b/docs/adminregistry.md
index 9196a93f..34033446 100644
--- a/docs/adminregistry.md
+++ b/docs/adminregistry.md
@@ -51,3 +51,15 @@ overlapping routes, but for now, this key provides a manual override.
 ```
 > reg add HKLM\Software\WireGuard /v MultipleSimultaneousTunnels /t REG_DWORD /d 1 /f
 ```
+
+#### `HKLM\Software\WireGuard\ExperimentalKernelDriver`
+
+When this key is set to `DWORD(1)`, an experimental kernel driver from the
+[WireGuardNT](https://git.zx2c4.com/wireguard-nt/about/) project is used instead
+of the much slower wireguard-go/Wintun implementation. There are significant
+performance gains, but do note that this is _currently_ considered experimental,
+and hence is not recommended.
+
+```
+> reg add HKLM\Software\WireGuard /v ExperimentalKernelDriver /t REG_DWORD /d 1 /f
+```
diff --git a/docs/attacksurface.md b/docs/attacksurface.md
index 1700c1f2..53bcd7c6 100644
--- a/docs/attacksurface.md
+++ b/docs/attacksurface.md
@@ -12,14 +12,24 @@ Wintun is a kernel driver. It exposes:
   - There are also various ndis OID calls, accessible to certain users, which hit further code.
   - IOCTLs are added to the NDIS device file, and those IOCTLs are restricted to `O:SYD:P(A;;FA;;;SY)(A;;FA;;;BA)S:(ML;;NWNRNX;;;HI)`. The IOCTL allows userspace to register a pair of rings and event objects, which Wintun then locks the pages of with a double mapping and takes a reference to the event object. It parses the contents of the ring to send and receive layer 3 packets, each of which it minimally parses to determine IP family.
 
+### WireGuardNT
+
+WireGuardNT is a kernel driver. It exposes:
+
+  - A miniport driver to the ndis stack, meaning any process on the system that can access the network stack in a reasonable way can send and receive packets, hitting those related ndis handlers.
+  - A UDP port parsing WireGuard packets.
+  - There are also various ndis OID calls, accessible to certain users, which hit further code.
+  - A PNP and Close notifier added to the NDIS device file.
+  - IOCTLs are added to the NDIS device file, and those IOCTLs are restricted to `O:SYD:P(A;;FA;;;SY)(A;;FA;;;BA)S:(ML;;NWNRNX;;;HI)`. The IOCTL allows userspace to get and set configuration, adapter state, and read log messages from a ring buffer.
+
 ### Tunnel Service
 
-The tunnel service is a userspace service running as Local System, responsible for creating UDP sockets, creating Wintun adapters, and speaking the WireGuard protocol between the two. It exposes:
+The tunnel service is a userspace service running as Local System, responsible for either A) creating UDP sockets, creating Wintun adapters, and speaking the WireGuard protocol between the two, or B) creating WireGuardNT adapters and configuring them. It exposes:
 
-  - A listening pipe in `\\.\pipe\ProtectedPrefix\Administrators\WireGuard\%s`, where `%s` is some basename of an already valid filename. Its DACL is set to `O:SYD:P(A;;GA;;;SY)(A;;GA;;;BA)S:(ML;;NWNRNX;;;HI)`. If the config file used by the tunnel service is not DPAPI-encrypted and it is owned by a SID other than "Local System" then an additional ACE is added giving that file owner SID access to the named pipe. This pipe gives access to private keys and allows for reconfiguration of the interface, as well as rebinding to different ports (below 1024, even). Clients who connect to the pipe run `GetSecurityInfo` to verify that it is owned by "Local System".
-  - A global mutex is used for Wintun interface creation, with the same DACL as the pipe, but first CreatePrivateNamespace is called with a "Local System" SID.
-  - It handles data from its two UDP sockets, accessible to the public Internet.
-  - It handles data from Wintun, accessible to all users who can do anything with the network stack.
+  - In case A) a listening pipe in `\\.\pipe\ProtectedPrefix\Administrators\WireGuard\%s`, where `%s` is some basename of an already valid filename. Its DACL is set to `O:SYD:P(A;;GA;;;SY)(A;;GA;;;BA)S:(ML;;NWNRNX;;;HI)`. If the config file used by the tunnel service is not DPAPI-encrypted and it is owned by a SID other than "Local System" then an additional ACE is added giving that file owner SID access to the named pipe. This pipe gives access to private keys and allows for reconfiguration of the interface, as well as rebinding to different ports (below 1024, even). Clients who connect to the pipe run `GetSecurityInfo` to verify that it is owned by "Local System".
+  - A global mutex is used for Wintun/WireGuardNT interface creation, with the same DACL as the pipe, but first CreatePrivateNamespace is called with a "Local System" SID.
+  - In case A) it handles data from its two UDP sockets, accessible to the public Internet.
+  - In case A) it handles data from Wintun, accessible to all users who can do anything with the network stack.
   - After some initial setup, it uses `AdjustTokenPrivileges` to remove all privileges, except for `SeLoadDriverPrivilege`, so that it can remove the interface when shutting down. This latter point is rather unfortunate, as `SeLoadDriverPrivilege` can be used for all sorts of interesting escalation. Future work includes forking an additional process or the like so that we can drop this from the main tunnel process.
 
 ### Manager Service
diff --git a/docs/buildrun.md b/docs/buildrun.md
index 265c4d68..209c57ac 100644
--- a/docs/buildrun.md
+++ b/docs/buildrun.md
@@ -18,7 +18,7 @@ After you've built the application, run `amd64\wireguard.exe` or `x86\wireguard.
 C:\Projects\wireguard-windows> amd64\wireguard.exe
 ```
 
-Since WireGuard requires the Wintun driver to be installed, and this generally requires a valid Microsoft signature, you may benefit from first installing a release of WireGuard for Windows from the official [wireguard.com](https://www.wireguard.com/install/) builds, which bundles a Microsoft-signed Wintun, and then subsequently run your own wireguard.exe. Alternatively, you can craft your own installer using the `quickinstall.bat` script.
+Since WireGuard requires a driver to be installed, and this generally requires a valid Microsoft signature, you may benefit from first installing a release of WireGuard for Windows from the official [wireguard.com](https://www.wireguard.com/install/) builds, which bundles a Microsoft-signed driver, and then subsequently run your own wireguard.exe. Alternatively, you can craft your own installer using the `quickinstall.bat` script.
 
 ### Optional: Localizing
 
diff --git a/docs/enterprise.md b/docs/enterprise.md
index 37a0ca44..8e4ca59e 100644
--- a/docs/enterprise.md
+++ b/docs/enterprise.md
@@ -83,9 +83,9 @@ Or, to log the status of that command:
 > wireguard /update 2> C:\path\to\update\log.txt
 ```
 
-### Wintun Adapters
+### Network Adapters
 
-The tunnel service creates a Wintun adapter at startup and destroys it at shutdown. It may be desirable, however, to remove all Wintun adapters created in WireGuard's pool and uninstall the driver if no other applications are using Wintun. This can be accomplished using the command:
+The tunnel service creates a network adapter at startup and destroys it at shutdown. It may be desirable, however, to remove all network adapters created in WireGuard's pool and uninstall the driver if no other applications are using our network adapters. This can be accomplished using the command:
 
 ```text
 > wireguard /removealladapters
diff --git a/docs/netquirk.md b/docs/netquirk.md
index 1fe2ad72..c0aa7bf3 100644
--- a/docs/netquirk.md
+++ b/docs/netquirk.md
@@ -30,4 +30,4 @@ Windows assigns a unique GUID to each new WireGuard adapter. The application tak
 
 ### Adapter Lifetime
 
-WireGuard's Wintun adapter is created dynamically when a tunnel is started and destroyed when a tunnel is stopped. This means that additional filters, address families, or protocols should be bound to the adapter programmatically, possibly through use of dangerous script execution in thet configuration file or by way of automatic NDIS layer binding.
+WireGuard's network adapter is created dynamically when a tunnel is started and destroyed when a tunnel is stopped. This means that additional filters, address families, or protocols should be bound to the adapter programmatically, possibly through use of dangerous script execution in thet configuration file or by way of automatic NDIS layer binding.