Tinsology

I’ve just added a section about session management to Creating a Secure Login System the Right Way.

Check it out

Making a custom login system is a common task for beginning PHP developers. Jumping right into it, however, may not be the best approach. There are several important aspects do building a login system that not only makes it work, but makes it safe.
Updated on December 15th 2009: Added Session Control Section

Getting Started

To begin with, we’ll create our login form. This doesn’t need to be anything fancy, just a couple of input fields and a submit button:

<form name="login" action="login.php" method="post">
	Username: <input type="text" name="username" />
	Password: <input type="password" name="password" />
	<input type="submit" value="Login" />
</form>

The above example is stripped down; there is no formatting or styles so it will most likely won’t look to great if you copy and paste the code. Making your form pretty is beyond the scope of this article. In the form tag, notice that it has three attributes: name, action, and method. Name identifies the form and is not very important in the context of this article. Action identifies the script that will be processing the login, often times your form and the processing code are in a single file, but this does not have to be the case. Method typically takes one of two values: post or get. If you submit a form using GET the data is URL encoded and will be visible in the address bar. If the method is post the data will not be URL encoded. As you may have guessed there is actually a lot more to it than that but the difference between post and get is a topic for another article. We want to use post.

Notice that our input fields are given name attributes, this is important as we will need to identify and access these values by this name. PHP identifies form data using the name attribute, not the id. Now that our form is complete we can move on to processing the data.

Storing our Data

Actually we can’t process the data just yet. Before that we need to worry about how our data will be represented in the database. There are three essential values we must store in our database: the username, password, and a salt. We will get into what a salt is later. In addition to this you may choose to store other things about your user. It is also common to give the user a numeric user id. This is not absolutely necessary but it is common for tables to have a numeric, sequential primary key. For our purposes assume our table structure is this:

CREATE TABLE users (
	id INT NOT NULL AUTO_INCREMENT,
	username VARCHAR(30) NOT NULL UNIQUE,
	password VARCHAR(40) NOT NULL,
	salt VARCHAR(3) NOT NULL,
	PRIMARY KEY(id)
);

In the above SQL code we create a table called users having columns id, username, password, and salt. Even though we could use usernames to uniquely identify users we will use the id for this instead. One reason for this is that integer comparisons are cheaper than string comparisons, so searching through a large number of users will require fewer resources. Convention is another reason.

There are a few keywords in the above code that I’ll define for you. Not null means that each tuple (a tuple is a row in our table, each user will have a row) must have a value for this column. In this case all of our columns are ‘not null’ so every user must have each of these values. Auto increment applies to numeric primary keys. It allows us to give each user a sequential id without worrying about collisions or what the most recent users id was; the database will assign each user a correct id automatically. Unique, as you may guess, means that the value must be unique. In our case, no two users may have the same username. Finally, primary key tells the database which field will uniquely identify each row. No two users can have the same id. It also creates and index on the specified column, meaning that lookups will be faster (at the expense of memory).

Each column also has a data type. The id is and integer while the remain fields are varchars. Varchars are just arrays of characters, as are strings. Varchar(30) means a sequence of 30 characters. For the username I chose 30 as the length for no particular reason; it allows for a reasonable amount of characters without letting users write a paragraph. The lengths for password and salt are important and I’ll get into that later. Now that we have created our table we are ready to process our data.

Populating our Table

Actually we can’t process the data just yet. You can’t login if your users table is empty. Just like on any site, you have to register before you can login. To accomplish this we will create a simple registration form.

<form name="register" action="register.php" method="post">
	Username: <input type="text" name="username" maxlength="30" />
	Password: <input type="password" name="pass1" />
	Password Again: <input type="password" name="pass2" />
	<input type="submit" value="Register" />
</form>

The above code is similar to our login form code with one notable difference. In the username input field I specify the maxlength attribute as 30. This means the field can only contain 30 characters and corresponds to the username length we specified in our SQL code. Notice I don’t enforce the length of passwords even though they are defined as 40 characters in the SQL code, you will see why it is not necessary to do so later. Now that we have our registration form we can process our data.

Sign Me Up

Our registration data that is, we still can’t process our login data. At this point we actually get to write some PHP code (are you as excited as I am?).

register.php (part 1):

<?php
//retrieve our data from POST
$username = $_POST['username'];
$pass1 = $_POST['pass1'];
$pass2 = $_POST['pass2'];

