From 366aaf28203cc8dca8963c887ee0e64a39718434 Mon Sep 17 00:00:00 2001 From: "Jason A. Donenfeld" Date: Thu, 1 Aug 2019 17:42:54 +0200 Subject: Rearrange README and add additional MSM info Signed-off-by: Jason A. Donenfeld --- README.md | 163 ++++++++++++++++++++++++++++++++++---------------------------- 1 file changed, 90 insertions(+), 73 deletions(-) (limited to 'README.md') diff --git a/README.md b/README.md index 7b06464..299237f 100644 --- a/README.md +++ b/README.md @@ -3,87 +3,24 @@ This is a layer 3 TUN driver for Windows 7, 8, 8.1, and 10. Originally created for [WireGuard](https://www.wireguard.com/), it is intended to be useful to a wide variety of projects that require layer 3 tunneling devices with implementations primarily in userspace. -## Build Requirements +## Installation -- [Visual Studio 2019](https://visualstudio.microsoft.com/downloads/) -- [Windows Driver Kit for Windows 10, version 1903](https://docs.microsoft.com/en-us/windows-hardware/drivers/download-the-wdk) -- [WiX Toolset 3.11.1](http://wixtoolset.org/releases/) - - -## Digital Signing - -Digital signing is an integral part of the build process. By default, the driver will be test-signed using a certificate that the WDK should automatically generate. To subsequently load the driver, you will need to put your computer into test mode by executing as Administrator `bcdedit /set testsigning on`. - -If you possess an EV certificate for kernel mode code signing you should switch TUN driver digital signing from test-signing to production-signing by authoring your `wintun.vcxproj.user` file to look something like this: +The following snippet may be used inside of a WiX `` element for including Wintun inside of a Windows Installer. Note that **MSI is the only supported method of installing Wintun**; if you're using a different install system (such as NSIS) and cannot bother to switch to MSI/WiX, then simply bundle an embedded MSI that you can execute with `msiexec.exe`. ```xml - - - - ProductionSign - $(WDKContentRoot)CrossCertificates\DigiCert_High_Assurance_EV_Root_CA.crt - DF98E075A012ED8C86FBCF14854B8F9555CB3D45 - http://timestamp.digicert.com - - + + + + + + ``` -Modify the `` to contain the full path to the cross-signing certificate of CA that issued your certificate. You should be able to find its `.crt` file in `C:\Program Files (x86)\Windows Kits\10\CrossCertificates`. Note that the `$(WDKContentRoot)` expands to `C:\Program Files (x86)\Windows Kits\10\`. - -If you already have `wintun.vcxproj.user` file, just add the `` section. - - -## Building from Command Line - -Open _Developer Command Prompt for VS 2019_ and use the `msbuild` command: - -``` -msbuild wintun.proj [/t:] -``` - -### Targets - - - `Build`: Builds the driver release configurations of all supported platforms. This is the default target. - - - `Clean`: Deletes all intermediate and output files. - - - `Rebuild`: Alias for `Clean` followed by `Build`. - - - `SDV`: Runs Static Driver Verifier, which includes a clean driver build, only for AMD64 release configuration. - - - `SDVView`: Views the results of the Static Driver Verifier. - - - `DVL`: Runs the `SDV`, and creates a Driver Verification Log, only for AMD64 release configurations. - - - `MSM`: Builds Microsoft Installer Merge Modules in `\wintun--.msm`. Requires WHQL signed driver. - -The driver output folders are: - -Platform and Configuration | Folder --------------------------- | -------------------- -x86 Debug | `x86\Debug\wintun` -x86 Release | `x86\Release\wintun` -AMD64 Debug | `amd64\Debug\wintun` -AMD64 Release | `amd64\Release\wintun` -ARM64 Debug | `arm64\Debug\wintun` -ARM64 Release | `arm64\Release\wintun` - -Do note that since the `Build` target builds for all supported platforms, you will need to have the toolchains installed for those platforms. - -#### Building Microsoft Installer Merge Modules - -1. `msbuild wintun.proj /t:DVL;Build`. -2. Perform Windows Hardware Lab Kit tests. -3. Submit submission package to Microsoft. -4. Copy WHQL-signed driver to `x86\Release\whql\` and `amd64\Release\whql\` subfolders. -5. `msbuild wintun.proj /t:MSM` -6. MSM files are placed in `dist` subfolder. - -Note: due to the use of SHA256 signatures throughout, Windows 7 users who would like a prompt-less installation generally need to have the [KB2921916 hotfix](https://support.microsoft.com/en-us/help/2921916/the-untrusted-publisher-dialog-box-appears-when-you-install-a-driver-i) installed, which can be obtained from these mirrors: [amd64](https://download.wireguard.com/windows-toolchain/distfiles/Windows6.1-KB2921916-x64.msu) and [x86](https://download.wireguard.com/windows-toolchain/distfiles/Windows6.1-KB2921916-x86.msu). +It is advisable to use the prebuilt and Microsoft-signed MSM files from [Wintun.net](https://www.wintun.net/). ## Usage -After loading the driver and creating a network interface the typical way using [SetupAPI](https://docs.microsoft.com/en-us/windows-hardware/drivers/install/setupapi), open the NDIS device object associated with the PnPInstanceId. +After loading the driver and creating a network interface the typical way using [SetupAPI](https://docs.microsoft.com/en-us/windows-hardware/drivers/install/setupapi), open the NDIS device object associated with the PnPInstanceId, enabling all forms of file sharing. ### Ring layout @@ -191,3 +128,83 @@ for (;;) { ``` Wintun will abort reading the receive ring on invalid `Head` or `Tail` or on a bogus packet. In this case, Wintun will set the `Head` to 0xFFFFFFFF. In order to restart it, reopen the handle and call `TUN_IOCTL_REGISTER_RINGS` again. However, it should be entirely possible to avoid feeding Wintun bogus packets and invalid offsets. + +## Building + +General requirements: + +- [Visual Studio 2019](https://visualstudio.microsoft.com/downloads/) +- [Windows Driver Kit for Windows 10, version 1903](https://docs.microsoft.com/en-us/windows-hardware/drivers/download-the-wdk) +- [WiX Toolset 3.11.1](http://wixtoolset.org/releases/) + +`wintun.sln` may be opened in Visual Studio for development and building. Or the below instructions can be followed for command line builds. + +### Building from Command Line + +Open _Developer Command Prompt for VS 2019_ and use the `msbuild` command: + +``` +msbuild wintun.proj [/t:] +``` + +#### Targets + + - `Build`: Builds the driver release configurations of all supported platforms. This is the default target. + + - `Clean`: Deletes all intermediate and output files. + + - `Rebuild`: Alias for `Clean` followed by `Build`. + + - `SDV`: Runs Static Driver Verifier, which includes a clean driver build, only for AMD64 release configuration. + + - `SDVView`: Views the results of the Static Driver Verifier. + + - `DVL`: Runs the `SDV`, and creates a Driver Verification Log, only for AMD64 release configurations. + + - `MSM`: Builds Microsoft Installer Merge Modules in `\wintun--.msm`. Requires WHQL signed driver. + +The driver output folders are: + +Platform and Configuration | Folder +-------------------------- | -------------------- +x86 Debug | `x86\Debug\wintun` +x86 Release | `x86\Release\wintun` +AMD64 Debug | `amd64\Debug\wintun` +AMD64 Release | `amd64\Release\wintun` +ARM64 Debug | `arm64\Debug\wintun` +ARM64 Release | `arm64\Release\wintun` + +Do note that since the `Build` target builds for all supported platforms, you will need to have the toolchains installed for those platforms. + +### Building Microsoft Installer Merge Modules + +1. `msbuild wintun.proj /t:DVL;Build`. +2. Perform Windows Hardware Lab Kit tests. +3. Submit submission package to Microsoft. +4. Copy WHQL-signed driver to `x86\Release\whql\` and `amd64\Release\whql\` subfolders. +5. `msbuild wintun.proj /t:MSM` +6. MSM files are placed in `dist` subfolder. + +Note: due to the use of SHA256 signatures throughout, Windows 7 users who would like a prompt-less installation generally need to have the [KB2921916 hotfix](https://support.microsoft.com/en-us/help/2921916/the-untrusted-publisher-dialog-box-appears-when-you-install-a-driver-i) installed, which can be obtained from these mirrors: [amd64](https://download.wireguard.com/windows-toolchain/distfiles/Windows6.1-KB2921916-x64.msu) and [x86](https://download.wireguard.com/windows-toolchain/distfiles/Windows6.1-KB2921916-x86.msu). + +### Digital Signing + +By default, the driver will be test-signed using a certificate that the WDK should automatically generate. To subsequently load the driver, you will need to put your computer into test mode by executing as Administrator `bcdedit /set testsigning on`. + +If you possess an EV certificate for kernel mode code signing you should switch TUN driver digital signing from test-signing to production-signing by authoring your `wintun.vcxproj.user` file to look something like this: + +```xml + + + + ProductionSign + $(WDKContentRoot)CrossCertificates\DigiCert_High_Assurance_EV_Root_CA.crt + DF98E075A012ED8C86FBCF14854B8F9555CB3D45 + http://timestamp.digicert.com + + +``` + +Modify the `` to contain the full path to the cross-signing certificate of CA that issued your certificate. You should be able to find its `.crt` file in `C:\Program Files (x86)\Windows Kits\10\CrossCertificates`. Note that the `$(WDKContentRoot)` expands to `C:\Program Files (x86)\Windows Kits\10\`. + +If you already have `wintun.vcxproj.user` file, just add the `` section. -- cgit v1.2.3-59-g8ed1b