Getting Started with the CBEncrypt Component

Introduction

CBEncrypt is a filesystem filter component that monitors access to specified directories and transparently enforces file-level encryption and decryption policies based on the process initiating the request.

Applications define encryption rules that determine which directories are protected, and trusted processes that can access decrypted data within those directories. Files written by trusted processes are automatically encrypted on disk, and can read or write decrypted content on-the-fly. This ensures that sensitive data remains protected at rest without requiring any changes to existing applications or file access workflows.

Getting started with the component is straightforward. Initialize the component, define encryption rules for any directory you want to protect, add one or more trusted processes that may access protected directories, and start the component. Once running, trusted processes will automatically access decrypted data while all other access remains encrypted.

Please see the sections below for additional details.

Install and Uninstall the Drivers (Windows)

On Windows, the system driver must be installed on a machine before the CBEncrypt component can be used to begin enforcing file-level encryption and decryption policies. This is done using the Install method, which is present in the CBEncrypt component API, as well as in a standalone Installer dynamic library (.dll), included with the toolkit. The CBEncrypt API method is useful when your application is responsible for installing the driver; the Installer dynamic library is designed to be used from installation scripts.

It may be necessary to reboot the system after calling Install to complete the driver installation process; the Install method will return a value that indicates whether or not this is necessary. Once the driver installation is complete, you will be able to use the CBEncrypt component to begin enforcing file-level encryption and decryption policies.

The driver needs to be installed only once. You do not need to install it each time you start your application. If the driver is not installed correctly, you will receive a "File not found" error when trying to use the CBEncrypt component, which means that the driver could not be found or loaded.

To uninstall the system driver, call the Uninstall method; available in both the CBEncrypt component API and the Installer dynamic library. This is not necessary when you install a new minor or major version of the driver.

Component Overview

The CBEncrypt component functions as a filesystem filter that transparently encrypts and decrypts files based on defined security rules. Once initialized and started, it intercepts file operations performed on protected paths and enforces encryption policies automatically, ensuring that only approved applications can access decrypted data.

Before doing anything else with the CBEncrypt component, you must call its Initialize method. Once this is done, you will be able to use the CBEncrypt component to begin enforcing file-level encryption and decryption policies.

Additionally, the GlobalSalt property must be set accordingly. This property should be set to a random string or byte array of 16 bytes in length. This value is mixed into the key derivation process when generating encryption keys from passwords, and helps ensure that identical passwords produce unique keys. Using a cryptographically strong random number generator is recommended when creating this value.

Next, you will need to specify which processes are permitted to access decrypted data within protected directories, specified by defined encryption rules. Please see the below subsections for additional details here.

Once the component is started, it will transparently handle encryption and decryption for all matching file operations according to the defined rules and trusted process list. Rules and trusted processes can be modified dynamically at runtime without restarting the component.

To summarize, the flow for starting the component could look like:

• Call Initialize (mandatory before calling Start).
• Specify GlobalSalt (mandatory before calling Start).
• Add encryption rules and trusted processes (optional before calling Start).
• Call Start.

Managing Encryption Rules

The EncryptionRules property provides access to the collection of encryption rules defined for the CBEncrypt component. Each rule specifies a directory path and the encryption parameters that should be applied to files within that path.

You can add new rules using the AddEncryptionRule method, which takes a directory path, a flag indicating whether subdirectories should be included in the rule, and a password to use for encryption. Adding the same path multiple times will only create one rule for each distinct path. Rules can be removed using the RemoveEncryptionRule method.

For example, the following will add an encryption rule to monitor files in the C:\temp directory, and all contained subdirectories. If a file is created or modified by a trusted process within C:\temp, the component will use the specified password, along with the global salt, to encrypt the file.

mEncrypt.AddEncryptionRule("C:\temp", true, "PASSWORD");

Afterwards, only trusted processes will be able to access decrypted data within C:\temp. Processes not listed in the TrustedProcesses collection will only see encrypted file contents (assuming the file itself is encrypted).

Adding Trusted Processes

The TrustedProcesses collection defines which processes may access decrypted data in directories protected by the component. Each entry identifies a process either by its process ID (PID) or by its executable file name, and specifies whether the rule applies to child processes as well.

You can add trusted processes using the AddTrustedProcess method, which takes process file name or process id, along with a flag indicating whether the encryption rules should also apply to the children processes. To trust a process that is already running, specify its PID with an empty process name. To trust a process that may start later, specify the executable name and set the PID to 0. To allow all processes, specify an empty process name and set the PID to -1. For example:

