--- name: "tlsproxy" section: "8" platform: "macos" package: "postfix" version: "1636" release: "macOS 26.5" platforms: ["linux", "macos"] url: "https://new.carta.tech/tlsproxy" --- # tlsproxy(8) Postfix TLS proxy ## NAME tlsproxy - Postfix TLS proxy ## SYNOPSIS ``` tlsproxy [generic Postfix daemon options] ``` ## DESCRIPTION The [**tlsproxy**(8)](/tlsproxy/8.md) server implements a server-side TLS proxy. It is used by [**postscreen**(8)](/postscreen/8.md) to talk SMTP-over-TLS with remote SMTP clients that are not whitelisted (including clients whose whitelist status has expired), but it should also work for non-SMTP protocols. Although one [**tlsproxy**(8)](/tlsproxy/8.md) 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. ## PROTOCOL EXAMPLE ``` ``` The example below concerns [**postscreen**(8)](/postscreen/8.md). However, the [**tlsproxy**(8)](/tlsproxy/8.md) 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 [**postscreen**(8)](/postscreen/8.md) server sends the remote SMTP client endpoint string, the requested role (server), and the requested timeout to [**tlsproxy**(8)](/tlsproxy/8.md). [**postscreen**(8)](/postscreen/8.md) then receives a "TLS available" indication from [**tlsproxy**(8)](/tlsproxy/8.md). If the TLS service is available, [**postscreen**(8)](/postscreen/8.md) sends the remote SMTP client file descriptor to [**tlsproxy**(8)](/tlsproxy/8.md), and sends the plaintext 220 greeting to the remote SMTP client. This triggers TLS negotiations between the remote SMTP client and [**tlsproxy**(8)](/tlsproxy/8.md). Upon completion of the TLS-level handshake, [**tlsproxy**(8)](/tlsproxy/8.md) translates between plaintext from/to [**postscreen**(8)](/postscreen/8.md) and ciphertext to/from the remote SMTP client. ## SECURITY ``` ``` The [**tlsproxy**(8)](/tlsproxy/8.md) server is moderately security-sensitive. It talks to untrusted clients on the network. The process can be run chrooted at fixed low privilege. ## DIAGNOSTICS Problems and transactions are logged to [**syslogd**(8)](/syslogd/8.md). ## CONFIGURATION PARAMETERS ``` ``` Changes to **main.cf** are not picked up automatically, as [**tlsproxy**(8)](/tlsproxy/8.md) processes may run for a long time depending on mail server load. Use the command "**postfix** **reload**" to speed up a change. The text below provides only a parameter summary. See [**postconf**(5)](/postconf/5.md) for more details including examples. ## STARTTLS SUPPORT CONTROLS ``` ``` - **tlsproxy\_tls\_CAfile ($smtpd\_tls\_CAfile)** A file containing (PEM format) CA certificates of root CAs trusted to sign either remote SMTP client certificates or intermediate CA certificates. - **tlsproxy\_tls\_CApath ($smtpd\_tls\_CApath)** A directory containing (PEM format) CA certificates of root CAs trusted to sign either remote SMTP client certificates or intermediate CA certificates. - **tlsproxy\_tls\_always\_issue\_session\_ids ($smtpd\_tls\_always\_issue\_session\_ids)** Force the Postfix [**tlsproxy**(8)](/tlsproxy/8.md) server to issue a TLS session id, even when TLS session caching is turned off. - **tlsproxy\_tls\_ask\_ccert ($smtpd\_tls\_ask\_ccert)** Ask a remote SMTP client for a client certificate. - **tlsproxy\_tls\_ccert\_verifydepth ($smtpd\_tls\_ccert\_verifydepth)** The verification depth for remote SMTP client certificates. - **tlsproxy\_tls\_cert\_file ($smtpd\_tls\_cert\_file)** File with the Postfix [**tlsproxy**(8)](/tlsproxy/8.md) server RSA certificate in PEM format. - **tlsproxy\_tls\_ciphers ($smtpd\_tls\_ciphers)** The minimum TLS cipher grade that the Postfix [**tlsproxy**(8)](/tlsproxy/8.md) server will use with opportunistic TLS encryption. - **tlsproxy\_tls\_dcert\_file ($smtpd\_tls\_dcert\_file)** File with the Postfix [**tlsproxy**(8)](/tlsproxy/8.md) server DSA certificate in PEM format. - **tlsproxy\_tls\_dh1024\_param\_file ($smtpd\_tls\_dh1024\_param\_file)** File with DH parameters that the Postfix [**tlsproxy**(8)](/tlsproxy/8.md) server should use with non-export EDH ciphers. - **tlsproxy\_tls\_dh512\_param\_file ($smtpd\_tls\_dh512\_param\_file)** File with DH parameters that the Postfix [**tlsproxy**(8)](/tlsproxy/8.md) server should use with export-grade EDH ciphers. - **tlsproxy\_tls\_dkey\_file ($smtpd\_tls\_dkey\_file)** File with the Postfix [**tlsproxy**(8)](/tlsproxy/8.md) server DSA private key in PEM format. - **tlsproxy\_tls\_eccert\_file ($smtpd\_tls\_eccert\_file)** File with the Postfix [**tlsproxy**(8)](/tlsproxy/8.md) server ECDSA certificate in PEM format. - **tlsproxy\_tls\_eckey\_file ($smtpd\_tls\_eckey\_file)** File with the Postfix [**tlsproxy**(8)](/tlsproxy/8.md) server ECDSA private key in PEM format. - **tlsproxy\_tls\_eecdh\_grade ($smtpd\_tls\_eecdh\_grade)** The Postfix [**tlsproxy**(8)](/tlsproxy/8.md) server security grade for ephemeral elliptic-curve Diffie-Hellman (EECDH) key exchange. - **tlsproxy\_tls\_exclude\_ciphers ($smtpd\_tls\_exclude\_ciphers)** List of ciphers or cipher types to exclude from the [**tlsproxy**(8)](/tlsproxy/8.md) server cipher list at all TLS security levels. - **tlsproxy\_tls\_fingerprint\_digest ($smtpd\_tls\_fingerprint\_digest)** The message digest algorithm to construct remote SMTP client-certificate fingerprints. - **tlsproxy\_tls\_key\_file ($smtpd\_tls\_key\_file)** File with the Postfix [**tlsproxy**(8)](/tlsproxy/8.md) server RSA private key in PEM format. - **tlsproxy\_tls\_loglevel ($smtpd\_tls\_loglevel)** Enable additional Postfix [**tlsproxy**(8)](/tlsproxy/8.md) server logging of TLS activity. - **tlsproxy\_tls\_mandatory\_ciphers ($smtpd\_tls\_mandatory\_ciphers)** The minimum TLS cipher grade that the Postfix [**tlsproxy**(8)](/tlsproxy/8.md) server will use with mandatory TLS encryption. - **tlsproxy\_tls\_mandatory\_exclude\_ciphers ($smtpd\_tls\_mandatory\_exclude\_ciphers)** Additional list of ciphers or cipher types to exclude from the [**tlsproxy**(8)](/tlsproxy/8.md) server cipher list at mandatory TLS security levels. - **tlsproxy\_tls\_mandatory\_protocols ($smtpd\_tls\_mandatory\_protocols)** The SSL/TLS protocols accepted by the Postfix [**tlsproxy**(8)](/tlsproxy/8.md) server with mandatory TLS encryption. - **tlsproxy\_tls\_protocols ($smtpd\_tls\_protocols)** List of TLS protocols that the Postfix [**tlsproxy**(8)](/tlsproxy/8.md) server will exclude or include with opportunistic TLS encryption. - **tlsproxy\_tls\_req\_ccert ($smtpd\_tls\_req\_ccert)** With mandatory TLS encryption, require a trusted remote SMTP client certificate in order to allow TLS connections to proceed. - **tlsproxy\_tls\_security\_level ($smtpd\_tls\_security\_level)** The SMTP TLS security level for the Postfix [**tlsproxy**(8)](/tlsproxy/8.md) server; when a non-empty value is specified, this overrides the obsolete parameters smtpd\_use\_tls and smtpd\_enforce\_tls. Available in Postfix version 2.11 and later: - **tlsmgr\_service\_name (tlsmgr)** The name of the [**tlsmgr**(8)](/tlsmgr/8.md) service entry in master.cf. ## OBSOLETE STARTTLS SUPPORT CONTROLS ``` ``` These parameters are supported for compatibility with [**smtpd**(8)](/smtpd/8.md) legacy parameters. - **tlsproxy\_use\_tls ($smtpd\_use\_tls)** Opportunistic TLS: announce STARTTLS support to remote SMTP clients, but do not require that clients use TLS encryption. - **tlsproxy\_enforce\_tls ($smtpd\_enforce\_tls)** Mandatory TLS: announce STARTTLS support to remote SMTP clients, and require that clients use TLS encryption. ## RESOURCE CONTROLS ``` ``` - **tlsproxy\_watchdog\_timeout (10s)** How much time a [**tlsproxy**(8)](/tlsproxy/8.md) process may take to process local or remote I/O before it is terminated by a built-in watchdog timer. ## MISCELLANEOUS CONTROLS ``` ``` - **config\_directory (see 'postconf -d' output)** The default location of the Postfix main.cf and master.cf configuration files. - **process\_id (read-only)** The process ID of a Postfix command or daemon process. - **process\_name (read-only)** The process name of a Postfix command or daemon process. - **syslog\_facility (mail)** The syslog facility of Postfix logging. - **syslog\_name (see 'postconf -d' output)** A prefix that is prepended to the process name in syslog records, so that, for example, "smtpd" becomes "prefix/smtpd". ## SEE ALSO ``` postscreen(8), Postfix zombie blocker smtpd(8), Postfix SMTP server postconf(5), configuration parameters syslogd(5), system logging ``` ## LICENSE ``` ``` The Secure Mailer license must be distributed with this software. ## HISTORY This service was introduced with Postfix version 2.8. ## AUTHOR(S) ``` 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 ```