xenial (1) postfix-tls.1.gz

Provided by: postfix_3.1.0-3ubuntu0.4_amd64 bug

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
              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  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 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 additional 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 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  certificate  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  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 underlying 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 certificate 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-tls-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-tls-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)