Adding upstream version 16.2.upstream/16.2

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
author: Daniel Baumann <daniel.baumann@progress-linux.org> 2024-04-13 13:44:03 +0000
committer: Daniel Baumann <daniel.baumann@progress-linux.org> 2024-04-13 13:44:03 +0000
commit: 293913568e6a7a86fd1479e1cff8e2ecb58d6568 (patch)
tree: fc3b469a3ec5ab71b36ea97cc7aaddb838423a0c /doc/src/sgml/html/ssl-tcp.html
parent: Initial commit. (diff)
download: postgresql-16-293913568e6a7a86fd1479e1cff8e2ecb58d6568.tar.xz
postgresql-16-293913568e6a7a86fd1479e1cff8e2ecb58d6568.zip
1 files changed, 264 insertions, 0 deletions
diff --git a/doc/src/sgml/html/ssl-tcp.html b/doc/src/sgml/html/ssl-tcp.html
new file mode 100644
index 0000000..0a865bd
--- /dev/null
+++ b/doc/src/sgml/html/ssl-tcp.html
@@ -0,0 +1,264 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>19.9. Secure TCP/IP Connections with SSL</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="encryption-options.html" title="19.8. Encryption Options" /><link rel="next" href="gssapi-enc.html" title="19.10. Secure TCP/IP Connections with GSSAPI Encryption" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">19.9. Secure TCP/IP Connections with SSL</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="encryption-options.html" title="19.8. Encryption Options">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="runtime.html" title="Chapter 19. Server Setup and Operation">Up</a></td><th width="60%" align="center">Chapter 19. Server Setup and Operation</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 16.2 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="gssapi-enc.html" title="19.10. Secure TCP/IP Connections with GSSAPI Encryption">Next</a></td></tr></table><hr /></div><div class="sect1" id="SSL-TCP"><div class="titlepage"><div><div><h2 class="title" style="clear: both">19.9. Secure TCP/IP Connections with SSL <a href="#SSL-TCP" class="id_link">#</a></h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="ssl-tcp.html#SSL-SETUP">19.9.1. Basic Setup</a></span></dt><dt><span class="sect2"><a href="ssl-tcp.html#SSL-OPENSSL-CONFIG">19.9.2. OpenSSL Configuration</a></span></dt><dt><span class="sect2"><a href="ssl-tcp.html#SSL-CLIENT-CERTIFICATES">19.9.3. Using Client Certificates</a></span></dt><dt><span class="sect2"><a href="ssl-tcp.html#SSL-SERVER-FILES">19.9.4. SSL Server File Usage</a></span></dt><dt><span class="sect2"><a href="ssl-tcp.html#SSL-CERTIFICATE-CREATION">19.9.5. Creating Certificates</a></span></dt></dl></div><a id="id-1.6.6.12.2" class="indexterm"></a><p>
+   <span class="productname">PostgreSQL</span> has native support for using
+   <acronym class="acronym">SSL</acronym> connections to encrypt client/server communications
+   for increased security. This requires that
+   <span class="productname">OpenSSL</span> is installed on both client and
+   server systems and that support in <span class="productname">PostgreSQL</span> is
+   enabled at build time (see <a class="xref" href="installation.html" title="Chapter 17. Installation from Source Code">Chapter 17</a>).
+  </p><p>
+   The terms <acronym class="acronym">SSL</acronym> and <acronym class="acronym">TLS</acronym> are often used
+   interchangeably to mean a secure encrypted connection using a
+   <acronym class="acronym">TLS</acronym> protocol. <acronym class="acronym">SSL</acronym> protocols are the
+   precursors to <acronym class="acronym">TLS</acronym> protocols, and the term
+   <acronym class="acronym">SSL</acronym> is still used for encrypted connections even though
+   <acronym class="acronym">SSL</acronym> protocols are no longer supported.
+   <acronym class="acronym">SSL</acronym> is used interchangeably with <acronym class="acronym">TLS</acronym>
+   in <span class="productname">PostgreSQL</span>.
+
+  </p><div class="sect2" id="SSL-SETUP"><div class="titlepage"><div><div><h3 class="title">19.9.1. Basic Setup <a href="#SSL-SETUP" class="id_link">#</a></h3></div></div></div><p>
+   With <acronym class="acronym">SSL</acronym> support compiled in, the
+   <span class="productname">PostgreSQL</span> server can be started with
+   support for encrypted connections using <acronym class="acronym">TLS</acronym> protocols
+   enabled by setting the parameter
+   <a class="xref" href="runtime-config-connection.html#GUC-SSL">ssl</a> to <code class="literal">on</code> in
+   <code class="filename">postgresql.conf</code>.  The server will listen for both normal
+   and <acronym class="acronym">SSL</acronym> connections on the same TCP port, and will negotiate
+   with any connecting client on whether to use <acronym class="acronym">SSL</acronym>.  By
+   default, this is at the client's option; see <a class="xref" href="auth-pg-hba-conf.html" title="21.1. The pg_hba.conf File">Section 21.1</a> about how to set up the server to require
+   use of <acronym class="acronym">SSL</acronym> for some or all connections.
+  </p><p>
+   To start in <acronym class="acronym">SSL</acronym> mode, files containing the server certificate
+   and private key must exist.  By default, these files are expected to be
+   named <code class="filename">server.crt</code> and <code class="filename">server.key</code>, respectively, in
+   the server's data directory, but other names and locations can be specified
+   using the configuration parameters <a class="xref" href="runtime-config-connection.html#GUC-SSL-CERT-FILE">ssl_cert_file</a>
+   and <a class="xref" href="runtime-config-connection.html#GUC-SSL-KEY-FILE">ssl_key_file</a>.
+  </p><p>
+   On Unix systems, the permissions on <code class="filename">server.key</code> must
+   disallow any access to world or group; achieve this by the command
+   <code class="command">chmod 0600 server.key</code>.  Alternatively, the file can be
+   owned by root and have group read access (that is, <code class="literal">0640</code>
+   permissions).  That setup is intended for installations where certificate
+   and key files are managed by the operating system.  The user under which
+   the <span class="productname">PostgreSQL</span> server runs should then be made a
+   member of the group that has access to those certificate and key files.
+  </p><p>
+    If the data directory allows group read access then certificate files may
+    need to be located outside of the data directory in order to conform to the
+    security requirements outlined above.  Generally, group access is enabled
+    to allow an unprivileged user to backup the database, and in that case the
+    backup software will not be able to read the certificate files and will
+    likely error.
+  </p><p>
+   If the private key is protected with a passphrase, the
+   server will prompt for the passphrase and will not start until it has
+   been entered.
+   Using a passphrase by default disables the ability to change the server's
+   SSL configuration without a server restart, but see <a class="xref" href="runtime-config-connection.html#GUC-SSL-PASSPHRASE-COMMAND-SUPPORTS-RELOAD">ssl_passphrase_command_supports_reload</a>.
+   Furthermore, passphrase-protected private keys cannot be used at all
+   on Windows.
+  </p><p>
+   The first certificate in <code class="filename">server.crt</code> must be the
+   server's certificate because it must match the server's private key.
+   The certificates of <span class="quote">“<span class="quote">intermediate</span>”</span> certificate authorities
+   can also be appended to the file.  Doing this avoids the necessity of
+   storing intermediate certificates on clients, assuming the root and
+   intermediate certificates were created with <code class="literal">v3_ca</code>
+   extensions.  (This sets the certificate's basic constraint of
+   <code class="literal">CA</code> to <code class="literal">true</code>.)
+   This allows easier expiration of intermediate certificates.
+  </p><p>
+   It is not necessary to add the root certificate to
+   <code class="filename">server.crt</code>.  Instead, clients must have the root
+   certificate of the server's certificate chain.
+  </p></div><div class="sect2" id="SSL-OPENSSL-CONFIG"><div class="titlepage"><div><div><h3 class="title">19.9.2. OpenSSL Configuration <a href="#SSL-OPENSSL-CONFIG" class="id_link">#</a></h3></div></div></div><p>
+   <span class="productname">PostgreSQL</span> reads the system-wide
+   <span class="productname">OpenSSL</span> configuration file. By default, this
+   file is named <code class="filename">openssl.cnf</code> and is located in the
+   directory reported by <code class="literal">openssl version -d</code>.
+   This default can be overridden by setting environment variable
+   <code class="envar">OPENSSL_CONF</code> to the name of the desired configuration file.
+  </p><p>
+   <span class="productname">OpenSSL</span> supports a wide range of ciphers
+   and authentication algorithms, of varying strength.  While a list of
+   ciphers can be specified in the <span class="productname">OpenSSL</span>
+   configuration file, you can specify ciphers specifically for use by
+   the database server by modifying <a class="xref" href="runtime-config-connection.html#GUC-SSL-CIPHERS">ssl_ciphers</a> in
+   <code class="filename">postgresql.conf</code>.
+  </p><div class="note"><h3 class="title">Note</h3><p>
+    It is possible to have authentication without encryption overhead by
+    using <code class="literal">NULL-SHA</code> or <code class="literal">NULL-MD5</code> ciphers.  However,
+    a man-in-the-middle could read and pass communications between client
+    and server.  Also, encryption overhead is minimal compared to the
+    overhead of authentication.  For these reasons NULL ciphers are not
+    recommended.
+   </p></div></div><div class="sect2" id="SSL-CLIENT-CERTIFICATES"><div class="titlepage"><div><div><h3 class="title">19.9.3. Using Client Certificates <a href="#SSL-CLIENT-CERTIFICATES" class="id_link">#</a></h3></div></div></div><p>
+   To require the client to supply a trusted certificate,
+   place certificates of the root certificate authorities
+   (<acronym class="acronym">CA</acronym>s) you trust in a file in the data
+   directory, set the parameter <a class="xref" href="runtime-config-connection.html#GUC-SSL-CA-FILE">ssl_ca_file</a> in
+   <code class="filename">postgresql.conf</code> to the new file name, and add the
+   authentication option <code class="literal">clientcert=verify-ca</code> or
+   <code class="literal">clientcert=verify-full</code> to the appropriate
+   <code class="literal">hostssl</code> line(s) in <code class="filename">pg_hba.conf</code>.
+   A certificate will then be requested from the client during SSL
+   connection startup.  (See <a class="xref" href="libpq-ssl.html" title="34.19. SSL Support">Section 34.19</a> for a description
+   of how to set up certificates on the client.)
+  </p><p>
+   For a <code class="literal">hostssl</code> entry with
+   <code class="literal">clientcert=verify-ca</code>, the server will verify
+   that the client's certificate is signed by one of the trusted
+   certificate authorities. If <code class="literal">clientcert=verify-full</code>
+   is specified, the server will not only verify the certificate
+   chain, but it will also check whether the username or its mapping
+   matches the <code class="literal">cn</code> (Common Name) of the provided certificate.
+   Note that certificate chain validation is always ensured when the
+   <code class="literal">cert</code> authentication method is used
+   (see <a class="xref" href="auth-cert.html" title="21.12. Certificate Authentication">Section 21.12</a>).
+  </p><p>
+   Intermediate certificates that chain up to existing root certificates
+   can also appear in the <a class="xref" href="runtime-config-connection.html#GUC-SSL-CA-FILE">ssl_ca_file</a> file if
+   you wish to avoid storing them on clients (assuming the root and
+   intermediate certificates were created with <code class="literal">v3_ca</code>
+   extensions).  Certificate Revocation List (CRL) entries are also
+   checked if the parameter <a class="xref" href="runtime-config-connection.html#GUC-SSL-CRL-FILE">ssl_crl_file</a> or
+   <a class="xref" href="runtime-config-connection.html#GUC-SSL-CRL-DIR">ssl_crl_dir</a> is set.
+  </p><p>
+   The <code class="literal">clientcert</code> authentication option is available for
+   all authentication methods, but only in <code class="filename">pg_hba.conf</code> lines
+   specified as <code class="literal">hostssl</code>.  When <code class="literal">clientcert</code> is
+   not specified, the server verifies the client certificate against its CA
+   file only if a client certificate is presented and the CA is configured.
+  </p><p>
+   There are two approaches to enforce that users provide a certificate during login.
+  </p><p>
+   The first approach makes use of the <code class="literal">cert</code> authentication
+   method for <code class="literal">hostssl</code> entries in <code class="filename">pg_hba.conf</code>,
+   such that the certificate itself is used for authentication while also
+   providing ssl connection security. See <a class="xref" href="auth-cert.html" title="21.12. Certificate Authentication">Section 21.12</a> for details.
+   (It is not necessary to specify any <code class="literal">clientcert</code> options
+   explicitly when using the <code class="literal">cert</code> authentication method.)
+   In this case, the <code class="literal">cn</code> (Common Name) provided in
+   the certificate is checked against the user name or an applicable mapping.
+  </p><p>
+   The second approach combines any authentication method for <code class="literal">hostssl</code>
+   entries with the verification of client certificates by setting the
+   <code class="literal">clientcert</code> authentication option to <code class="literal">verify-ca</code>
+   or <code class="literal">verify-full</code>. The former option only enforces that
+   the certificate is valid, while the latter also ensures that the
+   <code class="literal">cn</code> (Common Name) in the certificate matches
+   the user name or an applicable mapping.
+  </p></div><div class="sect2" id="SSL-SERVER-FILES"><div class="titlepage"><div><div><h3 class="title">19.9.4. SSL Server File Usage <a href="#SSL-SERVER-FILES" class="id_link">#</a></h3></div></div></div><p>
+    <a class="xref" href="ssl-tcp.html#SSL-FILE-USAGE" title="Table 19.2. SSL Server File Usage">Table 19.2</a> summarizes the files that are
+    relevant to the SSL setup on the server.  (The shown file names are default
+    names.  The locally configured names could be different.)
+   </p><div class="table" id="SSL-FILE-USAGE"><p class="title"><strong>Table 19.2. SSL Server File Usage</strong></p><div class="table-contents"><table class="table" summary="SSL Server File Usage" border="1"><colgroup><col /><col /><col /></colgroup><thead><tr><th>File</th><th>Contents</th><th>Effect</th></tr></thead><tbody><tr><td><a class="xref" href="runtime-config-connection.html#GUC-SSL-CERT-FILE">ssl_cert_file</a> (<code class="filename">$PGDATA/server.crt</code>)</td><td>server certificate</td><td>sent to client to indicate server's identity</td></tr><tr><td><a class="xref" href="runtime-config-connection.html#GUC-SSL-KEY-FILE">ssl_key_file</a> (<code class="filename">$PGDATA/server.key</code>)</td><td>server private key</td><td>proves server certificate was sent by the owner; does not indicate
+      certificate owner is trustworthy</td></tr><tr><td><a class="xref" href="runtime-config-connection.html#GUC-SSL-CA-FILE">ssl_ca_file</a></td><td>trusted certificate authorities</td><td>checks that client certificate is
+      signed by a trusted certificate authority</td></tr><tr><td><a class="xref" href="runtime-config-connection.html#GUC-SSL-CRL-FILE">ssl_crl_file</a></td><td>certificates revoked by certificate authorities</td><td>client certificate must not be on this list</td></tr></tbody></table></div></div><br class="table-break" /><p>
+    The server reads these files at server start and whenever the server
+    configuration is reloaded.  On <span class="systemitem">Windows</span>
+    systems, they are also re-read whenever a new backend process is spawned
+    for a new client connection.
+   </p><p>
+    If an error in these files is detected at server start, the server will
+    refuse to start.  But if an error is detected during a configuration
+    reload, the files are ignored and the old SSL configuration continues to
+    be used.  On <span class="systemitem">Windows</span> systems, if an error in
+    these files is detected at backend start, that backend will be unable to
+    establish an SSL connection.  In all these cases, the error condition is
+    reported in the server log.
+   </p></div><div class="sect2" id="SSL-CERTIFICATE-CREATION"><div class="titlepage"><div><div><h3 class="title">19.9.5. Creating Certificates <a href="#SSL-CERTIFICATE-CREATION" class="id_link">#</a></h3></div></div></div><p>
+     To create a simple self-signed certificate for the server, valid for 365
+     days, use the following <span class="productname">OpenSSL</span> command,
+     replacing <em class="replaceable"><code>dbhost.yourdomain.com</code></em> with the
+     server's host name:
+</p><pre class="programlisting">
+openssl req -new -x509 -days 365 -nodes -text -out server.crt \
+  -keyout server.key -subj "/CN=<em class="replaceable"><code>dbhost.yourdomain.com</code></em>"
+</pre><p>
+    Then do:
+</p><pre class="programlisting">
+chmod og-rwx server.key
+</pre><p>
+    because the server will reject the file if its permissions are more
+    liberal than this.
+    For more details on how to create your server private key and
+    certificate, refer to the <span class="productname">OpenSSL</span> documentation.
+   </p><p>
+    While a self-signed certificate can be used for testing, a certificate
+    signed by a certificate authority (<acronym class="acronym">CA</acronym>) (usually an
+    enterprise-wide root <acronym class="acronym">CA</acronym>) should be used in production.
+   </p><p>
+    To create a server certificate whose identity can be validated
+    by clients, first create a certificate signing request
+    (<acronym class="acronym">CSR</acronym>) and a public/private key file:
+</p><pre class="programlisting">
+openssl req -new -nodes -text -out root.csr \
+  -keyout root.key -subj "/CN=<em class="replaceable"><code>root.yourdomain.com</code></em>"
+chmod og-rwx root.key
+</pre><p>
+    Then, sign the request with the key to create a root certificate
+    authority (using the default <span class="productname">OpenSSL</span>
+    configuration file location on <span class="productname">Linux</span>):
+</p><pre class="programlisting">
+openssl x509 -req -in root.csr -text -days 3650 \
+  -extfile /etc/ssl/openssl.cnf -extensions v3_ca \
+  -signkey root.key -out root.crt
+</pre><p>
+    Finally, create a server certificate signed by the new root certificate
+    authority:
+</p><pre class="programlisting">
+openssl req -new -nodes -text -out server.csr \
+  -keyout server.key -subj "/CN=<em class="replaceable"><code>dbhost.yourdomain.com</code></em>"
+chmod og-rwx server.key
+
+openssl x509 -req -in server.csr -text -days 365 \
+  -CA root.crt -CAkey root.key -CAcreateserial \
+  -out server.crt
+</pre><p>
+    <code class="filename">server.crt</code> and <code class="filename">server.key</code>
+    should be stored on the server, and <code class="filename">root.crt</code> should
+    be stored on the client so the client can verify that the server's leaf
+    certificate was signed by its trusted root certificate.
+    <code class="filename">root.key</code> should be stored offline for use in
+    creating future certificates.
+   </p><p>
+    It is also possible to create a chain of trust that includes
+    intermediate certificates:
+</p><pre class="programlisting">
+# root
+openssl req -new -nodes -text -out root.csr \
+  -keyout root.key -subj "/CN=<em class="replaceable"><code>root.yourdomain.com</code></em>"
+chmod og-rwx root.key
+openssl x509 -req -in root.csr -text -days 3650 \
+  -extfile /etc/ssl/openssl.cnf -extensions v3_ca \
+  -signkey root.key -out root.crt
+
+# intermediate
+openssl req -new -nodes -text -out intermediate.csr \
+  -keyout intermediate.key -subj "/CN=<em class="replaceable"><code>intermediate.yourdomain.com</code></em>"
+chmod og-rwx intermediate.key
+openssl x509 -req -in intermediate.csr -text -days 1825 \
+  -extfile /etc/ssl/openssl.cnf -extensions v3_ca \
+  -CA root.crt -CAkey root.key -CAcreateserial \
+  -out intermediate.crt
+
+# leaf
+openssl req -new -nodes -text -out server.csr \
+  -keyout server.key -subj "/CN=<em class="replaceable"><code>dbhost.yourdomain.com</code></em>"
+chmod og-rwx server.key
+openssl x509 -req -in server.csr -text -days 365 \
+  -CA intermediate.crt -CAkey intermediate.key -CAcreateserial \
+  -out server.crt
+</pre><p>
+    <code class="filename">server.crt</code> and
+    <code class="filename">intermediate.crt</code> should be concatenated
+    into a certificate file bundle and stored on the server.
+    <code class="filename">server.key</code> should also be stored on the server.
+    <code class="filename">root.crt</code> should be stored on the client so
+    the client can verify that the server's leaf certificate was signed
+    by a chain of certificates linked to its trusted root certificate.
+    <code class="filename">root.key</code> and <code class="filename">intermediate.key</code>
+    should be stored offline for use in creating future certificates.
+   </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="encryption-options.html" title="19.8. Encryption Options">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="runtime.html" title="Chapter 19. Server Setup and Operation">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="gssapi-enc.html" title="19.10. Secure TCP/IP Connections with GSSAPI Encryption">Next</a></td></tr><tr><td width="40%" align="left" valign="top">19.8. Encryption Options </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 16.2 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 19.10. Secure TCP/IP Connections with GSSAPI Encryption</td></tr></table></div></body></html>
+\ No newline at end of file
author	Daniel Baumann <daniel.baumann@progress-linux.org>	2024-04-13 13:44:03 +0000
committer	Daniel Baumann <daniel.baumann@progress-linux.org>	2024-04-13 13:44:03 +0000
commit	293913568e6a7a86fd1479e1cff8e2ecb58d6568 (patch)
tree	fc3b469a3ec5ab71b36ea97cc7aaddb838423a0c /doc/src/sgml/html/ssl-tcp.html
parent	Initial commit. (diff)
download	postgresql-16-293913568e6a7a86fd1479e1cff8e2ecb58d6568.tar.xz postgresql-16-293913568e6a7a86fd1479e1cff8e2ecb58d6568.zip