Subject: Update encryption options doc for SCRAM-SHA-256

From: PG Doc comments form <[email-masked]>
Date: Fri, 02 Feb 2018 23:42:35 +0000

The following documentation comment has been logged on the website:

Page: https://www.postgresql.org/docs/10/static/encryption-options.html
Description:

Section "18.8. Encryption Options" only mentions MD5 as the password storage
encryption mechanism, although PostgreSQL 10 introduced the superior SHA256
- somebody looking at the docs would get a bad idea of PostgreSQL's
capabilities...

---

From: Peter Eisentraut <[email-masked]>
Date: Sat, 3 Feb 2018 11:30:51 -0500

> - somebody looking at the docs would get a bad idea of PostgreSQL's

I propose the attached patch.  I have combined the password storage and
password transmission items, because I don't want to go into the details
of how SCRAM works on the wire.

-- 
Peter Eisentraut              http://www.2ndQuadrant.com/
PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services
From 34eff9bd65ca051c3ba173476e3f9360ee0d51b9 Mon Sep 17 00:00:00 2001
From: Peter Eisentraut <[email-masked]>
Date: Sat, 3 Feb 2018 11:29:23 -0500
Subject: [PATCH] doc: Update mentions of MD5 in the documentation

---
 doc/src/sgml/runtime.sgml | 34 +++++++++-------------------------
 1 file changed, 9 insertions(+), 25 deletions(-)

diff --git a/doc/src/sgml/runtime.sgml b/doc/src/sgml/runtime.sgml
index d162acb2e8..71f02300c2 100644
--- a/doc/src/sgml/runtime.sgml
+++ b/doc/src/sgml/runtime.sgml
@@ -2023,16 +2023,18 @@ <title>Encryption Options</title>
   <variablelist>
 
   <varlistentry>
-   <term>Password Storage Encryption</term>
+   <term>Password Encryption</term>
    <listitem>
 
     <para>
-     By default, database user passwords are stored as MD5 hashes, so
-     the administrator cannot determine the actual password assigned
-     to the user. If MD5 encryption is used for client authentication,
-     the unencrypted password is never even temporarily present on the
-     server because the client MD5-encrypts it before being sent
-     across the network.
+     Database user passwords are stored as hashes (determined by the setting
+     <xref linkend="guc-password-encryption"/>), so the administrator cannot
+     determine the actual password assigned to the user. If SCRAM or MD5
+     encryption is used for client authentication, the unencrypted password is
+     never even temporarily present on the server because the client encrypts
+     it before being sent across the network. SCRAM is preferred, because it
+     is an Internet standard and is more secure than the PostgreSQL-specific
+     MD5 authentication protocol.
     </para>
    </listitem>
   </varlistentry>
@@ -2086,24 +2088,6 @@ <title>Encryption Options</title>
    </listitem>
   </varlistentry>
 
-  <varlistentry>
-   <term>Encrypting Passwords Across A Network</term>
-
-   <listitem>
-     <para>
-      The <literal>MD5</literal> authentication method double-encrypts the
-      password on the client before sending it to the server. It first
-      MD5-encrypts it based on the user name, and then encrypts it
-      based on a random salt sent by the server when the database
-      connection was made. It is this double-encrypted value that is
-      sent over the network to the server. Double-encryption not only
-      prevents the password from being discovered, it also prevents
-      another connection from using the same encrypted password to
-      connect to the database server at a later time.
-     </para>
-    </listitem>
-  </varlistentry>
-
   <varlistentry>
    <term>Encrypting Data Across A Network</term>
 
-- 
2.16.1

---

From: Shay Rojansky <[email-masked]>
Date: Sat, 3 Feb 2018 09:55:59 -0800

Thanks for your attention to this.

I'm definitely not a cryptography expert, but it seems to me that the
actual mechanisms (MD5, SHA-256) are more important than the protocols used
to negotiate them (SASL, SCRAM). When some security expert unfamiliar with
PostgreSQL goes over itss documentation to determine whether it's secure, I
think it's important to make sure that the word SHA-256 is actually there.