On Mon, Jun 21, 2021 at 01:23:56PM +0200, Daniel Gustafsson wrote: > On 18 Jun 2021, at 07:37, Michael Paquier <mich...@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
diff --git a/doc/src/sgml/acronyms.sgml b/doc/src/sgml/acronyms.sgml
index 13bd819eb1..658000b29c 100644
--- a/doc/src/sgml/acronyms.sgml
+++ b/doc/src/sgml/acronyms.sgml
@@ -410,6 +410,17 @@
</listitem>
</varlistentry>
+ <varlistentry>
+ <term><acronym>MITM</acronym></term>
+ <listitem>
+ <para>
+ <ulink
+ url="https://en.wikipedia.org/wiki/Man-in-the-middle_attack";>
+ Man-in-the-middle</ulink>
+ </para>
+ </listitem>
+ </varlistentry>
+
<varlistentry>
<term><acronym>MSVC</acronym></term>
<listitem>
@@ -590,6 +601,18 @@
</listitem>
</varlistentry>
+ <varlistentry>
+ <term><acronym>SNI</acronym></term>
+ <listitem>
+ <para>
+ <ulink
+ 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>
+ </listitem>
+ </varlistentry>
+
<varlistentry>
<term><acronym>SPI</acronym></term>
<listitem>
diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml
index eeba2caa43..f82ae4e461 100644
--- a/doc/src/sgml/config.sgml
+++ b/doc/src/sgml/config.sgml
@@ -1378,7 +1378,7 @@ include_dir 'conf.d'
<listitem>
<para>
Disables anonymous cipher suites that do no authentication. Such
- cipher suites are vulnerable to man-in-the-middle attacks and
+ cipher suites are vulnerable to <acronym>MITM</acronym> attacks and
therefore should not be used.
</para>
</listitem>
diff --git a/doc/src/sgml/libpq.sgml b/doc/src/sgml/libpq.sgml
index 441cc0da3a..641970f2a6 100644
--- a/doc/src/sgml/libpq.sgml
+++ b/doc/src/sgml/libpq.sgml
@@ -1783,18 +1783,17 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname
<listitem>
<para>
By default, libpq sets the TLS extension <quote>Server Name
- Indication</quote> (SNI) on SSL-enabled connections. See <ulink
- url="https://tools.ietf.org/html/rfc6066#section-3";>RFC 6066</ulink>
- for details. By setting this parameter to 0, this is turned off.
+ Indication</quote> (<acronym>SNI</acronym>) on SSL-enabled connections.
+ By setting this parameter to 0, 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
requires a proxy that is aware of the PostgreSQL protocol handshake,
- not just any SSL proxy.) However, SNI makes the destination host name
- appear in cleartext in the network traffic, so it might be undesirable
- in some cases.
+ 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.
</para>
</listitem>
</varlistentry>
@@ -8430,7 +8429,7 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*)
</varlistentry>
<varlistentry>
- <term>Man in the middle (<acronym>MITM</acronym>)</term>
+ <term>Man-in-the-middle (<acronym>MITM</acronym>)</term>
<listitem>
<para>If a third party can modify the data while passing between the
client and server, it can pretend to be the server and therefore see and
signature.asc
Description: PGP signature
