Struct themis::secure_cell::SecureCellSeal

pub struct SecureCellSeal(_);

Secure Cell in sealing operation mode.

In this mode the input data is mixed with the provided context and encrypted, then the authentication tag is appended to the data, resulting in a single encrypted and authenticated container. Note that the resulting sealed cell takes more space than the input data:

use themis::secure_cell::SecureCell;

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

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

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

Methods

impl SecureCellSeal

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

Encrypts and puts the provided message into a sealed cell.

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")?.seal();

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>>

Encrypts and puts the provided message together with the context into a sealed cell.

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")?.seal();

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]>) -> Result<Vec<u8>>

Extracts the original message from a sealed cell.

Examples

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

use themis::secure_cell::SecureCell;

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

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

However, if the key is invalid then decryption fails:

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

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

Secure Cell in sealing mode checks 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]>,
    user_context: impl AsRef<[u8]>
) -> Result<Vec<u8>>

Extracts the original message from a sealed cell given the context.

Examples

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

use themis::secure_cell::SecureCell;

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

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

However, if the key or the context are invalid then decryption fails:

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

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

Secure Cell in sealing mode checks 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, b"context").is_err());

Trait Implementations

impl Debug for SecureCellSeal

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

Formats the value using the given formatter.