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

   1
   2 18.9. Secure TCP/IP Connections with SSL #
   3
   4    18.9.1. Basic Setup
   5    18.9.2. OpenSSL Configuration
   6    18.9.3. Using Client Certificates
   7    18.9.4. SSL Server File Usage
   8    18.9.5. Creating Certificates
   9
  10    PostgreSQL has native support for using SSL connections to encrypt
  11    client/server communications for increased security. This requires that
  12    OpenSSL is installed on both client and server systems and that support
  13    in PostgreSQL is enabled at build time (see Chapter 17).
  14
  15    The terms SSL and TLS are often used interchangeably to mean a secure
  16    encrypted connection using a TLS protocol. SSL protocols are the
  17    precursors to TLS protocols, and the term SSL is still used for
  18    encrypted connections even though SSL protocols are no longer
  19    supported. SSL is used interchangeably with TLS in PostgreSQL.
  20
  21 18.9.1. Basic Setup #
  22
  23    With SSL support compiled in, the PostgreSQL server can be started with
  24    support for encrypted connections using TLS protocols enabled by
  25    setting the parameter ssl to on in postgresql.conf. The server will
  26    listen for both normal and SSL connections on the same TCP port, and
  27    will negotiate with any connecting client on whether to use SSL. By
  28    default, this is at the client's option; see Section 20.1 about how to
  29    set up the server to require use of SSL for some or all connections.
  30
  31    To start in SSL mode, files containing the server certificate and
  32    private key must exist. By default, these files are expected to be
  33    named server.crt and server.key, respectively, in the server's data
  34    directory, but other names and locations can be specified using the
  35    configuration parameters ssl_cert_file and ssl_key_file.
  36
  37    On Unix systems, the permissions on server.key must disallow any access
  38    to world or group; achieve this by the command chmod 0600 server.key.
  39    Alternatively, the file can be owned by root and have group read access
  40    (that is, 0640 permissions). That setup is intended for installations
  41    where certificate and key files are managed by the operating system.
  42    The user under which the PostgreSQL server runs should then be made a
  43    member of the group that has access to those certificate and key files.
  44
  45    If the data directory allows group read access then certificate files
  46    may need to be located outside of the data directory in order to
  47    conform to the security requirements outlined above. Generally, group
  48    access is enabled to allow an unprivileged user to backup the database,
  49    and in that case the backup software will not be able to read the
  50    certificate files and will likely error.
  51
  52    If the private key is protected with a passphrase, the server will
  53    prompt for the passphrase and will not start until it has been entered.
  54    Using a passphrase by default disables the ability to change the
  55    server's SSL configuration without a server restart, but see
  56    ssl_passphrase_command_supports_reload. Furthermore,
  57    passphrase-protected private keys cannot be used at all on Windows.
  58
  59    The first certificate in server.crt must be the server's certificate
  60    because it must match the server's private key. The certificates of
  61    “intermediate” certificate authorities can also be appended to the
  62    file. Doing this avoids the necessity of storing intermediate
  63    certificates on clients, assuming the root and intermediate
  64    certificates were created with v3_ca extensions. (This sets the
  65    certificate's basic constraint of CA to true.) This allows easier
  66    expiration of intermediate certificates.
  67
  68    It is not necessary to add the root certificate to server.crt. Instead,
  69    clients must have the root certificate of the server's certificate
  70    chain.
  71
  72 18.9.2. OpenSSL Configuration #
  73
  74    PostgreSQL reads the system-wide OpenSSL configuration file. By
  75    default, this file is named openssl.cnf and is located in the directory
  76    reported by openssl version -d. This default can be overridden by
  77    setting environment variable OPENSSL_CONF to the name of the desired
  78    configuration file.
  79
  80    OpenSSL supports a wide range of ciphers and authentication algorithms,
  81    of varying strength. While a list of ciphers can be specified in the
  82    OpenSSL configuration file, you can specify ciphers specifically for
  83    use by the database server by modifying ssl_ciphers in postgresql.conf.
  84
  85 Note
  86
  87    It is possible to have authentication without encryption overhead by
  88    using NULL-SHA or NULL-MD5 ciphers. However, a man-in-the-middle could
  89    read and pass communications between client and server. Also,
  90    encryption overhead is minimal compared to the overhead of
  91    authentication. For these reasons NULL ciphers are not recommended.
  92
  93 18.9.3. Using Client Certificates #
  94
  95    To require the client to supply a trusted certificate, place
  96    certificates of the root certificate authorities (CAs) you trust in a
  97    file in the data directory, set the parameter ssl_ca_file in
  98    postgresql.conf to the new file name, and add the authentication option
  99    clientcert=verify-ca or clientcert=verify-full to the appropriate
 100    hostssl line(s) in pg_hba.conf. A certificate will then be requested
 101    from the client during SSL connection startup. (See Section 32.19 for a
 102    description of how to set up certificates on the client.)
 103
 104    For a hostssl entry with clientcert=verify-ca, the server will verify
 105    that the client's certificate is signed by one of the trusted
 106    certificate authorities. If clientcert=verify-full is specified, the
 107    server will not only verify the certificate chain, but it will also
 108    check whether the username or its mapping matches the cn (Common Name)
 109    of the provided certificate. Note that certificate chain validation is
 110    always ensured when the cert authentication method is used (see
 111    Section 20.12).
 112
 113    Intermediate certificates that chain up to existing root certificates
 114    can also appear in the ssl_ca_file file if you wish to avoid storing
 115    them on clients (assuming the root and intermediate certificates were
 116    created with v3_ca extensions). Certificate Revocation List (CRL)
 117    entries are also checked if the parameter ssl_crl_file or ssl_crl_dir
 118    is set.
 119
 120    The clientcert authentication option is available for all
 121    authentication methods, but only in pg_hba.conf lines specified as
 122    hostssl. When clientcert is not specified, the server verifies the
 123    client certificate against its CA file only if a client certificate is
 124    presented and the CA is configured.
 125
 126    There are two approaches to enforce that users provide a certificate
 127    during login.
 128
 129    The first approach makes use of the cert authentication method for
 130    hostssl entries in pg_hba.conf, such that the certificate itself is
 131    used for authentication while also providing ssl connection security.
 132    See Section 20.12 for details. (It is not necessary to specify any
 133    clientcert options explicitly when using the cert authentication
 134    method.) In this case, the cn (Common Name) provided in the certificate
 135    is checked against the user name or an applicable mapping.
 136
 137    The second approach combines any authentication method for hostssl
 138    entries with the verification of client certificates by setting the
 139    clientcert authentication option to verify-ca or verify-full. The
 140    former option only enforces that the certificate is valid, while the
 141    latter also ensures that the cn (Common Name) in the certificate
 142    matches the user name or an applicable mapping.
 143
 144 18.9.4. SSL Server File Usage #
 145
 146    Table 18.2 summarizes the files that are relevant to the SSL setup on
 147    the server. (The shown file names are default names. The locally
 148    configured names could be different.)
 149
 150    Table 18.2. SSL Server File Usage
 151    File Contents Effect
 152    ssl_cert_file ($PGDATA/server.crt) server certificate sent to client to
 153    indicate server's identity
 154    ssl_key_file ($PGDATA/server.key) server private key proves server
 155    certificate was sent by the owner; does not indicate certificate owner
 156    is trustworthy
 157    ssl_ca_file trusted certificate authorities checks that client
 158    certificate is signed by a trusted certificate authority
 159    ssl_crl_file certificates revoked by certificate authorities client
 160    certificate must not be on this list
 161
 162    The server reads these files at server start and whenever the server
 163    configuration is reloaded. On Windows systems, they are also re-read
 164    whenever a new backend process is spawned for a new client connection.
 165
 166    If an error in these files is detected at server start, the server will
 167    refuse to start. But if an error is detected during a configuration
 168    reload, the files are ignored and the old SSL configuration continues
 169    to be used. On Windows systems, if an error in these files is detected
 170    at backend start, that backend will be unable to establish an SSL
 171    connection. In all these cases, the error condition is reported in the
 172    server log.
 173
 174 18.9.5. Creating Certificates #
 175
 176    To create a simple self-signed certificate for the server, valid for
 177    365 days, use the following OpenSSL command, replacing
 178    dbhost.yourdomain.com with the server's host name:
 179 openssl req -new -x509 -days 365 -nodes -text -out server.crt \
 180   -keyout server.key -subj "/CN=dbhost.yourdomain.com"
 181
 182    Then do:
 183 chmod og-rwx server.key
 184
 185    because the server will reject the file if its permissions are more
 186    liberal than this. For more details on how to create your server
 187    private key and certificate, refer to the OpenSSL documentation.
 188
 189    While a self-signed certificate can be used for testing, a certificate
 190    signed by a certificate authority (CA) (usually an enterprise-wide root
 191    CA) should be used in production.
 192
 193    To create a server certificate whose identity can be validated by
 194    clients, first create a certificate signing request (CSR) and a
 195    public/private key file:
 196 openssl req -new -nodes -text -out root.csr \
 197   -keyout root.key -subj "/CN=root.yourdomain.com"
 198 chmod og-rwx root.key
 199
 200    Then, sign the request with the key to create a root certificate
 201    authority (using the default OpenSSL configuration file location on
 202    Linux):
 203 openssl x509 -req -in root.csr -text -days 3650 \
 204   -extfile /etc/ssl/openssl.cnf -extensions v3_ca \
 205   -signkey root.key -out root.crt
 206
 207    Finally, create a server certificate signed by the new root certificate
 208    authority:
 209 openssl req -new -nodes -text -out server.csr \
 210   -keyout server.key -subj "/CN=dbhost.yourdomain.com"
 211 chmod og-rwx server.key
 212
 213 openssl x509 -req -in server.csr -text -days 365 \
 214   -CA root.crt -CAkey root.key -CAcreateserial \
 215   -out server.crt
 216
 217    server.crt and server.key should be stored on the server, and root.crt
 218    should be stored on the client so the client can verify that the
 219    server's leaf certificate was signed by its trusted root certificate.
 220    root.key should be stored offline for use in creating future
 221    certificates.
 222
 223    It is also possible to create a chain of trust that includes
 224    intermediate certificates:
 225 # root
 226 openssl req -new -nodes -text -out root.csr \
 227   -keyout root.key -subj "/CN=root.yourdomain.com"
 228 chmod og-rwx root.key
 229 openssl x509 -req -in root.csr -text -days 3650 \
 230   -extfile /etc/ssl/openssl.cnf -extensions v3_ca \
 231   -signkey root.key -out root.crt
 232
 233 # intermediate
 234 openssl req -new -nodes -text -out intermediate.csr \
 235   -keyout intermediate.key -subj "/CN=intermediate.yourdomain.com"
 236 chmod og-rwx intermediate.key
 237 openssl x509 -req -in intermediate.csr -text -days 1825 \
 238   -extfile /etc/ssl/openssl.cnf -extensions v3_ca \
 239   -CA root.crt -CAkey root.key -CAcreateserial \
 240   -out intermediate.crt
 241
 242 # leaf
 243 openssl req -new -nodes -text -out server.csr \
 244   -keyout server.key -subj "/CN=dbhost.yourdomain.com"
 245 chmod og-rwx server.key
 246 openssl x509 -req -in server.csr -text -days 365 \
 247   -CA intermediate.crt -CAkey intermediate.key -CAcreateserial \
 248   -out server.crt
 249
 250    server.crt and intermediate.crt should be concatenated into a
 251    certificate file bundle and stored on the server. server.key should
 252    also be stored on the server. root.crt should be stored on the client
 253    so the client can verify that the server's leaf certificate was signed
 254    by a chain of certificates linked to its trusted root certificate.
 255    root.key and intermediate.key should be stored offline for use in
 256    creating future certificates.