8000 doc: Expand user documentation on SCRAM · postgres/postgres@9b31c72 · GitHub
[go: up one dir, main page]
Skip to content

Commit 9b31c72

Browse files
peterepetere
committed
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 <jeff.janes@gmail.com>
1 parent 74ca8f9 commit 9b31c72

File tree

3 files changed

+100
-31
lines changed

3 files changed

+100
-31
lines changed

‎doc/src/sgml/client-auth.sgml

Lines changed: 98 additions & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -916,46 +916,82 @@ omicron bryanh guest1
916916
<indexterm>
917917
<primary>MD5</>
918918
</indexterm>
919+
<indexterm>
920+
<primary>SCRAM</>
921+
</indexterm>
919922
<indexterm>
920923
<primary>password</primary>
921924
<secondary>authentication</secondary>
922925
</indexterm>
923926

924927
<para>
925-
The password-based authentication methods are <literal>scram-sha-256</>,
926-
<literal>md5</>, and <literal>password</>. These methods operate
927-
similarly except for the way that the password is sent across the
928+
There are several password-based authentication methods. These methods
929+
operate similarly but differ in how the users' passwords are stored on the
930+
server and how the password provided by a client is sent across the
928931
connection.
929932
</para>
930933

931-
<para>
932-
Plain <literal>password</> sends the password in clear-text, and is
933-
therefore vulnerable to password <quote>sniffing</> attacks. It should
934-
always be avoided if possible. If the connection is protected by SSL
935-
encryption then <literal>password</> can be used safely, though.
936-
(Though SSL certificate authentication might be a better choice if one
937-
is depending on using SSL).
938-
</para>
934+
<variablelist>
935+
<varlistentry>
936+
<term><literal>scram-sha-256</literal></term>
937+
<listitem>
938+
<para>
939+
The method <literal>scram-sha-256</> performs SCRAM-SHA-256
940+
authentication, as described in
941+
<ulink url="https://tools.ietf.org/html/rfc7677">RFC 7677</ulink>. It
942+
is a challenge-response scheme that prevents password sniffing on
943+
untrusted connections and supports storing passwords on the server in a
944+
cryptographically hashed form that is thought to be secure.
945+
</para>
939946

947+
<para>
948+
This is the most secure of the currently provided methods, but it is
949+
not supported by older client libraries.
950+
</para>
951+
</listitem>
952+
</varlistentry>
940953

941-
<para>
942-
<literal>scram-sha-256</> performs SCRAM-SHA-256 authentication, as
943-
described in
944-
<ulink url="https://tools.ietf.org/html/rfc7677">RFC 7677</ulink>. It
945-
is a challenge-response scheme, that prevents password sniffing on
946-
untrusted connections. It is more secure than the <literal>md5</>
947-
method, but might not be supported by older clients.
948-
</para>
954+
<varlistentry>
955+
<term><literal>md5</literal></term>
956+
<listitem>
957+
<para>
958+
The method <literal>md5</> uses a custom less secure challenge-response
959+
mechanism. It prevents password sniffing and avoids storing passwords
960+
on the server in plain text but provides no protection if an attacker
961+
manages to steal the password hash from the server. Also, the MD5 hash
962+
algorithm is nowadays no longer consider secure against determined
963+
attacks.
964+
</para>
949965

950-
<para>
951-
<literal>md5</> allows falling back to a less secure challenge-response
952-
mechanism for those users with an MD5 hashed password.
953-
The fallback mechanism also prevents password sniffing, but provides no
954-
protection if an attacker manages to steal the password hash from the
955-
server, and it cannot be used with the <xref
956-
linkend="guc-db-user-namespace"> feature. For all other users,
957-
<literal>md5</> works the same as <literal>scram-sha-256</>.
958-
</para>
966+
<para>
967+
The <literal>md5</literal> method cannot be used with
968+
the <xref linkend="guc-db-user-namespace"> feature.
969+
</para>
970+
971+
<para>
972+
To ease transition from the <literal>md5</literal> method to the newer
973+
SCRAM method, if <literal>md5</literal> is specified as a method
974+
in <filename>pg_hba.conf</filename> but the user's password on the
975+
server is encrypted for SCRAM (see below), then SCRAM-based
976+
authentication will automatically be chosen instead.
977+
</para>
978+
</listitem>
979+
</varlistentry>
980+
981+
<varlistentry>
982+
<term><literal>password</literal></term>
983+
<listitem>
984+
<para>
985+
The method <literal>password</> sends the password in clear-text and is
986+
therefore vulnerable to password <quote>sniffing</> attacks. It should
987+
always be avoided if possible. If the connection is protected by SSL
988+
encryption then <literal>password</> can be used safely, though.
989+
(Though SSL certificate authentication might be a better choice if one
990+
is depending on using SSL).
991+
</para>
992+
</listitem>
993+
</varlistentry>
994+
</variablelist>
959995

