wiki:BuildingTapWindows6

Version 22 (modified by Samuli Seppänen, 7 years ago) (diff)

--

Introduction

Generic build instructions for tap-windows6 are available in it's Git repo. This page contains additional information that is more generic and not really suitable for inclusion in the main documentation.

Codesigning requirements

Getting the Authenticode signatures right so that all Windows versions detect them can be quite tricky. This seems to be particularly true for kernel-mode driver packages. In practice tap-windows6 driver needs two signatures:

  1. Primary signature created with a normal (non-EV) SHA1 code-signing certificate. This is required by Windows Vista, which does not seem to understand SHA2 signatures at all, and which can apparently only handle one signature. Very outdated Windows 7 installations may have similar issues.
  2. Secondary signature created with an Extended Validation (EV) SHA2 code-signing certificate. An EV certificate is required on Windows 10 for kernel drivers.

There are two additional requirements for both of these signatures:

  1. The Certificate path needs to be complete. This can be achieved by including cross-certificate of your CA (e.g. Digicert) in the signed files. At least for Digicert non-EV and EV code-signing certificates have different CAs.
  2. The signature needs to be timestamped, or the driver will stop functioning when the code-signing certificate expires.

It is not clear if signtool's digest algorithm (/fd SHA|SHA256) affects the validity of the signature, or if the only important thing is the hash algorithm of the actual certificate. When the cross-certificates expires (in 5-15 years), an actual Microsoft signature is required in all drivers. This means that all drivers need to be submitted to Microsoft for signing (see links below for more information).

Due to the above, the build environment for tap-windows6 needs to be setup just right:

  • Build computer should have WinDDK 7600.* installed, because currently buildtap.py does not work on anything newer. Build computer should have a SHA1 code-signing certificate in the certificate store under Currentuser\My
  • Code-signing computer should have Windows Kit 10 installed: this kit includes a version of Signtool.exe which supports appending signatures to files. The SHA2 EV code-signing certificate needs to be visible in the certificate store under Currentuser\My.

Signing process

The actual build/signing procedure is rather convoluted.

On build computer

Copy your kernel-mode SHA1 code-signing certificate and the intermediate cross-signing certificate to the tap-windows6 directory.

Run buildtap.py to build and to sign with SHA1

$ python buildtap.py -b --sign <certificate-options>

NOTE: using the "-c" switch will wipe out any pre-built tapinstall.exe's in the tapinstall directory, so be careful with it.

Copy the following files to the code-signing computer:

  • tap6.tar.gz
  • 32-bit tapinstall.exe (renamed to tapinstall32.exe)
  • 64-bit tapinstall.exe (renamed to tapinstall64.exe)

On code-signing computer

Clone the Sign-Tap6 repository. Ensure your SHA2 EV code-signing certificate is visible in the Windows certificate store, and copy the matching cross-certificate to the sign-tap6 directory.

Copy tap6.tar.gz to the sign-tap6 directory and extract it:

$ tar -zxf tap6.tar.gz

Move tapinstall.exe's to the tap6 directory:

$ mv tapinstall32.exe tap6/i386/tapinstall.exe
$ mv tapinstall64.exe tap6/amd64/tapinstall.exe

Next append secondary signatures with Sign-Tap6.ps1. For example:

$ Sign-Tap6.ps1 -SourceDir tap6 -Append

Now wrap the dual-signed files into a tarball (e.g. using Git Bash):

$ tar -zxf tap6-dual-signed.tar.gz tap6

Copy the dual-signed tarball back to the build computer.

On build computer

Extract contents of tap6-dual-signed.tar.gz to the tap-windows6 directory:

$ rm -rf dist tap6
$ tar -zxf tap6-dual-signed.tar.gz
$ mv tap6 dist

Next you will need to run buildtap.py using the same parameters as before, except that you must not clean (-c) or build (-b). You should only package (-p) the dist directory into an installer. If you have a user-mode SHA2 certificate available on the build computer, then it is easiest to sign with that, e.g.

$ python buildtap.py -p --sign --certfile=<my-sha2-certificate> --certpw=<password> --crosscert=<my-cross-cert> --timestamp=http://timestamp.digicert.com --ti=tapinstall

