This is the README for the secure_hash class written by Julius Beckmann in PHP.

I created this class because there are many people still saving simple md5 
instead of more secure hashes.

The class should be fully PHP4 and PHP5 compatible.

The usage of the class should be straight forward.
If you just want to use it, use the methods hash() and check().
EXAMPLE:
$secure_hash = new secure_hash;
$hash = $secure_hash->hash('pass');
if($secure_hash->check($hash, 'pass')) 
	echo "Password fits to hash.";
else
	echo "Password does NOT fit to hash.";
	
Thats all you need to know for just using it, but i have to tell you,
you will miss something important if you stop reading here.

There are several other things included for making hashes from this class 
even more secure.
First to know is the principle behind the class. A normal md5() is just 
one operation. Todays computer can millions of them in a second (!).
So what to do? You can use sha1() but this is still the same problem.
So we need a techniqe to slow the hashing process down to a timeframe a 
brute force attack would be much too ineffective.

We generated our example hash:
$sha1$~=<=/<_%=|$71$bdf6a4a8bb2914f6152f31eabf34fd4b8b7f4a74$

The format of the hash is:
delimiter = $
$ hashing-mehtod $ salt $ interations $ hash $

First step for solving this problem is: using salts.
A salt is some random string that is appended to the password to make it 
more complex. This class generates random salts so rainbowtables will be useless.
In the formated hash the salt is ~=<=/<_%=|.
You can configure length of the salt with:
var $salt_len = 4;
Hint: A much longer salt does NOT result a way more secure hash. 
The salt needs to be stored too so better leave it at 4.

Second step is: random iterations.
Each hash gets rehashed n times. This makes cracking the hash very difficult 
because you need specialized software for hashes from this class.
Also doing more iterations will take longer, too long for current hardware.
In the formated hash the number of iterations is 71 ($71$).
You can configure this with:
var $iter_min = 10;
var $iter_max = 99;

Third step: Using unusual hashmethods
Our example hash is done with sha1 ($sha1$), but it is also possible to write
own hashing methods an attacker needs to know first.
Check out "secure_hash_example" for an example.
You can change hash method with:
var $hashing_method = 'sha1';

Forth step is: a global salt.
Each password gets its own salt, that is great. But we have to save the salt 
inside our formated hash. That is baaad because the attacker will get it too.
So lets define something the attacker can NOT get with a SQL-Injection.
We define a globale salt. This has to be done BEFORE the hashes get created. 
This values should NOT CHANGE, or your hashes get incorrect.
So if you want to use a global salt, define it BEFORE FIRST USE and let it stay!
var $salt_global = '';

Fifth step: using permutations.
A permutation is something like this:
The rules this class uses look like "abc|cab". 
This means, the "a" will become "c", "b"->"a" and "c"->"b".
The principe is something like shuffling the string with a defined rule.
This is another thing the attacker needs to know if he wants to crack our hashes.
This feature has to be defined BEFORE FIRST USE! and then let it stay!
Otherwise your hashes will become incorrect.
You can define your own permutations at:
var $permutate = true;
var $permutations = array(.....);
There is also a method for creating permutations:
function _new_permutation();


If you use all these steps you will have a fine solution for the problem with
common hashes. Storing a hash created by this class with all its features 
enabled should be safe way to store your users passwords.

Thanks for reading so far.

Hope you enjoy my work.
Get in touch if you have questions or hints.

Regards, Julius Beckmann.