Key Manager

Endpoints do serviço ws-hop-api-keymanager

Key Manager Generate Key Module

post

Returns the KeyId generated by the HSM.

Authorizations

bearerAuth

AuthorizationstringRequired

Token JWT obtido via Auth0

Body

application/json

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

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

retDescriptionstringOptional

Descricao do resultado

Example: No error

retMultiValuestring[] · nullableOptional

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

retKeyTTLminintegerOptional

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

Example: 1440

400

Requisição inválida — campo obrigatório ausente ou formato incorreto

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

HTTPcURLJavaScriptPython

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

{
  "client_id": 99,
  "keyName": "ZEK",
  "keySizeType": "S",
  "modeFlag": "0",
  "zmk_TMK_flag": null,
  "zmk_TMK_keyId": null
}

{
  "retCode": 0,
  "retValid": true,
  "retValue": "client-99-key-id-XXXXX-ZEK",
  "retDescription": "HSM Error: 00 - No error",
  "retMultiValue": [
    "AB12DA"
  ]
}

Key Manager Import Key Module

post

Returns the KeyId generated from the imported key.

Authorizations

bearerAuth

AuthorizationstringRequired

Token JWT obtido via Auth0

Body

application/json

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

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

retDescriptionstringOptional

Descricao do resultado

Example: No error

retMultiValuestring[] · nullableOptional

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

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

HTTPcURLJavaScriptPython

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

{
  "client_id": 99,
  "keyName": "ZEK",
  "keySizeType": "S",
  "key_under_ZMK_to_import": "X1234567890ABCDEF1234567890ABCDEF",
  "ZMK_keyId": "client-99-key-id-XXXXX-ZMK"
}

{
  "retCode": 0,
  "retValid": true,
  "retValue": "client-99-key-id-XXXXX-ZEK",
  "retDescription": "HSM Error: 00 - No error",
  "retMultiValue": [
    "123BCA"
  ]
}

Key Manager Import ZMK Module

post

Authorizations

bearerAuth

AuthorizationstringRequired

Token JWT obtido via Auth0

Body

application/json

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

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

retDescriptionstringOptional

Descricao do resultado

Example: No error

retMultiValuestring[] · nullableOptional

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

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

HTTPcURLJavaScriptPython

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

{
  "client_id": 99,
  "kcv": "123ABC",
  "keyZMK": "S1009652TB00S0001575416528B0000000000470D91B8AA5AA45876481BB53C57F1FA5C3570298E7E123456789065335A"
}

{
  "retCode": 0,
  "retValid": true,
  "retValue": "client-99-key-id-XXXXX-ZEK",
  "retDescription": "HSM Error: 00 - No error",
  "retMultiValue": [
    "123ABC"
  ]
}

Key Manager Export Key Module

post

Authorizations

bearerAuth

AuthorizationstringRequired

Token JWT obtido via Auth0

Body

application/json

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

retValidbooleanOptional

Indica se a operacao foi bem-sucedida

Example: true

retValuestring · nullableOptional

Valor de retorno simples

retDescriptionstringOptional

Descricao do resultado

Example: No error

retMultiValuestring[] · nullableOptional

Array com os valores de retorno da operacao

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

HTTPcURLJavaScriptPython

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

{
  "client_id": 99,
  "keyId": "client-99-key-id-XXXXX-ZEK",
  "ZMK_keyId": "client-99-key-id-XXXXX-ZMK",
  "export_scheme": "TR31"
}

{
  "retCode": 0,
  "retValid": true,
  "retValue": "",
  "retDescription": "HSM Error: 00 - No error",
  "retMultiValue": [
    "RA0072D0TB00S00004AC8A51234567890123456789012345678900EA1311287BA42237FC7",
    "AB45DE"
  ]
}