960996
<para>
961997
<productname>PostgreSQL</productname> database passwords are
@@ -964,11 +1000,44 @@ omicron bryanh guest1
9641000
catalog. Passwords can be managed with the SQL commands
9651001
<xref linkend="sql-createuser"> and
9661002
<xref linkend="sql-alterrole">,
967-
e.g., <userinput>CREATE USER foo WITH PASSWORD 'secret'</userinput>.
1003+
e.g., <userinput>CREATE USER foo WITH PASSWORD 'secret'</userinput>,
1004+
or the <application>psql</application>
1005+
command <literal>\password</literal>.
9681006
If no password has been set up for a user, the stored password
9691007
is null and password authentication will always fail for that user.
9701008
</para>
9711009

1010+
<para>
1011+
The availability of the different password-based authentication methods
1012+
depends on how a user's password on the server is encrypted (or hashed,
1013+
more accurately). This is controlled by the configuration
1014+
parameter <xref linkend="guc-password-encryption"> at the time the
1015+
password is set. If a password was encrypted using
1016+
the <literal>scram-sha-256</literal> setting, then it can be used for the
1017+
authentication methods <literal>scram-sha-256</literal>
1018+
and <literal>password</literal> (but password transmission will be in
1019+
plain text in the latter case). The authentication method
1020+
specification <literal>md5</literal> will automatically switch to using
1021+
the <literal>scram-sha-256</literal> method in this case, as explained
1022+
above, so it will also work. If a password was encrypted using
1023+
the <literal>md5</literal> setting, then it can be used only for
1024+
the <literal>md5</literal> and <literal>password</literal> authentication
1025+
method specifications (again, with the password transmitted in plain text
1026+
in the latter case). (Previous PostgreSQL releases supported storing the
1027+
password on the server in plain text. This is no longer possible.) To
1028+
check the currently stored password hashes, see the system
1029+
catalog <literal>pg_authid</literal>.
1030+
</para>
1031+
1032+
<para>
1033+
To upgrade an existing installation from <literal>md5</literal>
1034+
to <literal>scram-sha-256</literal>, after having ensured that all client
1035+
libraries in use are new enough to support SCRAM,
1036+
set <literal>password_encryption = 'scram-sha-256'</literal>
1037+
in <filename>postgresql.conf</filename>, make all users set new passwords,
1038+
and change the authentication method specifications
1039+
in <filename>pg_hba.conf</filename> to <literal>scram-sha-256</literal>.
1040+
</para>
9721041
</sect2>
9731042

9741043
<sect2 id="gssapi-auth">

‎doc/src/sgml/config.sgml

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1190,7 +1190,7 @@ include_dir 'conf.d'
11901190
<para>
11911191
Note that older clients might lack support for the SCRAM authentication
11921192
mechanism, and hence not work with passwords encrypted with
1193-
SCRAM-SHA-256.
1193+
SCRAM-SHA-256. See <xref linkend="auth-password"> for more details.
11941194
</para>
11951195
</listitem>
11961196
</varlistentry>

‎doc/src/sgml/release-10.sgml

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1184,7 +1184,7 @@
11841184
2017-04-18 [c727f120f] Rename "scram" to "scram-sha-256" in pg_hba.conf and pas
11851185
-->
11861186
<para>
1187-
Add <link linkend="auth-pg-hba-conf"><literal>SCRAM-SHA-256</></>
1187+
Add <link linkend="auth-password">SCRAM-SHA-256</>
11881188
support for password negotiation and storage (Michael Paquier,
11891189
Heikki Linnakangas)
11901190
</para>

0 commit comments

Comments
 (0)
0