Skip to main content

rustium_pdf/
filters.rs

1//! Stream filters.
2//!
3//! Content and font streams decode fully here. Image-only filters (DCT, JPX, CCITT, JBIG2) are
4//! passed through untouched with the filter name reported, because the pixel decoders live in
5//! the renderer and callers extracting structure never need the pixels.
6
7use crate::error::{Error, Result};
8use crate::object::{Dict, Object};
9
10/// The most a single stream may decompress to.
11///
12/// Flate and LZW both have compression ratios of a thousand to one and better, so a few kilobytes
13/// of hostile input can otherwise ask for gigabytes of memory. Real streams are far smaller than
14/// this; a stream that reaches the cap is truncated there, the same as a corrupt tail, rather than
15/// failing the document.
16const MAX_DECOMPRESSED: usize = 256 << 20;
17
18/// The result of running a stream's filter chain.
19pub struct Decoded {
20    pub data: Vec<u8>,
21    /// `Some(name)` when the chain ended at an image codec the byte-level filters do not
22    /// decode; `data` is then that codec's compressed payload.
23    pub image_filter: Option<String>,
24}
25
26/// Applies a stream's `/Filter` chain to `data`.
27///
28/// `resolve` maps indirect objects to direct ones, since `/Filter`, `/DecodeParms` and their
29/// members may all be references.
30pub fn decode(dict: &Dict, data: &[u8], resolve: &dyn Fn(&Object) -> Object) -> Result<Decoded> {
31    let filters = filter_names(dict, resolve);
32    let parms = decode_parms(dict, filters.len(), resolve);
33
34    let mut data = data.to_vec();
35    for (i, name) in filters.iter().enumerate() {
36        let parm = parms.get(i).cloned().unwrap_or_default();
37        match name.as_str() {
38            "FlateDecode" | "Fl" => {
39                data = apply_predictor(&parm, inflate(&data)?, resolve)?;
40            }
41            "LZWDecode" | "LZW" => {
42                let early = parm
43                    .get("EarlyChange")
44                    .map(resolve)
45                    .and_then(|o| o.as_int())
46                    .unwrap_or(1)
47                    != 0;
48                data = apply_predictor(&parm, lzw_decode(&data, early), resolve)?;
49            }
50            "ASCIIHexDecode" | "AHx" => data = ascii_hex_decode(&data),
51            "ASCII85Decode" | "A85" => data = ascii85_decode(&data),
52            "RunLengthDecode" | "RL" => data = run_length_decode(&data),
53            "Crypt" => {
54                // Identity crypt filters appear on already-decrypted streams; anything else was
55                // handled at the document layer before filters ran.
56            }
57            "DCTDecode" | "DCT" | "JPXDecode" | "CCITTFaxDecode" | "CCF" | "JBIG2Decode" => {
58                return Ok(Decoded {
59                    data,
60                    image_filter: Some(name.clone()),
61                });
62            }
63            other => {
64                return Err(Error::Parse(format!("unknown filter {other}")));
65            }
66        }
67    }
68    Ok(Decoded {
69        data,
70        image_filter: None,
71    })
72}
73
74fn filter_names(dict: &Dict, resolve: &dyn Fn(&Object) -> Object) -> Vec<String> {
75    let entry = dict
76        .get("Filter")
77        .or_else(|| dict.get("F").filter(|o| !matches!(o, Object::String(_))));
78    let Some(entry) = entry else {
79        return Vec::new();
80    };
81    match resolve(entry) {
82        Object::Name(n) => vec![n],
83        Object::Array(items) => items
84            .iter()
85            .filter_map(|o| resolve(o).as_name().map(str::to_owned))
86            .collect(),
87        _ => Vec::new(),
88    }
89}
90
91fn decode_parms(dict: &Dict, n: usize, resolve: &dyn Fn(&Object) -> Object) -> Vec<Dict> {
92    let entry = dict.get("DecodeParms").or_else(|| dict.get("DP"));
93    let Some(entry) = entry else {
94        return vec![Dict::new(); n];
95    };
96    match resolve(entry) {
97        Object::Dict(d) => {
98            let mut v = vec![Dict::new(); n];
99            if let Some(slot) = v.first_mut() {
100                *slot = d;
101            }
102            v
103        }
104        Object::Array(items) => (0..n)
105            .map(|i| {
106                items
107                    .get(i)
108                    .map(resolve)
109                    .and_then(|o| o.as_dict().cloned())
110                    .unwrap_or_default()
111            })
112            .collect(),
113        _ => vec![Dict::new(); n],
114    }
115}
116
117/// Inflates zlib or raw deflate data, keeping whatever decoded cleanly when the tail is corrupt.
118///
119/// Truncated and trailing-garbage Flate streams are common enough in the wild that failing hard
120/// would reject otherwise fine documents. Output stops at [`MAX_DECOMPRESSED`].
121fn inflate(data: &[u8]) -> Result<Vec<u8>> {
122    use flate2::{Decompress, FlushDecompress, Status};
123
124    // Skip leading whitespace some producers leave before the zlib header.
125    let start = data
126        .iter()
127        .position(|&b| !b.is_ascii_whitespace())
128        .unwrap_or(0);
129    let data = &data[start..];
130
131    let zlib = data.first().is_some_and(|&b| b & 0x0f == 8);
132    let mut inflater = Decompress::new(zlib);
133    let mut out = Vec::with_capacity(data.len().saturating_mul(4).min(1 << 20));
134    let mut buf = vec![0u8; 64 * 1024];
135    loop {
136        let before_in = inflater.total_in();
137        let before_out = inflater.total_out();
138        let status = inflater.decompress(
139            &data[inflater.total_in() as usize..],
140            &mut buf,
141            FlushDecompress::None,
142        );
143        let produced = (inflater.total_out() - before_out) as usize;
144        let room = MAX_DECOMPRESSED - out.len();
145        out.extend_from_slice(&buf[..produced.min(room)]);
146        if produced >= room {
147            // A zip bomb, or a stream far larger than anything a page needs; keep the prefix.
148            break;
149        }
150        match status {
151            Ok(Status::StreamEnd) => break,
152            Ok(_) => {
153                let consumed = inflater.total_in() - before_in;
154                if consumed == 0 && produced == 0 {
155                    break; // No progress: truncated stream.
156                }
157            }
158            Err(_) => break, // Corrupt tail: keep what we have.
159        }
160    }
161    if out.is_empty() && !data.is_empty() {
162        return Err(Error::Parse("flate stream decoded to nothing".into()));
163    }
164    Ok(out)
165}
166
167fn apply_predictor(
168    parm: &Dict,
169    data: Vec<u8>,
170    resolve: &dyn Fn(&Object) -> Object,
171) -> Result<Vec<u8>> {
172    let get = |k: &str, default: i64| {
173        parm.get(k)
174            .map(resolve)
175            .and_then(|o| o.as_int())
176            .unwrap_or(default)
177    };
178    let predictor = get("Predictor", 1);
179    if predictor <= 1 {
180        return Ok(data);
181    }
182    let colors = get("Colors", 1).max(1) as usize;
183    let bpc = get("BitsPerComponent", 8).max(1) as usize;
184    let columns = get("Columns", 1).max(1) as usize;
185    let bpp = (colors * bpc).div_ceil(8); // bytes per pixel, min 1
186    let row_len = (colors * bpc * columns).div_ceil(8);
187
188    if predictor == 2 {
189        return Ok(tiff_predictor(data, colors, bpc, columns));
190    }
191
192    // PNG predictors: each row is prefixed with its filter type.
193    let stride = row_len + 1;
194    let rows = data.len() / stride;
195    let mut out = Vec::with_capacity(rows * row_len);
196    let mut prev = vec![0u8; row_len];
197    for r in 0..rows {
198        let row = &data[r * stride..(r + 1) * stride];
199        let ft = row[0];
200        let mut cur = row[1..].to_vec();
201        match ft {
202            0 => {}
203            1 => {
204                for i in bpp..row_len {
205                    cur[i] = cur[i].wrapping_add(cur[i - bpp]);
206                }
207            }
208            2 => {
209                for i in 0..row_len {
210                    cur[i] = cur[i].wrapping_add(prev[i]);
211                }
212            }
213            3 => {
214                for i in 0..row_len {
215                    let left = if i >= bpp { cur[i - bpp] as u32 } else { 0 };
216                    cur[i] = cur[i].wrapping_add(((left + prev[i] as u32) / 2) as u8);
217                }
218            }
219            4 => {
220                for i in 0..row_len {
221                    let a = if i >= bpp { cur[i - bpp] as i32 } else { 0 };
222                    let b = prev[i] as i32;
223                    let c = if i >= bpp { prev[i - bpp] as i32 } else { 0 };
224                    let p = a + b - c;
225                    let (pa, pb, pc) = ((p - a).abs(), (p - b).abs(), (p - c).abs());
226                    let pred = if pa <= pb && pa <= pc {
227                        a
228                    } else if pb <= pc {
229                        b
230                    } else {
231                        c
232                    };
233                    cur[i] = cur[i].wrapping_add(pred as u8);
234                }
235            }
236            _ => return Err(Error::Parse(format!("png predictor row type {ft}"))),
237        }
238        out.extend_from_slice(&cur);
239        prev = cur;
240    }
241    Ok(out)
242}
243
244fn tiff_predictor(mut data: Vec<u8>, colors: usize, bpc: usize, columns: usize) -> Vec<u8> {
245    if bpc != 8 {
246        // Sub-byte TIFF prediction is vanishingly rare; return as-is rather than corrupt.
247        return data;
248    }
249    let row_len = colors * columns;
250    for row in data.chunks_mut(row_len) {
251        for i in colors..row.len() {
252            row[i] = row[i].wrapping_add(row[i - colors]);
253        }
254    }
255    data
256}
257
258/// Decodes LZW, stopping at [`MAX_DECOMPRESSED`] output bytes.
259fn lzw_decode(data: &[u8], early_change: bool) -> Vec<u8> {
260    const CLEAR: u16 = 256;
261    const EOD: u16 = 257;
262
263    let mut out = Vec::with_capacity(data.len().saturating_mul(3).min(1 << 20));
264    let mut table: Vec<Vec<u8>> = Vec::new();
265    let reset = |table: &mut Vec<Vec<u8>>| {
266        table.clear();
267        for b in 0u16..256 {
268            table.push(vec![b as u8]);
269        }
270        table.push(Vec::new()); // 256: clear
271        table.push(Vec::new()); // 257: eod
272    };
273    reset(&mut table);
274
275    let mut bits = 9usize;
276    let mut acc = 0u32;
277    let mut nbits = 0usize;
278    let mut prev: Option<u16> = None;
279
280    for &byte in data {
281        acc = (acc << 8) | byte as u32;
282        nbits += 8;
283        while nbits >= bits {
284            let code = ((acc >> (nbits - bits)) & ((1 << bits) - 1)) as u16;
285            nbits -= bits;
286
287            if code == CLEAR {
288                reset(&mut table);
289                bits = 9;
290                prev = None;
291                continue;
292            }
293            if code == EOD {
294                return out;
295            }
296            let entry: Vec<u8> = if (code as usize) < table.len() {
297                table[code as usize].clone()
298            } else if let Some(p) = prev {
299                // KwKwK case.
300                let mut e = table[p as usize].clone();
301                if let Some(&f) = table[p as usize].first() {
302                    e.push(f);
303                }
304                e
305            } else {
306                return out; // Corrupt.
307            };
308            let room = MAX_DECOMPRESSED - out.len();
309            if entry.len() >= room {
310                // A bomb, or a stream far larger than anything a page needs; keep the prefix.
311                out.extend_from_slice(&entry[..room]);
312                return out;
313            }
314            out.extend_from_slice(&entry);
315            if let Some(p) = prev {
316                let mut ne = table[p as usize].clone();
317                if let Some(&f) = entry.first() {
318                    ne.push(f);
319                }
320                table.push(ne);
321            }
322            prev = Some(code);
323
324            let limit = if early_change { 1 } else { 0 };
325            if table.len() + limit >= (1 << bits) && bits < 12 {
326                bits += 1;
327            }
328        }
329    }
330    out
331}
332
333fn ascii_hex_decode(data: &[u8]) -> Vec<u8> {
334    let mut out = Vec::with_capacity(data.len() / 2);
335    let mut hi: Option<u8> = None;
336    for &b in data {
337        if b == b'>' {
338            break;
339        }
340        let Some(v) = crate::lexer::hex_val(b) else {
341            continue;
342        };
343        match hi.take() {
344            Some(h) => out.push(h * 16 + v),
345            None => hi = Some(v),
346        }
347    }
348    if let Some(h) = hi {
349        out.push(h * 16);
350    }
351    out
352}
353
354fn ascii85_decode(data: &[u8]) -> Vec<u8> {
355    let mut out = Vec::with_capacity(data.len() * 4 / 5);
356    let mut group = [0u8; 5];
357    let mut n = 0usize;
358    let mut i = 0usize;
359    // Optional <~ prefix.
360    if data.len() >= 2 && &data[0..2] == b"<~" {
361        i = 2;
362    }
363    while i < data.len() {
364        let b = data[i];
365        i += 1;
366        match b {
367            b'~' => break,
368            b'z' if n == 0 => out.extend_from_slice(&[0, 0, 0, 0]),
369            b'!'..=b'u' => {
370                group[n] = b - b'!';
371                n += 1;
372                if n == 5 {
373                    let mut v = 0u32;
374                    for &g in &group {
375                        v = v.wrapping_mul(85).wrapping_add(g as u32);
376                    }
377                    out.extend_from_slice(&v.to_be_bytes());
378                    n = 0;
379                }
380            }
381            _ => {} // Whitespace and junk.
382        }
383    }
384    if n > 0 {
385        // Pad with 'u' (84) and keep n-1 bytes.
386        for slot in group.iter_mut().skip(n) {
387            *slot = 84;
388        }
389        let mut v = 0u32;
390        for &g in &group {
391            v = v.wrapping_mul(85).wrapping_add(g as u32);
392        }
393        out.extend_from_slice(&v.to_be_bytes()[..n - 1]);
394    }
395    out
396}
397
398fn run_length_decode(data: &[u8]) -> Vec<u8> {
399    let mut out = Vec::with_capacity(data.len() * 2);
400    let mut i = 0usize;
401    while i < data.len() {
402        let len = data[i];
403        i += 1;
404        match len {
405            0..=127 => {
406                let take = (len as usize + 1).min(data.len() - i);
407                out.extend_from_slice(&data[i..i + take]);
408                i += take;
409            }
410            128 => break,
411            _ => {
412                if i < data.len() {
413                    out.extend(std::iter::repeat_n(data[i], 257 - len as usize));
414                    i += 1;
415                }
416            }
417        }
418    }
419    out
420}
421
422#[cfg(test)]
423mod tests {
424    use super::*;
425
426    fn no_resolve(o: &Object) -> Object {
427        o.clone()
428    }
429
430    #[test]
431    fn flate_round_trip() {
432        use flate2::write::ZlibEncoder;
433        use flate2::Compression;
434        use std::io::Write;
435        let payload = b"BT /F1 12 Tf (Hello) Tj ET".repeat(100);
436        let mut enc = ZlibEncoder::new(Vec::new(), Compression::default());
437        enc.write_all(&payload).unwrap();
438        let compressed = enc.finish().unwrap();
439
440        let mut dict = Dict::new();
441        dict.insert("Filter", Object::Name("FlateDecode".into()));
442        let d = decode(&dict, &compressed, &no_resolve).unwrap();
443        assert_eq!(d.data, payload);
444        assert!(d.image_filter.is_none());
445    }
446
447    #[test]
448    fn truncated_flate_keeps_prefix() {
449        use flate2::write::ZlibEncoder;
450        use flate2::Compression;
451        use std::io::Write;
452        let payload = vec![7u8; 100_000];
453        let mut enc = ZlibEncoder::new(Vec::new(), Compression::default());
454        enc.write_all(&payload).unwrap();
455        let mut compressed = enc.finish().unwrap();
456        compressed.truncate(compressed.len() / 2);
457
458        let mut dict = Dict::new();
459        dict.insert("Filter", Object::Name("FlateDecode".into()));
460        let d = decode(&dict, &compressed, &no_resolve).unwrap();
461        assert!(!d.data.is_empty());
462        assert!(d.data.iter().all(|&b| b == 7));
463    }
464
465    #[test]
466    fn flate_bomb_is_capped() {
467        use flate2::write::ZlibEncoder;
468        use flate2::Compression;
469        use std::io::Write;
470
471        // Half a gigabyte of zeros in about a megabyte of stream: the shape of a zip bomb.
472        let chunk = vec![0u8; 1 << 20];
473        let mut enc = ZlibEncoder::new(Vec::new(), Compression::best());
474        for _ in 0..512 {
475            enc.write_all(&chunk).unwrap();
476        }
477        let compressed = enc.finish().unwrap();
478        assert!(compressed.len() < 1 << 21, "test bomb should be small");
479
480        let mut dict = Dict::new();
481        dict.insert("Filter", Object::Name("FlateDecode".into()));
482        let d = decode(&dict, &compressed, &no_resolve).unwrap();
483        assert_eq!(d.data.len(), MAX_DECOMPRESSED);
484    }
485
486    #[test]
487    fn ascii_filters() {
488        assert_eq!(ascii_hex_decode(b"48656C6C6F>"), b"Hello");
489        assert_eq!(ascii85_decode(b"87cURD_*#T~>"), b"Hello, w");
490        assert_eq!(ascii85_decode(b"z~>"), [0, 0, 0, 0]);
491    }
492
493    #[test]
494    fn run_length() {
495        // 2 literal bytes, then 0xFF repeated 4 times (257-253), then EOD.
496        assert_eq!(
497            run_length_decode(&[1, b'a', b'b', 253, 0xFF, 128]),
498            b"ab\xff\xff\xff\xff"
499        );
500    }
501
502    #[test]
503    fn lzw_known_vector() {
504        // The example from the PDF spec, 7.4.4.2: decodes to 45 45 45 45 45 65 45 45 45 66.
505        let encoded = [0x80, 0x0B, 0x60, 0x50, 0x22, 0x0C, 0x0C, 0x85, 0x01];
506        assert_eq!(
507            lzw_decode(&encoded, true),
508            [45, 45, 45, 45, 45, 65, 45, 45, 45, 66]
509        );
510    }
511
512    #[test]
513    fn png_up_predictor() {
514        // Two rows of 3 bytes, filter type 2 (Up).
515        let mut dict = Dict::new();
516        dict.insert("Filter", Object::Name("FlateDecode".into()));
517        let mut parms = Dict::new();
518        parms.insert("Predictor", Object::Int(12));
519        parms.insert("Columns", Object::Int(3));
520        dict.insert("DecodeParms", Object::Dict(parms));
521
522        use flate2::write::ZlibEncoder;
523        use flate2::Compression;
524        use std::io::Write;
525        let raw = [2u8, 1, 2, 3, 2, 1, 1, 1];
526        let mut enc = ZlibEncoder::new(Vec::new(), Compression::default());
527        enc.write_all(&raw).unwrap();
528        let compressed = enc.finish().unwrap();
529
530        let d = decode(&dict, &compressed, &no_resolve).unwrap();
531        assert_eq!(d.data, [1, 2, 3, 2, 3, 4]);
532    }
533
534    #[test]
535    fn dct_passes_through() {
536        let mut dict = Dict::new();
537        dict.insert("Filter", Object::Name("DCTDecode".into()));
538        let d = decode(&dict, b"\xff\xd8jpegdata", &no_resolve).unwrap();
539        assert_eq!(d.image_filter.as_deref(), Some("DCTDecode"));
540        assert_eq!(d.data, b"\xff\xd8jpegdata");
541    }
542}