Introdução e Fundamentos

Introdução

O módulo PayShield Pan da plataforma Hop V4 constitui o núcleo de gestão criptográfica de PIN e PAN da First Tech. A API expõe operações para geração, tradução entre chaves de diferentes algoritmos (3DES e AES) e domínios (LMK e ZPK), além da validação e re-cifragem de PIN sob mudança de PAN.

Embora o módulo se denomine "Pan", a maioria dos seus endpoints opera sobre o PIN — sendo que apenas o TranslatePan e o TranslatePinPan envolvem a alteração efetiva do PAN. Este documento serve como referência técnica completa, detalhando os modelos de dados, a taxonomia de erros e os fluxos de integração para o ciclo de vida do PIN.

Público-alvo

Desenvolvedores encarregues da integração de aplicações ou hosts ao Hop V4 para operações de PIN e PAN.
Arquitetos de sistemas para avaliação de criptografia como serviço.
Equipas de segurança da informação e de operações responsáveis pela migração e ciclo de vida de cartões.

Pré-requisitos

Cliente devidamente provisionado na plataforma Hop V4 com client_id atribuído.
Chaves criptográficas (LMK, ZPK do emissor e ZPK do adquirente) cadastradas e associadas ao client_id.
Credenciais Auth0 (token JWT) válidas e conectividade autorizada para o endpoint apivin.first-tech.net.

Fundamentos

Conceitos-chave

Termo

Significado

LMK

Local Master Key. Chave-mestra do HSM da First Tech, utilizada para proteger PINs em repouso e como ponto de entrada/saída para traduções. Tipicamente AES.

ZPK

Zone PIN Key. Chave partilhada entre instituições (zona de confiança) entre adquirente, emissor, bandeira ou gráfica. Pode ser 3DES ou AES.

TPK

Terminal PIN Key. Chave que protege o PIN entre o terminal (POS, ATM) e o adquirente. Tratada como uma ZPK específica de canal.

PinBlock

Bloco padronizado que encapsula o PIN para transmissão segura. Suporta múltiplos formatos ISO e proprietários.

Embossing

Refere-se à tradução de LMK para ZPK destinada a um canal externo (gráfica, terminal).

Internalization

Tradução inversa: traz o PIN de uma ZPK externa para a LMK interna do emissor.

Princípio Operacional

Toda a operação de PIN no Hop V4 referencia as chaves através do seu alias (keyId), garantindo que o material criptográfico real nunca saia do HSM. Da mesma forma, os PINs em claro nunca trafegam pela rede; estão sempre encapsulados num PinBlock cifrado.

O HoP atua como um tradutor entre domínios: recebe um PinBlock cifrado por uma chave de origem, realiza a decifragem e a re-cifragem com a chave de destino dentro do ambiente seguro, e devolve o novo PinBlock ao solicitante.

Matriz de Operações

O módulo PAN suporta as traduções entre os domínios LMK e ZPK utilizando algoritmos AES e 3DES.

Tradução de PIN

Origem

Destino

Algoritmos

Endpoint

LMK

ZPK

AES → 3DES

PinEmbossing

LMK

ZPK

AES → AES

TranslatePinLmkToZpk

ZPK

LMK

3DES → AES

PinInternalization

ZPK

LMK

AES → AES

TranslatePinZpkToLmk

Geração, Tradução de PAN e Validação

Operação

Endpoint

Observação

Gerar PIN sob LMK

GeneratePin

Destinado a uso interno.

Gerar PIN sob ZPK

GeneratePinIssuerKey

Para envio à gráfica ou personalização.

Trocar PAN (Preservar PIN)

TranslatePan

Re-cifra o PIN para o novo PAN (reemissão).

Trocar PAN + Traduzir PIN

TranslatePinPan

Combina a troca de PAN com a tradução de chave.

Validar PIN

ValidatePinIssuerKey

Traduz e valida o PIN para autorização.

Flowchart de Decisão

O diagrama seguinte auxilia na escolha do endpoint adequado com base na operação e nas chaves envolvidas:

Formatos de PinBlock

A API utiliza duas convenções para identificar o formato do PinBlock, dependendo do endpoint acionado.

Códigos Thales (`pinBlockFmt`)

Utilizada nos endpoints PinEmbossing e PinInternalization.

Código

Padrão

Notas

ISO 9564-1 Format 0

Formato mais comum em transações ISO 8583.

ISO 9564-1 Format 1

Sem PAN no bloco.

03/04/05

ISO Format 2 / Proprietário

Formatos para cartões com chip ou variantes Thales.

47/48

ISO 9564-1 Format 4

O Formato 48 é exclusivo para algoritmos AES.

Índices Abreviados (`formatCode`)

Utilizada nos endpoints TranslatePinLmkToZpk, TranslatePinZpkToLmk, TranslatePan e TranslatePinPan.

formatCode

Código Thales

Padrão Equivalente

ISO 9564-1 Format 0.

Proprietário Thales.

ISO 9564-1 Format 4 (variante).

ISO 9564-1 Format 4 (padrão default).

Matriz de Compatibilidade

Formato

Suporte AES

Suporte 3DES

01-47

Sim

Não

O Formato 48 (ISO Format 4) requer obrigatoriamente chaves AES. Consequentemente, não é suportado como destino em operações que envolvam chaves 3DES, como no caso do PinEmbossing.

Modelo de Retorno

retCode

integer

0 indica sucesso; outros valores indicam erro.

retValue

string

Texto informativo (ex.: "PIN Generated").

retMultiValue

any

Resultado estruturado (ex.: o PinBlock gerado).

retValid

boolean

Sucesso da operação ou validade do PIN.

retDescription