Selecting header fields (tags) for DKIM signature

[kstirn]

Hello,

emails sent from our WHM/Cpanel servers are DKIM signed; valid and working fine.

A lot of email headers are included in the DKIM signature:

Content-Type:Message-ID:Date:Subject:Reply-To:To:From:Sender:Cc:MIME-Version:Content-Transfer-Encoding:Content-ID:Content-Description:Resent-Date:Resent-From:Resent-Sender:Resent-To:Resent-Cc:Resent-Message-ID:In-Reply-To:References:List-Id:List-Help:List-Unsubscribe:List-Subscribe:List-Post:List-Owner:List-Archive;

My question is: how can we add additional or remove existing headers from DKIM signatures?

Thank you

 

[cPanelMichael]

Hello @kstirn,

Exim documents the dkim_sign_headers option under the Signing outgoing messages section on the link below:

57. DKIM and SPF

Changing this value is unsupported, but you should be able to simply add a custom dkim_sign_headers line under the dkim_remote_smtp section in the Exim configuration file using the example instructions found on the link below:

How to Edit the exim.conf File - cPanel Knowledge Base - cPanel Documentation

Note the Advanced Editor does not support a change to this specific option, so you'd need to follow the instructions listed on the above document:

• Any edits that you make directly to the /etc/exim.conf file only work temporarily, unless you also make the same edits to the /etc/exim.conf.local file. The /etc/exim.conf.local file is Exim’s override file and stores Exim’s default configuration. If you do not edit the /etc/exim.conf.local file when you edit the /etc/exim.conf file, the system will overwrite your changes when you update Exim.

Thank you.

 

[kstirn]

Thank you, Michael!

Just a heads up for everyone else why we are doing this:

We found that if the message doesn't have a MIME-Version header (it's not a MIME-formatted) and has a valid DKIM signature, Microsoft (outlook.com) will automatically add the "MIME-Version=1.0" header.

Because Exim by default includes the MIME-Version header (or lack thereof) in the DKIM signature, outlook.com will verify DKIM as FAILED in this case; MIME-Version wasn't in the original body hash, but it is in their calculated body hash because they have added it themselves, hence body hash mismatch.

Of course, no one else (Google, AOL, Yahoo, Cpanel servers, ...) will do such a stu..d thing and all DKIM signature tests show pass.

 

[thowden]

Hi All

I know this thread goes back a while but it comes up when searching for dkim_sign_headers.

I can see the instructions for using exim.conf.local and tried following another thread How to edit /etc/exim.conf manually as well as the How to Edit the exim.conf File - cPanel Knowledge Base - cPanel Documentation How to Edit Exim.conf page but none of it makes sense.

The parameter I want to modify sits within the section dkim_remote_smtp in exim.conf. There is no option in the Advanced Editor to modify any content near this section. Further, the exim.conf.local does not have 'sections' like exim.conf and appears to consist of a number of constants that will be exploded into content when the /scripts/buildeximconf process is run.

I've been dealing with an issue that is similar to the one kstirn has highlighted and I'd interested to hear what modifications / settings they made to fix their issue ?

Ultimately I want to add a custom dkim_sign_headers to exim.conf.local so that it is permanent as the Cpanel documentation is not working for me.

Thanks.

 

[cPRex]

As with any option not present in the WHM interface, we have to defer to the Exim documentation for customizing that value:

"If set, this option must expand to a colon-separated list of header names. Headers with these names, or the absence or such a header, will be included in the message signature. When unspecified, the header names listed in RFC4871 will be used, whether or not each header is present in the message. The default list is available for the expansion in the macro “_DKIM_SIGN_HEADERS”"

58. DKIM, SPF and DMARC

Exim is a message transfer agent (MTA) developed at the University of Cambridge for use on Unix systems connected to the Internet.

www.exim.org

The docs in your post are from the older site, so it's possible the newer versions have better information:

Exim Configuration Manager | cPanel & WHM Documentation

Use the features in the Exim Configuration Manager interface to modify your Exim configuration.

docs.cpanel.net

 

[thowden]

Hi

Thanks for the response.

