Skip to content

Latest commit

 

History

History
253 lines (164 loc) · 6.24 KB

hmac.md

File metadata and controls

253 lines (164 loc) · 6.24 KB
Raw

HMAC

The HMAC class provides functions for creating a keyed-hash message authentication code (HMAC) message digest from a supplied key and block of data. It allows to choose a message digest algorithm.

The HMAC class extends MAC class which extends Hash class. It means that with an exception of the constructor all methods are inherited from Hash class.

Instance Methods

HMAC::__construct($key, $algorithm)

Description: Creates a new HMAC class if supplied algorithm is supported.

The constructor first checks if the algorithm is found. If not, then MACException is thrown. Otherwise a new instance of HMAC is created.

The key length is compared with block size:

  • if the key length is the same as block size, then the key is used as it is
  • if the key length is smaller, then the key is padded with zero bytes to the block size
  • if the key length is greater, then the key is hashed (unless it's greater than C INT_MAX)
  • if the key length is greater then C INT_MAX, then the exception is thrown
Parameters

key : string - the key string algorithm : string - the algorithm name (e.g. sha256, sha512, md5)

Return value

HMAC: New instances of the HMAC class.

Throws

It can throw MACException with code

  • MACException::HASH_ALGORITHM_NOT_FOUND - the supplied algorithm is not found
  • MACException::KEY_LENGTH_INVALID - the supplied key length is too high (over C INT_MAX)
Examples
$hmac = new \Crypto\HMAC('key', 'sha256');

If the algorithm is passed by user in variable, then it might be a good idea to wrap it in a try/catch block:

try {
    $hmac = new \Crypto\HMAC($key, $hash_algorithm);
}
catch (\Crypto\HashException $e) {
    echo $e->getMessage();
}

HMAC::digest()

Description: Returns a MAC in binary encoding

This method returns a binary message authentication code (MAC). It also finalizes the HMAC context which means that if HMAC::update is called again, then the context is reinitialized - the result is the same like creating a new object using the same algorithm and key and then calling HMAC::update.

If the HMAC object has not been updated, then the result will be a HMAC for an empty string.

Parameters

This method has no parameters.

Throws

It can throw HashException with code

  • HashException::INIT_FAIED - initialization failed
  • HashException::DEGEST_FAIED - creating digest failed
Return value

string: The MAC binary string with length equal to the result of HMAC::getSize()

Examples
$hmac = new \Crypto\HMAC('key', 'sha256');
$digest = $hmac->update('abc')->digest();

HMAC::getAlgorithmName()

Description: Returns an underlaying hash algorithm name.

It is a getter for internal inherited Hash::$algorithm reod only property which is set during the object construction.

Parameters

This method has no parameters.

Throws

This method does not throw any exception.

Return value

string: The name of the underlaying hash algorithm (e.g. sha256)

Examples
$hmac = new \Crypto\HMAC('key', 'sha256');
// this will output SHA256
echo $hmac->getAlgorithmName();

HMAC::getBlockSize()

Description: Returns an underlaying hash block size in bytes.

This method returns a block size of the underlaying hash algorithm. That should not be confused with the output size (which is returned by HMAC::getSize()). The block size is a size that the hash algorithm operates on and it is bigger than output size (e.g. 64 bytes which is 512 bits for SHA256).

Parameters

This method has no parameters.

Throws

This method does not throw any exception.

Return value

int: underlaying hash block size in bytes

Examples
$hmac = new \Crypto\HMAC('key', 'sha256');
// this will output 64
echo $hmac->getBlockSize();

HMAC::getSize()

Description: Returns an underlaying hash output size in bytes.

This method returns the output size of the underlaying hash algorithm. It means how many bytes will be returned by the HMAC::digest() method.

Parameters

This method has no parameters.

Throws

This method does not throw any exception.

Return value

int: underlaying hash output size in bytes

Examples
$hash = new \Crypto\HMAC('key', 'sha256');
// this will output 32
echo $hash->getSize();

HMAC::hexdigest()

Description: Returns a MAC in hex encoding.

This method returns a message authentication code. It also finalizes the HMAC context which means that if Hash::update is called again, then the context is reinitialized - the result is the same like creating a new object using the same algorithm and then calling Hash::update on it.

If the HMAC object has not been updated, then the result will be a HMAC for an empty string.

Parameters

This method has no parameters.

Throws

It can throw HashException with code

  • HashException::INIT_FAIED - initialization failed
  • HashException::DEGEST_FAIED - creating digest failed
Return value

string: message authentication code hex string

Examples
$hmac = new \Crypto\HMAC('key', 'sha256');
echo $hmac->update('abc')->hexdigest();

HMAC::update($data)

Description: Updates the HMAC object with supplied data

This method updates HMAC object context with supplied data. It can be useful when reading data from database or big files.

Before the update, it also initializes the internal context if it's the first update. If the initialization or update fails, the exception is thrown.

Parameters

data : string - data that updates the HMAC

Throws

It can throw HashException with code

  • HashException::INIT_FAIED - initialization failed
  • HashException::UPDATE_FAIED - updating HMAC failed
Return value

HMAC: An instance of the called object (for chaining)

Examples
try {
    $key = 'secret_key';
    $hmac = new \Crypto\HMAC($key, 'sha256');
    while (($data = read_data_from_somewhere()) !== false) {
        $hmac->update($data);
    }
    echo $hmac->hexdigest();
} catch (\Crypto\HashException $e) {
    echo $e->getMessage();
}