BACKEND 15 min

TLS 1.3 y mTLS en Spring Boot 3: Keystores, Truststores y Depuración SSL

Guía técnica para implementar TLS 1.3 y autenticación mutua (mTLS) en Spring Boot 3: gestión de almacenes PKCS#12, autorización con certificados X.509, rotación sin reinicios y depuración avanzada de handshakes.

Escrito por Samir El Azem Crovetto • Senior Backend Engineer & DevSecOps

Cifrado en Tránsito y Confianza Cero en Microservicios

Durante muchos años, la arquitectura predominante en el despliegue de microservicios corporativos adoptó el patrón de \"perímetro blindado\": el tráfico entrante desde Internet se cifraba mediante TLS hasta un balanceador de carga o API Gateway perimetral, pero una vez dentro de la red interna o clúster de Kubernetes, los microservicios se comunicaban entre sí en texto plano mediante HTTP/1.1 sin autenticación mutua.

En el modelo de seguridad moderno Zero Trust, este diseño se considera una vulnerabilidad estructural inaceptable.

Si un atacante o un contenedor comprometido logra acceso a la red interna (por ejemplo, mediante una vulnerabilidad de ejecución remota de código en un pod periférico o un ataque de interceptación de tráfico ARP/DNS), puede escuchar de forma pasiva todo el tráfico este-oeste, capturando tokens de sesión, credenciales de bases de datos y cargas de datos confidenciales no cifradas.

Para garantizar la confidencialidad y la autenticidad en cada llamada interna, los microservicios basados en Spring Boot 3 y Java 21 deben aplicar cifrado en tránsito estricto mediante TLS 1.3 y, en comunicaciones entre servicios críticos, Mutual TLS (mTLS). En este escenario, tanto el servidor como el cliente deben presentar y verificar certificados criptográficos válidos emitidos por una Autoridad de Certificación (CA) de confianza antes de transmitir un solo byte de datos a nivel de aplicación.

En esta guía técnica analizamos la arquitectura de transporte seguro en Spring Boot 3: desde la distinción operativa entre Keystores y Truststores bajo el estándar PKCS#12, hasta la configuración de mTLS en Tomcat embebido, la autorización basada en certificados X.509, la recarga dinámica de certificados sin reinicio con SSL Bundles y la metodología de depuración de fallos de handshake con las banderas de diagnóstico de la JVM.

1. Fundamentos Criptográficos: Keystore vs. Truststore

En el ecosistema Java y la máquina virtual JVM, la gestión de certificados digitales se apoya en dos almacenes conceptual y operativamente distintos:

flowchart LR
    subgraph ServiceA ["Microservicio A (Cliente)"]
        KA["Keystore (p12)<br/>• Clave Privada del Cliente<br/>• Certificado X.509 del Cliente"]
        TA["Truststore (p12)<br/>• Certificado Raíz de la CA"]
    end

    subgraph ServiceB ["Microservicio B (Servidor)"]
        KB["Keystore (p12)<br/>• Clave Privada del Servidor<br/>• Certificado X.509 del Servidor"]
        TB["Truststore (p12)<br/>• Certificado Raíz de la CA"]
    end

    KA -.->|1. Presenta identidad criptográfica| TB
    KB -.->|2. Presenta identidad criptográfica| TA

    classDef store fill:#1e1e2e,stroke:#6366f1,stroke-width:2px,color:#cdd6f4;
    classDef svc fill:#181825,stroke:#a6e3a1,stroke-width:2px,color:#cdd6f4;
    class KA,TA,KB,TB store;
    class ServiceA,ServiceB svc;

1. El Keystore (Almacén de Claves)

  • Propósito: Define quién soy yo.
  • Contenido: Contiene la clave privada del servicio y la cadena de certificados públicos X.509 asociada (incluyendo el certificado del servidor y los certificados de las CAs intermedias).
  • Seguridad: Es un secreto de alta sensibilidad. Si la clave privada de un keystore se filtra, un atacante puede suplantar la identidad del servicio en la red.
  • Uso: El servidor lo utiliza para descifrar o firmar durante el handshake TLS y demostrar su identidad ante el cliente; en mTLS, el cliente también lo usa para demostrar su identidad ante el servidor.

