EFT

Descrição detalhada

Operações para Transferência Eletrônica de Fundos.

EFT

As APIs do módulo EFT (Eletronic Funds Transfer) são destinadas às operações de autenticação e verificação de identidade de usuários em transações com cartões Visa e Mastercard.

A identidade do usuário de cartão normalmente pode ser verificada de duas formas:

1. assinatura manuscrita, comparada com um cartão de assinatura mantido pelo emissor de cartão;
2. através de um PIN (Personal Identification Number) informado pelo usuário; A verificação via PIN pode ser feita online, com uma validação feita pelo emissor do cartão, ou offline, usando um cartão com chip.

Os padrões adotados estão em conformidade com o Manual de Padrões de Tecnologia de Pagamentos da Visa (Payment Technology Standards Manual, October 2007).

De forma genérica, o processo de transferência de fundos com cartão, segue o fluxo da figura abaixo. Há vários atores envolvidos no processo. O portador do cartão (card holder) o apresenta ao lojista (Retailer/Merchant), a autenticidade do portador pode ser verificada através de um PIN, que o portador digita na estação do lojista (por exemplo um terminal tipo POS, Point of Sale). A partir daí o PIN é cifrado (é gerado um PIN Block) e os dados da transação são enviados para um prestador de serviços de pagamento eletrônicos, contratado pelo lojista (Acquirer), que por sua envia os dados para o esquema de cartão correspondente, conforme o brand do cartão usado pelo portador, e daí é enviado para o emissor do cartão, que tem os dados de identificação, crédito e outros a respeito do portador e mantém contrato com este para uso do serviço. Após analisar os dados da transação, quanto á cadastro, crédito e autenticação, entre outros, o emissor pode autorizar ou recusar a transação, e esta mensagem de resposta percorre o fluxo no sentido inverso.

--- title: Processo genérico de transferência eletrônica de fundos --- sequenceDiagram autonumber participant Portador participant Loja participant Rede participant Bandeira participant Banco Portador ->> Loja: Cartão/PIN/CVV activate Loja Loja ->> Rede: Dados
Transação deactivate Loja activate Rede Rede ->> Bandeira: Dados
Transação deactivate Rede activate Bandeira Bandeira ->> Banco: Dados
Transação deactivate Bandeira activate Banco Banco ->> Bandeira: $ deactivate Banco activate Bandeira Bandeira ->> Rede: $ deactivate Bandeira activate Rede Rede ->> Loja: $ deactivate Rede activate Loja Loja ->> Portador: Mercadorias/
Serviços deactivate Loja Banco -->> Portador: Débito Portador -->> Banco: $

Do ponto de vista das chaves de criptografia usadas no processo, o processo é mostrado na figura abaixo. Cada ator mantém suas próprias chaves, e sempre que uma mensagem criptografada precisa ir de um ator para outro, a criptografia deve ser traduzida, ou seja, deve ser usada a chave correspondente do ator que deverá fazer a decriptografia da mensagem.

--- title: Chaves criptográficas na transferência de fundos --- sequenceDiagram participant Portador participant Loja participant Rede participant Bandeira participant Banco destroy Portador Portador ->> Loja: Cartão/PIN/CVV destroy Loja Loja ->> Rede: PIN Block Note over Rede: HSM:
PIN Translation Note over Rede: ZCMK
AWK
... destroy Rede Rede ->> Bandeira: PIN Block Note over Bandeira: HSM:
PIN Translation Note over Bandeira: ZCMK
AWK
IWK
... destroy Bandeira Bandeira ->> Banco: PIN Block activate Banco Note over Banco: HSM:
PIN Block Verification
CVV Verification Note over Banco: ZCMK
IWK
CVK
PVK
... deactivate Banco

Variações ou simplificações do esquema acima podem ser usados, por exemplo quando a mesma entidade tem mais de um papel, ou há uma comunicação direta do prestador (acquirer) com o emissor (issuer), como pode acontecer em certas transações de débito em conta.

Observação

1. Cada chave criptográfica deve ser dedicada a apenas um aplicação, conforme determina o manual da Visa.
2. Os tamanhos informados dos parâmetros se referem aos dados; a aplicação deve garantir que o buffer passado tenha espaço suficiente para os dados e mais o caracter terminador.
3. O módulo EFT trabalha com tamanho de PIN de 4 (MIN_EFT_PIN_LEN) a 12 (MAX_EFT_PIN_LEN) dígitos.

Sobre o suporte ao algoritmos do protocolo 3-D Secure:

O HSM Dinamo implementa os algoritmos criptográficos que suportam o protocolo 3-D Secure, desenvolvido pela Visa. Os serviços Verified by Visa da Visa e Secure Code da Mastercard são oferecidos pelas bandeiras baseados neste protocolo. O HSM implementa os algoritmos criptográficos de verificação de cartão que dão suporte ao protocolo e aos serviços, permitindo ao usuário do HSM fazer a geração e a verificação dos códigos, CVC2 (Card Verification Code 2) e HMAC SHA1 no caso da Mastercard (Secure Payment Application Algorithm) e CAVV (Cardholder Authentication Verification Value, CVV2 com método ATN) no caso da Visa.

