pam_sqlite3 v1.0.1
==================

Introduction
============

This module provides support to authenticate against SQLite
tables for PAM-enabled appliations.

This module is based on pam_sqlite, which is based on the pam_pgsql
module.

Compilation & Installation
==========================

pam_sqlite3 is autoconf'ed, thus, compiling should be a matter of:

    $ ./configure
    $ make
    $ make install

Compilation has been tested on:
- CentOS 5.1
- CentOS 5.4
- Mac OS X 10.6.4

You will need to have SQLite and PAM library and header files for this
module to compile.

See test.c for an example application that authenticates using
this module.

You can also use the pamtester utility found here:
https://pamtester.sourceforge.net/

Known Issues
============
- No multi-type character support

Configuration
=============

For the service you wish the module to be used, you need
to edit the /etc/pam.d/<service> file or /etc/pam.conf, and 
add the relevant lines.

For example:

auth        required    pam_sqlite3.so 
account     required    pam_sqlite3.so
password    required    pam_sqlite3.so

Configure the database, and table the module should use with
the configuration file /etc/pam_sqlite3.conf. An example of
this file:

database = /etc/sysdb
table = account
user_column = user_name
pwd_column = user_password
expired_column = acc_expired
newtok_column = acc_new_pwreq
debug

expired_column tells PAM if the user account has expired. Set it to '1'
or 'y' if it has.

newtok_column tells PAM if the user needs a new password. Set it to '1'
or 'y' if it does.

Note that for backwards compatibility with earlier versions, options specified
in the configuration file can be supplied as module arguments as well. Module
arguments will override the configuration file.

Configuration Options
=====================

    database            - the database which should be connected to
    table               - the name of the table to query
    user_column         - the column containing usernames
    pwd_column          - the column containing the passwords
    expired_column      - this column should contain '1' or 'y' if the account
                          has expired
    newtok_column       - this column should contain '1' or 'y' if the user
                          needs to change their password
    debug               - this is a standard module option that will enable
                          debug output to syslog (takes no values)
    pw_type             - specifies the password encryption scheme, can be one
                          of 'clear', 'md5', or 'crypt'. defaults to 'clear'.
    config_file         - specifies the path to a file to read for further
                          configuration options
    sql_verify          - specifies SQL template to use when verifying the
                          the password for a user; this query should select only
                          the password field and does not need to be wrapped in 
                          quotes                          
                          Default: SELECT %Op FROM %Ot WHERE %Ou='%U'
    sql_check_expired   - SQL template to use when checking for account expiry.
                          Default: SELECT 1 from %Ot WHERE %Ou='%U' AND (%Ox='y' OR %Ox='1')
    sql_check_newtok    - SQL template to use when checking to see if the user
                          needs to change their password.
                          Default: SELECT 1 FROM %Ot WHERE %Ou='%U' AND (%On='y' OR %On='1')
    sql_set_passwd      - SQL template to use when updating the password for
                          and user.
                          Default: UPDATE %Ot SET %Op='%P' WHERE %Ou='%U'


SQL Templates
=============

SQL templates are printf-inspired format strings.  The following escape
sequences are understood:

    %%       - literal % character
    %U       - The username (provided by PAM).  It will be quoted for use
               in the SQL.
    %P       - The password, either entered by the user or the new password
               to use when changing it.  It will be quoted for use in SQL.

    %O<char> - an option from the configuration; the following options are
               supported:

               %Op  - value of pwd_column
               %Ou  - value of user_column
               %Ot  - value of table
               %Ox  - value of expired_column
               %On  - value of newtok_column