Kernel-Mode Code Signing Walkthrough - 1
Topic: How to Release-Sign a Kernel Module

Kernel-Mode Code Signing Walkthrough

July 25, 2007 — Version 1.1c

Abstract

Kernel-mode software must be digitally signed to be loaded on x64-based versions of Windows Vista® and later versions of the Windows® family of operating systems. Boot-start drivers should be signed for all versions of Windows Vista and later. In addition, content protection policies for next-generation premium content might require signed kernel-mode software for certain configurations of x86-based systems.

The scope of the new kernel-mode code-signing policy is far reaching. It has a number of implications for publishers of kernel-mode software for Windows Vista and later versions of Windows, including:

  • Software that is not already signed.
    Publishers must obtain a software publishing certificate (SPC) and use it to sign all 64-bit kernel-mode software. This requirement includes kernel-mode services software.
  • Software that has already been signed through the Windows Logo Program.
    Publishers can have their driver package's catalog (.cat) file signed with a Windows Hardware Quality Labs (WHQL) signature. To fully test the driver package before submission to WHQL, publishers can sign the catalog file by using an SPC.
  • Boot-start drivers.
    In the special case of boot-start drivers—drivers that are loaded by the Windows Vista operating system loader—publishers must use an SPC to embedded-sign the driver binary image file. This requirement ensures optimal system boot performance.

Note: The mandatory kernel-mode code-signing policy applies to all kernel-mode software for x64-based systems that are running Windows Vista. However, Microsoft encourages publishers to digitally sign all kernel-mode software, including device drivers for both 32-bit and 64-bit platforms. Windows Vista verifies kernel-mode signatures on 32-bitsystems as required to support protected media content. For more information on support for protected media, see the white paper titled “Code Signing for Protected Media Components in Windows Vista.”

This paper provides a beginning-to-end walkthrough of how to digitally sign kernel-mode software for x64 versions of Windows Vista. This version of the document has been updated for Windows Vista Release-to-Manufacturing (RTM), and supersedes the original document based on Windows Vista Beta2.

This information applies for the following operating systems:
Windows Vista®
Windows Server®2008

Future versions of this preview information will be provided in the Windows Driver Kit.

The current version of this paper is maintained on the Web at:

References and resources discussed here are listed at the end of this paper.

Contents

Introduction

Getting Started with Code Signing

Code-Signing Tools Overview

MakeCert

CertMgr

SignTool

Capicom.dll

MakeCat

Signability

Inf2Cat

PVK2PFX

Code Sign Example Script

How to Test-Sign a Kernel Module

Step 1: Prepare the Computer for Test-Signing

Step 2: Create a Test Certificate by Using MakeCert

Step 3: Create a Catalog File for Test-Signing

Using Inf2Cat to Create a Catalog File

Using Signability to Create a Catalog File

Using MakeCat

Step 4: Test-Sign the Catalog File

Step 5: Install the Test Certificate in the Trusted Root Certification
Authorities Certificate Store

Step 6: Test-Sign a Driver Image File by Using an Embedded Signature

Boot-Start Drivers

How to Embedded-Sign a Boot-Start Driver

How to Install and Load a Test-Signed Driver Package

Preparing the Test System

Step 1: Install the Test Certificates

Step 2: Enable the Kernel-Mode Test-Signing Boot Configuration Option

Step 3: Enable Code Integrity Event Logging and System Auditing

Step 4: Reboot the Test Computer

Installing and Loading the Test-Signed Driver Package

Step 5: Copy the Test-Signed Driver Package to the Test Computer

Step 6: Install the Test-Signed Driver Package

Step 7: Verify that the Test-Signed Driver Is Operating Correctly

How to Troubleshoot Test-Signed Drivers

Using the Add Hardware Wizard

Using Device Manager

Using the Windows Security Audit Log

Using the Code Integrity Event Operational Event Log

Using Informational Events in the Code Integrity Verbose Log

How to Release-Sign a Kernel Module

Step 1: Prepare the Computer for Release-Signing

Step 2: Obtain an SPC

Step 3: Obtain a Cross-Certificate

Step 4: Create a Catalog File for Release-Signing

Using Inf2Cat to Create a Catalog File

Using Signability to Create a Catalog File

Using MakeCat

Step 5: Release-Sign the Catalog File

Step 6: Release-Sign a Driver Image File by Using an Embedded Signature

