Generador HMAC y verificador de firmas

¿Qué es un 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);
}

Funciones clave

Ejemplos de HMAC

Hello, World!

cf3141611e22ea26a9cac6fe41d941274dd6653622c83cba13972d177bd69699

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

Cd2f7zTKaJFeG6k+t1FcvDPn51OAZ2f4GrxkCUgMhGs=

what do ya want for nothing?

5bdcc146bf60754e6a042426089575c75a003f089d2739839dec58b964ec3843

The quick brown fox

36f44b125a8a90639dc46733039571792e081e0fd8685ff746784b02ed14aa35629d562c7117cde4a701570551faa5a5e1b7ef1eb5c3bcd4cc1fdb8923fcf14e

Cómo generar y verificar un HMAC

1. 1

   Elegir el algoritmo

   Elige HMAC-SHA256 (el predeterminado y la opción correcta para casi todos los webhooks, API y JWT), o cambia a SHA-1, SHA-384 o SHA-512 para coincidir con un sistema que lo requiera. Los cuatro se ejecutan de forma nativa en tu navegador mediante la API Web Crypto.

2. 2

   Introducir la clave secreta y fijar su codificación

   Escribe o pega tu clave secreta, luego ajusta la codificación de clave para que coincida con cómo la interpreta el servidor: Texto (UTF-8) para una cadena normal, Hex para un bloque hexadecimal, o Base64 para un secreto en base64. Equivocarse aquí es la principal causa de desajustes de HMAC, así que ante la duda prueba las tres.

3. 3

   Introducir el mensaje

   Pega los bytes exactos que quieres firmar: para un webhook, este es el cuerpo crudo de la solicitud, byte a byte, sin reserialización ni cambios de espacios. El HMAC se recalcula en vivo mientras editas, sin enviar nada a un servidor.

4. 4

   Elegir el formato de salida y copiar

   Selecciona Hex (estilo GitHub), Base64 (estilo Stripe/AWS) o Base64URL (estilo JWT) para coincidir con lo que espera tu integración, luego haz clic en Copiar para obtener la firma.

5. 5

   Verificar una firma existente

   Cambia a la pestaña Verificar, pega el HMAC esperado de una cabecera o token, y la herramienta confirma en tiempo constante si tu firma calculada coincide, para que puedas autenticar un contenido antes de actuar sobre él.

Errores comunes de 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 */ }

Para qué se usa HMAC

Verificar firmas de webhook

Proveedores como GitHub, Stripe, Slack y Twilio firman cada webhook con un HMAC sobre el cuerpo de la solicitud y un secreto que solo tú compartes. Recalcula la etiqueta y compárala con la cabecera (por ejemplo X-Hub-Signature-256) para confirmar que el evento es genuino antes de actuar sobre él. Usa la pestaña Verificar para hacerlo sin escribir código desechable.

Firmar solicitudes de API

Las API autenticadas suelen exigir que el cliente firme la solicitud con HMAC (método, ruta, marca de tiempo, cuerpo) usando un secreto compartido en lugar de enviar el secreto mismo. AWS Signature Version 4 es el ejemplo canónico. Esta herramienta te permite reproducir y depurar esas firmas paso a paso.

Garantizar la integridad de los mensajes

Cuando pasas un token, una cookie o un mensaje entre servicios, adjuntar un HMAC permite al receptor detectar cualquier manipulación. Como la etiqueta depende de un secreto, un atacante no puede recalcularla tras modificar los datos, a diferencia de una simple suma de comprobación.

Entender la firma HS256 de los JWT

Un JWT firmado con HS256 es simplemente base64url(cabecera) + '.' + base64url(contenido), firmado con HMAC-SHA256 y con el resultado emitido como Base64URL. Ajusta el algoritmo a SHA-256 y la salida a Base64URL aquí para ver exactamente cómo se produce esa firma, y luego compruébalo en el codificador JWT.

Depurar una firma que no coincide

Cuando tu HMAC no coincide con el del servidor, esta herramienta es la forma más rápida de aislar por qué: prueba la clave como Texto, Hex y Base64, cambia la salida entre Hex y Base64, y confirma que estás firmando exactamente los bytes crudos, todo sin volver a desplegar código.

Cómo funciona HMAC

Construcción de la RFC 2104

