From fa2a7f3d4ebbb73024ed564a61e19c677d4a13f5 Mon Sep 17 00:00:00 2001 From: Jeremy Harris Date: Sat, 20 Jan 2018 13:13:52 +0000 Subject: [PATCH] Docs: Update DKIM section with RFC 8301 requirements --- doc/doc-docbook/spec.xfpt | 64 +++++++++++++++++++++++++++++++++++++-- 1 file changed, 61 insertions(+), 3 deletions(-) diff --git a/doc/doc-docbook/spec.xfpt b/doc/doc-docbook/spec.xfpt index 40de5b9b1..c908009a4 100644 --- a/doc/doc-docbook/spec.xfpt +++ b/doc/doc-docbook/spec.xfpt @@ -38560,8 +38560,12 @@ In typical Exim style, the verification implementation does not include any default "policy". Instead it enables you to build your own policy using Exim's standard controls. +.new Please note that verification of DKIM signatures in incoming mail is turned -on by default for logging purposes. For each signature in incoming email, +on by default for logging (in the <= line) purposes. + +Additional log detail can be enabled using the &%dkim_verbose%& log_selector. +When set, for each signature in incoming email, exim will log a line displaying the most important signature details, and the signature status. Here is an example (with line-breaks added for clarity): .code @@ -38570,6 +38574,8 @@ signature status. Here is an example (with line-breaks added for clarity): c=relaxed/relaxed a=rsa-sha1 i=@facebookmail.com t=1252484542 [verification succeeded] .endd +.wen + You might want to turn off DKIM verification processing entirely for internal or relay mail sources. To do that, set the &%dkim_disable_verify%& ACL control modifier. This should typically be done in the RCPT ACL, at points @@ -38580,6 +38586,18 @@ senders). .section "Signing outgoing messages" "SECDKIMSIGN" .cindex "DKIM" "signing" +.new +For signing to be usable you must have published a DKIM record in DNS. +Note that RFC 8301 says: +.code +rsa-sha1 MUST NOT be used for signing or verifying. + +Signers MUST use RSA keys of at least 1024 bits for all keys. +Signers SHOULD use RSA keys of at least 2048 bits. +.endd +.wen +.wen + Signing is enabled by setting private options on the SMTP transport. These options take (expandable) strings as arguments. @@ -38616,9 +38634,24 @@ be signed. This case will not result in an error, even if &%dkim_strict%& is set. .endlist +.new +Note that RFC 8301 says: +.code +Signers MUST use RSA keys of at least 1024 bits for all keys. +Signers SHOULD use RSA keys of at least 2048 bits. +.endd +.wen + .option dkim_hash smtp string&!! sha256 Can be set alternatively to &"sha1"& to use an alternate hash -method. Note that sha1 is now condidered insecure, and deprecated. +method. + +.new +Note that RFC 8301 says: +.code +rsa-sha1 MUST NOT be used for signing or verifying. +.endd +.wen .option dkim_identity smtp string&!! unset If set after expansion, the value is used to set an "i=" tag in @@ -38772,7 +38805,7 @@ re-written or otherwise changed in a way which is incompatible with DKIM verification. It may of course also mean that the signature is forged. .endlist -This variable can be overwritten using an ACL 'set' modifier. +This variable can be overwritten, with any value, using an ACL 'set' modifier. .vitem &%$dkim_domain%& The signing domain. IMPORTANT: This variable is only populated if there is @@ -38790,6 +38823,19 @@ The key record selector string. .vitem &%$dkim_algo%& The algorithm used. One of 'rsa-sha1' or 'rsa-sha256'. +.new +Note that RFC 8301 says: +.code +rsa-sha1 MUST NOT be used for signing or verifying. + +DKIM signatures identified as having been signed with historic +algorithms (currently, rsa-sha1) have permanently failed evaluation +.endd + +To enforce this you must have a DKIM ACL which checks this variable +and overwrites the &$dkim_verify_status$& variable as discussed above. +.wen + .vitem &%$dkim_canon_body%& The body canonicalization method. One of 'relaxed' or 'simple'. @@ -38840,6 +38886,18 @@ Notes from the key record (tag n=). .vitem &%$dkim_key_length%& Number of bits in the key. + +.new +Note that RFC 8301 says: +.code +Verifiers MUST NOT consider signatures using RSA keys of +less than 1024 bits as valid signatures. +.endd + +To enforce this you must have a DKIM ACL which checks this variable +and overwrites the &$dkim_verify_status$& variable as discussed above. +.wen + .endlist In addition, two ACL conditions are provided: -- 2.30.2