Implement KeyObfuscator for Deterministic Encryption of storage keys.

Add KeyObfuscator to provide a helper object for client-side key obfuscation.
This implementation uses AES-256-SIV for deterministic encryption and
nonce misuse-resistance, enhancing security and preventing common pitfalls
(foot-guns) in client-side encryption.

Author: G8XSU

Cargo.toml

@@ -18,6 +18,10 @@ tokio = { version = "1", default-features = false, features = ["time"] }
 rand = "0.8.5"
 async-trait = "0.1.77"
 
+base64 = { version = "0.21.0", default-features = false }
+aes-siv = "0.7.0"
+bitcoin_hashes = "0.14.0"
+
 [target.'cfg(genproto)'.build-dependencies]
 prost-build = { version = "0.11.3" }
 reqwest =  { version = "0.11.13", default-features = false, features = ["rustls-tls", "blocking"] }

src/util/key_obfuscator.rs

@@ -0,0 +1,143 @@
+use std::io;
+use std::io::{Error, ErrorKind};
+
+use aes_siv::aead::generic_array::GenericArray;
+use aes_siv::aead::{Aead, Payload};
+use aes_siv::{Aes256SivAead, KeyInit};
+use base64::prelude::BASE64_STANDARD_NO_PAD;
+use base64::Engine;
+use bitcoin_hashes::{sha512, Hash, HashEngine, Hmac, HmacEngine};
+
+/// [`KeyObfuscator`] is a utility to obfuscate and deobfuscate storage
+/// keys to be used for VSS operations.
+///
+/// It provides client-side deterministic encryption of given keys using AES-256-SIV.
+pub struct KeyObfuscator {
+	obfuscation_key: [u8; 64],
+	hashing_key: [u8; 64],
+}
+
+impl KeyObfuscator {
+	/// Constructs a new instance.
+	pub fn new(obfuscation_master_key: [u8; 64]) -> KeyObfuscator {
+		let (obfuscation_key, hashing_key) = Self::derive_obfuscation_and_hashing_keys(&obfuscation_master_key);
+		Self { obfuscation_key, hashing_key }
+	}
+}
+
+impl KeyObfuscator {
+	/// Obfuscates the given key.
+	pub fn obfuscate(&self, key: &str) -> io::Result<String> {
+		let cipher = Aes256SivAead::new(GenericArray::from_slice(&self.obfuscation_key));
+		let mut engine = HmacEngine::<sha512::Hash>::new(&self.hashing_key);
+		engine.input(key.as_bytes());
+		let hmac = Hmac::from_engine(engine).to_byte_array();
+
+		let nonce = &hmac[..16];
+		let mut ciphertext = self.encrypt(key.as_bytes(), nonce, &cipher).map_err(|e| {
+			let msg = format!("Failed to encrypt key: {}, Error: {}", key, e);
+			Error::new(ErrorKind::InvalidData, msg)
+		})?;
+
+		let wrapped_nonce = self.encrypt(nonce, &[0; 16], &cipher).map_err(|e| {
+			let msg = format!("Failed to wrap nonce. key: {}, Error: {}", key, e);
+			Error::new(ErrorKind::InvalidData, msg)
+		})?;
+		debug_assert_eq!(wrapped_nonce.len(), 32);
+		ciphertext.extend_from_slice(&wrapped_nonce);
+		Ok(BASE64_STANDARD_NO_PAD.encode(ciphertext))
+	}
+
+	/// Deobfuscates the given key.
+	pub fn deobfuscate(&self, key: &str) -> io::Result<String> {
+		let cipher = Aes256SivAead::new(GenericArray::from_slice(&self.obfuscation_key));
+
+		let ciphertext_and_wrapped_nonce = BASE64_STANDARD_NO_PAD.decode(key).map_err(|e| {
+			let msg = format!("Failed to decode base64 while deobfuscating key: {}, Error: {}", key, e);
+			Error::new(ErrorKind::InvalidData, msg)
+		})?;
+		let (ciphertext, wrapped_nonce) =
+			ciphertext_and_wrapped_nonce.split_at(ciphertext_and_wrapped_nonce.len() - 32);
+
+		let nonce = self.decrypt(wrapped_nonce, &[0; 16], &cipher).map_err(|e| {
+			let msg = format!("Failed to unwrap nonce. key: {}, Error: {}", key, e);
+			Error::new(ErrorKind::InvalidData, msg)
+		})?;
+		let plaintext = self.decrypt(ciphertext, nonce.as_slice(), &cipher).map_err(|e| {
+			let msg = format!("Failed to decrypt key: {}, Error: {}", key, e);
+			Error::new(ErrorKind::InvalidData, msg)
+		})?;
+
+		let original_key = String::from_utf8(plaintext).map_err(|e| {
+			let msg = format!("Input was not valid utf8 while deobfuscating key: {}, Error: {}", key, e);
+			Error::new(ErrorKind::InvalidData, msg)
+		})?;
+		Ok(original_key)
+	}
+
+	/// Encrypts the given plaintext using the provided cipher and nonce.
+	fn encrypt(&self, plaintext_bytes: &[u8], nonce: &[u8], cipher: &Aes256SivAead) -> Result<Vec<u8>, aes_siv::Error> {
+		let nonce = GenericArray::from_slice(nonce);
+		let payload = Payload { msg: plaintext_bytes, aad: b"" };
+
+		let ciphertext = cipher.encrypt(nonce, payload)?;
+		Ok(ciphertext)
+	}
+
+	/// Decrypts the given ciphertext using the provided cipher and nonce.
+	fn decrypt(&self, ciphertext: &[u8], nonce: &[u8], cipher: &Aes256SivAead) -> Result<Vec<u8>, aes_siv::Error> {
+		let nonce = GenericArray::from_slice(nonce);
+		let cipher_payload = Payload { msg: ciphertext, aad: b"" };
+
+		let plaintext = cipher.decrypt(nonce, cipher_payload)?;
+		Ok(plaintext)
+	}
+
+	/// Derives the obfuscation and hashing keys from the master key.
+	fn derive_obfuscation_and_hashing_keys(obfuscation_master_key: &[u8; 64]) -> ([u8; 64], [u8; 64]) {
+		let hkdf = |key: &[u8], salt: &[u8]| -> [u8; 64] {
+			let mut engine = HmacEngine::<sha512::Hash>::new(key);
+			engine.input(salt);
+			Hmac::from_engine(engine).to_byte_array()
+		};
+		let prk = hkdf(obfuscation_master_key, "pseudo_random_key".as_bytes());
+		let k1 = hkdf(&prk, "obfuscation_key".as_bytes());
+		let k2 = hkdf(&prk, &[&k1[..], "hashing_key".as_bytes()].concat());
+
+		(k1, k2)
+	}
+}
+
+#[cfg(test)]
+mod tests {
+	use crate::util::key_obfuscator::KeyObfuscator;
+	use crate::util::storable_builder::EntropySource;
+
+	pub struct TestEntropyProvider;
+	impl EntropySource for TestEntropyProvider {
+		/// A terrible implementation which fills a buffer with bytes from a simple counter for testing
+		/// purposes.
+		fn fill_bytes(&self, buffer: &mut [u8]) {
+			for (i, byte) in buffer.iter_mut().enumerate() {
+				*byte = (i % 256) as u8;
+			}
+		}
+	}
+
+	#[test]
+	fn obfuscate_deobfuscate() {
+		let test_entropy_provider = TestEntropyProvider;
+		let mut obfuscation_master_key = [0u8; 64];
+		test_entropy_provider.fill_bytes(&mut obfuscation_master_key);
+		let key_obfuscator = KeyObfuscator::new(obfuscation_master_key);
+		let expected_key = "a_semi_secret_key";
+		let obfuscated_key = key_obfuscator.obfuscate(expected_key).unwrap();
+
+		let actual_key = key_obfuscator.deobfuscate(obfuscated_key.as_str()).unwrap();
+		assert_eq!(actual_key, expected_key);
+		assert_eq!(
+			obfuscated_key,
+			"VR5MoPsIAz2jgV3czpsp8T58EXBs8EmZdXWqXg8J9a+w5+rsMQcP7Ku15Q2pmKW+6U55Irm8gR+OBTYDrpaCOjc"
+		);
+	}
+}

src/util/mod.rs

@@ -5,3 +5,8 @@ pub mod storable_builder;
 
 /// Contains retry utilities.
 pub mod retry;
+
+/// Contains [`KeyObfuscator`] utility.
+///
+/// [`KeyObfuscator`]: key_obfuscator::KeyObfuscator
+pub mod key_obfuscator;