Deployment

The topics in this section provide information regarding the deployment of applications built with CBFS Encrypt. The information in these topics should be reviewed carefully when designing a deployment strategy, because CBFS Encrypt's kernel mode drivers and other supplementary DLLs must be distributed along with the application for it to function correctly.

Topics

• Driver Installation
• User Mode Library

Driver Installation

At a high level, CBFS Encrypt consists of a kernel mode driver, a helper DLL, and a user mode library; all of which work together in tandem to provide the product's functionality. Therefore, it is necessary to install the CBFS Encrypt kernel mode driver and helper DLL when deploying an application built with the CBFS Encrypt user mode library.

The functionality needed to install the above-mentioned modules is included in the user mode library itself, as well as in a separate installer DLL.

Important: the signatures of the functions in the installer DLL differ from the signatures of the corresponding methods of the components. Use the signatures provided in installer/{ComponentName}Inst.h when using the installer DLL.

The drivers directory, located within the product's installation directory, contains the following files:

NOTE: When the user-mode library is installed or updated on end-user systems, it is required to ensure that the kernel-mode drivers already present in the system are updated to match the version of the installed user-mode library.

NuGet Notes

If CBFS Encrypt is installed using NuGet, the drivers directory described above will be located within NuGet's global-packages directory at the following path (assuming NuGet's global-packages directory has not been changed): %USERPROFILE%\.nuget\packages\callback.cbfsencrypt\24.0.xxxx\contentFiles\any\any\drivers.

Installation and Uninstallation via User Mode Library Methods

The component includes the following methods to install and uninstall the required files; please refer to their documentation for more information:

• Install
• Uninstall
• GetDriverStatus
• GetDriverVersion

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.

Installation and Uninstallation via Installer DLL Functions

The installer DLL is a lightweight, stand-alone library that contains only the functionality required for installing and uninstalling the required files. It is available in both 32-bit and 64-bit versions (each of which is capable of installing both 32-bit and 64-bit drivers and helper DLLs); and may be used as desired in installation scripts, setup applications, or any other executable capable of loading dynamically-linked libraries (DLLs).

The functions exposed by the installer DLL mirror the component methods listed above. Each function is available in two forms: those with an *A suffix, which can be used with ANSI/UTF8 strings; and those with a *W suffix, which can be used with Unicode (UTF16) strings.

Windows 7/8/8.1 and Windows 2008R2/2012/2012R2 Server notes: to install the drivers, you need to have certificate-related updates installed on the target system. This includes KB3033929 that adds support for SHA2 certificates. Other notable updates are are KB976932 (Service Pack 1 of the mentioned systems) and KB4474419 (Security Update). Other updates, such as updates to known Root and CA certificates may be required as well. Without these updates, the drivers can be installed but may not be loaded by the OS.

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.

For example, the helper DLL must be loaded by Windows File Explorer when it starts, and a reboot or restart of Explorer is required for this to occur. When installing or uninstalling the Plug-and-Play (PnP) drivers, a reboot is almost always requested by Windows.

Always check the return value of the Install and Uninstall methods/functions; it will indicate whether a reboot is required (and if so, which module(s) required it).

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.

Required Permissions

By default, Windows only allows installation and uninstallation of the CBFS Encrypt 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 component itself.

Some examples of obtaining the required permissions for driver installation and uninstallation are below.

• Starting the application which uses the component 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>

User Mode Library

The user-mode library must be deployed to end-user systems along with the kernel-mode drivers; the version of the kernel-mode drivers on the end-user systems must be equal to or newer than the version of the user-mode library. Thus, when the user-mode library is installed or updated on end-user systems, it is required to ensure that the kernel-mode drivers already present in the system are updated to match the version of the installed user-mode library.

The user-mode library comes in two pieces, both of which must be deployed along with the application:

1. A .NET assembly (managed), named callback.CBFSEncrypt.dll (or callback.CBFSEncrypt.NetStd.dll, for .NET Standard).
2. A native dynamic library (unmanaged), named cbfsencrypt24.dll, available for both 32-bit (x86) and 64-bit (x64, ARM64) processor architectures.

When deploying the application, copy both the .NET assembly and the native library to the target system and place them next to the application's .exe file .

Alternatively, the native library may be placed into one of directories, the paths to which are contained in the PATH environment variable, such as C:\Windows\System32 (or C:\Windows\SysWOW64 when deploying a 32-bit application on a 64-bit Windows system).

