Seguridad de la API blockchain: 6 consejos prácticos
Seis prácticas de seguridad para una API blockchain: generación de claves, custodia sin conexión, firma local, direcciones, tokens de API y webhooks firmados.
Revisado por Maurice Sobiera
La seguridad de una API blockchain es el conjunto de prácticas que mantienen alejados de los atacantes las claves privadas, los tokens de API y el tráfico de webhooks. El riesgo está en la gestión de claves, en las credenciales y en el endpoint de webhooks, no en la blockchain. Estas seis prácticas valen para Chaingateway y para cualquier API similar.
¿Cómo debe generar las claves privadas?
Genere las claves privadas con un generador de números aleatorios criptográficamente seguro, y hágalo en un entorno que usted controle. La Hoja de referencia de OWASP sobre almacenamiento criptográfico indica que las claves deben proceder de una función criptográficamente segura, y no construirse con palabras comunes ni con combinaciones de teclas tecleadas al azar. Una clave débil o predecible puede adivinarse, y quien la adivine puede gastar los fondos.
Chaingateway puede crear una dirección por usted mediante POST /api/v2/{blockchain}/addresses. La guía de gestión de monederos describe dos modos. Con un password, la clave privada se guarda cifrada de nuestro lado y usted usa la contraseña para enviar transacciones. Sin contraseña, la respuesta contiene la clave privada en texto plano, lo cual sirve para una dirección temporal pero no para una que piense conservar. Si quiere control total, genere la clave en su propio equipo o en un monedero de hardware, e impórtela solo si lo necesita.
¿Cómo debe almacenar las claves privadas?
Guarde sin conexión las claves que custodian fondos a largo plazo, y deje solo los saldos de trabajo en claves que estén en un servidor. Una clave en un equipo conectado a internet puede robarla cualquiera que comprometa ese equipo. Los monederos de hardware y las copias de seguridad sin conexión eliminan esa exposición, aunque un monedero de hardware puede perderse, así que conserve una copia de recuperación probada.
Nunca escriba claves ni contraseñas en el código fuente, en los registros o en los tickets. La Hoja de referencia de OWASP sobre gestión de secretos señala que muchas organizaciones codifican secretos en texto plano en el código y en los archivos de configuración, y recomienda un almacenamiento centralizado con control de acceso y rotación automática.
¿Debe firmar las transacciones en su propio equipo?
Sí, si puede. Una transacción firmada localmente nunca expone la clave privada a un tercero, y la API solo tiene que difundir el resultado. Para TRON, Chaingateway admite este flujo: los endpoints build devuelven una transacción sin firmar, usted la firma con las herramientas de TRON descritas en la guía de firma sin conexión de TRON, y POST /api/v2/tron/transactions/broadcast envía la transacción firmada.
En las redes EVM, los endpoints de transacciones aceptan el password de una dirección almacenada o un privatekey en el cuerpo de la solicitud. Si usa privatekey, la clave viaja en la solicitud, así que llame a la API solo por HTTPS y nunca registre los cuerpos de las solicitudes. Nuestra guía de descifrado de keystores muestra cómo abrir localmente un archivo keystore exportado.
¿Puede usar como monedero en frío las direcciones creadas con la API?
No. Una dirección cuya clave se creó o se guardó a través de un servicio en línea es un monedero en caliente, como se llame. Use las direcciones creadas por la API como direcciones de depósito, traslade los fondos entrantes a un monedero en frío que haya generado sin conexión y trate la dirección de depósito como de vida corta.
Trasladar periódicamente los depósitos y usar una dirección nueva para cada cliente o pedido limita lo que un atacante obtiene de una sola clave filtrada. Si usó el modo sin protección, la clave privada se le devolvió una sola vez, así que guárdela como si fuera una contraseña.
¿Cómo debe proteger su token de API?
Envíe el token en la cabecera Authorization y manténgalo fuera de las URL, del código de front-end y de los repositorios. Chaingateway usa el esquema bearer, Authorization: Bearer <token>, tal como define la RFC 6750. Esa RFC exige TLS para cada solicitud que lleve un token bearer, porque quien vea el token puede usarlo.
Tres hábitos reducen el daño de una filtración:
- Guarde el token en una variable de entorno o en un gestor de secretos, no en el código.
- Rótelo según un calendario y tras cualquier sospecha de exposición, como se describe en nuestra guía de rotación de claves API.
- Restrinja el acceso por dirección IP si el panel de su cuenta lo ofrece. Nuestra entrada sobre la función de lista blanca de IP explica cómo funciona.
El OWASP API Security Top 10 incluye la autenticación rota, con un manejo débil de los tokens, como un riesgo principal de las API.
¿Cómo se verifican los webhooks de la API?
Verifique la cabecera X-Signature de cada webhook antes de confiar en su contenido. Sin esa comprobación, cualquiera que conozca la URL de su webhook puede enviar una notificación de pago falsa. Chaingateway firma los webhooks cuando usted establece un secreto personal en la configuración de su perfil. La firma es un HMAC, tal como especifica la RFC 2104, construido a partir del ID de la transacción y de su secreto.
La guía de seguridad de webhooks incluye código de verificación en Python, Java, PHP y JavaScript. Compare las firmas con una función de tiempo constante, y confirme la transacción en la cadena antes de acreditar un pedido. Chaingateway no reintenta automáticamente los webhooks fallidos. Las notificaciones fallidas aparecen en /api/v2/{blockchain}/webhooks/notifications/failed, y puede reenviar cada una mediante /webhooks/notifications/{id}/retry, así que revise esa lista cuando parezca que falta un pago.
¿Necesita las seis?
Para cualquier cosa que tenga valor real, sí. Las prácticas cubren puntos de fallo distintos, y saltarse una deja abierto ese punto, sea cual sea lo que haga en los demás.
| Punto de fallo | Qué hacer | Dónde comprobar |
|---|---|---|
| Creación de claves | Use un generador criptográficamente seguro, o una dirección protegida con contraseña | Guía de gestión de monederos |
| Almacenamiento de claves | Guarde los fondos a largo plazo sin conexión y mantenga los secretos fuera del código y de los registros | Hoja de referencia de OWASP sobre gestión de secretos |
| Firma | Firme localmente donde la API lo admita; si no, use solo HTTPS | POST /api/v2/tron/transactions/broadcast |
| Uso de direcciones | Use direcciones de la API para depósitos y traslade los fondos a un monedero en frío | Su propio proceso de traslado |
| Acceso a la API | Guarde el token bearer en un gestor de secretos y rótelo | Guía de rotación de claves API |
| Notificaciones | Verifique X-Signature y confirme la transacción en la cadena | Guía de seguridad de webhooks |
Revise la tabla antes de pasar de testnet a mainnet. La cabecera X-Network: testnet le permite ejecutar el flujo completo, incluida la verificación de webhooks, sin fondos reales.
Cómo escribimos estos artículos
¿Listo para construirlo tú mismo? Obtenga su clave de API — prueba de 7 días, sin tarjeta — o consulte API Blockchain para la referencia completa de los endpoints.