Changes between Version 32 and Version 33 of BuildingTapWindows6


Ignore:
Timestamp:
04/05/19 07:52:56 (5 years ago)
Author:
Samuli Seppänen
Comment:

Update tap-windows6 cross-signing documentation

Legend:

Unmodified
Added
Removed
Modified

  • BuildingTapWindows6

    v32 v33  
    12121. The signature needs to be timestamped, or the driver will stop functioning when the code-signing certificate expires.
    1313
    14 It is not clear if signtool's digest algorithm (/fd SHA|SHA256) affects the acceptability 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).
     14It is not clear if signtool's digest algorithm (/fd SHA|SHA256) affects the acceptability of the signature in Windows 7 and beyond, or if the only important thing is the hash algorithm of the actual certificate.
    1515
    16 The build computer should have WinDDK 7600.* installed, because currently buildtap.py does not work on anything newer.
     16Cross-signing is possible for Windows 7/8/8.1/Server 2012r2 as long as the certification authority's cross-certificate is valid. Beyond that point an actual Microsoft signature is required in all drivers. Windows 10 already requires these Microsoft signatures - they're called [https://docs.microsoft.com/en-us/windows-hardware/drivers/dashboard/attestation-signing-a-kernel-driver-for-public-release attestation signatures] in MS jargon. These signatures can be created in [https://developer.microsoft.com/en-us/windows Windows Dev Center] once you've cleared all the bureaucratic obstacles like signing in to development programs and registering your EV hardware token with your account.
    1717
    1818= Building with support for Windows Vista =
    1919
    20 If the driver has to support Windows Vista or very old Windows 7 versions it has to have two signatures:
     20**NOTE:** It is generally a bad idea to support Windows Vista. But if you must, please look [wiki:SigningForWindowsVista here].
    2121
    22 1. Primary signature created with a normal (non-EV) SHA1 code-signing certificate. The SHA1 signature needs to be the primary as Vista can apparently understand only one signature.
    23 1. Secondary signature created with an Extended Validation (EV) SHA2 code-signing certificate. An EV certificate is required on Windows 10 for kernel drivers.
     22= Building and signing for Windows 7/8/8.1/Server 2012r2 =
    2423
    25 There are also further requirements due to the two signatures:
     24Any relatively recent Windows 7 installation supports SHA2 Authenticode signatures. This means that the laborious and fragile [wiki:SigningForWindowsVista dual-signature process] can be avoided. You only need the EV SHA2 kernel-mode code-signing certificate, which probably comes in the form of a dongle that integrates with Windows certificate store. The tap-windows6 ''installer'' may optionally signed with a different, non-EV SHA2 code-signing certificate.
    2625
    27 * Build computer should have a SHA1 code-signing certificate in the certificate store under ''Currentuser\My'' or as a PFX file. The primary signature will be created by tap-windows6 build system.
    28 * 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''.
     26The prequisites for cross-signing:
    2927
    30 The actual build/signing procedure in this case is rather convoluted.
     28* On build computer
     29 * [https://github.com/OpenVPN/tap-windows6 tap-windows6] source directory is up-to-date
     30 * [https://docs.microsoft.com/en-us/windows-hardware/drivers/develop/using-the-enterprise-wdk Enterprise Windows Drive Kit] ISO image is installed and mounted as a system drive
     31 * tap-windows6 build system is configured properly (mostly file paths)
     32 * A user- or kernel mode authenticode certificate is present for signing the tap-windows6 ''installer''
     33* On signing computer
     34 * An EV token is visible in the Windows Certificate Store
     35 * [https://github.com/mattock/sign-tap6 Sign-Tap6] source directory is up-to-date
     36 * A correct cross-certificate from your CA is installed into the sign-tap6 directory
     37 * Sign-Tap6 is configured properly
     38* Your workstation
     39 * You are able to transfer files (e.g. via SSH) from and to the build and signing computers
     40
     41It is also assumed that all Windows commands are executed from within a Powershell session.
     42The signing process is as follows
    3143
    3244'''On build computer'''
    3345
    34 Copy your kernel-mode SHA1 code-signing certificate and the intermediate cross-signing certificate to the ''tap-windows6'' directory.
     46{{{
     47$ cd tap-windows6
     48$ python buildtap.py -c -b
     49}}}
    3550
    36 Run ''buildtap.py'' to build and to sign with SHA1
     51'''On workstation'''
     52
     53Copy the tap6.tar.gz from the build computer to the signing computer.
     54
     55'''On signing computer'''
    3756
    3857{{{
    39 $ python buildtap.py -b --sign <certificate-options>
     58$ cd sign-tap6
     59$ tar -zxf tap6.tar.gz
     60$ Sign-Tap6.ps1 -SourceDir tap6 -Force
     61$ Move-Item tap6 tap6-signed
     62$ tar -zcf tap6-signed.tar.gz tap6-signed
    4063}}}
    4164
    42 '''NOTE:''' using the "-c" switch will wipe out any pre-built tapinstall.exe's in the ''tapinstall'' directory, so be careful with it.
     65The EV dongle will probably prompt you twice per architecture (x86, x64, arm64) as it signs the catalog file and tapinstall.exe for each. Note that the -Force switch ''is required'' or the file hashes in the .cat files will be incorrect and the driver will not install.
    4366
    44 Copy the following files to the ''code-signing computer'':
     67'''On workstation'''
    4568
    46 * tap6.tar.gz
    47 * 32-bit tapinstall.exe (renamed to tapinstall32.exe)
    48 * 64-bit tapinstall.exe (renamed to tapinstall64.exe)
    49 
    50 '''On code-signing computer'''
    51 
    52 Clone the [https://github.com/mattock/sign-tap6/ 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. All commands except the actual signing should be done from Git Bash or similar.
    53 
    54 Copy ''tap6.tar.gz'' to the ''sign-tap6'' directory and extract it:
    55 
    56 {{{
    57 $ tar -zxf tap6.tar.gz
    58 }}}
    59 
    60 Copy tapinstall.exe's to the ''tap6'' directory:
    61 
    62 {{{
    63 $ cp tapinstall32.exe tap6/i386/tapinstall.exe
    64 $ cp tapinstall64.exe tap6/amd64/tapinstall.exe
    65 }}}
    66 
    67 Next append secondary signatures with ''Sign-Tap6.ps1'' in an ''administrator Powershell session''. For example:
    68 
    69 {{{
    70 $ Sign-Tap6.ps1 -SourceDir tap6 -Append
    71 }}}
    72 
    73 Now wrap the dual-signed files into a tarball (e.g. using Git Bash):
    74 
    75 {{{
    76 $ tar -zcf tap6-dual-signed.tar.gz tap6
    77 }}}
    78 
    79 Copy the dual-signed tarball back to the ''build computer''.
     69Copy tap6-signed.tar.gz from signing computer to the build computer for packaging.
    8070
    8171'''On build computer'''
    82 
    83 Extract contents of ''tap6-dual-signed.tar.gz'' to the ''tap-windows6'' directory:
    84 
    85 {{{
    86 $ rm -rf dist tap6
    87 $ tar -zxf tap6-dual-signed.tar.gz
    88 $ mv tap6 dist
    89 }}}
    90 
    91 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.
    92 
    93 {{{
    94 $ python buildtap.py -p --sign --certfile=<my-sha2-certificate> --certpw=<password> --crosscert=<my-cross-cert> --timestamp=http://timestamp.digicert.com --ti=tapinstall
    95 }}}
    96 
    97 Alternatively copy the installer produced by ''buildtap.py'' to the ''code-signing computer'' for the additional signature, as described below.
    98 
    99 '''On code-signing computer'''
    100 
    101 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 [https://github.com/mattock/sign-tap6/ Sign-Tap6.ps1].
    102 
    103 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.
    104 
    105 = Building for Windows 7 and later =
    106 
    107 Any relatively recent Windows 7 installation supports SHA2 Authenticode signatures. This means that the laborious and fragile dual-signature process can be avoided. You only need the EV SHA2 kernel-mode code-signing certificate, which probably comes in the form of a dongle that integrates with Windows certificate store. The tap-windows6 ''installer'' may optionally signed with a different, non-EV SHA2 code-signing certificate.
    108 
    109 The build process is somewhat easier than with dual signatures. There are only a couple small differences:
    110 
    111 * buildtap.py should not use the --sign switch or any of its parameters
    112 * The -Append switch must not be used in Sign-Tap6
    113 * '''The -Force switch must be used in Sign-Tap6:''' without it the file hashes in the .cat files will be incorrect and driver will not install.
    114 * An older version of signtool.exe can be used on the code-signing computer as appending of signatures is not necessary
    11572
    11673= Useful commands =
    … …  
    205162'''General information'''
    206163 * [http://www.osr.com/blog/2015/07/24/questions-answers-windows-10-driver-signing/ Questions and Answers: Windows 10 Driver Signing]
     164 * [https://docs.microsoft.com/en-us/windows-hardware/drivers/dashboard/attestation-signing-a-kernel-driver-for-public-release Attestation signing a kernel driver for public release]
    207165 * [http://www.davidegrayson.com/signing/ Practical Windows Code and Driver Signing]
    208166 * [https://msdn.microsoft.com/en-us/library/windows/hardware/ff686697%28v=vs.85%29.aspx Authenticode Digital Signatures]