Skip to content

rsa_sha256_signer

kumo.dkim.rsa_sha256_signer { PARAMS }

Create a DKIM signer that uses RSA SHA256.

-- Called once the body has been received.
-- For multi-recipient mail, this is called for each recipient.
kumo.on('smtp_server_message_received', function(msg)
  local signer = kumo.dkim.rsa_sha256_signer {
    domain = msg:from_header().domain,
    selector = 'default',
    headers = { 'From', 'To', 'Subject' },
    key = 'example-private-dkim-key.pem',
  }
  msg:dkim_sign(signer)
end)

PARAMS is a lua table that can have the following keys:

domain

Required. The domain for which the mail is being signed.

selector

Required. The selector used for signing

headers

Required. The list of headers which should be signed.

atps

Optional string. Allows setting the Authorized Third-Party signature.

atpsh

Optional string. Set the Authorized Third-Party Signature hashing algorithm.

agent_user_identifier

Optional string. Sets the Agent of User Identifier (AUID) to use for signing.

expiration

Optional number. Sets the number of seconds from now to use for the signature expiration.

body_length

Optional boolean. If true, the body length will be included in the signature.

reporting

Optional boolean. If true, the signature will be marked as requesting reports from the receiver/verifier.

header_canonicalization

Specify the canonicalization method to be used when hashing message headers. Can be one of:

  • "Relaxed" - this is the default
  • "Simple"

body_canonicalization

Specify the canonicalization method to be used when hashing message body. Can be one of:

  • "Relaxed" - this is the default
  • "Simple"

key

Required. Specify the signing key data.

The value is a KeySource.

The key data must be either RSA PEM or a PKCS8 PEM encoded.

local file_signer = kumo.dkim.rsa_sha256_signer {
  domain = msg:from_header().domain,
  selector = 'default',
  headers = { 'From', 'To', 'Subject' },
  key = '/path/to/example-private-dkim-key.pem',
}

Tip

The KeySource page explains how to read from HashiCorp Vault or from an arbitrary source of data.

ttl

Optional number. Specifies the time-to-live (TTL) in KumoMTA's DKIM signer cache. The default is 300 seconds.

Each call to this function with the same parameters is cached for up to the specified TTL in order to avoid the overhead of repeatedly load the key from disk.

Since: Version 2025.03.19-1d3f1f67

The functionality described in this outlined box requires version 2025.03.19-1d3f1f67 of KumoMTA, or a more recent version.

The ttl now supports a duration string like "5 mins"

over_sign

Since: Version 2024.06.10-84e84b89

The functionality described in this outlined box requires version 2024.06.10-84e84b89 of KumoMTA, or a more recent version.

Optional boolean. If true then the list of headers will be adjusted to match the email message being signed so that the message is signed in such a way that a replay attack cannot forge additional headers without invalidating the signature.

The way this works is by counting the number of headers in the message, so if you set:

headers = {'From', 'To', 'Subject'},

and the message had 1 instance each of From and To, but was, for whatever reason, missing the Subject header, it would compute the effective header list as:

headers = {'From', 'From', 'To', 'To', 'Subject'},

In other words, it will compute N as the number of times each of your listed headers are found in the email to be signed, then treat it as though you listed that name N+1 times in your configuration.