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.

Processo genérico de transferência eletrônica de fundos

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.

Chaves criptográficas na transferência de fundos

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.

Geração de CVV, iCVV e CVV 2

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.

Geração PIN por derivação

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.

Algoritmo de Geração de PIN IBM 3624

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.

Algoritmo de Geração de PIN IBM 3624 com offset

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.

Operação de PIN Translate

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).

Operação de verificação de PIN Block

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).

Geração chaves DUKPT

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.

Comunicação DUKPT entre o POS/ATM e o HSM

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

Funções
int AAP_API	DPINBlockTranslate (HSESSIONCTX hSession, char *szSrcPEK, char *szDstPEK, BYTE bTransBlockType, char *szPAN, BYTE *pbInPinBlock, BYTE *pbOutPinBlock, DWORD dwParam)
int AAP_API	DGenerateCVV (HSESSIONCTX hSession, char *szKeyId, char *szPAN, char *szExpirationDate, char *szServiceCode, char *szCVV, DWORD dwParam)
int AAP_API	DVerifyCVV (HSESSIONCTX hSession, char *szKeyId, char *szPAN, char *szExpirationDate, char *szServiceCode, char *szCVV, DWORD dwParam)
int AAP_API	DGeneratePIN (HSESSIONCTX hSession, char *szPGK, char *szPAN, DWORD dwOperation, int nPinLen, char *szInPin, char *szOffset, char *szOutPin, DWORD dwParam)
int AAP_API	DVerifyPINBlock (HSESSIONCTX hSession, char *szPTK, char *szPGK, char *szPAN, char *szOffset, BYTE *pbInPinBlock, DWORD dwParam)
int AAP_API	DEFTCheckKeyParts (int nKeyAlgId, EFT_VISA_KEY_PARTS *pstKeyParts, DWORD dwParam)
int AAP_API	DGenerateDUKPT (HSESSIONCTX hSession, BYTE *pbKSI, BYTE *pbDID_CTR, char *szDUKPT, DWORD dwParam)
void AAP_API	DGenerateBDKName (BYTE *pbKSI, char *szBDKName, DWORD dwParam)
void AAP_API	DGenerateDUKPTName (BYTE *pbKSI, BYTE *pbDID_CTR, char *szDUKPTName, DWORD dwParam)
int AAP_API	DGeneratePVV (HSESSIONCTX hSession, char *szPGK, BYTE bPVKI, char *szPAN, char *szPIN, char *szPVV, DWORD dwParam)
int AAP_API	DGenerateDAC (HSESSIONCTX hSession, char *szIMKDAC, char *szPAN, BYTE *pbSEQ, BYTE *pbDAC, DWORD dwParam)
int AAP_API	DVerifyDAC (HSESSIONCTX hSession, char *szIMKDAC, char *szPAN, BYTE *pbSEQ, BYTE *pbDAC, DWORD dwParam)
int AAP_API	DSignSDA (HSESSIONCTX hSession, char *szIK, BYTE *pbDAC, DWORD dwSDA_DATALen, BYTE *pbSDA_DATA, DWORD *pdwSigLen, BYTE *pbSig, DWORD dwParam)
int AAP_API	DGenerateDDA_ICCCert (HSESSIONCTX hSession, BYTE bOP, char *szIK, char *szPAN, DWORD dwDDA_DATALen, BYTE *pbDDA_DATA, DWORD *pdwSigLen, BYTE *pbSig, DWORD dwParam)
int AAP_API	DGenerateICCMK (HSESSIONCTX hSession, BYTE bOP, char *szIK, char *szKeK, char *szPAN, BYTE *pbSEQ, DWORD *pdwEnvelopeLen, BYTE *pbEnvelope, DWORD dwParam)
int AAP_API	DGenerateEMV_HMAC (HSESSIONCTX hSession, BYTE bOP, char *szIK, char *szPAN, BYTE *pbSEQ, BYTE *pbNONCE, DWORD dwDataLen, BYTE *pbData, BYTE *pbMAC, DWORD dwParam)
int AAP_API	DGenerateEMV_MAC (HSESSIONCTX hSession, BYTE bOP, char *szIK, char *szPAN, BYTE *pbSEQ, BYTE *pbNONCE, DWORD dwDataLen, BYTE *pbData, BYTE *pbMAC, DWORD dwParam)
int AAP_API	DCheckIDN (HSESSIONCTX hSession, char *szIK, char *szPAN, BYTE *pbSEQ, BYTE *pbATC, BYTE *pbUN, BYTE *pbIDN, DWORD dwParam)
int AAP_API	DEncryptEMV (HSESSIONCTX hSession, BYTE bEncOP, char *szEncIK, BYTE *pbEncNONCE, BYTE bMacOP, char *szMacIK, BYTE *pbMacNONCE, char *szPAN, BYTE *pbSEQ, DWORD dwDataLen, BYTE *pbData, DWORD *pdwEncDataLen, BYTE *pbEncData, BYTE *pbMAC, DWORD dwParam)
int AAP_API	DGenerateEMV_CSR (HSESSIONCTX hSession, BYTE bOP, char *szIK, BYTE *pbTrackNum, BYTE *pbServiceID, BYTE *pbIssuerID, BYTE *pbExpDate, DWORD *pdwCSRLen, BYTE *pbCSR, DWORD dwParam)
int AAP_API	DGenerateEMV_CSREx (HSESSIONCTX hSession, BYTE bOP, char *szIK, BYTE *pbTrackNum, BYTE *pbServiceID, BYTE *pbIssuerID, BYTE *pbExpDate, DBLOB *pdbCSR, BYTE *pbHash, DWORD dwParam)
int AAP_API	DGenerateEMV_PinBlock (HSESSIONCTX hSession, BYTE bOP, BYTE *pbNONCE, char *szTransportKey, char *szISSUER_MK, char *szISSUER_SMC_MK, char *szPAN, BYTE *pbSEQ, BYTE *pbOLD_PB, BYTE *pbNEW_PB, BYTE *pbOutBlock, DWORD *pdwOutBlockLen, DWORD dwParam)
int AAP_API	DDeriveEMV_Key (HSESSIONCTX hSession, char *szSrcKey, WORD wBufferLen, BYTE *pbBuffer, BYTE bOP, DWORD dwAttrib, char *szDstKey, HKEYCTX *phKey, DWORD dwParam)
int AAP_API	DCalculateARPC (HSESSIONCTX hSession, char *szIssuerMK, char *szPAN, BYTE *pbSEQ, BYTE *pbARQC, BYTE *pbARC, BYTE *pbARPC, DWORD dwParam)
int AAP_API	DCalculateARPC_Ex (HSESSIONCTX hSession, DWORD dwOp, void *pvInData, BYTE *pbARPC, DWORD dwParam)
int AAP_API	DMAC_ISO9797_1_Met2 (DWORD dwType, BYTE *pbKey, DWORD dwAlg, const BYTE *pbMsg, DWORD dwMsgLen, BYTE *pbMAC)
int AAP_API	DEFTImportKey (HSESSIONCTX hSession, char *szKeyId, int nKeyAlgId, void *pstKeyParts, DWORD dwParam)
int AAP_API	DEFTExportAESKeyParts (HSESSIONCTX hSession, BYTE bKcvType, const char *szKeyId, void *pvKeyParts, DWORD dwReserved)
int AAP_API	DEFTExportKey (HSESSIONCTX hSession, BYTE bExportMode, char *szKEKId, char *szKeyId, BYTE *pbEncryptedBlock, DWORD *pdwEncryptedBlockLen, BYTE *pbKeyCheckValue, DWORD dwParam)
int AAP_API	DEFTKeKImport (HSESSIONCTX hSession, BYTE bOP, DWORD dwAlgId, char *szKeKName, char *szKeyName, DWORD dwAttr, BYTE *pbKCV1, BYTE *pbKCV2, BYTE *pbKCV3, BYTE *pbKCVFinal, BYTE *pbBlob, DWORD dwFlags)
int AAP_API	DEFTExportZPK (HSESSIONCTX hSession, char *szKeyId, int *pnKeyAlg, int *pnKeySize, EFT_VISA_KEY_PARTS *pstKeyParts, DWORD dwParam)
int AAP_API	DEFTGetKcv (HSESSIONCTX hSession, BYTE bType, const char *szKeyId, BYTE *pbKcv, DWORD *pdwKcvLen, DWORD dwReserved)
int AAP_API	DEFTGenKCVOffline (DWORD dwType, int nAlgId, const BYTE *pbKey, DWORD dwKeyLen, BYTE *pbKCV, DWORD *pdwKCVLen, DWORD reserved)
int AAP_API	DEFTExportTR31 (HSESSIONCTX hSession, const char *szKBPK, const char *szKey, void *pvReserved, WORD wUsage, BYTE bMode, BYTE bExport, BYTE *pbOutBlock, DWORD *pdwOutBlockLen, DWORD dwParam)
int AAP_API	DEFTImportTR31 (HSESSIONCTX hSession, const char *szKBPK, const char *szKey, DWORD dwKeyAttributes, BYTE *pbKeyBlock, DWORD dwKeyBlockLen, DWORD dwParam)

Definições e macros

DN_CALC_ARPC_EMV_4_2_M1_ICC

#define DN_CALC_ARPC_EMV_4_2_M1_ICC   (1)

#include <dinamo.h>

DN_CALC_ARPC_EMV_4_2_M1_SK

#define DN_CALC_ARPC_EMV_4_2_M1_SK   (2)

#include <dinamo.h>

DN_CALC_ARPC_EMV_4_2_M2

#define DN_CALC_ARPC_EMV_4_2_M2   (3)

