CBEncrypt Class

Properties   Methods   Events   Config Settings   Errors  

[TBD].

Syntax

cbfsfilter.Cbencrypt

Remarks

TBD

TBD

Property List

---

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

Method List

---

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

Event List

---

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

Config Settings

---

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

Active Property (CBEncrypt Class)

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

Syntax

public boolean isActive();

Default Value

False

Remarks

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

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

Altitude Property (CBEncrypt Class)

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

Syntax

public String getAltitude();


public void setAltitude(String altitude);

Default Value

""

Remarks

This property specifies the altitude that the class'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.

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.

DefaultEncryption Property (CBEncrypt Class)

This property specifies the default encryption mode to use when encrypting files.

Syntax

public int getDefaultEncryption();


public void setDefaultEncryption(int defaultEncryption);

Default Value

0

Remarks

This property specifies the default encryption mode that the class should use when creating files. Valid values are as follows:

Applications also should specify an encryption password. A default password can be set using the DefaultPassword property.

As an alternative to using this property, applications can specify an encryption mode when adding encryption rules with the AddFilterRule method. When both this property and the rule contain the FILEENC_EM_NONE value, the application can dynamically provide the encryption mode using the corresponding parameter of CreateFile and OpenFile events.

DefaultFilePassword Property (CBEncrypt Class)

This property specifies the default encryption password to use when creating or opening files.

Syntax

public String getDefaultFilePassword();


public void setDefaultFilePassword(String defaultFilePassword);

Default Value

""

Remarks

This property specifies the default encryption password that the class should use when creating or opening files.

Please refer to the Encryption topic for more information.

As an alternative to using this property, applications can specify the password when adding encryption rules with the AddFilterRule method. When both this property and the rule contain an empty password, the application can dynamically provide the password using the corresponding parameter of CreateFile and OpenFile events.

EncryptAlternateDataStreams Property (CBEncrypt Class)

This property specifies whether alternate data streams of files are also encrypted.

Syntax

public boolean isEncryptAlternateDataStreams();


public void setEncryptAlternateDataStreams(boolean encryptAlternateDataStreams);

Default Value

False

Remarks

This property controls whether the class should encrypt alternate data streams of files that are covered by encryption rules. When the property is false, 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.

This property is not available at design time.

EncryptRules Property (CBEncrypt Class)

This property includes the collection of encryption rules.

Syntax

public FileEncryptRuleList getEncryptRules();

Remarks

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

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

• AddEncryptRule
• RemoveEncryptRule

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 FileEncryptRule type for a complete list of fields.

FireVolumeEvents Property (CBEncrypt Class)

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

Syntax

public int getFireVolumeEvents();


public void setFireVolumeEvents(int fireVolumeEvents);

Default Value

0

Remarks

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

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

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.

GlobalSalt Property (CBEncrypt Class)

This property [TBD].

Syntax

public String getGlobalSalt();


public void setGlobalSalt(String globalSalt);

Default Value

""

Remarks

TBD.

TBD.

Tag Property (CBEncrypt Class)

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

Syntax

public long getTag();


public void setTag(long tag);

Default Value

0

Remarks

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

AddEncryptRule Method (Cbencrypt Class)

This method adds a new rule for file encryption.

Syntax

public boolean addEncryptRule(String fileMask, boolean includeSubdirectories, int headerSize, int encryption, String password);

Remarks

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

The FileMask parameter must be a valid file mask according to the File Masks topic and IncludeSubdirectories specifies whether or not the mask is recursive (i.e., covers files in subdirectories).

The HeaderSize parameter specifies the size of the additional data that are stored at the beginning of the file. The value passed for this parameter is adjusted by the class to include a component-specific header and align the whole header to the required granularity.

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

For more information, see Encryption.

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

The method will return true if the rule was added to the list and false otherwise.

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.

ChangeEncryption Method (Cbencrypt Class)

This method changes the encryption mode or password of a file.

Syntax

public void changeEncryption(String fileName, int encryption, String oldPassword, String newPassword);

Remarks

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

If the file is not encrypted, it will be encrypted using the specified parameters. If the file is encrypted and the specified new encryption is set to FILEENC_EM_NONE, the file will be decrypted.

The Encryption parameter specifies the new encryption mode to use. Valid values are:

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 Class)

Sets or retrieves a configuration setting.

Syntax

public String config(String configurationString);

Remarks

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

These settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the class, 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 Class)

