> 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/fundamentos-e-arquitetura.md).

# Fundamentos e Arquitetura

O módulo PayShield RSA da plataforma Hop V4 disponibiliza operações REST para a importação de chaves públicas (RSA e ECC) e a exportação segura de chaves simétricas (DES, AES, HMAC) protegidas por essas chaves públicas.

Este módulo é fundamental para fluxos de troca de chaves entre instituições, como em cerimónias de troca inicial de chaves entre adquirentes, emissores e bandeiras, ou na integração com parceiros que exijam o transporte seguro de chaves simétricas através de criptografia de chave pública.

### Funcionamento do Módulo

O transporte de chaves sob chave pública permite que a instituição destinatária gere um par de chaves RSA, envie a parte pública e receba a chave simétrica criptografada, garantindo que apenas o detentor da chave privada correspondente consiga decifrá-la.

O fluxo implementado no Hop V4 ocorre em duas etapas obrigatórias:

1. Import: Recebe a chave pública em formato DER ASN.1, gera um MAC sobre ela utilizando a LMK do HSM e devolve a chave encapsulada num Key Block Thales. Este formato protege a chave pública contra adulterações após a importação.
2. Export: Recebe a referência (`keyId`) de uma chave simétrica e o Key Block Thales obtido no passo anterior, retornando a chave simétrica criptografada sob a chave pública.

> ⚠️ Sequência Obrigatória: Import → Export A chave pública utilizada como entrada no endpoint `Export` NÃO deve ser a chave bruta DER recebida da contraparte. Deve ser obrigatoriamente o resultado da operação `Import` (o Key Block Thales com MAC). O uso direto da chave DER resultará em erros de validação (código 02 ou 83).

***

### Modos de Padding (RSA)

A criptografia RSA exige um esquema de preenchimento (*padding*) para garantir a segurança da operação. O Hop V4 suporta os dois esquemas padrão da indústria através do parâmetro `padModeId`:

<table data-header-hidden="false" data-header-sticky><thead><tr><th>padModeId</th><th>Esquema</th><th>Aplicação</th><th>Requer MGF?</th></tr></thead><tbody><tr><td>1</td><td>PKCS#1 v1.5</td><td>Compatibilidade com sistemas legados ou parceiros que ainda não migraram para OAEP.</td><td>Não</td></tr><tr><td>2</td><td>PKCS#1 v2.2 OAEP</td><td>Padrão moderno recomendado. Mais resistente a ataques de oráculo de padding.</td><td>Sim</td></tr></tbody></table>

#### Funções Hash MGF (Apenas OAEP)

Ao utilizar o modo OAEP (`padModeId = 2`), o campo `mgfHashFunction` torna-se obrigatório para indicar a função hash utilizada no MGF1 (*Mask Generation Function*):

<table data-header-hidden="false" data-header-sticky><thead><tr><th>mgfHashFunction</th><th>Função Hash</th><th>Recomendação</th></tr></thead><tbody><tr><td>1</td><td>SHA-1</td><td><p>Apenas para compatibilidade legada.</p><p><a class="button secondary"></a></p></td></tr><tr><td>5</td><td>SHA-224</td><td><p>Pouco utilizada na prática.</p><p><a class="button secondary"></a></p></td></tr><tr><td>6</td><td>SHA-256</td><td><p>Padrão recomendado para novas integrações.</p><p><a class="button secondary"></a></p></td></tr><tr><td>7 / 8</td><td>SHA-384 / SHA-512</td><td><p>Níveis superiores de segurança (verificar compatibilidade).</p><p><a class="button secondary"></a></p></td></tr></tbody></table>

***

### Formatos de Chave Pública e Bloco de Saída

#### Codificação na Importação (`publicKeyEncoding`)

O parâmetro `publicKeyEncoding` no endpoint `Import` define a estrutura da chave pública DER ASN.1 recebida:

<table data-header-hidden="false" data-header-sticky><thead><tr><th>publicKeyEncoding</th><th>Formato</th><th>Tipo de Chave</th></tr></thead><tbody><tr><td>1</td><td>DER ASN.1 RSA (INTEGER unsigned)</td><td>RSA (PKCS#1 ou X.509).</td></tr><tr><td>2</td><td>DER ASN.1 RSA (INTEGER 2's complement)</td><td>RSA (variação de codificação de módulo).</td></tr><tr><td>3</td><td>DER ASN.1 ECC X9.62 uncompressed</td><td>ECC (formato de ponto uncompressed, prefixo <code>0x04</code>).</td></tr></tbody></table>

#### Tipo de Bloco na Exportação (`keyBlockType`)

O parâmetro `keyBlockType` define o formato do bloco de chave produzido. Atualmente, o único valor suportado em produção é o 3 (*Unformatted Key Data Block*).

***

### Arquitetura e Padrão de Resposta

* Base URL: `https://apivin.first-tech.net/v4/PayShieldRsa/`.
* Autenticação: Exige token Bearer JWT enviado no cabeçalho `Authorization` de cada requisição.
* Identificação do Cliente: O campo `client_id` identifica o cliente, garantindo a segregação de chaves e histórico no HSM.
* Identificação da Chave (`keyId`): Referencia o alias da chave simétrica (DES, AES ou HMAC) previamente cadastrada no módulo Key Manager. O formato padrão é `client-{client_id}-key-id-XXX-TIPO`.

#### Estrutura de Resposta (`ReturnSingle`)

Todas as respostas do módulo RSA utilizam o envelope `ReturnSingle`, processando uma única chave por chamada:

<table data-header-hidden="false" data-header-sticky><thead><tr><th>Campo</th><th>Tipo</th><th>Descrição</th></tr></thead><tbody><tr><td><code>retCode</code></td><td><code>integer</code></td><td>Código de retorno (<code>0</code> para sucesso).</td></tr><tr><td><code>retValid</code></td><td><code>boolean</code></td><td>Indica o sucesso da operação.</td></tr><tr><td><code>retValue</code></td><td><code>string</code></td><td>Valor em hexadecimal (Key Block no Import; Chave criptografada no Export).</td></tr><tr><td><code>retDescription</code></td><td><code>string</code></td><td>Descrição textual do resultado (Ex.: "OK").</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/fundamentos-e-arquitetura.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.