HMAC генератор и проверка подписи

Что такое HMAC?

const crypto = require('crypto');

// HMAC-SHA256 with a UTF-8 text key, hex output
const hmac = crypto
  .createHmac('sha256', 'my-secret-key')
  .update('Hello, World!')
  .digest('hex');

console.log(hmac);
// → 'cf3141611e22ea26a9cac6fe41d941274dd6653622c83cba13972d177bd69699'

// Verify a signature in constant time
function verify(message, key, expectedHex) {
  const actual = crypto.createHmac('sha256', key).update(message).digest();
  const expected = Buffer.from(expectedHex, 'hex');
  return actual.length === expected.length &&
    crypto.timingSafeEqual(actual, expected);
}

Ключевые возможности

Примеры HMAC

Hello, World!

cf3141611e22ea26a9cac6fe41d941274dd6653622c83cba13972d177bd69699

{"id":42,"event":"user.created"}

Cd2f7zTKaJFeG6k+t1FcvDPn51OAZ2f4GrxkCUgMhGs=

what do ya want for nothing?

5bdcc146bf60754e6a042426089575c75a003f089d2739839dec58b964ec3843

The quick brown fox

36f44b125a8a90639dc46733039571792e081e0fd8685ff746784b02ed14aa35629d562c7117cde4a701570551faa5a5e1b7ef1eb5c3bcd4cc1fdb8923fcf14e

Как сгенерировать и проверить HMAC

1. 1

   Выберите алгоритм

   Возьмите HMAC-SHA256 (по умолчанию и верный выбор почти для всех вебхуков, API и JWT) либо переключитесь на SHA-1, SHA-384 или SHA-512 под систему, которая этого требует. Все четыре работают нативно в вашем браузере через Web Crypto API.

2. 2

   Введите секретный ключ и задайте его кодировку

   Введите или вставьте секретный ключ, затем задайте кодировку ключа в соответствии с тем, как его интерпретирует сервер: Text (UTF-8) для обычной строки, Hex для шестнадцатеричного блока или Base64 для секрета в base64. Ошибка здесь — главная причина несовпадений HMAC, поэтому в случае сомнений попробуйте все три.

3. 3

   Введите сообщение

   Вставьте точные байты, которые хотите подписать — для вебхука это сырое тело запроса, байт в байт, без повторной сериализации и изменений пробелов. HMAC пересчитывается на лету по мере правки, и ничего не отправляется на сервер.

4. 4

   Выберите формат вывода и скопируйте

   Выберите Hex (в стиле GitHub), Base64 (в стиле Stripe/AWS) или Base64URL (в стиле JWT) под то, что ожидает ваша интеграция, затем нажмите «Копировать», чтобы взять подпись.

5. 5

   Проверьте существующую подпись

   Перейдите на вкладку «Проверить», вставьте ожидаемый HMAC из заголовка или токена, и инструмент за постоянное время подтвердит, совпадает ли ваша вычисленная подпись — чтобы вы могли аутентифицировать полезную нагрузку, прежде чем действовать.

Частые ошибки с HMAC

// Server stored a base64 secret but you sign the literal string
createHmac('sha256', 'c2VjcmV0LWtleQ==').update(msg)

// Decode the base64 secret to raw bytes first
createHmac('sha256', Buffer.from('c2VjcmV0LWtleQ==', 'base64')).update(msg)

// Provider sends base64, you compare hex
expected = 'Cd2f7z...=' // base64
actual   = digest('hex') // hex — never matches

// Produce the same encoding the provider uses
actual = digest('base64')

// Re-serialization changes the bytes
body = JSON.stringify(JSON.parse(rawBody))
verify(hmac(body))

// Sign the raw bytes exactly as received
verify(hmac(rawBody))

if (received === computed) { /* trust */ }

if (crypto.timingSafeEqual(receivedBuf, computedBuf)) { /* trust */ }

Для чего используется HMAC

Проверка подписей вебхуков

Провайдеры вроде GitHub, Stripe, Slack и Twilio подписывают каждый вебхук с помощью HMAC над телом запроса и секретом, который есть только у вас. Пересчитайте тег и сравните его с заголовком (например, X-Hub-Signature-256), чтобы убедиться, что событие подлинное, прежде чем действовать. Используйте вкладку «Проверить», чтобы сделать это без одноразового кода.

Подпись API-запросов

Аутентифицированные API часто требуют, чтобы клиент подписывал запрос (метод, путь, метку времени, тело) общим секретом с помощью HMAC, а не отправлял сам секрет. AWS Signature Version 4 — канонический пример. Этот инструмент позволяет воспроизводить и отлаживать такие подписи шаг за шагом.

Гарантия целостности сообщения

