Files
inbuxa-server/vendor/mail-parser
jcoffey-dev 40054f5d4c Mail parsing: header fields are limited per part and per message
mail-parser kept every header field it read, each a struct of over a
hundred bytes for as little as four bytes of input, and mail-auth kept a
second list of the top-level ones. Anyone who can send to port 25 could
send a message whose 100 MB header block took several gigabytes to parse,
and a few at once could run the server out of memory.

In the vendored mail-parser, a part now keeps at most 10,000 header fields
and a message, with all its parts and nested messages (encoded ones
too), at most 262,144. Fields past either limit are read past and left
out; the raw message keeps them. That covers every place mail is
parsed. Because a mail client reading the raw message would still see
fields the server left out, SMTP DATA refuses with 552 5.3.4 a message
with more than 1,000 header fields in any part (real mail has tens) or
one the parser left fields out of. The headers a DKIM2-signed DSN
returns as text/rfc822-headers, which mail-auth parses on its own, are
looked at only up to 1,000 fields.

Found in a security review.

Test: in crates/email, a part of 50,000 header fields kept all of them;
now it keeps 10,000 and its body is still found, and 100 parts of 5,000
fields or 60 base64-encoded nested messages of 5,000 fields keep at most
262,144 in all. In the SMTP data suite, messages with 1,001 fields at
the top level or in a MIME part are refused with 552 5.3.4. In
crates/smtp, 1,000 fields per part, nested messages included, fit; more,
or a message the parser left fields out of, don't; and a DSN's returned
headers of 1,001 fields aren't parsed for DKIM2.
In the SMTP DMARC suite, the 1,001-field case from the DKIM limits is
now refused with 552 5.3.4 before DKIM is checked.
2026-11-18 07:16:01 -07:00
..

mail-parser

crates.io build docs.rs crates.io

mail-parser is an e-mail parsing library written in Rust that fully conforms to the Internet Message Format standard (RFC 5322), the Multipurpose Internet Mail Extensions (MIME; RFC 2045 - 2049) as well as many other internet messaging RFCs.

It also supports decoding messages in 41 different character sets including obsolete formats such as UTF-7. All Unicode (UTF-*) and single-byte character sets are handled internally by the library while support for legacy multi-byte encodings of Chinese and Japanese languages such as BIG5 or ISO-2022-JP is provided by the optional dependency encoding_rs.

In general, this library abides by the Postel's law or Robustness Principle which states that an implementation must be conservative in its sending behavior and liberal in its receiving behavior. This means that mail-parser will make a best effort to parse non-conformant e-mail messages as long as these do not deviate too much from the standard.

Unlike other e-mail parsing libraries that return nested representations of the different MIME parts in a message, this library conforms to RFC 8621, Section 4.1.4 and provides a more human-friendly representation of the message contents consisting of just text body parts, html body parts and attachments. Additionally, conversion to/from HTML and plain text inline body parts is done automatically when the alternative version is missing.

Performance and memory safety were two important factors while designing mail-parser:

  • Zero-copy: Practically all strings returned by this library are Cow<str> references to the input raw message.
  • High performance Base64 decoding based on Chromium's decoder (the fastest non-SIMD decoder).
  • Fast parsing of message header fields, character set names and HTML entities using perfect hashing.
  • Written in 100% safe Rust with no external dependencies.
  • Every function in the library has been fuzzed and thoroughly tested with MIRI.
  • Battle-tested with millions of real-world e-mail messages dating from 1995 until today.
  • Used in production environments worldwide by Stalwart Mail Server.

Usage Example

    let input = br#"From: Art Vandelay <[email protected]> (Vandelay Industries)
To: "Colleagues": "James Smythe" <[email protected]>; Friends:
    [email protected], =?UTF-8?Q?John_Sm=C3=AEth?= <[email protected]>;
Date: Sat, 20 Nov 2021 14:22:01 -0800
Subject: Why not both importing AND exporting? =?utf-8?b?4pi6?=
Content-Type: multipart/mixed; boundary="festivus";

--festivus
Content-Type: text/html; charset="us-ascii"
Content-Transfer-Encoding: base64

PGh0bWw+PHA+SSB3YXMgdGhpbmtpbmcgYWJvdXQgcXVpdHRpbmcgdGhlICZsZHF1bztle
HBvcnRpbmcmcmRxdW87IHRvIGZvY3VzIGp1c3Qgb24gdGhlICZsZHF1bztpbXBvcnRpbm
cmcmRxdW87LDwvcD48cD5idXQgdGhlbiBJIHRob3VnaHQsIHdoeSBub3QgZG8gYm90aD8
gJiN4MjYzQTs8L3A+PC9odG1sPg==
--festivus
Content-Type: message/rfc822

From: "Cosmo Kramer" <[email protected]>
Subject: Exporting my book about coffee tables
Content-Type: multipart/mixed; boundary="giddyup";

--giddyup
Content-Type: text/plain; charset="utf-16"
Content-Transfer-Encoding: quoted-printable

