Descrição detalhada

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

Estruturas de Dados
class	DinamoClient.PinComponents
	Classe que encapsula os componentes da geração de PIN. Mais...

Enumerações
enum	GenPINOperation : UInt32 { DEFAULT_PIN = DinamoApi.GP_DEFAULT_PIN , USER_DEF_PIN = DinamoApi.GP_USER_DEF_PIN , RANDOM_PIN = DinamoApi.GP_RANDOM_PIN }
	Opções de operação de PIN. Mais...

Funções
string	GenBDKName (byte[] pbKSI)
	Gera o nome da BDK a partir de uma KSI (Key Serial Identification).

string	GenBDKName (byte[] pbKSI, uint dwParam)
	Gera o nome da BDK a partir de uma KSI (Key Serial Identification).

string	GenDUKPT (byte[] pbKSI, byte[] pbDID_CTR, uint dwParam)
	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	GenCVV (string keyId, string pan, string expirationDate, string serviceCode)
	Gera um CVV (Card Verification Value), CVV2 ou iCVV utilizando uma chave dentro do HSM. Esta API também pode ser usada para a geração dos códigos de verificação de cartão que suportam o protocolo 3-D Secure.No caso da Visa o serviço que implementa o protocolo é o Verified by Visa, e o HSM suporta o padrão CAVV (Cardholder Authentication Verification Value, que é o CVV2 com método ATN). No caso da Mastercard o protocolo 3-D Secure é implementado no serviço SecureCode, o HSM suporta os padrões CVC2(Card Verification Code 2) e HMAC SHA1.

bool	VerifyCVV (string keyId, string pan, string expirationDate, string serviceCode, string cvv)
	Verifica um CVV (Card Verification Value), , CVV2 ou iCVV utilizando uma chave dentro do HSM. A API também pode ser usada para a verificação dos códigos de verificação de cartão que suportam o protocolo 3-D Secure. Veja mais detalhes na API GenCVV().

PinComponents	GenPIN (string pgk, string pan, GenPINOperation operation, int pinLen, string inPin)
	Faz operações de geração de PIN a partir dos dados de PAN (Personal Account Number) e nome de chave (PGK) informadas, com ou sem uso de offset.

bool	VerifyPINBlock (string ptk, string pgk, string pan, string offset, byte[] pinblock)
	Verifica a validade de um PIN em um PIN Block. Primeiro o PIN é extraído do PIN Block com a chave PTK, e depois é feita sua verificação com a chave PGK, a mesma que foi usada para geração do PIN, com a função GenPIN().

byte[]	ExportTR31 (string kbpk, string key, EftExportUsage usage, EftExportMode mode, EftExportExpType exp)
	Exporta uma chave no formato TR-31 de acordo com o padrão ASC X9 TR 31-2018.

void	ImportTR31 (string kbpk, string key, bool isExportable, bool isTemporary, byte[] keyBlock)
	Importa uma chave no formato TR-31 de acordo com o padrão ASC X9 TR 31-2018.

Enumerações

◆ GenPINOperation

enum GenPINOperation : UInt32

Opções de operação de PIN.

Enumeradores
DEFAULT_PIN
USER_DEF_PIN
RANDOM_PIN

Exemplos: eft_gen_pin.cs.

Funções

◆ GenBDKName() [1/2]

string GenBDKName ( byte[] pbKSI )

inline

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

Parâmetros

pbKSI Buffer de tamanho MIN_KSI_LEN contendo o KSI.

Retorna: O nome de chave BDK gerada a partir do KSI informado em pbKSI.

Exceções

DinamoException Lança exceção em caso de erro.

Exemplos: dukpt.cs.

◆ GenBDKName() [2/2]

string GenBDKName	(	byte[]	pbKSI,
		uint	dwParam )

inline

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

Parâmetros

pbKSI	Buffer de tamanho MIN_KSI_LEN contendo o KSI.
dwParam	Reservado para uso futuro.

