Professional Documents
Culture Documents
Abstract
For Windows Vista and later versions of the Windows family of operating systems:
Kernel-mode software must have a digital signature before it will load on x64-based computer systems.
Certain configurations of x86 systems require kernel-mode software to have digital signatures to access
next-generation premium content depending on content protection policy.
This paper describes how to manage the signing process for kernel-mode software for Windows Vista.
This information applies for the following operating systems:
Windows Vista
Windows Server 2008
The current version of this paper is maintained on the Web at:
http://www.microsoft.com/whdc/winlogo/drvsign/kmsigning.mspx
References and resources discussed here are listed at the end of this paper.
Contents
Introduction.............................................................................................................................. 3
Digital Signatures as a Best Practice..................................................................................3
Kernel-Mode Code-Signing Options...................................................................................4
The Kernel-Mode Code-Signing Process................................................................................5
How to Obtain a Software Publishing Certificate................................................................5
Guidance for Safeguarding Code-Signing Keys.............................................................6
Using Cross-Certificates with Kernel-Mode Code Signing.............................................6
Verification During Driver Installation and Loading.........................................................7
Generating Test Certificates...........................................................................................8
Creating a Signed Catalog File...........................................................................................8
How to Create a Catalog File.........................................................................................9
How to Create a Catalog File By Using Inf2Cat.............................................................9
How to Create a Catalog File Manually........................................................................10
How to Sign a Catalog File...........................................................................................10
Signing the Self-Extracting Download file.....................................................................11
How to Install a Signed Catalog File.............................................................................11
Adding an Embedded Signature to a Driver Image File....................................................11
How to Verify an Embedded Signature.............................................................................12
How to Disable Signature Enforcement during Development................................................12
How to Use Test Signing........................................................................................................13
Using the WHQL Test Signature Program.........................................................................13
Enabling Test Signing........................................................................................................13
Troubleshooting.....................................................................................................................14
Detecting Driver Load Errors.............................................................................................14
Enabling Code Integrity Diagnostic System Log Events...................................................15
System Audit Log Events.............................................................................................16
Informational Events in the Verbose Log......................................................................16
Driver Verification Debugging Options..............................................................................17
Disclaimer
This is a preliminary document and may be changed substantially prior to final commercial release of the software described herein.
The information contained in this document represents the current view of Microsoft Corporation on the issues discussed as of the date of
publication. Because Microsoft must respond to changing market conditions, it should not be interpreted to be a commitment on the part of
Microsoft, and Microsoft cannot guarantee the accuracy of any information presented after the date of publication.
This White Paper is for informational purposes only. MICROSOFT MAKES NO WARRANTIES, EXPRESS, IMPLIED OR STATUTORY, AS TO
THE INFORMATION IN THIS DOCUMENT.
Complying with all applicable copyright laws is the responsibility of the user. Without limiting the rights under copyright, no part of this document
may be reproduced, stored in or introduced into a retrieval system, or transmitted in any form or by any means (electronic, mechanical,
photocopying, recording, or otherwise), or for any purpose, without the express written permission of Microsoft Corporation.
Microsoft may have patents, patent applications, trademarks, copyrights, or other intellectual property rights covering subject matter in this
document. Except as expressly provided in any written license agreement from Microsoft, the furnishing of this document does not give you any
license to these patents, trademarks, copyrights, or other intellectual property.
Unless otherwise noted, the example companies, organizations, products, domain names, e-mail addresses, logos, people, places and events
depicted herein are fictitious, and no association with any real company, organization, product, domain name, email address, logo, person, place
or event is intended or should be inferred.
20062007 Microsoft Corporation. All rights reserved.
Microsoft, Win32, Windows, Windows Server, and Windows Vista are either registered trademarks or trademarks of Microsoft Corporation in the
United States and/or other countries.
The names of actual companies and products mentioned herein may be the trademarks of their respective owners.
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 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 that Microsoft
provides to find and fix problems in their software.
Windows Vista relies on digital signatures for kernel-mode code to increase the safety and stability of the
Windows platform and to 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.
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 runs on x64-based computer
systems running Windows Vista. This includes kernel-mode services software.
Publishers that provide 64-bit device driver or other kernel-mode software that is already signed through
the Windows Logo Program must have their driver catalog files signed with a Windows Hardware Quality Labs
(WHQL) signature. To fully test the driver package before submission to WHQL, they must use an SPC to sign
the driver catalog file.
In the special case of boot-start drivers, publishers must use an SPC to embedded-sign the driver binary
image file for optimal system boot performance. This requirement applies to x86 and x64 versions of Windows.
A driver is said to be boot start if it is loaded by the Windows Vista operating system loader. Boot-start drivers
are identified when the driver's 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 is boot.
The kernel-mode code-signing policy applies to all kernel-mode software on x64-based systems running Windows
Vista and to boot-start drivers for both x86 and x64 systems. 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.
This paper describes how to manage the signing process for kernel-mode code for Windows Vista, including how to
obtain an SPC, guidelines for protecting keys, and how to sign a driver package by using the tools in the Windows
Driver Kit (WDK).
For most kernel-mode driver packages, a digital signature is provided in a signed catalog (.cat) file. WHQL provides
a Microsoft-signed catalog 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 is not required 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:
To digitally sign image binary files or catalog files, a software publisher must have a certified code-signing key,
which means that a certification authority (CA) has sufficiently established the identity of the publisher.
Implementing the driver to be signed. This is typically handled by the publishers development team and
includes:
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.
Functionality verified to
meet logo requirements
Yes
No
No
No
Identity
verified
Yes
Yes
Yes
No
Intended
use
Release
Release
Testing
Testing
The Windows Logo Program verifies correct driver functionality and ensures high quality and reliability. Microsoft
digitally signs the driver packages that are submitted to this program. The Windows Logo Program accepts device
packages that are installed via INF file for hardware that meets the logo requirements. The driver publisher submits
the driver package after completing driver verification tests. Drivers that qualify for the logo receive a Microsoftsigned catalog file. For information about the Windows Logo Program, see Resources at the end of this paper.
Developers can sign the driver image file or driver catalog file with an SPC for testing before submitting to WHQL to
verify that the driver loads and operates correctly.
KMCS that uses an SPC provides identifiability of the publisher of a kernel module loading into Windows Vista.
KMCS does not provide any level of certification of functionality or reliability of the kernel module. If drivers do not
qualify for the Windows logo or the logo is not one of the product requirements, the publisher can create a catalog
file for the driver package and sign it with the publishers SPC.
Important: KMCS does not replace the WHQL program. Microsoft encourages publishers to use the Windows
Logo Program to ensure driver quality. KMCS does not require the software publisher to pass the Windows Logo
Program testing requirements associated with WHQL.
A signed catalog file is all that is necessary for most driver packages to install and load correctly. The only
exception is packages that contain a boot-start driver, which is loaded by the Windows Vista boot loader. These
drivers 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 an SPC. For simplicity, it may be easier to embedded-sign all driver image files in the
package.
The driver package installed by using an INF file must also have a signed catalog filejust like driver
packages that do not contain a boot start driverfor signature verification during installation.
Manufacturers should ensure that hardware vendors acquire an 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. Windows Vista systems recognize a test-signed binary only when a boot
configuration option that allows use of test signing certificates is enabled. Test signing is not enabled by default, and
test signatures are not 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 catalog files 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
Resources 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 How to Use Test Signing later in this paper.
Figure 1. Cross-certificates
Cross-certificates enable developers and publishers to use SPCs to sign kernel-mode software. Developers who
use KMCS download the correct cross-certificate (.cer) file to the system where the digital signature operation is
performed. Publishers are not required to distribute the cross-certificate file with their software or driver package.
The cross-certificate is included with the digital signature on the driver image file or driver package catalog file.
July 25, 2007
20062007 Microsoft Corporation. All rights reserved.
Users who install the driver package are not required to do any configuration steps for Windows Vista to verify the
digital signature that includes a cross-certificate.
Important: The version of SignTool in the WDK or Windows Vista Platform SDK is the only one 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 Web site. For more information, see Microsoft Cross-certificates for Windows Vista Kernel Mode
Code Signing in Resources at the end of this paper.
Details on how to add the cross-certificate to the digital signature is described in How to Sign a Catalog File and
Adding an Embedded Signature to a Driver Image File" later in this paper.
OutputFile.cer
Denotes the name of the file in which the root certificate is saved.
An example command script that uses MakeCert is available in the WDK. The script file name
selfsign_example.txtis 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 certificate store and
the Trusted Publishers certificate 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 the Certificate Manager Tool (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 that the registry location of the system store is under the HKEY_LOCAL_MACHINE key.
Root or trustedpublisher
Indicates the name of the system certificate store.
For more information on MakeCert and CertMgr, see Resources at the end of this paper.
1. Create a driver package directory that contains all of 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 Inf2Cat to create a valid catalog file based on the INF file by using the following command:
Inf2cat.exe /driver:C:\WinDDK\6000\src\general\toaster\toastpkg\toastcd\ /os:Vista_x64
A catalog file is created with the MakeCat command-line tool, which is included with the Platform SDK and the
WDK. The MakeCat tool:
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.
MakeCat does not modify the .cdf file.
The following example shows how to make a catalog 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
For information about how to use SignTool with a hardware security module (HSM), see the documentation in
Resources at the end of this paper.
This example uses several of the arguments that SignTool supports:
Sign
Configures the tool to sign the catalog file that is named CatFileName.cat.
/v
Specifies the verbose option for successful execution and warning messages.
/ac
Adds the cross-certificate from the CrossCertificateFile file 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 Time-Stamp Authority (TSA) indicated by the
URL.
Important: The catalog file or driver signature must include a timestamp to provide necessary information for key
revocation in case the signers 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 catalog file is not installed and Windows does not allow the driver to be loaded. However, if the signature is
timestamped by a trusted TSA, the catalog file is installed and Windows allows the driver to be loaded.
1. While running Windows Vista, right-click the drivers .sys file and click Properties on the shortcut 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 certificates 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.
July 25, 2007
20062007 Microsoft Corporation. All rights reserved.
5. Click the Certification Path tab and verify that the subject name of the top certificate is Microsoft Code
Verification Root.
To verify embedded signatures by using SignTool for kernel-mode code-signing policy
SignTool can be used to verify the signature on a catalog file by using the following command:
Verify that the image hash for the file toaster.sys is found in the catalog file. The tool returns the string Success.
The TESTSIGNING boot configuration option determines whether Windows Vista accepts test-signed kernel-mode
binaries. The option is not defined by default, which means that 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
You can take specific steps 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 Toaster sample in the WDK is used as an example. It can be found in the WDK under the src\general\toaster
directory.
The event indicates that the Toaster driver (toaster.sys) could not be loaded because 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).
July 25, 2007
20062007 Microsoft Corporation. All rights reserved.
All Code Integrity event log messages are listed in Code Integrity Event Log Messages later in this paper.
1. Left-click Operational view to display current Code Integrity events (if any).
2. Left-click the Code Integrity node to set the focus.
3. Right-click the Code Integrity node, select View, and then select Show Analytic and Debug Logs on the
shortcut menu.
This creates a subtree with two additional nodes: Operational and Verbose.
4. Right-click the Verbose node and select Properties on the shortcut menu.
5. On the General tab, select the Enable Logging option. This enables verbose logging mode.
6. Close the dialog boxes and reboot the system to reload all kernel-mode binaries.
7. 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. In this case, toaster.sys is a Plug and Play driver and is named in a
catalog file (tstamd64.cat in \src\general\toaster\toastpkg\toastcd). Use SignTool to verify if toaster.sys is correctly
catalog file signed by using the following command:
Signtool verify /kp /c tstamd64.cat toaster.sys
The following are information events that are 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>
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
WHDC Web site
Code Signing for Protected Media Components in Windows Vista
http://www.microsoft.com/whdc/winlogo/drvsign/Pmp-sign.mspx
Code-Signing Best Practices
http://www.microsoft.com/whdc/winlogo/drvsign/best_practices.mspx
Debugging Tools for Windows
http://www.microsoft.com/whdc/DevTools/Debugging/default.mspx
Driver Package Integrity during Plug and Play Device Installs in Windows Vista
http://www.microsoft.com/whdc/winlogo/drvsign/pnp-driver.mspx
Kernel-Mode Code Signing Walkthrough
http://www.microsoft.com/whdc/winlogo/drvsign/kmcs_walkthrough.mspx
Microsoft Cross-Certificates for Windows Vista Kernel Mode Code Signing
http://www.microsoft.com/whdc/winlogo/drvsign/crosscert.mspx
Windows Driver Kit (WDK)
http://www.microsoft.com/whdc/driver/WDK/aboutWDK.mspx
Windows Logo Program and Driver Signing
http://www.microsoft.com/whdc/winlogo
MSDN
Certificate Creation Tool (Makecert.exe)
http://go.microsoft.com/fwlink/?LinkId=95774
Certificate Manager Tool (Certmgr.exe)
http://go.microsoft.com/fwlink/?LinkId=95775
July 25, 2007
20062007 Microsoft Corporation. All rights reserved.