SSL/TLS instead of SSL in docs

On Tue, Jun 15, 2021 at 03:59:18PM +0200, Daniel Gustafsson wrote:

While in there I added IMO missing items to the glossary and acronyms sections
as well as fixed up markup around OpenSSL.

This only deals with docs, but if this is deemed interesting then userfacing
messages in the code should use SSL/TLS as well of course.

+    <term><acronym>SNI</acronym></term>
+    <listitem>
+     <para>
+      <link linkend="libpq-connect-sslsni">Server Name Indication</link>
+     </para>
+    </listitem>
It looks inconsistent to me to point to the libpq documentation to get
the details about SNI.  Wouldn't is be better to have an item in the
glossary that refers to the bits of RFC 6066, and remove the reference
of the RPC from the libpq page?

-       to present a valid (trusted) SSL certificate, while
+       to present a valid (trusted) <acronym>SSL</acronym>/<acronym>TLS</acronym> certificate, while
This style with two acronyms for what we want to be one thing is
heavy.  Could it be better to just have one single acronym called
SSL/TLS that references both parts?

Patch 0003, for the <productname> markups with OpenSSL, included one
SSL/TLS entry.
--
Michael

On 18 Jun 2021, at 07:37, Michael Paquier <michael@paquier.xyz> wrote:

On Tue, Jun 15, 2021 at 03:59:18PM +0200, Daniel Gustafsson wrote:

While in there I added IMO missing items to the glossary and acronyms sections
as well as fixed up markup around OpenSSL.

This only deals with docs, but if this is deemed interesting then userfacing
messages in the code should use SSL/TLS as well of course.

+    <term><acronym>SNI</acronym></term>
+    <listitem>
+     <para>
+      <link linkend="libpq-connect-sslsni">Server Name Indication</link>
+     </para>
+    </listitem>
It looks inconsistent to me to point to the libpq documentation to get
the details about SNI.  Wouldn't is be better to have an item in the
glossary that refers to the bits of RFC 6066, and remove the reference
of the RPC from the libpq page?

I opted for a version with SNI in the glossary but without a link to the RFC
since no definitions in the glossary has ulinks.

-       to present a valid (trusted) SSL certificate, while
+       to present a valid (trusted) <acronym>SSL</acronym>/<acronym>TLS</acronym> certificate, while
This style with two acronyms for what we want to be one thing is
heavy.  Could it be better to just have one single acronym called
SSL/TLS that references both parts?

Maybe, I don't know. I certainly don't prefer the way which is in the patch
but I also think it's the most "correct" way so I opted for that to start the
discussion. If we're fine with one acronym tag for the combination then I'm
happy to change to that.

A slightly more invasive idea would be to not have acronyms at all and instead
move the ones that do benefit from clarification to the glossary? ISTM that
having a brief description of terms and not just the expansion is beneficial to
the users. That would however be for another thread, but perhaps thats worth
discussing?

Patch 0003, for the <productname> markups with OpenSSL, included one
SSL/TLS entry.

Ugh, sorry, that must've been a git add -p fat-finger.

--
Daniel Gustafsson https://vmware.com/

On Mon, Jun 21, 2021 at 01:23:56PM +0200, Daniel Gustafsson wrote:

On 18 Jun 2021, at 07:37, Michael Paquier <michael@paquier.xyz> wrote:

It looks inconsistent to me to point to the libpq documentation to get
the details about SNI. Wouldn't is be better to have an item in the
glossary that refers to the bits of RFC 6066, and remove the reference
of the RPC from the libpq page?

I opted for a version with SNI in the glossary but without a link to the RFC
since no definitions in the glossary has ulinks.

Okay, but why making all this complicated if it can be simple? If I
read the top of the page, the description of the glossary refers more
to terms that apply to PostgreSQL and RDBMs in general. I think that
something like the attached is actually more adapted, where there are
acronyms for SNI and MITM, and where the references we have in the
libpq docs are moved to the page for acronyms. That's consistent with
what we do now for the existing acronyms SSL and TLS, and there does
not seem to need any references to all those terms in the glossary.

-       to present a valid (trusted) SSL certificate, while
+       to present a valid (trusted) <acronym>SSL</acronym>/<acronym>TLS</acronym> certificate, while
This style with two acronyms for what we want to be one thing is
heavy.  Could it be better to just have one single acronym called
SSL/TLS that references both parts?

