The Halon platform features DKIM (DomainKeys Identified Mail), based on our open source DKIM library. DKIM provides a cryptographic mechanisms to verify the integrity of a message. A DKIM signed message includes a DKIM-Signature header which contains a message signature that is based on public-key cryptography. DKIM uses DNS(SEC) as a carrier to provide the public keys.
The only requirement to deploy DKIM is domain control, since a DNS record needs to be added for each domain.
- Start by creating a private key (RSA 1024 or 2048). You can either add a key statically in the Halon configuration (from the Configuration > Email engine > Certificates and keys page, by adding a new PKI of type "private key" and leaving the "data" field empty) or in an external database which you then query using API calls. This key should be kept private as it is used to protects the integrity of your signature.
- In the outbound DATA flow, either add a static "DKIM delivery" block to the very end of it, or create a script that invokes the DKIMSign function.
- The graphical "DKIM delivery" block have a help function to generate the TXT entry for your DNS server to a subdomain of selector._domainkey.domain (eg. spaceship._domainkey.halon.se).
The selector is a sub-domain/name-space/identifier for the key you currently using, this allows you to rotate keys, but still keep the old once for a while. So when you update the key, you should also update your selector. You can select use whatever selector you want as long as it's a valid domain name. Some people use friendly names like (gamma, spaceship, rocket, piggy) just for the laugh.
The domain defines which domain that guarantees the integrity of the message, depending on your implementation this can be either a domain of your choice (halon.se) or $senderdomain. The simplest approach to deploy DKIM is to use a single domain. The only disadvantage is that it doesn't allow you to deploy (Author Domain Signing Practices) except for that domain. (which this document doesn't cover).
Each domain (possibly $senderdomain) that you sign, should provide the public key in their DNS server. Once done, you should verify that your public key looks valid. On your computer run (with your own values), run in a terminal;
host -t txt spaceship._domainkey.halon.se
or if using Windows;
nslookup set q=txt spaceship._domainkey.halon.se
which should look something like this.
v=DKIM1; k=rsa; p=MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQCocO7k2Nioo2T...
Both headers and envelope from ($senderdomain) can be spoofed by the sender. In a hosted environment you probably want to enforce the DKIM key signing based on a trusted variable such as $saslusername. The example below illustrates how a system that uses external API calls to fetch DKIM keys from a database uses the SASL username as a parameter.
$dkim = api_call("?type=dkim&user=$1&domain=$2", [$saslusername, $senderdomain]);
DKIMSign($dkim["selector"], $dkim["domain"], $dkim["rsakey"]);