O HSM possui suporte aos mecanismos de autenticação CAP (Visa) e DPA (Mastercard).

O HSM fornece suporte ao ATM Remote Key Loading/Transport através de funcionalidades criptográficas baseadas em funções RSA e X.509.

A implementação do HSM está de acordo com os padrões definidos na documentação listada abaixo:

EMVCo

• Integrated Circuit Card Specifications for Payment Systems, Book 2, Security and Key Management v. 4.2, junho 2008
• EMV Card Personalization Specification, v. 1.1, julho 2007

Visa

• Payment Technology Standards Manual, outubro 2007
• Visa Certification Authority Public Keys for Visa Smart Debit/Credit (VSDC), fevereiro 2007
• Visa Smart Debit/Credit Certification Authority Technical Requirements v. 2.1, abril 2006
• 3-D Secure Functional Requirements Access Control Server v. 1.0.2, maio 2006
• Visa Integrated Circuit Card v. 1.4.0, outubro 2001

Mastercard

• M/Chip Lite 2.1 Card Application Specifications for Debit and Credit, abril 2003
• M/Chip 4 Version 1.1 Issuer Guide to Debit and Credit Parameter Management, janeiro 2007
• M/Chip 4 Version 1.1 Security & Key Management, junho 2006
• Public Key Infrastructure (PKI) — Certification Authority Interface Specification, janeiro 2005
• Public Key Infrastructure (PKI) — Certification Authority Member Procedures, janeiro 2006
• SPA Algorithm for the MasterCard Implementation of 3-D Secure v1.04, maio 2004

Elo

• ELO Chip Card, CCD Cryptographic Algorithms, s/ versão, s/ data.
• Manual da Autoridade Certificadora Elo - Guia do Emissor, versão 1.2, setembro 2011

JCB

• JCB IC Card Specification, v. 2.0, outubro 2012
• JCB CA Interface Guide, s/ versão, janeiro 2014
• JCB Key Guide, s/ versão, janeiro 2014

Outros

• ANSI X9.24 part 1, Retail Financial Services Symmetric Key Management Part 1: Using Symmetric Techniques
• ASC X9 TR 31-2018, Interoperable Secure Key Exchange Key Block Specification, April 15, 2018
• ASC X9 TR 34–2019, Interoperable Method for Distribution of Symmetric Keys using Asymmetric Techniques: Part 1 – Using Factoring-Based Public Key Cryptography Unilateral Key Transport, September 22, 2019
• IBM z/OS V1R9.0 Cryptographic Services ICSF Application Programmer's Guide (3624 PIN Formats and Algorithms)
• ISO/IEC 9797-1 Method 2, Information technology - Security techniques - Message Authentication Codes (MACs) - Part 1, 1999
• IDTECH USER MANUAL SecureMag Encrypted MagStripe Reader (80096504-001 RevL 06/19/14)

Mecanismos de CVV

Há três formas de geração e verificação de CVV (Card Verification Value) no HSM:

1. Card Verification Value (CVV), para transações com cartões de tarja magnética;
2. Card Verification Value 2 (CVV 2); para transações sem a presença física do cartão (via telefone, correios ou Internet, por exemplo);
3. Alternate Card Verification Value (iCVV), para transações com cartões de chip; O mecanismo de cálculo é o mesmo nas três formas, e a diferença está na forma de entrada dos dados pela aplicação.

A chave usada para os cálculos de geração e verificação de CVV é denominada CVK (Card Verification Key). Esta chave é interna ao HSM, a aplicação precisa apenas informar seu nome de chave (id). Fisicamente é uma chave 3DES de 112 bits, o que corresponde à duas chaves de DES de 56 bits.

A Figura abaixo ilustra os esquema para geração e verificação de CVV, iCVV e CVV2.

--- title: Geração de CVV / iCVV / CVV2 --- %%{ init: { 'flowchart': { 'curve': 'basis' } } }%% flowchart TB PAN[PAN] Service[Código de serviço / 99/ 000] Data[Data de expiração] CVKid[CVK id] H[\"HSM: CVK (3DES 112)"/] cvv((CVV)) icvv((iCVV)) cvv2((CVV 2)) PAN --> H Service --> H Data --> H CVKid --> H H --> cvv H --> icvv H --> cvv2

Mecanismos de PIN

O HSM trabalha com geração de PIN (Personal Identification Number) por mecanismo de derivação, a partir de uma chave interna, denominada PGK (PIN Generation Key). Esta forma de geração tem várias vantagens, principalmente em relação ao método de geração de PIN com valores aleatórios, pois dispensa o uso de um banco de dados para validação (com provável exposição de dados sigilosos) e ainda mantém tanto o processo de geração quanto de validação, mais seguros, já que são realizados internamente ao HSM.

