Arquitetura, Autenticação e Modelos

Para consumir o módulo Key Manager de forma segura, a sua aplicação deve seguir os padrões de autenticação da plataforma Hop V4 e respeitar rigorosamente os schemas de entrada e saída.

Arquitetura e Autenticação

Base URL e Autenticação Bearer (JWT)

Todas as chamadas para o módulo Key Manager utilizam a seguinte URL base : https://apivin.first-tech.net/v4/PayShieldKeyManager/

A autenticação é feita através de um token Bearer (JWT) emitido pelo serviço Auth0. O token deve ser transportado no cabeçalho Authorization de todas as requisições :

HTTP
Authorization: Bearer <TOKEN_JWT>
Content-Type: application/json
Accept: */*

Segregação por client_id e keyId

• Identificação do Cliente (client_id): O client_id é o identificador numérico da sua empresa. As chaves ficam fisicamente segregadas por este ID no banco de dados do HSM — ou seja, duas chaves de clientes diferentes nunca interagem .

• Identificador da Chave (keyId): As respostas de geração e importação devolverão o alias da chave no campo retValue. Este alias deve ser guardado e utilizado nas chamadas futuras. O formato padrão segue a estrutura: client-{client_id}-key-id-XXX-TIPO.

Padrões de Resposta (Envelopes de Saída)

As respostas do módulo Key Manager seguem variações de envelope consoante o endpoint acionado.

ReturnImpKey

Utilizado em GenerateKey, ImportKey e ImportZMK (onde é necessário devolver a chave, o KCV e o tempo de vida).

Campo	Tipo	Descrição Técnica
retCode	integer	Código de retorno. 0 = sucesso; outros valores = erro (ver catálogo).
retDescription	string	Descrição textual do resultado.
retMultiValue	string[]	Array. A posição [0] contém o KCV (Key Check Value) da chave gerada/importada.
retValid	boolean	Indica se a operação global foi bem-sucedida.
retValue	string	O keyId gerado/importado no banco de dados (o alias da chave).
retKeyTTLmin	integer	Tempo de vida restante da chave em minutos. Retorna 0 se não tiver expiração.

ReturnMultiValue

Utilizado no ExportKey (onde a chave criptografada é devolvida no array).

Campo	Tipo	Descrição Técnica
retCode	integer	0 = sucesso.
retValue	string	Retorna uma string vazia neste endpoint.
retMultiValue	string[]	Array. A posição [0] contém a chave exportada (encriptada sob a ZMK de destino).
retValid	boolean	Indica sucesso.
retDescription	string	Descrição textual do resultado.

ReturnSingle e ReturnError

• ReturnSingle: Utilizado pelo TranslateLMK. A chave re-encriptada sob a LMK atual é devolvida isoladamente na variável retValue. O campo retMultiValue é null .

• ReturnError: Ocorre em respostas HTTP 400, 404 e 500. Mantém a base do ReturnSingle, mas com retValid em false, o código de erro em retCode e a mensagem explicativa em retDescription .

Schemas de Entrada (Modelos de Request)

Para simplificar a sua implementação, aqui estão os dicionários de dados exatos que cada endpoint espera receber no seu corpo (Body).

GenerateKeyInput

Para gerar novas chaves no HSM.

Campo	Tipo	Obrigatório	Descrição
client_id	integer	Sim	Identificador numérico do cliente.
keyName	string	Sim	Tipo da chave (ex.: ZEK, ZPK, ZMK, BDK).
keySizeType	string	Sim	Tamanho e algoritmo (ex.: S, D, A).
modeFlag	string	Sim	Modo da operação (0, 1, A, B).
zmk_TMK_flag	string	Condicional	Obrigatório se modeFlag for 1 ou B.
zmk_TMK_keyId	string	Condicional	Alias da ZMK/TMK destino. Obrigatório se modeFlag for 1 ou B.
is_ephemeral	boolean	Não	Se true, define a chave como efémera.
key_TTL_minutes	integer	Condicional	TTL em minutos. Obrigatório se is_ephemeral = true.

ImportKeyInput

Para importar uma chave protegida por uma ZMK.

Campo	Tipo	Obrigatório	Descrição
client_id	integer	Sim	Identificador numérico do cliente.
keyName	string	Sim	Tipo da chave a importar.
keySizeType	string	Sim	Tamanho e algoritmo.
key_under_ZMK_to_import	string	Sim	Chave criptografada sob ZMK (Formato Key Block ou X9.17).
ZMK_keyId	string	Sim	Alias da ZMK base que decifrará o pacote.
(Campos efêmeros)	-	-	Aceita is_ephemeral e key_TTL_minutes.

ImportZMKInput

Para importar uma ZMK base em formato Key Block.

Campo	Tipo	Obrigatório	Descrição
client_id	integer	Sim	Identificador numérico do cliente.
kcv	string	Sim	KCV de validação (exatamente 6 caracteres hexadecimais).
keyZMK	string	Sim	A ZMK em formato Key Block Thales puro.

ExportKeyInput

Para exportar uma chave para um parceiro.

Campo	Tipo	Obrigatório	Descrição
client_id	integer	Sim	Identificador numérico do cliente.
keyId	string	Sim	Alias da chave que deseja exportar.
ZMK_keyId	string	Sim	Alias da ZMK que irá encriptar o pacote para envio.
export_scheme	string	Sim	Esquema de exportação (X917, TR31, TKBF).

TranslateLMKInput

Para uso em migrações (tradução de LMK).

Campo	Tipo	Obrigatório	Descrição
client_id	integer	Sim	Identificador numérico do cliente.
OldKey	string	Sim	Chave Key Block Thales encriptada sob a LMK antiga.