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

<sect1 id="passwordcheck" xreflabel="passwordcheck">
 <title>passwordcheck &mdash; verify password strength</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>

 <sect2 id="passwordcheck-configuration-parameters">
  <title>Configuration Parameters</title>

  <variablelist>
   <varlistentry>
    <term>
     <varname>passwordcheck.min_password_length</varname> (<type>integer</type>)
     <indexterm>
      <primary><varname>passwordcheck.min_password_length</varname> configuration parameter</primary>
     </indexterm>
    </term>
    <listitem>
     <para>
      The minimum acceptable password length in bytes.  The default is 8.  Only
      superusers can change this setting.
     </para>
     <note>
      <para>
       This parameter has no effect if a user supplies a pre-encrypted
       password.
      </para>
     </note>
    </listitem>
   </varlistentry>
  </variablelist>

  <para>
   In ordinary usage, this parameter is set in
   <filename>postgresql.conf</filename>, but superusers can alter it on-the-fly
   within their own sessions.  Typical usage might be:
  </para>

<programlisting>
# postgresql.conf
passwordcheck.min_password_length = 12
</programlisting>
 </sect2>
</sect1>