Share via

Digital Signatures for Kernel Modules on Systems Running Windows Vista

  • Article

 

Microsoft Corporation

Updated June 2007

Applies to:
   Windows Vista
   Windows Server 2008

Summary: For Microsoft Windows Vista and later versions of the Windows family of operating systems, kernel-mode software must have a digital signature to load on x64-based computer systems. Learn how to manage the signing process for kernel-mode software for Windows Vista. (22 printed pages.)

The current version of this paper is maintained on the Web at: https://www.microsoft.com/whdc/system/platform/64bit/kmsigning.mspx.

Contents

Introduction
   Digital Signatures as a Best Practice
   Kernel Mode Code Signing Options
The Kernel Mode Code Signing Process
   How to Obtain a Software Publishing Certificate (SPC)
   Creating a Signed .cat File
   Adding an Embedded Signature to a Driver Image File
How to Disable Signature Enforcement during Development
How to use Test Signing
   Enabling Test Signing Troubleshooting
   Detecting driver load errors
   Enabling Code Integrity diagnostic system log events
   Driver Verification Debugging Options
Resources

Introduction

For both consumer and enterprise users of Windows around the world, protecting personal and corporate data remains a top concern. Microsoft is committed to implementing new ways to help restrict the spread of malicious software. Digital signatures for kernel-mode software are an important way to ensure security on computer systems.

Digital signatures allow the administrator or end user who is installing Windows-based software to know whether a legitimate publisher has provided the software package. When users choose to send Windows Error Reporting data to Microsoft after a fault or other error occurs, Microsoft can analyze the data to know which publishers' software was running on the system at the time of the error. Software publishers can then use the information provided by Microsoft to find and fix problems in their software.

Windows Vista relies on digital signatures on kernel mode code to increase the safety and stability of the Microsoft Windows platform and enable new customer experiences with next generation premium content:

  • Drivers must be signed for devices that stream protected content. This includes audio drivers that use Protected User Mode Audio (PUMA) and Protected Audio Path (PAP), and video device drivers that handle protected video path-output protection management (PVP-OPM) commands.
  • Unsigned kernel-mode software will not load and will not run on x64-based systems.

Note: Even users with administrator privileges cannot load unsigned kernel-mode code on x64-based systems. This applies for any software module that loads in kernel mode, including device drivers, filter drivers, and kernel services.

The scope of the new kernel mode code signing policy is far reaching. For developers who publish kernel-mode software, this policy has the following effects:

  • For any kernel-mode component that is not already signed, publishers must obtain a Software Publishing Certificate (SPC) and use the SPC to sign all 64-bit kernel-mode software that will run on x64-based computer systems running Windows Vista. This includes kernel-mode services software.

  • Publishers who provide 64-bit device driver or other kernel-mode software that is already signed through the Windows Logo Program will have their driver catalogs signed with a Windows Hardware Quality Labs (WHQL) signature. To fully test the driver package prior to submission to WHQL, sign the driver catalog using a SPC.

  • In the special case of boot-start drivers, it is also necessary to use a SPC to embedded sign the driver binary image file for optimal system boot performance.

    Note   A driver is said to be boot-start if it is loaded by the Windows Vista operating system loader. Boot-start drivers can be identified as follows: The driver INF specifies the start type as "Start=0", or a kernel service is configured with a ServiceType as Kernel Driver or File System Driver and StartMode to be "boot."

The mandatory kernel mode code signing policy applies to all kernel-mode software on x64-based systems running Windows Vista. However, Microsoft encourages publishers to digitally sign all software, including device drivers for both 32-bit and 64-bit platforms. Windows Vista performs kernel mode signature verification on x86 systems to support protected media content. However, kernel mode driver signatures are not mandatory for 32-bit systems.

This paper describes how to manage the signing process for kernel-mode code for Windows Vista, including how to obtain a Software Publishing Certificate (SPC), guidelines for protecting keys, and how to sign a driver package using the tools provided in the Windows Driver Kit (WDK).

Digital Signatures as a Best Practice

Ever since the release of Windows 98, Microsoft has promoted driver signing for designated device classes as a mechanism to advance driver reliability, to provide a better user experience, to reduce support costs for software and hardware vendors, and to lower the total cost of ownership for customers.

For device drivers and other kernel-mode software, drivers signed as part of the Windows Logo program increase end-user confidence in the quality of the software and improve the user experience, because a Windows Logo belonging to a driver indicates that the driver was tested and the digital signature that accompanies the Windows Logo confirms has not been altered since testing.

For most kernel-mode driver packages, a digital signature is provided in a signed catalog (.cat) file. The Windows Hardware Quality Labs (WHQL) provides a Microsoft-signed .cat file to distribute with a driver package that meets the requirements of the Windows Logo program.

