La API está diseñada partiendo de la base de que cada llamada tiene impacto financiero directo y puede acceder a credenciales sensibles del servidor. Por ello, los requisitos de seguridad están claramente por encima del estándar habitual en REST.
Controles aplicados
- HMAC-SHA256: Cada petición se firma con HMAC-SHA256 sobre método, ruta, marca de tiempo, nonce y hash del cuerpo. Verificación en tiempo constante (hash_equals).
- AES-256-GCM: Los secretos se almacenan persistentemente solo como cifrado AES-256-GCM (libsodium). La clave maestra reside fuera de la base de datos en /etc/kh-reseller-api/master.key.v{N}.
- Replay protection: Ventana de marca de tiempo +-300s, caché de nonce 600s. Una petición firmada correctamente no puede reenviarse.
- Scope-based authorization: Lista de permisos explícita por clave. Los permisos de escritura y sensibles deben activarse de forma explícita.
- IP whitelist (optional): Lista blanca de IP opcional por clave (notación CIDR, IPv4 e IPv6).
- Rate limit: Multinivel: por clave (minuto y día) y por IP (minuto). Cubo de tokens con tolerancia a ráfagas.
- Idempotency: Los pedidos y las acciones de servicio destructivas requieren Idempotency-Key. 24h de protección contra repetición frente a reintentos de red.
- Tenant isolation: Cada consulta a la base de datos filtra estrictamente por el identificador de su cuenta. El acceso entre clientes es imposible por construcción.
- Tamper-evident audit log: Cada petición se registra en el log de auditoría con hash en cadena (chain_hash[n] = sha256(chain_hash[n-1] || row_n)). Cualquier manipulación retroactiva se detecta por la ruptura del hash.
- Credentials.read alerting: Cada llamada credentials.read genera una entrada de auditoría dedicada y, opcionalmente, un correo de confirmación al titular de la cuenta.
- SSRF-guarded webhooks: Las URLs de webhook se validan antes de almacenarse: solo HTTPS, la resolución DNS solo puede devolver IPs públicas (sin RFC1918, sin link-local).
Buenas prácticas en su lado
- Guarde el secreto en un gestor de secretos (HashiCorp Vault, AWS Secrets Manager, Doppler, 1Password); nunca en el código, nunca en un repositorio git.
- Rote el secreto con regularidad (al menos anualmente o tras cambios de personal). Rotación con un solo clic en el portal, el secreto anterior queda invalidado de inmediato.
- Una clave dedicada por caso de uso con el permiso mínimo (solo lectura si es posible). Nada de claves "todo permitido".
- Si su integración se ejecuta desde IPs fijas (cloud, bastión), configure una lista blanca de IP.
- Genere el Idempotency-Key en su servidor y persístalo, no lo genere de nuevo en cada reintento. Recomendación: UUIDv4 por cada pedido lógico.
- Configure un webhook hacia su propia URL y vigile al menos order.created y credentials.read como flujo de eventos.
Divulgación de seguridad
Por favor, comunique los problemas de seguridad de forma confidencial a security@kernelhost.com. Clave PGP bajo petición. Respuesta garantizada en 24h. Programa bug-bounty en preparación.
