Referência da API - KEY MANAGER

Esta secção detalha os três primeiros endpoints do módulo Key Manager, responsáveis por introduzir novas chaves no ambiente seguro do HSM: GenerateKey (criação do zero), ImportKey (receção de chaves de trabalho de parceiros) e ImportZMK (receção da chave-mestra de zona de um parceiro) .

Gerar chave

post

Gera uma nova chave criptográfica no HSM e a armazena no banco de dados. Retorna o keyId gerado em retValue e o KCV (Key Check Value) em retMultiValue[0].

Suporta geração simples (modeFlag: "0") ou geração com exportação simultânea sob ZMK/TMK (modeFlag: "1").

Quando is_ephemeral: true, a chave tem tempo de vida limitado definido por key_TTL_minutes.

Authorizations

AuthorizationstringRequired

Token JWT obtido via Auth0

Body

client_idinteger · int64 · min: 1Required

Identificador do cliente

Example: 42

keyNamestringRequired

Nome/tipo da chave a ser gerada (ex ZEK, ZPK, ZMK, TMK, BDK)

Example: ZEK

keySizeTypestringRequired

Tamanho/tipo da chave:

S Single DES (64 bits)
D Double DES (128 bits)
T Triple DES (192 bits)
A AES-128
B AES-192
C AES-256

Example: S

modeFlagstring · enumRequired

Modo de operacao:

0 Gerar chave
1 Gerar chave e exportar sob ZMK/TMK
A Derivar chave
B Derivar chave e exportar sob ZMK/TMK

Example: 0Possible values:

zmk_TMK_flagstring · nullableOptional

Flag da ZMK/TMK, obrigatorio quando modeFlag 1 ou B

zmk_TMK_keyIdstring · nullableOptional

Alias da ZMK/TMK, obrigatorio quando modeFlag 1 ou B

is_ephemeralbooleanOptional

Se true, a chave tera tempo de vida limitado por key_TTL_minutes

Example: true

key_TTL_minutesinteger · nullableOptional

Tempo de vida da chave em minutos, obrigatorio quando is_ephemeral true

Example: 1440

Responses

200

Operação realizada com sucesso

application/json

retCodeintegerOptional

Codigo de retorno. 0 = sucesso, outros valores indicam erro

Example: 0

retDescriptionstringOptional

Descricao do resultado

Example: No error

retMultiValuestring[] · nullableOptional

Array com valores adicionais, retMultiValue[0] contem o KCV da chave gerada/importada

retValidbooleanOptional

Indica se a operacao foi bem-sucedida

Example: true

retValuestringOptional

KeyId gerado/importado no banco de dados

Example: client-4-key-id-XXX-ZEK

retKeyTTLminintegerOptional

Tempo de vida da chave em minutos (0 = sem expiracao)

Example: 1440

400

Requisição inválida

application/json

401

Não autorizado — token Bearer ausente ou inválido

404

Chave não encontrada no banco de dados

application/json

500

Erro interno do servidor

application/json

post/v4/PayShieldKeyManager/GenerateKey

POST /v4/PayShieldKeyManager/GenerateKey HTTP/1.1
Host: apivin.first-tech.net
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 149

{
  "client_id": 42,
  "keyName": "ZEK",
  "keySizeType": "S",
  "modeFlag": "0",
  "zmk_TMK_flag": null,
  "zmk_TMK_keyId": null,
  "is_ephemeral": true,
  "key_TTL_minutes": 1440
}

{
  "retCode": 0,
  "retDescription": "No error",
  "retMultiValue": [
    "6DA9EB"
  ],
  "retValid": true,
  "retValue": "client-4-key-id-XXX-ZEK",
  "retKeyTTLmin": 1440
}

O papel crítico do KCV (Key Check Value) Observe que o valor "6DA9EB" é retornado no retMultiValue[0]. Este é o KCV: um hash curto de 6 dígitos hexadecimais que serve como impressão digital da chave. É utilizado para confirmar com a contraparte que ambos possuem exatamente a mesma chave, sem nunca revelar a chave em si . Registe sempre o KCV junto com o keyId nos seus logs de auditoria.

Importar chave sob ZMK

post

Importa uma chave criptográfica que está criptografada sob uma ZMK (Zone Master Key). A chave é descriptografada pelo HSM e re-criptografada sob o LMK, sendo armazenada no banco de dados. Retorna o keyId gerado em retValue e o KCV em retMultiValue[0].

Quando is_ephemeral: true, a chave tem tempo de vida limitado definido por key_TTL_minutes.

Authorizations

AuthorizationstringRequired

Token JWT obtido via Auth0

Body

client_idinteger · int64 · min: 1Required

Identificador do cliente

Example: 42

keyNamestringRequired

Nome/tipo da chave a ser importada (ex ZEK, ZPK, TMK)

Example: ZEK

keySizeTypestringRequired

Tamanho/tipo da chave:

S Single DES
D Double DES
T Triple DES
A AES-128
B AES-192
C AES-256

