Test-Signing a Driver File

Use SignTool to embed a signature in a driver file.

Using a MakeCert Test Certificate or a Commercial Test Certificate to Embed a Test Signature in a Driver File

Use the following SignTool command to embed a signature in a driver file by using a MakeCert test certificate or a commercial test certificate.

The sign command configures SignTool to embed a signature in the driver file DriverFileName.sys.

The /v verbose option configures SignTool to print execution and warning messages.

The /sВ TestCertStoreName option supplies the name of the test certificate store that contains the test certificate named TestCertName.

The /nВ TestCertName option supplies the name of the test certificate that is installed in the certificate store named TestCertStoreName. The test certificate can be either a MakeCert test certificate or a commercial test certificate.

The /tВ http://timestamp.digicert.com option supplies the URL to the publicly-available time-stamp server that DigiCert provides.

DriverFileName.sys is the name of the driver file.

The following command shows how to use SignTool to test-sign a driver file. This example embeds a signature in Toaster.sys, which is in the amd64 subdirectory under the directory in which the command is run. The test certificate is named «contoso.com(test)» and it is installed in the certificate store named «PrivateCertStore.»

Using an Enterprise CA Test Certificate to Embed a Test Signature in a Driver File

The following SignTool command assumes that an Enterprise CA issues the test certificate that you use to test-sign a driver package. If the Enterprise CA test certificate is the only test certificate that is present in your certificate stores, you can use the following command where you specify only the /a option and the name of the driver file. In this situation, SignTool will locate and use your Enterprise CA test certificate by default.

If you have created or obtained other test certificates in addition to an Enterprise CA test certificate, you must use the SignTool options /s and /n to specify the name of the test certificate store and the name of the test certificate that is installed in the test certificate store.

Signing a Driver During Development and Testing

Before you install a driver on a computer running a 64-bit version of Windows, you must sign the driver package. For testing purposes, you can test sign the driver package, which is a more relaxed form of signing than signing for public release.

In Microsoft Visual Studio, test signing is enabled by default. Suppose you have created a KMDF driver solution as described in Writing a KMDF driver based on a template. When you build the solution, you can see in the Output window that the driver package has been test signed.

Enabling test signing manually

To manually enable test signing, follow these steps.

In Visual Studio, open a solution that has a driver package project. Select and hold (or right-click) the driver package project, and choose Properties.

In the property pages for the package, navigate to Configuation Properties > Driver Signing > General. In the Sign Mode drop-down list, select Test Sign.

In the property pages for the package, navigate to Configuation Properties > Inf2Cat > General. In the Run Inf2Cat drop-down list, select Yes.

Viewing the signed driver package

After you build your solution, navigate in File Explorer to the folder that contains your driver package. One of the files in the package is a catalog file. The catalog file contains the digital signature for the package. For an example of viewing the files in a signed package, see Writing a KMDF driver based on a template.

Sharing a signing certificate

When you test sign a driver package, Visual Studio creates a signing certificate (PFX file) and imports it into a certificate store on your host computer. When you deploy your test-signed driver package to a test computer, Visual Studio copies a verification certificate (CER file) to the test computer. If you want to share the certificate with developers who are building drivers on other host computers, you must share the signing certificate, not the verification certificate.

To share the signing certificate, follow these steps.

In Visual Studio, in the Solution Explorer window, select and hold (or right-click) your driver package project, and choose Properties.

In the property pages for the package, navigate to Configuation Properties > Driver Signing > General. In the Test Certificate field, choose Select From Store.

In the Select Certificate dialog box, locate your test-signing certificate. The name of the certificate will be similar to WDKTestCert yourName. Select your test-signing certificate, and select Properties. In the Details tab, select Copy to File.

Follow the instructions in the Certificate Export Wizard to export a PFX file. When you are asked whether you want to export the private key, select Yes, export the private key.

Share the exported PFX file with the other developers.

How to Test-Sign a Driver Package

This section provides information about the basic steps that you have to follow when you test-sign a driver package.

Test-signing refers to using a test certificate to sign a prerelease version of a driver package for use on test computers. In particular, this allows developers to sign kernel-mode binaries by using self-signed certificates, such as those the MakeCert tool generates. This capability allows developers to test kernel-mode binaries on Windows with driver signature verification enabled.

Windows supports test-signed drivers only for development and testing purposes. Test-signed drivers must not be used for production purposes or released to customers.