#include <dinamo.h>

DN_EFT_AES_KCV_TYPE_CMAC

#define DN_EFT_AES_KCV_TYPE_CMAC   (1)

#include <dinamo.h>

KCV do tipo CMAC. De acordo com o PCI "PIN Security Requirements".

DN_EFT_GET_KCV_TYPE_X9_24

#define DN_EFT_GET_KCV_TYPE_X9_24   (1)

#include <dinamo.h>

Exporta uma chave AES por partes no formato ANSI X9.24.

Parâmetros

[in]	hSession	Contexto adquirido através da função DOpenSession().
[in]	bKcvType	Tipo de KCV a ser utilizado na exportação. Valor Significado DN_EFT_GET_KCV_TYPE_X9_24 Gera o KCV (Key Check Value) da chave como definido na ANSI X.9.24 com tamanho de 3 bytes. DN_EFT_GET_KCV_TYPE_CMAC Gera o KCV (Key Check Value) da chave como definido no PCI PIN Security Requirements com tamanho de 3 bytes.
[in]	szKeyId	Nome da chave a ser exportada.
[out]	pvKeyParts	Ponteiro para uma estrutura EFT_AES_KEY_PARTS que conterá os dados para reconstrução da chave.
[in]	dwReserved	Reservado para uso futuro (deve ser 0).

Retorna

0 (ZERO) se a função for bem sucedida.
Consulte a seção Códigos de Retorno sobre outros valores. Gera o KCV (Key Check Value) da chave como definido na ANSI X.9.24 com tamanho de 3 bytes.

DN_EFT_GET_KCV_TYPE_CMAC

#define DN_EFT_GET_KCV_TYPE_CMAC   (2)

#include <dinamo.h>

Gera o KCV (Key Check Value) da chave como definido no PCI PIN Security Requirements com tamanho de 3 bytes.

DN_EXP_ZPK_FLAG_FULL_CKS

#define DN_EXP_ZPK_FLAG_FULL_CKS   (1)

#include <dinamo.h>

DN_EFT_GET_KCV_MAX_LEN

#define DN_EFT_GET_KCV_MAX_LEN   (3)

#include <dinamo.h>

Tamanho máximo do KCV (Key Check Value) gerado.

DN_EFT_GEN_OFFLINE_KCV_TYPE_X9_24

#define DN_EFT_GEN_OFFLINE_KCV_TYPE_X9_24   (1)

#include <dinamo.h>

Gera o KCV (Key Check Value) da chave como definido na ANSI X.9.24 com tamanho de 3 bytes.

DN_EFT_GEN_OFFLINE_KCV_TYPE_CMAC

#define DN_EFT_GEN_OFFLINE_KCV_TYPE_CMAC   (2)

#include <dinamo.h>

Gera o KCV (Key Check Value) da chave como definido no PCI PIN Security Requirements com tamanho de 3 bytes.

DN_EFT_KCV_TYPE_X9_24_LEN

#define DN_EFT_KCV_TYPE_X9_24_LEN   (3)

#include <dinamo.h>

Tamanho do KCV (Key Check Value) gerado.

DN_EFT_KCV_TYPE_CMAC_LEN

#define DN_EFT_KCV_TYPE_CMAC_LEN   (3)

#include <dinamo.h>

Tamanho do KCV (Key Check Value) gerado.

Funções

DPINBlockTranslate()

int AAP_API DPINBlockTranslate	(	HSESSIONCTX	hSession,
		char *	szSrcPEK,
		char *	szDstPEK,
		BYTE	bTransBlockType,
		char *	szPAN,
		BYTE *	pbInPinBlock,
		BYTE *	pbOutPinBlock,
		DWORD	dwParam
	)

#include <dinamo.h>

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

[in]	hSession	Contexto adquirido através da função DOpenSession().
[in]	szSrcPEK	Identificador da chave de decriptação dentro do HSM.
[in]	szDstPEK	Identificador da chave de encriptação dentro do HSM.
[in]	bTransBlockType	Identificador do formato do bloco de saída. De acordo com a tabela abaixo. Valor Significado 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. 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. TP_TRANSLATE_TYPE_ISO_1 Utiliza o tipo de bloco ISO PIN Block Format 1. PAN Bound: não. TP_TRANSLATE_TYPE_ISO_3 Utiliza o tipo de bloco ISO PIN Block Format 3. PAN Bound: sim. TP_TRANSLATE_TYPE_IBM_3624 Utilizada o tipo de bloco IBM 3624. Não implementado.
[in]	szPAN	PAN (Primary Account Number).
[in]	pbInPinBlock	Buffer contendo o PIN Block de entrada. O buffer deve ter o tamanho de um PIN Block, DES_BLOCK (8 bytes) .
[out]	pbOutPinBlock	Buffer que conterá o PIN Block de saída. O buffer deve ter o tamanho de um PIN Block, DES_BLOCK (8 bytes).
[in]	dwParam	Reservado para uso futuro (deve ser 0).

Retorna

0 (ZERO) se a função for bem sucedida.
Consulte a seção Códigos de Retorno sobre outros valores.

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.

Exemplos

pin_block_translate.c.

DGenerateCVV()

int AAP_API DGenerateCVV	(	HSESSIONCTX	hSession,
		char *	szKeyId,
		char *	szPAN,
		char *	szExpirationDate,
		char *	szServiceCode,
		char *	szCVV,
		DWORD	dwParam
	)

#include <dinamo.h>

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

[in]	hSession	Contexto adquirido através da função DOpenSession().
[in]	szKeyId	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.
[in]	szPAN	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.
[in]	szExpirationDate	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.
[in]	szServiceCode	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.
[out]	szCVV	Buffer de saída que conterá a string do CVV gerado. Tamanho de 3 dígitos. O valor gerado pode também ser um CVV2 ou iCVV, conforme os valores informados de Service Code.
[in]	dwParam	Reservado para uso futuro (deve ser 0).

Retorna

0 (ZERO) se a função for bem sucedida.
Consulte a seção Códigos de Retorno sobre outros valores.

Anotações

A API também é compatível com o padrão da bandeira American Express.

Exemplos

eft_validate_cvv.c.

DVerifyCVV()

int AAP_API DVerifyCVV	(	HSESSIONCTX	hSession,
		char *	szKeyId,
		char *	szPAN,
		char *	szExpirationDate,
		char *	szServiceCode,
		char *	szCVV,
		DWORD	dwParam
	)

#include <dinamo.h>

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 DGenerateCVV().

Parâmetros

[in]	hSession	Contexto adquirido através da função DOpenSession().
[in]	szKeyId	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.
[in]	szPAN	PAN (Primary Account Number). Tamanho de de 12 a 19 caracteres. Veja mais detalhes sobre este campo na API DGenerateCVV().
[in]	szExpirationDate	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 DGenerateCVV().
[in]	szServiceCode	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
[in]	szCVV	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.
[in]	dwParam	Reservado para uso futuro (deve ser 0).

Retorna

0 (ZERO) se a função for bem sucedida.
Consulte a seção Códigos de Retorno sobre outros valores.

Exemplos

eft_validate_cvv.c.

DGeneratePIN()

int AAP_API DGeneratePIN	(	HSESSIONCTX	hSession,
		char *	szPGK,
		char *	szPAN,
		DWORD	dwOperation,
		int	nPinLen,
		char *	szInPin,
		char *	szOffset,
		char *	szOutPin,
		DWORD	dwParam
	)

#include <dinamo.h>

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

[in]	hSession	Contexto adquirido através da função DOpenSession().
[in]	szPGK	Identificador da chave dentro do HSM.
[in]	szPAN	PAN (Primary Account Number).
[in]	dwOperation	Tipo da geração do PIN. Segundo a tabela abaixo. Valor Significado GP_DEFAULT_PIN Gera o PIN padrão baseado no PAN e PGK. O parâmetro szInPin deve ser NULL. GP_USER_DEF_PIN Gera um offset referente ao PIN definido pelo chamador. O parâmetro szInPin deve conter uma string contendo o PIN. GP_RANDOM_PIN Gera um PIN e offset aleatoriamente baseados no PAN e PGK. szInPin deve ser NULL.
[in]	nPinLen	Tamanho de PIN a ser utilizado/gerado na operação. Deve ter tamanho entre MIN_EFT_PIN_LEN e MAX_EFT_PIN_LEN.
[in]	szInPin	PIN de entrada. O buffer deve ter tamanho entre MIN_EFT_PIN_LEN + 1 e MAX_EFT_PIN_LEN + 1.
[out]	szOffset	Buffer que conterá a string do offset. O buffer deve ter tamanho entre MIN_EFT_PIN_LEN + 1 e MAX_EFT_PIN_LEN + 1.
[out]	szOutPin	Buffer que conterá a string do PIN de saída. O buffer deve ter tamanho entre MIN_EFT_PIN_LEN + 1 e MAX_EFT_PIN_LEN + 1.
[in]	dwParam	Reservado para uso futuro (deve ser 0).

Retorna

0 (ZERO) se a função for bem sucedida.
Consulte a seção Códigos de Retorno sobre outros valores.

DVerifyPINBlock()

int AAP_API DVerifyPINBlock	(	HSESSIONCTX	hSession,
		char *	szPTK,
		char *	szPGK,
		char *	szPAN,
		char *	szOffset,
		BYTE *	pbInPinBlock,
		DWORD	dwParam
	)

#include <dinamo.h>

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 DGeneratePIN().

Parâmetros

