Modos de Operação e Retornos

Para integrar com sucesso o módulo PayShield Crypto, é fundamental compreender como a API encadeia os dados durante a cifragem/decifragem e como os objetos de retorno são estruturados.

Modos de Operação (modeEncFlag)

Os modos de operação determinam como blocos sucessivos de dados são encadeados durante a cifragem ou decifragem. A escolha do modo impacta diretamente os requisitos de envio do Vetor de Inicialização (IV) e a resistência da criptografia a determinados ataques.

Tabela de Modos Suportados

Código (modeEncFlag)	Modo	IV Obrigatório?	Característica Principal
00	ECB	Não	Padrão se o campo for null ou ausente. Cada bloco é cifrado independentemente. Não recomendado para dados estruturados.
01	CBC	Sim	Encadeia blocos via XOR com o cifrado anterior. É o padrão de mercado para dados em repouso.
02	CFB8	Sim	Cifra o fluxo em janelas de 8 bits. Adequado para dados de comprimento arbitrário.
03	CFB64	Sim	Variante do CFB com janela de 64 bits.

Regras do Vetor de Inicialização (IV)

• Quando é obrigatório: Nos modos 01 (CBC), 02 (CFB8) e 03 (CFB64), o campo iv tem de ser enviado na requisição obrigatoriamente. No modo 00 (ECB), pode ser omitido ou enviado como null.

• Geração e Formato: O valor deve ser expresso em hexadecimal e tem de ser único por operação (nunca reutilize IVs entre transações com a mesma chave).

• Retorno em Cifragem: Nas operações de EncryptData que exigem IV, o vetor utilizado é refletido na resposta através do campo retMultiValue[1] (como ivResp). Esse valor retornado deve ser armazenado, pois será obrigatório como entrada na decifragem subsequente.

Uso de Chaves Derivadas (DUKPT)

Quando a chave referenciada pelo campo keyId for do tipo BDK (Base Derivation Key), a API passa a exigir parâmetros de DUKPT (Derived Unique Key Per Transaction). Neste cenário, os campos ksn_desc e ksn tornam-se obrigatórios na requisição. A plataforma Hop encarrega-se de derivar a chave de transação correspondente ao KSN informado e utilizá-la para a operação solicitada.

Mensagem de Retorno

Todos os endpoints da API Crypto retornam o mesmo "envelope" de resposta padronizado.

Estrutura Base do Response

Campo	Tipo	Significado
retCode	integer	Código numérico de retorno. 0 indica sucesso; valores diferentes de zero indicam erro (ver secção de códigos de erro).
retValue	string	Valor de retorno simples. Em operações Crypto, geralmente vem vazio (este campo é mais utilizado noutros módulos PayShield).
retMultiValue	array	Valores estruturados da operação. O conteúdo deste array varia de acordo com o endpoint acionado (ver tabela abaixo).
retValid	boolean	Indica se a operação foi bem-sucedida. No endpoint ValidateMac, indica também se o MAC analisado é válido.
retDesc	string	Descrição textual do resultado. Retorna "OK" em caso de sucesso; ou uma mensagem detalhada em caso de erro.

retMultiValue por Endpoint

O "coração" da resposta em criptografia reside no campo retMultiValue. Ele comporta-se de maneira diferente conforme a operação:

Endpoint	Posição [0]
EncryptData	msgRespEncrypted (Hexadecimal)	ivResp (Hexadecimal). Retorna apenas nos modos 01, 02 ou 03.
DecryptData	msgRespDecrypted (Hexadecimal)	ivResp (Hexadecimal). Retorna apenas nos modos 01, 02 ou 03.
SuperDecryptData	Array de arrays — Cada item do lote segue estritamente o formato de resposta do DecryptData.	-
GenerateMac	mac gerado (Hexadecimal)	ivResp — Apenas quando macModeFlag for 1 ou 2 (encadeamento multi-bloco).
ValidateMac	Confirmação do MAC (echo)	ivResp — Apenas quando macModeFlag for 1 ou 2.