Llaves RSA | Documentación

Encriptación AES/RSA

Encripta los mensajes entre tu servidor y Culqi

Culqi proporciona un mecanismo de encriptación híbrido AES/RSA entre tus servidor y Culqi, resguardando los datos en tránsito y brindando un segundo factor de protección, ya que cifra los datos y los protege contra cualquier acceso ilícito.

La data sensible del payload se encripta con AES-256-GCM (encriptación simétrica) con un “key” e “iv” generados aleatoriamente, luego se encripta el “key” e “iv” con la llave pública RSA (encriptación asimétrica) y el algoritmo “RSA/ECB/OAEPWithSHA-256AndMGF1Padding”.

Flujo de encriptación

En el siguiente gráfico puedes ver el flujo para realizar la encriptación del payload:

Flujo de encriptación

Cada entorno (producción / integración) maneja llaves RSA distintas por lo que deben ser creadas de forma independiente.

Cómo crear mi llave RSA

1. Ingresa al Dashboard de integración o producción con tu usuario y contraseña.

2. Luego, haz click en la sección “Desarrollo / RSA Keys” de la barra de navegación a la mano izquierda.

3. Pulsa crear llave RSA e ingresa los datos solicitados:

Nombre de tu llave RSA.
Tiempo de vigencia de la llave (el tiempo máximo es un año).
Marca los endpoints que deseas proteger.

Culqi Panel Crear

4. Una vez generada la llave copia y resguarda la siguiente información:

El id de la llave RSA
La llave RSA

Culqi Panel Copiar

5. En tu entorno de integración realiza pruebas con nuestras tarjetas de pruebas.

6. Luego de culminar tus pruebas, cambia tu llave RSA de integración por la de producción para empezar a vender.

¿Cómo usar la llave RSA?

Para poder usar los endpoints del API con encriptación, es necesario utilizar la llave RSA para encriptar los datos (payload) a enviar y agregar el header para identificar la llave que se utilizará para desencriptar el payload(x-culqi-rsa-id).

¿Qué es el payload?

El payload es el resultado de encriptar los datos a enviar utilizando la llave RSA.

El payload(request body) encriptado tiene formato JSON y consta de 3 parámetros:

encrypted_data: payload encriptado.
encrypted_key: key de la encriptación simétrica AES-256.
encrypted_iv: vector de inicialización de la encriptación simétrica AES-256.

¿Cómo generar el payload encriptado?

Para generar el payload encriptado debes seguir los siguientes pasos:

1. Almacena tu llave RSA y ID de la llave RSA en tu server.

2. Genera un key aleatorio(AES-GCM).

3. Genera un iv aleatorio(ASES-GCM).

4. Encripta el payload con el key e iv generados con el algoritmo AES-GCM.

5. Encripta el key aleatorio con la llave RSA pública.

6. Encripta el iv aleatorio con la llave RSA pública.

7. Genera el payload encriptado en formato JSON, el cual contiene el encrypted_data, encrypted_key, encrypted_id.

8. Debes enviar en tu petición el payload encriptado

A continuación mostramos un ejemplo de encriptación con Python:

import json
from Crypto.PublicKey import RSA
from Crypto.Cipher import PKCS1_OAEP
from Crypto.Cipher import AES
from Crypto.Random import get_random_bytes
from Crypto.Hash import SHA256
import base64

class RsaAesEncoder:

    def _encrypt(self, data, public_key):
        # Generate a random encryption key
        key = get_random_bytes(32)
        iv = get_random_bytes(16)
        
        # Message to be encrypted
        message = json.dumps(data).encode('utf-8')

        # Initialize the cipher with the key and IV
        cipher = AES.new(key, AES.MODE_GCM, iv)

        # Encrypt the message
        # Note that the message length must be a multiple of 16 bytes
        ciphertext = cipher.encrypt(message)
        
        encrypted_message = base64.b64encode(ciphertext).decode('utf-8')

        # Encrypt the key with the public key
        cipher = PKCS1_OAEP.new(RSA.import_key(public_key), hashAlgo=SHA256)
        ciphertext_key = cipher.encrypt(key)

        # Encrypt the iv with the public key
        cipher = PKCS1_OAEP.new(RSA.import_key(public_key), hashAlgo=SHA256)
        ciphertext_iv = cipher.encrypt(iv)

        # Convert the encrypted message to a string
        encrypted_aes_key = base64.b64encode(ciphertext_key).decode()
        encrypted_aes_iv = base64.b64encode(ciphertext_iv).decode()

        return {
            "encrypted_data": encrypted_message, 
            "encrypted_key": encrypted_aes_key, 
            "encrypted_iv": encrypted_aes_iv
        }

