DIFxApp and Catalog Files

I am working on writing a Windows kernel driver for a little project. As part of the project I decided to write a friendly .msi installer package that would install the driver along with the user-mode portions of my program. It turns out to be a surprisingly difficult/arcane task. After hours of struggling I think I finally figured out the solution. I am documenting it here so that other people can hopefully find this post and have a much easier time of it.

Note: I am using WiX 2.0.3309 and Driver Install Frameworks for Applications Version 2.0 (also known as DIFxApp 2.0) to install the drivers.

DIFxApp requires you to sign your drivers for it to install them. Actually, there is a test mode to get around that, but for most cases, you must sign them. The options for signing are to use an Authenticode certificate or a WHQL certificate once your driver passes Windows driver certification testing. I opted for the Authenticode certificate. I'll spare you the long story...

Here are the steps (simplified a bit) required to create a DIFx package with a signed catalog file.

1. Build your driver and create the .inf file for installation. Creating the .inf file is not easy either but at least there is a lot of documentation available if you search for it. I'll leave that part to you.

2. Create a .cdf file that describes the content you are cataloging. In the simple case, this is just your driver and the .inf file. Here is a simple example:

[CatalogHeader]
Name=mydrv.cat
ResultDir=.PublicVersion=0x0000001

[CatalogFiles]
<HASH>mydrv.inf=mydrv.inf
<HASH>mydrv.infATTR1=0x10010001:File:mydrv.inf
<HASH>mydrv.infATTR2=0x10010001:OSAttr:2:5.00,2:5.1,2:5.2
<HASH>mydrv.sys=mydrv.sys
<HASH>mydrv.sysATTR1=0x10010001:File:mydrv.sys
<HASH>mydrv.sysATTR2=0x10010001:OSAttr:2:5.00,2:5.1,2:5.2

3. Run makecat on the .cdf file to generate the catalog.

makecat -r -v mydrv.cdf

4. Run signtool on the catalog to add a digital signature.

signtool sign /f mycert.pfx /p password /v /a mydrv.cat

or

signtool signwizard

if you prefer.

You will probably want to put a timestamp on the catalog with the /t option as well, but it is not required.

5. Build your installer package. In my case, I am using WiX. Here is what the driver component tag looks like.

<Component Id="mydrv"
Guid="D10731D9-F126-4a70-8F79-54BC5F4C9A00"
DriverForceInstall="no" DriverSequence="0" >
<File Id="mydrvinf" Name="mydrv.inf" DiskId="1"
src="mydrv.inf" />
<File Id="mydrvsys" Name="mydrv.sys" DiskId="1"
src="mydrv.sys" />
<File Id="mydrvcat" Name="mydrv.cat" DiskId="1"
src="mydrv.cat" />
</Component>

I could not find the documentation for creating a proper .cdf file for driver signing anywhere. Also, Microsoft ships an example signed .cat file in the DIFx kit, but surprisingly, they don't include the .cdf file that was used to generate it. I worked backward from the contents of the .cat file in order to figure out how to build the proper .cdf. If someone else knows of a place where this documentation exists, I'd be interested in knowing about it. Or, if you see a mistake, feel free to correct me.