2. El Truststore (Almacén de Confianza)

  • Propósito: Define en quién confío yo.
  • Contenido: Contiene exclusivamente certificados públicos de Autoridades de Certificación (CAs) de confianza o certificados autofirmados autorizados. No contiene claves privadas.
  • Uso: Cuando un microservicio recibe un certificado de un interlocutor remoto, consulta su Truststore para validar que la firma del certificado provenga de una CA reconocida en su cadena de confianza.

Transición de Estándar: El formato histórico propietario JKS (Java KeyStore) está formalmente obsoleto desde Java 9. En entornos de producción modernos se debe emplear exclusivamente el formato estándar del sector PKCS#12 (archivos con extensión .p12 o .pfx), el cual ofrece interoperabilidad nativa con herramientas como OpenSSL y librerías criptográficas de otros lenguajes (Go, Rust, Python).

2. Anatomía del Handshake: TLS Unilateral vs. mTLS

Para dimensionar la seguridad añadida por mTLS, comparemos la secuencia de negociación en ambos modelos:

sequenceDiagram
    autonumber
    participant C as Cliente (Microservicio A)
    participant S as Servidor (Microservicio B)

    Note over C,S: Handshake TLS 1.3 Unilateral (Estándar Web)
    C->>S: 1. ClientHello (Ciphers compatibles, Key Share)
    S-->>C: 2. ServerHello, EncryptedExtensions, Certificate (Servidor), Finished
    Note over C: El cliente valida el certificado del servidor contra su Truststore
    C->>S: 3. Finished (Canal seguro establecido)

    Note over C,S: Handshake mTLS (Autenticación Mutua Zero Trust)
    C->>S: 4. ClientHello
    S-->>C: 5. ServerHello + Certificate (Servidor) + CertificateRequest (Exige certificado cliente)
    Note over C: Valida certificado del servidor contra su Truststore
    C->>S: 6. Certificate (Cliente) + CertificateVerify (Firma con su clave privada) + Finished
    Note over S: El servidor valida el certificado del cliente contra su Truststore<br/>Si es inválido o no lo presenta -> Conexión TCP abortada inmediatamente
    S-->>C: 7. Finished (Canal mTLS establecido con autenticación bidireccional)

En TLS estándar, cualquiera en la red interna puede abrir un socket y enviar peticiones HTTP a la API REST (confiando únicamente en el filtrado de tokens a nivel de aplicación). En mTLS, si el cliente no posee un certificado X.509 firmado por la CA autorizada, la conexión TCP se cierra a nivel de kernel durante el handshake criptográfico, impidiendo que el atacante pueda siquiera enviar un payload HTTP malicioso.

3. Generación Profesional de Keystores y Truststores PKCS12

Para desplegar un entorno de pruebas corporativo o configurar mTLS en un clúster privado, generamos una infraestructura de clave pública (PKI) mínima utilizando OpenSSL y la utilidad keytool de la JDK.

Paso 1: Generar la Autoridad de Certificación (CA) Raíz Privada

# 1. Generar la clave privada de la CA (cifrada con AES-256)
openssl genpkey -algorithm RSA -pkeyopt rsa_keygen_bits:4096 -out ca-private-key.pem

# 2. Generar el certificado autofirmado de la CA raíz (validez de 5 años)
openssl req -x509 -new -nodes -key ca-private-key.pem -sha256 -days 1825 \
  -subj "/C=ES/ST=Madrid/O=SecDevOps Enterprise/CN=SecDevOps Root CA" \
  -out ca-cert.pem

Paso 2: Generar el Keystore del Servidor

# 1. Generar clave privada y solicitud de firma de certificado (CSR) para el servidor
openssl req -new -nodes -newkey rsa:2048 \
  -keyout server-key.pem \
  -out server.csr \
  -subj "/C=ES/ST=Madrid/O=SecDevOps Enterprise/OU=Backend/CN=payment-service.internal"

# 2. Crear archivo de extensiones para SAN (Subject Alternative Names)
cat <<EOF > server-ext.cnf
authorityKeyIdentifier=keyid,issuer
basicConstraints=CA:FALSE
keyUsage = digitalSignature, keyEncipherment
extendedKeyUsage = serverAuth
subjectAltName = @alt_names