[in]	hSession	Contexto adquirido através da função DOpenSession().
[in]	szPTK	Identificador da chave de decriptação do “PIN Block” dentro do HSM. É a PIN Transport Key.
[in]	szPGK	Identificador da chave a ser utilizada na verificação do PIN dentro do HSM. É a PIN Generation Key.
[in]	szPAN	PAN (Primary Account Number).
[in]	szOffset	Offset do PIN. O buffer deve ter tamanho entre MIN_EFT_PIN_LEN + 1 e MAX_EFT_PIN_LEN + 1.
[in]	pbInPinBlock	Buffer que conterá 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, DES_BLOCK (8 bytes).
[in]	dwParam	Reservado para uso futuro (deve ser 0).

Retorna

0 (ZERO) se a função for bem sucedida.
Consulte a seção Códigos de Retorno sobre outros valores.

Exemplos

verify_pin_block.c.

DEFTCheckKeyParts()

int AAP_API DEFTCheckKeyParts	(	int	nKeyAlgId,
		EFT_VISA_KEY_PARTS *	pstKeyParts,
		DWORD	dwParam
	)

#include <dinamo.h>

Verifica a validade das partes de uma chave VISA com os seus respectivos valores de verificação, no formato descrito no VISA Payment Technology Standards Manual, october 2007.

Parâmetros

[in]	nKeyAlgId	Algoritmo da chave a ser verificada.
[in]	pstKeyParts	Ponteiro para uma estrutura EFT_VISA_KEY_PARTS contendo as partes da chave a ser verificada seus valores de verificação por partes.
[in]	dwParam	Reservado para uso futuro (deve ser 0).

Retorna

0 (ZERO) se a função for bem sucedida.
Consulte a seção Códigos de Retorno sobre outros valores.

Anotações

Apenas as partes são verificadas com os seus respectivos valores de verificação, a chave completa e montada não é verificada neste teste.

DGenerateDUKPT()

int AAP_API DGenerateDUKPT	(	HSESSIONCTX	hSession,
		BYTE *	pbKSI,
		BYTE *	pbDID_CTR,
		char *	szDUKPT,
		DWORD	dwParam
	)

#include <dinamo.h>

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

[in]	hSession	Contexto adquirido através da função DOpenSession().
[in]	pbKSI	Buffer de tamanho MIN_KSI_LEN contendo o KSI (primeiros 05 bytes do KSN).
[in]	pbDID_CTR	Buffer de tamanho MIN_CTR_LEN contendo o DID e CTR (últimos 05 bytes do KSN).
[out]	szDUKPT	Buffer de tamanho MAX_OBJ_ID que conterá o nome da chave DKUPT gerado a partir dos parâmetros informados.
[in]	dwParam	Flags de operação de acordo com a tabela abaixo. Valor Significado 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

0 (ZERO) se a função for bem sucedida.
Consulte a seção Códigos de Retorno sobre outros valores.

Exemplos

gen_dukpt.c.

DGenerateBDKName()

void AAP_API DGenerateBDKName	(	BYTE *	pbKSI,
		char *	szBDKName,
		DWORD	dwParam
	)

#include <dinamo.h>

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

Parâmetros

[in]	pbKSI	Buffer de tamanho MIN_KSI_LEN contendo o KSI.
[out]	szBDKName	Buffer de tamanho MAX_OBJ_ID que conterá o nome de chave BDK gerado a partir do KSI informado em pbKSI.
[in]	dwParam	Reservado para uso futuro (deve ser 0).

Retorna

Não retorna valor.

Exemplos

gen_dukpt.c.

DGenerateDUKPTName()

void AAP_API DGenerateDUKPTName	(	BYTE *	pbKSI,
		BYTE *	pbDID_CTR,
		char *	szDUKPTName,
		DWORD	dwParam
	)

#include <dinamo.h>

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

Parâmetros

[in]	pbKSI	Buffer de tamanho MIN_KSI_LEN contendo o KSI (Key Serial Identification).
[in]	pbDID_CTR	Buffer de tamanho MIN_CTR_LEN contendo o CTR (Device ID e Transaction Counter).
[out]	szDUKPTName	Buffer de tamanho MAX_OBJ_ID que conterá o nome de chave DKUPT gerado a partir do KSI e CTR informados em pbKSI e pbCTR.
[in]	dwParam	Reservado para uso futuro (deve ser 0).

Retorna

Não retorna valor.

DGeneratePVV()

int AAP_API DGeneratePVV	(	HSESSIONCTX	hSession,
		char *	szPGK,
		BYTE	bPVKI,
		char *	szPAN,
		char *	szPIN,
		char *	szPVV,
		DWORD	dwParam
	)

#include <dinamo.h>

Gera um PVV (Pin Verification Value) a partir de um PAN (Primary Account Number), um PIN (Personal Identification Number) e uma PGK.

Parâmetros

[in]	hSession	Contexto adquirido através da função DOpenSession().
[in]	szPGK	Identificador da chave dentro do HSM.
[in]	bPVKI	Identificador de chave variando de EFT_MIN_PVKI até EFT_MAX_PVKI.
[in]	szPAN	PAN (Primary Account Number).
[in]	szPIN	PIN (Personal Identification Number).
[out]	szPVV	Buffer que conterá a string do PVV gerado. Deve ter tamanho mínimo de EFT_PVV_LEN + 1 (terminador zero).
[in]	dwParam	Reservado para uso futuro (deve ser 0).

Retorna

0 (ZERO) se a função for bem sucedida.
Consulte a seção Códigos de Retorno sobre outros valores.

DGenerateDAC()

int AAP_API DGenerateDAC	(	HSESSIONCTX	hSession,
		char *	szIMKDAC,
		char *	szPAN,
		BYTE *	pbSEQ,
		BYTE *	pbDAC,
		DWORD	dwParam
	)

#include <dinamo.h>

Gera um DAC (Data Authentication Code) recebendo como parâmetros o PAN (Primary Account Number), a SEQ (PAN Sequence Number) e a chave IMKDAC (Issuer Master Key) utilizada no DAC.

Parâmetros

[in]	hSession	Contexto adquirido através da função DOpenSession().
[in]	szIMKDAC	Identificador da chave dentro do HSM.
[in]	szPAN	PAN (Primary Account Number).
[in]	pbSEQ	Buffer de tamanho EFT_EMV_SDA_SEQ_LEN contendo o SEQ (PAN Sequence Number).
[out]	pbDAC	Buffer de tamanho EFT_EMV_SDA_DAC_LEN contendo o DAC (Data Authentication Code) a ser verificado.
[in]	dwParam	Reservado para uso futuro (deve ser 0).

Retorna

0 (ZERO) se a função for bem sucedida.
Consulte a seção Códigos de Retorno sobre outros valores.

DVerifyDAC()

int AAP_API DVerifyDAC	(	HSESSIONCTX	hSession,
		char *	szIMKDAC,
		char *	szPAN,
		BYTE *	pbSEQ,
		BYTE *	pbDAC,
		DWORD	dwParam
	)

#include <dinamo.h>

Verifica um DAC (Data Authentication Code) recebendo como parâmetros o PAN (Primary Account Number), a SEQ (PAN Sequence Number) e a chave IMKDAC (Issuer Master Key) utilizada no DAC.

Parâmetros

[in]	hSession	Contexto adquirido através da função DOpenSession().
[in]	szIMKDAC	Identificador da chave dentro do HSM.
[in]	szPAN	PAN (Primary Account Number).
[in]	pbSEQ	Buffer de tamanho EFT_EMV_SDA_SEQ_LEN contendo o SEQ (PAN Sequence Number).
[in]	pbDAC	Buffer de tamanho EFT_EMV_SDA_DAC_LEN contendo o DAC (Data Authentication Code) a ser verificado.
[in]	dwParam	Reservado para uso futuro (deve ser 0).

Retorna

0 (ZERO) se a função for bem sucedida.
Consulte a seção Códigos de Retorno sobre outros valores.

DSignSDA()

int AAP_API DSignSDA	(	HSESSIONCTX	hSession,
		char *	szIK,
		BYTE *	pbDAC,
		DWORD	dwSDA_DATALen,
		BYTE *	pbSDA_DATA,
		DWORD *	pdwSigLen,
		BYTE *	pbSig,
		DWORD	dwParam
	)

#include <dinamo.h>

Assina um SAD (Static Application Data) para cartões SDA (Static Data Authentication) gerando um SSDA (Signed Static Application Data).

Parâmetros

[in]	hSession	Contexto adquirido através da função DOpenSession().
[in]	szIK	Nome da chave privada dentro do HSM que será utilizada para assinar o SAD.
[in]	pbDAC	Buffer de tamanho EFT_EMV_SDA_DAC_LEN contendo o DAC (Data Authentication Code) a ser verificado.
[in]	dwSDA_DATALen	Tamanho do buffer apontado por pbSDA_DATA .
[in]	pbSDA_DATA	Buffer que contém o SDA (Static Application Data) a ser assinado de tamanho especificado em dwSDA_DATALen.
[in,out]	pdwSigLen	Ponteiro para um DWORD que contém o tamanho do buffer apontado por pbSig.
[out]	pbSig	Buffer de tamanho apontado por pdwSigLen que receberá o SSDA (Signed Static Application Data). Pode ser passado NULL para recuperar o tamanho necessário de pbSig, que será retornado em pdwSigLen.
[in]	dwParam	Reservado para uso futuro (deve ser 0).

Retorna

0 (ZERO) se a função for bem sucedida.
Consulte a seção Códigos de Retorno sobre outros valores.

DGenerateDDA_ICCCert()

int AAP_API DGenerateDDA_ICCCert	(	HSESSIONCTX	hSession,
		BYTE	bOP,
		char *	szIK,
		char *	szPAN,
		DWORD	dwDDA_DATALen,
		BYTE *	pbDDA_DATA,
		DWORD *	pdwSigLen,
		BYTE *	pbSig,
		DWORD	dwParam
	)

