Changes between Version 16 and Version 17 of BuildingTapWindows6


Ignore:
Timestamp:
02/03/17 13:48:21 (5 years ago)
Author:
Samuli Seppänen
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • BuildingTapWindows6

    v16 v17  
    33= Introduction =
    44
    5 The build instructions for tap-windows6 [https://github.com/OpenVPN/tap-windows6/blob/master/README.rst 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.
     5Generic build instructions for tap-windows6 [https://github.com/OpenVPN/tap-windows6/blob/master/README.rst 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.
    66
    7 = Codesigning =
    8 
    9 == Basic process ==
     7= Codesigning requirements =
    108
    119Getting the [https://msdn.microsoft.com/en-us/library/windows/hardware/ff686697%28v=vs.85%29.aspx 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:
     
    2624* 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''.
    2725
    28 The actual build procedure is a bit convoluted:
     26= Signing process =
    2927
    30 1. Run ''buildtap.py'' on the build computer, using the SHA1 certificate for signing. Make sure to include the correct cross-certificate and to timestamp the signature. Creating the installer (buildtap.py -p) does not make any sense right here.
    31 1. Copy tap6.tar.gz to the signing computer
    32 1. Unpack tap6.tar.gz on the signing computer
    33 1. Copy pre-built 32-bit and 64-bit tapinstall.exe's to ''tap6/i386'' and ''tap6/amd64'', respectively
    34 1. Append signatures to ''tapinstall.exe'' and ''tap0901.cat'' files. The [https://github.com/mattock/sign-tap6/ Sign-Tap6 tool] is a convenient way to do this. Ensure you're using the correct cross-certificate and that you timestamp the signature.
    35 1. Copy the dual-signed files back to the build computer
    36 1. Copy the contents of the dual-signed tap6 directory to ''dist'' in tap-windows6 build root.
    37 1. Run ''buildtap.py'' again using the same parameters as before, but ensure you do not ''clean'' (-c) or ''build'' (-b). You should only ''package'' (-p) the dist directory into an installer.
    38 1. Copy the resulting ''installer'' to the code-signing computer, and append a signature to it using 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 [https://github.com/mattock/sign-tap6/ Sign-Tap6.ps1].
     28The actual build/signing procedure is rather convoluted.
    3929
    40 If this process sounds complicated, it'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.
     30'''On build computer'''
    4131
    42 == Useful commands ==
     32Run ''buildtap.py'' using the SHA1 certificate for signing. Make sure to include the correct cross-certificate and to timestamp the signature:
    4333
    44 === Installing certificates ===
     34{{{
     35$ python buildtap.py -b <certificate-options>
     36}}}
     37
     38'''NOTE:''' using the "-c" switch will wipe out any pre-built tapinstall.exe's in the ''tapinstall'' directory, so be careful with it.
     39
     40Copy the following files to the ''code-signing computer'':
     41
     42* tap6.tar.gz
     43* 32-bit tapinstall.exe (renamed to tapinstall32.exe)
     44* 64-bit tapinstall.exe (renamed to tapinstall64.exe)
     45
     46'''On code-signing computer'''
     47
     48Clone the [https://github.com/mattock/sign-tap6/ Sign-Tap6] repository. Copy ''tap6.tar.gz'' to the ''sign-tap6'' directory and extract it:
     49
     50{{{
     51$ tar -zxf tap6.tar.gz
     52}}}
     53
     54Move tapinstall.exe's to the ''tap6'' directory:
     55
     56{{{
     57$ mv tapinstall32.exe tap6/i386
     58$ mv tapinstall64.exe tap6/amd64
     59}}}
     60
     61Next append secondary signatures to ''tapinstall.exe'' and ''tap0901.cat'' files under ''tap6'' using [https://github.com/mattock/sign-tap6/ Sign-Tap6.ps1]. Ensure that you're using the correct cross-certificate and that you timestamp the signature.
     62
     63Now wrap the dual-signed files into a tarball (e.g. using Git Bash):
     64
     65{{{
     66$ tar -zxf tap6-dual-signed.tar.gz tap6
     67}}}
     68
     69Copy the dual-signed tarball back to the ''build computer''.
     70
     71'''On build computer'''
     72
     73Extract contents of tap6-dual-signed.tar.gz to tap-windows6 root:
     74
     75{{{
     76$ rm -rf dist tap6
     77$ tar -zxf tap6-dual-signed.tar.gz
     78$ mv tap6 dist
     79}}}
     80
     81Run ''buildtap.py'' again using the same parameters as before, but ensure that you do not ''clean'' (-c) or ''build'' (-b). You should only ''package'' (-p) the dist directory into an installer. Copy the resulting ''installer'' to the ''code-signing computer'', or sign the installer using a user-mode code-signing SHA2 certificate on the ''build computer'' itself.
     82
     83'''On code-signing computer'''
     84
     85Append 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 [https://github.com/mattock/sign-tap6/ Sign-Tap6.ps1].
     86
     87----
     88
     89If 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.
     90
     91= Useful commands =
     92
     93== Installing certificates ==
    4594
    4695Installing a PFX file to the Currentuser certificate store using Powershell:
     
    5099If you're not accustomed to Powershell you can just use ''mmc.exe'' and the certificate snap-ins to install the certificate.
    51100
    52 === Querying the certificate store ===
     101== Querying the certificate store ==
    53102
    54103To list all certificates in ''Currentuser\My'' store using Powershell:
     
    63112The ''dir'' command is just an alias for ''Get-!ChildItem''
    64113
    65 === Creating catalog files with inf2cat ===
     114== Creating catalog files with inf2cat ==
    66115
    67116To create a catalog file for a 32-bit driver:
     
    80129'''NOTE:''' According to Microsoft Inf2Cat requires a full path to the driver directory.
    81130
    82 === Signing files with signtool.exe ===
     131== Signing files with signtool.exe ==
    83132
    84133Sign 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:
     
    104153}}}
    105154
    106 === Validating signatures ===
     155== Validating signatures ==
    107156
    108157Verifying the Authenticode signature of a file using Powershell:
     
    120169Signatures 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.
    121170
    122 == External links ==
     171= External links =
    123172
    124173'''General information'''