This section includes topics that describe these steps and provide examples, such as the following:

Creating a test certificate that is used to sign a driver package. In this section, steps are described to create and use a self-signed test certificate named Contoso.com(Test). This certificate is used in many examples that are discussed in this section.

Preparing a driver package for test-signing. This includes creating a catalog file that contains the digital signature.

Test-signing the driver package’s catalog file by using the Contoso.com(Test) certificate.

Test-signing a driver through an embedded signature by using the Contoso.com(Test) certificate.

NoteВ В You have to embed a digital signature within the driver if the driver is a boot-start driver.

Each topic in this section describes a separate procedure in the test-signing process, and provides the general information that you need to understand the procedure. In addition, each topic points you to other topics that provide detailed information about the procedure.

Throughout this section, separate computers are used for the various processes involved in test-signing a driver. These computers are referred to as follows:

Signing computer
This is the computer that is used to test-sign a driver package for Windows Vista and later versions of Windows. This computer must be running Windows XP SP2 or later versions of Windows. In order to use the driver signing tools, this computer must have the Windows Vista and later versions of the Windows Driver Kit (WDK) installed.

Test computer
This is the computer that is used to install and test the test-signed driver package. This computer must be running Windows Vista or later versions of Windows.

The topics of this section use the ToastPkg sample driver package to introduce the test-signing process. Within the WDK installation directory, the ToastPkg driver package is located in the src\general\toaster\toastpkg directory.

NoteВ В The WDK contains a sample command script that shows the step-by-step procedure to correctly test-sign the ToastPkg sample driver package. You can modify this script to test-sign your own driver package. Within the WDK installation directory, the example is located at src\general\build\driversigning\selfsign_example.cmd. Additional instructions for test-signing are described in src\general\build\driversigning\selfsign_readme.htm.

This section includes the following topics:

Test-Signing Driver Packages

In this section, a computer that test-signs drivers for release on Windows Vista and later versions of Windows is referred to as the signing computer. The signing computer must be running Windows XP SP2 or later versions of Windows. For example, a driver intended for release on Windows 7 can be signed on a computer running Windows Vista.

In order to use the driver signing tools, the signing computer must have the Windows Vista and later versions of the WDK installed.

NoteВ В You must use the version of the SignTool tool that is provided in the Windows Vista and later versions of the Windows Driver Kit (WDK). Earlier versions of the SignTool do not support the kernel-mode code signing policy for Windows Vista and later versions of Windows.

To comply with the kernel-mode code signing policy and the Plug and Play (PnP) device installation signing requirements of Windows Vista and later versions of Windows, you must sign a driver during the development and test of that driver. You can sign the driver on the signing computer as follows, based on the driver type.

NoteВ В The Windows code-signing policy requires that a signed catalog file for a driver package be installed in the system component and driver database. PnP device installation automatically installs the catalog file of a PnP driver in the driver database. However, if you use a signed catalog file to sign a non-PnP driver, the installation application that installs the driver must also install the catalog file in the driver database.

PnP Kernel-Mode Boot-Start Driver

To comply with the kernel-mode code signing policy of 64-bit versions of Windows Vista and later versions of Windows, embed a signature in the boot-start driver file as follows:

Starting with Windows Vista, embedding a signature in a boot-start driver file is optional for 32-bit versions of Windows. Although Windows will check if a kernel-mode driver file has an embedded signature, an embedded signature is not required.

To comply with the PnP device installation signing requirements of Windows Vista and later versions of Windows, you must also test-sign a catalog file for the driver package. If a driver file will also include an embedded signature, embed the signature in the driver file before signing the driver package’s catalog file.

You can submit a request to have the Windows Hardware Quality Labs (WHQL) test-sign the catalog file. Alternatively, you can test-sign a catalog file yourself with a test certificate, as follows:

You can verify the signature of the catalog file itself or the signature of individual files that have corresponding entries in the catalog file.

Non-PnP Kernel-Mode Boot-Start Driver

To comply with the kernel-mode code signing policy of 64-bit versions of Windows Vista and later versions of Windows, embed a signature in a boot-start driver file as follows:

Starting with Windows Vista, embedding a signature in a boot-start driver file is optional for 32-bit versions of Windows. Although Windows will check if a kernel-mode driver file has an embedded signature, an embedded signature is not required.

PnP Kernel-Mode Driver that is not a Boot-Start Driver