Maybe, I don't know. I certainly don't prefer the way which is in the patch
but I also think it's the most "correct" way so I opted for that to start the
discussion. If we're fine with one acronym tag for the combination then I'm
happy to change to that.

That feels a bit more natural to me to have SSL/TLS in the contexts
where they apply as a single keyword. Do we have actually sections in
the docs where only one of them apply, like some protocol references?

A slightly more invasive idea would be to not have acronyms at all and instead
move the ones that do benefit from clarification to the glossary? ISTM that
having a brief description of terms and not just the expansion is beneficial to
the users. That would however be for another thread, but perhaps thats worth
discussing?

Not sure about this bit. That's a more general topic for sure, but I
also like the separation we have not between the glossary and the
acronyms. Having an entry in one does not make necessary the same
entry in the other, and vice-versa.

Patch 0003, for the <productname> markups with OpenSSL, included one
SSL/TLS entry.

Ugh, sorry, that must've been a git add -p fat-finger.

The extra SSL/TLS entry was on one of the files changed f80979f, so
git add has been working just fine :)
--
Michael

On 22 Jun 2021, at 06:37, Michael Paquier <michael@paquier.xyz> wrote:

On Mon, Jun 21, 2021 at 01:23:56PM +0200, Daniel Gustafsson wrote:

On 18 Jun 2021, at 07:37, Michael Paquier <michael@paquier.xyz> wrote:

It looks inconsistent to me to point to the libpq documentation to get
the details about SNI. Wouldn't is be better to have an item in the
glossary that refers to the bits of RFC 6066, and remove the reference
of the RPC from the libpq page?

I opted for a version with SNI in the glossary but without a link to the RFC
since no definitions in the glossary has ulinks.

Okay, but why making all this complicated if it can be simple? If I
read the top of the page, the description of the glossary refers more
to terms that apply to PostgreSQL and RDBMs in general. I think that
something like the attached is actually more adapted, where there are
acronyms for SNI and MITM, and where the references we have in the
libpq docs are moved to the page for acronyms. That's consistent with
what we do now for the existing acronyms SSL and TLS, and there does
not seem to need any references to all those terms in the glossary.

The attached v3 does it this way.

-       to present a valid (trusted) SSL certificate, while
+       to present a valid (trusted) <acronym>SSL</acronym>/<acronym>TLS</acronym> certificate, while
This style with two acronyms for what we want to be one thing is
heavy.  Could it be better to just have one single acronym called
SSL/TLS that references both parts?

Maybe, I don't know. I certainly don't prefer the way which is in the patch
but I also think it's the most "correct" way so I opted for that to start the
discussion. If we're fine with one acronym tag for the combination then I'm
happy to change to that.

That feels a bit more natural to me to have SSL/TLS in the contexts
where they apply as a single keyword. Do we have actually sections in
the docs where only one of them apply, like some protocol references?

Yes, there are a few but not too many. Whenever the protocol is refererred to
and not the concept of an encrypted connection, just the applicable term is
used.

The attached v3 wraps SSL/TLS in a single acronym block, which for sure is more
pleasing to the eye when working with the docs, but I still have no idea which
version technically is the most correct.

A slightly more invasive idea would be to not have acronyms at all and instead
move the ones that do benefit from clarification to the glossary? ISTM that
having a brief description of terms and not just the expansion is beneficial to
the users. That would however be for another thread, but perhaps thats worth
discussing?

Not sure about this bit. That's a more general topic for sure, but I
also like the separation we have not between the glossary and the
acronyms. Having an entry in one does not make necessary the same
entry in the other, and vice-versa.

It doesn't, I'm just not convinced that the acronyms page is consulted all too
frequently anymore to provide much value. I might be totally wrong though.
Either way, thats (potentially) for a separate discussion.

--
Daniel Gustafsson https://vmware.com/

On Thu, Jun 24, 2021 at 01:53:47PM +0200, Daniel Gustafsson wrote:

The attached v3 does it this way.

Thanks. Mostly what was on message upthread. Applied this one.

Yes, there are a few but not too many. Whenever the protocol is refererred to
and not the concept of an encrypted connection, just the applicable term is
used.