HMAC se define como H((K ⊕ opad) ‖ H((K ⊕ ipad) ‖ m)), donde ipad es el byte 0x36 repetido y opad es 0x5c repetido, ambos hasta el tamaño de bloque del hash. Una clave más larga que el tamaño de bloque se hashea primero; una clave más corta se rellena con ceros. Esta anidación de dos pasadas es lo que le da a HMAC su prueba de seguridad, que se mantiene incluso si el hash subyacente no es resistente a colisiones.

Por qué un hash con clave supera a un hash simple

Un hash simple solo prueba que los datos no se corrompieron accidentalmente, porque cualquiera puede recalcularlo para cualquier mensaje, incluido uno manipulado. HMAC mezcla un secreto, de modo que solo quienes poseen la clave pueden producir una etiqueta válida. Eso convierte la mera integridad en integridad más autenticidad, que es la propiedad que realmente necesitan los webhooks y las solicitudes firmadas.

Resistencia a la extensión de longitud

SHA-1, SHA-256 y SHA-512 puros son hashes Merkle–Damgård vulnerables a la extensión de longitud: dado H(secreto ‖ msg), un atacante puede calcular H(secreto ‖ msg ‖ extra) sin conocer el secreto. Los esquemas ingenuos de «MAC con prefijo secreto» quedan rotos por esto. El hash externo de HMAC neutraliza el ataque, que es la principal razón para usar HMAC en lugar de hashear juntos un secreto y un mensaje.

Elegir SHA-256 frente a SHA-512

HMAC-SHA256 produce una etiqueta de 256 bits (64 caracteres hex) y es el predeterminado para la interoperabilidad: rápido, omnipresente y compatible en todas partes. HMAC-SHA512 produce una etiqueta de 512 bits (128 caracteres hex) y suele ser más rápido en CPU de 64 bits porque SHA-512 usa palabras de 64 bits. Elige SHA-256 a menos que una especificación o un sistema par requiera SHA-512; ambos son seguros para la autenticación.

Implementación con Web Crypto

Esta herramienta llama a crypto.subtle.importKey para cargar tu clave (decodificada desde Texto, Hex o Base64) y a crypto.subtle.sign('HMAC', ...) para calcular la etiqueta, luego codifica los bytes crudos como Hex, Base64 o Base64URL. Es la misma implementación nativa y auditada que el navegador usa para TLS, ejecutándose fuera del motor de JavaScript para mayor rapidez.

Buenas prácticas de HMAC

Usar una clave al menos tan larga como la salida del hash

Para HMAC-SHA256 usa un secreto de al menos 32 bytes aleatorios (256 bits); para SHA-512 usa 64. Una clave corta o de baja entropía es el eslabón más débil. Genera las claves desde una fuente aleatoria criptográficamente segura, nunca una contraseña o una cadena predecible.

Comparar siempre las etiquetas en tiempo constante

Verifica las firmas con una comparación en tiempo constante (crypto.timingSafeEqual en Node, hmac.compare_digest en Python) en lugar de == o igualdad de cadenas. Una comparación ingenua termina pronto en el primer byte distinto, filtrando una temporización que puede permitir a un atacante recuperar una etiqueta válida byte a byte. La pestaña Verificar de esta herramienta ya compara en tiempo constante.

Nunca registrar ni exponer la clave secreta

Mantén los secretos de firma fuera de los registros, los mensajes de error, las URL y el código del lado del cliente. Guárdalos en un gestor de secretos o en variables de entorno, rótalos periódicamente, y limita cada integración a su propia clave para que una sola filtración no comprometa todo.

Preferir HMAC-SHA256 o más fuerte

Usa por defecto HMAC-SHA256; sube a SHA-384 o SHA-512 cuando un par lo requiera. Evita HMAC-SHA1 para sistemas nuevos y nunca uses HMAC-MD5. Aunque HMAC tolera mejor un hash más débil que una firma cruda, partir de un hash moderno te da el mayor margen.

Firmar los bytes exactos, incluida una marca de tiempo

Firma el contenido crudo y sin modificar: reserializar el JSON o recortar espacios cambia los bytes y rompe la verificación. Para la firma de solicitudes, incluye una marca de tiempo o un nonce en los datos firmados y rechaza las firmas caducadas para prevenir ataques de repetición.

Preguntas frecuentes sobre HMAC