← Blog
10 min de lectura
|
Publicado
|
Actualizado

Rotación de claves API: crear, fijar, probar, cerrar

Cómo rotar claves API sin tiempo de inactividad: el patrón crear, fijar, probar, cerrar, intervalos del NIST, gestores de secretos y detalles de Chaingateway.

Capítulos
C
Chaingateway Team
Expertos en blockchain

Revisado por Maurice Sobiera

Ilustración isométrica de la rotación de credenciales de API

La rotación de claves API consiste en sustituir una clave activa por una nueva de forma periódica o tras una exposición, y retirar después la clave antigua. El patrón fiable tiene cuatro pasos: crear, fijar, probar y cerrar. Un breve solapamiento permite que ambas claves funcionen, de modo que las solicitudes en curso no fallen. NIST y OWASP aconsejan automatizarla.

¿Por qué debo rotar las claves API?

La rotación acorta el tiempo en que una clave filtrada le sirve a un atacante. Cada clave API es una responsabilidad permanente. Una clave puede filtrarse a través de un archivo .env subido al repositorio, un runner de CI comprometido o el portátil de un antiguo empleado. Cuanto más tiempo siga siendo válida la clave, más tiempo se puede explotar la filtración.

OWASP recoge este riesgo como NHI7, Long-Lived Secrets, en su Non-Human Identities Top 10. Describe claves API y tokens con fechas de caducidad muy lejanas, o sin ninguna. Los califica de extremadamente comunes, porque la rotación es difícil y las alternativas efímeras no siempre están disponibles.

La rotación importa más en estas credenciales:

  • Claves con alcances amplios, como acceso de administrador, de facturación o de escritura a datos de producción.
  • Credenciales compartidas entre varios servicios o equipos.
  • Todo lo que está incrustado en código del lado del cliente, apps móviles o integraciones de terceros.
  • Tokens que han pasado por un repositorio público, aunque sea brevemente.

Siempre que pueda, sustituya la clave estática por un token de corta duración de OAuth o de un sistema de identidad de carga de trabajo. Una credencial que caduca por sí sola no necesita una tarea de rotación.

¿Con qué frecuencia debo rotar las claves API?

El NIST fija una cifra concreta, y se aplica a las claves de firma. El NIST IR 8587 indica que, en sistemas de alto impacto, las claves de firma deben tener un periodo máximo de uso activo de no más de 90 días. Para sistemas de impacto moderado y bajo, puede ser adecuado un periodo más largo, pero inferior a un año. El informe también indica documentar los criptoperiodos y emplear rotación automatizada.

El NIST no da intervalos para las claves API ordinarias. Los valores de abajo son sugerencias nuestras, derivadas del enfoque basado en el riesgo del informe. No son un requisito del NIST.

CredencialAntigüedad máxima sugeridaMotivo
Claves de firma de sistemas de alto impacto90 días (NIST)Mayor alcance del daño
Claves API entre serviciosDe 30 a 90 díasDepende del alcance
Tokens de CI/CD30 díasSuelen llevar acceso de despliegue
Claves API de cara al usuario90 días, e inmediatamente tras una sospecha de exposiciónExisten muchas copias

Gráfico de barras de los criptoperiodos sugeridos: claves de firma hasta 90 días, claves entre servicios de 30 a 90 días, tokens de CI/CD hasta 30 días, claves API de cara al usuario 90 días

La regla detrás de la tabla es sencilla: cuanto más daño podría causar una credencial filtrada, más corto debe ser su periodo utilizable. Un ciclo manual de 30 días es realista para un puñado de claves. Con decenas de servicios hace falta automatización. El NIST señala lo mismo. Los criptoperiodos más cortos empujan a las organizaciones a automatizar la rotación y a practicar el cambio de claves con regularidad.

¿Dónde debo guardar las claves API?

Guarde las claves en un gestor de secretos que versione los secretos, ejecute hooks de rotación, limite el acceso y registre cada lectura. Las hojas de cálculo y los archivos .env compartidos no pueden hacer nada de esto. Compruebe cuatro capacidades antes de elegir:

  • Versionado, para que el secreto actual y el anterior puedan existir al mismo tiempo.
  • Hooks de rotación que ejecuten su función de rotación según una programación o un evento.
  • Limitación del acceso, para que el agente de rotación no pueda leer todos los secretos.
  • Registros de auditoría que anoten quién accedió a qué secreto o lo rotó.

AWS Secrets Manager admite la rotación programada mediante una función de rotación. HashiCorp Vault puede emitir secretos dinámicos que caducan por sí solos. Los servicios nativos de la nube para la gestión de claves, vinculados a roles de IAM, cumplen la misma función.

Si la arquitectura lo permite, prescinda de las claves estáticas. OWASP recomienda secretos dinámicos siempre que sea posible, porque reducen la superficie para la reutilización de credenciales. Las credenciales temporales de AWS STS o las identidades administradas de Azure y Google Cloud caducan a los pocos minutos u horas, así que no queda nada de larga duración que rotar.

