Message Hashing (message-hashing) Plugin

This plugin calculates a hash for every attachment in a message (attachment determination done via istream-attachment-extractor code) and a hash for the entire message.

This calculated data is emitted via named events, which can be collected and analyzed as needed.

This plugin captures message saving via any method (LMTP/LDA, doveadm, IMAP APPEND). To restrict to a certain protocol, load the plugin in a protocol block instead of globally.

Settings

message_hashing

Default	hash_method=md5 min_atc_size=1
Value	string

A string of space-separated key=value configuration options.

Supported options:

Key	Default	Type	Description
hash_method	md5	string	The hashing method to use. Must be a recognized Dovecot hashing method (see auth_policy_hash_mech for list of supported methods) or else the plugin will log a warning and be disabled.
min_atc_size	1	unsigned integer	The minimum size of an attachment (in bytes) to be processed; attachments smaller than this will be skipped.

Events

message_hashing_msg_full

If message-hashing plugin is loaded, emitted for every message saved.

Field	Description
duration	Duration of the event (in microseconds)
reason_code	List of reason code strings why the event happened. See event reasons for possible values.
append	If 1, the message was saved via IMAP APPEND.
attachments	The number of attachments processed in this message (attachments with size > min_atc_size).
hash	The calculated hash of the entire message.
size	The size (in bytes) of the entire message.

message_hashing_msg_part

If message-hashing plugin is loaded, emitted for every attachment found when a message is saved.

Field	Description
duration	Duration of the event (in microseconds)
reason_code	List of reason code strings why the event happened. See event reasons for possible values.
append	If 1, the message was saved via IMAP APPEND.
hash	The calculated hash of the attachment.
size	The size (in bytes) of the attachment.

Example Configuration

Note

This plugin requires the notify plugin to be loaded.

mail_plugins = $mail_plugins notify message_hashing

plugin {
  message_hashing = hash_method=md5 min_atc_size=1
}

Debugging

You can view message hashing information in the log by using log_debug:

log_debug = event=message_hashing_msg_full OR event=message_hashing_msg_part

Example output:

Apr 21 19:11:39 imap(3752 foo)<KWoZVYDAEI9/AAAB>: Debug: message-hashing: message part (06a9effc7cb6182578e876d0cce2b617, 7)
Apr 21 19:11:39 imap(3752 foo)<KWoZVYDAEI9/AAAB>: Debug: message-hashing: message part (c9269421e2389c0ca53bcf1854e49182, 8)
Apr 21 19:11:39 imap(3752 foo)<KWoZVYDAEI9/AAAB>: Debug: message-hashing: full message (8e8c6d47004d4e0a99f14d6cd788ee4f, 81)