SecurityHelper.php 10.4 KB
Newer Older
Qiang Xue committed
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44
<?php
/**
 * @link http://www.yiiframework.com/
 * @copyright Copyright (c) 2008 Yii Software LLC
 * @license http://www.yiiframework.com/license/
 */

namespace yii\helpers\base;

use Yii;
use yii\base\Exception;
use yii\base\InvalidConfigException;
use yii\base\InvalidParamException;

/**
 * SecurityHelper provides a set of methods to handle common security-related tasks.
 *
 * In particular, SecurityHelper supports the following features:
 *
 * - Encryption/decryption: [[encrypt()]] and [[decrypt()]]
 * - Data tampering prevention: [[hashData()]] and [[validateData()]]
 * - Password validation: [[generatePasswordHash()]] and [[validatePassword()]]
 *
 * Additionally, SecurityHelper provides [[getSecretKey()]] to support generating
 * named secret keys. These secret keys, once generated, will be stored in a file
 * and made available in future requests.
 *
 * @author Qiang Xue <qiang.xue@gmail.com>
 * @author Tom Worster <fsb@thefsb.org>
 * @since 2.0
 */
class SecurityHelper
{
	/**
	 * Encrypts data.
	 * @param string $data data to be encrypted.
	 * @param string $key the encryption secret key
	 * @return string the encrypted data
	 * @throws Exception if PHP Mcrypt extension is not loaded or failed to be initialized
	 * @see decrypt()
	 */
	public static function encrypt($data, $key)
	{
		$module = static::openCryptModule();
ekerazha committed
45 46
		// 192-bit (24 bytes) key size
		$key = StringHelper::substr($key, 0, 24);
Qiang Xue committed
47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66
		srand();
		$iv = mcrypt_create_iv(mcrypt_enc_get_iv_size($module), MCRYPT_RAND);
		mcrypt_generic_init($module, $key, $iv);
		$encrypted = $iv . mcrypt_generic($module, $data);
		mcrypt_generic_deinit($module);
		mcrypt_module_close($module);
		return $encrypted;
	}

	/**
	 * Decrypts data
	 * @param string $data data to be decrypted.
	 * @param string $key the decryption secret key
	 * @return string the decrypted data
	 * @throws Exception if PHP Mcrypt extension is not loaded or failed to be initialized
	 * @see encrypt()
	 */
	public static function decrypt($data, $key)
	{
		$module = static::openCryptModule();
ekerazha committed
67 68
		// 192-bit (24 bytes) key size
		$key = StringHelper::substr($key, 0, 24);
Qiang Xue committed
69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133
		$ivSize = mcrypt_enc_get_iv_size($module);
		$iv = StringHelper::substr($data, 0, $ivSize);
		mcrypt_generic_init($module, $key, $iv);
		$decrypted = mdecrypt_generic($module, StringHelper::substr($data, $ivSize, StringHelper::strlen($data)));
		mcrypt_generic_deinit($module);
		mcrypt_module_close($module);
		return rtrim($decrypted, "\0");
	}

	/**
	 * Prefixes data with a keyed hash value so that it can later be detected if it is tampered.
	 * @param string $data the data to be protected
	 * @param string $key the secret key to be used for generating hash
	 * @param string $algorithm the hashing algorithm (e.g. "md5", "sha1", "sha256", etc.). Call PHP "hash_algos()"
	 * function to see the supported hashing algorithms on your system.
	 * @return string the data prefixed with the keyed hash
	 * @see validateData()
	 * @see getSecretKey()
	 */
	public static function hashData($data, $key, $algorithm = 'sha256')
	{
		return hash_hmac($algorithm, $data, $key) . $data;
	}

