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

# Fundamentos e Criptografia

O módulo PIN da plataforma Hop V4 expõe operações REST seguras para a validação de PINs de portadores e para a tradução de PinBlocks entre diferentes chaves criptográficas. Toda operação ocorre em ambiente de Hardware Security Module (HSM) certificado PCI PIN, garantindo que o PIN nunca seja exposto em claro .

### Regras de Ouro (PCI PIN)

Ao integrar com os endpoints deste módulo, as seguintes premissas arquiteturais são inegociáveis:

* Nunca exponha o PIN em claro: Os endpoints não retornam e não devem retornar o PIN decifrado.
* Cifragem de Ponta a Ponta: Chaves de PIN (TPK, ZPK, BDK, PVK) jamais circulam em claro.
* Não armazene PinBlocks em cache: O reaproveitamento de PinBlocks entre transações viola o padrão PCI PIN e falhará tecnicamente em esquemas de chaves dinâmicas (DUKPT) .
* Mascaramento de Logs: É estritamente proibido registrar os campos `hPibBlock`, `hPinHost` ou o PAN completo nos logs da sua aplicação .

***

### Tipos de Chaves Suportadas

O módulo suporta operações em uma cadeia completa de aquisição, atuando como tradutor de chaves para adquirentes e como validador final para emissores .

<table data-header-hidden="false" data-header-sticky><thead><tr><th>Tipo</th><th>Nome Completo</th><th>Descrição e Uso</th></tr></thead><tbody><tr><td>TPK</td><td><em>Terminal PIN Key</em></td><td>Chave injetada no terminal (maquininha). Cifra o PinBlock no momento em que o portador digita a senha.</td></tr><tr><td>ZPK</td><td><em>Zone PIN Key</em></td><td>Chave compartilhada entre zonas de segurança (ex: adquirente ↔ bandeira ↔ emissor). O PinBlock é traduzido entre ZPKs a cada fronteira de rede.</td></tr><tr><td>BDK</td><td><em>Base Derivation Key</em></td><td>Chave-mestra utilizada em ambientes DUKPT (<em>Derived Unique Key Per Transaction</em>). O HSM utiliza o BDK em conjunto com o KSN para derivar uma chave de sessão única por transação.</td></tr><tr><td>PVK</td><td><em>PIN Verification Key</em></td><td>Utilizada pelo emissor para gerar e validar o PVV (<em>PIN Verification Value</em>). O PIN é validado no HSM sem a necessidade de ser armazenado.</td></tr></tbody></table>

***

### Formatos de PinBlock

O campo que recebe o código de formato no payload da API é grafado como `pibBlockFmt`. Certifique-se de manter esta grafia exata na sua integração; o uso de "pinBlockFmt" resultará em erro de requisição (HTTP 400).

Os seguintes valores de formato são aceitos pela API:

#### Formatos ISO 9564-1

<table data-header-hidden="false" data-header-sticky><thead><tr><th>Código (pibBlockFmt)</th><th>Norma e Formato</th><th>Características</th></tr></thead><tbody><tr><td><code>01</code></td><td>ISO 9564-1 Formato 0</td><td>Bloco de 8 bytes. Padrão mais comum em transações com cartão. Construído com operação XOR entre o PIN e os últimos 12 dígitos do PAN.</td></tr><tr><td><code>02</code></td><td>ISO 9564-1 Formato 1</td><td>Bloco de 8 bytes com <em>padding</em> aleatório. Utilizado em cenários onde não há PAN disponível (ex: ATM offline).</td></tr><tr><td><code>03</code></td><td>ISO 9564-1 Formato 2</td><td>Bloco de 8 bytes sem operação XOR com o PAN. Uso restrito e tipicamente offline.</td></tr><tr><td><code>04</code></td><td>ISO 9564-1 Formato 3</td><td>Bloco de 8 bytes. Variação do formato 0, mas contendo <em>padding</em> aleatório adicional.</td></tr><tr><td><code>05</code></td><td>ISO 9564-1 Formato 4</td><td>Bloco de 16 bytes (128 bits) criptografado sob AES. Formato obrigatório em esquemas EMV modernos.</td></tr></tbody></table>

#### Formatos Proprietários

O módulo também oferece suporte nativo à validação e tradução de variantes proprietárias utilizadas na indústria:

* `34`: Variante Proprietária `0x34`.
* `35`: Variante Proprietária `0x35`.
* `41`: Variante Proprietária `0x41`.
* `42`: Variante Proprietária `0x42`.
* `47`: Variante Proprietária `0x47`.
* `48`: Variante Proprietária `0x48`.

> Atenção à consistência do PAN: Nos formatos baseados em operação XOR (`01`, `04`, `05`), se o PAN enviado na requisição da API divergir do PAN utilizado pelo terminal no momento da criação do PinBlock, o PIN resultante será corrompido, gerando erro de "tamanho zero" (Código 88) ou recusa indevida da senha.


---

# 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-pin/fundamentos-e-criptografia.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.