This method decrypts a file.

Syntax

public void decryptFile(String fileName, String password);

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 Class)

This method encrypts a file.

Syntax

public void encryptFile(String fileName, int encryption, String password);

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 ChangeEncryption method to change the file password or encryption mode.

The Encryption parameter specifies the encryption mode to use. Valid values are as follows:

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

GetDriverStatus Method (Cbencrypt Class)

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

Syntax

public int getDriverStatus(String productGUID);

Remarks

This method retrieves the status of the class'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:

ProductGUID is used to distinguish among driver installations performed by different applications. 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

This method is available in both the class 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 Class)

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

Syntax

public long getDriverVersion(String productGUID);

Remarks

This method retrieves the version of the class'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 class's system driver is not installed, this method returns 0.

ProductGUID is used to distinguish among driver installations performed by different applications. 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

This method is available in both the class 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.

GetFileHeader Method (Cbencrypt Class)

This method retrieves the header of a file.

Syntax

public byte[] getFileHeader(String fileName);

Remarks

This method retrieves the header of the file specified by FileName and returns it.

To set or update the header data, use the SetFileHeader method.

GetHandleCreatorProcessId Method (Cbencrypt Class)

This method retrieves the Id of the process (PID) that opened the file handle.

Syntax

public int getHandleCreatorProcessId();

Remarks

This method can be called within certain events to retrieve the Id of the process (PID) that opened the file handle. If the query fails, this method returns 0.

Note: PIDs are not unique and may be reused by different processes over time (although in practice, this is uncommon).

Applications cannot use this method to retrieve information about remote processes accessing 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 the AfterCreateFile and AfterOpenFile events, and must be called in the same thread that the event was originally fired on. Applications that need the information that this method returns during other events can do the following:

1. Call this method within the AfterCreateFile or AfterOpenFile event.
2. Store the information somewhere, and store a reference to it in the event's HandleContext parameter.
3. In a later event, access the information through the reference stored in HandleContext.

Please refer to the Contexts topic for more information on how to use events' context parameters.

Note: This method cannot be used from CleanupContext event handlers.

GetHandleCreatorProcessName Method (Cbencrypt Class)

This method retrieves the name of the process that opened the file handle.

Syntax

public String getHandleCreatorProcessName();

Remarks

This method can be called within certain events to retrieve the name of the process that opened the file handle. If the query fails, this method returns an empty string.

Applications cannot use this method to retrieve information about remote processes accessing 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 the AfterCreateFile and AfterOpenFile events, and must be called in the same thread that the event was originally fired on. Applications that need the information that this method returns during other events can do the following:

1. Call this method within the AfterCreateFile or AfterOpenFile event.
2. Store the information somewhere, and store a reference to it in the event's HandleContext parameter.
3. In a later event, access the information through the reference stored in HandleContext.

Please refer to the Contexts topic for more information on how to use events' context parameters.

Note: This method cannot be used from CleanupContext event handlers.

GetHandleCreatorThreadId Method (Cbencrypt Class)

This method retrieves the Id of the thread that opened the file handle.

Syntax

public int getHandleCreatorThreadId();

Remarks

This method can be called within certain events to retrieve the Id of the thread that opened the file handle. If the query fails, this method returns 0.

Notes: Thread Ids are not unique and may be reused by different threads over time.

Note: This method can be called only within the AfterCreateFile and AfterOpenFile events, and must be called in the same thread that the event was originally fired on. Applications that need the information that this method returns during other events can do the following:

1. Call this method within the AfterCreateFile or AfterOpenFile event.
2. Store the information somewhere, and store a reference to it in the event's HandleContext parameter.
3. In a later event, access the information through the reference stored in HandleContext.

Please refer to the Contexts topic for more information on how to use events' context parameters.

Note: This method cannot be used from CleanupContext event handlers.

GetHandleCreatorToken Method (Cbencrypt Class)

This method retrieves the security token associated with the process that opened the file handle.

Syntax

public long getHandleCreatorToken();

Remarks

This method can be called within certain events to retrieve the security token associated with the process that opened the file handle. If the query fails, this method returns INVALID_HANDLE_VALUE.

The security token returned by this method can be passed to the Windows API's GetTokenInformation function to obtain more information about the process.

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

Network Access Notes

