PHPTime

Хеширование паролей в PHP: password_hash, password_verify, md5 и hash

При регистрации PHP создаёт хеш пароля, а при входе проверяет введённый пароль по сохранённому хешу. Для этой задачи есть password_hash() и password_verify(). Функции md5() и hash() вычисляют быстрые дайджесты, которые применяются для других задач.

Что такое хеш в PHP и какую функцию выбрать

Хеширование преобразует последовательность байтов в дайджест. Для обычной хеш-функции одни и те же байты при одном алгоритме дают одинаковый результат. Парольный хеш включает случайную соль, поэтому два вызова password_hash() для одного пароля обычно возвращают разные строки. Соль хранится в самом хеше вместе с параметрами алгоритма.

У хеширования нет операции расшифровки. Однако пароль можно угадать, проверяя кандидатов по украденной базе. Поэтому для паролей используют алгоритмы с настраиваемой стоимостью вычисления. Они замедляют каждую попытку подбора, а уникальная соль мешает использовать один и тот же результат вычисления для множества записей.

ЗадачаФункция PHP
Сохранить пароль, проверить его при входе и со временем обновить параметрыpassword_hash(), password_verify(), password_needs_rehash()
Вычислить SHA-256 для строки или файлаhash(), hash_file()
Проверить целостность и подлинность сообщения с общим секретомhash_hmac(), hash_equals()
Получить MD5 для совместимости с существующим форматомmd5(), md5_file()

Как сохранить пароль через password_hash()

При регистрации и смене пароля передавайте введённую строку в password_hash(). Функция сама создаёт соль и возвращает готовую строку для хранения. В PHP 8.3–8.5 PASSWORD_DEFAULT использует bcrypt. У bcrypt предел в 72 байта: данные после этой границы отбрасываются. Для UTF-8 считайте байты через strlen(), поскольку число символов и байтов может различаться.

PHP
<?php
declare(strict_types=1);

function createPasswordHash(string $password): string
{
    // Проверяем ограничения bcrypt до вычисления хеша.
    if ($password === '' || strlen($password) > 72 || str_contains($password, "\0")) {
        throw new InvalidArgumentException('Пароль должен занимать от 1 до 72 байт и не содержать NUL.');
    }

    return password_hash($password, PASSWORD_BCRYPT);
}

В примере выбран PASSWORD_BCRYPT, поскольку проверка входных данных привязана к этому алгоритму. Минимальную длину по правилам приложения проверяйте отдельно. В обработчике формы убедитесь через is_string(), что поле пришло строкой. strict_types помогает контролировать типы аргументов, но сам по себе не валидирует поля формы.

Храните результат целиком, например в VARCHAR(255). Это поле вмещает стандартные хеши bcrypt и Argon2id и оставляет запас при смене формата. Записывайте хеш через подготовленный SQL-запрос, передавая его строковым параметром. Пароль, введённый пользователем, исключите из журналов и диагностических данных. Если вычисление хеша завершилось исключением, прервите запись и обработайте ошибку на уровне приложения.

Когда использовать PASSWORD_ARGON2ID

Argon2id позволяет настраивать затраты памяти и времени. Он подходит и для паролей длиннее 72 байт. Для новых приложений его можно выбрать как основной алгоритм, если он доступен во всех PHP-средах, где создаются и проверяются хеши. Проверьте это через password_algos() в том окружении, где работает приложение. CLI и PHP-FPM могут использовать разные сборки PHP.

PHP
<?php
declare(strict_types=1);

function createArgon2idHash(string $password): string
{
    if (!in_array('argon2id', password_algos(), true)) {
        throw new RuntimeException('В этой сборке PHP недоступен Argon2id.');
    }

    // Используем параметры сборки PHP по умолчанию.
    return password_hash($password, PASSWORD_ARGON2ID);
}

Для bcrypt настраивается cost. У Argon2id есть memory_cost в КиБ и time_cost. Параметр threads зависит от реализации Argon2 в сборке PHP. Подбирайте настройки под реальную параллельную нагрузку входов. Увеличение памяти на одну операцию влияет на общий расход памяти при одновременной проверке нескольких паролей.

Как проверить пароль через password_verify() и обновить хеш

Найдите пользователя и передайте введённый пароль первым аргументом password_verify(), а сохранённый хеш вторым. Функция извлечёт из хеша алгоритм, соль и параметры. Повторный вызов password_hash() с последующим сравнением строк не подходит: случайная соль будет другой.

