Intercambio de llave simétrica

Paso 1: Obtener llave pública del usuario

El cliente necesita de la llave pública del usuario para cifrar la llave simétrica que luego se enviará a POST api/v1/account/affiliate para desencriptar en el paso 2, para obtener esta llave se hará mediante GET api/v1/user/key el cual Devuelve la llave pública asimétrica del usuario autenticado.

Respuesta exitosa (200)

{
  "public_key": "-----BEGIN PUBLIC KEY-----\nMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEcmdSymRdS6nLdbiP0ei7Z2DHVt+G\nlbtq3+OnHnXPtPLr/KEpSCB8wn9yak8mPwoG06Ktz1NQbJK2iaBdvCmwYQ==\n-----END PUBLIC KEY-----"
}

Método de uso

Para completar este proceso, el usuario debe estar previamente autenticado. El flujo de ejecución consiste en los siguientes pasos:

Cifrado de Llave Simétrica: Utilice la public_key obtenida para cifrar su llave simétrica, empleando el esquema de cifrado correspondiente al backend (como ECDH o RSA).
Envío y Aplicación: La llave simétrica generada debe enviarse al servidor durante el Paso 2. Posteriormente, esta misma llave se utilizará para cifrar el cuerpo de la solicitud en el inicio de la afiliación (Paso 4).

Paso 2: Guardar la llave simétrica

Antes de iniciar cualquier flujo, el cliente genera una llave de 32 bytes aleatorios (AES-256) y debe enviarla a SyPago de forma segura. El cliente deberá registrar esta llave simétrica (obtenida en el paso anterior) para cifrar el payload de afiliación; el servidor, por su parte, la almacena asociada al usuario y la utiliza para desencriptar el cuerpo del POST api/v1/account/affiliate, mediante el cual se recibe y persiste la llave simétrica cifrada del usuario.

Endpoint
POST    api/v1/user/key/symetric

Criptografía: Se utiliza ECDH (Elliptic Curve Diffie-Hellman) sobre la curva P-256. Se generan un par de llaves efímeras ECDH, posteriormente se deriva un secreto compartido entre la llave pública de SyPago y la llave privada efímera del cliente, la cual es cifrada usando AES-256-GCM.

Payload de seguridad	Descripción
ephemeral_public_key	Base64 de la pública efímera del cliente.
encrypted_symmetric_key	El resultado de cifrar la llave de sesión (Ciphertext + 16 bytes de Auth Tag).
iv	Vector de inicialización de 12 bytes.

Paso 3 Registro y Cifrado de Llave Simétrica en SyPago

Este proceso permite al cliente establecer un canal seguro para el intercambio de información sensible. Mediante el uso de criptografía híbrida, el cliente envía su llave simétrica (AES-256) cifrada hacia SyPago, garantizando que solo el servidor pueda conocerla. Este paso es fundamental, ya que la llave registrada será la que el sistema utilice posteriormente para procesar y persistir los datos en el flujo de afiliación.

Endpoint
POST api/v1/user/key/symetric

Cuerpo del Json	Descripción
ephemeral_public_key	Base64 de la pública efímera del cliente.
encrypted_symmetric_key	El resultado de cifrar la llave de sesión (Ciphertext + 16 bytes de Auth Tag).
iv	Vector de inicialización de 12 bytes.

Body
{
  "ephemeral_public_key": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEz5yF0JaUxdJK1EvEsfH5L3627xD/Y95GKOofvevJe93slRzqQ/FfzrjDEshncoH6hK31PpygS5fHEiCv1FK0hg==",
  "encrypted_symmetric_key": "D3qAu7MR6b3H3gfwb7K7P97Gw5GfseMBSPQASWL/Y8TnN7gXP4YxvjejJG1pAUIt",
  "iv": "DpLjLxz8cIbGl7HC"
}

Una vez recibidos los datos, SyPago utiliza su llave privada junto con la ephemeral_public_key del cliente para derivar el mismo secreto compartido. Con este secreto, se desencripta la llave simétrica, se verifica la integridad mediante el tag GCM y, finalmente, se almacena la llave asociada al usuario para su uso exclusivo en el paso de afiliación.

Paso 4 Cifrado del payload de afiliación (inicio de flujo)

Este apartado describe el procedimiento de seguridad necesario para el envío de datos sensibles durante el inicio del flujo de afiliación. Para asegurar la confidencialidad e integridad de la información, el cliente debe aplicar un cifrado simétrico sobre el contenido del mensaje antes de consumirlo a través de la API. Este mecanismo garantiza que solo el servidor, poseedor de la llave previamente registrada, pueda acceder al contenido original del JSON de afiliación.

Endpoint
 POST api/v1/account/affiliate

Para realizar la petición al endpoint POST api/v1/account/affiliate, el cliente debe seguir estos pasos:

1. Construcción del Mensaje: Generar el JSON de afiliación en texto plano.
2. Aplicación de AES-256-GCM: Cifrar el JSON utilizando la llave simétrica de 32 bytes que se registró en pasos anteriores, bajo los siguientes parámetros:
- IV/Nonce: 12 bytes aleatorios (debe ser único para cada solicitud).
- Tag: 16 bytes (generado por el algoritmo AES-GCM).

Body

{
  "ciphertext": "<Base64 del ciphertext>",
  "iv": "<Base64 del IV de 12 bytes>",
  "tag": "<Base64 del tag de 16 bytes>"
}

Validaciones en SyPago

Al recibir la solicitud, el servidor ejecuta las siguientes comprobaciones de integridad:

Campos Obligatorios: Los campos ciphertext, iv y tag no deben estar vacíos y deben ser cadenas Base64 válidas.
Longitud del IV: Se valida que la cadena (string) del IV tenga una longitud de entre 16 y 24 caracteres.

Una vez superadas las validaciones, SyPago recupera la llave simétrica asociada al usuario para proceder con la desencriptación mediante AES-GCM. Este proceso incluye la verificación del Tag de autenticidad; si es exitoso, se obtiene el JSON de afiliación original para dar inicio al flujo de procesamiento.

Uso	Algoritmo	Detalles
Intercambio llave	ECDH P-256 Secreto compartido	Normalizado a 32 bytes
Cifrado llave	AES-256-GCM	IV 12 bytes, tag 16 bytes
Cifrado payload	AES-256-GCM	IV 12 bytes, tag 16 bytes, llave 32 bytes
Codificación	Base64	Para todos los campos binarios en JSON

Intercambio de llave simétrica