	/**
	 * Validates if the given data is tampered.
	 * @param string $data the data to be validated. The data must be previously
	 * generated by [[hashData()]].
	 * @param string $key the secret key that was previously used to generate the hash for the data in [[hashData()]].
	 * @param string $algorithm the hashing algorithm (e.g. "md5", "sha1", "sha256", etc.). Call PHP "hash_algos()"
	 * function to see the supported hashing algorithms on your system. This must be the same
	 * as the value passed to [[hashData()]] when generating the hash for the data.
	 * @return string the real data with the hash stripped off. False if the data is tampered.
	 * @see hashData()
	 */
	public static function validateData($data, $key, $algorithm = 'sha256')
	{
		$hashSize = StringHelper::strlen(hash_hmac($algorithm, 'test', $key));
		$n = StringHelper::strlen($data);
		if ($n >= $hashSize) {
			$hash = StringHelper::substr($data, 0, $hashSize);
			$data2 = StringHelper::substr($data, $hashSize, $n - $hashSize);
			return $hash === hash_hmac($algorithm, $data2, $key) ? $data2 : false;
		} else {
			return false;
		}
	}

	/**
	 * Returns a secret key associated with the specified name.
	 * If the secret key does not exist, a random key will be generated
	 * and saved in the file "keys.php" under the application's runtime directory
	 * so that the same secret key can be returned in future requests.
	 * @param string $name the name that is associated with the secret key
	 * @param integer $length the length of the key that should be generated if not exists
	 * @return string the secret key associated with the specified name
	 */
	public static function getSecretKey($name, $length = 32)
	{
		static $keys;
		$keyFile = Yii::$app->getRuntimePath() . '/keys.php';
		if ($keys === null) {
			$keys = is_file($keyFile) ? require($keyFile) : array();
		}
		if (!isset($keys[$name])) {
134
			$keys[$name] = static::generateRandomKey($length);
Qiang Xue committed
135 136 137 138 139
			file_put_contents($keyFile, "<?php\nreturn " . var_export($keys, true) . ";\n");
		}
		return $keys[$name];
	}

140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156
	/**
	 * Generates a random key.
	 * @param integer $length the length of the key that should be generated
	 * @return string the generated random key
	 */
	public static function generateRandomKey($length = 32)
	{
		if (function_exists('openssl_random_pseudo_bytes')) {
			$key = base64_encode(openssl_random_pseudo_bytes($length, $strong));
			if ($strong) {
				return substr($key, 0, $length);
			}
		}
		$chars = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789';
		return substr(str_shuffle(str_repeat($chars, 5)), 0, $length);
	}

Qiang Xue committed
157 158 159 160 161 162 163 164 165 166 167
	/**
	 * Opens the mcrypt module.
	 * @return resource the mcrypt module handle.
	 * @throws InvalidConfigException if mcrypt extension is not installed
	 * @throws Exception if mcrypt initialization fails
	 */
	protected static function openCryptModule()
	{
		if (!extension_loaded('mcrypt')) {
			throw new InvalidConfigException('The mcrypt PHP extension is not installed.');
		}
ekerazha committed
168
		// AES uses a 128-bit block size
ekerazha committed
169
		$module = @mcrypt_module_open('rijndael-128', '', 'cbc', '');
Qiang Xue committed
170 171 172 173 174 175 176 177 178 179 180 181 182 183 184
		if ($module === false) {
			throw new Exception('Failed to initialize the mcrypt module.');
		}
		return $module;
	}

