Skip to main content

wechat_protocol/
upload_source.rs

1//! Uploads whose plaintext stays in a file and is encrypted one chunk at a time.
2//!
3//! CDN objects use AES-128-ECB with PKCS#7 padding, so each 16-byte ciphertext
4//! block depends only on the plaintext block at the same offset. A chunk that
5//! starts on a block boundary is encrypted on its own from that plaintext
6//! range, and the result is byte-for-byte the slice of the whole-object
7//! ciphertext. A [`PreparedFileUpload`] is therefore read from disk as it is
8//! sent instead of being encrypted into memory first, and every request is the
9//! same as for the equivalent in-memory [`PreparedUpload`].
10use super::*;
11use std::{
12    io::{Seek, SeekFrom},
13    sync::{Arc, Mutex},
14};
15use zeroize::Zeroizing;
16
17fn ciphertext_len(plaintext: usize) -> usize {
18    (plaintext / 16 + 1) * 16
19}
20
21/// One object ready to upload from a private file. The file is read in steps
22/// while the object is sent; its length, MD5 and SHA-256 are checked again on
23/// the way, and the request that ends the object is only made once every byte
24/// read matched. Persist the key and file key before the first request, as
25/// for [`PreparedUpload`].
26#[derive(Clone)]
27pub struct PreparedFileUpload {
28    /// CDN object type to upload as.
29    pub kind: MediaQuality,
30    /// AES-128 key the object is encrypted with.
31    pub aes_key: Vec<u8>,
32    /// Client file key that correlates the upload's requests.
33    pub file_key: String,
34    /// Size of the plaintext in bytes.
35    pub plaintext_bytes: u32,
36    /// Lowercase hex MD5 of the plaintext.
37    pub md5: String,
38    /// Lowercase hex SHA-256 of the plaintext.
39    pub sha256: String,
40    /// File name sent with the upload.
41    pub file_name: String,
42    /// Chat the upload is for.
43    pub destination: String,
44    file: Arc<Mutex<std::fs::File>>,
45}
46impl Drop for PreparedFileUpload {
47    fn drop(&mut self) {
48        self.aes_key.zeroize();
49        self.file_key.zeroize();
50    }
51}
52impl fmt::Debug for PreparedFileUpload {
53    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
54        f.debug_struct("PreparedFileUpload")
55            .field("kind", &self.kind)
56            .field("plaintext_bytes", &self.plaintext_bytes)
57            .field("material", &"[redacted]")
58            .finish()
59    }
60}
61impl PreparedFileUpload {
62    /// Prepare an upload of `file`. `length`, `md5` and `sha256` describe the
63    /// file; the caller computed them while writing it. A file of another
64    /// length is refused now, and changed bytes before the final request.
65    #[allow(clippy::too_many_arguments)]
66    pub fn new(
67        file: std::fs::File,
68        length: u64,
69        md5: &str,
70        sha256: &str,
71        kind: MediaQuality,
72        file_name: &str,
73        destination: &str,
74        key: &[u8],
75        file_key: &str,
76    ) -> Result<Self> {
77        let plaintext_bytes = usize::try_from(length)?;
78        check_upload_profile(plaintext_bytes, kind, file_name, destination, key, file_key)?;
79        ensure!(
80            md5.len() == 32
81                && md5.bytes().all(|b| b.is_ascii_hexdigit())
82                && sha256.len() == 64
83                && sha256.bytes().all(|b| b.is_ascii_hexdigit()),
84            "Invalid upload source digest"
85        );
86        ensure!(file.metadata()?.len() == length, "Upload source changed");
87        Ok(Self {
88            kind,
89            aes_key: key.to_vec(),
90            file_key: file_key.to_string(),
91            plaintext_bytes: u32::try_from(plaintext_bytes)?,
92            md5: md5.to_ascii_lowercase(),
93            sha256: sha256.to_ascii_lowercase(),
94            file_name: file_name.into(),
95            destination: destination.into(),
96            file: Arc::new(Mutex::new(file)),
97        })
98    }
99    /// Length of the encrypted object, including its padding block.
100    pub fn encrypted_len(&self) -> usize {
101        ciphertext_len(self.plaintext_bytes as usize)
102    }
103    /// The same upload held in memory, for transports that send one object per
104    /// request. The file is read whole and checked against its digests.
105    pub fn to_memory(&self) -> Result<PreparedUpload> {
106        let mut raw = Zeroizing::new(vec![0u8; self.plaintext_bytes as usize]);
107        self.read_at(0, &mut raw)?;
108        let prepared = PreparedUpload::with_material(
109            &raw,
110            self.kind,
111            &self.file_name,
112            &self.destination,
113            &self.aes_key,
114            &self.file_key,
115        )?;
116        ensure!(
117            prepared.md5 == self.md5 && prepared.sha256 == self.sha256,
118            "Prepared upload digest mismatch"
119        );
120        Ok(prepared)
121    }
122    fn read_at(&self, offset: u64, buffer: &mut [u8]) -> Result<()> {
123        let mut file = self
124            .file
125            .lock()
126            .map_err(|_| anyhow::anyhow!("Upload source unavailable"))?;
127        file.seek(SeekFrom::Start(offset))?;
128        file.read_exact(buffer)
129            .map_err(|_| anyhow::anyhow!("Upload source changed"))
130    }
131}
132
133/// Checks shared by every way of preparing an upload.
134pub(super) fn check_upload_profile(
135    length: usize,
136    kind: MediaQuality,
137    file_name: &str,
138    destination: &str,
139    key: &[u8],
140    file_key: &str,
141) -> Result<()> {
142    ensure!(
143        length > 0
144            && length <= upload_plaintext_limit(kind)
145            && [
146                MediaQuality::File,
147                MediaQuality::LargeFile,
148                MediaQuality::Original,
149                MediaQuality::Video
150            ]
151            .contains(&kind),
152        "Unsupported upload profile"
153    );
154    ensure!(
155        !file_name.is_empty()
156            && file_name.len() <= 255
157            && file_name != "."
158            && file_name != ".."
159            && !file_name.contains(['/', '\\'])
160            && !file_name.chars().any(|c| c.is_control()),
161        "Invalid upload filename"
162    );
163    ensure!(
164        key.len() == 16 && file_key.len() == 32 && file_key.bytes().all(|b| b.is_ascii_hexdigit()),
165        "Invalid durable upload material"
166    );
167    encrypt_recipient(destination)?;
168    Ok(())
169}
170
171/// Either kind of prepared upload, for the shared request builders.
172#[derive(Clone, Copy)]
173pub(super) enum UploadRef<'a> {
174    Memory(&'a PreparedUpload),
175    File(&'a PreparedFileUpload),
176}
177impl<'a> UploadRef<'a> {
178    pub(super) fn kind(self) -> MediaQuality {
179        match self {
180            Self::Memory(p) => p.kind,
181            Self::File(p) => p.kind,
182        }
183    }
184    pub(super) fn aes_key(self) -> &'a [u8] {
185        match self {
186            Self::Memory(p) => &p.aes_key,
187            Self::File(p) => &p.aes_key,
188        }
189    }
190    pub(super) fn file_key(self) -> &'a str {
191        match self {
192            Self::Memory(p) => &p.file_key,
193            Self::File(p) => &p.file_key,
194        }
195    }
196    pub(super) fn plaintext_bytes(self) -> u32 {
197        match self {
198            Self::Memory(p) => p.plaintext_bytes,
199            Self::File(p) => p.plaintext_bytes,
200        }
201    }
202    pub(super) fn md5(self) -> &'a str {
203        match self {
204            Self::Memory(p) => &p.md5,
205            Self::File(p) => &p.md5,
206        }
207    }
208    pub(super) fn sha256(self) -> &'a str {
209        match self {
210            Self::Memory(p) => &p.sha256,
211            Self::File(p) => &p.sha256,
212        }
213    }
214    pub(super) fn file_name(self) -> &'a str {
215        match self {
216            Self::Memory(p) => &p.file_name,
217            Self::File(p) => &p.file_name,
218        }
219    }
220    pub(super) fn destination(self) -> &'a str {
221        match self {
222            Self::Memory(p) => &p.destination,
223            Self::File(p) => &p.destination,
224        }
225    }
226    pub(super) fn encrypted_len(self) -> usize {
227        match self {
228            Self::Memory(p) => p.encrypted.len(),
229            Self::File(p) => p.encrypted_len(),
230        }
231    }
232    /// Checks made before any request. An in-memory upload's ciphertext is
233    /// fully checked; a file is checked while it is sent instead.
234    pub(super) fn validate(self) -> Result<()> {
235        match self {
236            Self::Memory(p) => p.validate(),
237            Self::File(p) => {
238                ensure!(
239                    p.aes_key.len() == 16
240                        && p.file_key.len() == 32
241                        && p.file_key.bytes().all(|b| b.is_ascii_hexdigit())
242                        && p.plaintext_bytes > 0
243                        && p.plaintext_bytes as usize <= upload_plaintext_limit(p.kind),
244                    "Invalid prepared upload"
245                );
246                Ok(())
247            }
248        }
249    }
250    /// The encrypted object in order, one chunk at a time.
251    pub(super) fn chunks(self) -> CiphertextChunks<'a> {
252        CiphertextChunks {
253            upload: self,
254            position: 0,
255            md5: None,
256            sha256: None,
257        }
258    }
259    /// The uploaded object's receipt for this upload.
260    pub(super) fn uploaded(
261        self,
262        file_id: String,
263        width: Option<u32>,
264        height: Option<u32>,
265    ) -> UploadedMedia {
266        UploadedMedia {
267            descriptor: MediaDescriptor {
268                file_id,
269                aes_key: self.aes_key().to_vec(),
270                quality: self.kind(),
271                expected_bytes: Some(self.plaintext_bytes() as u64),
272                expected_md5: Some(self.md5().into()),
273                strict_size: true,
274                expires_at: None,
275            },
276            plaintext_bytes: self.plaintext_bytes(),
277            md5: self.md5().into(),
278            sha256: self.sha256().into(),
279            file_name: self.file_name().into(),
280            width,
281            height,
282        }
283    }
284}
285
286/// Produces an upload's ciphertext from the start, in order. For a file, the
287/// plaintext is hashed as it is read, and the chunk holding the end of the
288/// object is returned only when the length and both digests match.
289pub(super) struct CiphertextChunks<'a> {
290    upload: UploadRef<'a>,
291    position: usize,
292    md5: Option<Hasher>,
293    sha256: Option<Hasher>,
294}
295impl CiphertextChunks<'_> {
296    /// Ciphertext offset of the next chunk.
297    pub(super) fn position(&self) -> usize {
298        self.position
299    }
300    /// The next `size` ciphertext bytes, or fewer at the end of the object.
301    /// `size` must be a multiple of the 16-byte block size.
302    pub(super) fn next(&mut self, size: usize) -> Result<Zeroizing<Vec<u8>>> {
303        let total = self.upload.encrypted_len();
304        ensure!(
305            size > 0 && size.is_multiple_of(16) && self.position < total,
306            "Invalid upload range"
307        );
308        let end = (self.position + size).min(total);
309        let prepared = match self.upload {
310            UploadRef::Memory(prepared) => {
311                let chunk = Zeroizing::new(prepared.encrypted[self.position..end].to_vec());
312                self.position = end;
313                return Ok(chunk);
314            }
315            UploadRef::File(prepared) => prepared,
316        };
317        let plaintext = prepared.plaintext_bytes as usize;
318        let read = end.min(plaintext).saturating_sub(self.position);
319        let mut block = Zeroizing::new(vec![0u8; end - self.position]);
320        prepared.read_at(self.position as u64, &mut block[..read])?;
321        let md5 = match &mut self.md5 {
322            Some(hasher) => hasher,
323            None => self.md5.insert(Hasher::new(MessageDigest::md5())?),
324        };
325        md5.update(&block[..read])?;
326        let sha256 = match &mut self.sha256 {
327            Some(hasher) => hasher,
328            None => self.sha256.insert(Hasher::new(MessageDigest::sha256())?),
329        };
330        sha256.update(&block[..read])?;
331        if end == total {
332            // PKCS#7: the final block is completed with copies of its pad length.
333            let pad = (total - plaintext) as u8;
334            block[read..].fill(pad);
335            let md5 = hex::encode(self.md5.take().unwrap().finish()?);
336            let sha256 = hex::encode(self.sha256.take().unwrap().finish()?);
337            ensure!(
338                md5 == prepared.md5 && sha256 == prepared.sha256,
339                "Prepared upload digest mismatch"
340            );
341        }
342        let mut crypter = Crypter::new(
343            Cipher::aes_128_ecb(),
344            Mode::Encrypt,
345            &prepared.aes_key,
346            None,
347        )?;
348        crypter.pad(false);
349        let mut encrypted = Zeroizing::new(vec![0u8; block.len() + 16]);
350        let count = crypter.update(&block, &mut encrypted)?;
351        let rest = crypter.finalize(&mut encrypted[count..])?;
352        encrypted.truncate(count + rest);
353        ensure!(encrypted.len() == block.len(), "Invalid upload range");
354        self.position = end;
355        Ok(encrypted)
356    }
357}
358
359#[cfg(test)]
360pub(super) mod tests {
361    use super::*;
362    use std::io::Write;
363
364    fn material() -> ([u8; 16], String) {
365        ([9; 16], "a".repeat(32))
366    }
367    fn whole(upload: UploadRef<'_>, chunk: usize) -> Vec<u8> {
368        let mut chunks = upload.chunks();
369        let mut out = vec![];
370        while chunks.position() < upload.encrypted_len() {
371            out.extend_from_slice(&chunks.next(chunk).unwrap());
372        }
373        out
374    }
375    pub(in super::super) struct FileSource {
376        _directory: wechat_platform::PrivateTempDir,
377        pub(in super::super) path: std::path::PathBuf,
378    }
379    /// A file upload of `raw` with `kind`, using the given material.
380    pub(in super::super) fn file_upload_with(
381        raw: &[u8],
382        kind: MediaQuality,
383        key: &[u8],
384        file_key: &str,
385    ) -> (FileSource, PreparedFileUpload) {
386        let directory = wechat_platform::private_tempdir("wechat-upload-source-test-").unwrap();
387        let path = directory.path().join("source");
388        std::fs::File::create(&path)
389            .unwrap()
390            .write_all(raw)
391            .unwrap();
392        let prepared = PreparedFileUpload::new(
393            std::fs::File::open(&path).unwrap(),
394            raw.len() as u64,
395            &hex::encode(md5(raw)),
396            &hex::encode(sha256(raw)),
397            kind,
398            "a.bin",
399            "wxid_peer",
400            key,
401            file_key,
402        )
403        .unwrap();
404        (
405            FileSource {
406                _directory: directory,
407                path,
408            },
409            prepared,
410        )
411    }
412    fn file_upload(raw: &[u8]) -> (FileSource, PreparedFileUpload) {
413        let (key, file_key) = material();
414        file_upload_with(raw, MediaQuality::File, &key, &file_key)
415    }
416
417    #[test]
418    fn file_chunks_match_the_in_memory_upload_at_every_boundary() {
419        let (key, file_key) = material();
420        for length in [
421            1,
422            15,
423            16,
424            17,
425            31,
426            32,
427            33,
428            65535,
429            65536,
430            65537,
431            131072 - 16,
432            131072,
433        ] {
434            let raw: Vec<u8> = (0..length).map(|i| (i * 7 % 251) as u8).collect();
435            let memory = PreparedUpload::with_material(
436                &raw,
437                MediaQuality::File,
438                "a.bin",
439                "wxid_peer",
440                &key,
441                &file_key,
442            )
443            .unwrap();
444            let (_file, from_file) = file_upload(&raw);
445            assert_eq!(
446                from_file.encrypted_len(),
447                memory.encrypted.len(),
448                "length {length}"
449            );
450            for chunk in [16, 4096, UPLOAD_CHUNK] {
451                assert_eq!(whole(UploadRef::Memory(&memory), chunk), memory.encrypted);
452                assert_eq!(
453                    whole(UploadRef::File(&from_file), chunk),
454                    memory.encrypted,
455                    "file {length}/{chunk}"
456                );
457            }
458            let copied = from_file.to_memory().unwrap();
459            assert_eq!(copied.encrypted, memory.encrypted);
460            assert_eq!(
461                (copied.md5.clone(), copied.sha256.clone()),
462                (memory.md5.clone(), memory.sha256.clone())
463            );
464        }
465    }
466
467    #[test]
468    fn a_changed_or_truncated_file_never_yields_the_final_chunk() {
469        let raw: Vec<u8> = (0..70_000).map(|i| (i % 256) as u8).collect();
470        let (file, prepared) = file_upload(&raw);
471        // Changed after preparation: earlier chunks are produced, the last is refused.
472        let mut changed = raw.clone();
473        changed[69_999] ^= 1;
474        std::fs::write(&file.path, &changed).unwrap();
475        let mut chunks = UploadRef::File(&prepared).chunks();
476        chunks.next(UPLOAD_CHUNK).unwrap();
477        let error = chunks.next(UPLOAD_CHUNK).unwrap_err();
478        assert_eq!(error.to_string(), "Prepared upload digest mismatch");
479        assert!(prepared.to_memory().is_err());
480        // Truncated: the read itself fails.
481        std::fs::write(&file.path, &raw[..66_000]).unwrap();
482        let mut chunks = UploadRef::File(&prepared).chunks();
483        chunks.next(UPLOAD_CHUNK).unwrap();
484        let error = chunks.next(UPLOAD_CHUNK).unwrap_err();
485        assert_eq!(error.to_string(), "Upload source changed");
486        // A file whose length differs is refused when prepared.
487        let (key, file_key) = material();
488        let error = PreparedFileUpload::new(
489            std::fs::File::open(&file.path).unwrap(),
490            raw.len() as u64,
491            &hex::encode(md5(&raw)),
492            &hex::encode(sha256(&raw)),
493            MediaQuality::File,
494            "a.bin",
495            "wxid_peer",
496            &key,
497            &file_key,
498        )
499        .err()
500        .unwrap();
501        assert_eq!(error.to_string(), "Upload source changed");
502    }
503}