The issue is not with the Exim documentation but the CPanel documentation. I have sufficient knowledge to be dangerous with the exim.conf file and have edited it directly to accommodate the changes that I require. Thats the Exim documentation part sorted.

The file and concept of exim.conf.local is not a part of Exim, but a part of Cpanel / WHM.

My question can be restated as:

How to edit the exim.conf.local so that the desired changes to exim.conf are persistent and not removed with an Exim rebuild / restart / update.

The documentation for Cpanel :: Exim Configuration Manager does not provide any information on the expected formatting or syntax for directly editing the exim.conf.local file (in any of the versions). The documentation appears to indicate that it _could_ be edited directly, but that it _should_ be edited via the Advanced Editor interface. The documentation is silent on "how to edit exim.conf.local file" or is there some additional documentation that I am missing?

Reviewing the Advanced Editor interface, it presents the Exim configuration in a sequential order consistent with the exim.conf file with some editable blocks. There are no editable blocks in the region of the sections remote_smtp or dkim_remote_smtp, which indicates that the editing that I want to do must take place directly in the exim.conf.local file. Is this correct or am I missing something here ?

 

[cPRex]

Thanks for clearing that up - that's exactly what I needed to know.

The /etc/exim.conf.local file doesn't exist by default, but gets created once custom changes are made through the WHM interface in the Advanced Editor area. For example, if I add port 466 to the tls_on_connect_ports value through WHM (I picked this since it's an easy change you can add without breaking any existing settings) cPanel automagically creates the /etc/exim.conf.local file that looks like this:

%RETRYBLOCK%
+secondarymx                    *                               F,4h,5m; G,16h,1h,1.5; F,4d,8h
*                               *                               F,2h,15m; G,16h,1h,1.5; F,4d,8h
@[email protected]

@[email protected]

@[email protected]
tls_on_connect_ports = 465, 466

@[email protected]

@[email protected]

@[email protected]

@[email protected]

@[email protected]

@[email protected]

@[email protected]

@[email protected]

@[email protected]

@[email protected]

@[email protected]

@[email protected]

@[email protected]

@[email protected]

@[email protected]

@[email protected]

@[email protected]

@[email protected]

@[email protected]

@[email protected]

@[email protected]

@[email protected]

It creates each section and then just adds the data in the appropriate area.

Does that help with the understanding process of how that file works?

Now, if I change that line in the file directly through SSH to look like this:

tls_on_connect_ports = 465, 466, 467

and then refresh the advanced editor in WHM, the changes will show up in the interface. As long as they are in the file and properly formated, cPanel will not overwrite those and they will show up in the interface accordingly.

 

[thowden]

Hi

Yes, that bit I understand. I do have exim.conf.local already existing and I can successfully edit the exim.conf file directly with the correct syntax for dkim_sign_headers. What I cannot figure out is what syntax to use within the exim.conf.local file to make the change persistent.

In both the documentation and your comments the process is:

1. Use the Advanced Editor WHM Interface
2. Make a change
3. WHM generates the relevant exim.conf.local changes
4. You can then modify the line in exim.conf.local

BUT, in the Advanced Editor there is no option to Edit or Add to the remote_smtp or dkim_remote_smtp sections of the exim.conf file and therefore no option to have the system generate the relevant section within exim.conf.local.

If I manually add lines to the exim.conf.local file as you suggest like, dkim_sign_headers = values and try to rebuild exim with "/scripts/buildeximconf" it errors:

Error message from syntax check:
2021-05-21 04:59:53 Exim configuration error in line 9 of /etc/exim.conf.buildtest.work.b600de5d:
  main option "dkim_sign_headers" unknown

Alternatively, if I prefix the line with dkim_remote_smtp which I am assuming is the main option or section head I get:

Error message from syntax check:
2021-05-21 05:03:39 Exim configuration error in line 9 of /etc/exim.conf.buildtest.work.a76572d1:
  main option "dkim_remote_smtp" unknown

Try again, placing the line I want near the section @TRANSPORTMIDDLE, i.e. close to where the dkim_remote_smtp section appears in Advanced Editor, yields:

