688
edits
Changes
From SME Server
Jump to navigationJump to searchCreated page with "<span id="_top">Qpsmtpd#Plugins</span> = NAME = dkim: validate DomainKeys and (DKIM) Domain Keys Indentified Messages = SYNOPSIS = Validate the ..."
<span id="_top">[[Qpsmtpd#Plugins]]</span>
= [[#___top|NAME]] =
dkim: validate DomainKeys and (DKIM) Domain Keys Indentified Messages
= [[#___top|SYNOPSIS]] =
Validate the DKIM and Domainkeys signatures of a message, enforce DKIM sending policies, and DKIM sign outgoing messages.
= [[#___top|CONFIGURATION]] =
== [[#___top|reject [ 0 | 1 | naughty ]]] ==
<pre> dkim [ reject 0 ]
0 - do not reject
1 - reject messages that fail DKIM policy
naughty - defer rejection to the B<naughty> plugin</pre>
Default: 1
== [[#___top|reject_type]] ==
<pre> dkim reject_type [ temp | perm ]</pre>
Default: perm
= [[#___top|HOW TO SIGN]] =
== [[#___top|generate DKIM keys]] ==
=== [[#___top|the easy way]] ===
<pre> cd ~smtpd/config/dkim; ./dkim_key_gen.sh example.org</pre>
=== [[#___top|the manual way]] ===
<pre> mkdir -p ~smtpd/config/dkim/example.org
cd ~smtpd/config/dkim/example.org
echo 'may2013' > selector
openssl genrsa -out private 2048
chmod 400 private
openssl rsa -in private -out public -pubout
chown -R smtpd:smtpd ../example.org</pre>
After generating the keys, there will be three files in the example.org directory: selector, private, and public.
=== [[#___top|selector]] ===
The selector can be any value that is a valid DNS label.
=== [[#___top|key length]] ===
The minimum recommended key length for short duration keys (ones that will be replaced within a few months) is 1024. If you are unlikely to rotate your keys frequently, choose 2048, at the expense of a bit more CPU.
== [[#___top|publish public key in DNS]] ==
If the DKIM keys were generated the easy way, there will be a fourth file named ''dns''. The contents contain the DNS formatted record of the public key, as well as suggestions for DKIM, SPF, and DMARC policy records. The records are ready to be copy/pasted into a BIND zone file, or better yet, NicTool. If you created your keys manually, look in the dkim_key_gen.sh script to see the commands used to format the DKIM public key.
The combination of the three example DKIM, SPF, and DMARC policy records in the ''dns'' file tell other mail servers that if a sender claims to be from example.org, but the message is not DKIM nor SPF aligned, then the message should be rejected. Many email servers, including the largest email providers (Gmail, Yahoo, Outlook/Live/Hotmail) will refuse to accept such messages, greatly reducing the harm caused by miscreants who forge your domain(s) in the From header of their spam.
The DKIM record will look like this:
<pre> may2013._domainkey TXT "v=DKIM1;p=[public key stripped of whitespace];"</pre>
And the values in the address have the following meaning:
<pre> hash: h=[ sha1 | sha256 ]
test; t=[ s | s:y ]
granularity: g=[ ]
notes: n=[ ]
services: s=[email]
keytypes: [ rsa ]</pre>
== [[#___top|testing]] ==
After confirming that the DKIM public key can be fetched with DNS (dig TXT may2013._domainkey.example.org. @ns1.example.org.), send test messages. You can testing DKIM by sending an email to:
<pre> * a Gmail address and inspect the Authentication-Results header.
* mailtest@unlocktheinbox.com
* check-auth@verifier.port25.com
* checkmyauth@auth.returnpath.net</pre>
The three email reflectors provide nice email reports with additional debugging information.
== [[#___top|publish DKIM policy in DNS]] ==
_domainkey TXT "o=~; t=y; r=postmaster@example.org"
<pre> o=- - all are signed
o=~ - some are signed
t=y - test mode
r=[email] - responsible email address
n=[notes]</pre>
After DKIM and SPF are tested and working, update the policy, changing o=~ to o=-, so that other mail servers reject unsigned messages claiming to be from your domain.
As of this writing, most mail servers do not reject messages that fail DKIM policy, unless they also fail SPF, and no DMARC policy is published. The same holds true for SPF. There are technical reasons for this. See DMARC for more information, how you can control change that behavior, as well as receiving feedback from remote servers about messages they have accepted and rejected from senders claiming the identity of your domain(s).
= [[#___top|SEE ALSO]] =
http://www.dkim.org/
http://tools.ietf.org/html/rfc6376 - DKIM Signatures
http://tools.ietf.org/html/rfc5863 - DKIM Development, Deployment, & Operations
http://tools.ietf.org/html/rfc5617 - DKIM ADSP (Author Domain Signing Practices)
http://tools.ietf.org/html/rfc5585 - DKIM Service Overview
http://tools.ietf.org/html/rfc5016 - DKIM Signing Practices Protocol
http://tools.ietf.org/html/rfc4871 - DKIM Signatures
http://tools.ietf.org/html/rfc4870 - DomainKeys
http://dkimcore.org/tools/
http://www.protodave.com/tools/dkim-key-checker/
= [[#___top|AUTHORS]] =
<pre> 2013 - Matt Simerson - added DKIM signing and key creation script
2012 - Matt Simerson - initial plugin</pre>
= [[#___top|ACKNOWLEDGEMENTS]] =
David Summers - http://www.nntp.perl.org/group/perl.qpsmtpd/2010/08/msg9417.html
Matthew Harrell - http://alecto.bittwiddlers.com/files/qpsmtpd/dkimcheck
I first attempted to fix the dkimcheck plugin, but soon scrapped that effort and wrote this one. Why?
<blockquote>The use of $dkim->fetch_author_policy, which is deprecated by Mail::DKIM.
The paradim of a single policy, when DKIM supports 0 or many.
The OBF programming style, which is nigh impossible to test.
The nine 'if' brackets with 19 conditionals, and my inability to easily determine which of the 15 possible permutations (5 signature validation results x 3 possible policy results) were covered.
</blockquote>
<!-- Generated Tue Jul 18 06:43:47 EDT 2017 using
perldoc -T -ohtml /usr/share/qpsmtpd/plugins/dkim |pandoc -f html -t mediawiki |sed 1 i\\n\n\n<span id="_top">[[Qpsmtpd#Plugins]]</span> |sed -e s#</d.>##
-->
----
[[Category:Qpsmtpd|dkim]]
= [[#___top|NAME]] =
dkim: validate DomainKeys and (DKIM) Domain Keys Indentified Messages
= [[#___top|SYNOPSIS]] =
Validate the DKIM and Domainkeys signatures of a message, enforce DKIM sending policies, and DKIM sign outgoing messages.
= [[#___top|CONFIGURATION]] =
== [[#___top|reject [ 0 | 1 | naughty ]]] ==
<pre> dkim [ reject 0 ]
0 - do not reject
1 - reject messages that fail DKIM policy
naughty - defer rejection to the B<naughty> plugin</pre>
Default: 1
== [[#___top|reject_type]] ==
<pre> dkim reject_type [ temp | perm ]</pre>
Default: perm
= [[#___top|HOW TO SIGN]] =
== [[#___top|generate DKIM keys]] ==
=== [[#___top|the easy way]] ===
<pre> cd ~smtpd/config/dkim; ./dkim_key_gen.sh example.org</pre>
=== [[#___top|the manual way]] ===
<pre> mkdir -p ~smtpd/config/dkim/example.org
cd ~smtpd/config/dkim/example.org
echo 'may2013' > selector
openssl genrsa -out private 2048
chmod 400 private
openssl rsa -in private -out public -pubout
chown -R smtpd:smtpd ../example.org</pre>
After generating the keys, there will be three files in the example.org directory: selector, private, and public.
=== [[#___top|selector]] ===
The selector can be any value that is a valid DNS label.
=== [[#___top|key length]] ===
The minimum recommended key length for short duration keys (ones that will be replaced within a few months) is 1024. If you are unlikely to rotate your keys frequently, choose 2048, at the expense of a bit more CPU.
== [[#___top|publish public key in DNS]] ==
If the DKIM keys were generated the easy way, there will be a fourth file named ''dns''. The contents contain the DNS formatted record of the public key, as well as suggestions for DKIM, SPF, and DMARC policy records. The records are ready to be copy/pasted into a BIND zone file, or better yet, NicTool. If you created your keys manually, look in the dkim_key_gen.sh script to see the commands used to format the DKIM public key.
The combination of the three example DKIM, SPF, and DMARC policy records in the ''dns'' file tell other mail servers that if a sender claims to be from example.org, but the message is not DKIM nor SPF aligned, then the message should be rejected. Many email servers, including the largest email providers (Gmail, Yahoo, Outlook/Live/Hotmail) will refuse to accept such messages, greatly reducing the harm caused by miscreants who forge your domain(s) in the From header of their spam.
The DKIM record will look like this:
<pre> may2013._domainkey TXT "v=DKIM1;p=[public key stripped of whitespace];"</pre>
And the values in the address have the following meaning:
<pre> hash: h=[ sha1 | sha256 ]
test; t=[ s | s:y ]
granularity: g=[ ]
notes: n=[ ]
services: s=[email]
keytypes: [ rsa ]</pre>
== [[#___top|testing]] ==
After confirming that the DKIM public key can be fetched with DNS (dig TXT may2013._domainkey.example.org. @ns1.example.org.), send test messages. You can testing DKIM by sending an email to:
<pre> * a Gmail address and inspect the Authentication-Results header.
* mailtest@unlocktheinbox.com
* check-auth@verifier.port25.com
* checkmyauth@auth.returnpath.net</pre>
The three email reflectors provide nice email reports with additional debugging information.
== [[#___top|publish DKIM policy in DNS]] ==
_domainkey TXT "o=~; t=y; r=postmaster@example.org"
<pre> o=- - all are signed
o=~ - some are signed
t=y - test mode
r=[email] - responsible email address
n=[notes]</pre>
After DKIM and SPF are tested and working, update the policy, changing o=~ to o=-, so that other mail servers reject unsigned messages claiming to be from your domain.
As of this writing, most mail servers do not reject messages that fail DKIM policy, unless they also fail SPF, and no DMARC policy is published. The same holds true for SPF. There are technical reasons for this. See DMARC for more information, how you can control change that behavior, as well as receiving feedback from remote servers about messages they have accepted and rejected from senders claiming the identity of your domain(s).
= [[#___top|SEE ALSO]] =
http://www.dkim.org/
http://tools.ietf.org/html/rfc6376 - DKIM Signatures
http://tools.ietf.org/html/rfc5863 - DKIM Development, Deployment, & Operations
http://tools.ietf.org/html/rfc5617 - DKIM ADSP (Author Domain Signing Practices)
http://tools.ietf.org/html/rfc5585 - DKIM Service Overview
http://tools.ietf.org/html/rfc5016 - DKIM Signing Practices Protocol
http://tools.ietf.org/html/rfc4871 - DKIM Signatures
http://tools.ietf.org/html/rfc4870 - DomainKeys
http://dkimcore.org/tools/
http://www.protodave.com/tools/dkim-key-checker/
= [[#___top|AUTHORS]] =
<pre> 2013 - Matt Simerson - added DKIM signing and key creation script
2012 - Matt Simerson - initial plugin</pre>
= [[#___top|ACKNOWLEDGEMENTS]] =
David Summers - http://www.nntp.perl.org/group/perl.qpsmtpd/2010/08/msg9417.html
Matthew Harrell - http://alecto.bittwiddlers.com/files/qpsmtpd/dkimcheck
I first attempted to fix the dkimcheck plugin, but soon scrapped that effort and wrote this one. Why?
<blockquote>The use of $dkim->fetch_author_policy, which is deprecated by Mail::DKIM.
The paradim of a single policy, when DKIM supports 0 or many.
The OBF programming style, which is nigh impossible to test.
The nine 'if' brackets with 19 conditionals, and my inability to easily determine which of the 15 possible permutations (5 signature validation results x 3 possible policy results) were covered.
</blockquote>
<!-- Generated Tue Jul 18 06:43:47 EDT 2017 using
perldoc -T -ohtml /usr/share/qpsmtpd/plugins/dkim |pandoc -f html -t mediawiki |sed 1 i\\n\n\n<span id="_top">[[Qpsmtpd#Plugins]]</span> |sed -e s#</d.>##
-->
----
[[Category:Qpsmtpd|dkim]]