¿Cómo realizar una petición encriptada?

Para realizar una petición con payload encriptado, envía el header x-culqi-rsa-id y el body encriptado como se muestra a continuación:

curl --location --request POST 'https://secure.culqi.com/v2/tokens' \
--header 'Authorization: Bearer pk_live_53d22e51b61a43d1' \
--header 'Content-Type: application/json' \
--header 'x-culqi-rsa-id: 2ab335ad-c40d-4375-8dad-3ea315de23b0' \
--data-raw '{
    "encrypted_data": "+iXSkRrC7nUYL310YsEOnk39iqr5b6fUTf+taY1KgQuIyoK93Ss5EAI1MVnL8jmuHdOpZd1GP6+1AMZ7QjaHWW5gmEuPA/lHRbpqdw4hNLgIBZxu7kvnF9pLRLrtmrIrr1CQJXK4eX8NcLpV/JCvXQ/CMK4CnQwQLnTHf4b0fdg5GmqFugFSdynuey0ubel70HsB1bszmUl1cGNTkNyboe+PKWZcpSwl1btLszOvKSOVe0mNoWeiRYVbqGZF87BE",
    "encrypted_key": "G8YuFIiX7rDbtV9r0iKndJRNBRqOnPDqqhsHiUlGb6rmp0lNZgZayWsgP9etL4m1YdCsjuRhdhmOTbNtlhh4HrgeI2NGAHWltgdHsS85kbzuOZT3elV5BZptDBjhh9UeCiOWX228vE8wznIdXvp/hB1bmFtvR5w1DUB+qK2MPDY=",
    "encrypted_iv": "HZkjM80P5CpVP3XvmuTUjGFWp7Lol6u0ocn5OXoTr658dLgkCjZIubIrLqgmsiMV9+wV6XK0CZgXWNe+hYdI5ZfuuOvkT5onaajAOz5IjzaATM0xlzltAZqEFaZzPjJf7pdCVLUJRfOqbrJPljNk+axSrKc1o+6UxL7cQG3SHrY="
}'

Renovación de llaves RSA

Por seguridad es importante cambiar de llaves cada cierto tiempo para evitar que se puedan comprometer. Sigue el mismo proceso anteriormente delineado para generar un nuevo par de llaves y una vez que estás seguro que el nuevo par funciona bien da de baja las anteriores.

Recuerda que si no le pusiste una fecha de vencimiento automáticamente las llave expirarán en 1 año por lo que este proceso lo debes realizar por lo menos una vez al año de creadas las llaves RSA.

¿Donde puedo habilitar encriptación?

Existen diferentes opciones de integración donde puedes habilitar la encriptación de payload, dependen del nivel de control y personalización que se desee:

Plugins CMS	Si tienes un CMS y usas el plugin de Culqi descarga la última versión del plugin y configúralo para usar las llaves de encriptación.
Culqi Checkout	En caso uses el culqi Checkout debes agregar nuevos parámetros en el Culqi.setting. ver configuración
Culqi API	En caso uses el API directo sigue las instrucciones para generar el payload desde tu servidor.

Encriptación frontend

A nivel frontend el API permite consumir los endpoint de tokenización y órdenes. Así mismo existen diferentes mecanismos de integración que se pueden configurar para generar el mensaje encriptado.

Culqi Checkout

Para habilitar la encriptación de payload debes agregar a su configuración el id y la llave RSA, y este realizará el proceso de encriptación por ti.

En caso quieras utilizar este mecanismo de integración, sigue las instrucciones aquí.

Usando APIs

Para tener control total del proceso de encriptación, debes codear tu proceso de encriptación y usarlo según el flujo del diagrama antes mostrado.

Encriptación Backend

A nivel backend el API permite consumir todos los endpoint del API aunque idealmente la tokenización siempre se debe realizar a nivel de frontend para que el server no toque datos sensibles como la tarjeta .

Así mismo existen diferentes mecanismos de integración que se pueden configurar para generar el mensaje encriptado.

Usando librerías

Culqi tiene una serie de librerías (PHP, Ruby, Python,Java, .Net etc) que te sirven para interactuar con el API de CULQI, busca la versión que soporta el proceso de encriptación. Sigue los siguientes ejemplos para activar la encriptación mediante librerías. Para revisar nuetras librerías ingresa aquí.

Usando API

En caso desees integrarte directamente a nuestras APIs para tener control total de tu integración backend, puedes hacer uso de nuestra variedad de servicios Rest y codear tu propio proceso de encriptación. Ver ejemplo