(PHP 5 >= 5.5.0, PHP 7, PHP 8)
password_hash — Создаёт хеш пароля
Функция password_hash() создаёт хеш пароля, используя сильный необратимый алгоритм хеширования.
Поддерживаются следующие алгоритмы:
PASSWORD_DEFAULT — будет выбран алгоритм bcrypt (по умолчанию с PHP 5.5.0).
Обратите внимание, алгоритм может измениться на более
сильный, когда такой добавится в PHP. При изменении алгоритма и длина результата
также может измениться. Поэтому длину поля для хранения
в базе данных лучше устанавливать более 60 символов (255 символов будет хорошим значением).
PASSWORD_BCRYPT — будет выбран алгоритм
CRYPT_BLOWFISH. Генерирует стандартный хеш с идентификатором "$2y$",
совместимый с тем, который генерирует функция crypt().
В результате будет сгенерирована строка длиной 60 символов или false, если возникла ошибка.
PASSWORD_ARGON2I — будет выбран алгоритм хеширования Argon2i.
Этот алгоритм будет доступен, только если PHP собран с поддержкой Argon2.
PASSWORD_ARGON2ID — будет выбран алгоритм хеширования Argon2id.
Этот алгоритм будет доступен, только если PHP собран с поддержкой Argon2.
Поддерживаемые опции для PASSWORD_BCRYPT:
salt (string) — для самостоятельного задания соли для хеширования.
Обратите внимание, что это приведёт к переопределению и предотвратит
автоматическое создание соли.
Если не задано, то функция password_hash() будет генерировать случайную соль для каждого хешируемого пароля. Это предпочтительный режим работы.
Эта опция объявлена устаревшей. Рекомендуется использовать автоматически генерируемую соль. Начиная с PHP 8.0.0 явно заданная соль игнорируется.
cost (int) — задаёт алгоритмическую сложность.
Пример с этой опцией можно посмотреть на странице, посвящённой
функции crypt().
Если не задано, то будет выбрано значение по умолчанию: 10.
Это хорошая базовая стоимость, но можно увеличить её,
если позволяет производительность оборудования.
Поддерживаемые опции для 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.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 |
Добавлена поддержка алгоритма хеширования паролей Argon2id с помощью PASSWORD_ARGON2ID.
|
| 7.2.0 |
Добавлена поддержка хеширующего алгоритма Argon2i с помощью PASSWORD_ARGON2I.
|
Пример #1 Пример использования password_hash()
<?php
/**
* Мы просто хотим захешировать пароль с настройками по умолчанию.
* Значит, будет выбран алгоритм BCRYPT и результат будет длиной 60 символов.
*
* Помните, что алгоритм по умолчанию может измениться в будущем, так что
* имеет смысл заранее позаботиться о том, чтобы система хранения хешей
* смогла хранить более 60 символов (а лучше 255)
*/
echo password_hash("rasmuslerdorf", PASSWORD_DEFAULT);
?>Вывод приведённого примера будет похож на:
$2y$10$.vGA1O9wmRjrwAVXD98HNOgsNpDczlqm3Jq7KnEd1rVAGv3Fykk1a
Пример #2 Пример использования password_hash() с ручным заданием стоимости
<?php
/**
* Тут мы увеличиваем алгоритмическую стоимость BCRYPT до 12.
* Но это никак не скажется на длине полученного результата, она останется 60 символов
*/
$options = [
'cost' => 12,
];
echo password_hash("rasmuslerdorf", PASSWORD_BCRYPT, $options);
?>Вывод приведённого примера будет похож на:
$2y$12$QjSH496pcT5CEbzjD/vtVeH03tfHKFy36d4J0Ltp3lRtee9HDxY3K
Пример #3 Пример поиска хорошего значения стоимости для функции password_hash()
<?php
/**
* Данный код замерит скорость выполнения операции с разными значениями алгоритмической сложности хеширования
* на вашем сервере и определит
* его максимальное значение, не приводящее к деградации производительности. Хорошее базовое
* значение — 10, но если ваш сервер достаточно мощный, то можно
* задать и больше. Данный скрипт ищет максимальное значение, при котором
* хеширование уложится в значение ≤ 350 миллисекундам, что считается приемлемой задержкой
* для систем, которые обрабатывают интерактивные входы.
*/
$timeTarget = 0.350; // 350 миллисекунд
$cost = 8;
do {
$cost++;
$start = microtime(true);
password_hash("test", PASSWORD_BCRYPT, ["cost" => $cost]);
$end = microtime(true);
} while (($end - $start) < $timeTarget);
echo "Оптимальная стоимость: " . $cost;
?>Вывод приведённого примера будет похож на:
Оптимальная стоимость: 12
Пример #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
Настоятельно рекомендуется использовать автоматическую генерацию соли. Данная функция самостоятельно создаст хорошую соль, если вы не будете ей мешать подсовывая свою.
Как было замечено выше, опция salt была объявлена
устаревшей в PHP 7.0 и будет вызывать соответствующее предупреждение.
Поддержка ручного задания соли была удалена в PHP 8.0.
Замечание:
Рекомендуется протестировать данную функцию на вашем оборудовании для определения оптимального значения алгоритмической сложности. Убедитесь, что с выбранной сложностью функция выполняется быстрее 350 миллисекунд для интерактивных систем. Скрипт в приведённом выше примере поможет выбрать оптимальное значение.
Замечание: Обновление поддерживаемых алгоритмов для этой функции (или изменение значения по умолчанию) обязаны следовать правилам:
- Любой новый алгоритм должен присутствовать в ядре как минимум 1 полный релиз PHP для того, чтобы его можно было установить по умолчанию. Таким образом, если, к примеру, новый алгоритм был добавлен в 7.5.5, то задать по умолчанию его можно будет только в 7.7 (7.6 будет тем самым полным релизом, в течение которого он должен присутствовать, от 7.6.0 до 7.7.0). Но если новый алгоритм добавлен в 7.6.0, то его также можно будет задать по умолчанию в версии 7.7.0.
- Алгоритм по умолчанию может быть изменён только в полном релизе (7.3.0, 8.0.0 и т. д.), но не в промежуточных. Единственное исключение — это критическая уязвимость, найденная в текущем алгоритме.