Applications monitoring a drive shared on the network 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 network redirector (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 the AfterCreateFile and AfterOpenFile events, and must be called in the same thread that the event was originally fired on. Applications that need the information that this method returns during other events can do the following:

1. Call this method within the AfterCreateFile or AfterOpenFile event.
2. Store the information somewhere, and store a reference to it in the event's HandleContext parameter.
3. In a later event, access the information through the reference stored in HandleContext.

Please refer to the Contexts topic for more information on how to use events' context parameters.

Note: This method cannot be used from CleanupContext event handlers.

GetOriginatorProcessId Method (Cbencrypt Class)

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

Syntax

public int getOriginatorProcessId();

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 (though in practice, this is uncommon).

Applications cannot use this method to retrieve information about remote processes accessing 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. However, it must not be called within events that work with opened files since such events can be initiated by system components (e.g., the cache manager, memory manager, etc.). If applications need the information this method returns during such events, they may do the following:

1. Call this method within the CreateFile or OpenFile event.
2. Store the information somewhere, and store a reference to it in the event's HandleContext parameter.
3. In a later event, access the information via the reference stored in HandleContext.

Please refer to the Contexts topic for more information on how to use events' context parameters.

Note: Renaming and deletion of files is performed after the file is opened. Thus, access checks should be performed during file opening as described above.

Note: This method cannot be used from CleanupContext event handlers.

GetOriginatorProcessName Method (Cbencrypt Class)

Retrieves the name of the process that initiated the operation.

Syntax

public String getOriginatorProcessName();

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.

Applications cannot use this method to retrieve information about remote processes accessing 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. However, it must not be called within events that work with opened files since such events can be initiated by system components (e.g., the cache manager, memory manager, etc.). If applications need the information this method returns during such events, they may do the following:

1. Call this method within the CreateFile or OpenFile event.
2. Store the information somewhere, and store a reference to it in the event's HandleContext parameter.
3. In a later event, access the information via the reference stored in HandleContext.

Please refer to the Contexts topic for more information on how to use events' context parameters.

Note: Renaming and deletion of files is performed after the file is opened. Thus, access checks should be performed during file opening as described above.

Note: This method cannot be used from CleanupContext event handlers.

GetOriginatorThreadId Method (Cbencrypt Class)

Retrieves the Id of the thread that initiated the operation.

Syntax

public int getOriginatorThreadId();

Remarks

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

Please note that thread Ids are not unique, and may be reused by different threads over time.

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. However, it must not be called within events that work with opened files since such events can be initiated by system components (e.g., the cache manager, memory manager, etc.). If applications need the information this method returns during such events, they may do the following:

1. Call this method within the CreateFile or OpenFile event.
2. Store the information somewhere, and store a reference to it in the event's HandleContext parameter.
3. In a later event, access the information via the reference stored in HandleContext.

Please refer to the Contexts topic for more information on how to use events' context parameters.

Note: Renaming and deletion of files is performed after the file is opened. Thus, access checks should be performed during file opening as described above.

Note: This method cannot be used from CleanupContext event handlers.

GetOriginatorToken Method (Cbencrypt Class)

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

Syntax

public long getOriginatorToken();

Remarks

This method can be called within synchronous, i.e., Before* and After* 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: This method will not work properly when called from Notify* event handlers because security tokens are not kept for possible later use. If you need to obtain security information about a request, use corresponding After* events.

The security token returned by this method can be passed to the Windows API's GetTokenInformation function to obtain more information about the process.

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

Network Access Notes

Applications monitoring a drive shared on the network 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 network redirector (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. However, it must not be called within events that work with opened files since such events can be initiated by system components (e.g., the cache manager, memory manager, etc.). If applications need the information this method returns during such events, they may do the following:

1. Call this method within the CreateFile or OpenFile event.
2. Store the information somewhere, and store a reference to it in the event's HandleContext parameter.
3. In a later event, access the information via the reference stored in HandleContext.

Please refer to the Contexts topic for more information on how to use events' context parameters.

Note: Renaming and deletion of files is performed after the file is opened. Thus, access checks should be performed during file opening as described above.

Note: This method cannot be used from CleanupContext event handlers.

GetVolumeGUID Method (Cbencrypt Class)

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

Syntax

public String getVolumeGUID();

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 Class)

This method initializes the class.

Syntax

public void initialize(String productGUID);

Remarks

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

ProductGUID is used to distinguish among driver installations performed by different applications. 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

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 class can be used.

Install Method (Cbencrypt Class)

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

Syntax

public boolean install(String cabFileName, String productGUID, String pathToInstall, String altitude, int flags);

Remarks

This method is used to install or upgrade the class'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 class's driver, use only the Install method. Previously installed versions of the driver 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 class'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.

ProductGUID is used to distinguish among driver installations performed by different applications. 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

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.

Flags specifies various installation options. It should contain zero or more of the following flags, ORed together:

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.

This method is available in both the class 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 (0x0522) error.

Note: This method cannot be called within events.

NtStatusToWin32Error Method (Cbencrypt Class)

This method converts a native status code to a Win32 error code.

Syntax

public int ntStatusToWin32Error(int status);

Remarks

This method converts the native status code specified by Status to a Win32 error code. If the specified native status code does not map directly to a Win32 error code, this method returns ERROR_MR_MID_NOT_FOUND (317).

RemoveEncryptRule Method (Cbencrypt Class)

This method removes an encryption rule from the list.

Syntax

public boolean removeEncryptRule(String fileMask);

Remarks

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

The method will return true if the rule that includes the file mask was found in the list and was removed, and false otherwise.

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.

ResetTimeout Method (Cbencrypt Class)

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

Syntax

public boolean resetTimeout(int timeout);

Remarks

When event timeouts are being enforced, this method can be called within an event handler to inform the class 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 cancel the underlying OS request. 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 property is set to false), 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.

SetFileHeader Method (Cbencrypt Class)

This method sets the header data in a file.

Syntax

public void setFileHeader(String fileName, byte[] data);

Remarks

This method sets or updates the header data of the file specified by FileName.

Note: The header data must be set in full; the data, passed in the Data buffer, completely replace the existing header contents.

ShutdownSystem Method (Cbencrypt Class)

Shuts down or reboots the operating system.

Syntax

public boolean shutdownSystem(String shutdownPrompt, int timeout, boolean forceCloseApps, boolean reboot);

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 class 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 Class)

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

Syntax

public void start(int timeout);

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.

The Timeout parameter 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.

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

• If the class'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.

Stop Method (Cbencrypt Class)

This method stops monitoring of filesystem operations.

Syntax

public void stop();

Remarks

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

The method returns after monitoring is stopped.

Uninstall Method (Cbencrypt Class)

This method uninstalls the class's system driver.

Syntax

public boolean uninstall(String cabFileName, String productGUID, String installedPath, int flags);

Remarks

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

Important: To upgrade the class's driver, use only the Install method. Previously installed versions of the driver 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.

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 class's system driver should be uninstalled and which should be set by ORing together one or more of the following values:

This method is available in both the class 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 (0x0522) error.

Note: This method cannot be called within events.

AfterFilterAttachToVolume Event (Cbencrypt Class)

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

Syntax

public class DefaultCbencryptEventListener implements CbencryptEventListener {
  ...
  public void afterFilterAttachToVolume(CbencryptAfterFilterAttachToVolumeEvent e) {}
  ...
}

public class CbencryptAfterFilterAttachToVolumeEvent {
  public String volumeName;
  public int resultCode;
}

Remarks

This event fires after the filter attaches to the newly mounted filesystem volume specified by 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.

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 StartFilter 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.

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 format of the VolumeName parameter's value depends on whether the ResolveNtDeviceToDriveLetter configuration setting is enabled; please refer to its documentation for more information. 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 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 Reporting and Handling topic for more information.

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

AfterFilterDetachFromVolume Event (Cbencrypt Class)

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

Syntax

public class DefaultCbencryptEventListener implements CbencryptEventListener {
  ...
  public void afterFilterDetachFromVolume(CbencryptAfterFilterDetachFromVolumeEvent e) {}
  ...
}

public class CbencryptAfterFilterDetachFromVolumeEvent {
  public String volumeName;
  public int resultCode;
}

Remarks

This event fires after the filter detaches from the filesystem volume specified by 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.

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 format of the VolumeName parameter's value depends on whether the ResolveNtDeviceToDriveLetter configuration setting is enabled; please refer to its documentation for more information. 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 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 Reporting and Handling topic for more information.

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

BeforeFilterAttachToVolume Event (Cbencrypt Class)

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

Syntax

public class DefaultCbencryptEventListener implements CbencryptEventListener {
  ...
  public void beforeFilterAttachToVolume(CbencryptBeforeFilterAttachToVolumeEvent e) {}
  ...
}

