Add a hook to CREATE/ALTER ROLE to allow an external module to check the

strength of database passwords, and create a sample implementation of
such a hook as a new contrib module "passwordcheck".

Laurenz Albe, reviewed by Takahiro Itagaki

doc/src/sgml/contrib.sgml

@@ -1,4 +1,4 @@
-<!-- $PostgreSQL: pgsql/doc/src/sgml/contrib.sgml,v 1.14 2009/08/18 10:34:39 teodor Exp $ -->
+<!-- $PostgreSQL: pgsql/doc/src/sgml/contrib.sgml,v 1.15 2009/11/18 21:57:56 tgl Exp $ -->
 
 <appendix id="contrib">
  <title>Additional Supplied Modules</title>
@@ -98,6 +98,7 @@ psql -d dbname -f <replaceable>SHAREDIR</>/contrib/<replaceable>module</>.sql
  &ltree;
  &oid2name;
  &pageinspect;
+ &passwordcheck;
  &pgbench;
  &pgbuffercache;
  &pgcrypto;

doc/src/sgml/filelist.sgml

@@ -1,4 +1,4 @@
-<!-- $PostgreSQL: pgsql/doc/src/sgml/filelist.sgml,v 1.64 2009/08/18 10:34:39 teodor Exp $ -->
+<!-- $PostgreSQL: pgsql/doc/src/sgml/filelist.sgml,v 1.65 2009/11/18 21:57:56 tgl Exp $ -->
 
 <!entity history    SYSTEM "history.sgml">
 <!entity info       SYSTEM "info.sgml">
@@ -111,6 +111,7 @@
 <!entity ltree           SYSTEM "ltree.sgml">
 <!entity oid2name        SYSTEM "oid2name.sgml">
 <!entity pageinspect     SYSTEM "pageinspect.sgml">
+<!entity passwordcheck   SYSTEM "passwordcheck.sgml">
 <!entity pgbench         SYSTEM "pgbench.sgml">
 <!entity pgbuffercache   SYSTEM "pgbuffercache.sgml">
 <!entity pgcrypto        SYSTEM "pgcrypto.sgml">

doc/src/sgml/passwordcheck.sgml

@@ -0,0 +1,62 @@
+<!-- $PostgreSQL: pgsql/doc/src/sgml/passwordcheck.sgml,v 1.1 2009/11/18 21:57:56 tgl Exp $ -->
+
+<sect1 id="passwordcheck">
+ <title>passwordcheck</title>
+
+ <indexterm zone="passwordcheck">
+  <primary>passwordcheck</primary>
+ </indexterm>
+
+ <para>
+  The <filename>passwordcheck</filename> module checks users' passwords
+  whenever they are set with
+  <xref linkend="SQL-CREATEROLE" endterm="SQL-CREATEROLE-title"> or
+  <xref linkend="SQL-ALTERROLE" endterm="SQL-ALTERROLE-title">.
+  If a password is considered too weak, it will be rejected and
+  the command will terminate with an error.
+ </para>
+
+ <para>
+  To enable this module, add <literal>'$libdir/passwordcheck'</literal>
+  to <xref linkend="guc-shared-preload-libraries"> in
+  <filename>postgresql.conf</filename>, then restart the server.
+ </para>
+
+ <para>
+  You can adapt this module to your needs by changing the source code.
+  For example, you can use
+  <ulink url="http://sourceforge.net/projects/cracklib/">CrackLib</ulink>
+  to check passwords &mdash; this only requires uncommenting
+  two lines in the <filename>Makefile</filename> and rebuilding the
+  module.  (We cannot include <productname>CrackLib</productname>
+  by default for license reasons.)
+  Without <productname>CrackLib</productname>, the module enforces a few
+  simple rules for password strength, which you can modify or extend
+  as you see fit.
+ </para>
+
+ <caution>
+  <para>
+   To prevent unencrypted passwords from being sent across the network,
+   written to the server log or otherwise stolen by a database administrator,
+   <productname>PostgreSQL</productname> allows the user to supply
+   pre-encrypted passwords. Many client programs make use of this
+   functionality and encrypt the password before sending it to the server.
+  </para>
+  <para>
+   This limits the usefulness of the <filename>passwordcheck</filename>
+   module, because in that case it can only try to guess the password.
+   For this reason, <filename>passwordcheck</filename> is not
+   recommendable if your security requirements are high.
+   It is more secure to use an external authentication method such as Kerberos
+   (see <xref linkend="client-authentication">) than to rely on
+   passwords within the database.
+  </para>
+  <para>
+   Alternatively, you could modify <filename>passwordcheck</filename>
+   to reject pre-encrypted passwords, but forcing users to set their
+   passwords in clear text carries its own security risks.
+  </para>
+ </caution>
+
+</sect1>