Класс yii\base\Security

Все классы | Свойства | Методы

Наследование	yii\base\Security » yii\base\Component » yii\base\Object
Реализует	yii\base\Configurable
Доступна с версии	2.0
Исходный код	https://github.com/yiisoft/yii2/blob/master/framework/base/Security.php

Security предоставляет набор методов для обработки общих задач безопасности.

В частности, Security поддерживает следующие функции:

Шифрование/дешифрование: encryptByKey(), decryptByKey(), encryptByPassword() и decryptByPassword()
Вычисление ключей с использованием стандартных алгоритмов: pbkdf2() и hkdf()
Предотвращение подмены данных: hashData() и validateData()
Проверка паролей: generatePasswordHash() и validatePassword()

Примечание: для генерации случайных ключей/строк на Windows и для шифрования/дешифрования на всех платформах требуется расширение PHP 'OpenSSL'. Для максимальной безопасности рекомендуется использовать версию PHP >= 5.5.0.

Для получения более подробной информации и руководства по использованию Security, см. статью руководства о безопасности.

Общедоступные свойства

Свойство	Тип	Описание	Определено
$allowedCiphers	массив[]	Таблица соответствия размеров блоков и ключей для каждого поддерживаемого шифра OpenSSL.	yii\base\Security
$authKeyInfo	строка	Значение HKDF info для вывода ключа аутентификации сообщений.	yii\base\Security
$behaviors	yii\base\Behavior[]	Список присоединённых к этому компоненту поведений.	yii\base\Component
$cipher	строка	Шифр для использования при шифровании и дешифровании.	yii\base\Security
$derivationIterations	целое число	Количество итераций вывода.	yii\base\Security
$kdfHash	строка	Алгоритм хеширования для вывода ключей.	yii\base\Security
$macHash	строка	Алгоритм хеширования для аутентификации сообщений.	yii\base\Security
$passwordHashCost	целое число	Значение по умолчанию для сложности хеширования паролей.	yii\base\Security
$passwordHashStrategy	строка	Стратегия, которая должна использоваться для генерации хеша пароля.	yii\base\Security

Общедоступные методы

Метод	Описание	Определено в
__call()	Вызывает именованный метод, который не является методом класса.	yii\base\Component
__clone()	Этот метод вызывается после создания объекта путем клонирования существующего.	yii\base\Component
__construct()	Конструктор.	yii\base\Object
__get()	Возвращает значение свойства компонента.	yii\base\Component
__isset()	Проверяет, установлено ли свойство, т.е. определено и не равно null.	yii\base\Component
__set()	Устанавливает значение свойства компонента.	yii\base\Component
__unset()	Устанавливает свойство компонента в null.	yii\base\Component
attachBehavior()	Присоединяет поведение к этому компоненту.	yii\base\Component
attachBehaviors()	Присоединяет список поведений к компоненту.	yii\base\Component
behaviors()	Возвращает список поведений, по которым должен действовать этот компонент.	yii\base\Component
canGetProperty()	Возвращает значение, указывающее, можно ли считать свойство.	yii\base\Component
canSetProperty()	Возвращает значение, указывающее, можно ли установить свойство.	yii\base\Component
className()	Возвращает полное имя этого класса.	yii\base\Object
compareString()	Выполняет сравнение строк с использованием подхода, устойчивого к атакам с замедлением времени.	yii\base\Security
decryptByKey()	Проверяет и расшифровывает данные, зашифрованные с помощью encryptByKey().	yii\base\Security
decryptByPassword()	Проверяет и расшифровывает данные, зашифрованные с помощью encryptByPassword().	yii\base\Security
detachBehavior()	Отсоединяет поведение от компонента.	yii\base\Component
detachBehaviors()	Отсоединяет все поведения от компонента.	yii\base\Component
encryptByKey()	Шифрует данные с использованием криптографического ключа.	yii\base\Security
encryptByPassword()	Шифрует данные с использованием пароля.	yii\base\Security
ensureBehaviors()	Убеждается, что поведения, объявленные в behaviors(), присоединены к этому компоненту.	yii\base\Component
generatePasswordHash()	Генерирует безопасный хэш из пароля и случайной соли.	yii\base\Security
generateRandomKey()	Генерирует указанное количество случайных байтов.	yii\base\Security
generateRandomString()	Генерирует случайную строку указанной длины.	yii\base\Security
getBehavior()	Возвращает объект именованного поведения.	yii\base\Component
getBehaviors()	Возвращает все присоединенные к этому компоненту поведения.	yii\base\Component
hasEventHandlers()	Возвращает значение, указывающее, есть ли какой-либо обработчик, присоединенный к указанному событию.	yii\base\Component
hasMethod()	Возвращает значение, указывающее, определен ли метод.	yii\base\Component
hasProperty()	Возвращает значение, указывающее, определено ли свойство для этого компонента.	yii\base\Component
hashData()	Добавляет к данным значение хэша с ключом, чтобы можно было позже определить, были ли они изменены.	yii\base\Security
hkdf()	Выводит ключ из заданного входного ключа с помощью стандартного алгоритма HKDF.	yii\base\Security
init()	Инициализирует объект.	yii\base\Object
maskToken()	Маскирует маркер, чтобы сделать его несжимаемым.	yii\base\Security
off()	Отсоединяет существующий обработчик событий от этого компонента.	yii\base\Component
on()	Присоединяет обработчик событий к событию.	yii\base\Component
pbkdf2()	Выводит ключ из заданного пароля с помощью стандартного алгоритма PBKDF2.	yii\base\Security
trigger()	Вызывает событие.	yii\base\Component
unmaskToken()	Рамаскирует маркер, ранее замаскированный `maskToken`.	yii\base\Security
validateData()	Проверяет, были ли изменены данные.	yii\base\Security
validatePassword()	Проверяет пароль по хэшу.	yii\base\Security

