Thread: SSL/TLS instead of SSL in docs
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/
Attachment
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
Attachment
> 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/
Attachment
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
Attachment
> 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/
Attachment
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
Attachment
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 worriedabout 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" fordescribing 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.
Attachment
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 andrelated 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/
Attachment
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/