The process of creating signed kernel-mode software consists of two distinct but related activities. These can be done in parallel because the software usually does not have to be signed until relatively late in the development process.

  • Managing the signing process. This is typically handled by publishers' program management and software release services and includes:

    • Selecting the appropriate signing option.
    • Obtaining the necessary certificates.
    • Managing the digital signature or code signing keys.

    Note   To digitally sign image binary files or catalogs, a software publisher must have a certified code-signing key, which means that a Certificate Authority has sufficiently established the identity of the publisher.

  • Implementing the driver to be signed. This is typically handled by the publisher's development team and includes:

    • Implementing the driver itself.
    • Creating a signed driver package for internal testing or release.

These processes are documented for earlier versions of Windows in the WDK and the Platform SDK. This paper describes additional options related to kernel mode code signing for Windows Vista.

Kernel Mode Code Signing Options

There are multiple options available for working with the Kernel Mode Code Signing (KMCS) requirements in Windows Vista. Signing driver files is not required for Windows Vista to load drivers while developing kernel mode code. Instead, developers can use one of the mechanisms to temporarily disable load-time checks by the kernel on development and non-automated test systems. However, test signing of driver packages is required to automate installation of a driver package on test systems without having driver install pop-ups. The Driver Management Infrastructure (DMI) verifies the driver package signature during installation and warns users of unsigned drivers.

The following table compares options for digitally signing kernel modules supported by Windows Vista.

Options for signing kernel modules

Signing Options Functionality Verified to Meet Logo Requirements Identity Verified Intended Use
Windows Logo program Yes Yes Release
Kernel Mode Code Signing using a SPC No Yes Release
WHQL Test Signature program No Yes Testing
KMCS Test Signing No No Testing

The Windows Logo program verifies correct driver functionality and ensures high quality and reliability. Driver packages submitted to the Windows Logo program are digitally signed by Microsoft. The Windows Logo program accepts device packages that are installed via INF file for hardware that meets the Windows Logo requirements. The driver publisher submits the driver package after completing driver verification tests for the Windows Logo Program. Drivers that qualify for the logo receive a Microsoft-signed .cat file. For information about the Windows Logo Program, see the Resources section at the end of this paper.

Developers can sign the driver image file or driver catalog with a SPC for testing prior to submitting to WHQL in order to verify that the driver loads and operates correctly.

Kernel Mode Code Signing using a SPC provides identifiability of the publisher of a kernel module loading into Windows Vista. It does not provide any level of certification of functionality or reliability of the kernel module. For drivers that do not qualify for the Windows Logo, or the Windows Logo is not one of the product requirements, the publisher can create a .cat file for the driver package and sign it with the publisher's SPC.

Important   Kernel Mode Code Signing does not replace the WHQL program. Microsoft encourages publishers to use the Windows Logo program to ensure driver quality. Kernel Mode Code Signing does not require the software publisher to pass the Windows Logo Program testing requirements associated with WHQL.

A signed .cat file is all that is necessary for most driver packages to install and load correctly on x64 systems, except packages that contain a driver which is loaded by the Windows Vista boot loader. A driver package that contains a device driver that is loaded by the Windows Vista boot loader must be signed in two ways:

  • The kernel mode driver binary file that is loaded at boot time must have an embedded signature in the binary signed with a SPC. For simplicity, it may be easier to embedded sign all driver image files in the package.
  • The driver package installed using an INF file must also have a signed catalog file, just like driver packages that do not contain a boot start driver, for signature verification during installation.

Manufacturers should ensure that hardware vendors acquire a SPC and sign any boot-start drivers that will be installed on manufacturer-installed systems.

For testing purposes during the development cycle, code signing using a "test" certificate is recommended instead of signing with a release certificate. A test signed binary is only recognized by Windows Vista systems when a boot configuration option that allows use of test signing certificates is enabled. Test signing is not enabled by default and test signatures will not be trusted by the majority of Windows Vista systems.

The WHQL Test Signature program is also supported for test signing. Participants in the program can submit driver packages for WHQL Test Signing. The signature on the test signed catalogs are generated by a certificate issued under the Microsoft Test Root Authority. The Microsoft Test Root Authority is accepted when the Windows Vista boot configuration setting enables Test Signing. For information about the WHQL Test Signature Program, see the Resources section at the end of this paper.

For both "test" and "release" signing, the development team should follow best practices for key management, as described in Guidance for Safeguarding Code Signing Keys later in this paper.

Test signing is discussed in more detail in the section How to use Test Signing later in this document.

The Kernel Mode Code Signing Process

Digitally signing a kernel mode image file or catalog establishes the integrity of the signed file or files. Software modules should never be modified after the code-signing operation has been performed. Modification of the image file after code signing results in install-time and load-time signature verification failures.

