doc: Expand user documentation on SCRAM

Explain more about how the different password authentication methods and
the password_encryption settings relate to each other, give some
upgrading advice, and set a better link from the release notes.

Reviewed-by: Jeff Janes 

diff --git a/doc/src/sgml/client-auth.sgml b/doc/src/sgml/client-auth.sgml
index 1b568683a4733f80314015e434a7a282b4bb98f3..c4d4f1e80fc0dba66b9217cc8ee2e12620c439de 100644 (file)
--- a/doc/src/sgml/client-auth.sgml
+++ b/doc/src/sgml/client-auth.sgml
@@ -916,46 +916,82 @@ omicron         bryanh                  guest1
    
     MD5
    
+   
+    SCRAM
+   
    
     password
     authentication
    
 
    
-    The password-based authentication methods are scram-sha-256,
-    md5, and password. These methods operate
-    similarly except for the way that the password is sent across the
+    There are several password-based authentication methods.  These methods
+    operate similarly but differ in how the users' passwords are stored on the
+    server and how the password provided by a client is sent across the
     connection.
    
 
-   
-    Plain password sends the password in clear-text, and is
-    therefore vulnerable to password sniffing attacks. It should
-    always be avoided if possible. If the connection is protected by SSL
-    encryption then password can be used safely, though.
-    (Though SSL certificate authentication might be a better choice if one
-    is depending on using SSL).
-   
+   
+    
+     scram-sha-256
+     
+      
+       The method scram-sha-256 performs SCRAM-SHA-256
+       authentication, as described in
+       RFC 7677.  It
+       is a challenge-response scheme that prevents password sniffing on
+       untrusted connections and supports storing passwords on the server in a
+       cryptographically hashed form that is thought to be secure.
+      
 
+      
+       This is the most secure of the currently provided methods, but it is
+       not supported by older client libraries.
+      
+     
+    
 
-   
-    scram-sha-256 performs SCRAM-SHA-256 authentication, as
-    described in
-    RFC 7677. It
-    is a challenge-response scheme, that prevents password sniffing on
-    untrusted connections. It is more secure than the md5
-    method, but might not be supported by older clients.
-   
+    
+     md5
+     
+      
+       The method md5 uses a custom less secure challenge-response
+       mechanism.  It prevents password sniffing and avoids storing passwords
+       on the server in plain text but provides no protection if an attacker
+       manages to steal the password hash from the server.  Also, the MD5 hash
+       algorithm is nowadays no longer consider secure against determined
+       attacks.
+      
 
-   
-    md5 allows falling back to a less secure challenge-response
-    mechanism for those users with an MD5 hashed password.
-    The fallback mechanism also prevents password sniffing, but provides no
-    protection if an attacker manages to steal the password hash from the
-    server, and it cannot be used with the 
-    linkend="guc-db-user-namespace"> feature. For all other users,
-    md5 works the same as scram-sha-256.
-   
+      
+       The md5 method cannot be used with
+       the  feature.
+      
+
+      
+       To ease transition from the md5 method to the newer
+       SCRAM method, if md5 is specified as a method
+       in pg_hba.conf but the user's password on the
+       server is encrypted for SCRAM (see below), then SCRAM-based
+       authentication will automatically be chosen instead.
+      
+     
+    
+
+    
+     password
+     
+      
+       The method password sends the password in clear-text and is
+       therefore vulnerable to password sniffing attacks. It should
+       always be avoided if possible. If the connection is protected by SSL
+       encryption then password can be used safely, though.
+       (Though SSL certificate authentication might be a better choice if one
+       is depending on using SSL).
+      
+     
+    
+   
 
    
     PostgreSQL database passwords are
@@ -964,11 +1000,44 @@ omicron         bryanh                  guest1
     catalog. Passwords can be managed with the SQL commands
      and
     ,
-    e.g., CREATE USER foo WITH PASSWORD 'secret'.
+    e.g., CREATE USER foo WITH PASSWORD 'secret',
+    or the psql
+    command \password.
     If no password has been set up for a user, the stored password
     is null and password authentication will always fail for that user.
    
 
