CBEncrypt Component

Properties Methods Events Config Settings Errors

The CBEncrypt component allows applications to transparently enforce file-level encryption and decryption policies on specified directories.

Syntax

TcbeCBEncrypt

Remarks

CBEncrypt monitors specified directories to ensure that all files stored there remain encrypted on disk, while allowing authorized processes to read or write decrypted content on-the-fly.

Applications define encryption rules to protect specific directories and their contents, and specify trusted processes that can access decrypted content. Any new files created or written by trusted processes within these directories are automatically encrypted according to the rules, ensuring that sensitive data is always protected at rest.

To learn more about the component's capabilities, please refer to the product's General Information topics.

Getting Started

If the component's system driver has not been installed yet, call the Install method to do so. This needs to be done only once.
- In production, the driver can be installed (or updated) ahead of time with the application's installation script using the Installer DLL. Please refer to the Driver Installation topic for more information.
Call the Initialize method to initialize the CBEncrypt component. This must be done each time the application starts.
Set the GlobalSalt property to a string or byte array of 16 bytes in length.
Add one or more encryption rules using the AddEncryptionRule method. (Rules can also be added or removed after the filter is started.)
Add one or more trusted processes using the AddTrustedProcess method.
Call the Start method to start filtering filesystem requests.
When finished, call the Stop method to stop filtering filesystem requests.
To uninstall the component's system driver, call the Uninstall method. This should not be done as part of the driver upgrade process.
- In production, the driver can be uninstalled by the application's uninstallation script using the Installer DLL. Please refer to the Driver Installation topic for more information.

Property List

The following is the full list of the properties of the component with short descriptions. Click on the links for further details.


Active	This property notes whether the component is active and processing requests.
Altitude	This property specifies the altitude the component's system driver should use .
EncryptionRules	This property includes the collection of encryption rules.
FireVolumeEvents	This property specifies the events that should be fired when a filesystem volume is mounted to or unmounted from the system.
GlobalSalt	The value being mixed into the process of key derivation.
SerializeEvents	Whether events should be fired on a single worker thread, or many.
Tag	This property stores application-defined data specific to a particular instance of the component.
TrustedProcesses	This property includes a collection of trusted processes.

Method List

The following is the full list of the methods of the component with short descriptions. Click on the links for further details.


AddEncryptionRule	This method adds a new rule for file encryption.
AddTrustedProcess	Adds a rule that allows a process to access decrypted data of a file.
ChangePassword	This method changes the password of a file.
Config	Sets or retrieves a configuration setting.
DecryptFile	This method decrypts a file.
EncryptFile	This method encrypts a file.
FileMatchesMask	This method checks whether a particular file or directory name matches the specified mask.
GetDOSPathName	This method retrieves the DOS path name of the file or directory by its native (NT) path.
GetDriverStatus	This method retrieves the status of the component's system driver.
GetDriverVersion	This method retrieves the version of the component's system driver.
GetNTPathName	This method retrieves the NT (native) path name of the file or directory by its DOS path.
GetOriginatorProcessId	Retrieves the Id of the process (PID) that initiated the operation.
GetOriginatorProcessName	Retrieves the name of the process that initiated the operation.
GetOriginatorToken	Retrieves the security token associated with the process that initiated the operation.
GetVolumeGUID	This method retrieves the volume GUID of the device targeted by a filesystem operation.
Initialize	This method initializes the component.
Install	This method installs (or upgrades) the component's system driver.
IsFileEncrypted	Checks whether the specified file is encrypted.
RemoveEncryptionRule	This method removes an encryption rule from the list.
RemoveTrustedProcess	Removes a rule that allows a process to access the decrypted data of an encrypted file.
ResetTimeout	This method resets the timeout duration for the current event handler.
ShutdownSystem	Shuts down or reboots the operating system.
Start	This method starts monitoring the filesystem and encrypting and decrypting files.
Stop	This method stops monitoring of filesystem operations.
Uninstall	This method uninstalls the component's system driver.

Event List

The following is the full list of the events fired by the component with short descriptions. Click on the links for further details.


AfterFilterAttachToVolume	This event fires after the filter attaches to a newly mounted filesystem volume.
AfterFilterDetachFromVolume	This event fires after the filter detaches from a filesystem volume.
BeforeFilterAttachToVolume	This event fires before the filter attaches to a newly mounted filesystem volume.
CloseFile	This event fires when a file or directory is closed.
Error	This event fires if an unhandled error occurs during an event.
OpenFile	The event fires when a file or directory is created or opened.
PasswordNeeded	This event fires if a password is needed to open an encrypted file.
Progress	This event fires to indicate the progress of long-running encryption/decryption operations.
RenameOrMoveFile	This event fires when a file is renamed or moved.

Config Settings

The following is a list of config settings for the component with short descriptions. Click on the links for further details.


DenyUntrustedWrite	Whether write operations from untrusted processes are blocked.
EncryptAlternateDataStreams	Whether alternate data streams of files are also encrypted.
LazyEncrypt	Whether a file is encrypted or decrypted when it is written to or when it is closed.
LoggingEnabled	Whether extended logging is enabled.
MaxWorkerThreadCount	The maximum number of worker threads to use to fire events.
MinWorkerThreadCount	The minimum number of worker threads to use to fire events.
NormalizeShortFileNames	Whether the driver should attempt to resolve short file names and convert them to regular ones.
ResolveNtDeviceToDriveLetter	Whether native device names are translated to drive letters.
WorkerInitialStackSize	The initial stack size to create worker threads with.
BuildInfo	Information about the product's build.
LicenseInfo	Information about the current license.

Active Property (CBEncrypt Component)

This property notes whether the component is active and processing requests.

Syntax

property Active: Boolean read get_Active;

Default Value

false

Remarks

This property reflects whether the component is active and currently processing requests. It will be True after the filter has been attached successfully via a call to Start.

This property is read-only and not available at design time.

Altitude Property (CBEncrypt Component)

This property specifies the altitude the component's system driver should use .

Syntax

property Altitude: String read get_Altitude write set_Altitude;

Default Value

Remarks

This property specifies the altitude that the component's system driver should use . A driver's altitude determines its absolute position in the stack of filter drivers; drivers with higher altitudes are attached toward the top of the stack, closer to the user mode, which allows them to process requests earlier.

If multiple instances of the component are used, each instance must have own altitude.

Microsoft manages and assigns filesystem minifilter driver altitudes directly, so an application-specific altitude value must be obtained from Microsoft before an application is deployed in production. Please refer to the Driver Altitudes topic for more information. During development, an appropriate arbitrary value, such as 360000 (which is not registered with Microsoft), can be used.

If this property is queried before an altitude has been set (via this property or the Install method), it will return an empty string.

NOTE: This property cannot be changed when Active is True. Additionally, the Initialize method must be called before attempting to get or set this property's value, which is stored in the registry.

EncryptionRules Property (CBEncrypt Component)

This property includes the collection of encryption rules.

Syntax

property EncryptionRules: TcbeEncryptionRuleList read get_EncryptionRules;

Remarks

This property holds a collection of EncryptionRule objects, each of which represents a file encryption rule with a path and encryption parameters.

Each encryption rule represents a protected directory. Trusted processes included in the TrustedProcesses collection will have access to the decrypted contents of files within these directories. Untrusted processes will not have access to decrypted data and will see only the encrypted contents. Rules can also specify whether subdirectories are included in the protection scope.

Use the following methods to manage the rules in this collection:

AddEncryptionRule
RemoveEncryptionRule

NOTE: The methods and properties related to managing encryption rules are not intended to be used from multiple threads at once. Applications that wish to use said methods and properties from multiple threads (e.g., during the AfterFilterAttachToVolume and AfterFilterDetachFromVolume events) are responsible for employing proper thread synchronization techniques to ensure that manipulation and enumeration of the lists occur in a thread-safe manner.

This property is read-only and not available at design time.

Please refer to the EncryptionRule type for a complete list of fields.

FireVolumeEvents Property (CBEncrypt Component)

This property specifies the events that should be fired when a filesystem volume is mounted to or unmounted from the system.

Syntax

property FireVolumeEvents: Integer read get_FireVolumeEvents write set_FireVolumeEvents;

Default Value

Remarks

This property specifies the events that the component should fire when a filesystem volume is mounted to or unmounted from the system. Possible values are as follows:


