Driver Installation
At a high level, CBFS Filter consists of class-specific kernel mode drivers and user mode API libraries which work together in tandem to provide each class's functionality. Therefore, it is necessary to install a class's kernel mode driver when deploying an application built with its user mode API library.
The functionality needed to install the class drivers is included in each one's user mode API, as well as in the standalone installer DLLs provided for each one. The drivers directory, located within the product's node.JS package (see notes below), contains the following files for each class*:
| {ClassName}.cab | Contains the class's drivers and the supplementary installation/uninstallation files. |
Node.js Package Notes
In the Node.js edition, the drivers directory described above is included as part of the product's Node.js package, <install_dir>\cbfsfilter-20.0.tar.gz.
Installation and Uninstallation via User Mode (Class) API Methods
The user mode class APIs include the following methods to install and uninstall the required files; please refer to their documentation for more information:
All of the links in this topic point to the CBFilter's copy of these methods, but they are available in all components.Important: Uninstall must only be used when completely removing the driver. When updating the driver, this method must not be used as it may cause the OS to incorrectly remove the driver on reboot. Please refer to the "Updating the Driver" section, below, for more information.
Updating the Driver
To update the driver, call the Install method. The new version of the driver will replace the older version. Please do not call the Uninstall method when updating the driver.
Uninstalling the Driver
To uninstall the driver completely, call the Uninstall method. If the driver cannot be immediately uninstalled, it will be marked for removal and uninstalled on the next reboot.
Use caution when calling Uninstall; if it gets called and the driver cannot be uninstalled immediately, and then Install is subsequently called to install a new version, then upon reboot, the OS will end up uninstalling the newly-installed driver.
Important: The driver should only be uninstalled when the intent is to completely remove it from the system. Do not uninstall the driver to update it.
Reboot Requirements
Depending on the current state of the system, as well as the options chosen when installing or uninstalling the driver, the OS may need to reboot to complete the operation.
Always check the return value of the Install and Uninstall methods/functions; it will indicate whether a reboot is required .
Additional Notes
The OS treats major versions of the driver as separate products; they can operate in parallel and do not share any resources. Old major versions may optionally be removed from the system when calling Install by passing the appropriate value for its Flags parameter.
For each major version of the product, only one copy of the driver can be installed at any time. When the driver is being installed, its version is checked, and one of the following three things occurs:
- If no driver with the same major version is currently installed, then the install procedure installs the driver as a new product.
- If a driver with the same major version and an older minor version is currently installed, then the install procedure updates the existing driver with the new one.
- If a driver with the same major version and a newer minor version is currently installed, then the install procedure leaves the existing driver unchanged.
When deploying files to a target system, the CAB file must remain present on the system. This file is required for uninstallation of the driver at a later time.
The product's installation code maintains a ProductGUID-based record of driver installations in the Windows Registry, creating a separate registry entry for each different ProductGUID. When the driver is "uninstalled", the corresponding registry entry is removed. The driver is only removed from the system if there are no entries left in the registry that reference the driver.
Windows 7 and Windows 2008 Server R2
Kernel-mode drivers are signed using the SHA2 algorithm. The original releases of Windows 7 and Windows 2008 Server R2 didn't support SHA2. To be able to load the newest versions of the drivers, the system needs to have certain updates installed. The updates are KB976932 (Service Pack 1 of the mentioned systems) and KB4474419 (Security Update).
Required Permissions
By default, Windows only allows installation and uninstallation of the CBFS Filter system files (kernel mode drivers and helper DLLs) to be performed from a user account which is a member of the Administrators group.
On systems where UAC is enabled, the process responsible for installing or uninstalling the system files must run with elevated permissions. Detection of current privileges and elevation of permissions is not within the scope of the class itself.
Some examples of obtaining the required permissions for driver installation and uninstallation are below.
- Starting the application which uses the class with the "Run as administrator" option.
- Modifying the Load and unload device drivers setting in the Local Security Policy under the User Rights Assignment section.
- Including a manifest alongside the application indicating the requirement for elevated permissions. For instance, if a file MyApp.exe.manifest with the content below exists next to the application MyApp.exe, it will prompt for elevated permissions when started (if required).
<?xml version="1.0" encoding="UTF-8" standalone="yes"?> <assembly xmlns="urn:schemas-microsoft-com:asm.v1" manifestVersion="1.0"> <assemblyIdentity version="1.0.0.0" processorArchitecture="X86" name="ExeName" type="win32"/> <description>elevate execution level</description> <trustInfo xmlns="urn:schemas-microsoft-com:asm.v2"> <security> <requestedPrivileges> <requestedExecutionLevel level="requireAdministrator" uiAccess="false"/> </requestedPrivileges> </security> </trustInfo> </assembly>