> 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-key-manager/introducao-e-fundamentos.md).

# Introdução e Fundamentos

O módulo PayShield Key Manager da plataforma Hop V4 centraliza e gere o ciclo de vida das chaves criptográficas (DES, 3DES, AES) através do HSM Thales, sempre protegidas sob a LMK (Local Master Key) .

Como o Key Manager é o módulo de base da plataforma — uma vez que todos os outros módulos (CVV, EMV, PIN, PAN, Crypto) referenciam as chaves aqui cadastradas —, este é o ponto de partida natural para qualquer integração com a Hop V4.

### Para que serve o Módulo Key Manager?

Em plataformas de pagamento, as chaves precisam de ser geradas, importadas, exportadas, rotacionadas e, por vezes, traduzidas entre ambientes. O módulo expõe via API REST as seguintes operações fundamentais :

* Generate: Gera uma nova chave aleatória diretamente no HSM, sob a proteção da LMK. O seu alias (`keyId`) e KCV (*Key Check Value*) são retornados .
* Import: Importa uma chave recebida de um parceiro, encriptada sob uma ZMK (*Zone Master Key*). O HSM decifra com a ZMK e re-cifra com a LMK para armazenamento seguro .
* ImportZMK: Importa a própria ZMK (em formato Key Block Thales), que servirá de base para proteger todas as trocas subsequentes com a contraparte .
* ExportKey: Exporta uma chave armazenada sob a LMK, encriptando-a sob a ZMK do parceiro em formatos específicos (X9.17, TR-31, TKBF).
* TranslateLMK: Traduz uma chave de um LMK antigo para o LMK atual (essencial em migrações de ambiente, como da Hop V3 para V4) .

> Princípio de Proteção Absoluta As chaves nunca aparecem em texto claro fora do HSM. Estão sempre protegidas por outra chave: pela LMK no armazenamento, pela ZMK em trânsito, ou pelo Key Block Thales (que adiciona um MAC de integridade)

### Tipos de Chave (`keyName`)

O campo `keyName` define a finalidade da chave. O HSM impõe regras estritas com base neste tipo (ex.: dita se a chave pode encriptar PIN blocks, calcular MACs ou ser exportada) .

<table data-header-hidden="false" data-header-sticky><thead><tr><th>keyName</th><th>Nome Completo</th><th>Finalidade</th></tr></thead><tbody><tr><td><code>ZMK</code></td><td>Zone Master Key</td><td>Chave-mestra partilhada. Protege outras chaves em trânsito (nunca usada diretamente em transações).</td></tr><tr><td><code>TMK</code></td><td>Terminal Master Key</td><td>Chave-mestra de terminal POS. Protege chaves de trabalho enviadas para o terminal.</td></tr><tr><td><code>ZPK</code></td><td>Zone PIN Key</td><td>Chave de trabalho para encriptar PIN blocks em transações entre zonas.</td></tr><tr><td><code>ZAK</code></td><td>Zone Authentication Key</td><td>Chave para gerar e validar MACs em mensagens entre zonas.</td></tr><tr><td><code>ZEK</code></td><td>Zone Encryption Key</td><td>Chave para encriptar dados gerais em transações.</td></tr><tr><td><code>BDK</code></td><td>Base Derivation Key</td><td>Chave-mestra DUKPT. Deriva chaves únicas de transação (UDK) nos terminais.</td></tr><tr><td><code>CVK</code></td><td>Card Verification Key</td><td>Chave usada na geração/validação de CVV/CVC.</td></tr><tr><td><code>DEK</code></td><td>Data Encryption Key</td><td>Chave genérica de criptografia de dados sensíveis (não-PIN).</td></tr><tr><td><code>KERG</code></td><td>EMV Key Encryption Key</td><td>Proteção de chaves EMV na emissão de cartões com chip.</td></tr></tbody></table>

***

### Tamanhos e Algoritmos (`keySizeType`)

O campo `keySizeType` (um único caractere) define em simultâneo o algoritmo e o tamanho da chave.