The kernel-mode code signing policy on 64-bit versions of Windows Vista and later versions of Windows does not require a non-boot PnP driver to have an embedded signature. However, if the driver file will include an embedded signature, embed the signature in the driver file before signing the driver package’sВ catalog file.

For a PnP kernel-mode driver that is not a boot-start driver, signing the catalog file for the driver package complies with the kernel-mode code signing policy on 64-bit versions of Windows Vista and later versions of Windows, as well as the PnP device installation signing requirements for all versions of Windows Vista and later.

You can submit a request to have the Windows Hardware Quality Labs (WHQL) test-sign the catalog file. Alternatively, you can test-sign a catalog file yourself with a test certificate in the same manner as described in this section for test-signing the catalog file of a PnP kernel-mode boot-start driver.

Non-PnP Kernel-Mode Driver that is not a Boot-Start Driver

To comply with the kernel-mode code signing policy of 64-bit versions of Windows Vista and later versions of Windows, embed a signature in the driver file or sign the driver package’sВ catalog file.

Starting with Windows Vista, embedding a signature in a driver file is optional for 32-bit versions of Windows. Although Windows will check if a kernel-mode driver file has an embedded signature, an embedded signature is not required.

The PnP device installation signing requirements do not apply to non-PnP drivers.

NoteВ В Using embedded signatures is generally simpler and more efficient than using a signed catalog file. For more information about the advantages and disadvantages of using embedded signatures versus signed catalog files, see Test Signing a Driver.

Introduction to Test-Signing

Drivers should be test-signed with a digital signature during development and test for the following reasons:

To facilitate and automate installation.

If a driver is not signed, the Plug and Play (PnP) driver installation policy of Windows Vista and later versions of Windows require that a system administrator manually authorize the installation of an unsigned driver, adding an extra step to the installation process. This extra step can adversely affect the productivity of developers and testers. This requirement cannot be overridden.

To be able to load kernel-mode drivers on 64-bit versions of Windows Vista and later versions of Windows.

By default, the kernel-mode code signing policy for 64-bit versions of Windows Vista and later versions of Windows require that a kernel-mode driver be signed in order for the driver to be loaded. This requirement can be temporarily overridden to facilitate the development or debugging of a driver.

To play back certain types of next-generation premium content, all kernel-mode components in Windows Vista and later versions of Windows must be signed. In addition, all the user-mode and kernel-mode components in the Protected Media Path (PMP) must comply with PMP signing policy. For information about PMP signing policy, see the white paper Code-signing for Protected Media Components in Windows Vista.

For these reasons, drivers for Windows Vista and later versions of Windows should be test-signed with a digital certificate that is created by using Microsoft Authenticode. Such a digital certificate is referred to as a test certificate and a signature generated with a test certificate is referred to as a test signature.

NoteВ В Windows Vista and later versions of Windows support test-signed drivers only for development and testing purposes. Test signatures must not be used for production purposes or released to customers.

A development and test team can participate in the WHQL Test Signature program, where the Windows Hardware Quality Labs (WHQL) will sign PnP driver packages for testing purposes. Alternatively, a development and test team can manage their own in-house signing process and use the following types of test certificates to test-sign drivers:

MakeCert test certificate, which is a digital certificate created by the MakeCert tool.

Commercial test certificate, which is a digital certificate that is issued by a CA that is a member of the Microsoft Root Certificate Program.

Enterprise CA test certificate, which is a digital certificate that is deployed by an Enterprise CA.

For information about how a test team signs a driver package after the team creates, obtains, or is provided a test certificate, see Test-Signing Driver Packages.

For information about how to install driver packages that are test-signed, see Installing Test-Signed Driver Packages.

To facilitate early driver development and debugging, you can temporarily disable the kernel-mode code signing requirement to load and test an unsigned kernel-mode driver. However, you cannot disable the PnP driver installation policy that requires a system administrator to authorize the installation of an unsigned driver. For more information about how to install an unsigned driver, see Installing an Unsigned Driver during Development and Test.

For information about the most appropriate tools to use to test-sign driver packages, see Tools for Signing Drivers.

NoteВ В To get a better understanding of the steps that are involved in test-signing driver packages, see How to Test-Sign a Driver Package. This topic provides a summary of the test-signing process, and steps through many examples of test-signing by using the ToastPkg sample driver package within the Windows Driver Kit (WDK).