#include <dinamo.h>

Gera o Certificado do ICC (Integrated Circuit Card) utilizada em autenticação DDA (Dynamic Data Authentication).

Parâmetros

[in]	hSession	Contexto adquirido através da função DOpenSession().
[in]	bOP	Tipo da operação a ser aplicada de acordo com a tabela abaixo. Valor Signficado EFT_EMV_DDA_OP_RSA_SIGN1 RSA + SHA1
[in]	szIK	Nome da chave privada dentro do HSM que será utilizada para assinar o Certificado.
[in]	szPAN	PAN (Primary Account Number).
[in]	dwDDA_DATALen	Tamanho do buffer apontado por pbDDA_DATA.
[in]	pbDDA_DATA	Buffer que contém os dados do certificado a ser assinado. Passar a estrutura descrita no EMV Book 2 Tabelas 10 a 14, sem incluir os campos Recovered Data Header e Trailer.
[in,out]	pdwSigLen	Ponteiro para um DWORD que contém o tamanho do buffer pbSig.
[out]	pbSig	Buffer que receberá o certificado assinado. Pode ser passado NULL para recuperar o tamanho necessário de pbSig, que será retornado em pdwSigLen.
[in]	dwParam	Reservado para uso futuro (deve ser 0).

Retorna

0 (ZERO) se a função for bem sucedida.
Consulte a seção Códigos de Retorno sobre outros valores.

DGenerateICCMK()

int AAP_API DGenerateICCMK	(	HSESSIONCTX	hSession,
		BYTE	bOP,
		char *	szIK,
		char *	szKeK,
		char *	szPAN,
		BYTE *	pbSEQ,
		DWORD *	pdwEnvelopeLen,
		BYTE *	pbEnvelope,
		DWORD	dwParam
	)

#include <dinamo.h>

Gera Master Keysdo ICC (Integrated Circuit Card).

Parâmetros

[in]	hSession	Contexto adquirido através da função DOpenSession().
[in]	bOP	Tipo da operação a ser aplicada de acordo com a tabela abaixo. Valor Significado EFT_EMV_GEN_ICC_MK_OP_CBC_EXP Operação em modo CBC EFT_EMV_GEN_ICC_MK_OP_ECB_EXP Operação em modo ECB
[in]	szIK	Nome da chave dentro do HSM que será utilizada para gerar a Master Key.
[in]	szKeK	Nome da chave de transporte utilizada para encriptar a chave gerada.
[in]	szPAN	PAN (Primary Account Number).
[in]	pbSEQ	Buffer de tamanho EFT_EMV_SDA_SEQ_LEN contendo o SEQ (PAN Sequence Number).
[in,out]	pdwEnvelopeLen	Ponteiro para um DWORD que contém o tamanho do buffer apontado por pbEnvelope.
[out]	pbEnvelope	Buffer que receberá o envelope com a chave gerada. Pode ser passado NULL para recuperar o tamanho necessário de pbSig, que será retornado em pdwEnvelopeLen.
[in]	dwParam	Reservado para uso futuro (deve ser 0).

Retorna

0 (ZERO) se a função for bem sucedida.
Consulte a seção Códigos de Retorno sobre outros valores.

DGenerateEMV_HMAC()

int AAP_API DGenerateEMV_HMAC	(	HSESSIONCTX	hSession,
		BYTE	bOP,
		char *	szIK,
		char *	szPAN,
		BYTE *	pbSEQ,
		BYTE *	pbNONCE,
		DWORD	dwDataLen,
		BYTE *	pbData,
		BYTE *	pbMAC,
		DWORD	dwParam
	)

#include <dinamo.h>

Obsoleto(a):

A API DGenerateEMV_MAC() é funcional e sintáticamente equivalente à API DGenerateEMV_HMAC. A referência à DGenerateEMV_HMAC continue ativa na biblioteca (internamente ela é redirecionada para DGenerateEMV_MAC() ). As aplicações que fazem chamada à DGenerateEMV_HMAC não precisam ser alteradas.

DGenerateEMV_MAC()

int AAP_API DGenerateEMV_MAC	(	HSESSIONCTX	hSession,
		BYTE	bOP,
		char *	szIK,
		char *	szPAN,
		BYTE *	pbSEQ,
		BYTE *	pbNONCE,
		DWORD	dwDataLen,
		BYTE *	pbData,
		BYTE *	pbMAC,
		DWORD	dwParam
	)

#include <dinamo.h>

Gera um criptograma padrão EMV ou MAC (Message Authentication Code), utilizado nos comandos EMV.

Parâmetros

[in]	hSession	Contexto adquirido através da função DOpenSession().
[in]	bOP	Tipo da operação (padding, derivação de chave, etc) a ser aplicada na construção do criptograma (MAC) de acordo com a tabela abaixo. Valor Significado EMV_OP_ISO_9797_1_M2_COMMON Padrão ISO 9797-1 Padding Method 2 COMMON. EMV_OP_ISO_9797_1_M2_MCHIP Padrão ISO 9797-1 Padding Method 2 MCHIP. EMV_OP_ISO_9797_1_M2_VISA Padrão ISO 9797-1 Padding Method 2 VISA. EMV_OP_ISO_9797_1_M2_VISA_CRYPTOGRAM Padrão ISO 9797-1 Padding Method 2 VISA_CRYPTOGRAM. EMV_OP_ISO_9797_1_M2_RAW Padrão ISO 9797-1 Padding Method 2 Algorithm 3.Deve ser passado NULL nos parâmetros szPAN, pbSEQ e pbNONCE. EMV_OP_ISO_9797_1_M1_VISA_CRYPTOGRAM_PADD_V10 Padrão ISO 9797-1 Padding Method 1 VISA. EMV_OP_ISO_9797_1_M2_ELO Padrão ISO 9797-1 Padding Method 2 COMMON. EMV_OP_ISO_9797_1_M2_JCB Padrão ISO 9797-1 Padding Method 2. Como descrito em JCB IC Card Specification, Version 2.0 - October, 2012. EMV_OP_ISO_9797_1_M1_JCB Padrão ISO 9797-1 Padding Method 1. Como descrito em JCB IC Card Specification, Version 2.0 - October, 2012. EMV_OP_ISO_9797_1_M1_JCB_CRYPTOGRAM Padrão ISO 9797-1 Padding Method 1. Como descrito em JCB IC Card Specification, Version 2.0 - October, 2012.
[in]	szIK	Nome da chave dentro do HSM que será utilizada para gerar o MAC.
[in]	szPAN	PAN (Primary Account Number).
[in]	pbSEQ	Buffer de tamanho EFT_EMV_SDA_SEQ_LEN contendo o SEQ (PAN Sequence Number). Deve ser em formato ASCII.
[in]	pbNONCE	Buffer contendo o material diversificador utilizado na geração do MAC, deve ter tamanho DES_BLOCK. Tipo da operação conforme parâmetro bOP NONCE EMV_OP_ISO_9797_1_M2_COMMON ATC (2 bytes)||00||00||00||00||00||00 EMV_OP_ISO_9797_1_M2_MCHIP CVN10 e CVN11: ATC (2 bytes)||00||00||UC (Unpredictable Number) CVN14 e CVN15: ATC (2 bytes)||00||00||00||00||00||00 EMV_OP_ISO_9797_1_M2_VISA 00||00||00||00||00||00||ATC (2 bytes) EMV_OP_ISO_9797_1_M2_VISA_CRYPTOGRAM 00||00||00||00||00||00||00||00 ou NULL EMV_OP_ISO_9797_1_M2_RAW NULL EMV_OP_ISO_9797_1_M1_VISA_CRYPTOGRAM_PADD_V10 00||00||00||00||00||00||00||00 ou NULL EMV_OP_ISO_9797_1_M2_ELO ATC (2 bytes)||00||00||00||00||00||00 EMV_OP_ISO_9797_1_M2_JCB 00||00||00||00||00||00||ATC (2 bytes) EMV_OP_ISO_9797_1_M1_JCB 00||00||00||00||00||00||ATC (2 bytes) EMV_OP_ISO_9797_1_M1_JCB_CRYPTOGRAM 00||00||00||00||00||00||ATC (2 bytes)

O CVN (Cryptogram Version Number) determina a versão do criptograma utilizado e depende de definições de negócio. A aplicação deve utilizar o NONCE seguindo a versão do CVN, quando aplicável.
Para maiores informações sobre qual CVN utilizar consulte a administradora do esquema do cartão.

Parâmetros

[in]	dwDataLen	Tamanho do buffer apontado por pbData.
[in]	pbData	Buffer de tamanho especificado por dwDataLen contendo os dados que serão utilizados na geração do MAC. Observe que o padding será feito pelo HSM, conforme o parâmetro bOP, portanto a aplicação chamadora não deve fazer padding nos dados em pbData.
[out]	pbMAC	Buffer de tamanho DES_BLOCK que conterá o MAC gerado.
[in]	dwParam	Reservado para uso futuro (deve ser 0).

Retorna

0 (ZERO) se a função for bem sucedida.
Consulte a seção Códigos de Retorno sobre outros valores.

DCheckIDN()

int AAP_API DCheckIDN	(	HSESSIONCTX	hSession,
		char *	szIK,
		char *	szPAN,
		BYTE *	pbSEQ,
		BYTE *	pbATC,
		BYTE *	pbUN,
		BYTE *	pbIDN,
		DWORD	dwParam
	)

#include <dinamo.h>

Verifica o IDN (ICC Dynamic Number).

