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) .

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

---

Tamanhos e Algoritmos (keySizeType)

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

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

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 .

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

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 .

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

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 .