Создаёт хеш пароля

# password_hash

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

password_hash — Создаёт хеш пароля

### Описание

function 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.

### Примеры

Пример #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-кодированный хеш

`↑` and `↓` to navigate • `Enter` to select • `Esc` to close • `/` to open