From 860ea46ba7be69c46c37a96983e1ddca9d630c2e Mon Sep 17 00:00:00 2001
From: Daniel Gustafsson <dgustafsson@postgresql.org>
Date: Wed, 30 Mar 2022 13:07:30 +0200
Subject: [PATCH] doc: Clarify when SSL actually means TLS

SSL has become the de facto term to mean an end-to-end encrypted channel
regardless of protocol used, even though the SSL protocol is deprecated.
Clarify what we mean with SSL in our documentation, especially for new
users who might be looking for TLS.

Reviewed-by: Robert Haas <robertmhaas@gmail.com>
Discussion: https://postgr.es/m/D4ABB281-6CFD-46C6-A4E0-8EC23A2977BC@yesql.se
---
 doc/src/sgml/config.sgml  |  8 +++++++-
 doc/src/sgml/libpq.sgml   |  6 ++++--
 doc/src/sgml/runtime.sgml | 15 ++++++++++++++-
 3 files changed, 25 insertions(+), 4 deletions(-)

diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml
index 05df48131d..9788e831bc 100644
--- a/doc/src/sgml/config.sgml
+++ b/doc/src/sgml/config.sgml
@@ -1184,7 +1184,13 @@ include_dir 'conf.d'
      <title>SSL</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</acronym>. The configuration parameters for controlling
+      transfer encryption using <acronym>TLS</acronym> protocols 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>
diff --git a/doc/src/sgml/libpq.sgml b/doc/src/sgml/libpq.sgml
index eac5dee9f7..0b2a8720f0 100644
--- a/doc/src/sgml/libpq.sgml
+++ b/doc/src/sgml/libpq.sgml
@@ -8292,12 +8292,14 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*)
 
   <indexterm zone="libpq-ssl">
    <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 for increased
-   security. See <xref linkend="ssl-tcp"/> for details about the server-side
+   connections to encrypt client/server communications using
+   <acronym>TLS</acronym> protocols for increased security.
+   See <xref linkend="ssl-tcp"/> for details about the server-side
    <acronym>SSL</acronym> functionality.
   </para>
 
diff --git a/doc/src/sgml/runtime.sgml b/doc/src/sgml/runtime.sgml
index 3a463f12d7..1f021ea116 100644
--- a/doc/src/sgml/runtime.sgml
+++ b/doc/src/sgml/runtime.sgml
@@ -2182,6 +2182,7 @@ pg_dumpall -p 5432 | psql -d postgres -p 5433
 
   <indexterm zone="ssl-tcp">
    <primary>SSL</primary>
+   <secondary>TLS</secondary>
   </indexterm>
 
   <para>
@@ -2193,13 +2194,25 @@ pg_dumpall -p 5432 | psql -d postgres -p 5433
    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</acronym> is used interchangeably with <acronym>TLS</acronym>
+   in <productname>PostgreSQL</productname>.
+
+  </para>
   <sect2 id="ssl-setup">
    <title>Basic Setup</title>
 
   <para>
    With <acronym>SSL</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 using <acronym>TLS</acronym> protocols
+   enabled by 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