From e883d0b551bbb7f4e5eeef486c3abde4ae14cdfc Mon Sep 17 00:00:00 2001 From: Magnus Hagander Date: Fri, 24 Apr 2009 09:43:10 +0000 Subject: Remove sslverify parameter again, replacing it with two new sslmode values: "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. --- doc/src/sgml/libpq.sgml | 126 +++++++++++++++++++++++++--------------------- doc/src/sgml/runtime.sgml | 6 +-- 2 files changed, 71 insertions(+), 61 deletions(-) (limited to 'doc/src') diff --git a/doc/src/sgml/libpq.sgml b/doc/src/sgml/libpq.sgml index 4e7748c3c52..61a3e5d5e0e 100644 --- a/doc/src/sgml/libpq.sgml +++ b/doc/src/sgml/libpq.sgml @@ -1,4 +1,4 @@ - + <application>libpq</application> - C Library @@ -292,7 +292,21 @@ require only try an SSL connection - + + + verify-ca + only try an SSL connection, and verify that + the server certificate is issued by a trusted CA. + + + + + verify-full + only try an SSL connection, verify that + the server certificate is issued by a trusted CA and + that the server hostname matches that in the certificate. + + @@ -311,43 +325,6 @@ - - sslverify - - - This option controls how libpq verifies the certificate on the - server when performing an SSL connection. There are - three options: none disables verification completely - (not recommended); cert enables verification that - the server certificate chains to a known certificate - authority (CA); cn will both verify that the - certificate chains to a known CA and that the cn - attribute of the server certificate matches the server's - hostname (default). - - - - It is always recommended to use the 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 - cn field. - - - - If the cn attribute in the certificate sent by the - server starts with an asterisk (*), it will be treated - as a wildcard. This wildcard can only be present at the start of - the value, and will match all characters except a - dot (.). This means the certificate will not match - subdomains. - - - - requiressl @@ -5800,16 +5777,6 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) - - - - PGSSLVERIFY - - PGSSLVERIFY behaves the same as connection parameter. - - - @@ -6162,25 +6129,60 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) file. + + Certificate verification + + + By default, 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, + SSL certificate validation must be used. + + + + If the parameter sslmode is set to verify-ca + libpq will verify that the server is trustworthy by checking the certificate + chain up to a trusted CA. If sslmode is set to + verify-full, libpq will also verify that the server + hostname matches that of the certificate. The SSL connection will fail if + the server certificate cannot be verified. verify-full is + recommended in most security sensitive environments. + + - When the sslverify parameter is set to cn or - cert, libpq requires a trustworthy server certificate by - checking the certificate chain up to a CA. - To allow verification, place the certificate of a trusted CA - in the file ~/.postgresql/root.crt in the user's home directory. - (On Microsoft Windows the file is named + In verify-full mode, the cn attribute of the + certificate is matched against the hostname. If the cn + attribute starts with an asterisk (*), it will be treated as + a wildcard, and will match all characters except a dot + (.). 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). + + + + To allow verification, the certificate of a trusted CA must be + placed in the file ~/.postgresql/root.crt in the user's home + directory. (On Microsoft Windows the file is named %APPDATA%\postgresql\root.crt.) - libpq 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. + + + Certificate Revocation List (CRL) entries are also checked if the file ~/.postgresql/root.crl exists (%APPDATA%\postgresql\root.crl on Microsoft Windows). + + + The location of the root certificate store and the CRL can be overridden by the connection parameters sslrootcert and sslcrl or the environment variables PGSSLROOTCERT and PGSSLCRL. + + + + Client certificates If the server requests a trusted client certificate, @@ -6201,6 +6203,9 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) environment variables PGSSLCERT and PGSSLKEY. + + + SSL File Usage Libpq/Client SSL File Usage @@ -6243,6 +6248,10 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough)
+ + + + SSL library initialization If your application initializes libssl and/or @@ -6330,6 +6339,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) + diff --git a/doc/src/sgml/runtime.sgml b/doc/src/sgml/runtime.sgml index abfcd5dffb1..0d54a1cc959 100644 --- a/doc/src/sgml/runtime.sgml +++ b/doc/src/sgml/runtime.sgml @@ -1,4 +1,4 @@ - + Server Setup and Operation @@ -1422,8 +1422,8 @@ $ kill -INT `head -1 /usr/local/pgsql/data/postmaster.pid`server.key (key) and server.crt (certificate) files (). The TCP client must connect using - sslmode='require', specify sslverify='cn' - or sslverify='cert' and have the required certificate + sslmode='verify-ca' or + 'verify-full' and have the required certificate files present (). -- cgit v1.2.3