[alt_names]
DNS.1 = payment-service.internal
DNS.2 = localhost
IP.1 = 127.0.0.1
EOF

# 3. Firmar el certificado del servidor con nuestra CA privada
openssl x509 -req -in server.csr -CA ca-cert.pem -CAkey ca-private-key.pem \
  -CAcreateserial -out server-cert.pem -days 365 -sha256 -extfile server-ext.cnf

# 4. Empaquetar clave privada y certificado en un almacén PKCS#12 (server-keystore.p12)
openssl pkcs12 -export -in server-cert.pem -inkey server-key.pem \
  -chain -CAfile ca-cert.pem \
  -name payment-server \
  -out server-keystore.p12 -passout pass:server_keystore_secret

Paso 3: Generar el Keystore del Cliente y los Truststores

# 1. Generar par de claves y CSR para el microservicio cliente (Order Service)
openssl req -new -nodes -newkey rsa:2048 \
  -keyout client-key.pem \
  -out client.csr \
  -subj "/C=ES/ST=Madrid/O=SecDevOps Enterprise/OU=Clients/CN=order-service.internal"

# 2. Firmar el certificado del cliente con la CA (extendedKeyUsage = clientAuth)
openssl x509 -req -in client.csr -CA ca-cert.pem -CAkey ca-private-key.pem \
  -CAcreateserial -out client-cert.pem -days 365 -sha256

# 3. Empaquetar el keystore del cliente en PKCS#12
openssl pkcs12 -export -in client-cert.pem -inkey client-key.pem \
  -chain -CAfile ca-cert.pem \
  -name order-client \
  -out client-keystore.p12 -passout pass:client_keystore_secret

# 4. Crear el Truststore (importando el certificado público de la CA raíz)
keytool -importcert -alias secdevoops-root-ca -file ca-cert.pem \
  -keystore enterprise-truststore.p12 -storetype PKCS12 \
  -storepass truststore_secret -noprompt

4. Configuración de Spring Boot 3 para TLS 1.3 y mTLS

Con los almacenes generados, configuramos el servidor Spring Boot en application.yml para exigir TLS 1.3 y autenticación mutua de cliente obligatoria:

server:
  port: 8443
  ssl:
    enabled: true
    # Forzar exclusivamente TLS 1.3 (eliminando protocolos obsoletos TLS 1.0, 1.1 y 1.2)
    enabled-protocols: TLSv1.3
    # Configuración del Keystore (Identidad del Servidor)
    key-store: classpath:security/server-keystore.p12
    key-store-password: ${SERVER_KEYSTORE_PASSWORD:server_keystore_secret}
    key-store-type: PKCS12
    key-alias: payment-server
    
    # Configuración del Truststore (Validación de Clientes)
    trust-store: classpath:security/enterprise-truststore.p12
    trust-store-password: ${TRUSTSTORE_PASSWORD:truststore_secret}
    trust-store-type: PKCS12
    
    # Modo de autenticación de cliente:
    # NEED: Exige obligatoriamente un certificado de cliente válido (mTLS estricto)
    # WANT: Solicita certificado; si no lo presenta, permite continuar (para APIs mixtas)
    # NONE: No solicita certificado (TLS unilateral estándar)
    client-auth: need

Integración con Spring Security: Extracción de Identidad X.509

Cuando client-auth: need está activo, Tomcat valida criptográficamente que el certificado del cliente esté firmado por la CA del truststore. Sin embargo, en la capa de aplicación, necesitamos saber qué servicio concreto se está comunicando.

Spring Security proporciona un filtro nativo X509AuthenticationFilter que extrae el certificado de la petición y permite mapear el Common Name (CN) a un usuario autenticado:

package es.secdevoops.security.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.security.config.annotation.method.configuration.EnableMethodSecurity;
import org.springframework.security.config.annotation.web.builders.HttpSecurity;
import org.springframework.security.config.annotation.web.configuration.EnableWebSecurity;
import org.springframework.security.core.authority.SimpleGrantedAuthority;
import org.springframework.security.core.userdetails.User;
import org.springframework.security.core.userdetails.UserDetailsService;
import org.springframework.security.core.userdetails.UsernameNotFoundException;
import org.springframework.security.web.SecurityFilterChain;