Retorna: O nome de chave BDK gerada a partir do KSI informado em pbKSI.

Exceções

DinamoException Lança exceção em caso de erro.

◆ GenDUKPT()

string GenDUKPT	(	byte[]	pbKSI,
		byte[]	pbDID_CTR,
		uint	dwParam )

inline

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

pbKSI	Buffer de tamanho MIN_KSI_LEN contendo o KSI.
pbDID_CTR	Buffer de tamanho MIN_CTR_LEN contendo o DID e CTR (últimos 05 bytes do KSN).
dwParam	Flags de operação de acordo com a tabela abaixo. NEW_DUKPT_MODE_DUK : Gera uma chave DUK (Derived Unique Key) padrão de acordo com o manual ISO X9.24-1-2004. NEW_DUKPT_MODE_PEK : Gera uma chave PEK (PIN Encryption Key) de acordo com o manual ISO X9.24-1-2004 A aplicando o XOR da máscara 0000 0000 0000 FF00 nas partes da chave. NEW_DUKPT_MODE_MEK : Gera uma chave MEK (MAC Encryption Key) de acordo com o manual ISO X9.24-1-2004 A aplicando o XOR da máscara 0000 0000 0000 00FF nas partes da chave. 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: NEW_DUKPT_MODE_DUK, NEW_DUKPT_MODE_PEK ou NEW_DUKPT_MODE_MEK 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. NEW_DUKPT_MODE_TMP : Gera uma chave DUKPT temporária. Esta é uma flag de atributo e deve ser utilizada combinada com outras flags. NEW_DUKPT_MODE_IPEK : Gera uma chave IPEK (Initially Loaded PIN Entry Device Key) de acordo com o manual ISO X9.24-1-2004 A-6.

Retorna: O nome de chave BDK gerada a partir do KSI informado em pbKSI.

Exceções

DinamoException Lança exceção em caso de erro.

Exemplos: dukpt.cs.

◆ GenCVV()

string GenCVV	(	string	keyId,
		string	pan,
		string	expirationDate,
		string	serviceCode )

inline

Gera um CVV (Card Verification Value), CVV2 ou iCVV utilizando uma chave dentro do HSM. Esta API também pode ser usada para a geração dos códigos de verificação de cartão que suportam o protocolo 3-D Secure.No caso da Visa o serviço que implementa o protocolo é o Verified by Visa, e o HSM suporta o padrão CAVV (Cardholder Authentication Verification Value, que é o CVV2 com método ATN). No caso da Mastercard o protocolo 3-D Secure é implementado no serviço SecureCode, o HSM suporta os padrões CVC2(Card Verification Code 2) e HMAC SHA1.

Parâmetros

keyId	Identificador da chave dentro do HSM. Este identificador não deve conter espaços ou caracteres especiais. Caracteres maiúsculos e minúsculos são diferenciados (case-sensitive). Esta chave é a CVK (Card Verification Key), uma chave 3DES de 112 bits, e deve ser a mesma que será usada para a verificação do CVV. Esta chave pode ser gerada internamente no HSM ou importada manualmente. Normalmente esta chave também é usada na Visa, enviada cifrada pela ZCMK (Zone Contro Master Key). Conforme determinado no manual da Visa, a chave 3DES 112 usada como CVK deve ser diferente da chave usada para geração e verificação de PIN e não deve ser usada para outras aplicações do emissor, com exceção do CVV2 e iCVV.
pan	PAN (Primary Account Number). Tamanho de de 12 a 19 caracteres. Para o cálculo de CVV, CVV2 e iCVV, conforme o padrão da Visa, no documento Payment Technology Standards Manual, de 2007, é independente do tamanho do PAN. Para o cálculo de CVC2, conforme o documento da Mastercard SPA Algorithm for the MasterCard Implementation of 3-D Secure – v1.04, o tamanho do PAN deve ser exatamente de 16 dígitos; quando for menor precisa se completado à esquerda com zeros, e quando for maior devem ser usados apenas os 16 dígitos mais à direita.
expirationDate	Data de expiração. Tamanho de 4 dígitos. Na geração de CVV e iCVV o formato deve ser YYMM. Na geração de CVV2 o formato deve ser MMYY. No cáculo de CVC2 este campo deve ser uma string terminada em zero com os 4 dígitos menos significativos do Transaction Sequence Number, contido no AVV (Accountholder Authentication Value) convertido no BCD decimal equivalente. Qualquer valor menor que 4 dígitos deve ser completado à esquerda com zeros até inteirar os 4 dígitos. Para mais detalhes consulte o documento da Mastercard SPA Algorithm for the MasterCard Implementation of 3-D Secure – v1.04. No cáculo de CAVV (CVV2 com o Método ATN), este campo deve ser uma string terminada em zero com os 4 dígitos menos significativos do ATN (Authentication Tracking Number). Para mais detalhes consulte o documento da Visa 3-D Secure Functional Requirements Access Control Server v. 1.0.2.
serviceCode	Service Code. Tamanho de 3 dígitos. Para a geração de iCVV (Alternate Card Verification Value), o Service Code deve ser 999. Para a geração de CVV 2, o Service Code deve ser 000. Para a geração de CVV tradicional, o Service Code normalmente é 101.

