ec_dkim_sign

March 26, 2020 Contributors

Name

ec_dkim_sign — Sign a message with the DKIM protocol

Synopsis

ec_dkim_sign [ parameters_hash ]

Description

ec_dkim_sign signs the current message with a DKIM signature. By default it uses the configured parameters on the DKIM module configuration stanza. If desired, a hash table of parameter overrides may be passed as the only argument to the Sieve extension. It may contain the following parameters:

Note

This feature requires the DKIM module. See “dkim – DomainKeys Identified Mail Signatures” for more information.

base_domain/signing_domain

Override the default signing domain. These two parameters are synonyms for one another, each will have the same effect.

header_canon

Override the default header canonicalization setting.

body_canon

Override the default body canonicalization setting.

digest

Override the default digest setting.

headerlist

Override the default list of headers to sign.

identity

Override the default signing identity.

selector

Override the default signing selector.

keyfile

Override the default signing key file, which may be parameterized as defined in the “dkim – DomainKeys Identified Mail Signatures” configuration documentation.

keybuf

Override the default signing key. This hash entry must contain the PEM encoded private key to use for signing the messages. This must be a contiguous string, with no line breaks and no white space, without the –BEGIN and –END tags that are found in the key file itself. The format is similar to the format used to store the public key in the DKIM DNS records.

body_length_limit

Override the default body_length_limit setting.

lifetime

**Configuration Change. ** This feature is available starting from Momentum 3.1.

Override the default lifetime setting.

The core_final_validation hook is triggered from the SWAPOUT pool as the last step before journaling the message to spool. Because you are guaranteed that nothing will change the message contents, it is best to execute ec_dkim_sign in the core_final_validation hook. This is important because message modifications that occur after a signature is computed will render the signature invalid. This hook point must run synchronously; doing otherwise will lead to undefined behavior.

Warning

While it is possible to use this function in the data phase, doing so will have a massive impact on performance, as the system would be occupied with signing instead of processing mail, and the throughput would suffer tremendously. However, there can only be one Sieve script bound to the core_final_validation hook. If you want to sign both DKIM and DomainKeys, put your code into the same file.

Set the sieve async option to false when using the core_final_validation_hook otherwise you may experience spool corruption.

Sieve scripts implementing the core_final_validation hook should not modify the message since it may have already been written to the spool.

Find a sample sieve configuration below:

sieve "sieve1" {
  hook "core_final_validation" {
    source = "/path/to/dkim_sign_script.siv"
    async = "false"
  }
}

Documentation for how to execute a Sieve script at a hook point can be found on the “sieve – The Sieve Module” documentation page.

$params = hash_create;
hash_set $params "selector" "myselector";
hash_set $params "signing_domain" "my.signing.domain.com";
ec_dkim_sign $params;