Advertisement

Secure Your Forms With Form Keys

by
Student iconAre you a student? Get a yearly Tuts+ subscription for $45 →

Security is a hot topic. Ensuring that your websites are secure is extremely important for any web application. In fact, I spend 70% of my time securing my applications. One of the most important things we must secure are forms. Today, we are going to review a method to prevent XSS (Cross-site scripting) and Cross-site request forgery on forms.

Why?

POST data can be sent from one website to another. Why is this bad? A simple scenario...

A user, logged into your website, visits another website during his session. This website will be able to send POST data to your website -- for example, with AJAX. Because the user is logged in on your site, the other website will also be able to send post data to secured forms that are only accessible after a login.

We also must protect our pages against attacks using cURL

How Do We Fix This?

With form keys! We'll add a special hash (a form key) to every form to make sure that the data will only be processed when it has been sent from your website. After a form submit, our PHP script will validate the submitted form key against the form key we've set in a session.

What We Must Do:

  1. Add a form key to every form.
  2. Store the form key in a session.
  3. Validate the form key after a form submit.

Step 1: A Simple Form

Login Form

First we need a simple form for demonstration purposes. One of the most important forms we have to secure is the login form. The login form is vulnerable tobrute force attacks. Create a new file, and save it as index.php in your web-root. Add the following code within the body:

	<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
	<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
	<head>
		<meta http-equiv="content-type" content="text/html;charset=UTF-8" />
		<title>Securing forms with form keys</title>
	</head>
	<body>
		<form action="" method="post">
		<dl>
			<dt><label for="username">Username:</label></dt>
			<dd><input type="text" name="username" id="username" /></dd>
			<dt><label for="username">Password:</label></dt>
			<dd><input type="password" name="password" id="password" /></dd>
			<dt></dt>
			<dd><input type="submit" value="Login" /></dd>
		</dl>
		</form>
	</body>
	</html>

Now we have a simple XHTML page with a login form. If you want to use form keys on your website, you can replace the script above with your own login page. Now, let's continue to the real action.

Step 2: Creating a Class

We are going to create a PHP class for our form keys. Because every page can contain only one form key, we could make a singleton of our class to make sure that our class is used correctly. Because creating singletons is a more advanced OOP topic, we will skip that part. Create a new file called formkey.class.php and place it in your web-root. Now we have to think about the functions we need. First, we need a function to generate a form key so we can place it in our form. In your PHP file place the following code:

<?php

//You can of course choose any name for your class or integrate it in something like a functions or base class
class formKey
{
	//Here we store the generated form key
	private $formKey;
	
	//Here we store the old form key (more info at step 4)
	private $old_formKey;
	
	//Function to generate the form key
	private function generateKey()
	{
		
	}
}
?>

Above, you see a class with three parts: two variables and a function. We make the function private because this function will only be used by our outputfunctions, which we will create later. In the two variables, we will store the form keys. These are also private because they may only be used by functions inside our class.