A driver package containing multiple files may be signed using a catalog. The driver package must have a signed catalog (.cat) file which is used to identify the publisher when the driver package is installed and verify the driver image when it is loaded into the kernel. The catalog file contains a digital certificate that identifies the publisher, plus hashes of the contents of the package that allow the system to verify that files in the package have not been altered.

As previously mentioned, boot start drivers must have embedded signatures in the driver image file. Embedded signatures in boot start driver image files optimize operating system boot performance by eliminating the need to locate the appropriate.cat file when the operating system loader verifies the driver signature.

Driver signing is not required for every build during the driver development process. Developers can disable driver signing enforcement as described in How to Disable Signature Enforcement during Development later in this paper.

The following sections discuss how to obtain and manage certificates. The mechanics of signing driver packages are discussed later in this paper.

How to Obtain a Software Publishing Certificate (SPC)

Obtain a SPC for signing your kernel mode software that meets the mandatory kernel mode code signing policy using the following steps:

  1. Obtain a SPC from a commercial CA that issues digital certificates for signing kernel mode code. The list of CAs who provide Software Publishing Certificates (or code signing certificates) that can be used for kernel mode code signing is available at the Microsoft Cross-certificates for Windows Vista Kernel Mode Code Signing web page.
  2. Download a corresponding cross-certificate from the Microsoft Cross-certificates for Windows Vista Kernel Mode Code Signing web page for the root certificate authority who issued the SPC. The cross-certificate is used in the digital signature for kernel mode code so that the signature can be verified up to a trusted root authority known to the Windows Vista kernel.

When you request a Software Publishing Certificate from a commercial CA, follow the instructions on the CA's web site for how to acquire and install the code signing certificate on the machine where you will be using the private key to sign code.

Guidance for Safeguarding Code Signing Keys

The cryptographic keys that are at the heart of the code-signing process must be well protected and treated with the same care as the most valuable assets for any company. These keys represent a company identity. Any code that is signed with these keys appears to Windows as if it contains a valid digital signature that can be traced to the company. If the keys are stolen, they could be used to fraudulently sign malicious code and possibly result in the delivery of code that contains a Trojan or virus that appears to come from a legitimate publisher.

For a detailed information on safe guarding private keys, refer to the Code Signing Best Practices.

Using Cross-certificates with kernel mode code signing

Kernel mode code signing uses cross-certificates as part of the code signing process. A cross-certificate is an X.509 certificate issued by one Certificate Authority (CA) that signs the public key for the root certificate of another Certificate Authority. The Windows Vista operating system loader and kernel recognize cross-certificates in verifying driver signatures. The cross-certificates allow the kernel to have a single trusted Microsoft root authority, but also provide the flexibility to extend the chain of trust to multiple commercial CAs that issue Software Publisher Certificates.

Cross-certificates enable developers and publishers to use Software Publisher Certificates to sign kernel mode software. Developers who use Kernel Mode Code Signing, will download the correct cross-certificate (.cer) file to the system where the digital signature operation is performed. Publishers do not need to distribute the cross-certificate file with their software or driver package. The cross-certificate will be included with the digital signature on the driver image file or driver package catalog. Users who install the driver package will not have to do any configuration steps for Windows Vista to verify the digital signature that includes a cross-certificate.

Important   The SignTool in the Windows Vista Beta2 WDK is the only version of SignTool that currently supports adding cross-certificates to a digital signature. Previous versions of SignTool in the Windows Server 2003 Platform SDK or DDK do not support adding cross-certificates.

Cross-certificates for multiple CAs to use for kernel mode code signing are available for download from the Microsoft WHDC website. For more information, see Microsoft Cross-certificates for Windows Vista Kernel Mode Code Signing in the Resources at the end of this paper.

Details on how to add the cross-certificate to the digital signature is described in sections How to Sign a .cat File and Adding an Embedded Signature to a Driver Image File.

Generating test certificates

Test certificates are used in place of SPCs for test signing kernel mode software modules that are not for distribution or release outside your organization. Test signing is applying a digital signature to kernel mode binaries or driver package catalogs used for internal testing purposes. Test signing is discussed in more detail in the section How to use Test Signing later in this document. When using a test certificate for kernel mode code signing, a cross-certificate is not required.

Test certificates can be generated using an enterprise CA or using the Makecert utility. For more information about using an enterprise CA for issuing test signing certificates within your organization, see Code Signing Best Practices.

In the following example, Makecert generates a test certificate issued by the default test root, stores the private key in a key container, and outputs the certificate to a certificate store and a certificate file:

Makecert –r –pe –ss SubjectCertStoreName –n "CN= CertName" OutputFile.cer

