Script de ejemplo para cifrar información

09 octubre 2024

En caso de que estés en fase de pruebas y aún no cuentes con un HSM (Hardware Security Module), puedes solicitar a Kushki que te proporcione las claves de prueba para que, a través de una biblioteca, puedas cifrar los datos de la transacción y hacer peticiones en Postman a la API de Kushki, de esta forma poder acelerar la implementación de tu solución.

A continuación se mostrarán los pasos a seguir para poder cifrar los datos de la tarjeta leída con la terminal POS utilizando las claves de cifrado mediante la herramienta Cardtool.

Requisitos

Para poder realizar el cifrado por medio del script y obtener la información que se debe incluir en la solicitud, es necesario contar con los siguientes elementos:

• BDK (en formato TR-31) que será proporcionada por el área de Seguridad de la Información de Kushki.
• BDK (en formato TR-31) de PIN que de igual manera es proporcionado por el área de Seguridad de la Información. Este es utilizado solamente para transacciones con PIN online.
• Un par de credenciales para transaccionar, deberás contar con tu private key y tu public key.
• Key Serial Number (KSN) de tu terminal, puedes obtener un KSN de ejemplo y simplemente modificar el contador cada que realices una nueva transacción
• Instalar Python.
• Instalar la herramienta de Cardtool.

1. Preparación de variables

Debes configurar los siguientes datos en los archivos de configuración setting.yml y cards-out.json dentro del proyecto antes de ejecutarlo.

La configuración deberá mostrarse como se indica en la siguiente imagen:

Ejecutar los siguientes comandos:

python3 -m venv .env
source .env/bin/activate
!pip3 install cardtool

2. Obtener clave en “claro”

Para poder realizar el cifrado de los datos de PIN y tarjeta es necesario primero obtener la clave en “claro” desde la clave compartida por Kushki en formato tr-31

Para ello, vamos a realizar la ejecución del siguiente comando

cardtool decrypt-key -kbpk <your_key_block_protection_key> -kcv <key_check_value> YOUR_KEY_BLOCK

El resultado será parecido al siguiente:

Plaintext Key: ABCD1234AB01CD23F126FBAB02621ADA

Este valor será utilizado para el siguiente comando donde vamos a cifrar la información de la data y PIN.

3. Ejecución de script para obtener data cifrada

Ahora que tenemos configurado el archivo de settings.yaml e instalada nuestra dependencia, vamos a realizar la ejecución del siguiente comando:

cardtool gen-card -cfg setting.yml -fmt json cards-out.json

Al ejecutar el comando vamos a obtener el archivo de cards-out.json como salida, este archivo contendrá la información necesaria para poder enviar en el cuerpo de tu petición de ejemplo:

4. Payload de transacción

Para poder ejecutar el payload de prueba de una transacción, recomendamos utilizar Postman, en el cual ya contamos con una colección que podrás encontrar en este enlace. Dicha colección puede ser de apoyo para las pruebas y validaciones durante la implementación.

Al obtener la información cifrada de la tarjeta y el PIN, solo debes incluir en el body del request y enviar.