Вычислите HMAC или проверьте подпись, которую прислал вебхук
Этот HMAC генератор подписывает сообщение секретным ключом с помощью HMAC-SHA256, HMAC-SHA1, HMAC-SHA384 или HMAC-SHA512 и сразу показывает подпись в hex строчными и заглавными буквами, в Base64 и в Base64url. Ключ и сообщение можно ввести как обычный текст, hex или Base64, поэтому инструмент работает и с сырыми бинарными секретами, и с паролями. Вставьте полученную подпись — <code>sha256=…</code> от GitHub, заголовок Stripe <code>t=…,v1=…</code> или просто Base64 — и вы узнаете, совпадает ли она. Вычисление выполняет Web Crypto API вашего браузера; ключ и сообщение никогда не покидают страницу.
Как создать или проверить HMAC
- 1Выберите хеш-функцию: SHA-256 используют большинство API и вебхуков.
- 2Введите или вставьте секретный ключ и укажите, в каком виде он записан: текст, hex или Base64. Кнопка Случайный ключ создаст новый секрет нужной длины.
- 3Вставьте сообщение — для вебхука это сырое тело запроса ровно в том виде, в каком оно пришло, байт в байт.
- 4Скопируйте подпись в нужной кодировке. Чтобы проверить подпись, вставьте её в поле Ожидаемая подпись; префикс вроде
sha256=распознаётся и игнорируется.
Что такое HMAC?
HMAC (hash-based message authentication code, RFC 2104) — это короткое значение, вычисляемое из сообщения и секретного ключа. Любой, кто знает ключ, может вычислить то же значение и тем самым проверить сразу две вещи: что сообщение не изменили по пути и что его создал владелец ключа. Без ключа злоумышленник не может ни подделать корректный HMAC для нового сообщения, ни подогнать существующий после изменения сообщения.
Это не просто хеш склеенных ключа и сообщения. HMAC хеширует дважды, подмешивая ключ во внутреннее и внешнее дополнение: H((K ⊕ opad) ‖ H((K ⊕ ipad) ‖ message)). Именно эта конструкция делает его безопасным с SHA-256 и SHA-512, которые сами по себе уязвимы к атаке удлинения сообщения (length extension), если использовать их как H(key ‖ message).
Проверка подписей вебхуков
Большинство провайдеров вебхуков подписывают каждый запрос HMAC от тела и кладут результат в заголовок. Чтобы проверить подпись, вычислите HMAC от сырого тела с вашим секретом подписи и сравните со значением заголовка. Самая частая ошибка — хешировать заново сериализованный JSON-объект вместо пришедших байтов: другой порядок ключей или пропавший пробел полностью меняют подпись.
Некоторые провайдеры подписывают не только тело. Stripe подписывает timestamp.body — значение t из заголовка, точку и затем payload, — а Slack подписывает v0:timestamp:body. Соберите здесь именно такую строку в качестве сообщения и вставьте заголовок целиком в поле проверки; значение v1= или v0= будет извлечено из него.
- GitHub
- <code>X-Hub-Signature-256: sha256=<hex></code>, HMAC-SHA256 от тела с секретом вебхука как текстом.
- Stripe
- <code>Stripe-Signature: t=…,v1=<hex></code>, HMAC-SHA256 от <code>t.body</code>.
- Shopify
- <code>X-Shopify-Hmac-Sha256: <Base64></code>, HMAC-SHA256 от тела.
- Slack
- <code>X-Slack-Signature: v0=<hex></code>, HMAC-SHA256 от <code>v0:timestamp:body</code>.
Ключи в виде текста, hex и Base64
Ключ — это последовательность байтов, и важно, как он записан. Текст abc123 — это шесть байтов, а hex abc123 — три совершенно других байта. Многие сервисы выдают секреты в виде строк hex или Base64, но ожидают, что вы используете саму строку как текстовый ключ (так делают и GitHub, и Stripe), а другие, например цепочки подписи в стиле AWS и прокси приложений Shopify, используют декодированные байты. Если подпись не совпадает, первым делом попробуйте сменить кодировку ключа.
Для нового ключа используйте случайные байты длиной не меньше выхода хеша: 32 байта для HMAC-SHA256, 64 для HMAC-SHA512. Более длинный ключ ничего не добавляет — всё, что длиннее размера блока хеша, сначала хешируется.
Сравнение за постоянное время
Когда ваш сервер проверяет подпись, сравнивайте её функцией с постоянным временем выполнения, например crypto.timingSafeEqual в Node.js, hmac.compare_digest в Python или hash_equals в PHP. Обычное сравнение строк останавливается на первом отличающемся символе, и затраченное время может выдать, какая часть поддельной подписи была верной. Эта страница использует тот же приём с постоянным временем, поэтому код служит не только проверкой, но и образцом.
Если вам нужна обычная контрольная сумма файла или текста без ключа, воспользуйтесь генератором хешей. Для подписи токенов генератор JWT-секрета создаёт ключи HS256 нужного размера.
Часто задаваемые вопросы
- Чем хеш отличается от HMAC?
- Хеш вроде SHA-256 зависит только от данных, поэтому его может пересчитать кто угодно. HMAC зависит ещё и от секретного ключа, поэтому создать или проверить его может только владелец ключа. Поэтому HMAC подтверждает подлинность, а не только целостность.
- Почему мой HMAC не совпадает с HMAC от API?
- Почти всегда отличаются входные данные: сообщение не совпадает байт в байт с сырым телом (заново сериализованный JSON, перевод строки в конце, другие окончания строк), ключ читается как текст, хотя сервис имеет в виду байты hex или Base64, или наоборот, либо провайдер подписывает метку времени вместе с телом, а не одно тело.
- Какой алгоритм HMAC выбрать?
- HMAC-SHA256 — стандартный выбор, его используют почти все API. HMAC-SHA512 ничуть не хуже и быстрее на 64-битных серверах. HMAC-SHA1 по-прежнему безопасен как HMAC, несмотря на коллизии SHA-1, но используйте его, только если этого требует протокол.
- HMAC-SHA1 взломан?
- Нет. Коллизии SHA-1 не позволяют подделать HMAC-SHA1 без ключа, и практических атак на HMAC-SHA1 не известно. Для новых систем он не рекомендуется, но проверять старые подписи HMAC-SHA1 безопасно.
- Можно ли здесь вычислить HMAC-MD5?
- Нет. Web Crypto API браузера, на котором работает эта страница, не поддерживает MD5. HMAC-MD5 остался только в старых протоколах; для всего нового используйте HMAC-SHA256.
- Какой длины должен быть ключ HMAC?
- Не короче выхода хеша: 32 случайных байта для HMAC-SHA256, 48 для SHA-384, 64 для SHA-512. Кнопка «Случайный ключ» генерирует ровно столько с помощью криптостойкого генератора случайных чисел вашего браузера.
- Можно ли использовать пустой ключ?
- HMAC это допускает, и результат чётко определён, поэтому инструмент его показывает, но пустой или короткий ключ не даёт никакой защиты. Ту же подпись сможет вычислить кто угодно.
- Отправляется ли мой секретный ключ куда-либо?
- Нет. HMAC вычисляется Web Crypto API вашего браузера на этой странице. Ничего из того, что вы вводите, не загружается и не сохраняется.