Example: S

key_under_ZMK_to_importstringRequired

Chave criptografada sob a ZMK a ser importada (formato Key Block ou X9.17)

Example: XC16C32C5XXXXXX740B3C5EF95C3FCCF6

ZMK_keyIdstringRequired

Alias/identificador da ZMK no banco de dados

Example: client-4-key-id-XXX-ZMK

is_ephemeralbooleanOptional

Se true, a chave tera tempo de vida limitado por key_TTL_minutes

Example: true

key_TTL_minutesinteger · nullableOptional

Tempo de vida da chave em minutos, obrigatorio quando is_ephemeral true

Example: 1440

Responses

200

Operação realizada com sucesso

application/json

retCodeintegerOptional

Codigo de retorno. 0 = sucesso, outros valores indicam erro

Example: 0

retDescriptionstringOptional

Descricao do resultado

Example: No error

retMultiValuestring[] · nullableOptional

Array com valores adicionais, retMultiValue[0] contem o KCV da chave gerada/importada

retValidbooleanOptional

Indica se a operacao foi bem-sucedida

Example: true

retValuestringOptional

KeyId gerado/importado no banco de dados

Example: client-4-key-id-XXX-ZEK

retKeyTTLminintegerOptional

Tempo de vida da chave em minutos (0 = sem expiracao)

Example: 1440

400

Requisição inválida

application/json

401

Não autorizado — token Bearer ausente ou inválido

404

Chave não encontrada no banco de dados

application/json

500

Erro interno do servidor

application/json

post/v4/PayShieldKeyManager/ImportKey

POST /v4/PayShieldKeyManager/ImportKey HTTP/1.1
Host: apivin.first-tech.net
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 193

{
  "client_id": 42,
  "keyName": "ZEK",
  "keySizeType": "S",
  "key_under_ZMK_to_import": "XC16C32C5XXXXXX740B3C5EF95C3FCCF6",
  "ZMK_keyId": "client-4-key-id-XXX-ZMK",
  "is_ephemeral": true,
  "key_TTL_minutes": 1440
}

{
  "retCode": 0,
  "retDescription": "No error",
  "retMultiValue": [
    "6DA9EB"
  ],
  "retValid": true,
  "retValue": "client-4-key-id-XXX-ZEK",
  "retKeyTTLmin": 1440
}

Importar ZMK (Zone Master Key)

post

Importa uma ZMK (Zone Master Key) em formato Key Block Thales para o HSM. A ZMK é validada pelo KCV informado e armazenada no banco de dados. Retorna o keyId gerado em retValue e o KCV em retMultiValue[0].

O campo keyZMK deve estar no formato Key Block Thales (ex: S1009652TB00S0001...). O campo kcv deve ter exatamente 6 caracteres hexadecimais.

Authorizations

AuthorizationstringRequired

Token JWT obtido via Auth0

Body

client_idinteger · int64 · min: 1Required

Identificador do cliente

Example: 42

kcvstring · min: 6 · max: 6Required

Key Check Value da ZMK (exatamente 6 caracteres hexadecimais)

Example: 7BBC57

keyZMKstringRequired

ZMK em formato Key Block Thales

Example: S1009652TB00S0001575416528B0000000000470D91B8AA5AA45876481BB53C57F6E95C3570298E7E851B010C0065335A

Responses

200

Operação realizada com sucesso

application/json

retCodeintegerOptional

Codigo de retorno. 0 = sucesso, outros valores indicam erro

Example: 0

retDescriptionstringOptional

Descricao do resultado

Example: No error

retMultiValuestring[] · nullableOptional

Array com valores adicionais, retMultiValue[0] contem o KCV da chave gerada/importada

retValidbooleanOptional

Indica se a operacao foi bem-sucedida

Example: true

retValuestringOptional

KeyId gerado/importado no banco de dados

Example: client-4-key-id-XXX-ZEK

retKeyTTLminintegerOptional

Tempo de vida da chave em minutos (0 = sem expiracao)

Example: 1440

400

Requisição inválida

application/json

401

Não autorizado — token Bearer ausente ou inválido

500

Erro interno do servidor

application/json

post/v4/PayShieldKeyManager/ImportZMK

POST /v4/PayShieldKeyManager/ImportZMK HTTP/1.1
Host: apivin.first-tech.net
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 140

{
  "client_id": 42,
  "kcv": "7BBC57",
  "keyZMK": "S1009652TB00S0001575416528B0000000000470D91B8AA5AA45876481BB53C57F6E95C3570298E7E851B010C0065335A"
}

{
  "retCode": 0,
  "retDescription": "No error",
  "retMultiValue": [
    "7BBC57"
  ],
  "retValid": true,
  "retValue": "client-4-key-id-XXX-ZMK",
  "retKeyTTLmin": 0
}

Por que o KCV é separado

O KCV não é extraído automaticamente do Key Block — ele precisa ser informado pela contraparte e validado contra o resultado da decifração interna no HSM. Se houver divergência, o HSM rejeita a importação (tipicamente com retCode 11). Isso protege contra adulterações da ZMK em trânsito ou erros de digitação.