После успешной проверки вызовите password_needs_rehash() с целевым алгоритмом и настройками. Так можно повышать стоимость вычисления постепенно, при успешных входах. Функция сравнивает параметры хеша с заданными и вернёт true при различии в любую сторону. Перед выкладкой проверьте настройки всех экземпляров приложения, чтобы один сервер случайно не снижал стоимость, заданную другим.

PHP
<?php
declare(strict_types=1);

function verifyAndUpgradePassword(
    string $password,
    string $storedHash,
    callable $replaceHash
): bool {
    if (!password_verify($password, $storedHash)) {
        return false;
    }

    // Обновляем только после успешной проверки и сохраняем bcrypt.
    if (password_needs_rehash($storedHash, PASSWORD_BCRYPT)) {
        $newHash = password_hash($password, PASSWORD_BCRYPT);
        $replaceHash($storedHash, $newHash);
    }

    return true;
}

Этот пример рассчитан на учётные записи с bcrypt и с теми же ограничениями входа, что при создании пароля. Перед вызовом проверьте эти ограничения. В $replaceHash передайте функцию, которая обновляет запись по идентификатору пользователя и прежнему хешу. Условие по прежнему хешу защищает от перезаписи пароля, который успели сменить между чтением и обновлением. Если обновлено ноль строк, новый хеш записывать повторно не нужно.

При переходе с bcrypt на Argon2id учитывайте старые записи, для которых прежняя форма принимала пароли длиннее 72 байт. У bcrypt проверка подтверждает только учитываемый префикс. Если нельзя установить, какой пароль был у пользователя целиком, предложите ему задать новый через процедуру смены или сброса пароля.

PHP md5: результат функции и старые пароли

md5($data) возвращает 32 шестнадцатеричных символа. Вызов md5($data, true) возвращает 16 байт, среди которых могут быть нулевые и непечатные. Для текстового поля и обмена строками обычно используют шестнадцатеричное представление. У MD5 известны практические коллизии, поэтому он годится для совместимости с унаследованным форматом, где результат не служит доказательством подлинности.

PHP
<?php
declare(strict_types=1);

$data = 'hello';

// 5d41402abc4b2a76b9719d911017c592
 echo md5($data), PHP_EOL;

// Бинарное представление занимает 16 байт.
 echo strlen(md5($data, true)), PHP_EOL;

Если в базе уже есть пароли в MD5, формат старых записей лучше определять по отдельному признаку, например password_scheme. При входе проверяйте старую запись по точной исторической схеме, включая соль и порядок частей, если они использовались. Сравнивайте дайджесты через hash_equals(). При успехе вычислите современный хеш из введённого пароля и обновите хеш и признак формата одной операцией. Для пользователей, которые не войдут за отведённый период миграции, предусмотрите сброс пароля.

PHP hash: SHA-256 для строк, файлов и HMAC

Сигнатура hash($algo, $data, $binary = false) принимает имя алгоритма и строку байтов. Для SHA-256 результат занимает 64 шестнадцатеричных символа или 32 байта при $binary = true. Доступные алгоритмы перечисляет hash_algos(). Неизвестное имя алгоритма в PHP 8.x вызывает ValueError, поэтому в прикладном коде задавайте его явно или выбирайте из разрешённого списка.

PHP
<?php
declare(strict_types=1);

// Хешируем строку, включая перевод строки в конце.
 echo hash('sha256', "hello\n"), PHP_EOL;

// Хешируем сам PHP-файл без загрузки всего файла в строку.
$digest = hash_file('sha256', __FILE__);
if ($digest === false) {
    throw new RuntimeException('Не удалось прочитать файл.');
}
 echo $digest, PHP_EOL;

Для сверки файла с эталоном получите эталонный SHA-256 из доверенного источника. Если отправитель и получатель делят секретный ключ и нужно проверить сообщение, используйте HMAC. Подписывайте и проверяйте одну и ту же последовательность байтов. Например, повторная сериализация JSON может поменять пробелы или порядок ключей и дать другой результат.

PHP
<?php
declare(strict_types=1);

function verifyMessage(string $body, string $signature, string $secret): bool
{
    // По протоколу подпись передаётся шестнадцатеричной строкой.
    $expected = hash_hmac('sha256', $body, $secret);

    return hash_equals($expected, $signature);
}

