Schemas e Códigos de Erro

Esta secção detalha os modelos de objeto (schemas) utilizados para o envio de requisições e processamento de respostas, bem como a taxonomia completa dos erros técnicos que podem ser retornados pelo HSM ou pela camada de validação da API.

Modelos de Dados (Schemas)

Schemas de Entrada

Estes são os objetos JSON esperados no corpo (body) das requisições para cada endpoint.

ImportPublicKeyInput (Utilizado no endpoint Import):

Campo	Tipo	Obrigatório	Descrição
client_id	integer	Sim	Identificador numérico do cliente. Mínimo: 1.
publicKeyEncoding	integer	Sim	Regra de codificação da chave pública (1, 2 ou 3).
publicKey	string	Sim	Chave pública DER ASN.1 em hexadecimal.

ExportKeyInput (Utilizado no endpoint Export):

Campo	Tipo	Obrigatório	Descrição
client_id	integer	Sim	Identificador numérico do cliente.
keyId	string	Sim	Alias da chave simétrica DES/AES/HMAC a ser exportada.
padModeId	integer	Sim	Modo de padding (1 = PKCS#1 v1.5, 2 = OAEP).
mgfHashFunction	integer	Não	Função hash MGF. Obrigatório apenas se padModeId = 2.
publicKey	string	Sim	Chave pública em formato Key Block Thales (resultado do Import).
keyBlockType	integer	Sim	Tipo do Key Data Block (apenas 3 suportado).

Schemas de Saída

ReturnSingle (Resposta de Sucesso): Utilizado tanto no Import quanto no Export. O módulo RSA retorna sempre um único valor criptográfico por chamada .

Campo	Tipo	Obrigatório	Descrição
retCode	integer	Não	0 para sucesso. Outros valores indicam erro.
retValid	boolean	Não	Indica sucesso da operação.
retValue	string	Não	Chave importada ou exportada em formato hexadecimal.
retDescription	string	Não	Descrição textual do resultado.

ReturnError (Respostas HTTP 400, 404 e 500): Possui o mesmo formato do ReturnSingle, mas com a flag retValid definida como false e o retCode preenchido com o código específico da falha do HSM ou da API. A mensagem de detalhe é enviada no campo retDescription .

---

Catálogo de Códigos de Erro (retCode)

O módulo PayShield RSA possui um catálogo de erros extenso, refletindo o rigor das validações criptográficas e de formatação exigidas pelos padrões PCI HSM V3 . A coluna "Origem" ajuda a identificar se a recusa partiu da validação da API ou do próprio Hardware Security Module (HSM) .

Código	Significado	Origem	Ação Recomendada
01	Falha na verificação do MAC	HSM	Key Block Thales corrompido ou alterado após o Import. Refazer o Import e tentar novamente com o novo valor.
02	Falha na verificação do check value	HSM	A chave simétrica referenciada por keyId está corrompida na base de dados. Recadastrar a chave.
03	Tipo de codificação de chave pública inválido	HSM	Verificar se o publicKeyEncoding corresponde ao tipo real da chave enviada.
04 / 50	Estrutura DER ASN.1 mal formada	HSM	A estrutura de dados está incorreta. Reverificar o processo de geração da chave pública na origem.
05	Tipo de chave DES/AES inválido	HSM	A chave keyId não é do tipo suportado. Apenas chaves DES, AES ou HMAC são exportáveis.
06	Identificador de criptografia inválido	HSM	Combinação inválida de parâmetros criptográficos. Revisar o padModeId.
07	Identificador de modo de padding inválido	API	O padModeId está fora dos valores aceites (deve ser 1 ou 2).
08	Erro no Key Block HMAC	HSM	Falha ao tentar exportar chave HMAC devido a bloco interno inválido. Recadastrar a chave.
10	Erro de paridade na chave DES	HSM	A chave simétrica DES referenciada está corrompida. Recadastrar a chave.
34	Valor de identificador hash HMAC inválido	HSM	O identificador hash da chave HMAC não é reconhecido. Recadastrar a chave.
47	Algoritmo não licenciado	HSM	O HSM não possui a licença ativa para o algoritmo solicitado. Acionar suporte.
68	Comando desabilitado	HSM	A operação está bloqueada na configuração do HSM. Acionar suporte.
76	Erro no comprimento do Key Data Block	HSM	O tamanho do bloco da chave pública (publicKey) está incorreto.
81	Tipo de Key Data Block inválido	API	O keyBlockType está fora dos valores aceites (apenas 3 é suportado).
83	Erro no formato do Key Block	HSM	O publicKey enviado no Export NÃO está no formato Key Block Thales. Use o retValue retornado pelo Import.
84	Erro no check value do Key Block	HSM	O Key Block foi adulterado em trânsito. Refazer o Import.
85	Função MGF OAEP inválida	API	O mgfHashFunction foi enviado incorretamente num contexto PKCS#1 v1.5, ou o valor está fora do range aceite.
86	Função hash MGF OAEP inválida	API	O valor do mgfHashFunction não consta na lista aceita (1, 5, 6, 7, 8).
87 / 88	Erro no parâmetro OAEP	HSM	Parâmetros OAEP incompatíveis ou erro genérico. Validar acordo prévio de padding.
D3	Critérios PCI HSM V3 não atendidos	HSM	A chave não atende às regras de segurança PCI HSM V3 (ex: tamanho, uso ou algoritmo).
D4	Chave pública ECC inválida	HSM	A chave ECC não está no formato X9.62 uncompressed válido (aplicável quando publicKeyEncoding = 3).