From c51041f4ba52d722c336a1ac28ebe6be61df88bc Mon Sep 17 00:00:00 2001 From: Bruce Momjian Date: Tue, 29 Aug 2000 04:15:43 +0000 Subject: [PATCH] Here is a patch against the same cvs tree as the SSL patch (Aug 20). I hope I didn't mess the SGML up too bad, but somebody should definitly look that over. I tried to steal as much as I could from around :-) This patch updates: * Installation instructions (paragraph on how to compile with openssl) * Documentation of pg_hba.conf (added "hostssl" record docs) * Libpq documentation (added connection option, documentation of PQgetssl() function) * Add section on SSL to "Server Runtime Environment" If you beleive any particular area needs more attention, please let me know. //Magnus --- doc/src/sgml/client-auth.sgml | 17 +++++++++- doc/src/sgml/installation.sgml | 20 +++++++++++- doc/src/sgml/libpq.sgml | 32 ++++++++++++++++++- doc/src/sgml/runtime.sgml | 58 +++++++++++++++++++++++++++++++++- 4 files changed, 123 insertions(+), 4 deletions(-) diff --git a/doc/src/sgml/client-auth.sgml b/doc/src/sgml/client-auth.sgml index 31d910b302a..6cf5aef377d 100644 --- a/doc/src/sgml/client-auth.sgml +++ b/doc/src/sgml/client-auth.sgml @@ -1,4 +1,4 @@ - + Client Authentication @@ -53,6 +53,7 @@ local database authentication-method [ authentication-option ] host database IP-address IP-mask authentication-method [ authentication-option ] +hostssl database IP-address IP-mask authentication-method [ authentication-option ] The meaning of the fields is as follows: @@ -79,6 +80,20 @@ host database IP-address < + + hostssl + + + This record pertains to connection attemps with SSL over + TCP/IP. Note that SSL connections are completely disabled + unless the server is started with the , + and also require ordinary TCP/IP connections to be enabled. + SSL connections also require SSL support to be enabled in + the backend at compile time. + + + + database diff --git a/doc/src/sgml/installation.sgml b/doc/src/sgml/installation.sgml index 62ac008083a..261c283ac4d 100644 --- a/doc/src/sgml/installation.sgml +++ b/doc/src/sgml/installation.sgml @@ -1,4 +1,4 @@ - + <![%flattext-install-include[<productname>PostgreSQL</> ]]>Installation Instructions @@ -577,6 +577,24 @@ su - postgres + + --with-openssl=DIRECTORY + + + Build with support for SSL (encrypted) connections. + This requires the OpenSSL library to be installed. + The DIRECTORY argument specifies the + root directory of the OpenSSL installation. + + + + configure will check for the required header + files and libraries to make sure that your OpenSSL + installation is sufficient before proceeding. + + + + --enable-syslog diff --git a/doc/src/sgml/libpq.sgml b/doc/src/sgml/libpq.sgml index c14f9ee260d..648406e5462 100644 --- a/doc/src/sgml/libpq.sgml +++ b/doc/src/sgml/libpq.sgml @@ -1,5 +1,5 @@ @@ -177,6 +177,17 @@ PGconn *PQconnectdb(const char *conninfo) + + + requiressl + + + Set to '1' to require SSL connection to the backend. Libpq + will then refuse to connect if the server does not support + SSL. Set to '0' (default) to negotiate with server. + + + If any parameter is unspecified, then the corresponding @@ -633,6 +644,25 @@ int PQbackendPID(const PGconn *conn); server host, not the local host! + + + + PQgetssl + Returns the SSL structure used in the connection, or NULL + if SSL is not in use. + +SSL *PQgetssl(const PGconn *conn); + + This structure can be used to verify encryption levels, check + server certificate and more. Refer to the OpenSSL documentation + for information about this structure. + + + You must define USE_SSL in order to get the + prototype for this function. Doing this will also + automatically include ssl.h from OpenSSL. + + diff --git a/doc/src/sgml/runtime.sgml b/doc/src/sgml/runtime.sgml index 0142b6b6452..69e40f6f58c 100644 --- a/doc/src/sgml/runtime.sgml +++ b/doc/src/sgml/runtime.sgml @@ -1,5 +1,5 @@ @@ -1726,6 +1726,62 @@ perl: warning: Falling back to the standard locale ("C"). + + Secure TCP/IP Connection with SSL + + + PostgreSQL has native support for connections over SSL to encrypt + client/server communications for increased security. This requires + OpenSSL to be installed on both client + and server systems and support enabled at compile-time using + the configure script. + + + + With SSL support compiled in, the Postgres backend can be + started with argument -l to enable SSL connections. + When starting in SSL mode, the postmaster will look for the + files server.key and + server.cert in the PGDATA + directory. These files should contain the server private key and + certificate respectively. If the private key is protected with a + passphrase, the postmaster will prompt for the passphrase and not + start until it has been provided. + + + + The postmaster will listen for both standard and SSL connections + on the same TCP/IP port, and will negotiate with any connecting + client wether to use SSL or not. Use the pg_hba.conf + file to optionally require SSL in order to accept a connection. + + + + For details on how to create your server private key and certificate, + refer to the OpenSSL documentation. A simple self-signed certificate + can be used to get started testing, but a certificate signed by a CA + (either one of the global CAs or a local one) should be used in + production so the client can verify the servers identity. To create + a quick self-signed certificate, use the CA.pl + script included in OpenSSL: + + CA.pl -newcert + + Fill out the information the script asks for. Make sure to enter + the local hostname as Common Name. The script will generate a key + which is passphrase protected. To remove the passphrase (required + if you want automatic startup of the postmaster), run the command + + openssl x509 -inform PEM -outform PEM -in newreq.pem -out newkey_no_passphrase.pem + + Enter the old passphrase to unlock the existing key. Copy the file + newreq.pem to PGDATA/server.cert + and newkey_no_passphrase.pem to + PGDATA/server.key. Remove the PRIVATE KEY part + from the server.cert using any text editor. + + + Secure TCP/IP Connection with SSH