Integração, Exemplos e Troubleshooting

Fluxo de Integração

Pré-requisitos

Antes de consumir os endpoints do módulo RSA, o integrador deve garantir os seguintes itens :

• Credenciais Auth0: Client ID e Client Secret com escopo de acesso ao módulo RSA.

• Identificador do Cliente: O seu client_id numérico.

• Chave Simétrica Cadastrada: A chave (DES/AES/HMAC) a ser exportada deve estar previamente cadastrada via módulo Key Manager .

• Chave Pública da Contraparte: Recebida em formato DER ASN.1 (codificada em hexadecimal) .

• Acordo de Key Ceremony: Definição mútua sobre os parâmetros de padding (padModeId) e MGF (mgfHashFunction).

Fluxo Típico — Exportar uma ZMK para um Parceiro

Neste cenário, a instituição envia uma Zone Master Key (ZMK) para um parceiro adquirente de forma segura :

1. Receber a chave pública RSA do parceiro (formato DER ASN.1 em hexadecimal) através de um canal seguro.

2. Obter o token JWT de autenticação.

3. Invocar o endpoint Import utilizando o publicKeyEncoding adequado à chave recebida. O retorno (retValue) será o Key Block Thales .

4. Invocar o endpoint Export referenciando o keyId da ZMK, os parâmetros de padding acordados, e injetando o Key Block Thales no campo publicKey.

5. Enviar a chave criptografada (o retValue do Export) para a contraparte através do canal acordado.

Aviso Arquitetural: O módulo PayShield RSA efetua apenas a EXPORTAÇÃO da chave. A operação inversa (decifragem da chave simétrica utilizando a chave privada RSA) ocorre no HSM da contraparte e está fora do escopo do Hop V4 .

Boas Práticas

• OAEP por Padrão: Priorize sempre a utilização do padModeId = 2 (OAEP) combinado com mgfHashFunction = 6 (SHA-256). Utilize PKCS#1 v1.5 apenas em integrações legadas.

• Não armazene o Key Block em Cache: O retorno do Import (Key Block) contém um MAC com timestamp implícito. Refaça a importação a cada nova operação; não armazene este bloco para uso futuro .

• Auditoria: Registe nos logs de segurança os parâmetros da operação (client_id, keyId, padding, fingerprint SHA-256 da chave pública). NUNCA registe o retValue do Export, pois é o próprio material criptográfico .

• Validação Prévia: Antes de chamar a API, valide o tamanho e a estrutura da chave pública recebida utilizando o OpenSSL.

• Política de Retry: Efetue retry automático apenas em erros 500. Erros 400 (ex: 01, 02, 04, 83) indicam anomalias nos dados ou nos parâmetros e requerem correção antes de nova tentativa .

---

Exemplos Práticos

Preparação (Geração de Chaves via OpenSSL)

Para simular a contraparte em ambiente de testes :

Bash

# 1. Gera chave privada RSA de 2048 bits
openssl genpkey -algorithm RSA -pkeyopt rsa_keygen_bits:2048 -out private_key.pem

# 2. Extrai a chave pública
openssl rsa -in private_key.pem -pubout -out public_key.pem

# 3. Converte para DER e obtém o hexadecimal (input para a API)
openssl rsa -in public_key.pem -pubin -outform DER -out public_key.der
xxd -p -c 9999 public_key.der

Fluxo Completo via cURL

Bash

# Passo 1 - Import
curl -X POST https://apivin.first-tech.net/v4/PayShieldRsa/Import \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": 42,
    "publicKeyEncoding": 1,
    "publicKey": "3082020A0282020100A069D9C3..."
  }'

# Passo 2 - Export (utilizando o retValue retornado no passo 1)
KEY_BLOCK="S1056002RN00S00013082020A..."

curl -X POST https://apivin.first-tech.net/v4/PayShieldRsa/Export \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d "{
    \"client_id\": 42,
    \"keyId\": \"client-42-key-id-XXXX-ZMK\",
    \"padModeId\": 2,
    \"mgfHashFunction\": 6,
    \"publicKey\": \"$KEY_BLOCK\",
    \"keyBlockType\": 3
  }"

Snippet em Python

Python

import requests
BASE = "https://apivin.first-tech.net/v4/PayShieldRsa"

def exportar_chave_para_parceiro(token, client_id, key_id, public_key_hex, encoding=1, pad_mode=2, mgf_hash=6):
    headers = {"Authorization": f"Bearer {token}"}
    
    # Passo 1: Import
    r1 = requests.post(f"{BASE}/Import", headers=headers, json={
        "client_id": client_id,
        "publicKeyEncoding": encoding,
        "publicKey": public_key_hex,
    }, timeout=15)
    d1 = r1.json()
    if not d1.get("retValid"):
        raise RuntimeError(f"Import falhou: {d1}")
        
    key_block = d1["retValue"]
    
    # Passo 2: Export
    payload = {
        "client_id": client_id,
        "keyId": key_id,
        "padModeId": pad_mode,
        "publicKey": key_block,
        "keyBlockType": 3,
    }
    if pad_mode == 2:
        payload["mgfHashFunction"] = mgf_hash
        
    r2 = requests.post(f"{BASE}/Export", headers=headers, json=payload, timeout=15)
    d2 = r2.json()
    if not d2.get("retValid"):
        raise RuntimeError(f"Export falhou: {d2}")
        
    return d2["retValue"]

---

Troubleshooting

Sintoma	Causa Provável	Solução
HTTP 400 (retCode 04 ou 50) no Import	Chave pública em formato errado (ex: PKCS#1 vs X.509).	Confirmar com a contraparte o formato e ajustar o parâmetro publicKeyEncoding.
HTTP 400 (retCode 83) no Export	O publicKey enviado é a chave DER bruta.	Enviar estritamente o Key Block Thales obtido no retorno do Import.
HTTP 400 (retCode 07) no Export	O padModeId está incorreto.	Utilizar apenas os valores 1 ou 2.
HTTP 400 (retCode 85 ou 86) no Export	O mgfHashFunction foi enviado de forma inválida.	OAEP exige função MGF explícita. O modo PKCS#1 v1.5 exige a omissão deste campo.
HTTP 400 (retCode 10 ou 47) no Export	Erro de paridade na chave simétrica ou algoritmo não licenciado no HSM.	Recadastrar a chave no módulo Key Manager ou acionar o suporte técnico para questões de licenciamento.
HTTP 404 no Export	keyId não cadastrado.	Confirmar a sintaxe e a existência do alias no Key Manager.
HTTP 400 (retCode D3) no Export	Violação dos critérios PCI HSM V3.	O algoritmo ou o tamanho da chave não cumprem os requisitos mínimos de segurança parametrizados.
Contraparte falha na decifragem	Divergência de parâmetros criptográficos.	Reverificar o acordo formal (Key Ceremony) em relação ao Padding e à Função Hash.

---

Apêndices

Apêndice A. Acordo de Key Ceremony (Itens Obrigatórios)

Qualquer troca de chaves via módulo RSA requer um alinhamento prévio:

Parâmetro	Descrição
Partes Envolvidas	Razão social, CNPJ e responsáveis de ambas as instituições.
Tipo de Chave e Finalidade	Ex: ZMK, ZPK, BDK (e o seu propósito específico).
Algoritmos Simétricos e Assimétricos	Ex: AES-256 (simétrica) e RSA 2048 / ECC P-256 (assimétrica).
Codificação (publicKeyEncoding)	Formato exato da chave DER ASN.1 (1, 2 ou 3).
Modo de Preenchimento e MGF	padModeId (PKCS#1 v1.5 ou OAEP) e a respetiva função hash (ex: SHA-256).
Canal e Validade	Canal de partilha e o ciclo de vida/rotação da chave partilhada.

Apêndice B. Identificação Visual de Formatos

Se o parceiro não especificar o formato da chave, o cabeçalho hexadecimal fornece indícios cruciais:

Início do Hexadecimal	Formato Provável	publicKeyEncoding Aplicável
3082...	DER ASN.1 SEQUENCE longo (X.509 SubjectPublicKeyInfo).	1 (RSA unsigned)
3081...	DER ASN.1 SEQUENCE médio (RSAPublicKey PKCS#1).	1 ou 2
04...	X9.62 ECC uncompressed point.	3 (ECC X9.62)
02... / 03...	X9.62 ECC compressed.	Não suportado

Apêndice C. Glossário Resumido

Sigla	Significado	Contexto
ASN.1 / DER	Abstract Syntax Notation One / Distinguished Encoding Rules	Padrão e codificação binária das estruturas de chaves públicas.
BDK / ZMK / ZPK	Base Derivation Key / Zone Master Key / Zone PIN Key	Chaves simétricas protegidas e geridas pelo ecossistema de pagamentos.
ECC / RSA	Elliptic Curve Cryptography / Rivest-Shamir-Adleman	Algoritmos de criptografia assimétrica.
Key Block	Bloco Seguro (Thales)	Estrutura que encapsula o material criptográfico juntamente com um MAC (integridade).
OAEP / MGF	Optimal Asymmetric Encryption Padding / Mask Generation Function	Esquemas modernos e avançados de preenchimento matemático para chaves RSA.