> For the complete documentation index, see [llms.txt](https://ftcoders.first-tech.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://ftcoders.first-tech.com/landing-page/modulo-crypto/modos-de-operacao-e-retornos.md).

# 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

<table data-header-hidden="false" data-header-sticky><thead><tr><th>Código (modeEncFlag)</th><th>Modo</th><th>IV Obrigatório?</th><th>Característica Principal</th></tr></thead><tbody><tr><td><code>00</code></td><td>ECB</td><td>Não</td><td>Padrão se o campo for <code>null</code> ou ausente. Cada bloco é cifrado independentemente. Não recomendado para dados estruturados.</td></tr><tr><td><code>01</code></td><td>CBC</td><td>Sim</td><td>Encadeia blocos via XOR com o cifrado anterior. É o padrão de mercado para dados em repouso.</td></tr><tr><td><code>02</code></td><td>CFB8</td><td>Sim</td><td>Cifra o fluxo em janelas de 8 bits. Adequado para dados de comprimento arbitrário.</td></tr><tr><td><code>03</code></td><td>CFB64</td><td>Sim</td><td>Variante do CFB com janela de 64 bits.</td></tr></tbody></table>

#### 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

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

#### &#x20;`retMultiValue` por Endpoint

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

<table data-header-hidden="false" data-header-sticky><thead><tr><th>Endpoint</th><th>Posição [0]</th><th></th></tr></thead><tbody><tr><td><code>EncryptData</code></td><td><code>msgRespEncrypted</code> (Hexadecimal)</td><td><code>ivResp</code> (Hexadecimal). Retorna apenas nos modos <code>01</code>, <code>02</code> ou <code>03</code>.</td></tr><tr><td><code>DecryptData</code></td><td><code>msgRespDecrypted</code> (Hexadecimal)</td><td><code>ivResp</code> (Hexadecimal). Retorna apenas nos modos <code>01</code>, <code>02</code> ou <code>03</code>.</td></tr><tr><td><code>SuperDecryptData</code></td><td><em>Array</em> de <em>arrays</em> — Cada item do lote segue estritamente o formato de resposta do <code>DecryptData</code>.</td><td>-</td></tr><tr><td><code>GenerateMac</code></td><td><code>mac</code> gerado (Hexadecimal)</td><td><code>ivResp</code> — Apenas quando <code>macModeFlag</code> for <code>1</code> ou <code>2</code> (encadeamento multi-bloco).</td></tr><tr><td><code>ValidateMac</code></td><td>Confirmação do MAC (echo)</td><td><code>ivResp</code> — Apenas quando <code>macModeFlag</code> for <code>1</code> ou <code>2</code>.</td></tr></tbody></table>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://ftcoders.first-tech.com/landing-page/modulo-crypto/modos-de-operacao-e-retornos.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.