database/postgres
1
0
Fork 0
mirror of https://github.com/postgres/postgres.git synced 2025-07-30 11:03:19 +03:00
Code Activity

Remove sslverify parameter again, replacing it with two new sslmode values:

Browse Source 
"verify-ca" and "verify-full".

Since "prefer" remains the default, this will make certificate validation
off by default, which should lead to less upgrade issues.
This commit is contained in:
Magnus Hagander
2009-04-24 09:43:10 +00:00
parent 420ea68817
commit e883d0b551
5 changed files with 89 additions and 102 deletions
Download Patch File Download Diff File Expand all files Collapse all files

126
doc/src/sgml/libpq.sgml
View File

@ -1,4 +1,4 @@
<!-- $PostgreSQL: pgsql/doc/src/sgml/libpq.sgml,v 1.285 2009/04/15 13:03:11 momjian Exp $ -->
<!-- $PostgreSQL: pgsql/doc/src/sgml/libpq.sgml,v 1.286 2009/04/24 09:43:09 mha Exp $ -->
<chapter id="libpq">
<title><application>libpq</application> - C Library</title>
@ -292,7 +292,21 @@
<entry><literal>require</></entry>
<entry>only try an <acronym>SSL</> connection</entry>
</row>
<row>
<entry><literal>verify-ca</></entry>
<entry>only try an <acronym>SSL</> connection, and verify that
the server certificate is issued by a trusted <acronym>CA</>.
</entry>
</row>
<row>
<entry><literal>verify-full</></entry>
<entry>only try an <acronym>SSL</> connection, verify that
the server certificate is issued by a trusted <acronym>CA</> and
that the server hostname matches that in the certificate.</entry>
</row>
</tbody>
</tgroup>
</table>
@ -311,43 +325,6 @@
</listitem>
</varlistentry>
<varlistentry id="libpq-connect-sslverify" xreflabel="sslverify">
<term><literal>sslverify</literal></term>
<listitem>
<para>
This option controls how libpq verifies the certificate on the
server when performing an <acronym>SSL</> connection. There are
three options: <literal>none</> disables verification completely
(not recommended); <literal>cert</> enables verification that
the server certificate chains to a known certificate
authority (CA); <literal>cn</> will both verify that the
certificate chains to a known CA and that the <literal>cn</>
attribute of the server certificate matches the server's
hostname (default).
</para>
<para>
It is always recommended to use the <literal>cn</> value for
this parameter, since this is the only option that prevents
man-in-the-middle attacks. Note that this requires the server
name on the certificate to match exactly with the host name
used for the connection, and therefore does not support connections
to aliased names. It can be used with pure IP address connections
only if the certificate also has just the IP address in the
<literal>cn</> field.
</para>
<para>
If the <literal>cn</> attribute in the certificate sent by the
server starts with an asterisk (<literal>*</>), it will be treated
as a wildcard. This wildcard can only be present at the start of
the value, and will match all characters <emphasis>except</> a
dot (<literal>.</>). This means the certificate will not match
subdomains.
</para>
</listitem>
</varlistentry>
<varlistentry id="libpq-connect-requiressl" xreflabel="requiressl">
<term><literal>requiressl</literal></term>
<listitem>
@ -5800,16 +5777,6 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough)
</para>
</listitem>
<listitem>
<para>
<indexterm>
<primary><envar>PGSSLVERIFY</envar></primary>
</indexterm>
<envar>PGSSLVERIFY</envar> behaves the same as <xref
linkend="libpq-connect-sslverify"> connection parameter.
</para>
</listitem>
<listitem>
<para>
<indexterm>
@ -6162,25 +6129,60 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough)
file.
</para>
<sect2 id="libq-ssl-certificates">
<title>Certificate verification</title>
<para>
When the <literal>sslverify</> parameter is set to <literal>cn</> or
<literal>cert</>, libpq requires a trustworthy server certificate by
checking the certificate chain up to a <acronym>CA</>.
To allow verification, place the certificate of a trusted <acronym>CA</>
in the file <filename>~/.postgresql/root.crt</> in the user's home directory.
(On Microsoft Windows the file is named
By default, <productname>PostgreSQL</> will not perform any validation of
the server certificate. This means that it is possible to spoof the server
identity (for example by modifying a DNS record or by taking over the server
IP address) without the client knowing. In order to prevent this,
<acronym>SSL</> certificate validation must be used.
</para>
<para>
If the parameter <literal>sslmode</> is set to <literal>verify-ca</>
libpq will verify that the server is trustworthy by checking the certificate
chain up to a trusted <acronym>CA</>. If <literal>sslmode</> is set to
<literal>verify-full</>, libpq will <emphasis>also</> verify that the server
hostname matches that of the certificate. The SSL connection will fail if
the server certificate cannot be verified. <literal>verify-full</> is
recommended in most security sensitive environments.
</para>
<para>
In <literal>verify-full</> mode, the <literal>cn</> attribute of the
certificate is matched against the hostname. If the <literal>cn</>
attribute starts with an asterisk (<literal>*</>), it will be treated as
a wildcard, and will match all characters <emphasis>except</> a dot
(<literal>.</>). This means the certificate will not match subdomains.
If the connection is made using an IP address instead of a hostname, the
IP address will be matched (without doing any DNS lookups).
</para>
<para>
To allow verification, the certificate of a trusted <acronym>CA</> must be
placed in the file <filename>~/.postgresql/root.crt</> in the user's home
directory. (On Microsoft Windows the file is named
<filename>%APPDATA%\postgresql\root.crt</filename>.)
<application>libpq</application> will then verify that the server's
certificate is signed by one of the trusted certificate authorities.
The SSL connection will fail if the server certificate cannot be verified.
</para>
<para>
Certificate Revocation List (CRL) entries are also checked
if the file <filename>~/.postgresql/root.crl</filename> exists
(<filename>%APPDATA%\postgresql\root.crl</filename> on Microsoft
Windows).
</para>
<para>
The location of the root certificate store and the CRL can be overridden
by the connection parameters <literal>sslrootcert</> and <literal>sslcrl</>
or the environment variables <envar>PGSSLROOTCERT</> and <envar>PGSSLCRL</>.
</para>
</sect2>
<sect2 id="libpq-ssl-clientcert">
<title>Client certificates</title>
<para>
If the server requests a trusted client certificate,
@ -6201,6 +6203,9 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough)
environment variables <envar>PGSSLCERT</> and <envar>PGSSLKEY</>.
</para>
</sect2>
<sect2 id="libpq-ssl-fileusage">
<title>SSL File Usage</title>
<table id="libpq-ssl-file-usage">
<title>Libpq/Client SSL File Usage</title>
<tgroup cols="3">
@ -6243,6 +6248,10 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough)
</tbody>
</tgroup>
</table>
</sect2>
<sect2 id="libpq-ssl-initialize">
<title>SSL library initialization</title>
<para>
If your application initializes <literal>libssl</> and/or
@ -6330,6 +6339,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough)
</varlistentry>
</variablelist>
</para>
</sect2>
</sect1>

6
doc/src/sgml/runtime.sgml
View File

@ -1,4 +1,4 @@
<!-- $PostgreSQL: pgsql/doc/src/sgml/runtime.sgml,v 1.425 2009/01/09 13:37:18 petere Exp $ -->
<!-- $PostgreSQL: pgsql/doc/src/sgml/runtime.sgml,v 1.426 2009/04/24 09:43:09 mha Exp $ -->
<chapter Id="runtime">
<title>Server Setup and Operation</title>
@ -1422,8 +1422,8 @@ $ <userinput>kill -INT `head -1 /usr/local/pgsql/data/postmaster.pid`</userinput
<filename>server.key</filename> (key) and
<filename>server.crt</filename> (certificate) files (<xref
linkend="ssl-tcp">). The TCP client must connect using
<literal>sslmode='require'</>, specify <literal>sslverify='cn'</>
or <literal>sslverify='cert'</> and have the required certificate
<literal>sslmode='verify-ca'</> or
<literal>'verify-full'</> and have the required certificate
files present (<xref linkend="libpq-connect">).
</para>
</sect1>