Hesham/wintun
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Rearrange README and add additional MSM info

Browse Source 
Signed-off-by: Jason A. Donenfeld <Jason@zx2c4.com>
This commit is contained in:
Jason A. Donenfeld 2019-08-01 17:42:54 +02:00
parent 47a2a980a8
commit 366aaf2820
1 changed files with 90 additions and 73 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

163
README.md
View File

@ -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. 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/) The following snippet may be used inside of a WiX `<Product>` 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`.
- [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:
```xml ```xml
<?xml version="1.0" encoding="utf-8"?> <DirectoryRef Id="INSTALLFOLDER">
<Project ToolsVersion="15.0" xmlns="http://schemas.microsoft.com/developer/msbuild/2003"> <Merge Id="WintunMergeModule" Language="0" DiskId="1" SourceFile="path\to\wintun-x.y-amd64.msm" />
<PropertyGroup> </DirectoryRef>
<SignMode>ProductionSign</SignMode> <Feature Id="WintunFeature" Title="Wintun" Level="1">
<CrossCertificateFile>$(WDKContentRoot)CrossCertificates\DigiCert_High_Assurance_EV_Root_CA.crt</CrossCertificateFile> <MergeRef Id="WintunMergeModule" />
<ProductionCertificate>DF98E075A012ED8C86FBCF14854B8F9555CB3D45</ProductionCertificate> </Feature>
<TimestampServer>http://timestamp.digicert.com</TimestampServer>
</PropertyGroup>
</Project>
``` ```
Modify the `<CrossCertificateFile>` 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\`. It is advisable to use the prebuilt and Microsoft-signed MSM files from [Wintun.net](https://www.wintun.net/).
If you already have `wintun.vcxproj.user` file, just add the `<PropertyGroup>` section.
## Building from Command Line
Open _Developer Command Prompt for VS 2019_ and use the `msbuild` command:
```
msbuild wintun.proj [/t:<target>]
```
### 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 `<output folder>\wintun-<platform>-<version>.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).
## Usage ## 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 ### 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. 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:<target>]
```
#### 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 `<output folder>\wintun-<platform>-<version>.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
<?xml version="1.0" encoding="utf-8"?>
<Project ToolsVersion="15.0" xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
<PropertyGroup>
<SignMode>ProductionSign</SignMode>
<CrossCertificateFile>$(WDKContentRoot)CrossCertificates\DigiCert_High_Assurance_EV_Root_CA.crt</CrossCertificateFile>
<ProductionCertificate>DF98E075A012ED8C86FBCF14854B8F9555CB3D45</ProductionCertificate>
<TimestampServer>http://timestamp.digicert.com</TimestampServer>
</PropertyGroup>
</Project>
```
Modify the `<CrossCertificateFile>` 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 `<PropertyGroup>` section.