Installing

Quick Start:

This guide is for Version 0.4, which will be released in the next day or so.

Firstly, there are some decisions that need to be made about how your authentication model will work. As of Version 0.4, two HTTP methods are supported: Digest Authentication (recommended) and Basic Authentication. Both appear the same to the user and currently they both have the same limitations.

Next, we need to select the authentication and backend method. Currently, only MySQL functionality is built in. In future versions, additional database structures will be supported. You can also elect to create your own authentication and backend methods. Look at the [Interface Functions] section as a guide.

Configuration

Now we need to configure the library to reflect the options we decided on.
One of the first settings (before any section) is Debugging. It is recommended to leave it on during testing and to turn it off before deploying the application.

The first section of the configuration controls how users are directed after login failures and logouts. You can elect to display text or to redirect to a static URL. The options are commented as to their function and are rather self explanatory.

The next section is where we select the authentication methods we've decided on. Change the values in this section to reflect the settings we've decided on.
auth_http_method dictates whether we use Basic or Digest authentication.
auth_verify_method dictates how we retrive and validate user credentials.
backend_method dictates how we store backend information.
session_check_method dictates how we check for user inactivity
Currently, there are no issues with settings conflicts. This may change in later versions.

In the following sections, we set up Password Hash Settings (Defaults are recommended) as well as MySQL connections.
Be sure to insert the proper database credentials. (Note: Two separate databases can be used for authentication and backend processes if you want).

Next are some critical values we must adjust BEFORE we begin testing the application. First, set the realm to an appropriate value for your site. Also, select a good secret value. (256+ Charecters from /dev/urandom are a good choice here)

The rest of the settings can be left on the default.

Setting up the Database

If the MySQL authentication or backend processes are used, the database must match the structures included in the files. The database and table names can be changed, however the column names must remain the same. Also, feel free to add extra columns but the included columns MUST remain unchanged.

Adding a user:

This library does not add or remove users to a database, it only checks to see if they are there. Therefore, in order to generate the first user account several methods can be employed. Ultimately, you should include the file (detailed below) and call

genHash($user, $password)

to generate a hash for the user. Then insert that value into the database.

Usage

For some generic usage examples, check out the examples that are included (You must have the library configured and at least one user in the database.)

Basically, to use the library include it and call authUser.

include_once '/dir/to/file/php-digest.php'
authUser();

authUser does accept one argument that adjusts if the script terminates the page load on a failed auth. Specifying authUser(FALSE) will check if a user has passed credential and verify them if they have. If they have not, the function will return false and allow the page to load. (This feature is handy for creating pages with admin functions, etc).

Other Functions

Some other helpful functions:
genHash($user, $password) generates the hash that should be stored in the database.
logoutUser() logs out the current user
checkPassword($user, $password) This should NOT be used to login a user, only to validate the identity for other purposes (ie, changing a password).