Retorna: O CVV gerado, com tamanho de 3 dígitos. O valor gerado pode também ser um CVV2 ou iCVV, conforme os valores informados de Service Code.

Exceções

DinamoException Lança exceção em caso de erro.

Anotações: A API também é compatível com o padrão da bandeira American Express.

Exemplos: eft_gen_verify_cvv.cs.

◆ VerifyCVV()

bool VerifyCVV	(	string	keyId,
		string	pan,
		string	expirationDate,
		string	serviceCode,
		string	cvv )

inline

Verifica um CVV (Card Verification Value), , CVV2 ou iCVV utilizando uma chave dentro do HSM. A API também pode ser usada para a verificação dos códigos de verificação de cartão que suportam o protocolo 3-D Secure. Veja mais detalhes na API GenCVV().

Parâmetros

keyId	Identificador da chave dentro do HSM. Este identificador não deve conter espaços ou caracteres especiais. Caracteres maiúsculos e minúsculos são diferenciados (case-sensitive). Esta chave é a CVK (Card Verification Key), uma chave 3DES de 112 bits, e deve ser a mesma que foi usada na geração do CVV.
pan	PAN (Primary Account Number). Tamanho de de 12 a 19 caracteres. Veja mais detalhes sobre este campo na API GenCVV().
expirationDate	Data de expiração. Tamanho de 4 dígitos. Na verificação de CVV e iCVV o formato deve ser YYMM. Na verificação de CVV 2 o formato deve ser MMYY. Para informações sobre o suporte aos algoritmos do protocolo 3-D Secure veja mais detalhes sobre este campo na API GenCVV().
serviceCode	Service Code. Tamanho de 3 dígitos. Para a verificação de iCVV (Alternate Card Verification Value), o Service Code deve ser 999. Para a verificação de CVV 2, o Service Code deve ser 000
cvv	CVV a ser validado. Tamanho de 3 dígitos. O valor informado pode também ser um CVV2 ou iCVV, conforme os valores informados de Service Code.

Retorna: true se o CVV foi validado com sucesso e false caso seja inválido.

Exceções

DinamoException Lança exceção em caso de erro.

Exemplos: eft_gen_verify_cvv.cs.

◆ GenPIN()

PinComponents GenPIN	(	string	pgk,
		string	pan,
		GenPINOperation	operation,
		int	pinLen,
		string	inPin )

inline

Faz operações de geração de PIN a partir dos dados de PAN (Personal Account Number) e nome de chave (PGK) informadas, com ou sem uso de offset.

Parâmetros

pgk Identificador da chave PGK (PIN Generation Key), dentro do HSM.

pan PAN (Primary Account Number).

operation

