From ef9e113d60eae797327ce5a9d7b1553afc743720 Mon Sep 17 00:00:00 2001 From: Daniel Gustafsson Date: Thu, 17 Aug 2017 14:43:53 +0200 Subject: [PATCH 3/4] WIP: A first stab at documentation for Secure Transport This is a rough first stab at amending the documentation to support having multiple SSL backends, and adding Secure Transport specific information. --- doc/src/sgml/config.sgml | 20 ++++++++ doc/src/sgml/libpq.sgml | 52 ++++++++++++++----- doc/src/sgml/runtime.sgml | 127 +++++++++++++++++++++++++++++++++------------- 3 files changed, 152 insertions(+), 47 deletions(-) diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml index 2b6255ed95..22942d5680 100644 --- a/doc/src/sgml/config.sgml +++ b/doc/src/sgml/config.sgml @@ -1046,6 +1046,26 @@ include_dir 'conf.d' + + ssl_keychain_file (string) + + ssl_keychain_file configuration parameter + + + + + Specifies the name of the file containing the a Keychain. Relative + paths are relative to the current users system Keychain folder + (typically Library/Keychains). + Absolute paths can be used to use a Keychain located elsewhere. + This parameter can only be set in the postgresql.conf + file or on the server command line. + This parameter is only available when the server has been configured + with support for Secure Transport. + + + + ssl_ciphers (string) diff --git a/doc/src/sgml/libpq.sgml b/doc/src/sgml/libpq.sgml index ad5e9b95b4..0f204be205 100644 --- a/doc/src/sgml/libpq.sgml +++ b/doc/src/sgml/libpq.sgml @@ -1338,13 +1338,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 @@ -1405,7 +1406,11 @@ 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 invalid + when using Secure Transport, which require the + CRL to be imported into the default Keychain. In order to not + cause unintentional silent ignore, the server will abort if + this parameter is configured. @@ -2041,8 +2046,8 @@ 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. Possible values are + "OpenSSL" and "SecureTransport". @@ -7524,9 +7529,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, one + of which is enabled at build time. + Table lists the supported SSL + libraries. + + Using OpenSSL libpq reads the system-wide OpenSSL configuration file. By default, this @@ -7536,6 +7546,20 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*) OPENSSL_CONF to the name of the desired configuration file. + + + + Using Secure Transport + + libpq will use the default Keychain, as well + as a custom one if configured, when using + Secure Transport. Certificates and keys can be + loaded from either PEM files, or from the Keychain. To load an identity + from a Keychain, the ssl_cert parameter is prefixed with + keychain: followed by the certificate common name rather than + the filename. + + Client Verification of Server Certificates @@ -7582,10 +7606,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 + imported in the Keychain holding the server certificate to perform certificate + revocation checks automatically. @@ -7863,7 +7890,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 6d57525515..a23715b8c6 100644 --- a/doc/src/sgml/runtime.sgml +++ b/doc/src/sgml/runtime.sgml @@ -2169,12 +2169,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 10.11 El Capitan+ + + + + +
+ With SSL support compiled in, the PostgreSQL server can be started with @@ -2189,41 +2219,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. @@ -2258,6 +2260,55 @@ 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 as an identity from a + Keychain. To load an identity, the default + Keychain as well as the + Keychain specified by the + parameter is searched. The identity + is specified by prefixing with + keychain: and specifying the common name of the certificate. + + + Using Client Certificates @@ -2363,6 +2414,12 @@ pg_dumpall -p 5432 | psql -d postgres -p 5433 client certificate must not be on this list + + + server identities + searched for server identities (certificate and key) + + -- 2.14.1.145.gb3622a4ee