Driver Signing

Callback Technologies does not sign the CBFS Direct system driver due to the nature of the product; instead, the driver is provided in an unsigned form. Since modern versions of Windows refuse to load unsigned drivers under normal circumstances, this effectively prevents casual abuse or misuse of the product.

Therefore, it is important that you sign the provided driver files using your own code-signing certificate (one that is suitable for signing kernel mode drivers). More specifically, you will need a certificate from a Certificate Authority (CA) for which a cross-certificate exists and is available; refer to Microsoft's Cross-Certificates for Kernel Mode Code Signing article for more information. All major CAs have corresponding cross-certificates.

Getting Started

NOTE: By default, the product is installed into the Program Files directory. As a result, the scripts and instructions listed below must be run in an elevated command-line interface (CLI). To start cmd.exe (or another shell) with elevated privileges, run it using Windows Explorer's Run As Administrator command.

After installing CBFS Direct, you'll find the cbdirect.cab file in the drivers directory, which is located in the product's installation directory. This file contains the unsigned drivers and supplementary files for CBFS Direct, arranged in a directory structure suitable for use with the Install method.

In order to distribute properly signed driver files to your users, you'll need to unpack the cbdirect.cab file, sign each of the files that it contains as described below, and then re-create cbdirect.cab, placing the now-signed files into it. The sign_drivers.cmd script included with the product helps automate this task; its usage is described below.

The tools mentioned in this topic (i.e., inf2cat.exe and signtool.exe) are included in the Windows Kit, which is installed with Visual Studio and many other development tools. Also, it can be downloaded for free from the Microsoft's website. makecab.exe is the Windows system utility.

Scripts and Supplementary Files

Within the INSTALL_DIR\drivers\scripts directory, you'll find a number of files used in the signing process. The *.ddf and *.inf files are used in the process of creating a CAB file for submission, as described in "Signing Driver Files for Windows 10" section, below. The various *.cmd scripts help automate the signing procedures and the creation of the final CAB File.

In order to use the scripts, you'll first need to specify certain paths and certificate properties in the set_env.cmd script so that all files and certificates are found correctly by external tools (i.e., inf2cat.exe, signtool.exe, and makecab.exe). Specifically, you'll need to set the following variables in set_env.cmd:

  • CBTBASE: the path to the product's files. The default value should be sufficient unless the scripts have been moved, or the product's directory structure has been modified.
  • SIGN_SHA1_HASH and SIGN_SHA256_HASH: the SHA1 hashes of your SHA1 and SHA256 code signing certificates, respectively.
  • CERTPATH: the path of the root certificate file used to countersign your code signing certificates.
  • WINKITDIR: the path to the Windows SDK. By default, this variable is set to the path to the Windows 10 SDK on 64-bit machines.
  • SIGNTOOLDIR: the path to the signtool.exe utility. The signtool.exe utility is included in Windows 10 SDK, but the exact path will differ depending on the build number of the SDK that you have installed; the script will warn you if the default path must be changed.
  • INF2CATDIR: the path to the inf2cat.exe utility. The inf2cat.exe utility is included in Windows 10 SDK, but the exact path will differ depending on the build number of the SDK that you have installed; the script will warn you if the default path must be changed.
  • SEVENZIPPATH: the path to the 7zip executable (including the EXE name). 7zip is used to extract the signed driver files from the ZIP file that Microsoft provides for download. You can use another unzip utility if you wish, but you'll likely need to modify the relevant commands in the prepare_sign_new.cmd script if you do.

The sign_drivers.cmd script is designed to do everything for you. It unpacks the provided CAB file (i.e., the one with the unsigned driver files), and then calls the other scripts in the correct order. The other scripts are:

  • prepare_sign_new.cmd: performs the new-style signing process for Windows 10. See the "Signing Driver Files for Windows 10" section, below, for more information (please note that this process includes manual steps).
  • prepare_sign_old.cmd: performs the old-style signing process for Windows Vista, 7, and 8.x. See the "Signing the Driver Files for Previous Versions of Windows" section, below, for details.
  • prepare_cab.cmd: builds the final CAB file (i.e., the one containing the signed driver files) suitable for use with the Install method. The final CAB file will be named cbdirect_signed.cab.
  • sign_distro_drv.cmd: is called by the other scripts to actually sign files using your certificates; it should not be called directly.

