doc/src/sgml/passwordcheck.sgml

   1 <!-- doc/src/sgml/passwordcheck.sgml -->
   2
   3 <sect1 id="passwordcheck" xreflabel="passwordcheck">
   4  <title>passwordcheck &mdash; verify password strength</title>
   5
   6  <indexterm zone="passwordcheck">
   7   <primary>passwordcheck</primary>
   8  </indexterm>
   9
  10  <para>
  11   The <filename>passwordcheck</filename> module checks users' passwords
  12   whenever they are set with
  13   <xref linkend="sql-createrole"/> or
  14   <xref linkend="sql-alterrole"/>.
  15   If a password is considered too weak, it will be rejected and
  16   the command will terminate with an error.
  17  </para>
  18
  19  <para>
  20   To enable this module, add <literal>'$libdir/passwordcheck'</literal>
  21   to <xref linkend="guc-shared-preload-libraries"/> in
  22   <filename>postgresql.conf</filename>, then restart the server.
  23  </para>
  24
  25  <para>
  26   You can adapt this module to your needs by changing the source code.
  27   For example, you can use
  28   <ulink url="https://github.com/cracklib/cracklib">CrackLib</ulink>
  29   to check passwords &mdash; this only requires uncommenting
  30   two lines in the <filename>Makefile</filename> and rebuilding the
  31   module.  (We cannot include <productname>CrackLib</productname>
  32   by default for license reasons.)
  33   Without <productname>CrackLib</productname>, the module enforces a few
  34   simple rules for password strength, which you can modify or extend
  35   as you see fit.
  36  </para>
  37
  38  <caution>
  39   <para>
  40    To prevent unencrypted passwords from being sent across the network,
  41    written to the server log or otherwise stolen by a database administrator,
  42    <productname>PostgreSQL</productname> allows the user to supply
  43    pre-encrypted passwords. Many client programs make use of this
  44    functionality and encrypt the password before sending it to the server.
  45   </para>
  46   <para>
  47    This limits the usefulness of the <filename>passwordcheck</filename>
  48    module, because in that case it can only try to guess the password.
  49    For this reason, <filename>passwordcheck</filename> is not
  50    recommended if your security requirements are high.
  51    It is more secure to use an external authentication method such as GSSAPI
  52    (see <xref linkend="client-authentication"/>) than to rely on
  53    passwords within the database.
  54   </para>
  55   <para>
  56    Alternatively, you could modify <filename>passwordcheck</filename>
  57    to reject pre-encrypted passwords, but forcing users to set their
  58    passwords in clear text carries its own security risks.
  59   </para>
  60  </caution>
  61
  62  <sect2 id="passwordcheck-configuration-parameters">
  63   <title>Configuration Parameters</title>
  64
  65   <variablelist>
  66    <varlistentry>
  67     <term>
  68      <varname>passwordcheck.min_password_length</varname> (<type>integer</type>)
  69      <indexterm>
  70       <primary><varname>passwordcheck.min_password_length</varname> configuration parameter</primary>
  71      </indexterm>
  72     </term>
  73     <listitem>
  74      <para>
  75       The minimum acceptable password length in bytes.  The default is 8.  Only
  76       superusers can change this setting.
  77      </para>
  78      <note>
  79       <para>
  80        This parameter has no effect if a user supplies a pre-encrypted
  81        password.
  82       </para>
  83      </note>
  84     </listitem>
  85    </varlistentry>
  86   </variablelist>
  87
  88   <para>
  89    In ordinary usage, this parameter is set in
  90    <filename>postgresql.conf</filename>, but superusers can alter it on-the-fly
  91    within their own sessions.  Typical usage might be:
  92   </para>
  93
  94 <programlisting>
  95 # postgresql.conf
  96 passwordcheck.min_password_length = 12
  97 </programlisting>
  98  </sect2>
  99 </sect1>