Changes between Version 10 and Version 11 of BuildingTapWindows6


Ignore:
Timestamp:
04/21/16 17:15:22 (6 years ago)
Author:
Samuli Seppänen
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • BuildingTapWindows6

    v10 v11  
    55= Codesigning =
    66
    7 Getting 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 dual signatures (SHA1 and EV SHA2) with independent cross-certificates and timestamps may be required. This section contains miscellaneous notes about signing driver packages. In addition to this page you should have a look at the [https://github.com/mattock/sign-tap6/ Sign-Tap6 tool], which can be used to create and append signatures as desired.
     7Getting 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:
     8
     91. 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.
     101. Secondary signature created with an Extended Validation (EV) SHA2 code-signing certificate. An EV certificate is required on Windows 10 for kernel drivers.
     11
     12There are two additional requirements for both of these signatures:
     13
     141. The Certificate path needs to be complete. This can be achieved by including [https://msdn.microsoft.com/en-us/library/windows/hardware/dn170454%28v=vs.85%29.aspx 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.
     151. The signature needs to be timestamped, or the driver will stop functioning when the code-signing certificate expires.
     16
     17It 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).
     18
     19Due to the above, the build environment for tap-windows6 needs to setup just right:
     20
     21* 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''
     22* 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''.
     23
     24The actual build procedure is a bit convoluted:
     25
     261. Run ''buildtap.py'' on the build computer, signing it with the SHA1 certificate. 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.
     271. Copy tap6.tar.gz to the signing computer
     281. Unpack tap6.tar.gz on the signing computer
     291. 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.
     301. Copy the dual-signed files back to the build computer
     311. Copy the contents of the dual-signed tap6 directory to ''dist'' in tap-windows6 build root.
     321. 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.
     331. Copy the 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].
     34
     35If 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.
    836
    937== Installing certificates ==
     
    86114 * [https://msdn.microsoft.com/en-us/library/windows/hardware/ff686697%28v=vs.85%29.aspx Authenticode Digital Signatures]
    87115 * [https://msdn.microsoft.com/en-us/library/windows/hardware/dn170454%28v=vs.85%29.aspx Cross-Certificates for Kernel Mode Code Signing]
     116 * [https://bugzilla.mozilla.org/show_bug.cgi?id=1079858 Bug 1079858 - Deal with deprecation of SHA1 (SHA-1) Authenticode signatures for Windows signing] (from Mozilla.org)
    88117'''Practical guides'''
    89118 * [https://technet.microsoft.com/en-us/library/dd919238%28v=ws.10%29.aspx Steps for Signing a Device Driver Package]