This shows you the differences between two versions of the page.
Both sides previous revision Previous revision Next revision | Previous revision | ||
plugins:opendkim [2014/01/30 23:42] mrpink |
plugins:opendkim [2017/09/25 18:04] (current) nuxwin |
||
---|---|---|---|
Line 1: | Line 1: | ||
- | ======OpenDKIM Plugin Documentation====== | + | <WRAP center round important 60%> |
+ | **Bear in mind that this documentation is for the last available version. If you use an older version, you must refer to the README.md file inside the plugin archive.** | ||
+ | </WRAP> | ||
+ | <markdown> | ||
+ | # i-MSCP OpenDKIM plugin | ||
- | Plugin providing OpenDKIM an implementation for i-MSCP. | + | Provides DomainKeys Identified Mail (DKIM) service through MILTER. |
- | ===== Requirements ===== | + | ## Introduction |
- | * i-MSCP versions >= 1.1.0 | + | |
- | * Installed packages: opendkim opendkim-tools | + | |
- | ===== Existing milter configurations ===== | + | DKIM provides a way for senders to confirm their identity when sending email by |
+ | adding a cryptographic signature to the headers of the message. | ||
- | This plugin will not check for an existing milter configuration in the Postfix main.cf file. If you need to add an extra milter, please ask in our forum! | + | ## Requirements |
- | + | ||
- | **1.** Install needed Debian/Ubuntu packages if not already done | + | |
- | # aptitude update | + | - i-MSCP Serie ≥ 1.4.x |
- | # aptitude install opendkim opendkim-tools | + | |
- | + | ||
- | **2.** Get the plugin from github | + | |
- | # cd /usr/local/src | + | ## Installation |
- | # git clone git://github.com/i-MSCP/plugins.git | + | |
- | **3.** Create new Plugin archive | + | 1. Upload the plugin through the plugin management interface |
+ | 2. Install the plugin through the plugin management interface | ||
- | # cd plugins | + | ## Update |
- | # tar cvzf OpenDKIM.tar.gz OpenDKIM | + | |
- | + | ||
- | **4.** Plugin upload and installation | + | |
- | * Login into the panel as admin and go to the plugin management interface | + | 1. Be sure that all requirements as stated in the requirements section are met |
- | * Upload the OpenDKIM plugin archive | + | 2. Backup your plugin configuration file if needed |
- | * Install the plugin | + | 3. Upload the plugin through the plugin management interface |
- | + | ||
- | ===== Update ===== | + | |
- | **1.** Get the plugin from github | + | ### Restore you plugin configuration file if needed |
- | # cd /usr/local/src | + | 1. Restore your plugin configuration file (compare it with the new version |
- | # git clone git://github.com/i-MSCP/plugins.git | + | first) |
+ | 2. Update the plugin list through the plugin management interface | ||
- | **2.** Create new Plugin archive | + | ## Configuration |
- | # cd plugins | + | See [Configuration file](https://github.com/i-MSCP/plugins/blob/master/incubator/OpenDKIM/config.php) |
- | # tar cvzf OpenDKIM.tar.gz OpenDKIM | + | |
- | **3.** Backup your current plugin config | + | When changing a configuration parameter in the plugin configuration file, don't |
+ | forget to trigger a plugin list update, else you're changes will not be token | ||
+ | into account. | ||
- | # plugins/OpenDKIM/config.php | + | ## Plugin working level |
- | + | ||
- | **4.** Plugin upload and update | + | |
- | * Login into the panel as admin and go to the plugin management interface | + | It is possible to choose the plugin working level through the |
- | * Upload the OpenDKIM plugin archive | + | `plugin_working_level` plugin configuration parameter. There are actually two |
- | * Update the plugin list | + | working levels which are `admin` and `reseller`. |
- | + | ||
- | ===== Configuration ===== | + | |
- | For the different configuration options please check the plugin config file. | + | When it works at the `admin` level, the plugin activates OpenDKIM for all |
+ | customers automatically. In this working level, resellers can only trigger | ||
+ | renewal of DKIM keys through their own management interface. | ||
- | # plugins/OpenDKIM/config.php | + | When it works at `reseller` level, the plugin doesn't activate OpenDKIM |
- | + | automatically for customers. Resellers must enable the OpenDKIM feature | |
- | After you made your config changes, don't forget to update the plugin list. | + | manually for all of their customers. |
- | * Login into the panel as admin and go to the plugin management interface | + | ## Usage of an external DNS server |
- | * Update the plugin list | + | |
- | ===== Testing ===== | + | If you make use of an external DNS server (not the one managed by i-MSCP), you |
+ | must not forget to add the DKIM and ADSP DNS resource records in the zone of | ||
+ | your domain. | ||
- | ==== Internal DKIM test ==== | + | Each domain has one DKIM and one ADSP DNS resource records and each subdomain has |
+ | one ADSP resource record. | ||
- | You could check on the command line if OpenDKIM is working for your domain: | + | ## Testing |
- | + | ||
- | # opendkim-testkey -d example.com -s mail -vvv | + | |
- | + | ||
- | The result should look similar like this one. The 'key not secure' does not indicate an error. It is an expected consequence of not using DNSSSEC. | + | |
- | opendkim-testkey: checking key 'mail._domainkey.example.com' | + | ### Internal DKIM test |
- | opendkim-testkey: key not secure | + | |
- | opendkim-testkey: key OK | + | |
- | + | ||
- | Query your DNS server and check the TXT DKIM record for your domain. | + | |
- | + | ||
- | # dig -t txt mail._domainkey.example.com | + | |
- | ==== External DKIM test ==== | + | You can check on the command line if OpenDKIM is working for your domain by |
+ | running the following command: | ||
- | Open the link below and send a mail from the domain you activated OpenDKIM to the random mail address shown on that page. | + | ``` |
+ | opendkim-testkey -d example.com -s mail -vvv | ||
+ | ``` | ||
- | http://www.brandonchecketts.com/emailtest.php | + | The result should look similar like this one: |
- | + | ||
- | After you sent the mail, click on that page the 'View Results' button and verify the **DKIM Information:** section. | + | |
- | DKIM Information: | + | ``` |
- | + | root@jessie32:/etc/opendkim# opendkim-testkey -d weird.test.bbox.nuxwin.com -s mail -vvv | |
- | DKIM Signature | + | opendkim-testkey: using default configfile /etc/opendkim.conf |
- | + | opendkim-testkey: checking key 'mail._domainkey.weird.test.bbox.nuxwin.com' | |
- | + | opendkim-testkey: key not secure | |
- | Message contains this DKIM Signature: | + | opendkim-testkey: key OK |
- | DKIM-Signature: v=1; a=rsa-sha256; c=simple/simple; d=example.com; | + | ``` |
- | s=mail; t=1385558914; | + | |
- | bh=fdkeB/A0FkbVP2k4J4pNPoeWH6vqBm9+b0C3OY87Cw8=; | + | |
- | h=Date:From:To:Subject:From; | + | |
- | b=ZtWi/eDZtQ0RDv60FCDf4c+G9gqhFH3r6RPCw9vr400auTH0PnkOwt2BuLNpv4Uh4 | + | |
- | wjBHhFnIqt+t/c9/DLCC8envKmnzco8BATgXl5I5HHLxDcGMFYlwHDgOLXcCKXOXA5 | + | |
- | 15oFPlimBrwZXnq3XOJCwopZmUmZZhUyYT8pZO9k= | + | |
- | + | ||
- | + | ||
- | Signature Information: | + | |
- | v= Version: 1 | + | |
- | a= Algorithm: rsa-sha256 | + | |
- | c= Method: simple/simple | + | |
- | d= Domain: example.com | + | |
- | s= Selector: mail | + | |
- | q= Protocol: | + | |
- | bh= fdkeB/A0FkbVP2k4J4pNPoeWH6vqBm9+b0C3OY87Cw8= | + | |
- | h= Signed Headers: Date:From:To:Subject:From | + | |
- | b= Data: ZtWi/eDZtQ0RDv60FCDf4c+G9gqhFH3r6RPCw9vr400auTH0PnkOwt2BuLNpv4Uh4 | + | |
- | wjBHhFnIqt+t/c9/DLCC8envKmnzco8BATgXl5I5HHLxDcGMFYlwHDgOLXcCKXOXA5 | + | |
- | 15oFPlimBrwZXnq3XOJCwopZmUmZZhUyYT8pZO9k= | + | |
- | Public Key DNS Lookup | + | |
- | + | ||
- | + | ||
- | Building DNS Query for mail._domainkey.example.com | + | |
- | Retrieved this publickey from DNS: v=DKIM1; k=rsa; p=MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDN+HbTA3/7KoENKhMr6qRO0cFeaDX1NSD5Xe7zkGhkvOnajIrhycu0XyxzHLTTSbFLq9juJmUbPmP9OVj44o0p/NqoLQ9oWjfkcM+7nq+S4QYGoM7h+SMcxjFm05mo0LdessYi/Sw5z6x87nMkLD/wQViDvctss4srrPTr/hqD+wIDAQAB | + | |
- | Validating Signature | + | |
- | + | ||
- | + | ||
- | result = pass | + | |
- | Details: | + | |
- | ===== Authors ===== | + | Note that the `key not secure` message doesn't indicate an error. It is the |
+ | expected consequence of not using DNSSSEC. | ||
+ | |||
+ | You can also query your DNS server to check the TXT record for your domain: | ||
+ | |||
+ | ``` | ||
+ | dig -t txt mail._domainkey.example.com | ||
+ | ``` | ||
+ | |||
+ | ### External DKIM test | ||
+ | |||
+ | Go to [dkimvalidator.com](http://dkimvalidator.com) and send a mail from the | ||
+ | domain for which you activated OpenDKIM to the random mail address. Once you | ||
+ | have sent the mail, wait few seconds and then, click on the `View Results` | ||
+ | button. You should get a result similar to: | ||
+ | |||
+ | #### Original Message | ||
+ | |||
+ | ``` | ||
+ | Received: from jessie32.bbox.nuxwin.com (xxx-xxx-xx-xx.abo.bbox.fr [xxx.xxx.xx.xx]) | ||
+ | by relay-4.us-west-2.relay-prod (Postfix) with ESMTPS id 9B57F160208 | ||
+ | for <[email protected]>; Sat, 2 Sep 2017 18:29:48 +0000 (UTC) | ||
+ | Received: from panel.bbox.nuxwin.com (jessie32.bbox.nuxwin.com.local [127.0.0.1]) | ||
+ | (Authenticated sender: [email protected]) | ||
+ | by jessie32.bbox.nuxwin.com (Postfix) with ESMTPA id F3E645FC6A | ||
+ | for <[email protected]>; Sat, 2 Sep 2017 20:30:21 +0200 (CEST) | ||
+ | DKIM-Filter: OpenDKIM Filter v2.9.2 jessie32.bbox.nuxwin.com F3E645FC6A | ||
+ | DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; | ||
+ | d=weird.test.bbox.nuxwin.com; s=mail; t=1504377022; | ||
+ | i=@sub1.weird.test.bbox.nuxwin.com; | ||
+ | bh=g3zLYH4xKxcPrHOD18z9YfpQcnk/GaJedfustWU5uGs=; | ||
+ | h=Date:From:To:Subject:From; | ||
+ | b=HdAyJ/C0tBH5UkzZSGXo2ESZ6+8tCr1O/LC3REVuyRg1TSB/bYGDAv/H05+nJSisD | ||
+ | fExsy/Irnjjz5bVNSUq0nB8mPoHaTMibh9mWAC/Q23WDsu9j9vprH5TGw0k91UUuur | ||
+ | XQm2anEaugJtvEpCSdOf3CMHlxUF9M/oMti+Bm0N/aoqsvu1vRZHazQH4PUMd+Thyq | ||
+ | PtnEx4ZPQaU/f1HOdZTi7c4KjwWHoLDdQ1mNAwknUMjm5hsw2MGIIW0ecumNqzzKZH | ||
+ | vIFhX75q2Hw03rByI5paaUrf6bAEozOmQghDTzz+07pn/aYhoK+jNYMEvev/F8pRqz | ||
+ | 596UbuEZYMC1w== | ||
+ | MIME-Version: 1.0 | ||
+ | Content-Type: text/plain; charset=US-ASCII; | ||
+ | format=flowed | ||
+ | Content-Transfer-Encoding: 7bit | ||
+ | Date: Sat, 02 Sep 2017 20:30:21 +0200 | ||
+ | From: [email protected] | ||
+ | To: [email protected] | ||
+ | Subject: test | ||
+ | Message-ID: <[email protected]> | ||
+ | X-Sender: [email protected] | ||
+ | User-Agent: Roundcube Webmail/1.2.5 | ||
+ | |||
+ | test | ||
+ | ``` | ||
+ | |||
+ | #### DKIM Information | ||
+ | |||
+ | ``` | ||
+ | DKIM Signature | ||
+ | |||
+ | Message contains this DKIM Signature: | ||
+ | DKIM-Filter: OpenDKIM Filter v2.9.2 jessie32.bbox.nuxwin.com F3E645FC6A | ||
+ | DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; | ||
+ | d=weird.test.bbox.nuxwin.com; s=mail; t=1504377022; | ||
+ | [email protected]; | ||
+ | bh=g3zLYH4xKxcPrHOD18z9YfpQcnk/GaJedfustWU5uGs=; | ||
+ | h=Date:From:To:Subject:From; | ||
+ | b=HdAyJ/C0tBH5UkzZSGXo2ESZ6+8tCr1O/LC3REVuyRg1TSB/bYGDAv/H05+nJSisD | ||
+ | fExsy/Irnjjz5bVNSUq0nB8mPoHaTMibh9mWAC/Q23WDsu9j9vprH5TGw0k91UUuur | ||
+ | XQm2anEaugJtvEpCSdOf3CMHlxUF9M/oMti+Bm0N/aoqsvu1vRZHazQH4PUMd+Thyq | ||
+ | PtnEx4ZPQaU/f1HOdZTi7c4KjwWHoLDdQ1mNAwknUMjm5hsw2MGIIW0ecumNqzzKZH | ||
+ | vIFhX75q2Hw03rByI5paaUrf6bAEozOmQghDTzz+07pn/aYhoK+jNYMEvev/F8pRqz | ||
+ | 596UbuEZYMC1w== | ||
+ | |||
+ | Signature Information: | ||
+ | v= Version: 1 | ||
+ | a= Algorithm: rsa-sha256 | ||
+ | c= Method: relaxed/simple | ||
+ | d= Domain: weird.test.bbox.nuxwin.com | ||
+ | s= Selector: mail | ||
+ | q= Protocol: | ||
+ | bh= g3zLYH4xKxcPrHOD18z9YfpQcnk/GaJedfustWU5uGs= | ||
+ | h= Signed Headers: Date:From:To:Subject:From | ||
+ | b= Data: HdAyJ/C0tBH5UkzZSGXo2ESZ6+8tCr1O/LC3REVuyRg1TSB/bYGDAv/H05+nJSisD | ||
+ | fExsy/Irnjjz5bVNSUq0nB8mPoHaTMibh9mWAC/Q23WDsu9j9vprH5TGw0k91UUuur | ||
+ | XQm2anEaugJtvEpCSdOf3CMHlxUF9M/oMti+Bm0N/aoqsvu1vRZHazQH4PUMd+Thyq | ||
+ | PtnEx4ZPQaU/f1HOdZTi7c4KjwWHoLDdQ1mNAwknUMjm5hsw2MGIIW0ecumNqzzKZH | ||
+ | vIFhX75q2Hw03rByI5paaUrf6bAEozOmQghDTzz+07pn/aYhoK+jNYMEvev/F8pRqz | ||
+ | 596UbuEZYMC1w== | ||
+ | Public Key DNS Lookup | ||
+ | |||
+ | Building DNS Query for mail._domainkey.weird.test.bbox.nuxwin.com | ||
+ | Retrieved this publickey from DNS: v=DKIM1; h=sha256; k=rsa; s=email; p=MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAsGfEnQP49L7DrUvR8/cPOciHvATQkxXTgBm4qUcNFFDLnT6s45xsmU068RTED/QGJWaeL2eQcd7c5p7dlUdqVugYSfB+aDjOJuvPIr3P/jiISt6HERoBafu7pkc2mj92S70Xq3Jyx6lgIhMe63UGKyeyuBJHB7Nm3KHHiZFqH7AWtQwgBpMqa7LKPj4OCIELZ+G8SO8OMAkytLndDf40lABXXHsyjFSTaOPb27BStTLBmZT58AwPtSHTZ7+8hz+reHZDUXMos96SiwcvxOepDMSBMMdKpAI7iu+v86F+ewaMRllAogVIAFZb68DgjAUvk6fwDE4mwGyGk1y7QdKVEwIDAQAB | ||
+ | Validating Signature | ||
+ | |||
+ | result = pass | ||
+ | Details: | ||
+ | ``` | ||
+ | |||
+ | #### SPF Information | ||
+ | |||
+ | ``` | ||
+ | Using this information that I obtained from the headers | ||
+ | |||
+ | Helo Address = jessie32.bbox.nuxwin.com | ||
+ | From Address = [email protected] | ||
+ | From IP = xxx.xxx.xx.xx | ||
+ | SPF Record Lookup | ||
+ | |||
+ | Looking up TXT SPF record for sub1.weird.test.bbox.nuxwin.com | ||
+ | Found the following namesevers for sub1.weird.test.bbox.nuxwin.com: | ||
+ | Retrieved this SPF Record: zone updated 20170902 (TTL = 43897) | ||
+ | Using local nameserver for SPF resolution. This will probably be cached! | ||
+ | Result: pass (Mechanism 'include:weird.test.bbox.nuxwin.com' matched) | ||
+ | |||
+ | Result code: pass | ||
+ | Local Explanation: sub1.weird.test.bbox.nuxwin.com: Sender is authorized to use '[email protected]' in 'mfrom' identity (mechanism 'include:weird.test.bbox.nuxwin.com' matched) | ||
+ | spf_header = Received-SPF: pass (sub1.weird.test.bbox.nuxwin.com: Sender is authorized to use '[email protected]' in 'mfrom' identity (mechanism 'include:weird.test.bbox.nuxwin.com' matched)) receiver=dkimvalidator.com; identity=mailfrom; envelope-from="[email protected]"; helo=jessie32.bbox.nuxwin.com; client-ip=xxx.xxx.xx.xx | ||
+ | ``` | ||
+ | |||
+ | Regarding the SpamAssassin information at bottom, you can ignore them as the | ||
+ | SpamAssassin installation used is not able to validate DKIM signatures when | ||
+ | DKIM ADSP extension is involved. | ||
+ | |||
+ | ## License | ||
+ | |||
+ | i-MSCP OpenDKIM plugin | ||
+ | Copyright (C) 2013-2017 Laurent Declercq <[email protected]> | ||
+ | Copyright (C) 2013-2016 Rene Schuster <[email protected]> | ||
+ | Copyright (C) 2013-2016 Sascha Bay <[email protected]> | ||
+ | |||
+ | This program is free software; you can redistribute it and/or modify | ||
+ | it under the terms of the GNU General Public License as published by | ||
+ | the Free Software Foundation; version 2 of the License | ||
+ | |||
+ | This program is distributed in the hope that it will be useful, | ||
+ | but WITHOUT ANY WARRANTY; without even the implied warranty of | ||
+ | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the | ||
+ | GNU General Public License for more details. | ||
+ | </markdown> | ||
- | * Sascha Bay <[email protected]> | ||
- | * Rene Schuster <[email protected]> |