begriffs open source - ai-pg/blob - full-docs/src/sgml/html/ssl-tcp.html

   1 <?xml version="1.0" encoding="UTF-8" standalone="no"?>
   2 <!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>18.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="18.8. Encryption Options" /><link rel="next" href="gssapi-enc.html" title="18.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">18.9. Secure TCP/IP Connections with SSL</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="encryption-options.html" title="18.8. Encryption Options">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="runtime.html" title="Chapter 18. Server Setup and Operation">Up</a></td><th width="60%" align="center">Chapter 18. Server Setup and Operation</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 18.0 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="gssapi-enc.html" title="18.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">18.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">18.9.1. Basic Setup</a></span></dt><dt><span class="sect2"><a href="ssl-tcp.html#SSL-OPENSSL-CONFIG">18.9.2. OpenSSL Configuration</a></span></dt><dt><span class="sect2"><a href="ssl-tcp.html#SSL-CLIENT-CERTIFICATES">18.9.3. Using Client Certificates</a></span></dt><dt><span class="sect2"><a href="ssl-tcp.html#SSL-SERVER-FILES">18.9.4. SSL Server File Usage</a></span></dt><dt><span class="sect2"><a href="ssl-tcp.html#SSL-CERTIFICATE-CREATION">18.9.5. Creating Certificates</a></span></dt></dl></div><a id="id-1.6.5.12.2" class="indexterm"></a><p>
   3    <span class="productname">PostgreSQL</span> has native support for using
   4    <acronym class="acronym">SSL</acronym> connections to encrypt client/server communications
   5    for increased security. This requires that
   6    <span class="productname">OpenSSL</span> is installed on both client and
   7    server systems and that support in <span class="productname">PostgreSQL</span> is
   8    enabled at build time (see <a class="xref" href="installation.html" title="Chapter 17. Installation from Source Code">Chapter 17</a>).
   9   </p><p>
  10    The terms <acronym class="acronym">SSL</acronym> and <acronym class="acronym">TLS</acronym> are often used
  11    interchangeably to mean a secure encrypted connection using a
  12    <acronym class="acronym">TLS</acronym> protocol. <acronym class="acronym">SSL</acronym> protocols are the
  13    precursors to <acronym class="acronym">TLS</acronym> protocols, and the term
  14    <acronym class="acronym">SSL</acronym> is still used for encrypted connections even though
  15    <acronym class="acronym">SSL</acronym> protocols are no longer supported.
  16    <acronym class="acronym">SSL</acronym> is used interchangeably with <acronym class="acronym">TLS</acronym>
  17    in <span class="productname">PostgreSQL</span>.
  18
  19   </p><div class="sect2" id="SSL-SETUP"><div class="titlepage"><div><div><h3 class="title">18.9.1. Basic Setup <a href="#SSL-SETUP" class="id_link">#</a></h3></div></div></div><p>
  20    With <acronym class="acronym">SSL</acronym> support compiled in, the
  21    <span class="productname">PostgreSQL</span> server can be started with
  22    support for encrypted connections using <acronym class="acronym">TLS</acronym> protocols
  23    enabled by setting the parameter
  24    <a class="xref" href="runtime-config-connection.html#GUC-SSL">ssl</a> to <code class="literal">on</code> in
  25    <code class="filename">postgresql.conf</code>.  The server will listen for both normal
  26    and <acronym class="acronym">SSL</acronym> connections on the same TCP port, and will negotiate
  27    with any connecting client on whether to use <acronym class="acronym">SSL</acronym>.  By
  28    default, this is at the client's option; see <a class="xref" href="auth-pg-hba-conf.html" title="20.1. The pg_hba.conf File">Section 20.1</a> about how to set up the server to require
  29    use of <acronym class="acronym">SSL</acronym> for some or all connections.
  30   </p><p>
  31    To start in <acronym class="acronym">SSL</acronym> mode, files containing the server certificate
  32    and private key must exist.  By default, these files are expected to be
  33    named <code class="filename">server.crt</code> and <code class="filename">server.key</code>, respectively, in
  34    the server's data directory, but other names and locations can be specified
  35    using the configuration parameters <a class="xref" href="runtime-config-connection.html#GUC-SSL-CERT-FILE">ssl_cert_file</a>
  36    and <a class="xref" href="runtime-config-connection.html#GUC-SSL-KEY-FILE">ssl_key_file</a>.
  37   </p><p>
  38    On Unix systems, the permissions on <code class="filename">server.key</code> must
  39    disallow any access to world or group; achieve this by the command
  40    <code class="command">chmod 0600 server.key</code>.  Alternatively, the file can be
  41    owned by root and have group read access (that is, <code class="literal">0640</code>
  42    permissions).  That setup is intended for installations where certificate
  43    and key files are managed by the operating system.  The user under which
  44    the <span class="productname">PostgreSQL</span> server runs should then be made a
  45    member of the group that has access to those certificate and key files.
  46   </p><p>
  47     If the data directory allows group read access then certificate files may
  48     need to be located outside of the data directory in order to conform to the
  49     security requirements outlined above.  Generally, group access is enabled
  50     to allow an unprivileged user to backup the database, and in that case the
  51     backup software will not be able to read the certificate files and will
  52     likely error.
  53   </p><p>
  54    If the private key is protected with a passphrase, the
  55    server will prompt for the passphrase and will not start until it has
  56    been entered.
  57    Using a passphrase by default disables the ability to change the server's
  58    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>.
  59    Furthermore, passphrase-protected private keys cannot be used at all
  60    on Windows.
  61   </p><p>
  62    The first certificate in <code class="filename">server.crt</code> must be the
  63    server's certificate because it must match the server's private key.
  64    The certificates of <span class="quote">“<span class="quote">intermediate</span>”</span> certificate authorities
  65    can also be appended to the file.  Doing this avoids the necessity of
  66    storing intermediate certificates on clients, assuming the root and
  67    intermediate certificates were created with <code class="literal">v3_ca</code>
  68    extensions.  (This sets the certificate's basic constraint of
  69    <code class="literal">CA</code> to <code class="literal">true</code>.)
  70    This allows easier expiration of intermediate certificates.
  71   </p><p>
  72    It is not necessary to add the root certificate to
  73    <code class="filename">server.crt</code>.  Instead, clients must have the root
  74    certificate of the server's certificate chain.
  75   </p></div><div class="sect2" id="SSL-OPENSSL-CONFIG"><div class="titlepage"><div><div><h3 class="title">18.9.2. OpenSSL Configuration <a href="#SSL-OPENSSL-CONFIG" class="id_link">#</a></h3></div></div></div><p>
  76    <span class="productname">PostgreSQL</span> reads the system-wide
  77    <span class="productname">OpenSSL</span> configuration file. By default, this
  78    file is named <code class="filename">openssl.cnf</code> and is located in the
  79    directory reported by <code class="literal">openssl version -d</code>.
  80    This default can be overridden by setting environment variable
  81    <code class="envar">OPENSSL_CONF</code> to the name of the desired configuration file.
  82   </p><p>
  83    <span class="productname">OpenSSL</span> supports a wide range of ciphers
  84    and authentication algorithms, of varying strength.  While a list of
  85    ciphers can be specified in the <span class="productname">OpenSSL</span>
  86    configuration file, you can specify ciphers specifically for use by
  87    the database server by modifying <a class="xref" href="runtime-config-connection.html#GUC-SSL-CIPHERS">ssl_ciphers</a> in
  88    <code class="filename">postgresql.conf</code>.
  89   </p><div class="note"><h3 class="title">Note</h3><p>
  90     It is possible to have authentication without encryption overhead by
  91     using <code class="literal">NULL-SHA</code> or <code class="literal">NULL-MD5</code> ciphers.  However,
  92     a man-in-the-middle could read and pass communications between client
  93     and server.  Also, encryption overhead is minimal compared to the
  94     overhead of authentication.  For these reasons NULL ciphers are not
  95     recommended.
  96    </p></div></div><div class="sect2" id="SSL-CLIENT-CERTIFICATES"><div class="titlepage"><div><div><h3 class="title">18.9.3. Using Client Certificates <a href="#SSL-CLIENT-CERTIFICATES" class="id_link">#</a></h3></div></div></div><p>
  97    To require the client to supply a trusted certificate,
  98    place certificates of the root certificate authorities
  99    (<acronym class="acronym">CA</acronym>s) you trust in a file in the data
 100    directory, set the parameter <a class="xref" href="runtime-config-connection.html#GUC-SSL-CA-FILE">ssl_ca_file</a> in
 101    <code class="filename">postgresql.conf</code> to the new file name, and add the
 102    authentication option <code class="literal">clientcert=verify-ca</code> or
 103    <code class="literal">clientcert=verify-full</code> to the appropriate
 104    <code class="literal">hostssl</code> line(s) in <code class="filename">pg_hba.conf</code>.
 105    A certificate will then be requested from the client during SSL
 106    connection startup.  (See <a class="xref" href="libpq-ssl.html" title="32.19. SSL Support">Section 32.19</a> for a description
 107    of how to set up certificates on the client.)
 108   </p><p>
 109    For a <code class="literal">hostssl</code> entry with
 110    <code class="literal">clientcert=verify-ca</code>, the server will verify
 111    that the client's certificate is signed by one of the trusted
 112    certificate authorities. If <code class="literal">clientcert=verify-full</code>
 113    is specified, the server will not only verify the certificate
 114    chain, but it will also check whether the username or its mapping
 115    matches the <code class="literal">cn</code> (Common Name) of the provided certificate.
 116    Note that certificate chain validation is always ensured when the
 117    <code class="literal">cert</code> authentication method is used
 118    (see <a class="xref" href="auth-cert.html" title="20.12. Certificate Authentication">Section 20.12</a>).
 119   </p><p>
 120    Intermediate certificates that chain up to existing root certificates
 121    can also appear in the <a class="xref" href="runtime-config-connection.html#GUC-SSL-CA-FILE">ssl_ca_file</a> file if
 122    you wish to avoid storing them on clients (assuming the root and
 123    intermediate certificates were created with <code class="literal">v3_ca</code>
 124    extensions).  Certificate Revocation List (CRL) entries are also
 125    checked if the parameter <a class="xref" href="runtime-config-connection.html#GUC-SSL-CRL-FILE">ssl_crl_file</a> or
 126    <a class="xref" href="runtime-config-connection.html#GUC-SSL-CRL-DIR">ssl_crl_dir</a> is set.
 127   </p><p>
 128    The <code class="literal">clientcert</code> authentication option is available for
 129    all authentication methods, but only in <code class="filename">pg_hba.conf</code> lines
 130    specified as <code class="literal">hostssl</code>.  When <code class="literal">clientcert</code> is
 131    not specified, the server verifies the client certificate against its CA
 132    file only if a client certificate is presented and the CA is configured.
 133   </p><p>
 134    There are two approaches to enforce that users provide a certificate during login.
 135   </p><p>
 136    The first approach makes use of the <code class="literal">cert</code> authentication
 137    method for <code class="literal">hostssl</code> entries in <code class="filename">pg_hba.conf</code>,
 138    such that the certificate itself is used for authentication while also
 139    providing ssl connection security. See <a class="xref" href="auth-cert.html" title="20.12. Certificate Authentication">Section 20.12</a> for details.
 140    (It is not necessary to specify any <code class="literal">clientcert</code> options
 141    explicitly when using the <code class="literal">cert</code> authentication method.)
 142    In this case, the <code class="literal">cn</code> (Common Name) provided in
 143    the certificate is checked against the user name or an applicable mapping.
 144   </p><p>
 145    The second approach combines any authentication method for <code class="literal">hostssl</code>
 146    entries with the verification of client certificates by setting the
 147    <code class="literal">clientcert</code> authentication option to <code class="literal">verify-ca</code>
 148    or <code class="literal">verify-full</code>. The former option only enforces that
 149    the certificate is valid, while the latter also ensures that the
 150    <code class="literal">cn</code> (Common Name) in the certificate matches
 151    the user name or an applicable mapping.
 152   </p></div><div class="sect2" id="SSL-SERVER-FILES"><div class="titlepage"><div><div><h3 class="title">18.9.4. SSL Server File Usage <a href="#SSL-SERVER-FILES" class="id_link">#</a></h3></div></div></div><p>
 153     <a class="xref" href="ssl-tcp.html#SSL-FILE-USAGE" title="Table 18.2. SSL Server File Usage">Table 18.2</a> summarizes the files that are
 154     relevant to the SSL setup on the server.  (The shown file names are default
 155     names.  The locally configured names could be different.)
 156    </p><div class="table" id="SSL-FILE-USAGE"><p class="title"><strong>Table 18.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
 157       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
 158       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>
 159     The server reads these files at server start and whenever the server
 160     configuration is reloaded.  On <span class="systemitem">Windows</span>
 161     systems, they are also re-read whenever a new backend process is spawned
 162     for a new client connection.
 163    </p><p>
 164     If an error in these files is detected at server start, the server will
 165     refuse to start.  But if an error is detected during a configuration
 166     reload, the files are ignored and the old SSL configuration continues to
 167     be used.  On <span class="systemitem">Windows</span> systems, if an error in
 168     these files is detected at backend start, that backend will be unable to
 169     establish an SSL connection.  In all these cases, the error condition is
 170     reported in the server log.
 171    </p></div><div class="sect2" id="SSL-CERTIFICATE-CREATION"><div class="titlepage"><div><div><h3 class="title">18.9.5. Creating Certificates <a href="#SSL-CERTIFICATE-CREATION" class="id_link">#</a></h3></div></div></div><p>
 172      To create a simple self-signed certificate for the server, valid for 365
 173      days, use the following <span class="productname">OpenSSL</span> command,
 174      replacing <em class="replaceable"><code>dbhost.yourdomain.com</code></em> with the
 175      server's host name:
 176 </p><pre class="programlisting">
 177 openssl req -new -x509 -days 365 -nodes -text -out server.crt \
 178   -keyout server.key -subj "/CN=<em class="replaceable"><code>dbhost.yourdomain.com</code></em>"
 179 </pre><p>
 180     Then do:
 181 </p><pre class="programlisting">
 182 chmod og-rwx server.key
 183 </pre><p>
 184     because the server will reject the file if its permissions are more
 185     liberal than this.
 186     For more details on how to create your server private key and
 187     certificate, refer to the <span class="productname">OpenSSL</span> documentation.
 188    </p><p>
 189     While a self-signed certificate can be used for testing, a certificate
 190     signed by a certificate authority (<acronym class="acronym">CA</acronym>) (usually an
 191     enterprise-wide root <acronym class="acronym">CA</acronym>) should be used in production.
 192    </p><p>
 193     To create a server certificate whose identity can be validated
 194     by clients, first create a certificate signing request
 195     (<acronym class="acronym">CSR</acronym>) and a public/private key file:
 196 </p><pre class="programlisting">
 197 openssl req -new -nodes -text -out root.csr \
 198   -keyout root.key -subj "/CN=<em class="replaceable"><code>root.yourdomain.com</code></em>"
 199 chmod og-rwx root.key
 200 </pre><p>
 201     Then, sign the request with the key to create a root certificate
 202     authority (using the default <span class="productname">OpenSSL</span>
 203     configuration file location on <span class="productname">Linux</span>):
 204 </p><pre class="programlisting">
 205 openssl x509 -req -in root.csr -text -days 3650 \
 206   -extfile /etc/ssl/openssl.cnf -extensions v3_ca \
 207   -signkey root.key -out root.crt
 208 </pre><p>
 209     Finally, create a server certificate signed by the new root certificate
 210     authority:
 211 </p><pre class="programlisting">
 212 openssl req -new -nodes -text -out server.csr \
 213   -keyout server.key -subj "/CN=<em class="replaceable"><code>dbhost.yourdomain.com</code></em>"
 214 chmod og-rwx server.key
 215
 216 openssl x509 -req -in server.csr -text -days 365 \
 217   -CA root.crt -CAkey root.key -CAcreateserial \
 218   -out server.crt
 219 </pre><p>
 220     <code class="filename">server.crt</code> and <code class="filename">server.key</code>
 221     should be stored on the server, and <code class="filename">root.crt</code> should
 222     be stored on the client so the client can verify that the server's leaf
 223     certificate was signed by its trusted root certificate.
 224     <code class="filename">root.key</code> should be stored offline for use in
 225     creating future certificates.
 226    </p><p>
 227     It is also possible to create a chain of trust that includes
 228     intermediate certificates:
 229 </p><pre class="programlisting">
 230 # root
 231 openssl req -new -nodes -text -out root.csr \
 232   -keyout root.key -subj "/CN=<em class="replaceable"><code>root.yourdomain.com</code></em>"
 233 chmod og-rwx root.key
 234 openssl x509 -req -in root.csr -text -days 3650 \
 235   -extfile /etc/ssl/openssl.cnf -extensions v3_ca \
 236   -signkey root.key -out root.crt
 237
 238 # intermediate
 239 openssl req -new -nodes -text -out intermediate.csr \
 240   -keyout intermediate.key -subj "/CN=<em class="replaceable"><code>intermediate.yourdomain.com</code></em>"
 241 chmod og-rwx intermediate.key
 242 openssl x509 -req -in intermediate.csr -text -days 1825 \
 243   -extfile /etc/ssl/openssl.cnf -extensions v3_ca \
 244   -CA root.crt -CAkey root.key -CAcreateserial \
 245   -out intermediate.crt
 246
 247 # leaf
 248 openssl req -new -nodes -text -out server.csr \
 249   -keyout server.key -subj "/CN=<em class="replaceable"><code>dbhost.yourdomain.com</code></em>"
 250 chmod og-rwx server.key
 251 openssl x509 -req -in server.csr -text -days 365 \
 252   -CA intermediate.crt -CAkey intermediate.key -CAcreateserial \
 253   -out server.crt
 254 </pre><p>
 255     <code class="filename">server.crt</code> and
 256     <code class="filename">intermediate.crt</code> should be concatenated
 257     into a certificate file bundle and stored on the server.
 258     <code class="filename">server.key</code> should also be stored on the server.
 259     <code class="filename">root.crt</code> should be stored on the client so
 260     the client can verify that the server's leaf certificate was signed
 261     by a chain of certificates linked to its trusted root certificate.
 262     <code class="filename">root.key</code> and <code class="filename">intermediate.key</code>
 263     should be stored offline for use in creating future certificates.
 264    </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="18.8. Encryption Options">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="runtime.html" title="Chapter 18. Server Setup and Operation">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="gssapi-enc.html" title="18.10. Secure TCP/IP Connections with GSSAPI Encryption">Next</a></td></tr><tr><td width="40%" align="left" valign="top">18.8. Encryption Options </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 18.0 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 18.10. Secure TCP/IP Connections with GSSAPI Encryption</td></tr></table></div></body></html>