Защищенные методы

Метод	Описание	Определено в
decrypt()	Расшифровывает данные.	yii\base\Security
encrypt()	Шифрует данные.	yii\base\Security
generateSalt()	Генерирует соль, которая может быть использована для генерации хэша пароля.	yii\base\Security

Подробное описание свойств

$allowedCiphers общедоступное свойство

Таблица соответствия размеров блоков и ключей для каждого поддерживаемого OpenSSL шифра.

В каждом элементе ключ — это один из шифров, поддерживаемых OpenSSL (@see openssl_get_cipher_methods()). Значение — массив из двух целых чисел, первое — размер блока шифра в байтах, а второе — размер ключа в байтах.

Предупреждение: Все рекомендуемые OpenSSL шифры находятся в значениях по умолчанию, т.е. AES в режиме CBC.

Примечание: Протокол шифрования Yii использует одинаковый размер для ключа шифра, ключа подписи HMAC и соли вывода ключа.

public array[] $allowedCiphers = ['AES-128-CBC' => [16, 16], 'AES-192-CBC' => [16, 24], 'AES-256-CBC' => [16, 32]]

$authKeyInfo общедоступное свойство

Значение HKDF info для вывода ключа аутентификации сообщений.

См. также hkdf().

public string $authKeyInfo = 'AuthorizationKey'

$cipher общедоступное свойство

Шифр, который следует использовать для шифрования и дешифрования.

public string $cipher = 'AES-128-CBC'

$derivationIterations общедоступное свойство

Количество итераций вывода ключа. Установите значение как можно выше, чтобы затруднить атаки методом подбора паролей.

public integer $derivationIterations = 100000

$kdfHash общедоступное свойство

Алгоритм хэширования для вывода ключа. Рекомендуется sha256, sha384 или sha512.

См. также hash_algos().

public string $kdfHash = 'sha256'

$macHash открытая переменная

Алгоритм хэширования для аутентификации сообщений. Рекомендуется использовать sha256, sha384 или sha512.

См. также hash_algos().

public string $macHash = 'sha256'

$passwordHashCost открытая переменная (доступна с версии 2.0.6)

Значение по умолчанию для затрат на хэширование паролей. Допустимое значение от 4 до 31.

См. также generatePasswordHash().

public integer $passwordHashCost = 13

$passwordHashStrategy открытая переменная