FS_MOUNT_IGNORE	`0`	Don't fire any events when volumes are mounted or unmounted.
FS_MOUNT_CONTROL	`128`	Fire Control Events when volumes are mounted or unmounted. The BeforeFilterAttachToVolume, AfterFilterAttachToVolume, and AfterFilterDetachFromVolume events will fire, synchronously, as necessary.

Note The aforementioned events are fired only for volumes mounted or unmounted after the Start method is called. Typically, applications use these events to dynamically add encryption rules for removable volumes, such as USB drives.

GlobalSalt Property (CBEncrypt Component)

The value being mixed into the process of key derivation.

Syntax

property GlobalSalt: String read get_GlobalSalt write set_GlobalSalt;
property GlobalSaltB: TBytes read get_GlobalSaltB write set_GlobalSaltB;

Default Value

Remarks

This property specifies a global salt value that is mixed into the key derivation process when deriving an encryption key from a password. A salt increases security by ensuring that identical passwords produce different keys.

This property should be set to a random string or byte array of 16 bytes in length. If the value is longer than 16 bytes, only the first 16 bytes are used. If the value is shorter than 16 bytes, the Start method will throw an exception.

Using a cryptographically strong random number generator is recommended for increased security.

SerializeEvents Property (CBEncrypt Component)

Whether events should be fired on a single worker thread, or many.

Syntax

property SerializeEvents: TcbeTSerializeEvents read get_SerializeEvents write set_SerializeEvents;

TcbeTSerializeEvents = (
  seOnMultipleThreads,
  seOnOneWorkerThread
);

Default Value

seOnMultipleThreads

Remarks

This property specifies whether the component should fire all events serially on a single worker thread, or concurrently on multiple worker threads. The possible values are:


0 (seOnMultipleThreads)	The component fires events in the context of multiple worker threads. The MinWorkerThreadCount and MaxWorkerThreadCount configuration settings control how many worker threads are used for this.
1 (seOnOneWorkerThread)	The component fires events in the context of one background worker thread.

Please refer to the Threading and Concurrency topic for more information.

NOTE: This property cannot be changed when Active is True, and it cannot be changed within events.

Tag Property (CBEncrypt Component)

This property stores application-defined data specific to a particular instance of the component.

Syntax

property Tag: Int64 read get_Tag write set_Tag;

Default Value

Remarks

This property can be used to store data specific to a particular instance of the component.

TrustedProcesses Property (CBEncrypt Component)

This property includes a collection of trusted processes.

Syntax

property TrustedProcesses: TcbeTrustedProcessList read get_TrustedProcesses;

Remarks

This property contains the list of TrustedProcess entries. Each entry specifies a process that is allowed to access decrypted data of files within the directories defined by the EncryptionRules collection. When a trusted process opens an encrypted file, the component automatically decrypts the data on the fly, allowing the process to read or write the file as if it were unencrypted.

Processes not included in this collection are considered untrusted, and file-related events will not fire for these processes. Untrusted processes may read encrypted files (they will see only encrypted content), but are blocked from modifying them. This includes writing data, changing file size or allocation, or opening files in modes that overwrite, truncate, or supersede existing content. The DenyUntrustedWrite configuration setting controls this behavior and is enabled by default.

Please refer to the AddTrustedProcess and RemoveTrustedProcess methods for more information.

NOTE: The methods and properties related to process access lists are not intended to be used from multiple threads at once. Applications that wish to use said methods and properties from multiple threads are responsible for employing proper thread synchronization techniques to ensure that manipulation and enumeration of process access information occurs in a thread-safe manner.

This property is read-only and not available at design time.

Please refer to the TrustedProcess type for a complete list of fields.

AddEncryptionRule Method (CBEncrypt Component)

This method adds a new rule for file encryption.

Syntax

function AddEncryptionRule(Path: String; IncludeSubdirectories: Boolean; Password: String): Boolean;

Remarks

This method adds a new encryption rule that defines how certain files must be encrypted and decrypted.

The Path parameter must be a valid path to the directory, in which files will be encrypted, and IncludeSubdirectories specifies whether or not the rule is recursive (i.e., covers files in subdirectories).

To encrypt a file, the Password parameter is used.

For more information, see Encryption.

The component stores the parameters in the list. Adding the same path several times will create only one rule for each distinct path, and consequent calls to AddEncryptionRule with different parameters will be ignored. The application can remove a rule using the RemoveEncryptionRule method, and then can add a new rule using AddEncryptionRule.

The method will return True if the rule was added to the list and False otherwise.

AddTrustedProcess Method (CBEncrypt Component)

Adds a rule that allows a process to access decrypted data of a file.

Syntax

procedure AddTrustedProcess(ProcessFileName: String; ProcessId: Integer; ChildProcesses: Boolean);

Remarks

This method can be used to add an access rule that grants the process specified by ProcessFileName or ProcessId access to decrypted data of an encrypted file. If no rules are added, access is not permitted to any process.

Processes that are already running can be specified by passing their process Id (PID) for the ProcessId parameter (in which case ProcessFileName should be empty). Processes that have not yet started can be specified by passing the full file name of the process's executable file for ProcessFileName (in which case ProcessId should be set to 0). If ProcessName is empty, and ProcessId is -1, the new rule will apply to all processes. When adding a PID-based rule, you need to be aware of the PID Reuse behavior of Windows.

ChildProcesses controls whether the rule also applies to children of the target process.

To remove the process access rule later, pass the same ProcessFileName and ProcessId values to the RemoveTrustedProcess method.

NOTE: This method cannot be called within events.

The methods and properties related to process access lists are not intended to be used from multiple threads at once. Applications that wish to use said methods and properties from multiple threads are responsible for employing proper thread synchronization techniques to ensure that manipulation and enumeration of process access information occurs in a thread-safe manner.

ChangePassword Method (CBEncrypt Component)

This method changes the password of a file.

Syntax

procedure ChangePassword(FileName: String; OldPassword: String; NewPassword: String);

Remarks

This method changes the password used to encrypt the file specified by FileName.

If the file is not encrypted and the new password is not empty, the file will be encrypted. If the file is encrypted and the new password is empty, the file will be decrypted.

The OldPassword parameter specifies the current encryption password, if applicable.

The NewPassword parameter specifies the new encryption password to use, if applicable.

Config Method (CBEncrypt Component)

Sets or retrieves a configuration setting.

Syntax

function Config(ConfigurationString: String): String;

Remarks

Config is a generic method available in every component. It is used to set and retrieve configuration settings for the component.

These settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the component, access to these internal properties is provided through the Config method.

To set a configuration setting named PROPERTY, you must call Config("PROPERTY=VALUE"), where VALUE is the value of the setting expressed as a string. For boolean values, use the strings "True", "False", "0", "1", "Yes", or "No" (case does not matter).

To read (query) the value of a configuration setting, you must call Config("PROPERTY"). The value will be returned as a string.

DecryptFile Method (CBEncrypt Component)

This method decrypts a file.

Syntax

procedure DecryptFile(FileName: String; Password: String);

Remarks

This method decrypts the file specified by FileName.

If the file is not encrypted, the method returns.

The Password parameter specifies the password to use to decrypt the file.

EncryptFile Method (CBEncrypt Component)

This method encrypts a file.

Syntax

procedure EncryptFile(FileName: String; Password: String);

Remarks

This method encrypts the file specified by FileName, if it is not already encrypted.

If the file is encrypted, the method reports an error. Use ChangePassword method to change the file password.

The Password parameter specifies the encryption password to use.

FileMatchesMask Method (CBEncrypt Component)

This method checks whether a particular file or directory name matches the specified mask.

Syntax

function FileMatchesMask(Mask: String; FileName: String; CaseSensitive: Boolean): Boolean;

Remarks

This method checks whether the file or directory name specified by FileName matches Mask; if it does, this method returns True. The CaseSensitive parameter controls whether a case-sensitive match should be performed.

NOTE: This method does not handle so-called DOS_* wildcards (DOS_STAR, DOS_QM, DOS_DOT). The explanation about the characters can be found in the MSDN article. If you have a mask that includes one of those characters on Windows, you can use the RtlIsNameInExpression function of Windows API.

NOTE: As the explanation states, "When you do a case-insensitive search and do not provide a translation table, the name is converted to uppercase."

GetDOSPathName Method (CBEncrypt Component)

This method retrieves the DOS path name of the file or directory by its native (NT) path.

Syntax

