Struct themis::secure_cell::SecureCellTokenProtect

pub struct SecureCellTokenProtect(_);

Secure Cell in token protect operation mode.

In this mode the input data is mixed with the provided context and encrypted, then the authentication token is computed and returned separately, along with the encrypted container. You will have to provide the authentication token later to decrypt the data, but it can be stored or transmitted separately. The encrypted data has the same length as the original input.

use themis::secure_cell::SecureCell;

let cell = SecureCell::with_key(b"password")?.token_protect();

let input = b"test input";
let (output, token) = cell.encrypt(input)?;

assert!(output.len() == input.len());

Methods

impl SecureCellTokenProtect

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

Encrypts the provided message and returns the encrypted container with the authentication token (in that order).

The results can be stored or transmitted separately. You will need to provide both later for successful decryption.

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.

use themis::secure_cell::SecureCell;

let cell = SecureCell::with_key(b"password")?.token_protect();

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

However, the message must not be empty:

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

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

Encrypts the provided message together with the context and returns the encrypted container with the authentication token (in that order).

The results can be stored or transmitted separately. You will need to provide all three parts later for successful decryption.

Examples

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

use themis::secure_cell::SecureCell;

let cell = SecureCell::with_key(b"password")?.token_protect();

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

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]>,
    token: impl AsRef<[u8]>
) -> Result<Vec<u8>>

Extracts the original message from encrypted container and validates its authenticity.

You need to provide both the encrypted container and the authentication token previously obtained from encrypt. Decryption will fail if any of them is corrupted or invalid.

Examples

If you know the master key and the token then getting back your data is easy:

use themis::secure_cell::SecureCell;

let cell = SecureCell::with_key(b"password")?.token_protect();

let (encrypted, token) = cell.encrypt(b"byte string")?;
let decrypted = cell.decrypt(&encrypted, &token)?;
assert_eq!(decrypted, b"byte string");

However, you obviously cannot use tokens produced by Secure Cells with different keys:

let different_cell = SecureCell::with_key(b"qwerty123")?.token_protect();

assert!(different_cell.decrypt(&encrypted, &token).is_err());

Or by the same Secure Cell for different data:

let (encrypted,   _) = cell.encrypt(b"byte string")?;
let (_, other_token) = cell.encrypt(b"other data")?;

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

Secure Cell in token protect mode checks data integrity and can see if the data (or the token) was corrupted, returning an error on decryption attempts:

// Let's flip some bits somewhere.
let mut corrupted_data = encrypted.clone();
let mut corrupted_token = auth_token.clone();
corrupted_data[10] = !corrupted_data[10];
corrupted_token[9] = !corrupted_token[9];

assert!(cell.decrypt(&corrupted_data, &auth_token).is_err());
assert!(cell.decrypt(&encrypted, &corrupted_token).is_err());

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

Extracts the original message from encrypted container and validates its authenticity given the context.

You need to provide the user context used for encryption as well as the encrypted container and the authentication token previously obtained from encrypt_with_context. Decryption will fail if any of them is corrupted or invalid.

Examples

If you know the master key, the context, and the token then getting back your data is easy:

use themis::secure_cell::SecureCell;

let cell = SecureCell::with_key(b"password")?.token_protect();

let (encrypted, token) = cell.encrypt_with_context(b"byte string", b"context")?;
let decrypted = cell.decrypt_with_context(&encrypted, &token, b"context")?;
assert_eq!(decrypted, b"byte string");

However, you obviously cannot use tokens produced by Secure Cells with different keys, tokens for different data, or different contexts:

let different_cell = SecureCell::with_key(b"qwerty123")?.token_protect();

assert!(different_cell.decrypt_with_context(&encrypted, &token, b"context").is_err());

let (_, other_token) = cell.encrypt_with_context(b"other data", b"context")?;

assert!(cell.decrypt_with_context(&encrypted, &other_token, b"context").is_err());
assert!(cell.decrypt_with_context(&encrypted, &token, b"other context").is_err());

Secure Cell in token protect mode checks data integrity and can see if the data (or the token) was corrupted, returning an error on decryption attempts:

// Let's flip some bits somewhere.
let mut corrupted_data = encrypted.clone();
let mut corrupted_token = auth_token.clone();
corrupted_data[4] = !corrupted_data[4];
corrupted_token[9] = !corrupted_token[9];

assert!(cell.decrypt_with_context(&corrupted_data, &auth_token, b"context").is_err());
assert!(cell.decrypt_with_context(&encrypted, &corrupted_token, b"context").is_err());

Trait Implementations

impl Debug for SecureCellTokenProtect

fn fmt(&self, f: &mut Formatter) -> Result

Formats the value using the given formatter.