dkim – DomainKeys Identified Mail Signatures

dkim_validate "dkim_validate1" {
}

# mkdir -p /opt/msys/ecelerity/etc/conf/dkim/example.com
# openssl genrsa -out /opt/msys/ecelerity/etc/conf/dkim/example.com/dkim1024.key 1024
# openssl rsa -in /opt/msys/ecelerity/etc/conf/dkim/example.com/dkim1024.key \
        -out /opt/msys/ecelerity/etc/conf/dkim/example.com/dkim1024.pub -pubout -outform PEM

-----BEGIN PUBLIC KEY-----
MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQCrZXNwzXOk0mRqPcgSUOnmVHro
rg/BZHybpiBoDS/g6IaMjmVwaQf2E72x9yDBTgiUBtTCqydQRZJ3EbfYfvo+WAHq
2yz6HKR0XCwMDSE2S3brVe7mbV/GPEvnCuFPPEVjbfL4w0tEAd8Seb5h07uVQqy1
Q7jIOnF5fG9AQNd1UQIDAQAB
-----END PUBLIC KEY-----

dkim1024._domainkey.example.com. 86400 IN TXT
"v=DKIM1; k=rsa; h=sha256; t=y; p=MHww...QAB"

v=

DKIM key record version. The value of this tag must be set to "DKIM1".

k=

Key type. This tag defines the syntax and semantics of the p= tag value. Currently this tag should have the value "rsa".

h=

Hash algorithm. Currently this tag should have the value "sha1" or "sha256".

t=

Flags. The only value currently defined is "y". If specified this tag indicates the signing domain is testing DKIM.

p=

The DKIM public key value generated as described above.

g=

**Configuration Change. ** In line with RFC 6376, this tag has been deprecated.

Granularity of the key. The intent of this tag is to constrain which signing address can legitimately use the selector for this key. If this tag is specified, the local part of an email's signing address must match the value of this tag or verification will fail. If this tag is not specified only the domain part of the signing address will be used during verification. If an empty value (i.e. "g=") is specified, no signing address will be able to use this key.

s=

Service Type. If specified, this tag should be set to "*" or "email" which represents all service types or the email service type. Currently "email" is the only service using this key.

n=

Notes. If specified, the value of this tag is quoted-printable text used as a note to anyone reading the DNS text record. The tag is not interpreted by DKIM verification and should be used sparingly because of space limitations of the DNS text record.

dkim_sign "dkim_sign1"{
  sign_condition = "can_relay"
  digest="rsa-sha256"
  header_canon = "relaxed"
  body_canon = "relaxed"
  headerlist = "From:Subject:Date:To:MIME-Version?:Content-Type?"
  key = "/opt/msys/ecelerity/etc/conf/dkim/%{d}/%{s}.key"
  dk_domain "example.com" {
    selector = "dkim1024"
  }
  dk_domain "example2.com" {
    selector = "s1024"
  }
}

base_domain

base_domain specifies which domain should be used for the signing. DKIM allows for emails to be signed by a parent domain. For example, a mail from test@corp.example.com can be signed in the example.com domain. This option can only appear within the dk_domain scope.

body_canon

Specifies the canonicalization that should be performed on the email body before digesting and signing the message. The two supported canonicalizations are simple and relaxed. Use of relaxed is suggested.

body_length_limit

The body_length_limit option causes the number of message body characters signed to be included in the signature header. Only the number of characters indicated in the signature header will be included in verification at a receiving domain. To include body length limits, the value of this option should be set to "True". The DKIM specification cautions signers to be wary of using this option, as it is subject to potential attacks, such as additional MIME parts and additional HTML content. See section 8.1, "Misuse of Body Length Limits" of the draft specification.

copy_headers

This option causes all of the headers that were selected for signing by headerlist to be quoted-printable encoded and placed in the z= tag of the DKIM-Signature header. This can be useful for debugging.

digest

Specifies the algorithms that should be used to create the message digest and resulting signature. The supported mechanisms are rsa-sha1 and rsa-sha256.

