diff --git a/doc/src/sgml/client-auth.sgml b/doc/src/sgml/client-auth.sgml index 26c3d1242ba..c76d5faf445 100644 --- 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 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 5f59a382f18..4b265d9e40c 100644 --- a/doc/src/sgml/config.sgml +++ b/doc/src/sgml/config.sgml @@ -1190,7 +1190,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 2658b73ca65..9fd3b2c8ac6 100644 --- 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 SCRAM-SHA-256 + Add SCRAM-SHA-256 support for password negotiation and storage (Michael Paquier, Heikki Linnakangas)