Postfix manual - tlsproxy(8)

    TLSPROXY(8)                                                        TLSPROXY(8)

    NAME
           tlsproxy - Postfix TLS proxy

    SYNOPSIS
           tlsproxy [generic Postfix daemon options]

    DESCRIPTION
           The tlsproxy(8) server implements a server-side TLS proxy.
           It is used by postscreen(8)  to  talk  SMTP-over-TLS  with
           remote  SMTP  clients  whose whitelist status has expired,
           but it should also work for non-SMTP protocols.

           Although one tlsproxy(8) process can serve  multiple  ses-
           sions  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). However, the
           tlsproxy(8) server is agnostic of the  application  proto-
           col,  and  the example is easily adapted to other applica-
           tions.

           The postscreen(8) server sends the remote SMTP client end-
           point   string,  the  requested  role  (server),  and  the
           requested  timeout  to  tlsproxy(8).   postscreen(8)  then
           receives  a  "TLS  available" indication from tlsproxy(8).
           If the TLS service is available, postscreen(8)  sends  the
           remote  SMTP  client  file  descriptor to tlsproxy(8), and
           sends the  plaintext  220  greeting  to  the  remote  SMTP
           client.  This triggers TLS negotiations between the remote
           SMTP client and tlsproxy(8).  Upon completion of the  TLS-
           level  handshake, tlsproxy(8) translates between plaintext
           from/to postscreen(8) and ciphertext  to/from  the  remote
           SMTP client.

    SECURITY
           The  tlsproxy(8)  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).

    CONFIGURATION PARAMETERS
           Changes  to  main.cf  are  not picked up automatically, as
           tlsproxy(8) 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) 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 certifi-
                  cates.

           tlsproxy_tls_always_issue_session_ids
           ($smtpd_tls_always_issue_session_ids)
                  Force the Postfix tlsproxy(8) 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_verify-
           depth)
                  The  verification depth for remote SMTP client cer-
                  tificates.

           tlsproxy_tls_cert_file ($smtpd_tls_cert_file)
                  File with the Postfix tlsproxy(8) server  RSA  cer-
                  tificate in PEM format.

           tlsproxy_tls_ciphers ($smtpd_tls_ciphers)
                  The  minimum  TLS  cipher  grade  that  the Postfix
                  tlsproxy(8) server will use with opportunistic  TLS
                  encryption.

           tlsproxy_tls_dcert_file ($smtpd_tls_dcert_file)
                  File  with  the Postfix tlsproxy(8) server DSA cer-
                  tificate in PEM format.

           tlsproxy_tls_dh1024_param_file
           ($smtpd_tls_dh1024_param_file)
                  File  with   DH   parameters   that   the   Postfix
                  tlsproxy(8) server should use with EDH ciphers.

           tlsproxy_tls_dh512_param_file
           ($smtpd_tls_dh512_param_file)
                  File   with   DH   parameters   that   the  Postfix
                  tlsproxy(8) server should use with EDH ciphers.

           tlsproxy_tls_dkey_file ($smtpd_tls_dkey_file)
                  File with the Postfix tlsproxy(8) server  DSA  pri-
                  vate key in PEM format.

           tlsproxy_tls_eccert_file ($smtpd_tls_eccert_file)
                  File with the Postfix tlsproxy(8) server ECDSA cer-
                  tificate in PEM format.

           tlsproxy_tls_eckey_file ($smtpd_tls_eckey_file)
                  File with the Postfix tlsproxy(8) server ECDSA pri-
                  vate key in PEM format.

           tlsproxy_tls_eecdh_grade ($smtpd_tls_eecdh_grade)
                  The  Postfix  tlsproxy(8) 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) server cipher list at all TLS  security
                  levels.

           tlsproxy_tls_fingerprint_digest        ($smtpd_tls_finger-
           print_digest)
                  The  message  digest  algorithm  used  to construct
                  client-certificate fingerprints.

           tlsproxy_tls_key_file ($smtpd_tls_key_file)
                  File with the Postfix tlsproxy(8) server  RSA  pri-
                  vate key in PEM format.

           tlsproxy_tls_loglevel ($smtpd_tls_loglevel)
                  Enable  additional  Postfix tlsproxy(8) server log-
                  ging of TLS activity.

           tlsproxy_tls_mandatory_ciphers          ($smtpd_tls_manda-
           tory_ciphers)
                  The minimum  TLS  cipher  grade  that  the  Postfix
                  tlsproxy(8)  server  will  use  with  mandatory TLS
                  encryption.

           tlsproxy_tls_mandatory_exclude_ciphers  ($smtpd_tls_manda-
           tory_exclude_ciphers)
                  Additional list  of  ciphers  or  cipher  types  to
                  exclude  from the tlsproxy(8) server cipher list at
                  mandatory TLS security levels.

           tlsproxy_tls_mandatory_protocols        ($smtpd_tls_manda-
           tory_protocols)
                  The  SSL/TLS  protocols  accepted  by  the  Postfix
                  tlsproxy(8) server with mandatory TLS encryption.

           tlsproxy_tls_protocols ($smtpd_tls_protocols)
                  List  of TLS protocols that the Postfix tlsproxy(8)
                  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) server; when a non-empty value is spec-
                  ified,   this  overrides  the  obsolete  parameters
                  smtpd_use_tls and smtpd_enforce_tls.

           tlsproxy_tls_session_cache_timeout        ($smtpd_tls_ses-
           sion_cache_timeout)
                  The expiration time of Postfix  tlsproxy(8)  server
                  TLS session cache information.

    OBSOLETE STARTTLS SUPPORT CONTROLS
           These  parameters  are  supported  for  compatibility with
           smtpd(8) legacy parameters.

           tlsproxy_use_tls ($smtpd_use_tls)
                  Opportunistic TLS:  announce  STARTTLS  support  to
                  SMTP  clients,  but do not require that clients use
                  TLS encryption.

           tlsproxy_enforce_tls ($smtpd_enforce_tls)
                  Mandatory TLS: announce STARTTLS  support  to  SMTP
                  clients,  and  require that clients use TLS encryp-
                  tion.

    RESOURCE CONTROLS
           tlsproxy_watchdog_timeout (10s)
                  How much time a tlsproxy(8)  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)
                  The  mail  system  name  that  is  prepended to the
                  process name in syslog  records,  so  that  "smtpd"
                  becomes, for example, "postfix/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

                                                                       TLSPROXY(8)