Makes sense.

The attached v3 wraps SSL/TLS in a single acronym block, which for sure is more
pleasing to the eye when working with the docs, but I still have no idea which
version technically is the most correct.

I am not sure 100% sure, but I would still vote in favor of this
change, perhaps with a small addition of one extra entry for SSL/TLS
directly on the acronym's page for consistency. What you have here
sounds rather fine to me.

It doesn't, I'm just not convinced that the acronyms page is consulted all too
frequently anymore to provide much value. I might be totally wrong though.
Either way, thats (potentially) for a separate discussion.

No idea about that.
--
Michael

On 15.06.21 15:59, Daniel Gustafsson wrote:

Looking at the docs it turns out that we have a mix of SSL (with one ssl),
SSL/TLS and TLS for referring to the same thing. The attached changes the
documentation to consistently use SSL/TLS when referring to an encrypted
connection using a TLS protocol, leaving bare SSL and TLS only for referring to
the actual protocols. I*think* I found all instances, there are many so I
might have missed some, but this version seemed like a good place to continue
the discussion from the previous thread.

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. If we are
not, then saying SSL is enough.

I note that popular places such as the Apache and nginx SSL/TLS modules
just use SSL in their documentation, and they are probably under much
more scrutiny in this area. curl is a bit more inconsistent but also
generally just uses SSL. So it seems not a lot of people are really
bothered by this.

On Wed, 2021-06-30 at 20:20 +0200, Peter Eisentraut wrote:

I note that popular places such as the Apache and nginx SSL/TLS modules
just use SSL in their documentation, and they are probably under much
more scrutiny in this area.

For Apache, that's not strictly true [1, 2]. mod_ssl and its directive
names are probably a lost cause due to inertia, but the page titles
themselves have mostly changed to SSL/TLS.

httpd documentation is also less centrally directed than this project
is, in my experience -- if someone has the motivation to change things,
they'll be changed; otherwise, the status quo rules.

--Jacob

[1]: https://httpd.apache.org/docs/2.4/ssl/
[2]: https://httpd.apache.org/docs/2.4/ssl/ssl_intro.html

On 30 Jun 2021, at 20:20, Peter Eisentraut <peter.eisentraut@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.

If we are not, then saying SSL is enough.

I think consistency is the interesting aspect here. We already have a mix of
SSL, TLS and SSL/TLS (although heavily skewed towards SSL) so we should settle
on one and stick to it. The arguments in the NSS thread which led to this
pointed to SSL/TLS. If we feel that the churn isn't worth it, then we should
change all to SSL and perhaps instead just add TLS as indexterms to those
sections.

--
Daniel Gustafsson https://vmware.com/

On Wed, Jun 30, 2021, at 5:46 PM, Daniel Gustafsson wrote:

On 30 Jun 2021, at 20:20, Peter Eisentraut <peter.eisentraut@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]https://datatracker.ietf.org/doc/html/rfc7568. 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://datatracker.ietf.org/doc/html/rfc7568
[1]: https://datatracker.ietf.org/doc/html/rfc7568

--
Euler Taveira
EDB https://www.enterprisedb.com/

On 30.06.21 20:43, Jacob Champion wrote:

On Wed, 2021-06-30 at 20:20 +0200, Peter Eisentraut wrote:

I note that popular places such as the Apache and nginx SSL/TLS modules
just use SSL in their documentation, and they are probably under much
more scrutiny in this area.

For Apache, that's not strictly true [1, 2]. mod_ssl and its directive
names are probably a lost cause due to inertia, but the page titles
themselves have mostly changed to SSL/TLS.

[1] https://httpd.apache.org/docs/2.4/ssl/
[2] https://httpd.apache.org/docs/2.4/ssl/ssl_intro.html

That page entirely supports my point: It uses "SSL" throughout, except
in the title and where it talks about the specific protocol names.

On 30.06.21 22:46, Daniel Gustafsson wrote:

I think consistency is the interesting aspect here. We already have a mix of
SSL, TLS and SSL/TLS (although heavily skewed towards SSL) so we should settle
on one and stick to it. The arguments in the NSS thread which led to this
pointed to SSL/TLS. If we feel that the churn isn't worth it, then we should
change all to SSL and perhaps instead just add TLS as indexterms to those
sections.

