cfdkim 0.3.0

DKIM (RFC6376) implementation
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136

use crate::{parser, DKIMError};
use indexmap::map::IndexMap;

pub(crate) const HEADER: &str = "DKIM-Signature";
pub(crate) const REQUIRED_TAGS: &[&str] = &["v", "a", "b", "bh", "d", "h", "s"];

#[derive(Debug, Clone)]
pub struct DKIMHeader {
    pub(crate) tags: IndexMap<String, parser::Tag>,
    pub(crate) raw_bytes: String,
}

impl DKIMHeader {
    pub(crate) fn get_tag(&self, name: &str) -> Option<String> {
        self.tags.get(name).map(|v| v.value.clone())
    }

    pub(crate) fn get_raw_tag(&self, name: &str) -> Option<String> {
        self.tags.get(name).map(|v| v.raw_value.clone())
    }

    pub(crate) fn get_required_tag(&self, name: &str) -> String {
        // Required tags are guaranteed by the parser to be present so it's safe
        // to assert and unwrap.
        debug_assert!(REQUIRED_TAGS.contains(&name));
        self.tags.get(name).unwrap().value.clone()
    }
}

/// Generate the DKIM-Signature header from the tags
fn serialize(header: DKIMHeader) -> String {
    let mut out = "".to_owned();

    for (key, tag) in &header.tags {
        out += &format!("{}={};", key, tag.value);
        out += " ";
    }

    out.pop(); // remove trailing whitespace
    out
}

#[derive(Clone)]
pub(crate) struct DKIMHeaderBuilder {
    header: DKIMHeader,
    time: Option<chrono::DateTime<chrono::offset::Utc>>,
}
impl DKIMHeaderBuilder {
    pub(crate) fn new() -> Self {
        DKIMHeaderBuilder {
            header: DKIMHeader {
                tags: IndexMap::new(),
                raw_bytes: "".to_owned(),
            },
            time: None,
        }
    }

    pub(crate) fn add_tag(mut self, name: &str, value: &str) -> Self {
        let tag = parser::Tag {
            name: name.to_owned(),
            value: value.to_owned(),
            raw_value: value.to_owned(),
        };
        self.header.tags.insert(name.to_owned(), tag);

        self
    }

    pub(crate) fn set_signed_headers(self, headers: &[&str]) -> Self {
        let headers: Vec<String> = headers.iter().map(|h| h.to_lowercase()).collect();
        let value = headers.join(":");
        self.add_tag("h", &value)
    }

    pub(crate) fn set_expiry(self, duration: chrono::Duration) -> Result<Self, DKIMError> {
        let time = self
            .time
            .ok_or(DKIMError::BuilderError("missing require time"))?;
        let expiry = (time + duration).timestamp();
        Ok(self.add_tag("x", &expiry.to_string()))
    }

    pub(crate) fn set_time(mut self, time: chrono::DateTime<chrono::offset::Utc>) -> Self {
        self.time = Some(time);
        self.add_tag("t", &time.timestamp().to_string())
    }

    pub(crate) fn build(mut self) -> Result<DKIMHeader, DKIMError> {
        self.header.raw_bytes = serialize(self.header.clone());
        Ok(self.header)
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_dkim_header_builder() {
        let header = DKIMHeaderBuilder::new()
            .add_tag("v", "1")
            .add_tag("a", "something")
            .build()
            .unwrap();
        assert_eq!(header.raw_bytes, "v=1; a=something;".to_owned());
    }

    #[test]
    fn test_dkim_header_builder_signed_headers() {
        let header = DKIMHeaderBuilder::new()
            .add_tag("v", "2")
            .set_signed_headers(&["header1", "header2", "header3"])
            .build()
            .unwrap();
        assert_eq!(
            header.raw_bytes,
            "v=2; h=header1:header2:header3;".to_owned()
        );
    }

    #[test]
    fn test_dkim_header_builder_time() {
        use chrono::TimeZone;

        let time = chrono::Utc.with_ymd_and_hms(2021, 1, 1, 0, 0, 1).unwrap();

        let header = DKIMHeaderBuilder::new()
            .set_time(time)
            .set_expiry(chrono::Duration::hours(3))
            .unwrap()
            .build()
            .unwrap();
        assert_eq!(header.raw_bytes, "t=1609459201; x=1609470001;".to_owned());
    }
}