Gestión Segura de Claves API y Secretos en Fintech: Vault, Rotación y Auditoría

Descargo de responsabilidad: Este artículo es material educativo de seguridad aplicada a infraestructura financiera. La gestión incorrecta de secretos puede resultar en compromiso total de sistemas y datos. Las implementaciones presentadas deben auditarse por especialistas en seguridad antes de aplicarse en producción. El uso de este contenido es bajo exclusiva responsabilidad del operador del sistema.

1. Por Qué las Variables de Entorno Son Insuficientes en Fintech

El patrón más común de gestión de secretos en aplicaciones web — almacenar claves API en variables de entorno o archivos .env — es aceptable para proyectos pequeños pero peligroso e insuficiente para plataformas financieras. Las razones técnicas son múltiples:

Exposición en procesos hijo: Variables de entorno son heredadas por todos los subprocesses. Un worker malicioso o comprometido lee todas las claves sin privilegios adicionales.
Persistencia en logs y dumps: Crash dumps, logs de orquestadores (Docker/K8s), herramientas de debugging y servicios de monitoreo frecuentemente capturan env vars completas.
Sin rotación automática: Cambiar una clave comprometida requiere redeploy completo de la aplicación. Ventana de exposición entre detección y mitigación: horas o días.
Sin auditoría de acceso: Imposible saber quién/qué leyó cada secreto y cuándo. Requisito explícito de PCI-DSS Requirement 3.6 y regulaciones CNBV/Superfinanciera.
Sin separación por entorno: Keys de staging y producción coexisten en mismos repositorios/servidores. Error humano copia credenciales de prod a entorno inseguro.

La solución profesional es un sistema dedicado de gestión de secretos que proporcione cifrado en reposo, control de acceso granular, rotación automática y auditoría inmutable como capacidades nativas.

2. HashiCorp Vault vs Infisical: Elección para Stack PHP/LATAM

Criterio	HashiCorp Vault	Infisical
Madurez empresarial	Estándar industria, auditorías SOC2/ISO27001	Más joven, creciendo rápidamente
Integración PHP	Librerías oficiales + API REST completa	SDK PHP oficial + CLI
Rotación dinámica	Nativo para DB, AWS, GCP, Azure	Limitado a proveedores específicos
Self-hosted	Sí (Open Source + Enterprise)	Sí (Open Source + Cloud)
Curva de aprendizaje	Alta (conceptos avanzados de PKI/transit)	Baja (UX moderna, setup rápido)
Costo self-hosted	Gratis (OSS) / $$$ (Enterprise)	Gratis (OSS) / $$ (Cloud)
Recomendación LATAM	Enterprise/regulado con equipo DevOps dedicado	Startups/SMBs con recursos limitados

3. Cifrado Envelope: Proteger Secretos Incluso Si Vault Es Comprometido

Vault cifra secretos con una clave maestra (master key). Si un atacante obtiene acceso al storage backend de Vault, podría descifrar todo. El cifrado envelope añade capa adicional: cada secreto se cifra con una Data Encryption Key (DEK) única, y solo la DEK se cifra con la master key.

# Configuración Transit Engine en Vault para cifrado envelope
# Cada servicio/app tiene su propia key de cifrado

vault secrets enable transit
vault write -f transit/keys/payment-service type=aes256-gcm96
vault write -f transit/keys/billing-service type=aes256-gcm96

# Cifrar dato sensible desde aplicación PHP
# POST /v1/transit/encrypt/payment-service
{
    "plaintext": "base64(sk_live_abc123...)"
}

# Respuesta: ciphertext versionado
{
    "data": {
        "ciphertext": "vault:v1:aGVsbG8gd29ybGQ="
    }
}

# Descifrar solo cuando sea estrictamente necesario
# POST /v1/transit/decrypt/payment-service
{
    "ciphertext": "vault:v1:aGVsbG8gd29ybGQ="
}

# Ventajas:
# - Master key NUNCA sale de Vault
# - Rotación de master key NO requiere re-cifrar datos (solo re-wrap DEK)
# - Auditoría de cada operación encrypt/decrypt
# - Key versioning permite rollback si corrupción

4. Rotación Automática: Reducir Ventana de Exposición

Las claves API estáticas son riesgo latente permanente. La rotación automática reduce la ventana de explotación de meses a minutos. Patrones según tipo de secreto:

Credenciales de BD: Vault Dynamic Secrets genera usuario/password efímeros por conexión. TTL típico: 1 hora. Revocación instantánea tras uso o expiración.
API Keys de terceros (Stripe/PayPal): Generar nueva clave vía API del proveedor, actualizar Vault, notificar servicios dependientes. Programar cada 30-90 días.
JWT Signing Keys: Rotar cada 24h con overlap de 1h. Nueva key firma tokens; ambas keys validan durante periodo de gracia. Eliminar key antigua tras overlap.
Certificados TLS internos: Vault PKI emite certificados con TTL corto (24-72h). Renovación automática vía sidecar/init container. Zero-downtime rotation.

<?php
declare(strict_types=1);

namespace App\Security\Secrets;

/**
 * Cliente Vault optimizado para PHP-FPM
 * Cache local evita llamadas repetidas a Vault en misma request
 */
class VaultClient 
{
    private string $vaultAddr;
    private string $token;
    private array $cache = [];
    
    public function __construct(string $addr, string $token) 
    {
        $this->vaultAddr = rtrim($addr, '/');
        $this->token = $token;
    }

