On Wed, Jun 30, 2021, at 5:46 PM, Daniel Gustafsson wrote: > > On 30 Jun 2021, at 20:20, Peter Eisentraut > > <peter.eisentr...@enterprisedb.com> wrote: > > > I am not in favor of this direction. I think it just adds tediousness and > > doesn't really help anyone. If we are worried about correct terminology, > > then we should just change everything to TLS. > > I actually think SSL/TLS has won the debate of "correct terminology" for > describing a secure connection encrypted by a TLS protocol. > TLS is described as a successor of SSL. However, the terminology SSL is still popular when you are talking about secure connection over a computer network. It seems that's one of the main reasons for articles/documentation use SSL/TLS.
The primary use of SSL/TLS is to secure WWW connections over HTTP protocol. A recent survey reveals that SSL is supported by less than 4% of the websites in the world [1]. SSL 3.0 (the latest published protocol version) is deprecated since 2015 (6 years ago) [2]. There is no web browser that has SSL enabled by default (indeed, most of them don't support SSL anymore). I tend to agree with Peter that the correct terminology is TLS. However, SSL is still popular (probably because popular SSL/TLS libraries contain SSL in its name). If we change to SSL/TLS, I'm afraid we have this discussion again for (a) remove SSL or (b) add another popular secure protocol and we end up with SSL/TLS/FOO terminology. Commit fe61df7f introduces a new configure option that is --with-ssl. Such option is also used in other softwares too. All configuration parameters related to SSL/TLS starts with ssl. It is hard to decide among popular (SSL), correct (TLS), and mix (SSL/TLS). If I have to pick one, it would be SSL/TLS. It mentions both acronyms that is easier to correlate with configuration parameters, secure connections (via --with-ssl) and current protocol (TLS). Your patch doesn't apply anymore and requires a rebase. I'm attaching a new version. It looks good to me. I noticed that you are using <acronym>SSL/TLS</acronym>, however, the acronyms are declared separated. It doesn't seem to be a presentation issue per se but I'm asking just in case. [1] https://en.wikipedia.org/wiki/Transport_Layer_Security#Websites [1] https://datatracker.ietf.org/doc/html/rfc7568 -- Euler Taveira EDB https://www.enterprisedb.com/
From 22bc9135daf15723a9ef0f4c4365ac1bddc08f4c Mon Sep 17 00:00:00 2001 From: Daniel Gustafsson <dan...@yesql.se> Date: Thu, 24 Jun 2021 11:01:39 +0200 Subject: [PATCH v4 1/2] Docs: SSL/TLS related acronyms This adds MITM and SNI as acronyms, as the documentation already had them marked up with <acronym />. Also while in there, make sure to spell man-in-the-middle with dashes consistently. Author: Daniel Gustafsson <dan...@yesql.se> Reviewed-by: Michael Paquier <mich...@paquier.xyz> Discussion: https://postgr.es/m/ce12dd5c-4bb3-4166-bc9a-397795687...@yesql.se --- doc/src/sgml/acronyms.sgml | 4 ++-- doc/src/sgml/libpq.sgml | 3 ++- 2 files changed, 4 insertions(+), 3 deletions(-) diff --git a/doc/src/sgml/acronyms.sgml b/doc/src/sgml/acronyms.sgml index 9ed148ab84..98873ff09f 100644 --- a/doc/src/sgml/acronyms.sgml +++ b/doc/src/sgml/acronyms.sgml @@ -416,7 +416,7 @@ <para> <ulink url="https://en.wikipedia.org/wiki/Man-in-the-middle_attack";> - Man-in-the-middle attack</ulink> + Man-in-the-middle</ulink> attack </para> </listitem> </varlistentry> @@ -606,7 +606,7 @@ <listitem> <para> <ulink - url="https://en.wikipedia.org/wiki/Server_Name_Indication";> + url="https://en.wikipedia.org/wiki/Server_Name_Indication";> Server Name Indication</ulink>, <ulink url="https://tools.ietf.org/html/rfc6066#section-3";>RFC 6066</ulink> </para> diff --git a/doc/src/sgml/libpq.sgml b/doc/src/sgml/libpq.sgml index 59e3e678f9..61adadf4f6 100644 --- a/doc/src/sgml/libpq.sgml +++ b/doc/src/sgml/libpq.sgml @@ -1784,7 +1784,8 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname <para> By default, libpq sets the TLS extension <quote>Server Name Indication</quote> (<acronym>SNI</acronym>) on SSL-enabled connections. - By setting this parameter to 0, this is turned off. + By setting this parameter to <literal>0</literal>, this + is turned off. </para> <para> -- 2.20.1
From f3e00577aefe78ae0ec73c1be57766a4f616cd7a Mon Sep 17 00:00:00 2001 From: Daniel Gustafsson <dan...@yesql.se> Date: Thu, 24 Jun 2021 11:05:00 +0200 Subject: [PATCH v4 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 protocol is discussed. Also add small explanatory sections describing why SSL/TLS is used. Author: Daniel Gustafsson <dan...@yesql.se> Reviewed-by: Michael Paquier <mich...@paquier.xyz> Discussion: https://postgr.es/m/ce12dd5c-4bb3-4166-bc9a-397795687...@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 | 151 +++++++++++++++-------------- 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, 201 insertions(+), 182 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 <replaceable>database</replaceable> <replaceable>user</replaceabl <para> This record matches connection attempts made using TCP/IP. <literal>host</literal> records match - <acronym>SSL</acronym> or non-<acronym>SSL</acronym> connection + <acronym>SSL/TLS</acronym> or non-<acronym>SSL/TLS</acronym> connection attempts as well as <acronym>GSSAPI</acronym> encrypted or non-<acronym>GSSAPI</acronym> encrypted connection attempts. </para> @@ -156,14 +156,14 @@ hostnogssenc <replaceable>database</replaceable> <replaceable>user</replaceabl <listitem> <para> This record matches connection attempts made using TCP/IP, - but only when the connection is made with <acronym>SSL</acronym> + but only when the connection is made with <acronym>SSL/TLS</acronym> encryption. </para> <para> To make use of this option the server must be built with - <acronym>SSL</acronym> support. Furthermore, - <acronym>SSL</acronym> must be enabled + <acronym>SSL/TLS</acronym> support. Furthermore, + <acronym>SSL/TLS</acronym> must be enabled by setting the <xref linkend="guc-ssl"/> configuration parameter (see <xref linkend="ssl-tcp"/> for more information). Otherwise, the <literal>hostssl</literal> record is ignored except for @@ -178,7 +178,7 @@ hostnogssenc <replaceable>database</replaceable> <replaceable>user</replaceabl <para> This record type has the opposite behavior of <literal>hostssl</literal>; it only matches connection attempts made over - TCP/IP that do not use <acronym>SSL</acronym>. + TCP/IP that do not use <acronym>SSL/TLS</acronym>. </para> </listitem> </varlistentry> @@ -555,7 +555,7 @@ hostnogssenc <replaceable>database</replaceable> <replaceable>user</replaceabl <term><literal>cert</literal></term> <listitem> <para> - Authenticate using SSL client certificates. See + Authenticate using <acronym>SSL/TLS</acronym> client certificates. See <xref linkend="auth-cert"/> for details. </para> </listitem> @@ -603,7 +603,7 @@ hostnogssenc <replaceable>database</replaceable> <replaceable>user</replaceabl can be specified in any <literal>hostssl</literal> record. This option can be set to <literal>verify-ca</literal> or <literal>verify-full</literal>. Both options require the client - to present a valid (trusted) SSL certificate, while + to present a valid (trusted) <acronym>SSL/TLS</acronym> certificate, while <literal>verify-full</literal> additionally enforces that the <literal>cn</literal> (Common Name) in the certificate matches the username or an applicable mapping. @@ -993,8 +993,8 @@ omicron bryanh guest1 <listitem> <para> <link linkend="auth-cert">Certificate authentication</link>, which - requires an SSL connection and authenticates users by checking the - SSL certificate they send. + requires an <acronym>SSL/TLS</acronym> connection and authenticates users by checking the + <acronym>SSL/TLS</acronym> certificate they send. </para> </listitem> <listitem> @@ -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 <acronym>SSL/TLS</acronym> certificates), or are platform-specific. </para> <para> @@ -1150,10 +1150,10 @@ omicron bryanh guest1 <para> The method <literal>password</literal> sends the password in clear-text and is therefore vulnerable to password <quote>sniffing</quote> 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 <acronym>SSL/TLS</acronym> encryption then <literal>password</literal> can be used safely, though. - (Though SSL certificate authentication might be a better choice if one - is depending on using SSL). + (Though <acronym>SSL/TLS</acronym> certificate authentication might be a better choice if one + is depending on using <acronym>SSL/TLS</acronym>). </para> </listitem> </varlistentry> @@ -1223,7 +1223,7 @@ omicron bryanh guest1 <productname>GSSAPI</productname> provides automatic authentication (single sign-on) for systems that support it. The authentication itself is secure. If <productname>GSSAPI</productname> encryption - or <acronym>SSL</acronym> encryption is + or <acronym>SSL/TLS</acronym> encryption is used, the data sent along the database connection will be encrypted; otherwise, it will not. </para> @@ -1686,7 +1686,7 @@ omicron bryanh guest1 <listitem> <para> Set to <literal>ldaps</literal> to use LDAPS. This is a non-standard - way of using LDAP over SSL, supported by some LDAP server + way of using LDAP over <acronym>SSL/TLS</acronym>, supported by some LDAP server implementations. See also the <literal>ldaptls</literal> option for an alternative. </para> @@ -1697,7 +1697,7 @@ omicron bryanh guest1 <listitem> <para> Set to 1 to make the connection between PostgreSQL and the LDAP server - use TLS encryption. This uses the <literal>StartTLS</literal> + use <acronym>TLS</acronym> encryption. This uses the <literal>StartTLS</literal> operation per <ulink url="https://tools.ietf.org/html/rfc4513";>RFC 4513</ulink>. See also the <literal>ldapscheme</literal> option for an alternative. </para> @@ -1711,7 +1711,7 @@ omicron bryanh guest1 <literal>ldaptls</literal> 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 <acronym>SSL/TLS</acronym> is used there as well. </para> <para> @@ -1812,7 +1812,7 @@ ldap[s]://<replaceable>host</replaceable>[:<replaceable>port</replaceable>]/<rep <para> The URL scheme <literal>ldaps</literal> chooses the LDAPS method for - making LDAP connections over SSL, equivalent to using + making LDAP connections over <acronym>SSL/TLS</acronym>, equivalent to using <literal>ldapscheme=ldaps</literal>. To use encrypted LDAP connections using the <literal>StartTLS</literal> operation, use the normal URL scheme <literal>ldap</literal> and specify the @@ -2045,8 +2045,8 @@ host ... radius radiusservers="server1,server2" radiussecrets="""secret one"","" </indexterm> <para> - This authentication method uses SSL client certificates to perform - authentication. It is therefore only available for SSL connections. + This authentication method uses <acronym>SSL/TLS</acronym> client certificates to perform + authentication. It is therefore only available for <acronym>SSL/TLS</acronym> 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 <literal>cn</literal> (Common Name) @@ -2057,7 +2057,7 @@ host ... radius radiusservers="server1,server2" radiussecrets="""secret one"","" </para> <para> - The following configuration options are supported for SSL certificate + The following configuration options are supported for <acronym>SSL/TLS</acronym> certificate authentication: <variablelist> <varlistentry> diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml index 6098f6b020..97a590c665 100644 --- a/doc/src/sgml/config.sgml +++ b/doc/src/sgml/config.sgml @@ -1181,10 +1181,16 @@ include_dir 'conf.d' </sect2> <sect2 id="runtime-config-connection-ssl"> - <title>SSL</title> + <title>SSL/TLS</title> <para> - See <xref linkend="ssl-tcp"/> for more information about setting up SSL. + See <xref linkend="ssl-tcp"/> for more information about setting up + <acronym>SSL/TLS</acronym>. The configuration + parameters for controlling <acronym>SSL/TLS</acronym> + are named <literal>ssl</literal> for historic reasons, even though + support for the <acronym>SSL</acronym> protocol has been deprecated. + <acronym>SSL</acronym> is in this context used interchangeably with + <acronym>TLS</acronym>. </para> <variablelist> @@ -1196,7 +1202,7 @@ include_dir 'conf.d' </term> <listitem> <para> - Enables <acronym>SSL</acronym> connections. + Enables <acronym>SSL/TLS</acronym> connections. This parameter can only be set in the <filename>postgresql.conf</filename> file or on the server command line. The default is <literal>off</literal>. @@ -1212,7 +1218,7 @@ include_dir 'conf.d' </term> <listitem> <para> - Specifies the name of the file containing the SSL server certificate + Specifies the name of the file containing the <acronym>SSL/TLS</acronym> server certificate authority (CA). Relative paths are relative to the data directory. This parameter can only be set in the <filename>postgresql.conf</filename> @@ -1231,7 +1237,7 @@ include_dir 'conf.d' </term> <listitem> <para> - Specifies the name of the file containing the SSL server certificate. + Specifies the name of the file containing the <acronym>SSL/TLS</acronym> server certificate. Relative paths are relative to the data directory. This parameter can only be set in the <filename>postgresql.conf</filename> file or on the server command line. @@ -1248,7 +1254,7 @@ include_dir 'conf.d' </term> <listitem> <para> - Specifies the name of the file containing the SSL server certificate + Specifies the name of the file containing the <acronym>SSL/TLS</acronym> server certificate revocation list (CRL). Relative paths are relative to the data directory. This parameter can only be set in the <filename>postgresql.conf</filename> @@ -1267,7 +1273,7 @@ include_dir 'conf.d' </term> <listitem> <para> - Specifies the name of the directory containing the SSL server + Specifies the name of the directory containing the <acronym>SSL/TLS</acronym> server certificate revocation list (CRL). Relative paths are relative to the data directory. This parameter can only be set in the <filename>postgresql.conf</filename> file or on the server command @@ -1301,7 +1307,7 @@ include_dir 'conf.d' </term> <listitem> <para> - Specifies the name of the file containing the SSL server private key. + Specifies the name of the file containing the <acronym>SSL/TLS</acronym> server private key. Relative paths are relative to the data directory. This parameter can only be set in the <filename>postgresql.conf</filename> file or on the server command line. @@ -1318,13 +1324,13 @@ include_dir 'conf.d' </term> <listitem> <para> - Specifies a list of <acronym>SSL</acronym> cipher suites that are - allowed to be used by SSL connections. See the + Specifies a list of <acronym>SSL/TLS</acronym> cipher suites that are + allowed to be used by <acronym>SSL/TLS</acronym> connections. See the <citerefentry><refentrytitle>ciphers</refentrytitle></citerefentry> manual page in the <productname>OpenSSL</productname> 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 <acronym>TLS</acronym> version 1.2 and lower are affected. There is + currently no setting that controls the cipher choices used by <acronym>TLS</acronym> version 1.3 connections. The default value is <literal>HIGH:MEDIUM:+3DES:!aNULL</literal>. The default is usually a reasonable choice unless you have specific security requirements. @@ -1405,7 +1411,7 @@ include_dir 'conf.d' </term> <listitem> <para> - Specifies whether to use the server's SSL cipher preferences, rather + Specifies whether to use the server's <acronym>SSL/TLS</acronym> cipher preferences, rather than the client's. This parameter can only be set in the <filename>postgresql.conf</filename> file or on the server command line. @@ -1460,12 +1466,12 @@ include_dir 'conf.d' </term> <listitem> <para> - Sets the minimum SSL/TLS protocol version to use. Valid values are + Sets the minimum <acronym>TLS</acronym> protocol version to use. Valid values are currently: <literal>TLSv1</literal>, <literal>TLSv1.1</literal>, <literal>TLSv1.2</literal>, <literal>TLSv1.3</literal>. Older versions of the <productname>OpenSSL</productname> 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 <acronym>TLS</acronym> version 1.0, namely <acronym>SSL</acronym> version 2 and 3, are always disabled. </para> @@ -1489,7 +1495,7 @@ include_dir 'conf.d' </term> <listitem> <para> - Sets the maximum SSL/TLS protocol version to use. Valid values are as + Sets the maximum <acronym>TLS</acronym> protocol version to use. Valid values are as for <xref linkend="guc-ssl-min-protocol-version"/>, 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' <listitem> <para> 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 <acronym>SSL/TLS</acronym> 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' <listitem> <para> 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 <acronym>SSL/TLS</acronym> 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. </para> @@ -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 <varname>ssl_passphrase_command</varname> will be ignored during a - reload and the SSL configuration will not be reloaded if a passphrase + reload and the <acronym>SSL/TLS</acronym> 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 @@ -10211,9 +10217,9 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' </term> <listitem> <para> - Reports the name of the SSL library that this + Reports the name of the <acronym>SSL/TLS</acronym> library that this <productname>PostgreSQL</productname> server was built with (even if - SSL is not currently configured or in use on this instance), for + <acronym>SSL/TLS</acronym> is not currently configured or in use on this instance), for example <literal>OpenSSL</literal>, or an empty string if none. </para> </listitem> diff --git a/doc/src/sgml/install-windows.sgml b/doc/src/sgml/install-windows.sgml index ba794b8c93..50baeb4668 100644 --- a/doc/src/sgml/install-windows.sgml +++ b/doc/src/sgml/install-windows.sgml @@ -308,7 +308,7 @@ $ENV{MSBFLAGS}="/m"; <varlistentry> <term><productname>OpenSSL</productname></term> <listitem><para> - Required for SSL support. Binaries can be downloaded from + Required for <acronym>SSL/TLS</acronym> support. Binaries can be downloaded from <ulink url="https://slproweb.com/products/Win32OpenSSL.html";></ulink> or source from <ulink url="https://www.openssl.org";></ulink>. </para></listitem> diff --git a/doc/src/sgml/installation.sgml b/doc/src/sgml/installation.sgml index 61d0bc8c43..ab04fde462 100644 --- a/doc/src/sgml/installation.sgml +++ b/doc/src/sgml/installation.sgml @@ -995,7 +995,7 @@ build-postgresql: </term> <listitem> <para> - Build with support for <acronym>SSL</acronym> (encrypted) + Build with support for <acronym>SSL/TLS</acronym> (encrypted) connections. The only <replaceable>LIBRARY</replaceable> supported is <option>openssl</option>. This requires the <productname>OpenSSL</productname> package to be installed. diff --git a/doc/src/sgml/libpq.sgml b/doc/src/sgml/libpq.sgml index 61adadf4f6..6516310585 100644 --- a/doc/src/sgml/libpq.sgml +++ b/doc/src/sgml/libpq.sgml @@ -423,7 +423,7 @@ PostgresPollingStatusType PQconnectPoll(PGconn *conn); <term><symbol>CONNECTION_SSL_STARTUP</symbol></term> <listitem> <para> - Negotiating SSL encryption. + Negotiating <acronym>SSL/TLS</acronym> encryption. </para> </listitem> </varlistentry> @@ -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 <literal>verify-full</literal> SSL + methods, as well as for <literal>verify-full</literal> <acronym>SSL/TLS</acronym> certificate verification. The following rules are used: <itemizedlist> <listitem> @@ -1231,12 +1231,12 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname choose channel binding if available, and <literal>disable</literal> prevents the use of channel binding. The default is <literal>prefer</literal> if - <productname>PostgreSQL</productname> is compiled with SSL support; + <productname>PostgreSQL</productname> is compiled with <acronym>SSL/TLS</acronym> support; otherwise the default is <literal>disable</literal>. </para> <para> 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 <acronym>SSL/TLS</acronym> connections with <productname>PostgreSQL</productname> 11 or later servers using the <literal>SCRAM</literal> authentication method. </para> @@ -1517,7 +1517,7 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname <listitem> <para> This option determines whether or with what priority a secure - <acronym>SSL</acronym> TCP/IP connection will be negotiated with the + <acronym>SSL/TLS</acronym> TCP/IP connection will be negotiated with the server. There are six modes: <variablelist> @@ -1525,7 +1525,7 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname <term><literal>disable</literal></term> <listitem> <para> - only try a non-<acronym>SSL</acronym> connection + only try a non-<acronym>SSL/TLS</acronym> connection </para> </listitem> </varlistentry> @@ -1534,8 +1534,8 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname <term><literal>allow</literal></term> <listitem> <para> - first try a non-<acronym>SSL</acronym> connection; if that - fails, try an <acronym>SSL</acronym> connection + first try a non-<acronym>SSL/TLS</acronym> connection; if that + fails, try an <acronym>SSL/TLS</acronym> connection </para> </listitem> </varlistentry> @@ -1544,8 +1544,8 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname <term><literal>prefer</literal> (default)</term> <listitem> <para> - first try an <acronym>SSL</acronym> connection; if that fails, - try a non-<acronym>SSL</acronym> connection + first try an <acronym>SSL/TLS</acronym> connection; if that fails, + try a non-<acronym>SSL/TLS</acronym> connection </para> </listitem> </varlistentry> @@ -1554,7 +1554,7 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname <term><literal>require</literal></term> <listitem> <para> - only try an <acronym>SSL</acronym> connection. If a root CA + only try an <acronym>SSL/TLS</acronym> connection. If a root CA file is present, verify the certificate in the same way as if <literal>verify-ca</literal> was specified </para> @@ -1565,7 +1565,7 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname <term><literal>verify-ca</literal></term> <listitem> <para> - only try an <acronym>SSL</acronym> connection, and verify that + only try an <acronym>SSL/TLS</acronym> connection, and verify that the server certificate is issued by a trusted certificate authority (<acronym>CA</acronym>) </para> @@ -1576,7 +1576,7 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname <term><literal>verify-full</literal></term> <listitem> <para> - only try an <acronym>SSL</acronym> connection, verify that the + only try an <acronym>SSL/TLS</acronym> connection, verify that the server certificate is issued by a trusted <acronym>CA</acronym> and that the requested server host name matches that in the certificate @@ -1592,21 +1592,21 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname <para> <literal>sslmode</literal> is ignored for Unix domain socket communication. - If <productname>PostgreSQL</productname> is compiled without SSL support, + If <productname>PostgreSQL</productname> is compiled without <acronym>SSL/TLS</acronym> support, using options <literal>require</literal>, <literal>verify-ca</literal>, or <literal>verify-full</literal> will cause an error, while options <literal>allow</literal> and <literal>prefer</literal> will be accepted but <application>libpq</application> will not actually attempt - an <acronym>SSL</acronym> + an <acronym>SSL/TLS</acronym> connection.<indexterm><primary>SSL</primary><secondary sortas="libpq">with libpq</secondary></indexterm> </para> <para> Note that if <acronym>GSSAPI</acronym> encryption is possible, - that will be used in preference to <acronym>SSL</acronym> + that will be used in preference to <acronym>SSL/TLS</acronym> encryption, regardless of the value of <literal>sslmode</literal>. - To force use of <acronym>SSL</acronym> encryption in an + To force use of <acronym>SSL/TLS</acronym> encryption in an environment that has working <acronym>GSSAPI</acronym> infrastructure (such as a Kerberos server), also set <literal>gssencmode</literal> to <literal>disable</literal>. @@ -1623,15 +1623,15 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname </para> <para> - If set to 1, an <acronym>SSL</acronym> connection to the server + If set to 1, an <acronym>SSL/TLS</acronym> connection to the server is required (this is equivalent to <literal>sslmode</literal> <literal>require</literal>). <application>libpq</application> will then refuse to connect if the server does not accept an - <acronym>SSL</acronym> connection. If set to 0 (default), + <acronym>SSL/TLS</acronym> connection. If set to 0 (default), <application>libpq</application> will negotiate the connection type with the server (equivalent to <literal>sslmode</literal> <literal>prefer</literal>). This option is only available if - <productname>PostgreSQL</productname> is compiled with SSL support. + <productname>PostgreSQL</productname> is compiled with <acronym>SSL/TLS</acronym> support. </para> </listitem> </varlistentry> @@ -1640,13 +1640,13 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname <term><literal>sslcompression</literal></term> <listitem> <para> - If set to 1, data sent over SSL connections will be compressed. If + If set to 1, data sent over <acronym>SSL/TLS</acronym> 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 <acronym>SSL/TLS</acronym> is made. </para> <para> - SSL compression is nowadays considered insecure and its use is no + <acronym>SSL/TLS</acronym> compression is nowadays considered insecure and its use is no longer recommended. <productname>OpenSSL</productname> 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 <term><literal>sslcert</literal></term> <listitem> <para> - This parameter specifies the file name of the client SSL + This parameter specifies the file name of the client <acronym>SSL/TLS</acronym> certificate, replacing the default <filename>~/.postgresql/postgresql.crt</filename>. - This parameter is ignored if an SSL connection is not made. + This parameter is ignored if an <acronym>SSL/TLS</acronym> connection is not made. </para> </listitem> </varlistentry> @@ -1688,7 +1688,7 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname <productname>OpenSSL</productname> 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. + <acronym>SSL/TLS</acronym> connection is not made. </para> </listitem> </varlistentry> @@ -1729,7 +1729,7 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname <term><literal>sslrootcert</literal></term> <listitem> <para> - This parameter specifies the name of a file containing SSL + This parameter specifies the name of a file containing <acronym>SSL/TLS</acronym> certificate authority (<acronym>CA</acronym>) 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 <term><literal>sslcrl</literal></term> <listitem> <para> - 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 <acronym>SSL/TLS</acronym> certificate + revocation list (<acronym>CRL</acronym>). Certificates listed in this file, if it exists, will be rejected while attempting to authenticate the server's certificate. If neither <xref linkend='libpq-connect-sslcrl'/> nor @@ -1758,8 +1758,8 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname <term><literal>sslcrldir</literal></term> <listitem> <para> - 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 <acronym>SSL/TLS</acronym> certificate + revocation list (<acronym>CRL</acronym>). Certificates listed in the files in this directory, if it exists, will be rejected while attempting to authenticate the server's certificate. </para> @@ -1782,19 +1782,19 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname <term><literal>sslsni</literal><indexterm><primary>Server Name Indication</primary></indexterm></term> <listitem> <para> - By default, libpq sets the TLS extension <quote>Server Name - Indication</quote> (<acronym>SNI</acronym>) on SSL-enabled connections. + By default, libpq sets the <acronym>TLS</acronym> extension <quote>Server Name + Indication</quote> (<acronym>SNI</acronym>) on <acronym>SSL/TLS</acronym>-enabled connections. By setting this parameter to <literal>0</literal>, this is turned off. </para> <para> - 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 <acronym>SSL/TLS</acronym>-aware proxies to route + connections without having to decrypt the <acronym>TLS</acronym> stream. (Note that this requires a proxy that is aware of the PostgreSQL protocol handshake, - not just any SSL proxy.) However, <acronym>SNI</acronym> makes the - destination host name appear in cleartext in the network traffic, so - it might be undesirable in some cases. + not just any <acronym>SSL/TLS</acronym> proxy.) However, <acronym>SNI</acronym> makes the destination host name + appear in cleartext in the network traffic, so it might be undesirable + in some cases. </para> </listitem> </varlistentry> @@ -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 <acronym>SSL/TLS</acronym> certificates on TCP/IP connections. (Note that if the Unix-domain socket is in <filename>/tmp</filename> 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 <term><literal>ssl_min_protocol_version</literal></term> <listitem> <para> - This parameter specifies the minimum SSL/TLS protocol version to allow + This parameter specifies the minimum <acronym>TLS</acronym> protocol version to allow for the connection. Valid values are <literal>TLSv1</literal>, <literal>TLSv1.1</literal>, <literal>TLSv1.2</literal> and <literal>TLSv1.3</literal>. The supported protocols depend on the @@ -1842,7 +1842,7 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname <term><literal>ssl_max_protocol_version</literal></term> <listitem> <para> - This parameter specifies the maximum SSL/TLS protocol version to allow + This parameter specifies the maximum <acronym>TLS</acronym> protocol version to allow for the connection. Valid values are <literal>TLSv1</literal>, <literal>TLSv1.1</literal>, <literal>TLSv1.2</literal> and <literal>TLSv1.3</literal>. The supported protocols depend on the @@ -2494,7 +2494,7 @@ int PQconnectionUsedPassword(const PGconn *conn); </para> <para> - The following functions return information related to SSL. This information + The following functions return information related to <acronym>SSL/TLS</acronym>. This information usually doesn't change after a connection is established. <variablelist> @@ -2502,7 +2502,7 @@ int PQconnectionUsedPassword(const PGconn *conn); <term><function>PQsslInUse</function><indexterm><primary>PQsslInUse</primary></indexterm></term> <listitem> <para> - Returns true (1) if the connection uses SSL, false (0) if not. + Returns true (1) if the connection uses <acronym>SSL/TLS</acronym>, false (0) if not. <synopsis> int PQsslInUse(const PGconn *conn); @@ -2516,7 +2516,7 @@ int PQsslInUse(const PGconn *conn); <term><function>PQsslAttribute</function><indexterm><primary>PQsslAttribute</primary></indexterm></term> <listitem> <para> - Returns SSL-related information about the connection. + Returns <acronym>SSL/TLS</acronym>-related information about the connection. <synopsis> const char *PQsslAttribute(const PGconn *conn, const char *attribute_name); @@ -2524,7 +2524,7 @@ const char *PQsslAttribute(const PGconn *conn, const char *attribute_name); </para> <para> - The list of available attributes varies depending on the SSL library + The list of available attributes varies depending on the <acronym>SSL/TLS</acronym> library being used, and the type of connection. If an attribute is not available, returns NULL. </para> @@ -2536,7 +2536,7 @@ const char *PQsslAttribute(const PGconn *conn, const char *attribute_name); <term><literal>library</literal></term> <listitem> <para> - Name of the SSL implementation in use. (Currently, only + Name of the <acronym>SSL/TLS</acronym> implementation in use. (Currently, only <literal>"OpenSSL"</literal> is implemented) </para> </listitem> @@ -2545,9 +2545,9 @@ const char *PQsslAttribute(const PGconn *conn, const char *attribute_name); <term><literal>protocol</literal></term> <listitem> <para> - SSL/TLS version in use. Common values - are <literal>"TLSv1"</literal>, <literal>"TLSv1.1"</literal> - and <literal>"TLSv1.2"</literal>, but an implementation may + <acronym>TLS</acronym> protocol version in use. Common values + are <literal>"TLSv1.2"</literal>, <literal>"TLSv1.1"</literal> + and <literal>"TLSv1.3"</literal>, but an implementation may return other strings if some other protocol is used. </para> </listitem> @@ -2566,7 +2566,7 @@ const char *PQsslAttribute(const PGconn *conn, const char *attribute_name); <para> A short name of the ciphersuite used, e.g., <literal>"DHE-RSA-DES-CBC3-SHA"</literal>. The names are specific - to each SSL implementation. + to each <acronym>SSL/TLS</acronym> implementation. </para> </listitem> </varlistentry> @@ -2574,7 +2574,7 @@ const char *PQsslAttribute(const PGconn *conn, const char *attribute_name); <term><literal>compression</literal></term> <listitem> <para> - If SSL compression is in use, returns the name of the compression + If <acronym>SSL/TLS</acronym> 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". </para> @@ -2589,7 +2589,7 @@ const char *PQsslAttribute(const PGconn *conn, const char *attribute_name); <term><function>PQsslAttributeNames</function><indexterm><primary>PQsslAttributeNames</primary></indexterm></term> <listitem> <para> - Return an array of SSL attribute names available. The array is terminated by a NULL pointer. + Return an array of <acronym>SSL/TLS</acronym> attribute names available. The array is terminated by a NULL pointer. <synopsis> const char * const * PQsslAttributeNames(const PGconn *conn); </synopsis> @@ -2601,14 +2601,14 @@ const char * const * PQsslAttributeNames(const PGconn *conn); <term><function>PQsslStruct</function><indexterm><primary>PQsslStruct</primary></indexterm></term> <listitem> <para> - Return a pointer to an SSL-implementation-specific object describing + Return a pointer to an <acronym>SSL/TLS</acronym>-implementation-specific object describing the connection. <synopsis> void *PQsslStruct(const PGconn *conn, const char *struct_name); </synopsis> </para> <para> - The struct(s) available depend on the SSL implementation in use. + The struct(s) available depend on the <acronym>SSL/TLS</acronym> implementation in use. For <productname>OpenSSL</productname>, there is one struct, available under the name "OpenSSL", and it returns a pointer to the <productname>OpenSSL</productname> <literal>SSL</literal> struct. @@ -2644,8 +2644,8 @@ void *PQsslStruct(const PGconn *conn, const char *struct_name); <listitem> <para> <indexterm><primary>SSL</primary><secondary sortas="libpq">in libpq</secondary></indexterm> - Returns the SSL structure used in the connection, or null - if SSL is not in use. + Returns the <literal>SSL</literal> structure used in the connection, or null + if <acronym>SSL/TLS</acronym> is not in use. <synopsis> void *PQgetssl(const PGconn *conn); @@ -2656,8 +2656,8 @@ void *PQgetssl(const PGconn *conn); This function is equivalent to <literal>PQsslStruct(conn, "OpenSSL")</literal>. It should not be used in new applications, because the returned struct is specific to <productname>OpenSSL</productname> and will not be - available if another <acronym>SSL</acronym> implementation is used. - To check if a connection uses SSL, call + available if another <acronym>SSL/TLS</acronym> implementation is used. + To check if a connection uses <acronym>SSL/TLS</acronym>, call <xref linkend="libpq-PQsslInUse"/> instead, and for more details about the connection, use <xref linkend="libpq-PQsslAttribute"/>. </para> @@ -8268,17 +8268,18 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*) <sect1 id="libpq-ssl"> - <title>SSL Support</title> + <title>SSL/TLS Support</title> <indexterm zone="libpq-ssl"> <primary>SSL</primary> + <secondary>TLS</secondary> </indexterm> <para> - <productname>PostgreSQL</productname> has native support for using <acronym>SSL</acronym> + <productname>PostgreSQL</productname> has native support for using <acronym>SSL/TLS</acronym> connections to encrypt client/server communications for increased security. See <xref linkend="ssl-tcp"/> for details about the server-side - <acronym>SSL</acronym> functionality. + <acronym>SSL/TLS</acronym> functionality. </para> <para> @@ -8327,7 +8328,7 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*) If <literal>sslmode</literal> is set to <literal>verify-full</literal>, libpq will <emphasis>also</emphasis> 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 + <acronym>SSL/TLS</acronym> connection will fail if the server certificate cannot be verified. <literal>verify-full</literal> is recommended in most security-sensitive environments. </para> @@ -8443,7 +8444,7 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*) <para> The different values for the <literal>sslmode</literal> parameter provide different - levels of protection. SSL can provide + levels of protection. <acronym>SSL/TLS</acronym> can provide protection against three types of attacks: <variablelist> @@ -8452,7 +8453,7 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*) <listitem> <para>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. <acronym>SSL</acronym> + the user name and password) and the data that is passed. <acronym>SSL/TLS</acronym> uses encryption to prevent this. </para> </listitem> @@ -8468,7 +8469,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. <acronym>SSL</acronym> uses certificate + attack methods that can accomplish this. <acronym>SSL/TLS</acronym> uses certificate verification to prevent this, by authenticating the server to the client. </para> </listitem> @@ -8479,7 +8480,7 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*) <listitem> <para>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. <acronym>SSL</acronym> uses + happen through insecure password management. <acronym>SSL/TLS</acronym> uses client certificates to prevent this, by making sure that only holders of valid certificates can access the server. </para> @@ -8489,7 +8490,7 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*) </para> <para> - For a connection to be known SSL-secured, SSL usage must be configured + For a connection to be known <acronym>SSL/TLS</acronym>-secured, <acronym>SSL/TLS</acronym> usage must be configured on <emphasis>both the client and the server</emphasis> 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 @@ -8509,7 +8510,7 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*) </para> <para> - All <acronym>SSL</acronym> options carry overhead in the form of encryption and + All <acronym>SSL/TLS</acronym> 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. <xref linkend="libpq-ssl-sslmode-statements"/> illustrates the risks the different <literal>sslmode</literal> values @@ -8517,7 +8518,7 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*) </para> <table id="libpq-ssl-sslmode-statements"> - <title>SSL Mode Descriptions</title> + <title>SSL/TLS Mode Descriptions</title> <tgroup cols="4"> <colspec colname="col1" colwidth="1*"/> <colspec colname="col2" colwidth="1*"/> @@ -8612,15 +8613,15 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*) </sect2> <sect2 id="libpq-ssl-fileusage"> - <title>SSL Client File Usage</title> + <title>SSL/TLS Client File Usage</title> <para> <xref linkend="libpq-ssl-file-usage"/> summarizes the files that are - relevant to the SSL setup on the client. + relevant to the <acronym>SSL/TLS</acronym> setup on the client. </para> <table id="libpq-ssl-file-usage"> - <title>Libpq/Client SSL File Usage</title> + <title>Libpq/Client SSL/TLS File Usage</title> <tgroup cols="3"> <thead> <row> @@ -8664,12 +8665,12 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*) </sect2> <sect2 id="libpq-ssl-initialize"> - <title>SSL Library Initialization</title> + <title>SSL/TLS Library Initialization</title> <para> If your application initializes <literal>libssl</literal> and/or <literal>libcrypto</literal> libraries and <application>libpq</application> - is built with <acronym>SSL</acronym> support, you should call + is built with <acronym>SSL/TLS</acronym> support, you should call <xref linkend="libpq-PQinitOpenSSL"/> to tell <application>libpq</application> that the <literal>libssl</literal> and/or <literal>libcrypto</literal> libraries have been initialized by your application, so that @@ -8695,7 +8696,7 @@ void PQinitOpenSSL(int do_ssl, int do_crypto); opening a database connection. When <parameter>do_crypto</parameter> is non-zero, the <literal>libcrypto</literal> library will be initialized. By default (if <xref linkend="libpq-PQinitOpenSSL"/> is not called), both libraries - are initialized. When SSL support is not compiled in, this function is + are initialized. When <acronym>SSL/TLS</acronym> support is not compiled in, this function is present but does nothing. </para> diff --git a/doc/src/sgml/monitoring.sgml b/doc/src/sgml/monitoring.sgml index 07a042254f..b582beed0c 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 <row> <entry><structname>pg_stat_ssl</structname><indexterm><primary>pg_stat_ssl</primary></indexterm></entry> <entry>One row per connection (regular and replication), showing information about - SSL used on this connection. + <acronym>SSL/TLS</acronym> used on this connection. See <link linkend="monitoring-pg-stat-ssl-view"> <structname>pg_stat_ssl</structname></link> for details. </entry> @@ -1185,7 +1185,7 @@ postgres 27093 0.0 0.0 30096 2752 ? Ss 11:34 0:00 postgres: ser </row> <row> <entry><literal>SSLOpenServer</literal></entry> - <entry>Waiting for SSL while attempting connection.</entry> + <entry>Waiting for <acronym>SSL/TLS</acronym> while attempting connection.</entry> </row> <row> <entry><literal>WalSenderWaitForWAL</literal></entry> @@ -3054,7 +3054,7 @@ SELECT pid, wait_event_type, wait_event FROM pg_stat_activity WHERE wait_event i <para> The <structname>pg_stat_ssl</structname> 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 <acronym>SSL/TLS</acronym> usage on this connection. It can be joined to <structname>pg_stat_activity</structname> or <structname>pg_stat_replication</structname> on the <structfield>pid</structfield> 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 <structfield>ssl</structfield> <type>boolean</type> </para> <para> - True if SSL is used on this connection + True if <acronym>SSL/TLS</acronym> is used on this connection </para></entry> </row> @@ -3099,7 +3099,7 @@ SELECT pid, wait_event_type, wait_event FROM pg_stat_activity WHERE wait_event i <structfield>version</structfield> <type>text</type> </para> <para> - Version of SSL in use, or NULL if SSL is not in use + <acronym>TLS</acronym> protocol version in use, or NULL if <acronym>SSL/TLS</acronym> is not in use on this connection </para></entry> </row> @@ -3109,7 +3109,7 @@ SELECT pid, wait_event_type, wait_event FROM pg_stat_activity WHERE wait_event i <structfield>cipher</structfield> <type>text</type> </para> <para> - Name of SSL cipher in use, or NULL if SSL is not in use + Name of <acronym>SSL/TLS</acronym> cipher in use, or NULL if <acronym>SSL/TLS</acronym> is not in use on this connection </para></entry> </row> @@ -3120,7 +3120,7 @@ SELECT pid, wait_event_type, wait_event FROM pg_stat_activity WHERE wait_event i </para> <para> Number of bits in the encryption algorithm used, or NULL - if SSL is not used on this connection + if <acronym>SSL/TLS</acronym> is not used on this connection </para></entry> </row> @@ -3130,7 +3130,7 @@ SELECT pid, wait_event_type, wait_event FROM pg_stat_activity WHERE wait_event i </para> <para> 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 <acronym>SSL/TLS</acronym> is not in use on this connection. This field is truncated if the DN field is longer than <symbol>NAMEDATALEN</symbol> (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 </para> <para> 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 <acronym>SSL/TLS</acronym> 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 </para> <para> 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 <acronym>SSL/TLS</acronym> is not in use on this connection. This field is truncated like <structfield>client_dn</structfield>. </para></entry> </row> 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 <orderedlist> <listitem> - <para>Connect locally or use SSL connections.</para> + <para>Connect locally or use <acronym>SSL/TLS</acronym> connections.</para> </listitem> <listitem> <para>Trust both system and database administrator.</para> diff --git a/doc/src/sgml/protocol.sgml b/doc/src/sgml/protocol.sgml index a3562f3d08..f3091706e6 100644 --- a/doc/src/sgml/protocol.sgml +++ b/doc/src/sgml/protocol.sgml @@ -1432,49 +1432,49 @@ SELCT 1/0;<!-- this typo is intentional --> </sect2> <sect2> - <title><acronym>SSL</acronym> Session Encryption</title> + <title><acronym>SSL/TLS</acronym> Session Encryption</title> <para> If <productname>PostgreSQL</productname> was built with - <acronym>SSL</acronym> support, frontend/backend communications - can be encrypted using <acronym>SSL</acronym>. This provides + <acronym>SSL/TLS</acronym> support, frontend/backend communications + can be encrypted using <acronym>SSL/TLS</acronym>. This provides communication security in environments where attackers might be able to capture the session traffic. For more information on encrypting <productname>PostgreSQL</productname> sessions with - <acronym>SSL</acronym>, see <xref linkend="ssl-tcp"/>. + <acronym>SSL/TLS</acronym>, see <xref linkend="ssl-tcp"/>. </para> <para> - To initiate an <acronym>SSL</acronym>-encrypted connection, the + To initiate an <acronym>SSL/TLS</acronym>-encrypted connection, the frontend initially sends an SSLRequest message rather than a StartupMessage. The server then responds with a single byte containing <literal>S</literal> or <literal>N</literal>, indicating that it is - willing or unwilling to perform <acronym>SSL</acronym>, + willing or unwilling to perform <acronym>SSL/TLS</acronym>, respectively. The frontend might close the connection at this point if it is dissatisfied with the response. To continue after - <literal>S</literal>, perform an <acronym>SSL</acronym> startup handshake - (not described here, part of the <acronym>SSL</acronym> + <literal>S</literal>, perform an <acronym>SSL/TLS</acronym> startup handshake + (not described here, part of the <acronym>SSL/TLS</acronym> 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 - <acronym>SSL</acronym>-encrypted. To continue after + <acronym>SSL/TLS</acronym>-encrypted. To continue after <literal>N</literal>, send the usual StartupMessage and proceed without encryption. (Alternatively, it is permissible to issue a GSSENCRequest message after an <literal>N</literal> response to try to use <acronym>GSSAPI</acronym> encryption instead - of <acronym>SSL</acronym>.) + of <acronym>SSL/TLS</acronym>.) </para> <para> 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 <acronym>SSL</acronym> support + the server predates the addition of <acronym>SSL/TLS</acronym> support to <productname>PostgreSQL</productname>. (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 <acronym>SSL</acronym>. + and proceed without requesting <acronym>SSL/TLS</acronym>. </para> <para> @@ -1484,7 +1484,7 @@ SELCT 1/0;<!-- this typo is intentional --> <para> While the protocol itself does not provide a way for the server to - force <acronym>SSL</acronym> encryption, the administrator can + force <acronym>SSL/TLS</acronym> encryption, the administrator can configure the server to reject unencrypted sessions as a byproduct of authentication checking. </para> @@ -1525,7 +1525,7 @@ SELCT 1/0;<!-- this typo is intentional --> encryption. (Alternatively, it is permissible to issue an SSLRequest message after an <literal>N</literal> response to try to - use <acronym>SSL</acronym> encryption instead + use <acronym>SSL/TLS</acronym> encryption instead of <acronym>GSSAPI</acronym>.) </para> @@ -1664,7 +1664,7 @@ the password is in. <para> <firstterm>Channel binding</firstterm> is supported in PostgreSQL builds with -SSL support. The SASL mechanism name for SCRAM with channel binding is +<acronym>SSL/TLS</acronym> support. The SASL mechanism name for SCRAM with channel binding is <literal>SCRAM-SHA-256-PLUS</literal>. The channel binding type used by PostgreSQL is <literal>tls-server-end-point</literal>. </para> @@ -1685,7 +1685,7 @@ PostgreSQL is <literal>tls-server-end-point</literal>. 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 <acronym>SSL/TLS</acronym> connection failure. </para> <procedure> @@ -1695,7 +1695,7 @@ PostgreSQL is <literal>tls-server-end-point</literal>. The server sends an AuthenticationSASL message. It includes a list of SASL authentication mechanisms that the server can accept. This will be <literal>SCRAM-SHA-256-PLUS</literal> - and <literal>SCRAM-SHA-256</literal> if the server is built with SSL + and <literal>SCRAM-SHA-256</literal> if the server is built with <acronym>SSL/TLS</acronym> support, or else just the latter. </para> </step> @@ -5889,7 +5889,7 @@ SSLRequest (F) </term> <listitem> <para> - The <acronym>SSL</acronym> request code. The value is chosen to contain + The <acronym>SSL/TLS</acronym> request code. The value is chosen to contain <literal>1234</literal> in the most significant 16 bits, and <literal>5679</literal> 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 <application>pg_rewind</application> 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 + <acronym>SSL/TLS</acronym> keys and certificates. If such files are present on the target server it is recommended to remove them before running <application>pg_rewind</application>. 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 <term><option>-l</option></term> <listitem> <para> - Enables secure connections using <acronym>SSL</acronym>. + Enables secure connections using <acronym>SSL/TLS</acronym>. <productname>PostgreSQL</productname> must have been compiled with - support for <acronym>SSL</acronym> for this option to be - available. For more information on using <acronym>SSL</acronym>, + support for <acronym>SSL/TLS</acronym> for this option to be + available. For more information on using <acronym>SSL/TLS</acronym>, refer to <xref linkend="ssl-tcp"/>. </para> </listitem> 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 <para> To prevent spoofing on TCP connections, either use - SSL certificates and make sure that clients check the server's certificate, + <acronym>SSL/TLS</acronym> certificates and make sure that clients check the server's certificate, or use GSSAPI encryption (or both, if they're on separate connections). </para> <para> - To prevent spoofing with SSL, the server + To prevent spoofing with <acronym>SSL/TLS</acronym>, the server must be configured to accept only <literal>hostssl</literal> connections (<xref - linkend="auth-pg-hba-conf"/>) and have SSL key and certificate files + linkend="auth-pg-hba-conf"/>) and have <acronym>SSL/TLS</acronym> key and certificate files (<xref linkend="ssl-tcp"/>). The TCP client must connect using <literal>sslmode=verify-ca</literal> or <literal>verify-full</literal> and have the appropriate root certificate @@ -2115,13 +2115,13 @@ pg_dumpall -p 5432 | psql -d postgres -p 5433 <listitem> <para> - SSL connections encrypt all data sent across the network: the + <acronym>SSL/TLS</acronym> connections encrypt all data sent across the network: the password, the queries, and the data returned. The <filename>pg_hba.conf</filename> file allows administrators to specify which hosts can use non-encrypted connections (<literal>host</literal>) - and which require SSL-encrypted connections + and which require <acronym>SSL/TLS</acronym>-encrypted connections (<literal>hostssl</literal>). Also, clients can specify that they - connect to servers only via SSL. + connect to servers only via <acronym>SSL/TLS</acronym>. </para> <para> @@ -2144,11 +2144,11 @@ pg_dumpall -p 5432 | psql -d postgres -p 5433 </varlistentry> <varlistentry> - <term>SSL Host Authentication</term> + <term>SSL/TLS Host Authentication</term> <listitem> <para> - It is possible for both the client and server to provide SSL + It is possible for both the client and server to provide <acronym>SSL/TLS</acronym> 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 </sect1> <sect1 id="ssl-tcp"> - <title>Secure TCP/IP Connections with SSL</title> + <title>Secure TCP/IP Connections with SSL/TLS</title> <indexterm zone="ssl-tcp"> <primary>SSL</primary> + <secondary>TLS</secondary> </indexterm> <para> <productname>PostgreSQL</productname> has native support for using - <acronym>SSL</acronym> connections to encrypt client/server communications + <acronym>SSL/TLS</acronym> connections to encrypt client/server communications for increased security. This requires that <productname>OpenSSL</productname> is installed on both client and server systems and that support in <productname>PostgreSQL</productname> is enabled at build time (see <xref linkend="installation"/>). </para> + <para> + The terms <acronym>SSL</acronym> and <acronym>TLS</acronym> are often used + interchangeably to mean a secure encrypted connection using a + <acronym>TLS</acronym> protocol. <acronym>SSL</acronym> protocols are the + precursors to <acronym>TLS</acronym> protocols, and the term + <acronym>SSL</acronym> is still used for encrypted connections even though + <acronym>SSL</acronym> protocols are no longer supported. + <acronym>SSL/TLS</acronym> is used to refer to an + encrypted connection using a supported <acronym>TLS</acronym> protocol. + </para> + <sect2 id="ssl-setup"> <title>Basic Setup</title> <para> - With <acronym>SSL</acronym> support compiled in, the + With <acronym>SSL/TLS</acronym> support compiled in, the <productname>PostgreSQL</productname> server can be started with - <acronym>SSL</acronym> enabled by setting the parameter + support for encrypted connections enabled by setting the parameter <xref linkend="guc-ssl"/> to <literal>on</literal> in <filename>postgresql.conf</filename>. The server will listen for both normal - and <acronym>SSL</acronym> connections on the same TCP port, and will negotiate - with any connecting client on whether to use <acronym>SSL</acronym>. By + and <acronym>TLS</acronym> connections on the same TCP port, and will negotiate + with any connecting client on whether to use <acronym>TLS</acronym>. By default, this is at the client's option; see <xref linkend="auth-pg-hba-conf"/> about how to set up the server to require use of <acronym>SSL</acronym> for some or all connections. </para> <para> - To start in <acronym>SSL</acronym> mode, files containing the server certificate + To start in <acronym>SSL/TLS</acronym> mode, files containing the server certificate and private key must exist. By default, these files are expected to be named <filename>server.crt</filename> and <filename>server.key</filename>, 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 <literal>clientcert=verify-ca</literal> or <literal>clientcert=verify-full</literal> to the appropriate <literal>hostssl</literal> line(s) in <filename>pg_hba.conf</filename>. - A certificate will then be requested from the client during SSL + A certificate will then be requested from the client during <acronym>SSL/TLS</acronym> connection startup. (See <xref linkend="libpq-ssl"/> for a description of how to set up certificates on the client.) </para> @@ -2359,7 +2371,7 @@ pg_dumpall -p 5432 | psql -d postgres -p 5433 The first approach makes use of the <literal>cert</literal> authentication method for <literal>hostssl</literal> entries in <filename>pg_hba.conf</filename>, such that the certificate itself is used for authentication while also - providing ssl connection security. See <xref linkend="auth-cert"/> for details. + providing <acronym>SSL/TLS</acronym> connection security. See <xref linkend="auth-cert"/> for details. (It is not necessary to specify any <literal>clientcert</literal> options explicitly when using the <literal>cert</literal> authentication method.) In this case, the <literal>cn</literal> (Common Name) provided in @@ -2378,16 +2390,16 @@ pg_dumpall -p 5432 | psql -d postgres -p 5433 </sect2> <sect2 id="ssl-server-files"> - <title>SSL Server File Usage</title> + <title>SSL/TLS Server File Usage</title> <para> <xref linkend="ssl-file-usage"/> summarizes the files that are - relevant to the SSL setup on the server. (The shown file names are default + relevant to the <acronym>SSL/TLS</acronym> setup on the server. (The shown file names are default names. The locally configured names could be different.) </para> <table id="ssl-file-usage"> - <title>SSL Server File Usage</title> + <title>SSL/TLS Server File Usage</title> <tgroup cols="3"> <thead> <row> @@ -2439,10 +2451,10 @@ pg_dumpall -p 5432 | psql -d postgres -p 5433 <para> 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 <acronym>SSL/TLS</acronym> configuration continues to be used. On <systemitem class="osname">Windows</systemitem> 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 <acronym>SSL/TLS</acronym> connection. In all these cases, the error condition is reported in the server log. </para> </sect2> @@ -2614,7 +2626,7 @@ openssl x509 -req -in server.csr -text -days 365 \ It is possible to use <application>SSH</application> to encrypt the network connection between clients and a <productname>PostgreSQL</productname> server. Done properly, this - provides an adequately secure network connection, even for non-SSL-capable + provides an adequately secure network connection, even for non-<acronym>SSL/TLS</acronym>-capable clients. </para> @@ -2650,7 +2662,7 @@ psql -h localhost -p 63333 postgres connecting to the <literal>localhost</literal> 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 <acronym>SSL/TLS</acronym>-encrypted, since in fact it is not encrypted between the <application>SSH</application> server and the <productname>PostgreSQL</productname> 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 @@ </indexterm> <para> - The <filename>sslinfo</filename> module provides information about the SSL + The <filename>sslinfo</filename> module provides information about the <acronym>SSL/TLS</acronym> certificate that the current client provided when connecting to <productname>PostgreSQL</productname>. 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 <acronym>SSL/TLS</acronym>. </para> <para> @@ -38,7 +38,7 @@ </term> <listitem> <para> - Returns true if current connection to server uses SSL, and false + Returns true if current connection to server uses <acronym>SSL/TLS</acronym>, and false otherwise. </para> </listitem> @@ -53,7 +53,7 @@ </term> <listitem> <para> - Returns the name of the protocol used for the SSL connection (e.g., TLSv1.0, + Returns the name of the protocol used for the <acronym>SSL/TLS</acronym> connection (e.g., TLSv1.0, TLSv1.1, TLSv1.2 or TLSv1.3). </para> </listitem> @@ -68,7 +68,7 @@ </term> <listitem> <para> - Returns the name of the cipher used for the SSL connection + Returns the name of the cipher used for the <acronym>SSL/TLS</acronym> connection (e.g., DHE-RSA-AES256-SHA). </para> </listitem> @@ -83,7 +83,7 @@ </term> <listitem> <para> - Returns true if current client has presented a valid SSL client + Returns true if current client has presented a valid <acronym>SSL/TLS</acronym> client certificate to the server, and false otherwise. (The server might or might not be configured to require a client certificate.) </para> -- 2.20.1