Tipo da geração do PIN. Segundo a tabela abaixo.

Valor	Significado
GenPINOperation.DEFAULT_PIN	Gera o PIN padrão baseado no PAN e PGK. O parâmetro inPin deve ser null.
GenPINOperation.USER_DEF_PIN	Gera um offset referente ao PIN definido pelo chamador. O parâmetro inPin deve conter o PIN.
GenPINOperation.RANDOM_PIN	Gera um PIN e offset aleatoriamente baseados no PAN e PGK. `inPin` deve ser null.

Parâmetros

pinLen	Tamanho de PIN a ser utilizado/gerado na operação. Deve ter tamanho entre DinamoApi.MIN_EFT_PIN_LEN e DinamoApi.MAX_EFT_PIN_LEN.
inPin	PIN de entrada. Deve ter tamanho entre DinamoApi.MIN_EFT_PIN_LEN e DinamoApi.MAX_EFT_PIN_LEN.

Retorna: PIN e offset.

Exceções

DinamoException Lança exceção em caso de erro.

Exemplos: eft_gen_pin.cs.

◆ VerifyPINBlock()

bool VerifyPINBlock	(	string	ptk,
		string	pgk,
		string	pan,
		string	offset,
		byte[]	pinblock )

inline

Verifica a validade de um PIN em um PIN Block. Primeiro o PIN é extraído do PIN Block com a chave PTK, e depois é feita sua verificação com a chave PGK, a mesma que foi usada para geração do PIN, com a função GenPIN().

Parâmetros

ptk	Identificador da chave de decriptação do “PIN Block” dentro do HSM. PIN Transport Key (PTK).
pgk	Identificador da chave a ser utilizada na verificação do PIN dentro do HSM. PIN Generation Key (PGK).
pan	PAN (Primary Account Number).
offset	Offset do PIN. Deve ter tamanho entre DinamoApi.MIN_EFT_PIN_LEN e DinamoApi.MAX_EFT_PIN_LEN.
pinblock	Buffer contendo o Pin Block de entrada que será verificado. O formato de PIN Block esperado é ISO PIN Block Format 0 (equivalente ao ANSI PIN Block Format 0 e ao VISA PIN Block Format 1). O buffer deve ter o tamanho de um PIN Block, DinamoApi.DES_BLOCK (8 bytes).

Retorna: true se o PIN foi validado com sucesso e false caso seja inválido.

Exceções

DinamoException Lança exceção em caso de erro.

Exemplos: eft_verify_pinblock.cs.

◆ ExportTR31()

byte[] ExportTR31	(	string	kbpk,
		string	key,
		EftExportUsage	usage,
		EftExportMode	mode,
		EftExportExpType	exp )

inline

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.
mode	Identificador do modo de uso da chave, como descrito no ASC X9 TR 31-2018 Seção A.5.3 tabela 8.
exp	Identificador de exportabilidade da chave, como descrito no ASC X9 TR 31-2018 Seção A.5.5 tabela 10.

Retorna: Key block

Exceções

DinamoException Lança exceção em caso de erro.

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

Exemplos: export_import_tr31.cs.

◆ ImportTR31()

void ImportTR31	(	string	kbpk,
		string	key,
		bool	isExportable,
		bool	isTemporary,
		byte[]	keyBlock )

inline

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.
isExportable	Define se a chave importada será exportável.
isTemporary	Define se a chave importada será temporária.
keyBlock	Key block no formato TR-31.

Exceções

DinamoException Lança exceção em caso de erro.

Anotações

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

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

Exemplos: export_import_tr31.cs.

Descrição detalhada

Estruturas de Dados

Enumerações

Funções

Enumerações

◆ GenPINOperation

Funções

◆ GenBDKName() [1/2]

◆ GenBDKName() [2/2]

◆ GenDUKPT()

◆ GenCVV()

◆ VerifyCVV()

◆ GenPIN()

◆ VerifyPINBlock()

◆ ExportTR31()

◆ ImportTR31()