begriffs open source - ai-pg/blob - full-docs/txt/libpq-ssl.txt

   1
   2 32.19. SSL Support #
   3
   4    32.19.1. Client Verification of Server Certificates
   5    32.19.2. Client Certificates
   6    32.19.3. Protection Provided in Different Modes
   7    32.19.4. SSL Client File Usage
   8    32.19.5. SSL Library Initialization
   9
  10    PostgreSQL has native support for using SSL connections to encrypt
  11    client/server communications using TLS protocols for increased
  12    security. See Section 18.9 for details about the server-side SSL
  13    functionality.
  14
  15    libpq reads the system-wide OpenSSL configuration file. By default,
  16    this file is named openssl.cnf and is located in the directory reported
  17    by openssl version -d. This default can be overridden by setting
  18    environment variable OPENSSL_CONF to the name of the desired
  19    configuration file.
  20
  21 32.19.1. Client Verification of Server Certificates #
  22
  23    By default, PostgreSQL will not perform any verification of the server
  24    certificate. This means that it is possible to spoof the server
  25    identity (for example by modifying a DNS record or by taking over the
  26    server IP address) without the client knowing. In order to prevent
  27    spoofing, the client must be able to verify the server's identity via a
  28    chain of trust. A chain of trust is established by placing a root
  29    (self-signed) certificate authority (CA) certificate on one computer
  30    and a leaf certificate signed by the root certificate on another
  31    computer. It is also possible to use an “intermediate” certificate
  32    which is signed by the root certificate and signs leaf certificates.
  33
  34    To allow the client to verify the identity of the server, place a root
  35    certificate on the client and a leaf certificate signed by the root
  36    certificate on the server. To allow the server to verify the identity
  37    of the client, place a root certificate on the server and a leaf
  38    certificate signed by the root certificate on the client. One or more
  39    intermediate certificates (usually stored with the leaf certificate)
  40    can also be used to link the leaf certificate to the root certificate.
  41
  42    Once a chain of trust has been established, there are two ways for the
  43    client to validate the leaf certificate sent by the server. If the
  44    parameter sslmode is set to verify-ca, libpq will verify that the
  45    server is trustworthy by checking the certificate chain up to the root
  46    certificate stored on the client. If sslmode is set to verify-full,
  47    libpq will also verify that the server host name matches the name
  48    stored in the server certificate. The SSL connection will fail if the
  49    server certificate cannot be verified. verify-full is recommended in
  50    most security-sensitive environments.
  51
  52    In verify-full mode, the host name is matched against the certificate's
  53    Subject Alternative Name attribute(s) (SAN), or against the Common Name
  54    attribute if no SAN of type dNSName is present. If the certificate's
  55    name attribute starts with an asterisk (*), the asterisk will be
  56    treated as a wildcard, which will match all characters except a dot
  57    (.). This means the certificate will not match subdomains. If the
  58    connection is made using an IP address instead of a host name, the IP
  59    address will be matched (without doing any DNS lookups) against SANs of
  60    type iPAddress or dNSName. If no iPAddress SAN is present and no
  61    matching dNSName SAN is present, the host IP address is matched against
  62    the Common Name attribute.
  63
  64 Note
  65
  66    For backward compatibility with earlier versions of PostgreSQL, the
  67    host IP address is verified in a manner different from RFC 6125. The
  68    host IP address is always matched against dNSName SANs as well as
  69    iPAddress SANs, and can be matched against the Common Name attribute if
  70    no relevant SANs exist.
  71
  72    To allow server certificate verification, one or more root certificates
  73    must be placed in the file ~/.postgresql/root.crt in the user's home
  74    directory. (On Microsoft Windows the file is named
  75    %APPDATA%\postgresql\root.crt.) Intermediate certificates should also
  76    be added to the file if they are needed to link the certificate chain
  77    sent by the server to the root certificates stored on the client.
  78
  79    Certificate Revocation List (CRL) entries are also checked if the file
  80    ~/.postgresql/root.crl exists (%APPDATA%\postgresql\root.crl on
  81    Microsoft Windows).
  82
  83    The location of the root certificate file and the CRL can be changed by
  84    setting the connection parameters sslrootcert and sslcrl or the
  85    environment variables PGSSLROOTCERT and PGSSLCRL. sslcrldir or the
  86    environment variable PGSSLCRLDIR can also be used to specify a
  87    directory containing CRL files.
  88
  89 Note
  90
  91    For backwards compatibility with earlier versions of PostgreSQL, if a
  92    root CA file exists, the behavior of sslmode=require will be the same
  93    as that of verify-ca, meaning the server certificate is validated
  94    against the CA. Relying on this behavior is discouraged, and
  95    applications that need certificate validation should always use
  96    verify-ca or verify-full.
  97
  98 32.19.2. Client Certificates #
  99
 100    If the server attempts to verify the identity of the client by
 101    requesting the client's leaf certificate, libpq will send the
 102    certificate(s) stored in file ~/.postgresql/postgresql.crt in the
 103    user's home directory. The certificates must chain to the root
 104    certificate trusted by the server. A matching private key file
 105    ~/.postgresql/postgresql.key must also be present. On Microsoft Windows
 106    these files are named %APPDATA%\postgresql\postgresql.crt and
 107    %APPDATA%\postgresql\postgresql.key. The location of the certificate
 108    and key files can be overridden by the connection parameters sslcert
 109    and sslkey, or by the environment variables PGSSLCERT and PGSSLKEY.
 110
 111    On Unix systems, the permissions on the private key file must disallow
 112    any access to world or group; achieve this by a command such as chmod
 113    0600 ~/.postgresql/postgresql.key. Alternatively, the file can be owned
 114    by root and have group read access (that is, 0640 permissions). That
 115    setup is intended for installations where certificate and key files are
 116    managed by the operating system. The user of libpq should then be made
 117    a member of the group that has access to those certificate and key
 118    files. (On Microsoft Windows, there is no file permissions check, since
 119    the %APPDATA%\postgresql directory is presumed secure.)
 120
 121    The first certificate in postgresql.crt must be the client's
 122    certificate because it must match the client's private key.
 123    “Intermediate” certificates can be optionally appended to the file —
 124    doing so avoids requiring storage of intermediate certificates on the
 125    server (ssl_ca_file).
 126
 127    The certificate and key may be in PEM or ASN.1 DER format.
 128
 129    The key may be stored in cleartext or encrypted with a passphrase using
 130    any algorithm supported by OpenSSL, like AES-128. If the key is stored
 131    encrypted, then the passphrase may be provided in the sslpassword
 132    connection option. If an encrypted key is supplied and the sslpassword
 133    option is absent or blank, a password will be prompted for
 134    interactively by OpenSSL with a Enter PEM pass phrase: prompt if a TTY
 135    is available. Applications can override the client certificate prompt
 136    and the handling of the sslpassword parameter by supplying their own
 137    key password callback; see PQsetSSLKeyPassHook_OpenSSL.
 138
 139    For instructions on creating certificates, see Section 18.9.5.
 140
 141 32.19.3. Protection Provided in Different Modes #
 142
 143    The different values for the sslmode parameter provide different levels
 144    of protection. SSL can provide protection against three types of
 145    attacks:
 146
 147    Eavesdropping
 148           If a third party can examine the network traffic between the
 149           client and the server, it can read both connection information
 150           (including the user name and password) and the data that is
 151           passed. SSL uses encryption to prevent this.
 152
 153    Man-in-the-middle (MITM)
 154           If a third party can modify the data while passing between the
 155           client and server, it can pretend to be the server and therefore
 156           see and modify data even if it is encrypted. The third party can
 157           then forward the connection information and data to the original
 158           server, making it impossible to detect this attack. Common
 159           vectors to do this include DNS poisoning and address hijacking,
 160           whereby the client is directed to a different server than
 161           intended. There are also several other attack methods that can
 162           accomplish this. SSL uses certificate verification to prevent
 163           this, by authenticating the server to the client.
 164
 165    Impersonation
 166           If a third party can pretend to be an authorized client, it can
 167           simply access data it should not have access to. Typically this
 168           can happen through insecure password management. SSL uses client
 169           certificates to prevent this, by making sure that only holders
 170           of valid certificates can access the server.
 171
 172    For a connection to be known SSL-secured, SSL usage must be configured
 173    on both the client and the server before the connection is made. If it
 174    is only configured on the server, the client may end up sending
 175    sensitive information (e.g., passwords) before it knows that the server
 176    requires high security. In libpq, secure connections can be ensured by
 177    setting the sslmode parameter to verify-full or verify-ca, and
 178    providing the system with a root certificate to verify against. This is
 179    analogous to using an https URL for encrypted web browsing.
 180
 181    Once the server has been authenticated, the client can pass sensitive
 182    data. This means that up until this point, the client does not need to
 183    know if certificates will be used for authentication, making it safe to
 184    specify that only in the server configuration.
 185
 186    All SSL options carry overhead in the form of encryption and
 187    key-exchange, so there is a trade-off that has to be made between
 188    performance and security. Table 32.1 illustrates the risks the
 189    different sslmode values protect against, and what statement they make
 190    about security and overhead.
 191
 192    Table 32.1. SSL Mode Descriptions
 193    sslmode Eavesdropping protection MITM protection Statement
 194    disable No No I don't care about security, and I don't want to pay the
 195    overhead of encryption.
 196    allow Maybe No I don't care about security, but I will pay the overhead
 197    of encryption if the server insists on it.
 198    prefer Maybe No I don't care about encryption, but I wish to pay the
 199    overhead of encryption if the server supports it.
 200    require Yes No I want my data to be encrypted, and I accept the
 201    overhead. I trust that the network will make sure I always connect to
 202    the server I want.
 203    verify-ca Yes Depends on CA policy I want my data encrypted, and I
 204    accept the overhead. I want to be sure that I connect to a server that
 205    I trust.
 206    verify-full Yes Yes I want my data encrypted, and I accept the
 207    overhead. I want to be sure that I connect to a server I trust, and
 208    that it's the one I specify.
 209
 210    The difference between verify-ca and verify-full depends on the policy
 211    of the root CA. If a public CA is used, verify-ca allows connections to
 212    a server that somebody else may have registered with the CA. In this
 213    case, verify-full should always be used. If a local CA is used, or even
 214    a self-signed certificate, using verify-ca often provides enough
 215    protection.
 216
 217    The default value for sslmode is prefer. As is shown in the table, this
 218    makes no sense from a security point of view, and it only promises
 219    performance overhead if possible. It is only provided as the default
 220    for backward compatibility, and is not recommended in secure
 221    deployments.
 222
 223 32.19.4. SSL Client File Usage #
 224
 225    Table 32.2 summarizes the files that are relevant to the SSL setup on
 226    the client.
 227
 228    Table 32.2. Libpq/Client SSL File Usage
 229    File Contents Effect
 230    ~/.postgresql/postgresql.crt client certificate sent to server
 231    ~/.postgresql/postgresql.key client private key proves client
 232    certificate sent by owner; does not indicate certificate owner is
 233    trustworthy
 234    ~/.postgresql/root.crt trusted certificate authorities checks that
 235    server certificate is signed by a trusted certificate authority
 236    ~/.postgresql/root.crl certificates revoked by certificate authorities
 237    server certificate must not be on this list
 238
 239 32.19.5. SSL Library Initialization #
 240
 241    Applications which need to be compatible with older versions of
 242    PostgreSQL, using OpenSSL version 1.0.2 or older, need to initialize
 243    the SSL library before using it. Applications which initialize libssl
 244    and/or libcrypto libraries should call PQinitOpenSSL to tell libpq that
 245    the libssl and/or libcrypto libraries have been initialized by your
 246    application, so that libpq will not also initialize those libraries.
 247    However, this is unnecessary when using OpenSSL version 1.1.0 or later,
 248    as duplicate initializations are no longer problematic.
 249
 250    Refer to the documentation for the version of PostgreSQL that you are
 251    targeting for details on their use.
 252
 253    PQinitOpenSSL #
 254           Allows applications to select which security libraries to
 255           initialize.
 256
 257 void PQinitOpenSSL(int do_ssl, int do_crypto);
 258
 259           This function is deprecated and only present for backwards
 260           compatibility, it does nothing.
 261
 262    PQinitSSL #
 263           Allows applications to select which security libraries to
 264           initialize.
 265
 266 void PQinitSSL(int do_ssl);
 267
 268           This function is equivalent to PQinitOpenSSL(do_ssl, do_ssl).
 269           This function is deprecated and only present for backwards
 270           compatibility, it does nothing.
 271
 272           PQinitSSL and PQinitOpenSSL are maintained for backwards
 273           compatibility, but are no longer required since PostgreSQL 18.
 274           PQinitSSL has been present since PostgreSQL 8.0, while
 275           PQinitOpenSSL was added in PostgreSQL 8.4, so PQinitSSL might be
 276           preferable for applications that need to work with older
 277           versions of libpq.