¿Cuáles son los pasos crear, fijar, probar y cerrar?

Los cuatro pasos son el patrón que describe la hoja de referencia de OWASP para las funciones de rotación sin servidor. Se aplican a cualquier gestor de secretos o script propio.

  1. Crear: genere una nueva versión del secreto sin tocar la que está en uso.
  2. Fijar: envíe la nueva credencial al servicio dependiente o al almacén de configuración.
  3. Probar: ejecute una comprobación de integración que demuestre que el nuevo secreto autentica.
  4. Cerrar: promueva el nuevo secreto a activo, y revoque la versión antigua o programe su eliminación.

El paso que los equipos omiten es el solapamiento entre «fijar» y «cerrar». El NIST lo describe como una aceptación solapada de las claves antigua y nueva. La rotación debe programar el cambio de claves antes de la caducidad, de modo que los receptores acepten ambas versiones durante un tiempo. La duración adecuada del solapamiento depende de su sistema. Debe ser mayor que su solicitud en curso más larga y mayor que el tiempo que sus clientes necesitan para recoger el nuevo valor, incluida la vida útil de las cachés. Elija una cifra y pruébela en staging.

DesencadenanteMejor usoModelo de permisos
ProgramadoCadencia predecible, como 30 o 90 díasRol de rotación limitado a una ruta de secreto
Por eventoCompromiso detectado, baja de un empleadoElevado pero con límite de tiempo, revocado tras la ejecución
ManualAuditorías puntuales, incorporación de un nuevo servicioAprobación humana y MFA

El agente de rotación debe tener el conjunto de permisos más estrecho posible: acceso de escritura a un secreto y nada más amplio.

¿Qué debe incluir mi lista de comprobación de rotación?

Repase cuatro puntos antes de automatizar nada.

  1. Haga una copia del secreto actual y pruebe la reversión, para que no quede solo en teoría.
  2. Cree una prueba de integración que valide la nueva credencial contra un endpoint real.
  3. Cree un rol de rotación limitado exactamente a un secreto.
  4. Registre cada evento de rotación en su registro de auditoría.

Vigile tres puntos de fallo recurrentes. Las aplicaciones guardan credenciales en la memoria caché y no ven la nueva clave hasta un reinicio. Los proveedores limitan la tasa del endpoint de creación de claves si usted rota muchos secretos en un solo lote. Los clientes obsoletos siguen usando una clave revocada cuando ya ha terminado el solapamiento.

Registre quién o qué desencadenó cada rotación, una versión enmascarada de la clave antigua y de la nueva, el modo (programado, manual o de emergencia) y el resultado. Vigile un aumento repentino de solicitudes de una clave, las llamadas desde direcciones IP o regiones que la clave nunca había usado y las solicitudes que usan una clave que ya debería haber caducado. Ejecute análisis de los repositorios en busca de claves incrustadas en el código y mantenga un inventario, porque una clave fuera del inventario nunca se rota.

¿Cómo roto las credenciales de Chaingateway?

Una integración con Chaingateway tiene tres tipos de secretos, y cada uno se rota de forma distinta.

El token de API autentica sus solicitudes como bearer token. Usted crea los tokens en el panel de cuenta, en API Tokens, y asigna un nombre a cada uno. Use un nombre por entorno, como development, staging y production. Para rotarlo, cree un token nuevo, despliéguelo a través de su gestor de secretos, compruebe que las solicitudes funcionan y retire después el antiguo. Para limitar lo que puede hacer un token filtrado, active la lista blanca de IP (véase más abajo) para que solo las direcciones de su servidor puedan usarlo.

El secreto del webhook, llamado secreto personal, firma cada webhook mediante la cabecera X-Signature. La documentación de seguridad de webhooks indica que un nuevo secreto surte efecto de inmediato en las notificaciones de webhook. No se pueden usar dos secretos en el lado del emisor, así que el solapamiento debe estar en su receptor. Verifique con el secreto nuevo y con el antiguo durante un breve tiempo, y después descarte el antiguo.

import { createHmac, timingSafeEqual } from "node:crypto";
// Accept the new secret and, during rotation only, the previous one
const secrets = [process.env.WEBHOOK_SECRET, process.env.WEBHOOK_SECRET_PREVIOUS].filter(Boolean);
function signatureValid(txid, received) {
return secrets.some((secret) => {
const expected = createHmac("sha256", secret).update(txid).digest("base64");
return (
expected.length === received.length &&
timingSafeEqual(Buffer.from(expected), Buffer.from(received))
);
});
}

Las notificaciones que su servidor rechazó durante el cambio aparecen en la lista de notificaciones fallidas. Chaingateway no las reintenta automáticamente. Lea la lista con GET /api/v2/{chain}/webhooks/notifications/failed y reenvíe cada entrada con POST /api/v2/{chain}/webhooks/notifications/{id}/retry. La guía de entrega de webhooks lo trata con más detalle.

