X-Git-Url: https://git.exim.org/exim.git/blobdiff_plain/de52602ff2da93de105805ff0bdec199a4039d04..baabef80f200a5e028a6f1487276a441caa40255:/doc/doc-docbook/spec.xfpt diff --git a/doc/doc-docbook/spec.xfpt b/doc/doc-docbook/spec.xfpt index f3c7a060e..3b5cbbf5b 100644 --- a/doc/doc-docbook/spec.xfpt +++ b/doc/doc-docbook/spec.xfpt @@ -17133,8 +17133,13 @@ use when sending messages as a client, you must set the &%tls_certificate%& option in the relevant &(smtp)& transport. .new +&*Note*&: If you use filenames based on IP addresses, change the list +separator in the usual way to avoid confusion under IPv6. + &*Note*&: Under current versions of OpenSSL, when a list of more than one file is used, the &$tls_in_ourcert$& veriable is unreliable. + +&*Note*&: OCSP stapling is not usable when a list of more than one file is used. .wen If the option contains &$tls_out_sni$& and Exim is built against OpenSSL, then @@ -17276,6 +17281,11 @@ Certificate Authority. Usable for GnuTLS 3.4.4 or 3.3.17 or OpenSSL 1.1.0 (or later). +.new +&*Note*&: There is currently no support for multiple OCSP proofs to match the +multiple certificates facility. +.wen + .option tls_on_connect_ports main "string list" unset .cindex SSMTP @@ -27650,11 +27660,10 @@ if it requests it. If the server is Exim, it will request a certificate only if If the &%tls_verify_certificates%& option is set on the &(smtp)& transport, it specifies a collection of expected server certificates. -These may be the system default set (depending on library version), -a file or, -depending on library version, a directory, -must name a file or, -for OpenSSL only (not GnuTLS), a directory. +These may be +the system default set (depending on library version), +a file, +or (depending on library version) a directory. The client verifies the server's certificate against this collection, taking into account any revoked certificates that are in the list defined by &%tls_crl%&. @@ -31327,6 +31336,7 @@ address and some time-based randomizing information. The &%prvs%& expansion item creates a signed address, and the &%prvscheck%& expansion item checks one. The syntax of these expansion items is described in section &<>&. +The validity period on signed addresses is seven days. As an example, suppose the secret per-address keys are stored in an MySQL database. A query to look up the key for an address could be defined as a macro @@ -38553,8 +38563,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 @@ -38563,6 +38577,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 @@ -38573,6 +38589,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. @@ -38583,7 +38611,8 @@ After expansion, this can be a list. Each element in turn is put into the &%$dkim_domain%& expansion variable while expanding the remaining signing options. .wen -If it is empty after expansion, DKIM signing is not done. +If it is empty after expansion, DKIM signing is not done, +and no error will result even if &%dkim_strict%& is set. .option dkim_selector smtp string list&!! unset This sets the key selector string. @@ -38592,8 +38621,9 @@ After expansion, which can use &$dkim_domain$&, this can be a list. Each element in turn is put in the expansion variable &%$dkim_selector%& which may be used in the &%dkim_private_key%& option along with &%$dkim_domain%&. -If the option is empty after expansion, DKIM signing is not done for this domain. .wen +If the option is empty after expansion, DKIM signing is not done for this domain, +and no error will result even if &%dkim_strict%& is set. .option dkim_private_key smtp string&!! unset This sets the private key to use. @@ -38610,12 +38640,25 @@ be "0", "false" or the empty string, in which case the message will not be signed. This case will not result in an error, even if &%dkim_strict%& is set. .endlist -If the option is empty after expansion, DKIM signing is not done. .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 @@ -38777,7 +38820,7 @@ DKIM verification. It may of course also mean that the signature is forged. .endlist .new -This variable can be overwritten using an ACL 'set' modifier. +This variable can be overwritten, with any value, using an ACL 'set' modifier. .wen .vitem &%$dkim_domain%& @@ -38796,6 +38839,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'. @@ -38846,6 +38902,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: