Difference between revisions of "Documentation/Nightly/Developers/Windows Code Signing"

From Slicer Wiki
Jump to: navigation, search
 
(15 intermediate revisions by 3 users not shown)
Line 6: Line 6:
  
 
* Install [https://developer.microsoft.com/en-us/windows/downloads/windows-10-sdk Windows 10 SDK] to get latest [https://msdn.microsoft.com/en-us/library/8s9b9yaz(v=vs.110).aspx SignTool.exe].
 
* Install [https://developer.microsoft.com/en-us/windows/downloads/windows-10-sdk Windows 10 SDK] to get latest [https://msdn.microsoft.com/en-us/library/8s9b9yaz(v=vs.110).aspx SignTool.exe].
 +
 +
[[File:Windows 10 SDK-Installing-for-app-signing.png|500px]]
  
 
==Acquire and install a code signing certificate==
 
==Acquire and install a code signing certificate==
Line 19: Line 21:
 
SignTool.exe digitally signs files, verifies signatures in files, and time-stamps files. See [https://msdn.microsoft.com/en-us/library/8s9b9yaz(v=vs.110).aspx SignTool.exe documentation].
 
SignTool.exe digitally signs files, verifies signatures in files, and time-stamps files. See [https://msdn.microsoft.com/en-us/library/8s9b9yaz(v=vs.110).aspx SignTool.exe documentation].
  
−
For Slicer, at least the following files should be signed before creating the installer:
+
The final installer .exe should be signed.
−
* Slicer.exe (launcher)
+
 
−
* bin/SlicerApp-real.exe (application)
+
===Examples===
 +
 
 +
====Sign using SHA-2 (used to sign Slicer installer)====
 +
This is the recommended method, and was used to sign the Slicer installers starting with version 4.6.
 +
 
 +
1) Open a <i>Developer Command Prompt</i> (e.g VS2017 x64 Native Tools Command Prompt)
 +
 
 +
2) Download the DigiCert signing certificate (<code>codecert.pfx</code>) and get associated <code>&lt;password&gt;</code> needed in the command below.
 +
 
 +
3) Sign using a DigiCert code signing certificate, following their [https://www.digicert.com/code-signing/signcode-signtool-command-line.htm examples]:
 +
<pre>
 +
signtool.exe sign /f "C:\Users\dashboard\Downloads\codecert.pfx" /p <password> /fd sha256 /tr http://timestamp.digicert.com /td sha256 /v "C:\Users\dashboard\Downloads\installer.exe"
 +
</pre>
 +
* <tt>/f</tt> specifies the path to the code signing certificate
 +
* <tt>/p</tt> specifies the password for the code signing certificate
 +
* <tt>/fd</tt> specifies the file digest algorithm
 +
* <tt>/tr</tt> specifies the URL of the RFC-3161 timestamp server
 +
* <tt>/td</tt> specifies the digest algorithm to be used by the timestamp server
 +
* <tt>/v</tt> displays verbose output
 +
 
 +
====Dual sign with SHA-1 and SHA-2====
 +
Dual signing should be necessary only when targeting Windows XP SP3/Vista:
 +
<pre>
 +
signtool.exe sign /f "C:\path\to\cert.pfx" /p <password> /t http://timestamp.digicert.com /v setup.exe
 +
signtool.exe sign /f "C:\path\to\cert.pfx" /p <password> /fd sha256 /tr http://timestamp.digicert.com /td sha256 /as /v foo.exe
 +
</pre>
 +
* <tt>/as</tt> appends the SHA-2 signature to the primary signature
 +
 
 +
====Verify the signature====
 +
<pre>
 +
signtool.exe verify /pa /v setup.exe
 +
</pre>
 +
* <tt>/pa</tt> specifies that the Default Authenticode Verification Policy should be used instead of the Windows Driver Verification Policy
 +
 
 +
Alternatively, view the "Digital Signatures" tab on the file's properties in Windows Explorer.
  
−
Other candidate files to sign include:
+
===Notes===
−
* other .exe files in bin/
 
−
* other .exe files outside bin/, such as CLI modules
 
−
* .dll files in bin/ and for modules
 
  
−
After creating the installer, the installer .exe should also be signed.
+
The Windows 10 SDK installs the 64-bit SignTool.exe to <tt>C:\Program Files (x86)\Windows Kits\10\bin\x64\signtool.exe</tt>.
  
 
==CMake integration==
 
==CMake integration==
Line 35: Line 68:
  
 
MySQL's implementation could be a useful example; see https://github.com/mysql/mysql-server/blob/67d52e7c7a1a23424e39273cbb6f5f9d56fda8d1/cmake/install_macros.cmake#L155.
 
MySQL's implementation could be a useful example; see https://github.com/mysql/mysql-server/blob/67d52e7c7a1a23424e39273cbb6f5f9d56fda8d1/cmake/install_macros.cmake#L155.
 +
Also see another implementation: https://github.com/firebreath/FireBreath/blob/0fe3c7f8f9315768893442af51b03378d11a3a26/cmake/Win.cmake#L175.
 +
 +
Finally, see discussion on the CMake mailing list: http://cmake.3232098.n2.nabble.com/How-to-codesign-msi-from-WIX-CPack-td7594228.html.
 +
 +
Once CMake integration is achieved, it's recommend to also sign executables inside the installer, including at least:
 +
* Slicer.exe (launcher)
 +
* bin/SlicerApp-real.exe (application)
 +
 +
Other candidate files to sign include:
 +
* other .exe files in bin/
 +
* other .exe files outside bin/, such as CLI modules
 +
* .dll files in bin/ and for modules
  
 
==Additional references==
 
==Additional references==

Latest revision as of 15:55, 16 January 2019

Home < Documentation < Nightly < Developers < Windows Code Signing

Overview

This page contains information on code signing on Windows and on integrating code signing into the Slicer packaging process.

Prerequisites

Windows 10 SDK-Installing-for-app-signing.png

Acquire and install a code signing certificate

Follow the procedure described in Acquire a Code Signing Certificate to acquire a code signing certificate from a commercial vendor recognized by Microsoft. Some example vendor links include:

It may be necessary to install the code signing certificate on the machine that will be used to sign the code. Regardless, it is necessary to export the certificate to a .pfx file to be used by SignTool.exe.

Sign files using SignTool.exe

SignTool.exe digitally signs files, verifies signatures in files, and time-stamps files. See SignTool.exe documentation.

The final installer .exe should be signed.

Examples

Sign using SHA-2 (used to sign Slicer installer)

This is the recommended method, and was used to sign the Slicer installers starting with version 4.6.

1) Open a Developer Command Prompt (e.g VS2017 x64 Native Tools Command Prompt)

2) Download the DigiCert signing certificate (codecert.pfx) and get associated <password> needed in the command below.