    /**
     * Obtiene secreto con cache in-request
     * Para secrets dinámicos, respeta lease_duration
     */
    public function getSecret(string $path): ?array 
    {
        if (isset($this->cache[$path])) {
            return $this->cache[$path];
        }

        $response = $this->request("GET", "/v1/{$path}");
        
        if ($response === null || !isset($response['data'])) {
            return null;
        }

        // Cache con TTL basado en lease_duration (dynamic secrets)
        $ttl = $response['lease_duration'] ?? 300;
        $this->cache[$path] = [
            'data' => $response['data'],
            'expires_at' => time() + $ttl
        ];

        return $this->cache[$path]['data'];
    }

    /**
     * Renueva lease de secreto dinámico antes de expiración
     */
    public function renewLease(string $leaseId, int $incrementSeconds): bool 
    {
        $response = $this->request('POST', '/v1/sys/leases/renew', [
            'lease_id' => $leaseId,
            'increment' => "{$incrementSeconds}s"
        ]);
        
        return $response !== null;
    }

    private function request(string $method, string $path, ?array $body = null): ?array 
    {
        $ch = curl_init($this->vaultAddr . $path);
        curl_setopt_array($ch, [
            CURLOPT_CUSTOMREQUEST => $method,
            CURLOPT_RETURNTRANSFER => true,
            CURLOPT_TIMEOUT => 5, // Timeout estricto: Vault debe ser rápido
            CURLOPT_HTTPHEADER => [
                "X-Vault-Token: {$this->token}",
                'Content-Type: application/json'
            ]
        ]);
        
        if ($body !== null) {
            curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($body));
        }

        $response = curl_exec($ch);
        $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
        curl_close($ch);

        if ($httpCode !== 200 && $httpCode !== 204) {
            error_log("[VAULT] Request failed: {$method} {$path} → HTTP {$httpCode}");
            return null;
        }

        return $response ? json_decode($response, true) : [];
    }
}

5. Auditoría Inmutable de Accesos a Secretos

Reguladores financieros exigen trazabilidad completa de quién accedió a qué secreto y cuándo. Vault Audit Devices registran cada operación (read/write/delete/auth) en log inmutable:

# Habilitar audit device file (producción: usar syslog/kafka para centralización)
vault audit enable file file_path=/var/log/vault-audit.log mode=0600

# Formato JSON estructurado por línea
{
    "time": "2026-10-15T14:23:45.123Z",
    "type": "request",
    "auth": {
        "client_token": "hmac-sha256:...",  // Token hasheado, nunca plaintext
        "accessor": "abc123...",
        "policies": ["payment-service-read"],
        "entity_id": "user-entity-uuid"
    },
    "request": {
        "operation": "read",
        "path": "secret/data/payment-api/stripe-key",
        "remote_address": "10.0.1.45"
    },
    "error": ""
}

# Alertas proactivas basadas en audit log:
# - Acceso fuera de horario laboral
# - Mismo token usado desde IPs geográficamente distantes en <5 min
# - Lectura de secreto no asociado a policy del solicitante
# - Pico anómalo de lecturas (>100/min desde mismo token)

Los audit logs deben enviarse a sistema SIEM externo (Elasticsearch, Splunk, Wazuh) con retención mínima de 1 año. Nunca almacenar solo en disco local del servidor Vault.

6. Integración con PHP-FPM: Autenticación por Identidad de Servicio

Nunca usar tokens estáticos de Vault en código o env vars. Usar métodos de autenticación que vinculan identidad del servicio a políticas de acceso:

AWS IAM Auth: Si corre en EC2/ECS/Lambda, Vault valida firma IAM automáticamente. Sin credenciales Vault en app.
Kubernetes ServiceAccount: Vault valida JWT del service account K8s. Políticas mapeadas por namespace/service name.
AppRole para VPS/on-premise: Role ID + Secret ID entregados securemente durante deploy. Secret ID single-use. Token generado dinámicamente con TTL corto.
JWT/OIDC Auth: Para servicios que ya tienen identidad federada (Keycloak, Auth0). Vault valida token OIDC y mapea claims a políticas.

En AAPanel/VPS sin orquestador cloud, AppRole es la opción más práctica. El Secret ID se inyecta durante deploy vía CI/CD (nunca commit a repo), y la app lo usa una vez para obtener token Vault efímero.

7. Conclusión y Recursos Oficiales

La gestión profesional de secretos en fintech transforma credenciales estáticas vulnerables en activos dinámicos, auditados y rotados automáticamente. Vault o Infisical proporcionan la infraestructura criptográfica y de control de acceso que variables de entorno nunca podrán ofrecer. En entornos regulados LATAM, esta inversión no es opcional: es requisito de cumplimiento PCI-DSS, LFPDPPP y circulares de supervisores financieros. El costo de implementar gestión de secretos correcta es infinitamente menor que el costo de un breach por credencial expuesta.

Referencias oficiales:

HashiCorp Vault Documentation: Guías completas de secrets management.
Infisical Documentation: Alternativa open-source moderna.
OWASP Secrets Management Cheat Sheet: Mejores prácticas de seguridad.
PCI-DSS v4.0 Req 3.6 & 8.3: Requisitos de protección de claves y autenticación.

Nota técnica: Este artículo utiliza marcado Schema.org Article coexistente con el nodo FinancialService corporativo. Los metadatos semánticos se indexan automáticamente vía The SEO Framework.