File2=File2
A catalog file is created with the MakeCat command-line tool, 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 catalog file.
Hashes each of the listed files.
Stores the hashes of each file into the catalog file.
To create a catalog 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.
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
The catalog file is now ready to be signed.
For more information about MakeCat and the format of .cdf files, see the MakeCat documentation in “Resources” at the end of this paper.
How to Sign a Catalog File
The catalog file that MakeCat generates contains all the required file hashes to install kernel-mode modules on a user’s system. However, the file must also be digitally signed.
A catalog file is signed with the command-line SignTool (Signtool.exe). The digital signature on the catalog file, which is used to verify kernel-mode image files, must contain a cross-certificate. The cross-certificate is added by using a new command option to SignTool.
Important: You must use the version of SignTool from the WDK or the Windows Vista version of the Platform SDK to add a cross-certificate to the digital signature.
The following example shows how to use SignTool to sign a catalog file with an SPC and corresponding private key that is imported into the Windows certificate store:
SignTool sign /v /ac CrossCertificateFile /s SPCCertificateStore /n SPCSubjectName /t http://timestamp.verisign.com/scripts/timestamp.dll Good.cat
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 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 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.
Software that is published for distribution on a product support Web site is usually packaged in a self-extracting archive file. The self-extracting executable is downloaded by using a Web browser, and the contents are extracted before users begin to install the software on their machine. You can also use the SPC that signed the driver package catalog file to 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 file that is downloaded over the Internet. Users who download the file typically see a trust dialog box—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 box and selects Always install software from <publisher name>, this option simplifies the later confirmation when a driver package is installed. When the driver package is installed, user are asked if they trust the publisher of the signed driver package before the driver installation begins. If users select the option to always install software from the driver publisher when they downloaded the self-extracting .exe file, the trust dialog prompt box does not appear during driver installation.
How to Install a Signed Catalog 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 can install driver packages.
Drivers that do not install through Plug and Play must install their catalog files in the system catalog file root folder. Installation of a catalog file in the catalog file root folder can be managed by using existing Microsoft Win32® catalog file 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 that uses the SPC in addition to the signed catalog file for the package. The embedded signature saves significant time during operating system boot-up because the operating system loader is not required to locate the driver’s catalog file. A typical Windows Vista system may have over a hundred different catalog files in the catalog file 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 catalog files 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 catalog file signing or validation. Note that the hashes in catalog files and embedded signatures selectively exclude the signature portion of the PE file format.
To use SignTool to embed a signature into a boot-start driver binary by using an 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
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 named SPCSubjectName.
/t URL
Specifies that the digital signature should be timestamped by the TSA that is indicated by URL.
Important: The catalog file or driver must be timestamped because this provides necessary information for key revocation if the signer’s 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’s .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 certificate’s property pages.
Verify that there are no warning dialog boxes.
Verify that the certificate’s subject name is Publisher is registered with a recognized certification authority.
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:
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 unnecessary. The following options are available for developers to temporarily disable kernel-mode code-signing enforcement 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.
How to Use Test Signing
Test signing provides additional options to development organizations for incorporating kernel-mode code signing for prerelease 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 prerelease versions of a driver on test systems where it is not practical to attach a kernel debugger.
Automated testing of kernel-mode software makes 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 prerelease versions of kernel-mode binaries so that Windows Vista can verify and load the signed driver. Test signing involves the following differences from normal production or release signing:
Certificates for test signing can be generated by using the MakeCert code-signing tool or issued by an enterprise CA, instead of using an 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 set up an enterprise public key infrastructure (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 accepts certificates issued by any CA or issuing authority. Test signing verifies that 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 KMCS.
Using certificates generated by MakeCert is also acceptable for test signing. However, certificates generated by this tool often do not provide useful identity information and offer no way to track which individual developer created a test-signed version of the prerelease binary.
The SignTool instructions in this document work the same way whether you are using an SPC, a certificate generated by MakeCert, or a certificate issued by an enterprise CA. The only difference is typically the issuer and subject name in the certificate.
