Verificar una firma HMAC-SHA256: comparar los valores

PublicadoHerramientaGenerador de firmas HMAC

Contenido
  1. Qué suele pasar cuando la firma del webhook no coincide
  2. Cómo calcular un valor HMAC a mano, sin herramientas
  3. Las 4 cosas que más se pasan por alto cuando la firma no coincide
  4. En resumen
  5. Preguntas frecuentes

Cuando el valor de firma HMAC que llega en un webhook o en la respuesta de una API no coincide con el que has calculado tú, casi nunca se trata de una brecha de seguridad: lo habitual es que una de las tres entradas —el mensaje, la clave secreta o el algoritmo de hash— sea ligeramente distinta. Solo si esas tres entradas son exactamente iguales se obtiene el mismo valor de firma.

Este artículo muestra valores calculados de verdad como ejemplo y repasa qué conviene revisar primero cuando la firma no cuadra. No es un problema que exija el criterio de un experto: es un procedimiento que termina en cuanto vuelves a introducir las mismas entradas y comparas con tus propios ojos si sale el mismo valor.

Resumen ① El valor de firma HMAC se calcula a partir de tres entradas —mensaje, clave secreta y algoritmo de hash— y solo si las tres son exactamente iguales se obtiene el mismo valor. ② Las causas de que no coincida suelen ser espacios o saltos de línea, mayúsculas y minúsculas, el encoding (hexadecimal/Base64) o la elección del algoritmo. ③ La verificación consiste en recalcular con el mismo mensaje, la misma clave y el mismo algoritmo, y comparar el resultado carácter por carácter.

Qué suele pasar cuando la firma del webhook no coincide

Cuando un servicio externo envía un webhook para avisar de un evento —un pago completado, un cambio de estado de un pedido—, es habitual que adjunte el cuerpo de la petición (payload) junto con un valor de firma HMAC calculado sobre ese mismo cuerpo, dentro de una cabecera. El receptor calcula también la firma con la misma clave secreta y comprueba si coincide con el valor que llegó en la cabecera.

Cuando esa comparación falla, es fácil sospechar que hay un error en el código o que la petición ha sido falsificada. Pero lo que suele ocurrir es que no se usa el payload original tal cual, sino que se parsea y se vuelve a convertir en cadena, y en ese proceso se cuela un espacio de más o un salto de línea.

HMAC está diseñado precisamente para reaccionar a estas diferencias mínimas. Basta con que cambie un solo carácter del mensaje, una mayúscula en la clave secreta o el algoritmo de hash elegido para que el resultado sea una cadena completamente distinta de principio a fin.

Cómo calcular un valor HMAC a mano, sin herramientas

HMAC es un método de cálculo estandarizado que define el documento RFC 2104 y que firma un mensaje usando una clave secreta y un algoritmo de hash. Puedes reproducir ese cálculo directamente en la terminal, sin necesidad de ningún programa especial.

En macOS y Linux, OpenSSL viene instalado por defecto, así que puedes hacer el mismo cálculo con el siguiente comando:

echo -n "order:1001,amount:5000" | openssl dgst -sha256 -hmac "mySecretKey"

Al ejecutar el comando obtienes este resultado:

SHA2-256(stdin)= 148bec9dd63667edc6b3d37f9e7f5607c75144bd267159d843ec898b0667cea4

Es el valor que sale cuando usas el mensaje order:1001,amount:5000, la clave secreta mySecretKey y el algoritmo SHA-256. Con esas mismas tres entradas, el resultado es siempre este, sea cual sea el sistema operativo o el lenguaje de programación.

Comprobar que en otro lenguaje sale el mismo valor

De hecho, al calcular el mismo mensaje y la misma clave con el módulo hmac de Python, hemos comprobado que el valor es idéntico.

import hmac, hashlib
hmac.new(b"mySecretKey", b"order:1001,amount:5000", hashlib.sha256).hexdigest()

Si te olvidas de la opción -n en echo, se añade automáticamente un carácter de salto de línea al final del mensaje y, aunque el mensaje, la clave y el algoritmo sean los mismos, el valor sale completamente distinto. Este problema lo volverás a ver con valores reales en el apartado siguiente.

Vamos a comprobarlo directamente con nuestro Generador de firmas HMAC.

Generador de firmas HMAC

Se calcula al instante en el navegador con la Web Crypto API, y el mensaje y la clave secreta que introduces no se envían a ningún servidor.

Las 4 cosas que más se pasan por alto cuando la firma no coincide

Con el mismo mensaje order:1001,amount:5000 y la misma clave secreta mySecretKey, si calculas la firma SHA-256 cambiando solo un detalle minúsculo cada vez, obtienes resultados como estos.

Original:                        order:1001,amount:5000
Resultado SHA-256:               148bec9dd63667edc6b3d37f9e7f5607c75144bd267159d843ec898b0667cea4

Con salto de línea al final:     order:1001,amount:5000  (seguido de 1 carácter de nueva línea)
Resultado SHA-256:               015bc2c0bf5cc82fd005e37b7a2b0ae8777e41a109bae303b263aaa162f32cff

Solo la primera letra en mayúscula:  Order:1001,amount:5000
Resultado SHA-256:               11c1403b448d39601f4a14119514f6a44b16bdcb378f384d767ffafc0054ffb2

Cuando el mensaje en sí difiere mínimamente

El mensaje parece prácticamente igual a simple vista, pero el resultado es distinto desde el primer carácter. Muchas veces este es el verdadero trasfondo de eso de «la firma no coincide». No es que la clave se haya filtrado ni que la lógica esté mal: es que las dos cadenas que estás comparando en realidad no son iguales.

Cuando el encoding o el algoritmo son distintos

