Fundamentos e Arquitetura

O módulo PayShield RSA da plataforma Hop V4 disponibiliza operações REST para a importação de chaves públicas (RSA e ECC) e a exportação segura de chaves simétricas (DES, AES, HMAC) protegidas por essas chaves públicas.

Este módulo é fundamental para fluxos de troca de chaves entre instituições, como em cerimónias de troca inicial de chaves entre adquirentes, emissores e bandeiras, ou na integração com parceiros que exijam o transporte seguro de chaves simétricas através de criptografia de chave pública.

Funcionamento do Módulo

O transporte de chaves sob chave pública permite que a instituição destinatária gere um par de chaves RSA, envie a parte pública e receba a chave simétrica criptografada, garantindo que apenas o detentor da chave privada correspondente consiga decifrá-la.

O fluxo implementado no Hop V4 ocorre em duas etapas obrigatórias:

1. Import: Recebe a chave pública em formato DER ASN.1, gera um MAC sobre ela utilizando a LMK do HSM e devolve a chave encapsulada num Key Block Thales. Este formato protege a chave pública contra adulterações após a importação.

2. Export: Recebe a referência (keyId) de uma chave simétrica e o Key Block Thales obtido no passo anterior, retornando a chave simétrica criptografada sob a chave pública.

⚠️ Sequência Obrigatória: Import → Export A chave pública utilizada como entrada no endpoint Export NÃO deve ser a chave bruta DER recebida da contraparte. Deve ser obrigatoriamente o resultado da operação Import (o Key Block Thales com MAC). O uso direto da chave DER resultará em erros de validação (código 02 ou 83).

---

Modos de Padding (RSA)

A criptografia RSA exige um esquema de preenchimento (padding) para garantir a segurança da operação. O Hop V4 suporta os dois esquemas padrão da indústria através do parâmetro padModeId:

padModeId	Esquema	Aplicação	Requer MGF?
1	PKCS#1 v1.5	Compatibilidade com sistemas legados ou parceiros que ainda não migraram para OAEP.	Não
2	PKCS#1 v2.2 OAEP	Padrão moderno recomendado. Mais resistente a ataques de oráculo de padding.	Sim

Funções Hash MGF (Apenas OAEP)

Ao utilizar o modo OAEP (padModeId = 2), o campo mgfHashFunction torna-se obrigatório para indicar a função hash utilizada no MGF1 (Mask Generation Function):

mgfHashFunction	Função Hash	Recomendação
1	SHA-1	Apenas para compatibilidade legada.
5	SHA-224	Pouco utilizada na prática.
6	SHA-256	Padrão recomendado para novas integrações.
7 / 8	SHA-384 / SHA-512	Níveis superiores de segurança (verificar compatibilidade).

---

Formatos de Chave Pública e Bloco de Saída

Codificação na Importação (publicKeyEncoding)

O parâmetro publicKeyEncoding no endpoint Import define a estrutura da chave pública DER ASN.1 recebida:

publicKeyEncoding	Formato	Tipo de Chave
1	DER ASN.1 RSA (INTEGER unsigned)	RSA (PKCS#1 ou X.509).
2	DER ASN.1 RSA (INTEGER 2's complement)	RSA (variação de codificação de módulo).
3	DER ASN.1 ECC X9.62 uncompressed	ECC (formato de ponto uncompressed, prefixo 0x04).

Tipo de Bloco na Exportação (keyBlockType)

O parâmetro keyBlockType define o formato do bloco de chave produzido. Atualmente, o único valor suportado em produção é o 3 (Unformatted Key Data Block).

---

Arquitetura e Padrão de Resposta

• Base URL: https://apivin.first-tech.net/v4/PayShieldRsa/.

• Autenticação: Exige token Bearer JWT enviado no cabeçalho Authorization de cada requisição.

• Identificação do Cliente: O campo client_id identifica o cliente, garantindo a segregação de chaves e histórico no HSM.

• Identificação da Chave (keyId): Referencia o alias da chave simétrica (DES, AES ou HMAC) previamente cadastrada no módulo Key Manager. O formato padrão é client-{client_id}-key-id-XXX-TIPO.

Estrutura de Resposta (ReturnSingle)

Todas as respostas do módulo RSA utilizam o envelope ReturnSingle, processando uma única chave por chamada:

Campo	Tipo	Descrição
retCode	integer	Código de retorno (0 para sucesso).
retValid	boolean	Indica o sucesso da operação.
retValue	string	Valor em hexadecimal (Key Block no Import; Chave criptografada no Export).
retDescription	string	Descrição textual do resultado (Ex.: "OK").