Troubleshooting, Erros e Apêndices
Troubleshooting, Erros e Apêndices
Esta secção serve como o guia de referência operacional e de diagnóstico para a integração com o módulo Key Manager.
Catálogo de Códigos de Erro (retCode)
retCode)O catálogo de erros é partilhado entre todos os endpoints do módulo. A coluna "Origem" indica se o erro foi detetado pela camada de validação da API ou diretamente pelo HSM Thales.
-1
Erro interno
API
Erro genérico. O retDescription traz tipicamente "Internal error: <mensagem>". Abrir chamado com a First Tech.
01
Erro de paridade na chave (Aviso)
HSM
A chave gerada/importada tem um byte de paridade incorreto. Tipicamente é um warning (aviso).
04
Tipo de chave inválido
HSM
O valor enviado em keyName não é reconhecido. Verifique a lista de tipos suportados.
05
Flag de comprimento inválido
API
O keySizeType está fora dos valores aceites (S/D/T/A/B/C).
07
Tipo de ZKA Master Key inválido
HSM
O tipo da ZMK referenciada não corresponde ao esperado. Verifique zmk_TMK_keyId ou ZMK_keyId.
10
Erro de paridade na ZMK/TMK
HSM
A chave-mestra referenciada está corrompida no banco. Recadastrar via ImportZMK.
11
Erro de paridade na chave
HSM
A chave referenciada está corrompida. Em ImportZMK, indica KCV divergente (validar com a contraparte).
44
Migração não permitida
HSM
A operação (TranslateLMK) viola regras de Compliance PCI HSM V3. Contatar o suporte.
45
Tipo de chave de destino inválido
HSM
Em TranslateLMK: a chave de destino tem tipo incompatível.
68
Comando desabilitado
HSM
Operação desabilitada no HSM. Contatar o suporte.
137
Malformação da requisição
API
JSON malformado, tipo de dado errado ou combinação inválida (ex.: is_ephemeral = true sem key_TTL_minutes) .
155
Chave não encontrada
API
O keyId não existe ou pertence a outro client_id .
Guia de Troubleshooting
Sintomas comuns e resoluções para integrações iniciais :
HTTP 400 com retCode = 137
JSON malformado ou combinação inválida.
Validar o body contra o schema; conferir tipos numéricos vs strings.
HTTP 404 com retCode = 155 em Export/Import
O ZMK_keyId ou o keyId não existem.
Listar as chaves no banco para confirmar os aliases exatos.
HTTP 400 com retCode = 11 no ImportZMK
O KCV informado não bate com o KCV calculado pelo HSM após decifrar o Key Block.
Confirmar com a contraparte o KCV correto; verificar erro de transcrição.
HTTP 400 com retCode = 07 no GenerateKey (modeFlag=1)
O zmk_TMK_keyId aponta para uma chave que não é do tipo ZMK ou TMK.
Confirmar que o alias passado corresponde realmente a uma ZMK/TMK no banco.
Em ExportKey (scheme=X917), retCode = 04
Tentativa de exportar chave AES com esquema X9.17.
Trocar o export_scheme para TR31 ou TKBF (X9.17 só suporta DES).
Chave deixou de funcionar após horas
A chave foi gerada com is_ephemeral = true e expirou.
Se precisa de chave permanente, gere com is_ephemeral = false.
KCV difere do informado pela contraparte
Diferença na convenção de cálculo de KCV (ex.: Thales usa os primeiros 3 bytes de zeros encriptados).
Confirmar o algoritmo de KCV utilizado pela contraparte.
Apêndice A - TranslateLMK e a Migração Hop V3 → V4
TranslateLMK e a Migração Hop V3 → V4O endpoint TranslateLMK re-criptografa chaves entre ambientes (V3 para V4) . Abaixo estão os comportamentos técnicos esperados após uma tradução bem-sucedida:
keyId
Mantém o mesmo alias. O que muda é apenas o LMK interno que protege a chave.
KCV
Mantém o mesmo valor. O KCV é calculado sobre o material da chave em si, e não sobre a proteção LMK.
Consumo em Módulos
Continuam 100% funcionais imediatamente após a tradução (CVV, EMV, PIN, etc.).
Reversibilidade
A operação é tipicamente irreversível. Voltar ao LMK antigo exigiria nova chamada inversa, reforçando a importância da validação pós-migração.
Apêndice B - Matrizes de Combinações Válidas
B.1 keyName x keySizeType
keyName x keySizeTypeA matriz abaixo indica os tamanhos e algoritmos suportados por cada tipo de chave .
ZMK / TMK
-
Sim
Sim
Sim
-
Sim
ZPK / ZAK
-
Sim
-
Sim
-
Sim
ZEK / DEK
Sim
Sim
Sim
Sim
-
Sim
BDK
-
Sim
Sim
Sim
-
Sim
CVK / KERG
-
Sim
-
Sim
-
-
B.2 export_scheme x keySizeType
export_scheme x keySizeTypeCompatibilidade entre os formatos de exportação e os algoritmos :
X917
Sim
Não (Esquema exclusivamente DES)
TR31
Sim
Sim
TKBF
Sim
Sim
Apêndice C - Glossário
AES / DES
Advanced / Data Encryption Standard
Algoritmos de criptografia simétrica.
BDK / UDK
Base Derivation Key / Unique Derived Key
Chaves do esquema DUKPT para terminais POS.
HSM
Hardware Security Module
Dispositivo de alta segurança (Thales) que executa a criptografia.
KCV
Key Check Value
Hash curto (6 caracteres hex) que atua como impressão digital da chave.
Key Block
-
Estrutura proprietária (ou TR-31) que embrulha a chave com um MAC sob LMK.
LMK
Local Master Key
A chave-mestra interna do HSM.
ZMK / ZPK
Zone Master / PIN Key
Chaves-mestras e de trabalho para comunicação segura entre instituições.
Last updated