doc/src/sgml/chkpass.sgml

   1 <!-- $PostgreSQL$ -->
   2
   3 <sect1 id="chkpass">
   4  <title>chkpass</title>
   5
   6  <indexterm zone="chkpass">
   7   <primary>chkpass</primary>
   8  </indexterm>
   9
  10  <para>
  11   This module implements a data type <type>chkpass</> that is
  12   designed for storing encrypted passwords.
  13   Each password is automatically converted to encrypted form upon entry,
  14   and is always stored encrypted.  To compare, simply compare against a clear
  15   text password and the comparison function will encrypt it before comparing.
  16  </para>
  17
  18  <para>
  19   There are provisions in the code to report an error if the password is
  20   determined to be easily crackable.  However, this is currently just
  21   a stub that does nothing.
  22  </para>
  23
  24  <para>
  25   If you precede an input string with a colon, it is assumed to be an
  26   already-encrypted password, and is stored without further encryption.
  27   This allows entry of previously-encrypted passwords.
  28  </para>
  29
  30  <para>
  31   On output, a colon is prepended.  This makes it possible to dump and reload
  32   passwords without re-encrypting them.  If you want the encrypted password
  33   without the colon then use the <function>raw()</> function.
  34   This allows you to use the
  35   type with things like Apache's Auth_PostgreSQL module.
  36  </para>
  37
  38  <para>
  39   The encryption uses the standard Unix function <function>crypt()</>,
  40   and so it suffers
  41   from all the usual limitations of that function; notably that only the
  42   first eight characters of a password are considered.
  43  </para>
  44
  45  <para>
  46   Note that the chkpass data type is not indexable.
  47   <!--
  48   I haven't worried about making this type indexable.  I doubt that anyone
  49   would ever need to sort a file in order of encrypted password.
  50   -->
  51  </para>
  52
  53  <para>
  54   Sample usage:
  55  </para>
  56
  57 <programlisting>
  58 test=# create table test (p chkpass);
  59 CREATE TABLE
  60 test=# insert into test values ('hello');
  61 INSERT 0 1
  62 test=# select * from test;
  63        p
  64 ----------------
  65  :dVGkpXdOrE3ko
  66 (1 row)
  67
  68 test=# select raw(p) from test;
  69       raw
  70 ---------------
  71  dVGkpXdOrE3ko
  72 (1 row)
  73
  74 test=# select p = 'hello' from test;
  75  ?column?
  76 ----------
  77  t
  78 (1 row)
  79
  80 test=# select p = 'goodbye' from test;
  81  ?column?
  82 ----------
  83  f
  84 (1 row)
  85 </programlisting>
  86
  87  <sect2>
  88   <title>Author</title>
  89
  90   <para>
  91    D'Arcy J.M. Cain (<email>darcy@druid.net</email>)
  92   </para>
  93  </sect2>
  94
  95 </sect1>