X-Git-Url: https://git.exim.org/exim.git/blobdiff_plain/f3d8f75105d83b511cf0cf43d3f8b23323d1106b..exim-4_83_RC1:/doc/doc-docbook/spec.xfpt diff --git a/doc/doc-docbook/spec.xfpt b/doc/doc-docbook/spec.xfpt index 7c34bbbc7..990df6241 100644 --- a/doc/doc-docbook/spec.xfpt +++ b/doc/doc-docbook/spec.xfpt @@ -5557,16 +5557,21 @@ unreachable. The next two lines are concerned with &'ident'& callbacks, as defined by RFC 1413 (hence their names): .code -rfc1413_hosts = * -rfc1413_query_timeout = 5s +rfc1413_query_hosts = * +rfc1413_query_timeout = 0s +.endd +These settings cause Exim to avoid ident callbacks for all incoming SMTP calls. +Few hosts offer RFC1413 service these days; calls have to be +terminated by a timeout and this needlessly delays the startup +of an incoming SMTP connection. +If you have hosts for which you trust RFC1413 and need this +information, you can change this. + +This line enables an efficiency SMTP option. It is negociated by clients +and not expected to cause problems but can be disabled if needed. +.code +prdr_enable = true .endd -These settings cause Exim to make ident callbacks for all incoming SMTP calls. -You can limit the hosts to which these calls are made, or change the timeout -that is used. If you set the timeout to zero, all ident calls are disabled. -Although they are cheap and can provide useful information for tracing problem -messages, some hosts and firewalls have problems with ident calls. This can -result in a timeout instead of an immediate refused connection, leading to -delays on starting up an incoming SMTP session. When Exim receives messages over SMTP connections, it expects all addresses to be fully qualified with a domain, as required by the SMTP definition. However, @@ -6002,9 +6007,14 @@ One remote transport and four local transports are defined. .code remote_smtp: driver = smtp + hosts_try_prdr = * .endd -This transport is used for delivering messages over SMTP connections. All its -options are defaulted. The list of remote hosts comes from the router. +This transport is used for delivering messages over SMTP connections. +The list of remote hosts comes from the router. +The &%hosts_try_prdr%& option enables an efficiency SMTP option. +It is negotiated between client and server +and not expected to cause problems but can be disabled if needed. +All other options are defaulted. .code local_delivery: driver = appendfile @@ -8887,10 +8897,10 @@ the certificate. Supported fields are: .display &`version `& &`serial_number `& -&`subject `& -&`issuer `& -&`notbefore `& -&`notafter `& +&`subject `& RFC4514 DN +&`issuer `& RFC4514 DN +&`notbefore `& time +&`notafter `& time &`sig_algorithm `& &`signature `& &`subj_altname `& tagged list @@ -8909,6 +8919,22 @@ extracted is used. Some field names take optional modifiers, appended and separated by commas. +The field selectors marked as "RFC4514" above +output a Distinguished Name string which is +not quite +parseable by Exim as a comma-separated tagged list +(the exceptions being elements containin commas). +RDN elements of a single type may be selected by +a modifier of the type label; if so the expansion +result is a list (newline-separated by default). +The separator may be changed by another modifer of +a right angle-bracket followed immediately by the new separator. +Recognised RDN type labels include "CN", "O", "OU" and "DC". + +The field selectors marked as "time" above +may output a number of seconds since epoch +if the modifier "int" is used. + The field selectors marked as "list" above return a list, newline-separated by default, (embedded separator characters in elements are doubled). @@ -8921,7 +8947,7 @@ Elements of only one type may be selected by a modifier which is one of "dns", "uri" or "mail"; if so the elenment tags are omitted. -Field values are generally presented in human-readable form. +If not otherwise noted field values are presented in human-readable form. .wen .vitem "&*${dlfunc{*&<&'file'&>&*}{*&<&'function'&>&*}{*&<&'arg'&>&*}&&& @@ -13196,6 +13222,7 @@ listed in more than one group. .row &%tls_crl%& "certificate revocation list" .row &%tls_dh_max_bits%& "clamp D-H bit count suggestion" .row &%tls_dhparam%& "DH parameters for server" +.row &%tls_ocsp_file%& "location of server certificate status proof" .row &%tls_on_connect_ports%& "specify SSMTP (SMTPS) ports" .row &%tls_privatekey%& "location of server private key" .row &%tls_remember_esmtp%& "don't reset after starting TLS" @@ -16315,6 +16342,13 @@ prior to the 4.80 release, as Debian used to patch Exim to raise the minimum acceptable bound from 1024 to 2048. +.option tls_ocsp_file main string&!! unset +This option +must if set expand to the absolute path to a file which contains a current +status proof for the server's certificate, as obtained from the +Certificate Authority. + + .option tls_on_connect_ports main "string list" unset This option specifies a list of incoming SSMTP (aka SMTPS) ports that should operate the obsolete SSMTP (SMTPS) protocol, where a TLS session is immediately @@ -22979,6 +23013,18 @@ hard failure if required. See also &%hosts_try_auth%&, and chapter &<>& for details of authentication. +.option hosts_request_ocsp smtp "host list&!!" * +.cindex "TLS" "requiring for certain servers" +Exim will request a Certificate Status on a +TLS session for any host that matches this list. +&%tls_verify_certificates%& should also be set for the transport. + +.option hosts_require_ocsp smtp "host list&!!" unset +.cindex "TLS" "requiring for certain servers" +Exim will request, and check for a valid Certificate Status being given, on a +TLS session for any host that matches this list. +&%tls_verify_certificates%& should also be set for the transport. + .option hosts_require_tls smtp "host list&!!" unset .cindex "TLS" "requiring for certain servers" Exim will insist on using a TLS session when delivering to any host that @@ -23256,6 +23302,11 @@ in clear. This option gives a list of hosts for which, on encrypted connections, certificate verification will be tried but need not succeed. The &%tls_verify_certificates%& option must also be set. +Note that unless the host is in this list +TLS connections will be denied to hosts using self-signed certificates +when &%tls_verify_certificates%& is set. +The &$tls_out_certificate_verified$& variable is set when +certificate verification succeeds. .option tls_verify_certificates smtp string&!! unset @@ -25342,7 +25393,7 @@ dovecot_plain: driver = dovecot public_name = PLAIN server_socket = /var/run/dovecot/auth-client - server_set_id = $auth2 + server_set_id = $auth1 dovecot_ntlm: driver = dovecot @@ -26133,12 +26184,79 @@ certificate is supplied, &$tls_in_peerdn$& is empty. .cindex "TLS" "revoked certificates" .cindex "revocation list" .cindex "certificate" "revocation list" +.cindex "OCSP" "stapling" Certificate issuing authorities issue Certificate Revocation Lists (CRLs) when certificates are revoked. If you have such a list, you can pass it to an Exim server using the global option called &%tls_crl%& and to an Exim client using an identically named option for the &(smtp)& transport. In each case, the value of the option is expanded and must then be the name of a file that contains a CRL in PEM format. +The downside is that clients have to periodically re-download a potentially huge +file from every certificate authority the know of. + +The way with most moving parts at query time is Online Certificate +Status Protocol (OCSP), where the client verifies the certificate +against an OCSP server run by the CA. This lets the CA track all +usage of the certs. It requires running software with access to the +private key of the CA, to sign the responses to the OCSP queries. OCSP +is based on HTTP and can be proxied accordingly. + +The only widespread OCSP server implementation (known to this writer) +comes as part of OpenSSL and aborts on an invalid request, such as +connecting to the port and then disconnecting. This requires +re-entering the passphrase each time some random client does this. + +The third way is OCSP Stapling; in this, the server using a certificate +issued by the CA periodically requests an OCSP proof of validity from +the OCSP server, then serves it up inline as part of the TLS +negotiation. This approach adds no extra round trips, does not let the +CA track users, scales well with number of certs issued by the CA and is +resilient to temporary OCSP server failures, as long as the server +starts retrying to fetch an OCSP proof some time before its current +proof expires. The downside is that it requires server support. + +Unless Exim is built with the support disabled, +or with GnuTLS earlier than version 3.1.3, +support for OCSP stapling is included. + +There is a global option called &%tls_ocsp_file%&. +The file specified therein is expected to be in DER format, and contain +an OCSP proof. Exim will serve it as part of the TLS handshake. This +option will be re-expanded for SNI, if the &%tls_certificate%& option +contains &`tls_in_sni`&, as per other TLS options. + +Exim does not at this time implement any support for fetching a new OCSP +proof. The burden is on the administrator to handle this, outside of +Exim. The file specified should be replaced atomically, so that the +contents are always valid. Exim will expand the &%tls_ocsp_file%& option +on each connection, so a new file will be handled transparently on the +next connection. + +When built with OpenSSL Exim will check for a valid next update timestamp +in the OCSP proof; if not present, or if the proof has expired, it will be +ignored. + +For the client to be able to verify the stapled OCSP the server must +also supply, in its stapled information, any intermediate +certificates for the chain leading to the OCSP proof from the signer +of the server certificate. There may be zero or one such. These +intermediate certificates should be added to the server OCSP stapling +file named by &%tls_ocsp_file%&. + +Note that the proof only covers the terminal server certificate, +not any of the chain from CA to it. + +.code + A helper script "ocsp_fetch.pl" for fetching a proof from a CA + OCSP server is supplied. The server URL may be included in the + server certificate, if the CA is helpful. + + One failure mode seen was the OCSP Signer cert expiring before the end + of validity of the OCSP proof. The checking done by Exim/OpenSSL + noted this as invalid overall, but the re-fetch script did not. +.endd + + .section "Configuring an Exim client to use TLS" "SECID185" @@ -26194,6 +26312,19 @@ The &%tls_verify_hosts%& and &%tls_try_verify_hosts%& options restrict certificate verification to the listed servers. Verification either must or need not succeed respectively. +The &(smtp)& transport has two OCSP-related options: +&%hosts_require_ocsp%&; a host-list for which a Certificate Status +is requested and required for the connection to proceed. The default +value is empty. +&%hosts_request_ocsp%&; a host-list for which (additionally) +a Certificate Status is requested (but not necessarily verified). The default +value is "*" meaning that requests are made unless configured +otherwise. + +The host(s) should also be in &%hosts_require_tls%&, and +&%tls_verify_certificates%& configured for the transport, +for OCSP to be relevant. + If &%tls_require_ciphers%& is set on the &(smtp)& transport, it must contain a list of permitted cipher suites. If either of these checks fails, delivery to @@ -26279,6 +26410,9 @@ during TLS session handshake, to permit alternative values to be chosen: .next .vindex "&%tls_verify_certificates%&" &%tls_verify_certificates%& +.next +.vindex "&%tls_ocsp_file%&" +&%tls_verify_certificates%& .endlist Great care should be taken to deal with matters of case, various injection @@ -26663,6 +26797,8 @@ See also the &%prdr_enable%& global option and the &%hosts_try_prdr%& smtp transport option. This ACL is evaluated after &%acl_smtp_dkim%& but before &%acl_smtp_data%&. +If the ACL is not defined, processing completes as if +the feature was not requested by the client. .section "The QUIT ACL" "SECTQUITACL" .cindex "QUIT, ACL for"