public class CbencryptBeforeFilterAttachToVolumeEvent {
  public String volumeName;
  public boolean skipVolume;
  public int resultCode;
}

Remarks

This event fires before the filter attaches to the newly mounted filesystem volume specified by 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.

The VolumeName parameter's value is always an NT native format in this event (unlike the other volume-related events, listed below, where its format depends on the ResolveNtDeviceToDriveLetter configuration setting). It is therefore recommended that applications add volume-specific rules, if desired, during the AfterFilterAttachToVolume event rather than this one. 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 class'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 class's system driver. It also will prevent any of the following events from firing for the volume:

• AfterFilterAttachToVolume
• NotifyFilterAttachToVolume
• AfterFilterDetachFromVolume
• NotifyFilterDetachFromVolume

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 Reporting and Handling topic for more information.

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

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).

CloseFile Event (Cbencrypt Class)

This event fires when a file or directory is closed.

Syntax

public class DefaultCbencryptEventListener implements CbencryptEventListener {
  ...
  public void closeFile(CbencryptCloseFileEvent e) {}
  ...
}

public class CbencryptCloseFileEvent {
  public String fileName;
  public int resultCode;
}

Remarks

This event fires when the file or directory specified by FileName is closed.

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 Reporting and Handling topic for more information.

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

Error Event (Cbencrypt Class)

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

Syntax

public class DefaultCbencryptEventListener implements CbencryptEventListener {
  ...
  public void error(CbencryptErrorEvent e) {}
  ...
}

public class CbencryptErrorEvent {
  public int errorCode;
  public String description;
}

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.

Note: Not everything is possible or allowed in the event handlers. For details, see the Recursive Calls topic.

NotifyFilterAttachToVolume Event (Cbencrypt Class)

This event fires when the filter has been attached to a newly mounted filesystem volume.

Syntax

public class DefaultCbencryptEventListener implements CbencryptEventListener {
  ...
  public void notifyFilterAttachToVolume(CbencryptNotifyFilterAttachToVolumeEvent e) {}
  ...
}

public class CbencryptNotifyFilterAttachToVolumeEvent {
  public String volumeName;
  public int resultCode;
}

Remarks

This event fires when the filter has been attached to the newly mounted filesystem volume specified by 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_NOTIFY flag.

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

Applications that use volume-specific rules should typically add such rules during the AfterFilterAttachToVolume event, which is fired synchronously, rather than this one.

The format of the VolumeName parameter's value depends on whether the ResolveNtDeviceToDriveLetter configuration setting is enabled; please refer to its documentation for more information. 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 ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason, set it to a non-zero value to report an appropriate error.

Note: This event fires after the operation has already completed, so reporting an error will not actually affect the operation itself. Please refer to the Error Reporting and Handling topic for more information.

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

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).

NotifyFilterDetachFromVolume Event (Cbencrypt Class)

This event fires when the filter has been detached from a filesystem volume.

Syntax

public class DefaultCbencryptEventListener implements CbencryptEventListener {
  ...
  public void notifyFilterDetachFromVolume(CbencryptNotifyFilterDetachFromVolumeEvent e) {}
  ...
}

public class CbencryptNotifyFilterDetachFromVolumeEvent {
  public String volumeName;
  public int resultCode;
}

Remarks

This event fires when the filter has been detached from the filesystem volume specified by VolumeName, typically as a result 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_NOTIFY flag.

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

Applications that use volume-specific rules typically should remove such rules during the AfterFilterDetachFromVolume event, which is fired synchronously, rather than this one.

The format of the VolumeName parameter's value depends on whether the ResolveNtDeviceToDriveLetter configuration setting is enabled; please refer to its documentation for more information. 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 ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason, set it to a non-zero value to report an appropriate error.

Note: This event fires after the operation has already completed, so reporting an error will not actually affect the operation itself. Please refer to the Error Reporting and Handling topic for more information.

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

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).

OpenFile Event (Cbencrypt Class)

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

Syntax

public class DefaultCbencryptEventListener implements CbencryptEventListener {
  ...
  public void openFile(CbencryptOpenFileEvent e) {}
  ...
}

public class CbencryptOpenFileEvent {
  public String fileName;
  public boolean fileExists;
  public int existingAttributes;
  public int desiredAccess;
  public int attributes;
  public int shareMode;
  public int options;
  public int createDisposition;
  public ByteBuffer headerBuffer;
  public long maxHeaderSize;
  public long bytesInHeader;
  public int encryption;
  public String password;
  public int resultCode;
}

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 Internet Relay Programming).

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