Error message from syntax check:
2021-05-21 05:07:36.502 [1309132] cwd=/etc 4 args: /usr/sbin/exim -bV -C /etc/exim.conf.buildtest.work.7e52864c
2021-05-21 05:07:36.504 [1309132] Exim configuration error in line 2371 of /etc/exim.conf.buildtest.work.7e52864c:
  option "dkim_remote_smtp" unknown

And finally attempting to add a section header formatted as "dkim_remote_smtp: " to mimic the syntax of exim.conf, provides this error:

Error message from syntax check:
2021-05-21 05:13:25.738 [1311765] cwd=/etc 4 args: /usr/sbin/exim -bV -C /etc/exim.conf.buildtest.work.28c3c781
2021-05-21 05:13:25.740 [1311765] Exim configuration error:
  there are two transports called "dkim_remote_smtp"

Obviously, this syntax is recognised, but does not 'take precedence over' or 'complement' the existing exim.conf configuration, it is treated as conflicting with the exim.conf and fails.

If manual editing of the exim.conf.local with syntactically correct Exim options is not sufficient, there must be some specific syntax that is required to allow for the edit.

My question remains with emphasis added: How to edit the exim.conf.local so that the desired changes to exim.conf are persistent and not removed with an Exim rebuild / restart / update?

 

[thowden]

Hi

While searching further I think this thread confirms that there is no way to utilise exim.conf.local without using Advanced Editor in the WHM interface.

https://forums.cpanel.net/threads/yahoo-defers-mail-from-cpanel.675909/#post-2773721

From the comments there, the Advanced Editor appears to only provide support for the specifically selected options in exim.conf.local. i.e. if there is an edit block in Advanced Editor, then it can be customised, but if there is no block (like for dkim_remote_smtp) then there is not option in exim.conf.local that will work.

Any customisation / Edit & Save process, in the Advanced Editor will overwrite the contents of exim.conf.local, with the supported features of Advanced Editor and removing any customisations.

The thread includes comments regarding editing of perl scripts at /usr/local/cpanel/etc/exim/perl/ in order to achieve an outcome!

If this is this correct, I have a lot more work to do to make this change persistent. Please advise if this is the case.

 

[cPRex]

I've done some additional testing on this and determined the file is only used to support edits that can be made through WHM. External values that aren't supported in WHM do cause errors.

I'd recommend submitting a feature request using the link in my signature if you'd like to see a specific value added to the Advanced Configuration interface. That will make our developers aware and allow other users to vote for the request.

 

[thowden]

Hi

Feature request added at https://features.cpanel.net/topic/2...tor-add-management-of-dkim_sign_headers-value

In the meantime I am reviewing the information at https://forums.cpanel.net/threads/yahoo-defers-mail-from-cpanel.675909/#post-2773721 which appears to offer some ideas for creating file copies that will / may preserve my desired settings.

Importantly, from several unanswered, unresolved threads in the forums that I noted on this journey, I think the Cpanel Docs should be updated apropos Exim.conf Editing, to clearly state that although editing exim.conf can work, it is not persistent, AND that attempting to edit exim.conf.local is wasted effort as it can only really work with Advanced Editor and not as a manual process.

The documentation https://docs.cpanel.net/knowledge-base/email/how-to-edit-the-exim-conf-file/ presents this information:

Warnings:

• Any edits that you make directly to the /etc/exim.conf file only work temporarily, unless you also make the same edits to the /etc/exim.conf.local file. The /etc/exim.conf.local file is Exim’s override file and stores Exim’s default configuration. If you do not edit the /etc/exim.conf.local file when you edit the /etc/exim.conf file, the system will overwrite your changes when you update Exim.
• We strongly recommend that you use the Advanced Editor feature to make changes to your Exim configuration.

Which is mis-leading as it indicates that editing both exim.conf AND exim.conf.local is 'essential' to having modification persist, when it should preface this with the fact that ONLY Advanced Editor modifications can be used in the exim.conf.local. No other Exim configuration modifications can be used.

Similarly https://documentation.cpanel.net/display/CKB/How+to+Edit+the+exim.conf+File and https://docs.cpanel.net/whm/service-configuration/exim-configuration-manager/ present the same mis-leading information.

 

[cPRex]

I agree - I've let the email team know and they've created an internal case to get that documentation page updated. I can't say for sure when that will happen, but it's at least on the schedule now!