| 39 | | = Modifying the Visual Studio project file = |
| | 40 | = Setting up the SMB share = |
| | 41 | |
| | 42 | 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. |
| | 43 | |
| | 44 | 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: |
| | 45 | |
| | 46 | {{{ |
| | 47 | dsc_windowsfeature { 'File server': |
| | 48 | dsc_ensure => 'present', |
| | 49 | dsc_name => 'FS-FileServer', |
| | 50 | } |
| | 51 | |
| | 52 | dsc_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 | |
| | 62 | 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. |
| | 63 | |
| | 64 | Once 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 | |
| | 70 | Note 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 | |
| | 74 | The 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 | |
| | 79 | 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. |
| | 80 | |
| | 81 | It 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 == |
| 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 = |
