>From 4e15bdbec554609f0ed441bfc680479b8c6a04c1 Mon Sep 17 00:00:00 2001 From: Daniel Gustafsson Date: Tue, 4 Oct 2016 14:43:43 +0200 Subject: [PATCH 3/3] A first stab at updating the docs to handle multiple SSL libraries At this point it's a mere start and a nudge in the corner and not even close to a finished patch. Keeping the current structure of having a single set of config option seems key though, keeping the differences between the libraries small and contained. --- doc/src/sgml/libpq.sgml | 44 +++++++++++----- doc/src/sgml/runtime.sgml | 124 +++++++++++++++++++++++++++++++++------------- 2 files changed, 121 insertions(+), 47 deletions(-) diff --git a/doc/src/sgml/libpq.sgml b/doc/src/sgml/libpq.sgml index 4e34f00..78fcf4c 100644 --- a/doc/src/sgml/libpq.sgml +++ b/doc/src/sgml/libpq.sgml @@ -1237,13 +1237,14 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname sslcompression + This requires OpenSSL 1.0.0 or later, when using + other SSL libraries this setting will be ignored. If set to 1 (default), data sent over SSL connections will be compressed. - If set to 0, compression will be disabled (this requires - OpenSSL 1.0.0 or later). + If set to 0, compression will be disabled. This parameter is ignored if a connection without SSL is made, - or if the version of OpenSSL used does not support - it. + if the version of OpenSSL used does not support + it or an SSL library other than OpenSSL is used. Compression uses CPU time, but can improve throughput if @@ -1304,7 +1305,9 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname revocation list (CRL). Certificates listed in this file, if it exists, will be rejected while attempting to authenticate the server's certificate. The default is - ~/.postgresql/root.crl. + ~/.postgresql/root.crl. This setting is ignored + when using Secure Transport which require the + CRL to be included in the certificate. @@ -1900,8 +1903,7 @@ const char *PQsslAttribute(const PGconn *conn, const char *attribute_name); library - Name of the SSL implementation in use. (Currently, only - "OpenSSL" is implemented) + Name of the SSL implementation in use. @@ -7322,9 +7324,14 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*) PostgreSQL has native support for using SSL connections to encrypt client/server communications for increased security. See for details about the server-side - SSL functionality. + SSL functionality. Multiple SSL libraries are supported and + are enabled at build time. + Table lists the supported SSL + libraries. + + Using OpenSSL libpq reads the system-wide OpenSSL configuration file. By default, this @@ -7334,6 +7341,15 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*) OPENSSL_CONF to the name of the desired configuration file. + + + + Using Secure Transport + + Secure Transport utilize the Keychain of the + current user. WRITEME. + + Client Verification of Server Certificates @@ -7380,10 +7396,13 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*) - Certificate Revocation List (CRL) entries are also checked - if the file ~/.postgresql/root.crl exists + Certificate Revocation List (CRL) entries are also checked. When libpq + is built using OpenSSL + the file ~/.postgresql/root.crl is used (%APPDATA%\postgresql\root.crl on Microsoft - Windows). + Windows). When using Secure Transport the CRL must be + included in the server certificate for Keychain to perform certificate + revocation checks automatically. @@ -7661,7 +7680,8 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*) ~/.postgresql/root.crl certificates revoked by certificate authorities - server certificate must not be on this list + any certificate in this list will be rejected; server certificate + must not be on this list diff --git a/doc/src/sgml/runtime.sgml b/doc/src/sgml/runtime.sgml index 88ec120..632939c 100644 --- a/doc/src/sgml/runtime.sgml +++ b/doc/src/sgml/runtime.sgml @@ -2117,12 +2117,42 @@ pg_dumpall -p 5432 | psql -d postgres -p 5433 PostgreSQL has native support for using SSL connections to encrypt client/server communications - for increased security. This requires that - OpenSSL is installed on both client and + for increased security. This requires that a supported SSL library + is installed on both client and server systems and that support in PostgreSQL is - enabled at build time (see ). + enabled at build time (see ). Clients are + not required to use the same SSL library as the server, all supported + libraries are compatible. + Table lists the supported SSL + libraries. + + Supported SSL libraries + + + + Library + Platform + + + + + + + OpenSSL + All platforms supported by PostgreSQL + + + + Secure Transport + Apple macOS + + + + +
+ With SSL support compiled in, the PostgreSQL server can be started with @@ -2137,41 +2167,13 @@ pg_dumpall -p 5432 | psql -d postgres -p 5433 - PostgreSQL reads the system-wide - OpenSSL configuration file. By default, this - file is named openssl.cnf and is located in the - directory reported by openssl version -d. - This default can be overridden by setting environment variable - OPENSSL_CONF to the name of the desired configuration file. - - - - OpenSSL supports a wide range of ciphers - and authentication algorithms, of varying strength. While a list of - ciphers can be specified in the OpenSSL - configuration file, you can specify ciphers specifically for use by - the database server by modifying in - postgresql.conf. - - - - - It is possible to have authentication without encryption overhead by - using NULL-SHA or NULL-MD5 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. - - - - - To start in SSL mode, files containing the server certificate - and private key must exist. By default, these files are expected to be + To start in SSL mode, a server certificate + and private key must exist. By default, these are expected to be in files named server.crt and server.key, respectively, in the server's data directory, but other names and locations can be specified using the configuration parameters - and . + and . See the notes on the library used + for specifics on how certificates and keys can be specified. @@ -2202,6 +2204,58 @@ pg_dumpall -p 5432 | psql -d postgres -p 5433 root.crt files. + + + It is possible to have authentication without encryption overhead by + using NULL ciphers (NULL-SHA or NULL-MD5 in + OpenSSL for example). 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. + + + + + Using OpenSSL + + + PostgreSQL reads the system-wide + OpenSSL configuration file. By default, this + file is named openssl.cnf and is located in the + directory reported by openssl version -d. + This default can be overridden by setting environment variable + OPENSSL_CONF to the name of the desired configuration file. + + + + OpenSSL supports a wide range of ciphers + and authentication algorithms, of varying strength. While a list of + ciphers can be specified in the OpenSSL + configuration file, you can specify ciphers specifically for use by + the database server by modifying in + postgresql.conf. + + + + + Using Secure Transport + + + Secure Transport can use certificates and + keys either stored in files or load them from + Keychain by prefixing the configuration + parameters and + with keychain:. + It is not possible to load certificate revocation list, CRL, + manually with Secure Transport, certificate revocation + can only be handled from within Keychain. When using a + certificate stored in Keychain, certificate revocation + is automatically supported via CRL and OCSP if the URL for + the revocation responder is contained in the certificate. + + + Using Client Certificates -- 2.6.4 (Apple Git-63)