Типичные ошибки и отличия PHP 8.3–8.5

  • Хешировать пароль через md5() или hash('sha256', ...). Эти функции рассчитаны на быстрые вычисления. Самодельная соль не устраняет высокую скорость перебора. Используйте password_hash().
  • Обрезать сохранённый хеш до 60 символов. Это длина хеша bcrypt. Полная строка Argon2id длиннее и содержит параметры, нужные для проверки.
  • Менять пароль перед проверкой. trim(), перевод регистра и HTML-экранирование изменяют входные байты. Передавайте пароль в том виде, в котором пользователь его ввёл. Экранирование HTML относится к выводу на страницу.
  • Сравнивать дайджесты через ==. PHP может сравнить строки вида 0e123 и 0e456 как числа. Для HMAC используйте hash_equals() и передавайте вычисленное значение первым. Для парольных хешей используйте password_verify().
  • Обновлять хеш при каждом входе. Повторное вычисление нужно только при успешной проверке и положительном результате password_needs_rehash().

В PHP 8.3 стоимость bcrypt по умолчанию равна 10. В PHP 8.4 она выросла до 12 и в PHP 8.5 остаётся 12. Смена значения по умолчанию влияет на создание новых хешей и проверку необходимости обновления. Старый хеш продолжает проверяться с указанной в нём стоимостью. Если приложение явно передаёт ['cost' => 10], обновление PHP само по себе эту настройку не изменит.

Для кода под PHP 8.3–8.5 используйте строковый результат password_hash() и обработку исключений при сбое. Проверка результата на false из старых примеров для этой функции больше не нужна. У hash_file() отдельный контракт: функция по-прежнему может вернуть false, если файл не удалось прочитать.

Чек-лист для регистрации и входа

  1. Выберите алгоритм и его параметры. Для Argon2id проверьте доступность в рабочих сборках, для bcrypt задайте явное ограничение в 72 байта.
  2. При регистрации и смене пароля вызывайте password_hash() и сохраняйте всю строку в поле с запасом длины.
  3. При входе используйте password_verify(). Ограничивайте частоту попыток входа независимо от стоимости хеширования.
  4. После успешной проверки применяйте password_needs_rehash(). Обновляйте запись с условием по прежнему хешу.
  5. После смены версии PHP проверьте вход с уже сохранёнными хешами, регистрацию и обновление хеша. Измерьте нагрузку при нескольких одновременных входах.

Частые вопросы

Какая функция PHP нужна для хеширования пароля?

Для создания хеша используйте password_hash(), а для проверки при входе — password_verify(). Соль и параметры алгоритма входят в строку хеша.

Чем в PHP md5() отличается от hash('sha256', ...)?

md5() вычисляет MD5 и по умолчанию выдаёт 32 шестнадцатеричных символа. hash('sha256', ...) вычисляет SHA-256 и выдаёт 64 символа. Обе функции подходят для вычисления дайджестов, а для паролей используется password_hash().

Будут ли старые хеши bcrypt работать после перехода на PHP 8.5?

Да. password_verify() берёт стоимость вычисления из сохранённого хеша. После успешной проверки password_needs_rehash() может предложить обновить хеш, если его стоимость отличается от заданной.

Справка по теме

Ещё в разделе «Справочник PHP»

Циклы в PHP: for, while, do-while и foreach

Как работают циклы for, while, do-while и foreach в PHP 8.3–8.5. Примеры обхода массивов, вложенных циклов и применения break и continue.

10 мин

Что нового в PHP 8.x: от 8.0 до 8.5

Разбираем, что изменилось в PHP 8.0–8.5: типы, enum, readonly, хуки свойств и оператор pipe. Примеры кода, ошибки совместимости и чек-лист обновления.

9 мин

Composer: установка, composer.json и управление зависимостями

Как установить Composer для PHP 8.3–8.5, настроить composer.json и автозагрузку PSR-4, обновлять зависимости и устранять конфликты версий.

8 мин

Cookie в PHP: setcookie, чтение, удаление и флаги безопасности

Как установить, прочитать и удалить cookie в PHP 8.3–8.5. Примеры setcookie и $_COOKIE, настройка Secure, HttpOnly и SameSite, разбор типичных ошибок.

9 мин