	/**
	 * Generates a secure hash from a password and a random salt.
	 *
	 * The generated hash can be stored in database (e.g. `CHAR(64) CHARACTER SET latin1` on MySQL).
	 * Later when a password needs to be validated, the hash can be fetched and passed
	 * to [[validatePassword()]]. For example,
	 *
	 * ~~~
	 * // generates the hash (usually done during user registration or when the password is changed)
185
	 * $hash = SecurityHelper::generatePasswordHash($password);
Qiang Xue committed
186 187 188
	 * // ...save $hash in database...
	 *
	 * // during login, validate if the password entered is correct using $hash fetched from database
189
	 * if (SecurityHelper::verifyPassword($password, $hash) {
Qiang Xue committed
190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234
	 *     // password is good
	 * } else {
	 *     // password is bad
	 * }
	 * ~~~
	 *
	 * @param string $password The password to be hashed.
	 * @param integer $cost Cost parameter used by the Blowfish hash algorithm.
	 * The higher the value of cost,
	 * the longer it takes to generate the hash and to verify a password against it. Higher cost
	 * therefore slows down a brute-force attack. For best protection against brute for attacks,
	 * set it to the highest value that is tolerable on production servers. The time taken to
	 * compute the hash doubles for every increment by one of $cost. So, for example, if the
	 * hash takes 1 second to compute when $cost is 14 then then the compute time varies as
	 * 2^($cost - 14) seconds.
	 * @throws Exception on bad password parameter or cost parameter
	 * @return string The password hash string, ASCII and not longer than 64 characters.
	 * @see validatePassword()
	 */
	public static function generatePasswordHash($password, $cost = 13)
	{
		$salt = static::generateSalt($cost);
		$hash = crypt($password, $salt);

		if (!is_string($hash) || strlen($hash) < 32) {
			throw new Exception('Unknown error occurred while generating hash.');
		}

		return $hash;
	}

	/**
	 * Verifies a password against a hash.
	 * @param string $password The password to verify.
	 * @param string $hash The hash to verify the password against.
	 * @return boolean whether the password is correct.
	 * @throws InvalidParamException on bad password or hash parameters or if crypt() with Blowfish hash is not available.
	 * @see generatePasswordHash()
	 */
	public static function validatePassword($password, $hash)
	{
		if (!is_string($password) || $password === '') {
			throw new InvalidParamException('Password must be a string and cannot be empty.');
		}

Qiang Xue committed
235
		if (!preg_match('/^\$2[axy]\$(\d\d)\$[\.\/0-9A-Za-z]{22}/', $hash, $matches) || $matches[1] < 4 || $matches[1] > 30) {
Qiang Xue committed
236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289
			throw new InvalidParamException('Hash is invalid.');
		}

		$test = crypt($password, $hash);
		$n = strlen($test);
		if (strlen($test) < 32 || $n !== strlen($hash)) {
			return false;
		}

		// Use a for-loop to compare two strings to prevent timing attacks. See:
		// http://codereview.stackexchange.com/questions/13512
		$check = 0;
		for ($i = 0; $i < $n; ++$i) {
			$check |= (ord($test[$i]) ^ ord($hash[$i]));
		}

		return $check === 0;
	}

	/**
	 * Generates a salt that can be used to generate a password hash.
	 *
	 * The PHP [crypt()](http://php.net/manual/en/function.crypt.php) built-in function
	 * requires, for the Blowfish hash algorithm, a salt string in a specific format:
	 * "$2a$", "$2x$" or "$2y$", a two digit cost parameter, "$", and 22 characters
	 * from the alphabet "./0-9A-Za-z".
	 *
	 * @param integer $cost the cost parameter
	 * @return string the random salt value.
	 * @throws InvalidParamException if the cost parameter is not between 4 and 30
	 */
	protected static function generateSalt($cost = 13)
	{
		$cost = (int)$cost;
		if ($cost < 4 || $cost > 30) {
			throw new InvalidParamException('Cost must be between 4 and 31.');
		}

		// Get 20 * 8bits of pseudo-random entropy from mt_rand().
		$rand = '';
		for ($i = 0; $i < 20; ++$i) {
			$rand .= chr(mt_rand(0, 255));
		}

		// Add the microtime for a little more entropy.
		$rand .= microtime();
		// Mix the bits cryptographically into a 20-byte binary string.
		$rand = sha1($rand, true);
		// Form the prefix that specifies Blowfish algorithm and cost parameter.
		$salt = sprintf("$2y$%02d$", $cost);
		// Append the random salt data in the required base64 format.
		$salt .= str_replace('+', '.', substr(base64_encode($rand), 0, 22));
		return $salt;
	}
ekerazha committed
290
}