PostgreSQL 8.4beta1 Documentation | ||||
---|---|---|---|---|
Prev | Fast Backward | Chapter 30. libpq - C Library | Fast Forward | Next |
PostgreSQL has native support for using SSL connections to encrypt client/server communications for increased security. See Section 17.8 for details about the server-side SSL functionality.
libpq 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.
When the sslverify parameter is set to cn or cert, libpq will verify that the server certificate is trustworthy by checking the certificate chain up to a CA. For this to work, 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 %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 does not present a trusted certificate. 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.
If the server requests a trusted client certificate, libpq will send the certificate stored in file ~/.postgresql/postgresql.crt in the user's home directory. The certificate must be signed by one of the certificate authorities (CA) trusted by the server. A matching private key file ~/.postgresql/postgresql.key must also be present. The private key file must not allow any access to world or group; achieve this by the command chmod 0600 ~/.postgresql/postgresql.key. On Microsoft Windows these files are named %APPDATA%\postgresql\postgresql.crt and %APPDATA%\postgresql\postgresql.key, and there is no special permissions check since the directory is presumed secure. The location of the certificate and key files can be overridden by the connection parameters sslcert and sslkey or the environment variables PGSSLCERT and PGSSLKEY.
Table 30-1. Libpq/Client SSL File Usage
File | Contents | Effect |
---|---|---|
~/.postgresql/postgresql.crt | client certificate | requested by server |
~/.postgresql/postgresql.key | client private key | proves client certificate sent by owner; does not indicate certificate owner is trustworthy |
~/.postgresql/root.crt | trusted certificate authorities | checks server certificate is signed by a trusted certificate authority |
~/.postgresql/root.crl | certificates revoked by certificate authorities | server certificate must not be on this list |
If your application initializes libssl and/or
libcrypto libraries and libpq
is built with SSL support, you should call
PQinitOpenSSL
to tell libpq
that the libssl and/or libcrypto libraries
have been initialized by your application, so that
libpq will not also initialize those libraries.
See http://h71000.www7.hp.com/doc/83final/BA554_90007/ch04.html
for details on the SSL API.
PQinitOpenSSL
Allows applications to select which security libraries to initialize.
void PQinitOpenSSL(int do_ssl, init do_crypto);
When do_ssl is non-zero, libpq
will initialize the OpenSSL library before first
opening a database connection. When do_crypto is
non-zero, the libcrypto library will be initialized. By
default (if PQinitOpenSSL
is not called), both libraries
are initialized. When SSL support is not compiled in, this function is
present but does nothing.
If your application uses and initializes either OpenSSL or its underlying libcrypto library, you must call this function with zeroes for the appropriate parameter(s) before first opening a database connection. Also be sure that you have done that initialization before opening a database connection.
PQinitSSL
Allows applications to select which security libraries to initialize.
void PQinitSSL(int do_ssl);
This function is equivalent to PQinitOpenSSL(do_ssl, do_ssl). It is sufficient for applications that initialize both or neither of OpenSSL and libcrypto.
PQinitSSL
has been present since
PostgreSQL 8.0, while PQinitOpenSSL
was added in PostgreSQL 8.4, so PQinitSSL
might be preferable for applications that need to work with older
versions of libpq.