O comportamento de expiração em ZMKs

Nas respostas de sucesso deste endpoint, observará que o campo retKeyTTLmin retorna sempre 0 (sem expiração). Motivo: As ZMKs tipicamente NÃO são efêmeras. São chaves-mestras de longa duração que garantem trocas contínuas com um parceiro. O endpoint não expõe a flag is_ephemeral; caso necessite de rotacionar a ZMK, o fluxo correto é importar uma nova (obtendo um novo keyId) e descontinuar a antiga .

Exportar chave sob ZMK

post

Exporta uma chave armazenada no HSM (criptografada sob LMK) para criptografia sob uma ZMK. Retorna a chave exportada em retMultiValue[0].

Suporta três esquemas de exportação:

X917: Formato X9.17 (DES/3DES apenas)
TR31: Formato TR-31 Key Block
TKBF: Thales Key Block Format

Authorizations

AuthorizationstringRequired

Token JWT obtido via Auth0

Body

client_idinteger · int64 · min: 1Required

Identificador do cliente

Example: 42

keyIdstringRequired

Alias/identificador da chave a ser exportada no banco de dados

Example: client-8-key-id-XXX-ZEK

ZMK_keyIdstringRequired

Alias/identificador da ZMK sob a qual a chave sera exportada

Example: client-8-key-id-XXX-ZMK

export_schemestring · enumRequired

Esquema de exportacao:

X917 Formato X9.17 (apenas DES/3DES)
TR31 Formato TR-31 Key Block
TKBF Thales Key Block Format

Example: X917Possible values:

Responses

200

Operação realizada com sucesso

application/json

retCodeintegerOptional

Codigo de retorno. 0 = sucesso, outros valores indicam erro

Example: 0

retValuestring · nullableOptional

Valor de retorno simples

retMultiValuestring[] · nullableOptional

Array com os valores de retorno da operacao

retValidbooleanOptional

Indica se a operacao foi bem-sucedida

Example: true

retDescriptionstringOptional

Descricao do resultado

Example: No error

400

Requisição inválida

application/json

401

Não autorizado — token Bearer ausente ou inválido

404

Chave não encontrada no banco de dados

application/json

500

Erro interno do servidor

application/json

post/v4/PayShieldKeyManager/ExportKey

POST /v4/PayShieldKeyManager/ExportKey HTTP/1.1
Host: apivin.first-tech.net
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 111

{
  "client_id": 42,
  "keyId": "client-8-key-id-XXX-ZEK",
  "ZMK_keyId": "client-8-key-id-XXX-ZMK",
  "export_scheme": "X917"
}

{
  "retCode": 0,
  "retDescription": "No error",
  "retMultiValue": [
    "XC16C32C5XXXXXX740B3C5EF95C3FCCF6"
  ],
  "retValid": true,
  "retValue": ""
}

Traduzir chave entre LMKs

post

Traduz uma chave de criptografia sob um LMK antigo para criptografia sob o LMK atual. Utilizado em processos de migração de LMK. Retorna a chave re-criptografada sob o novo LMK em retValue (formato Key Block Thales).

O campo OldKey deve estar no formato Key Block Thales criptografado sob o LMK antigo.

Authorizations

AuthorizationstringRequired

Token JWT obtido via Auth0

Body

client_idinteger · int64 · min: 1Required

Identificador do cliente

Example: 42

OldKeystringRequired

Chave em formato Key Block Thales criptografada sob o LMK antigo

Example: S1009652TB00S0001575416528B0000000000470D91B8AA3B845876481BB53C57F6E95C3570298E7E851B010C0065335A

Responses

200

Operação realizada com sucesso

application/json

retCodeintegerOptionalExample: 0

retValuestringOptionalExample: PIN Validated

retMultiValueany · nullableOptional

retValidbooleanOptionalExample: true

retDescriptionstringOptionalExample: OK

400

Requisição inválida

application/json

401

Não autorizado — token Bearer ausente ou inválido

500

Erro interno do servidor

application/json

post/v4/PayShieldKeyManager/TranslateLMK

POST /v4/PayShieldKeyManager/TranslateLMK HTTP/1.1
Host: apivin.first-tech.net
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 125

{
  "client_id": 42,
  "OldKey": "S1009652TB00S0001575416528B0000000000470D91B8AA3B845876481BB53C57F6E95C3570298E7E851B010C0065335A"
}

{
  "retCode": 0,
  "retDescription": "HSM Error: 00 - No error",
  "retMultiValue": null,
  "retValid": true,
  "retValue": "S1009652TB00S0001A4D018B8FB137ACD2E68FB88FA117F00D4F801E3811014D34D234F2EC5CD89743AC3B5279EF033DC9463BC9463BC"
}

PreviousArquitetura, Autenticação e Modelos NextIntegração e Exemplos Práticos

Last updated 3 months ago