Когда вы передаёте токен, cookie или сообщение между сервисами, добавление HMAC позволяет получателю обнаружить любую подмену. Поскольку тег зависит от секрета, атакующий не может пересчитать его после изменения данных — в отличие от обычной контрольной суммы.

Понять подпись JWT HS256

JWT, подписанный HS256, — это просто base64url(header) + '.' + base64url(payload), подписанные HMAC-SHA256, а результат выдан в Base64URL. Установите здесь алгоритм SHA-256 и вывод Base64URL, чтобы увидеть, как именно создаётся эта подпись, затем сверьтесь в кодировщике JWT.

Отладка несовпадающей подписи

Когда ваш HMAC не совпадает с серверным, этот инструмент — самый быстрый способ изолировать причину: попробуйте ключ как Text, Hex и Base64, переключите вывод между Hex и Base64 и убедитесь, что подписываете точно те же сырые байты — и всё без передеплоя кода.

Как работает HMAC

Конструкция RFC 2104

HMAC определяется как H((K ⊕ opad) ‖ H((K ⊕ ipad) ‖ m)), где ipad — это повторённый байт 0x36, а opad — повторённый 0x5c, оба до размера блока хеша. Ключ длиннее размера блока сначала хешируется; более короткий ключ дополняется нулями. Именно это двухпроходное вложение даёт HMAC его доказательство безопасности, которое держится, даже если базовый хеш не стоек к коллизиям.

Почему хеш с ключом лучше обычного хеша

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

Устойчивость к удлинению сообщения

«Голые» SHA-1, SHA-256 и SHA-512 — это хеши Меркла–Дамгарда, уязвимые к удлинению сообщения: имея H(secret ‖ msg), атакующий может вычислить H(secret ‖ msg ‖ extra), не зная секрета. Наивные схемы «MAC с секретом-префиксом» этим ломаются. Внешний хеш HMAC нейтрализует атаку, и это главная причина использовать HMAC вместо хеширования секрета и сообщения вместе.

Выбор SHA-256 против SHA-512

HMAC-SHA256 даёт тег в 256 бит (64 hex-символа) и является стандартом совместимости — быстрый, повсеместный и поддерживаемый везде. HMAC-SHA512 даёт тег в 512 бит (128 hex-символов) и часто быстрее на 64-битных процессорах, поскольку SHA-512 использует 64-битные слова. Берите SHA-256, если спецификация или одноранговая система не требуют SHA-512; оба безопасны для аутентификации.

Реализация на Web Crypto

Этот инструмент вызывает crypto.subtle.importKey, чтобы загрузить ваш ключ (декодированный из Text, Hex или Base64), и crypto.subtle.sign('HMAC', ...), чтобы вычислить тег, затем кодирует сырые байты как Hex, Base64 или Base64URL. Это та же нативная, проаудированная реализация, которую браузер использует для TLS, работающая вне движка JavaScript ради скорости.

Лучшие практики HMAC

Используйте ключ не короче длины вывода хеша

Для HMAC-SHA256 используйте секрет не менее 32 случайных байт (256 бит); для SHA-512 — 64. Короткий или низкоэнтропийный ключ — самое слабое звено. Генерируйте ключи из криптографически стойкого источника случайности — никогда из пароля или предсказуемой строки.

Всегда сравнивайте теги за постоянное время

Проверяйте подписи сравнением за постоянное время (crypto.timingSafeEqual в Node, hmac.compare_digest в Python), а не == или равенством строк. Наивное сравнение завершается рано на первом отличающемся байте, утекая тайминг, который может позволить атакующему восстановить валидный тег байт за байтом. Вкладка «Проверить» этого инструмента уже сравнивает за постоянное время.

Никогда не логируйте и не раскрывайте секретный ключ

Держите секреты подписи вне логов, сообщений об ошибках, URL и клиентского кода. Храните их в менеджере секретов или переменных окружения, периодически ротируйте и привязывайте каждую интеграцию к своему ключу, чтобы одна утечка не скомпрометировала всё.

Предпочитайте HMAC-SHA256 или сильнее

По умолчанию берите HMAC-SHA256; поднимайтесь до SHA-384 или SHA-512, когда этого требует одноранговая сторона. Избегайте HMAC-SHA1 для новых систем и никогда не используйте HMAC-MD5. Хотя HMAC терпит слабый хеш лучше, чем это сделала бы сырая подпись, старт с современного хеша даёт максимальный запас прочности.

Подписывайте точные байты, включая метку времени

Подписывайте сырую, неизменённую полезную нагрузку — повторная сериализация JSON или обрезка пробелов меняет байты и ломает проверку. Для подписи запросов включайте метку времени или nonce в подписываемые данные и отклоняйте устаревшие подписи, чтобы предотвратить атаки повтора.

HMAC FAQ