The arguments to Makecert in the example do the following:

  • -r
    Creates a self-signed certificate, that is, the certificate is a root certificate.
  • -pe
    Makes the private key that is associated with the certificate exportable.
  • -ss SubjectCertStoreName
    Specifies the name of the certificate store that contains the root certificate.
  • **-n "CN=**CertName"
    Specifies a name for the certificate. If a certificate name is not supplied, the default name of the certificate is "Joe's Software Emporium".
  • OutputFile.cer
    The name of the file in which the root certificate is saved.

An example command script using makecert is available in the WDK. The script file name is, selfsign_example.txt, located under the "bin\selfsign" directory. Before you can install your driver package you must add your test certificates into the certificate store on the target test machine.

The following example shows how to add the test certificates to the Trusted Root Store and Trusted Publisher Store on the target test machine.

certmgr.exe -add OutputFile.cer -s -r localMachine root 
certmgr.exe -add OutputFile.cer -s -r localMachine trustedpublisher

The arguments to Certmgr in the example do the following:

  • -add
    Adds the certificate in the certificate file to a certificate store.
  • -s
    Indicates the certificate store is a system store.
  • -r
    Indicates the registry location of the system store is under HKEY_LOCAL_MACHINE key
  • Root or trustedpublisher
    Indicates the name of the system certificate store

For more information on Certmgr and Makecert, see the Resources at the end of this paper.

Creating a Signed .cat File

The tools used to generate and sign catalog files, MakeCat and SignTool, are provided in the Windows Vista WDK.

Note   Signtool.exe and MakeCat.exe are located in the "bin\selfsign" directory of the WDK.

How to Create a .cat File

A digitally signed .cat file contains the hashes of all kernel-mode modules that are verified when loaded into the kernel. The catalog file can also include hashes for other files in the software package, such as user-mode application programs (.exes) and application extensions (.dlls). Microsoft recommends that the .cat file contain the hashes of all files in a software package.

The .cat file contains a list of file hashes that correspond to a specified set of files. A file hash is the product of an SHA1 hash over a target file. A flat file hash is not used for files, such as drivers, that use the portable executable (PE) file format. Instead, relevant sections such as the PE header, executable data, and authenticated attributes are selectively hashed.

When a driver is loaded into memory, the Windows Vista kernel performs an SHA1 hash over the relevant sections of the driver binary image file. Windows verifies that the file has not been tampered with by comparing the resulting hash value to the list of binary hashes in the associated .cat file.

If installing the driver with an INF file via Plug and Play, use the Signability tool from the WDK to create a catalog as described below. Otherwise, manually create a catalog as described in the How to Create a Catalog Manually later in this paper.

How to Create a Catalog Using Signability

Signability is a tool that is used to validate INF files and create a catalog file based on the INF file. It is included in the WDK and can be run from the WDK build environment. Signability requires a valid INF file for your driver package. For information on creating an INF file, consult the WDK documentation. In order to create a catalog using the signability tool proceed as follows:

Using signability to create a catalog

  1. Create a driver package directory that contains all the files in your driver package.
  2. Create an INF file in your driver package directory and edit it for Windows Vista. Specifically, change the build date to 4/1/2006 or greater and the version to 6. For example: DriverVer=04/01/2006, 6.0.1.0
  3. Run Signability to create a valid .cat file based on the INF file:

    • Run Signability.exe and use the GUI to create the catalog file.

    • Run Signability from the command line. Note package_directory must be the fully qualified path to the package directory.

      Signability.exe /auto /cat /driver:package_directory /os:512

This example creates a .cat file in the driver_package directory, using several arguments that Signability supports:

  • /auto
    Configures the Signability tool to run without the need for user interaction.
  • /cat
    Configures the Signability tool to generate the catalog file whose name is supplied by the driver package INF file.
  • /driver: DriverPath
    Supplies the path to the directory that contains the driver package files.
  • /os: nnn
    Configures the Signability tool to verify that the driver package INF file complies with the requirements of the Windows versions that are specified by the flag value nnn. 512 is the value for Windows Vista, 64-bit Edition.

How to Create a Catalog Manually

To manually create a .cat file, first use a text editor to create a catalog definition file (.cdf). The .cdf file includes a list of the files that are to be cataloged and their attributes.

The following example shows the contents of a typical .cdf file that is named Good.cdf. The package to be cataloged contains two files, File1 and File2. The resulting .cat file is named Good.cat.

[CatalogHeader]
Name=Good.cat
PublicVersion=0x0000001
EncodingType=0x00010001
CATATTR1=0x10010001:OSAttr:2:6.0
[CatalogFiles]
<hash>File1=File1
<hash>File2=File2

A .cat file is created with the command-line tool MakeCat, which is included with the Platform SDK and the WDK. The MakeCat tool:

  • Verifies the list of attributes for each listed file.
  • Adds the listed attributes to the .cat file.
  • Hashes each of the listed files.
  • Stores the hashes of each file into the .cat file.

