$Id: haserldb-howto.txt,v 1.2 2005/10/28 12:48:55 nangel Exp $

This document provides an example implementation of using haserldb for session management.
It implements a form-based logon system.  This is simply an example and has lots of warts.
Better implementations are welcomed - please post your suggestions to the haserl-users
mailing list.

This example uses the mini_httpd web server from acme.com, and assumes anything named ".cgi"
is executable.  Here's the example /etc/http.conf file:

port=81
cgipat=**.cgi
user=nobody
dir=/var/www
max_age=0


To keep the database out of the web root, we need to create a directory for the database:

mkdir /var/www-db
chown nobody:nobody /var/www-db
chmod 777 /var/www-db

---------------------------
TDB LIMITATIONS:

A Trivial database uses a similar format to gdbm, so each key MUST be unique.  We'll fake storing 
multiple values/keys by using the following format:

[primarykey].[secondarykey]=value

This allows us to have a "Row" of data containing multiple fields.


-------------------------
The login system schema looks something like this:

users.tdb:	[Master user database (aka "the password file")]
	[userid].passwd		sha256 passwd salted with userid 
	[userid].roles		list of roles the user is in
	[userid].name		Full name of the user


sessions.tdb	[List of active sessions]
	[userid].sessid		The sessionid (384 bit random hash)
	[userid].expires	Timestamp the sessionid expires

disabled.tdb	[List of disabled accounts or IP addresses]
	[account.offenses]	A list of up to 10 past invalid login attempts 
	[account].expires	If the account is locked, timestamp when the lock expires

In running the system on an embedded device, the users database can be on the flash filesystem;
it changes infrequently.  The sessions and disabled databases should be stored in a tempfs or
RAM filesystem, as they will change frequently.


-------------------------
POPULATE THE USER DATABASE:

* This is imporant - the logon system will not work if the user database is missing! *

We'll populate the users.tdb database with three users:

userid	name			roles		password
sams	Sam Smith		user		SecretPassword
tinaa	Tina Adams		admin user	Admin
guest	Generic Guest Account	guest		guest


We can create and populate the users.tdb database with the following script

#cat <<-EOF | haserldb
/var/www-db/users.tdb opendb
"Sam Smith" sams.name store
"user" sams.roles store
"sams" $ "SecretPassword" sub	# add the userid to the password
sha256 sams.passwd store	# and hash it
"Tina Adams" tinaa.name store
"admin user" tinaa.roles store
"tinaa" $ "Admin" sub
sha256 tinaa.passwd store
"Generic Guest Account" guest.name store
"guest" guest.roles store
"guest" $ "guest" sub
sha256 guest.passwd store
EOF


The script stores the values in the keys.  For the password, sha256 is used to hash the password.
Verify the data was stored by enumerating the database:

#haserldb -d /var/www-db/users.tdb ".*" enum

-------------------------
LOGIN API

The loginlib.sh file (in the haserl "extras" directory) contains the API for accessing the databases.  It
provides functions for checking sessionids, checking username/password combinations, and managing the 
"disabled" table.  Please note this is just an example to show how an API can be built using haserldb. 

Copy the following files fom the haserl distribution "extras" directory:

index.cgi to /var/www/index.cgi		# A sample logon protected page
login.cgi to /var/www/login.cgi		# The login/logout page
loginlib.sh to /var/www-db/loginlib.sh	# The login library API for login.cgi



-------------------------
TRY IT

Using your web browser, go to the index.cgi page.  You should be redirected to the 
login page, where you can login as one of the users (samss, tinaa, or guest);  Also
experiment with logging in with invalid users, invalid passwords, etc.