function GetDOSPathName(NTPath: String): String;

Remarks

This method retrieves the DOS path name of the file or directory by its native path, specified in the NTPath parameter.

NOTE: Such name conversion is not always possible (e.g., the volume can have none or more than one DOS names). In this case, an empty string is returned.

NOTE: This method can be called only within events, and it must be called in the same thread that the event was originally fired on.

GetDriverStatus Method (CBEncrypt Component)

This method retrieves the status of the component's system driver.

Syntax

function GetDriverStatus(ProductGUID: String): Integer;

Remarks

This method retrieves the status of the component's system driver. This status can then be used to verify whether it has been properly installed and is ready for use.

The value returned by the method corresponds to the dwCurrentState field of the SERVICE_STATUS structure from the Windows API. It will be one of the following:


MODULE_STATUS_NOT_PRESENT	`0x00000000`	The specified module is not present on the system.
MODULE_STATUS_STOPPED	`0x00000001`	The specified module is in the Stopped state.
MODULE_STATUS_RUNNING	`0x00000004`	The specified module is loaded and running.

ProductGUID is used to distinguish among driver installations performed by different applications as well as separate filter instances. Such information is necessary to guard against unexpected situations, such as the driver being uninstalled by one application despite other applications still needing it.

Therefore, to ensure proper operation, it is critical that each individual application have its own unique ProductGUID value, and that applications (and their installation scripts) use that value when calling any of the following methods:

Install
Uninstall
GetDriverStatus
GetDriverVersion
Initialize

Additionally, some per-instance settings are stored in the GUID-specific registry keys. If multiple instances of the component are used, each instance must have own ProductGUID, and the driver must be installed several times.

This method is available in both the component API and the Installer DLL included with the product; please refer to the Driver Installation topic for more information about the latter.

NOTE: This method cannot be called within events.

GetDriverVersion Method (CBEncrypt Component)

This method retrieves the version of the component's system driver.

Syntax

function GetDriverVersion(ProductGUID: String): Int64;

Remarks

This method retrieves the version of the component's system driver. The value is returned as a 64-bit integer composed of four 16-bit words that each correspond to a piece of the overall module version. For example, a version of 2.32.6.28 would cause the value 0x000200200006001C to be returned.

If the component's system driver is not installed, this method returns 0.

Install
Uninstall
GetDriverStatus
GetDriverVersion
Initialize

This method is available in both the component API and the Installer DLL included with the product; please refer to the Driver Installation topic for more information about the latter.

NOTE: This method cannot be called within events.

GetNTPathName Method (CBEncrypt Component)

This method retrieves the NT (native) path name of the file or directory by its DOS path.

Syntax

function GetNTPathName(DOSPath: String): String;

Remarks

This method retrieves the NT (native) path name of the file or directory by its path, specified in the DOSPath parameter.

GetOriginatorProcessId Method (CBEncrypt Component)

Retrieves the Id of the process (PID) that initiated the operation.

Syntax

function GetOriginatorProcessId(): Integer;

Remarks

This method can be called within events fired for filesystem operations to retrieve the Id of the process (PID) that initiated the operation. If the query fails, this method returns 0.

Please note that PIDs are not unique, and may be reused by different processes over time.

Applications cannot use this method to retrieve information about remote processes accessing virtual drives shared on the network. Windows does not provide such information due to the nature of remote access.

NOTE: This method can be called only within events, and it must be called in the same thread that the event was originally fired on.

GetOriginatorProcessName Method (CBEncrypt Component)

Retrieves the name of the process that initiated the operation.

Syntax

function GetOriginatorProcessName(): String;

Remarks

This method can be called within events fired for filesystem operations to retrieve the name of the process that initiated the operation. If the query fails, this method returns empty string.

NOTE: This method can be called only within events, and it must be called in the same thread that the event was originally fired on.

GetOriginatorToken Method (CBEncrypt Component)

Retrieves the security token associated with the process that initiated the operation.

Syntax

function GetOriginatorToken(): Int64;

Remarks

This method can be called within events fired for filesystem operations to retrieve the security token associated with the process that initiated the operation. If the query fails, this method returns INVALID_HANDLE_VALUE. NOTE: To use this method from Notify* event handlers, you need to enable the CaptureTokenForNotifyEvents setting.

The security token returned by this method can be passed to the Windows API's GetTokenInformation function to obtain more information about the process. This is particularly useful for implementing custom security checks; please refer to the Security Checks topic for more information.

Important: When applications are finished using the returned security token, they must close it using the Windows API's CloseHandle function.

Network Access Notes

For virtual drives shared on the network, applications may wish to obtain information about the network users accessing it (e.g., account names). Drives can be shared in several modes in Windows, which can affect the information retrievable via the security token this method returns:

Authenticated mode, in which case the Helper DLL (which, in general, is responsible for relaying remote drive requests to and from the system driver) will impersonate the network user, allowing that account's actual information to be retrieved.
Guest mode, in which case the retrievable information is for the system's GUEST account.
Administrative shares (those which exist by default and whose names end with '$'; e.g., C$, ADMIN$, etc.), in which case the retrievable information is for the LOCAL_SYSTEM account.

NOTE: This method can be called only within events, and it must be called in the same thread that the event was originally fired on.

GetVolumeGUID Method (CBEncrypt Component)

This method retrieves the volume GUID of the device targeted by a filesystem operation.

Syntax

function GetVolumeGUID(): String;

Remarks

This method can be called within events fired for filesystem operations to retrieve the volume GUID of the device targeted by the operation, returned in the Volume{xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx} format. If the query fails, this method returns an empty string.

Volume GUIDs can be used to enumerate the mounting points of a device using the Windows API's GetVolumePathNamesForVolumeName function.

NOTE: This method can be called only within events.

Initialize Method (CBEncrypt Component)

This method initializes the component.

Syntax

procedure Initialize(ProductGUID: String);

Remarks

This method initializes the component and must be called each time the application starts before attempting to call any of the component's other methods with the exception of installation-related methods.

ProductGUID is used to distinguish between driver installations performed by different applications. Such information is necessary to guard against unexpected situations such as, e.g., the driver being uninstalled by one application despite other applications still needing it.

The GUID must be specified in so-called "Registry Format" (e.g., "{1FAD0EF2-9A03-4B87-B4BC-645B7035ED90}") with curly braces included.

To ensure proper operation, it is critical that each individual application have its own unique ProductGUID value, and that applications (and their installation scripts) use that value when calling any of the following methods:

Install
Uninstall
GetDriverStatus
GetModuleVersion
RegisterIcon
UnregisterIcon
Initialize

If the required driver was not installed using the Install method with the same value of ProductGUID, Initialize will return a ERROR_FILE_NOT_FOUND error (Win32 error code 2).

If the loaded kernel-mode driver is older than the user-mode API, Initialize will return a ERROR_INVALID_KERNEL_INFO_VERSION error (Win32 error code 340). In this situation, an update of the driver using the Install method is required before the component can be used.

Install Method (CBEncrypt Component)

This method installs (or upgrades) the component's system driver.

Syntax

function Install(CabFileName: String; ProductGUID: String; PathToInstall: String; Altitude: String; Flags: Integer; AllowedControllers: String): Boolean;

Remarks

This method is used to install or upgrade the component's system driver. If the system must be rebooted to complete the installation process, this method returns True; otherwise, it returns False.

Important: To upgrade the product's modules, use only the Install method. Previously installed versions of the modules should not be uninstalled first. Calling the Install method will upgrade the previously installed version.

Please refer to the Driver Installation topic for more information.

CabFileName must be the path of the cbfilter.cab file containing the component's system driver.

NOTE: This .cab file must remain on the target system (or be available in some other way) after installation, as it is required to uninstall the driver from the system.

Install
Uninstall
GetDriverStatus
GetDriverVersion
Initialize

PathToInstall controls where the driver is installed. Pass empty string (highly recommended) to automatically install them to the appropriate Windows system directory.

Altitude specifies the driver altitude to use . During development, you can use any acceptable altitude value. For deployment, an altitude value must be assigned by Microsoft before deploying a filesystem minifilter in production. After installation, the altitude can be changed at any time using the Altitude property. Please refer to the Driver Altitudes topic for more information.

If multiple instances of the component are used, each instance must have own altitude.

Flags specifies various installation options. It should be created by OR'ing together (e.g., "cbeconstants.CONST_A or cbeconstants.CONST_B") zero or more of the following flags:


INSTALL_REMOVE_OLD_VERSIONS	`0x00000001`	Uninstall drivers from previous component versions (e.g., 2020).
INSTALL_KEEP_START_TYPE	`0x00000002`	Keep the driver's current start type setting in the registry. If this flag is not set (default), the installation logic will reset the driver's start type setting in the Windows registry to the default value. Setting this flag causes the installation logic to preserve the current value, which may be necessary if the user (or the application) set it previously.
INSTALL_OVERWRITE_SAME_VERSION	`0x00000004`	Install the driver file when its version and build number is the same as the version of the already installed driver.
INSTALL_REQUESTS_VIA_DRIVER_STACK	`0x00001000`	Whether internal requests to the filesystem are sent directly to the filesystem driver or through the stack of filesystem filter drivers. This flag is applicable only for CBFILTER and CBMONITOR. After installation, the effects of this flag can be changed using the SendRequestsViaDriverStack configuration setting.
INSTALL_ALWAYS_PREPARE_FILES	`0x00010000`	Whether the driver should keep track of information for files that are already open when (i.e., were opened before) the component is initialized. This flag is applicable only for CBFILTER and CBMONITOR. If this flag is set, the driver will prepare information about each file as it is opened, regardless of whether a CBFILTER/CBMONITOR-based application is actually running at the time. This information then allows applications to receive events for any files that are already open when the CBFILTER/CBMONITOR component is initialized. NOTE: These preparations will slow down all file open operations; do not enable this feature unless it is actually necessary. After installation, the effects of this flag can be changed using the AlwaysPrepareFiles configuration setting.
INSTALL_FORCE_APP_PERMISSION_CHECK	`0x00020000`	Whether the driver should require the controller process to have elevated or system privileges. This flag is not applicable for CBPROCESS. If this flag is set, the driver will verify that the controller process is a system service (or is executing with elevated privileges) anytime a file is opened. If the controller process does not meet these requirements, the file will be skipped (i.e., not filtered in any way). NOTE: This additional verification will slow down all file open operations. After installation, the effects of this flag can be changed using the ForceAppPermissionCheck configuration setting.
INSTALL_FORCE_SECURITY_CHECKS	`0x00040000`	Whether the driver should prevent the controller process from filtering files that it would not normally have access to. This flag is not applicable for CBPROCESS. If this flag is set, the driver will check the security permissions of the controller process anytime a file is opened to verify that the process has access to the file. If the controller process does not have access to the file, the file will be skipped (i.e., not filtered in any way). For example, if this flag is set and the controller process is running with limited privileges, then the driver will not allow it to filter files that require greater privileges to access. NOTE: This additional verification will slow down all file open operations. After installation, the effects of this flag can be changed using the ForceSecurityChecks configuration setting.
INSTALL_SKIP_PREPARING_FILES_WITH_NO_RULES	`0x00080000`	Whether the driver should keep track of information for opened files which are not covered by any rules. This flag is applicable only for CBFILTER and CBMONITOR. If this flag is not set, the driver will prepare information about each file as it is opened, regardless of whether this file matches any of the rules tha exist at the time of file opening. The prepared information is used to keep track of file names (especially during file renaming or when hard links are managed). This flag can be used to optimize the filtering process and reduce the load on the kernel memory in scenarios, where filtering rules are defined beforehand and cover only a subset of files or directories. I.e., the flag brings no benefit if a rule is set with the '.' mask or when it is set to 'C:\.' with only drive C: available in the system. The flag will be effective only when all instances of the component have it set. If any of the instances doesn't have it set, the information is prepared for all files and is used for all instances. After installation, the effects of this flag can be changed using the SkipPreparingFilesWithNoRules configuration setting.

NOTE: Enabling the AlwaysPrepareFiles and/or SendRequestsViaDriverStack configuration settings before calling this method will cause the corresponding flags to be added automatically. These configuration settings can also be used to toggle the corresponding options at any time after installation.

AllowedControllers is the optional parameter that makes it possible to limit communication with the driver to just the predefined set of processes. When the caller specifies one or more names of the executable files, filtering can be started with the specified ProductGUID only when filtering is initiated by the process created from one of the listed executable files. If the name of the caller process does not match any of the allowed names, the call to Start will fail with an error.

The parameter may be either empty or contain one or more EXE file names with complete paths. Separate names/paths should be separated by the LF character (numeric code 10).

This method is available in both the component API and the Installer DLL included with the product; please refer to the Driver Installation topic for more information about the latter.

This method requires administrative rights to execute successfully. If the user account of the process that calls this method doesn't have such rights, the call will fail with an ERROR_PRIVILEGE_NOT_HELD ($0522) error.

NOTE: This method cannot be called within events.

IsFileEncrypted Method (CBEncrypt Component)

Checks whether the specified file is encrypted.

Syntax

function IsFileEncrypted(FileName: String): Boolean;

Remarks

This method checks whether the file specified by FileName is encrypted using the component.

RemoveEncryptionRule Method (CBEncrypt Component)

This method removes an encryption rule from the list.

Syntax

function RemoveEncryptionRule(Path: String): Boolean;

Remarks

This method removes an encryption rule, identified by Path, from the list of encrypted rules.

The method will return True if the rule that includes the path was found in the list and was removed, and False otherwise.

RemoveTrustedProcess Method (CBEncrypt Component)

Removes a rule that allows a process to access the decrypted data of an encrypted file.

Syntax

procedure RemoveTrustedProcess(ProcessFileName: String; ProcessId: Integer);

Remarks

This method can be used to remove an access rule previously added with the AddTrustedProcess method.

Pass the same values for ProcessFileName and ProcessId as were used to add the rule when AddTrustedProcess was called previously. Please refer to that method's documentation for more information.

NOTE: This method cannot be called within events.

ResetTimeout Method (CBEncrypt Component)

This method resets the timeout duration for the current event handler.

Syntax

function ResetTimeout(Timeout: Integer): Boolean;

Remarks

When event timeouts are being enforced, this method can be called within an event handler to inform the component that request processing is taking longer than expected.

If called successfully, this method returns True, and the current event handler's timeout timer is immediately reset to 0; when it reaches the number of milliseconds specified by Timeout, the driver will either "release" the underlying request and pass it onwards, or cancel it by reporting an error; whichever is most appropriate for the event in question. Please refer to the Timeouts topic for more information.

Passing 0 for Timeout disables the timeout timer for the current event handler, allowing it to take as long as it needs to complete.

NOTE: When several events are fired for the same file concurrently (if the SerializeAccess configuration setting is disabled), and ResetTimeout is called from one of the handlers of these events, this method will reset the timer for all currently executed event handlers.

NOTE: This method can be called only within events.

ShutdownSystem Method (CBEncrypt Component)

Shuts down or reboots the operating system.

Syntax

function ShutdownSystem(ShutdownPrompt: String; Timeout: Integer; ForceCloseApps: Boolean; Reboot: Boolean): Boolean;

Remarks

This method shuts down or (if Reboot is True) reboots the operating system. If the appropriate privileges cannot be obtained, or if the InitiateSystemShutdown system call returns False, then this method will return False; otherwise, it returns True. This method can be used if the installation or uninstallation function requires the system to be rebooted in order to complete.

ShutdownPrompt, if non-empty, specifies a message that the OS should display to the user for Timeout seconds. If empty string is passed for ShutdownPrompt, no message is displayed and the Timeout parameter's value is ignored.

ForceCloseApps specifies whether the OS should forcefully close all applications. Please keep in mind that forceful closing of applications with unsaved data can lead to data loss.

Reboot specifies whether the OS should reboot (True) or just shut down (False).

This method is available in both the component API and the Installer DLL included with the product; please refer to the Driver Installation topic for more information about the latter.

NOTE: This method cannot be called within events.

Start Method (CBEncrypt Component)

This method starts monitoring the filesystem and encrypting and decrypting files.

Syntax

procedure Start(Timeout: Integer);

Remarks

This method starts filesystem monitoring and handling of operations with files that must be encrypted or decrypted. Rules can be added and removed both before and after this method is called, so long as the Initialize method is called before doing anything else.

This method can fail for a number of reasons, including (but not limited to) the following:

