Horton

Thread

Commits

  1. doc: Clarify when SSL actually means TLS

  2. doc: Add acronyms for MITM and SNI

  3. doc: Apply markup <productname> to OpenSSL more consistently

  4. Introduce --with-ssl={openssl} as a configure option

  1. SSL/TLS instead of SSL in docs

    Daniel Gustafsson <daniel@yesql.se> — 2021-06-15T13:59:18Z

    In the NSS thread it was discussed (20210603210642.GF22012@momjian.us etc) that
we use SSL rather than TLS in the documentation, which is technically somewhat
incorrect.  Consensus came to using SSL/TLS instead for referring to encrypted
connections.  Since this isn't really limited to the NSS work, I'm breaking
this out into a new thread.

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.

Admittedly it gets pretty unwieldy with the <acronym /> markup on SSL and TLS
but I opted for being consistent, since I don't know of any rules for when it
can/should be omitted (and it seems quite arbitrary right now).  Mentions in
titles were previously not marked up so I've left those as is.  I've also left
line breaks as an excercise for later to make the diff more readable.

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.

Thoughts?

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

  2. Re: SSL/TLS instead of SSL in docs

    Michael Paquier <michael@paquier.xyz> — 2021-06-18T05:37:32Z

    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

  3. Re: SSL/TLS instead of SSL in docs

    Daniel Gustafsson <daniel@yesql.se> — 2021-06-21T11:23:56Z

    > 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/

  4. Re: SSL/TLS instead of SSL in docs

    Michael Paquier <michael@paquier.xyz> — 2021-06-22T04:37:45Z

    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

  5. Re: SSL/TLS instead of SSL in docs

    Daniel Gustafsson <daniel@yesql.se> — 2021-06-24T11:53:47Z

    > 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/

  6. Re: SSL/TLS instead of SSL in docs

    Michael Paquier <michael@paquier.xyz> — 2021-06-25T02:45:44Z

    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

  7. Re: SSL/TLS instead of SSL in docs

    Peter Eisentraut <peter.eisentraut@enterprisedb.com> — 2021-06-30T18:20:50Z

    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.

  8. Re: SSL/TLS instead of SSL in docs

    Jacob Champion <pchampion@vmware.com> — 2021-06-30T18:43:09Z

    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

  9. Re: SSL/TLS instead of SSL in docs

    Daniel Gustafsson <daniel@yesql.se> — 2021-06-30T20:46:37Z

    > 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/

  10. Re: SSL/TLS instead of SSL in docs

    Euler Taveira <euler@eulerto.com> — 2021-07-01T16:01:52Z

    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]. 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/

  11. Re: SSL/TLS instead of SSL in docs

    Peter Eisentraut <peter.eisentraut@enterprisedb.com> — 2021-07-01T20:26:55Z

    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.

  12. Re: SSL/TLS instead of SSL in docs

    Peter Eisentraut <peter.eisentraut@enterprisedb.com> — 2021-07-01T20:40:25Z

    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.

  13. Re: SSL/TLS instead of SSL in docs

    Daniel Gustafsson <daniel@yesql.se> — 2021-07-01T21:40:27Z

    > 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/

  14. Re: SSL/TLS instead of SSL in docs

    Daniel Gustafsson <daniel@yesql.se> — 2021-09-15T12:47:11Z

    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/

  15. Re: SSL/TLS instead of SSL in docs

    Robert Haas <robertmhaas@gmail.com> — 2022-03-25T19:58:02Z

    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

  16. Re: SSL/TLS instead of SSL in docs

    Daniel Gustafsson <daniel@yesql.se> — 2022-03-25T21:01:01Z

    > 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/

  17. Re: SSL/TLS instead of SSL in docs

    Daniel Gustafsson <daniel@yesql.se> — 2022-03-28T21:51:30Z

    > 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/

  18. Re: SSL/TLS instead of SSL in docs

    Daniel Gustafsson <daniel@yesql.se> — 2022-03-30T11:43:54Z

    > 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/