Encryption
The CBVault class includes strong built-in data encryption support, which can be applied to individual files and alternate streams, entire vaults, or both. Each file, alternate stream, and vault can have its own encryption key. (Note: the API members discussed in this topic are available in all listed classes, unless otherwise noted.)
Encrypting Vaults
To specify a default encryption mode and password to use when creating new vaults, applications can set the vault_encryption and vault_password properties. To change the encryption mode and/or password of an existing vault, use the update_vault_encryption method.
When opening an existing vault, vault_encryption is updated to reflect the vault's encryption mode; and if the vault is encrypted, the password specified by vault_password is used to access it.
Encrypting Files and Alternate Streams
To specify a default encryption mode and password for files and alternate streams, applications can set the default_file_encryption and default_file_password properties. Additionally, the following methods allow applications to set a file or alternate stream's encryption mode and/or password explicitly:
- open_file (when creating a new file or alternate stream)
- open_file_ex (when creating a new file or alternate stream)
- set_file_encryption
- copy_to_vault
When a file or alternate stream is encrypted, its encryption password must be provided in order to access it; many methods in the class's API provide a Password parameter for this purpose. If the application doesn't explicitly specify a password when calling such a method, then the default_file_password will be used, if possible.
Using Custom Encryption
The class's built-in encryption implementation uses 256-bit AES encryption in XTS mode with PBKDF2 key derivation based on a HMAC-SHA256 key hash. However, applications also can choose to provide their own custom encryption and key derivation implementations. This flexibility allows applications to support more sophisticated security techniques, such as PKI-based encryption, or Digital Rights Management. To get started, do the following:
- Choose a custom encryption mode to implement (i.e., one of the CBFSSTORAGE_EM_CUSTOM* options from the table below). This choice will determine:
- Whether the custom encryption implementation uses a 256-bit, 512-bit, or 1024-bit block size; and,
- Whether to use built-in key derivation, custom key derivation, or no key derivation.
- Implement the on_data_encrypt and on_data_decrypt events.
- If a CBFSSTORAGE_EM_CUSTOM*_CUSTOM_KEY_DERIVE mode was chosen, implement the on_key_derive event.
- If a CBFSSTORAGE_EM_CUSTOM*_DIRECT_KEY mode was chosen, implement the on_hash_calculate event.
Supported Encryption Modes
The class support the following encryption modes:
CBFSSTORAGE_EM_NONE | 0x0 | Don't use encryption. |
CBFSSTORAGE_EM_DEFAULT | 0x1 | Use default encryption (CBFSSTORAGE_EM_XTS_AES256_PBKDF2_HMAC_SHA256). |
CBFSSTORAGE_EM_XTS_AES256_PBKDF2_HMAC_SHA256 | 0x2 | Use AES256 encryption with PBKDF2 key derivation based on a HMAC_SHA256 key hash. |
CBFSSTORAGE_EM_CUSTOM256_PBKDF2_HMAC_SHA256 | 0x3 | Use event-based custom 256-bit encryption with PBKDF2 key derivation based on a HMAC_SHA256 key hash.
256-bit (32-byte) block size. |
CBFSSTORAGE_EM_CUSTOM512_PBKDF2_HMAC_SHA256 | 0x4 | Use event-based custom 512-bit encryption with PBKDF2 key derivation based on a HMAC_SHA256 key hash.
512-bit (64-byte) block size. |
CBFSSTORAGE_EM_CUSTOM1024_PBKDF2_HMAC_SHA256 | 0x5 | Use event-based custom 1024-bit encryption with PBKDF2 key derivation based on a HMAC_SHA256 key hash.
1024-bit (128-byte) block size. |
CBFSSTORAGE_EM_CUSTOM256_CUSTOM_KEY_DERIVE | 0x23 | Use event-based custom 256-bit encryption with custom key derivation.
256-bit (32-byte) block size. |
CBFSSTORAGE_EM_CUSTOM512_CUSTOM_KEY_DERIVE | 0x24 | Use event-based custom 512-bit encryption with custom key derivation.
512-bit (64-byte) block size. |
CBFSSTORAGE_EM_CUSTOM1024_CUSTOM_KEY_DERIVE | 0x25 | Use event-based custom 1024-bit encryption with custom key derivation.
1024-bit (128-byte) block size. |
CBFSSTORAGE_EM_CUSTOM256_DIRECT_KEY | 0x43 | Use event-based custom 256-bit encryption with no key derivation.
256-bit (32-byte) block size. Useful for cases where the password is an identifier for an external key and should not be used for key derivation. |
CBFSSTORAGE_EM_CUSTOM512_DIRECT_KEY | 0x44 | Use event-based custom 512-bit encryption with no key derivation.
512-bit (64-byte) block size. Useful for cases where the password is an identifier for an external key and should not be used for key derivation. |
CBFSSTORAGE_EM_CUSTOM1024_DIRECT_KEY | 0x45 | Use event-based custom 1024-bit encryption with no key derivation.
1024-bit (128-byte) block size. Useful for cases where the password is an identifier for an external key and should not be used for key derivation. |
CBFSSTORAGE_EM_UNKNOWN | 0xFF | Unidentified or unknown encryption. |