Now, we have to think of a way to generate our form key. Because our form key must be unique (otherwise we don't have any security), we use a combination of the users IP-address to bind the key to a user, mt_rand() to make it unique, and the uniqid() function to make it even more unique. We also encrypt this information with md5() to create a unique hash which we can then insert into our pages. Because we used md5(), a user cannot see what we used to generate the key. The whole function:

//Function to generate the form key
private function generateKey()
{
	//Get the IP-address of the user
	$ip = $_SERVER['REMOTE_ADDR'];
	
	//We use mt_rand() instead of rand() because it is better for generating random numbers.
	//We use 'true' to get a longer string.
	//See http://www.php.net/mt_rand for a precise description of the function and more examples.
	$uniqid = uniqid(mt_rand(), true);
	
	//Return the hash
	return md5($ip . $uniqid);
}

Insert the code above into your formkey.class.php file. Replace the function with the new function.

Step 3: Inserting a Form Key into Our Form

For this step, we create a new function that outputs a hidden HTML field with our form key. The function consists of three steps:

Generate, Save, Output

  1. Generate a form key with our generateKey() function.
  2. Store the form key in our $formKey variable and in a session.
  3. Output the HTML field.

We name our function outputKey() and make it public, because we have to use it outside of our class. Our function will call the private function generateKey() to generate a new form key and save it locally in a session. Lastly, we create the XHTML code. Now add the following code inside our PHP class:

//Function to output the form key
public function outputKey()
{
	//Generate the key and store it inside the class
	$this->formKey = $this->generateKey();
	//Store the form key in the session
	$_SESSION['form_key'] = $this->formKey;
	
	//Output the form key
	echo "<input type='hidden' name='form_key' id='form_key' value='".$this->formKey."' />";
}

Now, we are going to add the form key to our login form to secure it. We have to include the class in our index.php file. We also have to start the session because our class uses sessions to store the generated key. For this, we add the following code above the doctype and head tag:

<?php
//Start the session
session_start();
//Require the class
require('formkey.class.php');
//Start the class
$formKey = new formKey();
?>

The code above is pretty self-explanatory. We start the session (because we store the form key) and load the PHP class file. After that, we start the class with new formKey(), this will create our class and store it in $formKey. Now we only have to edit our form so that it contains the form key:

<form action="" method="post">
<dl>
	<?php $formKey->outputKey(); ?>
	<dt><label for="username">Username:</label></dt>
	<dd><input type="text" name="username" id="username" /></dd>
	<dt><label for="username">Password:</label></dt>
	<dd>input type="password" name="password" id="password" /></dd>
<dl>
</form>

And that's all! Because we created the function outputKey(), we only have to include it in our form. We can use form keys in every form by just adding <?php $formKey->outputKey(); ?> Now just review the source of your webpage and you can see that there is a form key attached to the form. The only remaining step is to validate requests.

Step 4: Validating

We won't validate the whole form; only the form key. Validating the form is basic PHP and tutorials can be found all over the web. Let's validate the form key. Because our "generateKey" function overwrites the session value, we add a constructor to our PHP class. A constructor will be called when our class is created (or constructed). The constructor will store the previous key inside the class before we create a new one; so we'll always have the previous form key for validating our form. If we didn't do this, we wouldn't be able to validate the form key. Add the following PHP function to your class:

//The constructor stores the form key (if one exists) in our class variable.
function __construct()
{
	//We need the previous key so we store it
	if(isset($_SESSION['form_key']))
	{
		$this->old_formKey = $_SESSION['form_key'];
	}
}

A constructor should always be named __construct(). When the constructor is called we check if a session is set, and if so, we store it locally in our old_formKey variable.

Now we are able to validate our form key. We create a basic function inside our class which validates the form key. This function should also be public because we are going to use it outside our class. The function will validate the POST value of the form key against the stored value of the form key. Add this function to the PHP class:

//Function that validated the form key POST data
public function validate()
{
	//We use the old formKey and not the new generated version
	if($_POST['form_key'] == $this->old_formKey)
	{
		//The key is valid, return true.
		return true;
	}
	else
	{
		//The key is invalid, return false.
		return false;
	}
}

Within index.php, we validate the form key by using the function we just created in our class. Of course, we only validate after a POST request. Add the following code after $formKey = new formKey();

$error = 'No error';

//Is request?
if($_SERVER['REQUEST_METHOD'] == 'post')
{
	//Validate the form key
	if(!isset($_POST['form_key']) || !$formKey->validate())
	{
		//Form key is invalid, show an error
		$error = 'Form key error!';
	}
	else
	{
		//Do the rest of your validation here
		$error = 'No form key error!';
	}
}

We created a variable $error which stores our error message. If a POST request has been sent we validate our formkey with $formKey->validate(). If this returns false, the form key is invalid and we display an error. Note that we only validate the form key -- you're expected to validate the rest of the form yourself.

In your HTML, you can place the following code to show the error message:

	<div><?php if($error) { echo($error); } ?></div>

This will echo the $error variable if it is set.

Form

If you start your server and go to index.php, you will see our form and the message 'No error'. When you submit a form you will see the message 'No form key error' because it is an valid POST request. Now try to reload the page and accept when your browser requests that the POST data be sent again. You will see that our script triggers an error message: 'Form key error!' Your form is now protected against input from other websites and errors with page reloads! The error is also shown after a refresh because a new form key was generated after we submitted the form. This is good because, now, user can't accidentally post a form twice.

Full Code

Here is the whole PHP and HTML code:

index.php

<?php
//Start the session
session_start();
//Require the class
require('formkey.class.php');
//Start the class
$formKey = new formKey();

$error = 'No error';

//Is request?
if($_SERVER['REQUEST_METHOD'] == 'post')
{
	//Validate the form key
	if(!isset($_POST['form_key']) || !$formKey->validate())
	{
		//Form key is invalid, show an error
		$error = 'Form key error!';
	}
	else
	{
		//Do the rest of your validation here
		$error = 'No form key error!';
	}
}
?>
	
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
	<meta http-equiv="content-type" content="text/html;charset=UTF-8" />
	<title>Securing forms with form keys</title>
</head>
<body>
	<div><?php if($error) { echo($error); } ?>
	<form action="" method="post">
	<dl>
		<?php $formKey->outputKey(); ?>

		<dt><label for="username">Username:</label></dt>
		<dd><input type="text" name="username" id="username" /></dd>
		<dt><label for="username">Password:</label></dt>
		<dd><input type="password" name="password" id="password" /></dd>
		<dt></dt>
		<dd><input type="submit" value="Submit" /></dd>
	<dl>
	</form>
</body>
</html>

fomrkey.class.php

<?php

//You can of course choose any name for your class or integrate it in something like a functions or base class
class formKey
{
	//Here we store the generated form key
	private $formKey;
	
	//Here we store the old form key (more info at step 4)
	private $old_formKey;
	
	//The constructor stores the form key (if one excists) in our class variable
	function __construct()
	{
		//We need the previous key so we store it
		if(isset($_SESSION['form_key']))
		{
			$this->old_formKey = $_SESSION['form_key'];
		}
	}

	//Function to generate the form key
	private function generateKey()
	{
		//Get the IP-address of the user
		$ip = $_SERVER['REMOTE_ADDR'];
		
		//We use mt_rand() instead of rand() because it is better for generating random numbers.
		//We use 'true' to get a longer string.
		//See http://www.php.net/mt_rand for a precise description of the function and more examples.
		$uniqid = uniqid(mt_rand(), true);
		
		//Return the hash
		return md5($ip . $uniqid);
	}

	
	//Function to output the form key
	public function outputKey()
	{
		//Generate the key and store it inside the class
		$this->formKey = $this->generateKey();
		//Store the form key in the session
		$_SESSION['form_key'] = $this->formKey;
		
		//Output the form key
		echo "<input type='hidden' name='form_key' id='form_key' value='".$this->formKey."' />";
	}

	
	//Function that validated the form key POST data
	public function validate()
	{
		//We use the old formKey and not the new generated version
		if($_POST['form_key'] == $this->old_formKey)
		{
			//The key is valid, return true.
			return true;
		}
		else
		{
			//The key is invalid, return false.
			return false;
		}
	}
}
?>

Conclusion

Adding this code to every important form on your website will increase your form's security dramatically. It even stops refreshing issues, as we saw in step 4. Because the form key is only valid for one request, a double post is not possible.

This was my first tutorial, I hope you like it and use it to improve your security! Please let me know your thoughts, via the comments. Have a better method? Let us know.

Further Reading


Advertisement