Описание

password_hash(#[\SensitiveParameter] string $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.

Версия	Описание
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, но не в промежуточных. Единственное исключение — критическая уязвимость безопасности, которую обнаружили в текущем алгоритме по умолчанию.

Смотрите также

password_verify() - Проверяет, соответствует ли пароль хешу
password_needs_rehash() - Проверяет, что указанный хеш соответствует заданным опциям
crypt() - Хеширует строку необратимым способом
sodium_crypto_pwhash_str() - Получает ASCII-кодированный хеш