API C/C++
HSM Dinamo
|
Operações para Transferência Eletrônica de Fundos.
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:
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.
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.
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.
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
Visa
Mastercard
Elo
JCB
Outros
Há três formas de geração e verificação de CVV (Card Verification Value) no HSM:
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.
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.
Estão definidos três modos de geração de PIN por derivação:
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.
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.
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.
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).
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).
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:
No HSM:
É 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.
Key block contém os dados da chave exportada. Este bloco é divido em 3 partes:
Operações para Transferência Eletrônica de Fundos. Mais...
Definições e Macros | |
#define | DN_CALC_ARPC_EMV_4_2_M1_ICC (1) |
#define | DN_CALC_ARPC_EMV_4_2_M1_SK (2) |
#define | DN_CALC_ARPC_EMV_4_2_M2 (3) |
#define | DN_EFT_AES_KCV_TYPE_CMAC (1) |
#define | DN_EFT_GET_KCV_TYPE_X9_24 (1) |
#define | DN_EFT_GET_KCV_TYPE_CMAC (2) |
#define | DN_EXP_ZPK_FLAG_FULL_CKS (1) |
#define | DN_EFT_GET_KCV_MAX_LEN (3) |
#define | DN_EFT_GEN_OFFLINE_KCV_TYPE_X9_24 (1) |
#define | DN_EFT_GEN_OFFLINE_KCV_TYPE_CMAC (2) |
#define | DN_EFT_KCV_TYPE_X9_24_LEN (3) |
#define | DN_EFT_KCV_TYPE_CMAC_LEN (3) |
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) |
#define DN_CALC_ARPC_EMV_4_2_M1_ICC (1) |
#include <dinamo.h>
#define DN_CALC_ARPC_EMV_4_2_M1_SK (2) |
#include <dinamo.h>
#define DN_CALC_ARPC_EMV_4_2_M2 (3) |
#include <dinamo.h>
#define DN_EFT_AES_KCV_TYPE_CMAC (1) |
#include <dinamo.h>
KCV do tipo CMAC. De acordo com o PCI "PIN Security Requirements".
#define DN_EFT_GET_KCV_TYPE_X9_24 (1) |
#include <dinamo.h>
Exporta uma chave AES por partes no formato ANSI X9.24.
[in] | hSession | Contexto adquirido através da função DOpenSession(). | ||||||
[in] | bKcvType | Tipo de KCV a ser utilizado na exportação.
| ||||||
[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). |
#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.
#define DN_EXP_ZPK_FLAG_FULL_CKS (1) |
#include <dinamo.h>
#define DN_EFT_GET_KCV_MAX_LEN (3) |
#include <dinamo.h>
Tamanho máximo do KCV (Key Check Value) gerado.
#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.
#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.
#define DN_EFT_KCV_TYPE_X9_24_LEN (3) |
#include <dinamo.h>
Tamanho do KCV (Key Check Value) gerado.
#define DN_EFT_KCV_TYPE_CMAC_LEN (3) |
#include <dinamo.h>
Tamanho do KCV (Key Check Value) gerado.
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.
[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.
| ||||||||||||
[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). |
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.
[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). |
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().
[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). |
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.
[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.
| ||||||||
[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). |
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().
[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). |
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.
[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). |
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).
[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.
|
#include <dinamo.h>
Gera o nome da BDK a partir de uma KSI (Key Serial Identification).
[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). |
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.
[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). |
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.
[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). |
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.
[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). |
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.
[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). |
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).
[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). |
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).
[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.
| ||||
[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). |
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).
[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.
| ||||||
[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). |
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>
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.
[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.
| ||||||||||||||||||||||
[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.
|
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.
[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). |
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).
[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). |
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).
[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.
| ||||||||||||||||
[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.
| ||||||||||||||||
[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). |
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.
[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.
| ||||||||
[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). |
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;
[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.
| ||||||||||
[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). |
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.
[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.
| ||||||||||||
[in] | pbNONCE | Buffer contendo o material diversificador, deve ter tamanho DES_BLOCK.
| ||||||||||||
[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). |
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>
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.
[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). |
int AAP_API DCalculateARPC_Ex | ( | HSESSIONCTX | hSession, |
DWORD | dwOp, | ||
void * | pvInData, | ||
BYTE * | pbARPC, | ||
DWORD | dwParam ) |
#include <dinamo.h>
Calcula um ARPC (Authorisation Response Cryptogram).
[in] | hSession | Contexto adquirido através da função DOpenSession(). | ||||||||
[in] | dwOp | Tipo da operação ARPC que será executada.
| ||||||||
[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). |
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.
[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. |
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:
[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.
| ||||||
[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.
|
int AAP_API DEFTExportAESKeyParts | ( | HSESSIONCTX | hSession, |
BYTE | bKcvType, | ||
const char * | szKeyId, | ||
void * | pvKeyParts, | ||
DWORD | dwReserved ) |
#include <dinamo.h>
int AAP_API DEFTExportKey | ( | HSESSIONCTX | hSession, |
BYTE | bExportMode, | ||
char * | szKEKId, | ||
char * | szKeyId, | ||
BYTE * | pbEncryptedBlock, | ||
DWORD * | pdwEncryptedBlockLen, | ||
BYTE * | pbKeyCheckValue, | ||
DWORD | dwParam ) |
#include <dinamo.h>
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>
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.
[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.
|
int AAP_API DEFTGetKcv | ( | HSESSIONCTX | hSession, |
BYTE | bType, | ||
const char * | szKeyId, | ||
BYTE * | pbKcv, | ||
DWORD * | pdwKcvLen, | ||
DWORD | dwReserved ) |
#include <dinamo.h>
[in] | hSession | Contexto adquirido através da função DOpenSession(). | ||||||
[in] | bType | Tipo de chave a ser utilizada para gerar o KCV.
| ||||||
[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). |
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.
[in] | dwType | Tipo do KCV.
| ||||||
[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). |
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.
[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.
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
[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.
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
[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.
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
[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). |
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 |
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.
[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). |
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 |