Verificar una firma HMAC-SHA256: comparar los valores

Contenido
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.
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:
| Causa | Síntoma | Cómo comprobarlo |
|---|---|---|
| Espacio o salto de línea al final del mensaje | El texto original parece igual, pero el valor no coincide | Revisa a mano si hay un espacio o un salto de línea al final del mensaje |
| Diferencia de mayúsculas y minúsculas | Solo cambia una parte del nombre de un campo o de un valor | Compara 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 distinto | La 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
- 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.
- 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.
- Si las longitudes no coinciden, en nueve de cada diez casos el problema está en el encoding (hexadecimal/Base64) o en el algoritmo.
- 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.
- Recalcular a mano con el comando
openssl dgsto con una herramienta del navegador te ayuda a acotar cuál de las entradas es la que difiere.
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