How to Install and Load a Release-Signed Driver Package

Preparing the Test Computer

Step 1: Disable the Kernel-Mode Test-Signing Boot Configuration Option

Step 2: Enable Code Integrity Event Logging and System Auditing

Step 3: Reboot the Test Computer

Installing and Loading the Release-Signed Driver Package

Step 4: Copy the Release-Signed Driver Package to the Test Computer

Step 5: Install the Release-Signed Driver Package

Step 6. Verify that the Release-Signed Driver Is Operating Correctly

How to Troubleshoot Release-Signed Drivers

Using the Add Hardware Wizard

Using Device Manager

Using the Windows Security Audit Log

Using the Code Integrity Event Operational Event Log

Using the Informational Events in the Code Integrity Verbose Log

How to Disable Signature Enforcement on a Test Computer

Resources

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.

© 2006–2007 Microsoft Corporation. All rights reserved.

Microsoft, ActiveX, Authenticode, MSDN, 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

This paper provides detailed information about how to use the Windows® code-signing tools to digitally sign kernel-mode software that is designed for Windows Vista® and later versions of Windows. The paper covers the following areas:

  • Where to obtain code-signing tools.
  • How to prepare systems to use code-signing tools to build, sign, and test kernel-mode software.
  • Detailed examples of how to use the tools to test and release-sign kernel-mode software and troubleshoot common signing-related problems.
  • How to verify the signature.
  • How to install signed kernel-mode software.
  • How to disable signature enforcement.

Getting Started with Code Signing

Several approaches can be used to build, sign, and test kernel-mode software. To become more familiar with the code-signing tools, complete all of the examples in this paper on a single computer. However, this paper assumes separate computers for each process, which is often the best option for a production environment.

  • Build computer.
    The computer that is used to build the driver package. It should be running Windows XP SP2, Windows Server® 2003, or later versions of Windows.
  • Signing computer.
    The computer that is used to sign kernel-mode code for Windows Vista. It should be running Windows XP SP2, Windows Server 2003, or later versions of Windows and should have the code-signing tools installed.
  • Test computer.
    The computer that is used to test the signed driver package. It should be running Windows Vista x64 RC1 or later versions of 64-bit Windows.

The code-signing tools are available from several sources:

  • The Platform Software Development Kit (SDK) for Windows Server 2003 contains information and tools for developing 32-bit and 64-bit Windows-based applications. Many of these tools can also be used for kernel-mode software. It is available as a free download.
  • The Windows Driver Kit (WDK) contains information and tools for developing drivers for Windows operating systems. It includes the Windows Hardware Logo tests and tools that Microsoft uses to test the stability and reliability of the Windows operating system.
  • The .NET Framework SDK contains the required information and tools to develop managed-code applications. Like the Platform SDK, it is available as a free download.

For more information, see "Resources" at the end of this paper.

Note: The tools in the Platform SDK and the WDK are not re-distributable. For more information, see the end-user license agreements (EULAs) for the Platform SDK and WDK.

The following table summarizes the sources for code signing and related tools. For links to these sites, see "Resources" at the end of this paper.

Sources for Code Signing and Related Tools

Tool / WDK / Platform SDK / Additional sources
MakeCert / WDK / SDK / .NET SDK
CertMgr / WDK / SDK / .NET SDK
SignTool / WDK / SDK
Capicom.dll v.2.1.0.1 / WDK / SDK / Download Center
MakeCat / WDK / SDK
Signability / WDK
Inf2Cat / Winqual submission tools
PVK2PFX / WDK / SDK
SelfSign_example / WDK

Code-Signing Tools Overview

The code-signing tools in the previous table are used for both test-signing and release-signing of kernel-mode code. This section briefly describes each tool. The walkthrough that follows shows how the tools are used, including examples of typical command-line arguments.

MakeCert

MakeCert generates digital certificates that can be used for test-signing. They can be either self-signed or issued and signed by the Root Agent key. Self-signed certificates are recommended for test-signing drivers. The test certificate can be placed in a file, a system certificate store, or both. The Windows Vista RC1 and RTM releases accepts test certificates that are generated by MakeCert for test-signing.

Note: Generally, certificates that are issued by a third-party certification authority (CA) to be used for production signing should not be used for test-signing. For more information, see the white paper titled “Code-Signing Best Practices.”

CertMgr

