msi-example: add instructions and sample code

README.md

@@ -156,7 +156,7 @@ Wintun will abort reading the receive ring on invalid `Head` or `Tail` or on a b
 
 ## Building
 
-**Do not distribute drivers named "Wintun", as they will most certainly clash with official deployments. Instead distribute [the signed MSMs from Wintun.net](https://www.wintun.net/).**
+**Do not distribute drivers named "Wintun", as they will most certainly clash with official deployments. Instead distribute [the signed MSMs from Wintun.net](https://www.wintun.net/).** If you are unable to use MSMs, [consult the MSI creation instructions](msi-example/README.md).
 
 General requirements:
 

msi-example/README.md

@@ -0,0 +1,38 @@
+## Example Standalone MSI
+
+The best way to include Wintun in your software is by including the MSMs in your final MSI,
+as described by [the main README](../README.md). However, if you're stuck with an installation
+system such as NSIS, which can not bundle MSM files, then you must build your own MSI, which
+NSIS can then invoke. ***Do not use an MSI from elsewhere. You must build it yourself and
+distribute only the MSI that you yourself build.*** Otherwise different projects will wind up
+uninstalling each other by accident and disturbing the MSM reference counting. The steps in
+this file should only be taken if you're not able to include an MSM into a MSI, something that
+is easily possible using WiX or most commercial installation solutions.
+
+This `msi-example` folder contains a WiX skeleton and a build script that handles all
+dependencies. use it as follows below.
+
+#### Steps:
+
+1. Generate a UUID using uuidgen.exe and replace `{{{FIXED 64BIT UUID}}}` in exampletun.wxs
+with that UUID. For the life time of your entire product, even across versions, do not change
+that UUID.
+
+2. Generate another UUID using uuidgen.exe and replace `{{{FIXED 32BIT UUID}}}` in
+exampletun.wxs with that UUID. For the life time of your entire product, even across versions,
+do not change that UUID.
+
+3. Go to [Wintun.net](https://www.wintun.net/) and look at what the latest version is (`0.6`,
+for example). Replace `{{{VERSION}}}` in build.bat with that version.
+
+4. Download the amd64 MSM from [Wintun.net](https://www.wintun.net/) and compute its SHA2-256
+sum in all lowercase hex digits using `CertUtil -hashfile "path/to/file" SHA256`, and replace
+`{{{64BIT HASH}}}` in build.bat with that value.
+
+5. Download the x86 MSM from [Wintun.net](https://www.wintun.net/) and compute its SHA2-256
+sum in all lowercase hex digits using `CertUtil -hashfile "path/to/file" SHA256`, and replace
+`{{{32BIT HASH}}}` in build.bat with that value.
+
+6. Run build.bat.
+
+7. Distribute dist\exampletun-*.msi for your own software only.

msi-example/build.bat

@@ -0,0 +1,60 @@
+@echo off
+rem SPDX-License-Identifier: GPL-2.0
+rem Copyright (C) 2019 WireGuard LLC. All Rights Reserved.
+
+setlocal
+set PATHEXT=.exe
+set BUILDDIR=%~dp0
+cd /d %BUILDDIR% || exit /b 1
+
+set WIX_CANDLE_FLAGS=-nologo
+set WIX_LIGHT_FLAGS=-nologo -spdb -sice:ICE71 -sice:ICE61
+
+if exist .deps\prepared goto :build
+:installdeps
+	rmdir /s /q .deps 2> NUL
+	mkdir .deps || goto :error
+	cd .deps || goto :error
+	call :download wintun-x86.msm https://www.wintun.net/builds/wintun-x86-{{{VERSION}}}.msm {{{32BIT HASH}}} || goto :error
+	call :download wintun-amd64.msm https://www.wintun.net/builds/wintun-amd64-{{{VERSION}}}.msm {{{64BIT HASH}}} || goto :error
+	call :download wix-binaries.zip http://wixtoolset.org/downloads/v3.14.0.2812/wix314-binaries.zip 923892298f37514622c58cbbd9c2cadf2822d9bb53df8ee83aaeb05280777611 || goto :error
+	echo [+] Extracting wix-binaries.zip
+	mkdir wix\bin || goto :error
+	tar -xf wix-binaries.zip -C wix\bin || goto :error
+	echo [+] Cleaning up wix-binaries.zip
+	del wix-binaries.zip || goto :error
+	copy /y NUL prepared > NUL || goto :error
+	cd .. || goto :error
+
+:build
+	set WIX=%BUILDDIR%.deps\wix\
+	call :msi x86 i686 x86 || goto :error
+	call :msi amd64 x86_64 x64 || goto :error
+	if exist ..\sign.bat call ..\sign.bat
+	if "%SigningCertificate%"=="" goto :success
+	if "%TimestampServer%"=="" goto :success
+	echo [+] Signing
+	signtool sign /sha1 "%SigningCertificate%" /fd sha256 /tr "%TimestampServer%" /td sha256 /d "ExampleTun Setup" "dist\exampletun-*.msi" || goto :error
+
+:success
+	echo [+] Success.
+	exit /b 0
+
+:download
+	echo [+] Downloading %1
+	curl -#fLo %1 %2 || exit /b 1
+	echo [+] Verifying %1
+	for /f %%a in ('CertUtil -hashfile %1 SHA256 ^| findstr /r "^[0-9a-f]*$"') do if not "%%a"=="%~3" exit /b 1
+	goto :eof
+
+:msi
+	if not exist "%~1" mkdir "%~1"
+	echo [+] Compiling %1
+	"%WIX%bin\candle" %WIX_CANDLE_FLAGS% -dEXAMPLETUN_PLATFORM="%~1" -out "%~1\exampletun.wixobj" -arch %3 exampletun.wxs || exit /b %errorlevel%
+	echo [+] Linking %1
+	"%WIX%bin\light" %WIX_LIGHT_FLAGS% -out "dist\exampletun-%~1.msi" "%~1\exampletun.wixobj" || exit /b %errorlevel%
+	goto :eof
+
+:error
+	echo [-] Failed with error #%errorlevel%.
+	cmd /c exit %errorlevel%

msi-example/exampletun.wxs

@@ -0,0 +1,54 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+	SPDX-License-Identifier: GPL-2.0
+
+	Copyright (C) 2019 WireGuard LLC. All Rights Reserved.
+-->
+<?if $(var.EXAMPLETUN_PLATFORM) = "amd64"?>
+	<?define UpgradeCode = "{{{FIXED 64BIT UUID}}}"?>
+<?elseif $(var.EXAMPLETUN_PLATFORM) = "x86"?>
+	<?define UpgradeCode = "{{{FIXED 32BIT UUID}}}"?>
+<?else?>
+	<?error Unknown platform ?>
+<?endif?>
+
+
+<Wix xmlns="http://schemas.microsoft.com/wix/2006/wi">
+	<Product
+		Id="*"
+		Name="ExampleTun"
+		Language="1033"
+		Version="1.0"
+		Manufacturer="Acme Widgets Corporation"
+		UpgradeCode="$(var.UpgradeCode)">
+		<Package
+			InstallerVersion="400"
+			Compressed="yes"
+			InstallScope="perMachine"
+			Description="ExampleTun: Acme Widget's Distribution of Wintun"
+			ReadOnly="yes" />
+
+		<MediaTemplate EmbedCab="yes" CompressionLevel="high" />
+
+		<Property Id="ARPNOMODIFY" Value="yes" />
+		<Property Id="ARPSYSTEMCOMPONENT" Value="1" />
+		<Property Id="DISABLEADVTSHORTCUTS" Value="yes" />
+		<Property Id="DISABLEROLLBACK" Value="yes" />
+		<Property Id="MSIDISABLERMRESTART" Value="1" />
+		<Property Id="MSIRMSHUTDOWN" Value="1" />
+
+		<MajorUpgrade
+			AllowDowngrades="no"
+			AllowSameVersionUpgrades="yes"
+			DowngradeErrorMessage="A newer version of [ProductName] is already installed."
+			Schedule="afterInstallExecute" />
+
+		<Directory Id="TARGETDIR" Name="SourceDir">
+			<Merge Id="WintunMergeModule" Language="0" DiskId="1" SourceFile=".deps\wintun-$(var.EXAMPLETUN_PLATFORM).msm" />
+		</Directory>
+
+		<Feature Id="WintunFeature" Title="Wintun" Level="1">
+			<MergeRef Id="WintunMergeModule" />
+		</Feature>
+	</Product>
+</Wix>