(PHP 5 >= 5.5.0, PHP 7, PHP 8)
password_hash — Создаёт хеш пароля
$password, string|int|null $algo, array $options = []): stringФункция password_hash() создаёт хеш пароля через сильный необратимый алгоритм хеширования.
Поддерживаются следующие алгоритмы:
PASSWORD_DEFAULT — алгоритм хеширования bcrypt. С PHP 5.5.0 bcrypt стал алгоритмом по умолчанию.
По мере добавления в PHP новых усиленных алгоритмов значение константы изменяется и задаёт новый идентификатор алгоритма.
При изменении алгоритма длина результата изменяется, часто увеличивается.
Поэтому сохранять результат в базе данных лучше в столбце длиной больше 60 байтов. Длину поля устанавливают равной 255 байтам, чтобы сократить риск ошибок.
PASSWORD_BCRYPT — алгоритм хеширования bcrypt.
С этой константой функция генерирует стандартный хеш с идентификатором $2y$,
совместимый с хешем, который создаёт функция crypt().
PASSWORD_ARGON2I — алгоритм хеширования Argon2i.
Алгоритм доступен, только если PHP скомпилировали с поддержкой Argon2.
PASSWORD_ARGON2ID — алгоритм хеширования Argon2id.
Алгоритм доступен, только если PHP скомпилировали с поддержкой Argon2.
Алгоритм PASSWORD_BCRYPT поддерживает следующие опции:
salt (string) — пользовательская соль для хеширования пароля.
Ручная установка соли переопределит поведение функции — предотвратит
автоматическую генерацию соли.
При пропуске параметра функция password_hash() сгенерирует случайную соль для каждого хешируемого пароля. Это предпочтительный режим работы.
Опция salt устарела в пользу соли по умолчанию, которую функция генерирует автоматически. Начиная с PHP 8.0.0 функция игнорирует пользовательскую соль.
cost (int) — алгоритмическая сложность.
Пример работы с опцией доступен на странице
с описанием функции crypt().
При пропуске параметра функция выберет значение по умолчанию: 12.
Со значением по умолчанию функция генерирует стойкий хеш, но конкретное значение
подстраивают под конкретное оборудование.
Алгоритмы PASSWORD_ARGON2I и PASSWORD_ARGON2ID
поддерживают следующие опции:
memory_cost (int) — максимальный размер
памяти в килобайтах для вычисления хеша Argon2.
По умолчанию функция выбирает значение константы PASSWORD_ARGON2_DEFAULT_MEMORY_COST.
time_cost (int) — предельное количество раундов,
которые выполняет алгоритм Argon2 для вычисления хеша.
Значение по умолчанию: PASSWORD_ARGON2_DEFAULT_TIME_COST.
threads (int) — количество потоков
для вычисления хеша алгоритмом Argon2.
Значение по умолчанию: PASSWORD_ARGON2_DEFAULT_THREADS.
Опция доступна, только если PHP собрали с библиотекой libargon2, а не с libsodium.
passwordПользовательский пароль.
При хешировании пароля алгоритмом PASSWORD_BCRYPT
значение аргумента password усекается до предельной длины — 72 байтов.
algoКонстанта алгоритма хеширования пароля, который будет использовать функция.
optionsАссоциативный массив с опциями. За документацией по поддерживаемым опциям для каждого алгоритма обратитесь к разделу Константы алгоритмов хеширования паролей.
Функция возвращает хешированный пароль.
Идентификатор алгоритма, показатель вычислительной сложности и соль возвращаются в составе хеша, поэтому не требуется хранить информацию об алгоритме и соли отдельно, а для проверки пароля достаточно передать хеш в функцию password_verify().
| Версия | Описание |
|---|---|
| 8.4.0 |
Значение по умолчанию для опции cost алгоритма
PASSWORD_BCRYPT увеличили
с 10 до 12.
|
| 8.3.0 | Функция password_hash() теперь устанавливает базовое исключение Random\RandomException в качестве значения свойства Exception::$previous, если выбрасывается ошибка ValueError из-за сбоя во время генерации соли. |
| 8.0.0 |
Функция password_hash() больше не возвращает значение false, если возникла ошибка.
Вместо этого функция выбросит ошибку ValueError,
если алгоритм хеширования пароля недействителен, или ошибку Error,
если не получилось захешировать пароль из-за неизвестной ошибки.
|
| 8.0.0 |
Параметр algo теперь принимает значение null.
|
| 7.4.0 |
Параметр algo теперь ожидает строку (string), но всё ещё принимает
целое число (int) для обратной совместимости.
|
| 7.4.0 | Модуль sodium обеспечивает альтернативную реализацию паролей Argon2. |
| 7.3.0 |
Ввели константу PASSWORD_ARGON2ID, которая добавила поддержку алгоритма хеширования паролей алгоритмом Argon2id.
|
| 7.2.0 |
Ввели константу PASSWORD_ARGON2I, которая добавила поддержку хеширования паролей алгоритмом Argon2i.
|
Пример #1 Пример хеширования пароля функцией password_hash()
<?php
echo password_hash("rasmuslerdorf", PASSWORD_DEFAULT);
?>Вывод приведённого примера будет похож на:
$2y$12$4Umg0rCJwMswRw/l.SwHvuQV01coP0eWmGzd61QH2RvAOMANUBGC.
Пример #2 Пример генерации хеша функцией password_hash() установкой алгоритмической сложности вручную
<?php
$options = [
// Увеличиваем алгоритмическую сложность алгоритма bcrypt с 12 до 13
'cost' => 13,
];
echo password_hash("rasmuslerdorf", PASSWORD_BCRYPT, $options);
?>Вывод приведённого примера будет похож на:
$2y$13$xeDfQumlmdm0Sco.4qmH1OGfUUmOcuRmfae0dPJhjX1Bq0yYhqbNi
Пример #3 Пример поиска оптимума показателя алгоритмической сложности для функции password_hash()
Код протестирует машину и определит показатель вычислительной сложности, с которым функция сгенерирует стойкий хеш, но не испортит пользовательский опыт и не замедлит другие операции, которые выполняет машина. Тестирование начинают с базового значения 11 и увеличивают показатель, если машина не замедляет работу под нагрузкой. Код ищет максимум, при котором хеширование не превышает 350 миллисекунд — допустимая задержка для систем авторизации пользователей.
<?php
$timeTarget = 0.350; // 350 миллисекунд
$cost = 11;
do {
$cost++;
$start = microtime(true);
password_hash("test", PASSWORD_BCRYPT, ["cost" => $cost]);
$end = microtime(true);
} while (($end - $start) < $timeTarget);
echo "Оптимальная стоимость: " . $cost - 1;
?>Вывод приведённого примера будет похож на:
Оптимальная стоимость: 13
Пример #4 Пример генерации хеша функцией password_hash() алгоритмом Argon2i
<?php
echo 'Хеш Argon2i: ' . password_hash('rasmuslerdorf', PASSWORD_ARGON2I);
?>Вывод приведённого примера будет похож на:
Хеш Argon2i: $argon2i$v=19$m=1024,t=2,p=2$YzJBSzV4TUhkMzc3d3laeg$zqU/1IN0/AogfP4cmSJI1vc8lpXRW9/S0sYY2i2jHT0
Функция автоматически создаст безопасную соль, поэтому разработчики PHP настоятельно рекомендуют не указывать опцию salt вручную.
В PHP 7.0.0 установка значения опции salt вручную
сгенерирует предупреждение об устаревании. В PHP 8.0.0 установку пользовательской соли удалили.
Замечание:
Работу функции тестируют на конкретной машине и подстраивают параметры вычислительной сложности до значений, с которыми при авторизации пользователей функция выполняется не дольше 350 миллисекунд. Скрипт в предыдущем примере помогает определить оптимум алгоритмической сложности для алгоритма bcrypt.
Замечание: Обновление алгоритмов, которые поддерживает функция, или изменение алгоритма по умолчанию подчиняется следующим правилам:
- С момента включения нового алгоритма в ядро до установки по умолчанию прошёл 1 полный выпуск PHP. Алгоритм, который ввели в версии 7.5.5, получит право стать алгоритмом по умолчанию только в версии 7.7, поскольку версия 7.6 станет первым полным выпуском. Но и другой алгоритм, который добавили бы в версии 7.6.0, тоже получил бы право стать алгоритмом по умолчанию в версии 7.7.0.
- Алгоритм по умолчанию изменяется только в полном выпуске, например, 7.3.0 или 8.0.0, но не в промежуточных. Единственное исключение — критическая уязвимость безопасности, которую обнаружили в текущем алгоритме по умолчанию.