Fundamentos e Criptografia

O módulo PIN da plataforma Hop V4 expõe operações REST seguras para a validação de PINs de portadores e para a tradução de PinBlocks entre diferentes chaves criptográficas. Toda operação ocorre em ambiente de Hardware Security Module (HSM) certificado PCI PIN, garantindo que o PIN nunca seja exposto em claro .

Regras de Ouro (PCI PIN)

Ao integrar com os endpoints deste módulo, as seguintes premissas arquiteturais são inegociáveis:

• Nunca exponha o PIN em claro: Os endpoints não retornam e não devem retornar o PIN decifrado.

• Cifragem de Ponta a Ponta: Chaves de PIN (TPK, ZPK, BDK, PVK) jamais circulam em claro.

• Não armazene PinBlocks em cache: O reaproveitamento de PinBlocks entre transações viola o padrão PCI PIN e falhará tecnicamente em esquemas de chaves dinâmicas (DUKPT) .

• Mascaramento de Logs: É estritamente proibido registrar os campos hPibBlock, hPinHost ou o PAN completo nos logs da sua aplicação .

---

Tipos de Chaves Suportadas

O módulo suporta operações em uma cadeia completa de aquisição, atuando como tradutor de chaves para adquirentes e como validador final para emissores .

Tipo	Nome Completo	Descrição e Uso
TPK	Terminal PIN Key	Chave injetada no terminal (maquininha). Cifra o PinBlock no momento em que o portador digita a senha.
ZPK	Zone PIN Key	Chave compartilhada entre zonas de segurança (ex: adquirente ↔ bandeira ↔ emissor). O PinBlock é traduzido entre ZPKs a cada fronteira de rede.
BDK	Base Derivation Key	Chave-mestra utilizada em ambientes DUKPT (Derived Unique Key Per Transaction). O HSM utiliza o BDK em conjunto com o KSN para derivar uma chave de sessão única por transação.
PVK	PIN Verification Key	Utilizada pelo emissor para gerar e validar o PVV (PIN Verification Value). O PIN é validado no HSM sem a necessidade de ser armazenado.

---

Formatos de PinBlock

O campo que recebe o código de formato no payload da API é grafado como pibBlockFmt. Certifique-se de manter esta grafia exata na sua integração; o uso de "pinBlockFmt" resultará em erro de requisição (HTTP 400).

Os seguintes valores de formato são aceitos pela API:

Formatos ISO 9564-1

Código (pibBlockFmt)	Norma e Formato	Características
01	ISO 9564-1 Formato 0	Bloco de 8 bytes. Padrão mais comum em transações com cartão. Construído com operação XOR entre o PIN e os últimos 12 dígitos do PAN.
02	ISO 9564-1 Formato 1	Bloco de 8 bytes com padding aleatório. Utilizado em cenários onde não há PAN disponível (ex: ATM offline).
03	ISO 9564-1 Formato 2	Bloco de 8 bytes sem operação XOR com o PAN. Uso restrito e tipicamente offline.
04	ISO 9564-1 Formato 3	Bloco de 8 bytes. Variação do formato 0, mas contendo padding aleatório adicional.
05	ISO 9564-1 Formato 4	Bloco de 16 bytes (128 bits) criptografado sob AES. Formato obrigatório em esquemas EMV modernos.

Formatos Proprietários

O módulo também oferece suporte nativo à validação e tradução de variantes proprietárias utilizadas na indústria:

• 34: Variante Proprietária 0x34.

• 35: Variante Proprietária 0x35.

• 41: Variante Proprietária 0x41.

• 42: Variante Proprietária 0x42.

• 47: Variante Proprietária 0x47.

• 48: Variante Proprietária 0x48.

Atenção à consistência do PAN: Nos formatos baseados em operação XOR (01, 04, 05), se o PAN enviado na requisição da API divergir do PAN utilizado pelo terminal no momento da criação do PinBlock, o PIN resultante será corrompido, gerando erro de "tamanho zero" (Código 88) ou recusa indevida da senha.