Module themis::secure_cell

Secure Cell for data storage.

Secure Сell is a high-level cryptographic service aimed at protecting arbitrary data stored in various types of storage (e.g., databases, filesystem files, document archives, cloud storage, etc.) It provides both strong symmetric encryption and data authentication mechanism.

The general approach is that given:

• input: some source data to protect
• secret: symmetric key or a password
• context: and an optional “context information”

Secure Cell will produce:

• cell: the encrypted data
• authentication token: some authentication data

The purpose of the optional context information (e.g., a database row number or file name) is to establish a secure association between this context and the protected data. In short, even when the secret is known, if the context is incorrect then decryption will fail.

The purpose of the authentication data is to validate that given a correct key or passphrase (and context), the decrypted data is indeed the same as the original source data.

The authentication data must be stored somewhere. The most convenient way is to simply append it to the encrypted data, but this is not always possible due to the storage architecture of your application. Secure Cell offers variants that address this issue in different ways.

By default, Secure Cell uses AES-256 for encryption. Authentication data takes additional 44 bytes when symmetric keys are used and 70 bytes in case the data is secured with a passphrase.

Secure Cell supports 2 kinds of secrets:

• Symmetric keys are convenient to store and efficient to use for machines. However, they are relatively long and hard for humans to remember.

  New symmetric keys can be generated with SymmetricKey.

• Passphrases, in contrast, can be shorter and easier to remember.

  However, passphrases are typically much less random than keys. Secure Cell uses a key derivation function (KDF) to compensate for that and achieves security comparable to keys with shorter passphrases. This comes at a significant performance cost though.

Use SecureCell::with_key or with_passphrase to construct a Secure Cell with a particular kind of secret.

Secure Cell supports 3 operation modes:

• Seal mode is the most secure and easy to use. Your best choice most of the time. This is also the only mode that supports passphrases at the moment.

• Token Protect mode is just as secure, but a bit harder to use. This is your choice if you need to keep authentication data separate.

• Context Imprint mode is a length-preserving version of Secure Cell with no additional data stored. Should be used carefully.

The operation mode is selected via an appropriate method of a basic SecureCell object.

Here you can learn more about the underlying considerations, limitations, and features of each mode.

Examples

Here is how you use Secure Cell to seal away your data:

use themis::keys::SymmetricKey;
use themis::secure_cell::SecureCell;

let key = SymmetricKey::new();
let cell = SecureCell::with_key(&key)?.seal();

let encrypted = cell.encrypt(b"Beware the Jabberwock, my son!")?;
let decrypted = cell.decrypt(&encrypted)?;

assert_eq!(decrypted, b"Beware the Jabberwock, my son!");

You can find more examples for each operation mode in their respective documentation.

Structs

SecureCell	Basic Secure Cell.
SecureCellContextImprint	Secure Cell in Context Imprint operation mode.
SecureCellSeal	Secure Cell in Seal operation mode.
SecureCellSealWithPassphrase	Secure Cell in Seal operation mode.
SecureCellTokenProtect	Secure Cell in Token Protect operation mode.
SecureCellWithPassphrase	Basic Secure Cell with a passphrase.