Partial port of 0007 patch (sgml only)

afiskon · afiskon · commit a338a0d812b9 · 2016-12-01T19:16:56.000+03:00
diff --git a/doc/src/sgml/catalogs.sgml b/doc/src/sgml/catalogs.sgml
@@ -1310,13 +1310,18 @@
       <entry><type>text</type></entry>
       <entry>
        Password (possibly encrypted); null if none.  If the password
-       is encrypted, this column will begin with the string <literal>md5</>
-       followed by a 32-character hexadecimal MD5 hash.  The MD5 hash
-       will be of the user's password concatenated to their user name.
-       For example, if user <literal>joe</> has password <literal>xyzzy</>,
-       <productname>&productname;</> will store the md5 hash of
-       <literal>xyzzyjoe</>.  A password that does not follow that
-       format is assumed to be unencrypted.
+       is encrypted with MD5, this column will begin with the string
+       <literal>md5</> followed by a 32-character hexadecimal MD5 hash.
+       The MD5 hash will be of the user's password concatenated to their
+       user name. For example, if user <literal>joe</> has password
+       <literal>xyzzy</>, <productname>PostgreSQL</> will store the md5
+       hash of <literal>xyzzyjoe</>.  If the password is encrypted with
+       SCRAM-SHA-256, it is built with 4 fields separated by a colon. The
+       first field is a salt encoded in base-64.  The second field is the
+       number of iterations used to generate the password.  The third field
+       is a stored key, encoded in hexadecimal.  The fourth field is a
+       server key encoded in hexadecimal.  A password that does not follow
+       any of those formats is assumed to be unencrypted.
       </entry>
      </row>
 
diff --git a/doc/src/sgml/client-auth.sgml b/doc/src/sgml/client-auth.sgml
@@ -420,6 +420,17 @@ hostnossl  <replaceable>database</replaceable>  <replaceable>user</replaceable>
         </listitem>
        </varlistentry>
 
+       <varlistentry>
+        <term><literal>scram</></term>
+        <listitem>
+         <para>
+          Require the client to supply a password encrypted with
+          SCRAM-SHA-256 for authentication.
+          See <xref linkend="auth-password"> for details.
+         </para>
+        </listitem>
+       </varlistentry>
+
        <varlistentry>
         <term><literal>password</></term>
         <listitem>
@@ -904,6 +915,17 @@ omicron         bryanh                  guest1
     choice if one is depending on using SSL).
    </para>
 
+   <para>
+    <literal>scram</> has more advantages than <literal>md5</> as it
+    protects from cases where the hashed password is taken directly from
+    <structname>pg_authid</structname> in which case a connection using
+    only the stolen hash is possible without knowing the password behind
+    it.  It protects as well from password interception and data sniffing
+    where the password data could be directly obtained from the network
+    as well as man-in-the-middle (MITM) attacks.  So it is strongly
+    encouraged to use it over <literal>md5</> for password-based deployments.
+   </para>
+
    <para>
     <productname>&productname;</productname> database passwords are
     separate from operating system user passwords. The password for
diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml
@@ -1254,7 +1254,7 @@ include_dir 'conf.d'
         Authentication checks are always done with the server's user name
         so authentication methods must be configured for the
         server's user name, not the client's.  Because
-        <literal>md5</> uses the user name as salt on both the
+        <literal>md5</>uses the user name as salt on both the
         client and server, and <literal>scram</> uses the user name as
         a portion of the salt used on both the client and server,
         <literal>md5</> and <literal>scram</> cannot be used with
