On 9/19/17 20:45, Peter Eisentraut wrote: > On 9/19/17 17:55, Jeff Janes wrote: >> I guess I'm late to the party, but I don't see why this is needed at >> all. We encourage people to use any and all new features which are >> appropriate to them--that is why we implement new features. Why does >> this feature need a special invitation? > > It's not clear to me how an average user would get from the press > release or release notes to upgrading their installation to use > SCRAM-based authentication and passwords. A little bit more guidance > somewhere would be helpful.
Here is a patch that expands the SCRAM documentation a bit, adds more explanation how the different options are related, and sets some better links. I think now you can get from the release notes to the relevant documentation and have enough information on how to put the new features into use. -- Peter Eisentraut http://www.2ndQuadrant.com/ PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services
From 2e7640d9a6d65664721fff8d4acdd3c9289027b0 Mon Sep 17 00:00:00 2001 From: Peter Eisentraut <pete...@gmx.net> 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 @@ <title>Password Authentication</title> <indexterm> <primary>MD5</> </indexterm> + <indexterm> + <primary>SCRAM</> + </indexterm> <indexterm> <primary>password</primary> <secondary>authentication</secondary> </indexterm> <para> - The password-based authentication methods are <literal>scram-sha-256</>, - <literal>md5</>, and <literal>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. </para> - <para> - Plain <literal>password</> sends the password in clear-text, and is - therefore vulnerable to password <quote>sniffing</> attacks. It should - always be avoided if possible. If the connection is protected by SSL - encryption then <literal>password</> can be used safely, though. - (Though SSL certificate authentication might be a better choice if one - is depending on using SSL). - </para> + <variablelist> + <varlistentry> + <term><literal>scram-sha-256</literal></term> + <listitem> + <para> + The method <literal>scram-sha-256</> performs SCRAM-SHA-256 + authentication, as described in + <ulink url="https://tools.ietf.org/html/rfc7677">RFC 7677</ulink>. 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. + </para> + <para> + This is the most secure of the currently provided methods but might not + be supported by older client libraries. + </para> + </listitem> + </varlistentry> - <para> - <literal>scram-sha-256</> performs SCRAM-SHA-256 authentication, as - described in - <ulink url="https://tools.ietf.org/html/rfc7677">RFC 7677</ulink>. It - is a challenge-response scheme, that prevents password sniffing on - untrusted connections. It is more secure than the <literal>md5</> - method, but might not be supported by older clients. - </para> + <varlistentry> + <term><literal>md5</literal></term> + <listitem> + <para> + The method <literal>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 <literal>md5</literal> method cannot be used with + the <xref linkend="guc-db-user-namespace"> feature. + </para> - <para> - <literal>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 <xref - linkend="guc-db-user-namespace"> feature. For all other users, - <literal>md5</> works the same as <literal>scram-sha-256</>. - </para> + <para> + To ease transition from the <literal>md5</literal> method to the newer + SCRAM method, if <literal>md5</literal> is specified as a method + in <filename>pg_hba.conf</filename> but the user's password in the + server is encrypted for SCRAM (see below), then SCRAM-based + authentication will automatically be chosen instead. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>password</literal></term> + <listitem> + <para> + The method <literal>password</> sends the password in clear-text, and + is therefore vulnerable to password <quote>sniffing</> attacks. It + should always be avoided if possible. If the connection is protected by + SSL encryption then <literal>password</> can be used safely, though. + (Though SSL certificate authentication might be a better choice if one + is depending on using SSL). + </para> + </listitem> + </varlistentry> + </variablelist> <para> <productname>PostgreSQL</productname> database passwords are @@ -964,11 +996,43 @@ <title>Password Authentication</title> catalog. Passwords can be managed with the SQL commands <xref linkend="sql-createuser"> and <xref linkend="sql-alterrole">, - e.g., <userinput>CREATE USER foo WITH PASSWORD 'secret'</userinput>. + e.g., <userinput>CREATE USER foo WITH PASSWORD 'secret'</userinput>, + or the <application>psql</application> + command <literal>\password</literal>. If no password has been set up for a user, the stored password is null and password authentication will always fail for that user. </para> + <para> + 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 <xref linkend="guc-password-encryption"> at the time the + password is set. If a password was encrypted using + the <literal>scram-sha-256</literal> setting, then it can be used for the + authentication methods <literal>scram-sha-256</literal> + and <literal>password</literal> (but password transmission will be in + plain text in the latter case). The authentication method + specification <literal>md5</literal> will automatically switch to using + the <literal>scram-sha-256</literal> method in this case, as explained + above, so it will also work in this case. If a password was encrypted + using the <literal>md5</literal> setting, then it can be used only for + the <literal>md5</literal> and <literal>password</literal> 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 <literal>pg_authid</literal>. + </para> + + <para> + To upgrade an existing installation from <literal>md5</literal> + to <literal>scram-sha-256</literal>, set <literal>password_encryption = + 'scram-sha-256'</literal> in <filename>postgresql.conf</filename>, make + all users set new passwords, and change the authentication method + specifications in <filename>pg_hba.conf</filename> + to <literal>scram-sha-256</literal>. + </para> </sect2> <sect2 id="gssapi-auth"> 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 @@ <title>Security and Authentication</title> <para> 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 <xref linkend="auth-password"> for more details. </para> </listitem> </varlistentry> 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 @@ <title><acronym>Authentication</></title> 2017-04-18 [c727f120f] Rename "scram" to "scram-sha-256" in pg_hba.conf and pas --> <para> - Add <link linkend="auth-pg-hba-conf"><literal>SCRAM-SHA-256</></> + Add <link linkend="auth-password"><literal>SCRAM-SHA-256</></> support for password negotiation and storage (Michael Paquier, Heikki Linnakangas) </para> -- 2.14.1
-- Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org) To make changes to your subscription: http://www.postgresql.org/mailpref/pgsql-hackers