CertMgr manages certificates, certificate trust lists (CTLs), and certificate revocation lists (CRLs). The tool has three functions:

  • Displaying certificates, CTLs, and CRLs.
  • Adding certificates, CTLs, and CRLs from one certificate store to another.
  • Deleting certificates, CTLs, and CRLs from a certificate store.

SignTool

SignTool is a command-line tool that signs, verifies, and timestamps files. It can be used with Microsoft Authenticode®-supported file formats including portable executable (PE, which includes .exe, .dll, and .sys files), catalog (.cat), and cabinet (.cab) formats. SignTool verifies the following information about the signing certificate:

  • Whether it was issued by a trusted CA.
  • Whether it has been revoked.
  • Optionally, whether the certificate is valid for a specific policy.

SignTool can be used for a number of other purposes, including:

  • Verifying the files in a signed catalog file.
  • Verifying signatures against different Authenticode policies.
  • Displaying a signature’s certificate chain.
  • Displaying the SHA1 hash value of a file.
  • Displaying errors for files that did not verify.
  • Adding and removing catalog files from the catalog database.

Note: Signtool.exe depends on Capicom.dll, which is also in the bin/SelfSign folder of the WDK. If the WDK is not installed on the signing computer, be sure that it has copies of both capicom.dll and the updated Signtool.exe.

In addition, SignTool in the WDK is currently the only one that 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. For more information on cross-certificates, see the white paper titled “Microsoft Cross-Certificates for Windows Vista Kernel Mode Code Signing.”

Capicom.dll

Capicom.dll exports an API that application developers can use to add security that is based on cryptography to applications. Because SignTool uses this dynamic-link library (DLL), both files must be present on the signing computer.

MakeCat

MakeCat creates an unsigned catalog file that contains the hashes of a specified set of files along with their associated attributes. An organization can sign a single catalog file for an entire software package instead of signing numerous individual files.

Before using MakeCat, the user must use a text editor to create a catalog definition file (.cdf). This file contains the list of files to be cataloged and their attributes. The MakeCat tool:

  • Scans the .cdf file and verifies the attributes for each listed file.
  • Adds the listed attributes to the catalog file.
  • Hashes each of the listed files and stores the hash values in the catalog file.

Note: MakeCat does not modify the .cdf file.

Software consumers can use a package's signed catalog file to verify that the files they received have not been tampered with by the following methods:

  • Hashing the target files that they received.
  • Comparing the hash values for each target file to the corresponding hash values in the catalog file.
  • Verifying the signature on the catalog file.

Signability

Signability is a WDK tool for Plug and Play drivers that verifies the contents of a driver package and creates an unsigned catalog file. For driver vendors, this tool is easier to use than Makecat.exe because Signability.exe does not require a separate .cdf file. It gets the information it needs from the package's INF file.

Note: Signability is being replaced by a new tool, Inf2Cat.

Inf2Cat

Inf2Cat is a Winqual submission tool that replaces the functionality provided by Signability. For driver vendors, Inf2Cat verifies driver packages and uses the information in a driver's INF file to create an unsigned catalog file.

Note: Inf2Cat is not currently part of the WDK tools; it is installed with the Winqual Submission Tools. When the Winqual Submission Tools package is installed, Inf2Cat is placed in the Program Files (x86)\Microsoft Winqual Submission Tool folder. To add Inf2Cat to the build environment along with the other signing tools, copy Inf2cat.exe and all DLLs in the folder to the %WinDDK%\BuildNumber\bin\SelfSign folder.

PVK2PFX

PVK2PFX moves certificates and private keys that are stored in .spc and .pvk files to personal information exchange (.pfx) files.

To be used for kernel-mode code signing, a key must be stored in a .pfx file. However, some CAs use the .pvk file format to store the private key of the digital certificate and an .spc or .cer file to store the public key. In particular, Verisign Class-3 certificates are currently packaged as a pair of .pvk and .spc files. Before using such a certificate for code signing, convert the .pvk and .spc files into the .pfx format.

Note: When possible, the preferred approach is to store private keys in a hardware security module, such as a smartcard. For more information on managing private keys, see the white paper titled “Code-Signing Best Practices.”

Code Sign Example Script

The WDK contains a sample command script that shows the step-by-step procedure to correctly test-sign the sample driver package for Toaster. The example is located at WinDDK\BuildNumber\bin\selfsign\selfsign_example.cmd. The instructions in this walkthrough are concisely summarized in the example's command script.