diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/adminregistry.md | 18 | ||||
| -rw-r--r-- | docs/attacksurface.md | 15 | ||||
| -rw-r--r-- | docs/buildrun.md | 6 | ||||
| -rw-r--r-- | docs/enterprise.md | 45 | ||||
| -rw-r--r-- | docs/netquirk.md | 4 |
5 files changed, 56 insertions, 32 deletions
diff --git a/docs/adminregistry.md b/docs/adminregistry.md index f7d04409..4289fb38 100644 --- a/docs/adminregistry.md +++ b/docs/adminregistry.md @@ -13,12 +13,16 @@ users belonging to the Network Configuration Operators builtin group (S-1-5-32-556), with the following limitations for members of that group: - Configurations are stripped of all public, private, and pre-shared keys; - - No version update notifications are delivered; + - No version update popup notifications are shown, and updates are not permitted, though a tab still indicates the availability; - Adding, removing, editing, importing, or exporting configurations is forbidden; and - Quitting the manager is forbidden. However, basic functionality such as starting and stopping tunnels remains intact. +``` +> reg add HKLM\Software\WireGuard /v LimitedOperatorUI /t REG_DWORD /d 1 /f +``` + #### `HKLM\Software\WireGuard\DangerousScriptExecution` When this key is set to `DWORD(1)`, the tunnel service will execute the commands @@ -30,12 +34,6 @@ utmost trepidation. Rather than use `%i`, WireGuard for Windows instead sets the environment variable `WIREGUARD_TUNNEL_NAME` to the name of the tunnel when executing these scripts. -#### `HKLM\Software\WireGuard\MultipleSimultaneousTunnels` - -When this key is set to `DWORD(1)`, the UI may start multiple tunnels at the -same time; otherwise, an existing tunnel is stopped when a new one is started. -Note that it is always possible, regardless of this key, to start multiple -tunnels using `wireguard /installtunnelservice`; this controls only the semantics -of tunnel start requests coming from the UI. If all goes well, this key will be -removed and the logic of whether to stop existing tunnels will be based on -overlapping routes, but for now, this key provides a manual override. +``` +> reg add HKLM\Software\WireGuard /v DangerousScriptExecution /t REG_DWORD /d 1 /f +``` diff --git a/docs/attacksurface.md b/docs/attacksurface.md index 6dca229f..a495ba41 100644 --- a/docs/attacksurface.md +++ b/docs/attacksurface.md @@ -4,22 +4,21 @@ _This is an evolving document, describing currently known attack surface, a few WireGuard for Windows consists of four components: a kernel driver, and three separate interacting userspace parts. -### Wintun +### WireGuardNT -Wintun is a kernel driver. It exposes: +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. - - IOCTLs are added to the NDIS device file, and those IOCTLs are restricted to `SDDL_DEVOBJ_SYS_ALL`. 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. + - 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 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:(A;;GA;;;SY)`. 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. + - A global mutex is used for WireGuardNT interface creation, with the same DACL as the pipe, but first CreatePrivateNamespace is called with a "Local System" SID. - 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..687d2e61 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 @@ -60,8 +60,8 @@ C:\Projects\wireguard-windows\installer> build Add a file called `sign.bat` in the root of this repository with these contents, or similar: ```text -set SigningCertificate=DF98E075A012ED8C86FBCF14854B8F9555CB3D45 -set TimestampServer=http://timestamp.digicert.com +set SigningProvider=/sha1 8BC932FDFF15B892E8364C49B383210810E4709D +set TimestampServer=http://timestamp.entrust.net/rfc3161ts2 ``` After, run the above `build` commands as usual, from a shell that has [`signtool.exe`](https://docs.microsoft.com/en-us/windows/desktop/SecCrypto/signtool) in its `PATH`, such as the Visual Studio 2017 command prompt. diff --git a/docs/enterprise.md b/docs/enterprise.md index 3f75ad14..8430cc99 100644 --- a/docs/enterprise.md +++ b/docs/enterprise.md @@ -8,7 +8,7 @@ While consumer users are generally directed toward [wireguard-installer.exe](htt ### Tunnel Service versus Manager Service and UI -The "manager service" is responsible for displaying a UI on select users' desktops (in the system tray), and responding to requests from the UI to do things like add, remove, start, or stop tunnels. The "tunnel service" is a separate Windows service for each tunnel. These two services may be used together, or separately, as described below. +The "manager service" is responsible for displaying a UI on select users' desktops (in the system tray), and responding to requests from the UI to do things like add, remove, start, or stop tunnels. The "tunnel service" is a separate Windows service for each tunnel. These two services may be used together, or separately, as described below. The various commands below will log errors and status to standard error, or, if standard error does not exist, to standard output. ### Tunnel Service @@ -58,15 +58,24 @@ The manager service monitors `%ProgramFiles%\WireGuard\Data\Configurations\` for The UI is started in the system tray of all builtin Administrators when the manager service is running. A limited UI may also be started in the system tray of all builtin Network Configuration Operators, if the correct registry key is set. [See `adminregistry.md` for information.](adminregistry.md) -By default, the manager stops existing tunnels when starting new tunnels, so that only one tunnel service is running at a time. This behavior may be disabled if the correct registry key is set. [See `adminregistry.md` for information.](adminregistry.md) +### Diagnostic Logs +The manager and all tunnel services produce diagnostic logs in a shared ringbuffer-based log. This is shown in the UI, and also can be dumped to standard out using the command: -### Diagnostic Logs +```text +> wireguard /dumplog > C:\path\to\diagnostic\log.txt +``` + +Alternatively, the log can be tailed continuously, for passing it to logging services: -The manager and all tunnel services produce diagnostic logs in a shared ringbuffer-based log. This is shown in the UI, and also can be dumped to a file using the command: +```text +> wireguard /dumplog /tail | log-ingest +``` + +Or it can be monitored in PowerShell by piping to `select`: ```text -> wireguard /dumplog C:\path\to\diagnostic\log.txt +PS> wireguard /dumplog /tail | select ``` ### Updates @@ -74,13 +83,31 @@ The manager and all tunnel services produce diagnostic logs in a shared ringbuff Administrators are notified of updates within the UI and can update from within the UI, but updates can also be invoked at the command line using the command: ```text -> wireguard /update C:\path\to\update\log.txt +> wireguard /update +``` + +Or, to log the status of that command: + +```text +> wireguard /update 2> C:\path\to\update\log.txt +``` + +One could have Task Scheduler run it daily at 3am: + +```text +> schtasks /create /f /ru SYSTEM /sc daily /tn "WireGuard Update" /tr "%PROGRAMFILES%\WireGuard\wireguard.exe /update" /st 03:00 ``` -### Wintun Adapters +### Driver Removal + +The tunnel service creates a network adapter at startup and destroys it at shutdown. If there are no more network adapters, the driver may be removed with: + +```text +> wireguard /removedriver +``` -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: +Or, to log the status of that command: ```text -> wireguard /removealladapters C:\path\to\removal\log.txt +> wireguard /removedriver 2> C:\path\to\removal\log.txt ``` diff --git a/docs/netquirk.md b/docs/netquirk.md index 1fe2ad72..d53c8cdb 100644 --- a/docs/netquirk.md +++ b/docs/netquirk.md @@ -4,7 +4,7 @@ As part of setting up a WireGuard tunnel, the tunnel service also sets up variou ### Routing -The tunnel service takes all the allowed IPs from each peer, deduplicates them, and adds them to the routes for the WireGuard interface. The service then monitors which interface on the system has a default route (a route with a `/0` CIDR) that is not the WireGuard interface itself, and it uses the [`IP_UNICAST_IF` socket option](https://docs.microsoft.com/en-us/windows/win32/winsock/ipproto-ip-socket-options) to bind WireGuard's UDP packets to that default route interface. If no MTU has been specified in the configuration, it also sets the MTU of the WireGuard interface to be 80 less than the MTU of that default route interface. If no default route interface can be found, then those outgoing packets are blackholed. If WireGuard packets would ordinarily be routed over a non-default route interface, the use of `IP_UNICAST_IF` forces the packets to, in fact, go over the default route interface. This is problematic, but at this moment, Microsoft has not provided a viable workaround. If any allowed IPs are a `/0`, then the interface is given a `0` metric and Windows' [automatic metric logic](https://docs.microsoft.com/en-us/troubleshoot/windows-server/networking/automatic-metric-for-ipv4-routes) is disabled. +The tunnel service takes all the allowed IPs from each peer, deduplicates them, and adds them to the routes for the WireGuard interface. The service then monitors which interface on the system has a default route (a route with a `/0` CIDR) that is not the WireGuard interface itself, and, if no MTU has been specified in the configuration, it sets the MTU of the WireGuard interface to be 80 less than the MTU of that default route interface. WireGuardNT also monitors the routing table and determines the outgoing route that does not loopback to itself, and then sends each packet using `IP_PKTINFO`/`IPV6_PKTINFO`. It keeps track of the incoming interface and source address for received packets, and always replies to the sender in that way. ### Firewall Considerations for `/0` Allowed IPs @@ -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 the configuration file or by way of automatic NDIS layer binding. |