Parâmetros

[in]	hSession	Contexto adquirido através da função DOpenSession().
[in]	szIK	Nome da chave dentro do HSM que será utilizada para verificar o IDN.
[in]	szPAN	PAN (Primary Account Number).
[in]	pbSEQ	Buffer de tamanho EFT_EMV_SDA_SEQ_LEN contendo o SEQ (PAN Sequence Number).
[in]	pbATC	Buffer de tamanho EFT_EMV_IDN_ATC_LEN contendo o ATC (Application Transaction Counter).
[in]	pbUN	Buffer de tamanho EFT_EMV_IDN_UN_LEN contendo o UN (Unpredictable Number).
[in]	pbIDN	Buffer de tamanho EFT_EMV_IDN_LEN contendo o IDN (ICC Dynamic Number).
[in]	dwParam	Reservado para uso futuro (deve ser 0).

Retorna

0 (ZERO) se a função for bem sucedida.
Consulte a seção Códigos de Retorno sobre outros valores.

DEncryptEMV()

int AAP_API DEncryptEMV	(	HSESSIONCTX	hSession,
		BYTE	bEncOP,
		char *	szEncIK,
		BYTE *	pbEncNONCE,
		BYTE	bMacOP,
		char *	szMacIK,
		BYTE *	pbMacNONCE,
		char *	szPAN,
		BYTE *	pbSEQ,
		DWORD	dwDataLen,
		BYTE *	pbData,
		DWORD *	pdwEncDataLen,
		BYTE *	pbEncData,
		BYTE *	pbMAC,
		DWORD	dwParam
	)

#include <dinamo.h>

Encripta dados em SMC (Secure Message with Confidentiality) e gera MACs (Message Authenticatino Code) em SMC/SMI (Secure Messaging for Confidentiality/Integrity).

Parâmetros

[in]	hSession	Contexto adquirido através da função DOpenSession().
[in]	bEncOP	Tipo da operação a ser aplicada de acordo com a tabela abaixo. Valor Significado EMV_OP_ISO_9797_1_M2_COMMON Padrão ISO 9797-1 Method 2 COMMON. EMV_OP_ISO_9797_1_M2_MCHIP Padrão ISO 9797-1 Method 2 MCHIP. EMV_OP_ISO_9797_1_M2_VISA Padrão ISO 9797-1 Method 2 VISA. EMV_OP_ISO_9797_1_M2_ELO Padrão ISO 9797-1 Padding Method 2 COMMON. EMV_OP_ISO_9797_1_M2_JCB Padrão ISO 9797-1 Padding Method 2. Como descrito em JCB IC Card Specification, Version 2.0 - October, 2012.
[in]	szEncIK	Nome da chave dentro do HSM que será utilizada para encriptar os dados.
[in]	pbEncNONCE	Buffer contendo o material diversificador utilizado na encriptação dos dados, deve ter tamanho DES_BLOCK.
[in]	bMacOP	Tipo da operação a ser aplicada de acordo com a tabela abaixo. Valor Significado EMV_OP_ISO_9797_1_M2_COMMON Padrão ISO 9797-1 Method 2 COMMON. EMV_OP_ISO_9797_1_M2_MCHIP Padrão ISO 9797-1 Method 2 MCHIP. EMV_OP_ISO_9797_1_M2_VISA Padrão ISO 9797-1 Method 2 VISA. EMV_OP_ISO_9797_1_M2_ELO Padrão ISO 9797-1 Padding Method 2 COMMON. EMV_OP_ISO_9797_1_M2_JCB Padrão ISO 9797-1 Padding Method 2. Como descrito em JCB IC Card Specification, Version 2.0 - October, 2012. EMV_OP_ISO_9797_1_M1_JCB Padrão ISO 9797-1 Padding Method 1. Como descrito em JCB IC Card Specification, Version 2.0 - October, 2012. EMV_OP_ISO_9797_1_M1_JCB_CRYPTOGRAM Padrão ISO 9797-1 Padding Method 1. Como descrito em JCB IC Card Specification, Version 2.0 - October, 2012.
[in]	szMacIK	Nome da chave dentro do HSM que será utilizada para gerar o MAC.
[in]	pbMacNONCE	Buffer contendo o material diversificador utilizado na geração do MAC, deve ter tamanho DES_BLOCK.
[in]	szPAN	PAN (Primary Account Number).
[in]	pbSEQ	Buffer de tamanho EFT_EMV_SDA_SEQ_LEN contendo o SEQ (PAN Sequence Number).
[in]	dwDataLen	Tamanho do buffer apontado por pbData.
[in]	pbData	Buffer de tamanho especificado por dwDataLen contendo os dados que serão utilizados na encriptação/geração do MAC.
[in,out]	pdwEncDataLen	Ponteiro para um DWORD que contém o tamanho do buffer apontado por pbEncData.
[out]	pbEncData	Buffer que conterá os dados encriptados. Pode ser passado NULL para recuperar o tamanho necessário de pdwEncDataLen, que será retornado em pdwEncDataLen.
[out]	pbMAC	Buffer de tamanho DES_BLOCK que conterá o MAC gerado. Pode ser NULL se szMacIK e pbMacNONCE forem NULL.
[in]	dwParam	Reservado para uso futuro (deve ser 0).

Retorna

0 (ZERO) se a função for bem sucedida.
Consulte a seção Códigos de Retorno sobre outros valores.

DGenerateEMV_CSR()

int AAP_API DGenerateEMV_CSR	(	HSESSIONCTX	hSession,
		BYTE	bOP,
		char *	szIK,
		BYTE *	pbTrackNum,
		BYTE *	pbServiceID,
		BYTE *	pbIssuerID,
		BYTE *	pbExpDate,
		DWORD *	pdwCSRLen,
		BYTE *	pbCSR,
		DWORD	dwParam
	)

#include <dinamo.h>

Gera CSR (Certificate Signing Request) do Emissor.

Obsoleto(a):

Utilize a API DGenerateEMV_CSREx().

Parâmetros

[in]	hSession	Contexto adquirido através da função DOpenSession().
[in]	bOP	Tipo da operação a ser aplicada de acordo com a tabela abaixo. Valor Significado EFT_EMV_OP_CSR_VISA Padrão de processo VISA. O buffer pbCSR conterá CSR + HASH. Sendo HASH de tamanho EFT_EMV_CSR_VISA_HASH_SIZE. EFT_EMV_OP_CSR_MASTER Padrão de processo MASTERCARD. O buffer pbCSR conterá CSR + HASH. Sendo HASH de tamanho EFT_EMV_CSR_MASTER_HASH_SIZE. EFT_EMV_OP_CSR_ELO Padrão de processo ELO. O buffer pbCSR conterá o CSR.
[in]	szIK	Nome da chave dentro do HSM que será utilizada para gerar o CSR (Chave do Emissor).
[in]	pbTrackNum	Buffer de tamanho EFT_EMV_CSR_VISA_TRACK_NUM_LEN contendo o Track Number.
[in]	pbServiceID	Buffer de tamanho EFT_EMV_CSR_VISA_SERVICE_ID_LEN contendo o Service ID.
[in]	pbIssuerID	Buffer de tamanho EFT_EMV_CSR_VISA_ISSUER_ID_LEN contendo o Issuer ID.
[in]	pbExpDate	Buffer de tamanho EFT_EXP_DATE_LEN contendo a data de expiração no formato MMYY. Deve estar no formato ASCII.
[in,out]	pdwCSRLen	Ponteiro para um DWORD que contém o tamanho do buffer apontado por pbCSR.
[out]	pbCSR	Buffer que conterá o CSR. Pode ser passado NULL para recuperar o tamanho necessário de pbCSR, que será retornado em pdwCSRLen.
[in]	dwParam	Reservado para uso futuro (deve ser 0).

Retorna

0 (ZERO) se a função for bem sucedida.
Consulte a seção Códigos de Retorno sobre outros valores.

DGenerateEMV_CSREx()

int AAP_API DGenerateEMV_CSREx	(	HSESSIONCTX	hSession,
		BYTE	bOP,
		char *	szIK,
		BYTE *	pbTrackNum,
		BYTE *	pbServiceID,
		BYTE *	pbIssuerID,
		BYTE *	pbExpDate,
		DBLOB *	pdbCSR,
		BYTE *	pbHash,
		DWORD	dwParam
	)

#include <dinamo.h>

Gera CSR (Certificate Signing Request) do Emissor;

Parâmetros