import java.util.List;

@Configuration
@EnableWebSecurity
@EnableMethodSecurity
public class MTlsSecurityConfig {

    @Bean
    public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
        return http
            .csrf(csrf -> csrf.disable())
            .authorizeHttpRequests(auth -> auth
                // Solo clientes cuyo CN sea 'order-service.internal' acceden al endpoint de pagos
                .requestMatchers("/api/v1/payments/**").hasRole("ORDER_SERVICE")
                .anyRequest().authenticated()
            )
            // Habilita la autenticación X.509 extrayendo el Subject Principal
            .x509(x509 -> x509
                .subjectPrincipalRegex("CN=(.*?)(?:,|$)")
                .userDetailsService(x509UserDetailsService())
            )
            .build();
    }

    @Bean
    public UserDetailsService x509UserDetailsService() {
        return username -> {
            // Asignación de roles en base al Common Name del certificado del cliente
            if ("order-service.internal".equalsIgnoreCase(username)) {
                return new User(username, "", List.of(new SimpleGrantedAuthority("ROLE_ORDER_SERVICE")));
            } else if ("inventory-service.internal".equalsIgnoreCase(username)) {
                return new User(username, "", List.of(new SimpleGrantedAuthority("ROLE_INVENTORY_SERVICE")));
            }
            throw new UsernameNotFoundException("Servicio cliente no autorizado: " + username);
        };
    }
}

5. Recarga Dinámica de Certificados sin Reinicio (SSL Bundles)

Uno de los mayores dolores operativos en infraestructuras con TLS reside en la expiración de certificados: tradicionalmente, renovar un certificado implicaba reiniciar el proceso JVM de Spring Boot, provocando indisponibilidad momentánea o exigiendo complejas estrategias de despliegue progresivo (rolling restarts).

A partir de Spring Boot 3.1 y 3.2, Spring introdujo la abstracción de SSL Bundles, que desacopla la configuración criptográfica del servidor web embebido y permite la recarga en caliente de certificados:

spring:
  ssl:
    bundle:
      jks: # El término 'jks' engloba también almacenes PKCS12
        payment-service-bundle:
          key:
            alias: payment-server
          keystore:
            location: file:/etc/ssl/certs/server-keystore.p12
            password: ${KEYSTORE_PASSWORD}
            type: PKCS12
          truststore:
            location: file:/etc/ssl/certs/enterprise-truststore.p12
            password: ${TRUSTSTORE_PASSWORD}
            type: PKCS12
          reload-on-update: true # Detecta cambios en el sistema de archivos automáticamente

server:
  port: 8443
  ssl:
    bundle: payment-service-bundle
    client-auth: need

Cuando un operador o un Job de Kubernetes (como cert-manager) renueva el archivo server-keystore.p12 montado en el volumen, Spring Boot detecta la actualización y reconstruye el SSLContext en memoria sin interrumpir las peticiones en curso ni reiniciar el servidor.

6. Diagnóstico y Depuración Avanzada de Handshakes SSL

Los errores de TLS suelen ser frustrantes porque, por motivos de seguridad, las excepciones en los clientes suelen ser opacas (IOException: Connection closed by peer).

Para observar la negociación criptográfica paquete a paquete, la JVM dispone de una bandera de diagnóstico fundamental: -Djavax.net.debug=ssl:handshake.

Activación en Entornos de Desarrollo o Contenedores

# Ejecución directa con bandera JVM
java -Djavax.net.debug=ssl:handshake -jar payment-service.jar

En contenedores Docker:

environment:
  JAVA_TOOL_OPTIONS: "-Djavax.net.debug=ssl:handshake:verbose"

Decodificación de los Tres Errores SSL Más Frecuentes:

Error 1: PKIX path building failed: unable to find valid certification path

javax.net.ssl.SSLHandshakeException: PKIX path building failed: 
sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target
  • Causa Raíz: El cliente que realiza la petición no confía en el certificado presentado por el servidor.
  • Solución: El certificado de la CA que firmó el certificado del servidor no está presente en el truststore del cliente o en el cacerts de la JDK. Se debe importar la CA raíz con keytool -importcert.