if($pass1 != $pass2)
	header('Location: register_form.php');

if(strlen($username) > 30)
	header('Location: register_form.php');

In the above code we retrieve our data from $_POST, which is an associative array where all of the post data is stored. We also check if pass1 and pass2 are equal which is an example of validating user input. If they are not equal we use the header function to redirect back to our registration form (assume the registration form is located in a file called register_form.php). Ideally we would want to display an error message, but for the sake of example we will keep it simple. We also check if the username exceeds 30 characters. Even though we set the form to allow no more than 30 characters it is important that we check as well; it is possible (and very simple) to bypass the limit imposed in the html code. In addition to this you should check for any other constrains you have placed on your data (valid characters, minimum length, etc).

Hashing

As I mentioned earlier, the length of the password varchar in the database is significant. This is because we are not actually going to (and never should) store the password in the database. We are going to store an sha1 hash which is a string always containing 40 characters. In simple terms a hash is an algorithm that maps inputs to outputs in a deterministic way. Meaning that given an input the algorithm will always produce the same output. Sha1 is an algorithm that outputs a 40 digit hexadecimal value. As in most cases, given the output of the sha1 algorithm it is not easy (though possible) to determine the input. In PHP we can get the sha1 hash of our password like this:

regsiter.php (part 2)

$hash = sha1($pass1);

Pass the Salt

As I mentioned before, there is no simple way to determine the input of the sha1 algorithm from the output. It is, however, possible through brute force or more complicated means. One way to improve the security of your users’ passwords is to use a salt. A salt is just a random string of characters that is appended to the hash, which is then hashed again.

regsiter.php (part 3)

//creates a 3 character sequence
function createSalt()
{
	$string = md5(uniqid(rand(), true));
	return substr($string, 0, 3);
}

$salt = createSalt();

$hash = sha1($salt . $hash);

Some people will tell you that a salt is not necessary, but it certainly doesn’t hurt to use one.

Now comes the database portion of our code, for this I will assume we are using a mysql database. I will also assume the database host, name, user, and password. I won’t anticipate any database connection errors in the code, but you should.

register.php (part 4):

$dbhost = 'localhost';
$dbname = 'tinsology';
$dbuser = 'tinsley';
$dbpass = 'trueblood'; //awesome tv show

$conn = mysql_connect($dbhost, $dbuser, $dbpass);
mysql_select_db($dbname, $conn);

//sanitize username
$username = mysql_real_escape_string($username);

$query = "INSERT INTO users ( username, password, salt )
		VALUES ( '$username' , '$hash' , '$salt' );";
mysql_query($query);

mysql_close();

header('Location: login_form.php');

In the above code we establish a connection to our MySQL database and add our new user to the users table. Then we redirect to our login form. Notice that we call the funciton mysql_real_escape string. This function helps to prevent SQL injections by escaping the input. Using an abstraction layer like PDO will also help to prevent this. Now that we’ve processed our registration data we can write the code to process our login data.

Logging in

Seriously this time. Our login processor will pull the login data from post and compare it to the database values.

$username = $_POST['username'];
$password = $_POST['password'];

//connect to the database here

$username = mysql_real_escape_string($username);

$query = "SELECT password, salt
		FROM users
		WHERE username = '$username';";
$result = mysql_query($query);

if(mysql_num_rows($result) < 1) //no such user exists
{
	header('Location: login_form.php');
}

$userData = mysql_fetch_array($result, MYSQL_ASSOC);
$hash = sha1( $userData['salt'] . sha1($password) );

if($hash != $userData['password']) //incorrect password
{
	header('Location: login_form.php');
}

//login successful

As I mentioned before, this is a stripped down example. Ideally you would not have the code you use to connect to your database in each file, but rather in a single file or function that you could include. In addition to this you should maintain a session throughout the process in order to store and report error message, as well as other useful data. The most important thing to remember when creating a login system is that you should never trust your users. Validate all user input, protect against SQL injections, and never store raw passwords in the database.

P.S. Session Control
Added December 15th 2009

All of the above code illustrates how to register a user, and allow them to login. There is, however, one fundamental piece that is missing: session control. In order for a login system to be useful, it must provide some means to distinguish between a logged in user and a non-logged in user across the entire site. Sessions are the means by which we do this. What we want to do is, after a user has successfully logged in is indicate, using a session variable, that the user has done so.