[in]	hSession	Contexto adquirido através da função DOpenSession().
[in]	bOP	Tipo da operação a ser aplicada de acordo com a tabela abaixo. Valor Significado EFT_EMV_OP_CSR_VISA Padrão de processo VISA. O buffer pdbCSR conterá a CSR e pbHash o HASH. pbHash deverá ser previamente alocado com tamanho EFT_EMV_CSR_VISA_HASH_SIZE. EFT_EMV_OP_CSR_MASTER Padrão de processo MASTERCARD. O buffer pdbCSR conterá a CSR e pbHash o HASH. pbHash deverá ser previamente alocado com EFT_EMV_CSR_MASTER_HASH_SIZE. EFT_EMV_OP_CSR_ELO Padrão de processo ELO. O buffer pdbCSR conterá o CSR. pbHash deverá ser NULL e não será retornado HASH. EFT_EMV_OP_CSR_JCB Padrão de processo JCB. O buffer pdbCSR conterá o CSR. pbHash deverá ser NULL e não será retornado HASH. Segue o padrão JCB CA Interface Guide, 04/01/2014 no file layout descrito na seção 5.1.2.2.
[in]	szIK	Nome da chave dentro do HSM que será utilizada para gerar o CSR (Chave do Emissor).
[in]	pbTrackNum	Buffer de tamanho EFT_EMV_CSR_VISA_TRACK_NUM_LEN contendo o Track Number. Caso EFT_EMV_OP_CSR_JCB seja definido em bOP este campo deverá conter o Serial Number de tamanho EFT_EMV_CSR_VISA_TRACK_NUM_LEN.
[in]	pbServiceID	Buffer de tamanho EFT_EMV_CSR_VISA_SERVICE_ID_LEN contendo o Service ID.
[in]	pbIssuerID	Buffer de tamanho EFT_EMV_CSR_VISA_ISSUER_ID_LEN contendo o Issuer ID.
[in]	pbExpDate	Buffer de tamanho EFT_EXP_DATE_LEN contendo a data de expiração no formato MMYY. Deve estar no formato ASCII.
[out]	pdbCSR	Ponteiro para um DBLOB que conterá o CSR e seu tamanho. O membro pvData deverá ser liberado com DFree() após seu uso.
[out]	pbHash	Buffer que conterá o HASH. Ver tabela em bOP para os valores esperados neste parâmetro.
[in]	dwParam	Reservado para uso futuro (deve ser 0).

Retorna

0 (ZERO) se a função for bem sucedida.
Consulte a seção Códigos de Retorno sobre outros valores.

DGenerateEMV_PinBlock()

int AAP_API DGenerateEMV_PinBlock	(	HSESSIONCTX	hSession,
		BYTE	bOP,
		BYTE *	pbNONCE,
		char *	szTransportKey,
		char *	szISSUER_MK,
		char *	szISSUER_SMC_MK,
		char *	szPAN,
		BYTE *	pbSEQ,
		BYTE *	pbOLD_PB,
		BYTE *	pbNEW_PB,
		BYTE *	pbOutBlock,
		DWORD *	pdwOutBlockLen,
		DWORD	dwParam
	)

#include <dinamo.h>

Gera um segmento de dados para um comando de alteração de PIN (Personal Identification Number) a partir de PIN Blocks. Este comando é tipicamente um APDU (Application Protocol Data Unit) para um cartão ISO-7816.

Parâmetros

[in]	hSession	Contexto adquirido através da função DOpenSession().
[in]	bOP	Identificador do tipo de derivação das chaves de operação para geração do bloco de saída. De acordo com a tabela abaixo. Valor Significado PBC_EMV_PIN_BLOCK_OP_MCHIP Serão geradas chaves operacionais e o bloco de saída de acordo com o "M/Chip 4 Version 1.1 Issuer Guide, chapter 6", "M/Chip Lite 2.1 Card Application Specifications for Debit and Credit, section: 2.7 Secure Messaging" e "M/Chip 4 Version 1.1, Section 7.2.8". PBC_EMV_PIN_BLOCK_OP_VISA Serão geradas chaves operacionais e o bloco de saída de acordo com o "EMV book 2 v4.2, A1.4.1 option A e A1.4.2 option B", "VISA ICC specification 1.4.0 apêndice B.4/EMV Book 2 v4.2 A1.3" - para as chaves de cartão e sessão, respectivamente. "VISA ICC spec 1.4.0, B.3.3 Data Encipherment Calculation, C.11.1 PIN Data Generated Using the Current PIN e C.11.2 PIN Data Generated Without Using the Current PIN", para o bloco. PBC_EMV_PIN_BLOCK_OP_VISA_CRYPTOGRAM Serão geradas chaves operacionais e o bloco de saída de acordo com o "EMV book 2 v4.2, A1.4.1 option A e A1.4.2 option B" - para as chaves de cartão e sessão(a chave de sessão é igual à chave de ICC). "VISA ICC spec 1.4.0, B.3.3 Data Encipherment Calculation, C.11.1 PIN Data Generated Using the Current PIN e C.11.2 PIN Data Generated Without Using the Current PIN", para o bloco. PBC_EMV_PIN_BLOCK_OP_ELO Serão geradas chaves operacionais e blocos de saída de acordo com o Manual ELO Chip Card, CCD Cryptographic Algorithms, A5, seção TDES Keys Usage Algorithm (Script Processing Command Data Encryption in Change PIN script cmd), Algorithm no. 4. PBC_EMV_PIN_BLOCK_OP_JCB Serão geradas chaves operacionais e blocos de saída de acordo com o Manual JCB IC Card Specification, Version 2.0 - October, 2012.
[in]	pbNONCE	Buffer contendo o material diversificador, deve ter tamanho DES_BLOCK. Identificador usado no parâmetro bOP NONCE PBC_EMV_PIN_BLOCK_OP_MCHIP Codifique como determina o manual MCHIP: ATC (2 bytes) ||00||00||00||00||00||00. PBC_EMV_PIN_BLOCK_OP_VISA 00||00||00||00||00||00||ATC (2 bytes). PBC_EMV_PIN_BLOCK_OP_VISA_CRYPTOGRAM 00||00||00||00||00||00||00||00. PBC_EMV_PIN_BLOCK_OP_ELO ATC (2 bytes)||00||00||00||00||00||00 PBC_EMV_PIN_BLOCK_OP_JCB 00||00||00||00||00||00||ATC (2 bytes). JCB IC Card Specification, Version 2.0 - October, 2012.
[in]	szTransportKey	Identificador da chave de transporte dentro do HSM. Esta chave deve ser do tipo DES ou 3DES.
[in]	szISSUER_MK	Identificador da chave "Issuer MK" dentro doHSM. Esta chave deve ser do tipo 3DES 112 bits. Esta chave pode ser igual a chave "Issuer SMC MK" em determinados casos.
[in]	szISSUER_SMC_MK	Identificador da chave "Issuer SMC MK" dentro do HSM. Esta chave deve ser do tipo 3DES 112 bits.
[in]	szPAN	PAN (Primary Account Number).
[in]	pbSEQ	Buffer de tamanho EFT_EMV_SDA_SEQ_LEN contendo o SEQ (PAN Sequence Number). Deve ser em formato ASCII.
[in]	pbOLD_PB	Buffer contendo o PIN Block com o PIN atual. O buffer deve ter o tamanho DES_BLOCK (8 bytes). Deve ser passado NULL caso o PIN Block com a senha atual não seja necessário. São suportados blocos no formato ISO 0/1/2/3.
[in]	pbNEW_PB	Buffer contendo o PIN Block com o novo PIN. O buffer deve ter o tamanho de um DES_BLOCK (8 bytes). São suportados blocos no formato ISO 0/1/2/3.
[out]	pbOutBlock	Buffer que conterá o segmento de dados de saída. Pode se utilizar um buffer de tamanho máximo PBC_EMV_PIN_BLOCK_MAX_OUTPUT que será suficiente para todos os casos.
[in,out]	pdwOutBlockLen	Ponteiro para um DWORD contendo o tamanho do buffer disponibilizado em pbOutPinblock. Ele conterá o tamanho dos dados escritos em pbOutPinblock em caso de sucesso. Em caso de falha conterá o tamanho necessário de pbOutPinblock.
[in]	dwParam	Reservado para uso futuro (deve ser 0).

Retorna

0 (ZERO) se a função for bem sucedida.
Consulte a seção Códigos de Retorno sobre outros valores.

Anotações

Caso o erro D_ERR_OPERATION_FAILED seja retornado, pode ser indicativo de que:

1. A chave de transporte esteja errada;
2. Os PIN Blocks de entrada sejam desconhecidos ou inválidos;
3. Tenha ocorrido falha na derivação das chaves de ICC ou sessão;
4. O tipo de operação não seja válido.

DDeriveEMV_Key()

int AAP_API DDeriveEMV_Key	(	HSESSIONCTX	hSession,
		char *	szSrcKey,
		WORD	wBufferLen,
		BYTE *	pbBuffer,
		BYTE	bOP,
		DWORD	dwAttrib,
		char *	szDstKey,
		HKEYCTX *	phKey,
		DWORD	dwParam
	)

#include <dinamo.h>

DCalculateARPC()

int AAP_API DCalculateARPC	(	HSESSIONCTX	hSession,
		char *	szIssuerMK,
		char *	szPAN,
		BYTE *	pbSEQ,
		BYTE *	pbARQC,
		BYTE *	pbARC,
		BYTE *	pbARPC,
		DWORD	dwParam
	)

#include <dinamo.h>

Calcula um ARPC (Authorisation Response Cryptogram) seguindo o padrão EMV Book 2 (v4.2, 2008), Section 8.2.1, ARPC Method 1.

Parâmetros

[in]	hSession	Contexto adquirido através da função DOpenSession().
[in]	szIssuerMK	Nome da chave do emissor dentro do HSM que será utilizada para gerar o MAC.
[in]	szPAN	PAN (Primary Account Number).
[in]	pbSEQ	Buffer de tamanho EFT_EMV_SDA_SEQ_LEN contendo o SEQ (PAN Sequence Number).
[in]	pbARQC	Buffer de tamanho DES_BLOCK contendo o ARQC (Authorisation Request Cryptogram).
[in]	pbARC	Buffer de tamanho 2 (dois bytes) contendo o ARC (Authorisation Response Code).
[out]	pbARPC	Buffer de tamanho DES_BLOCK que conterá o ARPC gerado.
[in]	dwParam	Reservado para uso futuro (deve ser 0).

Retorna

0 (ZERO) se a função for bem sucedida.
Consulte a seção Códigos de Retorno sobre outros valores.

Anotações

O cálculo do Método 2 do ARPC EMV Book 2 (v4.2, 2008), Section 8.2.1, ARPC Method 2 pode ser feito utilizando a função DGenerateEMV_MAC().

