MAC

MAC algorithms

A MAC algorithm accepts as input a secret key and an arbitrary-length message to be authenticated, and outputs a MAC (sometimes known as a tag). A message authentication code (MAC) is a short piece of information used to authenticate a message and to provide integrity and authenticity assurances on the message. Integrity assurances detect accidental and intentional message changes, while authenticity assurances affirm the message's origin.

Usage

MAC classes implements the Cryptopp\MacInterface interface.

$o = new Cryptopp\MacHmac(new Cryptopp\HashSha1());

// returns the name of the MAC algorithm
$o->getName();

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

Calculate a MAC tag

To calculate the MAC tag of a string, use the calculateDigest() method :

$o   = new Cryptopp\MacHmac(new Cryptopp\HashSha1());
$o->setKey("your secret key");
$tag = $o->calculateDigest("your data");

The MAC tag 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 :

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

Incremental calculation

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

$o = new Cryptopp\MacHmac(new Cryptopp\HashSha1());
$o->setKey("your secret key");

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

// is equivalent to
$tag = $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 MAC tag as the previous snippet :

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

$o->restart();

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

Extending

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

class MyHmac extends Cryptopp\MacHmac
{
    public function __construct(Cryptopp\HashInterface $hash)
    {
        parent::__construct($hash);
    }

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

$o = new MyHmac(new Cryptopp\HashSha1());

Create a MAC class

You can create your own MAC class by implementing the Cryptopp\MacInterface 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
setKey($key)	Sets the key
getKey()	Returns the key
isValidKeyLength($length)	Indicates if a given key length is valid for this algorithm

MAC classes

HMAC

A keyed-hash message authentication code (HMAC) is a specific construction for calculating a message authentication code (MAC) involving a cryptographic hash function in combination with a secret cryptographic key. The cryptographic strength of the HMAC depends upon the cryptographic strength of the underlying hash function, the size of its hash output, and on the size and quality of the key. This is one of the most used MAC algorithm.

• Class : Cryptopp\MacHmac
  • Constructor accepts any instance of Cryptopp\HashInterface
• Digest size : Digest size of the underlying hash function (eg: 20 bytes for SHA1)
• Key size : any
  • Recommended key size is the digest size
  • Key size shorter than digest size decrease security
  • Key size larger than digest size does not increase security

Note that although SHA3 can be used, there is not any standard for HMAC-SHA3 so the correctness of the generated tag cannot be guaranteed and is subject to change if an official standard is published.

$hash = new Cryptopp\HashSha1();
$hmac = new Cryptopp\MacHmac($hash);

Two-Track-MAC

The Two-Track-MAC algorithm is based on the RIPEMD-160 hash function.

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