Jungo WinDriver  
Official Documentation
Chapter 17: Driver Installation — Advanced Issues

17.1. Windows INF Files

Device information (INF) files are text files that provide information used by the Windows Plug-and-Play mechanism to install software that supports a given hardware device. INF files are required for hardware that identifies itself, such as USB and PCI. An INF file includes all necessary information about a device and the files to be installed. When hardware manufacturers introduce new products, they must create INF files to explicitly define the resources and files required for each class of device.

In some cases, the INF file for your specific device is supplied by the operating system. In other cases, you will need to create an INF file for your device. WinDriver's DriverWizard can generate a specific INF file for your device. The INF file is used to notify the operating system that WinDriver now handles the selected device.

For USB devices, you will not be able to access the device with WinDriver (either from DriverWizard or from the code) without first registering the device to work with windrvr1630.sys. This is done by installing an INF file for the device. DriverWizard will offer to automatically generate the INF file for your device.

You can use DriverWizard to generate the INF file on the development machine and then install the INF file on any machine to which you distribute the driver, as explained in the following sections.

17.1.1. Why Should I Create an INF File?

We recommend creating an INF file for the following reasons:

  • To bind the WinDriver kernel module to a specific device.
  • To override the existing driver (if any).
  • To enable WinDriver applications and DriverWizard to access a device.

17.1.2. How Do I Install an INF File When No Driver Exists?

You must have administrative privileges in order to install an INF file.

You can use the wdreg utility with the install command to automatically install the INF file:

wdreg -inf <path to the INF file> install

On the development PC, you can have the INF file automatically installed when selecting to generate the INF file with DriverWizard, by checking the Automatically Install the INF file option in the DriverWizard's INF generation window (refer to 6.2. DriverWizard Walkthrough).

On the development PC, you can also use the wdreg_frontned utility to install/uninstall INFs and perform other advanced tasks.

It is also possible to install the INF file manually, using either of the following methods:

  • Windows Found New Hardware Wizard: this wizard is activated when the device is plugged in or, if the device was already connected, when scanning for hardware changes from the Device Manager.
  • Windows Add/Remove Hardware Wizard: right-click the mouse on My Computer, select Properties, choose the Hardware tab and click on Hardware Wizard....
  • Windows Upgrade Device Driver Wizard: locate the device in the Device Manager devices list and select the Update Driver... option from the right-click mouse menu or from the Device Manager's Action menu.

In all the manual installation methods above you will need to point Windows to the location of the relevant INF file during the installation.

We recommend using the wdreg utility to install the INF file automatically, instead of installing it manually.

If the installation fails with an ERROR_FILE_NOT_FOUND error, inspect the Windows registry to see if the RunOnce key exists in HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion. This registry key is required by Windows Plug-and-Play in order to properly install drivers using INF files. If the RunOnce key is missing, create it; then try installing the INF file again.

17.1.3. How Do I Replace an Existing Driver Using the INF File?

You must have administrative privileges in order to replace a driver.

  • Install your INF file.

You can use the wdreg utility with the install command to automatically install the INF file:

wdreg -inf <path to INF file> install

On the development PC, you can have the INF file automatically installed when selecting to generate the INF file with DriverWizard, by checking the Automatically Install the INF file option in the DriverWizard's INF generation window. On the development PC, you can also use the wdreg_frontned utility to install/uninstall INFs and perform other advanced tasks.

It is also possible to install the INF file manually, using either of the following methods:

  • Windows Found New Hardware Wizard: this wizard is activated when the device is plugged in or, if the device was already connected, when scanning for hardware changes from the Device Manager.
  • Windows Add/Remove Hardware Wizard: right-click on My Computer, select Properties, choose the Hardware tab and click on Hardware Wizard....
  • Windows Upgrade Device Driver Wizard: locate the device in the Device Manager devices list and select the Update Driver... option from the right-click mouse menu or from the Device Manager's Action menu.

In the manual installation methods above you will need to point Windows to the location of the relevant INF file during the installation. If the installation wizard offers to install an INF file other than the one you have generated, select Install one of the other drivers and choose your specific INF file from the list.

We recommend using the wdreg utility to install the INF file automatically, instead of installing it manually.

