Introdução e Fundamentos

Módulo Crypto

O módulo PayShield Crypto da plataforma Hop V4 oferece um conjunto de operações criptográficas simétricas executadas integralmente dentro do HSM (Hardware Security Module) gerenciado pela First Tech. A principal premissa deste serviço é garantir que o material de chave nunca deixe a fronteira segura do hardware.

Este documento fornece ao integrador a referência técnica completa, englobando fundamentos, modelos de dados, fluxo de integração, casos de uso práticos e taxonomia de erros.

Público-Alvo e Pré-requisitos

Esta documentação é desenhada para:

• Desenvolvedores que integram aplicações ou hosts ao Hop V4.

• Arquitetos que avaliam o uso de criptografia gerenciada como serviço.

• Times de Segurança da Informação responsáveis por validar o desenho criptográfico da solução.

Pré-requisitos de Integração

Para consumir os endpoints descritos neste guia, certifique-se de que o seu ambiente cumpre os seguintes requisitos:

1. Cliente provisionado na plataforma Hop V4, com um client_id atribuído.

2. Pelo menos uma chave criptográfica cadastrada e associada ao seu client_id, com o respectivo alias (keyId) conhecido.

3. Credenciais Auth0 (token JWT) válidas para o ambiente de destino.

4. Conectividade de rede autorizada para o endpoint apivin.first-tech.net.

Fundamentos do PayShield Crypto

Operações Suportadas

O serviço expõe quatro famílias principais de operações criptográficas simétricas:

1. Cifragem de dados (EncryptData): Proteção de informações sensíveis para armazenamento seguro ou trânsito.

2. Decifragem de dados (DecryptData e SuperDecryptData): Recuperação do conteúdo original em texto claro (incluindo suporte a múltiplos blocos).

3. Geração de MAC (GenerateMac): Produção de um código de autenticação (Message Authentication Code) para garantir a integridade e autenticidade de mensagens.

4. Validação de MAC (ValidateMac): Verificação da integridade e autenticidade do código gerado.

Princípio Operacional e Algoritmos

Toda operação criptográfica atua sobre uma chave referenciada pelo seu keyId, que funciona como um alias armazenado no banco de dados gerenciado pela First Tech. O material criptográfico real nunca trafega pela API. A sua aplicação envia apenas o identificador da chave e os dados a serem processados; o HSM executa o cálculo e o resultado retorna em formato hexadecimal .

O algoritmo simétrico aplicado (como DES, 3DES ou AES) é determinado automaticamente pelo tipo da chave que foi provisionada. O integrador não precisa enviar o algoritmo no payload; o seu controle resume-se à escolha do modo de operação através do campo modeEncFlag

Modelo Padrão de Chamada

Para garantir consistência na integração, todos os endpoints do módulo Crypto seguem o mesmo contrato base:

• Método HTTP: POST.

• Autenticação: Bearer Token (JWT obtido via Auth0).

• Content-Type: application/json.

• Identificação do Tenant: Informada obrigatoriamente no campo client_id do corpo da requisição (body).

• Identificação da Chave: Informada no campo keyId do body.

• Resposta Padronizada: Os objetos de retorno sempre conterão os campos retCode, retValue, retMultiValue, retValid e retDesc.