// Specify by PID mEncrypt.AddTrustedProcess("", 14426, true);
// Specify by file name mEncrypt.AddTrustedProcess("notepad.exe", 0, true);
// Allow all processes access to encryption rules mEncrypt.AddTrustedProcess("", -1, true);

Untrusted Process Behavior

Processes that are not listed in the TrustedProcesses collection are considered untrusted. These processes do not have access to decrypted file data for any directories protected by encryption rules.

Untrusted processes can still read protected files, however, these processes will receive only the encrypted data as it exists on disk. Decryption is never performed for these processes.

Additionally, write access by untrusted processes is blocked for encrypted files by default. This prevents accidental or intentional corruption of encrypted data. Attempting to modify, overwrite, or append to an encrypted file by an untrusted process will fail with an error.

This behavior ensures that encrypted data remains protected at all times, even if untrusted or unauthorized applications attempt to interact with the files directly. Only processes explicitly marked as trusted can view or modify decrypted content, and all others are transparently restricted to read-only access to the encrypted data.

Starting the Component

After initializing the component, setting the GlobalSalt, and configuring encryption rules and trusted processes, you can start the CBEncrypt component by calling the Start method. Once started, the component begins monitoring the specified directories and transparently enforces encryption and decryption policies for all file operations.

To stop the component, call the Stop method. This will cease all monitoring and encryption operations until the component is started again. Both Start and Stop can be called multiple times as needed during the application’s lifetime.

Handling Events

The configured EncryptionRules and TrustedProcesses may be sufficient for controlling how and when files are encrypted or decrypted. However, the events described in this section allow for finer-grained control over component behavior. These events can be used to dynamically adjust rules as various file operations occur.

Note that file-related events will only fire for processes in the TrustedProcesses collection. The component automatically handles filtering requests for untrusted processes.

Create and Open Files

The OpenFile event fires whenever a file within a monitored directory is created or opened. This event allows applications to inspect or modify the operation before the file is accessed, and can be used to dynamically control behaviors such as whether the file should be encrypted, decrypted, or blocked from being opened.

When the event fires, the component provides detailed information about the file, including its full path, access mode, and whether the file already exists. If the file is being opened (i.e., it already exists and is not recreated), the event is primarily informational. If the file is being created or recreated (superseded), the component will automatically determine encryption behavior based on the defined EncryptionRules.

By default, new files are encrypted automatically using the password defined in the applicable encryption rule. Applications may override this behavior by setting the Encryption and Password parameters in the event to control how the new file is encrypted.

For instance, you can specify a custom password not defined in any rule, or set Encryption to 0 to disable encryption for the file.

If the component needs a password to decrypt an existing file and one has not yet been provided, the PasswordNeeded event will fire before OpenFile. This typically occurs when the component attempts to decrypt the file using a rule-defined password and the operation fails.

Close Files

The CloseFile event is fired when a file or directory within a monitored location is closed. This event is triggered only for files that were previously opened for reading or writing, not when files are accessed for attribute retrieval.

This event provides information about the file being closed, including its name, access parameters, encryption state, and whether it was modified during the session. Applications can use this event to perform cleanup or to schedule asynchronous encryption or decryption operations as needed.

The DesiredAccess and CreateDisposition parameters correspond to those provided during the original OpenFile event. The Encrypted parameter indicates whether the file is currently encrypted, and the Modified parameter indicates whether the file’s contents, size, or valid data length changed while it was open.

Renaming Files

The RenameOrMoveFile event fires when a file within a monitored directory is renamed or moved to a new location. This event allows applications to monitor, validate, or modify rename and move operations, and can also be used to control encryption behavior during the process.

When the event fires, the component provides details about both the original and new file names. To prevent the operation, set the ResultCode parameter to a nonzero value, such as ACCESS_DENIED (5), which instructs the operating system to reject the rename or move request.

The Encryption and Password parameters indicate the current encryption state of the file. By default, if these parameters remain unchanged, the file retains its existing encryption. Applications may modify these parameters to encrypt or decrypt a file, or apply a different password to the file as it is renamed or moved.

Applications can also use the FileMatchesMask helper method to determine whether the file’s new name or location matches an existing encryption rule. This allows dynamically applying the correct password from the EncryptionRules collection when a file is moved into a directory governed by a different rule. For example:

lock (mEncrypt.EncryptionRules) { foreach (EncryptionRule rule in mEncrypt.EncryptionRules) { if (mEncrypt.FileMatchesMask(rule.Path + "\\*\\*", e.NewFileName, false)) { e.Encryption = 2; e.Password = rule.Password; } } }

If the file being renamed or moved is encrypted, the PasswordNeeded event may fire beforehand if the component requires a password to read or modify the file’s contents.