Cleaner API for encrypt_file_data / decrypt_file_data

- Struct for encrypted and unencrypted data
- Allow decrypting thumbnails as well, not just files
- Symmetric APIs
- Add unit test

Author: dbrgn

CHANGELOG.md

@@ -15,7 +15,9 @@ Possible log types:
 ### Unreleased
 
 - [added] Support downloading of blobs (#65)
+- [added] New `decrypt_file_data` helper function (#67)
 - [changed] Remove `mime` dependency in favor of plain strings (#64)
+- [changed] The API of `encrypt_file_data` has changed (#67)
 
 ### v0.15.1 (2021-12-06)
 

examples/download_blob.rs

@@ -2,10 +2,10 @@ use std::process;
 
 use data_encoding::HEXLOWER_PERMISSIVE;
 use docopt::Docopt;
-use threema_gateway::{ApiBuilder, BlobId};
+use threema_gateway::{decrypt_file_data, ApiBuilder, BlobId, EncryptedFileData, Key};
 
 const USAGE: &str = "
-Usage: download_blob [options] <our-id> <secret> <private-key> <blob-id>
+Usage: download_blob [options] <our-id> <secret> <private-key> <blob-id> [<blob-key>]
 
 Options:
     -h, --help    Show this help
@@ -28,6 +28,15 @@ async fn main() {
             process::exit(1);
         }
     };
+    let blob_key_raw = args.get_str("<blob-key>");
+    let blob_key = if !blob_key_raw.is_empty() {
+        let bytes = HEXLOWER_PERMISSIVE
+            .decode(blob_key_raw.as_bytes())
+            .expect("Invalid blob key");
+        Some(Key::from_slice(&bytes).expect("Invalid blob key bytes"))
+    } else {
+        None
+    };
 
     // Create E2eApi instance
     let api = ApiBuilder::new(our_id, secret)
@@ -37,14 +46,30 @@ async fn main() {
 
     // Download blob
     println!("Downloading blob with ID {}...", blob_id);
-    match api.blob_download(&blob_id).await {
+    let bytes = match api.blob_download(&blob_id).await {
         Err(e) => {
             eprintln!("Could not download blob: {}", e);
             process::exit(1);
         }
         Ok(bytes) => {
             println!("Downloaded {} blob bytes:", bytes.len());
-            println!("{}", HEXLOWER_PERMISSIVE.encode(&bytes));
+            bytes
         }
+    };
+    if let Some(key) = blob_key {
+        let decrypted = decrypt_file_data(
+            &EncryptedFileData {
+                file: bytes,
+                thumbnail: None,
+            },
+            &key,
+        )
+        .expect("Could not decrypt file data");
+        println!(
+            "Decrypted bytes: {}",
+            HEXLOWER_PERMISSIVE.encode(&decrypted.file)
+        );
+    } else {
+        println!("Encrypted bytes: {}", HEXLOWER_PERMISSIVE.encode(&bytes));
     }
 }

examples/send_e2e_file.rs

@@ -1,7 +1,7 @@
 use std::{ffi::OsStr, fs::File, io::Read, path::Path, process};
 
 use docopt::Docopt;
-use threema_gateway::{encrypt_file_data, ApiBuilder, FileMessage, RenderingType};
+use threema_gateway::{encrypt_file_data, ApiBuilder, FileData, FileMessage, RenderingType};
 
 const USAGE: &str = "
 Usage: send_e2e_file [options] <from> <to> <secret> <private-key> <path-to-file>
@@ -73,9 +73,9 @@ async fn main() {
 
     // Read files
     let mut file = etry!(File::open(filepath), "Could not open file");
-    let mut file_data: Vec<u8> = vec![];
-    etry!(file.read_to_end(&mut file_data), "Could not read file");
-    let thumb_data = match thumbpath {
+    let mut file_bytes: Vec<u8> = vec![];
+    etry!(file.read_to_end(&mut file_bytes), "Could not read file");
+    let thumbnail_bytes = match thumbpath {
         Some(p) => {
             let mut thumb = etry!(File::open(p), format!("Could not open thumbnail {:?}", p));
             let mut thumb_data: Vec<u8> = vec![];
@@ -89,15 +89,18 @@ async fn main() {
     };
 
     // Encrypt file data
-    let (encrypted_file, encrypted_thumb, key) =
-        encrypt_file_data(&file_data, thumb_data.as_deref());
+    let file_data = FileData {
+        file: file_bytes,
+        thumbnail: thumbnail_bytes,
+    };
+    let (encrypted, key) = encrypt_file_data(&file_data);
 
     // Upload files to blob server
     let file_blob_id = etry!(
-        api.blob_upload_raw(&encrypted_file, false).await,
+        api.blob_upload_raw(&encrypted.file, false).await,
         "Could not upload file to blob server"
     );
-    let thumb_blob_id = if let Some(et) = encrypted_thumb {
+    let thumb_blob_id = if let Some(et) = encrypted.thumbnail {
         let blob_id = etry!(
             api.blob_upload_raw(&et, false).await,
             "Could not upload thumbnail to blob server"
@@ -115,7 +118,8 @@ async fn main() {
         .first_or_octet_stream()
         .to_string();
     let file_name = filepath.file_name().and_then(OsStr::to_str);
-    let msg = FileMessage::builder(file_blob_id, key, file_media_type, file_data.len() as u32)
+    let file_size_bytes = file_data.file.len() as u32;
+    let msg = FileMessage::builder(file_blob_id, key, file_media_type, file_size_bytes)
         .thumbnail_opt(thumb_blob_id)
         .file_name_opt(file_name)
         .description_opt(caption)

src/api.rs

@@ -379,7 +379,9 @@ impl E2eApi {
         .await
     }
 
-    /// Download a blob from the blob server and return the bytes.
+    /// Download a blob from the blob server and return the encrypted bytes.
+    ///
+    /// Cost: 0 credits.
     pub async fn blob_download(&self, blob_id: &BlobId) -> Result<Vec<u8>, ApiError> {
         blob_download(
             &self.client,

src/crypto.rs

@@ -161,14 +161,31 @@ static THUMB_NONCE: secretbox::Nonce = secretbox::Nonce([
     0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 2,
 ]);
 
+/// Raw unencrypted bytes of a file and optionally a thumbnail.
+///
+/// This struct is used as a parameter type for [`encrypt_file_data`] and
+/// returned by [`decrypt_file_data`].
+#[derive(Clone)]
+pub struct FileData {
+    pub file: Vec<u8>,
+    pub thumbnail: Option<Vec<u8>>,
+}
+
+/// Encrypted bytes of a file and optionally a thumbnail.
+///
+/// This struct is used as a parameter type for [`decrypt_file_data`] and
+/// returned by [`encrypt_file_data`].
+#[derive(Clone)]
+pub struct EncryptedFileData {
+    pub file: Vec<u8>,
+    pub thumbnail: Option<Vec<u8>>,
+}
+
 /// Encrypt file data and an optional thumbnail using a randomly generated
 /// symmetric key.
 ///
 /// Return the encrypted bytes and the key.
-pub fn encrypt_file_data(
-    file_data: &[u8],
-    thumb_data: Option<&[u8]>,
-) -> (Vec<u8>, Option<Vec<u8>>, secretbox::Key) {
+pub fn encrypt_file_data(data: &FileData) -> (EncryptedFileData, Key) {
     // Make sure to init sodiumoxide library
     sodiumoxide::init().unwrap();
 
@@ -177,23 +194,48 @@ pub fn encrypt_file_data(
 
     // Encrypt data
     // Note: Since we generate a random key, we can safely re-use constant nonces.
-    let encrypted_file = secretbox::seal(file_data, &FILE_NONCE, &key);
-    let encrypted_thumb = thumb_data.map(|t| secretbox::seal(t, &THUMB_NONCE, &key));
+    let file = secretbox::seal(&data.file, &FILE_NONCE, &key);
+    let thumbnail = data
+        .thumbnail
+        .as_ref()
+        .map(|t| secretbox::seal(t, &THUMB_NONCE, &key));
 
-    (encrypted_file, encrypted_thumb, key)
+    (EncryptedFileData { file, thumbnail }, key)
 }
 
-pub fn decrypt_file_data(encrypted_data: &[u8], blob_key: &Key) -> Result<Vec<u8>, CryptoError> {
-    let decrypted_blob = secretbox::open(encrypted_data, &FILE_NONCE, blob_key);
-    decrypted_blob.map_err(|_| CryptoError::DecryptionFailed)
+/// Decrypt file data and optional thumbnail data with the provided symmetric
+/// key.
+///
+/// Return the decrypted bytes.
+pub fn decrypt_file_data(
+    data: &EncryptedFileData,
+    encryption_key: &Key,
+) -> Result<FileData, CryptoError> {
+    // Make sure to init sodiumoxide library
+    sodiumoxide::init().unwrap();
+
+    let file = secretbox::open(&data.file, &FILE_NONCE, encryption_key)
+        .map_err(|_| CryptoError::DecryptionFailed)?;
+    let thumbnail = match data.thumbnail.as_ref() {
+        Some(t) => {
+            let decrypted = secretbox::open(t, &THUMB_NONCE, encryption_key)
+                .map_err(|_| CryptoError::DecryptionFailed)?;
+            Some(decrypted)
+        }
+        None => None,
+    };
+
+    Ok(FileData { file, thumbnail })
 }
 
 #[cfg(test)]
 mod test {
     use std::str::FromStr;
 
-    use crate::api::ApiBuilder;
-    use crate::types::{BlobId, MessageType};
+    use crate::{
+        api::ApiBuilder,
+        types::{BlobId, MessageType},
+    };
     use sodiumoxide::crypto::box_::{self, Nonce, PublicKey, SecretKey};
 
     use super::*;
@@ -336,23 +378,26 @@ mod test {
     fn test_encrypt_file_data() {
         let file_data = [1, 2, 3, 4];
         let thumb_data = [5, 6, 7];
+        let data = FileData {
+            file: file_data.to_vec(),
+            thumbnail: Some(thumb_data.to_vec()),
+        };
 
         // Encrypt
-        let (encrypted_file, encrypted_thumb, key) =
-            encrypt_file_data(&file_data, Some(&thumb_data));
-        let encrypted_thumb = encrypted_thumb.expect("Thumbnail missing");
+        let (encrypted, key) = encrypt_file_data(&data);
+        let encrypted_thumb = encrypted.thumbnail.expect("Thumbnail missing");
 
         // Ensure that encrypted data is different from plaintext data
-        assert_ne!(encrypted_file, file_data);
+        assert_ne!(encrypted.file, file_data);
         assert_ne!(encrypted_thumb, thumb_data);
-        assert_eq!(encrypted_file.len(), file_data.len() + secretbox::MACBYTES);
+        assert_eq!(encrypted.file.len(), file_data.len() + secretbox::MACBYTES);
         assert_eq!(
             encrypted_thumb.len(),
             thumb_data.len() + secretbox::MACBYTES
         );
 
         // Test that data can be decrypted
-        let decrypted_file = secretbox::open(&encrypted_file, &FILE_NONCE, &key).unwrap();
+        let decrypted_file = secretbox::open(&encrypted.file, &FILE_NONCE, &key).unwrap();
         let decrypted_thumb = secretbox::open(&encrypted_thumb, &THUMB_NONCE, &key).unwrap();
         assert_eq!(decrypted_file, &file_data);
         assert_eq!(decrypted_thumb, &thumb_data);
@@ -361,11 +406,41 @@ mod test {
     #[test]
     fn test_encrypt_file_data_random_key() {
         // Ensure that a different key is generated each time
-        let (_, _, key1) = encrypt_file_data(&[1, 2, 3], None);
-        let (_, _, key2) = encrypt_file_data(&[1, 2, 3], None);
-        let (_, _, key3) = encrypt_file_data(&[1, 2, 3], None);
+        let (_, key1) = encrypt_file_data(&FileData {
+            file: [1, 2, 3].to_vec(),
+            thumbnail: None,
+        });
+        let (_, key2) = encrypt_file_data(&FileData {
+            file: [1, 2, 3].to_vec(),
+            thumbnail: None,
+        });
+        let (_, key3) = encrypt_file_data(&FileData {
+            file: [1, 2, 3].to_vec(),
+            thumbnail: None,
+        });
         assert_ne!(key1, key2);
         assert_ne!(key2, key3);
         assert_ne!(key1, key3);
     }
+
+    #[test]
+    fn test_decrypt_file_data() {
+        let file_data = [1, 2, 3, 4];
+        let thumb_data = [5, 6, 7];
+        let data = FileData {
+            file: file_data.to_vec(),
+            thumbnail: Some(thumb_data.to_vec()),
+        };
+
+        // Encrypt
+        let (encrypted, key) = encrypt_file_data(&data);
+        assert_ne!(encrypted.file, data.file);
+        assert!(encrypted.thumbnail.is_some());
+        assert_ne!(encrypted.thumbnail, data.thumbnail);
+
+        // Decrypt
+        let decrypted = decrypt_file_data(&encrypted, &key).unwrap();
+        assert_eq!(decrypted.file, &file_data);
+        assert_eq!(decrypted.thumbnail.unwrap(), &thumb_data);
+    }
 }

src/lib.rs

@@ -91,7 +91,8 @@ pub use crate::{
     api::{ApiBuilder, E2eApi, SimpleApi},
     connection::Recipient,
     crypto::{
-        decrypt_file_data, encrypt, encrypt_file_data, encrypt_raw, EncryptedMessage, RecipientKey,
+        decrypt_file_data, encrypt, encrypt_file_data, encrypt_raw, EncryptedFileData,
+        EncryptedMessage, FileData, RecipientKey,
     },
     lookup::{Capabilities, LookupCriterion},
     types::{BlobId, FileMessage, FileMessageBuilder, MessageType, RenderingType},