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

<sect1 id="chkpass" xreflabel="chkpass">
 <title>chkpass</title>

 <indexterm zone="chkpass">
  <primary>chkpass</primary>
 </indexterm>

 <para>
  This module implements a data type <type>chkpass</> that is
  designed for storing encrypted passwords.
  Each password is automatically converted to encrypted form upon entry,
  and is always stored encrypted.  To compare, simply compare against a clear
  text password and the comparison function will encrypt it before comparing.
 </para>

 <para>
  There are provisions in the code to report an error if the password is
  determined to be easily crackable.  However, this is currently just
  a stub that does nothing.
 </para>

 <para>
  If you precede an input string with a colon, it is assumed to be an
  already-encrypted password, and is stored without further encryption.
  This allows entry of previously-encrypted passwords.
 </para>

 <para>
  On output, a colon is prepended.  This makes it possible to dump and reload
  passwords without re-encrypting them.  If you want the encrypted password
  without the colon then use the <function>raw()</> function.
  This allows you to use the
  type with things like Apache's <literal>Auth_PostgreSQL</> module.
 </para>

 <para>
  The encryption uses the standard Unix function <function>crypt()</>,
  and so it suffers
  from all the usual limitations of that function; notably that only the
  first eight characters of a password are considered.
 </para>

 <para>
  Note that the <type>chkpass</type> data type is not indexable.
  <!--
  I haven't worried about making this type indexable.  I doubt that anyone
  would ever need to sort a file in order of encrypted password.
  -->
 </para>

 <para>
  Sample usage:
 </para>

<programlisting>
test=# create table test (p chkpass);
CREATE TABLE
test=# insert into test values ('hello');
INSERT 0 1
test=# select * from test;
       p
----------------
 :dVGkpXdOrE3ko
(1 row)

test=# select raw(p) from test;
      raw
---------------
 dVGkpXdOrE3ko
(1 row)

test=# select p = 'hello' from test;
 ?column?
----------
 t
(1 row)

test=# select p = 'goodbye' from test;
 ?column?
----------
 f
(1 row)
</programlisting>

 <sect2>
  <title>Author</title>

  <para>
   D'Arcy J.M. Cain (<email>darcy@druid.net</email>)
  </para>
 </sect2>

</sect1>