Устарело начиная с версии 2.0.7, generatePasswordHash() игнорирует $passwordHashStrategy и использует password_hash() при наличии, или crypt() при отсутствии.

Стратегия, которая должна использоваться для генерации хэша пароля. Доступные стратегии:

'password_hash' - использование PHP функции password_hash() с алгоритмом PASSWORD_DEFAULT. Этот вариант рекомендуется, но требует версию PHP >= 5.5.0
'crypt' - использование PHP функции crypt().

public string $passwordHashStrategy = null

Подробное описание методов

compareString() public method

Выполняет сравнение строк с использованием подхода, устойчивого к атакам по таймингу.

См. также http://codereview.stackexchange.com/questions/13512.

public boolean compareString ( $expected, $actual )
$expected	string	Строка для сравнения.
$actual	string	Строка, предоставленная пользователем.
return	boolean	Являются ли строки равными.

decrypt() protected method

Дешифрует данные.

См. также encrypt().

protected boolean\|string decrypt ( $data, $passwordBased, $secret, $info )
$data	string	Зашифрованные данные, которые необходимо дешифровать.
$passwordBased	boolean	Установите значение true, чтобы использовать вычисление ключа на основе пароля
$secret	string	Пароль или ключ для дешифрования
$info	string\|null	Информация, специфичная для контекста/приложения, см. encrypt()
return	boolean\|string	Дешифрованные данные или false при ошибке аутентификации
throws	yii\base\InvalidConfigException	при отсутствии загрузки OpenSSL
throws	yii\base\Exception	при ошибке OpenSSL

decryptByKey() public method

Проверяет и дешифрует данные, зашифрованные с помощью encryptByKey().

См. также encryptByKey().

public boolean\|string decryptByKey ( $data, $inputKey, $info = null )
$data	string	Зашифрованные данные для дешифрования
$inputKey	string	Входные данные для шифрования и аутентификации
$info	string	Дополнительная информация, специфичная для контекста и приложения, см. hkdf()
return	boolean\|string	Дешифрованные данные или false при ошибке аутентификации

decryptByPassword() public method

Проверяет и дешифрует данные, зашифрованные с помощью encryptByPassword().

См. также encryptByPassword().

public boolean\|string decryptByPassword ( $data, $password )
$data	string	Зашифрованные данные для дешифрования
$password	string	Пароль для использования при дешифровании
return	boolean\|string	Дешифрованные данные или false при ошибке аутентификации

encrypt() protected method

Шифрует данные.

См. также decrypt().

protected string encrypt ( $data, $passwordBased, $secret, $info )
$data	string	Данные для шифрования
$passwordBased	boolean	Установите значение true, чтобы использовать вычисление ключа на основе пароля
$secret	string	Пароль или ключ для шифрования
$info	string\|null	Информация, специфичная для контекста/приложения, например, идентификатор пользователя. Дополнительные сведения см. в RFC 5869 Раздел 3.2.
return	string	Зашифрованные данные
throws	yii\base\InvalidConfigException	при отсутствии загрузки OpenSSL
throws	yii\base\Exception	при ошибке OpenSSL

encryptByKey() public method

Шифрует данные с помощью криптографического ключа.

Вычисляет ключи для шифрования и аутентификации из входного ключа с помощью HKDF и случайной соли, что очень быстро по сравнению с encryptByPassword(). Входной ключ должен быть правильно случайным — используйте generateRandomKey() для генерации ключей. Зашифрованные данные включают в себя код аутентификации сообщения с ключом (MAC), поэтому нет необходимости хешировать входные или выходные данные.

См. также:

public string encryptByKey ( $data, $inputKey, $info = null )
$data	string	Данные для шифрования
$inputKey	string	Входные данные для шифрования и аутентификации
$info	string	Дополнительная информация, специфичная для контекста и приложения, см. hkdf()
return	string	Зашифрованные данные

encryptByPassword() public method

Шифрует данные с помощью пароля.

