Abrir una sesión post-cuántica (ML-KEM)

Establece una clave de sesión con un mecanismo de encapsulamiento de claves post-cuántico, para que los cuerpos de las solicitudes y las respuestas viajen cifrados con ella además de con TLS.

Quién puede hacerlo

Cualquier cliente. El handshake no necesita token: se ejecuta antes de iniciar sesión, y la sesión que abre la usan después la solicitud del token y las llamadas autenticadas.

Antes de empezar

• Elige un KEM que admita el despliegue. GET /api/v3/pqc-handshake/supported-algorithms los lista; el SDK usa ML-KEM-768 salvo que se le indique otro.
• Ten en cuenta las operaciones de streaming y de interoperabilidad: nunca se envían con la clave de sesión, y se rechaza una solicitud de streaming que lleva los encabezados de sesión.

Pasos

1. Con el SDK de Java, activa el transporte en las propiedades que pasas a AnkaSecureSdk: pqc.transport.enabled=true y, de forma opcional, pqc.kem.algorithm=<KEM> (predeterminado ML-KEM-768) y pqc.session.ttl.seconds (predeterminado 600: el SDK reutiliza una sesión durante esa cantidad de segundos desde que la abrió y luego hace un handshake nuevo). Un KEM que el SDK no admite se rechaza cuando se construye el SDK, antes de cualquier solicitud. Después, el SDK hace el handshake, cifra cada solicitud que tiene cuerpo (incluida la solicitud del token) y descifra las respuestas; las solicitudes de streaming, de interoperabilidad y de handshake, y las solicitudes sin cuerpo, se envían sin cambios.
2. Con la CLI criptográfica, establece las mismas propiedades en su archivo de configuración, ~/.ankasecure-crypto/config.properties salvo que --config-path nombre otro. Un archivo escrito por AnkaSecureCLI init ya las lleva, con el transporte desactivado. La CLI pasa el archivo completo al SDK, que las aplica como se indica arriba; AnkaSecureCLI view-session muestra PQC Transport: Enabled y el KEM que resuelve, o nombra los KEM admitidos cuando el configurado no está entre ellos. Con el transporte activado, usa los comandos de streaming explícitos (como encrypt-file-stream) para los archivos grandes.
3. Con la API, genera un par de claves para el KEM elegido y llama a POST /api/v3/pqc-handshake/init con {"clientPublicKeyBase64": "<public key>", "algorithm": "ML-KEM-768"}. La respuesta lleva ciphertextBase64 y sessionId. Desencapsula el texto cifrado con tu clave privada para obtener la clave de sesión AES-256, y luego envía cada solicitud con X-PQC-Transport: true y X-PQC-Session: <sessionId> y su cuerpo cifrado con esa clave. El formato del cuerpo se describe en PQC transport in the SDK (en inglés).
4. Usa la sesión dentro de los 5 minutos. Una sesión nueva vence entonces, salvo que antes la use una solicitud que demuestre una identidad, una llamada autenticada o la solicitud del token; ese primer uso la extiende a 4 horas.

Qué ves cuando funcionó

El handshake responde 200 con ciphertextBase64 y sessionId. Las llamadas cifradas responden con un cuerpo cifrado que abre la clave de sesión. Un rechazo escrito antes de que la capa de transporte pudiera cifrar nada, como una sesión perdida, llega como un application/problem+json sin cifrar.

Si falla

Sin la consola

El handshake no tiene pantalla en la consola.

Relacionado

• Obtener un token de acceso para una aplicación

Esta página está en inglés:

• PQC transport in the SDK