1
|
|
|
<?php |
2
|
|
|
/** |
3
|
|
|
* @link http://www.yiiframework.com/ |
4
|
|
|
* @copyright Copyright (c) 2008 Yii Software LLC |
5
|
|
|
* @license http://www.yiiframework.com/license/ |
6
|
|
|
*/ |
7
|
|
|
|
8
|
|
|
namespace yii\base; |
9
|
|
|
|
10
|
|
|
use Yii; |
11
|
|
|
use yii\helpers\StringHelper; |
12
|
|
|
|
13
|
|
|
/** |
14
|
|
|
* Security provides a set of methods to handle common security-related tasks. |
15
|
|
|
* |
16
|
|
|
* In particular, Security supports the following features: |
17
|
|
|
* |
18
|
|
|
* - Encryption/decryption: [[encryptByKey()]], [[decryptByKey()]], [[encryptByPassword()]] and [[decryptByPassword()]] |
19
|
|
|
* - Key derivation using standard algorithms: [[pbkdf2()]] and [[hkdf()]] |
20
|
|
|
* - Data tampering prevention: [[hashData()]] and [[validateData()]] |
21
|
|
|
* - Password validation: [[generatePasswordHash()]] and [[validatePassword()]] |
22
|
|
|
* |
23
|
|
|
* > Note: this class requires 'OpenSSL' PHP extension for random key/string generation on Windows and |
24
|
|
|
* for encryption/decryption on all platforms. For the highest security level PHP version >= 5.5.0 is recommended. |
25
|
|
|
* |
26
|
|
|
* For more details and usage information on Security, see the [guide article on security](guide:security-overview). |
27
|
|
|
* |
28
|
|
|
* @author Qiang Xue <[email protected]> |
29
|
|
|
* @author Tom Worster <[email protected]> |
30
|
|
|
* @author Klimov Paul <[email protected]> |
31
|
|
|
* @since 2.0 |
32
|
|
|
*/ |
33
|
|
|
class Security extends Component |
34
|
|
|
{ |
35
|
|
|
/** |
36
|
|
|
* @var string The cipher to use for encryption and decryption. |
37
|
|
|
*/ |
38
|
|
|
public $cipher = 'AES-128-CBC'; |
39
|
|
|
/** |
40
|
|
|
* @var array[] Look-up table of block sizes and key sizes for each supported OpenSSL cipher. |
41
|
|
|
* |
42
|
|
|
* In each element, the key is one of the ciphers supported by OpenSSL (@see openssl_get_cipher_methods()). |
43
|
|
|
* The value is an array of two integers, the first is the cipher's block size in bytes and the second is |
44
|
|
|
* the key size in bytes. |
45
|
|
|
* |
46
|
|
|
* > Warning: All OpenSSL ciphers that we recommend are in the default value, i.e. AES in CBC mode. |
47
|
|
|
* |
48
|
|
|
* > Note: Yii's encryption protocol uses the same size for cipher key, HMAC signature key and key |
49
|
|
|
* derivation salt. |
50
|
|
|
*/ |
51
|
|
|
public $allowedCiphers = [ |
52
|
|
|
'AES-128-CBC' => [16, 16], |
53
|
|
|
'AES-192-CBC' => [16, 24], |
54
|
|
|
'AES-256-CBC' => [16, 32], |
55
|
|
|
]; |
56
|
|
|
/** |
57
|
|
|
* @var string Hash algorithm for key derivation. Recommend sha256, sha384 or sha512. |
58
|
|
|
* @see [hash_algos()](https://secure.php.net/manual/en/function.hash-algos.php) |
59
|
|
|
*/ |
60
|
|
|
public $kdfHash = 'sha256'; |
61
|
|
|
/** |
62
|
|
|
* @var string Hash algorithm for message authentication. Recommend sha256, sha384 or sha512. |
63
|
|
|
* @see [hash_algos()](https://secure.php.net/manual/en/function.hash-algos.php) |
64
|
|
|
*/ |
65
|
|
|
public $macHash = 'sha256'; |
66
|
|
|
/** |
67
|
|
|
* @var string HKDF info value for derivation of message authentication key. |
68
|
|
|
* @see hkdf() |
69
|
|
|
*/ |
70
|
|
|
public $authKeyInfo = 'AuthorizationKey'; |
71
|
|
|
/** |
72
|
|
|
* @var int derivation iterations count. |
73
|
|
|
* Set as high as possible to hinder dictionary password attacks. |
74
|
|
|
*/ |
75
|
|
|
public $derivationIterations = 100000; |
76
|
|
|
/** |
77
|
|
|
* @var string strategy, which should be used to generate password hash. |
78
|
|
|
* Available strategies: |
79
|
|
|
* - 'password_hash' - use of PHP `password_hash()` function with PASSWORD_DEFAULT algorithm. |
80
|
|
|
* This option is recommended, but it requires PHP version >= 5.5.0 |
81
|
|
|
* - 'crypt' - use PHP `crypt()` function. |
82
|
|
|
* @deprecated since version 2.0.7, [[generatePasswordHash()]] ignores [[passwordHashStrategy]] and |
83
|
|
|
* uses `password_hash()` when available or `crypt()` when not. |
84
|
|
|
*/ |
85
|
|
|
public $passwordHashStrategy; |
86
|
|
|
/** |
87
|
|
|
* @var int Default cost used for password hashing. |
88
|
|
|
* Allowed value is between 4 and 31. |
89
|
|
|
* @see generatePasswordHash() |
90
|
|
|
* @since 2.0.6 |
91
|
|
|
*/ |
92
|
|
|
public $passwordHashCost = 13; |
93
|
|
|
/** |
94
|
|
|
* @var boolean if LibreSSL should be used. |
95
|
|
|
* The recent (> 2.1.5) LibreSSL RNGs are faster and likely better than /dev/urandom. |
96
|
|
|
*/ |
97
|
|
|
private $_useLibreSSL; |
98
|
|
|
|
99
|
|
|
|
100
|
|
|
/** |
101
|
|
|
* @return boolean if LibreSSL should be used |
102
|
|
|
* Use version is 2.1.5 or higher. |
103
|
|
|
* @since 2.0.36 |
104
|
|
|
*/ |
105
|
|
|
protected function shouldUseLibreSSL() |
106
|
|
|
{ |
107
|
|
|
if ($this->_useLibreSSL === null) { |
108
|
|
|
// Parse OPENSSL_VERSION_TEXT because OPENSSL_VERSION_NUMBER is no use for LibreSSL. |
109
|
|
|
// https://bugs.php.net/bug.php?id=71143 |
110
|
|
|
$this->_useLibreSSL = defined('OPENSSL_VERSION_TEXT') |
111
|
1 |
|
&& preg_match('{^LibreSSL (\d\d?)\.(\d\d?)\.(\d\d?)$}', OPENSSL_VERSION_TEXT, $matches) |
112
|
|
|
&& (10000 * $matches[1]) + (100 * $matches[2]) + $matches[3] >= 20105; |
113
|
1 |
|
} |
114
|
|
|
|
115
|
|
|
return $this->_useLibreSSL; |
116
|
|
|
} |
117
|
|
|
|
118
|
|
|
/** |
119
|
|
|
* @return bool if operating system is Windows |
120
|
|
|
*/ |
121
|
|
|
private function isWindows() |
122
|
|
|
{ |
123
|
|
|
return DIRECTORY_SEPARATOR !== '/'; |
124
|
|
|
} |
125
|
|
|
|
126
|
|
|
/** |
127
|
|
|
* Encrypts data using a password. |
128
|
|
|
* Derives keys for encryption and authentication from the password using PBKDF2 and a random salt, |
129
|
|
|
* which is deliberately slow to protect against dictionary attacks. Use [[encryptByKey()]] to |
130
|
1 |
|
* encrypt fast using a cryptographic key rather than a password. Key derivation time is |
131
|
|
|
* determined by [[$derivationIterations]], which should be set as high as possible. |
132
|
1 |
|
* The encrypted data includes a keyed message authentication code (MAC) so there is no need |
133
|
|
|
* to hash input or output data. |
134
|
|
|
* > Note: Avoid encrypting with passwords wherever possible. Nothing can protect against |
135
|
|
|
* poor-quality or compromised passwords. |
136
|
|
|
* @param string $data the data to encrypt |
137
|
|
|
* @param string $password the password to use for encryption |
138
|
|
|
* @return string the encrypted data as byte string |
139
|
|
|
* @see decryptByPassword() |
140
|
|
|
* @see encryptByKey() |
141
|
|
|
*/ |
142
|
10 |
|
public function encryptByPassword($data, $password) |
143
|
|
|
{ |
144
|
10 |
|
return $this->encrypt($data, true, $password, null); |
145
|
|
|
} |
146
|
|
|
|
147
|
|
|
/** |
148
|
|
|
* Encrypts data using a cryptographic key. |
149
|
|
|
* Derives keys for encryption and authentication from the input key using HKDF and a random salt, |
150
|
|
|
* which is very fast relative to [[encryptByPassword()]]. The input key must be properly |
151
|
|
|
* random -- use [[generateRandomKey()]] to generate keys. |
152
|
|
|
* The encrypted data includes a keyed message authentication code (MAC) so there is no need |
153
|
|
|
* to hash input or output data. |
154
|
|
|
* @param string $data the data to encrypt |
155
|
10 |
|
* @param string $inputKey the input to use for encryption and authentication |
156
|
|
|
* @param string $info optional context and application specific information, see [[hkdf()]] |
157
|
10 |
|
* @return string the encrypted data as byte string |
158
|
|
|
* @see decryptByKey() |
159
|
|
|
* @see encryptByPassword() |
160
|
|
|
*/ |
161
|
|
|
public function encryptByKey($data, $inputKey, $info = null) |
162
|
|
|
{ |
163
|
|
|
return $this->encrypt($data, false, $inputKey, $info); |
164
|
|
|
} |
165
|
|
|
|
166
|
|
|
/** |
167
|
|
|
* Verifies and decrypts data encrypted with [[encryptByPassword()]]. |
168
|
|
|
* @param string $data the encrypted data to decrypt |
169
|
|
|
* @param string $password the password to use for decryption |
170
|
|
|
* @return bool|string the decrypted data or false on authentication failure |
171
|
|
|
* @see encryptByPassword() |
172
|
|
|
*/ |
173
|
|
|
public function decryptByPassword($data, $password) |
174
|
2 |
|
{ |
175
|
|
|
return $this->decrypt($data, true, $password, null); |
176
|
2 |
|
} |
177
|
|
|
|
178
|
|
|
/** |
179
|
2 |
|
* Verifies and decrypts data encrypted with [[encryptByKey()]]. |
180
|
|
|
* @param string $data the encrypted data to decrypt |
181
|
|
|
* @param string $inputKey the input to use for encryption and authentication |
182
|
|
|
* @param string $info optional context and application specific information, see [[hkdf()]] |
183
|
2 |
|
* @return bool|string the decrypted data or false on authentication failure |
184
|
|
|
* @see encryptByKey() |
185
|
2 |
|
*/ |
186
|
2 |
|
public function decryptByKey($data, $inputKey, $info = null) |
187
|
1 |
|
{ |
188
|
|
|
return $this->decrypt($data, false, $inputKey, $info); |
189
|
1 |
|
} |
190
|
|
|
|
191
|
|
|
/** |
192
|
2 |
|
* Encrypts data. |
193
|
|
|
* |
194
|
2 |
|
* @param string $data data to be encrypted |
195
|
2 |
|
* @param bool $passwordBased set true to use password-based key derivation |
196
|
|
|
* @param string $secret the encryption password or key |
197
|
|
|
* @param string|null $info context/application specific information, e.g. a user ID |
198
|
|
|
* See [RFC 5869 Section 3.2](https://tools.ietf.org/html/rfc5869#section-3.2) for more details. |
199
|
2 |
|
* |
200
|
2 |
|
* @return string the encrypted data as byte string |
201
|
|
|
* @throws InvalidConfigException on OpenSSL not loaded |
202
|
|
|
* @throws Exception on OpenSSL error |
203
|
|
|
* @see decrypt() |
204
|
|
|
*/ |
205
|
|
|
protected function encrypt($data, $passwordBased, $secret, $info) |
206
|
|
|
{ |
207
|
|
|
if (!extension_loaded('openssl')) { |
208
|
2 |
|
throw new InvalidConfigException('Encryption requires the OpenSSL PHP extension'); |
209
|
|
|
} |
210
|
|
|
if (!isset($this->allowedCiphers[$this->cipher][0], $this->allowedCiphers[$this->cipher][1])) { |
211
|
|
|
throw new InvalidConfigException($this->cipher . ' is not an allowed cipher'); |
212
|
|
|
} |
213
|
|
|
|
214
|
|
|
list($blockSize, $keySize) = $this->allowedCiphers[$this->cipher]; |
215
|
|
|
|
216
|
|
|
$keySalt = $this->generateRandomKey($keySize); |
217
|
|
|
if ($passwordBased) { |
218
|
|
|
$key = $this->pbkdf2($this->kdfHash, $secret, $keySalt, $this->derivationIterations, $keySize); |
219
|
|
|
} else { |
220
|
|
|
$key = $this->hkdf($this->kdfHash, $secret, $keySalt, $info, $keySize); |
221
|
|
|
} |
222
|
|
|
|
223
|
|
|
$iv = $this->generateRandomKey($blockSize); |
224
|
20 |
|
|
225
|
|
|
$encrypted = openssl_encrypt($data, $this->cipher, $key, OPENSSL_RAW_DATA, $iv); |
226
|
20 |
|
if ($encrypted === false) { |
227
|
|
|
throw new \yii\base\Exception('OpenSSL failure on encryption: ' . openssl_error_string()); |
228
|
|
|
} |
229
|
20 |
|
|
230
|
|
|
$authKey = $this->hkdf($this->kdfHash, $key, null, $this->authKeyInfo, $keySize); |
231
|
|
|
$hashed = $this->hashData($iv . $encrypted, $authKey); |
232
|
|
|
|
233
|
20 |
|
/* |
234
|
|
|
* Output: [keySalt][MAC][IV][ciphertext] |
235
|
20 |
|
* - keySalt is KEY_SIZE bytes long |
236
|
20 |
|
* - MAC: message authentication code, length same as the output of MAC_HASH |
237
|
10 |
|
* - IV: initialization vector, length $blockSize |
238
|
|
|
*/ |
239
|
10 |
|
return $keySalt . $hashed; |
240
|
|
|
} |
241
|
|
|
|
242
|
20 |
|
/** |
243
|
20 |
|
* Decrypts data. |
244
|
20 |
|
* |
245
|
2 |
|
* @param string $data encrypted data to be decrypted. |
246
|
|
|
* @param bool $passwordBased set true to use password-based key derivation |
247
|
|
|
* @param string $secret the decryption password or key |
248
|
20 |
|
* @param string|null $info context/application specific information, @see encrypt() |
249
|
20 |
|
* |
250
|
|
|
* @return bool|string the decrypted data or false on authentication failure |
251
|
20 |
|
* @throws InvalidConfigException on OpenSSL not loaded |
252
|
20 |
|
* @throws Exception on OpenSSL error |
253
|
|
|
* @see encrypt() |
254
|
|
|
*/ |
255
|
|
|
protected function decrypt($data, $passwordBased, $secret, $info) |
256
|
20 |
|
{ |
257
|
|
|
if (!extension_loaded('openssl')) { |
258
|
|
|
throw new InvalidConfigException('Encryption requires the OpenSSL PHP extension'); |
259
|
|
|
} |
260
|
|
|
if (!isset($this->allowedCiphers[$this->cipher][0], $this->allowedCiphers[$this->cipher][1])) { |
261
|
|
|
throw new InvalidConfigException($this->cipher . ' is not an allowed cipher'); |
262
|
|
|
} |
263
|
|
|
|
264
|
|
|
list($blockSize, $keySize) = $this->allowedCiphers[$this->cipher]; |
265
|
|
|
|
266
|
|
|
$keySalt = StringHelper::byteSubstr($data, 0, $keySize); |
267
|
|
|
if ($passwordBased) { |
268
|
|
|
$key = $this->pbkdf2($this->kdfHash, $secret, $keySalt, $this->derivationIterations, $keySize); |
269
|
|
|
} else { |
270
|
|
|
$key = $this->hkdf($this->kdfHash, $secret, $keySalt, $info, $keySize); |
271
|
|
|
} |
272
|
|
|
|
273
|
|
|
$authKey = $this->hkdf($this->kdfHash, $key, null, $this->authKeyInfo, $keySize); |
274
|
27 |
|
$data = $this->validateData(StringHelper::byteSubstr($data, $keySize, null), $authKey); |
275
|
|
|
if ($data === false) { |
276
|
27 |
|
return false; |
277
|
27 |
|
} |
278
|
27 |
|
|
279
|
|
|
$iv = StringHelper::byteSubstr($data, 0, $blockSize); |
280
|
|
|
$encrypted = StringHelper::byteSubstr($data, $blockSize, null); |
281
|
|
|
|
282
|
27 |
|
$decrypted = openssl_decrypt($encrypted, $this->cipher, $key, OPENSSL_RAW_DATA, $iv); |
283
|
|
|
if ($decrypted === false) { |
284
|
|
|
throw new \yii\base\Exception('OpenSSL failure on decryption: ' . openssl_error_string()); |
285
|
|
|
} |
286
|
|
|
|
287
|
|
|
return $decrypted; |
288
|
|
|
} |
289
|
|
|
|
290
|
|
|
/** |
291
|
|
|
* Derives a key from the given input key using the standard HKDF algorithm. |
292
|
|
|
* Implements HKDF specified in [RFC 5869](https://tools.ietf.org/html/rfc5869). |
293
|
|
|
* Recommend use one of the SHA-2 hash algorithms: sha224, sha256, sha384 or sha512. |
294
|
|
|
* @param string $algo a hash algorithm supported by `hash_hmac()`, e.g. 'SHA-256' |
295
|
|
|
* @param string $inputKey the source key |
296
|
|
|
* @param string $salt the random salt |
297
|
|
|
* @param string $info optional info to bind the derived key material to application- |
298
|
|
|
* and context-specific information, e.g. a user ID or API version, see |
299
|
|
|
* [RFC 5869](https://tools.ietf.org/html/rfc5869) |
300
|
|
|
* @param int $length length of the output key in bytes. If 0, the output key is |
301
|
|
|
* the length of the hash algorithm output. |
302
|
|
|
* @throws InvalidArgumentException when HMAC generation fails. |
303
|
|
|
* @return string the derived key |
304
|
|
|
*/ |
305
|
|
|
public function hkdf($algo, $inputKey, $salt = null, $info = null, $length = 0) |
306
|
|
|
{ |
307
|
|
|
if (function_exists('hash_hkdf')) { |
308
|
|
|
$outputKey = hash_hkdf($algo, $inputKey, $length, $info, $salt); |
|
|
|
|
309
|
|
|
if ($outputKey === false) { |
310
|
|
|
throw new InvalidArgumentException('Invalid parameters to hash_hkdf()'); |
311
|
|
|
} |
312
|
|
|
|
313
|
|
|
return $outputKey; |
314
|
|
|
} |
315
|
|
|
|
316
|
|
|
$test = @hash_hmac($algo, '', '', true); |
317
|
|
|
if (!$test) { |
318
|
|
|
throw new InvalidArgumentException('Failed to generate HMAC with hash algorithm: ' . $algo); |
319
|
|
|
} |
320
|
|
|
$hashLength = StringHelper::byteLength($test); |
321
|
|
|
if (is_string($length) && preg_match('{^\d{1,16}$}', $length)) { |
|
|
|
|
322
|
|
|
$length = (int) $length; |
323
|
|
|
} |
324
|
|
|
if (!is_int($length) || $length < 0 || $length > 255 * $hashLength) { |
|
|
|
|
325
|
|
|
throw new InvalidArgumentException('Invalid length'); |
326
|
|
|
} |
327
|
|
|
$blocks = $length !== 0 ? ceil($length / $hashLength) : 1; |
328
|
|
|
|
329
|
|
|
if ($salt === null) { |
330
|
|
|
$salt = str_repeat("\0", $hashLength); |
331
|
18 |
|
} |
332
|
|
|
$prKey = hash_hmac($algo, $inputKey, $salt, true); |
333
|
18 |
|
|
334
|
18 |
|
$hmac = ''; |
335
|
18 |
|
$outputKey = ''; |
336
|
|
|
for ($i = 1; $i <= $blocks; $i++) { |
337
|
|
|
$hmac = hash_hmac($algo, $hmac . $info . chr($i), $prKey, true); |
338
|
|
|
$outputKey .= $hmac; |
339
|
18 |
|
} |
340
|
|
|
|
341
|
|
|
if ($length !== 0) { |
342
|
|
|
$outputKey = StringHelper::byteSubstr($outputKey, 0, $length); |
343
|
|
|
} |
344
|
|
|
|
345
|
|
|
return $outputKey; |
346
|
|
|
} |
347
|
|
|
|
348
|
|
|
/** |
349
|
|
|
* Derives a key from the given password using the standard PBKDF2 algorithm. |
350
|
|
|
* Implements HKDF2 specified in [RFC 2898](http://tools.ietf.org/html/rfc2898#section-5.2) |
351
|
|
|
* Recommend use one of the SHA-2 hash algorithms: sha224, sha256, sha384 or sha512. |
352
|
|
|
* @param string $algo a hash algorithm supported by `hash_hmac()`, e.g. 'SHA-256' |
353
|
|
|
* @param string $password the source password |
354
|
|
|
* @param string $salt the random salt |
355
|
|
|
* @param int $iterations the number of iterations of the hash algorithm. Set as high as |
356
|
|
|
* possible to hinder dictionary password attacks. |
357
|
|
|
* @param int $length length of the output key in bytes. If 0, the output key is |
358
|
|
|
* the length of the hash algorithm output. |
359
|
|
|
* @return string the derived key |
360
|
|
|
* @throws InvalidArgumentException when hash generation fails due to invalid params given. |
361
|
|
|
*/ |
362
|
|
|
public function pbkdf2($algo, $password, $salt, $iterations, $length = 0) |
363
|
|
|
{ |
364
|
|
|
if (function_exists('hash_pbkdf2') && PHP_VERSION_ID >= 50500) { |
365
|
|
|
$outputKey = hash_pbkdf2($algo, $password, $salt, $iterations, $length, true); |
366
|
|
|
if ($outputKey === false) { |
367
|
|
|
throw new InvalidArgumentException('Invalid parameters to hash_pbkdf2()'); |
368
|
|
|
} |
369
|
|
|
|
370
|
|
|
return $outputKey; |
371
|
|
|
} |
372
|
|
|
|
373
|
|
|
// todo: is there a nice way to reduce the code repetition in hkdf() and pbkdf2()? |
374
|
|
|
$test = @hash_hmac($algo, '', '', true); |
375
|
|
|
if (!$test) { |
376
|
|
|
throw new InvalidArgumentException('Failed to generate HMAC with hash algorithm: ' . $algo); |
377
|
|
|
} |
378
|
|
|
if (is_string($iterations) && preg_match('{^\d{1,16}$}', $iterations)) { |
|
|
|
|
379
|
|
|
$iterations = (int) $iterations; |
380
|
|
|
} |
381
|
|
|
if (!is_int($iterations) || $iterations < 1) { |
|
|
|
|
382
|
|
|
throw new InvalidArgumentException('Invalid iterations'); |
383
|
|
|
} |
384
|
|
|
if (is_string($length) && preg_match('{^\d{1,16}$}', $length)) { |
|
|
|
|
385
|
|
|
$length = (int) $length; |
386
|
|
|
} |
387
|
|
|
if (!is_int($length) || $length < 0) { |
|
|
|
|
388
|
|
|
throw new InvalidArgumentException('Invalid length'); |
389
|
|
|
} |
390
|
|
|
$hashLength = StringHelper::byteLength($test); |
391
|
|
|
$blocks = $length !== 0 ? ceil($length / $hashLength) : 1; |
392
|
|
|
|
393
|
|
|
$outputKey = ''; |
394
|
|
|
for ($j = 1; $j <= $blocks; $j++) { |
395
|
|
|
$hmac = hash_hmac($algo, $salt . pack('N', $j), $password, true); |
396
|
8 |
|
$xorsum = $hmac; |
397
|
|
|
for ($i = 1; $i < $iterations; $i++) { |
398
|
8 |
|
$hmac = hash_hmac($algo, $hmac, $password, true); |
399
|
8 |
|
$xorsum ^= $hmac; |
400
|
|
|
} |
401
|
|
|
$outputKey .= $xorsum; |
402
|
|
|
} |
403
|
8 |
|
|
404
|
|
|
if ($length !== 0) { |
405
|
|
|
$outputKey = StringHelper::byteSubstr($outputKey, 0, $length); |
406
|
|
|
} |
407
|
|
|
|
408
|
|
|
return $outputKey; |
409
|
|
|
} |
410
|
|
|
|
411
|
|
|
/** |
412
|
|
|
* Prefixes data with a keyed hash value so that it can later be detected if it is tampered. |
413
|
|
|
* There is no need to hash inputs or outputs of [[encryptByKey()]] or [[encryptByPassword()]] |
414
|
|
|
* as those methods perform the task. |
415
|
|
|
* @param string $data the data to be protected |
416
|
|
|
* @param string $key the secret key to be used for generating hash. Should be a secure |
417
|
|
|
* cryptographic key. |
418
|
|
|
* @param bool $rawHash whether the generated hash value is in raw binary format. If false, lowercase |
419
|
|
|
* hex digits will be generated. |
420
|
|
|
* @return string the data prefixed with the keyed hash |
421
|
21 |
|
* @throws InvalidConfigException when HMAC generation fails. |
422
|
|
|
* @see validateData() |
423
|
21 |
|
* @see generateRandomKey() |
424
|
21 |
|
* @see hkdf() |
425
|
|
|
* @see pbkdf2() |
426
|
|
|
*/ |
427
|
21 |
|
public function hashData($data, $key, $rawHash = false) |
428
|
21 |
|
{ |
429
|
21 |
|
$hash = hash_hmac($this->macHash, $data, $key, $rawHash); |
430
|
21 |
|
if (!$hash) { |
431
|
|
|
throw new InvalidConfigException('Failed to generate HMAC with hash algorithm: ' . $this->macHash); |
432
|
21 |
|
} |
433
|
|
|
|
434
|
21 |
|
return $hash . $data; |
435
|
21 |
|
} |
436
|
|
|
|
437
|
|
|
/** |
438
|
|
|
* Validates if the given data is tampered. |
439
|
3 |
|
* @param string $data the data to be validated. The data must be previously |
440
|
|
|
* generated by [[hashData()]]. |
441
|
|
|
* @param string $key the secret key that was previously used to generate the hash for the data in [[hashData()]]. |
442
|
|
|
* function to see the supported hashing algorithms on your system. This must be the same |
443
|
|
|
* as the value passed to [[hashData()]] when generating the hash for the data. |
444
|
|
|
* @param bool $rawHash this should take the same value as when you generate the data using [[hashData()]]. |
445
|
|
|
* It indicates whether the hash value in the data is in binary format. If false, it means the hash value consists |
446
|
|
|
* of lowercase hex digits only. |
447
|
|
|
* hex digits will be generated. |
448
|
|
|
* @return string|false the real data with the hash stripped off. False if the data is tampered. |
449
|
|
|
* @throws InvalidConfigException when HMAC generation fails. |
450
|
|
|
* @see hashData() |
451
|
|
|
*/ |
452
|
|
|
public function validateData($data, $key, $rawHash = false) |
453
|
|
|
{ |
454
|
|
|
$test = @hash_hmac($this->macHash, '', '', $rawHash); |
455
|
110 |
|
if (!$test) { |
456
|
|
|
throw new InvalidConfigException('Failed to generate HMAC with hash algorithm: ' . $this->macHash); |
457
|
110 |
|
} |
458
|
3 |
|
$hashLength = StringHelper::byteLength($test); |
459
|
|
|
if (StringHelper::byteLength($data) >= $hashLength) { |
460
|
|
|
$hash = StringHelper::byteSubstr($data, 0, $hashLength); |
461
|
107 |
|
$pureData = StringHelper::byteSubstr($data, $hashLength, null); |
462
|
3 |
|
|
463
|
|
|
$calculatedHash = hash_hmac($this->macHash, $pureData, $key, $rawHash); |
464
|
|
|
|
465
|
|
|
if ($this->compareString($hash, $calculatedHash)) { |
466
|
104 |
|
return $pureData; |
467
|
100 |
|
} |
468
|
|
|
} |
469
|
|
|
|
470
|
|
|
return false; |
471
|
|
|
} |
472
|
|
|
|
473
|
4 |
|
private $_randomFile; |
474
|
4 |
|
|
475
|
4 |
|
/** |
476
|
|
|
* Generates specified number of random bytes. |
477
|
|
|
* Note that output may not be ASCII. |
478
|
|
|
* @see generateRandomString() if you need a string. |
479
|
|
|
* |
480
|
|
|
* @param int $length the number of bytes to generate |
481
|
4 |
|
* @return string the generated random bytes |
482
|
1 |
|
* @throws InvalidArgumentException if wrong length is specified |
483
|
|
|
* @throws Exception on failure. |
484
|
1 |
|
*/ |
485
|
4 |
|
public function generateRandomKey($length = 32) |
486
|
|
|
{ |
487
|
|
|
if (!is_int($length)) { |
|
|
|
|
488
|
|
|
throw new InvalidArgumentException('First parameter ($length) must be an integer'); |
489
|
|
|
} |
490
|
|
|
|
491
|
|
|
if ($length < 1) { |
492
|
|
|
throw new InvalidArgumentException('First parameter ($length) must be greater than 0'); |
493
|
|
|
} |
494
|
|
|
|
495
|
|
|
// always use random_bytes() if it is available |
496
|
|
|
if (function_exists('random_bytes')) { |
497
|
|
|
return random_bytes($length); |
498
|
|
|
} |
499
|
|
|
|
500
|
|
|
// The recent LibreSSL RNGs are faster and likely better than /dev/urandom. |
501
|
4 |
|
// Since 5.4.0, openssl_random_pseudo_bytes() reads from CryptGenRandom on Windows instead |
502
|
|
|
// of using OpenSSL library. LibreSSL is OK everywhere but don't use OpenSSL on non-Windows. |
503
|
|
|
if (function_exists('openssl_random_pseudo_bytes') |
504
|
|
|
&& ($this->shouldUseLibreSSL() || $this->isWindows()) |
505
|
|
|
) { |
506
|
|
|
$key = openssl_random_pseudo_bytes($length, $cryptoStrong); |
507
|
|
|
if ($cryptoStrong === false) { |
508
|
|
|
throw new Exception( |
509
|
4 |
|
'openssl_random_pseudo_bytes() set $crypto_strong false. Your PHP setup is insecure.' |
510
|
|
|
); |
511
|
4 |
|
} |
512
|
|
|
if ($key !== false && StringHelper::byteLength($key) === $length) { |
513
|
|
|
return $key; |
514
|
4 |
|
} |
515
|
4 |
|
} |
516
|
4 |
|
|
517
|
|
|
// mcrypt_create_iv() does not use libmcrypt. Since PHP 5.3.7 it directly reads |
518
|
4 |
|
// CryptGenRandom on Windows. Elsewhere it directly reads /dev/urandom. |
519
|
|
|
if (function_exists('mcrypt_create_iv')) { |
520
|
|
|
$key = mcrypt_create_iv($length, MCRYPT_DEV_URANDOM); |
|
|
|
|
521
|
|
|
if (StringHelper::byteLength($key) === $length) { |
522
|
3 |
|
return $key; |
523
|
|
|
} |
524
|
3 |
|
} |
525
|
3 |
|
|
526
|
|
|
// If not on Windows, try to open a random device. |
527
|
|
|
if ($this->_randomFile === null && !$this->isWindows()) { |
528
|
3 |
|
// urandom is a symlink to random on FreeBSD. |
529
|
3 |
|
$device = PHP_OS === 'FreeBSD' ? '/dev/random' : '/dev/urandom'; |
530
|
|
|
// Check random device for special character device protection mode. Use lstat() |
531
|
|
|
// instead of stat() in case an attacker arranges a symlink to a fake device. |
532
|
|
|
$lstat = @lstat($device); |
533
|
|
|
if ($lstat !== false && ($lstat['mode'] & 0170000) === 020000) { |
534
|
|
|
$this->_randomFile = fopen($device, 'rb') ?: null; |
535
|
4 |
|
|
536
|
3 |
|
if (is_resource($this->_randomFile)) { |
537
|
3 |
|
// Reduce PHP stream buffer from default 8192 bytes to optimize data |
538
|
3 |
|
// transfer from the random device for smaller values of $length. |
539
|
3 |
|
// This also helps to keep future randoms out of user memory space. |
540
|
3 |
|
$bufferSize = 8; |
541
|
1 |
|
|
542
|
|
|
if (function_exists('stream_set_read_buffer')) { |
543
|
2 |
|
stream_set_read_buffer($this->_randomFile, $bufferSize); |
544
|
2 |
|
} |
545
|
2 |
|
// stream_set_read_buffer() isn't implemented on HHVM |
546
|
|
|
if (function_exists('stream_set_chunk_size')) { |
547
|
2 |
|
stream_set_chunk_size($this->_randomFile, $bufferSize); |
548
|
|
|
} |
549
|
|
|
} |
550
|
1 |
|
} |
551
|
1 |
|
} |
552
|
|
|
|
553
|
|
|
if (is_resource($this->_randomFile)) { |
554
|
2 |
|
$buffer = ''; |
555
|
|
|
$stillNeed = $length; |
556
|
|
|
while ($stillNeed > 0) { |
557
|
|
|
$someBytes = fread($this->_randomFile, $stillNeed); |
558
|
|
|
if ($someBytes === false) { |
559
|
|
|
break; |
560
|
|
|
} |
561
|
|
|
$buffer .= $someBytes; |
562
|
|
|
$stillNeed -= StringHelper::byteLength($someBytes); |
563
|
|
|
if ($stillNeed === 0) { |
564
|
|
|
// Leaving file pointer open in order to make next generation faster by reusing it. |
565
|
87 |
|
return $buffer; |
566
|
|
|
} |
567
|
87 |
|
} |
568
|
|
|
fclose($this->_randomFile); |
569
|
|
|
$this->_randomFile = null; |
570
|
|
|
} |
571
|
87 |
|
|
572
|
|
|
throw new Exception('Unable to generate a random key'); |
573
|
|
|
} |
574
|
|
|
|
575
|
87 |
|
/** |
576
|
87 |
|
* Generates a random string of specified length. |
577
|
|
|
* The string generated matches [A-Za-z0-9_-]+ and is transparent to URL-encoding. |
578
|
|
|
* |
579
|
|
|
* @param int $length the length of the key in characters |
580
|
|
|
* @return string the generated random key |
581
|
|
|
* @throws Exception on failure. |
582
|
|
|
*/ |
583
|
|
|
public function generateRandomString($length = 32) |
584
|
|
|
{ |
585
|
|
|
if (!is_int($length)) { |
|
|
|
|
586
|
|
|
throw new InvalidArgumentException('First parameter ($length) must be an integer'); |
587
|
|
|
} |
588
|
|
|
|
589
|
|
|
if ($length < 1) { |
590
|
|
|
throw new InvalidArgumentException('First parameter ($length) must be greater than 0'); |
591
|
|
|
} |
592
|
|
|
|
593
|
|
|
$bytes = $this->generateRandomKey($length); |
594
|
|
|
return substr(StringHelper::base64UrlEncode($bytes), 0, $length); |
595
|
|
|
} |
596
|
|
|
|
597
|
|
|
/** |
598
|
|
|
* Generates a secure hash from a password and a random salt. |
599
|
|
|
* |
600
|
|
|
* The generated hash can be stored in database. |
601
|
|
|
* Later when a password needs to be validated, the hash can be fetched and passed |
602
|
|
|
* to [[validatePassword()]]. For example, |
603
|
|
|
* |
604
|
|
|
* ```php |
605
|
|
|
* // generates the hash (usually done during user registration or when the password is changed) |
606
|
|
|
* $hash = Yii::$app->getSecurity()->generatePasswordHash($password); |
607
|
|
|
* // ...save $hash in database... |
608
|
|
|
* |
609
|
|
|
* // during login, validate if the password entered is correct using $hash fetched from database |
610
|
|
|
* if (Yii::$app->getSecurity()->validatePassword($password, $hash)) { |
611
|
|
|
* // password is good |
612
|
1 |
|
* } else { |
613
|
|
|
* // password is bad |
614
|
1 |
|
* } |
615
|
1 |
|
* ``` |
616
|
|
|
* |
617
|
|
|
* @param string $password The password to be hashed. |
618
|
1 |
|
* @param int $cost Cost parameter used by the Blowfish hash algorithm. |
619
|
|
|
* The higher the value of cost, |
620
|
1 |
|
* the longer it takes to generate the hash and to verify a password against it. Higher cost |
621
|
|
|
* therefore slows down a brute-force attack. For best protection against brute-force attacks, |
622
|
|
|
* set it to the highest value that is tolerable on production servers. The time taken to |
623
|
|
|
* compute the hash doubles for every increment by one of $cost. |
624
|
|
|
* @return string The password hash string. When [[passwordHashStrategy]] is set to 'crypt', |
625
|
|
|
* the output is always 60 ASCII characters, when set to 'password_hash' the output length |
626
|
|
|
* might increase in future versions of PHP (https://secure.php.net/manual/en/function.password-hash.php) |
627
|
|
|
* @throws Exception on bad password parameter or cost parameter. |
628
|
|
|
* @see validatePassword() |
629
|
|
|
*/ |
630
|
|
|
public function generatePasswordHash($password, $cost = null) |
631
|
|
|
{ |
632
|
|
|
if ($cost === null) { |
633
|
|
|
$cost = $this->passwordHashCost; |
634
|
|
|
} |
635
|
|
|
|
636
|
|
|
if (function_exists('password_hash')) { |
637
|
|
|
/* @noinspection PhpUndefinedConstantInspection */ |
638
|
|
|
return password_hash($password, PASSWORD_DEFAULT, ['cost' => $cost]); |
639
|
|
|
} |
640
|
|
|
|
641
|
1 |
|
$salt = $this->generateSalt($cost); |
642
|
|
|
$hash = crypt($password, $salt); |
643
|
1 |
|
// strlen() is safe since crypt() returns only ascii |
644
|
|
|
if (!is_string($hash) || strlen($hash) !== 60) { |
645
|
|
|
throw new Exception('Unknown error occurred while generating hash.'); |
646
|
|
|
} |
647
|
1 |
|
|
648
|
1 |
|
return $hash; |
649
|
1 |
|
} |
650
|
|
|
|
651
|
|
|
/** |
652
|
|
|
* Verifies a password against a hash. |
653
|
|
|
* @param string $password The password to verify. |
654
|
1 |
|
* @param string $hash The hash to verify the password against. |
655
|
1 |
|
* @return bool whether the password is correct. |
656
|
|
|
* @throws InvalidArgumentException on bad password/hash parameters or if crypt() with Blowfish hash is not available. |
657
|
|
|
* @see generatePasswordHash() |
658
|
|
|
*/ |
659
|
|
|
public function validatePassword($password, $hash) |
660
|
|
|
{ |
661
|
|
|
if (!is_string($password) || $password === '') { |
|
|
|
|
662
|
|
|
throw new InvalidArgumentException('Password must be a string and cannot be empty.'); |
663
|
|
|
} |
664
|
|
|
|
665
|
|
|
if (!preg_match('/^\$2[axy]\$(\d\d)\$[\.\/0-9A-Za-z]{22}/', $hash, $matches) |
666
|
|
|
|| $matches[1] < 4 |
667
|
|
|
|| $matches[1] > 30 |
668
|
|
|
) { |
669
|
|
|
throw new InvalidArgumentException('Hash is invalid.'); |
670
|
|
|
} |
671
|
|
|
|
672
|
|
|
if (function_exists('password_verify')) { |
673
|
|
|
return password_verify($password, $hash); |
674
|
|
|
} |
675
|
|
|
|
676
|
|
|
$test = crypt($password, $hash); |
677
|
|
|
$n = strlen($test); |
678
|
|
|
if ($n !== 60) { |
679
|
|
|
return false; |
680
|
|
|
} |
681
|
|
|
|
682
|
|
|
return $this->compareString($test, $hash); |
683
|
|
|
} |
684
|
|
|
|
685
|
|
|
/** |
686
|
|
|
* Generates a salt that can be used to generate a password hash. |
687
|
|
|
* |
688
|
|
|
* The PHP [crypt()](https://secure.php.net/manual/en/function.crypt.php) built-in function |
689
|
|
|
* requires, for the Blowfish hash algorithm, a salt string in a specific format: |
690
|
|
|
* "$2a$", "$2x$" or "$2y$", a two digit cost parameter, "$", and 22 characters |
691
|
|
|
* from the alphabet "./0-9A-Za-z". |
692
|
|
|
* |
693
|
|
|
* @param int $cost the cost parameter |
694
|
|
|
* @return string the random salt value. |
695
|
|
|
* @throws InvalidArgumentException if the cost parameter is out of the range of 4 to 31. |
696
|
|
|
*/ |
697
|
|
|
protected function generateSalt($cost = 13) |
698
|
|
|
{ |
699
|
|
|
$cost = (int) $cost; |
700
|
|
|
if ($cost < 4 || $cost > 31) { |
701
|
|
|
throw new InvalidArgumentException('Cost must be between 4 and 31.'); |
702
|
|
|
} |
703
|
39 |
|
|
704
|
|
|
// Get a 20-byte random string |
705
|
39 |
|
$rand = $this->generateRandomKey(20); |
706
|
|
|
// Form the prefix that specifies Blowfish (bcrypt) algorithm and cost parameter. |
707
|
|
|
$salt = sprintf('$2y$%02d$', $cost); |
708
|
|
|
// Append the random salt data in the required base64 format. |
709
|
39 |
|
$salt .= str_replace('+', '.', substr(base64_encode($rand), 0, 22)); |
710
|
|
|
|
711
|
|
|
return $salt; |
712
|
|
|
} |
713
|
39 |
|
|
714
|
39 |
|
/** |
715
|
|
|
* Performs string comparison using timing attack resistant approach. |
716
|
|
|
* @see http://codereview.stackexchange.com/questions/13512 |
717
|
|
|
* @param string $expected string to compare. |
718
|
|
|
* @param string $actual user-supplied string. |
719
|
|
|
* @return bool whether strings are equal. |
720
|
|
|
*/ |
721
|
|
|
public function compareString($expected, $actual) |
722
|
|
|
{ |
723
|
|
|
if (!is_string($expected)) { |
|
|
|
|
724
|
|
|
throw new InvalidArgumentException('Expected expected value to be a string, ' . gettype($expected) . ' given.'); |
725
|
|
|
} |
726
|
|
|
|
727
|
|
|
if (!is_string($actual)) { |
|
|
|
|
728
|
|
|
throw new InvalidArgumentException('Expected actual value to be a string, ' . gettype($actual) . ' given.'); |
729
|
|
|
} |
730
|
|
|
|
731
|
|
|
if (function_exists('hash_equals')) { |
732
|
|
|
return hash_equals($expected, $actual); |
733
|
|
|
} |
734
|
|
|
|
735
|
|
|
$expected .= "\0"; |
736
|
|
|
$actual .= "\0"; |
737
|
81 |
|
$expectedLength = StringHelper::byteLength($expected); |
738
|
|
|
$actualLength = StringHelper::byteLength($actual); |
739
|
|
|
$diff = $expectedLength - $actualLength; |
740
|
81 |
|
for ($i = 0; $i < $actualLength; $i++) { |
741
|
80 |
|
$diff |= (ord($actual[$i]) ^ ord($expected[$i % $expectedLength])); |
742
|
|
|
} |
743
|
|
|
|
744
|
|
|
return $diff === 0; |
745
|
|
|
} |
746
|
|
|
|
747
|
|
|
/** |
748
|
|
|
* Masks a token to make it uncompressible. |
749
|
|
|
* Applies a random mask to the token and prepends the mask used to the result making the string always unique. |
750
|
9 |
|
* Used to mitigate BREACH attack by randomizing how token is outputted on each request. |
751
|
|
|
* @param string $token An unmasked token. |
752
|
9 |
|
* @return string A masked token. |
753
|
9 |
|
* @since 2.0.12 |
754
|
|
|
*/ |
755
|
9 |
|
public function maskToken($token) |
756
|
1 |
|
{ |
757
|
|
|
// The number of bytes in a mask is always equal to the number of bytes in a token. |
758
|
|
|
$mask = $this->generateRandomKey(StringHelper::byteLength($token)); |
759
|
9 |
|
return StringHelper::base64UrlEncode($mask . ($mask ^ $token)); |
760
|
|
|
} |
761
|
|
|
|
762
|
|
|
/** |
763
|
|
|
* Unmasks a token previously masked by `maskToken`. |
764
|
|
|
* @param string $maskedToken A masked token. |
765
|
|
|
* @return string An unmasked token, or an empty string in case of token format is invalid. |
766
|
|
|
* @since 2.0.12 |
767
|
|
|
*/ |
768
|
|
|
public function unmaskToken($maskedToken) |
769
|
|
|
{ |
770
|
|
|
$decoded = StringHelper::base64UrlDecode($maskedToken); |
771
|
|
|
$length = StringHelper::byteLength($decoded) / 2; |
772
|
|
|
// Check if the masked token has an even length. |
773
|
|
|
if (!is_int($length)) { |
|
|
|
|
774
|
|
|
return ''; |
775
|
|
|
} |
776
|
|
|
|
777
|
|
|
return StringHelper::byteSubstr($decoded, $length, $length) ^ StringHelper::byteSubstr($decoded, 0, $length); |
778
|
|
|
} |
779
|
|
|
} |
780
|
|
|
|