Hash

Hash functions

A hash function is a transformation that takes a variable-size input and returns a fixed-size string called the message digest. In cryptography, a hash function is considered impossible to invert, that is, to recreate the input data from its hash value alone.

Usage

Hash classes implements the Cryptopp\HashInterface interface.

$o = new Cryptopp\HashSha1();

// returns the name of the hash function
$o->getName();

// returns the message digest size
$o->getDigestSize();

Calculate a message digest

To calculate the message digest of a string, use the calculateDigest() method :

$o      = new Cryptopp\HashSha1();
$digest = $o->calculateDigest("your string");

The message digest is returned in its binary form, and thus might be not displayable (you'll see strange characters). If you want to show it on the screen, you can convert it to its hexadecimal form using the bin2hex() PHP function :

$hexDigest = bin2hex($digest);
var_dump($hexDigest);
// will output something like: string(40) "b0399d2029f64d445bd131ffaa399a42d2f8e7dc"

Incremental calculation

You are not required to pass a single string to calculate a message digest. The update() and finalize() methods allows you to pass your data in several pieces :

$o = new Cryptopp\HashSha1();
$o->update("first piece");
$o->update("second piece");
$o->update("third piece");
$digest = $o->finalize();

// is equivalent to
$digest = $o->calculateDigest("first piecesecond piecethird piece");

The finalize() method resets the current state automatically. You can reset it yourself if you want with the restart() method. The following code snippet will produce the same message digest as the previous snippet :

$o = new Cryptopp\HashSha1();
$o->update("data that I don't want");

$o->restart();

$o->update("first piece");
$o->update("second piece");
$o->update("third piece");
$digest = $o->finalize();

Extending

Extending a hash class is possible to add some methods, but existing methods are not overwritable. Also, you are required to call the parent constructor.

class MySha1 extends Cryptopp\HashSha1
{
    public function __construct()
    {
        parent::__construct();
    }

    public function myMethod()
    {
        // ...
    }
}

$o = new MySha1();

Create a hash class

You can create your own hash class by implementing the Cryptopp\HashInterface interface. The following methods are required :

Method signature	Descritption
getName()	Returns algorithm name
getDigestSize()	Returns digest size (in bytes)
getBlockSize()	Returns block size (in bytes)
calculateDigest($data)	Calculate the digest of a given string
update($data)	Adds data to current incremental digest calculation
finalize()	Finalize current incremental digest calculation and return the resulting digest
restart()	Resets current incremental digest calculation

Hash classes

MD5

The Message Digest 5 (MD5) algorithm is a widely used cryptographic hash function commonly used to verify data integrity. In 2004 it was shown that MD5 is not collision resistant, and more serious flaws were discovered. The use of MD5 for security purposes is strongly discouraged.

• Class : Cryptopp\HashMd5
• Digest size : 128 bits (16 bytes)

SHA1

The Secure Hash Algorithm 1 (SHA1) is a cryptographic hash function is the most widely used of the existing SHA hash functions, and is employed in several widely used applications and protocols. In 2005, cryptanalysts found attacks on SHA-1 suggesting that the algorithm might not be secure enough for ongoing use. Thus, the use of SHA1 for security purposes is discouraged.

• Class : Cryptopp\HashSha1
• Digest size : 160 bits (20 bytes)

SHA3

SHA-3, a subset of the cryptographic primitive family Keccak, is a cryptographic hash function designed by Guido Bertoni, Joan Daemen, Michaël Peeters, and Gilles Van Assche. On October 2012, Keccak was selected as the winner of the NIST hash function competition.

SHA3-224

• Class : Cryptopp\HashSha3_224
• Digest size : 224 bits (28 bytes)

SHA3-256

• Class : Cryptopp\HashSha3_256
• Digest size : 256 bits (32 bytes)

SHA3-384

• Class : Cryptopp\HashSha3_384
• Digest size : 384 bits (48 bytes)

SHA3-512

• Class : Cryptopp\HashSha3_512
• Digest size : 512 bits (64 bytes)