Integração e Exemplos Práticos

Integração e Exemplos Práticos

Para garantir uma implementação segura e fluida, esta secção detalha os três fluxos operacionais mais comuns na gestão de chaves criptográficas com parceiros, acompanhados de snippets de código nas linguagens mais utilizadas.

Cenários de Integração (Fluxos)

Cenário 1: Onboarding Interno (Gerar Nova Chave)

Este é o cenário mais simples. O cliente integrador necessita de gerar uma nova chave para uso estritamente interno (ex.: uma ZPK que será usada no módulo PayShield PIN para validar PIN blocks recebidos do front-end) .

Sequência:

1. Obter o token JWT via Auth0.

2. Invocar o GenerateKey com keyName = "ZPK", keySizeType = "D" (DES double-length, padrão em PIN) e modeFlag = "0" .

3. Capturar o retValue (keyId) retornado e registá-lo na base de dados do cliente, associado a este contexto de uso.

4. Capturar o retMultiValue[0] (KCV) e registá-lo para fins de auditoria e reconciliação futura.

5. A partir deste momento, o keyId pode ser consumido em chamadas aos restantes módulos da Hop V4.

---

Cenário 2: Receção de Chave de Parceiro

Cenário típico de integração: o cliente necessita de receber uma chave ZPK gerada por um adquirente parceiro. Esta chave é enviada encriptada sob uma ZMK que ambas as partes partilham .

Sequência:

1. Key Ceremony: Acordo prévio documentado com o parceiro para definir tipos de chave, tamanhos e esquema de troca.

2. Receber do parceiro a ZMK no formato Key Block Thales e o respetivo KCV.

3. Invocar o ImportZMK utilizando os dados do passo anterior. Registar o keyId retornado.

4. Receber do parceiro a ZPK (encriptada sob a ZMK partilhada).

5. Invocar o ImportKey passando a chave encriptada (key_under_ZMK_to_import) e o alias da ZMK (ZMK_keyId). Registar o novo keyId da ZPK .

6. Validação Crítica: Comparar o KCV retornado no retMultiValue[0] com o KCV informado pelo parceiro. Têm de coincidir obrigatoriamente; caso contrário, aborte a operação e investigue .

---

Cenário 3: Envio de Chave para Parceiro

Cenário inverso: o cliente necessita de enviar uma ZPK para um parceiro. Existem duas abordagens possíveis .

Abordagem A: Geração com Exportação Simultânea Ideal quando já se sabe de antemão qual o parceiro que vai receber a chave.

1. Importar a ZMK do parceiro via ImportZMK (se ainda não existir no banco).

2. Invocar o GenerateKey com modeFlag = "1", apontando para a ZMK do parceiro no campo zmk_TMK_keyId. A API gera a chave e, na mesma chamada, devolve a chave já encriptada sob a ZMK de destino .

3. Enviar o resultado e o KCV para o parceiro através do canal seguro acordado.

Abordagem B: Geração e Exportação Separadas Ideal quando a ZPK é criada para uso interno primeiro, ou precisa de ser distribuída a múltiplos parceiros .

1. Invocar o GenerateKey com modeFlag = "0" para criar a ZPK no banco.

2. Para cada parceiro destino: invocar o ExportKey utilizando o keyId da ZPK e a ZMK_keyId do parceiro em questão. Recomenda-se selecionar "TR31" no export_scheme .

3. Enviar o retMultiValue[0] resultante a cada parceiro, acompanhado do KCV correspondente.

---

Exemplos de Código (Snippets)

cURL — Gerar uma ZEK Efémera (GenerateKey)

Bash

curl -X POST \
  https://apivin.first-tech.net/v4/PayShieldKeyManager/GenerateKey \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": 42,
    "keyName": "ZEK",
    "keySizeType": "S",
    "modeFlag": "0",
    "is_ephemeral": true,
    "key_TTL_minutes": 1440
}'

Python — Pipeline de Onboarding de Parceiro

Este script demonstra a importação da ZMK e, de seguida, a importação da ZPK protegida por ela.

Python

import requests

BASE = "https://apivin.first-tech.net/v4/PayShieldKeyManager"

def onboard_partner(token, client_id, partner_zmk, partner_zmk_kcv, partner_zpk_under_zmk):
    headers = {"Authorization": f"Bearer {token}"}

    # 1) Importa a ZMK
    r1 = requests.post(f"{BASE}/ImportZMK", headers=headers, json={
        "client_id": client_id,
        "kcv": partner_zmk_kcv,
        "keyZMK": partner_zmk,
    }, timeout=15)
    
    d1 = r1.json()
    if not d1.get("retValid"):
        raise RuntimeError(f"ImportZMK falhou: {d1}")
        
    zmk_alias = d1["retValue"]
    print(f"ZMK cadastrada: {zmk_alias} (KCV={d1['retMultiValue'][0]})")

    # 2) Importa a ZPK sob a ZMK
    r2 = requests.post(f"{BASE}/ImportKey", headers=headers, json={
        "client_id": client_id,
        "keyName": "ZPK",
        "keySizeType": "D",
        "key_under_ZMK_to_import": partner_zpk_under_zmk,
        "ZMK_keyId": zmk_alias,
    }, timeout=15)
    
    d2 = r2.json()
    if not d2.get("retValid"):
        raise RuntimeError(f"ImportKey falhou: {d2}")
        
    return {
        "zmk_keyId": zmk_alias,
        "zpk_keyId": d2["retValue"],
        "zpk_kcv": d2["retMultiValue"][0]
    }

Node.js — Geração com Exportação Simultânea (modeFlag = 1)

JavaScript

const axios = require("axios");

async function generateAndExportZpkToPartner(token, clientId, partnerZmkAlias) {
  const url = "https://apivin.first-tech.net/v4/PayShieldKeyManager/GenerateKey";
  const payload = {
    client_id: clientId,
    keyName: "ZPK",
    keySizeType: "D",
    modeFlag: "1",
    zmk_TMK_flag: "ZMK",
    zmk_TMK_keyId: partnerZmkAlias,
  };

  const { data } = await axios.post(url, payload, {
    headers: { Authorization: `Bearer ${token}` },
    timeout: 15000,
  });

  if (!data.retValid) {
    throw new Error(`HSM retCode=${data.retCode}: ${data.retDescription}`);
  }

  return {
    keyId: data.retValue,
    kcv: data.retMultiValue[0],
    keyUnderZmk: data.retMultiValue[1] || null
  };
}