To create a .cat file

  1. Use a text editor to create a .cdf file that contains a list of files to be cataloged, with their attributes.
  2. Run MakeCat against the .cdf file.

Note   MakeCat does not modify the .cdf file.

The following example shows how to make a .cat file from Good.cdf. The -v flag specifies the verbose version of MakeCat. The hashed files and the newly generated Good.cat file are placed in the same folder as File1 and File2.

MakeCat -v Good.cdf

The .cat file is now ready to be signed.

For more information about MakeCat and the format of .cdf files, see the MakeCat documentation listed in the Resources at the end of this paper.

How to Sign a .cat File

The .cat file that is generated by MakeCat contains all the file hashes that are required to install kernel-mode modules on a user's system. However, the file must also be digitally signed.

A .cat file is signed with the command-line tool SignTool. The digital signature on the catalog, which is used to verify kernel mode image files, must contain a cross-certificate. The cross-certificate is added using a new command option to SignTool.

Important   You must use the version of SignTool from the Windows Vista Beta2 WDK to add the cross-certificate to digital signature.

The following example shows how to use Signtool to sign a .cat file with a SPC and corresponding private key that is imported into the Windows certificate store. For information about how to use Signtool with an HSM, see the SignTool documentation listed in the Resources at the end of this paper.

SignTool sign /v /ac CrossCertificateFile /s SPCCertificateStore /n SPCSubjectName /t http://timestamp.verisign.com/scripts/timestamp.dll Good.cat

This example uses several of the arguments that SignTool supports:

  • Sign
    Configures the tool to sign the .cat file that is named CatFileName.cat.
  • /v
    Specifies the verbose option for successful execution and warning messages*.*
  • /ac
    Adds the cross-certificate from the file CrossCertificateFile to the digital signature
  • /s
    Specifies a certificate store that is named SPCCertificateStore.
  • /n
    Specifies a certificate with the subject name SPCSubjectName.
  • /t URL
    Specifies that the digital signature will be timestamped by the Timestamping Authority (TSA) indicated by URL.

Important   The catalog or driver signature mist include a timestamp to provide necessary information for key revocation in case the signer's code signing private key is compromised.

During device installation, if the SPC that was used for signing has expired and the signature was not timestamped, the .cat file is not installed and Windows does not allow the driver to be loaded. However, if the signature is timestamped by a trusted Time Stamp Authority, the .cat file is installed and Windows allows the driver to be loaded.

Signing the Self-extracting Download file

Software published for distribution on a product support web site is usually packaged in a self-extracting archive file. The self-extracting executable is downloaded using a web browser, and the contents extracted before the user begins to install on their machine. Use the SPC that signed the driver package .cat file to also digitally sign the self-extracting .exe file.

Digitally signing the self-extracting .exe file identifies the publisher of the archive file and ensures the integrity of the self-extracting .exe file that gets downloaded over the Internet. Users who download the self-extracting .exe file will typically get a trust dialog, or Security Warning, when they choose to download and run the self-extracting file.

In Windows Vista, if the user looks at the details of the Security Warning dialog and selects, "Always install software from <publisher name>", this option will simplify the later confirmation when a driver package is installed. When the driver package is installed, the user will be asked if they trust the publisher of the signed driver package before the driver install begins. If the user selected the option to always install software from the driver publisher when they downloaded the self-extracting .exe file, the trust dialog prompt during driver installation will not occur.

How to Install a Signed .cat File

For drivers that are installed through Plug and Play, no changes in the installation process are expected. Installation of an embedded signed driver requires no special processing beyond the standard INF and setup mechanisms. Note that only users who are members of the Administrators group are allowed to install driver packages.

Drivers that do not install through Plug and Play must install their .cat files in the system catalog root folder. Installation of a catalog in the catalog root folder can be managed using existing Win32 catalog API calls, specifically CryptCATAdminAddCatalog.

Adding an Embedded Signature to a Driver Image File

To optimize the performance of driver verification at boot time, boot-start driver binaries must have an embedded signature using the SPC in addition to the signed .cat file for the package. The embedded signature saves significant time during operating system boot-up because there is no need for the operating system loader to locate the .cat file in the driver. A typical Windows Vista system may have over a hundred different catalog files in the catalog root store. Locating the correct catalog file to verify the image hash of a particular driver can involve a lot of system overhead searching multiple catalogs for the correct file.

Boot-start drivers are identified based on the service StartType value of SERVICE_BOOT_START (0).

Embedded signatures do not interfere with .cat file signing or validation. Note that the hashes contained in catalogs and embedded signatures selectively exclude the signature portion of the PE file format

