mail_auth/dkim2/
headers.rs

1/*
2 * SPDX-FileCopyrightText: 2020 Stalwart Labs LLC <hello@stalw.art>
3 *
4 * SPDX-License-Identifier: Apache-2.0 OR MIT
5 */
6
7use super::{ChainBinding, MessageInstance, Signature, SignatureValue};
8use crate::common::headers::{HeaderFolder, HeaderWriter, Writer};
9use mail_builder::encoders::base64::base64_encode_mime;
10use std::{
11    fmt::{Display, Formatter},
12    io::Write,
13};
14
15struct Base64Writer<'x, W: Writer> {
16    inner: &'x mut W,
17}
18
19impl<'x, W: Writer> Write for Base64Writer<'x, W> {
20    fn write(&mut self, buf: &[u8]) -> std::io::Result<usize> {
21        self.inner.write(buf);
22        Ok(buf.len())
23    }
24
25    fn flush(&mut self) -> std::io::Result<()> {
26        Ok(())
27    }
28}
29
30fn write_base64(writer: &mut impl Writer, bytes: &[u8]) {
31    let _ = base64_encode_mime(bytes, Base64Writer { inner: writer }, true);
32}
33
34impl SignatureValue {
35    fn write(&self, writer: &mut impl Writer, empty: bool) {
36        writer.write(self.selector.as_bytes());
37        writer.write(b":");
38        writer.write(self.a.name().as_bytes());
39        writer.write(b":");
40        if !empty {
41            write_base64(writer, &self.b);
42        }
43    }
44}
45
46impl Signature {
47    pub(super) fn write_value(&self, writer: &mut impl Writer, empty_signature: bool) {
48        writer.write(b"i=");
49        writer.write(self.i.to_string().as_bytes());
50        writer.write(b"; m=");
51        writer.write(self.m.to_string().as_bytes());
52        writer.write(b"; t=");
53        writer.write(self.t.to_string().as_bytes());
54        writer.write(b"; d=");
55        writer.write(self.d.as_bytes());
56        writer.write(b"; ");
57
58        match &self.chain {
59            ChainBinding::Envelope { mail_from, rcpt_to } => {
60                writer.write(b"mf=");
61                write_base64(writer, mail_from.as_bytes());
62                writer.write(b"; rt=");
63                for (pos, rcpt) in rcpt_to.iter().enumerate() {
64                    if pos > 0 {
65                        writer.write(b",");
66                    }
67                    write_base64(writer, rcpt.as_bytes());
68                }
69            }
70            ChainBinding::NextDomain(domain) => {
71                writer.write(b"nd=");
72                writer.write(domain.as_bytes());
73            }
74        }
75
76        writer.write(b"; s=");
77        for (pos, value) in self.s.iter().enumerate() {
78            if pos > 0 {
79                writer.write(b",");
80            }
81            value.write(writer, empty_signature);
82        }
83        writer.write(b";");
84
85        if let Some(nonce) = &self.n {
86            writer.write(b" n=");
87            writer.write(nonce.as_bytes());
88            writer.write(b";");
89        }
90
91        if !self.flags.is_empty() {
92            writer.write(b" f=");
93            for (pos, flag) in self.flags.iter().enumerate() {
94                if pos > 0 {
95                    writer.write(b",");
96                }
97                writer.write(flag.as_bytes());
98            }
99            writer.write(b";");
100        }
101    }
102
103    pub fn write(&self, writer: &mut impl Writer) {
104        writer.write(b"DKIM2-Signature: ");
105        self.write_value(writer, false);
106        writer.write(b"\r\n");
107    }
108}
109
110impl MessageInstance {
111    pub(super) fn write_value(&self, writer: &mut impl Writer) {
112        writer.write(b"m=");
113        writer.write(self.m.to_string().as_bytes());
114        writer.write(b"; h=");
115        for (pos, hash) in self.hashes.iter().enumerate() {
116            if pos > 0 {
117                writer.write(b",");
118            }
119            writer.write(hash.name.map(|n| n.name().as_bytes()).unwrap_or(b""));
120            writer.write(b":");
121            write_base64(writer, &hash.header_hash);
122            writer.write(b":");
123            write_base64(writer, &hash.body_hash);
124        }
125
126        if let Some(recipe) = &self.recipe {
127            let mut json = Vec::new();
128            if recipe.to_json(&mut json).is_ok() {
129                writer.write(b"; r=");
130                write_base64(writer, &json);
131            }
132        }
133        writer.write(b";");
134    }
135
136    pub fn write(&self, writer: &mut impl Writer) {
137        writer.write(b"Message-Instance: ");
138        self.write_value(writer);
139        writer.write(b"\r\n");
140    }
141}
142
143impl HeaderWriter for Signature {
144    fn write_header(&self, writer: &mut impl Writer) {
145        self.write(&mut HeaderFolder::new(writer));
146    }
147}
148
149impl HeaderWriter for MessageInstance {
150    fn write_header(&self, writer: &mut impl Writer) {
151        self.write(&mut HeaderFolder::new(writer));
152    }
153}
154
155impl Display for Signature {
156    fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
157        let mut buf = Vec::new();
158        self.write_value(&mut buf, false);
159        f.write_str(&String::from_utf8_lossy(&buf))
160    }
161}
162
163impl Display for MessageInstance {
164    fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
165        let mut buf = Vec::new();
166        self.write_value(&mut buf);
167        f.write_str(&String::from_utf8_lossy(&buf))
168    }
169}
170
171#[cfg(test)]
172mod test {
173    use crate::common::crypto::{Algorithm, HashAlgorithm};
174    use crate::common::headers::HeaderWriter;
175    use crate::dkim2::{ChainBinding, Flag, MessageHash, MessageInstance, Signature, SignatureValue};
176
177    const MAX_HEADER_LINE_LEN: usize = 76;
178
179    fn strip_all_ws(bytes: &[u8]) -> Vec<u8> {
180        bytes
181            .iter()
182            .copied()
183            .filter(|c| !matches!(c, b' ' | b'\t' | b'\r' | b'\n'))
184            .collect()
185    }
186
187    // draft-ietf-dkim-dkim2-spec-03 §9.6: the signature canonicalization unfolds
188    // and then deletes ALL whitespace, so a folded header field and its unfolded
189    // form MUST reduce to identical bytes. Also assert no physical line exceeds the
190    // fold limit (excluding the single leading fold tab).
191    fn assert_fold_is_transparent(field_name: &[u8], folded: &[u8], unfolded: &[u8]) {
192        assert!(
193            folded.ends_with(b"\r\n"),
194            "a folded header field must end with CRLF: {:?}",
195            String::from_utf8_lossy(folded)
196        );
197
198        for (n, line) in folded.strip_suffix(b"\r\n").unwrap().split(|&c| c == b'\n').enumerate() {
199            let line = line.strip_suffix(b"\r").unwrap_or(line);
200            let content = line.strip_prefix(b"\t").unwrap_or(line);
201            assert!(
202                content.len() <= MAX_HEADER_LINE_LEN,
203                "{}: line {n} is {} bytes, exceeds {MAX_HEADER_LINE_LEN}: {:?}",
204                String::from_utf8_lossy(field_name),
205                content.len(),
206                String::from_utf8_lossy(content),
207            );
208        }
209
210        for (i, &ch) in folded.iter().enumerate() {
211            if ch == b'\n' && i + 1 < folded.len() {
212                assert!(
213                    i >= 1 && folded[i - 1] == b'\r' && folded.get(i + 1) == Some(&b'\t'),
214                    "every interior LF must be part of a CRLF+TAB fold: {:?}",
215                    String::from_utf8_lossy(folded)
216                );
217            }
218        }
219
220        let mut expected = field_name.to_vec();
221        expected.extend_from_slice(unfolded);
222        assert_eq!(
223            strip_all_ws(folded),
224            strip_all_ws(&expected),
225            "folding changed the whitespace-stripped (signed) bytes of {}",
226            String::from_utf8_lossy(field_name)
227        );
228    }
229
230    fn dump_folded(title: &str, folded: &[u8]) {
231        println!("\n===== {title} ({} bytes) =====", folded.len());
232        for (n, line) in folded.split(|&c| c == b'\n').enumerate() {
233            if line.is_empty() {
234                continue;
235            }
236            let line = line.strip_suffix(b"\r").unwrap_or(line);
237            let content = line.strip_prefix(b"\t").unwrap_or(line);
238            let leader = if line.len() != content.len() { "\\t" } else { "  " };
239            println!(
240                "  line {n:>2} | {:>3} | {leader}{}",
241                content.len(),
242                String::from_utf8_lossy(content)
243            );
244        }
245        println!("----- raw (escaped) -----");
246        println!("  {}", String::from_utf8_lossy(folded).escape_debug());
247    }
248
249    fn value_of<'a>(folded: &'a [u8], field_name: &[u8]) -> &'a [u8] {
250        folded
251            .strip_prefix(field_name)
252            .expect("folded header must start with the field name")
253    }
254
255    fn big_signature() -> Signature {
256        Signature {
257            i: 3,
258            m: 2,
259            t: 1782394336,
260            d: "test.dkim2.eu".to_string(),
261            s: vec![
262                SignatureValue {
263                    selector: "rsa2048".to_string(),
264                    a: Algorithm::RsaSha256,
265                    b: (0u8..=255).cycle().take(256).collect(),
266                },
267                SignatureValue {
268                    selector: "ed25519".to_string(),
269                    a: Algorithm::Ed25519Sha256,
270                    b: (0u8..64).collect(),
271                },
272            ],
273            chain: ChainBinding::Envelope {
274                mail_from: "<sender@test.dkim2.eu>".to_string(),
275                rcpt_to: vec![
276                    "<recipient@example.com>".to_string(),
277                    "<second-recipient@another-example.org>".to_string(),
278                ],
279            },
280            n: Some("banana".to_string()),
281            flags: vec![Flag::Feedback, Flag::DoNotModify],
282        }
283    }
284
285    fn big_instance() -> MessageInstance {
286        MessageInstance {
287            m: 1,
288            hashes: vec![
289                MessageHash {
290                    name: Some(HashAlgorithm::Sha256),
291                    header_hash: (0u8..32).collect(),
292                    body_hash: (32u8..64).collect(),
293                },
294                MessageHash {
295                    name: Some(HashAlgorithm::Sha256),
296                    header_hash: (64u8..96).collect(),
297                    body_hash: (96u8..128).collect(),
298                },
299            ],
300            recipe: None,
301        }
302    }
303
304    #[test]
305    fn signature_write_header_folds_and_round_trips() {
306        let sig = big_signature();
307
308        let mut folded = Vec::new();
309        sig.write_header(&mut folded);
310
311        let mut unfolded = Vec::new();
312        sig.write_value(&mut unfolded, false);
313        unfolded.extend_from_slice(b"\r\n");
314
315        assert!(
316            folded.windows(3).any(|w| w == b"\r\n\t"),
317            "a large signature should have been folded: {:?}",
318            String::from_utf8_lossy(&folded)
319        );
320        dump_folded("DKIM2-Signature (large: rsa2048 + ed25519, 2 recipients)", &folded);
321        assert_fold_is_transparent(b"DKIM2-Signature: ", &folded, &unfolded);
322
323        let value = value_of(&folded, b"DKIM2-Signature: ");
324        assert_eq!(
325            Signature::parse(value).unwrap(),
326            sig,
327            "folded signature must parse back to the original"
328        );
329    }
330
331    #[test]
332    fn message_instance_write_header_folds_and_round_trips() {
333        let instance = big_instance();
334
335        let mut folded = Vec::new();
336        instance.write_header(&mut folded);
337
338        assert!(
339            folded.windows(3).any(|w| w == b"\r\n\t"),
340            "a large message-instance should have been folded: {:?}",
341            String::from_utf8_lossy(&folded)
342        );
343        let mut unfolded = Vec::new();
344        instance.write_value(&mut unfolded);
345        unfolded.extend_from_slice(b"\r\n");
346        dump_folded("Message-Instance (large: 2 sha256 hash sets)", &folded);
347        assert_fold_is_transparent(b"Message-Instance: ", &folded, &unfolded);
348
349        let value = value_of(&folded, b"Message-Instance: ");
350        assert_eq!(
351            MessageInstance::parse(value).unwrap(),
352            instance,
353            "folded message-instance must parse back to the original"
354        );
355    }
356
357    #[test]
358    fn signature_folds_at_every_realistic_size() {
359        for extra_recipients in 0..6 {
360            let mut sig = big_signature();
361            if let ChainBinding::Envelope { rcpt_to, .. } = &mut sig.chain {
362                for n in 0..extra_recipients {
363                    rcpt_to.push(format!("<rcpt-{n}@padding-domain-for-length.example>"));
364                }
365            }
366
367            let mut folded = Vec::new();
368            sig.write_header(&mut folded);
369
370            let mut unfolded = Vec::new();
371            sig.write_value(&mut unfolded, false);
372            unfolded.extend_from_slice(b"\r\n");
373
374            dump_folded(
375                &format!("DKIM2-Signature ({} recipients)", extra_recipients + 2),
376                &folded,
377            );
378            assert_fold_is_transparent(b"DKIM2-Signature: ", &folded, &unfolded);
379            assert_eq!(Signature::parse(value_of(&folded, b"DKIM2-Signature: ")).unwrap(), sig);
380        }
381    }
382
383    fn sample() -> Signature {
384        Signature {
385            i: 2,
386            m: 1,
387            t: 1700000000,
388            d: "example.com".to_string(),
389            s: vec![SignatureValue {
390                selector: "sel".to_string(),
391                a: Algorithm::Ed25519Sha256,
392                b: vec![1, 2, 3, 4],
393            }],
394            chain: ChainBinding::Envelope {
395                mail_from: "<a@example.com>".to_string(),
396                rcpt_to: vec!["<b@example.org>".to_string()],
397            },
398            n: None,
399            flags: Vec::new(),
400        }
401    }
402
403    #[test]
404    fn flags_emitted_in_order() {
405        let mut buf = Vec::new();
406        Signature {
407            flags: vec![Flag::DoNotModify, Flag::FeedHere],
408            ..sample()
409        }
410        .write_value(&mut buf, false);
411        let out = String::from_utf8(buf).unwrap();
412        assert!(out.contains("f=donotmodify,feedhere;"), "{out}");
413    }
414
415    #[test]
416    fn next_domain_emits_nd_and_omits_envelope() {
417        let mut buf = Vec::new();
418        Signature {
419            chain: ChainBinding::NextDomain("relay.example".to_string()),
420            ..sample()
421        }
422        .write_value(&mut buf, false);
423        let out = String::from_utf8(buf).unwrap();
424        assert!(out.contains("nd=relay.example"), "{out}");
425        assert!(!out.contains("mf="), "{out}");
426        assert!(!out.contains("rt="), "{out}");
427    }
428
429    #[test]
430    fn write_then_parse_round_trips() {
431        let sig = sample();
432        let mut buf = Vec::new();
433        sig.write_value(&mut buf, false);
434        assert_eq!(Signature::parse(&buf).unwrap(), sig);
435    }
436}
mail_auth/dkim2/headers.rs

mail_auth/dkim2/
headers.rs
