SHA-3 и другие хеши в PHP: контрольные суммы, HMAC и пароли
В PHP выбор функции хеширования зависит от задачи. Для контрольной суммы файла подходит SHA3-256, для проверки подлинности вебхука нужен HMAC с общим секретом, а для хранения паролей предназначена password_hash().
Что такое SHA-3 и чем он отличается от SHA-2
SHA-3 — семейство криптографических хеш-функций, основанное на Keccak, победителе конкурса NIST. В PHP доступны четыре варианта с фиксированным размером дайджеста: sha3-224, sha3-256, sha3-384 и sha3-512. Число в имени означает длину результата в битах.
SHA-256 из семейства SHA-2 и SHA3-256 выдают по 256 бит, но используют разные конструкции и дают разные результаты для одних и тех же байтов. SHA-3 расширяет выбор криптографических примитивов. Для контрольных сумм и HMAC SHA-256 по-прежнему подходит. В существующем протоколе применяйте алгоритм, указанный в его спецификации: замена меняет дайджесты и ломает совместимость.
SHA3-256 и Keccak-256 дают разные дайджесты
Стандартизованный SHA3-256 и Keccak-256 различаются правилами дополнения входа. Например, для расчётов в Ethereum, где спецификация требует Keccak-256, используйте библиотеку с явной поддержкой Keccak-256. hash('sha3-256', $data) в таком протоколе выдаст другой результат.
Как посчитать SHA3-256 в PHP
hash() принимает имя алгоритма и строку байтов. В PHP 8.3–8.5 для SHA3-256 достаточно стандартного расширения Hash. По умолчанию функция возвращает 64 строчных шестнадцатеричных символа. Если передать true третьим аргументом, получится бинарная строка длиной 32 байта.
<?php
declare(strict_types=1);
$data = 'abc';
// Шестнадцатеричная строка для вывода или текстового поля.
echo hash('sha3-256', $data), PHP_EOL;
// Бинарные байты для поля BINARY(32) или обмена по протоколу.
$binaryDigest = hash('sha3-256', $data, true);
echo strlen($binaryDigest), PHP_EOL; // 32Хеш вычисляется по точным байтам строки. Перевод строки в конце файла, другой порядок полей JSON или смена кодировки меняют результат. Чтобы сверить полученные данные с контрольной суммой отправителя, хешируйте их в согласованном представлении. Если хеш нужен для сравнения структур по содержимому, заранее определите общий способ их сериализации.
Контрольная сумма файла и выбор алгоритма
hash_file() вычисляет дайджест файла без загрузки всего содержимого в строку. Это удобно для больших архивов и образов. При ошибке чтения функция может выдать предупреждение и возвращает false. Обработайте этот случай отдельно.
<?php
declare(strict_types=1);
// Передайте путь к файлу первым аргументом скрипта.
$path = $argv[1] ?? throw new InvalidArgumentException('Укажите путь к файлу');
$digest = hash_file('sha3-256', $path);
if ($digest === false) {
throw new RuntimeException('Не удалось прочитать файл');
}
echo $digest, PHP_EOL;Обычный хеш позволяет обнаружить изменение файла, если ожидаемый дайджест получен из доверенного источника. Когда злоумышленник может подменить и архив, и опубликованную рядом сумму, совпадение ничего не говорит о происхождении архива. Для подтверждения происхождения в такой схеме используют цифровую подпись и доверенный публичный ключ.
| Задача | Функция PHP | Что важно |
|---|---|---|
| Контрольная сумма или отпечаток данных | hash(), hash_file() | SHA-256 или SHA3-256. Алгоритм и формат дайджеста должны совпадать у обеих сторон. |
| Проверка подлинности запроса с общим секретом | hash_hmac(), hash_equals() | Используйте алгоритм, формат подписи и состав подписываемых данных из протокола. |
| Хранение и проверка паролей | password_hash(), password_verify() | Используйте Argon2id при наличии поддержки либо PASSWORD_DEFAULT с учётом ограничений выбранного алгоритма. |
Для новых криптографических задач выбирайте SHA-256 или SHA3-256. У MD5 и SHA-1 известны практические атаки на устойчивость к коллизиям, поэтому их применение уместно лишь там, где нужна совместимость и от хеша не зависит безопасность.
HMAC в PHP: как проверить подпись вебхука
Обычный дайджест может пересчитать любой, у кого есть сообщение. HMAC использует общий секрет, известный отправителю и получателю, и позволяет проверить подлинность и целостность данных. В PHP вызывайте hash_hmac($algo, $data, $secret). Для своего протокола подходит HMAC-SHA-256, а для стороннего вебхука параметры задаёт отправитель.
Ниже пример для протокола, в котором подписывается сырое тело запроса, а заголовок X-Signature содержит 64 строчных шестнадцатеричных символа без префикса. Загружайте секрет из конфигурации окружения или хранилища секретов. Если протокол включает метку времени, префикс подписи или Base64, обработайте их по его правилам.
<?php
declare(strict_types=1);
$secret = getenv('WEBHOOK_SECRET');
if ($secret === false || $secret === '') {
throw new RuntimeException('Не настроен секрет вебхука');
}
// Берём исходные байты до разбора JSON.
$body = file_get_contents('php://input');
if ($body === false) {
throw new RuntimeException('Не удалось прочитать тело запроса');
}
$received = $_SERVER['HTTP_X_SIGNATURE'] ?? '';
$expected = hash_hmac('sha256', $body, $secret);
// Сначала передаём вычисленную подпись, затем полученную.
if (!hash_equals($expected, $received)) {
http_response_code(403);
exit;
}
// После проверки можно разбирать тело и обрабатывать событие.hash_equals() сравнивает строки одинаковой длины за время, которое не зависит от содержимого. Даже с корректной подписью запрос может оказаться повтором. Если протокол подписывает метку времени, проверяйте допустимый возраст запроса. Для событий с уникальным идентификатором храните отметку обработки и обеспечьте атомарное обнаружение дублей, в том числе при одновременных доставках.
Почему для паролей нужна password_hash()
SHA-256 и SHA3-256 рассчитаны на быстрое хеширование. После утечки базы это позволяет проверять много вариантов пароля без участия приложения. password_hash() использует алгоритм с настраиваемой стоимостью вычислений и самостоятельно создаёт случайную соль для каждого пароля. Argon2id позволяет настроить и объём памяти на одну проверку, что усложняет массовый перебор.
<?php
declare(strict_types=1);
// Argon2id должен быть доступен в сборке PHP.
function createPasswordHash(string $password): string
{
return password_hash($password, PASSWORD_ARGON2ID);
}
function verifyPassword(string $password, string $storedHash): bool
{
// PHP извлекает алгоритм, соль и параметры из сохранённой строки.
return password_verify($password, $storedHash);
}Храните результат целиком, например в поле VARCHAR(255). Прежде чем выбрать PASSWORD_ARGON2ID, проверьте его наличие в password_algos() на целевом окружении. PASSWORD_DEFAULT в PHP 8.3–8.5 выбирает bcrypt, у которого предел входа составляет 72 байта. Многобайтовый пароль может достичь этого предела при меньшем числе символов. При использовании bcrypt явно отклоняйте более длинные пароли при задании и проверке, чтобы они не принимались после усечения.
После успешной проверки вызовите password_needs_rehash() с текущим алгоритмом и настройками. Если функция вернёт true, создайте новый хеш из только что проверенного пароля и сохраните его. Так параметры обновятся при входе даже для аккаунтов, созданных до смены алгоритма. При выборе стоимости измеряйте время проверки и потребление памяти под параллельной нагрузкой на сервере приложения.
Чек-лист перед внедрением
- Для отпечатка строки используйте
hash(), для файла —hash_file(). Зафиксируйте имя алгоритма и представление результата: байты или hex. - Если хешируете JSON, определите, какие байты должны совпадать. Для вебхука используйте исходное тело или другую последовательность байтов, которую требует протокол.
- Для вебхука с общим секретом вычисляйте HMAC и сравнивайте подписи через
hash_equals(). Учитывайте повторные доставки. - Для паролей храните полную строку
password_hash(), проверяйте её черезpassword_verify()и обновляйте параметры после успешного входа. - Перед изменением алгоритма найдите потребителей старых дайджестов. Если оба формата будут жить одновременно, храните идентификатор алгоритма рядом с дайджестом.
Частые вопросы
Как получить SHA3-256 в PHP и какой длины будет результат?
Вызовите hash('sha3-256', $data). По умолчанию результат содержит 64 строчных шестнадцатеричных символа. Третий аргумент true возвращает 32 бинарных байта.
Можно ли заменить SHA-256 на SHA3-256 в существующей интеграции?
Только если обе стороны согласовали замену. У алгоритмов одинаковая длина дайджеста, но разные результаты. Ранее сохранённые суммы и подписи проверяйте тем алгоритмом, которым они были рассчитаны.
Когда использовать hash_hmac(), а когда password_hash()?
Используйте hash_hmac() для проверки подлинности сообщений с общим секретом. Для хранения паролей применяйте password_hash() со случайной солью и настраиваемой стоимостью вычислений, а для входа используйте password_verify().