Error 2: Received fatal alert: badcertificate o certificateunknown

javax.net.ssl.SSLException: Received fatal alert: certificate_unknown
  • Causa Raíz: Típico en entornos mTLS. El servidor solicitó un certificado al cliente (CertificateRequest), y el cliente envió un certificado desconocido o autofirmado que no figura en la cadena de confianza del trust-store del servidor.
  • Solución: Verificar que el certificado del cliente fue emitido por la misma CA cargada en el server.ssl.trust-store.

Error 3: Unsupported or unrecognized SSL message

  • Causa Raíz: Discrepancia de protocolo. La aplicación cliente está enviando una petición HTTP en texto plano hacia un puerto configurado con HTTPS/TLS (por ejemplo, ejecutar curl http://localhost:8443 en lugar de https).

7. Cliente mTLS con RestClient o WebClient

Para que otro microservicio Spring Boot invoque al servicio protegido por mTLS, debe configurar su cliente HTTP inyectando su propio Keystore y el Truststore correspondiente:

@Configuration
public class RestClientConfig {

    @Bean
    public RestClient paymentServiceClient(
        @Value("${app.services.payment.url}") String paymentUrl,
        SslBundles sslBundles
    ) {
        // Obtenemos el bundle configurado en el cliente
        SslBundle clientBundle = sslBundles.getBundle("client-identity-bundle");

        // Construcción de un HttpComponentsClientHttpRequestFactory con el SSLContext del bundle
        ClientHttpRequestFactory requestFactory = ClientHttpRequestFactories.get(
            ClientHttpRequestFactorySettings.DEFAULTS.withSslBundle(clientBundle)
        );

        return RestClient.builder()
            .baseUrl(paymentUrl)
            .requestFactory(requestFactory)
            .build();
    }
}

8. Checklist de Producción: TLS 1.3 y mTLS

Antes de certificar el endurecimiento criptográfico de una flota de microservicios Spring Boot, valida la siguiente matriz de control:

Control de Seguridad Configuración Recomendada Propósito Defensivo
Formato de Almacén PKCS#12 (.p12) Sustituye el formato obsoleto JKS y garantiza compatibilidad estándar.
Protocolo Forzado Exclusivamente TLSv1.3 Elimina suites de cifrado vulnerables a ataques como POODLE o BEAST.
SAN Validado Subject Alternative Names (DNS e IP) Previene ataques de suplantación y errores de hostname mismatch.
mTLS Estricto server.ssl.client-auth: need Bloquea a nivel de socket TCP cualquier petición de clientes no autorizados.
Autorización X.509 x509().subjectPrincipalRegex(...) Aplica control de acceso RBAC basado en la identidad criptográfica del servicio.
Rotación Dinámica spring.ssl.bundle.*.reload-on-update: true Permite renovar certificados sin paradas de servicio ni caída de conexiones.
Depuración Segura Desactivar javax.net.debug en producción Evita saturación de registros y fugas de metadatos en logs centralizados.

Conclusión

El cifrado en tránsito y la autenticación mutua no deben reservarse exclusivamente para las fronteras externas de una infraestructura. En un entorno de amenazas avanzadas y arquitecturas distribuidas, mTLS y TLS 1.3 representan el estándar mínimo de comunicación entre microservicios.

La combinación de almacenes seguros PKCS#12, autenticación basada en certificados X.509 y la gestión desacoplada de claves mediante SSL Bundles permite a los equipos de ingeniería desplegar arquitecturas Zero Trust robustas, observables y completamente resilientes ante inspecciones de red no autorizadas.

Alinear estas capacidades de transporte con una adecuada gobernanza de identidades en OAuth 2.1 y Spring Security 6, optimizaciones en Spring Data JPA y despliegues inmutables en Contenedores Docker constituye la base para operar microservicios empresariales verdaderamente blindados.

Si necesitas auditar la seguridad de la capa de transporte, implementar mTLS Zero Trust o depurar problemas criptográficos en tus microservicios Spring Boot, puedes consultar mis Servicios de Ciberseguridad y Consultoría o ponerte en contacto conmigo a través de Sobre mí.