I think it is already consistent in that it uses "SSL". Is that not the
case?

I notice that the NSS documentation also uses "SSL" almost exclusively
when referring to the SSL and TLS protocols and related APIs.

On 1 Jul 2021, at 22:40, Peter Eisentraut <peter.eisentraut@enterprisedb.com> wrote:

On 30.06.21 22:46, Daniel Gustafsson wrote:

I think consistency is the interesting aspect here. We already have a mix of
SSL, TLS and SSL/TLS (although heavily skewed towards SSL) so we should settle
on one and stick to it. The arguments in the NSS thread which led to this
pointed to SSL/TLS. If we feel that the churn isn't worth it, then we should
change all to SSL and perhaps instead just add TLS as indexterms to those
sections.

I think it is already consistent in that it uses "SSL". Is that not the case?

Almost, but not entirely, and if we want to settle on a single term now is a
good time before it diverges too far.

I notice that the NSS documentation also uses "SSL" almost exclusively when referring to the SSL and TLS protocols and related APIs.

To be fair, the NSS documentation has more or less not seen updates at all in
years, large parts of the API are completely missing.

The best maintained TLS library documentation today is, I would argue, OpenSSL
and grepping around there (unscientifially) looks a bit different:

SSL: 177 (corrected for not counting the SSL struct)
SSL/TLS (or TLS/SSL): 154
TLS: 252

This patch came about since there was an ask over in the NSS thread to top
using SSL as a term, but if there isn't enough support to warrant the churn
then we should standardize on SSL and just include a paragraph explaining what
we mean by that.

--
Daniel Gustafsson https://vmware.com/

Since the approach taken wasn't to anyones liking, attached is a v4 (partly
extracted from the previous patch) which only adds notes that SSL is used
interchangeably with TLS in our documentation and configuration.

--
Daniel Gustafsson https://vmware.com/

On Wed, Sep 15, 2021 at 8:47 AM Daniel Gustafsson <daniel@yesql.se> wrote:

Since the approach taken wasn't to anyones liking, attached is a v4 (partly
extracted from the previous patch) which only adds notes that SSL is used
interchangeably with TLS in our documentation and configuration.

I have actually been wondering why we have been insisting on calling
it SSL when it clearly is not. However, if we're not ready/willing to
make a bigger change, then doing as you have proposed here seems fine
to me.

--
Robert Haas
EDB: http://www.enterprisedb.com

On 25 Mar 2022, at 20:58, Robert Haas <robertmhaas@gmail.com> wrote:

On Wed, Sep 15, 2021 at 8:47 AM Daniel Gustafsson <daniel@yesql.se> wrote:

Since the approach taken wasn't to anyones liking, attached is a v4 (partly
extracted from the previous patch) which only adds notes that SSL is used
interchangeably with TLS in our documentation and configuration.

I have actually been wondering why we have been insisting on calling
it SSL when it clearly is not.

SSL has become the de facto term for a network channel encryption regardless of
actual protocol used. Few use TLS, with most SSL/TLS is

However, if we're not ready/willing to make a bigger change, then doing as you
have proposed here seems fine to me.

Thanks for review! Trying out again just now the patch still applies (with
some offsets) and builds.

--
Daniel Gustafsson https://vmware.com/

On 25 Mar 2022, at 22:01, Daniel Gustafsson <daniel@yesql.se> wrote:

On 25 Mar 2022, at 20:58, Robert Haas <robertmhaas@gmail.com> wrote:

However, if we're not ready/willing to make a bigger change, then doing as you
have proposed here seems fine to me.

Thanks for review! Trying out again just now the patch still applies (with
some offsets) and builds.

Barring objections I will go ahead and push this for 15. It's the minimal
change but it might still help someone new to PostgreSQL who gets confused on
the choice of naming/wording.

--
Daniel Gustafsson https://vmware.com/

On 28 Mar 2022, at 23:51, Daniel Gustafsson <daniel@yesql.se> wrote:

Barring objections I will go ahead and push this for 15. It's the minimal
change but it might still help someone new to PostgreSQL who gets confused on
the choice of naming/wording.

Hearing no objections I went ahead with this now.

--
Daniel Gustafsson https://vmware.com/