Changes between Version 45 and Version 46 of BuildingTapWindows6


Ignore:
Timestamp:
04/24/19 10:32:40 (2 years ago)
Author:
Samuli Seppänen
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • BuildingTapWindows6

    v45 v46  
    55Generic 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 = Generic requirements =
     7= Requirements =
    88
    99Getting 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. The Authenticode signatures have a few requirements:
     
    2323 * [https://github.com/OpenVPN/tap-windows6 tap-windows6] source directory is up-to-date
    2424 * [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
    25  * tap-windows6 build system is configured properly (file paths etc.)
    26  * Clone [https://github.com/Microsoft/Windows-driver-samples/ Windows-driver-samples] under the tap-windows6 directory
    27  * Clone [https://github.com/mattock/sign-tap6 sign-tap6] under the tap-windows6 directory
     25 * tap-windows6 build system is configured properly (paths.py etc.)
     26 * Clone [https://github.com/Microsoft/Windows-driver-samples/ Windows-driver-samples]
     27  * Optionally copy the "setup\devcon" directory to the tap-windows6 directory
    2828* On signing computer
    2929 * An EV token is visible in the Windows Certificate Store
    30  * [https://github.com/mattock/sign-tap6 Sign-Tap6] source directory is up-to-date
    31  * A correct cross-certificate from your CA is installed into the sign-tap6 directory
    32  * Sign-Tap6 is configured properly (see Sign-Tap6.conf.ps1)
    33  * Optionally relax the [https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.security/set-executionpolicy Powershell execution policy] to remove some extra warnings when signing
    34 * Your workstation
    35  * You are able to transfer files (e.g. via SSH) from and to the build and signing computers
     30 * A correct cross-certificate from your CA is installed into the tap-windows6 directory
     31 * sign\Sign-Tap6.conf.ps1 is configured properly
     32
     33On top of the generic requirements listed above there are a few extra requirements when doing attestation signing for Windows 10:
     34
     35* You need to register your EV dongle with your organization's account in the Windows Dev Center ([https://developer.microsoft.com/en-us/dashboard/account/managecertificates direct link]).
     36* INF file syntax needs to be valid, as MS backend servers will check it at submission time. Use the latest version of !InfVerif (see footer in Hardware Dev Center) to validate the syntax before submission.
    3637
    3738In the documentation below it is assumed that all Windows commands are executed from within a Powershell session.
    3839
    39 = Modifying the Visual Studio project file =
     40= Setting up the SMB share =
     41
     42If the building and signing computers are separate you are ''strongly encouraged'' to share the build directory on the build computer with the signing computer, e.g. using SMB); this removes the need for doing error-prone file copying, archive extraction, etc. In the instructions below it is assumed that this is the case.
     43
     44You can create new shares on the build computer in various ways. Here's an example on how to do it with Puppet using Powershell DSC resources:
     45
     46{{{
     47dsc_windowsfeature { 'File server':
     48  dsc_ensure => 'present',
     49  dsc_name   => 'FS-FileServer',
     50}
     51
     52dsc_xsmbshare { 'tap-windows6-build-directory':
     53  dsc_ensure                => 'present',
     54  dsc_name                  => 'tap6build',
     55  dsc_description           => 'tap-windows6 build directory',
     56  dsc_path                  => 'C:\\Users\\build\\opt\\tap-windows6',
     57  dsc_folderenumerationmode => 'AccessBased',
     58  dsc_fullaccess            => 'tapbuilder\build',
     59}
     60}}}
     61
     62This code can be mapped almost 1:1 to Powershell DSC. Alternatively you can use raw Powershell commands [https://ss64.com/ps/add-windowsfeature.html Add-Windowsfeature] and [https://docs.microsoft.com/en-us/powershell/module/smbshare/new-smbshare?view=win10-ps New-Smbshare] to do the same. Or just create the share via Windows GUI somehow. Remember to open port 445 in the firewall.
     63
     64Once the share is up, mount it on a Powershell session:
     65
     66{{{
     67$ net use W: \\tapbuilder.example.org\tap6build /user:build 'password-here'
     68}}}
     69
     70Note that this mount is session-specific, so you need to do it from the session you use to sign the files from.
     71
     72= Building =
     73
     74The building and signing process is automated to a large degree and documented in detail in tap-windows6's [https://github.com/OpenVPN/tap-windows6/blob/master/README.rst README.rst file]. The instructions work equally well in two scenarios:
     75
     76* A single computer is use to build and sign
     77* Build and signing computers are separate, but the build directory is shared with SMB
     78
     79If tap-windows6 build directory is shared via SMB you will get warnings about running scripts from the Internet. Unfortunately it is not possible to make this problem go away, even with the [https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.utility/unblock-file?view=powershell-6 Unblock-File] CmdLet when working with SMB shares, unless you modify the global Powershell execution policy with [https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.security/set-executionpolicy Set-ExecutionPolicy] CmdLet.
     80
     81It is generally a bad idea to support Windows Vista. But if you must, please look [wiki:SigningForWindowsVista here].
     82
     83= Hints =
     84
     85== Modifying the Visual Studio project files ==
    4086
    4187Many tap-windows6 build settings come from the Visual studio project file, src\tap-windows6.vcxproj. That file is generated by buildtap.py from src\tap-windows6.vcxproj.in.
     
    67113Once you've figured out what the GUI does you can port those changes to tap-windows6.vcxproj.in and they will get applied to all subsequent builds.
    68114
    69 = Setting up the SMB share =
    70 
    71 If the building and signing computers are separate you are ''strongly encouraged'' to share the build directory on the build computer with the signing computer, e.g. using SMB); this removes the need for doing error-prone file copying, archive extraction, etc. In the instructions below it is assumed that this is the case.
    72 
    73 You can create new shares on the build computer in various ways. Here's an example on how to do it with Puppet using Powershell DSC resources:
    74 
    75 {{{
    76 dsc_windowsfeature { 'File server':
    77   dsc_ensure => 'present',
    78   dsc_name   => 'FS-FileServer',
    79 }
    80 
    81 dsc_xsmbshare { 'tap-windows6-build-directory':
    82   dsc_ensure                => 'present',
    83   dsc_name                  => 'tap6build',
    84   dsc_description           => 'tap-windows6 build directory',
    85   dsc_path                  => 'C:\\Users\\build\\opt\\tap-windows6',
    86   dsc_folderenumerationmode => 'AccessBased',
    87   dsc_fullaccess            => 'tapbuilder\build',
    88 }
    89 }}}
    90 
    91 This code can be mapped almost 1:1 to Powershell DSC. Alternatively you can use raw Powershell commands [https://ss64.com/ps/add-windowsfeature.html Add-Windowsfeature] and [https://docs.microsoft.com/en-us/powershell/module/smbshare/new-smbshare?view=win10-ps New-Smbshare] to do the same. Or just create the share via Windows GUI somehow. Remember to open port 445 in the firewall.
    92 
    93 Once the share is up, mount it on a Powershell session:
    94 
    95 {{{
    96 $ net use W: \\tapbuilder.example.org\tap6build /user:build 'password-here'
    97 }}}
    98 
    99 Note that this mount is session-specific, so you need to do it from the session you use to sign the files from.
    100 
    101 = Building an unsigned driver and tapinstall.exe =
    102 
    103 Regardless of the signature type you need to build unsigned tap-windows6 driver first:
    104 
    105 '''On build computer'''
    106 
    107 {{{
    108 $ cd tap-windows6
    109 $ python.exe buildtap.py -c -b --ti=Windows-driver-samples\setup\devcon
    110 }}}
    111 
    112 = Building for Windows Vista =
    113 
    114 **NOTE:** It is generally a bad idea to support Windows Vista. But if you must, please look [wiki:SigningForWindowsVista here].
    115 
    116 = Building and signing for Windows 7/8/8.1/Server 2012r2 =
    117 
    118 Any 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.
    119 
    120 '''On build computer'''
    121 
    122 Build an unsigned driver (see above)
    123 
    124 '''On signing computer'''
    125 
    126 Sign the build files using the EV token:
    127 
    128 {{{
    129 $ cd W:\tap-windows6\sign-tap6
    130 $ .\Sign-Tap6.ps1 -SourceDir ..\dist -Force
    131 }}}
    132 
    133 If tap-windows6 build directory is shared via SMB you will get warnings about running scripts from the Internet. Unfortunately it is not possible to make this problem go away, even with the [https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.utility/unblock-file?view=powershell-6 Unblock-File] CmdLet when working with SMB shares, unless you modify the global Powershell execution policy with [https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.security/set-executionpolicy Set-ExecutionPolicy] CmdLet.
    134 
    135 Once you're past the script warnings the 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.
    136 
    137 '''On build computer'''
    138 
    139 Package the signed files:
    140 
    141 {{{
    142 $ cd tap-windows6
    143 $ python.exe buildtap.py -p --ti=Windows-driver-samples\setup\devcon
    144 $ cd sign-tap6
    145 $ .\Sign-File -SourceFile ..\<installer-file>
    146 }}}
    147 
    148 '''On signing computer'''
    149 
    150 Sign the installer:
    151 
    152 {{{
    153 $ ...
    154 }}}
    155 
    156 = Building and signing for Windows 10 =
    157 
    158 On top of the generic requirements listed above there are a few extra requirements when doing attestation signing:
    159 
    160 * You need to register your EV dongle with your organization's account in the Windows Dev Center ([https://developer.microsoft.com/en-us/dashboard/account/managecertificates direct link]).
    161 * INF file syntax needs to be valid, as MS backend servers will check it at submission time. Use the latest version of !InfVerif (see footer in Hardware Dev Center) to validate the syntax before submission.
    162 
    163 The building and signing process is as follows
    164 
    165 '''On build computer'''
    166 
    167 Build an unsigned driver (see above)
    168 
    169 '''On workstation'''
    170 
    171 Copy the tap6.tar.gz from the build computer to the signing computer.
    172 
    173 '''On signing computer'''
    174 
    175 {{{
    176 $ cd sign-tap6
    177 $ tar -zxf tap6.tar.gz
    178 }}}
    179 
    180 Next you need to create three DDF files, one for each architecture (x86, x64, arm64), which are used to create the cabined files. Here's an example for amd64:
    181 
    182 {{{
    183 ; tap-windows6-amd64.ddf
    184 ;
    185 .OPTION EXPLICIT     ; Generate errors
    186 .Set CabinetFileCountThreshold=0
    187 .Set FolderFileCountThreshold=0
    188 .Set FolderSizeThreshold=0
    189 .Set MaxCabinetSize=0
    190 .Set MaxDiskFileCount=0
    191 .Set MaxDiskSize=0
    192 .Set CompressionType=MSZIP
    193 .Set Cabinet=on
    194 .Set Compress=on
    195 ;Specify file name for new cab file
    196 .Set CabinetNameTemplate=tap-windows6-amd64.cab
    197 ;Specify files to be included in cab file
    198 .Set DestinationDir=amd64
    199 C:\users\sign\opt\sign-tap6\tap6\amd64\tap0901.sys
    200 C:\users\sign\opt\sign-tap6\tap6\amd64\OemVista.inf
    201 }}}
    202 
    203 Generate the cabinet file:
    204 
    205 {{{
    206 makecab.exe /f "C:\Users\sign\opt\sign-tap6\tap-windows6-amd64.ddf"
    207 }}}
    208 
    209 This puts the cabinet file to a subdirectory called "disk1". Then sign the cabinet file, adapting the parameters as needed:
    210 
    211 {{{
    212 SignTool sign /ac "C:\Users\sign\opt\sign-tap6\digicert-high-assurance-ev.crt" /s MY /n "OpenVPN" /fd sha256 /tr http://timestamp.digicert.com /td sha256 /v "C:\Users\sign\opt\sign-tap6\disk1\tap-windows6-amd64.cab"
    213 }}}
    214 
    215 For other platforms just replace "amd64" with "i386" or "arm64". After this process you have three signed cabined files.
    216 
    217 Now submit each one individually to Windows Dev Center for attestation signing. Make sure to check only the applicable platforms in the "Requested signatures" section. If all goes well, you can click "More" at the right of your submission below "Package and signing properties" and download a ZIP file with signed driver files.
    218 
    219 Once you have the signed driver files you may want to wrap them into an installer.
    220 
    221 For more generic instructions and more details please refer to the [https://docs.microsoft.com/en-us/windows-hardware/drivers/dashboard/attestation-signing-a-kernel-driver-for-public-release official MS documentation] on attestation signing.
    222 
    223 = Useful commands =
    224115
    225116== Installing certificates ==