To use Signtool.exe to embed a signature into a boot-start driver binary using a SPC and a corresponding private key imported into the Windows certificate store, use the following command:

SignTool sign /v /ac CrossCertificateFile /s SPCCertificateStore /n SPCSubjectName /t http://timestamp.verisign.com/scripts/timestamp.dll winloaddriver.sys

This example uses several of the arguments that SignTool supports:

  • Sign
    The sign command configures the tool to sign the driver named winloaddriver.sys.
  • /v
    Specifies the verbose option for successful execution and warning messages*.*
  • /ac
    Adds the cross-certificate from the file CrossCertificateFile to the digital signature
  • /s options
    Specifies the certificate store named SPCCertificateStore
  • /n
    Specifies the certificate with the subject name SPCSubjectName.
  • /t URL
    Specifies that the digital signature should be timestamped by the TSA that is indicated by URL.

Important: The catalog or driver must be timestamped, since this will provide necessary information for key revocation in case the signers key is compromised.

How to Verify an Embedded Signature

The following procedure shows how to verify an embedded signature with Windows Explorer.

To verify embedded signatures

  1. While running Windows Vista, right-click the driver .sys file and click Properties in the context menu.
  2. Click the Digital Signatures tab, if it is present.
    • If this tab is not present, the file does not have an embedded signature.
  3. Select the signer and click Details to open the Signature Details dialog box.
  4. Click View Certificate to open the certificate’s property pages.
    • Verify that there are no warning dialog boxes.
    • Verify that the certificates subject name is Publisher is registered with a recognized certification authority.
  5. Click the Certification Path tab.
    • Verify that the subject name of the top certificate is Microsoft Code Verification Root.

To verify embedded signatures using signtool.exe for kernel mode code signing policy

  • Signtool.exe can be used to verify the signature on a .cat file using the following command:
Signtool verify /kp /c tstamd64.cat toaster.sys

Verify that the image hash for the file toaster.sys is found in the catalog file. The tool returns the string "Success."

How to Disable Signature Enforcement during Development

During the early stages of development, developers can disable enforcement in Windows so that driver signing is not necessary. The following options are available for developers to disable kernel mode code signing enforcement temporarily so that Windows Vista will load an unsigned driver.

  • Attaching a kernel debugger. Attaching an active kernel debugger to the target computer disables the enforcement of kernel mode signatures in Windows Vista and allows the driver to load.

  • Using the F8 option. An F8 Advanced Boot Option introduced with Windows Vista—"Disable Driver Signature Enforcement"—is available to disable the kernel-signing enforcement only for the current boot session. This setting does not persist across boot sessions.

  • Setting the boot configuration. A boot configuration setting is available in the Windows Vista Beta2 release that disables the enforcement of kernel mode signatures to be persisted across boot sessions.

    Windows Vista includes a command-line tool, BCDedit, which can be used to set the option in Windows Vista Beta2 to disable signature checks. To use BCDedit, the user must be a member of the Administrators group on the system and run the command from an elevated command prompt. An elevated command prompt can be launched by creating a desktop shortcut to cmd.exe, and then using right-click and "Run as administrator."

    The following shows an example of running BDCedit at the command prompt:

    // Disable enforcement – no signing checks
Bcdedit.exe –set nointegritychecks ON 

// Enable enforcement – signing checks apply
Bcdedit.exe –set nointegritychecks OFF 

// Disabling integrity check on an alternate OS 
// specified by a GUID for the system ID
Bcdedit.exe –set {4518fd64-05f1-11da-b13e-00306e386aee} nointegritychecks ON

Note   The Bcdedit option to disable integrity checks is only available for loading unsigned drivers on the Windows Vista Beta2 release. For more information, see the BCD Editor FAQ on the MSDN Web site.

How to use Test Signing

Test signing provides additional options to development organizations for incorporating kernel mode code signing for pre-release software that is not ready for publication. Test signing allows the use of "test" code signing certificates to sign drivers that will load on Windows Vista when the Windows Vista boot configuration setting allows test signatures.

Test signing may be appropriate to use in the following scenarios:

  • Development teams need to test pre-release versions of a driver on test systems where it is not practical to attach a kernel debugger.
  • Automated testing of kernel mode software make it impractical to use the F8 Advanced Boot Option to temporarily disable driver signature enforcement on every machine boot cycle.

Test signing allows developers to sign pre-release versions of kernel mode binaries in such a way that Windows Vista can verify and load the signed driver. Test signing involves the following differences from normal production or release signing:

  • Certificates used for test signing can be generated using the Makecert.exe code signing tool, or issued by an Enterprise CA, instead of using a SPC issued by a commercial CA.
  • The Windows Vista boot configuration option to enable Test Signing must be enabled on the Windows Vista system that will load the test signed driver.

