Configuring DKIM signing for messages routed to external Internet domains

Domino can use Domain Keys Identified Mail (DKIM) to sign messages sent by internal users to external Internet domains.

When an external SMTP MTA receives a DKIM signed message, it uses the DKIM signature to verify that specific content and headers on the message have not been modified since DKIM signing. The DKIM signature takes the form of a DKIM-Signature header that the Domino router prepends to the message on an SMTP hop. The DKIM-Signature header contains information that the external MTA can use to verify the message content using the signature data and a public key acquired via DNS. For details on DKIM siging, see RFC6376.

To sign messages using DKIM, Domino uses key pairs that you create with the keymgmt command. The command creates a document in a credential store that includes Internet domain and selector items. These items allow the Domino router to find the correct private key to use to generate the DKIM signature.

To use DKIM to sign messages being routed to the Internet, configure DKIM on the Domino servers on the edge of your Domino environment that use SMTP to transfer mail to the internet.

The requirements for DKIM signing are:
  • Domino V12.0.1 SMTP server on Linux 64 or Windows 64.
  • A credential store for storing DKIM keys on each Domino SMTP that uses DKIM signing. For information on creating a credential store if you don't already use one, see Using a credential store to store credentials. If your SMTP servers already have a credential store, ensure the credential store is using the V12.0.1 websecuritystore.ntf template.
  • A public DNS TXT record for each key used for DKIM signing. You use a keymgmt command to generate the contents of the DNS TXT record, as described in this procedure. Your DNS provider can provide instructions for adding this record to your DNS domain settings.
The steps to configure DKIM signing are:
  1. Create DKIM signing keys in the credential store.
  2. Create a DNS TXT record that contains the key and add it to your DNS domain settings.
  3. Specify the key(s) to use for DKIM signing (through notes.ini) on the server.
  4. Enable DKIM signing (through notes.ini) on the server.

Create DKIM signing keys

Create one or more keypairs in a credential store to use for DKIM signing. To create a DKIM signing keypair in a document in the credential store, run the following command from the console of a Domino server that has the credential store:
keymgmt create DKIM <domain> <selector> RSA [<keySize>]
where:
  • <domain> is the name of the Domino Internet domain, for example, renovations.com or sales.renovations.com.
  • <selector> is the name of your choice for the DKIM selector. The selector is specified in the DKIM-Signature header and indicates where the public key portion of the DKIM keypair exists in DNS.
  • <keySize> is the specified size for the DKIM key. Size can be 1024, 2048 or 4096.
For example: 
keymgmt create DKIM renovations.com 12345 RSA 2048
A console message similar to the following one indicates the command is successful:
> keymgmt create DKIM renovations.com 12345 RSA 2048
[4F24:0007-2F28] Created DKIM key 12345._domainkey.renovations.com
Note: A DKIM key is enabled by specifying the domain and selector in a server notes.ini setting. 255 characters are the maximum allowed for notes.ini settings which puts a practical limit on domain and selector sizes.

Create a DNS TXT record in a .txt file

After you create the DKIM signing keys in the credential store, run the following command to create a .txt file in the Domino data directory that contains the contents of a DNS TXT record for the specified key:
keymgmt export DKIM DNS <domain> <selector> <dkimdnsfile>
where:
  • <domain> is the name of the Domino Internet domain that you specified for the key.
  • <selector> is the DKIM selector you specified for the key.
  • <dkimdnsfile> is the name of the .txt file to create in the Domino data directory that contains the DNS TXT record.
For example: 
keymgmt export DKIM DNS renovations.com 12345 dkimdns.txt

This command creates the file dkimdns.txt which in this case contains information to use as the contents of a DNS TXT record for 12345._domainkey.renovations.com. Use the information in the file you create for your DKIM signing keys to add the TXT record for your DKIM signing keys to your DNS domain settings. The DNS entry name must be in the form <selector>._domainkey.<domain>, where <selector> and <domain> are as you specified when creating the key and generating the file.

Specify keys to use for DKIM signing

After you add a DNS TXT record for the keys to use for DKIM signing to your DNS domain settings, use the notes.ini setting DKIM_KEY on a Domino SMTP server to map a domain to a key to use for DKIM signing. The following table describes various options for this setting. If the router is running, restart it for the changes to take effect.
Example setting Description Example
DKIM_KEY_<domain>=<selector> When users send messages from the specified domain or any of its subdomains, the server signs the messages with the key that corresponds to the specified selector. DKIM_KEY_renovations.com=09262021
DKIM_KEY_<subdomain>=<selector> When users send messages from the specified subdomain, the server signs the messages with the key that corresponds to the specified selector. DKIM_KEY_sales.renovations.com=sales4321
DKIM_KEY_<domain>=<selector>,<selector> When users send messages from the specified domain, signs the messages with both of the keys specified by two selectors.
This scenario is useful for:
  • Allowing signing by both old and new keys during key rollover transition while a new key propagates to DNS.
  • Using multiple signing algorithms.
 DKIM_KEY_renovations.com=09262021,10042021
DKIM_KEY_<aliasdomain>=<domain>;<selector> When users send messages from an alias domain (a domain that is not the primary domain), the messages are signed with the key that corresponds to the selector for the primary domain. DKIM_KEY_aliasrenovations.com=renovations.com;09262021

Enable DKIM signing

After you configure the DKIM_KEY settings to map a domain to a key, specify the following additional setting to enable DKIM signing. You can enable or disable DKIM signing while the router is running and no router restart is required. 
RouterDKIMSigning=<value>
where <value> is one of the following values:
  • 1 This option makes a best effort to sign a message if a signing key is specified for the senders domain. If a signing error occurs, an error is logged but the message is delivered unsigned.
  • 2 This option enforces DKIM signing. If a signing key is specified for the senders domain and a signing error occurs, the error is logged and the message isn't send. The sending user receives a non-delivery report.