doc/src/sgml/passwordcheck.sgml

<!-- doc/src/sgml/passwordcheck.sgml -->

<sect1 id="passwordcheck" xreflabel="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"/> or
  <xref linkend="sql-alterrole"/>.
  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="https://github.com/cracklib/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
   recommended if your security requirements are high.
   It is more secure to use an external authentication method such as GSSAPI
   (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>