php-litesec – A Minimalistic Library For PHP Security

Overview

The php-litesec library is meant to provide basic security functionalities in a robust and easy-to-use way. It currently has the following features:

• escaping strings for HTML
• secure password hashes
• generating stronger random numbers

Requirements

You need at least PHP 5.3.7. Generating random numbers also requires the OpenSSL extension or the Mcrypt extension or access to /dev/urandom.

Installation

Download the files and include them in your application.

Usage

Escaping strings for HTML

Use Escaping::escapeHTML() to prepare a string for an HTML context. This method replaces the characters <, >, ", ' and & with HTML entities to prevent cross-site scripting attacks.

Apart from the input string, you also have to specify the character encoding to be used. It has to match the document encoding as defined in the Content-Type header or a corresponding meta element.

$input = 'This will be escaped and shows up literally: <hr>';
$documentEncoding = 'UTF-8';

echo Escaping::escapeHTML($input, $documentEncoding);

Note: Do not insert PHP values into a JavaScript or CSS context like a script element or a style attribute. This is never secure.

Password hashes

php-litesec currently uses the bcrypt algorithm to hash passwords.

To create a hash from a plaintext password, call PasswordHash::create() with the password and a cost factor:

$password = 'test';
$cost = 12;

$hash = PasswordHash::create($password, $cost);

echo 'The resulting hash is ' . $hash->getHash();

The higher the cost factor, the more difficult it is for an attacker to break the hash by trying out different passwords. But a high cost factor will also stress your server and cause a delay on all pages which involve password hashing. Try out different values to find a balance between security and performance. The minimum value should be 10.

In the rare case that you cannot provide any of the randomness sources listed under the requirements, you have to generate the cryptographic salts yourself and pass them as the third argument. This is not recommended unless you know what you are doing. The salt must be a binary string with exactly 16 randomly generated bytes. Make sure to choose an appropriate source which is equivalent to /dev/urandom.

The hashes consist of exactly 60 ASCII-encoded characters. To resume an existing hash, use PasswordHash::resume():

// this is an example hash of the password "test"
$storedHash = '$2y$10$.Y9gszppmWDzCEnJhbxoJOoj7zt5u2zGLfmXr/KV/ARhyIttupFTG';

$hash = PasswordHash::resume($storedHash);

You can then check passwords with $hash->check():

$password = 'test';

if ($hash->check($password))
    echo 'The password "test" is correct.';
else
    echo 'The password "test" is wrong.';

Generating random numbers

Functions like rand(), mt_rand() or uniqid() are not suitable for security purposes, because they produce weak random numbers which can potentially be predicted. Use the Random class to get stronger random numbers. Note, however, that the results are not guaranteed to be cryptographically secure, so do not use them for encryption.

Call Random::generateBytes() to get a binary string containing a certain number of pseudo-random bytes:

$binaryRand = Random::generateBytes(16);

You can also generate a hexadecimal string instead:

$hexRand = Random::generateHexBytes(16);

echo 'The result is ' . $hexRand;