Struct Encryptor

Source

pub struct Encryptor { /* private fields */ }

Expand description

Encrypts and decrypts column values with keys derived from SECRET_KEY_BASE.

Models use it through Encrypted and Deterministic; use it directly for values outside a model (a job argument, an API token to call another service).

§Examples

use ocre::encryption::Encryptor;

let secret = "a".repeat(64);
let encryptor = Encryptor::new(&secret, &[]).unwrap();
let stored = encryptor.encrypt("123-45-6789");
assert!(stored.starts_with("v1:"));
assert_ne!(stored, encryptor.encrypt("123-45-6789")); // a random nonce each time
assert_eq!(encryptor.decrypt(&stored).unwrap(), "123-45-6789");
// Deterministic: the same text for the same value, so it can be looked up.
assert_eq!(encryptor.encrypt_deterministic("ada@example.com"), encryptor.encrypt_deterministic("ada@example.com"));

Implementations§

Source §

impl Encryptor

Source

pub fn new(secret: &str, previous: &[&str]) -> Result<Self>

Derives the keys from the current secret and the previous ones (newest first).

Each secret must be 64 characters or more, like SECRET_KEY_BASE.

§Errors

Error::Internal naming the fix when a secret is too short.

§Examples

use ocre::encryption::Encryptor;

let (old, new) = ("o".repeat(64), "n".repeat(64));
let stored = Encryptor::new(&old, &[]).unwrap().encrypt("secret");
let rotated = Encryptor::new(&new, &[old.as_str()]).unwrap();
assert_eq!(rotated.decrypt(&stored).unwrap(), "secret");
assert!(Encryptor::new("short", &[]).is_err());

Source

pub fn encrypt(&self, plaintext: &str) -> String

Encrypts plaintext with a random nonce: v1: plus URL-safe base64.

§Examples

let encryptor = ocre::encryption::Encryptor::new(&"k".repeat(64), &[]).unwrap();
assert_eq!(encryptor.decrypt(&encryptor.encrypt("")).unwrap(), "");

Source

pub fn encrypt_deterministic(&self, plaintext: &str) -> String

Encrypts plaintext so that equal values give equal texts (see Deterministic).

§Examples

let encryptor = ocre::encryption::Encryptor::new(&"k".repeat(64), &[]).unwrap();
let a = encryptor.encrypt_deterministic("ada@example.com");
assert_ne!(a, encryptor.encrypt_deterministic("bob@example.com"));
assert_eq!(encryptor.decrypt(&a).unwrap(), "ada@example.com");

Source

pub fn deterministic_candidates(&self, plaintext: &str) -> Vec<String>

The deterministic texts of plaintext under every key, current first: look rows up with Query::is_in during a key rotation.

§Examples

use ocre::encryption::Encryptor;

let (old, new) = ("o".repeat(64), "n".repeat(64));
let stored = Encryptor::new(&old, &[]).unwrap().encrypt_deterministic("ada@example.com");
let rotated = Encryptor::new(&new, &[old.as_str()]).unwrap();
let candidates = rotated.deterministic_candidates("ada@example.com");
assert_eq!(candidates.len(), 2);
assert!(candidates.contains(&stored));

Source

pub fn decrypt(&self, ciphertext: &str) -> Result<String>

Decrypts a value from encrypt or encrypt_deterministic, with the current key or a previous one.

§Errors

Error::Internal when ciphertext is not an encrypted value, was changed, or was encrypted with a key that is neither current nor previous. The message never contains the value.

§Examples

let encryptor = ocre::encryption::Encryptor::new(&"k".repeat(64), &[]).unwrap();
assert!(encryptor.decrypt("plain text").is_err());

Source

pub fn decrypt_or_plaintext(&self, text: &str) -> Result<String>

Like decrypt, but a value without the v1: prefix is returned as is: read a column while a data migration encrypts its existing rows (Rails’ support_unencrypted_data).

§Errors

Error::Internal when an encrypted value does not decrypt.

§Examples

let encryptor = ocre::encryption::Encryptor::new(&"k".repeat(64), &[]).unwrap();
assert_eq!(encryptor.decrypt_or_plaintext("not yet encrypted").unwrap(), "not yet encrypted");