> 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/hop-kms/key-derivation/fluxo-transacional-dukpt.md).

# Fluxo transacional - DUKPT

Esta página detalha o fluxo completo de ponta a ponta da nossa arquitetura. O ciclo de vida do gerenciamento de chaves no HoP KMS v4 é dividido em duas fases distintas: Fase 1: Provisionamento (Inicialização do Dispositivo) e Fase 2: Transacional (Operação do Dispositivo).

### 1. Visão Geral das Fases

Para garantir a máxima proteção dos dados transacionais, dividimos a responsabilidade criptográfica entre o servidor seguro (KMS) e o dispositivo final de captura (mPOS/COTS)

1. FASE 1: PROVISIONAMENTO (Ocorre uma única vez): O HoP KMS gera e entrega a IKEY de forma segura ao cliente.
2. FASE 2: TRANSACIONAL (Ocorre a cada transação): O dispositivo deriva suas próprias chaves para cifrar dados e o servidor as re-deriva internamente para decifrar.

### 2. Fase 1: Provisionamento (Carga da IKEY)

Esta fase é executada quando o dispositivo de captura precisa ser inicializado ou quando o seu contador de transações do KSN atinge o limite máximo e uma nova semente criptográfica precisa ser injetada.

#### Diagrama de Sequência: Provisionamento Seguro

<figure><img src="/files/KwmSXRhbjFulTa5UA7ka" alt=""><figcaption></figcaption></figure>

#### Detalhamento dos Passos:

1. Solicitação do Terminal: O dispositivo de captura (mPOS) solicita sua semente criptográfica ao back-end da sua aplicação.
2. Preparação do Back-end: O seu back-end gera um par de chaves efêmeras ECC sob a curva P-521 (Privada $$d\_A$$ e Pública $$Q\_A$$).
3. Chamada ao KMS: O seu back-end envia uma requisição `POST` para o endpoint `/v4/keyDerivation` contendo a sua chave pública $$Q\_A$$, o KSN de inicialização do terminal e o alias da BDK a ser utilizada.
4. Segurança no KMS:
   * O KMS realiza o cálculo do acordo de chaves Diffie-Hellman (ECDH) para gerar a chave de criptografia de transporte (ZMK efêmera).
   * O KMS deriva a IKEY a partir da BDK e do KSN informados.
   * A IKEY é encapsulada em um Key Block TR-31 e cifrada com a ZMK efêmera.
   * O KMS gera uma assinatura digital (ECDSA) sobre o pacote para garantir que a resposta não seja alterada.
5. Decifração no Back-end: Seu back-end recebe a resposta, valida a assinatura do KMS, realiza o acordo ECDH localmente para obter a mesma ZMK efêmera, decifra o Key Block TR-31 e obtém a IKEY limpa.
6. Injeção no Dispositivo: Seu back-end transfere a IKEY e o KSN inicial para o dispositivo de captura através de um canal seguro local de injeção.

### 3. Fase 2: Fluxo Transacional (Operação Offline)

Uma vez provisionado com a IKEY e o KSN inicial, o dispositivo de captura (mPOS) não precisa mais consultar o HoP KMS para realizar transações. Ele é capaz de operar de forma autônoma. o HoP API é capaz de reconstruir a IKEY e validar o PIN/dado gerado pelo dispositivo mPOS - <https://ftcoders.first-tech.com/hop-api/modulo-pin/referencia-api-pin>

#### Diagrama de Sequência: Autorização de Transação

<figure><img src="/files/xzXmWCzicOmclFZy162O" alt=""><figcaption></figcaption></figure>

#### Detalhamento dos Passos:

1. Derivação no Terminal: No momento da transação, o dispositivo utiliza o algoritmo DUKPT interno para calcular a chave de transação específica (*Working Key*) usando a semente IKEY e o contador atual do KSN.
2. Criptografia do Payload: O dispositivo cifra o PIN ou os dados confidenciais do cartão com a chave recém-derivada e, em seguida, incrementa o contador do KSN, inutilizando a chave utilizada.
3. Envio ao Back-end: O dispositivo envia para o seu back-end os dados criptografados junto com o KSN utilizado naquela transação.
4. Descriptografia Segura: Ao receber a transação, o seu back-end envia o payload criptografado e o KSN para o HoP API.
5. Processamento no Hardware Seguro (HSM): O HSM do HoP API utiliza a BDK (que nunca saiu de lá) e o KSN recebido para recalcular exatamente a mesma chave usada pelo terminal naquela transação. O HSM decifra o payload ou valida o PIN dentro de sua memória segura e retorna apenas o resultado para o seu back-end.

> 📌 A Regra de Ouro do DUKPT Note que as chaves de transação (*Working Keys*) são geradas pelo terminal de um lado, reconstruídas pelo HSM do outro, e nunca trafegam em canais abertos nem são expostas ao servidor de aplicação. Isso garante a conformidade absoluta com as normas internacionais de segurança de pagamentos.


---

# 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/hop-kms/key-derivation/fluxo-transacional-dukpt.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.