1## CMAC 2 3The `CMAC` class provides functions for creating a block cipher-based message 4authentication code (CMAC). It allows to choose an underlaying block 5cipher algorithm. 6 7The `CMAC` class extends `MAC` class which extends [`Hash`](hash.md) class. It 8means that with exception of a constructor all methods are inherited 9from [`Hash`](hash.md) class. 10 11### Instance Methods 12 13#### `CMAC::__construct($key, $algorithm)` 14 15_**Description**_: Creates a new `CMAC` class if supplied algorithm is supported. 16 17The constructor first checks if the algorithm is found. If not, then 18`MACException` is thrown. Otherwise a new instance of `CMAC` is created. 19 20The key length is compared with the underlaying cipher block size if it's 21not equal, then `MACException` is thrown. 22 23##### *Parameters* 24 25*key* : `key` - the key string 26*algorithm* : `string` - the cipher algorithm name (e.g. `aes-128-cbc`) 27 28##### *Return value* 29 30`CMAC`: New instances of the `CMAC` class. 31 32##### *Throws* 33 34It can throw `MACException` with code 35 36- `MACException::HASH_ALGORITHM_NOT_FOUND` - the supplied algorithm is not found 37- `MACException::KEY_LENGTH_INVALID` - the supplied key length is incorrect 38 39##### *Examples* 40 41```php 42$cmac = new \Crypto\CMAC('key', 'aes-128-cbc'); 43``` 44 45If the algorithm is passed by user in variable, then it might be a good idea to 46wrap it in a try/catch block: 47```php 48try { 49 $cmac = new \Crypto\CMAC($key, $cipher_algorithm); 50} 51catch (\Crypto\MACException $e) { 52 echo $e->getMessage(); 53} 54``` 55 56#### `CMAC::digest()` 57 58_**Description**_: Returns a MAC in binary encoding 59 60This method returns a binary message authentication code (MAC). 61It also finalizes the CMAC context which means that if 62`CMAC::update` is called again, then the context is 63reinitialized - the result is the same like creating a new object 64using the same algorithm and key and then calling `CMAC::update`. 65 66If the `CMAC` object has not been updated, then the result will 67be a CMAC for an empty string. 68 69##### *Parameters* 70 71This method has no parameters. 72 73##### *Throws* 74 75It can throw `HashException` with code 76 77- `HashException::INIT_FAIED` - initialization failed 78- `HashException::DEGEST_FAIED` - creating digest failed 79 80##### *Return value* 81 82`string`: The MAC binary string with length equal to 83the result of `CMAC::getSize()` 84 85##### *Examples* 86 87```php 88$cmac = new \Crypto\CMAC('key', 'aes-128-cbc'); 89$digest = $cmac->update('abc')->digest(); 90``` 91 92#### `CMAC::getAlgorithmName()` 93 94_**Description**_: Returns an underlaying cipher algorithm name. 95 96It is a getter for internal inherited `Hash::$algorithm` 97reod only property which is set during the object construction. 98 99##### *Parameters* 100 101This method has no parameters. 102 103##### *Throws* 104 105This method does not throw any exception. 106 107##### *Return value* 108 109`string`: The name of the underlaying cipher (e.g. `aes-128-cbc`) 110 111##### *Examples* 112 113```php 114$cmac = new \Crypto\CMAC('key', 'aes-128-cbc'); 115// this will output AES-128-CBC 116echo $cmac->getAlgorithmName(); 117``` 118 119#### `CMAC::getBlockSize()` 120 121_**Description**_: Returns an underlaying cipher block size in bytes. 122 123This method returns a block size of the underlaying cipher algorithm. 124 125##### *Parameters* 126 127This method has no parameters. 128 129##### *Throws* 130 131This method does not throw any exception. 132 133##### *Return value* 134 135`int`: underlaying cipher block size in bytes 136 137##### *Examples* 138 139```php 140$cmac = new \Crypto\CMAC('key', 'aes-128-cbc'); 141// this will output 16 142echo $cmac->getBlockSize(); 143``` 144 145#### `CMAC::getSize()` 146 147_**Description**_: Returns an output size of the MAC in bytes. 148 149This method returns the output size of the message authentication code. 150The output size for CMAC is equal to the block size of the underlaying 151cipher. It means that it returns the same value as `CMAC::getBlockSize`. 152 153##### *Parameters* 154 155This method has no parameters. 156 157##### *Throws* 158 159This method does not throw any exception. 160 161##### *Return value* 162 163`int`: underlaying hash output size in bytes 164 165##### *Examples* 166 167```php 168$hash = new \Crypto\CMAC('key', 'aes-128-cbc'); 169// this will output 16 170echo $hash->getSize(); 171``` 172 173#### `CMAC::hexdigest()` 174 175_**Description**_: Returns a MAC in hex encoding. 176 177This method returns a message authentication code. It also 178finalizes the `CMAC` context which means that if `Hash::update` 179is called again, then the context is reinitialized - the result 180is the same like creating a new object using the same algorithm 181and then calling `Hash::update` on it. 182 183If the `CMAC` object has not been updated, then the result will 184be a CMAC for an empty string. 185 186##### *Parameters* 187 188This method has no parameters. 189 190##### *Throws* 191 192It can throw `HashException` with code 193 194- `HashException::INIT_FAIED` - initialization failed 195- `HashException::DEGEST_FAIED` - creating digest failed 196 197##### *Return value* 198 199`string`: message authentication code hex string 200 201##### *Examples* 202 203```php 204$cmac = new \Crypto\CMAC('key', 'aes-128-cbc'); 205echo $cmac->update('abc')->hexdigest(); 206``` 207 208#### `CMAC::update($data)` 209 210_**Description**_: Updates the CMAC object with supplied data 211 212This method updates `CMAC` object context with supplied data. It can 213be useful when reading data from database or big files. 214 215Before the update, it also initializes the internal context if it's 216the first update. If the initialization or update fails, the exception 217is thrown. 218 219##### *Parameters* 220 221*data* : `string` - data that updates the CMAC 222 223##### *Throws* 224 225It can throw `HashException` with code 226 227- `HashException::INIT_FAIED` - initialization failed 228- `HashException::UPDATE_FAIED` - updating CMAC failed 229 230##### *Return value* 231 232`CMAC`: An instance of the called object (for chaining) 233 234##### *Examples* 235 236```php 237try { 238 $key = pack('H*', '2b7e151628aed2a6abf7158809cf4f3c'); 239 $cmac = new \Crypto\CMAC($key, 'aes-128-cbc'); 240 while (($data = read_data_from_somewhere()) !== false) { 241 $cmac->update($data); 242 } 243 echo $cmac->hexdigest(); 244} catch (\Crypto\MACException $e) { 245 echo $e->getMessage(); 246} 247``` 248