Signing Driver Files for Windows 10

To sign the drivers for use with Windows 10, you'll need to obtain an Extended Validation (EV) code signing certificate and register it with Microsoft for kernel-mode signing; refer to Microsoft's Driver Signing Policy article for more information. Then, either use the provided scripts, or follow these steps (adapted from Microsoft's Attestation Signing a Kernel Driver for Public Release article):

  1. Ensure that the cbdirect.cab file's contents have been unpacked into the INSTALL_DIR\drivers\scripts directory.
  2. Create a new CAB file for submission (this is different from the CAB unpacked in step 1). To do this, run the prepare_sign_new.cmd script in the INSTALL_DIR\drivers\scripts directory; it performs the following steps:
    1. Creates a CAB File for submission to Microsoft:
      makecab.exe /V3 /D "ver"="20" /F cbdirect_ms.ddf
    2. Signs the newly-created CAB file with your EV certificate using the following command (any recent version of signtool.exe will work):
      %SIGNTOOLDIR%\signtool.exe sign /T http://timestamp.globalsign.com/scripts/timstamp.dll /n "your-cert-subject" cbdirect.cab
    3. Opens the Microsoft Partner Center, and then pauses so that you can do steps 4-8 manually:
    4. On the opened page, create a driver signing submission by filling in the form fields as follows:
      • File: Upload the cbdirect.cab file created in step 2 (not the one included with the product).
      • Product name: A name of your choosing which is used to identify this driver signing submission.
      • Perform test-signing ...: Leave unchecked.
      • Requested Signatures: All checkboxes must be checked.
      Then, click the "Submit" button.
    5. The signing process will be displayed at the top of the page.
    6. In the "Distribution" section, none of the actions are required.
    7. After signing is complete (i.e., when the progress reaches the "Finalize" stage), a Signed_XXXXXXX.zip file will be available for downloading. This ZIP file will contain the signed driver files for all architectures. To download the ZIP file, click the "More" link in the "Packages and signing properties" section of the page, then click the "Download signed files" button.
    8. Save the ZIP file to the same directory where the previously-submitted CAB file is (i.e., INSTALL_DIR\drivers\scripts\Sign), then continue the script.
    9. The script will finish by unpacking the downloaded ZIP file's contents.
  3. After the ZIP file is unpacked, you may proceed with preparation of the final CAB file (i.e., the one that will be distributed to end-users). Refer to the "Creation of Installation CAB File" section, below.

Signing the Driver Files for Previous Versions of Windows

To sign the driver files for use with versions of Windows prior to Windows 10:

  1. Ensure that the cbdirect.cab file's contents have been unpacked into the INSTALL_DIR\drivers\scripts directory.
  2. Run the prepare_sign_old.cmd script in the INSTALL_DIR\drivers\scripts directory. This script calls sign_distro_drv.cmd script, which uses signtool.exe to sign drivers directly.

Producing Binaries Compatible with All Supported Versions of Windows

There are two options for producing binaries that are compatible with all supported versions of Windows (i.e., 10, 8.x, 7, and Vista):

  1. The first option is to sign the driver files using the new-style signing process, and then sign them again using the old-style signing process. Drivers signed in this fashion will cause Windows 10 to show an information dialog to the user when they're installed.
  2. The second option is to sign separate sets for Windows 10 and previous versions of Windows. In this case, the drivers signed for Windows 10 can be installed without any information dialogs being shown, but you'll need to be sure to install the drivers signed with the old-style process for previous versions of Windows.

Creation of Installation CAB File

The final CAB can be prepared by running the prepare_cab.cmd script in the INSTALL_DIR\drivers\scripts directory. The sign_drivers.cmd script will make this call for you automatically.

 
 
Copyright (c) 2021 Callback Technologies, Inc. - All rights reserved.
CBFS Direct 2020 C++ Edition - Version 20.0 [Build 7836]