X-Git-Url: https://git.exim.org/exim.git/blobdiff_plain/ea792dac9f89e1a0b396e6c8982ff04afafe91be..a79d883474c84fa2a286b7797a7664b599912fcd:/doc/doc-docbook/spec.xfpt?ds=inline diff --git a/doc/doc-docbook/spec.xfpt b/doc/doc-docbook/spec.xfpt index 546a944b6..98986e032 100644 --- a/doc/doc-docbook/spec.xfpt +++ b/doc/doc-docbook/spec.xfpt @@ -12906,6 +12906,11 @@ It is only useful as the argument of a &%certextract%& expansion item, &%md5%&, &%sha1%& or &%sha256%& operator, or a &%def%& condition. +.new +&*Note*&: Under current versions of OpenSSL, when a list of more than one +file is used for &%tls_certificate%&, this variable is not reliable. +.wen + .vitem &$tls_in_peercert$& .vindex "&$tls_in_peercert$&" This variable refers to the certificate presented by the peer of an @@ -17107,11 +17112,15 @@ using the &%tls_certificate%& option. If TLS support for incoming connections is not required the &%tls_advertise_hosts%& option should be set empty. -.option tls_certificate main string&!! unset +.option tls_certificate main string list&!! unset .cindex "TLS" "server certificate; location of" .cindex "certificate" "server, location of" -The value of this option is expanded, and must then be the absolute path to a -file which contains the server's certificates. The server's private key is also +.new +The value of this option is expanded, and must then be a list of absolute paths to +files which contains the server's certificates. Commonly only one file is +needed. +.wen +The server's private key is also assumed to be in this file if &%tls_privatekey%& is unset. See chapter &<>& for further details. @@ -17120,6 +17129,11 @@ receiving incoming messages as a server. If you want to supply certificates for use when sending messages as a client, you must set the &%tls_certificate%& option in the relevant &(smtp)& transport. +.new +&*Note*&: Under current versions of OpenSSL, when a list of more than one +file is used, the &$tls_in_ourcert$& veriable is unreliable. +.wen + If the option contains &$tls_out_sni$& and Exim is built against OpenSSL, then if the OpenSSL build supports TLS extensions and the TLS client sends the Server Name Indication extension, then this option and others documented in @@ -17270,10 +17284,13 @@ further details, see section &<>&. -.option tls_privatekey main string&!! unset +.option tls_privatekey main string list&!! unset .cindex "TLS" "server private key; location of" -The value of this option is expanded, and must then be the absolute path to a -file which contains the server's private key. If this option is unset, or if +.new +The value of this option is expanded, and must then be a list of absolute paths to +files which contains the server's private keys. +.wen +If this option is unset, or if the expansion is forced to fail, or the result is an empty string, the private key is assumed to be in the same file as the server's certificates. See chapter &<>& for further details. @@ -27115,6 +27132,11 @@ When using OpenSSL, this option is ignored. (If an API is found to let OpenSSL be configured in this way, let the Exim Maintainers know and we'll likely use it). .next +.new +With GnuTLS, if an explicit list is used for the &%tls_privatekey%& main option +main option, it must be ordered to match the %&tls_certificate%& list. +.wen +.next Some other recently added features may only be available in one or the other. This should be documented with the feature. If the documentation does not explicitly state that the feature is infeasible in the other TLS @@ -27270,6 +27292,12 @@ tls_require_ciphers = ${if =={$received_port}{25}\ {HIGH:!MD5:!SHA1}} .endd +.new +This example will prefer ECDSA-authenticated ciphers over RSA ones: +.code +tls_require_ciphers = ECDSA:RSA:!COMPLEMENTOFDEFAULT +.endd +.wen .section "Requiring specific ciphers or other parameters in GnuTLS" &&& @@ -27358,8 +27386,7 @@ from someone able to intercept the communication. Further protection requires some further configuration at the server end. -It is rumoured that all existing clients that support TLS/SSL use RSA -encryption. To make this work you need to set, in the server, +To make TLS work you need to set, in the server, .code tls_certificate = /some/file/name tls_privatekey = /some/file/name @@ -27378,6 +27405,15 @@ is assumed to be the case. The certificate file may also contain intermediate certificates that need to be sent to the client to enable it to authenticate the server's certificate. +.new +For dual-stack (eg. RSA and ECDSA) configurations, these options can be +colon-separated lists of file paths. Ciphers using given authentication +algorithms require the presence of a suitable certificate to supply the +public-key. The server selects among the certificates to present to the +client depending on the selected cipher, hence the priority ordering for +ciphers will affect which certificate is used. +.wen + If you do not understand about certificates and keys, please try to find a source of this background information, which is not Exim-specific. (There are a few comments below in section &<>&.) @@ -38695,6 +38731,19 @@ available in &%$dkim_verify_reason%&. &%pass%&: The signature passed verification. It is valid. .endlist +.new +This variable can be overwritten using an ACL 'set' modifier. +This might, for instance, be done to enforce a policy restriction on +hash-method or key-size: +.code + warn condition = ${if eq {$dkim_algo}{rsa-sha1}} + condition = ${if eq {$dkim_verify_status}{pass}} + logwrite = NOTE: forcing dkim verify fail (was pass) + set dkim_verify_status = fail + set dkim_verify_reason = hash too weak +.endd +.wen + .vitem &%$dkim_verify_reason%& A string giving a little bit more detail when &%$dkim_verify_status%& is either "fail" or "invalid". One of @@ -38715,6 +38764,10 @@ 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 +.new +This variable can be overwritten using an ACL 'set' modifier. +.wen + .vitem &%$dkim_domain%& The signing domain. IMPORTANT: This variable is only populated if there is an actual signature in the message for the current domain or identity (as