> For the complete documentation index, see [llms.txt](https://ftcoders.first-tech.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://ftcoders.first-tech.com/landing-page/modulo-rsa/integracao-exemplos-e-troubleshooting.md).

# 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

```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

```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

```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

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

***

### 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:

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

#### 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:

<table data-header-hidden="false" data-header-sticky><thead><tr><th>Início do Hexadecimal</th><th>Formato Provável</th><th>publicKeyEncoding Aplicável</th></tr></thead><tbody><tr><td><code>3082...</code></td><td>DER ASN.1 SEQUENCE longo (X.509 <code>SubjectPublicKeyInfo</code>).</td><td><code>1</code> (RSA unsigned)</td></tr><tr><td><code>3081...</code></td><td>DER ASN.1 SEQUENCE médio (<code>RSAPublicKey</code> PKCS#1).</td><td><code>1</code> ou <code>2</code></td></tr><tr><td><code>04...</code></td><td>X9.62 ECC uncompressed point.</td><td><code>3</code> (ECC X9.62)</td></tr><tr><td><code>02...</code> / <code>03...</code></td><td>X9.62 ECC compressed.</td><td>Não suportado</td></tr></tbody></table>

#### Apêndice C. Glossário Resumido

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


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://ftcoders.first-tech.com/landing-page/modulo-rsa/integracao-exemplos-e-troubleshooting.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.