O padrão utilizado na geração de PIN pelo HSM é o IBM 3624, com o emprego de offsets para permitir a troca de PIN pelo usuário ou pelo emissor do cartão. Para mitigar ataques de decimalização e verificação, o HSM emprega uma tabela de conversão interna, não exposta para a aplicação. Como fator de segurança adicional é empregado uma chave 3DES de 168 bits, ao invés de uma 3DES de 112 bits; não há interferência na operação do algoritmo, já que as chaves DES e 3DES utilizam blocos de entrada e saída do mesmo tamanho.

--- title: Geração de PIN por derivação --- %%{ init: { 'flowchart': { 'curve': 'basis' } } }%% flowchart TB PAN[PAN] InPIN[InPIN] Offset[offset] PGKid[PGK id] H[\"HSM: CVK (3DES 112)"/] r((PIN)) PAN --> H InPIN --> H Offset --> H PGKid --> H H --> r

Estão definidos três modos de geração de PIN por derivação:

1. a partir do PAN (Personal Account Number), do PIN de entrada (inPIN) e da PGK;
2. a partir de um PIN de entrada e da PGK, com o uso de um offset permite a troca do PIN pelo usuário;
3. a partir do PAN, da PGK e um PIN de entrada, com o uso de um offset permite a troca de PIN automática;

Não há tratamento para regras de negócio dos PIN gerados dentro do HSM, tal função deve ser exercida pela aplicação chamadora.

Os algoritmos para geração usando o padrão IBM 3624 são mostrados nos diagramas abaixo.

--- title: Algoritmo de Geração de PIN IBM 3624 --- %%{ init: { 'flowchart': { 'curve': 'basis' } } }%% flowchart TD Dado{{Dado de Validação}} PGK{{PGK}} Op3DES[\Operação 3DES/] Troca[Troca de dígito] Ajuste[Ajuste de tamanho] Pin((PIN)) Dado --> Op3DES PGK --> Op3DES Op3DES -- Tabela de decimalização interna --> Troca Troca -- PIN Intermediário --> Ajuste Ajuste --> Pin

Para permitir que o usuário (cardholder) selecione o próprio PIN, um PIN offset é usado no método IBM 3624, com isso duas novas entradas são necessárias, o PIN definido pelo usuário e um check de tamanho de 4 bits. A operação com offset é realizada após os passos do algoritmo IBM 3624, mostrado acima. Com isso o processo interno do HSM consegue realizar a validação do PIN, mesmo que o usuário defina um PIN diferente daquele gerado inicialmente pelo HSM.