Aunque la firma sea la misma, si el formato de representación cambia, la cadena se ve distinta. Si expresas en Base64 el resultado del ejemplo original anterior, obtienes FIvsndY2Z+3Gs9N/nn9WB8dRRL0mcVnYQ+yJiwZnzqQ=, que no es más que esa misma firma escrita en Base64 en lugar de en hexadecimal.

Si el valor que llega en la cabecera está en hexadecimal y tú calculas en Base64 para comparar, es normal que parezcan distintos.

Si el algoritmo en sí es diferente, la diferencia empieza por la longitud. Con el mismo mensaje y la misma clave, SHA-1 produce una cadena hexadecimal de 40 caracteres, SHA-256 de 64, SHA-384 de 96 y SHA-512 de 128.

Si calculas el mensaje anterior con SHA-1, obtienes d67244f34d44c077a2a3dada4528c8284c2951cb, que se diferencia de SHA-256 tanto en longitud como en valor. Estas son las cuatro causas:

CausaSíntomaCómo comprobarlo
Espacio o salto de línea al final del mensajeEl texto original parece igual, pero el valor no coincideRevisa a mano si hay un espacio o un salto de línea al final del mensaje
Diferencia de mayúsculas y minúsculasSolo cambia una parte del nombre de un campo o de un valorCompara carácter por carácter si copiaste el payload original tal cual
Diferencia de encoding (hexadecimal/Base64)Cambian la longitud y los caracteres que lo componen (Base64 incluye +, /, =)Comprueba primero si la firma que comparas está en hexadecimal o en Base64
Algoritmo distintoLa longitud del valor en sí cambia (40/64/96/128 caracteres)Verifica que el algoritmo que indicó el emisor sea el mismo que elegiste tú

En resumen

  1. El valor de firma HMAC viene determinado por tres entradas —mensaje, clave secreta y algoritmo—, y solo si las tres coinciden sale el mismo valor.
  2. Basta con que haya un espacio o un salto de línea de más en el mensaje para que el resultado cambie por completo.
  3. Si las longitudes no coinciden, en nueve de cada diez casos el problema está en el encoding (hexadecimal/Base64) o en el algoritmo.
  4. Para verificar basta con recalcular con esas mismas tres entradas y comparar carácter por carácter el valor obtenido con el que has recibido.
  5. Recalcular a mano con el comando openssl dgst o con una herramienta del navegador te ayuda a acotar cuál de las entradas es la que difiere.
Generador de firmas HMAC

Se calcula al instante en el navegador con la Web Crypto API, y el mensaje y la clave secreta que introduces no se envían a ningún servidor.

Preguntas frecuentes

Uso el mismo mensaje y la misma clave, pero el valor sale distinto cada vez. ¿Es normal?

No. HMAC es un cálculo determinista: si el mensaje, la clave secreta y el algoritmo son los mismos, el valor es siempre idéntico, se calcule donde se calcule. Si el valor cambia todo el rato, significa que una de las tres cosas está cambiando de verdad. Es habitual que el mensaje incluya un dato variable, como la hora actual.

¿Qué formato es el correcto, hexadecimal o Base64?

Ninguno de los dos es «el correcto»: son dos formas de representar los mismos bytes de resultado. Tienes que usar la misma que empleó quien envió la firma para que los valores coincidan. Si el valor solo contiene 0-9 y a-f, es hexadecimal; si aparecen los caracteres +, / y =, es Base64.

¿Cómo averiguo el algoritmo si no lo sé?

Deja el mensaje y la clave tal cual y calcula con SHA-256, SHA-384, SHA-512 y SHA-1, en ese orden; empieza comparando con el algoritmo cuya longitud coincida con el valor recibido. En muchos casos el algoritmo está indicado en la documentación o en la especificación de la API, así que lo más fiable es revisarlo primero.

Si el mensaje incluye caracteres no ASCII (tildes, eñes, coreano), ¿el valor cambia?

Si el encoding es el mismo (por ejemplo, UTF-8), la misma cadena siempre se convierte en los mismos bytes y da el mismo valor. Ahora bien, si en el proceso de guardado o de envío cambia la codificación de caracteres (por ejemplo, un lado usa UTF-8 y el otro EUC-KR), los caracteres pueden parecer iguales pero los bytes reales son distintos y el resultado puede cambiar.

Este artículo está adaptado de nuestro original en coreano. Leer el original en coreano

Artículos relacionados

  1. Previsualización de email HTML en móvil, tablet y PCComprueba en el navegador cómo se ve tu código de email HTML en móvil, tablet y PC, y por qué conviene usar tablas y estilos en línea.
  2. Convertir entidades HTML: 5 reglas de codificaciónCómo se convierten <, >, & y las comillas en entidades HTML, en qué orden, y cómo devolver entidades numéricas y con nombre a su carácter original.
  3. Caracteres especiales HTML: escapar, desescapar y tabla 1:1Por qué &, <, >, " y ' se escapan en HTML, la tabla de conversión 1:1, el orden correcto al sustituir y cómo comprobar el resultado.
  4. Convertir HTML a cadena de JavaScript: guía y erroresAprende por qué los modos de comillas y de backticks tratan los saltos de línea de forma distinta y cómo evitar los errores de sintaxis más comunes.
  5. Eliminar espacios en HTML: por qué solo se borran entre etiquetasQué borra realmente la minificación de HTML: espacios entre etiquetas, saltos de línea y comentarios, y por qué script, style, pre y textarea se conservan intactos.
  6. Generador de htpasswd: crea el archivo sin instalar nadaCrea la línea usuario:hash de .htpasswd para la autenticación básica de Apache y Nginx en el navegador, con la estructura {SHA} y {SHA256} explicada.

Herramientas relacionadas