header_canon

Specifies the canonicalization that should be performed on the email headers before digesting and signing the message. The two supported canonicalizations are simple and relaxed. Due to the way MTAs operate, the simple canonicalization is very fragile and prone to failure because of header rewriting and rewrapping. Use of relaxed is suggested.

headerlist

The headerlist configuration directive is required. During digestion DKIM will sign all headers specified in the headerlist in the order they are specified. Although there is no default headerlist, the DKIM specification requires signing the From header and any header field that describes the role of the signer such Sender or Resent-From. The specification also recommends signing, Subject, Date, all MIME header fields and all existing, non-repeatable header fields.

The headerlist itself is a colon separated list of header field names. The characters "?", "*" and "+" are appended to the header field name to specify signing of multiple copies of a header and to assert a non-existent header.

DKIM provides for a signer to sign a non-existent header. This mechanism can be used to prevent the header from being added to the message during transit. If the header is added during transit the DKIM signature will not verify. Using this mechanism the signer asserts that the header was not there when the message was signed.

The headerlist syntax is described below.

*`header_field_name`*

A single copy of the header will be signed. Assert a non-existent header if the header does not exist. If that header is added later, the signature will be invalidated.

*`header_field_name`*?

A single copy of the header will be signed. Do not assert a non-existent header if the header does not exist.

*`header_field_name`**

Sign all existing copies of the header. Assert a non-existent header if the header does not exist.

*`header_field_name`*+

Sign all existing copies of the header. Do not assert a non-existent header if the header does not exist.

Example Headerlist (syntactically correct only):

Received+:X-Example*:From:Subject?:Received

The headerlist shown above will cause the following signing actions:

1. All (multiple) Received headers will be signed

2. All (multiple) X-Example headers will be signed. If no X-Example headers are found a non-existent header is asserted.

3. A single From header will be signed. A non-existent header is asserted if no From header is found.

4. A single Subject header will be signed.

5. A single Received header will be signed. In this case no additional Received headers will be found because of the first "Received+" entry in the headerlist. A non-existent Received header will be asserted prohibiting the addition of any more Received headers during transit.

identity

The identity option can be used to specify a user or agent. A standard email address is specified. This value is used in conjunction with the DKIM DNS Key record's g= tag value where the local part of the identity must match the value of the "g=" tag. Note: Use of the g= tag has been deprecated.

key

This option is required and specifies the location of the RSA private key file on disk. The key file must be readable by the user that Momentum is running as and must be in Privacy Enhanced Mail (PEM) format.

The file name has two expandable variables that may be used to ease deployment over multiple domains: %{d} expands to the responsible domain and %{s} expands to the selector.

keycache_size

The key cache size expressed as the number of keys. The default value is 2048.

lifetime

The lifetime option can be used to specify the length of time a signature remains valid. An expiration value is included in the signature header added to each email message. The lifetime of the signature begins at signing and expires some time later as determined by the lifetime option value. A message will not verify after the signature lifetime has expired. The value of this option is specified in hours.

neg_keycache_ttl

In the event that the key isn't already in the cache, the amount of time in seconds before retrieving it again. The default value is 3600.

pos_keycache_ttl

The total time in seconds for items to stay in the cache before fetching them again. The default value is 300.

selector

This option specifies the DKIM selector to be used for signing. During verification the selector will be used along with the signing domain to retrieve the signing domain's public key. The key retrieved will be contained in the DNS TXT record for {selector}._domainkey.{domain}.

sign_condition

sign_condition specifies which validation context variable must exist as a predicate to signing messages. When an SMTP client performs an SMTP AUTH action, the auth_user context key will be set to the username used during authorization. When an SMTP client is allowed to relay through Momentum because of an entry in Relay_Hosts or a relaying declaration in an ESMTP_Listener IP access control list, the can_relay context key is set to "true."

In most corporate environments, sign_condition should be auth_user and in large sending architectures where the relaying SMTP clients are implicitly trusted the sign_condition should be can_relay.