Вычисляет ключи для шифрования и аутентификации из пароля с использованием PBKDF2 и случайной соли, что намеренно медленно, чтобы защитить от атак словарями. Используйте encryptByKey() для быстрого шифрования с использованием криптографического ключа, а не пароля. Время вычисления ключа определяется $derivationIterations, которое следует устанавливать как можно выше. Зашифрованные данные включают в себя код аутентификации сообщения с ключом (MAC), поэтому нет необходимости хешировать входные или выходные данные. > Примечание: избегайте шифрования с паролями, где это возможно. Ничто не может защитить от паролей низкого качества или компрометированных паролей.

См. также:

public string encryptByPassword ( $data, $password )
$data	string	Данные для шифрования
$password	string	Пароль для использования при шифровании
return	string	Зашифрованные данные

generatePasswordHash() public method

Генерирует защищённый хеш из пароля и случайной соли.

Сгенерированный хеш можно хранить в базе данных. Позже, когда необходимо проверить пароль, хеш можно извлечь и передать в validatePassword(). Например,

// generates the hash (usually done during user registration or when the password is changed)
$hash = Yii::$app->getSecurity()->generatePasswordHash($password);
// ...save $hash in database...

// during login, validate if the password entered is correct using $hash fetched from database
if (Yii::$app->getSecurity()->validatePassword($password, $hash) {
    // password is good
} else {
    // password is bad
}

См. также validatePassword().

public string generatePasswordHash ( $password, $cost = null )
$password	string	Пароль, который нужно хешировать.
$cost	integer	Параметр стоимости, используемый алгоритмом хеширования Blowfish. Чем выше значение стоимости, тем дольше занимает генерация хеша и проверка пароля по нему. Более высокая стоимость, следовательно, замедляет атаку методом перебора. Для наилучшей защиты от атак методом перебора установите его на максимальное значение, допустимое на серверах в производстве. Время, необходимое для вычисления хеша, удваивается при каждом увеличении $cost на единицу.
return	string	Строка хеша пароля. Когда $passwordHashStrategy установлено в 'crypt', вывод всегда составляет 60 символов ASCII, когда установлено в 'password_hash', длина вывода может увеличиться в будущих версиях PHP (http://php.net/manual/en/function.password-hash.php)
throws	yii\base\Exception	при плохом параметре пароля или параметре стоимости.

generateRandomKey() public method

Генерирует указанное количество случайных байтов.

Обратите внимание, что вывод может не быть ASCII.

См. также generateRandomString(), если вам нужна строка.

public string generateRandomKey ( $length = 32 )
$length	integer	Количество генерируемых байтов
return	string	Сгенерированные случайные байты
throws	yii\base\InvalidParamException	если указана неправильная длина
throws	yii\base\Exception	при ошибке.

generateRandomString() public method

Генерирует случайную строку заданной длины.

Сгенерированная строка соответствует [A-Za-z0-9_-]+ и прозрачна для URL-кодирования.

public string generateRandomString ( $length = 32 )
$length	integer	Длина ключа в символах
return	string	Сгенерированный случайный ключ
throws	yii\base\Exception	при ошибке.

generateSalt() protected method

Генерирует соль, которая может быть использована для генерации хеша пароля.

Встроенная функция PHP crypt() для алгоритма хеширования Blowfish требует строку соли в определенном формате: "$2a$", "$2x$" или "$2y$", двухзначный параметр стоимости, "$", и 22 символа из алфавита "./0-9A-Za-z".

protected string generateSalt ( $cost = 13 )
$cost	integer	Параметр стоимости
return	string	Случайное значение соли.
throws	yii\base\InvalidParamException	если параметр стоимости находится вне диапазона от 4 до 31.

hashData() public method

Предваряет данные значением хеша с ключом, чтобы можно было впоследствии определить, были ли они изменены.

Нет необходимости хешировать входные или выходные данные encryptByKey() или encryptByPassword(), так как эти методы выполняют эту задачу.

См. также:

public string hashData ( $data, $key, $rawHash = false )
$data	string	Защищаемые данные
$key	string	Секретный ключ, используемый для генерации хеша. Должен быть безопасным криптографическим ключом.
$rawHash	boolean	Является ли сгенерированное значение хеша в формате сырых двоичных данных. Если false, генерируются строчные шестнадцатеричные цифры.
return	string	Данные, предваряемые хешем с ключом
throws	yii\base\InvalidConfigException	при ошибке генерации HMAC.

hkdf() public method

Выводит ключ из заданного входного ключа с использованием стандартного алгоритма HKDF.

Реализует HKDF, указанный в RFC 5869. Рекомендуется использовать один из алгоритмов хеширования SHA-2: sha224, sha256, sha384 или sha512.

public string hkdf ( $algo, $inputKey, $salt = null, $info = null, $length = 0 )
$algo	string	Алгоритм хеширования, поддерживаемый `hash_hmac()`, например, 'SHA-256'
$inputKey	string	Исходный ключ
$salt	string	Случайная соль
$info	string	Необязательная информация для привязки полученных данных ключа к прикладной и контекстно-специфичной информации, например, идентификатору пользователя или версии API, см. RFC 5869
$length	integer	Длина выходного ключа в байтах. Если 0, выходной ключ имеет длину выходного значения алгоритма хеширования.
return	string	Выведенный ключ
throws	yii\base\InvalidParamException	при ошибке генерации HMAC.

maskToken() public method (доступно с версии 2.0.12)

Маскирует токен, чтобы сделать его несжимаемым.

Применяет случайную маску к токену и добавляет использованную маску в результат, что делает строку всегда уникальной. Используется для смягчения атаки BREACH путем случайного изменения способа вывода токена при каждом запросе.

public string maskToken ( $token )
$token	string	Незамаскированный токен.
return	string	Замаскированный токен.

pbkdf2() public method

Выводит ключ из заданного пароля с использованием стандартного алгоритма PBKDF2.

Реализует HKDF2, указанный в RFC 2898. Рекомендуется использовать один из алгоритмов хеширования SHA-2: sha224, sha256, sha384 или sha512.

public string pbkdf2 ( $algo, $password, $salt, $iterations, $length = 0 )
$algo	string	Алгоритм хеширования, поддерживаемый `hash_hmac()`, например, 'SHA-256'
$password	string	Исходный пароль
$salt	string	Случайная соль
$iterations	integer	Количество итераций алгоритма хеширования. Установите как можно выше, чтобы затруднить атаки методом подбора паролей.
$length	integer	Длина выходного ключа в байтах. Если 0, выходной ключ имеет длину выходного значения алгоритма хеширования.
return	string	Выведенный ключ
throws	yii\base\InvalidParamException	при ошибке генерации хеша из-за некорректных заданных параметров.

unmaskToken() public method (доступно с версии 2.0.12)

Рассмаскирует токен, ранее замаскированный maskToken.

public string unmaskToken ( $maskedToken )
$maskedToken	string	Замаскированный токен.
return	string	Размаскированный токен или пустая строка в случае неверного формата токена.

validateData() public method

Проверяет, не была ли изменёна предоставленные данные.

См. также hashData().

public string\|false validateData ( $data, $key, $rawHash = false )
$data	string	Данные для проверки. Данные должны быть предварительно сгенерированы с помощью hashData().
$key	string	Секретный ключ, который ранее использовался для генерации хэша данных в функции hashData(). Он должен совпадать со значением, переданным в hashData() при генерации хэша данных.
$rawHash	boolean	Это значение должно совпадать с тем, которое вы использовали при генерации данных с помощью hashData(). Оно указывает, находится ли значение хэша в данных в двоичном формате. Если false, значит, значение хэша состоит только из строчных шестнадцатеричных цифр. hex-значения будут сгенерированы.
return	string\|false	Реальные данные с удалённым хэшем. False, если данные были изменены.
throws	yii\base\InvalidConfigException	при ошибке генерации HMAC.

validatePassword() public method

Проверяет пароль по хэшу.

См. также generatePasswordHash().

public boolean validatePassword ( $password, $hash )
$password	string	Пароль для проверки.
$hash	string	Хэш для проверки пароля.
return	boolean	Соответствует ли пароль.
throws	yii\base\InvalidParamException	при плохих параметрах пароля/хэша или если crypt() с Blowfish хэшем недоступен.

© 2008–2017 by Yii Software LLC
Licensed under the three clause BSD license.
http://www.yiiframework.com/doc-2.0/yii-base-security.html