Accessing Session Data

Activating and managing sessions in PHP is very straightforward, you only need one function to both create and recall a particular session: session_start(). Here is a generic example of how to use session_start to store session data:

page1.php

session_start();

$_SESSION['foo'] = 'bar';

page2.php

session_start();

echo $_SESSION['foo']; //will output bar

In the above example you can see that in page1 we start a session and assign the session variable “foo” the value “bar”. If the user visits page2 sometime there after the session will be recalled and the value of foo (bar) will be echo’d. Notice that session_start creates a new session if one does not exist or recalls that session if it already exists.

There are a few subtleties relating to session_start that are important to remember. You must call session_start before any headers are sent to the browser. This means that your script cannot have any output or calls to header() (or any other function that sends headers) before calling session_start. The simplest way to avoid this problem is to call session_start before anything else. One common case where this problem can occur is when some code that normally wouldn’t have any output generates an error or warning prior to calling session_start. The default error handler will automatically output any error messages to the browser.

Generally (though not necessarily), a session lives as long as the browser remains open.

Using Sessions in Our Login System

There are three basic functions we want to incorporate into our login system: validating a user (i.e. indicating that user has logged on), checking if a user is logged on, and logging a user out.

Validating a User

function validateUser()
{
	session_regenerate_id (); //this is a security measure
	$_SESSION['valid'] = 1;
	$_SESSION['userid'] = $userid;
}

This function simply sets the session variable ‘valid’ to 1. You may also want to use this function to store certain variables. It is a good idea to store frequently accessed data about a particular user (such as a user id, username, NOT a password or sensitive data). The $_SESSION['userid'] = $userid; line is an example of how to store user info. Additional information about session security will be provided in the following section.

Checking if a User is Logged On

function isLoggedIn()
{
	if($_SESSION['valid'])
		return true;

	return false;
}

This function simply checks if the session variable ‘valid’ is set to 1.

Logging Out

function logout()
{
	$_SESSION = array(); //destroy all of the session variables
	session_destroy();
}

When it is time to log a user out, we destroy the session. All of these functions assume session_start has already been called.

Now it is time to incorporate this into our login script:

session_start(); //must call session_start before using any $_SESSION variables

$username = $_POST['username'];
$password = $_POST['password'];

//connect to the database here

$username = mysql_real_escape_string($username);

$query = "SELECT password, salt
		FROM users
		WHERE username = '$username';";
$result = mysql_query($query);

if(mysql_num_rows($result) < 1) //no such user exists
{
	header('Location: login_form.php');
	die();
}

$userData = mysql_fetch_array($result, MYSQL_ASSOC);
$hash = sha1( $userData['salt'] . sha1($password) );

if($hash != $userData['password']) //incorrect password
{
	header('Location: login_form.php');
	die();
}
else
{
	validateUser(); //sets the session data for this user
}

//redirect to another page or display "login success" message

Now we can use the isLoggedIn function to determine if a user is logged in and act accordingly:

membersonly.php

session_start();

//if the user has not logged in
if(!isLoggedIn())
{
	header('Location: login.php');
	die();
}

//page content follows

A Note About Session Security

By default, sessions are cookie based. This means that a particular session is associated with a user by use of a cookie. This being the case, there are certain vulnerabilities that arise. There are a variety of methods by which a session can be hijacked (XSS for example; a javascript injection can cause a user to give up their session id). Unfortunately you cannot expect to eliminate the possibility that a user has hijacked someone else’s session. Further research into the subject may yield a few tricks, but ultimately the best practice is to be cautious about certain tasks. If a user wants to change their password (after logging in), require the old password and whenever possible avoid displaying sensitive data.

Earlier I mentioned that you shouldn’t use session variables to store sensitive data. It is important to remember that session data lives on the server, this means that a user cannot directly view or modify session data. On a shared server, however, other users of that server may be able to access this information.

Just a reminder, all of the code examples I provided are exactly that: examples. They are meant to serve as a starting point, and hopefully shed some light on a few key concepts, but they are not is a real world implementation. I don’t recommend, for example, using header() to bounce your users around to different pages; there are better methods that reduce the number of page loads and give the user a more fluid experience. Using this method, however, simplifies things and makes the examples easier to follow.