From 2e7640d9a6d65664721fff8d4acdd3c9289027b0 Mon Sep 17 00:00:00 2001 From: Peter Eisentraut Date: Thu, 21 Sep 2017 10:33:09 -0400 Subject: [PATCH] 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. --- doc/src/sgml/client-auth.sgml | 122 ++++++++++++++++++++++++++++++++---------- doc/src/sgml/config.sgml | 2 +- doc/src/sgml/release-10.sgml | 2 +- 3 files changed, 95 insertions(+), 31 deletions(-) diff --git a/doc/src/sgml/client-auth.sgml b/doc/src/sgml/client-auth.sgml index 1b568683a4..f2f7527107 100644 --- a/doc/src/sgml/client-auth.sgml +++ b/doc/src/sgml/client-auth.sgml @@ -916,46 +916,78 @@ Password Authentication 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 might not + be 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. The md5 method cannot be used with + the feature. + - - 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 feature. For all other users, - md5 works the same as scram-sha-256. - + + 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 in 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 +996,43 @@ Password Authentication 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 in 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 in this case. 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, 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 2b6255ed95..a051724d1c 100644 --- a/doc/src/sgml/config.sgml +++ b/doc/src/sgml/config.sgml @@ -1198,7 +1198,7 @@ Security and Authentication 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 2658b73ca6..98912ab3a2 100644 --- a/doc/src/sgml/release-10.sgml +++ b/doc/src/sgml/release-10.sgml @@ -1184,7 +1184,7 @@ <acronym>Authentication</> 2017-04-18 [c727f120f] Rename "scram" to "scram-sha-256" in pg_hba.conf and pas --> - Add SCRAM-SHA-256 + Add SCRAM-SHA-256 support for password negotiation and storage (Michael Paquier, Heikki Linnakangas) -- 2.14.1