1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
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 15.4 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</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</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</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</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</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</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 15.4 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>
|
