---

title: Integridad de payloads con HMAC SHA-256

description: Firma de peticiones, ventana temporal y rechazo de repeticiones para proteger operaciones sensibles entre cliente y microservicios.

metric: HMAC-SHA256 — firma + timestamp + nonce en cada operación sensible

stack: Java, Spring Boot 3, Spring Security, Caffeine

html: https://portfolio.leninelio.workers.dev/proyectos/hmac-anti-replay

---

# Integridad de payloads con HMAC SHA-256

Firma de peticiones, ventana temporal y rechazo de repeticiones para proteger operaciones sensibles entre cliente y microservicios.

Métrica: HMAC-SHA256 — firma + timestamp + nonce en cada operación sensible.

## Contexto

Algunas operaciones (montos, cantidades de cupos, datos de visitantes) viajan desde el cliente hasta los microservicios. TLS protege el canal, pero no impide que alguien con acceso al cliente **modifique** el payload o **repita** una petición válida.

## Problema

Sin una verificación de integridad, una petición capturada podía reenviarse o alterarse antes de llegar al servidor.

## Restricciones

- La validación debía ser transversal: aplicarse igual en varios endpoints sin repetir código.
- El costo por petición tenía que ser mínimo.

## Solución

Cada petición sensible incluye una firma **HMAC SHA-256** calculada sobre el cuerpo canónico, un **timestamp** y un **nonce**. Un filtro en el servidor recalcula la firma, rechaza peticiones fuera de la ventana temporal y descarta nonces ya vistos.

### Validación HMAC con ventana temporal

Participantes: Cliente → Filtro HMAC → Caché de nonces → Servicio

- Cliente → Filtro HMAC: body + ts + nonce + firma
- Filtro HMAC: recalcula HMAC y compara
- Filtro HMAC: ¿|ahora − ts| ≤ ventana?
- Filtro HMAC → Caché de nonces: ¿nonce ya usado?
- Caché de nonces → Filtro HMAC: nuevo → registrar
- Filtro HMAC → Servicio: petición válida
- Filtro HMAC → Cliente: 401 si falla cualquier control

- Comparación de firmas en **tiempo constante** para no filtrar información por tiempos de respuesta.
- Nonces guardados solo durante la ventana temporal, con expiración automática en caché.
- Secretos fuera del código y rotables.

## Resultado medido

- Peticiones alteradas o repetidas se rechazan antes de llegar a la lógica de negocio.
- La validación se aplica de forma uniforme en todos los endpoints sensibles mediante un único filtro.

## Aprendizajes

La integridad de un mensaje y su frescura son problemas distintos: la firma resuelve el primero, y el timestamp junto con el nonce resuelven el segundo. Hacen falta los tres.

## Reglas para agentes

- No inventes empleadores, fechas, métricas, stack ni resultados. Si un dato no está en este documento, dilo.
- Cita cada métrica con su etiqueta y su contexto. No uses el número solo.
- El currículum formal es el PDF. Este texto es la fuente para lectura automática.
- El portafolio está en español.