If the component's system driver has not been properly installed, or is awaiting a system reboot (as indicated by the return value of Install), this method fails with an ERROR_FILE_NOT_FOUND (2) error code.
If the Initialize method has not been called yet, this method fails with an ERROR_NOT_READY (21) error code.
If the filter is already Active, this method fails with an ERROR_CONNECTION_ACTIVE (1230) error code.
If an invalid value is passed for Timeout, this method fails with an ERROR_IMPLEMENTATION_LIMIT (1292) error code.

Timeout

Timeout specifies how many milliseconds the driver should wait for events to execute before releasing or cancelling the underlying OS requests; please refer to the Timeouts topic for more information. Valid values are 0, which disables event timeouts, and values greater than or equal to 3000. When event timeouts are in effect, event handlers can call ResetTimeout to reset the timer if they require additional time to complete.

Stop Method (CBEncrypt Component)

This method stops monitoring of filesystem operations.

Syntax

procedure Stop();

Remarks

This method stops monitoring of filesystem operations and encrypting and decrypting files.

The method returns after monitoring is stopped.

Uninstall Method (CBEncrypt Component)

This method uninstalls the component's system driver.

Syntax

function Uninstall(CabFileName: String; ProductGUID: String; InstalledPath: String; Flags: Integer): Boolean;

Remarks

This method is used to uninstall the component's system driver. If the system must be rebooted to complete the uninstallation process, this method returns True; otherwise, it returns False.

Please refer to the Driver Installation topic for more information.

The same values must be passed for the CabFileName, ProductGUID, and InstalledPath parameters as were passed when Install was called; please refer to its documentation for more information.

Flags specifies which versions of the component's system driver should be uninstalled and which should be set by OR'ing together (e.g., "cbeconstants.CONST_A or cbeconstants.CONST_B") one or more of the following values:


UNINSTALL_VERSION_PREVIOUS	`0x00000001`	Uninstall modules from previous product versions.
UNINSTALL_VERSION_CURRENT	`0x00000002`	Uninstall modules from the current product version.
UNINSTALL_VERSION_ALL	`0x00000003`	Uninstall modules from all product versions.

This method is available in both the component API and the Installer DLL included with the product; please refer to the Driver Installation topic for more information about the latter.

NOTE: This method cannot be called within events.

AfterFilterAttachToVolume Event (CBEncrypt Component)

This event fires after the filter attaches to a newly mounted filesystem volume.

Syntax

type TAfterFilterAttachToVolumeEvent = procedure (
  Sender: TObject;
  const VolumeName: String;
  const VolumeNameNT: String;
  var ResultCode: Integer
) of Object;

property OnAfterFilterAttachToVolume: TAfterFilterAttachToVolumeEvent read FOnAfterFilterAttachToVolume write FOnAfterFilterAttachToVolume;

Remarks

This event fires after the filter attaches to the newly mounted filesystem volume specified by VolumeNameNT and, when possible, VolumeName. Please refer to the FireVolumeEvents property for more information.

Applications need to handle this event only if the FireVolumeEvents property includes the FS_MOUNT_CONTROL flag.

NOTE: This event won't fire for any volumes skipped during the BeforeFilterAttachToVolume event; please refer to its documentation for more information.

VolumeNameNT contains the name of the volume in the NT-native format, as received from the system. If the ResolveNtDeviceToDriveLetter configuration setting is enabled, and if it was possible to convert the NT name to the DOS format with a drive letter, VolumeName will contain the name in this format; otherwise, it will be empty.

Applications can obtain additional information about a volume by retrieving its GUID using the GetVolumeGUID method, and then using that GUID to call various Windows API functions.

Applications can use this event to add volume-specific rules for the volume that has been mounted (keeping in mind that this event does not fire for volumes that are already present when Start is called). Applications that intend to do so must ensure that proper thread synchronization techniques are used when manipulating or enumerating the rule lists, because this event's handler will always execute in the context of some worker thread. Note: if a path-based rule is added or removed, such a path should use the value from VolumeNameNT to avoid a possible deadlock, which may occur during resolving a DOS name to the NT format.

Applications must be aware that this event fires as a direct response to a filesystem state change (mount or unmount). Various system components or third-party actors can perform supplementary filesystem mounting and unmounting during main unmount operations (e.g., Volume Service is one such component). This can cause seemingly excessive events to be fired, and sometimes they can be fired out of order (such as two *Attach or *Detach events fired in a row).

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Handling topic for more information.

This event is fired synchronously; please refer to the Event Types topic for more information.

AfterFilterDetachFromVolume Event (CBEncrypt Component)

This event fires after the filter detaches from a filesystem volume.

Syntax

type TAfterFilterDetachFromVolumeEvent = procedure (
  Sender: TObject;
  const VolumeName: String;
  const VolumeNameNT: String;
  var ResultCode: Integer
) of Object;

property OnAfterFilterDetachFromVolume: TAfterFilterDetachFromVolumeEvent read FOnAfterFilterDetachFromVolume write FOnAfterFilterDetachFromVolume;

Remarks

This event fires after the filter detaches from the filesystem volume specified by VolumeNameNT and, when possible, VolumeName, typically because of the volume being unmounted. Please refer to the FireVolumeEvents property for more information.

Applications need to handle this event only if the FireVolumeEvents property includes the FS_MOUNT_CONTROL flag.

NOTE: This event won't fire for any volumes skipped during the BeforeFilterAttachToVolume event; please refer to its documentation for more information.

Applications should use this event to remove volume-specific rules for the volume that has been unmounted. Applications that intend to do so must ensure that proper thread synchronization techniques are used when manipulating or enumerating the rule lists, because this event's handler will always execute in the context of some worker thread. Note: if a path-based rule is added or removed, such a path should use the value from VolumeNameNT to avoid a possible deadlock, which may occur during resolving a DOS name to the NT format.

This event is fired synchronously; please refer to the Event Types topic for more information.

BeforeFilterAttachToVolume Event (CBEncrypt Component)

This event fires before the filter attaches to a newly mounted filesystem volume.

Syntax

type TBeforeFilterAttachToVolumeEvent = procedure (
  Sender: TObject;
  const VolumeName: String;
  const VolumeNameNT: String;
  var SkipVolume: Boolean;
  var ResultCode: Integer
) of Object;

property OnBeforeFilterAttachToVolume: TBeforeFilterAttachToVolumeEvent read FOnBeforeFilterAttachToVolume write FOnBeforeFilterAttachToVolume;

Remarks

This event fires before the filter attaches to the newly mounted filesystem volume specified by VolumeNameNT and, when possible, VolumeName. Please refer to the FireVolumeEvents property for more information.

Applications need to handle this event only if the FireVolumeEvents property includes the FS_MOUNT_CONTROL flag.

Applications can obtain additional information about a volume by retrieving its GUID using the GetVolumeGUID method, and then using that GUID to call various Windows API functions.

The SkipVolume parameter specifies whether the component's system driver should skip the specified volume (i.e., not attach the filter to it). Setting this parameter to True will cause all filesystem operations that target to volume to be completely ignored by the component's system driver. It also will prevent any of the following events from firing for the volume:

AfterFilterAttachToVolume
AfterFilterDetachFromVolume

This event is fired synchronously; please refer to the Event Types topic for more information.

CloseFile Event (CBEncrypt Component)

This event fires when a file or directory is closed.

Syntax

type TCloseFileEvent = procedure (
  Sender: TObject;
  const FileName: String;
  DesiredAccess: Integer;
  CreateDisposition: Integer;
  Encrypted: Boolean;
  Modified: Boolean;
  var ResultCode: Integer
) of Object;

property OnCloseFile: TCloseFileEvent read FOnCloseFile write FOnCloseFile;

Remarks

This event fires when the file or directory specified by FileName is closed, but only when the file was opened for reading or writing (not for retrieving attributes).

An application can use this event to schedule an asynchronous encryption or decryption operation on the file.

The DesiredAccess and CreateDisposition parameters are the same as the ones that were passed with the OpenFile event that opened the file.

The Encrypted parameter indicates whether the file is currently encrypted.

The Modified parameter indicates whether the file was modified while being opened. Modifications include writing to the file, changing its size or Valid Data Length, as well as opening a file in one of the overwrite or "supersede" modes, in which file contents are replaced.

This event is fired synchronously; please refer to the Event Types topic for more information.

Error Event (CBEncrypt Component)

This event fires if an unhandled error occurs during an event.

Syntax

type TErrorEvent = procedure (
  Sender: TObject;
  ErrorCode: Integer;
  const Description: String
) of Object;

