Verificar firmas de webhooks con HMAC
La cabecera X-Signature de un webhook de Chaingateway permite comprobar que una solicitud procede realmente de Chaingateway. Contiene el HMAC-SHA256 del id de transacción (txid) del payload, calculado con su secreto personal y codificado en base64. Su receptor recalcula el valor y lo compara con la cabecera. La cabecera se envía una vez fijado un secreto personal.
¿Contra qué protege la cabecera X-Signature?
Sección titulada «¿Contra qué protege la cabecera X-Signature?»Protege contra solicitudes falsificadas: cualquiera puede enviar una solicitud POST a la URL pública de su receptor, pero solo un emisor que conozca el secreto personal puede generar una firma válida. HMAC, definido en la RFC 2104, combina una función hash con una clave secreta, aquí SHA-256. NIST FIPS 198-1 especifica la misma construcción como Keyed-Hash Message Authentication Code.
La firma cubre el txid y nada más. El importe, las direcciones y los campos del token del cuerpo no están firmados. Por eso un par válido de txid y firma no demuestra que el resto del cuerpo no haya cambiado. Tras la comprobación, trate el txid como clave de búsqueda: lea la transacción con GET /api/v2/{chain}/transactions/{txid} y acredite el pago con los datos que devuelve la API, no con el importe del cuerpo de la notificación.
¿Cómo configuro el secreto personal?
Sección titulada «¿Cómo configuro el secreto personal?»Puede configurar o regenerar el secreto personal en los ajustes de su perfil. Siga estos pasos:
- Abra la configuración del perfil.
- Localice la sección etiquetada como «Personal Secret».
- Si no hay ningún secreto, haga clic en «Set Personal Secret» para generar uno. Si ya existe uno, haga clic en «Regenerate Secret» para sustituirlo.
Dos detalles importan en un sistema en producción. Si todavía no tiene un secreto personal, añadir uno activa la cabecera X-Signature en todos los webhooks salientes. Despliegue un receptor que acepte y verifique la cabecera antes de hacerlo. Si regenera un secreto existente, el nuevo secreto se aplica de inmediato a las notificaciones de webhook. Actualice el receptor al mismo tiempo, o rechazará solicitudes válidas.
¿Cómo se construye la cabecera X-Signature?
Sección titulada «¿Cómo se construye la cabecera X-Signature?»Chaingateway lee el txid del payload, calcula sobre él un HMAC con la función hash SHA-256 usando el secreto personal como clave, y codifica en base64 los 32 bytes del resultado. El txid es el identificador único de la transacción que ya aparece en el cuerpo del webhook, así que el receptor tiene todo lo necesario para recalcular el valor. El secreto solo lo comparten Chaingateway y usted.
¿Cómo verifico la firma en mi código?
Sección titulada «¿Cómo verifico la firma en mi código?»Recalcule el HMAC a partir del txid del cuerpo y compárelo con el valor de la cabecera. Use una función de comparación en tiempo constante, para que el tiempo de la comparación no revele nada del valor esperado. Los ejemplos siguientes lo hacen en Python, Java, PHP y JavaScript.
import hmacimport hashlibimport base64
def verify_signature(txid, received_signature, personal_secret): # Generate the expected signature expected_signature = base64.b64encode(hmac.new( personal_secret.encode(), txid.encode(), hashlib.sha256 ).digest()).decode()
# Compare the expected signature with the received signature return hmac.compare_digest(expected_signature, received_signature)
# Example usagetxid = 'your_txid_here'received_signature = 'received_signature_here'personal_secret = 'your_personal_secret_here'
if verify_signature(txid, received_signature, personal_secret): print("Signature is valid.")else: print("Invalid signature.")import javax.crypto.Mac;import javax.crypto.spec.SecretKeySpec;import java.nio.charset.StandardCharsets;import java.security.MessageDigest;import java.util.Base64;
public class SignatureVerifier { public static boolean verifySignature(String txid, String receivedSignature, String personalSecret) throws Exception { Mac mac = Mac.getInstance("HmacSHA256"); SecretKeySpec secretKeySpec = new SecretKeySpec(personalSecret.getBytes(StandardCharsets.UTF_8), "HmacSHA256"); mac.init(secretKeySpec);
byte[] signatureBytes = mac.doFinal(txid.getBytes(StandardCharsets.UTF_8)); String expectedSignature = Base64.getEncoder().encodeToString(signatureBytes);
// Constant-time comparison return MessageDigest.isEqual( expectedSignature.getBytes(StandardCharsets.UTF_8), receivedSignature.getBytes(StandardCharsets.UTF_8)); }
public static void main(String[] args) { try { String txid = "your_txid_here"; String receivedSignature = "received_signature_here"; String personalSecret = "your_personal_secret_here";
if (verifySignature(txid, receivedSignature, personalSecret)) { System.out.println("Signature is valid."); } else { System.out.println("Invalid signature."); } } catch (Exception e) { e.printStackTrace(); } }}<?phpfunction verifySignature($txid, $receivedSignature, $personalSecret) { // Generate the expected signature $expectedSignature = base64_encode(hash_hmac('sha256', $txid, $personalSecret, true));
// Compare the expected signature with the received signature return hash_equals($expectedSignature, $receivedSignature);}
// Example usage$txid = 'your_txid_here';$receivedSignature = 'received_signature_here';$personalSecret = 'your_personal_secret_here';
if (verifySignature($txid, $receivedSignature, $personalSecret)) { echo "Signature is valid.";} else { echo "Invalid signature.";}const crypto = require('crypto');
function verifySignature(txid, receivedSignature, personalSecret) { // Generate the expected signature const expectedSignature = crypto .createHmac('sha256', personalSecret) .update(txid) .digest('base64');
// timingSafeEqual throws if the lengths differ, so check them first const expected = Buffer.from(expectedSignature); const received = Buffer.from(receivedSignature); return expected.length === received.length && crypto.timingSafeEqual(expected, received);}
// Example usageconst txid = 'your_txid_here';const receivedSignature = 'received_signature_here';const personalSecret = 'your_personal_secret_here';
if (verifySignature(txid, receivedSignature, personalSecret)) { console.log("Signature is valid.");} else { console.log("Invalid signature.");}¿Cómo puedo probar mi código de verificación?
Sección titulada «¿Cómo puedo probar mi código de verificación?»Pruebe la función con una entrada fija antes de conectarla al tráfico real. Los valores siguientes son un vector de prueba que puede reproducir con cualquier herramienta HMAC-SHA256. El secreto es un marcador de posición, no un secreto personal real. Si su función devuelve otro valor para esta entrada, el error está en su código y no en el webhook.
personal_secret: my_personal_secrettxid: 18f52f2a55b94a6e3705de4abb18e95dfce79970f27b29450705c561e12b6988X-Signature: t2vU2mYBCv/UvpKprNJB7qbgrCpPXKb6NWgL77xsZgQ=Los errores habituales son calcular el hash de todo el cuerpo JSON en lugar del txid, usar el digest hexadecimal en lugar de base64 y comparar con ==, que no es en tiempo constante. Recuerde también que el secreto personal vale para toda la cuenta. Un secreto que regenere en los ajustes del perfil cambia a la vez la firma de todos los webhooks de la cuenta.
¿Qué debo hacer cuando la firma no coincide?
Sección titulada «¿Qué debo hacer cuando la firma no coincide?»Rechace la solicitud con un estado de error como 401 o 403 y no procese el cuerpo. Registre el txid, la cabecera recibida y la dirección de origen, para distinguir un secreto mal configurado de una solicitud falsificada. Si el mismo emisor produce discrepancias justo después de regenerar el secreto, el receptor sigue usando el antiguo. Una solicitud falsificada que solo adivina un txid no puede producir una firma válida sin el secreto.
¿Qué más debe hacer un receptor de webhooks?
Sección titulada «¿Qué más debe hacer un receptor de webhooks?»La verificación de la firma es una capa. Las medidas siguientes cubren el resto del recorrido.
- Sirva el receptor por HTTPS, para que el payload viaje cifrado. La REST Security Cheat Sheet de OWASP recomienda HTTPS para todo endpoint que maneje datos sensibles.
- Rechace con un estado de error las solicitudes con un
X-Signatureausente o incorrecto, y regístrelas. - Use el
txidcomo clave de idempotencia. Una notificación que reenvía conPOST /api/v2/{chain}/webhooks/notifications/{id}/retrylleva el mismotxidy no debe acreditar un pago dos veces. - Guarde el secreto personal en un almacén de secretos, nunca en el repositorio, y rótelo si pudo filtrarse. Chaingateway no reintenta por sí mismo las entregas fallidas, así que planifique la actualización del receptor y del secreto como un solo paso, y reenvíe después las notificaciones perdidas desde la lista de fallidas.
Fuentes
Sección titulada «Fuentes»- RFC 2104, HMAC: Keyed-Hashing for Message Authentication
- NIST FIPS 198-1, The Keyed-Hash Message Authentication Code (HMAC)
- OWASP REST Security Cheat Sheet
- Webhooks en esta documentación para el payload y los endpoints de reintento.