=FF=FE=0C!5=D8"=DD5=D8)=DD5=D8-=DD =005=D8*=DD5=D8"=DD =005=D8"=
=DD5=D85=DD5=D8-=DD5=D8,=DD5=D8/=DD5=D81=DD =005=D8*=DD5=D86=DD =
=005=D8=1F=DD5=D8,=DD5=D8,=DD5=D8(=DD =005=D8-=DD5=D8)=DD5=D8"=
=DD5=D8=1E=DD5=D80=DD5=D8"=DD!=00
--giddyup
Content-Type: image/gif; name*1="about "; name*0="Book ";
              name*2*=utf-8''%e2%98%95 tables.gif
Content-Transfer-Encoding: Base64
Content-Disposition: attachment

R0lGODlhAQABAIAAAAAAAP///yH5BAEAAAAALAAAAAABAAEAAAIBRAA7
--giddyup--
--festivus--
"#;

    let message = MessageParser::default().parse(input).unwrap();

    // Parses addresses (including comments), lists and groups
    assert_eq!(
        message.from().unwrap().first().unwrap(),
        &Addr::new(
            "Art Vandelay (Vandelay Industries)".into(),
            "[email protected]"
        )
    );

    assert_eq!(
        message.to().unwrap().as_group().unwrap(),
        &[
            Group::new(
                "Colleagues",
                vec![Addr::new("James Smythe".into(), "[email protected]")]
            ),
            Group::new(
                "Friends",
                vec![
                    Addr::new(None, "[email protected]"),
                    Addr::new("John Smîth".into(), "[email protected]"),
                ]
            )
        ]
    );

    assert_eq!(
        message.date().unwrap().to_rfc3339(),
        "2021-11-20T14:22:01-08:00"
    );

    // RFC2047 support for encoded text in message readers
    assert_eq!(
        message.subject().unwrap(),
        "Why not both importing AND exporting? ☺"
    );

    // HTML and text body parts are returned conforming to RFC8621, Section 4.1.4
    assert_eq!(
        message.body_html(0).unwrap(),
        concat!(
            "<html><p>I was thinking about quitting the &ldquo;exporting&rdquo; to ",
            "focus just on the &ldquo;importing&rdquo;,</p><p>but then I thought,",
            " why not do both? &#x263A;</p></html>"
        )
    );

    // HTML parts are converted to plain text (and viceversa) when missing
    assert_eq!(
        message.body_text(0).unwrap(),
        concat!(
            "I was thinking about quitting the “exporting” to focus just on the",
            " “importing”,\nbut then I thought, why not do both? ☺\n"
        )
    );

    // Supports nested messages as well as multipart/digest
    let nested_message = message
        .attachment(0)
        .unwrap()
        .message();
        .unwrap();

    assert_eq!(
        nested_message.subject().unwrap(),
        "Exporting my book about coffee tables"
    );

    // Handles UTF-* as well as many legacy encodings
    assert_eq!(
        nested_message.body_text(0).unwrap(),
        "ℌ𝔢𝔩𝔭 𝔪𝔢 𝔢𝔵𝔭𝔬𝔯𝔱 𝔪𝔶 𝔟𝔬𝔬𝔨 𝔭𝔩𝔢𝔞𝔰𝔢!"
    );
    assert_eq!(
        nested_message.body_html(0).unwrap(),
        "<html><body>ℌ𝔢𝔩𝔭 𝔪𝔢 𝔢𝔵𝔭𝔬𝔯𝔱 𝔪𝔶 𝔟𝔬𝔬𝔨 𝔭𝔩𝔢𝔞𝔰𝔢!</body></html>"
    );

    let nested_attachment = nested_message.attachment(0).unwrap();

    assert_eq!(nested_attachment.len(), 42);

    // Full RFC2231 support for continuations and character sets
    assert_eq!(
        nested_attachment.attachment_name().unwrap(),
        "Book about ☕ tables.gif"
    );

    // Integrates with Serde
    println!("{}", serde_json::to_string_pretty(&message).unwrap());

More examples available under the examples directory. Please note that this library does not support building e-mail messages as this functionality is provided separately by the mail-builder crate.

Testing, Fuzzing & Benchmarking

To run the testsuite:

 $ cargo test --all-features

or, to run the testsuite with MIRI:

 $ cargo +nightly miri test --all-features

To fuzz the library with cargo-fuzz:

 $ cargo +nightly fuzz run mail_parser

and, to run the benchmarks:

 $ cargo +nightly bench --all-features

Conformed RFCs

Supported Character Sets

  • UTF-8
  • UTF-16, UTF-16BE, UTF-16LE
  • UTF-7
  • US-ASCII
  • ISO-8859-1
  • ISO-8859-2
  • ISO-8859-3
  • ISO-8859-4
  • ISO-8859-5
  • ISO-8859-6
  • ISO-8859-7
  • ISO-8859-8
  • ISO-8859-9
  • ISO-8859-10
  • ISO-8859-13
  • ISO-8859-14
  • ISO-8859-15
  • ISO-8859-16
  • CP1250
  • CP1251
  • CP1252
  • CP1253
  • CP1254
  • CP1255
  • CP1256
  • CP1257
  • CP1258
  • KOI8-R
  • KOI8_U
  • MACINTOSH
  • IBM850
  • TIS-620

Supported character sets via the optional dependency encoding_rs:

  • SHIFT_JIS
  • BIG5
  • EUC-JP
  • EUC-KR
  • GB18030
  • GBK
  • ISO-2022-JP
  • WINDOWS-874
  • IBM-866

License

Licensed under either of

at your option.

Copyright (C) 2020, Stalwart Labs LLC