From b5896ba9f6047e7031e2bdee0622d543e11a6734 Mon Sep 17 00:00:00 2001
From: Daniel Baumann <daniel.baumann@progress-linux.org>
Date: Mon, 6 May 2024 03:46:30 +0200
Subject: Adding upstream version 3.4.23.

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
---
 html/postfix-tls.1.html | 243 ++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 243 insertions(+)
 create mode 100644 html/postfix-tls.1.html

(limited to 'html/postfix-tls.1.html')

diff --git a/html/postfix-tls.1.html b/html/postfix-tls.1.html
new file mode 100644
index 0000000..099284e
--- /dev/null
+++ b/html/postfix-tls.1.html
@@ -0,0 +1,243 @@
+<!doctype html public "-//W3C//DTD HTML 4.01 Transitional//EN"
+        "http://www.w3.org/TR/html4/loose.dtd">
+<html> <head>
+<meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
+<title> Postfix manual - postfix-tls(1) </title>
+</head> <body> <pre>
+POSTFIX-TLS(1)                                                  POSTFIX-TLS(1)
+
+<b>NAME</b>
+       postfix-tls - Postfix TLS management
+
+<b>SYNOPSIS</b>
+       <b><a href="postfix-tls.1.html">postfix tls</a></b> <i>subcommand</i>
+
+<b>DESCRIPTION</b>
+       The  "<b><a href="postfix-tls.1.html">postfix  tls</a></b> <i>subcommand</i>" 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:
+
+       <b>enable-client</b> [<b>-r</b> <i>randsource</i>]
+              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  <i>randsource</i> to update the value of the <b><a href="postconf.5.html#tls_random_source">tls_random_source</a></b>
+              configuration parameter (typically, /dev/urandom).  Prepend <b>dev:</b>
+              to device paths or <b>egd:</b> to EGD socket paths.
+
+              See also the <b>all-default-client</b> subcommand.
+
+       <b>enable-server</b> [<b>-r</b> <i>randsource</i>] [<b>-a</b> <i>algorithm</i>] [<b>-b</b> <i>bits</i>] [<i>hostname</i><b>...</b>]
+              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 <i>randsource</i> parameter is as with <b>enable-client</b> above, and the
+              remaining options are as with <b>new-server-key</b> below.
+
+              See also the <b>all-default-server</b> subcommand.
+
+       <b>new-server-key</b> [<b>-a</b> <i>algorithm</i>] [<b>-b</b> <i>bits</i>] [<i>hostname</i><b>...</b>]
+              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 <i>algorithm</i> defaults to <b>rsa</b>, and <i>bits</i> defaults  to  2048.   If
+              you  choose  the  <b>ecdsa</b>  <i>algorithm</i> then <i>bits</i> will be an EC curve
+              name (by default <b>secp256r1</b>, also known as  prime256v1).   Curves
+              other  than <b>secp256r1</b>, <b>secp384r1</b> or <b>secp521r1</b> 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 <i>hostname</i> argument will be the <b>CommonName</b> of  both  the
+              subject  and issuer of the self-signed certificate.  It, and any
+              additional <i>hostname</i> arguments, will also be listed as DNS alter-
+              native names in the certificate.  If no <i>hostname</i> is provided the
+              value of the <b><a href="postconf.5.html#myhostname">myhostname</a></b> <a href="postconf.5.html">main.cf</a> parameter will be used.
+
+              For RSA, the generated private key  and  certificate  files  are
+              named   <b>key-</b><i>yyyymmdd-hhmmss</i><b>.pem</b>   and  <b>cert-</b><i>yyyymmdd-hhmmss</i><b>.pem</b>,
+              where <i>yyyymmdd</i> is the calendar date and <i>hhmmss</i> is  the  time  of
+              day  in  UTC.   For  ECDSA, the file names start with <b>eckey-</b> and
+              <b>eccert-</b> instead of <b>key-</b> and <b>cert-</b> 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.
+
+       <b>new-server-cert</b> [<b>-a</b> <i>algorithm</i>] [<b>-b</b> <i>bits</i>] [<i>hostname</i><b>...</b>]
+              This is just like <b>new-server-key</b> 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 <i>algorithm</i> and <i>bits</i> 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).
+
+       <b>deploy-server-cert</b> <i>certfile keyfile</i>
+              This subcommand deploys the certificates in <i>certfile</i> and private
+              key  in  <i>keyfile</i>  (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 <i>keyfile</i> and <i>certfile</i> file-
+              names may be relative to the Postfix configuration directory.
+
+       <b>output-server-csr</b> [<b>-k</b> <i>keyfile</i>] [<i>hostname</i><b>...</b>]
+              Write to stdout a certificate  signing  request  (CSR)  for  the
+              specified <i>keyfile</i>.
+
+              Instead  of an absolute pathname or a pathname relative to $<a href="postconf.5.html#config_directory">con</a>-
+              <a href="postconf.5.html#config_directory">fig_directory</a>, <i>keyfile</i> may specify  one  of  the  supported  key
+              algorithm  names  (see  "<b>postconf -T public-key-algorithms</b>"). In
+              that case, the corresponding setting from  <a href="postconf.5.html">main.cf</a>  is  used  to
+              locate the <i>keyfile</i>.  The default <i>keyfile</i> value is <b>rsa</b>.
+
+              Zero  or  more  <i>hostname</i>  values  can be specified.  The default
+              <i>hostname</i> is the value of <b><a href="postconf.5.html#myhostname">myhostname</a></b> <a href="postconf.5.html">main.cf</a> parameter.
+
+       <b>output-server-tlsa</b> [<b>-h</b> <i>hostname</i>] [<i>keyfile</i><b>...</b>]
+              Write to stdout a DANE TLSA RRset suitable for a  port  25  SMTP
+              server on host <i>hostname</i> with keys from any of the specified <i>key-</i>
+              <i>file</i> values.  The default <i>hostname</i> is the value of  the  <b>myhost-</b>
+              <b>name</b> <a href="postconf.5.html">main.cf</a> parameter.
+
+              Instead  of  absolute  pathnames  or pathnames relative to $<a href="postconf.5.html#config_directory">con</a>-
+              <a href="postconf.5.html#config_directory">fig_directory</a>, the <i>keyfile</i> list may specify names  of  supported
+              public key algorithms (see "<b>postconf -T public-key-algorithms</b>").
+              In that case, the actual <i>keyfile</i> list uses  the  values  of  the
+              corresponding  Postfix  server  TLS  key  file parameters.  If a
+              parameter value is empty or equal to <b>none</b>, then no  TLSA  record
+              is output for that algorithm.
+
+              The  default  <i>keyfile</i>  list  consists of the two supported algo-
+              rithms <b>rsa</b> and <b>ecdsa</b>.
+
+<b>AUXILIARY COMMANDS</b>
+       <b>all-default-client</b>
+              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:
+
+              <b><a href="postfix-tls.1.html">postfix tls</a> all-default-client</b> &amp;&amp;
+                      <b><a href="postfix-tls.1.html">postfix tls</a> enable-client</b>
+
+       <b>all-default-server</b>
+              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:
+
+              <b><a href="postfix-tls.1.html">postfix tls</a> all-default-server</b> &amp;&amp;
+                      <b><a href="postfix-tls.1.html">postfix tls</a> enable-server</b>
+
+<b>CONFIGURATION PARAMETERS</b>
+       The "<b><a href="postfix-tls.1.html">postfix tls</a></b> <i>subcommand</i>" feature reads  or  updates  the  following
+       configuration parameters.
+
+       <b><a href="postconf.5.html#command_directory">command_directory</a> (see 'postconf -d' output)</b>
+              The location of all postfix administrative commands.
+
+       <b><a href="postconf.5.html#config_directory">config_directory</a> (see 'postconf -d' output)</b>
+              The  default  location of the Postfix <a href="postconf.5.html">main.cf</a> and <a href="master.5.html">master.cf</a> con-
+              figuration files.
+
+       <b><a href="postconf.5.html#openssl_path">openssl_path</a> (openssl)</b>
+              The location of the OpenSSL command line program <b>openssl</b>(1).
+
+       <b><a href="postconf.5.html#smtp_tls_loglevel">smtp_tls_loglevel</a> (0)</b>
+              Enable additional Postfix SMTP client logging of TLS activity.
+
+       <b><a href="postconf.5.html#smtp_tls_security_level">smtp_tls_security_level</a> (empty)</b>
+              The default SMTP TLS security level for the Postfix SMTP client;
+              when a non-empty value is specified, this overrides the obsolete
+              parameters       <a href="postconf.5.html#smtp_use_tls">smtp_use_tls</a>,       <a href="postconf.5.html#smtp_enforce_tls">smtp_enforce_tls</a>,       and
+              <a href="postconf.5.html#smtp_tls_enforce_peername">smtp_tls_enforce_peername</a>.
+
+       <b><a href="postconf.5.html#smtp_tls_session_cache_database">smtp_tls_session_cache_database</a> (empty)</b>
+              Name of the file containing the optional Postfix SMTP client TLS
+              session cache.
+
+       <b><a href="postconf.5.html#smtpd_tls_cert_file">smtpd_tls_cert_file</a> (empty)</b>
+              File with the Postfix SMTP server RSA certificate in PEM format.
+
+       <b><a href="postconf.5.html#smtpd_tls_eccert_file">smtpd_tls_eccert_file</a> (empty)</b>
+              File  with the Postfix SMTP server ECDSA certificate in PEM for-
+              mat.
+
+       <b><a href="postconf.5.html#smtpd_tls_eckey_file">smtpd_tls_eckey_file</a> ($<a href="postconf.5.html#smtpd_tls_eccert_file">smtpd_tls_eccert_file</a>)</b>
+              File with the Postfix SMTP server ECDSA private key in PEM  for-
+              mat.
+
+       <b><a href="postconf.5.html#smtpd_tls_key_file">smtpd_tls_key_file</a> ($<a href="postconf.5.html#smtpd_tls_cert_file">smtpd_tls_cert_file</a>)</b>
+              File with the Postfix SMTP server RSA private key in PEM format.
+
+       <b><a href="postconf.5.html#smtpd_tls_loglevel">smtpd_tls_loglevel</a> (0)</b>
+              Enable additional Postfix SMTP server logging of TLS activity.
+
+       <b><a href="postconf.5.html#smtpd_tls_received_header">smtpd_tls_received_header</a> (no)</b>
+              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.
+
+       <b><a href="postconf.5.html#smtpd_tls_security_level">smtpd_tls_security_level</a> (empty)</b>
+              The  SMTP TLS security level for the Postfix SMTP server; when a
+              non-empty value is specified, this overrides the obsolete param-
+              eters <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>.
+
+       <b><a href="postconf.5.html#tls_random_source">tls_random_source</a> (see 'postconf -d' output)</b>
+              The  external  entropy source for the in-memory <a href="tlsmgr.8.html"><b>tlsmgr</b>(8)</a> pseudo
+              random number generator (PRNG) pool.
+
+<b>SEE ALSO</b>
+       <a href="master.8.html">master(8)</a> Postfix master program
+       <a href="postfix.1.html">postfix(1)</a> Postfix administrative interface
+
+<b>README FILES</b>
+       <a href="TLS_README.html">TLS_README</a>, Postfix TLS configuration and operation
+
+<b>LICENSE</b>
+       The Secure Mailer license must be distributed with this software.
+
+<b>HISTORY</b>
+       The "<b><a href="postfix-tls.1.html">postfix tls</a></b>" command was introduced with Postfix version 3.1.
+
+<b>AUTHOR(S)</b>
+       Viktor Dukhovni
+
+                                                                POSTFIX-TLS(1)
+</pre> </body> </html>
-- 
cgit v1.2.3