SKILL.md
hmacsha256session_hashing
Cada registro de auditoría incluye un HMAC-SHA256 calculado sobre los campos clave de la sesión. Esto garantiza que los logs no han sido alterados a posteriori (no-repudio) y permite detectar manipulación del historial de decisiones KYC.
When to use
Usar al persistir cada registro de auditoría en PostgreSQL. El hash se calcula antes del INSERT y se almacena como columna integrity_hash.
Instructions
- No requiere instalación adicional — usar
hmacyhashlibde la stdlib Python. - Definir clave HMAC en Vault:
vault kv put secret/kyc/audit hmac_key=<random-256-bit-hex>. - Cargar clave al arrancar:
HMACKEY = os.environ["AUDITHMAC_KEY"]. - Calcular hash antes de persistir:
``python import hmac, hashlib, json def computeintegrityhash(sessiondata: dict, key: bytes) -> str: payload = json.dumps(sessiondata, sortkeys=True, ensureascii=False).encode() return hmac.new(key, payload, hashlib.sha256).hexdigest() ``
- Campos a incluir en el payload:
sessionid, timestamp, decision, globalscore, agentscores, userid_hash. - Al leer un registro, verificar con
hmac.compare_digest()para prevenir timing attacks. - Rotar la clave HMAC en Vault sin downtime usando doble validación (aceptar clave anterior durante 24h).
Notes
- Nunca usar SHA256 directo sin HMAC — sin la clave secreta, cualquiera puede recalcular el hash.
hmac.compare_digest()es obligatorio para la verificación — nunca comparar strings directamente.- Los registros con hash inválido deben generar alerta crítica en Alertmanager.