From 138b95dc657c89de0cea9adf501c3e4569c3ecef Mon Sep 17 00:00:00 2001 From: Daniel Gustafsson Date: Thu, 24 Jun 2021 11:05:00 +0200 Subject: [PATCH v3 2/2] Docs: Replace usage of SSL with SSL/TLS While SSL protocols aren't supported anymore, the term SSL has come to mean "a secure connection". To avoid confusion and make searching for relevant pieces of documentation easier, replace SSL with the widely used term SSL/TLS to refer to secure connections with a TLS protocol. Mentions of TLS are reserved for when the specific protol is discussed. Also add small explanatory sections describing why SSL/TLS is used. Author: Daniel Gustafsson Reviewed-by: Michael Paquier Discussion: https://postgr.es/m/CE12DD5C-4BB3-4166-BC9A-39779568734C@yesql.se --- doc/src/sgml/client-auth.sgml | 42 ++++----- doc/src/sgml/config.sgml | 48 +++++----- doc/src/sgml/install-windows.sgml | 2 +- doc/src/sgml/installation.sgml | 2 +- doc/src/sgml/libpq.sgml | 147 +++++++++++++++-------------- doc/src/sgml/monitoring.sgml | 20 ++-- doc/src/sgml/pgcrypto.sgml | 2 +- doc/src/sgml/protocol.sgml | 36 +++---- doc/src/sgml/ref/pg_rewind.sgml | 2 +- doc/src/sgml/ref/postgres-ref.sgml | 6 +- doc/src/sgml/runtime.sgml | 60 +++++++----- doc/src/sgml/sslinfo.sgml | 12 +-- 12 files changed, 199 insertions(+), 180 deletions(-) diff --git a/doc/src/sgml/client-auth.sgml b/doc/src/sgml/client-auth.sgml index 02f0489112..f38757c58b 100644 --- a/doc/src/sgml/client-auth.sgml +++ b/doc/src/sgml/client-auth.sgml @@ -135,7 +135,7 @@ hostnogssenc database user This record matches connection attempts made using TCP/IP. host records match - SSL or non-SSL connection + SSL/TLS or non-SSL/TLS connection attempts as well as GSSAPI encrypted or non-GSSAPI encrypted connection attempts. @@ -156,14 +156,14 @@ hostnogssenc database user This record matches connection attempts made using TCP/IP, - but only when the connection is made with SSL + but only when the connection is made with SSL/TLS encryption. To make use of this option the server must be built with - SSL support. Furthermore, - SSL must be enabled + SSL/TLS support. Furthermore, + SSL/TLS must be enabled by setting the configuration parameter (see for more information). Otherwise, the hostssl record is ignored except for @@ -178,7 +178,7 @@ hostnogssenc database user This record type has the opposite behavior of hostssl; it only matches connection attempts made over - TCP/IP that do not use SSL. + TCP/IP that do not use SSL/TLS. @@ -555,7 +555,7 @@ hostnogssenc database usercert - Authenticate using SSL client certificates. See + Authenticate using SSL/TLS client certificates. See for details. @@ -603,7 +603,7 @@ hostnogssenc database userhostssl record. This option can be set to verify-ca or verify-full. Both options require the client - to present a valid (trusted) SSL certificate, while + to present a valid (trusted) SSL/TLS certificate, while verify-full additionally enforces that the cn (Common Name) in the certificate matches the username or an applicable mapping. @@ -993,8 +993,8 @@ omicron bryanh guest1 Certificate authentication, which - requires an SSL connection and authenticates users by checking the - SSL certificate they send. + requires an SSL/TLS connection and authenticates users by checking the + SSL/TLS certificate they send. @@ -1019,7 +1019,7 @@ omicron bryanh guest1 Password authentication is the easiest choice for remote connections. All the other options require some kind of external security infrastructure (usually an authentication server or a certificate - authority for issuing SSL certificates), or are platform-specific. + authority for issuing SSL/TLS certificates), or are platform-specific. @@ -1150,10 +1150,10 @@ omicron bryanh guest1 The method password sends the password in clear-text and is therefore vulnerable to password sniffing attacks. It should - always be avoided if possible. If the connection is protected by SSL + always be avoided if possible. If the connection is protected by SSL/TLS encryption then password can be used safely, though. - (Though SSL certificate authentication might be a better choice if one - is depending on using SSL). + (Though SSL/TLS certificate authentication might be a better choice if one + is depending on using SSL/TLS). @@ -1223,7 +1223,7 @@ omicron bryanh guest1 GSSAPI provides automatic authentication (single sign-on) for systems that support it. The authentication itself is secure. If GSSAPI encryption - or SSL encryption is + or SSL/TLS encryption is used, the data sent along the database connection will be encrypted; otherwise, it will not. @@ -1686,7 +1686,7 @@ omicron bryanh guest1 Set to ldaps to use LDAPS. This is a non-standard - way of using LDAP over SSL, supported by some LDAP server + way of using LDAP over SSL/TLS, supported by some LDAP server implementations. See also the ldaptls option for an alternative. @@ -1697,7 +1697,7 @@ omicron bryanh guest1 Set to 1 to make the connection between PostgreSQL and the LDAP server - use TLS encryption. This uses the StartTLS + use TLS encryption. This uses the StartTLS operation per RFC 4513. See also the ldapscheme option for an alternative. @@ -1711,7 +1711,7 @@ omicron bryanh guest1 ldaptls only encrypts the traffic between the PostgreSQL server and the LDAP server. The connection between the PostgreSQL server and the PostgreSQL client will still be unencrypted - unless SSL is used there as well. + unless SSL/TLS is used there as well. @@ -1812,7 +1812,7 @@ ldap[s]://host[:port]/ The URL scheme ldaps chooses the LDAPS method for - making LDAP connections over SSL, equivalent to using + making LDAP connections over SSL/TLS, equivalent to using ldapscheme=ldaps. To use encrypted LDAP connections using the StartTLS operation, use the normal URL scheme ldap and specify the @@ -2045,8 +2045,8 @@ host ... radius radiusservers="server1,server2" radiussecrets="""secret one"","" - This authentication method uses SSL client certificates to perform - authentication. It is therefore only available for SSL connections. + This authentication method uses SSL/TLS client certificates to perform + authentication. It is therefore only available for SSL/TLS connections. When using this authentication method, the server will require that the client provide a valid, trusted certificate. No password prompt will be sent to the client. The cn (Common Name) @@ -2057,7 +2057,7 @@ host ... radius radiusservers="server1,server2" radiussecrets="""secret one"","" - The following configuration options are supported for SSL certificate + The following configuration options are supported for SSL/TLS certificate authentication: diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml index eeba2caa43..e77c23f8eb 100644 --- a/doc/src/sgml/config.sgml +++ b/doc/src/sgml/config.sgml @@ -1181,10 +1181,16 @@ include_dir 'conf.d' - SSL + SSL/TLS - See for more information about setting up SSL. + See for more information about setting up + SSL/TLS. The configuration + parameters for controlling SSL/TLS + are named ssl for historic reasons, even though + support for the SSL protocol has been deprecated. + SSL is in this context used interchangeably with + TLS. @@ -1196,7 +1202,7 @@ include_dir 'conf.d' - Enables SSL connections. + Enables SSL/TLS connections. This parameter can only be set in the postgresql.conf file or on the server command line. The default is off. @@ -1212,7 +1218,7 @@ include_dir 'conf.d' - Specifies the name of the file containing the SSL server certificate + Specifies the name of the file containing the SSL/TLS server certificate authority (CA). Relative paths are relative to the data directory. This parameter can only be set in the postgresql.conf @@ -1231,7 +1237,7 @@ include_dir 'conf.d' - Specifies the name of the file containing the SSL server certificate. + Specifies the name of the file containing the SSL/TLS server certificate. Relative paths are relative to the data directory. This parameter can only be set in the postgresql.conf file or on the server command line. @@ -1248,7 +1254,7 @@ include_dir 'conf.d' - Specifies the name of the file containing the SSL server certificate + Specifies the name of the file containing the SSL/TLS server certificate revocation list (CRL). Relative paths are relative to the data directory. This parameter can only be set in the postgresql.conf @@ -1267,7 +1273,7 @@ include_dir 'conf.d' - Specifies the name of the directory containing the SSL server + Specifies the name of the directory containing the SSL/TLS server certificate revocation list (CRL). Relative paths are relative to the data directory. This parameter can only be set in the postgresql.conf file or on the server command @@ -1301,7 +1307,7 @@ include_dir 'conf.d' - Specifies the name of the file containing the SSL server private key. + Specifies the name of the file containing the SSL/TLS server private key. Relative paths are relative to the data directory. This parameter can only be set in the postgresql.conf file or on the server command line. @@ -1318,13 +1324,13 @@ include_dir 'conf.d' - Specifies a list of SSL cipher suites that are - allowed to be used by SSL connections. See the + Specifies a list of SSL/TLS cipher suites that are + allowed to be used by SSL/TLS connections. See the ciphers manual page in the OpenSSL package for the syntax of this setting and a list of supported values. Only - connections using TLS version 1.2 and lower are affected. There is - currently no setting that controls the cipher choices used by TLS + connections using TLS version 1.2 and lower are affected. There is + currently no setting that controls the cipher choices used by TLS version 1.3 connections. The default value is HIGH:MEDIUM:+3DES:!aNULL. The default is usually a reasonable choice unless you have specific security requirements. @@ -1405,7 +1411,7 @@ include_dir 'conf.d' - Specifies whether to use the server's SSL cipher preferences, rather + Specifies whether to use the server's SSL/TLS cipher preferences, rather than the client's. This parameter can only be set in the postgresql.conf file or on the server command line. @@ -1460,12 +1466,12 @@ include_dir 'conf.d' - Sets the minimum SSL/TLS protocol version to use. Valid values are + Sets the minimum TLS protocol version to use. Valid values are currently: TLSv1, TLSv1.1, TLSv1.2, TLSv1.3. Older versions of the OpenSSL library do not support all values; an error will be raised if an unsupported setting - is chosen. Protocol versions before TLS 1.0, namely SSL version 2 and + is chosen. Protocol versions before TLS version 1.0, namely SSL version 2 and 3, are always disabled. @@ -1489,7 +1495,7 @@ include_dir 'conf.d' - Sets the maximum SSL/TLS protocol version to use. Valid values are as + Sets the maximum TLS protocol version to use. Valid values are as for , with addition of an empty string, which allows any protocol version. The default is to allow any version. Setting the maximum protocol version is mainly @@ -1513,7 +1519,7 @@ include_dir 'conf.d' Specifies the name of the file containing Diffie-Hellman parameters - used for so-called ephemeral DH family of SSL ciphers. The default is + used for so-called ephemeral DH family of SSL/TLS ciphers. The default is empty, in which case compiled-in default DH parameters used. Using custom DH parameters reduces the exposure if an attacker manages to crack the well-known compiled-in DH parameters. You can create your own @@ -1537,7 +1543,7 @@ include_dir 'conf.d' Sets an external command to be invoked when a passphrase for - decrypting an SSL file such as a private key needs to be obtained. By + decrypting an SSL/TLS file such as a private key needs to be obtained. By default, this parameter is empty, which means the built-in prompting mechanism is used. @@ -1575,7 +1581,7 @@ include_dir 'conf.d' configuration reload if a key file needs a passphrase. If this parameter is off (the default), then ssl_passphrase_command will be ignored during a - reload and the SSL configuration will not be reloaded if a passphrase + reload and the SSL/TLS configuration will not be reloaded if a passphrase is needed. That setting is appropriate for a command that requires a TTY for prompting, which might not be available when the server is running. Setting this parameter to on might be appropriate if the @@ -10228,9 +10234,9 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - Reports the name of the SSL library that this + Reports the name of the SSL/TLS library that this PostgreSQL server was built with (even if - SSL is not currently configured or in use on this instance), for + SSL/TLS is not currently configured or in use on this instance), for example OpenSSL, or an empty string if none. diff --git a/doc/src/sgml/install-windows.sgml b/doc/src/sgml/install-windows.sgml index 312edc6f7a..65e55f4b9d 100644 --- a/doc/src/sgml/install-windows.sgml +++ b/doc/src/sgml/install-windows.sgml @@ -308,7 +308,7 @@ $ENV{MSBFLAGS}="/m"; OpenSSL - Required for SSL support. Binaries can be downloaded from + Required for SSL/TLS support. Binaries can be downloaded from or source from . diff --git a/doc/src/sgml/installation.sgml b/doc/src/sgml/installation.sgml index 3c0aa118c7..868c401c51 100644 --- a/doc/src/sgml/installation.sgml +++ b/doc/src/sgml/installation.sgml @@ -994,7 +994,7 @@ build-postgresql: - Build with support for SSL (encrypted) + Build with support for SSL/TLS (encrypted) connections. The only LIBRARY supported is . This requires the OpenSSL package to be installed. diff --git a/doc/src/sgml/libpq.sgml b/doc/src/sgml/libpq.sgml index 6882c0ebce..fa0669ad95 100644 --- a/doc/src/sgml/libpq.sgml +++ b/doc/src/sgml/libpq.sgml @@ -423,7 +423,7 @@ PostgresPollingStatusType PQconnectPoll(PGconn *conn); CONNECTION_SSL_STARTUP - Negotiating SSL encryption. + Negotiating SSL/TLS encryption. @@ -1103,7 +1103,7 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname application to avoid a host name look-up, which might be important in applications with time constraints. However, a host name is required for GSSAPI or SSPI authentication - methods, as well as for verify-full SSL + methods, as well as for verify-full SSL/TLS certificate verification. The following rules are used: @@ -1231,12 +1231,12 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname choose channel binding if available, and disable prevents the use of channel binding. The default is prefer if - PostgreSQL is compiled with SSL support; + PostgreSQL is compiled with SSL/TLS support; otherwise the default is disable. Channel binding is a method for the server to authenticate itself to - the client. It is only supported over SSL connections + the client. It is only supported over SSL/TLS connections with PostgreSQL 11 or later servers using the SCRAM authentication method. @@ -1517,7 +1517,7 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname This option determines whether or with what priority a secure - SSL TCP/IP connection will be negotiated with the + SSL/TLS TCP/IP connection will be negotiated with the server. There are six modes: @@ -1525,7 +1525,7 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname disable - only try a non-SSL connection + only try a non-SSL/TLS connection @@ -1534,8 +1534,8 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname allow - first try a non-SSL connection; if that - fails, try an SSL connection + first try a non-SSL/TLS connection; if that + fails, try an SSL/TLS connection @@ -1544,8 +1544,8 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname prefer (default) - first try an SSL connection; if that fails, - try a non-SSL connection + first try an SSL/TLS connection; if that fails, + try a non-SSL/TLS connection @@ -1554,7 +1554,7 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname require - only try an SSL connection. If a root CA + only try an SSL/TLS connection. If a root CA file is present, verify the certificate in the same way as if verify-ca was specified @@ -1565,7 +1565,7 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname verify-ca - only try an SSL connection, and verify that + only try an SSL/TLS connection, and verify that the server certificate is issued by a trusted certificate authority (CA) @@ -1576,7 +1576,7 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname verify-full - only try an SSL connection, verify that the + only try an SSL/TLS connection, verify that the server certificate is issued by a trusted CA and that the requested server host name matches that in the certificate @@ -1592,21 +1592,21 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname sslmode is ignored for Unix domain socket communication. - If PostgreSQL is compiled without SSL support, + If PostgreSQL is compiled without SSL/TLS support, using options require, verify-ca, or verify-full will cause an error, while options allow and prefer will be accepted but libpq will not actually attempt - an SSL + an SSL/TLS connection.SSLwith libpq Note that if GSSAPI encryption is possible, - that will be used in preference to SSL + that will be used in preference to SSL/TLS encryption, regardless of the value of sslmode. - To force use of SSL encryption in an + To force use of SSL/TLS encryption in an environment that has working GSSAPI infrastructure (such as a Kerberos server), also set gssencmode to disable. @@ -1623,15 +1623,15 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - If set to 1, an SSL connection to the server + If set to 1, an SSL/TLS connection to the server is required (this is equivalent to sslmode require). libpq will then refuse to connect if the server does not accept an - SSL connection. If set to 0 (default), + SSL/TLS connection. If set to 0 (default), libpq will negotiate the connection type with the server (equivalent to sslmode prefer). This option is only available if - PostgreSQL is compiled with SSL support. + PostgreSQL is compiled with SSL/TLS support. @@ -1640,13 +1640,13 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname sslcompression - If set to 1, data sent over SSL connections will be compressed. If + If set to 1, data sent over SSL/TLS connections will be compressed. If set to 0, compression will be disabled. The default is 0. This - parameter is ignored if a connection without SSL is made. + parameter is ignored if a connection without SSL/TLS is made. - SSL compression is nowadays considered insecure and its use is no + SSL/TLS compression is nowadays considered insecure and its use is no longer recommended. OpenSSL 1.1.0 disables compression by default, and many operating system distributions disable it in prior versions as well, so setting this parameter to on @@ -1668,10 +1668,10 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname sslcert - This parameter specifies the file name of the client SSL + This parameter specifies the file name of the client SSL/TLS certificate, replacing the default ~/.postgresql/postgresql.crt. - This parameter is ignored if an SSL connection is not made. + This parameter is ignored if an SSL/TLS connection is not made. @@ -1688,7 +1688,7 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname OpenSSL loadable modules). An external engine specification should consist of a colon-separated engine name and an engine-specific key identifier. This parameter is ignored if an - SSL connection is not made. + SSL/TLS connection is not made. @@ -1729,7 +1729,7 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname sslrootcert - This parameter specifies the name of a file containing SSL + This parameter specifies the name of a file containing SSL/TLS certificate authority (CA) certificate(s). If the file exists, the server's certificate will be verified to be signed by one of these authorities. The default is @@ -1742,8 +1742,8 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname sslcrl - This parameter specifies the file name of the SSL certificate - revocation list (CRL). Certificates listed in this file, if it + This parameter specifies the file name of the SSL/TLS certificate + revocation list (CRL). Certificates listed in this file, if it exists, will be rejected while attempting to authenticate the server's certificate. If neither nor @@ -1758,8 +1758,8 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname sslcrldir - This parameter specifies the directory name of the SSL certificate - revocation list (CRL). Certificates listed in the files in this + This parameter specifies the directory name of the SSL/TLS certificate + revocation list (CRL). Certificates listed in the files in this directory, if it exists, will be rejected while attempting to authenticate the server's certificate. @@ -1782,17 +1782,17 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname sslsniServer Name Indication - By default, libpq sets the TLS extension Server Name - Indication (SNI) on SSL-enabled connections. + By default, libpq sets the TLS extension Server Name + Indication (SNI) on SSL/TLS-enabled connections. By setting this parameter to 0, this is turned off. - The Server Name Indication can be used by SSL-aware proxies to route - connections without having to decrypt the SSL stream. (Note that this + The Server Name Indication can be used by SSL/TLS-aware proxies to route + connections without having to decrypt the TLS stream. (Note that this requires a proxy that is aware of the PostgreSQL protocol handshake, - not just any SSL proxy.) However, SNI makes the destination host name + not just any SSL/TLS proxy.) However, SNI makes the destination host name appear in cleartext in the network traffic, so it might be undesirable in some cases. @@ -1810,7 +1810,7 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname connection that the server process is running under the specified user name; if it is not, the connection is aborted with an error. This parameter can be used to provide server authentication similar - to that available with SSL certificates on TCP/IP connections. + to that available with SSL/TLS certificates on TCP/IP connections. (Note that if the Unix-domain socket is in /tmp or another publicly writable location, any user could start a server listening there. Use this parameter @@ -1826,7 +1826,7 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname ssl_min_protocol_version - This parameter specifies the minimum SSL/TLS protocol version to allow + This parameter specifies the minimum TLS protocol version to allow for the connection. Valid values are TLSv1, TLSv1.1, TLSv1.2 and TLSv1.3. The supported protocols depend on the @@ -1842,7 +1842,7 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname ssl_max_protocol_version - This parameter specifies the maximum SSL/TLS protocol version to allow + This parameter specifies the maximum TLS protocol version to allow for the connection. Valid values are TLSv1, TLSv1.1, TLSv1.2 and TLSv1.3. The supported protocols depend on the @@ -2494,7 +2494,7 @@ int PQconnectionUsedPassword(const PGconn *conn); - The following functions return information related to SSL. This information + The following functions return information related to SSL/TLS. This information usually doesn't change after a connection is established. @@ -2502,7 +2502,7 @@ int PQconnectionUsedPassword(const PGconn *conn); PQsslInUsePQsslInUse - Returns true (1) if the connection uses SSL, false (0) if not. + Returns true (1) if the connection uses SSL/TLS, false (0) if not. int PQsslInUse(const PGconn *conn); @@ -2516,7 +2516,7 @@ int PQsslInUse(const PGconn *conn); PQsslAttributePQsslAttribute - Returns SSL-related information about the connection. + Returns SSL/TLS-related information about the connection. const char *PQsslAttribute(const PGconn *conn, const char *attribute_name); @@ -2524,7 +2524,7 @@ const char *PQsslAttribute(const PGconn *conn, const char *attribute_name); - The list of available attributes varies depending on the SSL library + The list of available attributes varies depending on the SSL/TLS library being used, and the type of connection. If an attribute is not available, returns NULL. @@ -2536,7 +2536,7 @@ const char *PQsslAttribute(const PGconn *conn, const char *attribute_name); library - Name of the SSL implementation in use. (Currently, only + Name of the SSL/TLS implementation in use. (Currently, only "OpenSSL" is implemented) @@ -2545,9 +2545,9 @@ const char *PQsslAttribute(const PGconn *conn, const char *attribute_name); protocol - SSL/TLS version in use. Common values - are "TLSv1", "TLSv1.1" - and "TLSv1.2", but an implementation may + TLS protocol version in use. Common values + are "TLSv1.2", "TLSv1.1" + and "TLSv1.3", but an implementation may return other strings if some other protocol is used. @@ -2566,7 +2566,7 @@ const char *PQsslAttribute(const PGconn *conn, const char *attribute_name); A short name of the ciphersuite used, e.g., "DHE-RSA-DES-CBC3-SHA". The names are specific - to each SSL implementation. + to each SSL/TLS implementation. @@ -2574,7 +2574,7 @@ const char *PQsslAttribute(const PGconn *conn, const char *attribute_name); compression - If SSL compression is in use, returns the name of the compression + If SSL/TLS compression is in use, returns the name of the compression algorithm, or "on" if compression is used but the algorithm is not known. If compression is not in use, returns "off". @@ -2589,7 +2589,7 @@ const char *PQsslAttribute(const PGconn *conn, const char *attribute_name); PQsslAttributeNamesPQsslAttributeNames - Return an array of SSL attribute names available. The array is terminated by a NULL pointer. + Return an array of SSL/TLS attribute names available. The array is terminated by a NULL pointer. const char * const * PQsslAttributeNames(const PGconn *conn); @@ -2601,14 +2601,14 @@ const char * const * PQsslAttributeNames(const PGconn *conn); PQsslStructPQsslStruct - Return a pointer to an SSL-implementation-specific object describing + Return a pointer to an SSL/TLS-implementation-specific object describing the connection. void *PQsslStruct(const PGconn *conn, const char *struct_name); - The struct(s) available depend on the SSL implementation in use. + The struct(s) available depend on the SSL/TLS implementation in use. For OpenSSL, there is one struct, available under the name "OpenSSL", and it returns a pointer to the OpenSSL SSL struct. @@ -2644,8 +2644,8 @@ void *PQsslStruct(const PGconn *conn, const char *struct_name); SSLin libpq - Returns the SSL structure used in the connection, or null - if SSL is not in use. + Returns the SSL structure used in the connection, or null + if SSL/TLS is not in use. void *PQgetssl(const PGconn *conn); @@ -2656,8 +2656,8 @@ void *PQgetssl(const PGconn *conn); This function is equivalent to PQsslStruct(conn, "OpenSSL"). It should not be used in new applications, because the returned struct is specific to OpenSSL and will not be - available if another SSL implementation is used. - To check if a connection uses SSL, call + available if another SSL/TLS implementation is used. + To check if a connection uses SSL/TLS, call instead, and for more details about the connection, use . @@ -8239,17 +8239,18 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*) - SSL Support + SSL/TLS Support SSL + TLS - PostgreSQL has native support for using SSL + PostgreSQL has native support for using SSL/TLS connections to encrypt client/server communications for increased security. See for details about the server-side - SSL functionality. + SSL/TLS functionality. @@ -8298,7 +8299,7 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*) If sslmode is set to verify-full, libpq will also verify that the server host name matches the name stored in the server certificate. The - SSL connection will fail if the server certificate cannot be + SSL/TLS connection will fail if the server certificate cannot be verified. verify-full is recommended in most security-sensitive environments. @@ -8414,7 +8415,7 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*) The different values for the sslmode parameter provide different - levels of protection. SSL can provide + levels of protection. SSL/TLS can provide protection against three types of attacks: @@ -8423,7 +8424,7 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*) If a third party can examine the network traffic between the client and the server, it can read both connection information (including - the user name and password) and the data that is passed. SSL + the user name and password) and the data that is passed. SSL/TLS uses encryption to prevent this. @@ -8439,7 +8440,7 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*) making it impossible to detect this attack. Common vectors to do this include DNS poisoning and address hijacking, whereby the client is directed to a different server than intended. There are also several other - attack methods that can accomplish this. SSL uses certificate + attack methods that can accomplish this. SSL/TLS uses certificate verification to prevent this, by authenticating the server to the client. @@ -8450,7 +8451,7 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*) If a third party can pretend to be an authorized client, it can simply access data it should not have access to. Typically this can - happen through insecure password management. SSL uses + happen through insecure password management. SSL/TLS uses client certificates to prevent this, by making sure that only holders of valid certificates can access the server. @@ -8460,7 +8461,7 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*) - For a connection to be known SSL-secured, SSL usage must be configured + For a connection to be known SSL/TLS-secured, SSL/TLS usage must be configured on both the client and the server before the connection is made. If it is only configured on the server, the client may end up sending sensitive information (e.g., passwords) before @@ -8480,7 +8481,7 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*) - All SSL options carry overhead in the form of encryption and + All SSL/TLS options carry overhead in the form of encryption and key-exchange, so there is a trade-off that has to be made between performance and security. illustrates the risks the different sslmode values @@ -8488,7 +8489,7 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*) - SSL Mode Descriptions + SSL/TLS Mode Descriptions @@ -8583,15 +8584,15 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*) - SSL Client File Usage + SSL/TLS Client File Usage summarizes the files that are - relevant to the SSL setup on the client. + relevant to the SSL/TLS setup on the client.
- Libpq/Client SSL File Usage + Libpq/Client SSL/TLS File Usage @@ -8635,12 +8636,12 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*) - SSL Library Initialization + SSL/TLS Library Initialization If your application initializes libssl and/or libcrypto libraries and libpq - is built with SSL support, you should call + is built with SSL/TLS support, you should call to tell libpq that the libssl and/or libcrypto libraries have been initialized by your application, so that @@ -8666,7 +8667,7 @@ void PQinitOpenSSL(int do_ssl, int do_crypto); opening a database connection. When do_crypto is non-zero, the libcrypto library will be initialized. By default (if is not called), both libraries - are initialized. When SSL support is not compiled in, this function is + are initialized. When SSL/TLS support is not compiled in, this function is present but does nothing. diff --git a/doc/src/sgml/monitoring.sgml b/doc/src/sgml/monitoring.sgml index dcbb10fb6f..270cad2758 100644 --- a/doc/src/sgml/monitoring.sgml +++ b/doc/src/sgml/monitoring.sgml @@ -349,7 +349,7 @@ postgres 27093 0.0 0.0 30096 2752 ? Ss 11:34 0:00 postgres: ser pg_stat_sslpg_stat_ssl One row per connection (regular and replication), showing information about - SSL used on this connection. + SSL/TLS used on this connection. See pg_stat_ssl for details. @@ -1185,7 +1185,7 @@ postgres 27093 0.0 0.0 30096 2752 ? Ss 11:34 0:00 postgres: ser SSLOpenServer - Waiting for SSL while attempting connection. + Waiting for SSL/TLS while attempting connection. WalSenderWaitForWAL @@ -3054,7 +3054,7 @@ SELECT pid, wait_event_type, wait_event FROM pg_stat_activity WHERE wait_event i The pg_stat_ssl view will contain one row per - backend or WAL sender process, showing statistics about SSL usage on + backend or WAL sender process, showing statistics about SSL/TLS usage on this connection. It can be joined to pg_stat_activity or pg_stat_replication on the pid column to get more details about the @@ -3090,7 +3090,7 @@ SELECT pid, wait_event_type, wait_event FROM pg_stat_activity WHERE wait_event i ssl boolean - True if SSL is used on this connection + True if SSL/TLS is used on this connection @@ -3099,7 +3099,7 @@ SELECT pid, wait_event_type, wait_event FROM pg_stat_activity WHERE wait_event i version text - Version of SSL in use, or NULL if SSL is not in use + TLS protocol version in use, or NULL if SSL/TLS is not in use on this connection @@ -3109,7 +3109,7 @@ SELECT pid, wait_event_type, wait_event FROM pg_stat_activity WHERE wait_event i ciphertext - Name of SSL cipher in use, or NULL if SSL is not in use + Name of SSL/TLS cipher in use, or NULL if SSL/TLS is not in use on this connection @@ -3120,7 +3120,7 @@ SELECT pid, wait_event_type, wait_event FROM pg_stat_activity WHERE wait_event i Number of bits in the encryption algorithm used, or NULL - if SSL is not used on this connection + if SSL/TLS is not used on this connection @@ -3130,7 +3130,7 @@ SELECT pid, wait_event_type, wait_event FROM pg_stat_activity WHERE wait_event i Distinguished Name (DN) field from the client certificate - used, or NULL if no client certificate was supplied or if SSL + used, or NULL if no client certificate was supplied or if SSL/TLS is not in use on this connection. This field is truncated if the DN field is longer than NAMEDATALEN (64 characters in a standard build). @@ -3143,7 +3143,7 @@ SELECT pid, wait_event_type, wait_event FROM pg_stat_activity WHERE wait_event i Serial number of the client certificate, or NULL if no client - certificate was supplied or if SSL is not in use on this connection. The + certificate was supplied or if SSL/TLS is not in use on this connection. The combination of certificate serial number and certificate issuer uniquely identifies a certificate (unless the issuer erroneously reuses serial numbers). @@ -3156,7 +3156,7 @@ SELECT pid, wait_event_type, wait_event FROM pg_stat_activity WHERE wait_event i DN of the issuer of the client certificate, or NULL if no client - certificate was supplied or if SSL is not in use on this connection. + certificate was supplied or if SSL/TLS is not in use on this connection. This field is truncated like client_dn. diff --git a/doc/src/sgml/pgcrypto.sgml b/doc/src/sgml/pgcrypto.sgml index c4dce94001..45fa4564b8 100644 --- a/doc/src/sgml/pgcrypto.sgml +++ b/doc/src/sgml/pgcrypto.sgml @@ -1271,7 +1271,7 @@ gen_random_uuid() returns uuid - Connect locally or use SSL connections. + Connect locally or use SSL/TLS connections. Trust both system and database administrator. diff --git a/doc/src/sgml/protocol.sgml b/doc/src/sgml/protocol.sgml index 01e87617f4..fe0ca55b14 100644 --- a/doc/src/sgml/protocol.sgml +++ b/doc/src/sgml/protocol.sgml @@ -1432,49 +1432,49 @@ SELCT 1/0; - <acronym>SSL</acronym> Session Encryption + <acronym>SSL/TLS</acronym> Session Encryption If PostgreSQL was built with - SSL support, frontend/backend communications - can be encrypted using SSL. This provides + SSL/TLS support, frontend/backend communications + can be encrypted using SSL/TLS. This provides communication security in environments where attackers might be able to capture the session traffic. For more information on encrypting PostgreSQL sessions with - SSL, see . + SSL/TLS, see . - To initiate an SSL-encrypted connection, the + To initiate an SSL/TLS-encrypted connection, the frontend initially sends an SSLRequest message rather than a StartupMessage. The server then responds with a single byte containing S or N, indicating that it is - willing or unwilling to perform SSL, + willing or unwilling to perform SSL/TLS, respectively. The frontend might close the connection at this point if it is dissatisfied with the response. To continue after - S, perform an SSL startup handshake - (not described here, part of the SSL + S, perform an SSL/TLS startup handshake + (not described here, part of the SSL/TLS specification) with the server. If this is successful, continue with sending the usual StartupMessage. In this case the StartupMessage and all subsequent data will be - SSL-encrypted. To continue after + SSL/TLS-encrypted. To continue after N, send the usual StartupMessage and proceed without encryption. (Alternatively, it is permissible to issue a GSSENCRequest message after an N response to try to use GSSAPI encryption instead - of SSL.) + of SSL/TLS.) The frontend should also be prepared to handle an ErrorMessage response to SSLRequest from the server. This would only occur if - the server predates the addition of SSL support + the server predates the addition of SSL/TLS support to PostgreSQL. (Such servers are now very ancient, and likely do not exist in the wild anymore.) In this case the connection must be closed, but the frontend might choose to open a fresh connection - and proceed without requesting SSL. + and proceed without requesting SSL/TLS. @@ -1484,7 +1484,7 @@ SELCT 1/0; While the protocol itself does not provide a way for the server to - force SSL encryption, the administrator can + force SSL/TLS encryption, the administrator can configure the server to reject unencrypted sessions as a byproduct of authentication checking. @@ -1525,7 +1525,7 @@ SELCT 1/0; encryption. (Alternatively, it is permissible to issue an SSLRequest message after an N response to try to - use SSL encryption instead + use SSL/TLS encryption instead of GSSAPI.) @@ -1664,7 +1664,7 @@ the password is in. Channel binding is supported in PostgreSQL builds with -SSL support. The SASL mechanism name for SCRAM with channel binding is +SSL/TLS support. The SASL mechanism name for SCRAM with channel binding is SCRAM-SHA-256-PLUS. The channel binding type used by PostgreSQL is tls-server-end-point. @@ -1685,7 +1685,7 @@ PostgreSQL is tls-server-end-point. certificate into the transmitted password hash. While a fake server can retransmit the real server's certificate, it doesn't have access to the private key matching that certificate, and therefore cannot prove it is - the owner, causing SSL connection failure. + the owner, causing SSL/TLS connection failure. @@ -1695,7 +1695,7 @@ PostgreSQL is tls-server-end-point. The server sends an AuthenticationSASL message. It includes a list of SASL authentication mechanisms that the server can accept. This will be SCRAM-SHA-256-PLUS - and SCRAM-SHA-256 if the server is built with SSL + and SCRAM-SHA-256 if the server is built with SSL/TLS support, or else just the latter. @@ -5875,7 +5875,7 @@ SSLRequest (F) - The SSL request code. The value is chosen to contain + The SSL/TLS request code. The value is chosen to contain 1234 in the most significant 16 bits, and 5679 in the least significant 16 bits. (To avoid confusion, this code must not be the same as any protocol version number.) diff --git a/doc/src/sgml/ref/pg_rewind.sgml b/doc/src/sgml/ref/pg_rewind.sgml index 33e6bb64ad..bfe42048c8 100644 --- a/doc/src/sgml/ref/pg_rewind.sgml +++ b/doc/src/sgml/ref/pg_rewind.sgml @@ -122,7 +122,7 @@ PostgreSQL documentation pg_rewind will fail immediately if it finds files it cannot write directly to. This can happen for example when the source and the target server use the same file mapping for read-only - SSL keys and certificates. If such files are present on the target server + SSL/TLS keys and certificates. If such files are present on the target server it is recommended to remove them before running pg_rewind. After doing the rewind, some of those files may have been copied from the source, in which case it may diff --git a/doc/src/sgml/ref/postgres-ref.sgml b/doc/src/sgml/ref/postgres-ref.sgml index 4aaa7abe1a..39250f567e 100644 --- a/doc/src/sgml/ref/postgres-ref.sgml +++ b/doc/src/sgml/ref/postgres-ref.sgml @@ -258,10 +258,10 @@ PostgreSQL documentation - Enables secure connections using SSL. + Enables secure connections using SSL/TLS. PostgreSQL must have been compiled with - support for SSL for this option to be - available. For more information on using SSL, + support for SSL/TLS for this option to be + available. For more information on using SSL/TLS, refer to . diff --git a/doc/src/sgml/runtime.sgml b/doc/src/sgml/runtime.sgml index f1cbc1d9e9..613946038a 100644 --- a/doc/src/sgml/runtime.sgml +++ b/doc/src/sgml/runtime.sgml @@ -2004,14 +2004,14 @@ pg_dumpall -p 5432 | psql -d postgres -p 5433 To prevent spoofing on TCP connections, either use - SSL certificates and make sure that clients check the server's certificate, + SSL/TLS certificates and make sure that clients check the server's certificate, or use GSSAPI encryption (or both, if they're on separate connections). - To prevent spoofing with SSL, the server + To prevent spoofing with SSL/TLS, the server must be configured to accept only hostssl connections () and have SSL key and certificate files + linkend="auth-pg-hba-conf"/>) and have SSL/TLS key and certificate files (). The TCP client must connect using sslmode=verify-ca or verify-full and have the appropriate root certificate @@ -2115,13 +2115,13 @@ pg_dumpall -p 5432 | psql -d postgres -p 5433 - SSL connections encrypt all data sent across the network: the + SSL/TLS connections encrypt all data sent across the network: the password, the queries, and the data returned. The pg_hba.conf file allows administrators to specify which hosts can use non-encrypted connections (host) - and which require SSL-encrypted connections + and which require SSL/TLS-encrypted connections (hostssl). Also, clients can specify that they - connect to servers only via SSL. + connect to servers only via SSL/TLS. @@ -2144,11 +2144,11 @@ pg_dumpall -p 5432 | psql -d postgres -p 5433 - SSL Host Authentication + SSL/TLS Host Authentication - It is possible for both the client and server to provide SSL + It is possible for both the client and server to provide SSL/TLS certificates to each other. It takes some extra configuration on each side, but this provides stronger verification of identity than the mere use of passwords. It prevents a computer from @@ -2181,39 +2181,51 @@ pg_dumpall -p 5432 | psql -d postgres -p 5433 - Secure TCP/IP Connections with SSL + Secure TCP/IP Connections with SSL/TLS SSL + TLS PostgreSQL has native support for using - SSL connections to encrypt client/server communications + SSL/TLS connections to encrypt client/server communications for increased security. This requires that OpenSSL is installed on both client and server systems and that support in PostgreSQL is enabled at build time (see ). + + The terms SSL and TLS are often used + interchangeably to mean a secure encrypted connection using a + TLS protocol. SSL protocols are the + precursors to TLS protocols, and the term + SSL is still used for encrypted connections even though + SSL protocols are no longer supported. + SSL/TLS is used to refer to an + encrypted connection using a supported TLS protocol. + + Basic Setup - With SSL support compiled in, the + With SSL/TLS support compiled in, the PostgreSQL server can be started with - SSL enabled by setting the parameter + support for encrypted connections enabled by setting the parameter to on in postgresql.conf. The server will listen for both normal - and SSL connections on the same TCP port, and will negotiate - with any connecting client on whether to use SSL. By + and TLS connections on the same TCP port, and will negotiate + with any connecting client on whether to use TLS. By default, this is at the client's option; see about how to set up the server to require use of SSL for some or all connections. - To start in SSL mode, files containing the server certificate + To start in SSL/TLS mode, files containing the server certificate and private key must exist. By default, these files are expected to be named server.crt and server.key, respectively, in the server's data directory, but other names and locations can be specified @@ -2316,7 +2328,7 @@ pg_dumpall -p 5432 | psql -d postgres -p 5433 authentication option clientcert=verify-ca or clientcert=verify-full to the appropriate hostssl line(s) in pg_hba.conf. - A certificate will then be requested from the client during SSL + A certificate will then be requested from the client during SSL/TLS connection startup. (See for a description of how to set up certificates on the client.) @@ -2359,7 +2371,7 @@ pg_dumpall -p 5432 | psql -d postgres -p 5433 The first approach makes use of the cert authentication method for hostssl entries in pg_hba.conf, such that the certificate itself is used for authentication while also - providing ssl connection security. See for details. + providing SSL/TLS connection security. See for details. (It is not necessary to specify any clientcert options explicitly when using the cert authentication method.) In this case, the cn (Common Name) provided in @@ -2378,16 +2390,16 @@ pg_dumpall -p 5432 | psql -d postgres -p 5433 - SSL Server File Usage + SSL/TLS Server File Usage summarizes the files that are - relevant to the SSL setup on the server. (The shown file names are default + relevant to the SSL/TLS setup on the server. (The shown file names are default names. The locally configured names could be different.)
- SSL Server File Usage + SSL/TLS Server File Usage @@ -2439,10 +2451,10 @@ pg_dumpall -p 5432 | psql -d postgres -p 5433 If an error in these files is detected at server start, the server will refuse to start. But if an error is detected during a configuration - reload, the files are ignored and the old SSL configuration continues to + reload, the files are ignored and the old SSL/TLS configuration continues to be used. On Windows systems, if an error in these files is detected at backend start, that backend will be unable to - establish an SSL connection. In all these cases, the error condition is + establish an SSL/TLS connection. In all these cases, the error condition is reported in the server log. @@ -2614,7 +2626,7 @@ openssl x509 -req -in server.csr -text -days 365 \ It is possible to use SSH to encrypt the network connection between clients and a PostgreSQL server. Done properly, this - provides an adequately secure network connection, even for non-SSL-capable + provides an adequately secure network connection, even for non-SSL/TLS-capable clients. @@ -2650,7 +2662,7 @@ psql -h localhost -p 63333 postgres connecting to the localhost bind address, and it will use whatever authentication procedure was configured for connections by that user to that bind address. Note that the server will not - think the connection is SSL-encrypted, since in fact it is not + think the connection is SSL/TLS-encrypted, since in fact it is not encrypted between the SSH server and the PostgreSQL server. This should not pose any diff --git a/doc/src/sgml/sslinfo.sgml b/doc/src/sgml/sslinfo.sgml index 2a9c45a111..4612a46a41 100644 --- a/doc/src/sgml/sslinfo.sgml +++ b/doc/src/sgml/sslinfo.sgml @@ -8,10 +8,10 @@ - The sslinfo module provides information about the SSL + The sslinfo module provides information about the SSL/TLS certificate that the current client provided when connecting to PostgreSQL. The module is useless (most functions - will return NULL) if the current connection does not use SSL. + will return NULL) if the current connection does not use SSL/TLS. @@ -38,7 +38,7 @@ - Returns true if current connection to server uses SSL, and false + Returns true if current connection to server uses SSL/TLS, and false otherwise. @@ -53,7 +53,7 @@ - Returns the name of the protocol used for the SSL connection (e.g., TLSv1.0, + Returns the name of the protocol used for the SSL/TLS connection (e.g., TLSv1.0, TLSv1.1, TLSv1.2 or TLSv1.3). @@ -68,7 +68,7 @@ - Returns the name of the cipher used for the SSL connection + Returns the name of the cipher used for the SSL/TLS connection (e.g., DHE-RSA-AES256-SHA). @@ -83,7 +83,7 @@ - Returns true if current client has presented a valid SSL client + Returns true if current client has presented a valid SSL/TLS client certificate to the server, and false otherwise. (The server might or might not be configured to require a client certificate.) -- 2.30.1 (Apple Git-130)