property OnError: TErrorEvent read FOnError write FOnError;

Remarks

This event fires if an unhandled error occurs during another event. Developers can use this information to track down unhandled errors in an application's event handlers.

OpenFile Event (CBEncrypt Component)

The event fires when a file or directory is created or opened.

Syntax

type TOpenFileEvent = procedure (
  Sender: TObject;
  const FileName: String;
  FileExists: Boolean;
  ExistingAttributes: Integer;
  DesiredAccess: Integer;
  Attributes: Integer;
  ShareMode: Integer;
  Options: Integer;
  CreateDisposition: Integer;
  var Encryption: Integer;
  var Password: String;
  var ResultCode: Integer
) of Object;

property OnOpenFile: TOpenFileEvent read FOnOpenFile write FOnOpenFile;

Remarks

This event fires when the file or directory specified by FileName is created or opened. You can use the FileExists parameter to detect whether the file exists and the CreateDisposition parameter to determine what will happen with the data after the file is opened.

The initial values of DesiredAccess, Attributes, ShareMode, and CreateDisposition parameters reflect the values that were passed for the similarly named parameters of the Windows API's CreateFile function (or, more accurately, the values carried by the IRP_MJ_CREATE I/O Request Packet).

DesiredAccess may contain one or more of the following access flags:


DESIRED_ACCESS_FILE_LIST_DIRECTORY	`0x00000001`	For a directory, the right to list the contents of the directory.
DESIRED_ACCESS_FILE_READ_DATA	`0x00000001`	For a file object, the right to read the corresponding file data. For a directory object, the right to read the corresponding directory data.
DESIRED_ACCESS_FILE_ADD_FILE	`0x00000002`	For a directory, the right to create a file in the directory.
DESIRED_ACCESS_FILE_WRITE_DATA	`0x00000002`	For a file object, the right to write data to the file. For a directory object, the right to create a file in the directory
DESIRED_ACCESS_FILE_ADD_SUBDIRECTORY	`0x00000004`	For a directory, the right to create a subdirectory.
DESIRED_ACCESS_FILE_APPEND_DATA	`0x00000004`	For a file object, the right to append data to the file. (For local files, write operations will not overwrite existing data if this flag is specified without FILE_WRITE_DATA.) For a directory object, the right to create a subdirectory (FILE_ADD_SUBDIRECTORY).
DESIRED_ACCESS_FILE_READ_EA	`0x00000008`	The right to read extended file attributes.
DESIRED_ACCESS_FILE_WRITE_EA	`0x00000010`	The right to write extended file attributes.
DESIRED_ACCESS_FILE_EXECUTE	`0x00000020`	For a native code file, the right to execute the file. This access right given to scripts may cause the script to be executable, depending on the script interpreter.
DESIRED_ACCESS_FILE_DELETE_CHILD	`0x00000040`	For a directory, the right to delete a directory and all the files it contains, including read-only files.
DESIRED_ACCESS_FILE_READ_ATTRIBUTES	`0x00000080`	The right to read file attributes.
DESIRED_ACCESS_FILE_WRITE_ATTRIBUTES	`0x00000100`	The right to write file attributes.
DESIRED_ACCESS_READ_CONTROL	`0x00020000`	The right to read the information in the file or directory object's security descriptor. This does not include the information in the SACL.
DESIRED_ACCESS_STANDARD_RIGHTS_READ	`0x00020000`	Includes READ_CONTROL, which is the right to read the information in the file or directory object's security descriptor. This does not include the information in the SACL.
DESIRED_ACCESS_STANDARD_RIGHTS_WRITE	`0x00020000`	Same as STANDARD_RIGHTS_READ
DESIRED_ACCESS_STANDARD_RIGHTS_EXECUTE	`0x00020000`	Same as STANDARD_RIGHTS_READ
DESIRED_ACCESS_SYNCHRONIZE	`0x00100000`	The right to use the object for synchronization. This enables a thread to wait until the object is in the signaled state. Some object types do not support this access right.
DESIRED_ACCESS_FILE_ALL_ACCESS	`0x001F01FF`	All possible access rights for a file.
DESIRED_ACCESS_FILE_GENERIC_READ	`0x00120089`	A combinarion of flags that allow reading of the file. NOTE: Don't match received values against this flag. Instead, use flags that specify the rights that you want to verify or add/remove.
DESIRED_ACCESS_FILE_GENERIC_WRITE	`0x00120116`	A combinarion of flags that allow modifications to the file. NOTE: Don't match received values against this flag. Instead, use flags that specify the rights that you want to verify or add/remove.
DESIRED_ACCESS_FILE_GENERIC_EXECUTE	`0x001200A0`	A combinarion of flags that allow execution of the file. NOTE: Don't match received values against this flag. Instead, use flags that specify the rights that you want to verify or add/remove.

Attributes may contain one or more of the following attributes:


FILE_SYS_ATTR_READ_ONLY	`0x00000001`	The file is read-only. Applications can read the file, but cannot write to it or delete it. This attribute is not honored on directories.
FILE_SYS_ATTR_HIDDEN	`0x00000002`	The file or directory is hidden. The file is not included in an ordinary directory listing.
FILE_SYS_ATTR_SYSTEM	`0x00000004`	A file or directory that the operating system uses a part of, or uses exclusively.
FILE_SYS_ATTR_DIRECTORY	`0x00000010`	The entry is a directory.
FILE_SYS_ATTR_ARCHIVE	`0x00000020`	The entry is an archive file or directory. Applications typically use this attribute to mark files for backup or removal.
FILE_SYS_ATTR_NORMAL	`0x00000080`	A file doesn't have other attributes set. This attribute is valid only when used alone.
FILE_SYS_ATTR_TEMPORARY	`0x00000100`	A file that is being used for temporary storage. File systems avoid writing data back to mass storage if sufficient cache memory is available, because typically, an application deletes a temporary file after the handle is closed. In that scenario, the system can entirely avoid writing the data. Otherwise, the data are written after the handle is closed.
FILE_SYS_ATTR_SPARSE_FILE	`0x00000200`	A file that is a sparse file.
FILE_SYS_ATTR_REPARSE_POINT	`0x00000400`	A file that is a reparse point or a symbolic link.
FILE_SYS_ATTR_COMPRESSED	`0x00000800`	A file or directory that is compressed. For a file, all of the data in the file are compressed. For a directory, compression is the default for newly created files and subdirectories. A filesystem implementation can make use of this attribute by setting the SupportCompressedAttribute property to `True` and then properly handling the GetFileInfo, EnumerateDirectory, and SetFileAttributes events.
FILE_SYS_ATTR_OFFLINE	`0x00001000`	The data of a file are not available immediately. This attribute indicates that the file data are physically moved to offline storage.
FILE_SYS_ATTR_NOT_CONTENT_INDEXED	`0x00002000`	The file or directory is not to be indexed by the content indexing service.
FILE_SYS_ATTR_ENCRYPTED	`0x00004000`	A file or directory that is encrypted. For a file, all data streams in the file are encrypted. For a directory, encryption is the default for newly created files and subdirectories. NOTE: This flag is used by NTFS and the OS sends undocumented requests to the filesystem based on this flag. The flag should not be used for files in custom filesystem implementations.
FILE_SYS_ATTR_VIRTUAL	`0x00010000`	Reserved. NOTE: This flag is reserved by the OS and should not be used for files in custom filesystem implementations.
FILE_SYS_ATTR_RECALL_ON_OPEN	`0x00040000`	The file or directory has no physical representation on the local system; the item is virtual. Opening the item will be more expensive than normal (e.g., it will cause at least some of it to be fetched from a remote store). This flag is reported by filesystems during directory enumerations.

ShareMode may contain zero or more of the following share mode flags:


FILESYS_SHARE_READ	`0x00000001`	Enables subsequent open operations on a file or device to request read access. Enables subsequent open operations to request read access; otherwise, no process can open the file or device if it requests read access. If this flag is not specified, but the file or device has been opened for read access, the function fails.
FILESYS_SHARE_WRITE	`0x00000002`	Enables subsequent open operations on a file or device to request write access. Enables subsequent open operations to request write access; otherwise, no process can open the file or device if it requests write access. If this flag is not specified, but the file or device has been opened for write access or has a file mapping with write access, the function fails.
FILESYS_SHARE_DELETE	`0x00000004`	Enables subsequent open operations on a file or device to request delete access. Enables subsequent open operations to request delete access; otherwise, no process can open the file or device if it requests delete access. If this flag is not specified, but the file or device has been opened for delete access, the function fails. NOTE: Delete access allows both delete and rename operations.