3) Sign using a DigiCert code signing certificate, following their examples: 

signtool.exe sign /f "C:\Users\dashboard\Downloads\codecert.pfx" /p <password> /fd sha256 /tr http://timestamp.digicert.com /td sha256 /v "C:\Users\dashboard\Downloads\installer.exe"
  • /f specifies the path to the code signing certificate
  • /p specifies the password for the code signing certificate
  • /fd specifies the file digest algorithm
  • /tr specifies the URL of the RFC-3161 timestamp server
  • /td specifies the digest algorithm to be used by the timestamp server
  • /v displays verbose output

Dual sign with SHA-1 and SHA-2

Dual signing should be necessary only when targeting Windows XP SP3/Vista: 

signtool.exe sign /f "C:\path\to\cert.pfx" /p <password> /t http://timestamp.digicert.com /v setup.exe
signtool.exe sign /f "C:\path\to\cert.pfx" /p <password> /fd sha256 /tr http://timestamp.digicert.com /td sha256 /as /v foo.exe
  • /as appends the SHA-2 signature to the primary signature

Verify the signature

signtool.exe verify /pa /v setup.exe
  • /pa specifies that the Default Authenticode Verification Policy should be used instead of the Windows Driver Verification Policy

Alternatively, view the "Digital Signatures" tab on the file's properties in Windows Explorer.

Notes

The Windows 10 SDK installs the 64-bit SignTool.exe to C:\Program Files (x86)\Windows Kits\10\bin\x64\signtool.exe.

CMake integration

Currently, CMake/CPack doesn't include any built-in functionality to automatically call SignTool.exe to digitally sign files or installers. Therefore, integrating code signing into Slicer requires adding custom steps for the targets chosen to be signed.

MySQL's implementation could be a useful example; see https://github.com/mysql/mysql-server/blob/67d52e7c7a1a23424e39273cbb6f5f9d56fda8d1/cmake/install_macros.cmake#L155. Also see another implementation: https://github.com/firebreath/FireBreath/blob/0fe3c7f8f9315768893442af51b03378d11a3a26/cmake/Win.cmake#L175.

Finally, see discussion on the CMake mailing list: http://cmake.3232098.n2.nabble.com/How-to-codesign-msi-from-WIX-CPack-td7594228.html.

Once CMake integration is achieved, it's recommend to also sign executables inside the installer, including at least:

  • Slicer.exe (launcher)
  • bin/SlicerApp-real.exe (application)

Other candidate files to sign include:

  • other .exe files in bin/
  • other .exe files outside bin/, such as CLI modules
  • .dll files in bin/ and for modules

Additional references

Introduction to Code Signing (MSDN)

Windows Enforcement of Authenticode Code Signing and Timestamping (Microsoft TechNet)

Retrieved from "https://www.slicer.org/w/index.php?title=Documentation/Nightly/Developers/Windows_Code_Signing&oldid=60714"