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