Attributes may contain one or more of the following attributes:

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

CreateDisposition may contain one of the following values:

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.

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)).

HeaderBuffer is the container of the application-defined data which are stored in the header of the encrypted file. The size of the header is specified in the MaxHeaderSize parameter. This size is equal or a bit larger than the required header size, specified in the encryption rule.

If the file exists, its header data are placed into HeaderBuffer and can be modified by the event handler. If the file does not exist, HeaderBuffer is empty (filled with zeros) and the event handler may place up to MaxHeaderSize bytes to the buffer. If the file is created or opened successfully after the event, these data will be stored in the header of the encrypted file, replacing the existing content (if any).

When the event handler modifies HeaderBuffer, it must set the BytesInHeader property to the number of bytes, which are valid in HeaderBuffer.

Note: The data of HeaderBuffer are stored in the file in plain form without encryption.

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).

Note: The data of HeaderBuffer are stored in the file in plain form without encryption.

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

If the file does not exist or is recreated (superseded), the The expected behavior of the application's event handlers in regard to the Encryption and Password parameters depends on the PassRulePasswords configuration setting. If the setting is enabled, the Encryption and Password parameters contain the values taken from the rule, and the application may leave them unchanged; or, it can dynamically adjust the values of these parameters based on the information that is available to the application (user-defined password and alike). If the setting is disabled, the application must set both Encryption and Password to valid values that the class will use to encrypt the file.

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.

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 Reporting and Handling topic for more information.

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

PasswordNeeded Event (Cbencrypt Class)

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

Syntax

public class DefaultCbencryptEventListener implements CbencryptEventListener {
  ...
  public void passwordNeeded(CbencryptPasswordNeededEvent e) {}
  ...
}

public class CbencryptPasswordNeededEvent {
  public String fileName;
  public byte[] headerBuffer;
  public int encryption;
  public String password;
  public int resultCode;
}

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.

The HeaderBuffer parameter contains application-defined data which are stored in the header of the encrypted file. These data may include information, needed for identification or authorization of access. Note: The data of HeaderBuffer are stored in the file in plain form without encryption.

Encryption specifies the encryption mode to use and can have one of the following values:

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.

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 Reporting and Handling topic for more information.

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

RenameOrMoveFile Event (Cbencrypt Class)

This event fires when a file is renamed or moved.

Syntax

public class DefaultCbencryptEventListener implements CbencryptEventListener {
  ...
  public void renameOrMoveFile(CbencryptRenameOrMoveFileEvent e) {}
  ...
}

public class CbencryptRenameOrMoveFileEvent {
  public String fileName;
  public String newFileName;
  public ByteBuffer headerBuffer;
  public long maxHeaderSize;
  public long bytesInHeader;
  public int encryption;
  public String password;
  public int resultCode;
}

Remarks

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

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 Internet Relay Programming).

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

Attributes may contain one or more of the following attributes:

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

CreateDisposition may contain one of the following values:

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.

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)).

HeaderBuffer is the container of the application-defined data which are stored in the header of the encrypted file. The size of the header is specified in the MaxHeaderSize parameter. This size is equal or a bit larger than the required header size, specified in the encryption rule.

If the file exists, its header data are placed into HeaderBuffer and can be modified by the event handler. If the file does not exist, HeaderBuffer is empty (filled with zeros) and the event handler may place up to MaxHeaderSize bytes to the buffer. If the file is created or opened successfully after the event, these data will be stored in the header of the encrypted file, replacing the existing content (if any).

When the event handler modifies HeaderBuffer, it must set the BytesInHeader property to the number of bytes, which are valid in HeaderBuffer.

Note: The data of HeaderBuffer are stored in the file in plain form without encryption.

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 in file encryption. Encryption specifies the encryption mode to use and can have one of the following values:

An application may leave the Encryption and Password parameters unchanged to indicate that the existing encryption mode and password of the file should not be altered; or, it can update the values of these parameters based on the information that is available to the application (user-defined password and alike).

For more information, see Encryption.

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 Reporting and Handling topic for more information.

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

FileEncryptRule Type

This type represents an encryption rule.

Remarks

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

Fields

Config Settings (Cbencrypt Class)

The class 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 class, access to these internal properties is provided through the Config method.

CBEncrypt Config Settings

Base Config Settings

Trappable Errors (Cbencrypt Class)