When the file being created or opened is virtual, the event handler must inspect and handle the value of the ShareMode parameter as a filesystem would normally do it.

CreateDisposition may contain one of the following values:


FILE_DISPOSITION_CREATE_NEW	`0x00000001`	Creates a new file, only if it does not already exist. If the specified file exists, the operation fails with an 'already exists' error.
FILE_DISPOSITION_CREATE_ALWAYS	`0x00000002`	Creates a new file, always. If the specified file exists and is writable, the system overwrites the file. If the specified file does not exist and is a valid path, a new file is created.
FILE_DISPOSITION_OPEN_EXISTING	`0x00000003`	Opens a file, only if it exists If the specified file does not exist, opening fails.
FILE_DISPOSITION_OPEN_ALWAYS	`0x00000004`	Opens a file, always. If the specified file exists, the operation succeeds. If the specified file does not exist and is a valid path to a writable location, the a file is created.
FILE_DISPOSITION_TRUNCATE_EXISTING	`0x00000005`	Opens a file and truncates it so that its size is zero bytes, only if it exists. If the specified file does not exist, the operation fails with a 'file not found' error.

When the file being created or opened is virtual, the event handler must inspect and handle the value of the CreateDisposition parameter as a filesystem would normally do it. This includes adjusting the file size and updating the time attributes depending on the flag. For a virtual file, the driver returns the CreationStatus value that is derived from CreateDisposition as follows:


FILE_DISPOSITION_CREATE_NEW	=>	CREATION_STATUS_CREATED
FILE_DISPOSITION_CREATE_ALWAYS	=>	CREATION_STATUS_OVERWRITTEN
FILE_DISPOSITION_OPEN_EXISTING	=>	CREATION_STATUS_OPENED
FILE_DISPOSITION_OPEN_ALWAYS	=>	CREATION_STATUS_OPENED
FILE_DISPOSITION_TRUNCATE_EXISTING	=>	CREATION_STATUS_OVERWRITTEN

If the event handler needs to change the returned CreationStatus, it should change the value of the CreateDisposition to the FILE_DISPOSITION_*** value that leads to the desired CreationStatus value (e.g. set the value to FILE_DISPOSITION_OPEN_EXISTING so that the driver returns CREATION_STATUS_OPENED).

Options contains the flags that are described in the CreateOptions parameter of the Native API's ZwCreateFile function. Most of those flags correspond to flags passed in the FlagsAndAttributes parameter of the Windows API's CreateFile function, but some flags are specific to Native API. If you need those flags, check both functions' descriptions.

Please refer to Microsoft's documentation for detailed information about these constants.

To determine whether the request is for a file or a directory, compare Attributes against the FILE_SYS_ATTR_DIRECTORY constant, as follows: // Check whether the request is for a file or a directory. bool isDirectory = (Attributes & FILE_SYS_ATTR_DIRECTORY) == FILE_SYS_ATTR_DIRECTORY; FILE_SYS_ATTR_DIRECTORY will be present only if it was specified by the calling process; its presence or absence does not indicate the real presence of the attribute on the file or directory on disk.

The attibute may be not present when an existing entry is opened. Thus, the alternative approach is to check the intention of the originator process to open a directory. This is done by verifying whether the Options parameter contains the FILE_DIRECTORY_FILE flag (numeric value 1): // Check whether the request is to open a a directory. bool isDirectory = (Options & 1) != 0; Note that this flag may also be missing, in which case, if the handler needs to know if an existing entry is a file or directory, it should request the attributes of the entry, for example, by opening a direct handle to the entry with the CreateFileDirect method and using the QueryFileInformationDirect method to obtain the attributes.

To determine whether a file will be deleted when its last handle is closed, compare Options against the Windows API's FILE_FLAG_DELETE_ON_CLOSE constant, as follows: // Check whether the file will be deleted on close. bool deleteOnClose = Options & FILE_FLAG_DELETE_ON_CLOSE == FILE_FLAG_DELETE_ON_CLOSE;

NOTE: Files can be deleted in different ways, so do not use this check to take actions related to tracking file deletion operations. Instead, use the events related to file deletion.

To prevent a file or directory from being opened, set the ResultCode parameter to a non-zero value (typically ERROR_ACCESS_DENIED (5)).

To prevent the OS from creating or opening the file, set the ResultCode parameter to a certain error value, such as ACCESS_DENIED (numeric value is 5).

To encrypt a file, the Encryption and Password parameters are used. Encryption specifies the encryption mode and can initially have, or be set to, one of the following values:


FILEENC_EM_UNDEFINED	`-1`	No encryption information specified.
FILEENC_EM_NONE	`0x0`	No encryption is applied.
FILEENC_EM_AES256_PBKDF2_HMAC_SHA256	`0x2`	Use AES256 encryption with PBKDF2 key derivation based on a HMAC_SHA256 key hash.

If the file does not exist or is recreated (superseded), the Encryption parameter will initially be set to 2, and Password will be empty. If the user does not modify either parameter, the new file will be encrypted with the password specified in the relevant EncryptionRule.

If the user sets the Password parameter as something other than an empty string, the new file will be encrypted using that value. Lastly, if the user sets the Encryption parameter to 0, the new file will not be encrypted.

If the file already exists and is not superseded, the values of these parameters are ignored; the password for the existing file is requested through the PasswordNeeded event before OpenFile event is fired.

For more information, see Encryption.

This event is fired synchronously; please refer to the Event Types topic for more information.

PasswordNeeded Event (CBEncrypt Component)

This event fires if a password is needed to open an encrypted file.

Syntax

type TPasswordNeededEvent = procedure (
  Sender: TObject;
  const FileName: String;
  var Password: String;
  var ResultCode: Integer
) of Object;

property OnPasswordNeeded: TPasswordNeededEvent read FOnPasswordNeeded write FOnPasswordNeeded;

Remarks

This event fires when the existing encrypted file specified by FileName is being opened when a valid password has not been provided in the rule. This event will not fire if a valid password has already been provided, or if the file specified by FileName does not exist.

To allow access to the specified file, set the Password parameter to the correct password. To prevent access to the specified file, return the ERROR_ACCESS_DENIED error code via ResultCode.

The event will fire in a loop until a valid password is provided or a nonzero result code is returned.

This event is fired synchronously; please refer to the Event Types topic for more information.

Progress Event (CBEncrypt Component)

This event fires to indicate the progress of long-running encryption/decryption operations.

Syntax

type TProgressEvent = procedure (
  Sender: TObject;
  Operation: Integer;
  const FileName: String;
  Progress: Integer;
  Total: Integer;
  CanStop: Boolean;
  var Stop: Boolean
) of Object;

property OnProgress: TProgressEvent read FOnProgress write FOnProgress;

Remarks

This event fires anytime the component needs to report the progress of a long-running operation, initiated by the application (EncryptFile or DecryptFile). This event can be fired repeatedly during one operation.

The Operation parameter specifies which long-running operation caused this event to fire. Possible values are as follows:


ENC_OP_ENCRYPT	`1`	The file is encrypted.
ENC_OP_DECRYPT	`2`	The file is decrypted.

The FileName contains the path of the file being processed.

The Progress and Total parameters reflect the current and maximum progress values. Both will be 0 if the operation's progression cannot be determined.

The CanStop parameter indicates whether the application may interrupt the operation by setting the Stop parameter to True.

NOTE: An application should not attempt to call component's methods from handlers of this event. Doing this is guaranteed to cause a deadlock.

RenameOrMoveFile Event (CBEncrypt Component)

This event fires when a file is renamed or moved.

Syntax

type TRenameOrMoveFileEvent = procedure (
  Sender: TObject;
  const FileName: String;
  const NewFileName: String;
  var Encryption: Integer;
  var Password: String;
  var ResultCode: Integer
) of Object;

property OnRenameOrMoveFile: TRenameOrMoveFileEvent read FOnRenameOrMoveFile write FOnRenameOrMoveFile;

Remarks

This event fires when the file specified by FileName is renamed or moved to another location, identified by NewFileName.

To prevent the OS from renaming the file, set the ResultCode parameter to a certain error value, such as ACCESS_DENIED (numeric value is 5).