<table data-header-hidden="false" data-header-sticky><thead><tr><th>keySizeType</th><th>Algoritmo</th><th>Tamanho Efetivo</th><th>Comentário Prático</th></tr></thead><tbody><tr><td><code>S</code></td><td>DES <em>single length</em></td><td>64 bits (56 + paridade)</td><td>Legado. Vulnerável a <em>brute force</em>; não recomendado para novas chaves.</td></tr><tr><td><code>D</code></td><td>DES <em>double length</em></td><td>128 bits (112 + paridade)</td><td>Padrão tradicional (3DES). Aceite pela maioria das bandeiras.</td></tr><tr><td><code>T</code></td><td>DES <em>triple length</em></td><td>192 bits (168 + paridade)</td><td>Maior segurança em DES. Usado em chaves-mestras de longa duração.</td></tr><tr><td><code>A</code></td><td>AES-128</td><td>128 bits</td><td>Padrão moderno recomendado para novas integrações.</td></tr><tr><td><code>B</code></td><td>AES-192</td><td>192 bits</td><td>Pouco utilizado na prática comercial.</td></tr><tr><td><code>C</code></td><td>AES-256</td><td>256 bits</td><td>Maior nível de segurança AES disponível.</td></tr></tbody></table>

### Modos de Operação (`modeFlag`)

No endpoint `GenerateKey`, o campo `modeFlag` define se a chave será apenas gerada internamente, ou se será também exportada em simultâneo para uma contraparte .

<table data-header-hidden="false" data-header-sticky><thead><tr><th>modeFlag</th><th>Operação</th><th>Campos Extra Exigidos</th><th>Quando Usar</th></tr></thead><tbody><tr><td><code>0</code></td><td>Apenas gerar chave</td><td>-</td><td>Geração de chaves para uso estritamente interno (ex.: ZPK para validar PINs).</td></tr><tr><td><code>1</code></td><td>Gerar e Exportar sob ZMK/TMK</td><td><code>zmk_TMK_flag</code>, <code>zmk_TMK_keyId</code></td><td>Quando a chave será enviada de imediato a um parceiro. Evita invocar o endpoint <code>Export</code> separadamente .</td></tr><tr><td><code>A</code></td><td>Derivar chave</td><td>-</td><td>Esquemas que derivam chaves de uma chave-mãe (ex.: KSI/KSN derivado de BDK).</td></tr><tr><td><code>B</code></td><td>Derivar e Exportar</td><td><code>zmk_TMK_flag</code>, <code>zmk_TMK_keyId</code></td><td>Combinação dos cenários A e 1.</td></tr></tbody></table>

### Esquemas de Exportação (`export_scheme`)

Ao exportar chaves (no endpoint `ExportKey`), a API suporta três métodos de empacotamento. A escolha depende unicamente do formato que o sistema do seu parceiro consegue processar .

<table data-header-hidden="false" data-header-sticky><thead><tr><th>Esquema (export_scheme)</th><th>Padrão e Algoritmo</th><th>Comentário de Integração</th></tr></thead><tbody><tr><td><code>TR31</code></td><td>ASC X9 TR-31 (DES, 3DES, AES, HMAC)</td><td>Recomendado. Inclui MAC de integridade e metadados de uso. Exigido por bandeiras em novas integrações .</td></tr><tr><td><code>X917</code></td><td>ANSI X9.17 (Apenas DES/3DES)</td><td>Esquema legado. Não suporta AES nem validação de integridade. Usar apenas se a contraparte for um sistema legado.</td></tr><tr><td><code>TKBF</code></td><td>Thales Key Block Format (DES, AES, HMAC)</td><td>Formato proprietário. Útil se a contraparte também possuir um HSM Thales.</td></tr></tbody></table>

### Chaves Efêmeras (Tempo de Vida)

A plataforma Hop suporta chaves com tempo de vida útil limitado, ativadas ao definir o campo `is_ephemeral = true` nos endpoints de geração ou importação. O tempo em minutos é estipulado no campo `key_TTL_minutes` . Após expirarem, as chaves tornam-se automaticamente inutilizáveis.

Casos de uso ideais:

* Tokens de sessão para transações específicas.
* Testes em ambiente de homologação (evitando que chaves de teste fiquem acumuladas no banco).
* Rotação de segurança programada.

Todas as respostas de geração e importação devolverão o campo `retKeyTTLmin`, indicando os minutos restantes. Para chaves permanentes (`is_ephemeral = false` ou omitido), este valor retornará `0` .


---

# 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-key-manager/introducao-e-fundamentos.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.