Email sender spoofing is the act of pretending to be in control of someone else’s email address. This is a common problem with phishing. Often scammers send emails with a sender address of something@paypal.com and hope that the recipient falls for it and trusts them. In fact SMTP does not care which sender address you send. Many mail service providers enforce that you send emails only using your own email address. But some do not. And spammer and scammers obviously could not care less.
So a new method was conceived that added a cryptographic signature to the header of an email that the recipient could check to verify the authenticity of the sender and the integrity of the email. The signature is created using a private key that only the sending mail server has. It can then be verified by the recipient by downloading the corresponding public key from the DNS zone of the sending domain and running a signature check. This works very similar to PGP or S/MIME signing – just on a domain level. Your mail server can sign all outgoing emails automatically. The method used nowadays is called Domain Keys Identified Mail – or short: DKIM.
Let’s take an example. I have just sent an email from GMail to my personal email account on my own mail server. Google uses DKIM signing so the email got this additional header from Google’s mail servers:
DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025; h=mime-version:from:date:message-id:subject:to; bh=/FpkZfBuKR0WWcH2fFcr9M4qgX4Z4+/0dX4dpqycK28=; b=fZ4Efy1TuXAl1ho2twkEuNiVP8k5GRKqlol/f/dTawaxciAv1bwinkbu…
I need Google’s DKIM public key to verify that signature. It is stored in their DNS zone as a TXT record of “20161025._domainkey.google.com”. The “20161025” is the key selector that is mentioned in the signature as “s=20161025“. You can use any number of keys as long as you create the signatures with the matching private key. The “_domainkey” part is the standard subdomain for DKIM keys. So let’s get that TXT record:
dig +short 20161025._domainkey.google.com txt
This returns…
"k=rsa; p=MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAwXNZF1j8sJPDleRjf9SPBNem0ik58kF1ilC1nUgKAttl9v7FX9hXJXPmLNhVtSKVZ8yruaeOZLeIxtgtk1s81zzIE5Mj0AiGn2wlFt4kYfqlDfYe95YLQHjynu4i7vj1Tj" "ksf62btcCbL+3XhbK+oD5PlqYhXHWuzoKoEp5L4lCihgkONvU/oy7NNeE6quqfF/y0YSLwF2WVA2Kd8L6R0Ar2dYT/3wZCFknI7xhvPqh9HNcIWBELGPwtXcsHbX1wvBlCgNQAUcdJrf2YWzAwqmZ564/1ipL1IMk1nafPJk75ktumVNz6ORuIn3jbZWp9rRpnaeI9cu/8KfSKH2EY9QIDAQAB"
That is the public key that I can use to verify the signature. An automated check can be done using the “opendkim-testmsg” tool as described later. I can run it and paste the entire email including headers and body into it. If it doesn’t complain with an error message then the signature is correct.
Sounds good? Then let’s implement that for your email domain, too.
Creating a keypair
As explained above you need a private key that your mail server will use and a public key that gets added to your DNS zone. rspamd can create DKIM keys already. You may want to install “dig” though which allows to query DNS records. It works like “nslookup” but is more versatile.
apt install dnsutils
rspamd has its built-in DKIM signing module enabled by default. If you put your key file into /var/lib/rspamd/dkim/ using a certain naming scheme it will pick it up automatically. Create that directory to store keys in:
mkdir /var/lib/rspamd/dkim chown _rspamd:_rspamd /var/lib/rspamd/dkim
Create your keypair:
rspamadm dkim_keygen -d example.org -s 2019122401
The selector (-s) I chose is 2019122401 because that’s the day I created it. The first (01) key on 2019-12-24. It doesn’t matter though – you can name it anything you want. If you are lazy and unconcerned you could even use “dkim” as the selector and later spare some work by not needing DKIM maps that define which key is supposed to be used for each domain. “dkim” is the default selector if you do not use maps. However if you need to replace your key later without invalidating previously sent emails you are in trouble. So I recommend you rather use maps as explained further below. It gives you more flexibility and is pretty easy to do.
The output will look like this:
-----BEGIN PRIVATE KEY----- MIICdwIBADANBgkqhkiG9w0BAQE… -----END PRIVATE KEY----- 2019122401._domainkey IN TXT ( "v=DKIM1; k=rsa; " "p=MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQCZ8e4RtsvuvsgXyo3Jr63twdx3Zm2RtnYPf87wba5ZnFP0sQIagjJ0R3WL+djKhM5EteBeboTeaflLR+AUKWJdQnL5jzGil+yWThH5C+ixhkdFZPdabkxBji+3r6uRxJKBsN0gy2/+Gp4sGs7lmFgioki9OLgQnzzFh2nE/MSACwIDAQAB" ) ;
The first part is the private key. And that includes the “…BEGIN…” and “…END…” lines. This key must be kept secret and will only be used by your mail server to sign outgoing emails.
The second part is the DNS record you need to add to your domain’s DNS zone. Let’s start with that.
Adding the DNS record
Before you start signing your emails you must make sure that the public key is properly present in your DNS zone for the domain you are sending emails from. Otherwise the recipient will be unable to verify the signature and may incorrectly assume that the email was spoofed.
Take a look at the TXT record. It will look something like this:
2019122401._domainkey IN TXT ( "v=DKIM1; h=sha256; k=rsa; " "p=MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQCxenHupkYLPmFMbJjV9dQICKUl2xH/aexSRUwCuw7TJ9dkddqIN+6tyw4VKhnW8R0/UlbzlSFLmVgMU0uUkwTtVqyDHhtSU7LV/SkVYmUst4dTUF1r+8PvhAm7vobMYKdwvRsOq27ABtZc8P4oU2XXHqqa6LU8s4sNxs12hLW9swIDAQAB" ) ;
If you are running your own DNS server you should be able to copy this entire file and put it into your DNS zone. However if your internet provider offers you just a web interface to manage your domains then create a new TXT record with a host name of “2018022301._domainkey” in your domain and put the string within the double-quotes into it as the value. In my example:
2019122401._domainkey ➠p=MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQCxenHupkYLPmFMbJjV9dQICKUl2xH/aexSRUwCuw7TJ9dkddqIN+6tyw4VKhnW8R0/UlbzlSFLmVgMU0uUkwTtVqyDHhtSU7LV/SkVYmUst4dTUF1r+8PvhAm7vobMYKdwvRsOq27ABtZc8P4oU2XXHqqa6LU8s4sNxs12hLW9swIDAQAB
Be aware that the string you got contains two strings “…” + “…” that must be merged into one to work. There must usually not be any quotes in the record data. Depending on your ISP it may take a while until the new record is visible on the internet. You can use dig to verify that:
dig +trace 2019122401._domainkey.example.org txt
If you get the TXT entry like as follows then you are ready to enable DKIM signing in rspamd for that domain:
TXT "p=MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQCxenHupkYLPmFMbJjV9dQICKUl2xH/aexSRUwCuw7TJ9dkddqIN+6tyw4VKhnW8R0/UlbzlSFLmVgMU0uUkwTtVqyDHhtSU7LV/SkVYmUst4dTUF1r+8PvhAm7vobMYKdwvRsOq27ABtZc8P4oU2XXHqqa6LU8s4sNxs12hLW9swIDAQAB" "" from server foo.bar in 24 ms.
Enabling DKIM maps in rspamd
As explained above it is advised to use DKIM maps. It’s nothing fancy. Just a simple file defining which selector you want to use for a certain domain. rspamd will assume that your selector is always “dkim” unless specified otherwise in a map. If you used “dkim” then you may get into trouble when you later want to replace your key. DNS is a sluggish system and propagating a new DKIM public key may take a day. Emails signed with a newer key may get rejected while the DNS record is not yet known everywhere in the world.
Using maps is simple. First we need to change the selector_map setting of the dkim_signing module. To do that create a new file in /etc/rspamd/local.d/dkim_signing.conf and make it contain just these two lines:
path = "/var/lib/rspamd/dkim/$domain.$selector.key"; selector_map = "/etc/rspamd/dkim_selectors.map";
The configuration is pretty self-explaining. rspamd will look for the domain-to-key mapping in the dkim_selectors.map file. Create that file and make it contain this line:
example.org 2019122401
That’s all really. rspamd now knows that whenever it sees an outgoing email from anyone@example.org it will get the DKIM private key from /var/lib/rspamd/dkim/example.org.2018022301.key and use it to sign the email.
Reload the configuration:
service rspamd reload
This method works well if you just have a few domains that virtually never change. If you are rather serving random customer domains you should consider putting the keys into a Redis database instead as described in the documentation. There is not yet a way to manage DKIM keys in a database like MySQL.
Adding the domain key to rspamd
Take the private key that was created earlier (the multi-line string including “…BEGIN PRIVATE KEYS…” and “…END PRIVATE KEY…”) and put it into a file at the location where rspamd will look for it:
/var/lib/rspamd/dkim/example.org.2019122401.key
The name of the file has to be DOMAIN + dot + SELECTOR + “.key” like above. If you name the file incorrectly you will get an error in your rspamd.log file like “lua_dkim_sign_handler: cannot load dkim key /var/lib/rspamd/dkim/example.org.dkim.key“.
Make sure that only _rspamd can read it:
chown _rspamd /var/lib/rspamd/dkim/* chmod u=r,go= /var/lib/rspamd/dkim/*
rspamd will automatically pick up the files and does not need to be restarted.
Send a test email
If you have another email account at another location then you could just send a test email there via your mail server. If you take a look at the received email it should have a DKIM header now like:
DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=example.org; s=2019122401; t=1519400838; h=from:subject:date:message-id:to:mime-version:content-type:content-transfer-encoding; bh=kpYel1IlDvqXEUc0SyIpXbMte3XpQOCXHl+zTyHQvGc=; b=NEUyWUoeKE…
To verify the signature install the opendkim-tools package, copy the entire test email (including headers and body), run opendkim-testmsg in your shell and paste the email (finish with CTRL-D).
If you get no output then the signature verified correctly. But if you get something like “opendkim-testmsg: dkim_eom(): Unable to verify” then double-check your DNS record.
You can also use websites like dkimvalidator.com, isnotspam.com or mail-tester.com service to verify that your signatures are working well.
SPF and DMARC
Adding DKIM signatures is a good first step. But you can take it further by telling receiving mail servers that they should not accept any email from your domain without a valid signature or from servers that you do no operate. There are two concepts that aim to help. The older SPF and the newer DMARC. Either of them means creating a machine-readable string in a predefined format and adding a TXT record to your DNS zone. Receiving mail servers can check those records and take your advice (as the domain owner) what to do if the criteria of the email are not met. It could accept the email anyway or flag it as spam or reject it altogether.
Let’s take a look at a typical SPF record:
"v=spf1 ip4:157.97.194.11 mx ~all"
What it means:
- this is an SPF record of version 1 of the standard (there is currently no other version)
- please accept emails from the IP address 157.97.194.11
- alternatively accept emails from any server that is mentioned in our domain’s MX record (the server(s) that receive email for your domain)
- any other email should be considered suspicious – it might be spam or worse
There are websites like SPFwizard that help you create your SPF string to add to your DNS domain. Keep in mind though:
- You should know which mail servers send email from your domain. Do not forget to include mailing list or newsletter services that send in your name.
- Start with “~all” to mark emails as spam that do not meet the criteria. If all goes well switch to “-all” after a few weeks if you like.
- Note that forwarding emails from your domain may break SPF because suddenly the email appears to be coming from an IP address that is not authorized. This has been a common problem for mailing lists and is gradually being fixed by resending the email from the domain of the mailing list service.
I mentioned that DMARC is the newer standard. So why use SPF anyway? Because some email providers value your effort if you use SPF, too. Technically it’s sufficient to specify a DMARC entry. In my opinion restricting the IP addresses allowed to send is a little dangerous and a little inflexible. It is far more interesting to require that emails from your domain have a valid DKIM signature. Such a record may roughly look like:
"v=DMARC1; p=reject; adkim=s"
However to create a proper DMARC entry I suggest you use one of the web sites that aid you there and explain the restrictions and extra features.
Hey,
when I try to send a mail via mail client “thunderbird” there is no dkim headers attached. 🙁
Here is some more Information.
When I use mutt on my server directly the dkim header get attached to the email.
When I use thunderbird from a client and send a mail there is no dkim header attached.
I’ve no clue what I need to do to fix this. Hope somebody can help me with this. 🙂
Strangely I see a similar behavior on my test system. After enabling debugging rspamd tells me: “arc; lua_dkim_tools.lua:104: ignoring unauthenticated mail”. I’m now trying to find out how rspamd determines if a user is “authenticated”.
Okay, I had a stupid typo in my configuration and accidentally set “-o smtpd_milters=” for the submission service in Postfix’s master.cf.
Could you grep for “dkim” in your /var/log/rspamd/rspamd.log?
Do you authenticate from Thunderbird and send from another system (not localhost or a private IP address over VPN?)
Hey Christoph,
but the “-o smtpd_milters=” should be set when you don’t want to send outgoing mails trough rspamd.
You explained the use in chapter “Filtering out spam with rspamd”.
Also to answer your question about the use of thunderbird.
I authenticate from Thunderbird which is on a VM in my network. The mailserver is hosted at a webhoster.
rspamd figures out whether an email is sent out and behaves differently. For example it doesn’t check DKIM signatures but rather creates a new one. So I strongly recommend using rspamd even for outgoing emails. So what I wrote was wrong and I’ll remove that right away.
When I don’t use the “-o smtpd_milters=” DKIM works over thunderbird.
but the “-o smtpd_milters=” should be set when you don’t want to send outgoing mails trough rspamd for check.
You explained the use in chapter “Filtering out spam with rspamd”.
I have several app & database servers in addition to my mail server, with each running postfix as a satellite system. Only use is for health checks, e.g. sending as hostname@mydomain.com via the mail server.
These servers are just relaying via the primary mail server. Am I safe to have just the IP of the primary mail server set in the SPF record?
Yes, you just need to set the IP address of the system that sends email to other mail servers. Just make sure that your main relay doesn’t accidentally reject those emails from your satellite system due to… you know… SPF. 🙂
Again, thanks so much for this great howto, I love it! 🙂
The last step can be simplified IMHO – instead of copying the private key, it can be directly saved with the parameter -k /var/lib/rspamd/dkim/mydomain.selector.key.
Thanks @Florian. I was getting There is no DKIM signature when I completed https://dkimvalidator.com/ test. My private key could not be read and I saw it look odd in shape. Likely to do with copying and pasting the key into the file. So I used the following to save a newly generated key automatically into the file:
# rspamadm dkim_keygen -d example.com -s 2019122401 -k /var/lib/rspamd/dkim/example.com.2019122401.key
That worked for me when I did the signature test again.
Hi, it gave me a strange problem when I generated the key with rspamadm dkim_keygen -d example.com -s 2020010503
show me this error
CPU doesn’t have SSSE3 instructions set required for hyperscan, disable it
—– BEGIN PRIVATE KEY —–
ect ect ect
—– END PRIVATE KEY —–
2020010503._domainkey IN TXT (“v = DKIM1; k = rsa;”
ect QAB “);
how do I solve it?
That means you are running this command on very old hardware where the CPU does not support that kind of instruction. As a workaround you could run “dkim_keygen” on another (newer) system.
To verify dkim and spf are working, one can send test emails to these two services:
http://isnotspam.com/
https://www.mail-tester.com/
Everything in this guide woks perfectly, except dkim signing. I spent two days trying every possible parameter, either according to your guide, or rspamd site, tried rspamadm configwizard – nothing. It fails silently, messages are unsigned. I enabled “debug_modules = [“dkim_signing”]”, but still nothing meaningful in the logs (how do I check if the module is called at all?).
The DKIM record in DNS is correct, and I can verify it on https://dkimcore.org/c/keycheck
Here’s an example from rspamd.log (mail address and domain redacted). Looks like the outgoing message is scanned by rspamd, but signing is not invoked. Help!
—
2020-03-02 08:09:23 #6727(normal) ; task; accept_socket: accepted connection from ::1 port 0, task ptr: 00007FACF9C98480
2020-03-02 08:09:23 #6727(normal) ; task; rspamd_message_parse: loaded message; id: ; queue-id: ; size: 434; checksum:
2020-03-02 08:09:23 #6727(normal) ; lua; settings.lua:358: check for settings
2020-03-02 08:09:23 #6727(normal) ; task; spf_symbol_callback: skip SPF checks for local networks and authorized users
2020-03-02 08:09:23 #6727(normal) ; task; dkim_symbol_callback: skip DKIM checks for local networks and authorized users
2020-03-02 08:09:23 #6727(normal) ; lua; once_received.lua:95: Skipping once_received for authenticated user or local network
2020-03-02 08:09:23 #6727(normal) ; lua; dmarc.lua:557: skip DMARC checks for local networks and authorized users
2020-03-02 08:09:23 #6727(normal) ; task; fuzzy_generate_commands: , part is shorter than 1000 bytes: 46 (23 * 2.00 bytes), use direct hash
2020-03-02 08:09:23 #6727(normal) ; task; bayes_classify: skip classification as ham class has not enough learns: 0, 200 required
2020-03-02 08:09:23 #6727(normal) ; task; rspamd_task_write_log: id: , qid: , ip: 212.87.27.79, user: pgolik@my.domain.pl, from: , (default: F (no action): [0.40/15.00] [MV_CASE(0.50){},MIME_GOOD(-0.10){text/plain;},ARC_NA(0.00){},ASN(0.00){asn:8664, ipnet:212.87.16.0/20, country:PL;},FREEMAIL_ENVRCPT(0.00){me.com;},FREEMAIL_TO(0.00){me.com;},FROM_EQ_ENVFROM(0.00){},FROM_HAS_DN(0.00){},MID_RHS_MATCH_FROM(0.00){},RCPT_COUNT_ONE(0.00){1;},RCVD_COUNT_ZERO(0.00){0;},RCVD_TLS_ALL(0.00){},TO_DN_ALL(0.00){},TO_MATCH_ENVRCPT_ALL(0.00){}]), len: 434, time: 252.004ms real, 10.023ms virtual, dns req: 0, digest: , rcpts: , mime_rcpts:
2020-03-02 08:09:23 #6727(normal) ; task; rspamd_protocol_http_reply: regexp statistics: 59 pcre regexps scanned, 5 regexps matched, 177 regexps total, 11 regexps cached, 1.58k bytes scanned using pcre, 1.58k bytes scanned total
—
Hi,
just to make sure, that everything is properly configured (e.g. domain=example.org, selector=2020030201):
1) you created a key-file /etc/rspamd/dkim/example.org.2020030201.key with the content of the private key generated by rspamadm dkim_keygen (copy+paste the part between and including ‘—–BEGIN PRIVATE KEY—–‘…’—–END PRIVATE KEY—–‘ + changed the permissions
2) you created a file /etc/rspamd/dkim_selectors.map and inserted:
example.org 2020030201
3) you are sending e-mail as somebody@example.org
Sorry, keyfile should be in /var/lib/rspamd/dkim/example.org.2020030201.key.
Nevermind, got it figured out. It was a problem with permissions on the keyfile.
Also, I had to add
use_esld = false;
to dkim_signing.conf (seems counterintuitive, but that’s how I got it to work).
Sorry, keyfile should be in /var/lib/rspamd/dkim/example.org.2020030201.key.
One of generating the commands to generate your dkim key pairs
select concat(‘rspamadm dkim_keygen -d ‘, name, ‘ -s 20200401’,id) from virtual_domains;
+————————————————————-+
| concat(‘rspamadm dkim_keygen -d ‘, name, ‘ -s 20200401’,id) |
+————————————————————-+
| rspamadm dkim_keygen -d example.org -s 202004011 |
| rspamadm dkim_keygen -d example.net -s 202004012 |
…
Just a small question regarding the selector maps: this is the place, where I would configure the different keys for the different domains, if I am hosting more than one. Or can I re-use the same key?
A quick tip for users with aliases.
I had a problem where rspamd would not do DKIM-signing sending mail as user@example.com when logged in as user@example.org. After adding “allow_username_mismatch = true;” (without the quotes) to /etc/rspamd/local.d/dkim_signing.conf and restarting rspamd DKIM-signing works just fine.
You could simply run “rspamadm configwizard” and it would create keypairs, enable DKIM maps in /etc/rspamd/local.d/dkim_signing.conf and add domain keys for you, after a few prompts.
If a DKIM header isn’t being added and you’re getting messages in the logs like
dkim_sigining; lua_dkim_tools.lua:104: ignoring unauthenticated mail
then it might be this issue https://workaround.org/ispmail/buster/filtering-out-spam-with-rspamd-2/#comment-107446 which I got stuck on recently.
It’s unclear how or why rspamd gets involved in adding a DKIM signature to outbound mails from your domain. In the Big Picture diagrams I only see rspamd where mails are received, in order to decide whether they’re spam or ham.
I have several domains but use one mailbox respectively one user account to send and receive all my mails. When I send a mail with the domain of the sender address similar to the domain of the authenticated user, the DKIM signature is added like it should be. But when I send a mail from a different domain than the domain of the authenticated user, no DKIM signature is added. Any idea how I can add a DKIM signature when the domain of the sender address is different to the domain of the authenticated user?
I should’ve read the comments more carefully before adding one by myself…
Paddy wrote the solution in https://workaround.org/ispmail/buster/prevent-spoofing-using-dkim/#comment-112048
Now it works, thanks Paddy!
service rspamd reload
everywhere else the systemctl command is used to interact with services.
It probably would also be a better idea to save the immediately tell the user to save the private key after generating it, otherwise it could be difficult to retrieve the key again in the scrollback history.
seems like rspam is not working.
1 – junk folder is not created.
2 – dkim is not added to my mail.
can you help?
hi to all thanks Christoph i love this server 🙂
dkim never works for me …. at last folow this link and manage to get it to work
https://words.bombast.net/rspamd-with-postfix-dovecot-debian-stretch/
thanks again for you work
In my case dkim signing wasn’t working because in postfix’s main.cf I had quotes in this line (I should have used postconf instead of copy pasting this into main.cf):
milter_mail_macros=”i {mail_addr} {client_addr} {client_name} {auth_authen}”
After I removed the quotes rspamd started working.
I have configured DKIM, SPF and DMARC and verified against https://www.dmarcanalyzer.com/, among others.
Still, I receive emails from “myself” that originates from another domain, why isn’t my server stopping this type of email?
What settings should I check in my server?
I ran into the same DKIM issue the first comments on this page mention. Emails with Roundcube were signed, emails sent from Kmail were not.
After staring at logs for far too long I found this one https://github.com/rspamd/rspamd/issues/2622 where its stated that the “milter_mail_macros” setting in main.cf is not required…
Well, commented it out and bingo. Kmail emails are DKIM signed.
In case someone else runs into this…