--- title: Algoritmo de Geração de PIN IBM 3624 com offset --- %%{ init: { 'flowchart': { 'curve': 'basis' } } }%% flowchart TD Dado{{Dado de Validação}} PGK{{PGK}} Op3DES[\Operação 3DES/] Troca[Troca de dígito] Ajuste[Ajuste de tamanho] Sub[\"Subtração em módulo 10
(InPin -PIN)"/] OpOff[\Operação de offset no PIN/] Pin((PIN)) InPin{{"InPin
(PIN gerado pelo usuário)"}} Of{{"dado de offset
(4-bit)"}} Dado --> Op3DES PGK --> Op3DES Op3DES -- Tabela de decimalização interna --> Troca Troca -- PIN Intermediário --> Ajuste Ajuste --> Sub Sub --> OpOff OpOff --> Pin InPin --> Sub Of --> OpOff

As operações de tradução de PIN Block (PIN Block Translate) funcionam com duas chaves, uma de origem e uma de destino; há uma fase intermediária para compatibilizar o formato de entrada ao formato de saída, caso seja possível. Há certos formatos de blocos que não são interoperáveis, ou por ausência de dados para a conversão ou por restrição da norma.

O modo de tradução default do HSM implica na tradução do bloco de entrada para o formato ISO PIN Block Format 0. No modo de tradução automático, a conversão é realizada de forma opaca, convertendo do bloco com a chave de origem para o bloco com a chave de destino, sem análise do formato ou conteúdo do bloco.

--- title: Operação de PIN Translate --- %%{ init: { 'flowchart': { 'curve': 'basis' } } }%% flowchart TD blockin{{Bloco de entrada}} keyin{{Chave de entrada}} OpDES1[\DES/] Prep[Preparação] OpDES2[\DES/] keyout{{Chave de destino}} blockout{{Bloco da saída}} blockin --> OpDES1 keyin --> OpDES1 OpDES1 --> Prep Prep --> OpDES2 keyout --> OpDES2 OpDES2 --> blockout

Na verificação de um PIN Block ocorrem duas operações com chaves, primeiro o PIN Block é decifrado com a chave PTK (PIN Transport Key), do bloco do PIN decifrado, é extraído o PIN, e a partir daí é realizada a verificação de PIN usando a PGK (PIN Generation Key, a mesma chave utilizada para a geração original do PIN). Esta verificação pode ser feita com ou sem o uso de um offset; este PIN offset não faz parte do PIN Block e não é criptografado pela PTK. O formato de PIN Block esperado é o ISO PIN Block Format 0 (equivalente ao ANSI PIN Block Format 0 e ao VISA PIN Block Format 1).

--- title: Operação de Verificação de PIN Block --- %%{ init: { 'flowchart': { 'curve': 'basis' } } }%% flowchart TD pinblock{{PIN Block}} ptk{{PTK}} OpDES1[\DES/] Prep[PIN, PAN, ...] pin[PIN] pgk{{PGK}} off{{offset}} OpDES2[\3DES/] r((Result)) ptk --> OpDES1 pinblock --> OpDES1 OpDES1 --> Prep Prep --> pin pin --> OpDES2 pgk --> OpDES2 off --> OpDES2 OpDES2 --> r

Mecanismos de DUKPT

DUKPT (Derived Unique Key Per Transaction) é uma forma de utilizar chaves únicas por transação, derivadas a partir de uma chave fixa, sendo este processo definido na ANSI X9.24 part 1.

A KSN (Key Serial Number) é o identificador de uma chave de transação, sendo dividida em partes como: KSI (Key Set ID), TRSM (Tamper Resistant Security Module), identificador do POS (Point of Sale) também conhecido como DID (Device ID) e o CTR (Transaction Counter).

--- title: Geração chaves DUKPT --- sequenceDiagram participant hsm as HSM participant pos as PoS/ATM
Device Note over hsm: BDK activate hsm hsm ->> hsm: IPEK (Device Id) deactivate hsm hsm ->> pos: IPEK Note over pos: IPEK

O HSM utiliza as partes da KSN separadas em KSI e DID + CTR cada uma contendo 5 bytes.

Os passos do processo de utilização de DUKPT são, em cada ponta da comunicação:

No POS:

1. Previamente inicializado com uma IPEK derivada de uma BDK.
2. Gera (ou recupera de uma tabela de chaves futuras) a chave futura utilizando o DID e CTR.
3. Encripta o bloco necessário (Ex.: PIN Block).
4. Envia KSN + Bloco encriptado. KSN é composto de TRMS (ou DID), KSI e CTR.
5. Incrementa o CTR interno.

No HSM:

1. Recebe KSN + Bloco Encriptado.
2. Seleciona a BDK apropriada baseado na KSN recebida. KSN é composto de TRMS (ou DID), KSI e CTR.
3. Gera a IPEK baseado no BDK e KSN selecionados.
4. Utiliza a IPEK, o DID e o CTR contidos no KSN para gerar a chave de sessão.
5. Decripta o Bloco e faz o processamento necessário.
6. O POS tem uma chave IPEK (Initial Pin Encryption Key) derivada de uma BDK (Base Derivation Key). Esta BDK está armazenada dentro do HSM e é utilizada na regeração da IPEK do respectivo POS e então esta IPEK é utilizada na derivação das chaves únicas de transação deste POS.

--- title: Comunicação DUKPT entre o POS/ATM e o HSM --- sequenceDiagram participant pos as PoS/ATM
Device participant hsm as HSM Note over pos: IPEK activate pos pos ->> pos: KSI,CTR pos ->> pos: Chave de sessão pos ->> pos: Texto claro > bloco cifrado deactivate pos pos ->> hsm: bloco cifrado
TRSM (Device Id)
KSI
CTR activate hsm Note over hsm: BDK hsm ->> hsm: IPEK (Device Id) hsm ->> hsm: KSI,CTR hsm ->> hsm: Chave de sessão hsm ->> hsm: bloco cifrado > texto claro deactivate hsm

Key-wrapping TR-31

É um processo de wrapping/_unwrapping_ com proteção de confidencialidade e integridade para chaves e dados associados, definido no documento ASC X9 TR 31-2018.

KBPK (Key Block Protection Key) é a chave de derivação utilizada para derivar as chaves de encriptação e autenticação. Esta chave é utilizada apenas para derivação. Também conhecida como KWK (Key Wrapping Key). Armazenada no HSM.

KBEK (Key Block Encryption Key) é a chave derivada da KBPK e usada apenas para a encriptação do key klock. Gerada a cada operação de wrap/unwrap, não é armazenada de forma persistente no HSM.

KBAK (Key Block Authentication Key) é a chave derivada da KBPK e usada apenas para o cálculo do MAC do key klock. Gerada a cada operação de wrap/unwrap, não é armazenada de forma persistente no HSM.

KDID (Key Derivation Input Data) são os dados utilizados para a derivação das chaves KBEK e KBAK. Contém dados como: counter, key usage indicator, algorithm indicator e tamanho. Varia de acordo com o método de derivação utilizado, chave que será derivada e demais parâmetros.

A derivação das chaves KBEK e KBAK utiliza o CMAC tendo como entrada o Key Derivation Input Data (específico de cada chave derivada) e a chave KBPK.

--- title: Processo de derivação KBEK e KBAK --- %%{ init: { 'flowchart': { 'curve': 'basis' } } }%% flowchart TD kbekin("Key derivation
input data
KBEK") kbakin("Key derivation
input data
KBAK") cmac1([CMAC]) kbpk(KBPK) cmac2([CMAC]) kbek("Key Block
Encryption Key") kbak("Key Block
Authentication Key") kbekin --> cmac1 kbakin --> cmac2 cmac1 --> kbek cmac2 --> kbpk cmac2 --> kbak cmac1 --> kbpk

Key block contém os dados da chave exportada. Este bloco é divido em 3 partes:

1. KBH (Key Block Header) contém informações sobre a chave e o key block.

1. Os dados confidenciais que serão enviados/guardados. É encriptado com a chave KBEK. Os dados de entrada para a encriptação são: o tamanho da chave, a chave e o padding.

1. O MAC que que liga o KBH e o key block encriptado. É gerado utilizando a chave KBAK. Os dados de entrada para a operação de MAC são: o KBH, e os dados de entrada para a encriptação.

%%{init: { 'theme': 'dark' } }%% timeline title Processo de Geração do Key Block section KBH section Bloco Cifrado Inputs#58; : tamanho da chave : chave KBEK : padding section MAC Inputs#58; : KBH : tamanho da chave : chave KBAK : padding

Definições

• KSN: Key Serial Number
• KSI: Key Set ID
• TRSM: Tamper Resistant Security Module
• POS: Point of Sale
• CTR: Transaction Counter
• DID: Device ID
• BDK: Base Derivation Key
• IPEK: Initial Pin Encryption Key
• ATM: Automatic Teller Machine
• KBPK: Key Block Protection Key
• KBEK: Key Block Encryption Key
• KBAK: Key Block Authentication Key
• AESKW: AES Key Wrap
• TDKW: Tripple DES Key Wrap
• KWK: Key Wrapping Key
• KBH: Key Block Header

Funções
String	generateDUKPT (byte[] baKSI, byte[] baDID_CTR, int dwParam) throws TacException
	Gera uma chave DUKPT dentro do HSM utilizando uma KSI (Key Serial Identification), um DID (Device ID) e um CTR (Transaction Counter) de uma mesma KSN (Key Serial Number).
String	generateDUKPTName (byte[] baKSI, byte[] baDID_CTR) throws TacException
	Gera o nome da DUKPT a partir de uma KSI e CTR informados.
String	generateBDKName (byte[] baKSI) throws TacException
	Gera o nome da BDK a partir de uma KSI (Key Serial Identification).
byte[]	translatePINBlock (String srcPEK, String dstPEK, int transBlockType, String PAN, byte[] inPINBlock) throws TacException
	Faz a tradução de um PIN Block, decriptando o bloco com uma chave e encriptando com outra.
byte[]	exportTR31 (String kbpk, String key, int usage, byte mode, byte export) throws TacException
	Exporta uma chave no formato TR-31 de acordo com o padrão ASC X9 TR 31-2018.
void	importTR31 (String kbpk, String key, int keyAttributes, byte[] keyBlock) throws TacException
	Importa uma chave no formato TR-31 de acordo com o padrão ASC X9 TR 31-2018.

Funções

generateDUKPT()

String generateDUKPT	(	byte[]	baKSI,
		byte[]	baDID_CTR,
		int	dwParam ) throws TacException

Gera uma chave DUKPT dentro do HSM utilizando uma KSI (Key Serial Identification), um DID (Device ID) e um CTR (Transaction Counter) de uma mesma KSN (Key Serial Number).

Parâmetros

baKSI	Buffer de tamanho TacNDJavaLib.MIN_KSI_LEN contendo o KSI (primeiros 05 bytes do KSN).
baDID_CTR	Buffer de tamanho TacNDJavaLib.MIN_CTR_LEN contendo o DID e CTR (últimos 05 bytes do KSN).
dwParam	Flags de operação de acordo com a tabela abaixo. Valor Significado TacNDJavaLib.NEW_DUKPT_MODE_DUK Gera uma chave DUK (Derived Unique Key) padrão de acordo com o manual ISO X9.24-1-2004. TacNDJavaLib.NEW_DUKPT_MODE_PEK Gera uma chave PEK (PIN Encryption Key) de acordo com o manual ISO X9.24-1-2004 A-1,A-6 aplicando o XOR da máscara 0000 0000 0000 FF00 nas partes da chave. TacNDJavaLib.NEW_DUKPT_MODE_MEK Gera uma chave MEK (MAC Encryption Key) de acordo com o manual ISO X9.24-1-2004 A-1,A-6 aplicando o XOR da máscara 0000 0000 0000 00FF nas partes da chave. TacNDJavaLib.NEW_DUKPT_MODE_DE Diversifica a chave gerada no formato Data Encryption. Aplica um XOR da máscara 0000 0000 00FF 0000 0000 0000 00FF 0000 sobre a chave DUKPT gerada, encripta a chave esquerda da DUKPT utilizando a DUKPT gerada e repete a encriptação com a chave direita. Após esta operação junta as partes esquerda e direita encriptadas para formar a Data Encryption Key. Como descrito em IDTECH USER MANUAL SecureMag Encrypted MagStripe Reader (80096504-001 RevL 06/19/14). Deve ser utilizada combinada (via operação OR) com uma das flags: TacNDJavaLib.NEW_DUKPT_MODE_DUK, TacNDJavaLib.NEW_DUKPT_MODE_PEK ou TacNDJavaLib.NEW_DUKPT_MODE_MEK TacNDJavaLib.NEW_DUKPT_MODE_EXP Gera uma chave DUKPT exportável. Esta é uma flag de atributo e deve ser utilizada combinada com outras flags. Utilizar apenas se especificamente necessário. TacNDJavaLib.NEW_DUKPT_MODE_TMP Gera uma chave DUKPT temporária. Esta é uma flag de atributo e deve ser utilizada combinada com outras flags.

Retorna

Retorna o nome da chave DUKPT gerada.

Exceções

TacException

generateDUKPTName()

String generateDUKPTName	(	byte[]	baKSI,
		byte[]	baDID_CTR ) throws TacException

Gera o nome da DUKPT a partir de uma KSI e CTR informados.

Parâmetros

baKSI	Buffer de tamanho TacNDJavaLib.MIN_KSI_LEN contendo o KSI (primeiros 05 bytes do KSN).
baDID_CTR	Buffer de tamanho TacNDJavaLib.MIN_CTR_LEN contendo o DID e CTR (últimos 05 bytes do KSN).

Retorna

Retorna o nome da chave DUKPT.

Exceções

TacException

generateBDKName()

String generateBDKName

(

byte[]

baKSI

)

throws TacException

Gera o nome da BDK a partir de uma KSI (Key Serial Identification).

Parâmetros

baKSI

Buffer de tamanho TacNDJavaLib.MIN_KSI_LEN contendo o KSI (primeiros 05 bytes do KSN).

Retorna

Retorna o nome da chave BDK.

Exceções

TacException

translatePINBlock()

byte[] translatePINBlock	(	String	srcPEK,
		String	dstPEK,
		int	transBlockType,
		String	PAN,
		byte[]	inPINBlock ) throws TacException

Faz a tradução de um PIN Block, decriptando o bloco com uma chave e encriptando com outra.

O formato de bloco de entrada é identificado automaticamente, e o formato de bloco de saída pode ser definido pelo chamador, desde que a troca do formato não seja de um PAN Unbound para um PAN Bound. Os formatos PAN Bound são aqueles que utilizam informação de PAN em sua composição. É possível, portanto, realizar tanto tradução de chaves quanto tradução de formato. O chamador pode fazer uma validação forçada do formato indicando para o formato de saída, o mesmo que está usando no PIN Block de entrada.

Parâmetros

srcPEK	Identificador da chave de decriptação dentro do HSM.
dstPEK	Identificador da chave de encriptação dentro do HSM.
transBlockType	Identificador do formato do bloco de saída. De acordo com a tabela abaixo. Valor Significado TacNDJavaLib.TP_TRANSLATE_TYPE_AUTO Faz uma conversão de forma opaca, traduzindo do bloco com a chave de origem para o bloco com a chave de destino, sem análise do formato ou conteúdo do bloco. PAN Bound: não se aplica. TacNDJavaLib.TP_TRANSLATE_TYPE_ISO_0 Utiliza o tipo de bloco ISO PIN Block Format 0 (equivalente ao ANSI PIN Block Format 0 e ao VISA PIN Block Format 1). PAN Bound: sim. TacNDJavaLib.TP_TRANSLATE_TYPE_ISO_1 Utiliza o tipo de bloco ISO PIN Block Format 1. PAN Bound: não. TacNDJavaLib.TP_TRANSLATE_TYPE_ISO_3 Utiliza o tipo de bloco ISO PIN Block Format 3. PAN Bound: sim. TacNDJavaLib.TP_TRANSLATE_TYPE_IBM_3624 Utilizada o tipo de bloco IBM 3624. Não implementado.
PAN	PAN (Primary Account Number).
inPINBlock	PIN Block de entrada. O buffer deve ter o tamanho de um PIN Block, TacNDJavaLib.DES_BLOCK (8 bytes)

Retorna

PIN block de saída.

Exceções

TacException

Anotações

No caso de uma conversão não opaca, ou seja de uma tradução de formato, se o formato do PIN Block de entrada não puder ser reconhecido, será retornado erro D_ERR_OPERATION_FAILED.
O método ISO PIN Block Format 2 não é implementado no HSM, pois este formato é destinado para ser usado na proteção do PIN quando é submetido da leitora do chip do cartão.

exportTR31()

byte[] exportTR31	(	String	kbpk,
		String	key,
		int	usage,
		byte	mode,
		byte	export ) throws TacException

Exporta uma chave no formato TR-31 de acordo com o padrão ASC X9 TR 31-2018.

Parâmetros

kbpk	Nome da chave KBPK (Key Block Protection Key) utilizada para derivar as chaves de encriptação e autenticação.
key	Nome da chave que será exportada do HSM.
usage	Identificador de uso de chave, como descrito no ASC X9 TR 31-2018 Seção A.5.1 tabela 6. As seguintes opções são aceitas. Valor Significado TacNDJavaLib.EFT_ME_TR31_EXP_USAGE_AUTO Define o identificador automaticamente. Os seguintes valores são utilizados: TacNDJavaLib.EFT_ME_TR31_EXP_USAGE_D0 para chave simétrica e TacNDJavaLib.EFT_ME_TR31_EXP_USAGE_D1 para chave assimétrica. TacNDJavaLib.EFT_ME_TR31_EXP_USAGE_B0 BDK Base Derivation Key TacNDJavaLib.EFT_ME_TR31_EXP_USAGE_B1 Initial DUKPT Key TacNDJavaLib.EFT_ME_TR31_EXP_USAGE_B2 Base Key Variant Key TacNDJavaLib.EFT_ME_TR31_EXP_USAGE_C0 CVK Card Verification Key TacNDJavaLib.EFT_ME_TR31_EXP_USAGE_D0 Symmetric Key for Data Encryption TacNDJavaLib.EFT_ME_TR31_EXP_USAGE_D1 Asymmetric Key for Data Encryption TacNDJavaLib.EFT_ME_TR31_EXP_USAGE_D2 Data Encryption Key for Decimalization Table TacNDJavaLib.EFT_ME_TR31_EXP_USAGE_E0 EMV/chip Issuer Master Key: Application cryptograms TacNDJavaLib.EFT_ME_TR31_EXP_USAGE_E1 EMV/chip Issuer Master Key: Secure Messaging for Confidentiality TacNDJavaLib.EFT_ME_TR31_EXP_USAGE_E2 EMV/chip Issuer Master Key: Secure Messaging for Integrity TacNDJavaLib.EFT_ME_TR31_EXP_USAGE_E3 EMV/chip Issuer Master Key: Data Authentication Code TacNDJavaLib.EFT_ME_TR31_EXP_USAGE_E4 EMV/chip Issuer Master Key: Dynamic Numbers TacNDJavaLib.EFT_ME_TR31_EXP_USAGE_E5 EMV/chip Issuer Master Key: Card Personalization TacNDJavaLib.EFT_ME_TR31_EXP_USAGE_E6 EMV/chip Issuer Master Key: Other TacNDJavaLib.EFT_ME_TR31_EXP_USAGE_I0 Initialization Vector (IV) TacNDJavaLib.EFT_ME_TR31_EXP_USAGE_K0 Key Encryption or wrapping TacNDJavaLib.EFT_ME_TR31_EXP_USAGE_K1 TR-31 Key Block Protection Key TacNDJavaLib.EFT_ME_TR31_EXP_USAGE_K2 TR-34 Asymmetric key TacNDJavaLib.EFT_ME_TR31_EXP_USAGE_K3 Asymmetric key for key agreement/key wrapping TacNDJavaLib.EFT_ME_TR31_EXP_USAGE_M0 ISO 16609 MAC algorithm 1 (using TDEA) TacNDJavaLib.EFT_ME_TR31_EXP_USAGE_M1 ISO 9797-1 MAC Algorithm 1 TacNDJavaLib.EFT_ME_TR31_EXP_USAGE_M2 ISO 9797-1 MAC Algorithm 2 TacNDJavaLib.EFT_ME_TR31_EXP_USAGE_M3 ISO 9797-1 MAC Algorithm 3 TacNDJavaLib.EFT_ME_TR31_EXP_USAGE_M4 ISO 9797-1 MAC Algorithm 4 TacNDJavaLib.EFT_ME_TR31_EXP_USAGE_M5 ISO 9797-1:1999 MAC Algorithm 5 TacNDJavaLib.EFT_ME_TR31_EXP_USAGE_M6 ISO 9797-1:2011 MAC Algorithm 5/CMAC TacNDJavaLib.EFT_ME_TR31_EXP_USAGE_M7 HMAC TacNDJavaLib.EFT_ME_TR31_EXP_USAGE_M8 ISO 9797-1:2011 MAC Algorithm 6 TacNDJavaLib.EFT_ME_TR31_EXP_USAGE_P0 PIN Encryption TacNDJavaLib.EFT_ME_TR31_EXP_USAGE_S0 Asymmetric key pair for digital signature TacNDJavaLib.EFT_ME_TR31_EXP_USAGE_S1 Asymmetric key pair, CA key TacNDJavaLib.EFT_ME_TR31_EXP_USAGE_S2 Asymmetric key pair, nonX9.24 key TacNDJavaLib.EFT_ME_TR31_EXP_USAGE_V0 PIN verification, KPV, other algorithm TacNDJavaLib.EFT_ME_TR31_EXP_USAGE_V1 PIN verification, IBM 3624 TacNDJavaLib.EFT_ME_TR31_EXP_USAGE_V2 PIN Verification, VISA PVV TacNDJavaLib.EFT_ME_TR31_EXP_USAGE_V3 PIN Verification, X9.132 algorithm 1 TacNDJavaLib.EFT_ME_TR31_EXP_USAGE_V4 PIN Verification, X9.132 algorithm 2
mode	Identificador do modo de uso da chave, como descrito no ASC X9 TR 31-2018 Seção A.5.3 tabela 8. As seguintes opções são aceitas. Valor Significado TacNDJavaLib.EFT_ME_TR31_EXP_MODE_AUTO Define o identificador de modo de uso automaticamente. O seguinte valor é utilizado TacNDJavaLib.EFT_ME_TR31_EXP_MODE_N. TacNDJavaLib.EFT_ME_TR31_EXP_MODE_B Ambos Encriptação & Decriptação / Wrap & Unwrap TacNDJavaLib.EFT_ME_TR31_EXP_MODE_C Ambos Geração & Verificação TacNDJavaLib.EFT_ME_TR31_EXP_MODE_D Decriptação / Unwrap Apenas TacNDJavaLib.EFT_ME_TR31_EXP_MODE_E Encriptação / Wrap Apenas TacNDJavaLib.EFT_ME_TR31_EXP_MODE_G Geração Apenas TacNDJavaLib.EFT_ME_TR31_EXP_MODE_N Sem restrições especiais (exceto as restrições definidas pelo identificador de uso da chave) TacNDJavaLib.EFT_ME_TR31_EXP_MODE_S Assinatura Apenas TacNDJavaLib.EFT_ME_TR31_EXP_MODE_T Ambos Assinatura & Decriptação TacNDJavaLib.EFT_ME_TR31_EXP_MODE_V Verificação Apenas TacNDJavaLib.EFT_ME_TR31_EXP_MODE_X Chave usada para derivar outra(s) chave(s) TacNDJavaLib.EFT_ME_TR31_EXP_MODE_Y Chave usada para criar variantes de chaves
export	Identificador de exportabilidade da chave, como descrito no ASC X9 TR 31-2018 Seção A.5.5 tabela 10. As seguintes opções são aceitas. Valor Significado TacNDJavaLib.EFT_ME_TR31_EXP_AUTO Define o identificador de exportabilidade automaticamente. O seguinte valor é utilizado TacNDJavaLib.EFT_ME_TR31_EXP_X9_24. TacNDJavaLib.EFT_ME_TR31_EXP_X9_24 Exportável sob uma KEK (Key Encryption Key) em um formato de encontro com o definido nos requisitos do X9.24 Partes 1 ou 2. TacNDJavaLib.EFT_ME_TR31_EXP_NON_EXPORTABLE Não exportável pelo recebedor do Key Block, ou local de armazenamento. Não impede a exportação de chaves derivadas de uma chave não exportável. TacNDJavaLib.EFT_ME_TR31_EXP_KEK_EXPORTABLE Sensível, Exportável sob uma KEK (Key Encryption Key) em um formato não necessariamente de acordo com os requisitos do X9.24 Partes 1 ou 2.

Retorna

key block

Exceções

TacException

Anotações

Essa API exporta uma chave usando os métodos de geração de key_block abaixo.

Algoritmo da KBPK	Método de exportação
3DES	5.3.2.1 Key Derivation Binding Method - TDEA
AES	5.3.2.3 Key Block Binding Method – AES

importTR31()

void importTR31	(	String	kbpk,
		String	key,
		int	keyAttributes,
		byte[]	keyBlock ) throws TacException

Importa uma chave no formato TR-31 de acordo com o padrão ASC X9 TR 31-2018.

Parâmetros

kbpk	Nome da chave KBPK (Key Block Protection Key) utilizada para derivar as chaves de encriptação e autenticação.
key	Nome da chave que será importada no HSM.
keyAttributes	Parâmetros adicionais da chave. Veja as opções no método createKey().
keyBlock	key block

Exceções

TacException

Anotações

Essa API importa chaves protegidas pelos métodos de geração do key_block.

Algoritmo da KBPK	Método
3DES	5.3.2.1 Key Derivation Binding Method - TDEA
AES	5.3.2.3 Key Block Binding Method – AES