Alternatively copy the installer produced by buildtap.py to the code-signing computer for the additional signature, as described below.

On code-signing computer

Append a signature to the tap-windows-<versio>-<buildnum>.exe using Sign-Tap6.ps1. Make sure you use the EV SHA2 certificate. Right now this process has not been automated, but the command-line is fairly easy to construct manually by looking at Sign-Tap6.ps1.

If this process sounds complicated, that's because it is. At some point would make sense to adapt buildtap.py to add both signatures automatically, which would simplify the process dramatically. However, that would require porting buildtap.py to Windows Kit 10, which would require a non-trivial amount of work.

Useful commands

Installing certificates

Installing a PFX file to the Currentuser certificate store using Powershell:

Import-PfxCertificate –FilePath <path-to-pfx> cert:\CurrentUser\My -Password (ConvertTo-SecureString -String <pfx-password> -Force –AsPlainText)

If you're not accustomed to Powershell you can just use mmc.exe and the certificate snap-ins to install the certificate.

Querying the certificate store

To list all certificates in Currentuser\My store using Powershell:

Get-ChildItem cert:\CurrentUser\My

Or alternatively:

Set-Location cert:\CurrentUser\My
dir

The dir command is just an alias for Get-ChildItem

Creating catalog files with inf2cat

To create a catalog file for a 32-bit driver:

Inf2Cat.exe /driver:<full-path-to-driver-directory> /os:Vista_x86,Server2008_X86,7_X86

To create a catalog file for a 64-bit driver:

Inf2Cat.exe /driver:<full-path-to-driver-directory> /os:Vista_X64,Server2008_X64,Server2008R2_X64,7_X64 

Example:

Inf2Cat.exe /driver:C:\Users\John\tap6\amd64 /os:Vista_X64,Server2008_X64,Server2008R2_X64,7_X64 

NOTE: According to Microsoft Inf2Cat requires a full path to the driver directory.

Signing files with signtool.exe

Sign a file using a (non-EV) certificate stored in a pfx file. Note that this process is not suitable for EV certificates, which are probably all stored in some sort of dongle and thus only visible through the Windows Certificate Store:

signtool.exe sign /v /ac <cross-certificate> /t <timestamp-url> /f <pfx-file> /p <pfx-password> <file>

Sign a driver with the "best" certificate found from the certificate store. This should work if there is only code-signing certificate in the store:

signtool.exe sign /v /ac <cross-certificate> /t <timestamp-url> /a <file>

Sign a driver using a certificate under Currentuser\My, selecting the right certificate based on a substring of the certificate's subjectname:

signtool.exe sign /v /ac <cross-certificate> /t <timestamp-url> /s My /n <subjectname> <file>

Example of adding two signatures and timestamps. This requires a relatively recent signtool.exe (e.g. from Windows Kit 10):

# Create primary (SHA1) signature (certificate in a pfx file)
signtool.exe sign /v /f digicert-sha1.pfx /p <pfx-password> /ac digicert-assured-id.crt /t http://timestamp.digicert.com /fd SHA1 tap6/amd64/tap0901.cat

# Add secondary (SHA2) signature (certificate in the certificate store)
signtool.exe sign /v /s My /n OpenVPN /ac digicert-high-assurance-ev.crt /as /fd SHA256 tap6/amd64/tap0901.cat
signtool.exe timestamp /tr http://timestamp.digicert.com /td SHA256 /tp 1 tap6/amd64/tap0901.cat

Validating signatures

Verifying the Authenticode signature of a file using Powershell:

Get-AuthenticodeSignature <path-to-file>

Note that even if the above command says that the file's certificate is valid, there is absolutely no guarantee that various Windows versions will accept it. It is unclear whether the Cmdlet checks the entire certificate path or not: it does hang for long periods of time occasionally doing something.

Using signtool.exe to verify a driver's signature probably gives more reliable results than the Get-AuthenticodeSignature Cmdlet:

signtool.exe verify /v /kp /c <drivername>.cat <drivername>.sys

Signatures can also be validated by looking at "File properties" of the tap0901.cat file. The publisher should show up correctly in some places (not necessarily all), there should be a timestamp counter-certificate, and an unbroken certification path should be present.

External links

General information

Practical guides

References