Encryption

CBFS Storage 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.

Encrypting Vaults

To specify a default encryption mode and password to use when creating new vaults, applications can set the VaultEncryption and VaultPassword properties. To change the encryption mode and/or password of an existing vault, use the UpdateVaultEncryption method.

When opening an existing vault, VaultEncryption is updated to reflect the vault's encryption mode; and if the vault is encrypted, the password specified by VaultPassword 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 DefaultFileEncryption and DefaultFilePassword properties. Additionally, the following methods allow applications to set a file or alternate stream's encryption mode and/or password explicitly:

When a file or alternate stream is encrypted, its encryption password must be provided in order to access it; many methods in the CBFS Storage API provide a Password parameter for this purpose. If the application doesn't explicitly specify a password when calling such a method, then the DefaultFilePassword will be used, if possible.

Using Custom Encryption

CBFS Storage's built-in encryption implementation uses 256-bit AES encryption 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:

  1. 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.
  2. Implement the DataEncrypt and DataDecrypt events.
  3. If a CBFSSTORAGE_EM_CUSTOM*_CUSTOM_KEY_DERIVE mode was chosen, implement the KeyDerive event.
  4. If a CBFSSTORAGE_EM_CUSTOM*_DIRECT_KEY mode was chosen, implement the HashCalculate event.

Supported Encryption Modes

CBFS Storage supports the following encryption modes:

CBFSSTORAGE_EM_NONE0x0Don't use encryption.

CBFSSTORAGE_EM_DEFAULT0x1Use default encryption (CBFSSTORAGE_EM_XTS_AES256_PBKDF2_HMAC_SHA256).

CBFSSTORAGE_EM_XTS_AES256_PBKDF2_HMAC_SHA2560x2Use AES256 encryption with PBKDF2 key derivation based on a HMAC_SHA256 key hash.

CBFSSTORAGE_EM_CUSTOM256_PBKDF2_HMAC_SHA2560x3Use 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_SHA2560x4Use 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_SHA2560x5Use 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_DERIVE0x23Use event-based custom 256-bit encryption with custom key derivation.

256-bit (32-byte) block size.

CBFSSTORAGE_EM_CUSTOM512_CUSTOM_KEY_DERIVE0x24Use event-based custom 512-bit encryption with custom key derivation.

512-bit (64-byte) block size.

CBFSSTORAGE_EM_CUSTOM1024_CUSTOM_KEY_DERIVE0x25Use event-based custom 1024-bit encryption with custom key derivation.

1024-bit (128-byte) block size.

CBFSSTORAGE_EM_CUSTOM256_DIRECT_KEY0x43Use 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_KEY0x44Use 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_KEY0x45Use 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_UNKNOWN0xFFUnidentified or unknown encryption.

(Note: All API members discussed in this topic are available in both CBDrive and CBVault, unless otherwise noted.)

 
 
Copyright (c) 2020 Callback Technologies, Inc. - All rights reserved.
CBFS Storage 2020 Qt Edition - Version 20.0 [Build 7649]