diff options
Diffstat (limited to '')
| -rw-r--r-- | man/man8/tlsproxy.8 | 383 |
1 files changed, 383 insertions, 0 deletions
diff --git a/man/man8/tlsproxy.8 b/man/man8/tlsproxy.8 new file mode 100644 index 0000000..0e66496 --- /dev/null +++ b/man/man8/tlsproxy.8 @@ -0,0 +1,383 @@ +.TH TLSPROXY 8 +.ad +.fi +.SH NAME +tlsproxy +\- +Postfix TLS proxy +.SH "SYNOPSIS" +.na +.nf +\fBtlsproxy\fR [generic Postfix daemon options] +.SH DESCRIPTION +.ad +.fi +The \fBtlsproxy\fR(8) server implements a two\-way TLS proxy. It +is used by the \fBpostscreen\fR(8) server to talk SMTP\-over\-TLS +with remote SMTP clients that are not whitelisted (including +clients whose whitelist status has expired), and by the +\fBsmtp\fR(8) client to support TLS connection reuse, but it +should also work for non\-SMTP protocols. + +Although one \fBtlsproxy\fR(8) process can serve multiple +sessions at the same time, it is a good idea to allow the +number of processes to increase with load, so that the +service remains responsive. +.SH "PROTOCOL EXAMPLE" +.na +.nf +.ad +.fi +The example below concerns \fBpostscreen\fR(8). However, +the \fBtlsproxy\fR(8) server is agnostic of the application +protocol, and the example is easily adapted to other +applications. + +After receiving a valid remote SMTP client STARTTLS command, +the \fBpostscreen\fR(8) server sends the remote SMTP client +endpoint string, the requested role (server), and the +requested timeout to \fBtlsproxy\fR(8). \fBpostscreen\fR(8) +then receives a "TLS available" indication from \fBtlsproxy\fR(8). +If the TLS service is available, \fBpostscreen\fR(8) sends +the remote SMTP client file descriptor to \fBtlsproxy\fR(8), +and sends the plaintext 220 greeting to the remote SMTP +client. This triggers TLS negotiations between the remote +SMTP client and \fBtlsproxy\fR(8). Upon completion of the +TLS\-level handshake, \fBtlsproxy\fR(8) translates between +plaintext from/to \fBpostscreen\fR(8) and ciphertext to/from +the remote SMTP client. +.SH "SECURITY" +.na +.nf +.ad +.fi +The \fBtlsproxy\fR(8) server is moderately security\-sensitive. +It talks to untrusted clients on the network. The process +can be run chrooted at fixed low privilege. +.SH DIAGNOSTICS +.ad +.fi +Problems and transactions are logged to \fBsyslogd\fR(8) +or \fBpostlogd\fR(8). +.SH "CONFIGURATION PARAMETERS" +.na +.nf +.ad +.fi +Changes to \fBmain.cf\fR are not picked up automatically, +as \fBtlsproxy\fR(8) processes may run for a long time +depending on mail server load. Use the command "\fBpostfix +reload\fR" to speed up a change. + +The text below provides only a parameter summary. See +\fBpostconf\fR(5) for more details including examples. +.SH "STARTTLS GLOBAL CONTROLS" +.na +.nf +.ad +.fi +The following settings are global and therefore cannot be +overruled by information specified in a \fBtlsproxy\fR(8) +client request. +.IP "\fBtls_append_default_CA (no)\fR" +Append the system\-supplied default Certification Authority +certificates to the ones specified with *_tls_CApath or *_tls_CAfile. +.IP "\fBtls_daemon_random_bytes (32)\fR" +The number of pseudo\-random bytes that an \fBsmtp\fR(8) or \fBsmtpd\fR(8) +process requests from the \fBtlsmgr\fR(8) server in order to seed its +internal pseudo random number generator (PRNG). +.IP "\fBtls_high_cipherlist (see 'postconf -d' output)\fR" +The OpenSSL cipherlist for "high" grade ciphers. +.IP "\fBtls_medium_cipherlist (see 'postconf -d' output)\fR" +The OpenSSL cipherlist for "medium" or higher grade ciphers. +.IP "\fBtls_low_cipherlist (see 'postconf -d' output)\fR" +The OpenSSL cipherlist for "low" or higher grade ciphers. +.IP "\fBtls_export_cipherlist (see 'postconf -d' output)\fR" +The OpenSSL cipherlist for "export" or higher grade ciphers. +.IP "\fBtls_null_cipherlist (eNULL:!aNULL)\fR" +The OpenSSL cipherlist for "NULL" grade ciphers that provide +authentication without encryption. +.IP "\fBtls_eecdh_strong_curve (prime256v1)\fR" +The elliptic curve used by the Postfix SMTP server for sensibly +strong +ephemeral ECDH key exchange. +.IP "\fBtls_eecdh_ultra_curve (secp384r1)\fR" +The elliptic curve used by the Postfix SMTP server for maximally +strong +ephemeral ECDH key exchange. +.IP "\fBtls_disable_workarounds (see 'postconf -d' output)\fR" +List or bit\-mask of OpenSSL bug work\-arounds to disable. +.IP "\fBtls_preempt_cipherlist (no)\fR" +With SSLv3 and later, use the Postfix SMTP server's cipher +preference order instead of the remote client's cipher preference +order. +.PP +Available in Postfix version 2.9 and later: +.IP "\fBtls_legacy_public_key_fingerprints (no)\fR" +A temporary migration aid for sites that use certificate +\fIpublic\-key\fR fingerprints with Postfix 2.9.0..2.9.5, which use +an incorrect algorithm. +.PP +Available in Postfix version 2.11\-3.1: +.IP "\fBtls_dane_digest_agility (on)\fR" +Configure RFC7671 DANE TLSA digest algorithm agility. +.IP "\fBtls_dane_trust_anchor_digest_enable (yes)\fR" +Enable support for RFC 6698 (DANE TLSA) DNS records that contain +digests of trust\-anchors with certificate usage "2". +.PP +Available in Postfix version 2.11 and later: +.IP "\fBtlsmgr_service_name (tlsmgr)\fR" +The name of the \fBtlsmgr\fR(8) service entry in master.cf. +.PP +Available in Postfix version 3.0 and later: +.IP "\fBtls_session_ticket_cipher (Postfix >= 3.0: aes\-256\-cbc, Postfix < 3.0: aes\-128\-cbc)\fR" +Algorithm used to encrypt RFC5077 TLS session tickets. +.IP "\fBopenssl_path (openssl)\fR" +The location of the OpenSSL command line program \fBopenssl\fR(1). +.PP +Available in Postfix version 3.2 and later: +.IP "\fBtls_eecdh_auto_curves (see 'postconf -d' output)\fR" +The prioritized list of elliptic curves supported by the Postfix +SMTP client and server. +.PP +Available in Postfix version 3.4 and later: +.IP "\fBtls_server_sni_maps (empty)\fR" +Optional lookup tables that map names received from remote SMTP +clients via the TLS Server Name Indication (SNI) extension to the +appropriate keys and certificate chains. +.SH "STARTTLS SERVER CONTROLS" +.na +.nf +.ad +.fi +These settings are clones of Postfix SMTP server settings. +They allow \fBtlsproxy\fR(8) to load the same certificate +and private key information as the Postfix SMTP server, +before dropping privileges, so that the key files can be +kept read\-only for root. These settings can currently not +be overruled by information in a \fBtlsproxy\fR(8) client +request, but that limitation may be removed in a future +version. +.IP "\fBtlsproxy_tls_CAfile ($smtpd_tls_CAfile)\fR" +A file containing (PEM format) CA certificates of root CAs +trusted to sign either remote SMTP client certificates or intermediate +CA certificates. +.IP "\fBtlsproxy_tls_CApath ($smtpd_tls_CApath)\fR" +A directory containing (PEM format) CA certificates of root CAs +trusted to sign either remote SMTP client certificates or intermediate +CA certificates. +.IP "\fBtlsproxy_tls_always_issue_session_ids ($smtpd_tls_always_issue_session_ids)\fR" +Force the Postfix \fBtlsproxy\fR(8) server to issue a TLS session id, +even when TLS session caching is turned off. +.IP "\fBtlsproxy_tls_ask_ccert ($smtpd_tls_ask_ccert)\fR" +Ask a remote SMTP client for a client certificate. +.IP "\fBtlsproxy_tls_ccert_verifydepth ($smtpd_tls_ccert_verifydepth)\fR" +The verification depth for remote SMTP client certificates. +.IP "\fBtlsproxy_tls_cert_file ($smtpd_tls_cert_file)\fR" +File with the Postfix \fBtlsproxy\fR(8) server RSA certificate in PEM +format. +.IP "\fBtlsproxy_tls_ciphers ($smtpd_tls_ciphers)\fR" +The minimum TLS cipher grade that the Postfix \fBtlsproxy\fR(8) server +will use with opportunistic TLS encryption. +.IP "\fBtlsproxy_tls_dcert_file ($smtpd_tls_dcert_file)\fR" +File with the Postfix \fBtlsproxy\fR(8) server DSA certificate in PEM +format. +.IP "\fBtlsproxy_tls_dh1024_param_file ($smtpd_tls_dh1024_param_file)\fR" +File with DH parameters that the Postfix \fBtlsproxy\fR(8) server +should use with non\-export EDH ciphers. +.IP "\fBtlsproxy_tls_dh512_param_file ($smtpd_tls_dh512_param_file)\fR" +File with DH parameters that the Postfix \fBtlsproxy\fR(8) server +should use with export\-grade EDH ciphers. +.IP "\fBtlsproxy_tls_dkey_file ($smtpd_tls_dkey_file)\fR" +File with the Postfix \fBtlsproxy\fR(8) server DSA private key in PEM +format. +.IP "\fBtlsproxy_tls_eccert_file ($smtpd_tls_eccert_file)\fR" +File with the Postfix \fBtlsproxy\fR(8) server ECDSA certificate in PEM +format. +.IP "\fBtlsproxy_tls_eckey_file ($smtpd_tls_eckey_file)\fR" +File with the Postfix \fBtlsproxy\fR(8) server ECDSA private key in PEM +format. +.IP "\fBtlsproxy_tls_eecdh_grade ($smtpd_tls_eecdh_grade)\fR" +The Postfix \fBtlsproxy\fR(8) server security grade for ephemeral +elliptic\-curve Diffie\-Hellman (EECDH) key exchange. +.IP "\fBtlsproxy_tls_exclude_ciphers ($smtpd_tls_exclude_ciphers)\fR" +List of ciphers or cipher types to exclude from the \fBtlsproxy\fR(8) +server cipher list at all TLS security levels. +.IP "\fBtlsproxy_tls_fingerprint_digest ($smtpd_tls_fingerprint_digest)\fR" +The message digest algorithm to construct remote SMTP +client\-certificate +fingerprints. +.IP "\fBtlsproxy_tls_key_file ($smtpd_tls_key_file)\fR" +File with the Postfix \fBtlsproxy\fR(8) server RSA private key in PEM +format. +.IP "\fBtlsproxy_tls_loglevel ($smtpd_tls_loglevel)\fR" +Enable additional Postfix \fBtlsproxy\fR(8) server logging of TLS +activity. +.IP "\fBtlsproxy_tls_mandatory_ciphers ($smtpd_tls_mandatory_ciphers)\fR" +The minimum TLS cipher grade that the Postfix \fBtlsproxy\fR(8) server +will use with mandatory TLS encryption. +.IP "\fBtlsproxy_tls_mandatory_exclude_ciphers ($smtpd_tls_mandatory_exclude_ciphers)\fR" +Additional list of ciphers or cipher types to exclude from the +\fBtlsproxy\fR(8) server cipher list at mandatory TLS security levels. +.IP "\fBtlsproxy_tls_mandatory_protocols ($smtpd_tls_mandatory_protocols)\fR" +The SSL/TLS protocols accepted by the Postfix \fBtlsproxy\fR(8) server +with mandatory TLS encryption. +.IP "\fBtlsproxy_tls_protocols ($smtpd_tls_protocols)\fR" +List of TLS protocols that the Postfix \fBtlsproxy\fR(8) server will +exclude or include with opportunistic TLS encryption. +.IP "\fBtlsproxy_tls_req_ccert ($smtpd_tls_req_ccert)\fR" +With mandatory TLS encryption, require a trusted remote SMTP +client certificate in order to allow TLS connections to proceed. +.IP "\fBtlsproxy_tls_security_level ($smtpd_tls_security_level)\fR" +The SMTP TLS security level for the Postfix \fBtlsproxy\fR(8) server; +when a non\-empty value is specified, this overrides the obsolete +parameters smtpd_use_tls and smtpd_enforce_tls. +.IP "\fBtlsproxy_tls_chain_files ($smtpd_tls_chain_files)\fR" +Files with the Postfix \fBtlsproxy\fR(8) server keys and certificate +chains in PEM format. +.SH "STARTTLS CLIENT CONTROLS" +.na +.nf +.ad +.fi +These settings are clones of Postfix SMTP client settings. +They allow \fBtlsproxy\fR(8) to load the same certificate +and private key information as the Postfix SMTP client, +before dropping privileges, so that the key files can be +kept read\-only for root. Some settings may be overruled by +information in a \fBtlsproxy\fR(8) client request. +.PP +Available in Postfix version 3.4 and later: +.IP "\fBtlsproxy_client_CAfile ($smtp_tls_CAfile)\fR" +A file containing CA certificates of root CAs trusted to sign +either remote TLS server certificates or intermediate CA certificates. +.IP "\fBtlsproxy_client_CApath ($smtp_tls_CApath)\fR" +Directory with PEM format Certification Authority certificates +that the Postfix \fBtlsproxy\fR(8) client uses to verify a remote TLS +server certificate. +.IP "\fBtlsproxy_client_chain_files ($smtp_tls_chain_files)\fR" +Files with the Postfix \fBtlsproxy\fR(8) client keys and certificate +chains in PEM format. +.IP "\fBtlsproxy_client_cert_file ($smtp_tls_cert_file)\fR" +File with the Postfix \fBtlsproxy\fR(8) client RSA certificate in PEM +format. +.IP "\fBtlsproxy_client_key_file ($smtp_tls_key_file)\fR" +File with the Postfix \fBtlsproxy\fR(8) client RSA private key in PEM +format. +.IP "\fBtlsproxy_client_dcert_file ($smtp_tls_dcert_file)\fR" +File with the Postfix \fBtlsproxy\fR(8) client DSA certificate in PEM +format. +.IP "\fBtlsproxy_client_dkey_file ($smtp_tls_dkey_file)\fR" +File with the Postfix \fBtlsproxy\fR(8) client DSA private key in PEM +format. +.IP "\fBtlsproxy_client_eccert_file ($smtp_tls_eccert_file)\fR" +File with the Postfix \fBtlsproxy\fR(8) client ECDSA certificate in PEM +format. +.IP "\fBtlsproxy_client_eckey_file ($smtp_tls_eckey_file)\fR" +File with the Postfix \fBtlsproxy\fR(8) client ECDSA private key in PEM +format. +.IP "\fBtlsproxy_client_fingerprint_digest ($smtp_tls_fingerprint_digest)\fR" +The message digest algorithm used to construct remote TLS server +certificate fingerprints. +.IP "\fBtlsproxy_client_loglevel ($smtp_tls_loglevel)\fR" +Enable additional Postfix \fBtlsproxy\fR(8) client logging of TLS +activity. +.IP "\fBtlsproxy_client_loglevel_parameter (smtp_tls_loglevel)\fR" +The name of the parameter that provides the tlsproxy_client_loglevel +value. +.IP "\fBtlsproxy_client_scert_verifydepth ($smtp_tls_scert_verifydepth)\fR" +The verification depth for remote TLS server certificates. +.IP "\fBtlsproxy_client_security_level ($smtp_tls_security_level)\fR" +The default TLS security level for the Postfix \fBtlsproxy\fR(8) +client. +.IP "\fBtlsproxy_client_policy_maps ($smtp_tls_policy_maps)\fR" +Optional lookup tables with the Postfix \fBtlsproxy\fR(8) client TLS +security policy by next\-hop destination. +.IP "\fBtlsproxy_client_use_tls ($smtp_use_tls)\fR" +Opportunistic mode: use TLS when a remote server announces TLS +support. +.IP "\fBtlsproxy_client_enforce_tls ($smtp_enforce_tls)\fR" +Enforcement mode: require that SMTP servers use TLS encryption. +.IP "\fBtlsproxy_client_per_site ($smtp_tls_per_site)\fR" +Optional lookup tables with the Postfix \fBtlsproxy\fR(8) client TLS +usage policy by next\-hop destination and by remote TLS server +hostname. +.PP +Introduced with Postfix 3.4.6, 3.3.5, 3.2.10, and 3.1.13: +.IP "\fBtls_fast_shutdown_enable (yes)\fR" +A workaround for implementations that hang Postfix while shuting +down a TLS session, until Postfix times out. +.SH "OBSOLETE STARTTLS SUPPORT CONTROLS" +.na +.nf +.ad +.fi +These parameters are supported for compatibility with +\fBsmtpd\fR(8) legacy parameters. +.IP "\fBtlsproxy_use_tls ($smtpd_use_tls)\fR" +Opportunistic TLS: announce STARTTLS support to remote SMTP clients, +but do not require that clients use TLS encryption. +.IP "\fBtlsproxy_enforce_tls ($smtpd_enforce_tls)\fR" +Mandatory TLS: announce STARTTLS support to remote SMTP clients, and +require that clients use TLS encryption. +.SH "RESOURCE CONTROLS" +.na +.nf +.ad +.fi +.IP "\fBtlsproxy_watchdog_timeout (10s)\fR" +How much time a \fBtlsproxy\fR(8) process may take to process local +or remote I/O before it is terminated by a built\-in watchdog timer. +.SH "MISCELLANEOUS CONTROLS" +.na +.nf +.ad +.fi +.IP "\fBconfig_directory (see 'postconf -d' output)\fR" +The default location of the Postfix main.cf and master.cf +configuration files. +.IP "\fBprocess_id (read\-only)\fR" +The process ID of a Postfix command or daemon process. +.IP "\fBprocess_name (read\-only)\fR" +The process name of a Postfix command or daemon process. +.IP "\fBsyslog_facility (mail)\fR" +The syslog facility of Postfix logging. +.IP "\fBsyslog_name (see 'postconf -d' output)\fR" +A prefix that is prepended to the process name in syslog +records, so that, for example, "smtpd" becomes "prefix/smtpd". +.PP +Available in Postfix 3.3 and later: +.IP "\fBservice_name (read\-only)\fR" +The master.cf service name of a Postfix daemon process. +.SH "SEE ALSO" +.na +.nf +postscreen(8), Postfix zombie blocker +smtpd(8), Postfix SMTP server +postconf(5), configuration parameters +postlogd(8), Postfix logging +syslogd(8), system logging +.SH "LICENSE" +.na +.nf +.ad +.fi +The Secure Mailer license must be distributed with this software. +.SH HISTORY +.ad +.fi +.ad +.fi +This service was introduced with Postfix version 2.8. +.SH "AUTHOR(S)" +.na +.nf +Wietse Venema +IBM T.J. Watson Research +P.O. Box 704 +Yorktown Heights, NY 10598, USA + +Wietse Venema +Google, Inc. +111 8th Avenue +New York, NY 10011, USA |