If the installation fails with an ERROR_FILE_NOT_FOUND error, inspect the Windows registry to see if the RunOnce key exists in HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion. This registry key is required by Windows Plug-and-Play in order to properly install drivers using INF files. If the RunOnce key is missing, create it; then try installing the INF file again.

17.2. Renaming the WinDriver Kernel Driver

The WinDriver APIs are implemented within the WinDriver kernel driver module (windrvr1630.sys/.dll/.ko — depending on the OS), which provides the main driver functionality and enables you to code your specific driver logic from the user mode.

On Windows and Linux you can change the name of the WinDriver kernel module to your preferred driver name, and then distribute the renamed driver instead of the default kernel module — windrvr1630.sys/.dll/.ko. The following sections explain how to rename the driver for each of the supported operating systems.

For information on how to use the Debug Monitor to log debug messages from your renamed driver, refer to 8.2.1.3. Running wddebug_gui for a Renamed Driver : Running wddebug_gui for a Renamed Driver.

A renamed WinDriver kernel driver can be installed on the same machine as the original kernel module. You can also install multiple renamed WinDriver drivers on the same machine, simultaneously.

💡 Recommendation

‍Try to give your driver a unique name in order to avoid a potential conflict with other drivers on the target machine on which your driver will be installed.

17.2.1. Windows Driver Renaming

DriverWizard automates most of the work of renaming the Windows WinDriver kernel driver — windrvr1630.sys.

When renaming the driver, the CPU architecture (32-/64-bit) of the development platform and its WinDriver installation, should match the target platform.

Renaming the signed windrvr1630.sys driver nullifies its signature. In such cases you can select either to sign your new driver, or to distribute an unsigned driver. For more information on driver signing and certification, refer to 17.3. Windows Digital Driver Signing and Certification. For guidelines for signing and certifying your renamed driver, refer to 17.3.2. Driver Signing and Certification of WinDriver-Based Drivers.

⚠ Attention

‍References to xxx in this section should be replaced with the name of your generated DriverWizard driver project.

To rename your Windows WinDriver kernel driver, follow these steps:

  • Use the DriverWizard utility to generate driver code for your hardware on Windows (refer to 6.2. DriverWizard Walkthrough), using your preferred driver name (xxx) as the name of the generated driver project. The generated project directory (xxx) will include an xxx_installation directory with the following files and directories:
    • redist directory:
      File                                      Description
      xxx.sys Your new driver, which is actually a renamed copy of the windrvr1630.sys driver. The properties of the generated driver file (such as the file's version, company name, etc.) are identical to the properties of the original windrvr1630.sys driver. You can rebuild the driver with new properties using the files from the generated xxx_installation\sys directory, as explained below.
      xxx_driver.inf A modified version of the windrvr1630.inf file, which will be used to install your new xxx.sys driver. You can make additional modifications to this file, if you wish — namely, changing the string definitions and/or comments in the file.
      xxx_device.inf A modified version of the standard generated DriverWizard INF file for your device, which registers your device with your driver (xxx.sys).You can make additional modifications to this file, if you wish, such as changing the manufacturer or driver provider strings.
      wdapi1630.dll A copy of the WinDriver-API DLL. The DLL is copied here in order to simplify the driver distribution, allowing you to use the generated xxx\redist directory as the main installation directory for your driver, instead of the original WinDriver\redist directory.
      wdreg.exe, wdreg_gui.exe, and devcon.exe Copies of the CUI and GUI versions of the wdreg WinDriver driver installation utility, and the Device Console app required by this utility, (respectively). These files are copied from the WinDriver\util directory, to simplify the installation of the renamed driver.
      xxx_install.bat An installation script that executes the wdreg commands for installing the xxx_driver.inf and xxx_device.inf files. This script is designed to simplify the installation of the renamed xxx_driver.sys driver, and the registration of your device with this driver.
    • sys directory:
      This directory contains files for advanced users, who wish to change the properties of their driver file. Changing the file's properties requires rebuilding of the driver module using the Windows Driver Kit (WDK).
      To modify the properties of your xxx.sys driver file:
      • Verify that you have WDK 8 or above and its corresponding Windows SDK installed on your development PC.
      • Modify the xxx.rc resources file in the generated sys directory in order to set different driver file properties.
      • Compile xxx.vcxproj with MsBuild or Visual Studio.
      • After rebuilding the xxx.sys driver, copy the new driver file to the generated xxx_installation\redist directory.
  • Verify that your user-mode application calls the WD_DriverName() function with your new driver name before calling any other WinDriver function. Note that the sample and generated DriverWizard WinDriver applications already include a call to this function, but with the default driver name (windrvr1630), so all you need to do is replace the driver name that is passed to the function in the code with your new driver name.
  • Verify that your user-mode driver project is built with the WD_DRIVER_NAME_CHANGE preprocessor flag (e.g., -DWD_DRIVER_NAME_CHANGE). Note: The sample and generated DriverWizard WinDriver kernel projects/makefiles already set this preprocessor flag by default.
  • Install your new driver by following the instructions in 15.2. Windows Driver Distribution of the manual, using the modified files from the generated xxx_installation directory instead of the installation files from the original WinDriver distribution. Note that you can use the generated xxx_install.bat installation script to simplify the installation.

17.2.1.1 Rebuilding with Custom Version Information (Windows)

WinDriver for Windows allows building your driver with custom version information (Provider, Date, Version, etc…). This information can be seen upon entering the Device Properties of your device in the Device Manager or by right-clicking the driver binary and selecting the “Details” tab.

Visual Studio is required in order to perform the following procedure. In the following instructions xxx stands for your generated driver name.

  • In your generated code folder go to the xxx_installation\sys subfolder.
  • Edit xxx.rc and modify the details in it to suit your needs.
  • Open the xxx.vcxproj with Visual Studio and build the project. Make sure you compile the driver in Release configuration for your platform (32 or 64 bits).
  • The resulting xxx.sys file should include your custom version information.

17.2.1.2 Changing the Details of Your Driver in the Device Manager and Pnputil (Windows)

In order to change the details of your driver as they appear in the Device Manager and pnputil utility, several lines in the driver's device and driver .inf files must be edited. Each change affects a different field, as can be seen in the table below:

Line File Affected Fields Device / Driver Instance
Class="YOUR CLASS" ClassGuid=<Your GUID> xxx_device.inf
xxx_driver.inf
* Device Manager>Properties>Details>Property>Class
* Device Manager>Properties>Details>Property>Class Description
* pnputil /enum-devices -> Class Name
Both
jun="YOUR DEVICE PROVIDER" xxx_device.inf * Device Manager>Properties>Driver>Driver Provider
* Device Manager>Properties>Details>Property>Provider
Device
Mfg="YOUR DEVICE MANUFACTURER" xxx_device.inf * Device Manager>Properties>General>Manufacturer
* Device Manager>Properties>Details>Property>Manufacturer
* pnputil /enum-devices -> Manufacturer Name (device instance only)
Device
HKR,,,,"YOUR DEVICE TYPE" xxx_driver.inf * Driver subfolder in the Device Manager
* Device Manager>Properties>General>Device Type
* Device Manager>Properties>Details>Property>Class Name
* Device Manager>Properties>Details>Property>Display Name
Both
MFGNAME="YOUR MANUFACTURER" xxx_driver.inf * Device Manager>Properties>Driver>Driver Provider
* Device Manager>Properties>General>Manufacturer
* Device Manager>Properties>Details>Property>Provider
* Device Manager>Properties>Details>Property>Manufacturer
* pnputil /enum-devices -> Manufacturer Name (driver instance only)
Driver

⚠ Attention

‍A unique GUID must be generated for the field ClassGuid. This GUID can be generated in https://www.guidgenerator.com/ or similar sites.


Device and Driver Instances in the Subfolder in Device Manager


Device and Driver Instance Details in Pnputil


17.2.2. Linux Driver Renaming

DriverWizard automates most of the work of renaming the Linux WinDriver kernel driver — windrvr1630.ko.

⚠ Attention

‍References to xxx in this section should be replaced with the name of your generated DriverWizard driver project.

To rename your Linux WinDriver kernel driver, follow these steps:

  • Use the DriverWizard utility to generate driver code for your hardware on Linux
    (refer to 6.2. DriverWizard Walkthrough), using your preferred driver name (xxx) as the name of the generated driver project. The generated project directory (xxx) will include an xxx_installation directory with the following files and directories:

redist directory: This directory contains copies of the files from the original WinDriver/redist installation directory, but with the required modifications for building your xxx.ko driver instead of windrvr1630.ko. lib and include directories: Copies of the library and include directories from the original WinDriver distribution. These copies are created since the supported Linux WinDriver kernel driver build method relies on the existence of these directories directly under the same parent directory as the redist directory.

  • Verify that your user-mode application calls the WD_DriverName() function with your new driver name before calling any other WinDriver function. Note that the sample and generated DriverWizard WinDriver applications already include a call to this function, but with the default driver name (windrvr1630), so all you need to do is replace the driver name that is passed to the function in the code with your new driver name.
  • Verify that your user-mode driver project is built with the WD_DRIVER_NAME_CHANGE preprocessor flag (-DWD_DRIVER_NAME_CHANGE). Note that the sample and generated DriverWizard WinDriver kernel projects/makefiles already set this preprocessor flag by default. If you have created a Kernel PlugIn driver, you will need to add this flag by uncommenting the following line in the Kernel PlugIn driver's configuration script:
# ADDITIONAL_FLAGS="-DWD_DRIVER_NAME_CHANGE"
  • Install your new driver by following the instructions in 15.3. Linux Driver Distribution of the manual, using the modified files from the generated xxx_installation directory instead of the installation files from the original WinDriver distribution.

As part of the installation, build your new kernel driver module(s) by following the instructions in
15.3. Linux Driver Distribution, using the files from your new installation directory.

17.3. Windows Digital Driver Signing and Certification

17.3.1. Windows Digital Driver Signing and Certification Overview

Before distributing your driver, you may digitally sign it using Microsoft's Authenticode mechanism, and/or certify it by submitting it to Microsoft's Windows Certification Program (HLK/HCK/WLP).

Some Windows operating systems, do not require installed drivers to be digitally signed or certified. Only a popup with a warning will appear. There are, however, advantages to getting your driver digitally signed or fully certified, including the following:

  • Driver installation on systems where installing unsigned drivers has been blocked.
  • Avoiding warnings during driver installation.
  • Full pre-installation of INF files.

64-bit versions of Windows 8 and higher require Kernel-Mode Code Signing (KMCS) of software that loads in kernel mode. This has the following implications for WinDriver-based drivers:

  • Drivers that are installed via an INF file must be distributed together with a signed catalog file. During driver development, please configure your Windows OS to temporarily allow the installation of unsigned drivers.

For more information about digital driver signing and certification, refer to the following documentation in the Microsoft Development Network (MSDN) library:

  • Driver Signing Requirements for Windows.
  • Introduction to Code Signing.
  • Digital Signatures for Kernel Modules on Windows.

This white paper contains information about kernel-mode code signing, test signing, and disabling signature enforcement during development.

Some of the documentation may still use old terminology. For example, references to the Windows Logo Program (WLP) or to the Windows Hardware Quality Labs (WHQL) or to the Windows Certification Program or to the Windows Hardware Certification Kit (HCK) should be replaced with the Windows Hardware Lab Kit (HLK), and references to the Windows Quality Online Services (Winqual) should be replaced with the Windows Dev Center Hardware Dashboard Services (the Hardware Dashboard).

17.3.1.1. Authenticode Driver Signature

The Microsoft Authenticode mechanism verifies the authenticity of a driver's provider. It allows driver developers to include information about themselves and their code with their programs through the use of digital signatures, and informs users of the driver that the driver's publisher is participating in an infrastructure of trusted entities.

The Authenticode signature does not, however, guarantee the code's safety or functionality.

The WinDriver\redist\windrvr1630.sys driver has an Authenticode digital signature.

17.3.1.2. Windows Certification Program

Microsoft's Windows Certification Program (previously known as the Windows Logo Program (WLP)), lays out procedures for submitting hardware and software modules, including drivers, for Microsoft quality assurance tests. Passing the tests qualifies the hardware/software for Microsoft certification, which verifies both the driver provider's authenticity and the driver's safety and functionality.

To digitally sign and certify a device driver, a Windows Hardware Lab Kit (HLK) package, which includes the driver and the related hardware, should be submitted to the Windows Certification Program for testing, using the Windows Dev Center Hardware Dashboard Services (the Hardware Dashboard).

Jungo's professional services unit provides a complete Windows driver certification service for Jungo-based drivers. Professional engineers efficiently perform all the tests required by the Windows Certification Program, relieving customers of the expense and stress of in-house testing. Jungo prepares an HLK / HCK submission package containing the test results, and delivers the package to the customer, ready for submission to Microsoft.

For more information, refer to https://www.jungo.com/st/services/windows_drivers_certification/.

For detailed information regarding Microsoft's Windows Certification Program and the certification process, refer to the MSDN Windows Hardware Certification page — https://msdn.microsoft.com/library/windows/hardware/gg463010.aspx — and to the documentation referenced from that page, including the MSDN Windows Dev Center — Hardware Dashboard Services page — https://msdn.microsoft.com/library/windows/hardware/gg463091.

17.3.2. Driver Signing and Certification of WinDriver-Based Drivers

As indicated above, The WinDriver\redist\windrvr1630.sys driver has an embedded Authenticode signature. Since WinDriver's kernel module (windrvr1630.sys) is a generic driver, which can be used as a driver for different types of hardware devices, it cannot be submitted to Microsoft's Windows Certification Program as a standalone driver. However, once you have used WinDriver to develop a Windows driver for your selected hardware, you can submit both the hardware and driver for Microsoft certification, as explained below.

The driver certification and signature procedures — either via Authenticode or the Windows Certification Program — require the creation of a catalog file for the driver. This file is a sort of hash, which describes other files. The signed windrvr1630.sys driver is provided with a matching catalog file — WinDriver\redist\windrvr1630.cat. This file is assigned to the CatalogFile entry in the windrvr1630.inf file (provided as well in the redist directory). This entry is used to inform Windows of the driver's signature and the relevant catalog file during the driver's installation.

When the name, contents, or even the date of the files described in a driver's catalog file is modified, the catalog file, and consequently the driver signature associated with it, become invalid. Therefore, if you select to rename the windrvr1630.sys driver (17.2. Renaming the WinDriver Kernel Driver) and/or the related windrvr1630.inf file, the windrvr1630.cat catalog file and the related driver signature will become invalid.

In addition, when using WinDriver to develop a driver for your Plug-and-Play device, you normally also create a device-specific INF file that registers your device to work with the windrvr1630.sys driver module (or a renamed version of this driver). Since this INF file is created at your site, for your specific hardware, it is not referenced from the windrvr1630.cat catalog file and cannot be signed by Jungo a priori.

When renaming windrvr1630.sys and/or creating a device-specific INF file for your device, you have two alternative options regarding your driver's digital signing:

  • Do not digitally sign your driver. If you select this option, remove or comment-out the reference to the windrvr1630.cat file from the windrvr1630.inf file (or your renamed version of this file).
  • Submit your driver to the Windows Certification Program, or have it Authenticode signed.

Note that while renaming WinDriver\redist\windrvr1630.sys nullifies the driver's digital signature, the driver is still compliant with the certification requirements of the Windows Certification Program.

To digitally sign/certify your driver, follow these steps:

  • Create a new catalog file for your driver, as explained in the Windows Certification Program documentation. The new file should reference both windrvr1630.sys (or your renamed driver) and any INF files used in your driver's installation.
  • Assign the name of your new catalog file to the CatalogFile entry in your driver's INF file(s). (You can either change the CatalogFile entry in the windrvr1630.inf file to refer to your new catalog file, and add a similar entry in your device-specific INF file; or incorporate both windrvr1630.inf and your device INF file into a single INF file that contains such a CatalogFile entry).
  • Submit your driver to Microsoft's Windows Certification Program or for an Authenticode signature. If you wish to submit your driver to the Windows Certification Program, refer to the additional guidelines in 17.3.2.1. HCK/HLK Test Notes.

Many WinDriver customers have already successfully digitally signed and certified their WinDriver-based drivers.

17.3.2.1. HCK/HLK Test Notes

As indicated in Microsoft's documentation, before submitting the driver for testing and certification you need to download the Windows Hardware Certification Kit (HCK) (for Windows 8) or the Windows Hardware Lab Kit (HLK) (for Windows 10), and run the relevant tests for your hardware/software. After you have verified that you can successfully pass the HCK/HLK tests, create the required logs package and proceed according to Microsoft's documentation.

For more information, refer to the MSDN Windows Hardware Certification Kit (HCK) page — https://msdn.microsoft.com/library/windows/hardware/hh833788.

17.3.3. Secure Boot and Driver Development

Secure boot is a security standard developed by Microsoft to help make sure that a PC boots using only software that is trusted by the Original Equipment Manufacturer (OEM). When the PC starts, the firmware checks the signature of each piece of boot software (UEFI, EFI apps, etc.) and blocks the loading of unsigned drivers.

⚠ Attention

‍Disabling Secure Boot and Digital signature enforcement is recommended during driver development and testing. However, a signed driver (Attestation Signing or HLK/WHQL) is required in order to install the driver after it has been distributed.

You can check if Secure Boot is enabled on your system by following one of the procedures below:

17.3.3.1. Through System Information

  • Press on Windows + R to open Run window.

Run window

  • Run msinfo32.exe to open the system information.
  • Look for “Secure Boot State and check its status under “System Summary”.

System Information

  • If the state is “Off” / “Unsupported” or if “Secure Boot State” is not listed under “System Summary” – that means that Secure Boot is disabled.

17.3.3.2. Through PowerShell

  • Open PowerShell with administrator privileges.
  • Enter the command Confirm-SecureBootUEFI and press Enter.

PowerShell

  • Any result other than True means that Secure Boot is disabled

17.3.3.3. Through WinDriver User-Mode API

Starting from WinDriver 12.8 the user-mode API (e.g. wdapi1280.dll)
includes the function check_secureBoot_enabled() that can be used as follows:

DWORD dwStatus = check_secureBoot_enabled();
if (dwStatus == WD_STATUS_SUCCESS)
printf("Secure Boot is enabled");
else
printf("Secure Boot is disabled / unsupported");
@ WD_STATUS_SUCCESS
[0] Operation completed successfully
Definition: windrvr.h:1066
DWORD DLLCALLCONV check_secureBoot_enabled(void)
Checks whether the Secure Boot feature is enabled on the system.

17.3.3.4. Disabling Secure Boot

In order to install and load unsigned drivers Secure Boot must be disabled.

Secure Boot can be disabled as follows:

  • Open PC BIOS menu (this can be done by restarting your PC).
  • Find the Secure Boot setting (usually under “Boot Manager”) and set it to “Disabled”.
  • Save the settings and Exit. PC will reboot.

For more information on Secure Boot setting, please see Microsoft Documentation.

17.3.4. Temporary disabling digital signature enforcement in Windows 10

Windows 10 (and other Windows versions) requires kernel drivers to be digitally signed. The WinDriver virtual device, which is installed during WinDriver installation process, is digitally signed. However, INF files that are generated by the DriverWizard utility are not signed and therefore will fail to install on Windows 10. In order to install them, it is required to digitally sign them. To bypass this requirement, it is possible to temporarily disable digital driver signing enforcement and install your INF file while the enforcement is disabled.

You can do this by following the procedure below:

  • Click on the Start menu button.
  • Hold down the Shift button in the keyboard, and click the Power icon on the left side of the Start menu.
  • From the menu that will open, choose Restart.
  • In the screen that will open, choose Troubleshoot.
  • Choose Advanced options.
  • Choose Start-up Settings.
  • The computer will restart and load a Startup Settings screen. Press F7 to disable driver signature enforcement.
  • Your INF should install successfully.

This operation mode (Disabled Digital Signature Enforcement), which allows you to freely install INF files generated by WinDriver, will last until the next reboot. Your newly installed INF files should work properly even after the Digital Signature Enforcement will automatically be switched on again in the next reboot. Other ways are available to permanently disable Digital Signature Enforcement, and are dependent on your Windows version. Full explanation for these ways can be found online.

ℹ️ Note

‍Jungo provides Digital Signature Services for drivers developed with WinDriver. In order to find ore information, please send us an e-mail to sales.nosp@m.@jun.nosp@m.go.co.nosp@m.m.

17.3.5. Test Signing a Driver Package in Windows 10 and Later

Another way to avoid having to restart the computer constantly due to Windows' digital signature enforcement policy is to test sign your driver and enable test signing mode. This solution should be used for development and testing purposes only.

To test sign a driver you need a test certificate installed on your development machine (a test certificate is a self-signed certificate).

If you choose to create a test certificate in the WinDriver installer (See Chapter 3.2.1.1. Setting up Test Signing), then, when you use DriverWizard code generation, DriverWizard will automatically generate a digitally-test-signed catalog file for your driver package (a digitally-signed catalog file is used as a digital signature for an arbitrary collection of files). In that case, if you enable test-signing mode, you will be able to load the test signed driver without any prompts or warnings from Windows.

⚠ Attention

‍Test signed drivers should be used for development and testing purposes only, and should NOT be distributed to customers.

17.3.5.1 The wdreg Utility - Test Signing Set Up Usage

WinDriver provides an option for enabling and disabling test signing mode and for creating or removing the WinDriver test certificate. This option appears in two separate utilities: wdreg and wdreg_gui.

Both utilities can be found in the WinDriver\util directory; they can be run from the command line, and provide the same functionality. The difference is that wdreg_gui displays installation messages graphically, while wdreg displays them in console mode.

This section describes the use of wdreg / wdreg_gui on Windows operating systems.

The explanations and examples below refer to wdreg, but any references to wdreg can be replaced with wdreg_gui.

17.3.5.1.1 Enabling and Disabling Test Signing Mode

This section explains how to use the wdreg utility to enable or disable test signing mode on Windows.

Usage:

wdreg -testsigning {on | off}

ACTIONS

wdreg supports several basic ACTIONS:

Action                    Description
on Enables test signing mode. This mode enables test signed drivers to load.
off Disables test signing mode.

⚠ Attention

‍After changing the testsigning boot configuration, a reboot is required for the changes to take effect. Once these changes take effect, you are not required to do anything else with Windows security settings during the development process (as opposed to disabling digital signature enforcement, which must be done after every reboot).

⚠ Attention

‍You must have administrative rights and disable Secure Boot to change the testsigning boot configuration.

You can verify the value of the testsigning boot configuration by running:

# From cmd or powershell
$ bcdedit | findstr testsigning
# From powershell:
$ bcdedit | Select-String testsigning

The output look as follows:

# If test sign mode is enabled the output will be:
testsigning Yes
# If test sign mode is disabled the output will be empty (default) or:
testsigning No

17.3.5.1.2 Creating and Removing the WinDriver Test Certificate

This section explains how to use the wdreg utility to create or remove test certificates on Windows.

Usage:

wdreg -cert <filepath>.cer {create | remove}

ACTIONS

wdreg supports several basic ACTIONS:

Action                    Description
create Creates a WinDriver test certificate and installs it in 3 local machine stores: 'Personal', 'Trusted Root Certification Authorities' and 'Trusted Publishers'.

filepath should be the desired path of the created certificate file.

Note: The certificate name (as opposed to the file name) will always be set to WinDriver1630.development.
remove Removes a certificate from local machine stores: 'Personal', 'Trusted Root Certification Authorities' and 'Trusted Publishers'.

filepath should be the path of the .cer file of the certificate you wish to remove.

⚠ Attention

‍You must have administrative rights to create/remove certificates from local machine certificate stores.


ℹ️ Note

‍There are two types of certificate stores:

  1. Local machine certificate store.
  2. Current user certificate store.

Local machine stores are shared between all users, as opposed to current user stores, which are specific to the current user. As mentioned before, WinDriver places test certificates only in the local machine certificate store.

To verify a certificate was created and installed, open the run dialog box (winkey+r) and enter certlm.msc; the certificate manager tool for the local machine will open. In the manager you can view certificates installed in the relevant stores: 'Personal', 'Trusted Root Certification Authorities' and 'Trusted Publishers'

17.3.5.2 Installing Test Signed INF Files

17.3.5.2.1 Prerequisites for Installing Test Signed INF Files

windrvr1630.sys is digitally signed by Jungo and Microsoft, as opposed to a renamed driver generated by DriverWizard which is not signed, and therefore there is a difference in prerequisites for installing the different INF files.

The following table summarizes the different prerequisites:

INF Type Secure Boot Test Signing Mode* Test Signed INF** Test Certificate Installed*** Will I be able to install the INF?
Device INF requiring the WinDriver driver windrvr1630.sys Enabled X
(enforced by Secure Boot on)
V V Yes
Disabled X V V Yes
Disabled V V V Yes
Disabled V V X Yes, you will be prompted to authorize the installation
Disabled X V X No
Device INF requiring a renamed driver <projectname>.sys
and the driver INF for the renamed driver
Enabled X
(enforced by Secure Boot on)
V V No
Disabled X V V No
Disabled V V V Yes
Disabled V V X Yes, you will be prompted to authorize the installation
Disabled X V X No

*To enable test signing mode see Chapter 17.3.5.1.1 Enabling and Disabling Test Signing Mode or 3.2.1.1. Setting up Test Signing.

**To generate test signed INF files via DriverWizard see Chapter 17.3.5.3 How to Generate Test Signed INF Files in DriverWizard Code Generation?.

***To create the WinDriver test certificate see Chapter 17.3.5.1.2 Creating and Removing the WinDriver Test Certificate.


Note:This table displays only some of the cases, and the behaviour may vary between different versions of Windows.

17.3.5.2.2 Steps for Installing Test Signed INF Files on a Testing Machine

If your testing computer is not your development computer (the computer running DriverWizard), then you need to set up your testing computer before installing test signed INF files:

  1. (Required in some cases) Enable test signing mode (as explained in 17.3.5.1.1 Enabling and Disabling Test Signing Mode). See Chapter 17.3.5.2.1 Prerequisites for Installing Test Signed INF Files for more information about when test signing mode is mandatory.
  2. Install the WinDriver test certificate in the 'Trusted Root Certification Authorities' and 'Trusted Publishers' certificate stores. To do so, look for the following files in the folder <projectname>\<projectname_installation>\redist:
    • .cer file - the test certificate used to sign the INF files.
    • install_test_cert.bat and uninstall_test_cert.bat - scripts for installing and uninstalling the test certificate (when running one of the scripts, make sure the .cer file is in the same folder as the script).
      Note: You must run install_test_cert.bat and uninstall_test_cert.bat with administrative privileges in order to install/uninstall the test certificate.

After you have installed the test certificate you can install the test signed INF files using wdreg. See Chapter 16.2.1.1. WDM Drivers for more information on how to install the driver and device INFs.

17.3.5.3 How to Generate Test Signed INF Files in DriverWizard Code Generation?

Once you have created and installed the WinDriver test certificate, every INF created in the code generation process will have an associated catalog file that is test signed.

To create and install the WinDriver test certificate either check the 'Create test certificate' checkbox in the WinDriver installer (as explained in 3.2.1.1. Setting up Test Signing), or manually create and install the WinDriver test certificate (as explained in 17.3.5.1.2 Creating and Removing the WinDriver Test Certificate).

⚠ Attention

‍In order to load test signed INFs, you might need to enable test signing mode

>(as explained in 17.3.5.1.1 Enabling and Disabling Test Signing Mode). >See Chapter 17.3.5.2.1 Prerequisites for Installing Test Signed INF Files >for more information about when test signing mode is mandatory.

17.3.5.4 Manually Signing INF files using SignTool

ℹ️ Note

‍Inf2Cat and SignTool are command line tools provided with the Windows Driver Kit (WDK). You can run them from Visual Studio Developer PowerShell or Visual Studio Developer Command Prompt, without the need to use their full path or to add them to your PATH environment variable.

To manually test sign INF files:

  1. Create a catalog file using Inf2Cat.
    $ Inf2Cat /drive:<driver package path> /os:<Windows os version list>
  2. Sign the catalog file using SignTool.
    $ Signtool sign /fd <digest algorithm> /f <path to .cer file of your test certificate> <path to the catalog file to sign>
  3. Verify the digital signature.
    $ SignTool verify /v /pa <catalog filepath>
    See Microsoft documantation for more information about Inf2Cat.exe and Signtool.exe.