+   
+    The availability of the different password-based authentication methods
+    depends on how a user's password on the server is encrypted (or hashed,
+    more accurately).  This is controlled by the configuration
+    parameter  at the time the
+    password is set.  If a password was encrypted using
+    the scram-sha-256 setting, then it can be used for the
+    authentication methods scram-sha-256
+    and password (but password transmission will be in
+    plain text in the latter case).  The authentication method
+    specification md5 will automatically switch to using
+    the scram-sha-256 method in this case, as explained
+    above, so it will also work.  If a password was encrypted using
+    the md5 setting, then it can be used only for
+    the md5 and password authentication
+    method specifications (again, with the password transmitted in plain text
+    in the latter case).  (Previous PostgreSQL releases supported storing the
+    password on the server in plain text.  This is no longer possible.)  To
+    check the currently stored password hashes, see the system
+    catalog pg_authid.
+   
+
+   
+    To upgrade an existing installation from md5
+    to scram-sha-256, after having ensured that all client
+    libraries in use are new enough to support SCRAM,
+    set password_encryption = 'scram-sha-256'
+    in postgresql.conf, make all users set new passwords,
+    and change the authentication method specifications
+    in pg_hba.conf to scram-sha-256.
+   
   
 
   


diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml

index 2b6255ed95adabb1645e291079b7673831d6e8c0..a051724d1c82fef8d618b62cdb9522163aedc672 100644 (file)

--- a/doc/src/sgml/config.sgml
+++ b/doc/src/sgml/config.sgml
@@ -1198,7 +1198,7 @@ include_dir 'conf.d'
        
         Note that older clients might lack support for the SCRAM authentication
         mechanism, and hence not work with passwords encrypted with
-        SCRAM-SHA-256.
+        SCRAM-SHA-256.  See  for more details.
        
       
      


diff --git a/doc/src/sgml/release-10.sgml b/doc/src/sgml/release-10.sgml

index 2658b73ca65315e5195707888bb7143583afbb07..9fd3b2c8ac60c0afece2f6ab4e68df6b87499d16 100644 (file)

--- a/doc/src/sgml/release-10.sgml
+++ b/doc/src/sgml/release-10.sgml
@@ -1184,7 +1184,7 @@
 2017-04-18 [c727f120f] Rename "scram" to "scram-sha-256" in pg_hba.conf and pas
 -->
        
-        Add g-hba-conf">SCRAM-SHA-256
+        Add assword">SCRAM-SHA-256
         support for password negotiation and storage (Michael Paquier,
         Heikki Linnakangas)
       

diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml
index 2b6255ed95adabb1645e291079b7673831d6e8c0..a051724d1c82fef8d618b62cdb9522163aedc672 100644 (file)
--- a/doc/src/sgml/config.sgml
+++ b/doc/src/sgml/config.sgml
@@ -1198,7 +1198,7 @@ include_dir 'conf.d'
        
         Note that older clients might lack support for the SCRAM authentication
         mechanism, and hence not work with passwords encrypted with
-        SCRAM-SHA-256.
+        SCRAM-SHA-256.  See  for more details.
        
       
      

diff --git a/doc/src/sgml/release-10.sgml b/doc/src/sgml/release-10.sgml
index 2658b73ca65315e5195707888bb7143583afbb07..9fd3b2c8ac60c0afece2f6ab4e68df6b87499d16 100644 (file)
--- a/doc/src/sgml/release-10.sgml
+++ b/doc/src/sgml/release-10.sgml
@@ -1184,7 +1184,7 @@
 2017-04-18 [c727f120f] Rename "scram" to "scram-sha-256" in pg_hba.conf and pas
 -->
        
-        Add g-hba-conf">SCRAM-SHA-256
+        Add assword">SCRAM-SHA-256
         support for password negotiation and storage (Michael Paquier,
         Heikki Linnakangas)