DCalculateARPC_Ex()

int AAP_API DCalculateARPC_Ex	(	HSESSIONCTX	hSession,
		DWORD	dwOp,
		void *	pvInData,
		BYTE *	pbARPC,
		DWORD	dwParam
	)

#include <dinamo.h>

Calcula um ARPC (Authorisation Response Cryptogram).

Parâmetros

[in]	hSession	Contexto adquirido através da função DOpenSession().
[in]	dwOp	Tipo da operação ARPC que será executada. Valor Significado DN_CALC_ARPC_EMV_4_2_M1_ICC Calcula um ARPC no padrão EMV Book 2 (v4.2, 2008), Section 8.2.1, ARPC Method 1 utilizando a chave do emissor dentro do HSM. Utilizar a estrutura DN_CALC_ARPC_EMV_METHOD_1 como parâmetro de pvInData. DN_CALC_ARPC_EMV_4_2_M1_SK Calcula um ARPC no padrão EMV Book 2 (v4.2, 2008), Section 8.2.1, ARPC Method 1 utilizando a chave de sessão derivada da chave do emisor dentro do HSM. Utilizar a estrutura DN_CALC_ARPC_EMV_METHOD_1 como parâmetro de pvInData. DN_CALC_ARPC_EMV_4_2_M2 Calcula um ARPC no padrão EMV Book 2 (v4.2, 2008), Section 8.2.1, ARPC Method 2 utilizando a chave de sessão derivada da chave do emisor dentro do HSM. Utilizar a estrutura DN_CALC_ARPC_EMV_METHOD_2 como parâmetro de pvInData.
[in]	pvInData	Dados de entrada para cálculo do ARPC, de acordo com o descrito no parâmetro dwOP.
[out]	pbARPC	Buffer de tamanho DES_BLOCK que conterá o ARPC gerado.
[in]	dwParam	Reservado para uso futuro (deve ser 0).

Retorna

0 (ZERO) se a função for bem sucedida.
Consulte a seção Códigos de Retorno sobre outros valores.

Anotações

O cálculo do Método 2 do ARPC EMV Book 2 (v4.2, 2008), Section 8.2.1, ARPC Method 2 também pode ser feito utilizando a função DGenerateEMV_MAC().

DMAC_ISO9797_1_Met2()

int AAP_API DMAC_ISO9797_1_Met2	(	DWORD	dwType,
		BYTE *	pbKey,
		DWORD	dwAlg,
		const BYTE *	pbMsg,
		DWORD	dwMsgLen,
		BYTE *	pbMAC
	)

#include <dinamo.h>

Gera um MAC (Message Authentication Code) no padrão ISO/IEC 9797-1 Method 2. Esta operação é feita offline na biblioteca, fora do HSM.

Parâmetros

[in]	dwType	Tipo da operação a ser feita, de acordo com a tabela abaixo.
[in]	pbKey	Buffer contendo a chave utilizada para a geração do MAC, deve ter o tamanho referente ao tipo de chave informado em dwAlg.
[in]	dwAlg	Tipo da chave utilizada na geração do MAC.
[in]	pbMsg	Buffer que passará pelo processo de MAC.
[in]	dwMsgLen	Tamanho do buffer pbMsg.
[out]	pbMAC	Buffer que conterá o MAC gerado, deve ter tamanho DES_BLOCK.

Retorna

0 (ZERO) se a função for bem sucedida.
Consulte a seção Códigos de Retorno sobre outros valores.

DEFTImportKey()

int AAP_API DEFTImportKey	(	HSESSIONCTX	hSession,
		char *	szKeyId,
		int	nKeyAlgId,
		void *	pstKeyParts,
		DWORD	dwParam
	)

#include <dinamo.h>

Importa uma chave por partes em formatos EFT.

Utilizados para importação de chaves por partes:

• DES e 3DES: ZMK (Zone Master Key), também conhecida como ZCMK (Zone Control Master Key) no formato VISA;
• AES: no formato ANSI X9.24.

  Parâmetros

  [in]	hSession	Contexto adquirido através da função DOpenSession().
  [in]	szKeyId	Nome da chave que será importada no HSM.
  [in]	nKeyAlgId	Suporta os seguintes algoritmos. Valor Significado ALG_DES, ALG_3DES_112 ou ALG_3DES_168 Importa uma chave DES no formato descrito no VISA Payment Technology Standards Manual, october 2007 Chapter 7 e Appendix C. Utilizar a estrutura EFT_VISA_KEY_PARTS como parâmetro pstKeyParts. ALG_AES_128, ALG_AES_192 ou ALG_AES_256 Importa uma chave AES no formato ANSI X9.24 (2004), XOR method (KCV descrito no anexo C). Utilizar a estrutura EFT_AES_KEY_PARTS_DATA como parâmetro pstKeyParts.
  [in]	pstKeyParts	Ponteiro para uma estrutura contendo os dados para reconstrução da chave de acordo com o descrito em nKeyAlgId.
  [in]	dwParam	Passar 0. Ou algum dos valores abaixo. Valor Significado DN_EFT_AES_KCV_TYPE_CMAC Utilizado para importação de chaves AES no formato ANSI X9.24, com KCV do tipo CMAC. De acordo com o PCI "PIN Security Requirements".

  Retorna

  0 (ZERO) se a função for bem sucedida.
  Consulte a seção Códigos de Retorno sobre outros valores.

DEFTExportAESKeyParts()

int AAP_API DEFTExportAESKeyParts	(	HSESSIONCTX	hSession,
		BYTE	bKcvType,
		const char *	szKeyId,
		void *	pvKeyParts,
		DWORD	dwReserved
	)

#include <dinamo.h>

DEFTExportKey()

int AAP_API DEFTExportKey	(	HSESSIONCTX	hSession,
		BYTE	bExportMode,
		char *	szKEKId,
		char *	szKeyId,
		BYTE *	pbEncryptedBlock,
		DWORD *	pdwEncryptedBlockLen,
		BYTE *	pbKeyCheckValue,
		DWORD	dwParam
	)

#include <dinamo.h>

DEFTKeKImport()

int AAP_API DEFTKeKImport	(	HSESSIONCTX	hSession,
		BYTE	bOP,
		DWORD	dwAlgId,
		char *	szKeKName,
		char *	szKeyName,
		DWORD	dwAttr,
		BYTE *	pbKCV1,
		BYTE *	pbKCV2,
		BYTE *	pbKCV3,
		BYTE *	pbKCVFinal,
		BYTE *	pbBlob,
		DWORD	dwFlags
	)

#include <dinamo.h>

DEFTExportZPK()

int AAP_API DEFTExportZPK	(	HSESSIONCTX	hSession,
		char *	szKeyId,
		int *	pnKeyAlg,
		int *	pnKeySize,
		EFT_VISA_KEY_PARTS *	pstKeyParts,
		DWORD	dwParam
	)

#include <dinamo.h>

Exporta uma chave ZPK (Zone PIN Key) ou ZMK (Zone Master Key). A exportação é feita por partes, com os seus respectivos valores de verificação como descrito no VISA Payment Technology Standards Manual, october 2007.

Parâmetros

[in]	hSession	Contexto adquirido através da função DOpenSession().
[in]	szKeyId	Nome da chave que será importada no HSM.
[out]	pnKeyAlg	Algoritmo da chave a exportada.
[out]	pnKeySize	Tamanho da chave exportada.
[out]	pstKeyParts	Ponteiro para uma estrutura EFT_VISA_KEY_PARTS que conterá as partes da chave a exportada e seus KCVs (Key Check Value).
[in]	dwParam	As seguintes opções são aceitas. Valor Significado 0 Gera o KCV (Key Check Value) da chave como definido na ANSI X.9.24 com tamanho de 3 bytes. DN_EXP_ZPK_FLAG_FULL_CKS Gera o KCV (Key Check Value) da chave como definido na ANSI X.9.24 com tamanho de 8 bytes.

Retorna

0 (ZERO) se a função for bem sucedida.
Consulte a seção Códigos de Retorno sobre outros valores.

Anotações

Pode ser utilizada para exportação de chaves que sigam o padrão de exportação por partes descrito no documento VISA Payment Technology Standards Manual, october 2007 Chapter 7 e Appendix C. Pode ser utilizado para chaves ZPK (Zone PIN Key), ZMK (Zone Master Key)/ZCMK (Zone Control Master Key), por exemplo.

DEFTGetKcv()

int AAP_API DEFTGetKcv	(	HSESSIONCTX	hSession,
		BYTE	bType,
		const char *	szKeyId,
		BYTE *	pbKcv,
		DWORD *	pdwKcvLen,
		DWORD	dwReserved
	)

#include <dinamo.h>

Parâmetros

[in]	hSession	Contexto adquirido através da função DOpenSession().
[in]	bType	Tipo de chave a ser utilizada para gerar o KCV. Valor Significado DN_EFT_GET_KCV_TYPE_X9_24 Gera o KCV (Key Check Value) da chave como definido na ANSI X.9.24 com tamanho de 3 bytes. DN_EFT_GET_KCV_TYPE_CMAC Gera o KCV (Key Check Value) da chave como definido no PCI PIN Security Requirements com tamanho de 3 bytes.
[in]	szKeyId	Nome da chave que será utilizada para gerar o KCV.
[out]	pbKcv	Ponteiro para um buffer que conterá o KCV gerado. Pode ser NULL para obter o tamanho do KCV em pdwKcvLen.
[in,out]	pdwKcvLen	Tamanho do buffer pbKcv. Ao final da chamada conterá o tamanho do KCV gerado.
[in]	dwReserved	Reservado para uso futuro (deve ser 0).