Development organizations can setup an enterprise PKI and issue their own test code signing certificates to use for test signing. When Windows Vista enables Test Signing, verification of the digital signature on the driver binary will accept certificates issued by any CA or Issuing authority. Test signing verifies the driver image is signed, but certificate path validation performed in kernel mode does not require the issuer to be configured as a trusted root authority. This allows organizations to use individual signatures on test binaries, based on the credentials issued for code signing within the organization. Microsoft recommends this form of deployment for test signing within the Kernel Mode Code Signing.

Using certificates generated by the makecert.exe tool is also acceptable for test signing. However, certificates generated by makecert often do not provide useful identity information and there is no way to track which individual developer created a test signed version of the pre-release binary.

Note   The Windows Vista Beta2 release only accepts test certificates generated by the makecert tool. Test code signing certificates issued by an enterprise CA for test signing is not available in Windows Vista Beta2.

The Signtool instructions in this document work the same way whether you are using a SPC, or a certificate generated by makecert utility, or using a certificate issued by an enterprise CA. The only difference will typically be the issuer and subject name in the certificate.

The WHQL Test Signature program is also supported for test signing. Participants in the program can submit driver packages for WHQL Test Signatures. The signature on the test signed catalogs are generated by a certificate issued under the Microsoft Test Root Authority. The Microsoft Test Root Authority is accepted by default on Windows Vista Beta2 as part of the beta program. In the final release of Windows Vista, the Microsoft Test Root Authority is accepted when the Windows Vista boot configuration setting enables Test Signing.

Test signed kernel mode binaries will not load on Windows Vista systems by default. The digital signatures on test signed binaries are not valid on Windows Vista systems by default because the kernel mode code signing policy does not accept and does not trust test signing certificates.

Enabling Test Signing

Use the Bcdedit command-line tool to enable test signing. To use BCDedit, the user must be a member of the Administrators group on the system and run the command from an elevated command prompt. An elevated command prompt can be launched by creating a desktop shortcut to cmd.exe, and then using right-click and "Run as administrator."

The following shows an example of running BDCedit at the command prompt:

// Accept test signed kernel mode signatures
Bcdedit.exe –set TESTSIGNING ON 

// Do not accept test signed kernel mode signatures
Bcdedit.exe –set TESTSIGNING OFF

The TESTSIGNING boot configuration option determines whether Windows Vista accepts test signed kernel mode binaries. The option is not defined by default which means digital signatures on test signed kernel mode drivers will not verify and will not load. When Windows Vista accepts test signed kernel mode binaries, some premium content that is protected may not be accessible on the system.

Troubleshooting

There are specific steps you can take to identify and troubleshoot potential problems related to verifying kernel mode code signatures. This section provides information on troubleshooting problems with driver signing enforcement. The main tools for troubleshooting driver signing problems are the following:

  • Detecting driver load errors
  • Enabling Code Integrity diagnostic system log events.

The toaster application included in the Windows Vista WDK is used as an example. The toaster application can be found in the WDK under the "src\general\toaster" directory.

Detecting driver load errors

The toaster application installs a device driver (toaster.sys), which for this example, is not signed. The symptom of a problem with the unsigned driver is that the toaster device fails to start. Using the Device Manager, you can check the status of the Toaster device and view the driver status, as shown the following screen image.

Bb530195.digitalsigskernmodules01(en-us,MSDN.10).gif

Figure 1. Unsigned driver error

The device failed to start because the device driver was not signed and kernel mode signing enforcement blocked the driver from loading into the kernel. In order to definitively identify the source of the problem, we set up the system to enable signing enforcement diagnostics as described below.

Enabling Code Integrity diagnostic system log events

Kernel mode code signing enforcement is implemented by a Windows Vista component known as Code Integrity. Code Integrity generates diagnostic events and a system audit log event when the signature of a kernel module fails to verify correctly.

  • Code Integrity Operational events are always enabled. The Operational events are Warning events when an image verification check failed when loading a kernel mode binary file.
  • Code Integrity System audit events are generated when the System audit policy is enabled. The System audit policy is not enabled by default.
  • Code Integrity Verbose events are analytic and debug Information events that show all successful image verification checks when loading kernel mode binary files. Verbose events are not enabled by default.

The Code Integrity events are viewable under the Event Viewer, which is part of the Computer Management MMC snapin. (From the Start button, right-click on Computer, and select Manage).

The Code Integrity event stream is located under the following hierarchy:

Event Viewer -> Applications and Services Logs -> Microsoft -> Windows -> CodeIntegrity

Bb530195.digitalsigskernmodules02(en-us,MSDN.10).gif

Figure 2. Code integrity events