The .NET assembly may be deployed to the Global Assembly Cache (GAC).

Loading of Native Library

Usually, .NET finds the native library when it is placed next to the assembly. But on some systems, it skips the directory of the assembly or even of the main application module. To ensure that this doesn't happen on a user's system when an application keeps the native library next to the .NET assembly, in the .NET Core 3.1 and .NET 5+ applications, you can use the DllImportResolver function as shown in the following snippet: public static IntPtr CBEncryptImportResolver(string libraryName, Assembly assembly, DllImportSearchPath? searchPath) { bool loaded = false; IntPtr libHandle = IntPtr.Zero; if (!libraryName.Contains("callback.CBFSEncrypt")) return IntPtr.Zero; //Look for the native library next to the .NET assembly loaded = NativeLibrary.TryLoad(libraryName, assembly, DllImportSearchPath.AssemblyDirectory, out libHandle); //Look for the native library in the application's main directory if (!loaded) loaded = NativeLibrary.TryLoad(libraryName, assembly, DllImportSearchPath.ApplicationDirectory, out libHandle); //Look for the native library using teh default .NET behavior if (!loaded) loaded = NativeLibrary.TryLoad(libraryName, assembly, searchPath, out libHandle); return loaded ? libHandle : IntPtr.Zero; } ... NativeLibrary.SetDllImportResolver(Assembly.GetAssembly(typeof(CBEncrypt)), CBEncryptImportResolver); This code attempts to load the native library in the directory of the managed .NET assembly, and if not found then attempts to find the library in the application's main directory, and if not found then revert to the default .NET behavior. Only one DllImportResolver function may be set for the assembly, so doing the above for one component is sufficient.

In the .NET Framework 4.x applications, one can use AppDomain.CurrentDomain.AssemblyResolve event for the same purpose.

NuGet Notes

After the NuGet package is added to a project, both the managed .NET assembly and the unmanaged native library will be copied to the project's output directory anytime the project is built. However, the exact files copied to the output directory for the native library will vary based on the project type:

• For .NET Core projects, a runtimes directory will be created in the output directory (if it does not already exist), and versions of the native library for each supported runtime identifer (RID) (e.g., win-x64) will be placed in the appropriate subdirectories. When the .NET Core application is distributed, the entire runtimes directory should be deployed alongside it.
• For other types of projects (.NET Framework, UWP), only the native library version specific to the currently selected platform target (e.g., x64) will be copied to the output directory.
  • For .NET Framework projects specifically, please note that the project's platform target (Project > Properties > Build Tab > Platform target) must be set to a real architecture. If it is set to "Any CPU", no native library will be copied to the output directory.

The native library may alternatively be installed to the Windows system directory. This approach allows deploying both the 32-bit and 64-bit versions of the native library simultaneously, because each gets placed into the system directory that corresponds to the appropriate processor architecture.

Remember to deploy the drivers too, as they are an integral part of CBFS Encrypt.

General Information

The topics in this section provide general information about various aspects of the product's functionality.

Topics

• Encryption
• Driver Altitudes
• Thread Safety of the API
• Buffer Parameters
• Timeouts
• Loading Drivers in Safe Mode
• Error Handling
• Troubleshooting

Encryption

The CBEncrypt component includes strong built-in data encryption support, which can be applied to individual files as specified by one or more encryption rules. Each file can have its own password.

Passwords are not used to encrypt file data. When a file is first encrypted, the component generates so-called session keys, which are then used to encrypt actual file data. Session keys are generated separately for each file. Next, the component derives encryption keys from application-provided passwords and generated unique seeds and uses these encryption keys to encrypt session keys. Encrypted session keys are stored in the component-private portion of the file header.

Driver Altitudes

A key benefit of filter drivers in general is that any number of them can be active at the same time. To keep things organized, Windows maintains a stack of filesystem filter drivers and ensures that the stack is sorted consistently based on the drivers' altitudes.

These altitudes, which are expressed in a string notation as numbers with an optional fractional part (e.g., "12345.768"), essentially define each driver's absolute position in the stack. Drivers with higher altitudes are attached toward the top of the stack, closer to user mode, whereas drivers with lower altitudes are attached toward the bottom of the stack, closer to the applicable system component. Please refer to Microsoft's Load Order Groups and Altitudes for Minifilter Drivers article for more information about altitudes.

When an operation is requested, that request "enters" the top of the filter driver stack and moves downward, toward the applicable system component. Once the request has been handled (either by the system component or by one of the filter drivers in the stack), a response travels back up the stack. So the process of choosing a suitable altitude depends primarily on the intended functionality of the filter application being developed.

To prevent collisions, Microsoft also manages all filesystem minifilter altitude assignments.

When developing an application that uses CBEncrypt, an altitude must be requested from Microsoft. Use the instructions described in their Minifilter Altitude Request article; and be sure to specify "FileSystem" (or "Both") for the "Filter type:" field when composing the request.

Once Microsoft has assigned an altitude for the application, it should be specified using the Altitude property or the Altitude parameter of the Install method.

Thread Safety of the API

The properties and methods provided by CBFS Encrypt's APIs fall into one of the following categories when it comes to thread safety:

• Properties and methods that are intended to be accessed from event handlers (i.e., those documented as such) are thread-safe, since event handlers always execute in the context of worker threads.
• Methods related to installation, uninstallation, and status retrieval are not thread-safe, since they are expected to be used during the application installation process. (Methods in this category are those which are documented as being "available in both the component API and the Installer DLL".)
• Any helper methods documented in the component's API (i.e., those used to convert error codes, or provide similar supplementary functionality) don't use any explicit thread synchronization, but also don't access any other component properties or methods, and thus are inherently thread-safe.
• All other properties and methods are not thread-safe, so applications must employ proper thread synchronization techniques when using them on multiple threads (including, but not limited to, during event handlers).

Buffer Parameters

Some events include one or more parameters intended for use as a binary data buffer. Depending on the event, these parameters may contain data when the event is fired, or it may be expected that the application populates them with the desired amount of data during the event handler. Some events combine both paradigms and then expect the application to modify the data already present when the event is fired.

The documentation for such events will describe which of these cases applies to each buffer parameter. In all cases, buffer parameters point to a preallocated block of unmanaged memory, the size of which is specified by the parameter immediately following the buffer parameter. In cases in which data are to be written, be sure to write it directly to the pointed-to memory, do not change the value of the buffer parameter itself.

Buffer parameters are always of the IntPtr type; use the .NET Marshal.Copy() method to read and write data from and to the unmanaged memory region. When targeting newer .NET versions, such as .NET Standard 2.1 and later, applications can use the Span<T> and ReadOnlySpan<T> classes to access and modify the unmanaged memory region without extra data copying.

Timeouts

(This topic references methods of the CBEncrypt component.)

Because the CBFS Encrypt components' filesystem events are tied directly to the underlying operations' requests and responses, it is critical that their event handlers complete quickly to prevent the system from being blocked. To help prevent such blocking, the components' system drivers can enforce event timeouts.

To enable event timeouts, pass a nonzero value for the Timeout parameter when calling the Start method. Passing 0 will disable event timeouts, in which case, events may take as long as necessary to execute.

It is strongly recommended to have timeouts enabled in production. Disabling the timeouts is handy during development so that you can debug the code of your event handlers; as a safety mechanism that helps prevent various deadlocks, timeouts should be enabled in production.

When timeout enforcement is in effect, and an event executes long enough for its timeout to expire, the driver either "releases" the underlying request (passing it onward unchanged), or cancels it by reporting an error; whichever is most appropriate for the event in question and according to the DenyExpiredEvents. The tardy event still runs to completion, but any results it returns once finished are ignored because the underlying request has already passed through the filter driver.

If an event handler knows it will require additional time to complete an operation, it can call the ResetTimeout method before the current timeout expires to restart its timeout timer.

Applications should always strive to ensure that all event handlers complete quickly, even if request timeouts are disabled. Do not perform time-consuming work within event handlers; offload such work to background threads.

Loading Drivers in Safe Mode

When booting in Safe Mode, Windows loads only a limited set of drivers. If circumstances require that the CBEncrypt driver be loaded in Safe Mode, this can be accomplished by adding the file name of the applicable driver to the following registry key:

HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\SafeBoot.

Warning: Attempting to load the CBEncrypt driver in Safe Mode can render the system unbootable if the driver fails.

Error Handling

Error Codes

The CBFS Encrypt communicates errors using the Win32 error codes defined in WinError.h, which is part of the Windows Platform SDK. The CBFS Encrypt system drivers, however, use NT native error codes, which do not have one-to-one mappings with Win32 error codes. The component includes logic for converting between the two as necessary, and that logic can be updated if any codes are not covered.

Additionally, CBFS Encrypt uses use certain error codes in a special manner. For more information about such error codes, please refer to the Error Codes page .

Reporting Errors to the Component from Event Handlers

If an event has a ResultCode parameter, an event handler can use it to return the result code of the operation to the component. The ResultCode parameter is set to 0 by default, which indicates the operation was successful.

If an unhandled exception occurs in the event handler, it will be caught by the component, which will fire the OnError event.

In some events, the OS does not expect the error code to be returned and either the component or the OS ignores the returned error code. Please refer to the description of a particular event for more information.

How to Handle Errors Reported by the Component

If an error occurs, the component will throw an exception. The Code property of the exception object will contain an error code, and the Message property will contain an error message (if available).

Extended Logging in Windows

Some component methods in CBFS Encrypt are capable of writing extended information about reported errors to the Windows event logs, which can be viewed using the system's eventvwr.exe tool. The user mode part of the component writes to the "Windows Logs \ Application" or to "CBFS \ {component}" folder, while the kernel mode part (where applicable) writes to the "Windows Logs \ System" folder.

The information written in the extended logs is meaningful to the Callback Technologies development team, but not to end-users, so extended logging is disabled by default. Important: These logs are not trace logs; do not enable them expecting to see detailed logging of the operations. The logs are used solely for troubleshooting.

If issues occur during the installation of the CBFS Encrypt system drivers, or while using the component, please do the following:

1. Enable extended logging (see below).
2. Replicate the issue.
3. Using Event Viewer (eventvwr.exe), export the event log entries from the locations mentioned above in native format (please restrict the scope of the export to just those entries related to CBFS Encrypt).
4. Submit an issue report that includes the exported file.

There are two ways to toggle extended logging for a component:

1. By toggling the component's LoggingEnabled configuration setting.
2. By adding a DWORD-typed value named Enabled to the HKEY_LOCAL_MACHINE\SOFTWARE\Callback Technologies\{ComponentName}\EventLog registry key and setting it to 0 (disabled) or 1 (enabled).
   • Replace the {ComponentName} part of the registry key path with the name of the applicable component.
   • If this registry key, one of its parents, or the actual value does not exist, please create it manually.

   NOTE: If your code runs in emulated mode (x86 mode on x64 or ARM64 architecture), you need to add the value to the HKEY_LOCAL_MACHINE\SOFTWARE\WOW6432Node\Callback Technologies\{ComponentName}\EventLog registry key in addition to the "main" registry key.

If modification of the flag is done via the registry, the system must be rebooted anytime extended logging is enabled or disabled to make the changes take effect.

Troubleshooting

CBFS Encrypt is a complex product that operates in both user mode and kernel mode simultaneously; so when a serious issue occurs, it's critical that we are able to obtain sufficient information about the circumstances of the failure.

In order to help us assist you in a more expedient manner, please collect the information described in the instructions below when reporting a serious issue (i.e., one that causes the system to crash or hang). Our development team cannot effectively diagnose such issues without this information.

Also, please note that these sorts of issues commonly involve environmental differences and other factors that are either unforeseen or otherwise out of our control. It is also not unheard-of for a crash to appear attributable to one thing while in fact being caused by something completely different. Rest assured that we are committed to assisting you as best we can, and we thank you ahead-of-time for your patience and understanding throughout the support process.

System Crashes (BSODs)

If you encounter a consistently-reproducible system crash (BSOD) that you suspect may be due to CBFS Encrypt, please obtain a crash dump and include it when reporting the issue to us. Our development team is unable to diagnose system crashes without the information these dumps contain.

Ensure that your system is set up to generate crash dumps, and to not restart automatically after a crash, by following the steps found in Microsoft's Enabling a Kernel-Mode Dump File article. The options available in the memory dump dropdown vary depending on your version of Windows; please choose the first one from the following list that is present in yours:

• Complete
• Full
• Automatic
• Kernel

Once your system is set up to generate crash dumps, perform the same action that caused the BSOD originally to trigger the crash again. When it occurs, be sure to copy the information on the BSOD screen exactly so that it can be included in your submission (a picture of the screen in which all of the information is legible is also acceptable). Here are some examples of the specific information we're looking for:

Recent versions of Windows:

What failed: cb***24.sys Stop Code: FILE_SYSTEM

Older versions of Windows:

STOP: 0x00000022 (0x00240076, 0xF7A07AA8, 0xF7A077A8, 0xF7800C82) cb***24.sys - Address F7800C82 base at F77CD000, DateStamp 447d6975

After you've copied this information, reboot and check that the memory dump file was created at %SYSTEMROOT%\MEMORY.DMP (typically this is C:\Windows\MEMORY.DMP; if you changed the dump file location in the crash dump settings, check the location you specified instead). It will be a very large file that is too big to attach to an email, so please upload it to a file sharing site of your choice and generate a sharing link that our development team can use to download it.

Finally, submit a support issue to us that includes the link to your dump file, all of the information from the BSOD screen (if you took a picture, attach it or provide another sharing link), a description of how the BSOD was triggered, and any other information that you feel is relevant.

System Hangs

If you encounter a consistently-reproducible system hang that you suspect may be due to CBFS Encrypt, you'll need to collect the same information as described above. But in order to obtain a crash dump, you'll first need to configure your system so that you can trigger a crash from the keyboard once it hangs. To make this possible, follow these steps (adapted from Microsoft's Forcing a System Crash from the Keyboard article):

1. First, using the instructions provided in the section above, configure your system to generate crash dumps, and to not restart automatically after a crash.
2. Next, you must enable keyboard-initiated crashes in the registry by creating a new value named CrashOnCtrlScroll, and setting it equal to a REG_DWORD value of 0x01, in all of the following registry keys:
   • HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services\i8042prt\Parameters
   • HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services\kbdhid\Parameters
   • HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services\hyperkbd\Parameters
3. Finally, you must restart the system in order for these settings to take effect.

After these steps are complete, you'll be able to trigger a keyboard-initiated crash by using the following hotkey sequence: hold down the Right CTRL key, and press the SCROLL LOCK key twice.

At this point, you can perform the same action that caused the system to hang originally to trigger the hang again. Once the system hangs, use the hotkey sequence to force it to crash, and then follow the rest of the instructions from the section above to collect and submit the necessary information.

Method Never Returns

If your application makes a call to some CBFS Encrypt method and that method never returns, there's a high chance that the driver deadlock has occurred. This can be caused by various factors; to determine the reason and possible solutions, we need a memory dump, as described above. If your system remains functional, you may also use easier ways to initiate a crash:

1. Use the NotMyFault tool by SysInternals to initiate a system crash. This is the preferred way because it generates Complete memory dumps. This tool has a self-explanatory GUI.
2. Use the LiveKD tool by SysInternals to create a live memory dump without crashing a system. The disadvantage of this method is that it creates Kernel dumps that are missing user-mode information. To use LiveKD on 32-bit systems, use this command: "livekd.exe -ml -o memory.dmp". On 64-bit systems, the command line would be "livekd64.exe -ml -k .\kd64.exe -o memory.dmp".

Application Crashes

Sometimes, an application crashes while the OS continues to operate, and the name of one of the modules of CBFS Encrypt is present in the crash information. A crashing application can be the one that uses CBFS Encrypt or some third-party process. If the crash occurs repeatedly, it is possible to make use of a User-Mode Crash Dump to locate or narrow down the source of the crash. Generation of crash dumps is disabled by default. Before you reproduce the crash, you need to Enable Collecting User-Mode Crash Dumps.

After you enable the crash dump, you don't need to reboot, you can proceed to reproduction of the crash immediately. After the crash re-occurs, you can pick the dump file from its location. The default locations of user-mode dump files are:

• For regular applications: %LOCALAPPDATA%\CrashDumps
• For System services: %WINDIR%\System32\Config\SystemProfile
• For Network and Local services: %WINDIR%\ServiceProfiles

If you changed the dump file location in the crash dump settings in the Registry, check the location you specified instead.

A crash dump can be a large file (depending on the settings) that is too big to attach to an email, so please upload it to a file sharing site of your choice and generate a sharing link that our development team can use to download it.

Finally, submit a support issue to us that includes the link to your dump file, a description of how the BSOD or a manual crash was triggered, and any other information that you feel is relevant.