    POSTFIX-TLS(1)                                                  POSTFIX-TLS(1)

    NAME
           postfix-tls - Postfix TLS management

    SYNOPSIS
           postfix tls subcommand

    DESCRIPTION
           The  "postfix  tls subcommand" feature enables opportunistic TLS in the
           Postfix SMTP client or server, and manages Postfix SMTP server  private
           keys and certificates.

           The following subcommands are available:

           enable-client [-r randsource]
                  Enable opportunistic TLS in the Postfix SMTP client, if all SMTP
                  client TLS settings are at  their  default  values.   Otherwise,
                  suggest parameter settings without making any changes.

                  Specify  randsource to update the value of the tls_random_source
                  configuration parameter (typically, /dev/urandom).  Prepend dev:
                  to device paths or egd: to EGD socket paths.

                  See also the all-default-client subcommand.

           enable-server [-r randsource] [-a algorithm] [-b bits] [hostname...]
                  Create  a new private key and self-signed server certificate and
                  enable opportunistic TLS in the Postfix SMTP server, if all SMTP
                  server  TLS  settings  are  at their default values.  Otherwise,
                  suggest parameter settings without making any changes.

                  The randsource parameter is as with enable-client above, and the
                  remaining options are as with new-server-key below.

                  See also the all-default-server subcommand.

           new-server-key [-a algorithm] [-b bits] [hostname...]
                  Create a new private key and self-signed server certificate, but
                  do not deploy them. Log and display commands to deploy  the  new
                  key  and  corresponding  certificate.  Also log and display com-
                  mands to output a corresponding CSR or TLSA records which may be
                  needed  to  obtain  a CA certificate or to update DNS before the
                  new key can be deployed.

                  The algorithm defaults to rsa, and bits defaults  to  2048.   If
                  you  choose  the  ecdsa  algorithm then bits will be an EC curve
                  name (by default secp256r1, also known as  prime256v1).   Curves
                  other  than secp256r1, secp384r1 or secp521r1 are unlikely to be
                  widely interoperable.  When generating EC keys, use one of these
                  three.  DSA keys are obsolete and are not supported.

                  Note:  ECDSA support requires OpenSSL 1.0.0 or later and may not
                  be available on your system.  Not all client systems  will  sup-
                  port  ECDSA,  so  you'll  generally  want to deploy both RSA and
                  ECDSA certificates to make use of ECDSA with compatible  clients
                  and  RSA with the rest. If you want to deploy certificate chains
                  with intermediate CAs for both RSA and  ECDSA,  you'll  want  at
                  least OpenSSL 1.0.2, as earlier versions may not handle multiple
                  chain files correctly.

                  The first hostname argument will be the CommonName of  both  the
                  subject  and issuer of the self-signed certificate.  It, and any
                  additional hostname arguments, will also be listed as DNS alter-
                  native names in the certificate.  If no hostname is provided the
                  value of the myhostname main.cf parameter will be used.

                  For RSA, the generated private key  and  certificate  files  are
                  named   key-yyyymmdd-hhmmss.pem   and  cert-yyyymmdd-hhmmss.pem,
                  where yyyymmdd is the calendar date and hhmmss is  the  time  of
                  day  in  UTC.   For  ECDSA, the file names start with eckey- and
                  eccert- instead of key- and cert- respectively.

                  Before deploying the new key and certificate with  DANE,  update
                  the  DNS  with  new  DANE  TLSA records, then wait for secondary
                  nameservers to update and then for stale records in  remote  DNS
                  caches to expire.

                  Before  deploying  a new CA certificate make sure to include all
                  the required intermediate issuing CA certificates  in  the  cer-
                  tificate  chain  file.  The server certificate must be the first
                  certificate in the chain file.  Overwrite and  deploy  the  file
                  with  the  original  self-signed  certificate that was generated
                  together with the key.

           new-server-cert [-a algorithm] [-b bits] [hostname...]
                  This is just like new-server-key except that, rather than gener-
                  ating  a  new private key, any currently deployed private key is
                  copied to the new key file.  Thus if you're publishing DANE TLSA
                  "3  1  1"  or  "3  1  2" records, there is no need to update DNS
                  records.  The algorithm and bits arguments are used only  if  no
                  key of the same algorithm is already configured.

                  This  command is rarely needed, because the self-signed certifi-
                  cates generated have a 100-year nominal  expiration  time.   The
                  underlying  public key algorithms may well be obsoleted by quan-
                  tum computers long before then.

                  The most plausible reason for using this  command  is  when  the
                  system hostname changes, and you'd like the name in the certifi-
                  cate to match the new hostname (not required for DANE "3  1  1",
                  but some needlessly picky non-DANE opportunistic TLS clients may
                  log warnings or even refuse to communicate).

           deploy-server-cert certfile keyfile
                  This subcommand deploys the certificates in certfile and private
                  key  in  keyfile  (which are typically generated by the commands
                  above, which will also log and display the full  command  needed
                  to  deploy  the  generated  key and certificate).  After the new
                  certificate and key are deployed any obsolete keys and  certifi-
                  cates  may  be removed by hand.   The keyfile and certfile file-
                  names may be relative to the Postfix configuration directory.

           output-server-csr [-k keyfile] [hostname...]
                  Write to stdout a certificate  signing  request  (CSR)  for  the
                  specified keyfile.

                  Instead  of an absolute pathname or a pathname relative to $con-
                  fig_directory, keyfile may specify  one  of  the  supported  key
                  algorithm  names  (see  "postconf -T public-key-algorithms"). In
                  that case, the corresponding setting from  main.cf  is  used  to
                  locate the keyfile.  The default keyfile value is rsa.

                  Zero  or  more  hostname  values  can be specified.  The default
                  hostname is the value of myhostname main.cf parameter.

           output-server-tlsa [-h hostname] [keyfile...]
                  Write to stdout a DANE TLSA RRset suitable for a  port  25  SMTP
                  server on host hostname with keys from any of the specified key-
                  file values.  The default hostname is the value of  the  myhost-
                  name main.cf parameter.

                  Instead  of  absolute  pathnames  or pathnames relative to $con-
                  fig_directory, the keyfile list may specify names  of  supported
                  public key algorithms (see "postconf -T public-key-algorithms").
                  In that case, the actual keyfile list uses  the  values  of  the
                  corresponding  Postfix  server  TLS  key  file parameters.  If a
                  parameter value is empty or equal to none, then no  TLSA  record
                  is output for that algorithm.

                  The  default  keyfile  list  consists of the two supported algo-
                  rithms rsa and ecdsa.

    AUXILIARY COMMANDS
           all-default-client
                  Exit with status 0 (success) if all SMTP client TLS settings are
                  at their default values.  Otherwise, exit with a non-zero status.
                  This is typically used as follows:

                  postfix tls all-default-client &&
                          postfix tls enable-client

           all-default-server
                  Exit with status 0 (success) if all SMTP server TLS settings are
                  at their default values.  Otherwise, exit with a non-zero status.
                  This is typically used as follows:

                  postfix tls all-default-server &&
                          postfix tls enable-server

    CONFIGURATION PARAMETERS
           The "postfix tls subcommand" feature reads  or  updates  the  following
           configuration parameters.

           command_directory (see 'postconf -d' output)
                  The location of all postfix administrative commands.

           config_directory (see 'postconf -d' output)
                  The  default  location of the Postfix main.cf and master.cf con-
                  figuration files.

           openssl_path (openssl)
                  The location of the OpenSSL command line program openssl(1).

           smtp_tls_loglevel (0)
                  Enable additional Postfix SMTP client logging of TLS activity.

           smtp_tls_security_level (empty)
                  The default SMTP TLS security level for the Postfix SMTP client.

           smtp_tls_session_cache_database (empty)
                  Name of the file containing the optional Postfix SMTP client TLS
                  session cache.

           smtpd_tls_cert_file (empty)
                  File with the Postfix SMTP server RSA certificate in PEM format.

           smtpd_tls_eccert_file (empty)
                  File  with the Postfix SMTP server ECDSA certificate in PEM for-
                  mat.

           smtpd_tls_eckey_file ($smtpd_tls_eccert_file)
                  File with the Postfix SMTP server ECDSA private key in PEM  for-
                  mat.

           smtpd_tls_key_file ($smtpd_tls_cert_file)
                  File with the Postfix SMTP server RSA private key in PEM format.

           smtpd_tls_loglevel (0)
                  Enable additional Postfix SMTP server logging of TLS activity.

           smtpd_tls_received_header (no)
                  Request that the Postfix SMTP server produces Received:  message
                  headers  that  include information about the protocol and cipher
                  used, as well as the remote SMTP client  CommonName  and  client
                  certificate issuer CommonName.

           smtpd_tls_security_level (empty)
                  The  SMTP TLS security level for the Postfix SMTP server; when a
                  non-empty value is specified, this overrides the obsolete param-
                  eters smtpd_use_tls and smtpd_enforce_tls.

           tls_random_source (see 'postconf -d' output)
                  The  external  entropy source for the in-memory tlsmgr(8) pseudo
                  random number generator (PRNG) pool.

    SEE ALSO
           master(8) Postfix master program
           postfix(1) Postfix administrative interface

    README FILES
           TLS_README, Postfix TLS configuration and operation

    LICENSE
           The Secure Mailer license must be distributed with this software.

    HISTORY
           The "postfix tls" command was introduced with Postfix version 3.1.

    AUTHOR(S)
           Viktor Dukhovni

                                                                    POSTFIX-TLS(1)