feat: CRP-2847 Add AES-GCM encryption helpers to the Rust library (#220)

This matches the behavior of the functions in the TS frontend library

Author: randombit

Cargo.lock

@@ -24,6 +24,7 @@ readme = "README.md"
 crate-type = ["lib"]
 
 [dependencies]
+aes-gcm = "0.10"
 anyhow = { workspace = true }
 candid = { workspace = true }
 ic_bls12_381 = { version = "0.10.1", default-features = false, features = [

backend/rs/ic_vetkeys/Cargo.toml

@@ -529,6 +529,16 @@ impl VetKey {
         derive_symmetric_key(self.serialize(), domain_sep, output_len)
     }
 
+    /**
+     * Return a DerivedKeyMaterial
+     *
+     * This class allows further key derivation and encryption but the underlying
+     * secret key cannot be extracted.
+     */
+    pub fn as_derived_key_material(&self) -> DerivedKeyMaterial {
+        DerivedKeyMaterial::new(self)
+    }
+
     /**
      * Deserialize a VetKey from the byte encoding
      *
@@ -547,6 +557,109 @@ impl VetKey {
     }
 }
 
+/// Key material derived from a VetKey
+///
+/// This struct allows deriving further keys from the VetKey without
+/// allowing direct access to the VetKey secret key, preventing it
+/// from being reused inappropriately.
+///
+/// As a convenience this struct also offers AES-GCM encryption/decryption
+#[derive(Clone, Zeroize, ZeroizeOnDrop)]
+pub struct DerivedKeyMaterial {
+    key: Vec<u8>,
+}
+
+#[derive(Copy, Clone, Eq, PartialEq, Debug)]
+/// An error while encrypting
+pub enum EncryptionError {
+    /// The provided message was too long to be encrypted
+    PlaintextTooLong,
+}
+
+#[derive(Copy, Clone, Eq, PartialEq, Debug)]
+/// An error while decrypting
+pub enum DecryptionError {
+    /// The ciphertext was too short to possibly be valid
+    MessageTooShort,
+    /// The GCM tag did not validate
+    InvalidCiphertext,
+}
+
+impl DerivedKeyMaterial {
+    const GCM_KEY_SIZE: usize = 32;
+    const GCM_TAG_SIZE: usize = 16;
+    const GCM_NONCE_SIZE: usize = 12;
+
+    /// Create a new DerivedKeyMaterial
+    fn new(vetkey: &VetKey) -> Self {
+        Self {
+            key: vetkey.serialize().to_vec(),
+        }
+    }
+
+    fn derive_aes_gcm_key(&self, domain_sep: &str) -> Vec<u8> {
+        derive_symmetric_key(&self.key, domain_sep, Self::GCM_KEY_SIZE)
+    }
+
+    /// Encrypt a message
+    ///
+    /// The decryption used here is interoperable with the TypeScript
+    /// library ic_vetkeys function `DerivedKeyMaterial.decryptMessage`
+    pub fn encrypt_message<R: rand::RngCore + rand::CryptoRng>(
+        &self,
+        message: &[u8],
+        domain_sep: &str,
+        rng: &mut R,
+    ) -> Result<Vec<u8>, EncryptionError> {
+        use aes_gcm::{aead::Aead, aead::AeadCore, Aes256Gcm, Key, KeyInit};
+        let key = self.derive_aes_gcm_key(domain_sep);
+        let key = Key::<Aes256Gcm>::from_slice(&key);
+        // aes_gcm::Aes256Gcm only supports/uses 12 byte nonces
+        let nonce = Aes256Gcm::generate_nonce(rng);
+        assert_eq!(nonce.len(), Self::GCM_NONCE_SIZE);
+        let gcm = Aes256Gcm::new(key);
+
+        // The function returns an opaque `Error` with no details, but upon
+        // examination, the only way it can fail is if the plaintext is larger
+        // than GCM's maximum input length of 2^36 bytes.
+        let ctext = gcm
+            .encrypt(&nonce, message)
+            .map_err(|_| EncryptionError::PlaintextTooLong)?;
+
+        let mut res = vec![];
+        res.extend_from_slice(nonce.as_slice());
+        res.extend_from_slice(ctext.as_slice());
+        Ok(res)
+    }
+
+    /// Decrypt a message
+    ///
+    /// The decryption used here is interoperable with the TypeScript
+    /// library ic_vetkeys function `DerivedKeyMaterial.encryptMessage`
+    pub fn decrypt_message(
+        &self,
+        ctext: &[u8],
+        domain_sep: &str,
+    ) -> Result<Vec<u8>, DecryptionError> {
+        use aes_gcm::{aead::Aead, Aes256Gcm, Key, KeyInit};
+        let key = self.derive_aes_gcm_key(domain_sep);
+        let key = Key::<Aes256Gcm>::from_slice(&key);
+
+        // Minimum possible length 12 bytes nonce plus 16 bytes GCM tag
+        if ctext.len() < Self::GCM_NONCE_SIZE + Self::GCM_TAG_SIZE {
+            return Err(DecryptionError::MessageTooShort);
+        }
+        let nonce = aes_gcm::Nonce::from_slice(&ctext[0..Self::GCM_NONCE_SIZE]);
+        let gcm = Aes256Gcm::new(key);
+
+        let ptext = gcm
+            .decrypt(nonce, &ctext[Self::GCM_NONCE_SIZE..])
+            .map_err(|_| DecryptionError::InvalidCiphertext)?;
+
+        Ok(ptext.as_slice().to_vec())
+    }
+}
+
 #[derive(Copy, Clone, Debug)]
 /// Error indicating that deserializing an encrypted key failed
 pub enum EncryptedVetKeyDeserializationError {

backend/rs/ic_vetkeys/src/utils/mod.rs

@@ -285,3 +285,72 @@ fn vrf_from_prod_can_be_verified() {
         "a484fc1e8a2b0dca99beb6f4409370f5c6932a931e47a7625c3bfe9e1f9af37f"
     );
 }
+
+#[test]
+fn aes_gcm_encryption() {
+    let dkm = VetKey::deserialize(&hex!("ad19676dd92f116db11f326ff0822f295d87cc00cf65d9f132b5a618bb7381e5b0c3cb814f15e4a0f015359dcfa8a1da")).unwrap().as_derived_key_material();
+
+    let test_message = b"stay calm, this is only a test";
+    let domain_sep = "ic-test-domain-sep";
+
+    // Test string encryption path, then decryption
+
+    let mut rng = reproducible_rng();
+
+    let ctext = dkm
+        .encrypt_message(test_message, domain_sep, &mut rng)
+        .unwrap();
+    assert_eq!(
+        dkm.decrypt_message(&ctext, domain_sep).unwrap(),
+        test_message,
+    );
+
+    // Test decryption of known ciphertext encrypted with the derived key
+    let fixed_ctext = hex!("476f440e30bb95fff1420ce41ba6a07e03c3fcc0a751cfb23e64a8dcb0fc2b1eb74e2d4768f5c4dccbf2526609156664046ad27a6e78bd93bb8b");
+
+    assert_eq!(
+        dkm.decrypt_message(&fixed_ctext, domain_sep).unwrap(),
+        test_message,
+    );
+
+    // Test decryption of various mutated or truncated ciphertexts: all should fail
+
+    // Test sequentially flipping each bit
+
+    for i in 0..ctext.len() * 8 {
+        let mod_ctext = {
+            let mut m = ctext.clone();
+            m[i / 8] ^= 0x80 >> i % 8;
+            m
+        };
+
+        assert!(dkm.decrypt_message(&mod_ctext, domain_sep).is_err());
+    }
+
+    // Test truncating
+
+    for i in 0..ctext.len() - 1 {
+        let mod_ctext = {
+            let mut m = ctext.clone();
+            m.truncate(i);
+            m
+        };
+
+        assert!(dkm.decrypt_message(&mod_ctext, domain_sep).is_err());
+    }
+
+    // Test appending random bytes
+
+    for i in 1..32 {
+        let mod_ctext = {
+            use rand::RngCore;
+            let mut m = ctext.clone();
+            let mut extra = vec![0u8; i];
+            rng.fill_bytes(&mut extra);
+            m.extend_from_slice(&extra);
+            m
+        };
+
+        assert!(dkm.decrypt_message(&mod_ctext, domain_sep).is_err());
+    }
+}