Retorna

0 (ZERO) se a função for bem sucedida.
Consulte a seção Códigos de Retorno sobre outros valores.

DEFTGenKCVOffline()

int AAP_API DEFTGenKCVOffline	(	DWORD	dwType,
		int	nAlgId,
		const BYTE *	pbKey,
		DWORD	dwKeyLen,
		BYTE *	pbKCV,
		DWORD *	pdwKCVLen,
		DWORD	reserved
	)

#include <dinamo.h>

Gera um KCV (Key Check Value) de uma chave offline.

Parâmetros

[in]	dwType	Tipo do KCV. Valor Significado DN_EFT_GEN_OFFLINE_KCV_TYPE_X9_24 Gera o KCV (Key Check Value) da chave como definido na ANSI X.9.24 com tamanho de DN_EFT_KCV_TYPE_X9_24_LEN. DN_EFT_GEN_OFFLINE_KCV_TYPE_CMAC Gera o KCV (Key Check Value) da chave como definido no PCI PIN Security Requirements com tamanho de DN_EFT_KCV_TYPE_CMAC_LEN.
[in]	nAlgId	Algoritmo da chave. Atualmente aceita apenas DES, 3DES e AES.
[in]	pbKey	Ponteiro para o buffer que contém a chave.
[in]	dwKeyLen	Tamanho da chave.
[out]	pbKCV	Ponteiro para o buffer que conterá o KCV gerado.
[in,out]	pdwKCVLen	Tamanho do buffer pbKCV. Ao final da chamada conterá o tamanho do KCV gerado.
[in]	reserved	Reservado para uso futuro (deve ser 0).

Retorna

0 (ZERO) se a função for bem sucedida.
Consulte a seção Códigos de Retorno sobre outros valores.

DEFTExportTR31()

int AAP_API DEFTExportTR31	(	HSESSIONCTX	hSession,
		const char *	szKBPK,
		const char *	szKey,
		void *	pvReserved,
		WORD	wUsage,
		BYTE	bMode,
		BYTE	bExport,
		BYTE *	pbOutBlock,
		DWORD *	pdwOutBlockLen,
		DWORD	dwParam
	)

#include <dinamo.h>

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

Parâmetros

[in]	hSession	Contexto adquirido através da função DOpenSession().
[in]	szKBPK	Nome da chave KBPK (Key Block Protection Key) utilizada para derivar as chaves de encriptação e autenticação.
[in]	szKey	Nome da chave que será exportada do HSM.
[in]	pvReserved	Reservado para uso futuro (deve ser NULL).
[in]	wUsage	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 EFT_ME_TR31_EXP_USAGE_AUTO Define o identificador automaticamente. Os seguintes valores são utilizados: EFT_ME_TR31_EXP_USAGE_D0 para chave simétrica e EFT_ME_TR31_EXP_USAGE_D1 para chave assimétrica. EFT_ME_TR31_EXP_USAGE_B0 BDK Base Derivation Key EFT_ME_TR31_EXP_USAGE_B1 Initial DUKPT Key EFT_ME_TR31_EXP_USAGE_B2 Base Key Variant Key EFT_ME_TR31_EXP_USAGE_C0 CVK Card Verification Key EFT_ME_TR31_EXP_USAGE_D0 Symmetric Key for Data Encryption EFT_ME_TR31_EXP_USAGE_D1 Asymmetric Key for Data Encryption EFT_ME_TR31_EXP_USAGE_D2 Data Encryption Key for Decimalization Table EFT_ME_TR31_EXP_USAGE_E0 EMV/chip Issuer Master Key: Application cryptograms EFT_ME_TR31_EXP_USAGE_E1 EMV/chip Issuer Master Key: Secure Messaging for Confidentiality EFT_ME_TR31_EXP_USAGE_E2 EMV/chip Issuer Master Key: Secure Messaging for Integrity EFT_ME_TR31_EXP_USAGE_E3 EMV/chip Issuer Master Key: Data Authentication Code EFT_ME_TR31_EXP_USAGE_E4 EMV/chip Issuer Master Key: Dynamic Numbers EFT_ME_TR31_EXP_USAGE_E5 EMV/chip Issuer Master Key: Card Personalization EFT_ME_TR31_EXP_USAGE_E6 EMV/chip Issuer Master Key: Other EFT_ME_TR31_EXP_USAGE_I0 Initialization Vector (IV) EFT_ME_TR31_EXP_USAGE_K0 Key Encryption or wrapping EFT_ME_TR31_EXP_USAGE_K1 TR-31 Key Block Protection Key EFT_ME_TR31_EXP_USAGE_K2 TR-34 Asymmetric key EFT_ME_TR31_EXP_USAGE_K3 Asymmetric key for key agreement/key wrapping EFT_ME_TR31_EXP_USAGE_M0 ISO 16609 MAC algorithm 1 (using TDEA) EFT_ME_TR31_EXP_USAGE_M1 ISO 9797-1 MAC Algorithm 1 EFT_ME_TR31_EXP_USAGE_M2 ISO 9797-1 MAC Algorithm 2 EFT_ME_TR31_EXP_USAGE_M3 ISO 9797-1 MAC Algorithm 3 EFT_ME_TR31_EXP_USAGE_M4 ISO 9797-1 MAC Algorithm 4 EFT_ME_TR31_EXP_USAGE_M5 ISO 9797-1:1999 MAC Algorithm 5 EFT_ME_TR31_EXP_USAGE_M6 ISO 9797-1:2011 MAC Algorithm 5/CMAC EFT_ME_TR31_EXP_USAGE_M7 HMAC EFT_ME_TR31_EXP_USAGE_M8 ISO 9797-1:2011 MAC Algorithm 6 EFT_ME_TR31_EXP_USAGE_P0 PIN Encryption EFT_ME_TR31_EXP_USAGE_S0 Asymmetric key pair for digital signature EFT_ME_TR31_EXP_USAGE_S1 Asymmetric key pair, CA key EFT_ME_TR31_EXP_USAGE_S2 Asymmetric key pair, nonX9.24 key EFT_ME_TR31_EXP_USAGE_V0 PIN verification, KPV, other algorithm EFT_ME_TR31_EXP_USAGE_V1 PIN verification, IBM 3624 EFT_ME_TR31_EXP_USAGE_V2 PIN Verification, VISA PVV EFT_ME_TR31_EXP_USAGE_V3 PIN Verification, X9.132 algorithm 1 EFT_ME_TR31_EXP_USAGE_V4 PIN Verification, X9.132 algorithm 2
[in]	bMode	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 EFT_ME_TR31_EXP_MODE_AUTO Define o identificador de modo de uso automaticamente. O seguinte valor é utilizado EFT_ME_TR31_EXP_MODE_N. EFT_ME_TR31_EXP_MODE_B Ambos Encriptação & Decriptação / Wrap & Unwrap EFT_ME_TR31_EXP_MODE_C Ambos Geração & Verificação EFT_ME_TR31_EXP_MODE_D Decriptação / Unwrap Apenas EFT_ME_TR31_EXP_MODE_E Encriptação / Wrap Apenas EFT_ME_TR31_EXP_MODE_G Geração Apenas EFT_ME_TR31_EXP_MODE_N Sem restrições especiais (exceto as restrições definidas pelo identificador de uso da chave) EFT_ME_TR31_EXP_MODE_S Assinatura Apenas EFT_ME_TR31_EXP_MODE_T Ambos Assinatura & Decriptação EFT_ME_TR31_EXP_MODE_V Verificação Apenas EFT_ME_TR31_EXP_MODE_X Chave usada para derivar outra(s) chave(s) EFT_ME_TR31_EXP_MODE_Y Chave usada para criar variantes de chaves
[in]	bExport	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 EFT_ME_TR31_EXP_AUTO Define o identificador de exportabilidade automaticamente. O seguinte valor é utilizado EFT_ME_TR31_EXP_X9_24. 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. 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. 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.
[out]	pbOutBlock	Buffer que conterá o key block.
[in,out]	pdwOutBlockLen	Ponteiro para o tamanho do buffer passado pbOutBlock. Após o retorno da API conterá o tamanho real do key block armazenado em pbOutBlock. Caso o tamanho não seja o suficiente, essa variável conterá o tamanho necessário de pbOutBlock.
[in]	dwParam	Reservado para uso futuro (deve ser 0).

Retorna

0 (ZERO) se a função for bem sucedida.
Consulte a seção Códigos de Retorno sobre outros valores.

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.c.

DEFTImportTR31()

int AAP_API DEFTImportTR31	(	HSESSIONCTX	hSession,
		const char *	szKBPK,
		const char *	szKey,
		DWORD	dwKeyAttributes,
		BYTE *	pbKeyBlock,
		DWORD	dwKeyBlockLen,
		DWORD	dwParam
	)

#include <dinamo.h>

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

Parâmetros

[in]	hSession	Contexto adquirido através da função DOpenSession().
[in]	szKBPK	Nome da chave KBPK (Key Block Protection Key) utilizada para derivar as chaves de encriptação e autenticação.
[in]	szKey	Nome da chave que será importada no HSM.
[in]	dwKeyAttributes	Parâmetros adicionais da chave. Veja as opções na função DGenerateKey().
[in]	pbKeyBlock	Buffer contendo o key block.
[in]	dwKeyBlockLen	Tamanho do buffer passado pbKeyBlock.
[in]	dwParam	Reservado para uso futuro (deve ser 0).

Retorna

0 (ZERO) se a função for bem sucedida.
Consulte a seção Códigos de Retorno sobre outros valores.

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

Exemplos

export_import_tr31.c.