Las contraseñas de wallet protegen las direcciones que usted creó con una contraseña. Puede cambiar una con POST /api/v2/ethereum/addresses/{address}, que acepta old_password y new_password. La misma ruta existe para las otras cadenas. Chaingateway no guarda las contraseñas, así que guarde la nueva en su gestor de secretos antes de cambiarla. Una contraseña perdida no se puede recuperar.

¿Qué hace la lista blanca de IP de Chaingateway?

La lista blanca de IP es un ajuste de la cuenta que limita su clave API a las direcciones de servidor que usted indique. Se publicó el 21 de junio de 2021. Usted la activa en los ajustes del panel de cuenta y después introduce las direcciones permitidas. Una solicitud desde cualquier otra dirección se rechaza, aunque la clave sea correcta, de modo que una clave filtrada no sirve desde una máquina que usted no haya incluido en la lista.

Añada la dirección de su propio servidor al activarla; si no, también se rechazan sus propias solicitudes. Indique la dirección pública que su servidor presenta a internet. Los rangos privados como 10.0.0.0/8 y 192.168.0.0/16 están definidos en la RFC 1918 y nunca llegan a la API como origen de una solicitud. Detrás de una puerta de enlace NAT, indique la dirección de esa puerta de enlace. Entonces quedan permitidas todas las máquinas que están detrás de ella, no solo una.

La lista blanca se aplica a las solicitudes que usted envía a la API. No se aplica a los webhooks, que van de Chaingateway a su endpoint. Verifique los webhooks con la firma, como se describe arriba.

La lista blanca y la rotación limitan cosas distintas. La lista blanca limita desde dónde funciona una clave robada. La rotación limita durante cuánto tiempo funciona. Use ambas. Cuando sus servidores pasen a direcciones nuevas, actualice la lista antes del cambio, para que no se rechace su propio tráfico.

¿Cuándo dejan de tener sentido las claves API estáticas?

Las claves estáticas son aceptables para herramientas internas de bajo riesgo. Cuando expone una API a socios externos o maneja datos financieros, pase a una autenticación basada en OIDC o JWT con tiempos de caducidad cortos. Empiece por un servicio de poco tráfico. Confirme que su automatización de rotación aguanta con tráfico real y después amplíe. Una política de rotación que se aplica, y no solo se recomienda, es uno de los cambios operativos más eficaces que puede hacer un equipo de seguridad.

Captura de pantalla de la página de inicio de Chaingateway con el titular sobre una API blockchain unificada para pagos cripto y webhooks y un botón para iniciar una prueba gratuita de 7 días

Chaingateway cubre Ethereum, Bitcoin, Tron, Solana, Polygon, BNB Smart Chain y Arbitrum con una sola API REST y una sola capa de autenticación, así que no gestiona usted un ciclo de vida de credenciales distinto por cadena. La función de webhooks cubre las notificaciones de depósito. Los planes empiezan en 49 € al mes en la página de precios, y la prueba gratuita de 7 días no requiere tarjeta.

Fuentes

Preguntas frecuentes

¿Qué significa rotar una clave API?

Rotar una clave API significa generar una nueva credencial para sustituir a la activa, y retirar después la antigua cuando todos los sistemas dependientes hayan cambiado. Bien hecho, se ejecuta como un ciclo automatizado de crear, fijar, probar y cerrar, con un breve solapamiento en el que ambas claves funcionan.

¿Con qué frecuencia deben rotarse las claves API?

Depende del riesgo. El NIST IR 8587 indica que las claves de firma de los sistemas de alto impacto no deben permanecer en uso activo más de 90 días. Para las claves API ordinarias no da ninguna cifra, así que elija un intervalo según el alcance de la clave. Cuanto más corto, mejor para los tokens de CI/CD y para todo lo que tenga acceso amplio.

¿Por qué hay que rotar las claves API?

La rotación limita el daño de una credencial filtrada o robada, porque acorta el tiempo en que la clave es válida. OWASP recoge los secretos de larga duración como NHI7 en su Non-Human Identities Top 10.

¿Cuál es la mejor práctica para rotar claves API?

Automatice el proceso con un gestor de secretos, siga el patrón crear, fijar, probar y cerrar y mantenga una ventana de transición en la que la clave antigua y la nueva funcionen. Así se evita el tiempo de inactividad que supone cambiar todos los servicios dependientes a la vez.

¿Admite Chaingateway una gestión segura de claves para webhooks?

Sí. Chaingateway firma los webhooks con HMAC-SHA256 en la cabecera X-Signature, de modo que puede verificar la autenticidad. Si cambia el secreto personal, el nuevo secreto se aplica de inmediato, así que su receptor debe aceptar ambos secretos durante un breve tiempo.

Recomendado

Creado con BabyLoveGrowth para construir backlinks

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.

C
Chaingateway Team
Expertos en blockchain

El equipo de Chaingateway se dedica a simplificar la integración blockchain para desarrolladores de todo el mundo.