The Code Integrity Operational log shows events generated by the kernel when a kernel mode driver fails an image verification check when the driver is loaded. The image verification failure may be due to a number of reasons, including the following:

  • The driver was unsigned, but installed on the system by an administrator and Code Integrity is not allowing the driver to load.
  • The driver was signed, but the driver image file was modified or tampered with and the modification invalidated the driver signature.
  • The system disk device may have device errors when reading the image file for the device from bad disk sectors.

An Operational log entry for an unsigned or modified driver image verification failure looks like the following example:

Bb530195.digitalsigskernmodules03(en-us,MSDN.10).gif

Figure 3. Operational log entry

The event indicates the toaster driver (toaster.sys) could not be loaded since it was unsigned (or the toaster.sys image that is trying to load is not the same one that was digitally signed by the publisher).
All Code Integrity event log messages are listed in the section Code Integrity Event Logt Messages below.

System Audit Log Events

Code Integrity generates System Audit log events corresponding to the Operational warning events when image verification of a kernel mode driver fails. The System log events are viewable in the Event Viewer under the Windows Logs, System log view.

System audit events may not be enabled on all Windows Vista systems. Use the Local Security Settings MMC snap-in to verify or enable "Audit system events" under the Local Policies, Audit Policy settings.

Informational Events in the Verbose Log

Additional Code Integrity Informational events for all kernel mode image verification checks are available using the Verbose event view. These events show successful image verification of all drivers loaded on the system.

The steps for enabling the Code Integrity Verbose event view are the following:

  1. Left click on the Operational view to display current Code Integrity events (if any).
  2. Left click on the Code Integrity node to set the focus.
  3. Right click on the Code Integrity node to get the context menu.
  4. Select View.
  5. Select Show Analytic and Debug Logs.
  6. This creates a sub-tree with two additional nodes, the Operational and the Verbose node.
  7. Right-click on the Verbose node and select Properties.
  8. Select the General sheet and select the Enable Logging option. This should enable verbose logging mode.
  9. Reboot the system to reload all kernel mode binaries.
  10. After reboot, open the Computer Management snap-in and view the Code Integrity Verbose event log.

You can check if toaster.sys is correctly signed as follows:

In this particular case, toaster.sys is a PnP driver and is named in a catalog file (tstamd64.cat in "\src\general\toaster\toastpkg\toastcd". Use the SignTool utility to verify if toaster.sys is correctly catalog signed using the following command:

Signtool verify /kp /c tstamd64.cat toaster.sys

Driver Verification Debugging Options

In some cases, developers may want to enforce mandatory kernel mode code signing policy even when a debugger is attached. An example of this is when a driver stack has an unsigned driver (such as a filter driver) that fails to load, which may invalidate the entire stack. Since attaching a debugger allows the unsigned driver to load, the problem appears to vanish as soon as the debugger is attached. Debugging this type of issue may be difficult. In order to facilitate debugging in this case, Code Integrity supports a registry key that can be set to enforce kernel mode signing enforcement even when a debugger is attached.

There are two flags defined in the registry that control Code Integrity behavior under the debugger. The flags are not defined by default.

Create registry value as follows:

Key:   HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\CI
Value:   DebugFlags      REG_DWORD

Possible values:

  • 00000001
    Results in a debug break into the debugger and unsigned driver is allowed to load with g.
  • 00000010
    CI will ignore the presence of the debugger and unsigned drivers are blocked from loading.

Any other value results in unsigned drivers loading—this is the default policy.

Code Integrity Event Log Messages

The following are Warning events logged to the Code Integrity Operational log:

  • "Code Integrity is unable to verify the image integrity of the file <file name> because file hash could not be found on the system."
  • "Code Integrity detected an unsigned driver."
  • "This event is related to Software Quality Monitoring (SQM)."

The following are Information events logged to the Code Integrity Verbose log:

  • "Code Integrity found a set of per-page image hashes for the file <file name> in a catalog <catalog name>."
  • "Code Integrity found a set of per-page image hashes for the file <file name> in the image embedded certificate."
  • "Code Integrity found a file hash for the file <file name> in a catalog <catalog name>."
  • "Code Integrity found a file hash for the file <file name> in the image embedded certificate."
  • "Code Integrity determined an unsigned kernel module <file name> is loaded into the system. Check with the publisher to see if a signed version of the kernel module is available."
  • "Code Integrity is unable to verify the image integrity of the file <file name> because the set of per-page image hashes could not be found on the system."
  • "Code Integrity is unable to verify the image integrity of the file <file name> because the set of per-page image hashes could not be found on the system. The image is allowed to load because kernel mode debugger is attached."
  • "Code Integrity is unable to verify the image integrity of the file <file name> because a file hash could not be found on the system. The image is allowed to load because kernel mode debugger is attached."
  • "Code Integrity was unable to load the <file name> catalog."
  • "Code Integrity successfully loaded the <file name> catalog."

Resources