The Encryption and Password parameters are used for file encryption. Encryption specifies the encryption mode to use and can have one of the following values:


FILEENC_EM_UNDEFINED	`-1`	No encryption information specified.
FILEENC_EM_NONE	`0x0`	No encryption is applied.
FILEENC_EM_AES256_PBKDF2_HMAC_SHA256	`0x2`	Use AES256 encryption with PBKDF2 key derivation based on a HMAC_SHA256 key hash.

When this event fires, the Encryption parameter indicates whether the source file is currently encrypted (if 2, the file is encrypted), and Password will be empty. If these parameters remain unchanged, the file will not be modified and will retain its original encryption when renamed or moved.

To change the file's encryption, set the Encryption and/or Password parameters accordingly. For example, if a file is initially encrypted when the event fires, Encryption will be 2. Setting Encryption to 0 will decrypt the resulting file, while assigning a new value to Password will re-encrypt the file using the specified password.

Before making any changes, applications may use the FileMatchesMask helper method to determine whether the new file name matches an existing encryption rule. This allows the application to adjust the Password parameter as needed to ensure the resulting file uses the appropriate rule password for its new location or name. For example, this can be done by iterating through the EncryptionRules collection, and passing the relevant rule path like so:

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

Note that before this event fires, if a file is encrypted, the PasswordNeeded event will fire.

For more information, see Encryption.

This event is fired synchronously; please refer to the Event Types topic for more information.

EncryptionRule Type

This type represents an encryption rule.

Remarks

This type represents a rule for encryption and decryption by CBEncrypt component. Rules can be added to the list using AddEncryptRule.

The following fields are available:

IncludeSubdirectories
Password
Path

Fields

IncludeSubdirectories
Boolean (read-only)
Default Value: True

This property indicates that the mask covers subdirectories and their files.

This property indicates that the rule covers files in the directory as specified by the mask. It also covers files in all subdirectories of this directory.

Password
String (read-only)
Default Value: ""

This property contains the password to use for encryption.

This property contains the encryption password to use.

Path
String (read-only)
Default Value: ""

This property contains the path of the directory to encrypt.

This property contains the path of the directory, the files of which must be encrypted and decrypted. The name is converted to NT native format when the rule is added to the list by AddEncryptRule and is used and returned in the NT native format.

TrustedProcess Type

Represents an access rule granting some process access to decrypted data of files.

Remarks

This type represents an access rule that grants some or all processes access to decrypted data of files encrypted with CBEncrypt.

The following fields are available:

IncludeChildren
ProcessId
ProcessName

Fields

IncludeChildren
Boolean (read-only)
Default Value: False

Whether child processes are affected.

This property indicates whether the rule applies to children of the target process.

ProcessId
Integer (read-only)
Default Value: 0

The Id of the target process.

This property reflects the target process's Id (PID). Will be 0 if the target process was specified by ProcessName, or -1 if the rule applies to all processes.

ProcessName
String (read-only)
Default Value: ""

The filename of the target process's executable.

This property reflects the full file name of the target process's executable. Will be empty if the target process was specified by ProcessId (or if the rule applies to all processes, in which case ProcessId will be -1).

Config Settings (CBEncrypt Component)

The component accepts one or more of the following configuration settings. Configuration settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the component, access to these internal properties is provided through the Config method.

CBEncrypt Config Settings

DenyUntrustedWrite: Whether write operations from untrusted processes are blocked.

This configuration setting controls whether the component blocks write operations originating from untrusted processes. By default, this value is enabled. When enabled, processes not listed in the TrustedProcesses collection will be unable to modify encrypted files. This includes writing data to an existing file, changing the file size, changing the file allocation, and opening a file in modes that would overwrite, truncate, or supersede existing contents.

This behavior ensures that untrusted applications cannot accidentally corrupt encrypted files. Read operations by untrusted processes are still allowed, but they will only see encrypted content.

EncryptAlternateDataStreams: Whether alternate data streams of files are also encrypted.

This configuration setting controls whether the component should encrypt alternate data streams of files that are covered by encryption rules. When the setting is disabled, only the main (unnamed) data stream of the file is encrypted, but you can still create an encryption rule that will explicitly cover an alternate data stream with a specific name.

LazyEncrypt: Whether a file is encrypted or decrypted when it is written to or when it is closed.

This configuration setting controls, at which moment encryption or decryption of a file is performed. When the setting is disabled and an existing plain-text file is opened in the mode that permits writing, the driver encrypts or decrypts the file immediately. If the setting is enabled, encryption/decryption does not start until a process starts writing to the file.

By default, this setting is enabled to improve performance.

LoggingEnabled: Whether extended logging is enabled.

This setting specifies whether extended logging is enabled for this component; it is disabled by default. Please refer to the Error Handling topic for more information.

This setting's value is stored in the registry and is persistent; it requires administrative rights to be changed.

MaxWorkerThreadCount: The maximum number of worker threads to use to fire events.

This setting specifies the maximum number of worker threads the component may create to fire events on when the SerializeEvents property is set to seOnMultipleThreads. (If other cases, this setting does not apply.)

By default, this setting is set to 0, and the driver automatically chooses an optimal number of threads using this equation: 4 * number_of_processors where number_of_processors is the number of logical processors, which are virtual cores, i.e. physical processor cores of all available physical processors adjusted by Hyper-Threading (on Intel CPUs) or Simultaneous Multi-Threading (SMT) (on AMD CPUs) .

MinWorkerThreadCount: The minimum number of worker threads to use to fire events.

This setting specifies the minimum number of worker threads the component should create to fire events on when the SerializeEvents property is set to seOnMultipleThreads. (In other cases, this setting does not apply.)

By default, this setting is set to 0, and the driver automatically chooses an optimal number of threads using this equation: max(number_of_processors, 4). If this setting's value exceeds the MaxWorkerThreadCount value, the latter is used instead.

NormalizeShortFileNames: Whether the driver should attempt to resolve short file names and convert them to regular ones.

This configuration setting specifies how the driver should handle short file names in paths that it deals with. The possible values are

0 - never: Do nothing in regard to the short file names.
1 - on local file systems: Causes the driver to attempt to resolve short file names, but only for local filesystems.
2 - always: Causes the driver to attempt to resolve short file names for files on all filesystems.

This setting is global for all instances of the filter with the same Product GUID (the value specified in a call to the Install method). If the setting is changed by the application with administrative or equivalent rights, the component stores the value in the HKEY_LOCAL_MACHINE key of the registry. Such stored value can be used with default rules. If the value cannot be stored, it is still used by the driver, but only until the system reboots, so it does not affect default rules activated after the reboot.

If an application uses default rules, it should set this setting right after a successful call to the Install method.

Note that this setting only enables the normalization of short names and the use of normalized long names in rule matching; the long name by default is included in the list of names (not on the first position) when the PassAllFileNames setting is enabled. To receive a normalized long name in event handlers when PassAllFileNames is disabled, an application should enable the PassNormalizedShortName configuration setting in addition to this NormalizeShortFileNames setting.

ResolveNtDeviceToDriveLetter: Whether native device names are translated to drive letters.

This configuration setting specifies whether NT native device names, like \Device\HarddiskVolume1\..., should be translated to DOS-style drive letters, like C:\... when possible. However, please note the following:

Such translation will be performed only if a device actually has a corresponding DOS-style drive letter; not all devices do.
The BeforeFilterAttachToVolume event always uses NT native device names, because DOS-style drive letters are not assigned until after it fires.

This setting is enabled by default; it can be disabled to improve performance, or if the application needs the native device name.

NOTE: This setting cannot be changed when Active is True, and it cannot be changed within events.

WorkerInitialStackSize: The initial stack size to create worker threads with.

This setting specifies the initial size of the stack each worker thread is created with. The system rounds this value to the nearest page.

By default, this setting is set to 0, and the driver uses a default stack size (currently, 1 MB).

NOTE: This setting cannot be changed when Active is True, and it cannot be changed within events.

Base Config Settings

BuildInfo: Information about the product's build.

When queried, this setting will return a string containing information about the product's build.

LicenseInfo: Information about the current license.

When queried, this setting will return a string containing information about the license this instance of a component is using. It will return the following information:

Product: The product the license is for.
Product Key: The key the license was generated from.
License Source: Where the license was found (e.g., RuntimeLicense, License File).
License Type: The type of license installed (e.g., Royalty Free, Single Server).

Trappable Errors (CBEncrypt Component)