Struct themis::secure_cell::SecureCellSeal[−]

pub struct SecureCellSeal(_);

Expand description

Secure Cell in Seal operation mode.

This is the most secure and easy way to protect stored data. The data is protected by a symmetric key.

Secure Cell in Seal mode will encrypt the data and append an “authentication tag” with auxiliary security information, forming a single sealed container. This means that the encrypted data will be longer than the original input.

Additionally, it is possible to bind the encrypted data to some “associated context” (for example, database row number). In this case decryption of the data with incorrect context will fail (even if the correct key is known and the data has not been tampered). This establishes a cryptographically secure association between the protected data and the context in which it is used. With database row numbers this prevents the attacker from swapping encrypted password hashes in the database so the system will not accept credentials of a different user.

Security of symmetric key operation mode depends on the quality of the key, with short and incorrectly generated keys being easier to crack. You can use SymmetricKey to generate good random keys of sufficient length. If you need to use a short and easy to remember passphrase, use passphrase API instead: SecureCell::with_passphrase and SecureCellSealWithPassphrase.

You can read more about Seal mode in documentation.

Examples

Note that the resulting sealed cell takes more space than the input data:

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

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

let plaintext = b"O frabjous day! Callooh! Callay!";
let encrypted = cell.encrypt(&plaintext)?;
let decrypted = cell.decrypt(&encrypted)?;

assert!(encrypted.len() > plaintext.len());
assert_eq!(decrypted, plaintext);

Implementations

impl SecureCellSeal

pub fn encrypt(&self, message: impl AsRef<[u8 ]>) -> Result<Vec<u8>>

Encrypts the provided message.

Data is encrypted and authentication token is appended to form a single sealed buffer. Use decrypt to decrypt the result later.

This call is equivalent to encrypt_with_context with an empty associated context.

Examples

You can use anything convertible into a byte slice as a message: a byte slice or an array, a Vec<u8>, or a String, etc.

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

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

assert!(cell.encrypt(b"byte string").is_ok());
assert!(cell.encrypt(&[1, 2, 3, 4, 5]).is_ok());
assert!(cell.encrypt(vec![6, 7, 8, 9]).is_ok());
assert!(cell.encrypt(format!("owned string")).is_ok());

However, the message must not be empty:

assert!(cell.encrypt(&[]).is_err());

pub fn encrypt_with_context(
 &self,
 message: impl AsRef<[u8 ]>,
 context: impl AsRef<[u8 ]>
) -> Result<Vec<u8>>

Encrypts the provided message with associated context.

Data is encrypted and authentication token is appended to form a single sealed buffer. Use decrypt_with_context to decrypt the result later.

The context is cryptographically mixed with the data but not included into the resulting encrypted message. You will have to provide the same context again during decryption. Usually this is some plaintext data associated with encrypted data, such as database row number, protocol message ID, etc.

Examples

You can use anything convertible into a byte slice as a message and context: a byte slice or an array, a Vec<u8>, or a String, etc.

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

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

assert!(cell.encrypt_with_context(b"byte string", format!("owned string")).is_ok());
assert!(cell.encrypt_with_context(&[1, 2, 3, 4, 5], vec![6, 7, 8, 9, 10]).is_ok());

The context may be empty (in which case this call is equivalent to encrypt). However, the message must not be empty.

assert!(cell.encrypt_with_context(b"message", &[]).is_ok());
assert!(cell.encrypt_with_context(&[], b"context").is_err());

pub fn decrypt(&self, message: impl AsRef<[u8 ]>) -> Result<Vec<u8>>

Decrypts the provided message.

Secure Cell decrypts the message and verifies its integrity using authentication data embedded into the message.

Use this method to decrypt data encrypted with encrypt. If you use associated context, call decrypt_with_context instead.

Examples

Obviously, the key must be the same for decryption to succeed:

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

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

let message = b"All mimsy were the borogoves";
let encrypted = cell.encrypt(&message)?;
let decrypted = cell.decrypt(&encrypted)?;
assert_eq!(decrypted, message);

let other_cell = SecureCell::with_key(SymmetricKey::new())?.seal();
assert!(other_cell.decrypt(&encrypted).is_err());

You also cannot use this method when data was encrypted with associated context. Use decrypt_with_context in that case.

let context = b"And the mome raths outgrabe";
let encrypted = cell.encrypt_with_context(&message, &context)?;

assert!(cell.decrypt(&encrypted).is_err());

let decrypted = cell.decrypt_with_context(&encrypted, &context)?;

assert_eq!(decrypted, b"All mimsy were the borogoves");

Secure Cell in Seal mode verifies data integrity and can see if the data was corrupted, returning an error on decryption attempts:

// Let's flip some bits somewhere...
let mut corrupted = encrypted.clone();
corrupted[20] = !corrupted[20];

assert!(cell.decrypt(&corrupted).is_err());

pub fn decrypt_with_context(
 &self,
 message: impl AsRef<[u8 ]>,
 context: impl AsRef<[u8 ]>
) -> Result<Vec<u8>>

Decrypts the provided message with associated context.

Secure Cell validates association with the context data, decrypts the message, and verifies its integrity using authentication data embedded into the message.

You need to provide the same context data as provided to encrypt_with_context. You can also decrypt data encrypted with encrypt by using an empty context.

Examples

Obviously, the key must be the same for decryption to succeed:

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

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

let message = b"All mimsy were the borogoves";
let context = b"And the mome raths outgrabe";
let encrypted = cell.encrypt_with_context(&message, &context)?;
let decrypted = cell.decrypt_with_context(&encrypted, &context)?;
assert_eq!(decrypted, message);

let other_cell = SecureCell::with_key(SymmetricKey::new())?.seal();
assert!(other_cell.decrypt_with_context(&encrypted, &context).is_err());

The context must match as well for decryption to succeed:

assert!(cell.decrypt_with_context(&encrypted, b"incorrect context").is_err());
let decrypted = cell.decrypt_with_context(&encrypted, &context)?;
assert_eq!(decrypted, b"All mimsy were the borogoves");

Secure Cell in Seal mode verifies data integrity and can see if the data was corrupted, returning an error on decryption attempts:

// Let's flip some bits somewhere...
let mut corrupted = encrypted.clone();
corrupted[20] = !corrupted[20];

assert!(cell.decrypt_with_context(&corrupted, &context).is_err());