POSTFIX-TLS(1)						      General Commands Manual						    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 pri-
       vate 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,  sug-
	      gest 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 commands 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  inter-
	      operable.  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 support
	      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 addi-
	      tional hostname arguments, will also be listed as DNS alternative 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  name-
	      servers 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 certificate
	      chain file.  The server certificate must be the first certificate in the chain file.  Overwrite and deploy the file with the  origi-
	      nal 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 generating 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 certificates generated have a 100-year nominal expiration time.  The underly-
	      ing public key algorithms may well be obsoleted by quantum 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 certificate	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 certifi-
	      cate and key are deployed any obsolete keys and certificates may be removed by hand.   The keyfile and  certfile	filenames  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 $config_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 keyfile
	      values.  The default hostname is the value of the myhostname main.cf parameter.

	      Instead of absolute pathnames or pathnames relative to $config_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 algorithms 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 configuration 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; when a non-empty value is specified, this overrides the obsolete
	      parameters smtp_use_tls, smtp_enforce_tls, and smtp_tls_enforce_peername.

       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 format.

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

       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 parameters
	      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

       Use "postconf readme_directory" or "postconf html_directory" to locate this information.
       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)