Updated -- May 2024
Citadel now natively supports signing all outgoing mail with a DKIM (DomainKey) signature. it does not cover verification of incoming mail. It is recommended to use SpamAssassin for that purpose -- which is easy to attach to Citadel.
Starting with version 1000 of Citadel Server -- a nice round number, purely by chance -- signing outgoing email with DKIM is extremely easy. The server setup is, in fact, completely automatic; you need only create the DKIM record in your domain's DNS.
Warning: An improper DKIM/Domainkey setup can cause mail from your site being rejected or tagged as spam. http://www.dkim.org has a lot of information.
The first time you start your Citadel Server (or the first time after you upgrade to a supported version), a 2048-bit RSA private key and a DKIM selector will be automatically generated for you. You will not be shown the key unless you dig for it in your configuration database. It's not important. What is important will appear in the Aide room. The helpful Citadel Aide will automatically post a message for you, the administrator, that looks something like this:
Subject: Confirm your DKIM records
Your domain configuration may have changed.
To allow the DKIM signatures of outbound mail to be verified,
please ensure that the following DNS records are created:
Host name : bxqiq._domainkey.bigbuttbear.com
Record type: TXT
Value : v=DKIM1;k=rsa;p=MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEArLjizZqrXRK19VmsrlgAip831eCSDzVQ0tdg+1Jx6sNVEx0IkADj7T6aC4637k0HOBr8G7Oa6sw9iVpEDNg3QvJFBBoTA9kkmVo0N3Xc5ltvVUsNT1iv6BTn90i55+SwWufQ+Oa9iGKvSnx5Uoev0xulOTCiDbdF1AIj5Uiu8Q//DGpXHitkF7FXWu7n8ivxp0iajXd+wfqp0s+qxcEHWxCO3TOdOUClx2g1P5DdlXWxpf8KIZIkcIHXv2FCRQsK6np0Xiv/X77Fi1TwTjmNLL0MoHnGW5PP0XYedP+DG5hw7Iw8yzOciUmBRa3DGKYDUz0f1rKqtylRxCUjSUyC/wIDAQAB
Host name : bxqiq._domainkey.citadel.org
Record type: TXT
Value : v=DKIM1;k=rsa;p=MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEArLjizZqrXRK19VmsrlgAip831eCSDzVQ0tdg+1Jx6sNVEx0IkADj7T6aC4637k0HOBr8G7Oa6sw9iVpEDNg3QvJFBBoTA9kkmVo0N3Xc5ltvVUsNT1iv6BTn90i55+SwWufQ+Oa9iGKvSnx5Uoev0xulOTCiDbdF1AIj5Uiu8Q//DGpXHitkF7FXWu7n8ivxp0iajXd+wfqp0s+qxcEHWxCO3TOdOUClx2g1P5DdlXWxpf8KIZIkcIHXv2FCRQsK6np0Xiv/X77Fi1TwTjmNLL0MoHnGW5PP0XYedP+DG5hw7Iw8yzOciUmBRa3DGKYDUz0f1rKqtylRxCUjSUyC/wIDAQAB
Those are the TXT records you need to publish in your DNS to make DKIM work. You should definitely configure your DNS with those records immediately. As soon as the DNS is published, email recipients will be able to validate your outgoing email against the digital signatures automatically attached by Citadel to each message.
Note that any time you add, change, or remove email domains on your Citadel Server, the Citadel Aide will post an updated copy of that message. That's when you can add, remove, or verify your DKIM records for those domains. Normally you'll never have to change a working record -- Citadel will never change the private key on its own.
WARNING: If you are configuring your DNS via a web interface you may have to leave out the quotation marks. Test this carefully as wrong quotes may cause a wrong TXT entry or mess up your entire zone configuration!
If you prefer to begin in a test mode, it is advisable to create a second TXT record to create a DKIM policy:
_domainkey IN TXT "o=-; t=y"
This entry tells the testing server that this site is signing all messages, but that it is still in testing mode. You can remove the t=y once you are VERY VERY sure that your setup works. DO NOT CHANGE IT TO t=n !
Changing o=- to o=~ tells the server that not all messages coming from this site are signed.It may take up to two days for your DNS setup to be propagated through the internet. You can check the DNS records with the following Linux command lines:
host -t TXT selector1._domainkey.yourcitadelmaildomain.org should return the key record
host -t TXT _domainkey.yourcitadelmaildomain.org should return the policy record
Send a test message from Citadel to an outside email address and check that the message source contains DKIM and Domainkey - headers. Once that works you can try one of the reflectors on https://dkimvalidator.com/ to see if your message passes their test.
Google mail is verifying Domainkeys and DKIM as well. You can send a message to a GMail account and select "View Original Message". It will display pass/fail for all of the digital signature options.
If you've launched in testing mode, now switch your DKIM setup out of testing mode by removing the t=y entry from DNS.
Have a cup and enjoy your Citadel system!