Topics

Introduction

Simple User Access Control System is designed as a set of subfunctions to be used in other programs such as a message board or file access system. It is written in PHP, and designed to be highly and easily customize. It handles the user login and management requests and their interface with the DB, thereby handling the security and allowing the developer to work on the other, perhaps more interesting sections of code.

Requirements

This piece of software requires the following:
  1. PHP
  2. MySQL
Please note that other DBs may work, but have not been tested.

Extension

To utilize this set of code, please see the following section, Functions, for a list of the functions, their signatures, and pre/post conditions (C style). Note that all instances of ' and " will be removed from input strings to maintain data integrity. If used in user passwords, it may prove a frustrating necessity. Please examine the test script in index.php carefully, as it shows what steps should be taken for login, logout, etc. Also, be sure to include the call to db_connect at the beginning of every file, and to close the DB connection (last 2 lines of index.php) at the end of every file. Lastly, please note that usernames are treated as case insensitive while passwords are case sensitive. Also, the user data field can be used to store virtually unlimited information (MySQL BLOB element). It must contain a large string, but that string can be used to store many variables using the PHP implode and explode functions. This will, however, add at least one restricted character for the data fields. As a final note, be sure that data types are correct when sending arguments to the functions as, for instance, trying to create a user with $in_urn as an integer will create a user with the username of whatever results from string(false).

Functions

// Pre: inTime as a valid integer, and inMsg and inTarget are valid strings.
// Post: Generates code to wait inTime seconds, then redirect to Target. Displays inMsg w/ a link in case browser does not auto-redirect.
string redirect(integer $inTime, string $inMsg, string $inTarget)

// Pre: Connection to database has been established.
// Post: Adds user with the appropriate credentials if a user with the same username (login) does not already exist.
boolean add_user(string $in_urn, string $in_pass, integer $in_status, string $in_data)

// Pre: Connection to database has been established.
// Post: User $in_usr is updated with new credentials.
void update_user(string $in_usr, integer $in_status, integer $in_enabled, string $in_data)

// Pre: Connection to database has been established.
// Post: If $in_usr exists in DB, user is removed.
void remove_user(string $in_usr)

// Pre: Connection to database has been established.
// Post: user $in_usr is logged in if they exist.
void login_user(string $in_usr, string $ip)

// Pre: Connection to database has been established.
// Post: User $in_usr is logged out.
void logout_user(string $in_usr)

// Pre: Connection to database has been established.
// If the password for $in_usr is $in_pass, return true. Else, return false.
boolean verify_pass(string $in_usr, string $in_pass)

// Pre: Connection to database has been established.
// Post: Change the password for user $in_pass.
void change_pass(string $in_usr, string $in_pass)

// Pre: None
// Post: connects to server if possible, or displays applicable error message.
resource db_connect( )

// Pre: Connection to database has been established.
// Post: Returns 0 if logged out, or the value of user_status if logged in.
integer get_status(string $in_usr, string $in_ip)

// Pre: Connection to database has been established.
// Post: returns an array containing a list of the users contained in the DB. Returns false on error or no users.
array/boolean get_users( )

// Pre: Connection to database has been established.
// Post: get the user for $in_usr if it exists and return it in an array. Else return false.
array/boolean get_user_info(string $in_urn)

// Pre: None.
// Post: If $in_str is a valid string, all instances of the quotation mark characters (single and double) are removed. If illegal input, return false.
string clean_str(string $in_str)

Installation

To install, follow these steps:
  1. Create a database, and make note of the login credentials.
  2. Edit the configuration file located at ./include/config.php to reflect the DB login credentials. Also update the variable prefix to reflect the desired table prefix and the salt variable to change the password salt used. DO NOT EDIT THESE VARIABLES FROM HERE ON OUT
  3. You can change the timeout of an active login by changing the variable timeout in this file. You can do this at any point.
  4. Save and close the configuration file.
  5. Direct your browser to ./install.php and the database will be initialized if possible.
  6. You will be redirected to the index, which by default is just a test/demonstration script.
  7. The default login is username: admin and password: password which will be important to note.
  8. Enjoy.

Credits

Simple User Access Control System was originally written by Matt Berntsen in October of 2005.