postfix-master/tlsproxy.8.html

   1 <!doctype html public "-//W3C//DTD HTML 4.01 Transitional//EN"
   2         "http://www.w3.org/TR/html4/loose.dtd">
   3 <html> <head>
   4 <meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
   5 <title> Postfix manual - tlsproxy(8) </title>
   6 </head> <body> <pre>
   7 TLSPROXY(8)                                                        TLSPROXY(8)
   8
   9 <b>NAME</b>
  10        tlsproxy - Postfix TLS proxy
  11
  12 <b>SYNOPSIS</b>
  13        <b>tlsproxy</b> [generic Postfix daemon options]
  14
  15 <b>DESCRIPTION</b>
  16        The <a href="tlsproxy.8.html"><b>tlsproxy</b>(8)</a> server implements a server-side TLS proxy.
  17        It is used by <a href="postscreen.8.html"><b>postscreen</b>(8)</a>  to  talk  SMTP-over-TLS  with
  18        remote  SMTP  clients  whose whitelist status has expired,
  19        but it should also work for non-SMTP protocols.
  20
  21        Although one <a href="tlsproxy.8.html"><b>tlsproxy</b>(8)</a> process can serve  multiple  ses-
  22        sions  at  the  same  time, it is a good idea to allow the
  23        number of processes to increase with  load,  so  that  the
  24        service remains responsive.
  25
  26 <b>PROTOCOL EXAMPLE</b>
  27        The  example  below  concerns  <a href="postscreen.8.html"><b>postscreen</b>(8)</a>. However, the
  28        <a href="tlsproxy.8.html"><b>tlsproxy</b>(8)</a> server is agnostic of the  application  proto-
  29        col,  and  the example is easily adapted to other applica-
  30        tions.
  31
  32        The <a href="postscreen.8.html"><b>postscreen</b>(8)</a> server sends the remote SMTP client end-
  33        point   string,  the  requested  role  (server),  and  the
  34        requested  timeout  to  <a href="tlsproxy.8.html"><b>tlsproxy</b>(8)</a>.   <a href="postscreen.8.html"><b>postscreen</b>(8)</a>  then
  35        receives  a  "TLS  available" indication from <a href="tlsproxy.8.html"><b>tlsproxy</b>(8)</a>.
  36        If the TLS service is available, <a href="postscreen.8.html"><b>postscreen</b>(8)</a>  sends  the
  37        remote  SMTP  client  file  descriptor to <a href="tlsproxy.8.html"><b>tlsproxy</b>(8)</a>, and
  38        sends the  plaintext  220  greeting  to  the  remote  SMTP
  39        client.  This triggers TLS negotiations between the remote
  40        SMTP client and <a href="tlsproxy.8.html"><b>tlsproxy</b>(8)</a>.  Upon completion of the  TLS-
  41        level  handshake, <a href="tlsproxy.8.html"><b>tlsproxy</b>(8)</a> translates between plaintext
  42        from/to <a href="postscreen.8.html"><b>postscreen</b>(8)</a> and ciphertext  to/from  the  remote
  43        SMTP client.
  44
  45 <b>SECURITY</b>
  46        The  <a href="tlsproxy.8.html"><b>tlsproxy</b>(8)</a>  server is moderately security-sensitive.
  47        It talks to untrusted clients on the network. The  process
  48        can be run chrooted at fixed low privilege.
  49
  50 <b>DIAGNOSTICS</b>
  51        Problems and transactions are logged to <b>syslogd</b>(8).
  52
  53 <b>CONFIGURATION PARAMETERS</b>
  54        Changes  to  <a href="postconf.5.html"><b>main.cf</b></a>  are  not picked up automatically, as
  55        <a href="tlsproxy.8.html"><b>tlsproxy</b>(8)</a> processes may run for a long time depending on
  56        mail  server  load.   Use  the command "<b>postfix reload</b>" to
  57        speed up a change.
  58
  59        The text below provides  only  a  parameter  summary.  See
  60        <a href="postconf.5.html"><b>postconf</b>(5)</a> for more details including examples.
  61
  62 <b>STARTTLS SUPPORT CONTROLS</b>
  63        <b><a href="postconf.5.html#tlsproxy_tls_CAfile">tlsproxy_tls_CAfile</a> ($<a href="postconf.5.html#smtpd_tls_CAfile">smtpd_tls_CAfile</a>)</b>
  64               A  file  containing (PEM format) CA certificates of
  65               root CAs trusted to sign either remote SMTP  client
  66               certificates or intermediate CA certificates.
  67
  68        <b><a href="postconf.5.html#tlsproxy_tls_CApath">tlsproxy_tls_CApath</a> ($<a href="postconf.5.html#smtpd_tls_CApath">smtpd_tls_CApath</a>)</b>
  69               A directory containing (PEM format) CA certificates
  70               of root CAs trusted  to  sign  either  remote  SMTP
  71               client  certificates  or  intermediate  CA certifi-
  72               cates.
  73
  74        <b><a href="postconf.5.html#tlsproxy_tls_always_issue_session_ids">tlsproxy_tls_always_issue_session_ids</a></b>
  75        <b>($<a href="postconf.5.html#smtpd_tls_always_issue_session_ids">smtpd_tls_always_issue_session_ids</a>)</b>
  76               Force the Postfix <a href="tlsproxy.8.html"><b>tlsproxy</b>(8)</a> server to issue a TLS
  77               session id, even when TLS session caching is turned
  78               off.
  79
  80        <b><a href="postconf.5.html#tlsproxy_tls_ask_ccert">tlsproxy_tls_ask_ccert</a> ($<a href="postconf.5.html#smtpd_tls_ask_ccert">smtpd_tls_ask_ccert</a>)</b>
  81               Ask a remote SMTP client for a client  certificate.
  82
  83        <b><a href="postconf.5.html#tlsproxy_tls_ccert_verifydepth">tlsproxy_tls_ccert_verifydepth</a>   ($<a href="postconf.5.html#smtpd_tls_ccert_verifydepth">smtpd_tls_ccert_verify</a>-</b>
  84        <b><a href="postconf.5.html#smtpd_tls_ccert_verifydepth">depth</a>)</b>
  85               The  verification depth for remote SMTP client cer-
  86               tificates.
  87
  88        <b><a href="postconf.5.html#tlsproxy_tls_cert_file">tlsproxy_tls_cert_file</a> ($<a href="postconf.5.html#smtpd_tls_cert_file">smtpd_tls_cert_file</a>)</b>
  89               File with the Postfix <a href="tlsproxy.8.html"><b>tlsproxy</b>(8)</a> server  RSA  cer-
  90               tificate in PEM format.
  91
  92        <b><a href="postconf.5.html#tlsproxy_tls_ciphers">tlsproxy_tls_ciphers</a> ($<a href="postconf.5.html#smtpd_tls_ciphers">smtpd_tls_ciphers</a>)</b>
  93               The  minimum  TLS  cipher  grade  that  the Postfix
  94               <a href="tlsproxy.8.html"><b>tlsproxy</b>(8)</a> server will use with opportunistic  TLS
  95               encryption.
  96
  97        <b><a href="postconf.5.html#tlsproxy_tls_dcert_file">tlsproxy_tls_dcert_file</a> ($<a href="postconf.5.html#smtpd_tls_dcert_file">smtpd_tls_dcert_file</a>)</b>
  98               File  with  the Postfix <a href="tlsproxy.8.html"><b>tlsproxy</b>(8)</a> server DSA cer-
  99               tificate in PEM format.
 100
 101        <b><a href="postconf.5.html#tlsproxy_tls_dh1024_param_file">tlsproxy_tls_dh1024_param_file</a></b>
 102        <b>($<a href="postconf.5.html#smtpd_tls_dh1024_param_file">smtpd_tls_dh1024_param_file</a>)</b>
 103               File  with   DH   parameters   that   the   Postfix
 104               <a href="tlsproxy.8.html"><b>tlsproxy</b>(8)</a> server should use with EDH ciphers.
 105
 106        <b><a href="postconf.5.html#tlsproxy_tls_dh512_param_file">tlsproxy_tls_dh512_param_file</a></b>
 107        <b>($<a href="postconf.5.html#smtpd_tls_dh512_param_file">smtpd_tls_dh512_param_file</a>)</b>
 108               File   with   DH   parameters   that   the  Postfix
 109               <a href="tlsproxy.8.html"><b>tlsproxy</b>(8)</a> server should use with EDH ciphers.
 110
 111        <b><a href="postconf.5.html#tlsproxy_tls_dkey_file">tlsproxy_tls_dkey_file</a> ($<a href="postconf.5.html#smtpd_tls_dkey_file">smtpd_tls_dkey_file</a>)</b>
 112               File with the Postfix <a href="tlsproxy.8.html"><b>tlsproxy</b>(8)</a> server  DSA  pri-
 113               vate key in PEM format.
 114
 115        <b><a href="postconf.5.html#tlsproxy_tls_eccert_file">tlsproxy_tls_eccert_file</a> ($<a href="postconf.5.html#smtpd_tls_eccert_file">smtpd_tls_eccert_file</a>)</b>
 116               File with the Postfix <a href="tlsproxy.8.html"><b>tlsproxy</b>(8)</a> server ECDSA cer-
 117               tificate in PEM format.
 118
 119        <b><a href="postconf.5.html#tlsproxy_tls_eckey_file">tlsproxy_tls_eckey_file</a> ($<a href="postconf.5.html#smtpd_tls_eckey_file">smtpd_tls_eckey_file</a>)</b>
 120               File with the Postfix <a href="tlsproxy.8.html"><b>tlsproxy</b>(8)</a> server ECDSA pri-
 121               vate key in PEM format.
 122
 123        <b><a href="postconf.5.html#tlsproxy_tls_eecdh_grade">tlsproxy_tls_eecdh_grade</a> ($<a href="postconf.5.html#smtpd_tls_eecdh_grade">smtpd_tls_eecdh_grade</a>)</b>
 124               The  Postfix  <a href="tlsproxy.8.html"><b>tlsproxy</b>(8)</a> server security grade for
 125               ephemeral elliptic-curve Diffie-Hellman (EECDH) key
 126               exchange.
 127
 128        <b><a href="postconf.5.html#tlsproxy_tls_exclude_ciphers">tlsproxy_tls_exclude_ciphers</a> ($<a href="postconf.5.html#smtpd_tls_exclude_ciphers">smtpd_tls_exclude_ciphers</a>)</b>
 129               List of ciphers or cipher types to exclude from the
 130               <a href="tlsproxy.8.html"><b>tlsproxy</b>(8)</a> server cipher list at all TLS  security
 131               levels.
 132
 133        <b><a href="postconf.5.html#tlsproxy_tls_fingerprint_digest">tlsproxy_tls_fingerprint_digest</a>        ($<a href="postconf.5.html#smtpd_tls_fingerprint_digest">smtpd_tls_finger</a>-</b>
 134        <b><a href="postconf.5.html#smtpd_tls_fingerprint_digest">print_digest</a>)</b>
 135               The  message  digest  algorithm  used  to construct
 136               client-certificate fingerprints.
 137
 138        <b><a href="postconf.5.html#tlsproxy_tls_key_file">tlsproxy_tls_key_file</a> ($<a href="postconf.5.html#smtpd_tls_key_file">smtpd_tls_key_file</a>)</b>
 139               File with the Postfix <a href="tlsproxy.8.html"><b>tlsproxy</b>(8)</a> server  RSA  pri-
 140               vate key in PEM format.
 141
 142        <b><a href="postconf.5.html#tlsproxy_tls_loglevel">tlsproxy_tls_loglevel</a> ($<a href="postconf.5.html#smtpd_tls_loglevel">smtpd_tls_loglevel</a>)</b>
 143               Enable  additional  Postfix <a href="tlsproxy.8.html"><b>tlsproxy</b>(8)</a> server log-
 144               ging of TLS activity.
 145
 146        <b><a href="postconf.5.html#tlsproxy_tls_mandatory_ciphers">tlsproxy_tls_mandatory_ciphers</a>          ($<a href="postconf.5.html#smtpd_tls_mandatory_ciphers">smtpd_tls_manda</a>-</b>
 147        <b><a href="postconf.5.html#smtpd_tls_mandatory_ciphers">tory_ciphers</a>)</b>
 148               The minimum  TLS  cipher  grade  that  the  Postfix
 149               <a href="tlsproxy.8.html"><b>tlsproxy</b>(8)</a>  server  will  use  with  mandatory TLS
 150               encryption.
 151
 152        <b><a href="postconf.5.html#tlsproxy_tls_mandatory_exclude_ciphers">tlsproxy_tls_mandatory_exclude_ciphers</a>  ($<a href="postconf.5.html#smtpd_tls_mandatory_exclude_ciphers">smtpd_tls_manda</a>-</b>
 153        <b><a href="postconf.5.html#smtpd_tls_mandatory_exclude_ciphers">tory_exclude_ciphers</a>)</b>
 154               Additional list  of  ciphers  or  cipher  types  to
 155               exclude  from the <a href="tlsproxy.8.html"><b>tlsproxy</b>(8)</a> server cipher list at
 156               mandatory TLS security levels.
 157
 158        <b><a href="postconf.5.html#tlsproxy_tls_mandatory_protocols">tlsproxy_tls_mandatory_protocols</a>        ($<a href="postconf.5.html#smtpd_tls_mandatory_protocols">smtpd_tls_manda</a>-</b>
 159        <b><a href="postconf.5.html#smtpd_tls_mandatory_protocols">tory_protocols</a>)</b>
 160               The  SSL/TLS  protocols  accepted  by  the  Postfix
 161               <a href="tlsproxy.8.html"><b>tlsproxy</b>(8)</a> server with mandatory TLS encryption.
 162
 163        <b><a href="postconf.5.html#tlsproxy_tls_protocols">tlsproxy_tls_protocols</a> ($<a href="postconf.5.html#smtpd_tls_protocols">smtpd_tls_protocols</a>)</b>
 164               List  of TLS protocols that the Postfix <a href="tlsproxy.8.html"><b>tlsproxy</b>(8)</a>
 165               server will exclude or include  with  opportunistic
 166               TLS encryption.
 167
 168        <b><a href="postconf.5.html#tlsproxy_tls_req_ccert">tlsproxy_tls_req_ccert</a> ($<a href="postconf.5.html#smtpd_tls_req_ccert">smtpd_tls_req_ccert</a>)</b>
 169               With  mandatory  TLS  encryption, require a trusted
 170               remote SMTP client certificate in  order  to  allow
 171               TLS connections to proceed.
 172
 173        <b><a href="postconf.5.html#tlsproxy_tls_security_level">tlsproxy_tls_security_level</a> ($<a href="postconf.5.html#smtpd_tls_security_level">smtpd_tls_security_level</a>)</b>
 174               The   SMTP  TLS  security  level  for  the  Postfix
 175               <a href="tlsproxy.8.html"><b>tlsproxy</b>(8)</a> server; when a non-empty value is spec-
 176               ified,   this  overrides  the  obsolete  parameters
 177               <a href="postconf.5.html#smtpd_use_tls">smtpd_use_tls</a> and <a href="postconf.5.html#smtpd_enforce_tls">smtpd_enforce_tls</a>.
 178
 179        <b><a href="postconf.5.html#tlsproxy_tls_session_cache_timeout">tlsproxy_tls_session_cache_timeout</a>        ($<a href="postconf.5.html#smtpd_tls_session_cache_timeout">smtpd_tls_ses</a>-</b>
 180        <b><a href="postconf.5.html#smtpd_tls_session_cache_timeout">sion_cache_timeout</a>)</b>
 181               The expiration time of Postfix  <a href="tlsproxy.8.html"><b>tlsproxy</b>(8)</a>  server
 182               TLS session cache information.
 183
 184 <b>OBSOLETE STARTTLS SUPPORT CONTROLS</b>
 185        These  parameters  are  supported  for  compatibility with
 186        <a href="smtpd.8.html"><b>smtpd</b>(8)</a> legacy parameters.
 187
 188        <b><a href="postconf.5.html#tlsproxy_use_tls">tlsproxy_use_tls</a> ($<a href="postconf.5.html#smtpd_use_tls">smtpd_use_tls</a>)</b>
 189               Opportunistic TLS:  announce  STARTTLS  support  to
 190               SMTP  clients,  but do not require that clients use
 191               TLS encryption.
 192
 193        <b><a href="postconf.5.html#tlsproxy_enforce_tls">tlsproxy_enforce_tls</a> ($<a href="postconf.5.html#smtpd_enforce_tls">smtpd_enforce_tls</a>)</b>
 194               Mandatory TLS: announce STARTTLS  support  to  SMTP
 195               clients,  and  require that clients use TLS encryp-
 196               tion.
 197
 198 <b>RESOURCE CONTROLS</b>
 199        <b><a href="postconf.5.html#tlsproxy_watchdog_timeout">tlsproxy_watchdog_timeout</a> (10s)</b>
 200               How much time a <a href="tlsproxy.8.html"><b>tlsproxy</b>(8)</a>  process  may  take  to
 201               process local or remote I/O before it is terminated
 202               by a built-in watchdog timer.
 203
 204 <b>MISCELLANEOUS CONTROLS</b>
 205        <b><a href="postconf.5.html#config_directory">config_directory</a> (see 'postconf -d' output)</b>
 206               The default location of  the  Postfix  <a href="postconf.5.html">main.cf</a>  and
 207               <a href="master.5.html">master.cf</a> configuration files.
 208
 209        <b><a href="postconf.5.html#process_id">process_id</a> (read-only)</b>
 210               The  process  ID  of  a  Postfix  command or daemon
 211               process.
 212
 213        <b><a href="postconf.5.html#process_name">process_name</a> (read-only)</b>
 214               The process name of a  Postfix  command  or  daemon
 215               process.
 216
 217        <b><a href="postconf.5.html#syslog_facility">syslog_facility</a> (mail)</b>
 218               The syslog facility of Postfix logging.
 219
 220        <b><a href="postconf.5.html#syslog_name">syslog_name</a> (see 'postconf -d' output)</b>
 221               The  mail  system  name  that  is  prepended to the
 222               process name in syslog  records,  so  that  "smtpd"
 223               becomes, for example, "postfix/smtpd".
 224
 225 <b>SEE ALSO</b>
 226        <a href="postscreen.8.html">postscreen(8)</a>, Postfix zombie blocker
 227        <a href="smtpd.8.html">smtpd(8)</a>, Postfix SMTP server
 228        <a href="postconf.5.html">postconf(5)</a>, configuration parameters
 229        syslogd(5), system logging
 230
 231 <b>LICENSE</b>
 232        The  Secure  Mailer  license must be distributed with this
 233        software.
 234
 235 <b>HISTORY</b>
 236        This service was introduced with Postfix version 2.8.
 237
 238 <b>AUTHOR(S)</b>
 239        Wietse Venema
 240        IBM T.J. Watson Research
 241        P.O. Box 704
 242        Yorktown Heights, NY 10598, USA
 243
 244                                                                    TLSPROXY(8)
 245 </pre> </body> </html>