Академический Документы
Профессиональный Документы
Культура Документы
Copyright
Copyright
All intellectual property is protected by copyright. All trademarks and product names used or referred to are the copyright of their respective owners. No part of this document may be reproduced, stored in a retrieval system or transmitted in any form or by any means, electronic, mechanical, chemical, photocopy, recording or otherwise without the prior written permission of SafeNet. SafeNet makes no representations or warranties with respect to the contents of this document and specifically disclaims any implied warranties of merchantability or fitness for any particular purpose. Furthermore, SafeNet reserves the right to revise this publication and to make changes from time to time in the content hereof without the obligation upon SafeNet to notify any person or organization of any such revisions or changes. SafeNet invites constructive comments on the contents of this document. These comments, together with your personal and/or company details, should be sent to the address below. SafeNet, Inc. 4690 Millennium Drive Belcamp, Maryland 21017 USA
We have attempted to make this document complete, accurate, and useful, but we cannot guarantee it to be perfect. When we discover errors or omissions, or they are brought to our attention, we endeavor to correct them in succeeding releases of the product. SafeNet, Inc. is not responsible for any direct or indirect damages or loss of business resulting from inaccuracies or omissions. The specifications contained in this document are subject to change without notice. SafeNet HSM Payment (SHP) is a trademark of SafeNet, Inc. All other product names referenced herein are trademarks or registered trademarks of their respective manufacturers. Part Number 003198-002, Revision T Software versions 1.1 Revision
O P
Action/Change
This revision was skipped for Document Control reasons. SHP 1.1 Release. MarkII Programmers Guide updated for: 1. Card Issuance Integration 2. Host Key rationalization 3. Network Key Transfer Host Functions This revision was skipped for Document Control reasons. Functionality enhanced for FM=2 in function EE2048 and EE2058. This revision was skipped for Document Control reasons. Updated for a few host functions
Date
June 2009 June 2009
Q R
S T
SafeNet, Inc.
Copyright
Certifications
FCC Compliance
SafeNet HSM Payment device has been tested and found to comply with the limits for a Class B digital device, pursuant to part 15 of the FCC Rules.
Reorient or relocate the receiving antenna. Increase the separation between the equipment and receiver. Connect the equipment into an outlet on a circuit different from that to which the receiver is connected. Consult the dealer or an experienced radio/TV technician for help.
To ensure FCC compliance only devices also known to comply should be connected to the SHP (Ethernet Connect). If such devices do not feature their own cables, shielded cables must be used.
SafeNet, Inc.
ii
Table of Contents
Table of Contents
Copyright.............................................................................................................................................................. i Certifications ............................................................................................................................................................. ii FCC Compliance...................................................................................................................................................... ii FCC Notice to Users ................................................................................................................................................ ii WEEE and RoHS Compliance .................................................................................................................................. ii Table of Contents .............................................................................................................................................. iii Preface............................................................................................................................................................... vii Where to Find Information ?................................................................................................................................... vii Contacting Technical Support ................................................................................................................................ vii Part 1 ................................................................................................................................................................... 1 Chapter 1 Introduction ..................................................................................................................................... 3 Overview ...................................................................................................................................................................3 Product Architecture......................................................................................................................................... 4 Design Paradigm .......................................................................................................................................................4 Implementation.........................................................................................................................................................4 Using the ProtectToolkit EFT APIs ..........................................................................................................................4 Common Terms and Phraseology.............................................................................................................................4 Encryption Notation..................................................................................................................................................4 Supplemental Documentation ..................................................................................................................................5 Host Function Overview ...........................................................................................................................................5 Chapter 2 Function Construction .................................................................................................................... 7 Host Function Overview ...........................................................................................................................................7 Function Message Formats .......................................................................................................................................7 Data Item Representation in Request/Response Messages .........................................................................................7 Common Message Header Formats ..........................................................................................................................8 Transmission of Two-byte Integers ...........................................................................................................................8 Function Modifier Values ..........................................................................................................................................8 Variable Length Fields in Function Request and Response Messages ......................................................................9 Example Field Formats......................................................................................................................................... 11 Variants.................................................................................................................................................................. 13 KM Variants........................................................................................................................................................ 13 SafeNet Variant Scheme ....................................................................................................................................... 13 Atalla Variant Scheme.......................................................................................................................................... 14 AS2805.6.1 Variant Scheme ............................................................................................................................... 14 Public Key Verification Code.................................................................................................................................. 15 The Key Specifier Function Field.......................................................................................................................... 15 Key Specifier Formats for HSM-stored Keys.......................................................................................................... 16 Key Specifier Formats for Host-stored Keys........................................................................................................... 17 Usage Notes for Key Specifiers In Host Functions .................................................................................................. 24 PIN Block Formats............................................................................................................................................... 25 Function Identifier Control .................................................................................................................................... 26 Message Meta-function Format ............................................................................................................................. 26 Chapter 3 The Metafunction........................................................................................................................... 27 Message Meta-function Format ............................................................................................................................. 27 Chapter 4 HSM Status Functions ................................................................................................................... 31 The Error Log ......................................................................................................................................................... 31 Chapter 5 KM Change Functions ................................................................................................................... 39 Chapter 6 Transfer Functions......................................................................................................................... 45 Chapter 7 HSM Software Upgrade Functions ............................................................................................... 55 Chapter 8 EFT Terminal Functions ................................................................................................................ 61 Initial Session Key Generation ............................................................................................................................... 66 Rollover Session Key Generation ........................................................................................................................... 69 Docutel Key Generation ......................................................................................................................................... 71
SafeNet, Inc.
iii
Table of Contents
3624 Comms Key Generation................................................................................................................................ 72 Terminal Verification ............................................................................................................................................. 73 DUKPT BDK Generation......................................................................................................................................... 74 Chapter 9 Remote ATM Initialization Functions.......................................................................................... 77 Overview ................................................................................................................................................................ 77 Key Types ............................................................................................................................................................... 78 Authentication of public keys ................................................................................................................................ 78 Storage of RSA keys ............................................................................................................................................... 78 Chapter 10 Interchange Functions................................................................................................................ 93 Initial Session Key Generation ............................................................................................................................... 94 Receive Initial Session Key..................................................................................................................................... 97 Rollover Session Key Generation ......................................................................................................................... 101 Receive Rollover Session Key ............................................................................................................................... 103 Chapter 11 PIN Management Functions .....................................................................................................105 Host Stored PVK Management ............................................................................................................................ 105 PIN Encryption..................................................................................................................................................... 107 PIN Translation.................................................................................................................................................... 110 PIN Verification.................................................................................................................................................... 112 PINKEY PIN Translation...................................................................................................................................... 114 Base Key PIN Verification .................................................................................................................................... 115 Base Key PIN Verification - Variable Length ....................................................................................................... 116 PIN Offset Generation........................................................................................................................................... 117 Chapter 12 Online Banking Module Functions..........................................................................................129 Summary of Online Banking Module Functions .............................................................................................. 129 Online Banking Module Password Restrictions................................................................................................... 129 Function Field Constructs .................................................................................................................................... 130 Data Item Representation in Request/Response Messages .................................................................................... 130 EPB Processing Unit .......................................................................................................................................... 130 CTPV Processing Unit ........................................................................................................................................ 131 Chapter 13 Visa Functions............................................................................................................................151 Visa Overview ...................................................................................................................................................... 151 Key Management Operations .............................................................................................................................. 153 Visa Function Overview ....................................................................................................................................... 155 Visa 3DES Support ............................................................................................................................................... 156 Diebold Table Support .......................................................................................................................................... 163 SEED Translation ................................................................................................................................................. 167 Chapter 14 MAC Management Functions ...................................................................................................171 MAC Generation .................................................................................................................................................. 172 Terminal Master Key MAC Generation................................................................................................................ 178 Chapter 15 Data Ciphering Functions.........................................................................................................179 3624 B-Key Enciphering...................................................................................................................................... 190 3624 B-Key Deciphering...................................................................................................................................... 191 Chapter 16 MasterCard Functions...............................................................................................................193 MasterCard Security Requirements ..................................................................................................................... 193 Facilities for MasterCard Support......................................................................................................................... 193 MasterCard 3DES Support.................................................................................................................................... 194 Chapter 17 American Express Functions ....................................................................................................201 Card Security Code Keys (CSCK) .......................................................................................................................... 201 Chapter 18 PIN Issuance Functions.............................................................................................................207 PIN Issuance Overview ........................................................................................................................................ 207 Separating PIN Generation and Printing............................................................................................................. 207 Chapter 19 EMV Functions ...........................................................................................................................215 Chapter 20 CEPS Functions ..........................................................................................................................267 Chapter 21 AS2805.6.3 Support Functions ................................................................................................275 Chapter 22 Key Block ....................................................................................................................................281 Chapter 23 ZKA Functions............................................................................................................................285
SafeNet, Inc.
iv
Table of Contents
Session Key Derivation......................................................................................................................................... 285 Pin Verification .................................................................................................................................................... 285 Message Authentication Functions...................................................................................................................... 287 Key Management Functions ............................................................................................................................... 287 Chapter 24 Administration Functions ........................................................................................................303 Chapter 25 ABI Debit Card Functions .........................................................................................................305 Chapter 26 Superceded Functions...............................................................................................................309 Chapter 27 MasterCard PayPass and Visa payWave ..................................................................................359 MasterCard PayPass............................................................................................................................................. 359 Visa payWave....................................................................................................................................................... 359 Chapter 28 Network Key Transfer ...............................................................................................................365 Network Key Transfer .......................................................................................................................................... 365 New Key ............................................................................................................................................................ 365 Part 2 ...............................................................................................................................................................369 Chapter 29 Card Issuer Key Management and Operational Requirements ............................................371 Overview .............................................................................................................................................................. 371 ICC Initialization .................................................................................................................................................. 371 Issuer Key Pair Initialization .............................................................................................................................. 371 Static Data Authentication.................................................................................................................................. 371 Dynamic Data Authentication............................................................................................................................. 371 Offline PIN Encipherment................................................................................................................................... 372 Reference PIN Management................................................................................................................................ 372 Key Management ................................................................................................................................................. 372 Function Construction ......................................................................................................................................... 373 Chapter 30 PIN Management Functions .....................................................................................................375 Host Stored PVK Management ............................................................................................................................ 375 Chapter 31 Card Issuer Functions ...............................................................................................................379 Key Types ............................................................................................................................................................. 379 Issuer Key Management ...................................................................................................................................... 380 ICC Key Management .......................................................................................................................................... 396 Dynamic Data Authentication............................................................................................................................. 410 PIN Encipherment................................................................................................................................................ 412 PIN Initialization.................................................................................................................................................. 414 Chapter 32 MasterCard PayPass and Visa payWave ..................................................................................423 Visa payWave:...................................................................................................................................................... 423 MasterCard PayPass:............................................................................................................................................ 423 Part 3 ...............................................................................................................................................................429 Appendix A IBM 3624 PIN Verification Method.........................................................................................431 Definitions ............................................................................................................................................................ 431 Verification of a Derived PIN................................................................................................................................ 431 Verification of a Random PIN .............................................................................................................................. 432 Selecting Significant Offset Digits......................................................................................................................... 433 Appendix B EFT Terminal Functions ...........................................................................................................435 Appendix C Card Issuance Function Examples...........................................................................................437 Appendix D PIN Management Function Examples.....................................................................................439 Appendix E EMV Function Examples............................................................................................................441 Appendix F American Express Account Blocks ..........................................................................................447 How To Form An Account Block ......................................................................................................................... 447 34 Cards ............................................................................................................................................................... 447 Appendix G American Express Examples.....................................................................................................449 Test Program Output ........................................................................................................................................... 449 Appendix H Function Matrix - MarkII .........................................................................................................453 Appendix I SHP Toolkit..................................................................................................................................459 SHP Toolkit MK2.................................................................................................................................................. 459
SafeNet, Inc.
Table of Contents
Structures Representing Individual Key Specifiers................................................................................................ 459 Structure Representing All Key Specifiers............................................................................................................ 462 Structure Representing Variable Length Character Arrays. .................................................................................. 463 API Helper Functions ......................................................................................................................................... 463 Error Translation Functions ............................................................................................................................... 464 Optional IO Fields in Functions........................................................................................................................... 464 SHP Toolkit MK2 Functions............................................................................................................................... 464 SHP Toolkit CI ...................................................................................................................................................... 494 Appendix J Error Codes..................................................................................................................................501 Appendix K References MarkII and CI ......................................................................................................503 MarkII References ................................................................................................................................................ 503 Card Issuance References..................................................................................................................................... 504 Appendix L Glossary.......................................................................................................................................507 Appendix M Function List MarkII and Card Issuance.............................................................................511
SafeNet, Inc.
vi
Preface
Preface
This document, together with the ProtectHost White Card Issuance and the Mark II function sets, describes the cryptographic and key management functionality of the functions in support of card issuers. This Guide covers standard Mark II and Card Issuance functionality. It provides a complete function reference for all functions that make up the Mark II and Card issuance function set.
Appendix A - IBM 3624 PIN Verification Method Appendix B - EFT Terminal Functions Appendix C - Card Issuance Function Examples Appendix D - PIN Management Function Examples Appendix E - EMV Function Examples Appendix F - American Express Account Blocks Appendix G - American Express Examples Appendix H - Function Matrix (MarkII) Appendix I - SHP Toolkit Appendix J - Error Codes Appendix K - References Appendix L - Glossary Appendix M - Function list
SafeNet, Inc.
vii
Preface
SafeNet, Inc.
viii
Part 1
______________________________________________________________________
SafeNet, Inc.
SafeNet, Inc.
Chapter 1 Introduction
Chapter 1 Introduction
Overview
This Guide covers standard Mark II and Card Issuance functionality. It provides a complete function reference for all functions that make up the Mark II and Card issuance function set. These function sets, which are supported on SafeNet Hardware Security Modules (HSMs), may be utilized by EFT network designers to implement a variety of key and PIN management schemes. Mark II and Card Issuance functions are available as standard on the following SafeNet HSM products. These are the; ProtectHost EFT (referred to as SHP, hereafter) ProtectHost White Mark II ProtectHost White Card Issuance ProtectServer Orange The Mark II and Card Issuance function set is not implemented in its entirety on each of these HSM products. Rather, a unique subset of functions is provided to suit HSM design and application requirements in each case. Additionally, further functions may also be available. SafeNet also develops custom functions to meet the specific needs of particular customers. Details can be found in a customization guide supplied with the product, where applicable. The SHP product provides an application programming interface in the C programming language. SHP Toolkit MK2, is a component within this product, that allow third parties to easily interface to the SHP, HSM and ProtectServer Orange security modules running the MarkII and Card Issuance software. The SHP Toolkit MK2 is also described in this Guide.
SafeNet, Inc.
Chapter 1 Introduction
Product Architecture
Design Paradigm
The paradigm used for the design of the MarkII/ Card Issuance hardware security module (HSM) is of an issuer computer with connected card personalization system. Sensitive values generated by the HSM (card keys and PINs) are passed to the host in encrypted form using a transport key. The sensitive values are then passed to the card personalization system.
Implementation
Using the ProtectToolkit EFT APIs
It is possible to simplify system implementation by making use of the SafeNet product ProtectToolkit EFT. ProtectToolkit EFT offers host applications all of the available functions on the ProtectHost White Card Issuer HSM, in C callable form. The ProtectToolkit EFT product is made up of two application programming interfaces (APIs), SHP Toolkit CI and SHP Toolkit MK2. This is shown in the diagram below.
SHP Toolkit MK2 implements C calls for those functions that are available on the Mark II, as well as the Card Issuer HSM. SHP Toolkit CI implements C calls for those functions that are available on the Card Issuer HSM alone. The C call function prototypes for each of the available functions can be found at the end of their function descriptions, in this guide. The sections are labelled with the applicable ProtectToolkit EFT name: SHP Toolkit CI and SHP Toolkit MK2 in this guide.
Encryption Notation
The notation used for encryption and decryption is as follows: eK(D) where data D is encrypted under the key K. dK(D) where data D is decrypted with the key K.
SafeNet, Inc.
Chapter 1 Introduction
Supplemental Documentation
The Programmers Guide is supplemental to the following documentation: For SafeNet HSM Payment (SHP) MarkII and Card Issuance users: MarkII Communications Guide MarkII Installation Guide - SHP MarkII Console User Guide HSM Software Loader Help
For Customizations: For customizations, specific information may be available in the form of a customization guide.
SafeNet, Inc.
Chapter 1 Introduction
HSM product running the Card Issuance software. A D indicates that the function is supported in the product. A U indicates that it is not supported in the product. The specification of the function follows the title. For those functions that are supported in the SHP Toolkit MK2, the function definition is provided following the specification, as illustrated below.
SafeNet, Inc.
SafeNet, Inc.
Each field has an associated attribute and its length in bytes. The attributes are defined as follows: Attribute b h d x B64 B512 P-key K-Spec S-Block Description Represents a binary digit. These are always in multiples of 8. Represents a hexadecimal digit. These are always grouped in pairs. Represents a BCD digit. These are always in pairs. Represents a binary byte. Represents a 64 bit field. Represents a 512 bit field. Represents an RSA public key. Key specifier. A value that specifies the length, format and index for a key. Represents a variable length, DEA 2 enciphered data Block
Note that with some functions the length of the function code may be longer than one byte. Function Response Headers Each function response begins with a header of the form: Description Function Code Return Code Length 1 1 Attribute h h
Note that with some functions the length of the function code may be longer than one byte.
SafeNet, Inc.
Global Method Selected Legacy Legacy Legacy ECB ECB ECB CBC CBC CBC Legacy Legacy Legacy ECB ECB ECB CBC CBC CBC
FM xy
Disabled
0000 0000 0001 0000 0010 0000 0000 0000 0001 0000 0010 0000 0000 0000 0001 0000 0010 0000 0000 0000 0001 0000 0010 0000 0000 0000 0001 0000 0010 0000 0000 0000 0001 0000 0010 0000
Legacy method ECB method CBC method ECB method ECB method CBC method CBC method ECB method CBC method Legacy method Error (conflict with global method). Error code : 0x24 FN_INVALID_FN_MODIFIER Error (conflict with global method). Error code : : 0x24 FN_INVALID_FN_MODIFIER ECB method ECB (No conflict with global method) Error (conflict with global method). Error code : : 0x24 FN_INVALID_FN_MODIFIER CBC method Error (conflict with global method). Error code : : 0x24 FN_INVALID_FN_MODIFIER CBC (No conflict with global method)
SafeNet, Inc.
Chapter 2 Function Construction 00 7F 8000 BFFF C00000 DFFFFF E0000000 EFFFFFFF 00 7F 0000 3FFF 0 127 0 16383
1 2
3 4
0 2097151 0 268435455
The following points apply to the Mark II implementation of the method. A variable-length data value and its associated length prefix form a single field in a function request or request message, with an indicated length of Var. Therefore, there is no need to indicate the length as a separate field. The length prefix indicates the length of the data portion of the field, i.e. the length prefix is not included in the length. The specified length is a number of bytes. The length prefix is independent of the attributes and contents of the data value. For multi-byte length prefixes, the byte order in the field is most significant byte first, i.e. big endian. This is in line with the general rule for all multi-byte integer fields in Mark II functions. The method as defined above is open-ended, and therefore could be extended to a length prefix of more than four bytes. However, the HSM supports a maximum of four bytes for a length prefix. For variable-length fields in response messages, the length prefix consists of the minimum number of bytes required to express the data length of the field. A variable-length field with a data length of zero is represented entirely by a length prefix containing the value zero, e.g. X00 or X8000. A zero-length field is useful where a field is not optional, but is not used.
SafeNet, Inc.
10
SafeNet Technologies
11
SafeNet Technologies
12
Variants
KM Variants
The following KM variants are used to encrypt host stored keys. Variant 0 1 2 3 4 5 6 7 8 9 10 11 14 16 17 18 19 20 24 25 26 27 30 31 32 33 34 35 36 37 38 Value X00 X28 X24 X44 X88 X22 X20 X18 X14 X48 X45 X4D X5C X0C X0A X1E X2E X4E X72 X78 X70 X74 X30 X36 X3A X3C X50 X66 X6A X6C X7E Used to encrypt: DPK PPK MPK KIS KIR KTM CSCK KPV, DT KPVV KCVV Key Block encryption - terminal Key Block message authentication terminal KTPV KGK KKBLZ MK-ZKA MAC used for Format 15 host stored keys (K) used for Format 15 host stored keys BDK Key Block encryption host Key Block message authentication host PIN Block encryption KM encrypted PIN IMK-AC IMK-SMI IMK-SMC IMK-DAC IMK-IDN KTK PTK KMC IMK-CVC
The variant constant is obtained by repeating the variant byte from the above table 16 times.
SafeNet, Inc.
13
Size of Session Key 64-bit DEA keys 128 bit CBC and DEA keys
Method The variant constant is obtained by repeating the Variant Byte from the above table to yield an 8 byte constant. The variant constant is obtained by concatenating the variant byte from the above table with the constant xC0 and repeating these 2 bytes 8 times to yield a 16 byte constant. The variant constant is obtained by concatenating the variant byte from the above table with the constant x30 and repeating these 2 bytes 12 times to yield a 24 byte constant.
SafeNet, Inc.
14
The first 64 bits of the SHA1 digest will be the PVC of the key.
SafeNet, Inc.
15
byte 1 2
attribute x d
content 00 00 - 99
Index - short / binary Format 01 byte Field length: 2 1 2 Index - long / BCD Format 02 Field length: 3
attribute x x
content 01 00 - FF
byte 1 2-3
attribute x d
attribute x x
SafeNet, Inc.
16
attribute x x
content 10 eKMx(K)
Encrypted key - Double-length - ECB Format 11 byte attribute Field length: 17 1 x 2-17 x Encrypted key - Triple-length - ECB Format 12 byte attribute Field length: 25 1 x 2-25 x
content 11 eKMx(K)
content 12 eKMx(K)
Encrypted key - Double-length CBC Format 13 byte attribute Field length: 17 1 x 2-17 x Encrypted key Triple-length CBC Format 14 byte attribute Field length: 25 1 x 2-25 x
content 13 eKMx(K)
content 14 eKMx(K)
The following key specifier format supports the storage of key attributes. Note an IV of all zeros is used in the formation of the Authentication Code. Host-stored key / authenticated / with attributes Field Content Length Attribute Description Format 15 1 h 15 Version 1 h 01 Key Type 1 h 00 = RFU 01 = Interchange key Key sub-type 1 h 00, unless otherwise specified for a particular Key Type. For Key Type = 01: 00 = RFU 01 = KIS 02 = KIR KM-Id 1 h Identifies the KM (applies to AMB HSM) used with the authentication algorithm, otherwise must be zero. Authentication 1 h 01 = 3DES CBC 64-bit MAC Algorithm Id.
SafeNet, Inc.
17
Host-stored key / authenticated / with attributes Field Content Length Attribute Description Attribute Count 1 h Number of attributes 02 for KIS/KIR keys Padding 1 h 00 eKMv20(K) Var h 3DES CBC-encrypted key. IV = bytes 1 8 of key specifier. KIS/KIR See below Number related to Attribute Count. Attributes (See KIS/KIR Attributes below) MAC 8 h Authentication code calculated on previous fields, using variant 19 of KM and the algorithm specified in Authentication Algorithm Id. The following table lists KIS/KIR Attributes for Format 15. Attribute Number 1 Len 1 Attribute h Description Variant Scheme 00 none 01 Eracom 02 Atalla 03 AS2805.6.3 2000 00 functions enabled 01 functions disabled (only set when variant type = 00 )
DBL, Triple Length Permitted The following key specifier format explicitly incorporates algorithms and other parameters associated with the key. Encrypted key Algorithm included Field Content Length Attribute Format 16 1 h Algorithm 1 h Key length Block length Mode of operation eKMv(K) 1 1 1 h h h
Var
Description 16 Algorithm E0 = SEED Key length 02 = 128 Block Length 02 = 128 Mode of Operation 01 = ECB 02 = CBC Encrypted key
The following key specifier format supports a complete ANSI TR-31 Key Block. Variants of the KM are used as the encryption key and the MAC key for host stored keys. Variants of the KTM are used as the encryption key and the MAC key for terminal destined keys.
SafeNet, Inc.
18
Host-stored key / authenticated / with attributes Field Content Length Attribute Description Format 17 1 h 17 KM-Id 1 h Identifies the KM used to encrypt the key with the authentication algorithm (for the AMB HSM). Otherwise must be set to zero. Secure key Block n h ANSI key Block. The length n is identical to that specified in bytes 1 4 of the Block header. The following key specifier format supports an ANSI TR-31 Key Block using binary fields instead of ASCII. This uses less storage space and provides support for some fields not defined in TR-31 (for example, HMAC-SHA-1 algorithm). This key specifier format definition allows for a Binary Key Block to be converted to a TR-31 key Block (or vice versa) with no change to the value of the MAC. Variants of the KM are used as the encryption key and the MAC key for host stored keys. Variants of the KTM are used as the encryption key and the MAC key for terminal destined keys Host-stored key / authenticated / with attributes Field Content Length Attribute Description Format 18 1 h 18 KM-Id 1 h Identifies the KM used to encrypt the key with the authentication algorithm (for the AMB HSM). Otherwise must be set to zero. Secure key Block n h Binary Key Block. The key Block is identical Format 17 described above, with the exception that the encrypted key field and the MAC field are stored in binary and not expanded to hex-ASCII. The Key Block Length in bytes 1-4 of the Secure Key Block, however, is the length of the equivalent TR-31 Key Block (that is the length that would occur following the expansion to hexASCII). The following key specifier format supports a CAP Bitmap. The CAP Bitmap specifier is an authenticated data structure containing a payload in the clear. Although the CAP Bitmap specifier does not contain a key, it is implemented as a key specifier, as the key specifier format is easily extended to hold CAP Bitmap data. The data specifier incorporates a header, a payload and an authentication code. The header indicates the format of the payload. The present implementation only supports payload data that is not encrypted. With the exception of the header (first 8 bytes) and the final field (8-byte authentication code) the complete contents of the data specifier may be CBC-encrypted with KMv20, with the header utilized as the IV. An IV of all zeros is used in the formation of the Authentication Code.
Attribute h h
SafeNet, Inc.
19
Host-stored bitmap Field Content Length Encrypted 1 Payload KM-Id 1 Payload Length Pad1 Bitmap Authentication Code 2 2 8 8
Attribute h h h h h h
Description = 00 - payload is not encrypted For the AMB HSM, identifies the KM used, otherwise must be zero. = 0008 = 0000 Field from IPB 3DES CBC 64-bit MAC calculated on all previous fields, using KMv19.
The following key specifier format supports a Derived Unique Key per Transaction (DUKPT). DUKPT is a key management method which uses a unique key for each transaction, and prevents the disclosure of any past key used by the transaction-originating HSM (i.e. terminal PIN pad). DUKPT utilization is possible via host-stored and HSM-stored base derivation keys. Host-stored key / authenticated / with attributes Field Content Length Attribute Description Format 20 1 h 20 BDK Var K-spec Key specifier for the Base Derivation Key (BDK). (Formats 0-3, 13, 14 ) KSN 10 h Key serial number (= Initial key serial number + Encryption counter) supplied by pin pad Derived Key Type 1 h Specifies the length of the transaction key 0x02= double length (TDEA transaction key is derived) and the variant constant indicator will be used for request or both ways. 0x12= variant constant indicator will be used for response. This key specifier calculates a unique-per-card derived key. It is used to derive KKEK (as defined in [Reference [32] for Mark II]) so that the key may be used to encrypt a key or sensitive data to be sent to the card. CardMethod (01 or 02) define the mode of encryption. Unique-per-card derived key Field Content Length Attribute Format 50 1 h KMC Var K-Spec Card-unique derivation data Card method 16 1 h h = 01: ECB = 02: CBC
This key specifier calculates a unique-per-card derived session key. It is used to derive SKUENC, SKUMAC (as defined in [32] and [33] for MarkII]) in support of the mutual authentication of the card being personalized and its host. CardMethod (01 or 02) and SessionMethod (01 or 02) define the mode of encryption.
SafeNet, Inc.
20
Unique-per-card derived session key Field Content Length Attribute Format 51 1 h KMC Var K-Spec
16 1 16 1
The following formats for the key specifier structure support the host-storage of RSA public and private keys. A public key is stored in a clear form, with or without an authentication value, while a private key is stored encrypted by a variant of KM. In accordance with existing HSM convention, multi-byte integers (modulus and exponent) are stored with the leftmost byte containing the most-significant bits (i.e. big-endian). RSA public key Clear, unauthenticated Field Content Format 80 Modulus Exponent Length 1 Var Var Attribute h h h Description 80 Modulus of RSA public key. Exponent of RSA public key. len(Exponent) len(Modulus) No leading zeros
This key specifier will be supported by the KM-MIGRATE function, to translate Authentication Value from an old KM to the current KM. RSA public key Clear, authenticated Field Content Format Modulus Exponent Length 1 Var Var Attribute h h h Description 81 Public key modulus. Public key exponent. len(Exponent) len(Modulus) Leading zeroes need not be included. For the AMB HSM, identifies the KM used with the authentication algorithm, otherwise must be zero. Key Type attribute bits = 01 3DES CBC 64-bit MAC Optional user data. Authentication value calculated using variant 19 of KM and the algorithm specified in Authentication Algorithm Id.
KM-Id
2 1 Var Var
h h h h
This key specifier will be supported by the KM-MIGRATE function, to translate eKMv20(SK) and Authentication Value from an old KM to the current KM.
SafeNet, Inc.
21
RSA private key Encrypted Field Content Format Mod Len Key format KM-Id Length 1 2 1 1 Attribute h h h h Description 82 Length of modulus (m) in bytes. Format of the encrypted key field. = 01: Eracom default format. For the AMB HSM, identifies the KM used to encrypt the private key and with the authentication algorithm, otherwise must be zero. Key Type attribute bits = 01: 3DES CBC 64-bit MAC Optional user data. Private key, encrypted with variant 20 of KM. Plaintext format of SK prior to encryption defined elsewhere, and not necessarily for general publication. Authentication value calculated using variant 19 of KM and the algorithm specified in Authentication Algorithm Id.
2 1 Var Var
h h h h
Authentication Value
Var
The following Key Specifier Format specifies the format for a ZKA Random Number. This key specifier incorporates the data required to produce a clear PAC or MAC session key. A PAC key is produced if the key specifier is used within a PIN management function and a MAC key is produced if the key specifier is used within a message authentication function. It can also incorporate a format 92 key specifier as the MK-spec, in order to access a key in the MK2 table. This key specifier format can also be used as an alternative format in a PPK-spec or MPK-spec request field in standard functions. Specifically, the following functions will support a ZKA-RND format key specifier: MAC-UPDATE, MAC-GEN-FINAL, MAC-VER-FINAL PIN-TRANSLATE PIN-VERIFY, Calculate IBM Offset, MIGRATE-PIN PIN Verify PVV, Calculate PVV from IBM Offset, Calculate PVV from PIN Encrypted session key Length Attribute Description 1 h = 90 Var 1 K-spec h Key specifier for Master key (formats 03, 13, 92). 0 = use values in ZKA documentation; >0 = use HSM-stored CV values RND 16 h Random Number (Encrypted Session Key eTK(KS))
The CV values defined in ZKA documentation may be overridden by CV values stored within the HSM. The following Control Vector values are used when constructing a format 90 host stored key specifier. Key values for each type are defined below. Type MAC CV1 00 00 4D 00 03 41 00 00 CV2 00 00 4D 00 03 21 00 00
SafeNet, Inc.
22
PAC
00 21 5F 00 03 41 00 00
00 21 5F 00 03 21 00 00
The following Key Specifier Format specifies the format for a ZKA-Derived-*KK. This key specifier incorporates the data required to derive a *KKBLZ as follows: *KKBLZ = e*KGK1 (BLZ | BLZ) | e*KGK2 (BLZ | BLZ) The key specifier may be used in the functions that contain a '*KK-spec' field, i.e. 'ZKA-PIN-VER ecPVN method ' and 'ZKA-Calculate PVN from encrypted PIN' ZKA-Derived-*KK Attribute h = 91 K-spec K-spec h
Description
Key specifier for *KGK1 (formats 0-3 or 13) Key specifier for *KGK2 (format 0-3 or 13) 00000000 - FFFFFFFF
The following Key Specifier Format specifies the format for a ZKA-MK2 key. This key specifier is used to reference an MK in the MK2 table. A value of X'FF' in any of the 'h' attribute fields or a value of 9999 in the 'd' attribute Expiry Date field indicates that the field value has not been specified. The permissible omitted fields are indicated in the usage context of the key specifier. Specification of Sub-type Number, Version Number and Generation Number unambiguously references a specific record in the MK2 table. Alternatively (for example), Version Number and / or Generation Number may be set to X'FF' and / or Expiry Date may be set to 9999 to indicate that a search of the table should be performed. The search criteria are specified in the context where the key specifier is used. MK2 reference Attribute h = 92 h h h d
Field Content Format Sub-type Version Number Generation Number Expiry Date
Length 1 1 1 1 2
Description
= hex 00 63, or FF = hex 00 63, or FF = hex 00 63, or FF mmyy, where mm = BCD 01 31 and yy = BCD 00 99;
or mmyy = 9999 The following Key Specifier Format (1A) specifies the format for carrying a KM-encrypted PIN. The Domain Master Key (KM) and its variants are typically used to protect other keys. Modern usage of the KM has involved the key specifier function field. Consistent with this usage, the KMencrypted PIN comprises a formatted PIN Block that is encrypted using a dedicated variant of KM and managed within this key specifier, designed for this purpose. Prior to encryption, the PIN is formatted into an ISO format 3 PIN Block. The ISO format 3 PIN Block is ECB-encrypted using a dedicated variant of KM, and therefore the resulting cipher text Block has a length of 8 bytes.
SafeNet, Inc.
23
Use of ISO format 3 implies that the 12-digit Account Number Block (ANB) must be supplied when the PIN is generated, and whenever the KM-encrypted PIN is subsequently used. KM variant 27 is used for PIN-Block encryption to produce a KM-encrypted PIN for host storage. The hexadecimal constant associated with KMv27 is X74. KM-encrypted PIN Attribute h = 1A h h h = 01 For the AMB HSM, identifies the KM used, otherwise must be zero. Encrypted PIN Block.
Length 1 1 1 8
Description
SafeNet, Inc.
24
03 08 09 10 11 12 13
A particular function may not support all of the formats identified above. The specification of each function identifies which formats it supports. Note: Functions that translate PIN, output PIN block format can be 09 only if input PIN block format is 09.
Restrictions on reformatting
In those PIN translate functions that support the reformatting of the PIN block from one format to another, disassociation of the PIN from the Account Number is prevented by the following restrictions on the reformatting that is supported.
PIN Block Format ISO-0 / ANSI ISO-1 ISO-2 ISO-3 PIN/Pad Docutel
Reformatting supported ISO-3 ISO-0, ISO-3 ISO-0, ISO-1, ISO-3 none ISO-0, ISO-1, ISO-3 ISO-0, ISO-1, ISO-3
A console operation allows the user to modify the above default reformatting rules.
SafeNet, Inc.
25
A console operation allows the user to enable support for just those PIN block formats that are required.
SafeNet, Inc.
26
Request Message
Comms Header Metafunction Indicator Meta-function Type Version Type specific data Comms trailer
Response Message
Comms Header Metafunction Indicator Meta-function Type Version Respons e Code (= 00) Type specific data Comms trailer
A meta-function request could incorporate a normal request message as a variable-length field within its request data (i.e. type specific data) or it could contain another meta-function as the variable-length field. Two Meta-function types are presently defined. If the byte following the Meta-function Indicator byte is not one of the defined types, the HSM returns a Meta-function Error Response message with Response Code = 01. The Version field allows the format of the meta-function to change over time in a manner that provides backward compatibility. The Response Code field allows for error reporting for the meta-function header fields. This translates to a meta-function with a variable-length field that has a zero length (instead of containing the request). So the return code would be Invalid field length For further details on future meta-function support or the ProtectToolkit EFT product, please contact SafeNet.
SafeNet, Inc.
27
Metafunction
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
D D U U D
Request Content E3 Reserved Byte Meta-function ID Version Message Id Data Field Response Content E3 Reserved Byte Meta-function ID Version Return Code Message Id Data Field
Attribute h h h h x x Attribute h h h h h x x
Description Function Code Reserved currently 00 Meta-function type identifier Meta-function type version A Message Id used by cryptolink Normal request message ( or meta-function request) Description Function Code Reserved currently 00 Meta-function type identifier Meta-function type version A return code that indicates the status of the sent function A message Id used by cryptolink Normal request message (or Meta-function request)
The meta-function message format provides a transparent mechanism for implementing extensions to the current host message format. When used with SafeNets Cryptolink product, it provides a unique message identifier for all messages. Reserved Byte eta-function ID Currently restricted to 00 Meta-function type 00 The Message ID and Data field are not used when meta-function type = 00. No processing of data is performed. This meta-function is intended for use as a heartbeat function when used with ProtectToolkit EFT. Meta-function type 01 The Message ID and Data Fields are used when meta-function type = 01. The meta-function is used to encapsulate other functions. Version currently restricted to 01 The version field allows for the format of the meta-function to evolve over time in a manner that will support backward compatibility. (response only) The return code indicates the status of the sent message. A four byte message ID is used to uniquely identify each meta-function message. The message ID will be returned as part of the response message. Not used when Meta-function Id = 00
SafeNet, Inc.
28
Chapter 3 The Metafunction The data field is a var field which in the request contains the encapsulated message request and in the response contains the encapsulated response. Not used when Meta-function Id = 00
Data
Return Codes: 00 OK 01 Invalid meta-function Id 02 Invalid version number 03 Invalid data field length
NOTE
If an error occurs in the E3 Function the encapsulated message is not run and no return data will be presented.
SafeNet, Inc.
29
SafeNet, Inc.
30
SafeNet, Inc.
31
HSM_STATUS
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
D D D D D
Request Content 01 Response Content 01 rc RAM Status ROM Status DES Status Host Port Status Battery Status Hard Disk Status RSA Accelerator Performance Level Reset Count Calls in last minute Calls in last 10 mins. Software ID length Software ID
Length 1 Length 1 1 1 1 1 1 1 1 1 1 2 4 4 1 n
Attribute h Attribute h h h h h h h h h h h h h h h
This function activates the self-tests and returns the results to the host. * RAM Status * ROM Status DES Status This is the result of performing a OS function to test the RAM. A failure indicates faulty RAM. 0 = passed and 1 = failed. This is the result of performing a CRC check on the ROM. A failure indicates ROM corruption or tampering. 0 = passed and 1 = failed. This is the result of performing numerous integrity checks on the hardware cryptographic chip. A failure would indicate faulty crypto hardware. 0 = passed and 1 = failed. This is the result of performing various status checks to ensure the host port can be configured and perform successful communication. Failure may indicate either a software or hardware problem. 0 = passed, 1 = failed, and 02 = passed but not connected (for Ports). Note: The return value (02) is valid for SHP platform only. Failure indicates a low or failed battery used to maintain secure memory contents. Key loss is likely if mains power is removed. 0 = passed and 1 = failed. Read IDE status port to ensure no IDE errors are reported. 0 = passed and 1 = failed. Indicates that hardware is available to perform RSA encryption and decryption and that it is functioning correctly. 0 = passed, 1 = failed and 2 = not found. Returns the value of the factory set performance level which is configured to order. If the Performance Level is either unknown or not applicable a value of 0 is returned. Number of time the HSM has been reset since manufacture. The value is returned with least significant byte first
Battery Status * Hard Disk Status RSA Accelerator Performance Level Reset Count
SafeNet, Inc.
32
Chapter 4 HSM Status Functions Number of function calls to the host made in the last minute. The value is returned with least significant byte first. Number of function calls to the host made in the last 10 minutes. The value is returned with least significant byte first. The number of bytes (characters) making up the Software ID. The maximum is 8. The Software ID contains the string displayed in the top right corner of the console. It is limited to a maximum length of 8 characters (bytes). The Status screen also displays the Software ID field value. Part of the SHP Toolkit MK2 function call. The ESMID is a pointer to a NULL terminated string that identifies the name of the SafeNet HSM (ESM) to which functions are directed. The SafeNet HSM name is set using the wincommsconfig utility provided as part of the SHP Toolkit product suite.
ESMID
* The values of fields RAM, ROM and Hard Disk status are not valid for the SHP platform, and hence a default value (0) is returned for these items. SHP Toolkit MK2 int EFT_01_GetESMStatus ( IN UCHAR *ESMID, OUT OUT OUT OUT OUT OUT OUT OUT OUT OUT OUT OUT UCHAR UCHAR UCHAR UCHAR UCHAR UCHAR UCHAR UCHAR USHORT ULONG ULONG EFTBUFFER *RAMStatus, *ROMStatus, *DESStatus, *HostPortStatus, *BatteryStatus, *HardDiskStatus, *RSAAccelerator, *PerformanceLevel, *ResetCount, *CallsInLastMinute, *CallsInLast10Minutes, *SoftwareID);
SafeNet, Inc.
33
HSM-ERRORLOG-STATUS
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
D D U D D
Request Content FFF0 FM Response Content FFF0 rc No of Error log Files Repeat for each errorlog file: Errorlog File Number Total No of Errors logged First Errorlog Date First Errorlog Time Last Errorlog Date Last Errorlog Time
Length 3 1 Length 3 1 1
Attribute h h Attribute h h h
Description Function Code Function Modifier = 00 Description Function Code Return Code 00 if no errorlog file created
1 2 8 6 8 6
h h h h h h
00 to 10 max. 0 to 65,535 max, bigendian ASCII ddmmyyyy format ASCII hhmmss format ASCII ddmmyyyy format ASCII hhmmss format
This function checks for system error log files and returns the results to the host. The system will log errors to a current error log file until it exceeds a certain maximum size (by default, 50 Kbytes). The file is then copied to an archive file and cleared. The limit on the number of archive files that will be stored is 10 by default. This can be increased up to a maximum of 100. When this limit is reached the oldest, the archived file is overwritten. The current error log file is file number 0, and the archives range from 1 to 10. If no system errors have occurred then the error log file may not have been created. This will return a value of zero in the No of Error log Files field, otherwise this field will be the total of the current error log file plus each archived file. The function returns the number of errors logged in each error log file, together with the log date and times for the first and last error logs in the file. This information is repeated as a Block for each error log file. The details of the error log can be obtained by using the HSM_GET_ERRORLOG function specifying the appropriate error log file number and either the date and time of the error or the error log number. The date fields are sent in order of the digits e.g. 23/12/2002 would be sent in the order 2, 3, 1, 2, 2, 0, 0, 2. Similarly, the time fields are sent in the order h, h, m, m, s, s (most significant digit first). The date and time fields are ASCII formatted digits (i.e. the number 2 is 32H). ESMID Part of the SHP Toolkit MK2 function call. The ESMID is a pointer to a NULL terminated string that identifies the name of the SafeNet HSM (ESM) to which functions are directed. The SafeNet HSM name is set using the wincommsconfig utility provided as part of the SHP Toolkit product suite.
SafeNet, Inc.
34
SHP Toolkit MK2 int EFT_FFF0_HSMErrorLogStatus ( IN UCHAR *ESMID, IN UCHAR FM, OUT _OUT _OUT _OUT _OUT _OUT _OUT _OUT _OUT _OUT _OUT _OUT UCHAR UCHAR UCHAR UCHAR UCHAR UCHAR UCHAR UCHAR UCHAR UCHAR UCHAR UCHAR *Num_Files, LogFileStatus[31], LogFileStatus1[31], LogFileStatus2[31], LogFileStatus3[31], LogFileStatus4[31], LogFileStatus5[31], LogFileStatus6[31], LogFileStatus7[31], LogFileStatus8[31], LogFileStatus9[31], LogFileStatus10[31] );
SafeNet, Inc.
35
HSM-GET-ERRORLOG
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
D D U D D
Request Content FFF1 FM Errorlog File Number Errorlog Index number Errorlog Date Errorlog Time Get logs before/after flag Response Content FFF1 rc Errorlog File Number Repeat for each error log : Errorlog Index number Error Log Data
Length 3 1 1 2 8 6 1 Length 3 1 1
Attribute h h h h h h h Attribute h h h
Description Function Code Function Modifier = 00 00 to 100 max. 00 to 65,536, big-endian ASCII ddmmyyyy format ASCII hhmmss format 00 = Before 01 = After Description Function Code Return Code 00 to 10 max.
2 Var
h h
The current errorlog file is file number 0 and the archived errorlog files range from 1 to 10. For a given errorlog file number, this function will return the last 10 error logs prior to/after a given date/time or errorlog index number. If the Errorlog Index number is specified as 0, then the date and time will be used as the starting point for the list of error logs. If the index is specified, then the date and time fields will be ignored. If the Get logs before/after flag is set to 0 then the 10 error logs prior to and including the starting point will be returned. If the flag is set to a 1, then the 10 logs after and including the starting point will be returned. If there are less than 10 logs in the file prior to or after the starting point, then only the remaining logs will be returned. The error log will be returned as ASCII formatted data, just as it is stored in the error log file (including the linefeed/carriage return at the end of each logged entry). The maximum length of each log entry is 256 bytes. If the errorlog file number does not exist, then the function will return an rc of 01. Otherwise, if the function is successful, an rc of 00 is returned. ESMID Part of the SHP Toolkit MK2 function call. The ESMID is a pointer to a NULL terminated string that identifies the name of the SafeNet HSM (ESM) to which functions are directed. The SafeNet HSM name is set using the wincommsconfig utility provided as part of the SHP Toolkit product suite.
SafeNet, Inc.
36
SHP Toolkit MK2 int EFT_FFF1_HSMGetErrorLog( IN UCHAR *ESMID, IN UCHAR FM, IN UCHAR File_Number, IN UCHAR Error_Index[2], IN UCHAR Error_Date[8], IN UCHAR Error_Time[6], IN UCHAR Get_Error_Flag, OUT _OUT _OUT _OUT _OUT _OUT _OUT _OUT _OUT _OUT _OUT _OUT _OUT _OUT _OUT _OUT _OUT _OUT _OUT _OUT _OUT UCHAR UCHAR EFTBUFFER UCHAR EFTBUFFER UCHAR EFTBUFFER UCHAR EFTBUFFER UCHAR EFTBUFFER UCHAR EFTBUFFER UCHAR EFTBUFFER UCHAR EFTBUFFER UCHAR EFTBUFFER UCHAR EFTBUFFER *Returned_File_Number, Error_Log_Index[2], *Error_Log_Data, Error_Log_Index1[2], *Error_Log_Data1, Error_Log_Index2[2], *Error_Log_Data2, Error_Log_Index3[2], *Error_Log_Data3, Error_Log_Index4[2], *Error_Log_Data4, Error_Log_Index5[2], *Error_Log_Data5, Error_Log_Index6[2], *Error_Log_Data6, Error_Log_Index7[2], *Error_Log_Data7, Error_Log_Index8[2], *Error_Log_Data8, Error_Log_Index9[2], *Error_Log_Data9);
SafeNet, Inc.
37
SafeNet, Inc.
38
SafeNet, Inc.
39
Establish_KM
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
D D D D D
Length 1 Length 1 1
Attribute h Attribute h h
This function is used to move the current KM to the old KM and move the new KM to the current KM. This function can be enabled/disabled by a console operation.
SafeNet, Inc.
40
KM_Migrate
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
D D D D D
Length 1 1 1 Var
Attribute h h h K-Spec
Description Function Code KM Variant Used Number of Keys A key specifier for type of host-stored key used (Formats: 10, 11, 12, 13, 14, 18, 81, 82) Description Function Code Return Code Number of Keys A key specifier for key encrypted under Current KM (Formats: 10, 11, 12, 13, 14, 18, 81, 82)
Response Content 12 rc
1
Length 1 1 1 Var
Attribute h h h K-Spec
n Key Spec
This function translates keys from encryption under the old Domain Master Key to encryption under the current KM. This function is enabled/disabled by a console operation.
Notes: The key-types 10, 11, 12, 18, 81, 82 under the Response Content, are generated when using the Legacy option. The key-types 10, 11, 12, 13, 14 under the Response Content, are generated based on the chosen operation on console and FM. See, section Function Modifier Values.
Definitions
Key Spec i Single or double length key specifier Variant of the Domain Master Key
SafeNet, Inc.
41
int EFT_12_MigrateKey( IN UCHAR IN UCHAR IN KEYSPEC _IN KEYSPEC _IN KEYSPEC _IN KEYSPEC _IN KEYSPEC _IN KEYSPEC _IN KEYSPEC _IN KEYSPEC _IN KEYSPEC _IN KEYSPEC OUT OUT _OUT _OUT _OUT _OUT _OUT _OUT _OUT _OUT _OUT UCHAR KEYSPEC KEYSPEC KEYSPEC KEYSPEC KEYSPEC KEYSPEC KEYSPEC KEYSPEC KEYSPEC KEYSPEC
variantNum, NumKeys, *keyToTranslate1, *keyToTranslate2, *keyToTranslate3, *keyToTranslate4, *keyToTranslate5, *keyToTranslate6, *keyToTranslate7, *keyToTranslate8, *keyToTranslate9, *keyToTranslate10, *NumKeysReturned, *translatedKey1, *translatedKey2, *translatedKey3, *translatedKey4, *translatedKey5, *translatedKey6, *translatedKey7, *translatedKey8, *translatedKey9, *translatedKey10);
SafeNet, Inc.
42
Erase_Old_KM
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
D D D D D
Length 1 Length 1 1
Attribute h Attribute h h
Used to erase the old KM. This function is enabled/disabled by a console operation.
SafeNet, Inc.
43
SafeNet, Inc.
44
SafeNet, Inc.
45
Retrieve_Key
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
D D D D D
Description Function Code Function Modifier = x0 Key specifier for Key Transfer Table (Formats: 0 - 3) Description Function Code Return Code Representing returned Key Type: 01 = KIS 02 = KIR 03 = ZCMK Key specifier for retrieved key (Formats: 10, 11, 13, 15) Key Verification Code
Var 3
K-Spec h
This function is used to retrieve a key from the key transfer table. The key is deleted from the table if the retrieval is successful. The KVC/KCV of the key is also returned. 4-digit KVC/KCVs are returned with two trailing zeroes. KVC is returned for KIS or KIR key types, and KCV is returned for ZCMK key. KXT Spec
Note: The key-types 10, 11,15 under the Response Content, are generated when using the Legacy option. The key-types 10, 11, 13 under the Response Content, are generated based on the chosen operation on console and FM. See section, Function Modifier Values.
NOTE
The key specifier returned will depend on the key type stored in the transfer table. Single length keys will result in key specifier Format 10, double length keys will result in key specifier Format 11, and keys that have been stored as Format 15 through the STORE-KEY function will result in Format 15 being returned as the key specifier response field. When the Key Spec is returned as a Format 10 or 11 the specific KM variants are used. KM variant 4 is used for ZCMK's and KIR. KM variant 3 is used for KIS.
SafeNet, Inc.
46
Chapter 6 Transfer Functions UCHAR KEYSPEC Reserved[2], *tfrTableIndex, *keyType, *retrievedKey, KVC[3] );
IN IN
SafeNet, Inc.
47
Store_Key
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
D D D D D
Length 1 1 Var 1
Attribute h h K-Spec h
Description Function Code Function Modifier = 00 Key specifier for Key Transfer Table, (Formats: 0 - 3) Key Type representing key to store 01 = KIS 02 = KIR 03 = ZCMK Key specifier for stored key, (Formats: 10, 11, 13, 15 (See note)) Key Verification Code Description Function Code Return Code
Key Spec
Var
K-Spec
3 Length 1 1
h Attribute h h
This function is used to store a key in the key transfer table. The KVC/KCV of the key is also returned. 4-digit KVC/KCVs needs to be entered with two trailing zeroes. KVC is returned for KIS or KIR key types, and KCV is returned for ZCMK key.
NOTE
Format 15 is only accepted when the key sub type sent is 1 or 2. When the Key Spec field is a Format 15, the key stored in the transfer table will have its attributes set. Formats 10, 11, 13 for the Key Spec use the specific KM variant for the key type. KM variant 4 is used for ZCMK's and KIR. KM variant 3 is used for KIS.
SHP Toolkit MK2 int EFT_22_StoreKey( IN UCHAR IN KEYSPEC IN UCHAR IN KEYSPEC IN UCHAR
SafeNet, Inc.
48
KEY_IMPORT
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
D D D D D
Request Content EE0200 FM KIR Spec Key Type Enc Mode eKIRvx(K) Response Content EE0200 Rc Key Spec KVC
Description Function Code Function Modifier = x0 Key specifier for the KIR (Formats: 0 - 3, 10, 11, 13, 15) Key Type Encryption Mode (for decipher of incoming eKIRVx(K)) Encrypted Key (Formats: 10, 11, 13, 14) Description Function Code Return Code Key specifier containing eKMx(K) (Formats: 10, 11, 12, 13, 14) Key Verification Code
This function re-encrypts a received encrypted DES or 3DES key for host storage. As received, the keys are encrypted under the appropriate variant of the Interchange Receive Key (KIR) indicated by the 'KIR-Spec' field in the function request. The mode of encryption for the key sent in the function request (eKIRVx(K)) may be ECB for single-length keys and ECB or CBC for double-length keys. The received key is returned CBC encrypted under the appropriate *KM variant for storage within the host. The function also returns the KVC of the received key.
Note: The key-types 10, 11, 13, 14 under the Response Content, are generated when using the Legacy option. The key-types 10, 11, 12, 13, 14 under the Response Content, are generated based on the chosen operation on console and FM. See section, Function Modifier Values.
The Host Key Protection using Function Modifier can be in the range of x0, where x= 0 , 1, or 2. A key specifier for a HSM-stored or host-stored, single-length or double-length KIR. Accepts key spec formats 0 - 3, 10, 11, 13, and 15. Indicates the type of received encrypted key as follows:
SafeNet, Inc.
49
Chapter 6 Transfer Functions 00: DPK 01: PPK 02: MPK 03: KIS 04: KIR 05: KTM 06: CSCK 07: KPV, DT 08: KPVV 09: KCVV 16: ZKA KGK 17: ZKA KKBLZ 18:ZKA MK 24: BDK 30: IMKAC 31: IMKSMI 32:IMKSMC 33: IMKDAC 34: IMKDN 35: KTK 36: PTK 37: KMC 38: IMK-CVC
Enc Mode
Indicates the mode of operation used for decrypting the incoming key: 0 1 ECB CBC
Key encrypted by a variant of the Interchange Receive Key. Accepts key spec formats 10, 11, 13 and 14. Key Specifier incorporating an encrypted key. Single length ECB and double length CBC encrypted keys (Formats 10, 11, 12, 13, 14). Key Verification Code for the key
Details and Restrictions 1. If a HSM-stored KIR is provided in the request, its associated variant scheme will be used when decrypting the incoming key. 2. If a host-stored KIR is provided in the request in a format 10, 11 or 13 key specifier, no variants will be used when decrypting the incoming key. Error conditions When a double length received key is provided, but a single length KIR is specified this will result in an error condition 0C Inconsistent Request Fields.
Note
This function will check the length of KIR and use the appropriate encryption method (Single-DES). When the AS2805 variant scheme is used, the eKIRvx(K) is always received at the function encrypted using CBC (the function will ignore the encryption mode specified in the Enc Mode field). Please refer to Mark II Console User Guide for directions on how to set options for the KIR. Single length BDKs and IMKs are not supported. PIN Verification Key, Decimalization Table (PVK, DT). (KMv7) support format 0-3 and 13, 14 Function will return error code 19 for key-type not supported by SafeNet Variant scheme if Use No Variant is not-checked for Host-Stored KIR . Function will return error code 19 for key-type not supported by SafeNet Variant scheme if variant scheme is selected SafeNet for HSM stored KIR .
SHP Toolkit MK2 int EFT_EE0200_KeyImport( IN UCHAR FM, IN KEYSPEC *KIR, IN UCHAR KeyType, IN UCHAR EncMode, IN EFTBUFFER *eKIRvK,
SafeNet, Inc.
50
OUT OUT
KEYSPEC UCHAR
*eKMvK, KVC[3]);
SafeNet, Inc.
51
KEY_EXPORT
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
D D D D D
Request Content EE0201 FM KIS Spec Key Type Enc Mode Key Spec Response Content EE0201 rc eKISvx(K) KVC
Description Function Code Function Modifier = 00 Key specifier for the KIS, (Formats: 0 - 3, 10, 11, 13, 15) Key type Encryption Mode (for encipher of outbound eKISvx(K).) Key specifier containing eKMx(K) (Formats: 10, 11, 12, 13, 14) Description Function Code Return Code Encrypted Key Key Verification Code
This function re-encrypts a host-stored encrypted DES or 3DES key under a specified KIS. As stored on the host, the keys are encrypted under the appropriate variant of the Domain Master Key (KM). The keys are returned encrypted under the appropriate KIS variant. The function also returns the KVC of the key. FM KIS Spec Key Type = 00. Must be set to zero. A key specifier for a HSM-stored or host-stored, single length or double length KIS. Accepts key spec formats 0 - 3, 10, 11, 13 and 15. Indicates the type of host-stored encrypted key as follows: 00: DPK 01: PPK 02: MPK 03: KIS 04: KIR 05: KTM Enc Mode 06: CSCK 07: KPV, DT 08: KPVV 09: KCVV 16: ZKA KGK 17: ZKA KKBLZ 18:ZKA MK 24: BDK 30: IMKAC 31: IMKSMI 32:IMKSMC 33: IMKDAC 34: IMKDN 35: KTK 36: PTK 37: KMC 38: IMK-CVC
Indicates the mode of operation used for encrypting the outgoing key: 00 ECB
01 CBC eKISvx(K) Key Spec KVC Key encrypted by a variant of the Interchange Store Key. Key Specifier incorporating an encrypted key. Single length ECB and double length CBC encrypted keys (Formats 10, 11, 12, 13 and 14). Key Verification Code for the key
SafeNet, Inc.
52
1. If a HSM-stored KIS is provided in the request, its associated variant scheme will be used when encrypting the outgoing key. 2. If a host-stored KIS is provided in the request in a format 10, 11 or 13 key specifier, no variants will be used when encrypting the outgoing key. Error conditions If a double-length host-stored key is provided, but a single length KIS is specified, this will result in an error condition 0C Inconsistent Request Fields. Note This function will check the length of KIS and use the appropriate encryption method (Single-DES or Triple-DES). When the AS2805 variant scheme is used, the eKISVx(K) is always encrypted using CBC (it will ignore the encryption mode specified in the Enc Mode field). Please refer to the Mark II Console User Guide for directions on how to set options for the KIS. Single length BDKs and IMKs are not supported. PIN Verification Key, Decimalization Table (PVK, DT). (KMv7) support format 0-3 and 13,14 Function will return error code 19 for key-type not supported by SafeNet Variant scheme if Use No Variant is not-checked for Host-Stored KIS. Function will return error code 19 for key-type not supported by SafeNet Variant scheme if variant scheme is selected SafeNet for HSM stored KIS.
SHP Toolkit MK2 int EFT_EE0201_KeyExport ( IN UCHAR FM, IN KEYSPEC *KIS, IN UCHAR KeyType, IN UCHAR EncMode, IN KEYSPEC *eKMvK, OUT OUT EFTBUFFER UCHAR *eKISvK, KVC[3]);
SafeNet, Inc.
53
Get_Key_Details
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
D D D D D
Length 3 1 Var
Attribute h h K-Spec
Description Function Code Function Modifier = 00 Key specifier for the host stored key (Formats: 10,11, 12, 13, 14,15,16,17,18,50) Indicates the KM-variant with which the key K is encrypted 00: Standard Description Function Code Return Code For DES/3DES keys, indicates whether the key has odd, even or mixed parity. KVC for the host stored key.
1 1 Length 3 1 1 Var
h h Attribute h h h h
This function provides non-sensitive details of a host stored key that is stored in simple KM encrypted form. Key Type For key specifiers that contain an authenticated key Block incorporating the key type, this field must be set to zero (i.e. key specifier formats 15,17 and 18). Otherwise (ie key specifier formats 10, 11, 13, 14, 16 and 50) this field indicates the KM-variant with which the key is encrypted as follows: 00: DPK 01: PPK 02: MPK 03: KIS 04: KIR 05: KTM KVC Type Parity 06: CSCK 07: KPV,DT 08: KPVV 09: KCVV 16: ZKA KGK 17: ZKA KKBLZ 18:ZKA MK 24: BDK 30: IMKAC 31: IMKSMI 32:IMKSMC 33: IMKDAC 34: IMKDN 35: KTK 36: PTK 37: KMC 38: IMK-CVC
Specifies the method used to calculate the KVC. Initially only a value of zero is supported, indicating the use of the standard method. For DES/3DES keys, this field indicates whether the plain text key has odd, even or mixed parity, as follows: 00: Not applicable. 01: Odd parity. 02: Even parity. 03: Mixed parity
KVC
For DES/3DES keys, the field contains the 3-byte 'standard ' KVC
SHP Toolkit MK2 int EFT_EE0202_GetKeyDetails( IN UCHAR FM, IN KEYSPEC *K, IN UCHAR KeyType, IN UCHAR KVCType, OUT UCHAR *Parity, OUT EFTBUFFER *KVC);
SafeNet, Inc.
54
SafeNet, Inc.
55
LOAD_HSM_SOFTWARE
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
D D U D D
Length 3 1 1
Attribute h h h
Description Function Code Function Modifier = 00 Representing File type: = 01: s90 file = 02: key file Representing segment type: = 01: First segment = 02: Other segments Dual variable A data segment from the file Description Function Code Return Code Length of partial saved file.
Control
File Length / Offset Data Segment Response Content EE3100 rc Cumulative Data Length
4 Var Length 3 1 4
h h Attribute h h h
This function is used load s90 and key files (for software upgrade) to HSM box from host PC. To load these files thousands of call may require. On success function returns 4 bytes value in cumulative length field to show the length of the file that has been received so far and this value must be included in the File Length / Offset field in the next function call Once both the files are loaded it starts the load process in the background that does the actual verification and copies the new Software in the loaded area. Depending on the size of loaded files it takes some time in the verification and copy process. Once the files are loaded its status can be observed using the HSM_SOFTWARE_STATUS function.
File Id
This field identifies the name of the file that is being transferred as follows: 01 02 File eracom.s90 to be loaded. File eracom.key to be loaded. First segment of file to be loaded.
Control
01 02
Other segments of file to be loaded. This field acts as a dual variable which holds the value of File Length when function have been called first time (control =01) and Offset for other function calls (control =02). This field has variable data length and contains the data segment of image file. Usually have constant segment size. On success function returns 4 bytes value to show the length of the file that has been received so far and this value must be included in the File Length / Offset field in the next function call Part of the SHP Toolkit MK2 function call. The ESMID is a pointer to a NULL
SafeNet, Inc.
56
Chapter 7 HSM Software Upgrade Functions terminated string that identifies the name of the SafeNet HSM (ESM) to which functions are directed. The SafeNet HSM name is set using the wincommsconfig utility provided as part of the SHP Toolkit product suite.
SHP Toolkit MK2 int EFT_EE3100_ Load_HSM_Software ( IN UCHAR *ESMID, IN UCHAR FM, IN UCHAR File_id, IN UCHAR Control, IN UCHAR Offset [4], IN EFTBUFFER *Data, OUT UCHAR Data_len [4]);
SafeNet, Inc.
57
HSM_SOFTWARE_STATUS
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
D D U D D
Length 3 1 Length 3 1 1
Attribute h h Attribute h h h
Description Function Code Function Modifier = 00 Description Function Code Return Code Representing Loaded Software Status: = 00: loaded from CD ROM = 01: loaded from host function = 02: loading from host = 03: verifying = 04: not loaded = 05: loading from CD ROM = 06: verification failed- invalid software image = 07: verification failed-invalid software variety = 08: package have been loaded from host (SHP only) = 09: package is being transferred from host (SHP only) = 10: no package is loaded from host (SHP only) Representing Loaded Softwares version number.
Version
Var
This function is used to retrieve the status of loaded software of a HSM box. Version number of loaded software is returned if software is loaded on the HSM box.
Status
SafeNet, Inc.
58
Chapter 7 HSM Software Upgrade Functions 00 01 02 03 04 05 06 07 08 09 10 New Software has been loaded from CD ROM and available on Loaded Area for installation. New Software has been loaded from Host functions and available on Loaded Area for installation. New Software is being loaded from Host functions and currently not available on Loaded Area for installation. New Software has been loaded and being verified, currently not available on Loaded Area for installation. No Software is loaded into Loaded Area. New Software is being loaded from CD ROM and currently not available on Loaded Area for installation. New software being loaded cannot be verified because it is not valid software. New Software loading failed. New software being loaded cannot be verified because it is incompatible or not of allowed variety. New Software loading is failed. SHP package has been loaded from host into host loaded area. SHP package is being transferred from host to host loaded area. No SHP package is loaded from host to host loaded area.
Version ESMID
If any software is loaded on the HSM, its version number is returned in this variable length field as string like M070708. Part of the SHP Toolkit MK2 function call. The ESMID is a pointer to a NULL terminated string that identifies the name of the SafeNet HSM (ESM) to which functions are directed. The SafeNet HSM name is set using the wincommsconfig utility provided as part of the SHP Toolkit product suite.
SHP Toolkit MK2 int EFT_EE3101_ HSMSoftwareStatus( IN UCHAR *ESMID, IN UCHAR FM, OUT OUT UCHAR EFTBUFFER *Status, *Version);
SafeNet, Inc.
59
SafeNet, Inc.
60
Rollover Session Key Generation NT_KEY_GEN Docutel Key Generation D51-PPK-GEN 3624 Comms Key Generation M-DPK-GEN Terminal Verification TERM_VER_2 DUKPT BDK Generation BDKGEN EE0408 74 EE0406 73 49 72 47 71 EE0401 69
SafeNet, Inc.
61
Key Mailer
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
D D U D D
Request Content EE0E01 FM nA Line No. Column No. Data nB Line No. Column No. Data Key Type KVC Type Response Content EE0E01 rc eKMvX(key) KVC
Description Function Code Function Modifier = x0, 01, 02 or 03 Number of text fields for env. A
Indicates the KM-variant with which the key K is encrypted 00: Standard Description Function Code Return Code Encrypted key (Formats: 10, 11, 12, 13, 14) KVC for the host stored key.
This function generates a random key for an EFT terminal. The available key types are; DPK, PPK, MPK, KIS, KIR, KTM, KPVV, KCVV. The key is supplied in the response, encrypted by a variant of the Domain Master Key (KM), for host storage and subsequent use with other functions (e.g. Generate session keys). The key is also printed in split form on two envelopes (A and B) for subsequent entry into the terminal.
Notes: The key-types 10, 13 under the Response Content, are generated when using the Legacy option. The key-types 10, 11, 12, 13, 14 under the Response Content, are generated based on the chosen operation on console and FM. See, section Function Modifier Values.
The function is controlled by an associated set of console operations that determine various options, including the key type and whether the generated key is single or double length. FM Function Modifier = x0, x1,x2,x3, x0 x1 x2 x3 nB in position shown, no additional fields nB moves below nA, no additional fields nB in position shown, additional fields present nB moves below nA, additional fields present
The Host Key Protection using Function Modifier can be in the range of x0, where x= 0, 1, or 2.
SafeNet, Inc.
62
Chapter 8 EFT Terminal Functions Number of text fields to print on the A envelope (max.10). This is the number of the line on which the Data is to be printed. It must be in the range of 1 to 40. This is the number of the column from which the Data is to be printed. It must be in the range of 1 to 120. This is a variable length field that contains the data to be printed. Number of text fields to print on the B envelope (max.10). This field specifies the type of key that is to be printed and confirms the key type as input at the console. It indicates the KM-variant with which the key is encrypted, as follows: 00: DPK 03: KIS 08: KPVV 01: PPK 04: KIR 09: KCVV 02: MPK 05: KTM In order to use the value input at the console, with no confirmation, this field must be set to XFF. If key type specified in this field conflicts with that entered at the console, the function will fail with rc = X28 This field is only present with FM value 02 and 03.
KVC Type
eKMvX(key)
Specifies the method used to calculate the KVC. Initially only a value of zero is supported, indicating the use of the standard method. This field is only present with FM value 02 and 03. key may be any of DPK, PPK, MPK, KIS, KIR, KTM, KPVV, KCVV The particular variant used X is dependant upon the key type. See the section Variants in Chapter 2 Function Construction for details. Generated key formats are 10, 11, 12, 13, and 14.
ESMID
Part of the SHP Toolkit MK2 function call. The ESMID is a pointer to a NULL terminated string that identifies the name of the SafeNet HSM (ESM) to which functions are directed. The SafeNet HSM name is set using the wincommsconfig utility provided as part of the SHP Toolkit product suite. Returns value 28 if the Key Type field conflicts with the key type entered at the console Key Verification Code of the printed key calculated using the method specified in request field KVC Type. This field is only present with FM value 02 and 03.
rc KVC
Note that each optional item to be printed is defined by appending a set of the fields Line no., Column no., and Data to the host request. Each Data character must be printed within the area defined by the size of the key mailer envelope. Also, each Data character must not overprint any other defined area (including other defined Data areas). Return code 02 Error condition Illegal Function Code (that is, the Key Mailer facility was not enabled when the Key Mailer request was received). Invalid data in message: This condition occurs if: - One of the fields Line No. or Column No. contains an invalid value. - A Data field character is to be printed outside the area defined by the size of the Key Mailer envelope or is to overprint any character of the key, KVC or another Data field.
04
SafeNet, Inc.
63
0B
NOTE
The console operator must exit the key print parameters display in order for the function to execute correctly. An error code of 0B may otherwise be returned.
SHP Toolkit MK2 SHP Toolkit MK2 supports the function when used with FM = 01 03 . int EFT_EE0E01_KeyMailer( IN UCHAR *ESMID, IN UCHAR FM, IN UCHAR nA, IN UCHAR nB, _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN UCHAR *LineNo1a, UCHAR *ColumnNo1a, EFTBUFFER *Data1a, UCHAR *LineNo2a, UCHAR *ColumnNo2a, EFTBUFFER *Data2a, UCHAR *LineNo3a, UCHAR *ColumnNo3a, EFTBUFFER *Data3a, UCHAR *LineNo4a, UCHAR *ColumnNo4a, EFTBUFFER *Data4a, UCHAR *LineNo5a, UCHAR *ColumnNo5a, EFTBUFFER *Data5a, UCHAR *LineNo6a, UCHAR *ColumnNo6a, EFTBUFFER *Data6a, UCHAR *LineNo7a, UCHAR *ColumnNo7a, EFTBUFFER *Data7a, UCHAR *LineNo8a, UCHAR *ColumnNo8a, EFTBUFFER *Data8a, UCHAR *LineNo9a, UCHAR *ColumnNo9a, EFTBUFFER *Data9a, UCHAR *LineNo10a, UCHAR *ColumnNo10a, EFTBUFFER *Data10a,
SafeNet, Inc.
64
_IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN OUT _OUT
UCHAR *LineNo1b, UCHAR *ColumnNo1b, EFTBUFFER *Data1b, UCHAR *LineNo2b, UCHAR *ColumnNo2b, EFTBUFFER *Data2b, UCHAR *LineNo3b, UCHAR *ColumnNo3b, EFTBUFFER *Data3b, UCHAR *LineNo4b, UCHAR *ColumnNo4b, EFTBUFFER *Data4b, UCHAR *LineNo5b, UCHAR *ColumnNo5b, EFTBUFFER *Data5b, UCHAR *LineNo6b, UCHAR *ColumnNo6b, EFTBUFFER *Data6b, UCHAR *LineNo7b, UCHAR *ColumnNo7b, EFTBUFFER *Data7b, UCHAR *LineNo8b, UCHAR *ColumnNo8b, EFTBUFFER *Data8b, UCHAR *LineNo9b, UCHAR *ColumnNo9b, EFTBUFFER *Data9b, UCHAR *LineNo10b, UCHAR *ColumnNo10b, EFTBUFFER *Data10b, UCHAR *KeyType, UCHAR *KvcType, KEYSPEC EFTBUFFER *eKMvX_KEY, *KVC_Key );
SafeNet, Inc.
65
D D D D U
Description Function Code Function Modifier = x0 A key specifier for the KTM (Formats: 0 - 3, 10, 11, 13, 16) Key Type generation specifier Description Function Code Return Code Number of following key sets Encrypted Session Key Key specifier incorporating encrypted Session Key (Formats: 10, 11, 13, 16) Key Verification Code
n eKTM(KS) 1 KS-Spec
1
KVC
This function generates a set of random session keys for an EFT terminal. For distribution to the terminal the session keys are encrypted by the Terminal Master Key (KTM), and for host storage and subsequent use with other functions they are encrypted by variants of the Domain Master Key. The function also returns the KVC of the session keys. If a new KTM is to be generated by the function, any session keys that are also generated are returned encrypted by the new KTM. For double-length DES session keys, either ECB or CBC modes may be selected. When the request field KTM-Spec refers to a HSM or host stored SEED key (Format 16) the response field(s) KS-Spec will be Format 16, the session key(s) will be encrypted according to the SEED algorithm and the KVC will be calculated according to the SEED KVC method.
Notes: The key-types 10, 11, 13, 16 under the Response Content, are generated when using the Legacy option. The key-types 10, 11, 13 under the Response Content, are generated based on the chosen operation on console and FM. See, section Function Modifier Values.
FM
= x0 The Host Key Protection using Function Modifier can be in the range of x0, where x= 0, 1, or 2.
SafeNet, Inc.
66
Chapter 8 EFT Terminal Functions A key specifier, which incorporates an index to a HSM-stored or host-stored single length or double length KTM. Formats 00 03, 10, 11, 13 and 16 accepted. Indicates the session keys to generate. The function response will contain one or more sets of encrypted key fields as shown: one set for each bit set in the flags. The bit positions are allocated as follows: bit 0 1 2 3 7 8 9 10 11 12 13-15 session key type Single-length Data Key (DPK). Single-length PIN encrypting key (PPK). Single-length MAC key (MPK). Single-length terminal master key (KTM). Reserved. Must be zero. Double-length Data Key (DPK). Double-length PIN encrypting key (PPK). Double-length MAC key (MPK). Double-length terminal master key (KTM). Encryption mode for response encrypting: 0 = ECB, 1 = CBC Reserved. Must be zero.
KTM-Spec
Key Flags
Bit 0 is the least significant (right most) bit. Examples: To generate a single-length MAC key, this field must be set to X0004; eKTM(KS) KS-Spec KVC To generate a double-length PIN encrypting key and a singlelength MAC key, the field must be set to X0204.
These fields form a key set. The response incorporates a key set for each bit (validly) set in the Key Flags field. The order of the returned key sets is the same order that the keys are specified in the Key Flags field. Error condition An inconsistency is present in the setting of the Key Flags field. Seven conditional returns currently exist: a. Double length session keys required with single length KTM. b. Single and double length session key of same type requested. c. Reserved bit not set to zero. d. Single length KTM required with double length KTM (Format 16 KTM-Spec). e. Single length MPK requested with SEED KTM (Format 16 KTM-Spec). f. Double length session keys requested with SEED KTM (Format 16 KTM-Spec). g. CBC mode requested with SEED KTM (Format 16 KTM-Spec).
Return code 0C
NOTES
For key specifier formats, refer to Chapter 2 Function Construction. For information on the SEED algorithm and the SEED KVC method see the Glossary. This function supercedes functions 41,42,43, 4A Bit 7 and Bits 13-15 of the key flags are reserved.
SafeNet, Inc.
67
int EFT_EE0400_InitialSessionKeyGeneration( IN UCHAR FM, IN KEYSPEC *KTM, IN UCHAR KeyFlags[2], OUT OUT OUT OUT _OUT _OUT _OUT _OUT _OUT _OUT _OUT _OUT _OUT UCHAR EFTBUFFER KEYSPEC UCHAR EFTBUFFER KEYSPEC UCHAR EFTBUFFER KEYSPEC UCHAR EFTBUFFER KEYSPEC UCHAR *numKeys, *eKTM_KS1, *KS1, KVC1[3], *eKTM_KS2, *KS2, KVC2[3], *eKTM_KS3, *KS3, KVC3[3], *eKTM_KS4, *KS4, KVC4[3] );
SafeNet, Inc.
68
D D D D U
Request Content EE0401 FM Key Flags 1 KSn Spec Response Content EE0401 Rc
1
Description Function Code Function Modifier = x0 Key Type generation specifier Session Key Specifier (Formats: 10, 11, 13) Description Function Code Return Code Number of following key sets Encrypted Session Key Session Key specifier (Formats: 10, 11, 13) Key Verification Code
KVC
This function generates a set of new random Session Keys (KSn+1) for an EFT Terminal. For transmitting to the EFT Terminal, the keys are returned encrypted under the supplied previous Session Keys (KSn). They are also returned encrypted under the appropriate KM variant, for storage within the host system. The function also returns the KVCs of the Session Keys.
Notes: The key-types 10, 11 under the Response Content, are generated when using the Legacy option. The key-types 10, 11, 13 under the Response Content, are generated based on the chosen operation on console and FM. See, section, Function Modifier Values.
FM Key Flags
The Host Key Protection using Function Modifier can be in the range of x0, where x= 0, 1, or 2. Indicates the session keys to generate. The function response will contain one or more sets of encrypted key fields as shown: one set for each bit set in the flags. The bit positions are allocated as follows: bit 0 1 2 3 7 8 9 session key type Single-length Data Key (DPK). Single-length PIN encrypting key (PPK). Single-length MAC key (MPK). Reserved. Must be zero. Reserved. Must be zero. Double-length Data Key (DPK). Double-length PIN encrypting key (PPK).
SafeNet, Inc.
69
Chapter 8 EFT Terminal Functions 10 11 12 13-15 Double-length MAC key (MPK). Reserved. Must be zero. Encryption mode for response eKSn(KSn+1): encryption. 0 = ECB, 1 CBC. Reserved. Must be zero.
Bit 0 is the least significant (right most) bit. Examples: To generate a single-length MAC key, this field must be set to X0004; KS Spec eKSn(KSn+1) KSn+1 Spec KVC To generate a single-length PIN encrypting key and a doublelength MAC key, the field must be set to X0402.
A key specifier incorporating a session key, encrypted by a variant of the Domain master key The new session key encrypted by the supplied session key A key specifier to the new session key Key Verification Code for the new session key
NOTES
For key specifier formats, refer to the section Key specifier formats for HSM-stored keys earlier in this chapter. The encryption mode for eKSn(KSn+1) and KSn spec is ECB unless otherwise specified. This function supercedes functions 44,45,46 Key flag bits 3, 7, 11 and 13-15 are reserved.
SHP Toolkit MK2 int EFT_EE0401_RolloverSessionKeyGeneration( IN UCHAR FM, IN UCHA R KeyFlags[2], IN KEYSPEC *KSi1, _IN KEYSPEC *KSi2, _IN KEYSPEC *KSi3, OUT OUT OUT OUT _OUT _OUT _OUT _OUT _OUT _OUT UCHAR EFTBUFFER KEYSPEC UCHAR EFTBUFFER KEYSPEC UCHAR EFTBUFFER KEYSPEC UCHAR *numKeys, *eKS_KS1, *KS1, KVC1[3], *eKS_KS2, *KS2, KVC2[3], *eKS_KS3, *KS3, KVC3[3]);
SafeNet, Inc.
70
D D U U U
Length 1 1 Length 1 1 8 8 8
Description Function Code KTM Index Description Function Code Return Code PIN Protect Key PIN Protect Key Verification Constant
This function generates a random PIN Protect Key (PPK) and associated encrypted verification constant for a Docutel 5100 ATM. For transmitting to the ATM, the generated key is returned encrypted by the Terminal Master Key (KTMn) indicated by the specified index (KTM-index). For host storage and subsequent use with the PIN Management Functions, the generated key is returned encrypted under the KM Variant 1. The verification constant (VCon) of X'0123456789ABCDEF' is encrypted by the generated key and the result is returned for transmission to the ATM.
NOTE
This function only supports use of the first 99 KTMs.
SafeNet, Inc.
71
D D U U U
Length 1 1 Length 1 1 8 8
Description Function Code Terminal Key Set Index (1 - 2) Description Function Code Return Code Data Protect Key Data Protect Key
This function generates a random communications key (DPK) for an IBM 3624 Consumer Transaction Facility. For transmitting to the 3624, the key is returned encrypted under the Terminal Master Key (KTM) indicated by the specified index (TKSI) which is stored in the HSM. It is also returned encrypted under KM, for storage within the host.
SafeNet, Inc.
72
Terminal Verification
TERM_VER_2
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
D D D D U
Length 3 1 Var
Attribute h h K-Spec
Description Function Code Function Modifier = 00 Key specifier for KTM (Formats: 0 - 3, 10, 11, 13) Security Number Logon Data Description Function Code Return Code
8 8 Length 3 1
h h Attribute h h
This function verifies the validity of an EFT terminal by checking that the LOGON-DATA is equal to the result of encrypting its Security Number (SEC-NO) under its KTM. The function returns no response data. An Error Code of 00 indicates successful verification, while 08 indicates a verification failure. KTM-Spec SEC-No Logon-Data A key specifier which incorporates an index to an HSM-stored or host-stored single length or double length KTM. Security Number for the terminal. The logon data is equivalent to the security number encrypted under the terminal master key.
NOTES
For key specifier formats, refer to Chapter 2 Function Construction. This function supercedes function 4C.
SHP Toolkit MK2 int EFT_EE0406_TerminalVerification ( IN UCHAR FM, IN KEYSPEC *KTM, IN UCHAR SecurityNumber[8], IN UCHAR LogonData[8] );
SafeNet, Inc.
73
D D D D U
Length 3 1 1
Attribute h h h
Description Function Code Function Modifier = x0 Length of BDK 02 = Double Length 03 = Triple Length Description Function Code Return Code Key specifier incorporating encrypted BDK key (Formats: 11, 12, 13, 14)
Length 3 1 Var
Attribute h h K-Spec
Notes: The key-types 13, 14 under the Response Content, are generated when using the Legacy option. The key-types 11, 12, 13, 14 under the Response Content, are generated based on the chosen operation on console and FM. See, section Function Modifier Values.
Derived Unique Key per Transaction (DUKPT) is a key management method which uses a unique key for each transaction, and prevents the disclosure of any past key used by the transactionoriginating HSM (i.e. terminal PIN pad). This method relies on the use of a 'base derivation' key or BDK present only in the HSM of the first receiving node that cryptographically processes that transaction. The unique Transaction Keys used by the HSM of a terminal are transformations of an injected, unique-per-terminal Initial Key which is derived from the BDK. The transaction keys can be calculated by the HSM of the receiving node using only the BDK and non-secret data transmitted by the terminal as part of each transaction. With this method each transaction-originating HSM uses a unique key for each transaction, yet never contains any information which would allow the determination of any key previously used by the HSM except by an exhaustive key search, nor of any key which has been or will be used by any other transaction-originating HSM. This function generates a BDK. For subsequent use with other functions the generated BDK key is encrypted by the associated variant of the Domain Master Key.
SafeNet, Inc.
74
Chapter 8 EFT Terminal Functions UCHAR UCHAR KEYSPEC FM, KeyLength, *BDK);
IN IN OUT
SafeNet, Inc.
75
SafeNet, Inc.
76
Generate RSA Key Pair ................................... Import Public Key ........................................... Import public key certificate ........................... Sign Data ......................................................... Verify Signed Data........................................... Generate MD5 Hash ........................................ Generate SHA Hash ........................................ Generate Key Diebold ................................... Verify ATM Response Diebold ...................... Generate KM NCR ........................................ II_KEY_GEN .................................................... II_KEY_RCV .................................................... NI-KEY-GEN .................................................... NI_KEY_RCV................................................... CLR-PIN-ENCRYPT......................................... MIGRATEPIN .................................................. PIN-TRAN-2 ................................................... PIN-VER-IBM-MULTI...................................... PIN-TRAN-3624............................................. KB-PIN-VER .................................................... VAR-KB-PIN-VER ........................................... PIN-OFF........................................................... PIN-FROM-OFF ............................................... Generate KM-encrypted PIN ........................... Print a KM-encrypted PIN............................... Verify a PIN Using KM-encrypted PIN ............ Translate a PIN from PPK to KM .................... Migrate PIN ..................................................... IT-PVK-EXPORT .............................................
EE9001 .............................. 79 EE9003 .............................. 81 EE9004 .............................. 82 EE9005 .............................. 84 EE9006 .............................. 85 EE9007 .............................. 86 EE9008 .............................. 87 EE9101 .............................. 88 EE9102 .............................. 90 EE9201 .............................. 91 EE0402 .............................. 94 EE0403 .............................. 97 EE0404 .............................. 101 EE0405 .............................. 103 EE0600 .............................. 107 EE0601 .............................. 108 EE0602 .............................. 110 EE0603 .............................. 112 63....................................... 114 64....................................... 115 69....................................... 116 EE0604 .............................. 117 EE0609 .............................. 119 EE0640 .............................. 121 EE0641 .............................. 122 EE0642 .............................. 124 EE0643 .............................. 125 EE0644 .............................. 126 EF0210 .............................. 127
Overview
The functions described in this chapter provide cryptographic and key management functionality to support remote initialization of ATMs. In this context, remote initialization means the secure on-line transport to the ATM of its initial DES/3DES key (A-key) using public key techniques, along with associated key and certificate management. The extended functionality supports protocols defined by the major ATM manufacturers. Currently Diebold and NCR requirements are addressed specifically and where possible, the public key functionality is defined in a generic manner so as to provide generally applicable RSA-based public key crypto facilities. The function set includes:
SafeNet, Inc.
77
a set of generic public key functions that are applicable to remote ATM initialization and might also be useful in other environments; additional functions that are designed to support Diebold ATMs; additional functions that are designed to support NCR ATMs.
Key Types
The HSM supports multiple RSA key types, as follows: Key Type Certificate Data Signature Key Transport Private key processing Not currently supported Sign data Decrypt encrypted key Public key processing Verify certificate Verify signed data Encrypt key
The Generate RSA key pair, Import public key and Import public key certificate functions will set the appropriate key type for a key. Other functions will check that the supplied key is of the appropriate key type. The Generate RSA key pair function will not generate a key pair of type Certificate because there is no function provided that signs specific certificate data. A key may be of multiple types, e.g. used for data signatures and for key transport. To self-sign a public key (using the Sign data function) the private key must have the Data Signature type.
SafeNet, Inc.
78
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
D D D D U
Length 3 1 2
Attribute h h h
Description Function Code Function Modifier = 00 Indicates the valid usage for the private key bit key type 0 --- not valid --1 Data Signature 2 Key Transport Bit 0 is the least significant (rightmost) bit. Modulus size in bytes: 16 = 3 or 65537 (2 +1). Data to be stored in key specifier for SK. (May be zero-length field.) Description Function Code Return Code Key specifier containing the public key (PK). (Format: 80) Key specifier containing the private key (SK) encrypted by a KM variant. (Format: 82)
This function generates an RSA key pair (PK, SK) with the specified modulus length and public exponent and returns the keys for host storage. The Key Type is stored in the key specifier for the private key (SK) and may be used to restrict usage of the private key. The public key is deemed unauthenticated so it is returned in a Format 80 key specifier. Processing steps 1. Generate an RSA key pair of the specified type and length, and with the specified public exponent. 2. Ensure that the modulus is compatible with the specified public exponent. 3. Return the generated keys in the appropriate key specifiers. Function usage The public key may subsequently need to be authenticated for local use (see the Authentication of public keys section above), and/or sent to a CA for insertion into a Public Key Certificate. Function usage (in context of Remote ATM Initialization) The key pair may be used as the 'Host Key Pair' used in the Remote ATM Initialization protocols. The ATM manufacturers use the following nomenclature for this key pair.
SafeNet, Inc.
79
SK sHOST SK-HSM
NCR The generated PK-HSM must be taken to NCR using a secure channel and will be signed using SKNCR giving (PK-HSM)*SK-NCR. The signed public key can be verified using the Import public key certificate function Diebold The generated vHOST must be submitted to the CA in a message self-signed by sHOST. Function usage (in context of Remote ATM Initialization) Diebold The Host public key must be submitted to the CA in a self-signed message. Although the message format is not within the scope of the Diebold specifications it is probable that this function will be suitable. PK Diebold vHOST SK sHOST
SHP Toolkit MK2 int EFT_EE9001_GenerateRSAKeyPair ( IN UCHAR FM, IN UCHAR KeyType[2], IN UCHAR ModulusLen[2], IN EFTBUFFER *PublicExponent, IN EFTBUFFER *UserData, OUT OUT KEYSPEC KEYSPEC *PK, *SK);
SafeNet, Inc.
80
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
D D D D U
Length 3 1 2
Attribute h h h
Description Function Code Function Modifier = 00 Indicates the valid usage for the private key bit key type 0 Certificate 1 Data Signature 2 Key Transport Bit 0 is the least significant (rightmost) bit. Key specifier for unauthenticated public key. (Format: 80) Data to be stored in key specifier for PK. (May be zero-length field.) Description Function Code Return Code Key specifier for authenticated public key. (Format: 81)
This function produces a key specifier incorporating an authenticated public key. To prevent unauthorized public keys from being introduced, the function should normally be disabled. The default condition is disabled. Function usage (in context of Remote ATM Initialization) NCR Import of NCRs public key: PK-NCR.
SHP Toolkit MK2 int EFT_EE9003_ImportPublicKey ( IN UCHAR FM, IN UCHAR KeyType[2], IN KEYSPEC *PKi, IN EFTBUFFER *UserData, OUT KEYSPEC *PKo);
SafeNet, Inc.
81
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
D D D D U
Length 3 1 Var 1
Attribute h h K-Spec h
Description Function Code Function Modifier = 00 Authenticated public key of CA (Format 81, Key Type: Certificate) 01 = EMV (not currently implemented) 02 = X.509 03 = NCR 04 = NCR2 00 = None. 01 = SHA-1 02 = MD5 Provide used hash function if certificate format is of type 03. Public key certificate Indicates the valid usage for the private key bit key type 0 Certificate 1 Data Signature 2 Key Transport Bit 0 is the least significant (rightmost) bit. Optional user data to be included in Public Key Specifier. Description Function Code Return Code Key specifier for authenticated public key. (Format: 81)
Hash Function
Var 2
h h
h Attribute h h K-Spec
This function verifies the signature on the public key certificate and returns the public key in an authenticated key specifier. The key type of the key will be set in the key specifier as specified in the Key Type request field. Function usage (in context of Remote ATM Initialization) NCR 1. Import of Hosts public key, PK-HSM, from the signed public key: PK-HSM + (PK-HSM)*SK-NCR. The signature is as generated by the RSASSA-PKCS-v1_5 scheme of [Reference [21] of MarkII].
Note: The authenticated key specifier may not be required and may be discarded. The function may be used just to verify that the signed public key corresponds with the public key sent to NCR.
SafeNet, Inc.
82
(The Verify signed data function may be used instead.) 2. Import of EPPs public key, PK-EPP, from the signed public key: PK-EPP + (PK-EPP)*SK-NCR. The signature is as generated by the RSASSA-PKCS-v1_5 scheme of [Reference [21] of MarkII]. Certificate Format If equal to 03 (NCR), the data in the Certificate field takes the format: modulus (256 bytes) concatenated with signature (256 bytes). If equal to 04 (NCR2), the data in the Certificate field is represented in PKCS#1, ASN.1 type RSAPublicKey. RSAPublicKey ::= SEQUENCE { modulus INTEGER, -- n publicExponent INTEGER, -- e } The fields of type RSAPublicKey have the following meanings: modulus is the modulus n. publicExponent is the public exponent e.
The following table illustrates a certificate in the PKCS#1, ASN.1 type RSAPublicKey (i.e. Certificate format = 04 - NCR2 ). Component Sequence and length ASN.1 Integer type and length ASN.1 Modulus (257 bytes 256 byte modulus preceded by leading zero byte The ASN.1 integer type with length of 3 and then the exponent data Signature (256 bytes) Example 3082010A 02820101 009F9C7EAD 0203010001 6E45FCE8D6
Note: The certificate field is a Var field. The ASN.1 format described in the example above must be
SHP Toolkit MK2 int EFT_EE9004_ImportPublicKeyCertificate( IN UCHAR FM, IN KEYSPEC *PK_CA, IN UCHAR CertFormat, IN UCHAR HashFunction, IN EFTBUFFER *Certificate, IN UCHAR KeyType[2], IN EFTBUFFER *UserData, OUT KEYSPEC *PK);
SafeNet, Inc.
83
Sign Data
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
D D D D U
Length 3 1 Var
Attribute h h K-Spec
Description Function Code Function Modifier = 00 Key specifier for Private Key. (Format: 82, Key Type: Data Signature) 01 = RSASSA-PKCS-11v1_5 00 = None. 01 = SHA-1 02 = MD5 Data to be signed Description Function Code Return Code Signed data: sSK(Data) or sSK(h(Data))
1 1
h h
h Attribute h h h
This function signs the data using the private key and signature algorithm indicated, and returns the digital signature. If 0 is given as hash function, data must be already hashed and formatted into a valid ASN.1 DEREncoded DigestInfo structure. Function usage (in context of Remote ATM Initialization) None.
SHP Toolkit MK2 int EFT_EE9005_SignData IN UCHAR IN KEYSPEC IN UCHAR IN UCHAR IN EFTBUFFER OUT EFTBUFFER ( FM, *SK, Algorithm, HashFunction, *Data, *Signature);
SafeNet, Inc.
84
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
D D D D U
Length 3 1 Var
Attribute h h K-Spec
Description Function Code Function Modifier = 00 Key specifier for Public Key. (Format: 81, Key Type: Data Signature) 01 = RSASSA-PKCS-11v1_5 00 = None. 01 = SHA-1 02 = MD5 Data used for signature Signature Description Function Code Return Code
1 1
h h
h h Attribute h h
This function verifies the signature on a signed message. If 0 is given as hash function, data must be already hashed and formatted into a valid ASN.1 DEREncoded DigestInfo structure. Function usage (in context of Remote ATM Initialization) NCR The function may be used to verify that the received signed public key PK-HSM + (PK-HSM)*SK-NCR corresponds with the public key sent to NCR. The function may be used to verify the signed serial number of an EPP: SN-EPP + (SN-EPP)*SK-NCR
SHP Toolkit MK2 int EFT_EE9006_VerifySignedData ( IN UCHAR FM, IN KEYSPEC *PK, IN UCHAR Algorithm, IN UCHAR HashFunction, IN EFTBUFFER *Data, IN EFTBUFFER *Signature);
SafeNet, Inc.
85
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
D D D D U
Length 3 1 1
Attribute h h h
Description Function Code Function Modifier = 00 00 = Only 01 = Initial 02 = Intermediate 03 = Last For chaining: initially zero, then as returned in previous call. For chaining: initially zero, then as returned in previous call. Data to be hashed. Description Function Code Return Code Cumulative bit count
Bit Count Hash Value Data Response Content EE9007 rc Bit Count Hash Value
8 16 Var Length 3 1 8 16
h h h Attribute h h h h
This function returns the result of MD5 hashing the supplied data. Function usage (in context of Remote ATM Initialization) The function can be used to obtain the hash of a public key. The public key might be as generated by the Generate RSA key pair function or as received from a CA. Three examples are as follows: 1. Calculate a hash as part of importing a public key. The hash is used at the HSM console to obtain a fingerprint for the public key. The fingerprint and key are then used together to obtain a MAC for the public key. (See the Authentication of public keys section above) 2. Calculate a hash for sending to the CA with the public key. 3. Calculate a hash to provide to the ATM operator that confirms the validity of the certificate.
SHP Toolkit MK2 int EFT_EE9007_GenerateMD5Hash ( IN UCHAR FM, IN UCHAR Mode, IN UCHAR BitCount[8], IN UCHAR HashValue[16], IN EFTBUFFER *Data, OUT OUT UCHAR UCHAR BitCount2[8], HashValue2[16] );
SafeNet, Inc.
86
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
D D D D U
Length 3 1 1 1
Attribute h h h h
Description Function Code Function Modifier = 00 00 = SHA-1 00 = Only 01 = Initial 02 = Intermediate 03 = Last For chaining: initially zero, then as returned in previous call. For chaining: initially zero, then as returned in previous call. Data to be hashed. Description Function Code Return Code Cumulative bit count
Bit Count Hash Value Data Response Content EE9008 rc Bit Count Hash Result
h h h Attribute h h h h
This function returns the result of SHA hashing the supplied data. Function usage (in context of Remote ATM Initialization) The function can be used to obtain the hash of a public key. The public key might be as generated by the Generate RSA key pair function or as received from a CA. Three examples are as follows: 1. Calculate a hash as part of importing a public key. The hash is used at the HSM console to obtain a fingerprint for the public key. The fingerprint and key are then used together to obtain a MAC for the public key. (See the Authentication of public keys section above) 2. Calculate a hash for sending to the CA with the public key. 3. Calculate a hash to provide to the ATM operator that confirms the validity of the certificate.
SHP Toolkit MK2 int EFT_EE9008_GenerateSHAHash ( IN UCHAR FM, IN UCHAR Algorithm, IN UCHAR Mode, IN UCHAR BitCount[8], IN EFTBUFFER *HashValue, IN EFTBUFFER *Data, OUT OUT UCHAR EFTBUFFER BitCount2[8], *HashResult );
SafeNet, Inc.
87
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
D D D D U
Request Content EE9101 FM IHOST IATM rATM eATM sHOST Key Len Key Type Response Content EE9101 Rc KTB1 rHOST KKTM
Description Function Code Function Modifier = x0 Identifier of Host Identifier of ATM ATM random nonce Key specifier for ATM Public Key. (Format: 81, Key Type: Key Transport) Key specifier for Host Private Key. (Format: 82, Key Type: Data Signature) 01 = Single 02 = Double 05 = KTM Description Function Code Return Code Key token B1 Host random nonce Key specifier for generated key as determined by Key len (Formats: 10, 11, 13)
h h Attribute h h h h K-Spec
This function generates a random double-length KTM for initialization of a Diebold ATM. The generated key is returned in encrypted form in a key specifier for host storage. Also, cryptograms are returned that are suitable for transfer to the NCR ATM, i.e. the encrypted key Block and the digital signature of the encrypted key Block.
Notes: The key-types 10, 11 under the Response Content, are generated when using the Legacy option. The key-types 10, 11, 13 under the Response Content, are generated based on the chosen operation on console and FM. See, section Function Modifier Values.
NOTES
2048 length public keys only. The formats of the encrypted key Block and signature are as described in RSAES-PKCS1v1_5 and RSASSA-PKCS1-v1_5 in [Reference [21] of MarkII].
SHP Toolkit MK2 int EFT_EE9101_GenerateKey_Diebold( IN UCHAR FM, IN EFTBUFFER *I_HOST, IN EFTBUFFER *I_ATM,
SafeNet, Inc.
88
Chapter 9 Remote ATM Initialization Functions EFTBUFFER KEYSPEC KEYSPEC UCHAR UCHAR EFTBUFFER EFTBUFFER KEYSPEC *r_ATM, *e_ATM, *s_HOST, KeyLen, KeyType, *KT_B1, *r_HOST, *K_KTM);
SafeNet, Inc.
89
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
D D D D U
Request Content EE9102 FM KTA2 IHOST rATM rHOST PATM Response Content EE9102 rc
Attribute h h h h h h K-Spec
Description Function Code Function Modifier = 00 PKCS#7 message Identifier of Host ATM random nonce Host random nonce Key specifier for ATM Public Key. (Format: 81, Key Type: Data Signature) Description Function Code Return Code
Length 3 1
Attribute h h
This function processes the ATMs response (KTA2) to the download of the initial key (KTB1). It verifies the signature on the PKCS#7 messages and compares random nonces and identifier provided in the function request.
NOTES
2048 length public keys only.
SHP Toolkit MK2 int EFT_EE9102_VerifyATMResponse_Diebold ( IN UCHAR FM, IN EFTBUFFER *KT_A2, IN EFTBUFFER *I_HOST, IN EFTBUFFER *r_ATM, IN EFTBUFFER *r_HOST, IN KEYSPEC *P_ATM);
SafeNet, Inc.
90
Generate KM NCR
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
D D D D U
Request Content EE9201 FM SK-HSM PK-EPP Response Content EE9201 rc KTM-Spec [KTM]PK-EPP ([KTM]PK-EPP) *SK-HSM KVC(KTM)
Description Function Code Function Modifier = x0 Key specifier for HSM Private Key. (Format: 82) Key specifier for EPP Public Key. (Format: 81) Description Function Code Return Code Key specifier for generated KTM. (Format: 11, 13) Encrypted key Block Signed encrypted key Block NCR Key Verification Value (KVV)
This function generates a random double-length KTM for initialization of an NCR ATM. The generated key is returned in encrypted form in a key specifier for host storage. Also, cryptograms are returned that are suitable for transfer to the NCR ATM, i.e. the encrypted key Block and the digital signature of the encrypted key Block. The formats of the encrypted key Block and signature are as described in sections 4.3 and 4.4 of [Reference [20] of MarkII].
Notes: The key-type 13 under the Response Content, are generated when using the Legacy option. The key-types 11, 13 under the Response Content, are generated based on the chosen operation on console and FM. See section, Function Modifier Values.
NOTES
2048 length public keys only. As per NCR standards, this function support only public exponent 65537.
SHP Toolkit MK2 int EFT_EE9201_GenerateKTM_NCR ( IN UCHAR FM, IN KEYSPEC *SK_HSM, IN KEYSPEC *PK_EPP, OUT OUT OUT KEYSPEC EFTBUFFER EFTBUFFER *KTM, *eKTM_PK_EPP, *sSK_HSM_eKTM_PK_EPP,
SafeNet, Inc.
91
OUT
SafeNet, Inc.
92
SafeNet, Inc.
93
D D D D D
Description Function Code Function Modifier = 00, 10, 20 Key specifier for KIS (Formats: 0 - 3, 10, 11, 13, 15) Key Type indicator / Encryption mode Description Function Code Return Code Number of following key sets. Encrypted Session Key Key specifier for Session key (Formats: 10, 11, 13) Key Verification Code
N eKISnvx(KS) 1 KS-Spec
1
KVC
Notes: The key-types 10, 11, 13 under the Response Content, are generated when using the Legacy option. The key-types 10, 11, 13 under the Response Content, are generated based on the chosen operation on console and FM. See section, Function Modifier Values.
This function generates a set of random DES or 3DES keys for an interchange. The key set may include any of the session keys, PPK, MPK and DPK, and may also include a new key-encrypting key, KIS. For transmitting to the receiving institution, the generated keys are returned encrypted under the appropriate variant of the Interchange Sending Key (KIS) indicated by the 'KIS-Spec' field in the function request. Exceptionally, if a new KIS is to be generated by the function, any session keys that are also generated are returned encrypted by that new KIS. For double-length keys, either ECB or CBC encryption modes may be selected. The generated keys are also returned encrypted under the appropriate *KM variant for storage within the host. The function also returns the KVCs of the generated keys. The function response will contain one or more sets of encrypted key fields as shown: one set for each appropriate bit set in the 'Key Flags' field. That field also indicates the encryption mode for any double-length keys that are generated.
SafeNet, Inc.
94
Chapter 10 Interchange Functions = x0 The Host Key Protection using Function Modifier can be in the range of x0, where x= 0, 1, or 2.
FM
Key Flags
Indicates the received encrypted keys and the encryption mode. The bit positions are allocated as follows: Bit: 0 1 2 3 8 9 10 11 12 13-15 Indicates: Single-length Data Key (DPK). Single-length PIN encrypting key (PPK). Single-length MAC key (MPK). Single-length key-encrypting key (KIS). Double-length Data Key (DPK). Double-length PIN encrypting key (PPK). Double-length MAC key (MPK). Double-length key encrypting key (KIS). Encryption mode for decipher of the inbound eKIRnvx(KS): 0 = ECB; 1 = CBC. Reserved. Must be zero.
Bit 0 is the least significant (right most) bit. eKIRvx(KS) KS-Spec KVC Key encrypted by a variant of the Interchange Receive Key. Key Specifier incorporating an encrypted key. Key Verification Code for the key
Example values of 'Key Flags' field Value of 'Key Flags' field X0004 X0402 X'1600' X'1A00' Encryption mode ECB ECB CBC CBC Keys to be generated Single-length MPK Single-length PPK; double-length MPK Double-length PPK; double-length MPK Double-length KIS; double-length PPK
SafeNet, Inc.
95
5. When the Key Flags specify that a KIS is to be generated: If the KIS keys are HSM stored (KIS-Spec formats 0 - 3), the key referenced must be set to "no variants" If the KIS keys are host stored (KIS-Spec formats 10, 11 and 13) the keys are assumed to have no variants. This will only affect the outgoing eKISvx(KIS) field. If the KIS-Spec is a Format 15, then only when the attributes are set to "no variant scheme" will this key spec be accepted.
Failure caused due to any of the previous 3 occurrences will result in error 0x0C (Inconsistent request fields) being returning as the return code. 6. When the Key Flags specify that a KIS is to be generated this new KIS is returned encrypted with the old KIS. The encryption mode depends upon the Key Flags mode bit.
Error Conditions
The following settings for the Key Flags field will result in a Return Code of 0C. 1. A request for a double-length key to be generated, though the KIS indicated in the request is a single-length key 2. A request to generate a DPK, though this is disabled for the (HSM-stored) KIS. 3. A request to generate a single-length KIS, though the KIS indicated in the request is a doublelength key 4. A reserved bit not set to zero. 5. A request to generate more than one of the same key type (regardless of key length, e.g. Single DPK/Double DPK). Also see point 5 under Details and Restrictions above.
NOTES
The encryption mode for eKISnvx(KS) and KS-Spec is ECB unless otherwise specified. This function will check the length of KISn and use the appropriate encryption method. When there is no variant scheme chosen for the KIS, this function will automatically disable the ability to generate a DPK. This part of the function can be manually enabled from the console by selecting Enable function for data key generation under the KIS Options dialog. The AS2805 variant for KIS is chosen during key input at the HSM console. When the AS2805 variant scheme is used, the double length session key encrypted under KIS is output using CBC. Please refer to the Console User Guide for directions on how to set options for the KIS. This function supercedes function 51, 52, 53. Bits 13-15 of the key flags are reserved.
SafeNet, Inc.
96
int EFT_EE0402_InitialSessionKeyGeneration( IN UCHAR FM, IN KEYSPEC *KIS, IN UCHAR KeyFlags[2], OUT OUT OUT OUT _OUT _OUT _OUT _OUT _OUT _OUT _OUT _OUT _OUT UCHAR EFTBUFFER KEYSPEC UCHAR EFTBUFFER KEYSPEC UCHAR EFTBUFFER KEYSPEC UCHAR EFTBUFFER KEYSPEC UCHAR *numKeys, *eKIS_KS1, *KS1, KVC1[3], *eKIS_KS2, *KS2, KVC2[3], *eKIS_KS3, *KS3, KVC3[3], *eKIS_KS4, *KS4, KVC4[3] );
D D D D D
Request Content EE0403 FM KIR-Spec Key Flags eKIRnvx(KS) Response Content EE0403 Rc
1 1
Description Function Code Function Modifier = x0 Key specifier for KIR (Formats: 0 - 3, 10, 11, 13, 15) Key Type indicator / Encryption mode Encrypted Session Key Description Function Code Return Code Number of following key sets. Key specifier for Session Key (Formats: 10, 11, 13) Key Verification Code
N KS-Spec
1
KVC
Notes: The key-types 10, 11 under the Response Content, are generated when using the Legacy option.
SafeNet, Inc.
97
The key-types 10, 11, 13 under the Response Content, are generated based on the chosen operation on console and FM. See, section Function Modifier Values.
This function re-encrypts a received set of encrypted DES or 3DES keys for host storage. The key set may include any of the session keys, PPK, MPK and DPK, and may also include a new keyencrypting key, KIR. As received from the sending interchange institution, the keys are encrypted under the appropriate variant of the Interchange Receive Key (KIR) indicated by the 'KIR-Spec' field in the function request. Exceptionally, if a new KIR is included in the set, any session keys that are also included must be encrypted by that new KIR. For double-length keys, either ECB or CBC encryption modes are supported. The received keys are returned encrypted under the appropriate *KM variant for storage within the host. The function also returns the KVCs of the received keys. The function request and response will contain one or more sets of encrypted key fields as shown: one set for each appropriate bit set in the 'Key Flags' field. That field also indicates the encryption mode for any double-length keys that are received. FM = x0 The Host Key Protection using Function Modifier can be in the range of x0, where x= 0, 1, or 2. KIR-Spec A key specifier for an HSM-stored or host-stored, single-length or double-length KIR. Accepts key spec formats 0 - 3, 10, 11, 13 and 15. Indicates the received encrypted keys and the encryption mode. The bit positions are allocated as follows: Bit: 0 1 2 3 8 9 10 11 12 13-15 Indicates: Single-length Data Key (DPK). Single-length PIN encrypting key (PPK). Single-length MAC key (MPK). Single-length key-encrypting key (KIS). Double-length Data Key (DPK). Double-length PIN encrypting key (PPK). Double-length MAC key (MPK). Double-length key encrypting key (KIS). Encryption mode for decipher of the inbound eKIRnvx(KS): 0 = ECB; 1 = CBC. Reserved. Must be zero.
Key Flags
Bit 0 is the least significant (right most) bit. eKIRvx(KS) KS-Spec KVC Key encrypted by a variant of the Interchange Receive Key. Key Specifier incorporating an encrypted key. Key Verification Code for the key
Example values of 'Key Flags' field Value of 'Key Flags' field X0004 X0402 X'1600' Encryption mode ECB ECB CBC Keys to be generated Single-length MPK Single-length PPK; double-length MPK Double-length PPK; double-length MPK
SafeNet, Inc.
98
X'1A00'
CBC
Details and Restrictions 1. The formats of the key specifiers in the response are dependent on the key type, and on the format of the KIR-Spec in the request. 2. If an HSM-stored KIR is provided in the request, its associated variant scheme will be used when decrypting an encrypted key using that KIR. 3. If a host stored KIR is provided in the request in a format 10, 11 or 13 key specifier, the default KIR variants used to decrypt the incoming session keys will be SafeNet variants. No variants will be used when the Use 'No Variants' with host stored KIS/KIR flag is set. Please refer to the section Configuration Control in Chapter 5 of the Mark II Console User Guide for further information on setting or clearing this flag. 4. When the AS2805 variant scheme is used (HSM-stored KIR or host-stored KIR in a Format 15 key specifier), a double-length session key encrypted under KIR is decrypted using CBC. The encryption mode flag bit is ignored; i.e. a value of 0 (ECB) will not cause an error. 5. When the Key Flags indicate that a new KIR is included in the set: If the KIR keys are HSM stored (KIR-Spec formats 0 - 3), the key referenced must be set to "no variants" If the KIR keys are host stored (KIR-Spec formats 10, 11 and 13) the keys are assumed to have no variants. This will only affect the incoming eKIRvx(KIR) field. If the KIR-Spec is a Format 15, then only when the attributes are set to "no variant scheme" will this key spec be accepted.
Failure caused due to any of the previous 3 occurrences will result in error 0x0C (Inconsistent request fields) being returning as the return code. 6. When the Key Flags specify that a new KIR is included in the set this new KIR is encrypted with the old KIR (KIR-Spec). The encryption mode depends upon the Key Flags mode bit. Error conditions The following settings for the 'Key Flags' field will result in a Return Code of 0C. 1. A request for a double-length key to be re-encrypted, though the KIR indicated in the request is a single-length key 2. A request to re-encrypt a DPK, though this is disabled for the (HSM-stored) KIR. 3. A request to re-encrypt a single- and double-length key of same type. 4. A reserved bit not set to zero.
NOTES
The encryption mode for eKIRnvx(KS) and KS-Spec is ECB unless otherwise specified. This function will check the length of KIRn and use the appropriate encryption method. When there is no variant scheme chosen for the KIR, this function will automatically disable the ability to generate a DPK. This part of the function can be manually enabled from the console by selecting Enable function for receiving of data keys under the KIR Options dialog. The AS2805 variant for KIR is chosen during key input at the HSM console. When the AS2805 variant scheme is used, the eKIRnvx(KS) must be encrypted using CBC. Please refer to the Console User Guide for directions on how to set options for the KIR. This function supercedes functions 54, 55, 56. Bits 13-15 are reserved.
SafeNet, Inc.
99
SHP Toolkit MK2 int EFT_EE0403_ReceiveInitialSessionKey IN UCHAR FM, IN KEYSPEC *KIR, IN UCHAR KeyFlags[2], IN EFTBUFFER *eKIR_KS1, _IN EFTBUFFER *eKIR_KS2, _IN EFTBUFFER *eKIR_KS3, _IN EFTBUFFER *eKIR_KS4, OUT OUT OUT _OUT _OUT _OUT _OUT _OUT _OUT UCHAR KEYSPEC UCHAR KEYSPEC UCHAR KEYSPEC UCHAR KEYSPEC UCHAR *numKeys, *KS1, KVC1[3], *KS2, KVC2[3], *KS3, KVC3[3], *KS4, KVC4[3]); (
SafeNet, Inc.
100
D D D D D
Description Function Code Function Modifier = x0 Key Type indicator / Encryption mode Key Specifier for Session Key (Formats: 10, 11, 13) Description Function Code Return Code Number of following key sets Encrypted Session Key Key Specifier for Session Key (Formats: 10, 11, 13) Key Verification Code
KSn Spec
KVC
Notes: The key-types 10, 11 under the Response Content, are generated when using the Legacy option. The key-types 10, 11, 13 under the Response Content, are generated based on the chosen operation on console and FM. See, section Function Modifier Values.
This function generates a set of new random DES or 3DES Session Keys (KSn+1-Spec) for an Interchange. For transmitting to the receiving node, the generated keys are returned encrypted under the supplied previous Session Key (KSn). For double-length keys, either ECB or CBC encryption modes may be selected. The generated keys are also returned encrypted under the appropriate variant of the Domain Master Key (*KM), for storage within the host system. This function also returns the KVCs of the session keys. The function response will contain one or more sets of encrypted key fields as shown: one set for each appropriate bit set in the 'Key Flags' field. That field also indicates the encryption mode for any double-length keys that are generated.
SafeNet, Inc.
101
Chapter 10 Interchange Functions = x0 The Host Key Protection using Function Modifier can be in the range of x0, where x= 0, 1, or 2.
FM
Key Flags
Indicates the keys to generate and the encryption mode. The bit positions are allocated as follows: Bit: 0 1 2 3 8 9 10 11 12 13-15 Indicates: Single-length Data Key (DPK). Single-length PIN encrypting key (PPK). Single-length MAC key (MPK). Reserved. Must be zero. Double-length Data Key (DPK). Double-length PIN encrypting key (PPK). Double-length MAC key (MPK). Reserved. Must be zero. Encryption mode for the response encipher: 0 = ECB; 1 = CBC. Reserved. Must be zero.
Bit 0 is the least significant (right most) bit. KSn-Spec EKSn(KSn+1) KSn+1-Spec KVC A key specifier incorporating a session key encrypted by a variant of the Domain master key The new session key encrypted by the supplied session key A key specifier to the new session key Key Verification Code for the new session key
Note
This function returns error code 03 when a = 00 of 01 is utilized. The encryption mode for eKSn(KSn+1) and KSn spec is ECB unless otherwise specified. This function supercedes functions 57, 58, 59. Bit 3, Bit 7, Bit 11 and Bits 13-15 of the key flags are reserved.
SHP Toolkit MK2 int EFT_EE0404_RolloverSessionKeyGeneration ( IN UCHAR FM, IN UCHAR KeyFlags[2], IN KEYSPEC *KSi1, _IN KEYSPEC *KSi2, _IN KEYSPEC *KSi3, OUT OUT OUT OUT _OUT _OUT _OUT _OUT _OUT _OUT UCHAR EFTBUFFER KEYSPEC UCHAR EFTBUFFER KEYSPEC UCHAR EFTBUFFER KEYSPEC UCHAR *numKeys, *eKS_KS1, *KS1, KVC1[3], *eKS_KS2, *KS2, KVC2[3], *eKS_KS3, *KS3, KVC3 [3] );
SafeNet, Inc.
102
D D D D D
Description Function Code Function Modifier = x0 Key Type indicator / Encryption mode Key specifier for Session Key (Formats: 10, 11, 13) Encrypted Session Key Description Function Code Return Code Number of following key sets Key Specifier for Session Key (Formats: 10, 11, 13) Key Verification Code
KSn Spec
n KSn+1 Spec
1
KVC
Notes: The key-types 10, 11 under the Response Content, are generated when using the Legacy option. The key-types 10, 11, 13 under the Response Content, are generated based on the chosen operation on console and FM.
This function allows a Session Key rollover for the interchange. It re-encrypts a received set of encrypted DES or 3DES keys for host storage. The key set may include any of the session keys, PPK, MPK and DPK. The node receives a set of new Session Keys (KSn+1) encrypted under the current one (KSn) and sends them together with the current Session Key encrypted under the appropriate *KM Variant to the HSM. For double-length keys, either ECB or CBC encryption modes are supported. The HSM returns the new Session Keys encrypted under the appropriate *KM Variant, for storage within the host. This function also returns the KVCs of the session keys. FM = x0 The Host Key Protection using Function Modifier can be in the range of x0, where x= 0, 1, or 2. Key Flags Indicates the keys to generate and the encryption mode. The bit positions are allocated as follows: Bit: 0 1 2 3 Indicates: Single-length Data Key (DPK). Single-length PIN encrypting key (PPK). Single-length MAC key (MPK). Reserved. Must be zero.
SafeNet, Inc.
103
Chapter 10 Interchange Functions 8 9 10 11 12 Double-length Data Key (DPK). Double-length PIN encrypting key (PPK). Double-length MAC key (MPK). Reserved. Must be zero. Encryption mode for the response encipher: 0 = ECB; 1 = CBC. 13-15 Reserved. Must be zero. Bit 0 is the least significant (right most) bit.
Key specifier incorporating an encrypted session key. A new session key encrypted by the old Session Key. Key Verification Code of the session key
NOTES
This function returns error code 03 when a = 00 of 01 is utilized. The encryption mode for eKSn(KSn+1) and KSn spec is ECB unless otherwise specified. This function supercedes functions 5A, 5B, 5C. Bit 3, Bit 7, Bit 11 and Bits 13-15 of the key flags are reserved.
SHP Toolkit MK2 int EFT_EE0405_ReceiveRolloverSessionKey( IN UCHAR FM, IN UCHAR KeyFlags[2], IN KEYSPEC *KSi1, IN EFTBUFFER *eKS_KSi1, _IN _IN _IN _IN _IN _IN OUT OUT OUT _OUT _OUT _OUT _OUT _OUT _OUT KEYSPEC EFTBUFFER KEYSPEC EFTBUFFER KEYSPEC EFTBUFFER UCHAR KEYSPEC UCHAR KEYSPEC UCHAR KEYSPEC UCHAR KEYSPEC UCHAR *KSi2, *eKS_KSi2, *KSi3, *eKS_KSi3, *KSi4, *eKS_KSi4, *numKeys, *KS1, KVC1[3], *KS2, KVC2[3], *KS3, KVC3[3], *KS4, KVC4[3]);
SafeNet, Inc.
104
Creation of a Host Stored PVK for format 13 is calculated by the following method: Left hand side of the key becomes the Single Length PVK e.g. 1111111111111111 Right hand side of the key becomes the Decimalization Table value e.g. 0123456789012345
These two halves are then concatenated together to form a double length DES key, and then encrypted under the appropriate KM variant for use within a function. Creation of a Host Stored PVK for format 14 is calculated by the following method: Left hand side of the key becomes the Double Length PVK e.g. 33333333333333331111111111111111 Right hand side of the key becomes the Decimalization Table value e.g. 0123456789012345
These two halves are then concatenated together to form a triple length DES key, and then encrypted under the appropriate KM variant for use within a function.
SafeNet, Inc.
105
SafeNet, Inc.
106
PIN Encryption
CLR-PIN-ENCRYPT
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
D D D D U
Attribute h h h d d K-Spec
Description Function Code Function Modifier = 00 Number of digits in PIN field Clear PIN Account Number Block Key specifier for PPK (Formats: 0 - 3, 10, 11, 13, 20, 90) Description Function Code Return Code Encrypted output PIN
Length 3 1 8
Attribute h h h
This function accepts a clear PIN, formats it into an ANSI PIN Block and encrypts the Block using the supplied PPK. FM = 00. Must be set to zero. PIN-Len PIN Identifies the number of digits in the PIN, in the range 4 12. Clear PIN consisting of from 4 to 12 digits, packed 2 digits per byte. If PIN-len is odd, the digits must be left justified in the PIN field with one trailing decimal pad digit. Key specifier for the PPK (eKMv1 - Format 0-3, 10, 11, 13, 20 or 90). 12 PAN digits of the Account Number Block used to format the ANSI PIN Block.
PPK-Spec ANB
NOTES
Please contact SafeNet if you require this functionality or further details. SHP Toolkit MK2 int EFT_EE0600_ClearPinEncrypt( IN UCHAR FM, IN UCHAR PinLen, IN EFTBUFFER *PIN, IN UCHAR ANB[6], IN KEYSPEC *PPK,
OUT
UCHAR
ePPK_PIN[8]);
SafeNet, Inc.
107
MIGRATEPIN
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
D D D D D
Request Content EE0601 FM PVK1-Spec PAN Offset1 PINLEN PVK2-Spec Response Content EE0601 rc Offset2
Description Function Code Function Modifier = 00 Key specifier for old PVK (Formats: 0 - 3) Validation data. Existing offset for the PIN Number of digits in the PIN Key specifier for new PVK (Formats: 0 - 3) Description Function Code Return Code Replacement offset for PIN
This function migrates a PIN from one 3624 PVK to another. Note that this function will work only as permitted by the controlling console operation. Please refer to the MarkII Console User Guide for details on how to control this function via the console. FM PVK1-Spec PVK2-Spec PAN Offset1 Offset2 PINLEN = 00. Must be set to zero. Key specifiers that incorporate an index to an HSM-stored PVK and associated Decimalization Table. The values specified must be as previously set in the controlling console operation, The validation data that is used with the PVK and Decimalization table to produce the Offset. Existing and replacement PIN offset data. The significant digits are left-justified in the field. Identifies the number of digits in the PIN, and hence the length of the Derived PIN
For additional details regarding the 3624 PIN verification method, please refer to Appendix A. Note for users of CHKLEN during PIN verification: If CHKLEN < PINLEN and only CHKLEN digits of the existing PIN offset are available, then these digits need to be provided, positioned appropriately in the Offset1 field. The significant digits of the new PIN offset will be in the same position in the Offset2 field. Function Specific Return code. 02 Signifies that PVK 1 or PVK 2 has not been initialized for PIN migration via the console.
SafeNet, Inc.
108
int EFT_EE0601_MigratePin ( IN UCHAR FM, IN KEYSPEC *PVK1, IN UCHAR PAN[8], IN UCHAR offset1[6], IN UCHAR PinLen, IN KEYSPEC *PVK2, OUT UCHAR offset2[6]);
SafeNet, Inc.
109
PIN Translation
PIN-TRAN-2
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
D D D D D
Request Content EE0602 FM ePPKi(PIN) PPKi-Spec PFi ANB PFo PPKo-Spec Response Content EE0602 rc ePPKo(PIN)
Description Function Code Function Modifier = 00 Encrypted PIN Block. Key specifier for PPK (Formats: 0 - 3, 10, 11, 13, 20, 90) Input PIN Block format Account Number Block Output PIN Block format Key specifier for PPK (Formats: 0 - 3, 10,11, 13, 90) Description Function Code Return Code Encrypted PIN Block
This function performs translation of both the PIN Block format and the PIN encryption key. PFi PFo specifies the format of the input PIN Block format and supports PIN formats, 01, 02, 03, 08, 09, 10, 11, and 13, if enabled. specifies the output PIN Block format and supports PIN formats: 01, 02, 03, 08, 09, 10, 11, 12, and 13, if enabled. Specific restrictions on reformatting are specified in Chapter 2. Account Number Block, which is the right most 12 digits of the Primary Account Number (PAN), excluding the check digit. The key specifiers, PPKi-Spec and PPKo-Spec, may be any valid key specifier for a PPK. Consequently, the function supports all combinations of single-length and double-length HSM-stored and host-stored keys. For example, the input key could be a single-length, host-stored key and the output key could be a double-length HSM stored key.
The function will fail with Error Code 78 if PFi or PFo indicates a PIN block format that is disabled or conflicts with the reformatting restrictions.
NOTE
This function includes all the capabilities of the following existing functions, and therefore supercedes the following: PIN- TRAN (60), D51-PIN-TRAN (65), PIN-TRAN-1 (94), PIN-TRAN-2 (95). SHP Toolkit MK2
SafeNet, Inc.
110
int EFT_EE0602_PinTranslate ( IN UCHAR FM, IN UCHAR ePPKi_PIN[8], IN KEYSPEC *PPKi, IN UCHAR PFi, IN UCHAR ANB[6], IN UCHAR PFo, IN KEYSPEC *PPKo, OUT UCHAR ePPKo_PIN[8]);
FM
When FM=01, an additional Field (Session Method, see below for details) is incorporated into the function. If FM = 00 the function remains as per EE0602 Specifies the format of the input PIN Block format and supports PIN formats, 01, 02, 03, 08, 09, 10, 11, and 13 specified on page 25. Account Number Block, which is the rightmost 12 digits of the Primary Account Number (PAN), excluding the check digit. When Fm=01 Session Method 00 ECB, 01 CBC, is evoked on ePPKo (PIN + PIN Data)
PFi ANB
PFo
Specifies the output PIN Block format and supports PIN formats: 01, 03, 08, 09, 10, 11, 12, and 13 specified on page 25. The following restriction applies: formats 08 (Docutel) and 11 (ISO Format 1) are valid only in the case that PFo = PFi i.e. that the clear text PIN Block format is not changed. If PIN format translation is not required, PFo must be set to the same value as PFi. The key specifiers, PPKi-Spec and PPKo-Spec, may be any valid key specifier for a PPK. Consequently, the function supports all combinations of single-length and double-length, HSM-stored and host-stored keys. For example, the input key could be a single-length, host-stored key and the output key could be a double-length, HSM stored key. Used when FM = 01. Session Method encrypts ePPKo(PIN + PIN Data) as per selected method. 00 = ECB, 01 = CBC. Variable length field of either 8 or 16 bytes dependent upon length of PIN Data supplied.
Session Method
Data to incorporate with PIN in encrypted result. The data Block would typically incorporate the PIN Try Counter and PIN Try Limit, as specified in reference of Mark II, but no checks are applied to the data content. The field can contain 0 or 8 bytes. If the length is 0, this function performs identically to the PIN_TRANSLATE function. If the length is 8, the data Block is concatenated to the right of the (re-)formatted, plaintext PIN Block and the resulting 16-byte character sequence is CBC-encrypted using the PPKo.
SafeNet, Inc.
111
PIN Verification
PIN-VER-IBM-MULTI
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
D D D D D
Request Content EE0603 FM ePPK(PIN) PPK-Spec PF ANB PVK-Spec Validation Data Offset Check-Len Response Content EE0603 rc
Description Function Code Function Modifier = 00 Encrypted PIN Block Key specifier for PPK (Formats: 0 - 3, 10, 11, 13, 20, 90) PIN Block Format Account Number Block Key specifier for PVK (Formats: 0 - 3, 11, 12, 13, 14) Validation Data Existing offset for the PIN PIN Check Length (04 - 12) Description Function Code Return Code
This function performs the verification of a PIN using the IBM 3624 Offset method. The PIN is supplied in encrypted form, using any of the PIN Block formats. PPK-Spec May be any valid key specifier for a PPK. Consequently, the function supports an encrypted PIN Block encrypted using a single-length or doublelength HSM-stored or host-stored key. Supports PIN formats: 01, 02, 03, 08, 09, 10, 11, 13, 20 and 90. Account Number Block, which are the right most 12 digits of the Primary Account Number (PAN), excluding the check digit. Data (usually a part of the PAN) used in the calculation of the reference PIN. Up to 12 digits of offset data. The significant digits must be left justified in the field. Unused digits are ignored. If offsets are not used, the significant digits must be zeros. The number of PIN digits to be checked. This may be less than or equal to the actual length of the PIN. The significant Offset digits must be supplied left aligned and right padded in the Offset field.
Check-Len
The function will fail with Error Code 78 if PF indicates a PIN block format that is disabled.
NOTE
This function includes all the capabilities of the following existing functions, and therefore supercedes the following:
SafeNet, Inc.
112
PIN-VER (61), PIN-VER-PP (62), D51-PIN-VER (66), VAR-PIN-VER (67), VAR-PIN-VER-PP (68).
SHP Toolkit MK2 int EFT_EE0603_PinVerify_IBM( IN UCHAR FM, IN UCHAR ePPK_PIN[8], IN KEYSPEC *PPK, IN UCHAR PF, IN UCHAR ANB[6], IN KEYSPEC *PVK, IN UCHAR pan[8], IN UCHAR offset[6], IN UCHAR ChkLen);
SafeNet, Inc.
113
D D U U U
Length 1 8 1 8 6 Length 1 1 8
Description Function Code PIN Block encrypted under PVK Index of PVK PPK encrypted under KM Account Number Block Description Function Code Return Code PIN Block encrypted under PPK
This function translates both the format and the encryption key of a PIN Block which is supplied encrypted by a HSM stored PIN Verification Key (PVK). PP-PIN PVK-index eKMv1(PPK) ANB is the PIN/PAD formatted PIN Block. It must be supplied encrypted by a HSM stored PIN Verification KEY (PVK). identifies the PVKn with which the supplied PIN Block is encrypted. is the host stored encrypted session key with which the resultant AS/ANSI PIN Block is returned encrypted. is the 12-digit Account Number Block used in the formation of the clear AS/ANSI PIN Block.
The function will fail with Error Code 78 if PIN/PAD or ISO-0 PIN block is disabled or reformatting of PIN/PAD to ISO-0 PIN block is disabled.
SafeNet, Inc.
114
D D U U U
Request Content 64 PVK-Index KTM-Index eKTMn(AS-PIN) PAN ANB Offset Response Content 64 rc
Length 1 1 1 8 8 6 6 Length 1 1
Description Function Code Index of PVK Index of KTM PIN Block encrypted under KTM Primary Account Number Account Number Block Offset for the PIN Description Function Code Return Code
This function performs the verification of a PIN in an AS/ANSI formatted PIN Block using the IBM 3624 method. The PIN Block is supplied encrypted by a SafeNet HSM stored Base Key. PVK-index KTM-Index AS-PIN PAN ANB Offset identifies the PVKn, DTn, and MINPINn appropriate to the PIN verification procedure. identifies the Terminal Master Key (KTMn) with which the PIN Block is encrypted. is the AS/ANSI formatted PIN Block containing the PIN to be verified. is the Primary Account Number (or other card data) used in the verification procedure. It must be padded appropriately prior to input to this function. is the 12-digit Account Number Block used in the formation of the clear AS/ANSI PIN Block. consists of up to 12 digits of offset data. The significant digits must be leftjustified in the field. Unused digits are ignored. If offsets are not used, the significant digits must be zeros.
The function returns no response data. An Error Code of 00 indicates successful verification, while 08 indicates a verification failure. The function will fail with Error Code 78 if an ISO-0 PIN block is disabled.
SafeNet, Inc.
115
D D U U U
Request Content 69 PVK-Index KTM-Index eKTM(AS-PIN) PAN ANB CHKLEN Offset Response Content 69 rc
Length 1 1 1 8 8 6 1 6 Length 1 1
Description Function Code Index of PVK Index of KTM PIN Block encrypted under KTM Primary Account Number Account Number Block PIN Check Length (04 12) Offset for the PIN Description Function Code Return Code
This function verifies an AS/ANSI formatted PIN. The PIN Block must be supplied encrypted under an HSM stored Terminal Master Key (KTM). Note that only the first 99 KTMs may be used with this function. PK-Index AS-PIN PAN ANB CHKLEN identifies the PVKn, DTn, and MINPINn appropriate to the PIN verification procedure. is the AS/ANSI formatted PIN Block containing the PIN to be verified. It must be supplied encrypted by a PIN Protect session key (PPK). the Primary Account Number used in the verification procedure. It must be padded appropriately prior to input to this function. is the 12-digit Account Number Block used in the formation of the clear AS/ANSI PIN Block. The CHKLEN field contains the number of PIN digits to be checked and may be less than, or equal to, the actual length of the PIN. The significant Offset digits must be supplied left aligned and right padded in the Offset field. consists of up to 12 digits of offset data. The significant digits must be leftjustified in the field. Unused digits are ignored. If offsets are not used, the significant digits must be zeros.
Offset
The function will fail with Error Code 78 if an ISO-0 PIN block is disabled. See Appendix A, for a more detailed overview of the PIN verification procedure.
SafeNet, Inc.
116
D D D D D
Request Content EE0604 FM ePPK(PIN) PPK-Spec PF ANB PVK-Spec Validation Data Response Content EE0604 rc Offset PINLEN
Description Function Code Function Modifier = 00 PIN Block encrypted under PPK Key specifier for PPK (Formats: 0 - 3, 10, 11, 13, 20, 90) PIN Block Format Account Number Block Key specifier for PVK (Formats: 0 - 3, 11, 12, 13, 14) Validation Data Description Function Code Return Code Offset for the PIN Length of returned PIN
This function calculates an IBM 3624 Offset for a PIN and also provides the length of the PIN. The PIN is supplied in encrypted form, using any of the PIN Block formats specified in Appendix A. PPK-Spec May be any valid key specifier for a PPK. Consequently, the function supports an encrypted PIN Block encrypted using a single-length or doublelength HSM-stored or host-stored key. Supports PIN formats: 01, 03, 08, 09, 10, 11, and 13. Account Number Block, which is the right most 12 digits of the Primary Account Number (PAN), excluding the check digit. Data, which is usually a part of the PAN, and is used in the calculation of the reference PIN.
The function will fail with Error Code 78 if PF indicates a PIN block format that is disabled. The function performs a check that the ANB field and the Validation field contain a number of consecutive digits in common. The number of digits to check is in the range 0 to 12, as may be specified using a console operation, and defaults to 8. If the number of digits to check has been set to 0 the check is disabled, and in this case the function will accept any supported PIN block format that is enabled. If the number of digits to check is greater than 0, then only ISO-0 and ISO-3 PIN blocks are allowed, if enabled. If the check fails, the function will fail with Return Code 79.
SafeNet, Inc.
117
NOTE
This function includes all the capabilities of the following existing functions, and therefore supercedes the following PIN-OFF-AS (6A), PIN-OFF-PP (6B) SHP Toolkit MK2 int EFT_EE0604_CalculateIBMOffset_EncPIN( IN UCHAR FM, IN UCHAR ePPK_PIN[8], IN KEYSPEC *PPK, IN UCHAR PF, IN UCHAR ANB[6], IN KEYSPEC *PVK, IN UCHAR pan[8], OUT UCHAR offset[6], OUT UCHAR *PinLen);
SafeNet, Inc.
118
PIN-FROM-OFF
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
D D U D D
Length 3 1 Var
Attribute h h K-Spec
Description Function Code Function Modifier = 00 Key specifier for PVK/DT used in the regeneration of the reference PIN. (Formats: 0 - 3, 11, 12, 13, 14) Validation Data Offset Data Length of PIN ( 04 - 12) Key specifier for PPK (Formats: 0 - 3, 11, 13) PIN Block Format (Formats: 01, 10, 11, 13) Account Number Block -12 digits of the Primary Account Number (PAN), excluding the check digit Description Function Code Return Code Encrypted PIN Block
8 6 1 Var 1 6
h h h K-Spec h d
Length 3 1 8
Attribute h h x
This function calculates a PIN from a supplied IBM 3624 Offset for a PIN and returns the PIN encrypted using the supplied PPK from the request. The PIN is returned in encrypted form, using the PIN format specified in the request (PFo). The PIN Block format for output is represented in the request using PFo and can be any of the PIN Block formats indicated below. PVK PVK-Spec may be key specifier formats: HSM-stored (0-3) and Host-stored 13 and 14. When the key specifier format is Hoststored 13 or 14, then PVK is encrypted with KMv7. PVK key specifier represents the PVK and associated Decimalization Table and is used with the IBM offset supplied in the request to regenerate the PIN. Validation Data, which is usually a part of the Primary Account Number (PAN), and is used in the calculation of the reference PIN. Offset, consists of up to 12 nibbles of offset data. The significant nibbles must be left-justified in the field. For example, if the offset to be used is 0x1234, this should be formatted as 0x123400000000 in this field. Unused nibbles are ignored. PIN Length, identifies the number of digits in the PIN, and hence the length of the PIN.
Validation data
Offset
PIN Length
SafeNet, Inc.
119
Chapter 11 PIN Management Functions PPK-Spec may be key specifier formats: HSM-stored (0-3) and Host-stored 11 and 13. When the key specifier format is Hoststored 11 and 13, then PPK is encrypted with KMv1.The function supports HSM-stored single-length and double-length DES keys, host-stored double-length DES keys PFo Supports PIN formats: 01, 10, 11 and 13. Account Number Block, which is the right-most 12 digits of the Primary Account Number (PAN), excluding the check digit.
PPK
PFo ANB
The function will fail with Error Code 78 if PFo indicates a PIN block format that is disabled.
NOTES
Calculation of an IBM offset is unrelated to PIN Block formats. A Derived PIN may also be generated by this method if an Offset of all zeros is used.
SHP Toolkit MK2 int EFT_EE0609_CalculatePINFromOffset( IN UCHAR FM, IN KEYSPEC *PVK, IN UCHAR Validation_Data[8], IN UCHAR Offset[6], IN UCHAR Pin_Length, IN KEYSPEC *PPK, IN UCHAR PFo, IN UCHAR ANB[6], OUT UCHAR ePPK_PIN[8]);
SafeNet, Inc.
120
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
D D D D D
Request Content EE0640 FM PIN Len ANB Response Content EE0640 rc PIN-Spec
Description Function Code Function Modifier = 00 Length of PIN ( 04 - 12) Account Number Block: Description Function Code Return Code KM-encrypted PIN Block (Format: 1A)
This function generates a random PIN of the specified length and creates a format 1A key specifier, as defined in Chapter 2. The function will fail with Error Code 78 if PIN block format ISO-3 is disabled. SHP Toolkit MK2 int EFT_EE0640_GEN_KM_ENC_PIN( IN UCHAR FM, IN UCHAR PINLen, IN UCHAR ANB[6], OUT KEYSPEC *eKM_PIN);
SafeNet, Inc.
121
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
D D U D D
Length 3 1 Var 6 8
Attribute h h K-Spec h h
Description Function Code Function Modifier = 00 KM-encrypted PIN Block (Format: 1A) Account Number Block Primary Account Number. Content is significant only if PAN print is selected in PIN Mail control screen. Repeat count for the following data sets. This set of fields specifies data to be printed at a given line and column. The set of fields is optional and may be repeated multiple times, as specified by the Data sets field, causing 0, 1 or more data fields to be printed Description Function Code Return Code
1 1 1 Var
h h h h
Length 3 1
Attribute h h
NOTE
The function performs the same process as PIN-PRINT (EE0E05). The only difference is the form of the encrypted PIN input to the function. The function will fail with Error Code 78 if PIN block format ISO-3 is disabled. SHP Toolkit MK2 int EFT_EE0641_Print_eKMPin( IN UCHAR FM, IN KEYSPEC *eKM_PIN, IN UCHAR ANB[6], IN UCHAR PAN[8], IN _IN _IN _IN _IN _IN UCHAR UCHAR UCHAR EFTBUFFER UCHAR UCHAR DataSets, *LineNo1, *ColumnNo1, *Data1, *LineNo2, *ColumnNo2,
SafeNet, Inc.
122
Chapter 11 PIN Management Functions EFTBUFFER UCHAR UCHAR EFTBUFFER UCHAR UCHAR EFTBUFFER UCHAR UCHAR EFTBUFFER UCHAR UCHAR EFTBUFFER UCHAR UCHAR EFTBUFFER UCHAR UCHAR EFTBUFFER UCHAR UCHAR EFTBUFFER UCHAR UCHAR EFTBUFFER *Data2, *LineNo3, *ColumnNo3, *Data3, *LineNo4, *ColumnNo4, *Data4, *LineNo5, *ColumnNo5, *Data5, *LineNo6, *ColumnNo6, *Data6, *LineNo7, *ColumnNo7, *Data7, *LineNo8, *ColumnNo8, *Data8, *LineNo9, *ColumnNo9, *Data9, *LineNo10, *ColumnNo10, *Data10);
_IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN
SafeNet, Inc.
123
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
D D D D D
Request Content EE0642 FM ePPK(PIN) PPK-Spec PF ANB PIN-Spec Response Content EE0642 rc
Description Function Code Function Modifier = 00 Encrypted PIN Block Key specifier for PPK (Formats: 0 - 3, 10, 11, 13, 20, 90) PIN Block Format (Formats: 01, 03, 08, 09, 10, 11, 13) Account Number Block KM-encrypted PIN Block (Format: 1A) Description Function Code Return Code
This function verifies a transaction PIN by comparing it with a KM-encrypted reference PIN.
NOTE
The ANB field is used (if required) in recovering the transaction PIN. It is also used to recover the reference PIN. The function will fail with Error Code 78 if either PIN block format ISO-3 or PIN block format indicated by PF is disabled.
SHP Toolkit MK2 int EFT_EE0642_Verify_eKMPin( IN UCHAR FM, IN UCHAR ePPK_PIN[8], IN KEYSPEC *PPK, IN UCHAR PF, IN UCHAR ANB[6], IN EFTBUFFER *eKM_PIN);
SafeNet, Inc.
124
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
D D D D D
Request Content EE0643 FM ePPK(PIN) PPK-Spec PF ANB Response Content EE0643 rc PIN-Spec
Description Function Code Function Modifier = 00 Encrypted PIN Block Key specifier for PPK (Formats: 0 - 3, 10, 11, 13, 20, 90) PIN Block Format (Formats: 01, 03, 08, 09, 10, 11, 13) Account Number Block Description Function Code Return Code KM-encrypted PIN Block (Format: 1A)
This function translates a PIN from encryption using PPK to encryption using KM.
NOTES
The ANB field is used (if required) in recovering the input PIN. It is also used to build the KMencrypted PIN. The function will fail with Error Code 78 if PIN block format ISO-3 or PIN block format indicated by PF is disabled or conflicts with the reformatting restrictions..
SHP Toolkit MK2 int EFT_EE0643_TRANSPIN_PPKTOLMK( IN UCHAR FM, IN UCHAR ePPK_PIN[8], IN KEYSPEC *PPK, IN UCHAR PF, IN UCHAR ANB[6], OUT KEYSPEC *eKM_PIN);
SafeNet, Inc.
125
Migrate PIN
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
D D D D D
Description Function Code Function Modifier = 00 KM-encrypted PIN Block (old KM) (Format: 1A) Account Number Block Description Function Code Return Code KM-encrypted PIN Block (current KM) (Format: 1A)
This function re-encrypts a KM-encrypted PIN from the old KM to the current KM. The function will fail with Error Code 78 if PIN block format ISO-3 is disabled. SHP Toolkit MK2 int EFT_EE0644_Migrate_eKMPin( IN UCHAR FM, IN KEYSPEC *eKM_PINi, IN UCHAR ANB[6], OUT KEYSPEC *eKM_PINo);
SafeNet, Inc.
126
IT-PVK-EXPORT
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
U U D D U
Length 3 1 Var 1
Attribute h h K-Spec h
Description Function Code Function Modifier = 00 Key specifier for PVK (Formats: 0 - 3) Encryption Method 10 = ECB 11 = Reserved 12 = Reserved Key specifier for KTM (Formats: 0 - 3, 10, 11, 13) Description Function Code Return Code Encrypted PVK (single length key) KVC for PVK
K-Spec Attribute h h h h
This function encrypts a HSM Stored PVK with the nominated KTM and returns it encrypted for use in terminals that can do standalone PIN Verification. FM PVK-Spec = 00. Must be set to zero or one. Key specifier which provides access to the PVK. Only HSM-stored keys are currently supported, so the key specifier must contain a key index. A key specifier which incorporates an index to an HSM-stored or host stored single-length or double-length KTM. Encrypted PVK. The size of this field is 9 bytes as only single length PVKs may be ECB encrypted.
KTM-Spec
eKTM(PVK)
SHP Toolkit MK2 int EFT_EF0210_IT_PVK_Export( IN UCHAR FM, IN KEYSPEC *PVK, IN UCHAR Mode, IN KEYSPEC *KTM, OUT EFTBUFFER *eKTM_PVK, OUT UCHAR KVC[3]);
SafeNet, Inc.
127
SafeNet, Inc.
128
The following functions respect the above described password restrictions: Function Name OBM SetPassword RSAEncrypted TPV Function Code EE3004
SafeNet, Inc.
129
OBM ChangePassword RSAEncrypted TPV OBM PrintPassword OBM MigratePIN OffsetToTPV OBM GenerateRandomPIN
Attribute Struct
Description Represents a field that contains a structure that is made up of any number and variety of the other fields. EFB Processing Unit and CTPV Processing Unit, described below, are examples of the struct operator.
SafeNet, Inc.
130
Pre-requisites: None Process: Decrypt and decode the RSA-encrypted PIN Block. Result: Error Code or Plaintext PIN Block (M). Processing steps 1. Retrieve the index from the key specifier: SK-Spec. Read the RSA private key (SK) from the entry in the RSA Key Pair table indicated by the index. 2. Decrypt the RSA-encrypted PIN Block, C, using SK. 3. Decode the resulting PIN Block, in accordance with PKCS #1 and using parameter string P, and thereby recovering the message M. 4. Check that the header byte is equal to 1 or 2. 5. Check that the PIN Blocks contained in M are valid Format 2 or Format 12 PIN Blocks. If not, return an appropriate value in Error Code. 6. Compare the provided random number, RN, with the rightmost bytes of M. If the values do not agree, return an appropriate value of Error Code.
SafeNet, Inc.
131
1. If Algorithm Identifier indicates that the PIN is to be hashed (= x1 or x2): Extract the PIN from the PIN Block. If Format 2, unpack the digits and convert to ASCII. Build the hash data, consisting of DataA (if present) followed by the ASCII PIN followed by DataB (if present), and execute the appropriate hash function to obtain the hash result. If no encryption is required (Algorithm Identifier = 01 or 02), supply the hash result as the Transformed PIN Value. 2. If Algorithm Identifier indicates that the PIN is to be hashed and encrypted (= 11 or 12): If the hash algorithm is SHA-1, pad the hash result to the left with 4 bytes of zeroes to make the length a multiple of 8 bytes. Encrypt the 16 bytes (MD5) or 24 bytes (SHA-1) using the KTPV from KTPV-Spec, the CBC mode of operation and an IV of zeroes. Supply the resulting cipher text as the Transformed PIN Value. 3. If Algorithm Identifier indicates that the PIN is to be encrypted only (= 10): If the PIN Block is Format 2, convert to Format 0 using the data provided in DataA and DataB, (i.e. XOR DataA and DataB and XOR the result onto the PIN Block). Encrypt the result using the KTPV from KTPV-Spec. Supply the resulting encrypted PIN Block as the Transformed PIN Value. Otherwise (Format 12), XOR DataA and DataB and XOR the result onto the PIN Block excluding the first two bytes of the PIN Block. [This is similar to the formatting for the format 0 PIN Block.] Encrypt the resulting formatted PIN Block using the KTPV from KTPV-Spec, the CBC mode of operation and an IV of zeroes. Supply the resulting cipher text as the Transformed PIN Value. Note: The characters of DataA and DataB are XOR'd with the PIN Block. If more data is available in the field than is required, the leftmost characters are used; if insufficient characters are supplied they will be right-justified and padded to the left with zeroes. No demand has been made that the correct number of characters are supplied, as the application may not know whether a Format 2 or 12 PIN Block has been recovered or the length of the Format 12 Block.
SafeNet, Inc.
132
OBM GetPublicKey()
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
D D U D U
Length 3 1 Var
Attribute h h K-Spec
Description Function Code Function Modifier = 00 Key specifier for RSA Public Key (Formats: 0 3) Provides the index into the key table in secure memory where the key is stored Description Function Code Return Code Key specifier for RSA Public Key (Format: 80) Contains the key retrieved from secure memory Public Verification Code for PK
Length 3 1 Var
Attribute h h K-Spec
PVC
This function retrieves a Public Key from the HSM stored RSA Key Pair table in secure memory and returns it in a clear form in a key specifier along with the PVC for the key.
SHP Toolkit MK2 int EFT_EE3000_OBM_GetPublicKey( IN UCHAR FM, IN KEYSPEC *PK1, OUT OUT KEYSPEC UCHAR *PK2, PVC[8]);
SafeNet, Inc.
133
OBM GenerateRandomNumber
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
D D U D U
Attribute h h h Attribute h h h
Description Function Code Function Modifier = 00 = 01 FF.(Range = 01 255) Description Function Code Return Code Random Number with length as specified in Length of Random Number
This function generates and returns a random number of the specified length.
SHP Toolkit MK2 int EFT_EE3001_OBM_GenerateRandomNumber( IN UCHAR FM, IN UCHAR Length, OUT EFTBUFFER *RandomNumber);
SafeNet, Inc.
134
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
D D U D U
Request Content EE3002 FM EPB PVK-Spec Validation Data Offset Response Content EE3002 Rc
Description Function Code Function Modifier = 00 Decrypt and decode RSA-encrypted PIN Block Key specifier for PVK and Decimalization Table (Formats: 0 - 3, 11, 12, 13, 14) Customer data usually part of the PAN PIN offset Data Description Function Code Return Code
This function extracts the PIN from an RSA-encrypted PIN Block and verifies the PIN using the 3624 Offset method. Notes: This function only supports PINs in standard ISO format 2 This function only supports messages containing one PIN Block Processing steps 1. Decrypt and decode the RSA-encrypted PIN Block using EPB PU to recover the PIN Block, M. If the resulting Error Code is non-zero then end function processing and return appropriate value in Return Code. 2. Calculate the reference PIN, using the PVK and Decimalization Table indicated by PVK-Spec, Validation Data and Offset. 3. Compare the reference PIN with the transaction PIN (from recovered PIN Block, M). Return the result of the comparison in Return Code.
SHP Toolkit MK2 EXPORT int EFT_EE3002_OBM_VerifyPIN_RSAEncrypted_3624Offset( IN UCHAR FM, IN KEYSPEC *SK, IN EFTBUFFER *C, IN EFTBUFFER *P, IN EFTBUFFER *RN, IN KEYSPEC *PVK, IN UCHAR ValidationData[8], IN UCHAR Offset[6]);
SafeNet, Inc.
135
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
D D U D U
Request Content EE3003 FM EPB PVK-Spec1 Validation Data1 Offset1 PVK-Spec2 Validation Data2 Response Content EE3003 Rc Offset2
Description Function Code Function Modifier = 00 Decrypt and decode RSA-encrypted PIN Block Key specifier for PVK and Decimalization Table (Formats: 0 3, 11, 12, 13, 14) Customer data usually part of the PAN PIN offset data Key specifier for PVK and Decimalization Table (Formats: 0 3, 11, 12, 13, 14) Customer Data usually part of the PAN Description Function Code Return Code Returned PIN offset data
This function extracts the old PIN and new PIN from an RSA-encrypted PIN Block, verifies the old PIN and calculates a PIN offset for the new PIN. Notes: This function only supports PINs in standard ISO format 2 This function only supports messages containing two PIN Block Processing steps 1. Decrypt and decode the RSA-encrypted PIN Block using EPB PU to recover the PIN Block, M. If the resulting Error Code is non-zero then end function processing and return appropriate value in Return Code. 2. Calculate the reference PIN, using the PVK and Decimalization Table indicated by PVK-Spec1, Validation Data1 and Offset1. 3. Compare the reference PIN with the transaction old PIN (from PB1 in the recovered PIN Block, M). Store the result of the comparison in Return Code. 4. If the PIN verification succeeds, calculate the PIN offset for the transaction new PIN (from PB2 in the recovered PIN Block, M) using PVK-Spec2 and Validation Data2. 5. Return the PIN offset in Offset2. SHP Toolkit MK2
SafeNet, Inc.
136
EXPORT int EFT_EE3003_OBM_ChangePIN_RSAEncrypted_3624Offset( IN UCHAR FM, IN KEYSPEC *SK, IN EFTBUFFER *C, IN EFTBUFFER *P, IN EFTBUFFER *RN, IN KEYSPEC *PVK1, IN UCHAR ValidationData1[8], IN UCHAR Offset1[6], IN KEYSPEC *PVK2, IN UCHAR ValidationData2[8], OUT UCHAR Offset2[6]);
SafeNet, Inc.
137
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
D D U D U
Request Content EE3004 FM EPB CTPV Response Content EE3004 rc Reference Hash
Attribute h h PU PU Attribute h h h
Description Function Code Function Modifier = 00 RSA-encrypted password Block Calculate TPV Description Function Code Return Code Retuned hash data
This function extracts the (numeric or alpha-numeric) password from an RSA-encrypted password Block and calculates a Reference TPV for storage and subsequent use in password verification. Note: This function only supports PINs in standard ISO format 2.
SHP Toolkit MK2 int EFT_EE3004_OBM_SetPassword_RSAEncrypted_TPV( IN UCHAR FM, IN KEYSPEC *SK, IN EFTBUFFER *C, IN EFTBUFFER *P, IN EFTBUFFER *RN, IN UCHAR AlgorithmID, IN EFTBUFFER *DataA, IN EFTBUFFER *DataB, IN KEYSPEC *KTPV, OUT EFTBUFFER *ReferenceTPV);
SafeNet, Inc.
138
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
D D U D U
Request Content EE3005 FM EPB CTPV Reference TPV Response Content EE3005 rc
Attribute h h PU PU h Attribute h h
Description Function Code Function Modifier = 00 RSA-encrypted password Block Calculate TPV Transformed Password Value. Description Function Code Return Code
This function extracts the (numeric or alpha-numeric) password from an RSA-encrypted password Block, and verifies the password by using the extracted password to calculate a transaction TPV and comparing the result with the Reference TPV. Note: This function only supports PINs in standard ISO format 2.
SHP Toolkit MK2 int EFT_EE3005_OBM_VerifyPassword_RSAEncrypted_TPV( IN UCHAR FM, IN KEYSPEC *SK, IN EFTBUFFER *C, IN EFTBUFFER *P, IN EFTBUFFER *RN, IN UCHAR AlgorithmID, IN EFTBUFFER *DataA, IN EFTBUFFER *DataB, IN KEYSPEC *KTPV, IN EFTBUFFER *ReferenceTPV);
SafeNet, Inc.
139
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
D D U D U
Request Content EE3006 FM EPB CTPV 1 Reference TPV 1 CTPV 2 Response Content EE3006 rc Reference TPV 2
Attribute h h PU PU h PU Attribute h h h
Description Function Code Function Modifier = 00 RSA-encrypted password Block Calculate TPV Transformed Password Value Calculate TPV Description Function Code Return Code Transformed Password Value.
This function extracts the old password and new password from an RSA-encrypted password Block, verifies the old password and calculates a TPV for the new password. Note: This function only supports PINs in standard ISO format 2. SHP Toolkit MK2 int EFT_EE3006_OBM_ChangePassword_RSAEncrypted_TPV( IN UCHAR FM, IN KEYSPEC *SK, IN EFTBUFFER *C, IN EFTBUFFER *P, IN EFTBUFFER *RN, IN UCHAR AlgorithmID1, IN EFTBUFFER *DataA1, IN EFTBUFFER *DataB1, IN KEYSPEC *KTPV1, IN EFTBUFFER *ReferenceTPV1, IN UCHAR AlgorithmID2, IN EFTBUFFER *DataA2, IN EFTBUFFER *DataB2, IN KEYSPEC *KTPV2, OUT EFTBUFFER *ReferenceTPV2);
SafeNet, Inc.
140
OBM PrintPassword
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
D D U D U
Length 3 1 1
Attribute h h h
Password Length
CTPV
1
Struct
h
CTPV Processing Unit h h h h
1 = Alpha-numeric (upper & lower case alpha) 2 = Upper case alpha and numeric 3 = Lower case alpha and numeric In range 04 16.
Calculate TPV
1 1 1 Var
Repeat count for the following data sets. This set of fields specifies data to be printed at a given line and column. The set of fields is optional and may be repeated multiple times, as specified by the Data sets field, causing 0, 1 or more data fields to be printed.
Length 3 1 Var
Attribute h h h
This function generates a random (numeric or alpha-numeric) password, prints the password along with specified data on an attached serial printer, and returns a reference TPV for storage and subsequent verification of the password. The function is normally disabled, and is controlled by the associated set of console operations. Note: Before using this function print parameters and a print control string must be entered via the SafeNet HSM console. If print parameters or a print control string have not been entered a PIN mailing not enabled error (error code 02) will be returned to the host. For further information see the PIN Mailer section in the Mark II Console User Guide.
SHP Toolkit MK2 int EFT_EE3008_OBM_PrintPassword( IN UCHAR *ESMID, IN UCHAR FM, IN UCHAR PasswordType, IN UCHAR PasswordLength,
SafeNet, Inc.
141
Chapter 12 Online Banking Module Functions UCHAR EFTBUFFER EFTBUFFER KEYSPEC UCHAR UCHAR UCHAR EFTBUFFER UCHAR UCHAR EFTBUFFER UCHAR UCHAR EFTBUFFER UCHAR UCHAR EFTBUFFER UCHAR UCHAR EFTBUFFER UCHAR UCHAR EFTBUFFER UCHAR UCHAR EFTBUFFER UCHAR UCHAR EFTBUFFER UCHAR UCHAR EFTBUFFER UCHAR UCHAR EFTBUFFER EFTBUFFER AlgorithmID, *DataA, *DataB, *KTPV, DataSets, *LineNo1, *ColumnNo1, *Data1, *LineNo2, *ColumnNo2, *Data2, *LineNo3, *ColumnNo3, *Data3, *LineNo4, *ColumnNo4, *Data4, *LineNo5, *ColumnNo5, *Data5, *LineNo6, *ColumnNo6, *Data6, *LineNo7, *ColumnNo7, *Data7, *LineNo8, *ColumnNo8, *Data8, *LineNo9, *ColumnNo9, *Data9, *LineNo10, *ColumnNo10, *Data10, *ReferenceTPV);
IN IN IN IN IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN OUT
SafeNet, Inc.
142
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
D D U D U
Request Content EE3009 FM PVK-Spec Validation Data Offset Password Length CTPV Response Content EE3009 rc Reference TPV
Description Function Code Function Modifier = 00 Key specifier for PVK and Decimalization Table. (Format 0 3, 11, 12, 13, 14 ) Data (usually the PAN) used to derive the password. PIN offset data Number of digits in the password Calculate TPV Description Function Code Return Code Transformed Password Value.
This function calculates the reference password from the keys and data of the 3624 Offset method, then calculates a Reference TPV for storage and subsequent use in password verification.
SHP Toolkit MK2 int EFT_EE3009_OBM_MigratePIN_OffsetToTPV( IN UCHAR FM, IN KEYSPEC *PVK, IN UCHAR ValidationData[8], IN UCHAR Offset[6], IN UCHAR PINLength, IN UCHAR AlgorithmID, IN EFTBUFFER *DataA, IN EFTBUFFER *DataB, IN KEYSPEC *KTPV, OUT EFTBUFFER *ReferenceTPV);
SafeNet, Inc.
143
OBM GetPrintToken
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
D D U D U
Length 3 1 Length 3 1 8
Attribute h h Attribute h h h
Description Function Code Function Modifier = 00 Description Function Code Return Code Generated Print Token to be used for Print Verification
This function generates 8 bytes of random data, also known as a Print Token and 1) 2) stores the Print Token in Secure Memory, overwriting any prior Print Tokens returns the 8 byte Print Token in the clear to the host
SHP Toolkit MK2 int EFT_EE3016_OBM_GetPrintToken( IN UCHAR *ESMID, IN UCHAR FM, OUT UCHAR PrintToken[8]);
SafeNet, Inc.
144
OBM GenerateRandomPIN
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
D D U D U
Length 3 1 1
Attribute h h h
Description Function Code Function Modifier = 00 0 = Numeric 1 = Alpha-numeric (upper & lower case alpha) 2 = Upper case Alpha and numeric 3 = Lower case Alpha and numeric In range 04 - 16 Calculate TPV
1 Struct
8 Var Length 3 1
Var Var
Print Token of the Remote PHW which will be printing out this generated PIN Key Specifier for PPK (Formats: 0 - 3) Description Function Code Return Code
Encrypted OBM Print PIN Block Transformed PIN Value
This function generates a random (numeric or alpha-numeric) PIN and returns: 1) a reference TPV for storage and subsequent verification of the PIN 2) an encrypted OBM Print PIN Block (PIN Block = Print Token + PIN Block) to be printed in a remote location The Random PIN Generation adheres to the password restrictions as described in the Online Banking Module Password Restrictions section at the beginning of this chapter. SHP Toolkit MK2 int EFT_EE3017_OBM_GenerateRandomPIN( IN UCHAR FM, IN UCHAR PINType, IN UCHAR PINLength, IN UCHAR AlgorithmID, IN EFTBUFFER *DataA, IN EFTBUFFER *DataB, IN KEYSPEC *KTPV, IN UCHAR PrintToken[8], IN KEYSPEC *PPK, OUT OUT EFTBUFFER EFTBUFFER *ePPK_PIN, *ReferenceTPV);
SafeNet, Inc.
145
OBM PrintEncryptedPIN
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
D D U D U
Request Content EE3018 FM PIN Length PPK-Spec ePPK(OBM Print PIN Block) Data Sets
Attribute h h h K-Spec h h
Description Function Code Function Modifier = 00 In range 04 16 Key Specifier for PPK (Formats: 0 - 3) Encrypted OBM Print PIN Block A data set contains a Line No field, Column No field and Data field. The data sets field specifies the number of data sets that follow. The line number for the data to be printed at. The column number for the data to be printed at. The data to be printed. Description Function Code Return Code
Line No
1 1 Var Length 3 1
h h h Attribute h h
Column No
This set of fields repeats 0 or more times as specified by the Data Sets field.
This function decrypts an encrypted OBM Print PIN Block, verifies the Print Token and prints the PIN along with the specified data on an attached serial printer. The function is normally disabled, and is controlled by the associated set of console operations. Enabling PIN Printing enables this function. Before using this function print parameters and a print control string must be entered from the main PIN mailer menu. If print parameters or a print control string have not been entered a PIN mailing not enabled error (error code 02) will be returned to the host. Processing steps 1. Check that the Print Token in Secure Memory is valid (i.e. not equal to 0x0000000000000000), otherwise return error code Invalid Print Token (0x7F). 2. Decrypt the Encrypted OBM Print PIN block with the PPK specified. 3. Extract the Print Token (1st 8 bytes) from the OBM Print PIN Block. 4. Verify the extracted Print Token with the Print Token stored in Secured Memory. If both Print Tokens are not the same, return error code Invalid Print Token (0x7F). 5. Set the Print Token in Secure Memory to 0x0000000000000000. 6. Extract the PIN from the PIN block as specified by the PIN Length. 7. Print the PIN and supplied data on the attached serial printer.
SafeNet, Inc.
146
SHP Toolkit MK2 int EFT_EE3018_OBM_PrintEncryptedPIN( IN UCHAR *ESMID, IN UCHAR FM, IN UCHAR PINLength, IN KEYSPEC *PPK, IN EFTBUFFER *ePPK_PIN, IN UCHAR DataSets, _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN UCHAR UCHAR EFTBUFFER UCHAR UCHAR EFTBUFFER UCHAR UCHAR EFTBUFFER UCHAR UCHAR EFTBUFFER UCHAR UCHAR EFTBUFFER UCHAR UCHAR EFTBUFFER UCHAR UCHAR EFTBUFFER UCHAR UCHAR EFTBUFFER UCHAR UCHAR EFTBUFFER UCHAR UCHAR EFTBUFFER *LineNo1, *ColumnNo1, *Data1, *LineNo2, *ColumnNo2, *Data2, *LineNo3, *ColumnNo3, *Data3, *LineNo4, *ColumnNo4, *Data4, *LineNo5, *ColumnNo5, *Data5, *LineNo6, *ColumnNo6, *Data6, *LineNo7, *ColumnNo7, *Data7, *LineNo8, *ColumnNo8, *Data8, *LineNo9, *ColumnNo9, *Data9, *LineNo10, *ColumnNo10, *Data10);
SafeNet, Inc.
147
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
D D U D U
Request Content EE3019 FM EPB PPK-Spec PFo ANB Response Content EE3019 rc ePPKo
Description Function Code Function Modifier = 00 Decrypt and decode RSA-encrypted PIN Block Key Specifier for PPK (Formats: 0 - 3, 10, 11, 13, 90). PIN Block format (Formats: 01, 10, 11, 12, 13) Account Number Block Description Function Code Return Code Encrypted PIN Block
This function decrypts an OBM RSA-encrypted, format 12 PIN Block, changes the PIN Block format to that specified by the output PIN Block format and returns it encrypted by the specified PPK. Notes: This function only works for numeric PINs which are of length 04 to 12. This function has a potential to export a user PIN, so it has to be configurable at the HSM console's function control menu whether this function is enabled or disabled. The function will fail with Error Code 78 if PFo indicates a PIN block format that is disabled or conflicts with the reformatting restrictions. SHP Toolkit MK2 EXPORT int EFT_EE3019_OBM_TranslatePIN_RSAencrypted_PPK( IN UCHAR *ESMID, IN UCHAR FM, IN KEYSPEC *SK, IN EFTBUFFER *C, IN EFTBUFFER *P, IN EFTBUFFER *RN, IN KEYSPEC *PPKo, IN UCHAR PFo, IN UCHAR ANB[6], OUT EFTBUFFER *ePPKo_PIN);
SafeNet, Inc.
148
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
D D U D U
Request Content EE3020 FM ePPK(PIN) PPKi-Spec PFi ANB CTPV Response Content EE3020 rc Reference TPV
Description Function Code Function Modifier = 00 PIN Block encrypted by PPK Input PIN Protect Key Specifier (Formats: 0 - 3, 10, 11, 13, 90) Input PIN Block Format (Formats: 01, 03, 08, 09, 10, 11, 12, 13) Account Number Block Calculate TPV Description Function Code Return Code Transformed PIN Value
This function extracts the numeric PIN from a PPK-encrypted PIN Block and calculates a reference TPV for storage and subsequent use in PIN verification.
Notes: This function only works for numeric PINs which are of length 04 to 12. This function has a potential for a brute force attack on a known reference TPV, so it has to be configurable at the HSM console's function control menu whether this function is enabled or disabled.
SHP Toolkit MK2 EXPORT int EFT_EE3020_OBM_SetPIN_PPKencrypted_TPV( IN UCHAR *ESMID, IN UCHAR FM, IN EFTBUFFER *ePPKi_PIN, IN KEYSPEC *PPKi, IN UCHAR PFi, IN UCHAR ANB[6], IN UCHAR AlgorithmID, IN EFTBUFFER *DataA, IN EFTBUFFER *DataB, IN KEYSPEC *KTPV, OUT EFTBUFFER *ReferenceTPV);
SafeNet, Inc.
149
SafeNet, Inc.
150
Visa Overview
Visa provides a world-wide network which allows the cards of a participating member institution to be used in the EFT terminals of other participating members. In such a transaction, Visa refers to the institution which owns the EFT terminal as the Acquirer. The network performs the necessary switching between Acquirer and Issuer. Additionally, Visa provides an optional PIN Verification Service (PVS) which obviates the requirement to switch the transaction through to the Issuer. The PVS is performed at the Visa Network Central host. This service involves the PVV method of PIN Verification. The method may also be used by the Issuer for verification of the PIN in an 'on-us' transaction. Members of Visa International must comply with Visa's requirements for Card Verification Values (CVV).
Network Requirements
The routing of a transaction from Acquirer to Issuer involves two encryption zones: The Acquirer zone extends between the Acquirer host and a Network Central host. In this zone the PIN is encrypted by an Acquirer Working Key (AWK).
SafeNet, Inc.
151
The Issuer zone extends between the Network Central host and the Issuer host. In this zone the PIN is encrypted by an Issuer Working Key (IWK).
The translation of the PIN encryption key (and of the PIN Block format, if necessary) occurs in a HSM at the Network Central host. A more detailed description of these points follows.
Key Management
Although Visa specifies no standards for secure key management by an Issuer, it recommends that an Issuer adhere to the same standards required of an Acquirer. Therefore, the summary here applies the standards to both Issuer and Acquirer keys. The working keys, which may require management by a participating member, are: - Issuer Working Key (IWK) Support of two such keys is suggested, to provide an orderly change and fall-back protection. Acquirer Working Key (AWK) Support of two such keys is suggested, to provide an orderly change and fall-back protection. PIN Verification Keys (PVK-A, PVK-B) No more than two pairs should be used concurrently for each card base. However, other pairs may be held in reserve for each card base. Card Verification Keys (CVK-A, CVK-B)
For conveyance to Visa, the working keys are encrypted under a master key called the Zone Control Master Key (ZCMK). For in-house storage, the working keys should be encrypted under a 'member master key' (VMMK). The ZCMK (and/or its components) need only be similarly encrypted while stored outside of a physically-secure machine. The member master key is known only to the member, and Visa specify no standards for its management.
Key Generation
SafeNet, Inc.
152
Each Working Key used must be randomly generated by the member either by using a manual or automated procedure. [Visa provides a suggested procedure for both.] The ZCMK is formed by XORing three 'ZCMK components'. Each component is randomly generated (either manually or automatically) and is subject to the restriction that a pair of hexadecimal digits should not appear more than three times in the component. Each of the Working Keys and the ZCMK requires an associated non-secret Key Check Value (KCV), which consists of the most significant six hexadecimal digits of the result of encrypting a Block of zeros by the key.
Key Distribution
Each ZCMK component, along with the KCV of the resultant ZCMK, is mailed separately to Visa. Subsequently, each Working Key encrypted by ZCMK, along with the KCV of the Working Key, may be mailed to Visa. If any other distribution of a Working Key is required (for example, installation of AWK in a terminal), that key should be encrypted under a VMMK.
Issuer/Acquirer Assumptions
It is assumed that the definitions of Issuer and Acquirer are in relation to VisaNet only, and that the following situations exist: A VisaNet Acquirer may have received the transaction from the true Acquirer via some domestic network, and so is acting as a Gateway into VisaNet on behalf of other member institutions. A VisaNet Issuer may be acting as a Gateway from VisaNet on behalf of other member institutions, and so needs to route VisaNet transactions to the true Issuer via some domestic network.
The facilities provided in the SafeNet HSM cater for both these situations.
SafeNet, Inc.
153
Usage of this operation is optional. The user may elect to generate the ZCMK component using a manual process.
2. 3.
The above procedure allows the calculation of the ZCMK KCV for forwarding to Visa with each of the ZCMK components. On Visa's confirmation of receipt of the three components, they may be reentered and the ZCMK stored in the HSM for subsequent usage with Working Key generation.
IWK Storage
The HSM provides storage for two IWKs, though only one may be selected for access (by the PIN Management Functions) at any point in time. The operation of IWK storage requires the input of the IWK index (1 or 2) and of the IWK encrypted by the stored ZCMK. The KCV of the IWK is displayed.
AWK Storage
The HSM provides storage for two AWKs, though only one may be selected for access (by the PIN Management Functions) at any point in time. The operation of AWK storage requires the input of the AWK index (1 or 2) and of the AWK encrypted by the stored ZCMK. The KCV of the AWK is displayed.
IWK/AWK Selection
The HSM provides storage for two of each of IWK and AWK, but only one of each may be selected for access (by the PIN Management Functions) at any point in time. Additionally, a facility is
SafeNet, Inc.
154
provided to have neither version of the IWK/AWK selected, effectively disabling the associated PIN Management functions. The operation of IWK/AWK selection involves the display of the index (1 or 2) of the currently selected IWK or AWK, or of the letter X indicating that no key is selected. The user may choose a new value (1, 2 or X) and elect to store the updated value which will become effective immediately.
KCV Display
In addition to displaying the KCV whenever a key is entered, screens are provided which display the KCV of all the currently stored Visa keys. Any key which has not been stored is indicated by the display of a KCV of '------'.
SafeNet, Inc.
155
PPK --> AWK IWK --> PPK Translation from AWK to IWK is not supported as this is only performed at the Network Central Security Module. The remainder of this section describes each of the functions provided.
NOTE
A Return Code of 0A (meaning, uninitialized key accessed), will be returned whenever an attempt is made to access an AWK or IWK which has been stored in the HSM but is not currently selected.
Equivalent keys
Key Type Key encrypting key PIN encrypting key PIN verification key (PVV method) Card validation key (CVV method) Visa key ZCMK AWK / IWK PVK-A / PVK-B CVK-A / CVK-B HSM key KIS / KIR PPK
Console operations
Original operations (single-keys only) Generate and display random component parity adjusted limited repeated digit pairs. Enter and store ZCMK 3 components limited repeated digit pairs Generate WK, display ZCMK-encrypted + KCV Enter WK, display ZCMK-encrypted + KCV 2 components Replacement operations (single- and double-length keys) Display random components (single / double) parity adjusted no check of repeated digit pairs. Enter and store KIS / KIR 2 9 components, select 3. digits not checked. No equivalent No equivalent
SafeNet, Inc.
156
Chapter 13 Visa Functions Enter PPK clear components (or encrypted component) 99 HSM-stored, also host-stored No longer applicable Will change to standard key entry method Update to support export by KIS.
Enter and store IWK / AWK entered encrypted by stored ZCMK two of each supported IWK / AWK selection Enter and store PVK-A, PVK-B entered encrypted by stored ZCMK 99 supported
SafeNet, Inc.
157
PVV-VER
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
D D D D D
Request Content EE0605 FM ePPK(PIN) PPK-Spec PF ANB PVVK-Spec TSP12 PVV Response Content EE0605 rc
Description Function Code Function Modifier = 00 Encrypted PIN Block Key specifier for PPK (Formats: 0 - 3, 10, 11, 13, 20, 90) PIN Block Format Account Number Block Key specifier for PVVK (Formats: 0 - 3, 11, 13) Transformed Security Parameter PIN Validation Value Description Function Code Return Code
This function performs the verification of a PIN using the Visa PVV method. The PIN is supplied in encrypted form, using any of the PIN Block format specified in Chapter 2 Function Construction. PPK-Spec May be any valid key specifier for a PPK. Consequently, the function supports an encrypted PIN Block encrypted using a single-length or doublelength HSM-stored or host-stored key. specifies the format of the input PIN Block format. Account Number Block, which are the 12 right most digits of the Primary Account Number (PAN), excluding the check digit. A specifier to a HSM-stored or host-stored PVVK (PVK-A and PVK-B) The left most 12 digits of the Transformed Security Parameter.
The function will fail with Error Code 78 if PF indicates a PIN block format that is disabled.
NOTE
This function includes all the capabilities of the following existing functions and hence supercedes the following: PVV-VER-1 (91), PVV-VER-2 (92), PVV-VER-3 (93), PVV-VER-4 (97), PVV-VER-5 (98), PVV-VER-6 (99)
SafeNet, Inc.
158
SHP Toolkit MK2 int EFT_EE0605_PINVerify_VISA ( IN UCHAR FM, IN UCHAR ePPKi_PIN[8], IN KEYSPEC *PPKi, IN UCHAR PFi, IN UCHAR ANB[6], IN KEYSPEC *PVVK, IN UCHAR TSP12[6], IN UCHAR PVV[2]);
SafeNet, Inc.
159
PVV- CALC-3624
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
D D D D D
Request Content EE0606 FM PVK-Spec Validation Data Offset4 PVVK-Spec TSP12 Response Content EE0606 rc PVV
Description Function Code Function Modifier = 00 Key specifier for PVK (Formats: 0 - 3) Validation Data PIN offset data Key specifier for PVVK (Formats: 0 - 3, 11, 13) Transformed Security Parameter Description Function Code Return Code PIN Validation Value
This function calculates a Visa PVV from a PINs IBM Offset data. The four leftmost digits of the derived or random PIN are appended to the TSP12 to form the TSP. PVK-Spec Validation Data Offset4 PVVK-Spec TSP12 A specifier to the HSM stored PVK Data which is usually part of the PAN and used in the calculation of the reference PIN. Leftmost 4 digits of the PIN offset. If an offset is not used, the digits must contain zeros. A specifier to a HSM-stored or host-stored PVVK (PVK-A and PVK-B) The leftmost 12 digits of the Transformed Security Parameter.
NOTE
This function includes all the capabilities of the following existing functions, and thereby supercedes the following: PVV-GEN-1 (90), PIN-GEN-2 (96). SHP Toolkit MK2 int EFT_EE0606_CalculatePVV_IBM( IN UCHAR FM, IN KEYSPEC *PVK, IN UCHAR PAN[8], IN UCHAR offset[2], IN KEYSPEC *PVVK, IN UCHAR TSP12[6], OUT UCHAR PVV[2]);
SafeNet, Inc.
160
PVV-CALC
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
D D D D D
Request Content EE0607 FM ePPK(PIN) PPK-Spec PF ANB PVVK-Spec TSP12 Response Content EE0607 rc PVV
Description Function Code Function Modifier = 00 Encrypted PIN Block PIN Protection Key specifier (Formats: 0 - 3, 10, 11, 13, 20, 90) PIN Block Format (Formats: 01, 03, 08, 09, 10, 11. 13) Account Number Block Visa PIN Verification Key specifier (Formats: 0 - 3, 11, 13) Transformed Security Parameter Description Function Code Return Code PIN Validation Value
This function calculates a Visa PVV for a PIN and also provides the length of the PIN. The PIN is supplied in encrypted form, using any of the PIN Block formats specified in Chapter 2 Function Construction. PPK-Spec This may be any valid key specifier for a PPK. Consequently, the function supports an encrypted PIN Block encrypted using a single-length or doublelength HSM-stored or host-stored key. Account Number Block, which are the 12 right most digits of the Primary Account Number (PAN), excluding the check digit. A specifier to a HSM-stored or host-stored PVVK (PVK-A and PVK-B). The left most 12 digits of the Transformed Security Parameter.
The function will fail with Error Code 78 if PF indicates a PIN block format that is disabled. The function performs a check that the ANB field and the TSP12 field contain a number of consecutive digits in common. The number of digits to check is in the range 0 to 12, as may be specified using a console operation, and defaults to 8. If the number of digits to check has been set to 0 the check is disabled, and in this case the function will accept any supported PIN block format that is enabled. If the number of digits to check is greater than 0, then only ISO-0 and ISO-3 PIN blocks are allowed, if enabled. If the check fails, the function will fail with Return Code 79.
NOTE
This function includes all the capabilities of the following existing functions, and thereby supercedes the following: PVV-CHANGE (9A)
SafeNet, Inc.
161
SHP Toolkit MK2 int EFT_EE0607_CalculatePVV_EncPIN( IN UCHAR FM, IN UCHAR ePPKi_PIN[8], IN KEYSPEC *PPKi, IN UCHAR PFi, IN UCHAR ANB[6], IN KEYSPEC *PVVK, IN UCHAR TSP12[6], OUT UCHAR PVV[2]);
SafeNet, Inc.
162
U U D D U
Request Content EE0614 FM PF ePPK(PIN) PPK-Spec ANB ValidationData Offset AlgID PVK-Spec Response Content EE0614 rc
Description Function Code Function Modifier = 00 PIN Format (Formats: 01, 03, 08, 10, 11. 13) Encrypted PIN Block Key specifier for PPK (Formats: 0 - 3, 10, 11, 13) Account Number Block per AS2805.3 Validation data for pin verify operation PIN Offset Table Algorithm Number Diebold Table Specifier (Formats: 0 - 3) Description Function Code Return Code
This function generates an Offset for a PIN/PAD formatted PIN. The PIN Block must be supplied encrypted under a PIN Protect Key (PPK). PF Pin Format, which may take one of the following values: PIN-TRANS format 01 01h1 ISO 9564-1 format 0 AS2805 Part 3 format 0 03h PIN-TRANS format 3 08h Docutel 5100 format 10h same as 01 above ISO 9564-1 format 0 11h1 ISO 9564-1 format 3 13h1 Note 1 these formats require a valid ANB to be supplied. The formatted PIN Block encrypted under the PPK. Pin must have length 4. Key specifier for the PPK Account Number Block, usually the right most 12 digits of the Personal Account Number after the checksum is removed. Valid data is only required if the PIN Block requires it.
SafeNet, Inc.
163
Chapter 13 Visa Functions Data used in the PIN validation algorithm. Length should be 4<=N<=19 where N is the number of BCD digits (i.e. twice the length in bytes). If the length is odd then pad the right most nibble with 0xf Example. Account = 0123 data = 0123h Example. Account = 01234 data = 01234fh Four BCD digits that are modulo 10 added to the derived pin to create the actual pin. A number from 0 to 255 that is an input into the pin verification algorithm. A Var field that specifies the index of the Diebold Table to use in the verification. A number from 1 to 5 may be used.
ValidationData
SHP Toolkit MK2 int EFT_EE0614_Diebold_PIN_Ver( IN UCHAR FM, IN UCHAR PF, IN UCHAR ePPK_PIN[8], IN KEYSPEC *PPK, IN UCHAR ANB[6], IN EFTBUFFER *Validation_Data, IN UCHAR PINOffsetTable[2], IN UCHAR AlgID, IN KEYSPEC *PVK);
SafeNet, Inc.
164
DIEBOLD_PIN_OFF
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
U U D D U
Request Content EE0616 FM PF ePPK(PIN) PPK-Spec ANB ValidationData AlgID PVK-Spec Response Content EE0616 Rc Offset
Description Function Code Function Modifier = 00 PIN Format (Formats: 01, 03, 08, 10, 11. 13) Encrypted PIN Block Key specifier for PPK (Formats: 0 - 3, 10, 11, 13) Account Number Block per AS2805.3 Validation data for pin verify operation Algorithm Number Diebold Table Specifier (Formats: 0 - 3) Description Function Code Return Code PIN Offset Table
This function generates an Offset for a specified PIN using the Diebold Table method. The PIN Block must be supplied encrypted under a PIN Protect Key (PPK). PF Pin Format, which may take one of the following values: PIN-TRANS format 01 01h1 ISO 9564-1 format 0 AS2805 Part 3 format 0 03h PIN-TRANS format 3 08h Docutel 5100 format 10h same as 01 above ISO 9564-1 format 0 11h1 ISO 9564-1 format 3 13h1 Note 1 these formats require a valid ANB to be supplied. The formatted PIN Block encrypted under the PPK. Pin must have length 4. Key specifier for the PPK Account Number Block, usually the right most 12 digits of the Personal Account Number after the checksum is removed. Valid data is only required if the PIN Block requires it. Data used in the PIN validation algorithm. Length should be 4<=N<=19 where N is the number of BCD digits (i.e. twice the length in bytes). If the length is odd then pad the right most nibble with 0xf Example. Account = 0123 data = 0123h Example. Account = 01234 data = 01234fh
ValidationData
SafeNet, Inc.
165
Chapter 13 Visa Functions A number from 0 to 255 that is an input into the pin verification algorithm. A Var field that specifies the index of the Diebold Table to use in the verification. A number from 1 to 5 may be used. Four BCD digits that are modulo 10 added to the derived pin to create the actual pin.
NOTE
This function applies to PSO Firmware version 2.03.00 or above.
SHP Toolkit MK2 int EFT_EE0616_Diebold_PIN_Off( IN UCHAR FM, IN UCHAR PF, IN UCHAR ePPK_PIN[8], IN KEYSPEC *PPK, IN UCHAR ANB[6], IN EFTBUFFER *Validation_Data, IN UCHAR AlgID, IN KEYSPEC *PVK, OUT UCHAR PINOffsetTable[2]);
SafeNet, Inc.
166
SEED Translation
PIN-TRANS-SEED-DES
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
D D U D D
Request Content EE0615 FM ePPKi(PIN) PPKi-Spec PFi ANB PFo PPKo-Spec Response Content EE0615 rc ePPKo(PIN)
Description Function Code Function Modifier = 00 Encrypted PIN Block. PIN Protection Key specifier (Formats: 0 - 3, 16) Input PIN Block Format (Formats: 01, 03, 08, 10, 11, 13) Account Number Block Output PIN Block Format (Formats: 01, 03, 08, 10, 11, 13) Key specifier for PPK (Formats: 0 - 3, 10, 11, 13) Description Function Code Return Code Encrypted PIN Block
This function performs a translation from SEED to DES of the PIN Block format. The incoming PIN Block format is verified. Please note that only the first 8 bytes of the PIN Block are verified. For example, if the PFi field indicates an ANSI PIN Block the first 8 bytes of the PIN Block are verified according to the ANSI format while the last 8 bytes are ignored. The function will fail with Error Code 78 if PFi or PFo indicates a PIN block format that is disabled or conflicts with the reformatting restrictions. FM PFi and PFo = 00. Must be set to zero. Specify the format of the supplied PIN Block and of the required PIN Block. If PIN format translation is not required, PFo must be set to the same value as PFi. Supports PIN formats 01, 03, 08, 10, 11 and 13. Account Number Block The key specifier PPKi-Spec. Format 00 03 and 16 accepted. Where a HSM stored PPK is indicated (formats 00 03) the key must have been stored as a SEED key. The key specifier PPKo-Spec. Formats 00 03, 10, 11 and 13 accepted. PIN Block encrypted using the SEED algorithm by PPKi. This Var field must be 16 bytes in length.
ANB PPKi
PPKo ePPKi(PIN)
SafeNet, Inc.
167
NOTES
For key specifier formats, refer to Chapter 2 Function Construction. For information on the SEED algorithm see the Glossary.
SHP Toolkit MK2 int EFT_EE0615_SEEDTranslation( IN UCHAR FM, IN EFTBUFFER *ePPK_PIN, IN KEYSPEC *PPKi, IN UCHAR PFi, IN EFTBUFFER *ANB, IN UCHAR PFo, IN KEYSPEC *PPKo, OUT EFTBUFFER *ePPKo_PIN);
SafeNet, Inc.
168
CVV- GENERATE
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
D D D D D
Description Function Code Function Modifier = 00 Card Verification Key specification (Formats: 0 - 3, 11, 13) Card Verification Value Data Description Function Code Return Code Card Verification Value
This function generates a Card Verification Value (CVV) by the Visa method for card data (CVVdata). FM CVK-Spec = 00. Must be set to zero. A key specifier which incorporates an index to a HSM-stored double length or key pair CVV or a host-stored double-length CVV. The data from which the CVV is generated. It is up to the host to format the field correctly and to do any required range checking on the data. This field is normally populated in packed BCD format. CVV The three digit Card Verification Value. The three digits are left aligned and right padded with the hexadecimal digit "F".
CVV-Data
NOTE
This function is equivalent to function CVV-GEN (9B) but incorporates a key specifier to access the CVK.
SHP Toolkit MK2 int EFT_EE0802_CVVGenerate ( IN UCHAR FM, IN KEYSPEC *CVK_Spec, IN UCHAR CVV_Data[16], OUT UCHAR CVV[2] );
SafeNet, Inc.
169
CVV- VERIFY
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
D D D D D
Description Function Code Function Modifier = 00 Card Verification Key Index (Formats: 0 - 3, 11, 13) Card Verification Value Data Card Verification Value Description Function Code Return Code
This function verifies card data (CVV-data) deriving a CVV for that data and validating it against the CVV in the request. FM CVK-Spec = 00. Must be set to zero. A key specifier which incorporates an index to a HSM-stored double length or key pair CVV or a host-stored double-length CVV. The data from which the CVV is generated. It is up to the host to format the field correctly and to do any required range checking on the data. This field is normally populated in packed BCD format. CVV The digit byte Card Verification Value. The three digits are left aligned and right padded with the hexadecimal digit "F".
CVV-Data
A Return Code of 00 indicates CVV verification, and a Return Code of 08 indicates verification failure.
NOTE
This function is equivalent to function CVV-VER (9C) but incorporates a key specifier to access the CVK. SHP Toolkit MK2 int EFT_EE0803_CVVVerify( IN UCHAR FM, IN KEYSPEC *CVK_Spec, IN UCHAR CVV_Data[16], IN UCHAR CVV[2]);
SafeNet, Inc.
170
SafeNet, Inc.
171
MAC Generation
MAC_GEN_UPDATE
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
D D D D D
Length 3 1 1
Attribute h h h
Description Function Code Function Modifier = 00 Algorithm Qualifier Specifies details of the MACing algorithm. The left nibble specifies the padding and the right nibble specifies the algorithm: Left nibble: = 0: pad with zeroes. = 1: pad with a single one bit and subsequent zeroes Right nibble: For single length MPK this nibble must be zero For double length MPK: =0 ISO 9807 method =1 triple-DES CBC method Input Chaining Data Key Specifier for MPK (Formats: 0 - 3, 10, 11, 13, 20, 50, 51, 90) Data to be MACed Description Function Code Return Code Output Chaining Data
ICD MPK-Spec
8 Var
h K-Spec
Var Length 3 1 8
h Attribute h h h
This function is provided for long message MAC generation and verification, whereby a message authentication Block (OCD) is generated for the supplied DATA, using the supplied MAC Protect Key (MPK), in accordance with AS2805.4 1985. The long message support is integrated whereby the OCD is passed back to the function as the ICD after each cycle that the function performs. On the final Block of data the function MAC-GEN-FINAL (EE0701) should be called. This function is also used during long message MAC verification, whereby the OCD is passed back as the ICD until the last data Block. To finalize the MAC verification, the function MAC-VERFINAL (EE0702) should be called. FM Alg = 00. Must be set to zero. Specifies the MACing algorithm to use.
SafeNet, Inc.
172
Left nibble: = 0: pad with zeroes. = 1: pad with a single one bit and subsequent zeroes Right nibble: For single length MPK this nibble must be zero For double length MPK: = 0: ISO 9807 method
= 1: triple-DES CBC method e.g. Pad with zeroes and double-length MPK using triple-DES CBC method 0x01 ICD MPK-Spec OCD Input Chaining Data, used for long message feedback. A key specifier incorporating an encrypted MAC Protect Key. Output Chaining Data, used for long message feedback.
SHP Toolkit MK2 int EFT_EE0700_MACGenerate_Update( IN UCHAR FM, IN UCHAR algorithm, IN UCHAR icd[8], IN KEYSPEC *MPK, IN EFTBUFFER *data, OUT UCHAR ocd[8]);
SafeNet, Inc.
173
MAC_GEN_FINAL
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
D D D D D
Length 3 1 1
Attribute h h h
Description Function Code Function Modifier = 00 Algorithm Qualifier Specifies details of the MACing algorithm. The left nibble specifies the padding and the right nibble specifies the algorithm: Left nibble: = 0: pad with zeroes. = 1: pad with a single one bit and subsequent zeroes Right nibble: For single length MPK this nibble must be zero For double length MPK: =0 ISO 9807 method =1 triple-DES CBC method DES = 01 - 08 Bytes HMAC-SHA-1 = 04 - 20 bytes Input Chaining Data Key Specifier for MPK (Formats: 0 3,10,11,13,18,20,50,51,90) Data to be MACed Description Function Code Return Code Message Authentication Code
1 8 Var
h h K-Spec
h Attribute h h h
This function is provided for MAC generation, using the supplied MAC Protect Key (MPK), in accordance with AS2805.4 1985. The long message support is integrated whereby the OCD from MAC-UPDATE is passed as the ICD. When the MPK is a HSM stored HMAC-SHA-1 MPK, the HMAC-SHA-1 MAC algorithm will be used for message authentication. For HMAC-SHA-1 algorithm, valid range for requested MAC length is 4 to 20 bytes. A format 18 key specifier (embedded binary secure key Block) containing a host stored HMAC-SHA-1 MPK key may also be used for HMAC-SHA-1 message authentication. HMAC-SHA-1 MPK key length can be 128, 160 or 192 bits.
SafeNet, Inc.
174
Chapter 14 MAC Management Functions = 00. Must be set to zero. Specifies the MACing algorithm to use. Left nibble: = 0: = 1: pad with zeroes. pad with a single one bit and subsequent zeroes
FM Alg
Right nibble: For single length MPK this nibble must be zero For double length MPK: = 0: = 1: ISO 9807 method triple-DES CBC method
eg. Pad with zeroes and double-length MPK using triple-DES CBC method 0x01 MAClength ICD MPK-Spec Specifies the length of the output MAC Input Chaining Data, used for long message feedback. A key specifier incorporating an encrypted MAC Protect Key.
NOTES
This function supercedes functions 70, 71,72.
SHP Toolkit MK2 int EFT_EE0701_MACGenerate_Final( IN UCHAR FM, IN UCHAR algorithm, IN UCHAR MacLen, IN UCHAR icd[8], IN KEYSPEC *MPK, IN EFTBUFFER *data, OUT EFTBUFFER *mac);
SafeNet, Inc.
175
MAC_VER_FINAL
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
D D D D D
Length 3 1 1
Attribute h h h
Description Function Code Function Modifier = 00 Algorithm Qualifier. Specifies details of the MACing algorithm. Left nibble (Padding): = 0: pad with zeroes. = 1: pad with a single one bit and subsequent zeroes Right nibble (Algorithm): For single length MPK must be zero. For double length MPK: =0 ISO 9807 method =1 triple-DES CBC method Input Chaining Data Key Specifier for MPK (Formats: 0 3,10,11,13,18,20,50,51,90) Message Authentication Code Data to be MACed Description Function Code Return Code
ICD MPK-Spec
8 Var
h K-Spec
h h Attribute h h
This function verifies that the MAC is valid for the supplied DATA using the supplied MAC Protect Key (MPK), in accordance with AS2805.4 1985. When the MPK is a HSM stored HMAC-SHA-1 MPK, the HMAC-SHA-1 MAC algorithm will be used for message authentication. For HMAC-SHA-1 algorithm, valid length range for requested MAC verification is 4 to 20 bytes. A format 18 key specifier (embedded binary secure key Block) containing a host stored HMAC-SHA-1 MPK key may also be used for HMAC-SHA-1 message authentication. HMAC-SHA-1 MPK key length can be 128, 160 or 192 bits. The MAC-VER-FINAL function returns no response data. An Error Code of 00 indicates successful verification, while 08 indicates a verification failure.
SafeNet, Inc.
176
FM Alg
= 00. Must be set to zero. Specifies the MACing algorithm to use. Left nibble: = 0: pad with zeroes. = 1: pad with a single one bit and subsequent zeroes Right nibble: For single length MPK this nibble must be zero For double length MPK: = 0: ISO 9807 method =1: triple-DES CBC method Input Chaining Data, used for long message feedback. A key specifier incorporating an encrypted MAC Protect Key.
ICD MPK-Spec
SHP Toolkit MK2 int EFT_EE0702_MACVerify_Final( IN UCHAR FM, IN UCHAR algorithm, IN UCHAR icd[8], IN KEYSPEC *MPK, IN EFTBUFFER *mac, IN EFTBUFFER *data);
SafeNet, Inc.
177
D D U U U
Attribute h h d h Attribute h h h
Description Function Code No. of 8 byte Blocks KTM-Index Must be multiple of 8 bytes Description Function Code Return Code Message Authentication Code
This function generates a 32-bit Message Authentication Code (MAC) for the supplied DATA using the Terminal Master Key (KTMn) indicated by the supplied KTM-index, in accordance with AS2805.4 1985. Note that only the first 99 KTMs may be used with this function. The function may be used for both MAC generation and MAC verification.
SafeNet, Inc.
178
SafeNet, Inc.
179
ENCIPHER_2
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
D D D D D
Length 3 1 Var 1
Attribute h h K-Spec h
Description Function Code Function Modifier = 00 Key specifier for DPK (Formats: 0 - 3, 10, 11, 13, 20, 51) Cipher Mode 00 = ECB 01 = CBC Input Chaining Value Data to be enciphered Description Function Code Return Code Output Chaining Value Cipher text
h h Attribute h h h h
This function enciphers the supplied data using a host-stored session key (DPK) supplied within a key specifier. The function performs single-DES or triple-DES encipherment, as determined by the length of the supplied key, and supports both Electronic Code Book (ECB) and Cipher Block Chaining (CBC) modes of operation. The function supports encipherment of large messages (or data files) either by one call to the function or by multiple calls. For CBC encipherment using multiple calls, chaining values must be maintained between calls. DPK-Spec CM Key specifier incorporating a single or double length host-stored or HSM-stored DPK. Specifies the mode of operation for the encipherment: 0 Electronic Code Book (ECB) 1 Cipher Block Chaining (CBC) Chaining value for CBC encipherment. For encipherment of a message or file using one call, or on the first call of a multi-call encipherment, this field should be set to the required value of the Initialization Vector (IV). On subsequent calls of a multi-call encipherment, the field should be set to the value of the OCB provided by the previous call. For ECB encipherment, this field will be ignored. Chaining value for CBC encipherment. For encipherment of a message or file using a multi-call encipherment, the value in this field should be used as the ICV in the next call. For ECB encipherment, this field will be set to zero. Plaintext data to be enciphered. Must be a multiple of 8 bytes long.
ICV
OCV
Data
SafeNet, Inc.
180
NOTES
This function supercedes functions 80, 82. When the function modifier is missing, the function returns error code 24, missing function code.
SHP Toolkit MK2 int EFT_EE0800_Encipher IN UCHAR IN KEYSPEC IN UCHAR IN UCHAR IN EFTBUFFER OUT OUT UCHAR EFTBUFFER ( FM, *DPK, CipherMode, ICV[8], *clear_data, OCV[8], *enc_data ) ;
SafeNet, Inc.
181
DECIPHER_2
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
D D D D D
Length 3 1 Var 1
Attribute h h K-Spec h
Description Function Code Function Modifier = 00 Key specifier for DPK (Formats: 0 - 3, 10, 11, 13, 20, 51) Cipher Mode 00 = ECB 01 = CBC Input Chaining Value Cipher text Description Function Code Return Code Output Chaining Value Deciphered data
h h Attribute h h h h
This function deciphers the supplied data using a host-stored session key (DPK) supplied within a key specifier. The function performs single-DES or triple-DES decipherment, as determined by the length of the supplied key, and supports both Electronic Code Book (ECB) and Cipher Block Chaining (CBC) modes of operation. The function supports decipherment of large messages (or data files) either by one call to the function or by multiple calls. For CBC decipherment using multiple calls, chaining values must be maintained between calls. DPK-Spec Key specifier incorporating a single or double length host-stored or HSM-stored DPK. Specifies the mode of operation for the decipherment: 0 Electronic Code Book (ECB) 1 Cipher Block Chaining (CBC) Chaining value for CBC decipherment. For decipherment of a message or file using one call, or on the first call of a multi-call decipherment, this field should be set to the required value of the Initialization Vector (IV). On subsequent calls of a multi-call decipherment, the field should be set to the value of the OCB provided by the previous call. For ECB decipherment, this field will be ignored. eDPK(Data) OCV Cipher text to be deciphered. Must be a multiple of 8 bytes long. Chaining value for CBC decipherment. For decipherment of a message or file using a multi-call decipherment, the value in this field should be used as the ICV in the next call. For ECB decipherment, this field will be set to zero.
CM
ICV
SafeNet, Inc.
182
Data
NOTES
This function supercedes functions 81, 83. When the function modifier is missing, the function returns error code 24, missing function code.
SHP Toolkit MK2 int EFT_EE0801_Decipher IN UCHAR IN KEYSPEC IN UCHAR IN UCHAR IN EFTBUFFER OUT OUT UCHAR EFTBUFFER ( FM, *DPK, CipherMode, ICV[8], *enc_data, OCV[8], *clear_data);
SafeNet, Inc.
183
ENCIPHER_3
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
D D U D D
Length 3 1 Var 1
Attribute h h K-Spec h
Description Function Code Function Modifier = 00 Key specifier for DPK (Formats: 0 - 3, 10, 11, 13, 16) Cipher Mode 00 = ECB 01 = CBC Input Chaining Value Data to be enciphered Description Function Code Return Code Output Chaining Value Ciphertext
h h Attribute h h h h
This function enciphers the supplied Data using a session key (DPK) supplied within a key specifier. The function performs DES or SEED encryption, as determined by the DPK key specifier and supports both Electronic Code Book (ECB) and Cipher Block Chaining (CBC) modes of operation. The function supports encipherment of large messages (or data files) either by one call to the function or by multiple calls. For CBC encipherment using multiple calls, chaining values must be maintained between calls. FM DPK-Spec = 00. Must be set to zero. Key specifier incorporating a single-length or double-length host-stored or HSM stored DPK. This field determines the encryption method. DES formats 00 03 (DES keys only), 10, 11 and 13 SEED formats 00 03 (SEED keys only) and 16 Specifies the mode of operation for the encipherment for the response content eDPK(Data): 0 Electronic Code Book (ECB) 1 Cipher Block Chaining (CBC) Chaining value for CBC encipherment. For encipherment of a message or file using one call, or on the first call of a multi-call encipherment, this field should be set to the required value of the Initialization Vector (IV). On subsequent calls of a multi-call encipherment, the field should be set to the value of the OCB provided by the previous call. For ECB encipherment, the contents of this field will be ignored. For DES processing this field must be 8 bytes in length while for SEED processing this field must be 16 bytes in length. Chaining value for CBC encipherment. For encipherment of a message or file using a multi-call encipherment, the value in this field should be used as the ICV in the next call.
CM
ICV
OCV
SafeNet, Inc.
184
Chapter 15 Data Ciphering Functions For ECB encipherment, the contents of this field will be set to zero. For DES processing this field will be 8 bytes in length, while for SEED processing this field will be 16 bytes in length. Plaintext data to be enciphered. For DES processing this field must be a multiple of 8 bytes long while for SEED processing it must be a multiple of 16 bytes.
Data
NOTES
For information on the SEED algorithm see the Glossary. When the = 00 is missing, the function returns error code 24, missing function code.
SHP Toolkit MK2 int EFT_EE0804_Encipher3 ( IN UCHAR FM, IN KEYSPEC *DPK, IN UCHAR CipherMode, IN EFTBUFFER *ICV, IN EFTBUFFER *clear_data, OUT OUT EFTBUFFER EFTBUFFER *OCV, *enc_data );
SafeNet, Inc.
185
DECIPHER_3
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
D D U D D
Length 3 1 Var 1
Attribute h h K-Spec h
Description Function Code Function Modifier = 00 Key specifier for DPK (Formats: 0 - 3, 10, 11, 13, 16) Cipher Mode 00 = ECB 01 = CBC Input Chaining Value Ciphertext Description Function Code Return Code Output Chaining Value Deciphered data
h h Attribute h h h h
This function deciphers the supplied data using a session key (DPK) supplied within a key specifier. The function performs DES or SEED decryption, as determined by the DPK key specifier and supports both Electronic Code Book (ECB) and Cipher Block Chaining (CBC) modes of operation. The function supports decipherment of large messages (or data files) either by one call to the function or by multiple calls. For CBC decipherment using multiple calls, chaining values must be maintained between calls. FM DPK-Spec = 00. Must be set to zero. Key specifier incorporating a single-length or double-length hoststored or HSM-stored DPK. This field determines the encryption method. DES formats 00 03 (DES keys only), 10, 11 and 13. SEED formats 00 03 (SEED keys only) and 16. Specifies the mode of operation for the decipherment: 0 Electronic Code Book (ECB) 1 Cipher Block Chaining (CBC) Chaining value for CBC decipherment. For decipherment of a message or file using one call, or on the first call of a multi-call decipherment, this field should be set to the required value of the Initialization Vector (IV). On subsequent calls of a multi-call decipherment, the field should be set to the value of the OCB provided by the previous call. For ECB decipherment, the contents of this field will be ignored. For DES processing this field must be 8 bytes in length while for SEED processing this field must be 16 bytes in length. Ciphertext to be deciphered. For DES processing this field must be a multiple of 8 bytes long while for SEED processing it must be a multiple of 16 bytes. Chaining value for CBC decipherment. For decipherment of a
CM
ICV
eDPK(Data)
OCV
SafeNet, Inc.
186
Chapter 15 Data Ciphering Functions message or file using a multi-call decipherment, the value in this field should be used as the ICV in the next call. For ECB decipherment, the contents of this field will be set to zero. For DES processing this field will be 8 bytes in length, while for SEED processing this field will be 16 bytes in length. Deciphered plaintext data.
Data
NOTE
For information on the SEED algorithm see the Glossary. When the function modifier is missing, the function returns error code 24, missing function code.
SHP Toolkit MK2 int EFT_EE0805_Decipher3( IN UCHAR FM, IN KEYSPEC *DPK, IN UCHAR CipherMode, IN EFTBUFFER *ICV, IN EFTBUFFER *enc_data, OUT OUT EFTBUFFER EFTBUFFER *OCV, *clear_data);
SafeNet, Inc.
187
ENCIPHER-KTM1
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
D D U D D
Request Content
EE0806 FM DPK-Spec CM
Length 3
Attribute h
1 Var 1
h K-Spec h
Function Modifier = 00 Key specifier for DPK (Formats: 0 - 3, 10, 11, 13, 16) Cipher Mode 00 = ECB 01 = CBC Input Chaining Value Key specifier for KTM (Formats: 0 - 3, 10, 11, 13, 16)
Description
ICV KTM-Spec
Response Content
Var Var
Length
h K-Spec
Attribute
3 1 Var Var
h h h h
This function enciphers the supplied KTM using a session key (DPK) supplied within a key specifier. The function performs DES or SEED encryption, as determined by the DPK key specifier and supports both Electronic Code Book (ECB) and Cipher Block Chaining (CBC) modes of operation. FM DPK-Spec = 00. Must be set to zero. Key specifier incorporating a single-length or double-length host-stored or HSM -stored DPK. This field determines the encryption method. DES formats 00 03 (DES keys only), 10, 11 and 13. SEED formats 00 03 (SEED keys only) and 16. Specifies the mode of operation for the encipherment: 0 Electronic Code Book (ECB) 1 Cipher Block Chaining (CBC) For SEED processing this field must be set to 0 (ECB mode), otherwise error 0C will be returned. Chaining value for CBC encipherment. For encipherment of a message or file using one call, or on the first call of a multi-call encipherment, this field should be set to the required value of the Initialization Vector (IV). On subsequent calls of a multi-call encipherment, the field should be set to the value of the OCB provided by the previous call. For ECB or SEED processing the contents of this field will be ignored. This field must be 8 bytes in length. Key specifier incorporating a single-length or double-length host-stored or HSM -stored KTM. When DPK-Spec refers to an HSM or host stored SEED key the KTM must be either a double length DES key or a single length SEED key. Chaining value for CBC encipherment. For encipherment of a message or file using a multi-call encipherment, the value in this field should be used as the ICV in the next call. For ECB or SEED processing, this field will be set to zero. This field will be 8 bytes in length.
CM
ICV
KTM-Spec
OCV
SafeNet, Inc.
188
Chapter 15 Data Ciphering Functions KTM key encrypted with DPK according to the algorithm specified.
eDPK(KTM)
NOTE
1. This function is an insecure one as it allows KTMs to be encrypted by DPKs. Its use is not recommended by SafeNet. 2. This function currently supports SEED encryption using ECB mode. It does not support SEED CBC mode. 3. This function is not included as standard. It will only be available if selected as an order time option when purchasing a HSM. Please contact SafeNet if you require this functionality or further details. 4. For information on the SEED algorithm see the Glossary.
SHP Toolkit MK2 int EFT_EE0806_EncipherKTM1( IN UCHAR FM, IN KEYSPEC *DPK, IN UCHAR CipherMode, IN EFTBUFFER *ICV, IN KEYSPEC *KTM, OUT OUT EFTBUFFER EFTBUFFER *OCV, *eDPK_KTM);
SafeNet, Inc.
189
D D U U U
Description Function Code No. of 8 byte Blocks Terminal Key Set Index Must be multiple of 8 bytes Description Function Code Return Code Data encrypted under Base Key
This function encrypts the supplied DATA under the B- key (BK) of the HSM stored 3624 Terminal Key Set as indicated by the specified index (TKSI), using the DES in Electronic Code Book mode.
SafeNet, Inc.
190
D D U U U
Description Function Code No. of 8 byte Blocks Terminal Key Set Index Must be multiple of 8 bytes Description Function Code Return Code Clear Data
This function decrypts the supplied encrypted DATA using the B-key (BK) of the HSM stored 3624 Terminal Key Set as indicated by the specified index (TKSI), and using the DES in Electronic Code Book mode.
SafeNet, Inc.
191
SafeNet, Inc.
192
2.
SafeNet, Inc.
193
Consistent with existing HSM practice, long-term keys are stored within HSM key memory, whereas short-term (session) keys are stored encrypted in the host computer. The console operations allow two keys to be input and stored in key memory. The memory may be configured so that these keys are either Key Exchange Keys, for online key exchange, or Pin Encryption Keys for manual key management. The keys are input as a number of components, which are combined to form the required key. On successful key entry the Key Check Value (KCV) for the key is displayed. Additional host functions are available for: 1. Manual Key Management One function allows an acquirer institution to perform PIN translation for routing an encrypted PIN to the MasterCard Switch center. The other function permits an issuer to verify an encrypted PIN received from the MasterCard Switch center. 2. Online Key Exchange One function allows a PIN Encryption Key (KPE) received from the MasterCard Switch center to be re-encrypted for host storage and subsequent use with the standard HSM PIN management functions. The other function that is provided generates an encrypted random KPE. This is not required by a member institution for normal transaction processing, as the PIN Encryption Keys are generated only by the MCS. However, the function may be valuable during system testing.
Equivalent keys
Key Type Key encrypting key PIN encrypting key Visa key KEK KPE HSM key KIS / KIR PPK
Console operations
Original operations (single-keys only) Enter and store KEK Enter and store KPE Replacement operations (single- and double-length keys) Enter and store KIS / KIR Enter and store PPK
Host functions
Original functions MT-KPE-GEN Replacement functions II-Key-Gen
SafeNet, Inc.
194
SafeNet, Inc.
195
MT-KPE-GEN
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
D D U D U
Length 1 1 Length 1 1 8 8 2
Description Function Code Index of KEK Description Function Code Return Code PIN Encryption Key PIN Encryption Key Key Check Value
This function generates a random PIN Encryption Key (KPE). For transmitting to the receiving institution, it is returned encrypted under the Key Exchange Key (KEK) that is indicated by the specified index (MT-index). It is also returned encrypted under the appropriate Domain Master Key (KM) variant for storage within the host. The Key Check Value (KCV) for the generated key is also returned. MT-Index eKEKn(KPE) eKMv1(KPE) KCV This field has the range of 1 to 2 and indexes a KEK. The KEK is used to encrypt the KPE. The random PIN Encryption Key is returned encrypted under the Key Exchange Key indicated by the specified index. The random PIN Encryption Key is returned encrypted under variant 1 of the Domain Master Key for storage within the host. The Key Check Value.
This function is not required by member institutions. For online key exchange, the PIN Encryption Keys (KPE) are generated and distributed by the MasterCard Switch center. This function is included for testing purposes only. SHP Toolkit MK2 int EFT_A0_MT_KPE_Gen( IN UCHAR MTIndex, OUT OUT OUT UCHAR eKEKn_KPE[8], UCHAR eKMv1_KPE[8], UCHAR KCV[2]);
SafeNet, Inc.
196
MT-KPE-RCV
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
D D U D U
Length 1 1 8 Length 1 1 8 2
Description Function Code Index of KEK PIN Encryption Key Description Function Code Return Code PIN Encryption Key Key Check Value
This function allows a received PIN Encryption Key (KPE) that has been encrypted under the Key Exchange Key (KEKn) indicated by the supplied Index (MT-Index), to be further encrypted under Domain Master Key (KM) Variant1 for storage within the host. The Key Check Value (KCV) for the received key is also returned to allow verification of key synchronization. MT-Index eKEKn(KPE) eKMv1(KPE) KCV This field has the range of 1 to 2 and indexes a KEK. The KEK is used to encrypt the KPE. The PIN Encryption Key is received encrypted under the Key Exchange Key indicated by the supplied index. The PIN Encryption Key is returned encrypted under variant 1 of the Domain Master Key for storage within the host. The Key Check Value.
This function is provided for an acquirer / issuer member using the online key exchange procedure. As the received KPE is re-encrypted by KM1, it may be used with the standard HSM PIN management functions. In this case, the KPE is equivalent to the HSM notation of the PPK.
SHP Toolkit MK2 int EFT_A1_MT_KPE_Rcv( IN UCHAR MTIndex, IN UCHAR eKEKn_KPE[8], OUT OUT UCHAR eKMv1_KPE[8], UCHAR KCV[2]);
SafeNet, Inc.
197
MT-PIN-TRAN
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
D D U D U
Length 1 1 8 8 1 6 Length 1 1 8
Description Function Code PIN Format PIN encrypted under PPK PIN Protect Key Index of KEK Account Number Block Description Function Code Return Code AS/ANSI Formatted Pin Block
This function translates a PIN Block from encryption under a host stored PIN Protect Key (PPK) to encryption under an HSM stored PIN Encryption Key (KPE). If appropriate, the PIN Block format is changed to AS/ANSI format. PF This field specifies the format of the supplied PIN Block. The valid field values are: 1 = AS/ANSI format (no conversion required) 3 = PIN/PAD format (format conversion required) The PIN encrypted by a host stored PIN Protect Key. The PIN Protect Key encrypted by a variant 1 of the Domain Master Key. This field has the range of 1 to 2 and indexes a KPE. The KPE is used to reencrypt the PIN Block. The 12-digit Account Number Block used in the formation of the clear AS/ANSI PIN Block. The AS/ANSI formatted PIN Block containing the PIN to be verified is supplied encrypted by an HSM stored PIN Encryption Key.
This function is provided for use by an acquirer employing manual key management. The function will fail with Error Code 78 if PF indicates a PIN block format that is disabled or conflicts with the reformatting restrictions. SHP Toolkit MK2 int EFT_A2_MT_PIN_Tran( IN UCHAR PF, IN UCHAR ePPK_PIN[8], IN UCHAR eKMv1_PPK[8], IN UCHAR MTIndex, IN UCHAR ANB[6], OUT UCHAR eKPE_AS_PIN[8]);
SafeNet, Inc.
198
MT-PIN-VER
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
D D U D U
Request Content A3 PVK-Index eKPE(AS-PIN) MT-Index PAN ANB Offset Response Content A3 rc
Length 1 1 8 1 8 6 6 Length 1 1
Description Function Code Index of PVK AS/ANSI Formatted Pin Block Index of KPE Primary Account Number Account Number Block PIN offset data Description Function Code Return Code
This function performs the verification of a PIN in an AS/ANSI formatted PIN Block, using the IBM 3624 method. PVK-Index This field has the range of 01 to 99 and indexes the PIN Verification Key (PVKn) and the Decimalization Table (DTn) to be used in the PIN calculation process. The AS/ANSI formatted PIN Block containing the PIN to be verified is supplied encrypted by an HSM stored PIN Encryption Key. This field has the range of 1 to 2 and indexes a KPE. The Primary Account Number (or other card data) used in the verification procedure. The 12-digit Account Number Block used in the formation of the clear AS/ANSI PIN Block. Up to 12 digits of offset data. The significant digits must be left-justified padded with zeros.
No response data is returned by this function, and it is only provided for use by an issuer employing manual key management. An Error Code of 00 indicates successful verification, while 08 indicates a verification failure. The function will fail with Error Code 78 if the ANSI PIN block format is disabled. SHP Toolkit MK2 int EFT_A3_MT_PIN_Ver( IN UCHAR PVKIndex, IN UCHAR eKPE_AS_PIN[8], IN UCHAR MTIndex, IN UCHAR PAN[8], IN UCHAR ANB[6], IN UCHAR Offset[6]);
SafeNet, Inc.
199
MT_PIN_VER_PVV
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
D D U D U
Request Content A7 PVVK-Index eKPE(AS-PIN) MT-Index ANB TSP12 PVV Response Content A7 rc
Length 1 1 8 1 6 6 2 Length 1 1
Description Function Code Index of PVVK AS/ANSI Formatted Pin Block Index of KPE Account Number Block Transformed Security Parameter PIN Verification Value Description Function Code Return Code
This function performs the verification of a PIN in an AS/ANSI formatted PIN Block, using the PVV method. The PVVK-index has a range of 1 to 36. The PVKI has a range of 1 to 6. PVVK-Index eKPE(AS-PIN) Identifies the PVK-A/B pair that is to be used in the derivation of the PVV and must be in BCD format. The AS/ANSI formatted PIN Block containing the PIN to be verified is supplied encrypted by an HSM stored PIN Encryption Key as specified by the MT-index. This field has the range of 1 to 2 and indexes a KPE. The 12-digit Account Number Block used in the formation of the clear AS/ANSI PIN Block. The leftmost 12 digits of the TSP and consists of 11 PAN digits followed by the appropriate one digit PVKI. The PIN Verification Value used to verify the calculated PVV.
The function returns no response data. A Return Code of 00 indicates that the PIN is verified. A 07 indicates that the format of the PIN Block in the request is incorrect, and a 08 indicates PIN verification failure. The function will fail with Error Code 78 if the ANSI PIN block format is disabled. SHP Toolkit MK2 int EFT_A7_MT_PIN_Ver_PVV( IN UCHAR PVVKIndex, IN UCHAR eKPE_AS_PIN[8], IN UCHAR MTIndex, IN UCHAR ANB[6], IN UCHAR TSP12[6], IN UCHAR PVV[2]);
SafeNet, Inc.
200
SafeNet, Inc.
201
As mentioned in the introduction, a CSCK is distributed between American Express and a Card Issuer encrypted by a KIS or KIR. These keys are functionally equivalent to the key denoted ZMK. The HSM supports 99 single- or double-length Interchange Sending Keys (KIS) and 99 single- or double-length Interchange Receiving Keys (KIR). For distribution of a CSCK, a double-length KIS or KIR will be used.
SafeNet, Inc.
202
CALC_CSCK
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
D D U D D
Attribute
Description Function code Key specifier for CSCK (Formats: 0 - 3, 11, 13) The account Block Description Function code Return code Packed 3, 4 or 5 digit CSCs
K-Spec h Attribute h h h
This function calculates CSC values and returns them to the host. Six bytes are returned. This is a packed representation of the 3, 4 or 5 digit CSCs. The CSCs are returned in the previously mentioned order. CardData: this is the account Block derived from the PAN and expiry date as defined by American Express.
SHP Toolkit MK2 int EFT_A8_CalculateCSCK ( IN KEYSPEC *CSCK, IN UCHAR CardData [8], OUT UCHAR CSC[6] );
SafeNet, Inc.
203
CREATE_CSCK
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
D D U D D
Length 1 1
Attribute h h
Description Function code This field specifies whether the key is to be stored in the host database or in HSM secure memory. Currently only the value 0 is supported which means storage on the host. Description Function code Return code Key specifier for CSCK (Format: 11, 13) Key verification code of CSCK
Length 1 1 Var 3
Attribute h h K-Spec h
This function causes a random CSCK to be generated and returned to the host encrypted under the HSMs KM variant 6.
Notes: The key-type 11 under the Response Content, are generated when using the Legacy option. The key-types 11, 13 under the Response Content, are generated based on the chosen operation on console and FM.
SHP Toolkit MK2 int EFT_A9_CreateCSCK ( IN UCHAR CSCK_storage_indicator, OUT OUT KEYSPEC UCHAR *CSCK, KVC[3]);
SafeNet, Inc.
204
EXPORT_CSCK
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
D D U D D
Description Function code Key specifier for CSCK (Format: 11, 13) Key specifier KIS (ZMK). (Formats: 0 3) Description Function code Return code Encrypted CSCK Key verification code of CSCK
This function causes a key to be returned encrypted under a KIS (ZMK) specified by the index provided in the KIS specifier. SHP Toolkit MK2 int EFT_AA_ExportCSCK ( IN KEYSPEC *CSCK, IN KEYSPEC *KIS, OUT UCHAR OUT UCHAR eKIS_CSCK[16], KVC[3]);
SafeNet, Inc.
205
IMPORT_CSCK
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
D D U D D
Length 1 1
Attribute h h
Description Function code This field specifies whether the imported key is to be stored in the host database or in HSM secure memory. Currently only the value 0 is supported which means storage on the host. Key specifier for KIR (ZMK) (Formats: 0 - 3) Encrypted CSCK Description Function code Return code Key specifier for CSCK (Format: 11, 13) Key verification code of CSCK
K-Spec
Attribute h h K-Spec h
This function causes a key to be returned encrypted under the HSMs KM variant 6 for storage on the host database.
Notes: The key-type 11 under the Response Content, are generated when using the Legacy option. The key-types 11, 13 under the Response Content, are generated based on the chosen operation on console and FM.
The KVC returned in the response is calculated as the leftmost 24 bits of the result of triple-DES encrypting a 64-bit Block of zeros with the double-length key.
SHP Toolkit MK2 int EFT_AB_ImportCSCK ( IN UCHAR CSCK_storage_indicator, IN KEYSPEC *KIR, IN UCHAR eKIR_CSCK[16], OUT OUT KEYSPEC UCHAR *CSCK, KVC[3]);
SafeNet, Inc.
206
Subsequent to generation of a random PIN, associated data used in PIN verification (3624 Offset or Visa PVV) can be calculated using the applicable HSM functions.
SafeNet, Inc.
207
It is recommended that a static (host stored or HSM stored) double length PPK be used to encrypt the PIN when it is generated to ensure that a PIN cannot be compromised prior to issuance. For transmission to another node, the encrypted PIN can be translated to an interchange PPK using the PIN Translate function. Theses functions support PINs that are assigned to a customer (account number) at the time of generation. Additional functions can be added (if required) to support PIN printing of unassigned PINs. Each optional item to be printed is defined by appending a set of the fields Line No, Column No, Data Len, and Data to the host request. Each Data character must be printed within the area defined by the size of the PIN Mailer envelope. Also, each Data character must not overprint any other defined area (including other defined Data areas).
SafeNet, Inc.
208
PIN-MAIL
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
D D U D D
Request Content E2 PVK-Index PAN PIN Len PIN Type Line No* Column No* Data Len* Data* Response Content E2 rc Offset
* = optional set of fields.
Length 1 1 8 1 1 1 1 1
DATALEN
Attribute h d h h h h h h h Attribute h h h
Description Function Code Index of PVK Primary Account Number PIN Length PIN Type = 0 or Non zero Line Number Column Number Data Length Data Description Function Code Return Code PIN offset Data
Length 1 1 6
The optional data fields may be repeated as many times as is necessary, or until the buffer is full. This function generates a PIN that has a length equal to PIN Len. If a random PIN is generated an Offset associated with this PIN is returned with the HSM response. PVK-Index This field identifies the PVKn and DTn to be used in the PIN calculation process. This index should equal the institution index used in the access of the PIN Mailer console operations. This is the Primary Account Number used in the generation of the PIN. It must be padded appropriately prior to input to this function. This field specifies the number of PIN digits to be printed. It must be in the range 4 to 12 and be less than or equal to the number of PIN digits entered on the PIN Mailer Print Parameters screen. This field is an indicator for the type of PIN that is to be printed. The valid values are: 0 Use the derived PIN as the customer PIN and do not return an Offset in the response data; or non-0 Use a randomly generated number as the PIN and return an Offset which equals the randomly generated PIN minus the derived PIN. Line No Column No This is the number of the line on which Data is to be printed. It must be in the range 1 to 40. This is the number of the column from which Data is to be printed. It must be in the range 1 to 120.
PIN Type
SafeNet, Inc.
209
Chapter 18 PIN Issuance Functions This refers to the length of the Data. The maximum length of the data depends on the Ignore Optional data length check check box on the print parameter screen. If the check box is not selected, the length is greater than zero and must not extend beyond the end of an envelope line. If the check box is selected, then the data length check is ignored. This field contains the data to be printed. This field consists of 12 digits of offset data. The significant digits are leftjustified in the field. Part of the SHP Toolkit MK2 function call. The ESMID is a pointer to a NULL terminated string that identifies the name of the SafeNet HSM (ESM) to which functions are directed. The SafeNet HSM name is set using the wincommsconfig utility provided as part of the SHP Toolkit product suite.
Data Len
SHP Toolkit MK2 int EFT_E2_PinMailer( IN UCHAR IN UCHAR IN UCHAR IN UCHAR IN UCHAR _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN UCHAR UCHAR EFTBUFFER UCHAR UCHAR EFTBUFFER UCHAR UCHAR EFTBUFFER UCHAR UCHAR EFTBUFFER UCHAR UCHAR EFTBUFFER UCHAR UCHAR EFTBUFFER UCHAR UCHAR EFTBUFFER UCHAR UCHAR EFTBUFFER UCHAR UCHAR EFTBUFFER
*ESMID, PVKIndex, PAN[8], PinLen, PinType, *LineNo1, *ColumnNo1, *Data1, *LineNo2, *ColumnNo2, *Data2, *LineNo3, *ColumnNo3, *Data3, *LineNo4, *ColumnNo4, *Data4, *LineNo5, *ColumnNo5, *Data5, *LineNo6, *ColumnNo6, *Data6, *LineNo7, *ColumnNo7, *Data7, *LineNo8, *ColumnNo8, *Data8, *LineNo9, *ColumnNo9, *Data9,
SafeNet, Inc.
210
SafeNet, Inc.
211
PIN-GENERATE
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
D D U D D
Request Content EE0E04 FM PIN Len PFo ANB PPK-Spec Response Content EE0E04 rc ePPK(PIN)
Description Function Code Function Modifier = 00 PIN Length in the range 04 - 12 Output PIN Block Format (Formats: 01, 10, 13) Account Number Block Key specifier for PPK (Formats: 0 - 3, 10, 11, 13) Description Function Code Return Code Encrypted PIN Block.
This function generates a random PIN, formats and encrypts it for host storage. Processing steps 1. Generate a random PIN of the specified length. 2. Format the PIN into an ISO Format 0 or 3 PIN Block. 3. Encrypt the PIN Block using the PPK. The function will fail with Error Code 78 if PF indicates a PIN block format that is disabled.
SHP Toolkit MK2 int EFT_EE0E04_GenRandomPIN( IN UCHAR FM, IN UCHAR PINLen, IN UCHAR PFo, IN UCHAR ANB[6], IN KEYSPEC *PPK, OUT UCHAR ePPK_PIN[8]);
SafeNet, Inc.
212
PIN-PRINT
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
D D U D D
Length 3 1 8 Var 1 6 8
Attribute h h h K-Spec h h h
Description Function Code Function Modifier = 00 Encrypted PIN Block. Key specifier for (Formats: 0 - 3, 10, 11, 13) Input PIN Block Format (Formats: 01, 10, 13) Account Number Block Primary Account Number. Content is significant only if PAN print is selected in PIN Mail control screen. Repeat count for the following data sets. This set of fields specifies data to be printed at a given line and column. The set of fields is optional and may be repeated multiple times, as specified by the Data sets field, causing 0, 1 or more data fields to be printed. Description Function Code Return Code
1 1 1 Var
h h h h
Length 1 1
Attribute h h
This function prints a previously generated PIN. It is normally disabled and is controlled by the PIN Mailer console operations. ESMID Part of the SHP Toolkit MK2 function call. The ESMID is a pointer to a NULL terminated string that identifies the name of the SafeNet HSM (ESM) to which functions are directed. The SafeNet HSM name is set using the wincommsconfig utility provided as part of the SHP Toolkit product suite.
Processing steps 1. Decrypt the supplied encrypted PIN Block using PPK. 2. Extract the PIN from the ISO PIN Block. 3. Build a print image using the PIN, PAN and optional data.
The function will fail with Error Code 78 if PF indicates a PIN block format that is disabled. SHP Toolkit MK2
SafeNet, Inc.
213
int EFT_EE0E05_PrintPIN( IN UCHAR *ESMID, IN UCHAR FM, IN UCHAR ePPK_PIN[8], IN KEYSPEC *PPK, IN UCHAR PFi, IN UCHAR ANB[6], IN UCHAR PAN[8], IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN UCHAR UCHAR UCHAR EFTBUFFER UCHAR UCHAR EFTBUFFER UCHAR UCHAR EFTBUFFER UCHAR UCHAR EFTBUFFER UCHAR UCHAR EFTBUFFER UCHAR UCHAR EFTBUFFER UCHAR UCHAR EFTBUFFER UCHAR UCHAR EFTBUFFER UCHAR UCHAR EFTBUFFER UCHAR UCHAR EFTBUFFER DataSets, *LineNo1, *ColumnNo1, *Data1, *LineNo2, *ColumnNo2, *Data2, *LineNo3, *ColumnNo3, *Data3, *LineNo4, *ColumnNo4, *Data4, *LineNo5, *ColumnNo5, *Data5, *LineNo6, *ColumnNo6, *Data6, *LineNo7, *ColumnNo7, *Data7, *LineNo8, *ColumnNo8, *Data8, *LineNo9, *ColumnNo9, *Data9, *LineNo10, *ColumnNo10, *Data10);
SafeNet, Inc.
214
SafeNet, Inc.
215
GEN_RANDOM
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
D D D D D
Request Content EE0002 FM Random No. Len Response Content EE0002 rc Random No.
Attribute h h h Attribute h h h
Description Function Code Function Modifier = 00 = 01 FF. (1 255) Description Function Code Return Code Random number with length as specified in Length of Random Number
This function generates and returns a random number of the specified length. The return code (rc) for this function indicates the success or failure of the function call. Please refer to Appendix I Error Codes for a complete listing of return codes. Processing steps 1. Generates a random number with the number of bytes as specified in Length of Random Number. 2. Returns the generated number in the Response field Random Number. Note The generated random number is not 'massaged' in any way, e.g. the bytes are not adjusted for odd parity as is sometimes required for DES keys. SHP Toolkit MK2 int EFT_EE0002_EMVGenRandomNumber( IN UCHAR FM, IN UCHAR Len, OUT EFTBUFFER *RAND_NUM);
SafeNet, Inc.
216
EMV_AC_GEN
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
D D D D D
Request Content EE2000 FM IMKAC Spec APANB RN AC-Data Response Content EE2000 Rc AC
Description Function Code Function Modifier = 00 Key specifier for IMKAC (Formats: 0 3, 11, 13) Application PAN Block Random Number Application Cryptogram Data Description Function Code Return Code Application Cryptogram
This function generates an Application Cryptogram (TC, AAC or ARQC) as defined in [Ref. [1] of MarkII] FM IMKAC Spec APANB : RN : AC Data : = 00. Reserved for possible future use; must be set to zero. Key specifier which provides access to the IMKAC. Formats 0 3, and 11, 13 accepted. Application PAN Block as defined in [Ref. [1] of MarkII]. The HSM performs no checking on the contents of this field. Random number for creating the ICC Session Key as defined in [Ref. [1] of MarkII]. The HSM performs no checking on the contents of this field. Data used to calculate the TC, AAC or ARQC, as specified in [Ref. [1] of MarkII]. The HSM performs no checking on the contents of this field. This field must be a multiple of eight bytes.
The return code (rc) for this function indicates the success or failure of the function call. Please refer to Appendix J Error Codes for a complete listing of return codes. Processing steps 1. Derive the ICC Master Key (MKAC) using the Issuer Master Key and APANB, according to the method specified in 2.7.1 of reference [1] of MarkII. 2. Derive the ICC Session Key (SK) using the derived MKAC and RN, according to the method specified in 2.7.2 of reference [1] of MarkII. 3. Calculate the Application Cryptogram using SK and the data provided in AC-Data, according to the method specified in figure 2.3 of reference [1] of MarkII. SHP Toolkit MK2 int EFT_EE2000_EMVAcGen( IN UCHAR FM, IN KEYSPEC *IMK_AC, IN UCHAR APANB[8], IN UCHAR RN[8], IN EFTBUFFER *AC_DATA, OUT UCHAR AC[8]);
SafeNet, Inc.
217
EMV_AC_VERIFY
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
D D D D D
Attribute h h K-Spec h h h
Description Function Code Function Modifier = 00, 01 or 04 Key specifier for IMKAC (Formats: 0 - 3, 11, 13) Application PAN Block Random Number If FM = 00 this field contains the 8-byte Application Cryptogram (AC). If FM = 01 or 04 the field contains the variable length CAP token Data used in the calculation of the Application Cryptogram. Must be a multiple of 8 bytes. Only available when FM = 01 or 04 Authenticate field from IPB (Formats: 0 - 3, 19). Only present when FM = 04 Data signed to produce CAP Token. Must be a multiple of eight bytes. Description Function Code Return Code
AC-Data
Var
Bitmap
Var
K-Spec
Transaction Data
Var
Length 3 1
Attribute h h
This function verifies an application cryptogram (TC, AAC or ARQC) as defined in Reference [1] of MarkII. FM = 00. When the = 00 is set to 00 the Bitmap field is not included. When the = 00 is set to 01 or 04 the Bitmap field is included. The setting of this field also effects the AC/CAP Token and the Transaction Data fields. For details see the descriptions in the table above. Key specifier which provides access to the IMKAC. Formats 0 - 3, and 11, 13 accepted. Application PAN Block as defined in Reference [1] of MarkII. The HSM performs no checking on the contents of this field. Random number for creating the ICC Session Key as defined in Reference [1] of MarkII. The HSM performs no checking on the contents of this field. Application Cryptogram (TC, AAC or ARQC) Calculated by ICC as defined in reference [1]of MarkII. This field is 8 bytes in length. This field is present when FM = 00.
SafeNet, Inc.
218
Chapter 19 EMV Functions CAP Token (AAC or ARQC) that has been produced by an EMV ICC. This field is a Var field. This field is present when FM = 01 or 04.When the function is used with FM = 01 or 04 support is provided for a variablelength Application Cryptogram created as indicated by the set bits in the Bitmap field. This modification supports the Chip Authentication Program as specified in [reference [31] of MarkII]. The CAP Token field contains the bits of the Application Cryptogram to be verified as indicated by the Bitmap (see below). If the length (in bits) of this field is greater than the number of bits that are set to 1 in the Bitmap field, then the significant bits must be leftjustified and padded to the right with zero bits. Data used to calculate the TC, AAC or ARQC, as specified in reference [1] of MarkII. The HSM performs no checking on the contents of this field. This field must be a multiple of eight bytes. The Bitmap field is a key specifier field. It specifies a HSM stored or host stored portion of the Issuer Proprietary Bitmap (IPB) that relates to the Shortened AC. This field is not available when FM is set to 00. The number of set bits must be 16 and 64 (note: there is no requirement that the number of set bits is a multiple of 8). Data signed to produce CAP Token. Only present when FM = 04. Must be a multiple of eight bytes.
CAP Token
AC-Data
Bitmap
Transaction Data
Refer to the Appendix entitled EMV Function Examples for examples of request and response packages for this function. The return code (rc) for this function indicates the success or failure of the function call. Please refer to Appendix J Error Codes for a complete listing of return codes. Processing steps 1. Derive the ICC Master Key (MKAC) using the Issuer Master Key and APANB, according to the method specified in 2.7.1 of reference [1] of MarkII. 2. Derive the ICC Session Key (SK) using the derived MKAC and RN, according to the method specified in 2.7.2 of reference [1] of MarkII. 3. Calculate the Application Cryptogram using SK and the data provided in AC-Data, according to the method specified in figure 2.3 of reference [1] of MarkII. 4. When FM=01, select only the bits indicated by the set bits in the bitmap to generate the reference Application Cryptogram. 5. Compare the values of the calculated Application Cryptogram and that supplied in AC. EFT API For FM=00 int EFT_EE2001_EMVAcVerify( IN IN IN IN IN IN For FM=01 or FM=4 UCHAR KEYSPEC UCHAR UCHAR UCHAR EFTBUFFER FM, *IMK_AC, APANB[8], RN[8], AC[8], *AC_DATA);
SafeNet, Inc.
219
int EFT_EE2001_EMVAcVerify_2( IN IN IN IN IN IN IN IN
SafeNet, Inc.
220
EMV_DAC_GEN
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
D D D D D
Request Content EE2002 FM IMKDAC Spec APANB Response Content EE2002 rc DAC
Description Function Code Function Modifier = 00 Key specifier for IMKDAC (Formats: 0 - 3, 11, 13) Application PAN Block Description Function Code Return Code Data Authentication Code
This function generates a Data Authentication Code (DAC) as defined in reference [1] of MarkII. FM IMKDAC Spec APANB : = 00. Reserved for possible future use; must be set to zero. Key specifier which provides access to the IMKDAC. Formats 0 - 3, and 11, 13 accepted. Application PAN Block as defined in reference [1] of MarkII. The HSM performs no checking on the contents of this field.
The return code (rc) for this function indicates the success or failure of the function call. Please refer to Appendix J Error Codes for a complete listing of return codes. Processing steps 1. Derive the DAC using the Issuer Master Key and APANB, according to the method specified in 2.9 of reference [1] of MarkII. SHP Toolkit MK2 int EFT_EE2002_EMVDacGen( IN UCHAR FM, IN KEYSPEC *IMK_DAC, IN UCHAR APANB[8], OUT UCHAR DAC[2]);
SafeNet, Inc.
221
EMV_DAC_VERIFY
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
D D D D D
Request Content EE2003 FM IMKDAC Spec APANB DAC Response Content EE2003 rc
Description Function Code Function Modifier = 00 Key specifier for IMKDAC (Formats: 0 3, 11, 13) Application PAN Block Data Authentication Code Description Function Code Return Code
This function verifies a Data Authentication Code (DAC) as defined in reference [1] of MarkII. FM IMKDAC Spec APANB : DAC = 00. Reserved for possible future use; must be set to zero. Key specifier which provides access to the IMKDAC. Formats 0 3, and 11, 13 accepted. Application PAN Block as defined in reference [1] of MarkII. The HSM performs no checking on the contents of this field. DAC(Data Authentication Code) calculated by ICC as defined in reference [1] of MarkII.
The return code (rc) for this function indicates the success or failure of the function call. Please refer to Appendix J Error Codes for a complete listing of return codes. Processing steps 1. Derive the DAC using the Issuer Master Key and APANB, according to the method specified in 2.9 of reference [1] of MarkII. 2. Compare the values of the calculated Data Authentication Code and that supplied in DAC. SHP Toolkit MK2 int EFT_EE2003_EMVDacVerify( IN UCHAR FM, IN KEYSPEC *IMK_DAC, IN UCHAR APANB[8], IN UCHAR DAC[2]);
SafeNet, Inc.
222
EMV_ICC_DN_GEN
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
D D D D D
Request Content EE2004 FM IMKIDN-Spec APANB IDN Data Response Content EE2004 rc IDN
Description Function Code Function Modifier = 00 Key specifier for IMKIDN (Formats: 0 - 3, 11, 13) Application PAN Block ICC Dynamic Number Data Description Function Code Return Code ICC Dynamic Number
This function generates a ICC Dynamic Number as defined in reference [1] of MarkII. FM IMKIDN Spec APANB : IDN Data : = 00. Reserved for possible future use; must be set to zero. Key specifier which provides access to the IMKIDN. Formats 0 - 3, and 11, 13 accepted. Application PAN Block as defined in reference [1] of MarkII. The HSM performs no checking on the contents of this field. Data for calculating IDN, as specified in reference [1] of MarkII.
The return code (rc) for this function indicates the success or failure of the function call. Please refer to Appendix J Error Codes for a complete listing of return codes. Processing steps 1. Derive the ICC Master Key (MKIDN) using the Issuer Master Key and APANB, according to the method specified in 2.7.1 of reference [1] of MarkII. 2. Calculate the IDN using the MKIDN and the data provided in IDN Data, according to the method specified in 2.10 of reference [1] of MarkII.
NOTE
IDN Data should contain the value which is the ICC Application Transaction Counter (ATC) and the Unpredictable Number (UN). SHP Toolkit MK2 int EFT_EE2004_EMVIccDnGen( IN UCHAR FM, IN KEYSPEC *IMK_IDN, IN UCHAR APANB[8], IN UCHAR RN[8], OUT UCHAR IDN[2]);
SafeNet, Inc.
223
EMV_ICC_DN_VERIFY
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
D D D D D
Description Function Code Function Modifier = 00 Key specifier for IMKIDN (Formats: 0 - 3, 11, 13) Application PAN Block Random Number ICC Dynamic Number Description Function Code Return Code
This function verifies a ICC Dynamic Number as defined in reference [1] of MarkII. FM IMKIDN Spec APANB RN IDN = 00. Reserved for possible future use; must be set to zero. Key specifier which provides access to the IMKIDN Formats 0 3, and 11, 13 accepted. Application PAN Block as defined in reference [1] of MarkII. The HSM performs no checking on the contents of this field. Random number for calculating data of IDN as defined in reference [1] of MarkII. Calculated ICC Dynamic Number as defined in reference [1] of MarkII.
The return code (rc) for this function indicates the success or failure of the function call. Please refer to Appendix J Error Codes for a complete listing of return codes. Processing steps 1. Derive the ICC Master Key (MKIDN) using the Issuer Master Key and APANB, according to the method specified in 2.7.1 of reference [1] of MarkII. 2. Calculate the IDN using the MKIDN and the data provided in IDN Data, according to the method specified in 2.10 of reference [1] of MarkII. 3. Compare the values of the calculated ICC Dynamic Number and that supplied in IDN.
NOTE
IDN Data should contain the value which is the ICC Application Transaction Counter (ATC) and the Unpredictable Number (UN). SHP Toolkit MK2 int EFT_EE2005_EMVIccDnVerify( IN UCHAR FM, IN KEYSPEC *IMK_IDN, IN UCHAR APANB[8], IN UCHAR RN[8], IN UCHAR IDN[2]);
SafeNet, Inc.
224
EMV_ARPC_GEN
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
D D D D D
Request Content EE2006 FM IMKAC-Spec APANB ARPC-Data Response Content EE2006 rc ARPC
Description Function Code Function Modifier = 00 Key specifier for IMKAC (Formats: 0 - 3, 11, 13) Application PAN Block Authorization Response Cryptogram Data Description Function Code Return Code Authorization Response Cryptogram
This function generates an Authorization Response Cryptogram as defined in reference [1] of MarkII. FM IMKAC Spec APANB ARPC Data = 00. Reserved for possible future use; must be set to zero. Key specifier which provides access to the IMKAC. Formats 0 - 3, and 11, 13 accepted. Application PAN Block as defined in reference [1] of MarkII. The HSM performs no checking on the contents of this field. Authorization Response Cryptogram Data, used for calculating the ARPC as defined in reference [1] of MarkII.
The return code (rc) for this function indicates the success or failure of the function call. Please refer to Appendix J Error Codes for a complete listing of return codes. Processing steps 1. Derive the ICC Master Key (MKAC) using the Issuer Master Key and APANB, according to the method specified in 2.7.1 of reference [1] of MarkII. 2. Calculate the ARPC using the MKAC and the data provided in ARPC-DATA according to the method specified in figure 2.4 of reference [1] of MarkII. SHP Toolkit MK2 int EFT_EE2006_EMVArpcGen( IN IN IN IN OUT
SafeNet, Inc.
225
EMV_SCRIPT_CRYPTO
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
D D D D D
Length 3 1 1
Attribute h h h
Description Function Code Function Modifier = 00 Select Code 01 = Encrypt Command Data Only 02 = Calculate MAC for entire command 03 = Encrypt and Calculate MAC Key specifier for IMKSMI (Formats: 0 - 3, 11, 13) Key specifier for IMKSMC (Formats: 0 - 3, 11, 13) Application PAN Block Random Number Plain Text Data (Must be a multiple of 8 bytes) Pointer into Script-Data Script Data (Must be a multiple of 8 bytes) Description Function Code Return Code Encrypted data. Message Authentication Code
IMKSMI-Spec IMKSMC-Spec APANB RN Text Offset Script-Data Response Content EE2007 rc eSMC(text) MAC
This function performs the cryptographic processing required for Secure Messaging as defined in reference [1] of MarkII. It is intended to be used to either: encrypt the command data; calculate a MAC for the command header and command data; or encrypt the command data and calculate a MAC for the command header and encrypted command data.
FM SC
= 00. See eSMC(text) below for further information. Identifies the required processing: 1: encrypt (CBC mode) command data only in Text field 2: calculate a MAC for the entire command Script-Data field. 3: Combine 1 and 2, i.e. encrypt the command data, insert the resultant cipher text into the Script-Data field and calculate a MAC. Key specifier which provides access to the IMKSMI. Formats 0 3, and 11, 13 accepted. Note: When SC = 1, this field is not used; it must be a valid variable-length field but its data portion will not be checked to contain a valid key specifier.
IMKSMI Spec
SafeNet, Inc.
226
Chapter 19 EMV Functions Key specifier which provides access to the IMKSMC. Formats 0 3, and 11, 13 accepted. Note: When SC = 2, this field is not used; it must be a valid variable-length field but its data portion will not be checked to contain a valid key specifier. Application PAN Block as defined in reference [1] of MarkII. The HSM performs no checking on the contents of this field. ARQC/AAC/TC. Script Command Data that is included in the sent Script to ICC. For SC = 3, points to the start byte in Script-Data where the encrypted Text will be copied. An Offset of zero points to the start of Script-Data. Note this field is always big endian. i.e. the byte order in this field is most significant byte first. Script Data is sent to ICC. The script data length must be greater then or equal to the sum of offset and the length of encrypted New PIN data. Encrypted text in a variable length field. This is the same length as the specified input Text field. If FM = 0 this is pure data and is not formatted as a Var field. If FM = 1 it is a standard Var field.
IMKSMC Spec
Script-Data eSMC(text)
This function returns zero when completing successfully, otherwise an error is returned. Please refer to Appendix J Error Codes for a complete listing of return codes. Processing steps 1. If Select Code is 1 or 3, derive the ICC MAC Master Key (MKSMC) using the Issuer Master Key (IMKSMC) and APANB, according to the method specified in 2.7.1 of reference [1] of MarkII. Derive the ICC MAC Session Key (SKSMC) using the derived MKSMC and RN, according to the method specified in 2.7.2 of reference [1] of MarkII. 2. If Select Code is 2 or 3, derive the ICC Encipherment Master Key (MKSMI) using the Issuer Master Key (IMKSMI) and APANB, according to the method specified in 2.7.1 of reference reference [1] of MarkII. Derive the ICC Encipherment Session Key (SKSMI) using the derived MKSMI and RN, according to the method specified in 2.7.2 of reference [1] of MarkII. 3. If Select Code is 1 or 3, encrypt Text using SKSMC CBC mode. If Select Code is 3, insert the resulting cipher text in Script-Data at the position specified by Offset. 4. If Select Code is 2 or 3, calculate the MAC for Script-Data using SKSMI. SHP Toolkit MK2 SHP Toolkit MK2 only supports the function when used with = 00 FM=01. int EFT_EE2007_EMVScriptCrypto( IN UCHAR FM, IN UCHAR SC, IN KEYSPEC *IMK_SMI, IN KEYSPEC *IMK_SMC, IN UCHAR APANB[8], IN UCHAR RN[8], IN EFTBUFFER *Text, IN USHORT Offset, IN EFTBUFFER *Script_Data, OUT OUT EFTBUFFER UCHAR *eSMC_Text, MAC[8]);
SafeNet, Inc.
227
EMV_VERIFY_AC_EMV2000
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
D D D D D
Request Content EF2010 FM IMKAC-Spec PAN Data IV H B ATC AC/ CAP Token
Attribute h h K-Spec h h h h h h
Description Function Code. Function Modifier = 00, 01 or 04 Key specifier for IMKAC (Formats: 0 - 3, 11, 13) Formatted PAN and PAN Sequence No. Initialization Vector Height for tree of keys. Branch factor of tree of keys. Application Transaction Counter If FM = 00 this field contains the 8-byte Application Cryptogram (AC). If FM = 01 or 04 the field contains the variable length CAP token Data used in the calculation of the Application Cryptogram. Must be a multiple of 8 bytes. Only available when FM = 01 or 04 Authenticate field from IPB (Formats 0 - 3, 19). Only present when FM = 04 Data signed to produce CAP Token. Must be a multiple of eight bytes. Description Function Code. Return Code
AC Data
Var
Bitmap
Var
K-Spec
Transaction Data
Var
Length 3 1
Attribute h h
This function verifies an Application Cryptogram (TC, AAC, ARQC) that has been produced by an ICC. The ICC Session Key is derived using the method specified in the EMV2000 specification in reference [5] of MarkII. FM = 00. When the FM is set to 00 the Bitmap fields are not included. When the FM is set to 01or 04, the Bitmap field is included. The setting of this field also affects the AC/CAP Token and the Transaction Data fields. For details see the descriptions in the table above. Key specifier which provides access to the IMKAC. Formats 0 3, and 11, 13 accepted. Formatted PAN and PAN Sequence No. Initialization Vector Height for tree of keys Branch factor of tree of keys Application Transaction Counter (min = 01; max = FFFF)
SafeNet, Inc.
228
Chapter 19 EMV Functions Application Cryptogram (TC, AAC or ARQC) Calculated by ICC as defined in reference [1] of MarkII. This field is 8 bytes in length. This field is present when FM = 00. CAP Token (AAC or ARQC) that has been produced by an EMV ICC. This field is a Var field. This field is present when FM = 01 or 04. When the function is used with FM = 01 or 04 support is provided for a variablelength Application Cryptogram created as indicated by the set bits in the Bitmap field. This modification supports the Chip Authentication Program as specified in reference [31] of MarkII. The CAP Token field contains the bits of the Application Cryptogram to be verified as indicated by the Bitmap (see below). If the length (in bits) of this field is greater than the number of bits that are set to 1 in the Bitmap field, then the significant bits must be leftjustified and padded to the right with zero bits. Data used in the calculation of the Application Cryptogram. Must be a multiple of eight bytes). The Bitmap field is a key specifier field. It specifies an HSM stored or host stored portion of the Issuer Proprietary Bitmap (IPB) that relates to the Shortened AC. This field is not available when FM is set to 00. The number of bits set must be 16 and 64 (note: there is no requirement that the number of bits set is a multiple of 8). Data signed to produce CAP Token. Only present when FM = 04. Must be a multiple of eight bytes.
AC
CAP Token
AC Data Bitmap
Transaction Data
Refer to the Appendix titled EMV Function Examples for examples of request and response packages for this function. This function returns zero when completing successfully, otherwise an error is returned. Please refer to Appendix J Error Codes for a complete listing of return codes. Processing steps 1. Derive the ICC Master Key (MKAC) using the Issuer Master Key and PAN Data, according to the method specified in A1.4 of reference [5] of MarkII. 2. Derive the ICC Session Key (SK) using the derived MKAC, IV, H, b and ATC, according to the method specified in A1.3 of reference [5] of MarkII. 3. Calculate the Application Cryptogram using SK and the data provided in AC Data, according to the method specified in A1.2 of reference [5] of MarkII. 4. When FM=01, select only the bits indicated by the set bits in the bitmap to generate the reference Application Cryptogram. 5. Compare the values of the calculated Application Cryptogram and that supplied in AC. Function usage The function is used during on-line transactions and batch processing of off-line transactions, or during card initialization to test a card. SHP Toolkit MK2 For FM=00 int EFT_EF2010_EMVVerifyAc_EMV2000( IN UCHAR FM, IN KEYSPEC *IMK_AC, IN UCHAR PAN_data[8], IN UCHAR IV[16], IN UCHAR H, IN UCHAR b, IN UCHAR ATC[2], IN UCHAR AC[8], IN EFTBUFFER *AC_DATA); For FM = 01 or FM = 04
SafeNet, Inc.
229
int EFT_EF2010_EMVVerifyAc_EMV2000_2( IN UCHAR FM, IN KEYSPEC *IMK_AC, IN UCHAR PAN_data[8], IN UCHAR IV[16], IN UCHAR H, IN UCHAR b, IN UCHAR ATC[2], IN EFTBUFFER *CAPToken, IN EFTBUFFER *AC_DATA, IN KEYSPEC bitmap, _IN EFTBUFFER *TR_data);
SafeNet, Inc.
230
EMV_VERIFY_AC_VISA
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
D D D D D
Attribute h h K-Spec h h
Description Function Code. Function Modifier = 00 or 01 Key specifier for Issuer Master Key. (Formats: 0 - 3, 11, 13) PAN Sequence No. Application Cryptogram/ Shortened Application Cryptogram When FM = 00 this field contains the AC and is 8 bytes in length; When FM = 01 this field contains the Shortened AC and is a Var field) Application Cryptogram Data (Must be a multiple of eight bytes). Only available when FM = 01 Authenticated field from IPB (Formats 0 - 3, 19) Description Function Code. Return Code
AC Data Bitmap
Var Var
h K-Spec
Length 3 1
Attribute h h
This function verifies an Application Cryptogram (TC, AAC, ARQC) that has been produced by an ICC. The ICC Master Key is used directly to calculate the Application Cryptogram, as specified by Visa in reference [8]. FM IMKAC Spec PAN Data AC When Function Modifier = 00 the Bitmap field is not included. When Function Modifier = 01 the Bitmap field is included. Key specifier which provides access to the IMKAC. Formats 0 - 3, and 11, 13 accepted. Formatted PAN and PAN Sequence No. Application Cryptogram (TC, AAC or ARQC) Calculated by ICC as defined in reference [1] of MarkII. This field is 8 bytes in length. This field is present when FM = 00. Shortened Application Cryptogram (AAC or ARQC) that has been produced by an EMV ICC. This field is a Var field. This field is present when FM=01.When the function is used with FM = 01 support is provided for a variable-length Application Cryptogram created as indicated by the set bits in the Bitmap field. This modification supports the Chip Authentication Program as specified in reference [31] of MarkII. The Shortened AC field contains the bits of the Application Cryptogram to be verified as indicated by the Bitmap (see below). If the length (in bits) of this field is greater than the number of bits that are set to 1 in the Bitmap field, then the significant bits must be left-justified and padded to the right with zero bits.
Shortened AC
SafeNet, Inc.
231
Chapter 19 EMV Functions Data used in the calculation of the Application Cryptogram (must be a multiple of eight bytes). The Bitmap field is a key specifier field. It specifies a HSM stored or host stored portion of the Issuer Proprietary Bitmap (IPB) that relates to the Shortened AC. This field is not available when FM is set to 00. The number of set bits must be 16 and 64 (note: there is no requirement that the number of set bits is a multiple of 8).
AC Data Bitmap
Refer to the Appendix titled EMV Function Examples for examples of request and response packages for this function. This function returns zero when completing successfully, otherwise an error is returned. Please refer to Appendix J Error Codes for a complete listing of return codes. Processing steps 1. Derive the ICC Master Key (MKAC) using the Issuer Master Key and supplied PAN Data, according to the method specified in A1.4 of reference [5] of MarkII. 2. Calculate the Application Cryptogram using MKAC and the data provided in AC Data, according to the method specified in A1.2 of reference [5] of MarkII. 3. When FM = 01, select only the bits indicated by the set bits in the bitmap to generate the reference Application Cryptogram. 4. Compare the values of the calculated Application Cryptogram and that supplied in AC. Function usage The function is used during online transactions and batch processing of offline transactions, or during card initialization to test a card. SHP Toolkit MK2 For FM = 00 int EFT_EF2011_EMVVerifyAcVisa( IN UCHAR IN KEYSPEC IN UCHAR IN UCHAR IN EFTBUFFER For FM = 01 int EFT_EF2011_EMVVerifyAcVisa_2( IN UCHAR IN KEYSPEC IN UCHAR IN EFTBUFFER IN EFTBUFFER
IN KEYSPEC
SafeNet, Inc.
232
EMV_GENERATE_ARPC
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
D D D D D
Request Content EF2012 FM IMKAC-Spec PAN Data IV H b ATC ARPC Data Response Content EF2012 rc ARPC
Description Function Code. Function Modifier = 00 Key specifier for Issuer Master Key. (Formats: 0 - 3, 11, 13) Formatted PAN and PAN Sequence No. Initialization Vector Height of tree of keys. Branch factor of tree of keys. Application Transaction Counter. Authorization Response Cryptogram Data Description Function Code. Return Code Authorization Response Cryptogram.
This function calculates an ARPC for transmitting to an ICC. The ICC Session Key is derived using the method specified in the EMV2000 specification, reference [5] of MarkII. FM IMKAC Spec PAN Data IV H b ATC ARPC Data = 00. Reserved for possible future use; must be set to zero. Key specifier which provides access to the IMKAC. Formats 0 - 3, and 11, 13 accepted. Formatted PAN and PAN Sequence No. Initialization Vector Height for tree of keys Branch factor of tree of keys Application Transaction Counter (min = 01; max = FFFF) Authorization Response Cryptogram Data, used for calculating the ARPC as defined in [1].
This function returns zero when completing successfully, otherwise an error is returned. Please refer to Appendix J Error Codes for a complete listing of return codes. Processing steps 1. Derive the ICC Master Key (MKAC) using the Issuer Master Key and PAN Data, according to the method specified in A1.4 of reference [5] of MarkII. 2. Derive the ICC Session Key (SK) using the derived MKAC, IV, H, b and ATC, according to the method specified in A1.3 of reference [5] of MarkII. 3. Calculate the ARPC using SK and ARPC Data according to the method specified in 8.2 of reference [5] of MarkII. Note: ARPC Data should contain the value Y, which is the XORed combination of the ARQC and the ARC.
SafeNet, Inc.
233
Function usage The function is used during online transactions. It can also be used during card initialization to test a card. SHP Toolkit MK2 int EFT_EF2012_EMVGenerateArpc( IN UCHAR FM, IN KEYSPEC *IMK_AC, IN UCHAR PAN_data[8], IN UCHAR IV[16], IN UCHAR H, IN UCHAR b, IN UCHAR ATC[2], IN UCHAR ARPC_data[8], OUT UCHAR ARPC[8]);
SafeNet, Inc.
234
EMV_SCRIPT_CRYPTO_EMV2000
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
D D D D D
Length 3 1 1
Attribute h h h
Description Function Code. Function Modifier = 00/01 Select Code 01 = Encrypt Command Data Only 02 = Calculate MAC for entire command 03 = Encrypt and Calculate MAC Key specifier for IMKSMI. (Formats: 0 - 3, 11, 13) Key specifier for IMKSMC. (Formats: 0 - 3, 11, 13) Formatted PAN and PAN Sequence No. Initialization Vector Height of tree of keys Branch factor of tree of keys Application Transaction Counter Encryption Mode Plain text data. Offset Script Data to be sent to ICC Must be multiple of 8 Bytes Description Function Code. Return Code Encrypted data. Message Authentication Code
IMKSMI Spec IMKSMC Spec PAN Data IV H b ATC Mode Text Offset Script-Data Response Content EF2013 rc eSKSMC(Text) MAC
This function performs the cryptographic processing required for Secure Messaging, i.e. message authentication and / or message encryption. It is intended to be used to either: (i) just encrypt the command data; (ii) just calculate a MAC for the command header and command data; or (iii) both encrypt the command data and calculate a MAC for the command header and encrypted command data. The ICC Session Key is derived using the method specified in the EMV2000 specification, s reference [5] of MarkII. FM SC = 00/01. See eSKSMC(Text) below for further information. Identifies the required processing: 1: encrypt command data only in Text field 2: calculate a MAC for the entire command Script-Data field. 3: Combine 1 and 2, i.e. encrypt the command data, insert the resultant cipher text into the Script-Data field and calculate a MAC.
SafeNet, Inc.
235
Chapter 19 EMV Functions Key specifier which provides access to the IMKSMI. Formats 0 - 3, and 11, 13 accepted. Note: When SC = 01, this field is not used; it must be a valid variable-length field but its data portion will not be checked to contain a valid key specifier. Key specifier which provides access to the IMKSMC. Formats 0 - 3, and 11, 13 accepted. Note: When SC = 02, this field is not used; it must be a valid variable-length field but its data portion will not be checked for containing a valid key specifier. Formatted PAN and PAN Sequence No. Initialization Vector Height for tree of keys Branch factor of tree of keys Application Transaction Counter (min = 01; max = FFFF) Encryption Mode. 00=ECB; 01=CBC Script Command Data that is included in the sent Script to ICC. (Length must be a multiple of 8.) For SC = 3, points to the start byte in Script-Data where the encrypted Text will be copied. An Offset of zero points to the start of Script-Data. This field is big endian. i.e. the byte order in this field is most significant byte first. Script Data is sent to ICC. (Length must be a multiple of 8). The script data length must be greater then or equal to the sum of offset and the length of encrypted New PIN data. Encrypted text in a variable length field. This is the same length as the specified input Text field. If FM = 00 this is pure data and is not formatted the same as a Var field. If FM = 01 it is a standard Var field.
IMKSMI Spec
IMKSMC Spec
Script-Data
eSKSMC(Text)
This function returns zero when completing successfully, otherwise an error is returned. Please refer to Appendix J Error Codes for a complete listing of return codes. Processing steps 1. If Select Code is 1 or 3, derive the ICC MAC Master Key (MKSMC) using the Issuer Master Key (IMKSMC) and PAN Data, according to the method specified in A1.4 of reference[5] of MarkII. 2. Derive the ICC MAC Session Key (SKSMC) using the derived MKSMC, IV, H, b and ATC, according to the method specified in A1.3 of reference [5] of MarkII. 3. If Select Code is 2 or 3, derive the ICC Encipherment Master Key (MKSMI) using the Issuer Master Key (IMKSMI) and PAN Data, according to the method specified in A1.4 of reference [5] of MarkII. 4. Derive the ICC Encipherment Session Key (SKSMI) using the derived MKSMI, IV, H, b and ATC, according to the method specified in A1.3 of reference [5] of MarkII. 5. If Select Code is 1 or 3, encrypt Text using SKSMC according to the encryption mode of operation specified in Encryption Mode. If Select Code is 3, insert the resulting cipher text in Script-Data at the position specified by Offset. 6. If Select Code is 2 or 3, calculate the MAC for Script-Data using SKSMI.
SHP Toolkit MK2 SHP Toolkit MK2 only supports the function when used with FM = 01. int EFT_EF2013_EMVScriptCrypto_EMV2000( IN UCHAR
FM,
SafeNet, Inc.
236
Chapter 19 EMV Functions IN IN IN IN IN IN IN IN IN IN IN IN OUT OUT UCHAR KEYSPEC KEYSPEC UCHAR UCHAR UCHAR UCHAR UCHAR UCHAR EFTBUFFER USHORT EFTBUFFER EFTBUFFER UCHAR SC, *IMK_SMI, *IMK_SMC, PAN_data[8], IV[16], H, b, ATC[2], encrypt_mode, *Text, Offset, *Script_Data, *eSMC_Text, MAC[8]);
SafeNet, Inc.
237
EMV_SCRIPT_CRYPTO_VISA
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
D D D D D
Length 3 1 1
Attribute H H H
Description Function Code Function Modifier = 00/01 Select Code 01 = Encrypt Command Data Only 02 = Calculate MAC for entire command 03 = Encrypt and Calculate MAC Key specifier for IMKSMI. (Formats: 0 - 3, 11, 13) Key specifier for IMKSMC. (Formats: 0 - 3, 11, 13) Formatted PAN and PAN Sequence No. Application Transaction Counter. Plain text data. Must be multiple of 8 Bytes Offset Script Data to be sent to ICC. Must be multiple of 8 Bytes Description Function Code Return Code Encrypted data Message Authentication Code
IMKSMI Spec IMKSMC Spec PAN Data ATC Text Offset Script-Data Response Content EF2014 rc eSKSMC(Text) MAC
This function performs the cryptographic processing required for Secure Messaging, i.e. message authentication and / or message encryption. It is intended to be used to either: (i) just encrypt the command data; (ii) just calculate a MAC for the command header and command data; or (iii) both encrypt the command data and calculate a MAC for the command header and encrypted command data. The ICC session keys are derived using the method specified by Visa in reference [8] of MarkII. FM SC = 00/01. See eSKSMC(Text) below for further information. Identifies the required processing: 1: encrypt command data only (ECB mode) in Text field 2: calculate a MAC only - for the entire command in Script-Data field. 3: Combine 1 and 2, i.e. encrypt the command data, insert the resultant cipher text into the Script-Data field and calculate a MAC. Key specifier which provides access to the IMKSMI. Formats 0 - 3, and 11, 13 accepted. Note: When SC = 01, this field is not used; it must be a valid variable-length field but its data portion will not be checked to contain a valid key specifier.
IMKSMI Spec
SafeNet, Inc.
238
Chapter 19 EMV Functions Key specifier which provides access to the IMKSMC. Formats 0 - 3, and 11, 13 accepted. Note: When SC = 02, this field is not used; it must be a valid variable-length field but its data portion will not be checked to contain a valid key specifier. Formatted PAN and PAN Sequence No. Application Transaction Counter (min = 01, max = FFFF) Script Command Data that is included in the sent Script to ICC. (Length must be a multiple of 8.) For SC = 03, points to the start byte in Script-Data where the encrypted Text will be copied. An Offset of zero points to the start of Script-Data. This field is big endian. i.e. the byte order in this field is most significant byte first. Script Data is sent to ICC. (Length must be a multiple of 8). The script data length must be greater then or equal to the sum of offset and the length of encrypted New PIN data. Encrypted text in a variable length field. This is the same length as the specified input Text field. If FM = 00 this is pure data and is not formatted the same as a Var field. If FM = 01 it is a standard Var field.
IMKSMC Spec
Script-Data
eSKSMC(Text)
This function returns zero when completing successfully, otherwise an error is returned. Please refer to Appendix J Error Codes for a complete listing of return codes. Processing steps 1. If Select Code is 1 or 3, derive the ICC MAC Master Key (MKSMC) using the Issuer Master Key (IMKSMC) and PAN Data, according to the method specified in A1.4 of reference [5] of MarkII. Derive the ICC MAC Session Key (SKSMC) using the derived MKSMC and ATC, according to the method specified in B.4 of reference [8] of MarkII. 2. If Select Code is 2 or 3, derive the ICC Encipherment Master Key (MKSMI) using the Issuer Master Key (IMKSMI) and PAN Data, according to the method specified in A1.4 of reference [5]. Derive the ICC Encipherment Session Key (SKSMI) using the derived MKSMI and ATC, according to the method specified in B.4 of reference [8]of MarkII. 3. If Select Code is 1 or 3, encrypt Text using SKSMC ECB mode. If Select Code is 3, insert the resulting cipher text in Script-Data at the position specified by Offset. 4. If Select Code is 2 or 3, calculate the MAC for Script-Data using SKSMI. SHP Toolkit MK2 SHP Toolkit MK2 only supports the function when used with FM=01. int EFT_EF2014_EMVScriptCryptoVisa( IN UCHAR IN UCHAR IN KEYSPEC IN KEYSPEC IN UCHAR IN UCHAR IN EFTBUFFER IN USHORT IN EFTBUFFER OUT OUT EFTBUFFER UCHAR
FM, SC, *IMK_SMI, *IMK_SMC, PAN_data[8], ATC[2], *Text, Offset, *Script_Data, *eSMC_Text, MAC[8]);
SafeNet, Inc.
239
EMV_PIN_CHANGE_UNBLOCK_VISA
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
D D D D D
Length 3 1 1
Attribute h h h
Description Function Code Function Modifier = 00/01 Function Flag 00 = PIN UnBlock only 01 = PIN Change/UnBlock using PIN 02 = PIN Change/UnBlock using PIN Key specifier for IMKSMI (Formats: 0 - 3, 11, 13) Key specifier for IMKSMC (Formats: 0 - 3, 11, 13) Formatted PAN and PAN Sequence No. Application Transaction Counter. Key specifier for PPK (Formats: 0 - 3, 10, 11, 13) Encrypted PIN Block (New PIN) Account Number Block Key specifier for PVK (Formats: 0 - 3, 11, 12, 13, 14) Validation Data Offset PIN Length (Current PIN) Script-Data Position Script Data. Minimum length = 16 bytes Description Function Code Return Code Encrypted New PIN Data Message Authentication Code
IMKSMI Spec IMKSMC Spec PAN Data ATC PPK-Spec ePPK(PIN) ANB PVK-Spec Validation Data Offset PIN Length Script-Data Position Script-Data Response Content EF2015 rc New PIN Data MAC
The purpose of this function is to provide the issuer with the capability either to unBlock the PIN or to simultaneously change and unBlock the reference PIN. This function calculates the MAC and if required the encrypted new PIN data. FM P2 = 00/01. See New PIN Data below for further information. Identifies the required processing: 00: PIN UnBlock only 01: PIN Change/UnBlock with PIN data generated using the current PIN 02: PIN Change/UnBlock with PIN data generated without using the current PIN
SafeNet, Inc.
240
Chapter 19 EMV Functions Issuer Master Key for secure message integrity key specifier. Formats 0 - 3, and 11, 13 accepted. Issuer Master Key for secure message confidentiality key specifier. Formats 0 - 3, and 11, 13 accepted. Formatted PAN and PAN Sequence No. Application Transaction Counter (min = 01; max = FFFF)
The following three request fields are utilized in the calculation of the new PIN. These fields are only processed when P2 = 01 or 02. PPK-Spec ePPK(PIN) ANB Key specifier for PPK. Formats 0 - 3, 10, 11 and 13 accepted. Formatted PIN encrypted by the PPK. Account Number Block.
The following four request fields are utilized in the calculation of the current PIN. These fields are only processed when P2 = 01. PVK-Spec Validation Data Offset PIN length Key specifier for PVK. Formats 0 - 3 , 11, 12, 13, 14 accepted. Validation Data used to calculate the current PIN. This field consists of 12 digits of offset data. The significant digits are left justified in the field. Current PIN length.
Script-Data Position For P2 = 01 or 02, this points to the start byte in Script-Data where the encrypted PIN data will be copied. A Script-Data Position of zero points to the start of Script-Data. This field is big endian. Script-Data Used to calculate the MAC. If the last (or only) data Block is less than 8 bytes it is padded to the right with a hexadecimal 80. If this data Block is still less than 8 bytes it is right filled with 1 byte hexadecimal zeros until it is 8 bytes. The script data length must be greater then or equal to the sum of offset and the length of encrypted New PIN data. Encrypted New PIN Data. If FM = 01 it is formatted as a standard Var field. If FM = 00 then the field is only present when P2 = 01 or 02. The contents of the field when present is pure data, 16 bytes in length. MAC Message authentication code.
Processing steps 1. Get the value of P2. 2. If the value of P2 is set to 01 perform the following steps Get the current reference PIN from the PVK-Spec, Validation Data, Offset and PIN length fields. Derive the ICC Data Encipherment Master Key (MKSMC) using the Issuer Master Key (IMKSMC) and PAN data, according to the method specified in A1.4 of reference[5] of MarkII. Derive the ICC Data Encipherment Session Key (SKSMC) using the derived MKSMC and ATC, according to the method specified in B.4 of reference[9] of MarkII. Get the new reference PIN from the ePPK(PIN), PPK-Spec and ANB fields. A 16 hexadecimal digit PIN Block is formed as follows Take the 8 rightmost digits of the DK A and right justify them in a 16 digit field, zero fill the remaining 8 digits. Take a second 16 hexadecimal digit Block, form the unformatted ANSI PIN Block with the new PIN. Xor the 2 Blocks of data to form the PIN Block. Xor this PIN Block with the current PIN, where the current PIN is left justified in a 16 hexadecimal digit Block and zero filled. The result is called the delta PIN.
SafeNet, Inc.
241
Encrypt the delta PIN with the Data Encipherment SKs according to B.3 (figure B-2) of reference [9] of MarkII to generate the encrypted new PIN data. 3. If the value of P2 is set to 02 perform the following steps Derive the ICC Data Encipherment Master Key (MKSMC) using the Issuer Master Key (IMKSMC) and PAN data, according to the method specified in A1.4 of Ref [5]. Derive the ICC Data Encipherment Session Key (SKSMC) using the derived MKSMC and ATC, according to the method specified in B.4 of reference [9] of MarkII. Get the new reference PIN from the ePPK(PIN), PPK-Spec and ANB fields. A 16 hexadecimal digit PIN Block is formed as follows Take the 8 rightmost digits of the DK A and right justify them in a 16 digit field, zero fill the remaining 8 digits. Take a second 16 hexadecimal digit Block, form an unformatted ANSI PIN Block with the new PIN. Xor the 2 Blocks of data to form the PIN Block. Encrypt this PIN Block with the Data Encipherment Session Keys according to B.3 (figure B-2) of reference [9] of MarkII to generate the encrypted new PIN data. 4. Derive the ICC MAC Master Key (MKSMI) using the Issuer Master Key (IMKSMI) and PAN data, according to the method specified in A1.4 of reference [5] of MarkII. Derive the ICC MAC Session Key (SKSMI) using the derived MKSMI and ATC, according to the method specified in B.4 of reference [9] of MarkII . 5. Calculate the MAC according to B.2 (figure B-1) of reference [9] using SKSMI. If P2 is equal to 00, the MAC data is the Script-Data. If P2 is equal to 01 or 02, copy in the encrypted PIN data into the Script-Data at the position specified by the Script-Data position field, use this resulting data as the MAC data. The function will fail with Error Code 78 if the format 10 PIN block is disabled.
NOTES
Request fields that are not required for processing are present but not used. They must be of the correct length and format. If the field is a var field it must be a valid variable-length field, its data portion will not be checked. When P2 = 00 the response field New PIN data is absent.
SHP Toolkit MK2 only supports the function when used with FM=01. SHP Toolkit MK2 int EFT_EF2015_EMVPinChangeUnBlockVisa( IN UCHAR IN UCHAR IN KEYSPEC IN KEYSPEC IN UCHAR IN UCHAR IN KEYSPEC IN UCHAR IN UCHAR IN KEYSPEC IN UCHAR IN UCHAR IN UCHAR IN USHORT IN EFTBUFFER OUT OUT EFTBUFFER UCHAR FM, P2, *IMK_SMI, *IMK_SMC, PAN_data[8], ATC[2], *PPK, ePPK_PIN[8], ANB[6], *PVK, Validation_data[8], Offset[6], PIN_len, Script_Data_Pos, *Script_Data, *New_PIN_Data, MAC[8]);
SafeNet, Inc.
242
EMV_PIN_CHANGE_UNBLOCK
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
D D U D D
Length 3 1 1
Attribute h h h
Description Function Code Function Modifier = 00 Function Flag 00 = PIN UnBlock only 01 = PIN Change delta Block 02 = PIN Change non-delta PIN 01 = MasterCard 02 = Visa 1.4 PIN 03 = Visa 1.3 PIN Key specifier for IMKSMI (Formats 0 - 3, 11, 13) Key specifier for IMKSMC (Formats 0 - 3, 11, 13) Key specifier for IMKAC (Formats 0 - 3, 11, 13) Formatted PAN and PAN Sequence Number Session Key Data Encrypted PIN Block (Existing PIN) Encrypted PIN Block (New PIN) Key specifier for PPK (Formats: 0 - 3, 10, 11, 13) PIN Block Format (Formats: 10, 13) Account Number Block Script-Data Position Script Data Description Function Code Return Code Encrypted New PIN Data Message Authentication Code
Scheme
IMKSMI IMKSMC IMKAC PAN Data Session Key Data ePPK(PIN1) ePPK(PIN2) PPK PF ANB Script-Data Position Script Data Response Content EE2016 rc New PIN Data MAC
This function provides the cryptographic processing for an issuer script which will unBlock or change the offline reference PIN stored in an EMV96-based card. It calculates the MAC and, if required, the encrypted new PIN data.
SafeNet, Inc.
243
Chapter 19 EMV Functions Identifies the required processing: 00: PIN UnBlock only 01: PIN Change delta Block 02: PIN Change non-delta PIN Formatted PAN and PAN Sequence No. This field is used with IMK to derive unique integrity and confidentiality keys. Currently the Var field must be 8 bytes. If Scheme = 01 (MasterCard), then Session Key Data contains an 8-byte random number. If Scheme = 02 (Visa) then Session Key Data contains a 2-byte ATC. This field should be used to calculate session integrity and confidentiality keys. If the Function Flag (P2) = 01, this field is decrypted to get the existing PIN Decrypted to recover the new PIN ISO formats 0 and 3. This field is used to get the new PIN and, if appropriate, the existing PIN This field is used to get the new PIN and, if appropriate, the existing PIN For P2 = 01 or 02, this points to the start byte in Script-Data where the encrypted PIN data will be copied. A Script-Data Position of zero points to the start of Script-Data. This field is big endian. Script-Data Used to calculate the MAC. If the last (or only) data Block is less than 8 bytes it is padded to the right with a hexadecimal 80. If this data Block is still less than 8 bytes it is right filled with 1 byte hexadecimal zeros until it is 8 bytes. The script data length must be greater then or equal to the sum of offset and the length of encrypted New PIN data. Encrypted New PIN Data. If FM = 1 it is formatted as a standard Var field. If FM = 0 then the field is only present when P2 = 01 or 02. The contents of the field when present is pure data, 16 bytes in length. Message authentication code.
P2
PAN Data
Script-Data
MAC
The function will fail with Error Code 78 if PF indicates a PIN block format that is disabled. SHP Toolkit MK2 int EFT_EE2016_EMVPinChangeUnBlock( IN UCHAR FM, IN UCHAR P2, IN UCHAR Scheme, IN KEYSPEC *IMK_SMI, IN KEYSPEC *IMK_SMC, IN KEYSPEC *IMK_AC, IN EFTBUFFER *PAN_data, IN EFTBUFFER *SK_Data, IN UCHAR ePPK_PIN1[8], IN UCHAR ePPK_PIN2[8], IN KEYSPEC *PPK, IN UCHAR PF, IN UCHAR ANB[6], IN USHORT Script_Data_Pos, IN EFTBUFFER *Script_Data, OUT OUT EFTBUFFER UCHAR *New_PIN_Data, MAC[8]);
SafeNet, Inc.
244
EMV_PIN_CHANGE_UNBLOCK_EMV_2000
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
D D U D D
Length 3 1 1
Attribute h h h
Description Function Code Function Modifier = 00 Function Flag 00 = PIN UnBlock only 01 = PIN Change delta Block 02 = PIN Change non-delta PIN 01 = MasterCard 02 = Visa 1.4 PIN 03 =Reserved. (American Express) Key specifier for IMKSMI (Formats 0 - 3, 11, 13) Key specifier for IMKSMC (Formats 0 - 3, 11, 13) Reserved. (Key specifier for IMKAC) Formatted PAN and PAN Sequence No. Initialization Vector Height of tree of keys Branch factor of tree of keys Application Transaction Counter Encrypted PIN Block (Existing PIN) Encrypted PIN Block (New PIN) Key specifier for PPK (Formats: 0 3, 10, 11. 13) PIN Block Format (Formats: 10, 13) Account Number Block Script-Data Position Script Data Description Function Code Return Code Encrypted New PIN data Message Authentication Code
Scheme
IMKSMI IMKSMC IMKAC PAN Data IV H b ATC ePPK(PIN1) ePPK(PIN2) PPK PF ANB Script-Data Position Script-Data Response Content EE2017 rc New PIN data MAC
SafeNet, Inc.
245
This function provides the cryptographic processing for an issuer script which will unBlock or change the offline reference PIN stored in an EMV2000-based card. It calculates the MAC and, if required, the encrypted new PIN data. The key-types 11, 13 (IMKsmi/IMKsmc/IMKac) and 10, 11, 13 (PPK) under the Request Content, are generated based on the chosen operation on console and FM. P2 Identifies the required processing: 00: PIN UnBlock only 01: PIN Change delta Block 02: PIN Change non-delta PIN PAN Data Formatted PAN and PAN Sequence No. This field is used with IMK to derive unique integrity and confidentiality keys. Currently the Var field must be 8 bytes. If the Function Flag (P2) = 01, this field is decrypted to get the existing PIN Decrypted to recover the new PIN ISO formats 0 and 3. This field is used to get the new PIN and, if appropriate, the existing PIN This field is used to get the new PIN and, if appropriate, the existing PIN For P2 = 01 or 02, this points to the start byte in Script-Data where the encrypted PIN data will be copied. A Script-Data Position of zero points to the start of Script-Data. This field is big endian. Used to calculate the MAC. If the last (or only) data Block is less than 8 bytes it is padded to the right with a hexadecimal 80. If this data Block is still less than 8 bytes it is right filled with 1 byte hexadecimal zeros until it is 8 bytes. The script data length must be greater then or equal to the sum of offset and the length of encrypted New PIN data. Encrypted New PIN Data. If FM = 1 it is formatted as a standard Var field. If FM = 0 then the field is only present when P2 = 01 or 02. The contents of the field when present is pure data, 16 bytes in length. Message authentication code.
Script-Data
MAC
The function will fail with Error Code 78 if PF indicates a PIN block format that is disabled. SHP Toolkit MK2 int EFT_EE2017_EMVPinChangeUnBlockEMV2000( IN UCHAR FM, IN UCHAR P2, IN UCHAR Scheme, IN KEYSPEC *IMK_SMI, IN KEYSPEC *IMK_SMC, IN KEYSPEC *IMK_AC, IN UCHAR PAN_data[8], IN UCHAR IV[16], IN UCHAR H, IN UCHAR b, IN UCHAR ATC[2], IN UCHAR ePPK_PIN1[8], IN UCHAR ePPK_PIN2[8], IN KEYSPEC *PPK, IN UCHAR PF, IN UCHAR ANB[6], IN USHORT Script_Data_Pos,
SafeNet, Inc.
246
IN OUT OUT
SafeNet, Inc.
247
EMV_VERIFY_AC_GEN_ARPC
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
D D D D D
Length 3 1 1
Attribute h h h
Description Function Code Function Modifier = 00 01 = Verify AC only. 02 = Generate ARPC only. 03 = Verify AC and generate ARPC. Key specifier for IMKAC (Formats: 0 - 3, 11, 13) 00 = Common 01 = SECCOS. Data used with IMKAC to derive MKAC. The contents of this field are dependent on the value of MK Method. AC Key Method = 00 - 04, see page 250 Data used with MKAC to derive the session key SKAC. The contents of this field are dependent on the value of AC Key Method. AC Method = 00 03, see page 250 Data on which the AC is calculated. Application Cryptogram - ARQC, TC or AAC. 00 = same key as derived for AC. 01 = key = MKAC. Zero-length field. 01 = Method 1. = Method 2. Data on which the ARPC is calculated. Description Function Code Return Code 4 or 8 byte ARPC. zero-length field. 02
Var 1 Var
K-Spec h h
1 Var
h h
AC Method AC Data AC ARPC Key Method ARPC Key Data ARPC Method ARPC-Data Response Content EE2018 Rc ARPC
h h h h h h h Attribute h h h
Or
SafeNet, Inc.
248
This function can be used to verify an Application Cryptogram (AC), generates an ARPC both verify an Application Cryptogram (AC) and generate an ARPC The AC can be an ARQC, a TC or an AAC. The function is sufficiently flexible to meet the requirements of all processing variations used in different EMV implementations. The function therefore supports several methods (page 251) in each processing step. Each step involves a key, a method and some data, where the specific method determines the format of the related data. In the first step an initial key is provided in a key specifier, but subsequent steps use a key from a previous step. The function treats each processing step independently, so does not treat any combination of methods as invalid. However many combinations of methods would not coincide with the processing performed by any issued EMV card. See page 251 for a table of the common combinations of methods. Action The processing that the function must perform is specified in the Action request field, as follows:
Value Action
01 02 03 Verify AC only Generate ARPC only Verify AC and Generate ARPC
All fields in the request message are mandatory. Any field not used in a specific function call must be in an appropriate format. That is, fixed length fields must have the required length and variable-length fields must have a valid length. The content in an unused field is ignored, therefore unused variable-length fields can have a length of zero. MK Method The following values of MK Method are supported:
Value Implementation
00 01 Value 00 Common SECCOS
Reference
[1-8] [34]
Field Content
PAN Data
MK Data is a variable-length field that contains the concatenation of the PAN and PAN Sequence Number. The function processing of the MK Data to form an 8-byte field is, in summary, as follows:
Length
<16 digits =16 digits >16 digits Value 01
Processing
Left-padded with zeros. Used as is. Hashed and decimalized.
Field Content
CID
SafeNet, Inc.
249
AC Key Method
Value Implementation
00 01 02 03 04 Value 00 SKAC = MKAC SKD function using ATC and UN Tree of keys using ATC, IV, H and b Tree of keys using ATC. Fixed IV, H and b. Xor using ATC
Reference
[39] VSDC 1.3.2 [31], [34] M/Chip 2.1, SECCOS [5] EMV 4.0 [35] EMV 4.1 CCD [37], [38] AEIPS, J/Smart
Field Content
Null
Value 01
Field Content
ATC UN
Value 02
Field Content
ATC IV H B
Value 03
Field Content
ATC
Value 04
Field Content
ATC
AC Method
Reference
[5] EMV [39], [37], [38] VSDC, AEIPS, J/Smart [5], [31], [34] EMV, M/Chip, SECCOS
SafeNet, Inc.
250
Value Implementation
00 01 ARPC Method SKARPC = SKAC SKARPC = MKAC
Reference
All except M/Chip 2.1 [31] M/Chip 2.1
Value Implementation
01 02 Value 00 Method 1 Method 2
Reference
All [35] EMV 4.1
Field Content
ARC
Value 01
Field Content
CSU PAD
Implementatio n
AEIPS EMV 4.0 EMV 4.1 EMV 4.1 CDD J/Smart M/Chips 2.1 SECCOS VSDC 1.3.2
MK
00 00 00 00 00 00 01 00
AC Key
04 02 02, 03 03 04 01 01 00
Methods AC
02 01, 03 01, 03 01, 03 02 03 03 02
ARPC Key
00 00 00 00 00 01 00 00 (or 01)
ARPC
01 01 01, 02 02 01 01 01 01
int EFT_EE2018_EMV_VerifyAC_GenerateARPC( IN UCHAR FM, IN UCHAR Action, IN KEYSPEC *IMK_AC, IN UCHAR MK_Method, IN EFTBUFFER *MK_Data,
SafeNet, Inc.
251
Chapter 19 EMV Functions UCHAR EFTBUFFER UCHAR EFTBUFFER UCHAR UCHAR EFTBUFFER UCHAR EFTBUFFER EFTBUFFER AC_Key_Method, *AC_Key_Data, AC_Method, *AC_Data, AC[8], ARPC_Key_Method, *ARPC_Key_Data, ARPC_Method, *ARPC_Data, *ARPC);
IN IN IN IN IN IN IN IN IN _OUT
SafeNet, Inc.
252
EMV_AC_GEN_MULTI
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
D D U D D
Attribute h h K-Spec h h
Description Function Code Function Modifier = 00 Key specifier for IMKAC (Formats: 0 - 3, 11, 13) 00 = Common = SECCOS. 01
Data used with IMKAC to derive MKAC. The contents of this field are dependent on the value of MK Method. AC Key Method = 00 04 Data used with MKAC to derive the session key SKAC. The contents of this field are dependent on the value of AC Key Method. AC Method = 00 03, see page 250 Data on which the AC is calculated. Description Function Code Return Code Application Cryptogram ARQC, TC or AAC.
1 Var
h h
1 Var Length 3 1 8
h h Attribute h h h
This function generates an Application Cryptogram (AC). The AC can be an ARQC, a TC or an AAC. The function is sufficiently flexible to meet the AC Generation requirements of all processing variations used in different EMV implementations. The function therefore supports several methods in each processing step. Each step involves a key, a method and some data, where the specific method determines the format of the related data. In the first step an initial key is provided in a key specifier, but subsequent steps use a key from a previous step. The function treats each processing step independently, so does not treat any combination of methods as invalid. However many combinations of methods would not coincide with the processing performed by any issued EMV card.
MK Method
Value Implementation
00 01 Common SECCOS
Reference
[1-8] [34]
SafeNet, Inc.
253
Value 00
Field Content
PAN Data
MK Data is a variable-length field that contains the concatenation of the PAN and PAN Sequence Number. The function processing of the MK Data to form an 8-byte field is, in summary, as follows:
Length
<16 digits =16 digits >16 digits Value 01
Processing
Left-padded with zeros. Used as is. Hashed and decimalized.
Field Content
CID
AC Key Method
Value Implementation
00 01 02 03 04 SKAC = MKAC SKD function using ATC and UN Tree of keys using ATC, IV, H and b Tree of keys using ATC. Fixed IV, H and b. Xor using ATC
Reference
[39] VSDC 1.3.2 [31], [34] M/Chip 2.1, SECCOS [5] EMV 4.0 [35] EMV 4.1 CCD [37], [38] AEIPS, J/Smart
Value 00
Field Content
Null
Value 01
Field Content
ATC UN
Value 02
Field Content
ATC IV H
SafeNet, Inc.
254
Value 03
Field Content
ATC
Value 04
Field Content
ATC
AC Method
Reference
[5], EMV [39], [37], [38] VSDC, AEIPS, J/Smart [5], [31], [34] EMV, M/Chip, SECCOS
03
MK 00 00 00 00 00 00 01 00
SafeNet, Inc.
255
int EFT_EE2019_ EMV_AC_Generate_MULTI ( IN UCHAR FM, IN KEYSPEC *IMK_AC, IN UCHAR MK_Method, IN EFTBUFFER *MK_Data, IN UCHAR AC_Key_Method, IN EFTBUFFER *AC_Key_Data, IN UCHAR AC_Method, IN EFTBUFFER *AC_Data _OUT UCHAR AC[8] );
SafeNet, Inc.
256
EMV_SCRIPT_CRYPTO_MULTI
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
U D U D U
Length 3 1 1
Attribute h h h
Description Function Code Function Modifier = 00 Select Code 01 = Encrypt Command Data Only 02 = Calculate MAC for entire command 03 = Encrypt and Calculate MAC Key specifier for IMKSMI (Formats: 0 - 3, 11, 13) Key specifier for IMKSMC (Formats: 0 - 3, 11, 13) 00 = Common 01 = SECCOS. Data used with IMKSMx to derive MKSMx. The contents of this field are dependent on the value of MK Method. SM Key Method = 02 05 Data used with MKSMx to derive the session key SKSMx. The contents of this field are dependent on the value of SM Key Method. Encryption mode. Plain text data. Offset Script Data to be sent to ICC (multiple of 8 bytes) Description Function Code Return Code Encrypted data. Message Authentication Code calculated using SKSMI.
K-Spec K-Spec h h
1 Var
h h
h h h h Attribute h h h h
This function is a combination of functions EE2019 and EF2013. This function performs the cryptographic processing required for Secure Messaging, i.e. message authentication and / or message encryption. It is intended to be used to either: (i) just encrypt the command data; (ii) just calculate a MAC for the command header and command data; or (iii) both
SafeNet, Inc.
257
encrypt the command data and calculate a MAC for the command header and encrypted command data. The subscript SMx is used to denote both SMI and SMC. FM SC =00. Identifies the required processing: 1: encrypt command data only in Text field 2: calculate a MAC for the entire command Script-Data field. 3: Combine 1 and 2, i.e. encrypt the command data, insert the resultant cipher text into the Script-Data field and calculate a MAC. Key specifier which provides access to the IMKSMI. Formats 0 - 3, and 11, 13 accepted. Note: When SC = 01, this field is not used; it must be a valid variable-length field but its data portion will not be checked to contain a valid key specifier. Key specifier which provides access to the IMKSMC. Formats 0 - 3, and 11, 13 accepted. Note: When SC = 02, this field is not used; it must be a valid variable-length field but its data portion will not be checked for containing a valid key specifier. Methods are Supported for deriving the ICC Master Keys.(MKsmx) 00=Common ; 01=SECCOS. Data used with IMKSMx to derive MKSMx. The contents of this field are dependent on the value of MK Method. Methods exist for deriving a Session Key(SKsmx) from the MKsmx. Data used with MKSMx to derive the session key SKSMx. The contents of this field are dependent on the value of SM Key Method. Encryption Mode. 00=ECB; 01=CBC. Script Command Data that is included in the sent Script to ICC. (Length must be a multiple of 8.) For SC = 3, points to the start byte in Script-Data where the encrypted Text will be copied. An Offset of zero points to the start of Script-Data. This field is big endian. i.e. the byte order in this field is most significant byte first. Script-Data Script Data is sent to ICC. (Length must be a multiple of 8). The script data length must be greater then or equal to the sum of offset and the length of encrypted New PIN data. Encrypted text in a variable length field. This is the same length as the specified input Text field. it is a standard Var field. Message authentication code.
IMKSMI Spec
IMKSMC Spec
Script-Data
eSKSMC(Text) MAC
This function returns zero when completing successfully, otherwise an error is returned. Please refer to Appendix J Error Codes for a complete listing of return code The function is sufficiently flexible to meet the requirements of all processing variations used in different EMV implementations. The function therefore supports several methods in each processing step. Each step involves a key, a method and some data, where the specific method determines the format of the related data. In the first step an initial key is provided in a key specifier, but subsequent steps use a key from a previous step. The function treats each processing step independently, so does not treat any combination of methods as invalid. However many combinations of methods would not coincide with the
SafeNet, Inc.
258
processing performed by any issued EMV card. See page 255 for a table of the common combinations of methods. Select code(SC) The processing that the function must perform is specified in the SC request field, as follows:
Value Process
01 02 03 encrypt command data only in Text field calculate a MAC for the entire command ScriptData field. Combine 1 and 2, i. e. , encrypt the command data, insert the resultant cipher text into the Script-Data field and calculate a MAC.
All fields in the request message are mandatory. Any field not used in a specific function call must be in an appropriate format. That is, fixed length fields must have the required length and variable-length fields must have a valid length. The content in an unused field is ignored, therefore unused variable-length fields can have a length of zero. If SC is 1 then IMKsmi is not used . If SC is 2 then IMKsmc is not used. MK Method The following values of MK Method are supported:
Value Implementation
00 01 Value 00 Common SECCOS
Reference
[1-8] [34]
Field Content
PAN Data
MK Data is a variable-length field that contains the concatenation of the PAN and PAN Sequence Number. The function processing of the MK Data to form an 8-byte field is, in summary, as follows:
Length
<16 digits =16 digits >16 digits Value 01
Processing
Left-padded with zeros. Used as is. Hashed and decimalized.
Field Content
CID
SM Key Method
Value Implementation
02 Tree of keys using ATC, IV, H and b
Reference
[5] EMV 4.0
SafeNet, Inc.
259
03 04 05
Tree of keys using ATC. Fixed IV, H and b. Xor using ATC SKD Function
[35] EMV 4.1 CCD [37], [38], [39] AEIPS, J/Smart, VSDC [34] SECCOS
SM Key Data is a variable-length field that contains zero or more fields incorporating the data required by the specific SM Key methods. Value 02
Field Content
ATC IV H b
The SM Key Data length is 20. SKSMx is derived from MKSMx and ATC using the parameters IV, H and b, as described in clause A1.3.1 of [5]. Value 03
Field Content
ATC
The SM Key Data length is 2. SKSMx is derived from MKSMx and ATC using the parameters IV, H and b, as described in clause A1.3.1 of [35]. The values of IV, H and b are fixed as required by CCD as described in Part IV of [35]. Value 04
Field Content
ATC
The SM Key Data length is 2. SKSMx is derived from MKSMx and ATC using an exclusive-OR operation, as described in clause 6.2.4.2 of [38]. Value 05
Field Content
R
The SM Key Data length is 8. The random number (R) is combined with MKSMx to form SKSMx as described in clauses 2.7.2 and 2.8 of [7]. The identical transformation is also described in the SECCOS specifications [34] and in the EMVCo Bulletin No 46 [36]. Note: Method 05 is similar to method 01 (in EE2019) but is more flexible.
SafeNet, Inc.
260
Processing steps 1. If Select Code is 1 or 3, derive the ICC MAC Master Key (MKSMC) using the Issuer Master Key (IMKSMC) and MK Data according to method specified in MK Method. 2. Derive the ICC MAC Session Key (SKSMC) using the derived MKSMC,SM Key Data according to the method specified in SM Key Method. 3. If Select Code is 2 or 3, derive the ICC Encipherment Master Key (MKSMI) using the Issuer Master Key (IMKSMI) and MK Data, according to the method specified in MK Method. 4. Derive the ICC Encipherment Session Key (SKSMI) using the derived MKSMI, SM Key Data according to the method specified in SM Key Method. 5. If Select Code is 1 or 3, encrypt Text using SKSMC according to the encryption mode of operation specified in Encryption Mode. If Select Code is 3, insert the resulting cipher text in Script-Data at the position specified by Offset. 6. If Select Code is 2 or 3, calculate the MAC for Script-Data using SKSMI.
MK
AC 01 00 00 or 01 00 or 01 00 or 01 01
FM, SC, *IMK_SMI, *IMK_SMC, MK_Method, *MK_Data, SM_Key_Method, *SM_Key_Data, SM_method, *Text, Offset, *Script_Data, *eSMC_Text, MAC[8]);
SafeNet, Inc.
261
EMV_PIN_CHANGE_UNBLOCK_MULTI
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
U D U U U
Length 3 1 1
Attribute h h h
K-Spec K-Spec h h
Description Function Code Function Modifier = 00 Select Code 02 = PIN Unblock only 03 = PIN Change Key specifier for IMKSMI (Formats: 0 - 3, 11, 13) Key specifier for IMKSMC (Formats: 0 - 3, 11, 13) 00 = Common 01 = SECCOS. Data used with IMKSMx to derive MKSMx. The contents of this field are dependent on the value of MK Method. SM Key Method = 02 05 Data used with MKSMx to derive the session key SKSMx. The contents of this field are dependent on the value of SM Key Method. PIN formatting method = 01, 02, 11, 12. PIN formatting data (Formats: 10, 11, 13) PIN confidentiality method 00 = ECB 01 = CBC PIN confidentiality data Zero-length field. PIN integrity method 00 = Default PIN integrity data Description Function Code Return Code Encrypted New PIN data Message Authentication Code
1 Var
h h
1 Var 1
h h h
PC Data PI Method PI Data Response Content EE2021 Rc New PIN data MAC
h h h Attribute h h h h
This function is a combination of the designs of functions EE2019 and EE2017, using the approach to key derivation from the former with modifications as appropriate, and the encryption / MAC fields specific to PIN Unblock/Change from the latter.
SafeNet, Inc.
262
The subscript SMx is used to denote both SMI and SMC. FM SC =00. Identifies the required processing: 2: PIN Unblock only. 3: PIN Change Key specifier which provides access to the IMKSMI. Formats 0 - 3, and 11, 13 accepted. Key specifier which provides access to the IMKSMC. Formats 0 - 3, and 11, 13 accepted. Note: When SC = 02, this field is not used; it must be a valid variable-length field but its data portion will not be checked for containing a valid key specifier. Methods are supported for deriving the ICC Master Keys. (MKsmx) 00=Common; 01=SECCOS. Data used with IMKSMx to derive MKSMx. The contents of this field are dependent on the value of MK Method. Methods exist for deriving a Session Key (SKsmx) from the MKsmx. Data used with MKSMx to derive the session key SKSMx. The contents of this field are dependent on the value of SM Key Method. Methods exist for creating the cleartext PIN block. it is a variable-length field that contains zero or more fields incorporating the data required by the specific PF Method. PIN confidentiality data. Encrypt the cleartext PIN block using SKSMC to generate the Encrypted New PIN data. 00=ECB; 01=CBC. Zero-length field (for Future use). PIN integrity method. Just support one method for calculating MAC using SKSMI. 00 = Default. it is a variable-length field incorporating the data required by the specific PI method. Encrypted New PIN Data. It is formatted as a standard Var field. This field is only present when SC = 03. Message authentication code.
Note: When SC =02 then fields IMKSMC Spec , PF Method, PF Data, PC Method is not used ; they must have a valid length field but there data portion will not be checked . This function returns zero when completing successfully, otherwise an error is returned. Please refer to Appendix J Error Codes for a complete listing of return code The function is sufficiently flexible to meet the requirements of all processing variations used in different EMV implementations. The function therefore supports several methods in each processing step. Each step involves a key, a method and some data, where the specific method determines the format of the related data. In the first step an initial key is provided in a key specifier, but subsequent steps use a key from a previous step. The function treats each processing step independently, so does not treat any combination of methods as invalid. However many combinations of methods would not coincide with the processing performed by any issued EMV card. See page 260 for a table of the common combinations of methods.
SafeNet, Inc.
263
PF Method
Value Implementation
01 02 11 13 PF Data Value 01 and 02 ISO-1 ISO-2 delta PIN with UDK-A ISO-0 with UDK-A
Reference
[40] [7], [40] [37], [38], [39] [37], [38], [39]
It is a variable-length field that contains zero or more fields incorporating the data required by the specific PF methods.
Field Content
ePPK(PIN) PPK
PF ANB
1 6
h d
The method to create cleartext PIN block is : Obtain PPK using PPK. Decrypt ePPK (PIN) using PPK to obtain cleartext ISO-0 or ISO-3 PIN block. Extract PIN from cleartext PIN block using PF and ANB. Create a cleartext ISO-1 or ISO-2 PIN block. Value 11
Field Content
ePPK(PIN1) ePPK(PIN2) PPK
PF ANB IMKAC
1 6 Var
h d K-Spec
The method to create Delta PIN is : Obtain PPK using PPK. Decrypt ePPK(PIN1) using PPK to obtain cleartext ISO-0 or ISO-3 PIN block Extract current PIN from cleartext PIN block using PF and ANB. Decrypt ePPK (PIN2) using PPK to obtain cleartext ISO-0 or ISO-3 PIN block. Extract new PIN from cleartext PIN block using PF and ANB. Derive MKAC (i.e. UDK-A) using IMKAC, MK method and MK Data.
Calculate delta PIN using current PIN, new PIN and UDK-A as described in clause C.11.1 of [39].
SafeNet, Inc.
264
Value 12
Field Content
ePPK(PIN) PPK
PF ANB IMKAC
1 6 Var
h d K-Spec
The method to create ISO-0 PIN block is : Obtain PPK using PPK. Decrypt ePPK (PIN) using PPK to obtain cleartext ISO-0 or ISO-3 PIN block. Extract new PIN from cleartext PIN block using PF and ANB. Derive MKAC (i.e. UDK-A) using IMKAC, MK method and MK Data. Create a cleartext ISO-0 PIN block using the PIN and UDK -A as described in clause C.11.2 of [39].
PI Method
Value Method
00 PI Data Default
Reference
It is a variable-length field that contains zero or more fields incorporating the data required by the specific PI method.
Value 00
Field Content
Script-Data Position Script-Data
Script-Data Position
For SC = 03, this points to the start byte in Script-Data where the encrypted New PIN data will be copied. A Script-Data Position of zero points to the start of Script-Data. This field is big Endean. Used to calculate the MAC. If the last (or only) data Block is less than 8 bytes it is padded to the right with a hexadecimal 80. If this data Block is still less than 8 bytes it is right filled with 1 byte hexadecimal zeros until it is 8 bytes. The script data length must be greater then or equal to the sum of offset and the length of encrypted New PIN data.
Script-Data
Processing steps 1. If Select Code is 03, derive the ICC MAC Master Key (MKSMC) using the Issuer Master Key (IMKSMC) and MK Data according to method specified in MK Method.
SafeNet, Inc.
265
2. 3. 4. 5. 6.
7.
Derive the ICC MAC Session Key (SKSMC) using the derived MKSMC, SM Key Data according to the method specified in SM Key Method. Derive the ICC Encipherment Master Key (MKSMI) using the Issuer Master Key (IMKSMI) and MK Data, according to the method specified in MK Method. Derive the ICC Encipherment Session Key (SKSMI) using the derived MKSMI, SM Key Data according to the method specified in SM Key Method. If Select Code is 3, create the cleartext PIN block according to the method specified in PF Method. If Select Code is 3, encrypt cleartext PIN block using SKSMC according to the encryption mode of operation specified in PC Method. If Select Code is 3, insert the resulting cipher text in Script-Data (PI Data) at the position specified by Script-Data Position (PI Data). Calculate the MAC for Script-Data using SKSMI. Steps 1-4 is same as in EE2020 (EMV_SCRIPT_CRYPTO_MULTI)
MK 00 00 00 00 00 00 00 00 01 00
SafeNet, Inc.
266
SafeNet, Inc.
267
VCEPS_VER_S1_GEN_S2
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
D D U D D
Length 3 1 Var
Attribute h h K-Spec
Description Function Code Function Modifier = 00 Key specifier for Master Derivation Key (KML or KMX). (Formats: 0 - 3) Serial number of the CEP card Transaction number from the CEP card MAC calculated by CEP card Data used in the calculation of S1 Must be a multiple of 8 bytes Data used in the calculation of S2 Must be a multiple of 8 bytes Description Function Code Return Code MAC to send to CEP card
h h h h h Attribute h h h
This function verifies the S1 MAC produced by the CEP card and generates the S2 MAC for sending to the CEP card. Processing steps 1. Derive the card's diversified key (KDL or KDX) using the Master Derivation Key and IDCEP, according to the method specified in 3.5.1 of reference [12] of MarkII. 2. Derive the card Session Key (SK) using the card's diversified key and NTCEP, according to the method specified in 5.1.2 of reference [12] of MarkII. 3. Calculate the S1 MAC using SK and the data provided in S1 Data, according to the method specified in 5.1.3 of reference [12] of MarkII. 4. Compare the values of the calculated S1 and that supplied in S1. If the values are not identical, fail with the appropriate error code. 5. Calculate the S2 MAC using SK and the data provided in S2 Data, according to the method specified in 5.1.3 of reference [12] of MarkII. Return the result in S2. Function usage The function is used for Load / Unload and Currency Exchange authorization transactions. SHP Toolkit MK2 int EFT_EF0701_VcepsVerS1GenS2( IN UCHAR FM, IN KEYSPEC *KMx, IN UCHAR IDcep[6], IN UCHAR NTcep[2], IN UCHAR MAC_S1[8], IN EFTBUFFER *S1_Data, IN EFTBUFFER *S2_Data, OUT UCHAR MAC_S2[8]);
SafeNet, Inc.
268
VCEPS_VER_SN
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
D D U D D
Length 3 1 Var
Attribute h h K-Spec
Description Function Code Function Modifier = 00 Key specifier for Master Derivation Key (KM3L, KM3X or KMP). (Formats: 0 - 3) Data used in the calculation of the derived key. (0 or 2 - 6 bytes) Data used in the calculation of the session key. (0 or 2 - 6 bytes) MAC calculated by CEP card. Data used in the calculation of Sn Must be a multiple of 8 bytes Description Function Code Return Code
h h h h Attribute h h
This function verifies a MAC produced by the CEP card or PSAM. Processing steps 1. Derive the diversified key (KD3L, KD3X, KDP, etc) using the Master Derivation Key and Derivation Data. To derive the left half of the diversified key, Derivation Data is left-justified in an 8-byte data Block and padded to the right with 'F0' and sufficient '00' bytes to fill the Block. The data Block is then encrypted with the Master Derivation Key; the result is the left half of the diversified key. To derive the right half of the diversified key, Derivation Data is left-justified in an 8-byte data Block and padded to the right with '0F' and sufficient '00' bytes to fill the Block. The data Block is then encrypted with the Master Derivation Key; the result is the right half of the diversified key. 2. If Session Key Data has a length of zero, use the diversified key directly as the Session Key (SK) otherwise derive the SK using the diversified key and Session Key Data. To derive the left half of the session key, Session key Data is left-justified in an 8-byte data Block and padded to the right with 'F0' and sufficient '00' bytes to fill the Block. The data Block is then encrypted with the diversified key; the result is the left half of the session key. To derive the right half of the session key, Session Key Data is left-justified in an 8-byte data Block and padded to the right with '0F' and sufficient '00' bytes to fill the Block. The data Block is then encrypted with the diversified key; the result is the right half of the session key. 3. Calculate the Sn MAC using SK and the data provided in Sn Data, according to the method specified in 5.1.3 of reference [12] of MarkII. 4. Compare the values of the calculated Sn and that supplied in Sn.
SafeNet, Inc.
269
Function usage The function may be used to verify: S3 S4 S5 S6 S6' S6'' Note S6'' is named SIB in the VCEPS document [14].
SHP Toolkit MK2 int EFT_EF0702_VcepsVerSn( IN UCHAR FM, IN KEYSPEC *KMx, IN EFTBUFFER *Deriv_Data, IN EFTBUFFER *Session_Data, IN UCHAR MAC_Sn[8], IN EFTBUFFER *Sn_Data);
SafeNet, Inc.
270
VCEPS_GEN_SN
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
D D U D D
Length 3 1 Var
Attribute h h K-Spec
Description Function Code Function Modifier = 00 Key specifier for Master Derivation Key (KMx). (Formats: 0 - 3) Data used in the calculation of the derived key. (0 or 2 - 6 bytes) Data used in the calculation of the session key. (0 or 2 - 6 bytes) Data used in the calculation of Sn. Must be a multiple of 8 bytes Description Function Code Return Code MAC to send to CEP card
h h h Attribute h h h
This function generates a MAC to send to the CEP card. Processing steps 1. Derive the diversified key using the Master Derivation Key and Derivation Data, according to the method specified above in Verify Sn, step 1. 2. Derive the card Session Key (SK) using the diversified key and Session Key Data according to the method specified above in Verify Sn, step 2. 3. Calculate the Sn MA, reference [12] of MarkII. Return the result in Sn. Function usage The function could be used generate any Sn MAC, e.g. for testing purposes.
SHP Toolkit MK2 int EFT_EF0703_VcepsGenSn( IN UCHAR FM, IN KEYSPEC *KMx, IN EFTBUFFER *Deriv_Data, IN EFTBUFFER *Session_Data, IN EFTBUFFER *Sn_Data, OUT UCHAR MAC_Sn[8]);
SafeNet, Inc.
271
VCEPS_MAC_VER_LSAM
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
D D U D D
Request Content EF0704 FM LSAMK-Spec eLSAMK(R1) MACLSAM Data Response Content EF0704 rc
Description Function Code Function Modifier = 00 Key specifier for LSAM (Format: 11, 13) ECB encrypted MAC key. MAC created by LSAM. Data included in MAC calculation. Must be a multiple of 8 bytes Description Function Code Return Code
This function verifies the MAC calculated by the LSAM. The LSAM key that encrypts R1 (the MAC key) is provided in an encrypted form, encrypted by Variant 5 of KM. Processing steps 1. Recover the MAC key, R1 2. Calculate a MAC for Data, according to the method specified in 5.1.3 of reference [12] of MarkII. 3. Compare the calculated MAC with MACLSAM and return the result Function usage The function can be used when function Generate LSAM Key is used to generate the LSAM key.
SHP Toolkit MK2 int EFT_EF0704_VcepsSMacVerLSam( IN UCHAR FM, IN KEYSPEC *LSAMK, IN UCHAR eLSAMK_R1[16], IN UCHAR MAC[4], IN EFTBUFFER *Data);
SafeNet, Inc.
272
VCEPS_GEN_HASH_CEP
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
D D U D D
Length 3 1 Var
Attribute h h K-Spec
Description Function Code Function Modifier = 00 Key specifier for Master Derivation Key (KML). (Formats: 0 - 3) Serial number of the CEP card Data used in the calculation of HCEP Description Function Code Return Code Leftmost 80 bits of hash result.
6 Var Length 3 1 10
h h Attribute h h h
This function calculates RCEP, appends it to the hash data, then calculates and returns the hash result, HCEP. Processing steps 1. Derive the card's diversified key (KDL) using the Master Derivation Key and IDCEP, according to the method specified in 3.5.1 of reference [12] of MarkII. 2. Calculate RCEP using KDL, according to the method specified in 3.6.1 of reference [12] of MarkII. Note: The NETS document indicates that a OWF2(KDLcep. NTcep) is used to calculate RCEP. This differs from the above. 3. Append RCEP to Hash Data, and use the resulting string to calculate HCEP according to the method specified in 3.6.1 of reference [12] of MarkII.
SHP Toolkit MK2 int EFT_EF0F01_VcepsGenHashCep( IN UCHAR FM, IN KEYSPEC *KMx, IN UCHAR IDcep[6], IN EFTBUFFER *Hash_Data, OUT UCHAR Hcep[10]);
SafeNet, Inc.
273
SafeNet, Inc.
274
SafeNet, Inc.
275
GETPUBLICKEY
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
D D U D D
Request Content EE3030 FM PK-Spec Response Content EE3030 rc n PVC(PKi HSM) PKi HSM
Description Function Code Function Modifier = 00 Key specifier for HSM Public key pair. (Formats: 0 - 3) Description Function Code Return Code Length of PK HSM as in number of 8 byte Blocks within the modulus Verification Code Key specifier for HSM stored public key (Format: 80)
This function returns an HSM stored public key and its PVC. SHP Toolkit MK2 int EFT_EE3030_GetPublicKey( IN UCHAR FM, IN KEYSPEC *PK, OUT OUT OUT UCHAR UCHAR KEYSPEC *ModLen, PVC_PKI_HSM[20], *PKI_HSM);
SafeNet, Inc.
276
KIS_SEND
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
D D U D U
Request Content EE3031 FM SK-Spec PKr Response Content EE3031 rc KIS-Spec sSKs HSM(hash of key data) ePKr(KIS) KVC(KIS)
Description Function Code Function Modifier = 00 Key specifier for Index to SK HSM (Formats: 0 - 3) Receivers public Key (Format: 80) Description Function Code Return Code Key specifier for KIS (Format: 15) Signed hash of KIS Enciphered KIS Key Verification Code of KIS
This function generates a random interchange sending key (KIS) and prepares it for transfer to another HSM. The function signs the generated KIS under a HSM private key (SK HSM s) and enciphers it under the public key (PKr) provided by the intended receiver of the KIS. The function also returns the KIS in a key specifier.
NOTE
The KIS spec Format 15 must contain the attributes specific to AS2805.6.3 2000. SHP Toolkit MK2
int EFT_EE3031_KisSend IN UCHAR IN KEYSPEC IN KEYSPEC OUT OUT OUT KEYSPEC EFTBUFFER EFTBUFFER
OUT
UCHAR
KVC_KIS[3] );
SafeNet, Inc.
277
KIR_REC
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
D D U D U
Request Content EE3032 FM SK-Spec sSKs HSM(hash of key data) ePKr HSM(KIR) PKs-Spec Response Content EE3032 rc KIR-Spec KVC(KIR)
Description Function Code Function Modifier = 00 Key specifier for Index to SK HSM. (Formats: 0 - 3) Signed hash of KIR Enciphered KIR Key specifier for Senders Public Key (Format: 80) Description Function Code Return Code Key specifier for KIR (Format: 15) Verification Code of KIR
This function recovers an Interchange Key, which has been transferred from another HSM as part of the Interchange Sending Key transfer procedure. The recovered key is used and denoted as an Interchange Key (KIR). The KIR is transferred in a DEA 2 cipher text Block as produced by the KIS-SEND function and deciphers this result. The function returns KIR in a key specifier.
NOTE
The KIR spec Format 15 must contain the attributes specific to AS2805.6.3 2000. SHP Toolkit MK2 int EFT_EE3032_KirRec ( IN UCHAR FM, IN KEYSPEC *SK, IN EFTBUFFER *Signed_Hash, IN EFTBUFFER *ePKr_KIR, IN KEYSPEC *PK, OUT OUT KEYSPEC UCHAR *KIR, KVC_KIR [3] );
SafeNet, Inc.
278
NODEPROOF
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
D D U D U
Length 3 1 1
Attribute h h h
Description Function Code Function Modifier = 00 Output length required 01 = 64 bits 02 = 128 bits Key specifier for KIS (Formats 0 - 3, 15) Description Function Code Return Code Encrypted Random Number Encrypted Inverted Random Number.
K-Spec Attribute h x h h
This function generates the random number to be forwarded to the remote node as part of the internodal proof-of-endpoint processing. The Random Number (RNs) is inverted to form RNr. RNs and RNr are returned to the host enciphered by the KIS.
NOTE
The Random Number is not adjusted for parity The length of the response random numbers can be determined from the Var field header. The encryption mode is CBC with an IV of zero. When Format 15 is used for the KIS-Spec, it must contain the attributes specific to AS2805.6.3 2000. When formats 00 03 are used for the KIS-Spec, the HSM stored KIS must be a double length key with the variant scheme AS2805 1985 selected.
SHP Toolkit MK2 int EFT_EE3033_NodeProof( IN UCHAR FM, IN UCHAR len, IN KEYSPEC *KIS, OUT OUT EFTBUFFER EFTBUFFER *eKISv82_RNs, *eKISv84_RNr);
SafeNet, Inc.
279
NODERESP
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
D D U D U
Description Function Code Function Modifier = 00 Key specifier for KIR (Formats: 0 - 3, 15) Encrypted Random Number Description Function Code Return Code Encrypted Random Number Inverted
This function performs the response part of the internodal proof-of-endpoint processing. The function deciphers a number (RNs) using the KIR in the request. RNr is formed by inverting RNs and is returned enciphered under KIR.
NOTE
Encryption mode is CBC for B128 length. The length of the response random numbers can be determined from the Var field header. When Format 15 is used for the KIR-Spec, it must contain the attributes specific to AS2805.6.3 2000. When formats 00 03 are used for the KIR-Spec, the HSM stored KIR must be a double length key with the variant scheme AS2805 selected.
SHP Toolkit MK2 int EFT_EE3034_NodeResp( IN UCHAR IN KEYSPEC IN EFTBUFFER OUT EFTBUFFER
SafeNet, Inc.
280
SafeNet, Inc.
281
GEN_TERMINAL_KEY
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
D D U D U
Length 3 1 Var 1 2
Attribute h h K-Spec h h
Description Function Code Function Modifier = x0 Key specifier for KTM (Formats: 0 - 3, 11, 13) 01 = 3DES 03 = HMAC-SHA-1 Number of bits in a key. = 128 = 160 = 192 01 = PPK 02 = MPK Format of key to be distributed 01 = ECB encrypted key 05 = Verifone key Block(GISKE) Format of key specifier for host storage 01 = Encrypted key 02 = Binary key Block(TR-31) 00 = Not required 01 = 3 byte standard KVC A (for GISKE) 2 (for Verifone) 00 (for binary key Block) Valid values are described in the notes following this table. E (Encrypt only) 00 (Null) 00 (for Verifone) 0000 (Null) N (for Verifone) 00 (Null) For DES/3DES only 00 = Do not pad 02 = Pad to double-length 03 = Pad to triple length Always zero (00) Not present Description Function Code Return Code
1 1
h h
1 1
h h
Key Usage Mode of use Key version number Exportability Padding indicator
2 1 2 1 1
h h h h h
1 Var Length 3 1
h h Attribute h h
SafeNet, Inc.
282
Var Var
h K-Spec
KVC
Var
Encrypted key or key Block to send to terminal Key specifier incorporating an encrypted key or a key Block (as indicated by Host key format in the request) Formats: (11, 13, 18) Key Verification Code
This function generates a key for sending to a terminal and is sent KTM encrypted. The generated key can also be sent to a host KM encrypted for storage. A KVC for the generated key may also be requested for the response.
Notes: The key-types 13, 18 under the Response Content, are generated when using the Legacy option. The key-types 11, 13 under the Response Content, are generated based on the chosen operation on console and FM. See section, Function Modifier Values.
The generated key may be provided in simple encrypted form or incorporated in a secure key Block. See Appendix K References, references [25], [26] and [27] for details on secure key Block formats. FM = x0 The Host Key Protection using Function Modifier can be in the range of x0, where x= 0 , 1, or 2. KTM Crypto algorithm The key specifier used to protect the key being generated. Valid values are key specifier formats 0-3, 11 and 13 (3DES only). Identifies the cryptographic algorithm used to generate the key. Valid values are: 01=3DES. May only be used if the specified KTM is a 3DES key 03=HMAC-SHA-1. May only be used if the specified KTM is a 3DES key Specifies the length of the key to be generated. Valid key lengths for each supported algorithm are as follows: 3DES - 128 HMAC-SHA-1 - 128, 160, 192 Key type Specifies the key type. Key types supported for each algorithm are as follows: Algorithm 3DES - PPK, MPK Algorithm HMAC-SHA-1 - MPK Terminal key format Identifies the format in which the key is to be transmitted to the terminal. Valid formats are as follows: 01 - ECB encrypted using a variant of KTM, 05 - Verifone key Block (based on GISKE) Host key format Identifies the format in which the key is to be stored on the host. Formats are as follows: 01 - CBC encrypted using a variant of KM and supports 3DES key only. The key is returned in a format 13 key specifier 02 - binary key Block in a format 18 key specifier KVC format Key verification code standard format
Key length
SafeNet, Inc.
283
Chapter 22 Key Block 2 - for Verifone key Block 00 (Null) - for binary key Block
Version identifier
These fields must be specified to create a secure key Block. Note: Other key Block fields will be created using Algorithm, Key Length and key type host function request fields Valid combinations of these three fields for each key type are as follows:
Key usage M0 P0
N (not exportable) - for Verifone key Block 00 (Null) - for Binary key Block
Padding indicator
For DES/3DES only , indicates how the encrypted key field (in the key Block) should be padded so that its length is indistinguishable, as follows: 00 - do not pad
These support the optional fields of key Blocks. Currently not implemented.
int EFT_EE0628_ReceiveRolloverSessionKey( IN UCHAR FM, IN KEYSPEC *KTM, IN UCHAR Algorithm, IN UCHAR KeyLen[2], IN UCHAR KeyType, IN UCHAR TerminalKeyFormat, IN UCHAR HostKeyFormat, IN UCHAR KVCFormat, IN UCHAR VerID, IN UCHAR KeyUsage[2], IN UCHAR Mode, IN UCHAR KeyVerNum[2], IN UCHAR Export, IN UCHAR Padding, IN UCHAR NumOptFields, _IN EFTBUFFER *OptField1, _IN EFTBUFFER *OptField2, _IN EFTBUFFER *OptField3, _IN EFTBUFFER *OptField4, _IN EFTBUFFER *OptField5, _IN EFTBUFFER *OptField6, _IN EFTBUFFER *OptField7, _IN EFTBUFFER *OptField8, _IN EFTBUFFER *OptField9, _IN EFTBUFFER *OptField10, OUT EFTBUFFER *TerminalKey, OUT KEYSPEC *HostKey, OUT EFTBUFFER *KVC);
SafeNet, Inc.
284
Note: There is only one MK. But there are separate values for the CV and RND data, depending on the type of Session Key (MAC or PAC) - there is a CVMAC and CVPAC and RNDMES and RNDPAC To derive the Session Key using above definitions, the following steps are required: 1. TK1 = XOR (MKLEFT | CVLEFT) 2. TK2 = XOR (MKRIGHT | CVLEFT ) 3. TK3 = XOR (MKLEFT | CVRIGHT) 4. TK4 = XOR (MKRIGHT | CVRIGHT) 5. SKLEFT =d*TK1 | TK2 ( RNDLEFT ) 6. SKRIGHT = d*TK3 | TK4 ( RNDRIGHT ) 7. SK = SKLEFT | SKRIGHT
Pin Verification
PIN verification is performed with the help of two national PIN verification values, PVN 1 and PVN 2, which can be placed on the magnetic stripe of the ec-card instead of offset 1 and offset 2. It's also possible to verify the PIN without using the PVNs on the magnetic stripe if these are stored in a "Positive-File" in the authorization system database. In this case only one PVN is required. Each PVN is generated with the help of a bank specific Master Key *KKBLZ, which is valid for a particular area and card specific data. Within this BLZ area customer account numbers are
SafeNet, Inc.
285
unique and multiple cards per account are identifiable via the card sequence number. The keys can be changed depending on the card's expiration year so that a compromise of this key is restricted in time (1 year) and scope (this bank). PVN is calculated as follows: PVN = e* KKBLZ (X) The value X is formed as follows: All values are encoded in binary form. The 10-digit account number is binary encoded. At maximum, 34 bits are required. In the case of less than 34 effective bits, leading zeroes are pre-pended.
Example: The binary representation of the 10-digit account number 8589939303 is: 10 00000000 00000000 00010010 01100111 The card sequence number can be encoded by 4 bits. A leading zero bit may be pre-pended. Example: The card sequence number 7 is represented in binary as follows: 0111 The PIN length is encoded by 2 bits: Length 4: 00 Length 5: 01 Length 6: 10 The last digit of the expiration year of the card is encoded by 4 bits (the same as the card sequence number) Example: The 8 in the expiration year 1998 is encoded as: 1000 The PIN is interpreted as a maximum 6-digit number and can be represented in binary by a maximum of 20 bits. Example: The 6-digit PIN 291255 is encoded as follows: 0100 01110001 10110111 In their binary representation, 4-digit PINs are pre-pended with leading zeroes. The 64-bit value X is formed by the concatenation of the bits. PIN length | Account Number | Card Sequence Number | Last Digit Expiration Year | PIN For the above example the 64-bit value of X is: 10|10 0000 0000 0000 0000 0001 0010 0110 0111| 0111|1000|0100 0111 0001 1011 0111 Field PIN Length Account Number Card Sequence Number Length 2 bits 34 bits 4 bits Raw Value 4 8589939303 7 Converted Value 10 10 0000 0000 0000 0000 0001 0010 0110 0111 0111
SafeNet, Inc.
286
4 bits 20 bits
8 291255
X contains unique account number information and the PIN, so that the verification value within the validity scope of the key *KKBLZ cannot be compromised. For larger banking organizations with several branch and BLZ areas, identical account numbers for several areas may occur. In this case it is not permitted to use only one key for PIN verification for all areas of the bank. As the account numbers within a specific BLZ area are unique, a unique key *KKBLZ has to be selected for each BLZ area. If for organizational reasons, it isn't desirable to generate these keys independently of each other, they can be derived by means of a Master Key. For calculation of *KKBLZ two Master Keys *KGKBank 1 and *KGK Bank 2 are selected by a random process. A Triple-DES key *KKBLZ is calculated for the desired BLZ area of the bank institution as follows: e*KGKBank 1 (BLZ | BLZ) = *KKBLZ 1 e*KGKBank 2 (BLZ | BLZ) = *KKBLZ 2 and it is *KKBLZ = *KKBLZ1 | *KK BLZ 2 Decimalization is achieved as follows: I = 1; FOR j = 1 TO 16; IF Cj .{0,,9} THEN { PVN [I] = Cj; i = I + 1} ; IF I == 5 THEN pvn_ok ( ) NEXT j ; FOR j = 1 to 16; IF Cj .{A,B,C,D,E,F} THEN { PVN [i] = Cj - 10; i = i + 1} ; IF i = = 5 THEN pvn_ok ( ) NEXT j
SafeNet, Inc.
287
ZKA-IMPORT-MK
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
D D D D U
Request Content EE0210 FM e*KTK(K) *KTK-Spec Encryption Mode (of e*KTK(K)) Key Type
Length 3 1 16 Var 1 1
Attribute h h h K-Spec h h
Description Function Code Function Modifier = x0 Encrypted Key Key specifier for KTK (Formats: 0 - 3) 00 = ECB 01 = CBC 10 = *KGK 11 = *KKBLZ 12 = MK 00 = No check 01 = Standard KVC 02 = MDC-2 Leftmost 6 digits of eMK(0) 16-byte MDC-2 hash Description Function Code Return Code Key specifier containing eKMx(K) Formats: (11, 13)
ICM
H Attribute H H K-Spec
This function translates an ECB- or CBC-encrypted MK to encryption by variant 18. of the Domain Master Key for host storage. It optionally performs an integrity check on the clear MK using the specified method. If the integrity check fails, a return code of 08 results (and the key is not reencrypted).
Notes: The key-type 13 under the Response Content, are generated when using the Legacy option. The key-types 11, 13 under the Response Content, are generated based on the chosen operation on console and FM. See, section Function Modifier Values.
FM
= x0 The Host Key Protection using Function Modifier can be in the range of x0, where x= 0 , 1, or 2.
Is the supplied key encrypted by a Key Transport Key (*KTK). Supports only double-length HSM Mark II-stored keys. (Formats: 0 - 3) Indicates the encryption setting used for the *KTK 00 = ECB Encryption Mode, and 01 = CBC Encryption Mode.
Key Type
Indicates the Key Type and KM variant used to encrypt for Host storage.
SafeNet, Inc.
288
Chapter 23 ZKA Functions The Integrity Check Method - additional integrity check methods will be added later. The Integrity Check Value - This value is set to 00 if the ICM is zero.
int EFT_EE0210_ZKA_IMPORT_MK( IN UCHAR FM, IN UCHAR eKTK_K[16] IN KEYSPEC *KTK, IN UCHAR encMode_KTK, IN UCHAR KeyType, IN UCHAR ICM, IN UCHAR ICV, OUT EFTBUFFER *KSpec)
SafeNet, Inc.
289
ZKA-PIN-TRANS
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
D D D D U
Request Content EE0610 FM ePPKi(PIN) PPKi-Spec PFi ANB PFo MK-Spec Response Content EE0610 Rc ePPKo(PIN) RNDo
Description Function Code Function Modifier = 00 Encrypted PIN Block. Key specifier for PPK In (Formats: 0 - 3, 10, 11, 13, 90) Input PIN Block Format (Formats: 01, 03, 08, 09, 10, 11, 13) Account Number Block Output PIN Block Format (Formats: 01, 03, 08, 10, 11, 13) Key Specifier for ZKA MK (Format: 11, 13) Description Function Code Return Code Encrypted PIN Block Random Number (encrypted session key)
This function performs translation of both the PIN Block format and the PIN encryption key. The input PIN Block is encrypted by a PPKi, which might be a host- or HSM Mark II-stored session key or might be a ZKA-encrypted PAC key (RND). The output PIN Block is encrypted by a session key generated within the function. The session key is also returned in encrypted form (RNDo) FM ePPKi(PIN) PPKi-spec = 00. Must be set to zero. Is the input formatted PIN Block containing the PIN to be verified. It must be supplied encrypted by a PIN Protect session key (PPK). Can be any valid key specifier for a PPK. Consequently, the function supports an encrypted PIN Block encrypted using a single-length or double-length, HSM Mark II-stored or host-stored key or a ZKA terminal random number These respectively specify the format of the supplied PIN Block and of the required PIN Block, as defined for the standard PIN Translate function (includes formats 1, 3, 8, 9, 10, 11 and 13). Note: Restriction is placed on output format 8, PFi 8 PFo8 only. ANB MK-spec ePPKo(PIN) RNDo Account Number Block, which is the rightmost 12 digits of the Primary Account Number (PAN), excluding the check digit. A Host stored (format 13) CBC key specifier incorporating an encrypted ZKA Master Key. Is the output formatted PIN Block containing the PIN to be verified. It must be supplied encrypted by a PIN Protect session key (PPK). Is the encrypted Session Key (Refer Session Key Derivation for details).
SafeNet, Inc.
290
The function will fail with Error Code 78 if Pfi or PFo indicates a PIN block format that is disabled or conflicts with the reformatting restrictions
SHP Toolkit MK2 int EFT_EE0610_ZKA_PIN_Translate( IN IN IN IN IN IN IN UCHAR UCHAR KEYSPEC UCHAR UCHAR UCHAR KEYSPEC FM, ePPKi_PIN[8], *PPKi, PFi, ANB[6], PFo, *MK, ePPKo_PIN[8], RNDo[16]);
SafeNet, Inc.
291
ZKA-PIN-VER
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
D D D D U
Request Content EE0611 FM ePPK(PIN) PPK-Spec PF ANB *KKBLZ-Spec Account Number CSN Expiration Year PVN Type PVN Response Content EE0611 Rc
Description Function Code Function Modifier = 00 Encrypted PIN Block Key specifier for PPK (Formats: 0 - 3, 10, 11, 13, 90) PIN Block Format (Formats: 01, 03, 08, 09, 10, 11, 13) Account Number Block Key specifier for ZKA BLZ (Formats: 0 - 3, 11, 13, 91 ) 10-digit Account Number Card Sequence Number 00 - 09 Last digit only (00 09) PIN Verification Number Type = 00 or 04 PIN Verification Number Description Function Code Return Code
This function performs the verification of a PIN using the ecPVN method. The PIN is supplied in encrypted form, using any of the PIN Block formats supported by the standard product (including ISO formats 0 and 1). FM ePPK(PIN) PPK-spec = 00. Must be set to zero. Is the input formatted PIN Block containing the PIN to be verified. It must be supplied encrypted by a PIN Protect session key (PPK). Can be any valid key specifier for a PPK. Consequently, the function supports an encrypted PIN Block encrypted using a single-length or doublelength, HSM Mark II-stored or host-stored key. Specifies the format of the supplied PIN Block, as defined for the standard PIN Translate function (included formats: 1, 3, 8, 9, 10, 11 and 13). Account Number Block, which is the rightmost 12 digits of the Primary Account Number (PAN), excluding the check digit. Can be any valid key specifier for a *KKBLZ. Consequently, the function supports an encrypted PIN Block encrypted using a single-length HSM Mark II-stored or double-length, HSM Mark II-stored or double length hoststored key. Is the 10 digit Account Number. Is the Card Sequence Number. Is the last digit of the expiry year of the card. 0 = Complete value of X (undecimalized) in PVN. 4 = leftmost 4 digits of decimalize(X) packed in 2 bytes in PVN.
PF ANB *KKBLZ-spec
SafeNet, Inc.
292
Chapter 23 ZKA Functions Is the PIN Verification Number, used to verify the users PIN.
PVN
The function will fail with Error Code 78 if PF indicates a PIN block format that is disabled. SHP Toolkit MK2 int EFT_EE0611_ZKA_PIN_Ver_ecPVN( IN UCHAR FM, IN UCHAR ePPK_PIN[8], IN KEYSPEC *PPK, IN UCHAR PF, IN UCHAR ANB[6], IN KEYSPEC *KK_BLZ, IN UCHAR Account_Number[5], IN UCHAR CSN, IN UCHAR Expiration_Year, IN UCHAR PVN_Type, IN EFTBUFFER *PVN);
SafeNet, Inc.
293
ZKA-CALC-PVN
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
D D D D U
Request Content EE0612 FM ePPK(PIN) PPK-Spec PF ANB *KKBLZ-Spec Account Number CSN Expiration Year PVN Type Response Content EE0612 Rc PVN PINLEN
Description Function Code Function Modifier = 00 Encrypted PIN Block Key specifier for PPK (Formats: 0 - 3, 10, 11, 13, 90) PIN Block Format (Formats: 01, 03, 08, 09, 10, 11, 13) Account Number Block Key specifier for ZKA BLZ (Formats: 0 - 3, 11, 13, 91) 10-digit Account Number Card Sequence Number 00-09 Last digit only (00 - 09) PIN Verification Number Type = 00 or 04 Description Function Code Return Code PIN Verification Number PIN Length
This function calculates the two PVNs for a PIN and also provides the length of the PIN. The PIN is supplied in encrypted form, using any of the standard PIN Block formats specified in the HSM Mark II Programmers Guide. FM ePPK(PIN) PPK-spec = 00. Must be set to zero. Is the input formatted PIN Block containing the PIN to be verified. It must be supplied encrypted by a PIN Protect session key (PPK). Can be any valid key specifier for a PPK. Consequently, the function supports an encrypted PIN Block encrypted using a single-length or doublelength, HSM Mark II-stored or host-stored key. Specifies the format of the supplied PIN Block, as defined for the standard PIN Translate function. (includes formats: 1, 3, 8, 9, 10, 11 and 13). Account Number Block, which is the rightmost 12 digits of the Primary Account Number (PAN), excluding the check digit. Can be any valid key specifier for a *KKBLZ. Consequently, the function supports an encrypted PIN Block encrypted using a single-length HSM Mark II-stored or double-length, HSM Mark II-stored or double length hoststored key. Is a 10 digit Account Number. Is the Card Sequence Number.
PF
ANB *KKBLZ-spec
SafeNet, Inc.
294
Chapter 23 ZKA Functions Is the last digit of the expiry year of the card. 0 = Complete value of X (undecimalized) in PVN. 4 = leftmost 4 digits of decimalize(X) packed in 2 bytes in PVN. Is the returned PIN Verification Number, used to verify the users PIN. Is the returned length of the encrypted PIN.
The function will fail with Error Code 78 if PF indicates a PIN block format that is disabled. SHP Toolkit MK2 int EFT_EE0612_ZKA_PIN_Ver_enc_PIN( IN UCHAR FM, IN UCHAR ePPK_PIN[8], IN KEYSPEC *PPK, IN UCHAR PF, IN UCHAR ANB[6], IN KEYSPEC *KK_BLZ, IN UCHAR Account_Number[5], IN UCHAR CSN, IN UCHAR Expiration_Year, IN UCHAR PVN_Type, OUT EFTBUFFER OUT UCHAR *PVN, *PIN_Length);
SafeNet, Inc.
295
ZKA-PIN-TRANS-1
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
D D D D U
Description Function Code Function Modifier = 00 Encrypted PIN Block. Key specifier for PPK (Formats: 0 - 3, 10, 11, 13, 90) Input PIN Block Format (Formats: 01, 03, 08, 09, 10, 11, 13) Account Number Block Output PIN Block Format (Formats: 01, 03, 08, 09, 10, 11, 13) Key Specifier for ZKA MK2 (Format: 90)* VerNo / GenNo / ExpDate = FFFF9999 Description Function Code Return Code Encrypted PIN Block Random Number (encrypted session key) Key Specifier for ZKA MK2 (Format: 92)
Length 3 1 8 16 Var
Attribute H H H H K-Spec
* When using MK2-spec-1 format 90, ignore the RND field. This function performs translation of both the PIN Block format and the PIN encryption key. It is similar to function ZKA-PIN-TRANSLATE, but derives the output PPK using an MK from the MK2 table. The input PIN Block is encrypted by a PPKi, which might be a host- or HSM Mark II -stored session key or might be a ZKA-encrypted PAC key (RND). The output PIN Block is encrypted by a session key generated within the function. The session key is also returned in encrypted form (RNDo). The function uses MK2-spec-1 to search the MK2 table for the record for Sub-type Number that has the latest Expiry Date. The MK in this record is used to derive the PPKo. The MK2-spec-2 in the response has all fields completed from the MK record used. Pfi and Pfo respectively specify the format of the supplied PIN Block and of the required PIN Block, as defined for the standard PIN Translate function (including ISO formats 0 and 1). Note: Restriction is placed on output format 8, PFi 8 PFo8 only. ANB Account Number Block, which is the rightmost 12 digits of the Primary Account Number (PAN), excluding the check digit.
The function will fail with Error Code 78 if Pfi or PFo indicates a PIN block format that is disabled or conflicts with the reformatting restrictions.
SafeNet, Inc.
296
SHP Toolkit MK2 int EFT_EE0613_ZKA_PIN_Translate( IN UCHAR FM, IN UCHAR ePPKi_PIN[8], IN KEYSPEC *PPKi, IN UCHAR PFi, IN UCHAR ANB[6], IN UCHAR PFo, IN KEYSPEC *MK2_1, OUT UCHAR OUT UCHAR OUT KEYSPEC ePPKo_PIN[8], RND[16], *MK2_2);
SafeNet, Inc.
297
ZKA-MAC-GEN
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
D D D D U
Length 3 1 1
Attribute H H H
Description Function Code Function Modifier = 00 Algorithm Qualifier: 00 = Retail MAC (ISO 9807) method 01 = Triple-DES CBC method MAC Length 1 8 Bytes Input Chaining Data Key Specifier for ZKA Master Key (Format: 11, 13) Data to be MACed Must be a multiple of 8 bytes. Position in DATA where RND is inserted Description Function Code Return Code Message Authentication Code Random Number (encrypted session key)
H H K-Spec H H Attribute H H H H
This function generates a random encrypted MAC key, RND, and uses the clear MAC key to generate a MAC for the provided data. The value of RND may be inserted in the data prior to calculating the MAC. FM ALG = 00. Must be set to zero Specifies the MACing algorithm to use For single-length MPK this field must be zero For double-length MPK 00 01 MAClength ICD MK-spec Data C ISO 9807 method triple-DES CBC method
Specifies the length of the output MAC. Input Chaining Data, used for long message feedback. A key Specifier incorporating a ZKA Master Key. The data to be MACed. Must be a multiple of 8 bytes. Offset used to insert RND into Data. If zero, do not insert RND, else insert RND at specified offset, (1 indicates insert at leftmost byte of Data).
SafeNet, Inc.
298
SHP Toolkit MK2 int EFT_EE0710_ZKA_MAC_Generate( IN UCHAR FM, IN UCHAR Algorithm, IN UCHAR MacLen, IN UCHAR ICD[8], IN KEYSPEC *MK, IN EFTBUFFER *Data, IN UCHAR C[2], OUT OUT EFTBUFFER UCHAR *MAC, RND[16]);
SafeNet, Inc.
299
ZKA-MAC-GEN-1
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
D D D D U
Length 3 1 1 1 8 Var
Attribute H H H H H K-Spec
Description Function Code Function Modifier = 00 Algorithm Qualifier MAC Length 1 8 Bytes Input Chaining Data Key Specifier for ZKA MK2 (Format: 90)* VerNo / GenNo / ExpDate = FFFF9999 Data to be MACd Position in Data where RND replaces Data. Position in Data where VerNo replaces Data. Position in Data where GenNo replaces Data. Description Function Code Return Code Message Authentication Code Random No. (encrypted session key) Key Specifier for ZKA MK2 (Format: 92)
Data Offset1 Offset2 Offset3 Response Content EE0711 rc MAC RND MK2-Spec-2
H H H H Attribute H H H H K-Spec
* When using MK2-spec-1 format 90, ignore the RND field. This function generates a random encrypted MAC key, RND, and uses the clear MAC key to generate a MAC for the provided data. The values of RND, Version Number and Generation Number may be inserted in the data prior to calculating the MAC. FM Alg = 00. Must be set to zero. Specifies the MACing algorithm to use. 00 01 MAClength MK2-Spec Data Offset1 Offset2 Retail MAC (ISO 9807) method triple-DES CBC method
Specifies the length of the output MAC A key specifier for the Master Key. The data to be MACd. Must be a multiple of 8 bytes. If zero, do not insert RND in Data, else insert RND at specified Offset1 (01 indicates insert at leftmost byte of Data.) If zero, do not insert Version Number in Data, else insert Version Number at specified Offset2 (01 indicates insert at leftmost byte of Data.)
SafeNet, Inc.
300
Offset3
If zero, do not insert Generation Number in Data, else insert Generation Number at specified Offset3 (1 indicates insert at leftmost byte of Data.)
SHP Toolkit MK2 int EFT_EE0711_ZKA_MAC_Gen_1( IN UCHAR FM, IN UCHAR Algorithm, IN UCHAR MacLen, IN UCHAR ICD[8], IN KEYSPEC *MK2_1, IN EFTBUFFER *Data, IN UCHAR Offset1[2], IN UCHAR Offset2[2], IN UCHAR Offset3[2], OUT EFTBUFFER OUT UCHAR OUT KEYSPEC *MAC, RND[16], *MK2_2);
SafeNet, Inc.
301
SafeNet, Inc.
302
D D U D U
Request Content
EEBF29 FM
Length
3 1
Attribute
h x
Description
Function Code Function Modifier = 00 00 = Get details on specified Key or 01 = Get details on next Key Key Type (decimal) 01 - KIS 02 - KIR 03 - BDK 04 - PPK 05 - MPK 06 - DPK 07 - KTM 08 - PVK 09 - KM 10 - TRANSFER 12 - KKL 13 - PVVK 14 - CVVK 15 - DPVT 17 - IMK_AC 18 - IMK_SMI 19 - IMK_SMC 20 - IMK_DAC 21 - IMK_IDN 22 - CAP_BITMAP 23 - KEK_KPE 24 - DMK 25 - PMK 26 - MBTS 27 - VSK 28 - ZCMK 29 - AWK 30 - IWK 31 - PGK 32 - MDK 33 - KTPV 34 - ZKA_MK2 35 - ZKA_KTK 36 - ZKA_KK 37 - ZKA_MK 38 - ZKA_KGK 39 - 3624_KTM
Key Type
SafeNet, Inc.
303
Request Content
Length
Attribute
Description
40 - 3624_BK 41 - CSCK 42 - KMISS 43 KMCRE 44 - KMCIP 45 - KMAUTH 46 - KMSC1 47 - KMSC2 48 - KMDEB 49 MTMK 50 - IMK_CVC 52 KTK 53 PTK 54 - KMC KVC Algorithm (not applicable to the PHW, see Notes below) 01 = KR4 02 = ZL6 03 = ZL4 04 = SHA-1 05 = MDC2 Index into table of specified Key As for KM, 00 = Old KM, = Current KM, New KM 01 02 =
KVCType
Index
Response Content
EEBF29 rc KeyLen
Length
2 1 2
Attribute
h x h
Description
Function Code Return Code Key Length of specified Key 8 single length 16 double length 24 triple length Key Table Type
KeyType
If Transfer Table was specified then this is the type of the key in the Transfer Table KVC Var h KVC of clear key (size depends on KVC method) This function allows an operator to verify the existence and obtain the KVC of keys stored in the Secure Memory of the HSM device. Note: KVC methods vary depending on the Key Type. PHW calculates KVCs with the same method the console is using. SHP Toolkit MK2 EXPORT int EFT_EEBF29_GetKVC( IN UCHAR *ESMID, IN UCHAR FM, IN USHORT Type, IN USHORT KVCType, IN USHORT Index, OUT OUT OUT OUT USHORT *KeyLen, USHORT *KeyType, USHORT *IndexOut, EFTBUFFER *KVC);
SafeNet, Inc.
304
D D D D U
Request Content EF0616 FM ABI PAN Check Digit eKMv7(PVK) DT PF PPK-Spec Response Content EF0616 rc ePPK(PIN)
Description Function Code Function Modifier = 00 ABI code, Issuer Domestic Code - ASCII PAN Number - ASCII Check Digit PAN - ASCII Encrypted PVK (Formats: 0 - 3, 10) Decimalization Table PIN Block Format (Formats: 00, 01, 10) Key specifier for PPK (Formats: 0 - 3, 10, 11, 13) Description Function Code Return Code Encrypted PIN Block (ISO-0 or IBM-3624 format)
This function generates Italian 5 digit PIN according to IBM 3624 method (for derived PINs) The function will fail with Error Code 78 if PF indicates a PIN block format that is disabled except for format 00 which is always enabled for this function. SHP Toolkit MK2 EXPORT int EFT_EF0616_GNET_PIN_Generation( IN UCHAR FM, IN UCHAR ABI[5], IN UCHAR PAN[12], IN UCHAR Check, IN KEYSPEC *eKMv7, IN UCHAR DT[8], IN UCHAR PF, IN KEYSPEC *PPK, OUT UCHAR ePPK[8]);
SafeNet, Inc.
305
Auth_Param_Generate
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
D D D D U
Request Content EF0617 FM PPK ePPK(PIN) Issuer Domestic Code Card Secure Code PAN Data DPK-Spec Response Content EF0617 rc AP Value
Description Function Code Function Modifier = 00 Key specifier for PPK (Formats: 0 - 3, 10, 11, 13) Encrypted PIN Block, 5 digit PIN Issuer ABI code (domestic identifier for Italian bank) - ASCII Card Secure Code - ASCII PAN Number - ASCII Key specifier for DPK (Formats: 0 - 3, 10, 11, 13) Description Function Code Return Code Encrypted form if AP encryption key identifier specified, otherwise returned in plain text ASCII
This function computes the Authentication Parameter for the input encrypted PIN Block. The function decrypts the PIN Block and uses the authentication parameter algorithm with the input ABI code, Card Secure Code and PAN data to compute the Authentication Parameter. The returned Authentication Parameter is optionally enciphered using the provided key.
SHP Toolkit MK2 EXPORT int EFT_EF0617_GNET_Auth_Param_Generate( IN UCHAR FM, IN KEYSPEC *PIN_encryption_key_identifier, IN UCHAR encrypted_PIN_Block[8], IN UCHAR Issuer_Domestic_Code[5], IN UCHAR Card_Secure_Code[8], IN UCHAR PAN_data[12], IN KEYSPEC *AP_encryption_key_identifier, OUT UCHAR AP_value[8]);
SafeNet, Inc.
306
Random_Key_Generation
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
D D D D U
Description Function Code Function Modifier = 00 Key Format (Formats: 10, 11, 13, 14) KM Variant Index Description Function Code Return Code Key specifier encrypted under current KM (Formats: 10, 11, 13, 14)
This is a generic function allowing the random generation of any key type and encryption under the respective KM variant. This is required by the EF0616 PIN_Generate function described above. To create an eKMv7 PVK, the following parameters are to be passed in, KF = 10, KMVar= 7. SHP Toolkit MK2 EXPORT int EFT_EF0618_GNET_Random_Key_Generation( IN IN IN OUT UCHAR UCHAR UCHAR KEYSPEC FM, KF, KMVar, *encypted_Random_Key);
SafeNet, Inc.
307
SafeNet, Inc.
308
D D U U U
Length 1 1 Length 1 1 8 8
Description Function Code KTM Index Description Function Code Return Code PIN Protect Key PIN Protect Key
This function generates a random initial PIN Protect Key (PPK) for an EFT terminal. For transmitting to the EFT terminal, the key is returned encrypted under the Terminal Master Key (KTMn) indicated by the specified index (KTM Index). It is also returned encrypted under the Master Key Variant 1(KMv1) for storage within the host.
NOTE
This function is superceded by function EE0400 This function only supports use of the first 99 KTMs.
SafeNet, Inc.
309
IT-MPK-GEN
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
D D U U U
Length 1 1 Length 1 1 8 8
Description Function Code KTM Index Description Function Code Return Code MAC Protect Key MAC Protect Key
This function generates a random initial MAC Protect Key (MPK) for an EFT terminal. For transmitting to the EFT terminal, the key is returned encrypted under the Terminal Master Key (KTMn) indicated by the specified index (KTM index). It is also returned encrypted under KM Variant 2, for storage within the host.
NOTE
This function is superceded by function EE0400.
SafeNet, Inc.
310
IT-DPK-GEN
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
D D U U U
Length 1 1 Length 1 1 8 8
Description Function Code KTM Index Description Function Code Return Code Data Protect Key Data Protect Key
This function generates a random initial Data Protect Key (DPK) for an EFT terminal. For transmitting to the EFT terminal, the key is returned encrypted under the Terminal Master Key (KTMn) indicated by the specified index (KTM index). It is also returned encrypted under the KM, for storage within the host.
NOTE
This function is superceded by function EE0400.
SafeNet, Inc.
311
NT-PPK-GEN
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
D D U U U
Length 1 8 Length 1 1 8 8
Description Function Code PIN Protect Key Description Function Code Return Code PIN Protect Key PIN Protect Key
This function generates a new random PIN Protect Key (PPKn+1) for an EFT Terminal. For transmitting to the EFT Terminal, the key is returned encrypted under the supplied previous PIN Protect Key (PPKn). It is also returned encrypted under KM Variant 1, for storage within the host system.
NOTE
This function is superceded by function EE0401.
SafeNet, Inc.
312
NT-MPK-GEN
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
D D U U U
Length 1 8 Length 1 1 8 8
Description Function Code MAC Protect Key Description Function Code Return Code MAC Protect Key MAC Protect Key
This function generates a new random MAC Protect Key (PPKn+1) for an EFT Terminal. For transmitting to the EFT Terminal, the key is returned encrypted under the supplied previous MAC Protect Key (MPKn). It is also returned encrypted under KM Variant 2, for storage within the host system.
NOTE
This function is superceded by function EE0401.
SafeNet, Inc.
313
NT-DPK-GEN
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
D D U U U
Length 1 8 Length 1 1 8 8
Description Function Code Data Protect Key Description Function Code Return Code Data Protect Key Data Protect Key
This function generates a new random Data Protect Key (DPKn+1) for an EFT Terminal. For transmitting to the EFT Terminal, the key is returned encrypted under the supplied previous Data Protect Key (DPKn). It is also returned encrypted under the KM, for storage within the host system.
NOTE
This function is superceded by function EE0401.
SafeNet, Inc.
314
GEN_SESS_KEYS
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
D D U U U
Description Function Code Key specifier for KTM (Formats: 0 - 3) Key Type generation specifier. Description Function Code Return Code Encrypted Session Key Session Key
eKTM(KS) eKMx(KS)
This pair of fields will occur one or more times in the response
This function generates a set of random session keys for an EFT terminal. For distribution to the terminal the session keys are encrypted by the Terminal Master Key (KTM), and for host storage and subsequent use with other functions they are encrypted by variants of the Domain Master Key. KTM-Spec Key Flags A key specifier which incorporates an index to an HSM-stored KTM. Indicates the session keys to generate. The function response will contain one or more sets of encrypted key fields as shown: one set for each bit set in the flags. The bit positions are allocated as follows: bit 0 1 2 3-15 session key type Single-length Data Key (DPK). Single-length PIN encrypting key (PPK). Single-length MAC key (MPK). Reserved. Must be zero.
Bit 0 is the least significant (rightmost) bit. Examples: eKTM(KS) eKMx(KS) To generate a single-length MAC key, this field must be set to X0004; To generate a single-length PIN encrypting key and a MAC key, the field must be set to X0006.
These fields form a key set. The response incorporates a key set for each bit (validly) set in the Key flag field. The order of the returned key sets is the same order that the keys are specified in the Key flag field.
NOTE
This function is superceded by function EE0400.
SafeNet, Inc.
315
TERM-VER
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
D D U U U
Length 1 1 8 8 Length 1 1
Attribute h d h h Attribute h h
Description Function Code KTM Index Security Number Logon Data Description Function Code Return Code
This function verifies the validity of an EFT terminal by checking that the Logon-Data is equal to the result of encrypting its Security Number (SEC-No) under its Base Key.
NOTE
This function is superceded by function EE0406.
SafeNet, Inc.
316
II-PPK-GEN
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
D D U U U
Length 1 1 Length 1 1 8 8
Description Function Code KIS Index Description Function Code Return Code PIN Protect Key PIN Protect Key
This function generates a random initial interchange PIN Protect Key (PPK). For transmitting to the receiving institution, the key is returned encrypted under variant 1 of the Interchange Sending Key (KISn) indicated by the specified index (KIS Index). It is also returned encrypted under KM variant 1, for storage within the host.
eKISnv1(PPK)
is the session key encrypted under variant 1 of KISn. The variant is determined by the variant scheme associated with KISn. KIS range = 01 - 99. is the host stored session key encrypted under variant 1 of the KM.
eKMv1(PPK)
NOTE
This function will check the length of KISn and use the appropriate encryption method. This function is superceded by function EE0402.
SafeNet, Inc.
317
II-MPK-GEN
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
D D U U U
Length 1 1 Length 1 1 8 8
Description Function Code KIS Index Description Function Code Return Code MAC Protect Key MAC Protect Key
This function generates a random initial interchange MAC Protect Key (MPK). For transmitting to the receiving institution, the key is returned encrypted under variant 2 of the Interchange Sending Key (KISn) indicated by the specified index (KIS Index). It is also returned encrypted under KM variant 2, for storage within the host. eKISnv2(MPK) eKMv2(MPK) is the session key encrypted under variant 1 of KISn. The variant is determined by the variant scheme associated with KISn. is the host stored session key encrypted under variant 1 of the KM.
NOTE
This function will check the length of KISn and use the appropriate encryption method. This function is superceded by function EE0402.
SafeNet, Inc.
318
II-DPK-GEN
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
D D U U U
Length 1 1 Length 1 1 8 8
Description Function Code KIS Index Description Function Code Return Code Data Protect Key Data Protect Key
This function generates a random initial interchange Data Protect Key (DPK). For transmitting to the receiving institution, the key is returned encrypted under the Interchange Sending Key (KISn) indicated by the specified index (KIS Index). It is also returned encrypted under the KM, for storage within the host. eKISn(DPK) eKM(DPK) is the session key encrypted under KISn. is the host stored session key encrypted under the KM.
NOTE
This function will check the length of KISn and use the appropriate encryption method. When there is no variant scheme chosen for the KIS, this function will be automatically disabled. In such a case the function can be manually enabled from the console by selecting Enable function for data key generation under the KIS Options dialog. Please refer to the Console User Guide for directions on how to set options for the KIS. This function is superceded by function EE0402.
SafeNet, Inc.
319
II-PPK-RCV
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
D D U U U
Length 1 1 8 Length 1 1 8
Description Function Code KIR Index PIN Protect Key Description Function Code Return Code PIN Protect Key
This function takes an Interchange PIN Protect Key (PPK) that has already been encrypted under variant 1 of the Interchange Receive Key (KIRn) indicated by the supplied index (KIR Index), and re-encrypts it under KM variant 1, for storage within the host. eKIRnv1(PPK) eKMv1(PPK) is the session key encrypted under variant 1 of KIRn. The variant is determined by the variant scheme associated with KIRn. is the host stored session key encrypted under variant 1 of the KM.
NOTE
This function will check the length of KIRn and use the appropriate encryption method. This function is superceded by function EE0403.
SafeNet, Inc.
320
II-MPK-RCV
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
D D U U U
Length 1 1 8 Length 1 1 8
Description Function Code KIR Index MAC Protect Key Description Function Code Return Code MAC Protect Key
This function takes an Interchange MAC Protect Key (MPK) that has already been encrypted under the Interchange Receive Key (KIRn) indicated by the supplied index (KIR Index), and reencrypts it under KM variant 2, for storage within the host. eKIRnv2(MPK) eKMv2(MPK) is the session key encrypted under variant 2 of KIRn. The variant is determined by the variant scheme associated with KIRn. is the host stored session key encrypted under variant 2 of the KM.
NOTE
This function will check the length of KIRn and use the appropriate encryption method. This function is superceded by function EE0403.
SafeNet, Inc.
321
II-DPK-RCV
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
D D U U U
Length 1 1 8 Length 1 1 8
Description Function Code KIR Index Data Protect Key Description Function Code Return Code Data Protect Key
This function takes an Interchange Data Protect Key (DPK) that has already been encrypted under the Interchange Receive Key (KIRn) indicated by the supplied index (KIR Index), and reencrypts it under the KM, for storage within the host. eKIRn(DPK) eKM(DPK) is the session key encrypted under KIRn. is the host stored session key encrypted under the KM.
NOTE
This function will check the length of KIRn and use the appropriate encryption method. When there is no variant scheme chosen for the KIR, this function will be automatically disabled. In such a case, this function can be manually enabled from the console by selecting Enable function for receiving of data keys under the KIR Options dialog. Please refer to the Console User Guide for directions on how to set options for the KIR. This function is superceded by function EE0403.
SafeNet, Inc.
322
NI-PPK-GEN
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
D D U U U
Length 1 8 Length 1 1 8 8
Description Function Code PIN Protect Key Description Function Code Return Code PIN Protect Key PIN Protect Key
This function generates a new random PIN Protect Key (PPKn+1) for an Interchange. For transmitting to the receiving node, the key is returned encrypted under the supplied previous PIN Protect Key (PPKn). It is also returned encrypted under KM Variant1, for storage within the host system.
NOTE
This function is superceded by function EE0404.
SafeNet, Inc.
323
NI-MPK-GEN
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
D D U U U
Length 1 8 Length 1 1 8 8
Description Function Code MAC Protect Key Description Function Code Return Code MAC Protect Key MAC Protect Key
This function generates a new random MAC Protect Key (MPKn+1) for an Interchange. For transmitting to the receiving node, the key is returned encrypted under the supplied previous MAC Protect Key (MPKn). It is also returned encrypted under KM Variant 2, for storage within the host system.
NOTE
This function is superceded by function EE0404.
SafeNet, Inc.
324
NI-DPK-GEN
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
D D U U U
Length 1 8 Length 1 1 8 8
Description Function Code Data Protect Key Description Function Code Return Code Data Protect Key Data Protect Key
This function generates a new random Data Protect Key (DPKn+1) for an Interchange. For transmitting to the receiving node, the key is returned encrypted under the supplied previous Data Protect Key (DPKn). It is also returned encrypted under the KM, for storage within the host system.
NOTE
This function is superceded by function EE0404.
SafeNet, Inc.
325
NI-PPK-RCV
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
D D U U U
Length 1 8 8 Length 1 1 8
Description Function Code PIN Protect Key PIN Protect Key Description Function Code Return Code PIN Protect Key
This function allows a PIN Protect Key roll-over for the interchange. The node receives a new PIN Protect Key (PPKn+1) encrypted under the current one (PPKn) and sends it together with the current PIN Protect Key encrypted under KM Variant 1 to the HSM. The HSM returns the new PIN Protect Key encrypted under KM Variant 1, for storage within the host.
NOTE
This function is superceded by function EE0405.
SafeNet, Inc.
326
NI-MPK-RCV
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
D D U U U
Length 1 8 8 Length 1 1 8
Description Function Code MAC Protect Key MAC Protect Key Description Function Code Return Code MAC Protect Key
This function allows a MAC Protect Key roll-over for the interchange. The node receives a new MAC Protect Key (MPKn+1) encrypted under the current one (MPKn) and sends it together with the current MAC Protect Key encrypted under KM Variant 2 to the HSM. The HSM returns the new MAC Protect Key encrypted under KM Variant 2, for storage within the host.
NOTE
This function is superceded by function EE0405.
SafeNet, Inc.
327
NI-DPK-RCV
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
D D U U U
Length 1 8 8 Length 1 1 8
Description Function Code Data Protect Key Data Protect Key Description Function Code Return Code Data Protect Key
This function allows a Data Protect Key roll-over for the remote Interchange. The remote Interchange receives a new Data Protect Key (DPKn+1) encrypted under the current one (DPKn) and sends it together with the current Data Protect Key encrypted under the KM to the HSM.
NOTE
This function is superceded by function EE0405.
SafeNet, Inc.
328
PIN-TRAN
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
D D U U U
Request Content 60 PFi, PFo ePPKi(PIN) eKMv1(PPKi) eKMv1(PPKo) ANB Response Content 60 rc ePPKo(PIN)
Length 1 1 8 8 8 6 Length 1 1 8
Description Function Code PIN Format(input/output) (Formats: 00, 03) PIN encrypted under PPKi Encrypted Input PPK Encrypted Output PPK Account Number Block Description Function Code Return Code PIN encrypted under PPKo
This function allows translation of both the PIN Block format and the PIN encryption key. PFi and PFo respectively specify the format of the supplied PIN Block and of the required PIN Block. If format translation is not required, the PFi and PFo fields must be set to the same value. The valid field values are: 1 = AS/ANSI format 3 = PIN/PAD format PPKi and PPKo respectively specify the PIN Protect Key of the supplied PIN Block and of the required PIN Block. If key translation is not required, PPKo must equal PPKi. is the 12-digit Account Number Block used in the formation of the clear AS/ANSI PIN Block.
ANB
The function will fail with Error Code 78 if Pfi or PFo indicates a PIN block format that is disabled or conflicts with the reformatting restrictions.
NOTE
This function is superceded by function EE0602.
SafeNet, Inc.
329
PIN-VER-IBM-ANSI
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
D D U U U
Request Content 61 PVK-Index ePPK(AS-PIN) eKMv1(PPK) PAN ANB Offset Response Content 61 rc
Length 1 1 8 8 8 6 6 Length 1 1
Description Function Code Index of PVK PIN Protect Key Encrypted PPK Primary Account Number Account Number Block PIN Offset Data Description Function Code Return Code
This function performs the verification of a PIN in an AS/ANSI formatted PIN Block, using the IBM 3624 method. PVK-Index AS-PIN PAN ANB Offset identifies the PVKn, DTn, and MINPINn appropriate to the PIN verification procedure. is the AS/ANSI formatted PIN Block containing the PIN to be verified. It must be supplied encrypted by a PIN Protect session key (PPK). is the Primary Account Number (or other card data) used in the verification procedure. It must be padded appropriately prior to input to this function. is the 12-digit Account Number Block used in the formation of the clear AS/ANSI PIN Block. consists of up to 12 digits of Offset data. The significant digits must be leftjustified in the field. Unused digits are ignored. If Offsets are not used, the significant digits must be zeros.
The function will fail with Error Code 78 if the ANSI/ISO 0 PIN block format is disabled.
NOTE
This function is superceded by function EE0603.
SafeNet, Inc.
330
PIN-VER-PP
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
D D U U U
Length 1 1 8 8 8 6 Length 1 1
Description Function Code Index of PVK Encrypted PIN Block Encrypted PPK Primary Account Number PIN Offset Data Description Function Code Return Code
This function verifies a PIN in a PIN/PAD formatted PIN Block using the IBM 3624 method. PVK-Index PP-PIN PAN Offset identifies the PVKn, DTn, and MINPINn appropriate to the PIN verification procedure. is the formatted PIN Block containing the PIN to be verified. It must be supplied encrypted by a PIN Protect session key (PPK). is the Primary Account Number (or other card data) used in the verification procedure. It must be padded appropriately prior to input to this function. consists of up to 12 digits of Offset data. The significant digits must be leftjustified in the field. Unused digits are ignored. If Offsets are not used, the significant digits must be zeros.
In general, the function may be used to verify a PIN/PAD formatted PIN Block supplied encrypted by a host stored PPK, if the PIN Block has been received either from a terminal or from an interchange. However, in the interchange situation it is recommended that the Acquirer institution translates the PIN Block to AS/ANSI format prior to routing the transaction to the Issuer. The Issuer would then use the PIN-VER function to verify the PIN. The function will fail with Error Code 78 if the PIN/Pad PIN block format is disabled.
NOTE
This function is superceded by function EE0603.
SafeNet, Inc.
331
D51-PIN-TRAN
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
D D U U U
Request Content 65 ePPKi, PPKo(51-PIN) eKMv1(PPKi) eKMv1(PPKo) ANB Response Content 65 rc ePPKo(AS-PIN)
Length 1 8 8 8 6 Length 1 1 8
Description Function Code Encrypted PIN Block Encrypted Input PPK Encrypted Output PPK Account Number Block Description Function Code Return Code Encrypted PIN Block
This function performs translation of both the PIN Block format and the PIN Block encryption key of an encrypted PIN Block received from a Docutel 5100 ATM. 51-PIN is the Docutel formatted PIN Block. It must contain from four to six numeric PIN digits, left justified and terminated to the right with a single hex 'F' digit. All other digits in the PIN Block (Julian Date and Serial Number) are ignored. respectively specify the PIN Protect Key of the supplied PIN Block and of the required PIN Block. If key translation is not required, PPKo must equal PPKi. is the 12-digit Account Number Block used in the formation of the clear AS/ANSI PIN Block. is the resultant AS/ANSI formatted PIN Block.
PPKi
ANB AS-PIN
The function will fail with Error Code 78 if the Docutel or ANSI/ISO 0 PIN block format is disabled.
NOTE
This function is superceded by function EE0602.
SafeNet, Inc.
332
D51-PIN-VER
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
D D U U U
Length 1 1 8 8 8 6 Length 1 1
Description Function Code Index of PVK Encrypted PIN Block Encrypted PPK Primary Account Number PIN Offset Data Description Function Code Return Code
This function performs the verification of a PIN in a DOCUTEL 5100 formatted PIN Block, using the IBM 3624 method. PVK-Index D51-PIN PAN Offset identifies the PVKn, DTn, and MINPINn appropriate to the PIN verification procedure. is the DOCUTEL 5100 formatted PIN Block containing the PIN to be verified. It must be supplied encrypted by a PIN Protect Key (PPK). is the Primary Account Number (or other card data) used in the verification procedure. It must be padded appropriately prior to input to this function. consists of up to 12 digits of Offset data. The significant digits must be leftjustified in the field. Unused digits are ignored. If Offsets are not used, the significant digits must be zeros.
The function will fail with Error Code 78 if the Docutel PIN block format is disabled.
NOTE
This function is superceded by function EE0603.
SafeNet, Inc.
333
VAR-PIN-VER
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
D D U U U
Request Content 67 PVK-Index ePPK(AS-PIN) eKMv1(PPK) PAN ANB CHKLEN Offset Response Content 67 rc
Length 1 1 8 8 8 6 1 6 Length 1 1
Description Function Code Index of PVK Encrypted PIN Block Encrypted PPK Primary Account Number Account Number Block PIN Check Length 04 - 12 PIN Offset Data Description Function Code Return Code
This function verifies an AS/ANSI formatted PIN. The PIN Block must be supplied encrypted under a PIN Protect Key (PPK). PVK-index AS-PIN PAN ANB CHKLEN identifies the PVKn, DTn, and MINPINn appropriate to the PIN verification procedure. is the AS/ANSI formatted PIN Block containing the PIN to be verified. It must be supplied encrypted by a PIN Protect session key (PPK). the Primary Account Number used in the verification procedure. It must be padded appropriately prior to input to this function. is the 12-digit Account Number Block used in the formation of the clear AS/ANSI PIN Block. the CHKLEN field contains the number of PIN digits to be checked and may be less than, or equal to, the actual length of the PIN. The significant Offset digits must be supplied left aligned and right padded in the Offset field. consists of up to 12 digits of Offset data. The significant digits must be leftjustified in the field. Unused digits are ignored. If Offsets are not used, the significant digits must be zeros.
Offset
The function will fail with Error Code 78 if the ANSI/ISO 0 PIN block format is disabled.
See Appendix A IBM 3624 PIN Verification Method for a more detailed overview of the PIN verification procedure.
NOTE
This function is superceded by function EE0603.
SafeNet, Inc.
334
VAR-PIN-VER-PP
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
D D U U U
Request Content 68 PVK-Index ePPK(PP-PIN) eKMv1(PPK) PAN CHKLEN Offset Response Content 68 rc
Length 1 1 8 8 8 1 6 Length 1 1
Description Function Code Index of PVK PIN/PAD formatted PIN Block Encrypted PPK Primary Account Number PIN Check Length 04 12 PIN Offset Data Description Function Code Return Code
This function verifies a PIN/PAD formatted PIN. The PIN Block must be supplied encrypted under a PIN Protect Key (PPK). PVK-Index PAN CHKLEN identifies the PVKn, DTn, and MINPINn appropriate to the PIN verification procedure. the Primary Account Number used in the verification procedure. It must be padded appropriately prior to input to this function. The CHKLEN field contains the number of PIN digits to be checked and may be less than, or equal to, the actual length of the PIN. The significant Offset digits must be supplied left aligned and right padded in the Offset field. consists of up to 12 digits of Offset data. The significant digits must be leftjustified in the field. Unused digits are ignored. If Offsets are not used, the significant digits must be zeros.
Offset
The function will fail with Error Code 78 if the PIN/Pad PIN block format is disabled.
See Method for a more detailed overview of the PIN verification procedure.
NOTE
This function is superceded by function EE0603.
SafeNet, Inc.
335
PIN-OFF-AS
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
D D U U U
Request Content
6A PVK-Index ePPK(AS-PIN) eKMv1(PPK) PAN ANB Response Content 6A rc Offset PINLEN
Length
1 1 8 8 8 6 Length 1 1 6 1
Attribute
h d B64 B64 h h Attribute h h h h
Description
Function Code Index of PVK AS/ANSI formatted PIN Block Encrypted PPK Primary Account Number Account Number Block Description Function Code Return Code Returned PIN Offset Data Returned PIN Length
This function generates an Offset for an AS/ANSI formatted PIN. The PIN Block must be supplied encrypted under a PIN Protect Key (PPK). Offset digits for all PIN digits are returned. If CHKLEN is to be set to be less than the PINLEN in a PIN Verification function, then the significant digits must be selected from the returned Offset. These digits must then be passed left aligned and right padded in the Offset field of the appropriate PIN Verification function. See Appendix A IBM 3624 PIN Verification Method for a more detailed overview of the PIN verification procedure and for examples on selecting significant Offset digits. PVK-Index AS-PIN PAN ANB identifies the PVKn, DTn, and MINPINn appropriate to the PIN verification procedure. is the AS/ANSI formatted PIN Block containing the PIN to be verified. It must be supplied encrypted by a PIN Protect session key (PPK). the Primary Account Number used in the verification procedure. It must be padded appropriately prior to input to this function. is the 12-digit Account Number Block used in the formation of the clear AS/ANSI PIN Block.
A Return Code of 07 indicates that the format of the PIN Block in the request is incorrect. A Return Code of 0B indicates that PINLEN is less than MINPIN. The customer's current PIN should be verified before this function is called. The function will fail with Error Code 78 if the ANSI/ISO 0 PIN block format is disabled. The function performs a check that the ANB field and the PAN field (Validation Data) contain a number of consecutive digits in common. The number of digits to check is in the range 0 to 12, as may be specified using a console operation, and defaults to 8. If the number of digits to check has been set to 0 the check is disabled, and the function accepts any supported PIN block format that is enabled. If the number of digits to check is greater than 0, then only ISO-0 and ISO-3 PIN blocks are allowed, if enabled. If the check fails, the function will fail with Return Code 79.
NOTE
This function is superceded by function EE0604.
SafeNet, Inc.
336
PIN-OFF-PP
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
D D U U U
Request Content 6B PVK-Index ePPK(PP-PIN) eKMv1(PPK) PAN Response Content 6B rc Offset PINLEN
Length 1 1 8 8 8 Length 1 1 6 1
Description Function Code Index of PVK PIN/PAD formatted PIN Block Encrypted PPK Primary Account Number Description Function Code Return Code Returned PIN Offset Data Returned PIN Length
This function generates an Offset for a PIN/PAD formatted PIN. The PIN Block must be supplied encrypted under a PIN Protect Key (PPK). Offset digits for all PIN digits are returned. If CHKLEN is to be set to be less than the PINLEN in a PIN Verification function, then the significant digits must be selected from the returned Offset. These digits must then be passed left aligned and right padded in the Offset field of the appropriate PIN Verification function. See Appendix A IBM 3624 PIN Verification Method for a more detailed overview of the PIN verification procedure and for examples on selecting significant Offset digits. PVK-Index PAN identifies the PVKn, DTn, and MINPINn appropriate to the PIN verification procedure. the Primary Account Number used in the verification procedure. It must be padded appropriately prior to input to this function.
A Return Code of 07 indicates that the format of the PIN Block in the request is incorrect. A Return Code of 0B indicates that PINLEN is less than MINPIN. The current customer's PIN should be verified before this function is called. The function will fail with Error Code 78 if the PIN/Pad PIN block format is disabled. As the encrypted PIN block does not incorporate the account number (ANB) this function requires that the number of consecutive digits in common between the ANB and PAN field (Validation Data) is set to 0, otherwise the function will fail with Return Code 79. The number of digits to check is in the range 0 to 12, as may be specified using a console operation, and defaults to 8.
NOTE
This function is superceded by function EE0604.
SafeNet, Inc.
337
MAC-GEN
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
D D U U U
Description Function Code No of 8 byte Blocks Encrypted MPK Must be a multiple of 8 Bytes Description Function Code Return Code Message Authentication Code
This function generates a 32-bit Message Authentication Code (MAC) for the supplied DATA using the supplied MAC Protect Key (MPK), in accordance with AS2805.4 1985.
NOTE
This function is superceded by function EE0701.
SafeNet, Inc.
338
MAC-TRAN
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
D D U U U
Request Content 71 Blocks eKMv2(MPKi) eKMv2(MPKo) Data MACi Response Content 71 rc MACo
Description Function Code No of 8 byte Blocks Encrypted Input MPK Encrypted Output MPK Must be multiple of 8 bytes Input Message Authentication Code Description Function Code Return Code Output Message Authentication Code
This function verifies that MACi is a valid MAC for Data using MPKi, and generates a new MAC (MACo) using MPKo.
NOTE
This function is superceded by function EE0701.
SafeNet, Inc.
339
MAC-VER
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
D D U U U
Description Function Code No of 8 byte Blocks Encrypted Input MPK Must be multiple of 8 Bytes Message Authentication Code Description Function Code Return Code
This function verifies that the MAC is a valid MAC for the supplied DATA using the supplied MAC Protect Key (MPK), in accordance with AS2805.4 1985.
NOTE
This function is superceded by function EE0701.
SafeNet, Inc.
340
ENCIPHER
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
D D U U U
Description Function Code No of 8 byte Blocks Encrypted DPK Must be multiple of 8 bytes Description Function Code Return Code Data encrypted under DPK
This function DES encrypts the supplied DATA using the supplied Data Protect Key (DPK), the Cipher Block Chaining mode of operation and a fixed Initialization Vector having a value of X555555555555555555.
NOTE
This function is superceded by function EE0800.
SafeNet, Inc.
341
DECIPHER
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
D D U U U
Description Function Code No of 8 byte Blocks Data Protect Key Must be multiple of 8 bytes Description Function Code Return Code Clear Data
This function DES decrypts the supplied encrypted DATA using the supplied Data Protect Key (DPK), the Cipher Block Chaining mode of operation and a fixed Initialization Vector having a value of X555555555555555555.
NOTE
This function is superceded by function EE0801.
SafeNet, Inc.
342
ENCIPHER-ECB
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
D D U U U
Description Function Code No of 8 byte Blocks Data Protect Key Must be multiple of 8 bytes Description Function Code Return Code Data encrypted under DPK
This function encrypts the supplied DATA under the supplied Data Protect Key (DPK), using the DES in Electronic Code Book mode.
NOTE
This function is superceded by function EE0800.
SafeNet, Inc.
343
DECIPHER-ECB
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
D D U U U
Description Function Code No of 8 byte Blocks Data Protect Key Must be multiple of 8 bytes Description Function Code Return Code Clear Data
This function decrypts the supplied encrypted DATA using the supplied Data Protect Key (DPK) and the DES in Electronic Code Book mode.
NOTE
This function is superceded by function EE0801.
SafeNet, Inc.
344
PVV-GEN-1
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
D D U U U
Length 1 1 8 2 6 Length 1 1 2
Attribute h d h h h Attribute h h h
Description Function Code Index of PVK Primary Account Number PIN Offset Data Transformed Security Parameter Description Function Code Return Code PIN Verification Value
This function calculates the PVV by using the IBM 3624 method to produce the PIN. The four leftmost digits of the derived or random PIN are appended to the TSP12 to form the TSP. PVK-Index identifies the PVKn and DECTABn appropriate to the PIN Generation method. Note: Whenever PVK keys are used a corresponding decimalization table is used. Additionally in some functions, the PIN Length must exist. Therefore when entering PVKs the user should also enter the corresponding decimalization table PIN Length for each PVK. PAN Offset4 is the 16-digit field which is encrypted using PVKn and decimalized using DECTABn to produce the leftmost four digits of the derived PIN. is the leftmost 4 digits of Offset data which is modulo-10 added to the derived PIN to produce the random PIN. If random PINs are not used this field should be set to zeros. is the leftmost 12 digits of the TSP and consists of 11 PAN digits followed by the appropriate one digit PVKI.
TSP12
The PVV is calculated using an HSM stored PVK-A/B pair. This function uses the PVKI as the PVK-A/B index, hence only the first six of the thirty-six key pairs may be referenced.
NOTE
This function is superceded by function EE0606.
SafeNet, Inc.
345
PVV-VER-1
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
D D U U U
Length 1 8 6 6 2 Length 1 1
Description Function Code Encrypted PIN Block Account Number Block Transformed Security Parameter PIN Verification Value Description Function Code Return Code
This function verifies an Issuer AS 2805.3 1985 formatted PIN by using the Visa PVV method. AS-PIN ANB TSP12 PVV is the AS 2805.3 1985 formatted PIN Block containing the PIN to be verified. is the 12-digit Account Number Block (a PAN element of the clear PIN Block). is the leftmost 12 digits of the TSP and consists of 11 PAN digits followed by the appropriate one digit PVKI. is the PIN Verification Value used to verify the calculated PVV.
The PVKI is used as the PVK-A/B index, hence only the first six of the thirty-six key pairs may be referenced. The function will fail with Error Code 78 if the ANSI/ISO 0 PIN block format is disabled.
NOTE
This function is superceded by function EE0605.
SafeNet, Inc.
346
PVV-VER-2
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
D D U U U
Length 1 8 8 6 6 2 Length 1 1
Description Function Code Encrypted PIN Block Encrypted PPK Account Number Block Transformed Security Parameter PIN Verification Value Description Function Code Return Code
This function performs a local PIN verification of a PIN in an AS 2805.3 1985 formatted PIN Block using the Visa PVV method. AS-PIN ANB TSP12 PVV is the AS 2805.3 1985 formatted PIN Block containing the PIN to be verified. It must be supplied encrypted by a PIN Protect session key (PPK). is the 12-digit Account Number Block (a PAN element of the clear PIN Block). is the leftmost 12 digits of the TSP and consists of 11 PAN digits followed by the appropriate one digit PVKI. is the PIN Verification Value used to verify the calculated PVV.
The PVKI is used as the PVK-A/B index, hence only the first six of the thirty-six key pairs may be referenced. The function will fail with Error Code 78 if the ANSI/ISO 0 PIN block format is disabled.
NOTE
This function is superceded by function EE0605.
SafeNet, Inc.
347
PVV-VER-3
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
D D U U U
Length 1 8 8 6 2 Length 1 1
Description Function Code Encrypted PIN Block Encrypted PPK Transformed Security Parameter PIN Verification Value Description Function Code Return Code
This function performs a local PIN verification of a PIN/PAD formatted PIN by using the Visa PVV method (PIN must be left-justified). PP-PIN TSP12 PVKI is the PIN/PAD formatted PIN Block containing the PIN to be verified. It must be supplied encrypted by a PIN Protect session key (PPK). is the leftmost 12 digits of the TSP and consists of 11 PAN digits followed by the appropriate one digit PVKI. is the PIN Verification Key Indicator used to identify the PVK pair (PVK-A and PVK-B) and to build the Transformed Security Parameter (TSP) for the PIN verification procedure. is the PIN Verification Value used to verify the calculated PVV.
PVV
The PVKI is used as the PVK-A/B index, hence only the first six of the thirty-six key pairs may be referenced. The function will fail with Error Code 78 if the PIN/Pad PIN block format is disabled.
NOTE
This function is superceded by function EE0605.
SafeNet, Inc.
348
PIN-TRAN-1
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
D D U U U
Length 1 8 8 Length 1 1 8
Description Function Code Encrypted PIN Block PIN Protect Key Description Function Code Return Code Encrypted PIN
This function performs a PIN Translation from the local Key (PPK) to the Visa Acquirer Key (AWK). The function will fail with Error Code 78 if the ANSI/ISO 0 PIN block format is disabled.
NOTE
This function is superceded by function EE0602.
SafeNet, Inc.
349
PIN-TRAN-2
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
D D U U U
Length 1 8 8 Length 1 1 8
Description Function Code Encrypted PIN Encrypted PPK Description Function Code Return Code Encrypted PIN
This function performs a PIN Translation from a Visa Issuer Key (IWK) to the local Key (PPK). The function will fail with Error Code 78 if the ANSI/ISO 0 PIN block format is disabled.
NOTE
This function is superceded by function EE0602.
SafeNet, Inc.
350
PVV-GEN-2
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
D D U U U
Request Content 96 PVVK-Index PVK-Index PAN Offset 4 TSP12 Response Content 96 rc PVV
Length 1 1 1 8 2 6 Length 1 1 2
Attribute h d d h h h Attribute h h h
Description Function Code Index of PVVK Index of PVK Primary Account Number PIN Offset Data Transformed Security Parameter Description Function Code Return Code PIN Verification Value
This function is similar to the Visa function PVV-GEN-1 (Function Code 90), except that the request includes an index to select the PVK-A/B pair, which is to be used in the verification process. The PVKI that is contained in the TSP12 is no longer used as an index. This allows the host to dictate which key pairs are associated with each card base. The PVVK-index has a range of 1 to 36. The PVKI has a range of 1 to 6. PVVK-Index PVK-Index identifies the PVK-A/B pair that is to be used in the derivation of the PIN and must be in BCD format. identifies the PVKn and DECTABn appropriate to the PIN Generation method. Note: Whenever PVK keys are used a corresponding decimalization table is used. Additionally in some functions, the PIN Length must exist. Therefore when entering PVKs the user should also enter the corresponding decimalization table PIN Length for each PVK. PAN Offset4 is the 16-digit field which is encrypted using PVKn and decimalized using DECTABn to produce the leftmost four digits of the derived PIN. is the leftmost 4 digits of Offset data which is modulo-10 added to the derived PIN to produce the random PIN. If random PINs are not used this field should be set to zeros. is the leftmost 12 digits of the TSP and consists of 11 PAN digits followed by the appropriate one digit PVKI.
TSP12
NOTE
This function is superceded by function EE0606.
SafeNet, Inc.
351
PVV-VER-4
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
D D U U U
Length 1 1 8 6 6 2 Length 1 1
Description Function Code Index of PVVK Encrypted PIN Block Account Number Block Transformed Security Parameter PIN Verification Value Description Function Code Return Code
This function is similar to the Visa function PVV-VER-1 (Function Code 91), except that the request includes an index to select the PVK-A/B pair which is to be used in the verification process. The PVKI which is contained in the TSP12 is no longer used as an index. This allows the host to dictate which key pairs are associated with each card base. The PVVK-index has a range of 1 to 36. The PVKI has a range of 1 to 6. A Return Code of 00 indicates that the PIN is verified. A 07 indicates that the format of the PIN Block in the request is incorrect, and a 08 indicates PIN verification failure. PVVK-Index AS-PIN ANB TSP12 PVV identifies the PVK-A/B pair, which are to be used in the derivation of the PVV and must be in BCD format. is the AS2805.3 1985 formatted PIN Block containing the PIN to be verified. is the 12-digit Account Number Block (a PAN element of the clear PIN Block). is the leftmost 12 digits of the TSP and consists of 11 PAN digits followed by the appropriate one digit PVKI. is the PIN Verification Value used to verify the calculated PVV.
The function will fail with Error Code 78 if the ANSI/ISO 0 PIN block format is disabled.
NOTE
This function is superceded by function EE0605.
SafeNet, Inc.
352
PVV-VER-5
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
D D U U U
Request Content 98 PVVK-Index ePPK(AS-PIN) eKMv1(PPK) ANB TSP12 PVV Response Content 98 rc
Length 1 1 8 8 6 6 2 Length 1 1
Description Function Code Index of PVVK Encrypted PIN Block Encrypted PPK Account Number Block Transformed Security Parameter PIN Verification Value Description Function Code Return Code
This function is similar to the Visa function PVV-VER-2 (Function Code 92), except that the request includes an index to select the PVK-A/B pair that is to be used in the verification process. The PVKI that is contained in the TSP12 is no longer used as an index. This allows the host to dictate which key pairs are associated with each card base. The PVVK-index has a range of 1 to 36. The PVKI has a range of 1 to 6. A Return Code of 00 indicates that the PIN is verified. A 07 indicates that the format of the PIN Block in the request is incorrect, and a 08 indicates PIN verification failure. PVVK-Index AS-PIN ANB TSP12 PVV identifies the PVK-A/B pair, which are to be used in the derivation of the PVV and must be in BCD format. is the AS 2805.3 1985 formatted PIN Block containing the PIN to be verified. It must be supplied encrypted by a PIN Protect session key (PPK). is the 12-digit Account Number Block (a PAN element of the clear PIN Block). is the leftmost 12 digits of the TSP and consists of 11 PAN digits followed by the appropriate one digit PVKI. is the PIN Verification Value used to verify the calculated PVV.
The function will fail with Error Code 78 if the ANSI/ISO 0 PIN block format is disabled.
NOTE
This function is superceded by function EE0605.
SafeNet, Inc.
353
PVV-VER-6
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
D D U U U
Length 1 1 8 8 6 2 Length 1 1
Description Function Code Index of PVVK Encrypted PIN Block Encrypted PPK Transformed Security Parameter PIN Verification Value Description Function Code Return Code
This function is similar to the Visa function PVV-VER-3 (Function Code 93), except that the request includes an index to select the PVK-A/B pair that is to be used in the verification process. The PVKI that is contained in the TSP12 is no longer used as an index. This allows the host to dictate which key pairs are associated with each card base. The PVVK-index has a range of 1 to 36. The PVKI has a range of 1 to 6. A Return Code of 00 indicates that the PIN is verified. A 07 indicates that the format of the PIN Block in the request is incorrect, and a 08 indicates PIN verification failure. PVVK-Index PP-PIN TSP12 PVV identifies the PVK-A/B pair that is to be used in the derivation of the PVV and must be in BCD format. is the PIN/PAD formatted PIN Block containing the PIN to be verified. It must be supplied encrypted by a PIN Protect session key (PPK). is the leftmost 12 digits of the TSP and consists of 11 PAN digits followed by the appropriate one digit PVKI. is the PIN Verification Value used to verify the calculated PVV.
The function will fail with Error Code 78 if the PIN/Pad 0 PIN block format is disabled.
NOTE
This function is superceded by function EE0605.
SafeNet, Inc.
354
PVV-CHANGE
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
D D U U U
Request Content 9A PVVK-Index ePPK(AS-PIN) eKMv1(PPK) ANB TSP12 Response Content 9A rc PVV
Length 1 1 8 8 6 6 Length 1 1 2
Description Function Code Index of PVVK Encrypted PIN Block Encrypted PPK Account Number Block Transformed Security Parameter Description Function Code Return Code PIN Verification Value
This function generates a PVV for the encrypted PIN in the request. If the PIN is not in AS/ANSI format, a PIN format error (Return Code 07) is returned in the response. The request also includes an index to select the PVK-A/B pair that is to be used in the PVV generation process. The PVKI that is contained in the TSP12 is no longer used as an index. This allows the host to dictate which key pairs are associated with each card base. The PVVK-index has a range of 1 to 36. The PVKI has a range of 1 to 6. PVVK-Index AS-PIN identifies the PVK-A/B pair, which are to be used in the derivation of the PVV and must be in BCD format. is the AS 2805.3 1985 formatted PIN Block containing the PIN the PVV is to be generated for. It must be supplied encrypted by a PIN Protect session Key (PPK). is the 12-digit Account Number Block (a PAN element of the clear PIN Block). is the leftmost 12 digits of the TSP and consists of 11 PAN digits followed by the appropriate one digit PVKI.
ANB TSP12
The function will fail with Error Code 78 if the ANSI/ISO 0 PIN block format is disabled. The function performs a check that the ANB field and the TSP12 field contain a number of consecutive digits in common. The number of digits to check is in the range 0 to 12, as may be specified using a console operation, and defaults to 8. If the number of digits to check has been set to 0 the check is disabled. If the check fails, the function will fail with Return Code 79.
NOTE
This function is superceded by function EE0607.
SafeNet, Inc.
355
CVV-GEN
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
D D U U U
Length 1 1 16 Length 1 1 2
Attribute h d h Attribute h h h
Description Function Code Index of CVK Card Verification Value Data Description Function Code Return Code Card Verification Value
This function generates a Card Verification Value (CVV) by the Visa method for card data (CVVdata). CVK-Index CVV-Data CVV A one byte BCD field that indicates which HSM stored CVK-A/B pair to use in the CVV generation process. The data from which the CVV is generated. It is up to the host to format the field correctly and to do any required range checking on the data. The three digit Card Verification Value. The three digits are left aligned and right padded with the hexadecimal digit "F".
NOTE
This function is superceded by function EE0802.
SafeNet, Inc.
356
CVV-VER
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
D D U U U
Length 1 1 16 2 Length 1 1
Attribute h d h h Attribute h h
Description Function Code Index of CVK Card Verification Value Data Card Verification Value Description Function Code Return Code
This function verifies card data (CVV-data) deriving a CVV for that data and validating it against the CVV in the request. CVK-Index CVV-Data CVV is a one byte BCD field which indicates which HSM stored CVK-A/B pair to use in the CVV generation process. is the data from which the CVV is generated. It is up to the host to format the field correctly and to do any required range checking on the data. is the digit byte Card Verification Value. The three digits are left aligned and right padded with the hexadecimal digit "F".
NOTE
This function is superceded by function EE0803.
SafeNet, Inc.
357
SafeNet, Inc.
358
MasterCard PayPass
Calculation of the PayPass CVC3 uses a unique-per-card derived key, KDCVC3, which is derived from a Master Key, IMKCVC.The extension defined here supports:
A host function that derives the KDCVC3 from IMKCVC and then generates the CVC3. A host function that derives the KDCVC3 from IMKCVC and then verifies the CVC3.
The calculation of a CVC3 differs from that of a static CVC (or CVV) in that it is a 3DES encryption of a single 8-byte block, and the CVC3 is the rightmost 4 hex digits (2-bytes) rather than the left 3 digits after decimalization. A card that supports both EMV debit/credit and PayPass requires 2 public key certificates in support of DDA. A function is provided that creates an additional certificate, thereby supplementing the existing CI functions that generate the ICC key pair and certificate.
Visa payWave
Visa payWave embraces three contactless card technologies: Magnetic Stripe Data (MSD), qVSDC and contactless VSDC. In MSD, the contactless card presents a virtual magnetic stripe to the reader. The significant difference from a real magnetic stripe is that the virtual magnetic stripe contains a dynamic CVV (dCVV) rather than a static CVV. The dCVV is calculated using a card-stored Unique Derived Key (UDK). As for the UDKs in VSDC, this key value is unique per card and is derived from a Master Derivation Key (MDK). This is the significant difference from the calculation of a static CVV; there is also a difference in the data involved in the calculation, but this is of no consequence to the HSM processing. The algorithm is identical to that for a static CVV. Note: The IMKCVC will be used for the Visa payWave as MDK.
SafeNet, Inc.
359
CVC3_GENERATE
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
U D U U U
Attribute h h K-Spec h h
Description Function Code Function Modifier = 00 Issuer Master Key (Formats: 0 - 3, 11, 13) PAN || PAN Sequence No. = 0: IV Data contains 2-byte IVCVC3. = 1: IV Data contains Track 1 or 2 data. IVCVC or Static part of Track 1 or 2 data used to calculate IVCVC3. Unpredictable Number Application Transaction Counter Description Function Code Return Code Card Verification Code
IV Data
Var
4 2 Length 3 1 2
x x Attribute h h h
This function generates a CVC3 using the method specified in reference [41] of MarkII. Processing Steps 1. Derive KDCVC3 using IMKCVC3 and PAN Data. 2. If IV Mode = 0 IVCVC3 = IV Data If IV Mode = 1 calculate IVCVC3 using KDCVC3 and IV Data. 3. Calculate CVC3 using KDCVC3, IVCVC3, UN and ATC. 4. Return the calculated CVC3 in the response.
SafeNet, Inc.
360
CVC3_VERIFY
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
U D U U U
Attribute h h K-Spec h h
Description Function Code Function Modifier = 00 Issuer Master Key (Formats: 0 - 3, 11, 13) PAN || PAN Sequence No. = 0: IV Data contains 2-byte IVCVC3. = 1: IV Data contains Track 1 or 2 data. IVCVC or Static part of Track 1 or 2 data used to calculate IVCVC3. Unpredictable Number Application Transaction Counter Card Verification Code Description Function Code Return Code
IV Data
Var
4 2 2 Length 3 1
x x h Attribute h h
This function generates a CVC3 and compares it with the value of the transaction CVC3 provided in the request. Processing Steps 1. Calculate CVC3 identically to processing steps 1 3 in function CVC3-Generate - EE0010 2. Compare the calculated value of CVC3 with CVC3 in the request. Return the result of the comparison in the response. A Return Code of 00 indicates CVC3 verification, and a Return Code of 08 indicates verification failure.
SafeNet, Inc.
361
dCVV_GENERATE
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
U D U U U
Request Content Length EE0014 3 FM IMKCVC-Spec PAN Data CVV Data Response Content Function Code Return Code CVV 1 Var
Var
Attribute h h K-spec
h
Description Function Code Function Modifier = 00. Key specifier for IMKCVC (Formats 0 3, 11, 13) PAN || PAN Sequence No. Description = EE0014. Card Verification Value
16 Length 3 1 2
h Attribute h h h
This function generates a CVV for the virtual mag stripe data (CVV Data). FM IMKCVC-spec PAN Data CVV Data Function Modifier. Must be set to zero. A key specifier which incorporates an index to a HSM-stored double length key or a host-stored double-length key. PAN || PAN Sequence No. Length in range 6 -16 bytes, representing 12 -32 digits. The data from which the CVV is generated. It is up to the host to format the field correctly and to do any required range checking on the data. This field is normally populated in packed BCD format. The three-digit Card Verification Value. The three digits of packed BCD are left- aligned and right-padded with the hexadecimal digit F.
CVV
Note: IMKcvc key will be used as MDK(Master Derivation Key). Processing steps 1. Recover IMK using IMK-spec. 2. Derive MK (UDK) using IMK and PAN Data. (The algorithm is identical to MK Method = 00 in function EE2018.) 1. Prepare PAN Data
Length
<16 digits =16 digits >16 digits
Processing
Left-padded with zeros. Used as is. Hashed and decimalized.
SafeNet, Inc.
362
SafeNet, Inc.
363
dCVV_VERIFY
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
U D U U U
Request Content Length EE0015 3 FM IMKCVC-spec PAN Data CVV Data 1 Var
Var
Attribute h h K-spec
h
Description Function Code Function Modifier = 00. Key specifier for IMKCVC (Formats 0 3, 11, 13) PAN || PAN Sequence No. Card Verification Value Description = EE0015
16
h h Attribute h h
This function verifies the virtual mag stripe data (CVV Data), calculating a CVV for that data and comparing it with the CVV in the request. FM IMKCVC-spec PAN Data CVV Data Function Modifier. Must be set to zero. A key specifier which incorporates an index to a HSM-stored double length key or a host-stored double-length key. PAN || PAN Sequence No. Length in range 6 -16 bytes, representing 12 -32 digits. The data from which the CVV is generated. It is up to the host to format the field correctly and to do any required range checking on the data. This field is normally populated in packed BCD format. The three-digit Card Verification Value. The three digits of packed BCD are leftaligned and right-padded with the hexadecimal digit F.
CVV
Note: IMKcvc key will be used as MDK(Master Derivation Key). Processing steps 1. Recover IMKCVC using IMKCVC-spec. 2. Derive MK (UDK) using IMKCVC and PAN Data. (The algorithm is same as Function EE0014) 3. Calculate CVV1 using MK and CVV Data. (CVV1 is calculated using the method specified in reference [42] of MarkII ). 4. Compare CVV1 with CVV and return result. A Return Code of 00 indicates CVV verification, and a Return Code of 08 indicates verification failure.
SafeNet, Inc.
364
New Key
The Network Key Transfer functionality introduces the Host Tranfer Key (KHT).
SafeNet, Inc.
365
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
U D U U U
Length 1 1 Length 1 1 1
Attribute h h Attribute h h h
Description Function Code Function Modifier = 00 Description Function Code Return Code Representing Current Key Package Status = 01: Package present = 02: loading from host = 04: Not present Total Length of the Package Key Package Name CRC32 checksum of the entire Key Package
4 Var 4
h h x
This function returns the status of any Export Key Packages currently stored in the HSM. return code of zero indicates function completed successfully Key Package Status 01: Key Package is present and awaiting export 02: Key Package is only partially present as a result of incomplete IMPORT_KEY_PACKAGE sequence. 04: No Key Package is present inside the HSM 32 bit Big Endian integer total length of the Key Package variable length field, holds printable ASCII characters CRC32 checksum of the entire Key Package Algorithm TBA
rc Status
If no Key Package is present in the HSM then the rc will be zero and Status will be 4, Length=0, Name=empty and Checksum=0
SafeNet, Inc.
366
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
U D U U U
Length 1 1 1
Attribute h h H
Description Function Code Function Modifier = 00 Representing start or Continuation of this download = 01: Get Next Segment = 02: Acknowledge Offset into Key Package where this read will start Number of bytes to read Description Function Code Return Code Next segment of Package or empty (depending on control)
4 2 Length 1 1 Var
h h Attribute h h H
This function extracts the current Export Key Package out of the HSM (if any). Developers should first call the KEY_PACKAGE_STATUS function to determine if an Export Key Package is loaded and how large it is. The Key Package is a (potentially) large image that is held inside the HSM. The image is created manually by the administrator and Key Export Officer using Console operations. There is no way to create a Export Key Package from Host functions. After the image is extracted the host application may calculate and verify the CRC and then Acknowledge the successful download by calling the function with Control=Acknowledge. The HSM will respond by 1) removing the Pending flag from all HSM stored keys that are copied into the Key Package and 2) deleting the Key Package. Key Packages can be transmitted across the network and imported into a remote HSM. Control 01 get specified segment of Key Package 02 -- Acknowledge successful download This field indicates the offset from the beginning of the Key Package where the next read should start. For the first read, this field should have a value of zero. This field is ignored if Control=Acknowledge This field indicates the number of bytes to be extracted with this function call. This field is ignored if Control=Acknowledge; This field holds the segment retrieved from the Key Export image. The number of bytes extracted is indicated within the Var field, and may be less than the Length indicated in the request (e.g. end of file or buffer length limitation). The field will be empty if Control=Acknowledge
ReadOffset
Length
Package Segment
SafeNet, Inc.
367
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
U D U U U
Attribute h h h
Description Function Code Function Modifier = 00 Representing segment type = 01: First Segment = 02: Other segments
File Length/Offset Data Segment Response Content EE3104 rc Cumulative Data Length
Dual Variable A portion of the Key Package Description Function Code Return Code Length of partial saved package
Var Length 1 1 4
h Attribute h h h
This function is used to load an Export Key Package to the HSM from the host. To load the files many calls may be required. On success, the function returns a 4-byte value in cumulative length field to show the length of the file that has been received so far, and this value must be included in the File Length / Offset field in the next function call. Once the package is fully loaded the HSM will automatically begin the verification and key import operation. Depending on the size of the package it may take some time in the verification and import process. Control 01 First segment of Key Package is being presented. If a Key Package (or part of key Package) is already in the HSM then this function will cause the old package to be deleted. 02 Add this segment to the end of the Key Package. This field acts like a dual variable which holds the value of the total Key Package length when function is being called for the first time (control=1) and the Offset for other function calls (control=2). This field has a variable data length and contains the next data segment of the Key Package. On success function return 4 bytes value to show the length of the Key Package that has been received so far and this value must be included into the FileLength/Offset field of the next function call.
FileLength/Offset
DataSegment
SafeNet, Inc.
368
Part 2
______________________________________________________________________
SafeNet, Inc.
369
SafeNet, Inc.
370
ICC Initialization
Issuer Key Pair Initialization
Generate issuer key pair The issuer must generate and store an Issuer Key Pair (PI and SI). The public key and associated data must be self-signed and delivered to the Certification Authority (e.g. on diskette). Verify CA Public Key (PCA) The issuer must receive, verify and store a self-signed CA public key, and use it to verify issuer public key certificates provided by the CA. Verify Issuer Public Key certificate The issuer must verify the certificates provided by the CA (using PCA) prior to storing the certificate on an ICC.
SafeNet, Inc.
371
Verify card certificate The issuer does not usually need to verify the ICC certificate. Nevertheless, it may be beneficial to perform such verification (using PI) to confirm that an ICC is functioning correctly, prior to issue. Verify card dynamic data The issuer does not usually need to verify the dynamic data. Nevertheless, it may be beneficial to perform such verification (using PIC) to confirm that an ICC is functioning correctly, prior to issue.
Key Management
Console Operations CA Public Key CA Private Key Issuer Public Key Issuer Private Key ICC Public Key ICC Private Key PCA SCA PI SI PIC SIC generate + store generate + store generate + output generate + output generate + output generate + Host Functions input + output
SafeNet, Inc.
372
Console Operations ICC PIN Encipherment Public Key ICC PIN Encipherment Private Key Issuer Master Key PPE SPE IMKAC IMKSMI IMKSMC
IMKcvc
MKAC MKSMI MKSMC KTK enter + store + display enter + store + display
derive + output
PTK
Function Construction
Information about the construction of the host functions described in this manual can be found in the section, Host function Overview, of Chapter 1 under Part 1 of this guide.
SafeNet, Inc.
373
SafeNet, Inc.
374
Creation of a Host Stored PVK is calculated by the following Method: Left Hand Side of the Key becomes the Single Length PVK e.g. 1111111111111111 Right Hand Side of the Key becomes the Decimalization Table Value e.g. 0123456789012345
These two components are then concatenated together to form a double length DES key, and then encrypted under the appropriate KM Variant for use within a function Creation of a Host Stored PVK for format 14 is calculated by the following method: Left hand side of the key becomes the Double Length PVK e.g. 33333333333333331111111111111111 Right hand side of the key becomes the Decimalization Table value e.g. 0123456789012345
These two halves are then concatenated together to form a triple length DES key, and then encrypted under the appropriate KM Variant for use within a function
SafeNet, Inc.
375
PIN-TRANSLATEVSDC Personalization
Request Content EE0608 FM ePPKi(PIN) PPKi-Spec PFi ANB Pfo PPKo-Spec Length 3 1 8 Var 1 6 1 Var Attribute h h x K-Spec h h h K-Spec Description Function Code Function Modifier = 00, 01 Encrypted PIN block. Key specifier (Formats: 0-3,10,11,13) Input PIN Block format Account Number Block Output PIN block format PPK Key specifier (Formats: 03,10,11,13,50,51) 00 = ECB 01 = CBC 11 = Pad+CBC Data to incorporate with PIN in encrypted result. The length must be 0 or 8. Description Function Code Return Code Encrypted PIN and associated data
Encryption Method
PIN Data
Var
Length 3 1 Var
Attribute h h h
This function is similar to PIN-TRANSLATE (EE0602) but also: allows the PPKo to be specified in key specifier formats 50 and 51. Translates a PIN block, producing an encrypted PIN block that incorporates the PIN Try Counter and PIN Try Limit. Allows an additional data block, specified in PIN Data, to be appended to the plaintext PIN block prior to re-encryption. When FM=01, an additional Field (Session Method, see below for details) is incorporated into the function. If FM = 00 the function remains as per EE0602 specifies the format of the input PIN block format and supports PIN formats, 01, 03, 08, 09, 10, 11, and 13 specified in Chapter 2, of the Mark II Programmers Guide. Account Number Block, which is the rightmost 12 digits of the Primary Account Number (PAN), excluding the check digit. When FM=01 Session Method 00 ECB, 01 CBC, is invoked on ePPKo (PIN + PIN Data) PFo specifies the output PIN block format and supports PIN formats: 01, 03, 08, 09, 10, 11, 12, and 13. Information on these as well as the specific restrictions on reformatting are specified in Chapter 2, of the Mark II Programmers Guide. The following restriction applies: formats 08 (Docutel) and 11 (ISO Format 1) are valid only in the case that PFo = PFi i.e. that the clear text PIN block format is not changed. If PIN format translation is not required, PFo must be set to the same value as PFi.
FM
PFi
ANB
SafeNet, Inc.
376
Chapter 30 PIN Management Functions The key specifiers, PPKi-Spec and PPKo-Spec, may be any valid key specifier for a PPK. Consequently, the function supports all combinations of single-length and double-length, HSM-stored and host-stored keys. For example, the input key could be a single-length, host-stored key and the output key could be a double-length, HSM stored key.
Encryption Method Used when FM = 01. Encryption Method encrypts ePPKo(PIN + PIN Data) as per selected method. 00 = ECB, 01 = CBC,11=Pad+CBC. ePPKo (PIN+PIN Data) PIN Data Variable length field of either 8 or 16 bytes dependent upon length of PIN Data supplied.
Data to incorporate with PIN in encrypted result. The data block would typically incorporate the PIN Try Counter and PIN Try Limit, as specified in reference [29] of CI, but no checks are applied to the data content. The field can contain 0 or 8 bytes. If the length is 0, this function performs identically to the PIN_TRANSLATE function. If the length is 8, the data block is concatenated to the right of the (re-)formatted, plaintext PIN block and the resulting 16-byte character sequence is CBC-encrypted using the PPKo.
The function will fail with Error Code 78 if PFi or PFo indicates a PIN block format that is disabled.
Note: The Session Method field has been renamed as Encryption Method.
For Encryption Method = 11, the PIN block will be padded as shown in following table. The 16- or 24-byte plaintext padded block will be encrypted using the CBC mode of operation. This will produce a 16- or 24-byte encrypted PIN block, which will be returned in the Var field in the response. Length (bytes) Content 1 0x08 or 0x10 8/16 PIN + PIN Data 1 0x80 6 00 00 00 00 00 00
extern C EXPORT int EFT_EE0608_PIN_Translate_VSDC_2( IN UCHAR FM, IN UCHAR ePPKi_PIN[8], IN KEYSPEC *PPKi, IN UCHAR PFi, IN UCHAR ANB[6], IN UCHAR PFo, IN KEYSPEC *PPKo, IN UCHAR Encryption_Method, IN EFTBUFFER *PIN_Data,
SafeNet, Inc.
377
SafeNet, Inc.
378
Key Types
The HSM supports multiple RSA key types, as follows: Key Type Certificate Data Signature Key Transport PIN Encryption The EE2040, EE2048 and EE2058 functions set the appropriate key type for a key. Other functions check that the supplied key is of the appropriate key type. Sign data Decrypt encrypted key Private Key Processing Public Key Processing Verify certificate Verify signed data Encrypt key
SafeNet, Inc.
379
Var
K-Spec
This function generates an issuer key pair and returns the keys for host storage. Function modifier Key Length Exponent User Data Reserved for possible future use; must be set to zero. Modulus size in bytes for input to the PK/SK generation process. Variable length exponent type for input to the PK/SK generation process. Field length before prefix byte is 1 or 3. Variable length user data for input to the PK/SK generation process. User data is inserted into the clear PK and clear component of the SK. When no User data is being supplied, this field is 1 byte in length with value of zero to represent a zero length variable field. 00 indicates that the generation has completed successfully. The PI-Spec and SI-Spec fields are present as described below. 3A indicates that the generation has not yet completed. The generation of the key pair may take a few seconds to complete. The EE2040 request should be re-issued periodically (every 3 seconds) until either 00 (success) or non-zero-value-other-than-3A (failure) return code has been received. The PI-Spec and SI-Spec fields are not present. Non-zero-value-other-than-3A indicates failure. Refer to Appendix I Error Codes in this guide for further details. The PI-Spec and SI-Spec fields are not present. PI-Spec SI-Spec Key specifier for the Issuer Public Key (format 81). The Key specifier describes the complete Issuer PK. Key specifier for the Issuer Private Key (format 82). The Key specifier describes the complete Issuer SK. The encrypted component of SK, eKMv20(SK), is encrypted using KM variant 20.
Return Code
Processing steps 4. Generate an RSA key pair of the specified length and with the specified public exponent.
SafeNet, Inc.
380
5. Return the generated keys. Function usage The function may be used as an alternative to the equivalent console operation. If the console operation is used, the key pair will be stored in HSM secure memory.
SHP Toolkit CI extern "C" EXPORT int EFT_EE2040_GenerateIssuerKeyPair( IN UCHAR FM, IN USHORT key_len, IN EFTBUFFER *exponent, IN EFTBUFFER *user_data, OUT OUT KEYSPEC KEYSPEC *PK_Spec, *SK_Spec);
SafeNet, Inc.
381
PI-Spec
Var
K-Spec
ID of Certificate Subject Certificate Expiry Date Certificate Serial Number Hash Algorithm Indicator Issuer Public Key Index Response Content EE2041 rc Issuer Public Key Length Issuer Public Key Exponent Length Leftmost Digits of Issuer Public Key Issuer Public Key Remainder Issuer Public Key Exponent Issuer Public Key Certificate Issuer Public Key Check Sum
h h h h h Attribute h h h h h h h h
20
This function creates the 'Self-certified Issuer Public Key', as described in reference [17] of Card Issuance. It confirms that the provided public and private keys form a valid key pair, by verifying the self-certified public key. The function returns the certificate and other public key data, in the format required for providing to the CA. It also returns the calculated hash-code, for sending separately to the CA. SI-Spec Key specifier for the Issuer Private Key SK (formats 0 - 3, 82). The Key specifier in formats 0 - 3 describes the location of the key to be loaded
SafeNet, Inc.
382
Chapter 31 Card Issuer Functions from the ESM. The Key specifier in format 82 describes the complete Issuer SK.
PI-Spec
Key specifier for the Issuer Public Key (formats 0 - 3, 81). The Key specifier in formats 0 - 3 describes the location of the key to be loaded from the ESM. The Key specifier in format 81 describes the complete Issuer PK. Specified in Tables 3-1 and 3-2 of [17]. Specified in Tables 3-1 and 3-2 of [17]. Specified in Tables 3-1 and 3-2 of [17]. Specified in Tables 3-1 and 3-2 of [17]. Specified in Tables 7-2 of [17]. Contains zero for success. Variable length Issuer PK modulus length. 1 byte, valid length values are 1 and 3. Variable length field to represent Issuer PK modulus length. As in Tables 3-1 and 3-2 of Ref [17]. IPK remainder. As in Tables 3-1 and 3-2 of Ref [17]. Variable length field. Valid values are value=3 (length=1) and 16 value=2 +1 (length=3). As in Tables 3-1 and 3-2 of Ref [17]. As in Tables 3-1 and 3-2 of Ref [17].
ID of Certificate Subject Certificate Expiry Date Certificate Serial Number Hash Algorithm Indicator Issuer Public Key Index Return Code Issuer Public Key Length Issuer Public Key Exponent Length Leftmost Digits of Issuer Public Key Issuer Public Key Remainder Issuer Public Key Exponent Issuer Public Key Certificate Issuer Public Key Checksum
Processing steps 1. Build the data block to be included in the hash calculation, as specified in Tables 3-1 and 3-2 of [17], using the appropriate fields provided in the request and the public key specified by PK-Spec The following fixed values fields will also be incorporated into the data block: Certificate Format = 11 (hex); Issuer Public Key Algorithm Indicator = 01 (hex). 2. Calculate the hash result. [Currently, SHA-1 is the only approved hash algorithm, and is indicated in Hash Algorithm Indicator by a value of hex '01'.] 3. Truncate the data block, append the hash result, and add the data header and trailer to form the block to be signed. 4. Calculate Issuer Public Key Certificate by signing the block to be signed, using the private key specified in SK-Spec. 5. Confirm that SK and PK constitute a key pair, by using PK to recover the data block from Certificate and comparing the recovered data block with the original. Return an error if they do not. 6. Calculate the Issuer Public Key Check Sum, using ID of Certificate Subject, Issuer Public Key Index and the public key specified by PK-Spec, in accordance with Chapter 7 of [17].
SafeNet, Inc.
383
Function usage The function is used to create the Self-certified Issuer Public Key and associated Issuer Public Key Check Sum that is required to be sent to the Europay-MasterCard CA in order to obtain an Issuer Certificate. SHP Toolkit CI extern "C" EXPORT int EFT_EE2041_SelfCertIssuerPublicKey( IN UCHAR FM, IN KEYSPEC *SK_Spec, IN KEYSPEC *PK_Spec, IN UCHAR cert_subject_id[4], IN UCHAR cert_exp_date[2], IN UCHAR cert_serial_no[3], IN UCHAR hash_alg_indicator, IN UCHAR Iss_PK_index[3], OUT OUT OUT OUT OUT OUT OUT UCHAR UCHAR EFTBUFFER UCHAR EFTBUFFER EFTBUFFER UCHAR *Iss_PK_len, *Iss_PK_exp_len, *PK_left_digits, PK_remainder[36], *PK_exponent, *PK_certificate, PK_check_sum[20]);
SafeNet, Inc.
384
h h h D-Spec h h Attribute h h h h
PCA-Spec
Var
K-Spec
This function verifies the Self-certified Europay-MasterCard Public Key, as described in chapter 4 of [17]. It provides the public key for host storage, and the recovered certificate data for further processing by the host. Function Modifier ID of Certificate Subject CA Public Key Index CA Public Key Algorithm Indicator Leftmost Digits of CA Public Key CA Public Key Reserved for possible future use; must be set to zero. Specified in Tables 3-1 and 3-2 of [17]. Specified in Tables 4.1 and 7-1 of [17]. As in Tables 3-1 and 3-2 of Ref [17]. Currently specified as RSA value 01. Left-most digits of CA PK modulus. Variable length equal to (C_modLen - 32 - CERT_ID_LEN) or modulus length. Only present if CA PK (modulus length > (C_modLen - 32 CERT_ID_LEN). Variable length field, length is (C_modLen - 32 -
SafeNet, Inc.
385
Chapter 31 Card Issuer Functions CERT_ID_LEN) otherwise is length 1 with value 0. As in Tables 3-1 and 3-2 of Ref [17]. As in Tables 3-1 and 3-2 of Ref [17]. As in Tables 3-1 and 3-2 of Ref [17]. As in Tables 3-1 and 3-2 of Ref [17]. EMV currently specify the Hash Algorithm as SHA-1 value 01. Variable length user data for input to the PK/SK generation process. User data is inserted into the clear PK and clear component of the SK. When no User data is being supplied, this field is 1 byte in length with value of zero to represent a zero length variable field. The recovered CA PK data as in Tables3.1/3.2 of Ref [17].
Remainder CA Public Key Exponent CA Public Key Certificate CA Public Key Checksum Hash Algorithm Indicator User Data
Certificate Data
Processing steps 1. Verify the 'Self-certified Europay-MasterCard Public Key', as described in chapter 4 of [17]. 2. Build PCA-Spec, using CA Public Key Modulus and CA Public Key Exponent. 3. Provide the data block recovered from Certificate in Certificate Data. Function usage The function is used to verify and store a CA public key received from Europay or MasterCard. SHP Toolkit CI extern "C" EXPORT int EFT_EE2042_VerifyCAPublicKeyMC( IN UCHAR FM, IN UCHAR ID_cert_subject[5], IN UCHAR PK_index, IN UCHAR PK_alg_indicator, IN EFTBUFFER *PK_left_digits, IN UCHAR PK_remainder[37], IN EFTBUFFER *PK_exp, IN EFTBUFFER *PK_cert, IN EFTBUFFER *PK_checksum, IN UCHAR hash_alg_indicator, IN EFTBUFFER *user_data, OUT OUT OUT UCHAR EFTBUFFER KEYSPEC *validation_result, *cert_data, *PK);
SafeNet, Inc.
386
Var
K-Spec
h h h
Length 3 1 1 Var
Attribute h h h h
This function verifies the signature, form, and content of an Issuer Public Key Certificate. Function Modifier PCA-Spec PI-Spec Reserved for possible future use; must be set to zero. Key specifier for the CA Public Key (Format 81). The Key specifier describes the complete CA PK. Key specifier for the Issuer Public Key (Formats 0 - 3, 81). The Key specifier in formats 0 - 3 describes the location of the key to be loaded from the ESM. The Key specifier in format 81 describes the complete Issuer PK. Used to validate the recovered certificate data from the CA PK. Used to validate the recovered certificate data from the CA PK. As in tables Table 3.1/3.2 of Ref [17] Contains zero for success. 1 byte representing the result of validation tests on the certificate. Value 1 when validation failed, otherwise value 0. Variable length certificate data recovered from the CA PK.
Issuer Public Key Remainder Issuer Public Key Exponent Issuer Public Key Certificate Return Code Verify Flag Certificate Data
SafeNet, Inc.
387
Processing steps 1. Validate the certificate and recover the Issuer Public Key. 2. Provide the recovered certificate data block. Function usage The Issuer Public Key Certificate is stored for subsequent transfer to an ICC. SHP Toolkit CI extern "C" EXPORT int EFT_EE2043_VerifyIssuerPKCertMC( IN UCHAR FM, IN KEYSPEC *CA_PK_Spec, IN KEYSPEC *Iss_PK_Spec, IN EFTBUFFER *Iss_PK_rem, IN EFTBUFFER *PK_exp, IN EFTBUFFER *PK_cert, OUT OUT UCHAR EFTBUFFER *validation_result, *cert_data);
SafeNet, Inc.
388
PI-Spec
Var
K-Spec
15
Hash Algorithm Indicator Issuer's Public Key Algorithm Indicator Response Content EE2044 rc Signature
1 1 Length 3 1 Var
h h Attribute h h H
Hash Result
20
This function creates the 'Self-Signed Issuer Public Key Data', as described in 3.2.3.2 of [18]. It confirms that the provided public and private keys form a valid key pair, by verifying the selfsigned public key. Function Modifier SI-Spec Reserved for possible future use; must be set to zero. Key specifier for the Issuer Private Key SK (formats 0 - 3, 82). The Key specifier in formats 0 - 3 describes the location of the key to be loaded from the ESM. The Key specifier in format 82 describes the complete Issuer SK. Key specifier for the Issuer Public Key (Formats 0 - 3, 81). The Key specifier in formats 0 - 3 describes the location of the key to be loaded from the ESM. The Key specifier in format 81 describes the complete Issuer PK. As in Table 3.3 of Ref [[18] Currently specified as SHA-1 value 01. Currently specified as RSA value 01.
PI-Spec
General Public Key Data Hash Algorithm Indicator Issuer's Public Key Algorithm Indicator
SafeNet, Inc.
389
Contains zero for success. The returned variable length signature as in 3.2.3.2 of Ref [18].
Processing steps 1. Build the data block to be included in the hash calculation using: General Public Key Data, the algorithm indicators and the public key specified by PK-Spec. Calculate the hash result. 2. Truncate the data block and append the hash result, to form the block to be signed. 3. Calculate Signature by signing the block to be signed, using the private key specified in SKSpec. 4. Confirm that SK and PK constitute a key pair, by using PK to recover the data block from Signature and comparing the recovered data block with the original. Return an error if they do not. Function usage The function is used to obtain the 'Self-Signed Issuer Public Key Data' that is required to be sent to the Visa CA in order to obtain an Issuer Certificate. SHP Toolkit CI extern "C" EXPORT int EFT_EE2044_SelfSignIssuerPKVisa( IN UCHAR FM, IN KEYSPEC *Iss_SK_Spec, IN KEYSPEC *Iss_PK_Spec, IN UCHAR Gen_PK_Data[15], IN UCHAR hash_alg_indicator, IN UCHAR Iss_PK_ind, OUT _OUT EFTBUFFER UCHAR *signature, HashResult[20]);
SafeNet, Inc.
390
h Attribute h h K-Spec
Var
This function validates the 'Self-Signed Visa CA Public Key Certificate, as described in 3.4 of [18]. It provides the public key for host storage, and the recovered certificate data for further processing by the host. Function Modifier Visa CA Public Key Algorithm Indicator Registered Application Provider Identifier (RID) Visa CA Public Key Index Visa CA Public Key Modulus Visa CA Public Key Exponent Hash Result Certificate Reserved for possible future use; must be set to zero. Currently specified as RSA value 01. As in Tables 3-1 and 3-2 of Ref [17].
As in Tables 3-1 and 3-2 of Ref [17]. As in Tables 3-1 and 3-2 of Ref [17]. As in Tables 3-1 and 3-2 of Ref [17]. As in Tables 3-1 and 3-2 of Ref [17]. As in Tables 3-1 and 3-2 of Ref [17].
SafeNet, Inc.
391
User Data
Variable length user data for input to the PK/SK generation process. User data is inserted into the clear PK and clear component of the SK. When no User data is being supplied, this field is 1 byte in length with value of zero to represent a zero length variable field. Contains zero for success.
Return Code
PCA-Spec
Certificate Data
Key specifier for the CA Public Key (format 81). The Key specifier describes the complete CA PK.
As in table 3-10 of Ref [18].
Processing steps 1. Validate the Visa CA Public Key, as specified in steps 1 4 of 3.4.4 of [18] 2. Build PCA-Spec, using Visa CA Public Key Modulus and Visa CA Public Key Exponent. 3. Provide the data block recovered from Certificate in Certificate data. Function usage The function is used to validate and store a CA public key received from Visa.
SHP Toolkit CI
extern "C" EXPORT int EFT_EE2045_VerifyCAPKVisa( IN UCHAR FM, IN UCHAR CA_PK_alg_indicator, IN UCHAR RID[5], IN UCHAR CA_PK_index, IN EFTBUFFER *CA_PK_modulus, IN EFTBUFFER *CA_PK_exp, IN UCHAR hash_data[20], IN EFTBUFFER *CA_PK_cert, IN EFTBUFFER *user_data, OUT OUT KEYSPEC EFTBUFFER *CA_PK_Spec, *cert_data);
SafeNet, Inc.
392
Var
K-Spec
h h h Attribute h h h h
This function verifies the signature, form, and content of an Issuer Public Key Certificate (CERI). It provides the recovered certificate data for any further host checking. Function Modifier PCA-Spec PI-Spec Reserved for possible future use; must be set to zero. Key specifier for the CA Public Key (Format 81). The Key specifier describes the complete CA PK. Key specifier for the Issuer Public Key (Formats 0 - 3, 81). The Key specifier in formats 0 - 3 describes the location of the key to be loaded from the ESM. The Key specifier in format 81 describes the complete Issuer PK. 36 least most significant bytes of the Issuer PK modulus. Variable length field. Valid values are value = 3 (length = 1) and value 16 = 2 +1 (length = 3). Variable length field Issuer PK certificate. Contains zero for success. 1 byte representing the result of validation tests on the certificate. Value 1 when validation failed, otherwise value 0. Variable length certificate data recovered from the CA PK.
IPK Modulus Remainder IPK Exponent CERI Return Code Verify Flag Certificate Data
Processing steps 1. Validate the certificate and recover the Issuer Public Key, as specified in 5.3 of [5], and provide the result in Verify Flag. 2. Provide the recovered certificate data block in Certificate Data.
SafeNet, Inc.
393
Function usage The Issuer Public Key Certificate is stored for subsequent transfer to an ICC. SHP Toolkit CI extern "C" EXPORT int EFT_EE2046_VerifyIssuerPKCertVisa( IN UCHAR FM, IN KEYSPEC *Pca, IN KEYSPEC *Pi, IN EFTBUFFER *IPK_modulus_rem, IN EFTBUFFER *IPK_exp, IN EFTBUFFER *IPK_cert, OUT OUT UCHAR EFTBUFFER *validation_result, *cert_data);
SafeNet, Inc.
394
Var Var
h h
Length 3 1
Attribute h h
This function validates the Issuer Public Key Detached Signature, as described in 3.3.3.3 of [18]. Processing steps 1. Validate the Detached Signature according to 3.3.3.3 of [18]. Function Modifier PCA-Spec Detached Signature Hash Data Return Code Reserved for possible future use; must be set to zero. Key specifier for the CA Public Key (Format 81). The Key specifier describes the complete CA PK. Variable length detached signature to be verified. Variable length hash data (SHA-1) used to verify the detached signature. Returns the result of validation tests for the Visa Detached Signature. Contains value zero to represent validation was successful.
SHP Toolkit CI extern "C" EXPORT int EFT_EE2047_VerifyDetachedCertVisa( IN UCHAR FM, IN KEYSPEC *Pca, IN EFTBUFFER *detached_signature, IN EFTBUFFER *hash_data);
SafeNet, Inc.
395
Var
K-Spec
Var
Var 1 1
K-Spec h h
User Data Response Content EE2048 rc eKKTK(mod of Sxx) or eKKEK(mod of Sxx) or eKKEK(len | mod of Sxx | padding)
h Attribute h h h
Var
SafeNet, Inc.
396
Var Var
h K-Spec
As specified in Table 7 in [5]. Key Specifier for Pxx Key Type = Data Signature, PIN Encryption (Format: 81)
This function generates an ICC key pair (PIC / SIC or PPE / SPE) and calculates the digital signature for the ICC Public Key Certificate. The key pair may be used in Dynamic Data Authentication and / or PIN Encipherment. Note: In this description, the subscript 'XX' is used to denote either 'IC' or 'PE'. Function Modifier If set to 0, format of mod of S is (mod of S ) xx xx If set to 1, format of mod of S is (len : mod of S : padding)
xx xx
When FM=2, padding method shall be followed as specified in [33] SI-Spec Key specifier for the Issuer Private Key SK (Formats 0 - 3, 82). The Key specifier in formats 0 - 3 describes the location of the key to be loaded from the ESM. The Key specifier in format 82 describes the complete Issuer SK. Variable length ICC PK certificate data as specified by EMV. Used to build the signature together with the generated SK Key specifier for the Key Transport Key (KTK) (Formats 0 - 3, 13, 50. Encrypted with KMV35). ECB and CBC encryption methods represented using 00 or 01 respectively. 1 byte flag to represent whether to return a built PK Key specifier. Variable length user data for input to the PK/SK generation process. User data is inserted into the clear PK and clear component of the SK. When no user data is being supplied, this field is 1 byte in length with a value of zero to represent a zero length variable field. Contains zero for success. The return encrypted modulus of Sxx. If FM = 1 or FM = 2, the encrypted block containing a 1 byte length concatenated with the modulus of Sxx concatenated with 7 bytes of padding, will be returned.
Return Code eKTK(mod of Sxx) or eKKEK(mod of Sxx) or eKKEK(len | mod of Sxx | padding) eKTK(exp of Sxx) or eKKEK(exp of Sxx) or eKKEK(len | exp of Sxx | padding) ICC Public Key Certificate ICC Public Key Remainder PXX
The return encrypted exponent of Sxx. If FM = 1, the encrypted block containing a 1 byte length concatenated with the exponent of Sxx concatenated with padding bytes returned.
Signature for the ICC PK certificate. Variable length right-most digits of the ICC PK. Only present when (ICC_modLen > (ISS_modLen - 42)). Length equals (ICC_modLen (ISS_ModLen + 42)) or 1 (value=0, when no remainder present). Key specifier for the return Public Key (Format 81). The Key specifier describes the complete PK. The return PK Key specifier is only present
SafeNet, Inc.
397
Processing steps 1. Generate the ICC Public Key (PXX) and ICC Private Key (SXX), with a modulus of length NXX as specified in ICC Public Key Length in Certificate Data. The ICC Public Key Exponent is as specified in Certificate Data. 2. Insert the generated ICC Public Key modulus into Certificate Data. 3. Calculate the hash result for the Certificate Data using the hash algorithm indicated by Hash Algorithm Indicator in Certificate Data. [Currently, SHA-1 is the only approved hash algorithm, and is indicated by a value of hex '01'.] 4. Build the signature block using the calculated hash result and the leftmost bytes of Certificate Data, as defined in A2.1.2 in [5]. 5. Sign the signature block using SI and its associated asymmetric algorithm. [Currently, RSA is the only approved asymmetric algorithm.] 6. Return the signature in ICC Public Key Certificate. 7. Return the rightmost part of the ICC Public Key modulus in ICC Public Key Remainder. 8. Encrypt the ICC Private Key using the KEK specified by KEK-Spec and using the specified Encryption Method. Return the result in eKTK(mod of SIC) and eKTK(exp of SIC). If KTK-Spec incorporates a format 50 key specifier, the private key is returned encrypted by the derived key KKEK. 9. If indicated by PXX Flag, return PXX in a format 81 key specifier. Function usage The function is for use during card initialization: the public key certificate and the encrypted private key would be passed subsequently to the card personalization system. In addition to being provided in a certificate, PXX can optionally be provided in a key specifier, for subsequent use during testing of the card. SHP Toolkit CI extern "C" EXPORT int EFT_EE2048_GenerateICCKeypair( IN UCHAR FM, IN KEYSPEC *SK, IN EFTBUFFER *cert_data, IN KEYSPEC *KTK, IN UCHAR enc_method, IN UCHAR Pxx_flag, IN EFTBUFFER *user_data, OUT OUT OUT OUT OUT EFTBUFFER EFTBUFFER EFTBUFFER EFTBUFFER KEYSPEC *eK_SK_mod, *eKTK_SK_exp, *ICC_PK_cert, *ICC_PK_rem, *PK_Spec);
SafeNet, Inc.
398
Var
K-Spec
Var
Var 1 1
K-Spec H H
User Data Response Content EE2058 rc eK(P) eK(Q) eK(PQ) eK(DP1) eK(DQ1)
H Attribute H H H H H H H
Var
SafeNet, Inc.
399
Pxx
Var
K-Spec
Key Specifier for Pxx Key Type = Data Signature, PIN Encryption (Format: 81)
This function generates the CRT parameters and calculates the digital signature for the ICC Public Key Certificate. Note: 1. In this description, the subscript 'XX' is used to denote either 'IC' or 'PE'. 2. If the length of the modulus is not a multiple of 128 bits (16 bytes) then the CRT parameters will not be a multiple of 64 bits in length, and so will require padding prior to encryption. Ex - If modulus length is 1984 bits then the CRT parameters comprising 992 bits (124 bytes), will be padded to left with 4 bytes of zeroes.
Function Modifier
If set to 0, format of mod of S is (mod of S ) xx xx If set to 1, format of mod of S is (len : mod of S : padding)
xx xx
When FM=2, padding method shall be followed as specified in [33]. SI-Spec Key specifier for the Issuer Private Key SK (Formats 0 - 3, 82). The Key specifier in formats 0 - 3 describes the location of the key to be loaded from the ESM. The Key specifier in format 82 describes the complete Issuer SK. Variable length ICC PK certificate data as specified by EMV. Used to build the signature together with the generated SK Key specifier for the Key Transport Key (KTK) (Formats 0 - 3, 13, 50. Encrypted with KMV35). ECB and CBC encryption methods represented using 00 or 01 respectively. 1 byte flag to represent whether to return a built PK Key specifier. Variable length user data for input to the PK/SK generation process. User data is inserted into the clear PK and clear component of the SK. When no user data is being supplied, this field is 1 byte in length with a value of zero to represent a zero length variable field. Contains zero for success. The return encrypted CRT parameters. If FM = 1 or 2, the encrypted block containing a 1 byte length concatenated with the modulus of Sxx concatenated with 7 bytes of padding, will be returned. When FM=2, padding method shall be followed as specified in [33]
Return Code eK(P) eK(Q) eK(PQ) eK(DP1) eK(DQ1) ICC Public Key Certificate ICC Public Key Remainder PXX
Signature for the ICC PK certificate. Variable length right-most digits of the ICC PK. Only present when (ICC_modLen > (ISS_modLen - 42)). Length equals (ICC_modLen (ISS_ModLen + 42)) or 1 (value=0, when no remainder present). Key specifier for the return Public Key (Format 81). The Key specifier describes the complete PK. The return PK Key specifier is only present when PXX flag = 1.
SafeNet, Inc.
400
If S = md mod n, where m is the data to be signed, d is the private key exponent, and n is private key modulus composed of two prime numbers p and q then P, Q, PQ, DP1 and DQ1 will be: P, the prime factor p Q, the prime factor q. PQ = q-1 mod p DP1 = d mod (p - 1) DQ1 = d mod (q - 1) When all five components (P, Q, PQ, DP1and DQ1) of the key are set, the key is initialized and ready for use.
Processing steps 1. Generate the ICC Public Key (PXX) and ICC Private Key (SXX), with a modulus of length NXX as specified in ICC Public Key Length in Certificate Data. The ICC Public Key Exponent is as specified in Certificate Data. 2. Insert the generated ICC Public Key modulus into Certificate Data. 3. Calculate the hash result for the Certificate Data using the hash algorithm indicated by Hash Algorithm Indicator in Certificate Data. [Currently, SHA-1 is the only approved hash algorithm, and is indicated by a value of hex '01'.] 4. Build the signature block using the calculated hash result and the leftmost bytes of Certificate Data, as defined in A2.1.2 in [5]. 5. Sign the signature block using SI and its associated asymmetric algorithm. [Currently, RSA is the only approved asymmetric algorithm.] 6. Return the signature in ICC Public Key Certificate. 7. Return the rightmost part of the ICC Public Key modulus in ICC Public Key Remainder. 8. Encrypt the CRT parameters using the KEK specified by KEK-Spec and using the specified Encryption Method. Return the result in eKTK(P), eKTK(Q), eKTK(PQ), eKTK(DP1) and eKTK(DQ1). If KTK-Spec incorporates a format 50 key specifier, the CRT parameters are returned encrypted by the derived key KKEK. 9. If indicated by PXX Flag, return PXX in a format 81 key specifier. SHP Toolkit CI extern "C" EXPORT int EFT_EE2058_GENERATE_ICC_CRT_KEYPAIR(
IN IN IN IN IN IN IN OUT OUT OUT OUT OUT OUT OUT OUT UCHAR KEYSPEC EFTBUFFER KEYSPEC UCHAR UCHAR EFTBUFFER EFTBUFFER EFTBUFFER EFTBUFFER EFTBUFFER EFTBUFFER EFTBUFFER EFTBUFFER KEYSPEC FM, *SK, *cert_data, *KTK, enc_method, Pxx_flag, *user_data, *P, *Q, *PQ, *DP1, *DQ1, *ICC_PK_cert, *ICC_PK_remainder, *PK );
SafeNet, Inc.
401
ICC Public Key Certificate ICC Public Key Remainder ICC Public Key Exponent Static Data to be Authenticated Response Content EE2049 rc Pxx-Spec
Var
h h h Attribute h h K-Spec
This function verifies an ICC Certificate for PIC or PPE. It also returns the public key for subsequent use in verifying a DDA signature or encrypting a PIN. Function Modifier PI-Spec ICC Public Key Certificate ICC Public Key Remainder ICC Public Key Exponent Static Data to be Authenticated User Data Reserved for possible future use; must be set to zero. Key specifier for the Issuer Public Key (Formats 0 - 3, 81). Signature for the ICC PK certificate. Variable length right-most digits of the ICC PK. Only present when (ICC_modLen > (ISS_modLen - 42)). Length equals (ICC_modLen (ISS_ModLen + 42)) or 1 (value=0, when no remainder present). Variable length ICC PK exponent Valid values are value = 3 (length = 16 1) and value = 2 +1 (length = 3). Variable length static data to be authenticated. Variable length user data for input to the PK/SK generation process. User data is inserted into the clear PK and clear component of the SK. When no User data is being supplied, this field is 1 byte in length with value of zero to represent a zero length variable field. Contains zero for success. Key specifier for the return Public Key (Format 81). The Key specifier describes the complete PK.
Processing Steps 1. Validate the ICC Public Key Certificate according to Table 7 in [5].
SafeNet, Inc.
402
SHP Toolkit CI extern "C" EXPORT int EFT_EE2049_VerifyICCCertificate( IN UCHAR FM, IN KEYSPEC *PK, IN EFTBUFFER *ICC_PK_cert, IN EFTBUFFER *ICC_PK_rem, IN EFTBUFFER *ICC_PK_exp, IN EFTBUFFER *static_data, IN EFTBUFFER *user_data, OUT KEYSPEC *PK_Spec);
SafeNet, Inc.
403
8 Var 1
h K-Spec h
1 Length 3 1 16/24
h Attribute h h h
Var
This function derives a unique-per-card, 16-byte, ICC Master Key. Depending on the type of IMK referenced, the derived key may be one of the following: MKAC, MKSMI, MKSMC or MKIDN. Although the derivation method provided in the EMV2000 specification [5] is not mandated, the payment system specifications all incorporate that same method. Therefore, this function is appropriate for Europay, MasterCard or Visa implementations. Function Modifier IMK-Spec IMK Type PAN Data KTK-Spec Encryption Method Return Code eKTK(MK) eKKEK(MK) KVC(MK) Processing steps Reserved for possible future use; must be set to zero. Key specifier for the Issuer Master Key (Formats 0 3, 11. 13). The Key specifier describes the location of the key to be loaded from the ESM. 1 byte flag to represent the Issuer Master Key sub-type. PAN data, used to derive MK, which is then used with KTK to produce eKTK(MK). Key specifier for the Key Transport Key (KTK) (Formats 0 - 3, 13, 50,51). ECB , CBC , CBC with padding encryption methods represented using 00 , 01 or 11 respectively. Contains zero for success. The return KTK-encrypted MK. The return derived KKEK-encrypted MK. The return Key Verification Code (KVC) computed for the MK.
SafeNet, Inc.
404
1. Calculate the ICC Master Key (MK) using the Issuer Master Key and supplied PAN Data, according to the method specified in A1.4 of [5]. 2. Encrypt MK with KTK or the derived KKEK using the method specified by Encryption Method. If KTK-Spec incorporates a format 50 key specifier, the MK is returned encrypted by the derived key KKEK. 3. Calculate the KVC for MK and return in kvc(MK). For Encryption Method = 11, the derived key will be padded as shown in following table. The 24byte plaintext padded block will be encrypted using the CBC mode of operation. This will produce a 24-byte encrypted key which will be returned in the response. Length (bytes) Content 1 0x10 16 Derived Master Key 1 0x80 6 00 00 00 00 00 00
Function usage The function is called during card initialization: the encrypted key would be passed to the card personalization system.
SHP Toolkit CI extern "C" EXPORT int EFT_EE204A_DeriveICCMasterKey( IN UCHAR FM, IN KEYSPEC *IMK, IN UCHAR SC, IN UCHAR PAN[8], IN KEYSPEC *KTK, IN UCHAR enc_method, IN UCHAR KVC_method, OUT OUT UCHAR EFTBUFFER eKTK_MK[24], *KVC_MK);
SafeNet, Inc.
405
1 1 2
h h h
h Attribute h h h
Static Data to be authenticated. Description Function Code Return Code Digital signature for the Static Application Data. The field length will be equal to the length NI of the modulus of SI
This function calculates a digital signature for the ICC Static Application Data using an Issuer Private Key. The function request fields provide all the variable data fields that form the Static Application Data to be signed, as specified in Table 2 in [5]. Function Modifier SI-Spec Signed Data Format Hash Algorithm Indicator Data Authentication Code Static Data to be Authenticated Return Code Signed Static Application Data Reserved for possible future use; must be set to zero. Key specifier for the Issuer Private Key (Formats 0 - 3, 82). EMV currently specify the signed data format value 03. EMV currently specify the Hash Algorithm as SHA-1 value 01. Issuer assigned 2 byte code. Variable length static data to be authenticated. Contains zero for success. The variable length return signed static application data.
Processing steps 1. Build the Static Application Data using the request fields and the appropriate Pad Pattern. 2. Calculate the hash result for the Static Application Data using the hash algorithm indicated by Hash Algorithm Indicator. [Currently, SHA-1 is the only approved hash algorithm, and is indicated by a value of hex '01'.] 3. Build the signature block using the calculated hash result and the leftmost bytes of the Static Application Data, as defined in A2.1.2 in [5].
SafeNet, Inc.
406
4. Sign the signature block using SI and its associated asymmetric algorithm. [Currently, RSA is the only approved asymmetric algorithm.] 5. Return the signature in Signed Static Application Data. Function usage The function is for use during ICC initialization: the Static Application Data and corresponding digital signature would be passed subsequently to the card personalization system. SHP Toolkit CI extern "C" EXPORT int EFT_EE204B_SignICCStaticData( IN UCHAR FM, IN KEYSPEC *SK, IN UCHAR SDF, IN UCHAR hash_alg_indicator, IN UCHAR data_auth_code[2], IN EFTBUFFER *static_data, OUT EFTBUFFER *signature);
SafeNet, Inc.
407
Var Var
h h
Length 3 1 1
Attribute h h h
1 1 2
h h h
This function verifies an ICC's Static Data and the associated digital signature, using an Issuer Public Key. Data recovered from the signature block is returned in the response. Function Modifier PI-Spec Static Data to be Authenticated Signed Static Application Data Return Code Reserved for possible future use; must be set to zero. Key specifier for the Issuer Public Key (Formats 0 - 3, 81). Variable length static data to be authenticated. Used to build the static application data. Variable length signed static application data. Used to validate the recovered signature from the Issuer PK. Contains zero for success.
SafeNet, Inc.
408
Verify Flag Signed Data Format Hash Algorithm Indicator Data Authentication Code
1 byte length to represent result of validation test on the recovered signed application data. Recovered from the signed data and PK values. EMV currently specify the signed data format value 03. Recovered from the signed data and PK values. EMV currently specify the Hash Algorithm as SHA-1 value 01. Recovered from the signed data and PK values.
Processing steps 1. Obtain the Recovered Data, using the Signed Static Application Data with PI and its associated asymmetric algorithm. [Currently, RSA is the only approved asymmetric algorithm.] 2. Check the values of the Recovered Data Header, Recovered Data Trailer, Signed Data Format and Hash Algorithm Indicator. 3. Build the Static Application Data using the Static Data to be Authenticated request field and fields extracted from the Recovered Data. 4. Calculate the hash result for the Static Application Data using the hash algorithm indicated by Hash Algorithm Indicator in the Recovered Data. [Currently, SHA-1 is the only approved hash algorithm, and is indicated by a value of hex '01'.] 5. Compare the calculated hash result with the Hash Result field in the Recovered Data. If the two hash results are identical, then the signature is verified. Function usage Verification of the signature (i.e. data authentication) is generally performed by the terminal. This function may be used by a card issuer wishing to test a card prior to issue. SHP Toolkit CI extern "C" EXPORT int EFT_EE204C_VerifyICCStaticData( IN UCHAR FM, IN KEYSPEC *PK, IN EFTBUFFER *static_data, IN EFTBUFFER *signature, OUT OUT OUT OUT UCHAR UCHAR UCHAR UCHAR *verify_flag, *SDF, *hash_alg_indicator, data_auth_code[2]);
SafeNet, Inc.
409
Var Var
h h
Length 3 1 1
Attribute h h h
Signed Data Format Hash Algorithm Indicator ICC Dynamic Data Length ICC Dynamic Data
1 1 1 LDD
h h h h
This function verifies an ICC's Dynamic Application Data and the associated digital signature, using an ICC Public Key. Data recovered from the signature block is returned in the response. Function Modifier PIC-Spec Terminal Dynamic Data Reserved for possible future use; must be set to zero. Key specifier for the ICC Public Key (Format 81). The Key specifier describes the complete ICC PK. Variable length terminal dynamic data as described in Table 11 in [5].
SafeNet, Inc.
410
Signed Dynamic Application Data Return Code Verify Flag Signed Data Format Hash Algorithm Indicator ICC Dynamic Data Length ICC Dynamic Data
Variable length signed dynamic application data. Contains zero for success. 1 byte length to represent result of validation test on the recovered signed application data. Recovered from the signed data and PK values. EMV currently specify the signed data format value 05. Recovered from the signed data and PK values. EMV currently specify the Hash Algorithm as SHA-1 value 01. Length of the built return ICC dynamic data. The return built dynamic data.
Processing steps 1. Obtain the Recovered Data, using the Signed Dynamic Application Data with PIC and its associated asymmetric algorithm. [Currently, RSA is the only approved asymmetric algorithm.] 2. Check the values of the Recovered Data Header, Recovered Data Trailer, Signed Data Format and Hash Algorithm Indicator. 3. Build the Dynamic Application Data using the Terminal Dynamic Data request field and fields extracted from the Recovered Data. 4. Calculate the hash result for the Dynamic Application Data using the hash algorithm indicated by Hash Algorithm Indicator in the Recovered Data. [Currently, SHA-1 is the only approved hash algorithm, and is indicated by a value of hex '01'.] 5. Compare the calculated hash result with the Hash Result field in the Recovered Data. If the two hash results are identical, then the signature is verified. Function usage Verification of the signature (i.e. data authentication) is generally performed by the terminal. This function may be used by a card issuer wishing to test a card prior to issue. SHP Toolkit CI extern "C" EXPORT int EFT_EE204D_VerifyICCDynamicData( IN UCHAR FM, IN KEYSPEC *PKicc, IN EFTBUFFER *dynamic_data, IN EFTBUFFER *signature, OUT OUT OUT OUT UCHAR UCHAR UCHAR EFTBUFFER *verify_flag, *SDF, *hash_alg_indicator, *ICC_dynamic_data);
SafeNet, Inc.
411
PIN Encipherment
Encipher PIN
Request Content EE204E FM PVK-Spec Length 3 1 Var Attribute h h K-Spec Description Function Code Function Modifier = 00 Key Specifier for PVK and Dec. Table (Formats: 0-3, 11, 12, 13, 14) Data (usually a part of the PAN) used in the calculation of the reference PIN. Number of digits in the reference PIN. PIN offset data.
Validation Data PIN Length Offset ICC Unpredictable Number PPE-Spec or PIC-Spec Response Content EE204E rc ePxx(PIN)
8 1 6 8 Var
h h h h K-Spec
Length 3 1 Var
Attribute h h h
Key Specifier for ICC Public Key. Key Type = PIN Encryption (Formats: 0 - 3, 81) Description Function Code Return Code Enciphered PIN using PPE or PIC
This function calculates a card's random PIN, formats it in accordance with section 7.2 of [5] and encrypts it using the card's ICC PIN Encipherment Public Key, PPE, or DDA key, PIC. Function Modifier PVK-Spec Validation Data PIN Length Offset Reserved for possible future use; must be set to zero. Key specifier for PIN Verification Key (PVK) (Formats 0 - 3, 11, 12, 13, 14). HSM stored and encrypted with KMv7 8 bytes of PAN data used to recreate the reference PIN. Valid ISO PIN length. 6 byte offset that is used to recreate the reference PIN. The offset is in bcd format big endian. With the validation data and PIN length, the PIN can be recalculated. 8 byte number used to form the PIN Block. Key specifier for PIN encryption key (Formats 0 - 3, 81). Contains zero for success. The return Pxx encrypted PIN.
The function will fail with Error Code 78 if the ISO-2 PIN block format is disabled. Function usage Encipherment of a cardholder-entered PIN is generally performed by the terminal. This function may be used by a card issuer wishing to test a card prior to issue. SHP Toolkit CI
extern "C" EXPORT int EFT_EE204E_RsaEncipherPin(
SafeNet, Inc.
412
SafeNet, Inc.
413
PIN Initialization
Generate PIN
Request Content EE204F FM PVK-Spec Validation Data PIN Length ANB PIN Data Encryption Method PTK-Spec Response Content EE204F Rc Offset ePTK(PIN+PIN data) Length 3 1 Var 8 1 6 Var 1 Var Length 3 1 6 Var Attribute h h K-Spec h h h h h K-Spec Attribute h h h h Description Function Code Function Modifier = 00 Key specifier for PVK and Dec. Table (Formats: 0-3, 11, 12, 13, 14) Data (usually a part of the PAN) used in the calculation of the reference PIN. Number of digits in the generated PIN. Account Number Block Data to incorporate with PIN in encrypted result 00 = ECB 01 = CBC Key Specifier for PIN Transport Key (Formats: 0 - 3, 11, 13) Description Function Code Return Code PIN offset data. Encrypted PIN and PIN data.
This function generates a random PIN for storing in an ICC, formats it in an ANSI PIN block encrypts it for secure transport to a separate PIN-issuing device, and calculates 3624 offset data for use in subsequent online PIN verification. Function Modifier PVK-Spec Validation Data PIN Length ANB PIN Data Reserved for possible future use; must be set to zero. Key specifier for PIN Verification Key (PVK) (Formats 0 - 3, 11, 12. 13, 14). 8 bytes of PAN data used to recreate the reference PIN. Valid ISO PIN length. The Account Number Block is used in the formation of the ANSI PIN block. Variable length data from the host function request that is appended to the generated PIN block, without a leading variable length prefix before being encrypted and returned in the response as ePTK(PIN+PIN data). ECB and CBC encryption methods represented using 00 or 01 respectively. Key specifier for PIN Transport Key (PTK) (Formats 0 - 3, 11, 13). Encrypted with KMV36 Contains zero for success.
SafeNet, Inc.
414
Offset
6 byte offset that is used to recreate the reference PIN. The offset is in bcd format big endian. With the validation data and PIN length, the PIN can be recalculated. The return PTK-encrypted data block which contains the generated PIN and the appended PIN data.
ePTK(PIN+PIN data)
Processing steps 1. Generate a random PIN with the required number of digits. 2. Using the PVK, Decimalization Table and PAN, calculate the 3624 offset for the PIN. 3. Format the PIN and append the variable length PIN_data from the host function request so that the block of data as input to encryption looks like : a. PIN b. PIN_Data Block of data as input to encryption method : [PIN || PIN_Data] 4. Encrypt the data_block containing the PIN and PIN Data using the PIN Transport Key. Function usage Called during card initialization: the encrypted PIN would be passed to the card personalization system. It could also be passed to a separate PIN-mailing device. The function will fail with Error Code 78 if ANSI/ISO-0 PIN block format that is disabled. The function performs a check that the ANB field and the Validation field contain a number of consecutive digits in common. The number of digits to check is in the range 0 to 12, as may be specified using a console operation, and defaults to 8. If the number of digits to check has been set to 0, the check is disabled. If the check fails, the function will fail with Return Code 79. SHP Toolkit CI extern "C" EXPORT int EFT_EE204F_GenerateRandomPinEMV( IN UCHAR FM, IN KEYSPEC *PVK, IN UCHAR validation_data[8], IN UCHAR pin_len, IN UCHAR ANB[6], IN EFTBUFFER *PIN_Data, IN UCHAR enc_method, IN KEYSPEC *PTK, OUT OUT UCHAR EFTBUFFER Offset[6], *ePTK_PIN);
SafeNet, Inc.
415
Export PIN
Request Content EE2050 FM PVK-Spec Validation Data. Offset PIN Length ANB PIN Data Encryption Method PTK-Spec Length 3 1 Var 8 6 1 6 Var 1 Var Attribute h h K-Spec h h h h h h K-Spec Description Function Code Function Modifier = 00 Key Specifier for PVK and Dec. Table (Formats: 0-3, 11, 12, 13, 14) Data (usually a part of the PAN) used in the calculation of the reference PIN. PIN offset data. Number of digits in PIN. Account Number Block Data to incorporate with PIN in encrypted result 00 = ECB 01 = CBC Key Specifier for PIN Transport Key - HSM stored (Formats: 0-3, 11, 13) Description Function Code Return Code Encrypted PIN and associated data.
Length 3 1 Var
Attribute h h h
This function reproduces a previously generated PIN, formats it in an ANSI PIN block and encrypts the block for secure transport. Function Modifier PVK-Spec Validation Data Offset PIN Length ANB PIN_Data Reserved for possible future use; must be set to zero. Key specifier for PIN Verification Key (PVK) (Formats 0 - 3, 11, 12, 13, 14). 8 bytes of PAN data used to recreate the reference PIN. 6 byte offset that is used to recreate the reference PIN. The offset is in bcd format big endian. Valid ISO PIN length. The Account Number Block is used in the formation of the ANSI PIN block. Variable length data from the host function request that is appended to the generated PIN block, without a leading variable length prefix before being encrypted and returned in the response as ePTK(PIN+PIN data). ECB and CBC encryption methods represented using 00 or 01 respectively. Key specifier for PIN Transport Key (PTK) (formats 0 - 3, 11, 13). The PTK is used to encrypt the return export PIN. Contains zero for success. The return PTK-encrypted data block which contains the generated PIN and the appended PIN data.
SafeNet, Inc.
416
The function will fail with Error Code 78 if ANSI/ISO-0 PIN block format that is disabled. The function performs a check that the ANB field and the Validation field contain a number of consecutive digits in common. The number of digits to check is in the range 0 to 12, as may be specified using a console operation, and defaults to 8. If the number of digits to check has been set to 0 the check is disabled. If the check fails, the function will fail with Return Code 79. Processing steps 1. Reproduce the PIN, using the PVK, Decimalization Table, PAN and Offset. 2. Format the PIN and append the variable length PIN_data from the host function request so that the block of data as input to encryption looks like : a. PIN b. VarLen || PIN_Data Block of data as input to encryption method : [PIN || PIN_Data] 3. Encrypt the data_block containing the PIN and PIN Data using the PIN Transport Key. Function usage Called during card initialization: the encrypted PIN would be passed to the card personalization system. It could also be passed to a separate PIN-mailing device.
SHP Toolkit CI extern "C" EXPORT int EFT_EE2050_ExportPinEMV( IN UCHAR FM, IN KEYSPEC *PVK, IN UCHAR validation_data[8], IN UCHAR Offset[6], IN UCHAR pin_len, IN UCHAR ANB[6], IN EFTBUFFER *PIN_Data, IN UCHAR enc_method, IN KEYSPEC *PTK, OUT EFTBUFFER *ePTK_PIN);
SafeNet, Inc.
417
This function re-encrypts a host stored encrypted 3DES key under a specified KTK. The function is similar to the existing Key Export function, but uses a KTK rather than a KIS as the encryption key. SHP Toolkit CI extern "C" EXPORT int EFT_EE2051_KeyExportKTK( IN UCHAR FM, IN KEYSPEC *KTK, IN UCHAR KeyType, IN UCHAR EncMode, IN KEYSPEC *KX, OUT OUT EFTBUFFER UCHAR *eKTK_KX, KVC[3]);
SafeNet, Inc.
418
This function is provided to support the management of the Card Management Key (KMC) and the associated derived card keys. This function derives a new ICC key set K2KEK, K2MAC and K2ENC derived from the new KMC, denoted KMC2. The keys are returned individually encrypted by K1KEK, which is derived from the old KMC, denoted KMC1. K1KEK and K2xxx utilize the format 50 key specifier which incorporates a 16-byte Card-unique derivation data field. The eighth byte and the sixteenth byte (numbering from one at the left) must be set to specified values that indicate the key type of the derived key, as specified in Reference [32], and as follows: 02 = KMAC 03 = KKEK 01 = KENC The format 50 key specifier must have Card method set to 01. This indicates that the Cardunique derivation data will be ECB-encrypted to derive the card keys. K1KEK K2xxx Key specifier for K1KEK (derived from KMC1). The specifier must have the appropriate bytes set to 03, so that a valid (old) K1KEK is derived. Key specifier for K2xxx (derived from KMC2). The specifier must have the appropriate bytes set to 01, so that a valid (new) K2ENC is derived. After deriving the K2ENC, the two bytes are firstly overwritten with 02 and the K2MAC is derived, then they are overwritten with 03 and the K2KEK is derived.
The format 50 key specifiers must have Card method set to 01. This indicates that the Cardunique derivation data will be ECB-encrypted to derive the card keys. SHP Toolkit CI extern "C"EXPORT IN IN IN OUT OUT OUT int EFT_EE2052_DeriveNewICCKeySets( UCHAR FM, KEYSPEC *K1kek, KEYSPEC *K2xxx, UCHAR UCHAR UCHAR eK1kek_K2enc[16], eK1kek_K2mac[16], eK1kek_K2kek[16]);
SafeNet, Inc.
419
This function is provided to support the management of the Card Management Key (KMC) and the associated derived card keys. This function derives a new ICC key Key derived from the KMC. KEK utilizes the format 50 key specifier which incorporates a 16 byte Card unique derivation data field. The eighth byte and the sixteenth byte (numbering from one at the left) must be set to 0x03 so that a valid KEK is derived. The format 50 key specifier must have Card method set to 01. This indicates that the Card unique derivation data will be ECB encrypted to derive a key. The KVC is calculated by encrypting all zero data with the key and then using the leftmost 3 bytes.
SHP Toolkit CI EXPORT int EFT_EE2053_DeriveNewICCKey( IN UCHAR FM, IN KEYSPEC *KEK, IN KEYSPEC *Key, OUT OUT UCHAR eKEK_Key[16], UCHAR KVC[3]);
SafeNet, Inc.
420
Generate DCV
Request Content EE2054 FM eDEKi(Data) DEKi-Spec Key Type Mode Response Content EE2054 rc dcv(Data) Length 3 1 Var Var 1 1 Length 3 1 8 Attribute h h h K-Spec BCD h Attribute h h h Description Function code Function Modifier = 00 Encrypted Data. (Must be a multiple of 8 bytes) Key Specifier for PPK or KTK (Formats: 0 - 3, 10, 11, 13, 50, 51) 01 = PPK 35 = KTK 00 = ECB 01 = CBC Description Function Code Return Code Data Check Value
This function generates a Data Check Value (DCV) based on the data passed in the function and returns it.
SHP Toolkit CI EXPORT int EFT_EE2054_GenerateDCV( IN UCHAR IN EFTBUFFER IN KEYSPEC IN UCHAR IN UCHAR OUT UCHAR FM, *eDEKi_Data, *DEKi, KeyType, EncMode, DCV[8]);
SafeNet, Inc.
421
SafeNet, Inc.
422
Visa payWave:
Visa payWave embraces three contactless card technologies: Magnetic Stripe Data (MSD), qVSDC and contactless VSDC. Existing CI facilities that support (contact) VSDC are sufficient to also support qVSDC and contactless VSDC. Additional functionality is required to support MSD. In MSD, the contactless card presents a virtual magnetic stripe to the reader. The significant difference from a real magnetic stripe is that the virtual magnetic stripe contains a dynamic CVV (dCVV) rather than a static CVV. The dCVV is calculated using a card-stored Unique Derived Key (UDK). As for the UDKs in VSDC, this key value is unique per card and is derived from a Master Derivation Key (MDK). This is the significant difference from the calculation of a static CVV; there is also a difference in the data involved in the calculation, but this is of no consequence to the HSM processing. The algorithm is identical to that for a static CVV.
MasterCard PayPass:
Calculation of the PayPass CVC3 uses a unique-per-card derived key, KDCVC3, which is derived from a Master Key, IMKCVC. The extension defined here supports: Console operations for user management of the IMKCVC. A host function that derives the KDCVC3 and calculates IVCVC3 (for personalization of the ICC). A host function that derives the KDCVC3 from IMKCVC and then generates the CVC3. A host function that derives the KDCVC3 from IMKCVC and then verifies the CVC3. The calculation of a CVC3 differs from that of a static CVC (or CVV) in that it is a 3DES encryption of a single 8-byte block, and the CVC3 is the rightmost 4 hex digits (2-bytes) rather than the left 3 digits after decimalization. A card that supports both EMV debit/credit and PayPass requires 2 public key certificates in support of DDA. A function is provided that creates an additional certificate, thereby supplementing the existing CI functions that generate the ICC key pair and certificate.
SafeNet, Inc.
423
DERIVE_KDCVC3_AND_IVCVC3
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
U D U U U
Request Content EE0012 FM IMKCVC3 PAN Data KTK-Spec Encryption Method KVC method IV Data 1
Description Function Code Function Modifier = 00 Key Specifier for Issuer Master Key. (Formats: 0 - 3, 11, 13) Formatted PAN and PAN Sequence No. Key Specifier for Key Transport Key. (Formats: 0 - 3, 13, 50) 00 = ECB 01 = CBC 01 = left 6 digits of eK(0) Static part of Track 1 data used to calculate IVCVC3TRACK1. (Or zero-length field.) Static part of Track 2 data used to calculate IVCVC3 TRACK2. (Or zero-length field.) Description Function Code Return Code
IV Data 2
Var
Length 3 1
Attribute h h
16
Encrypted ICC Derived Key for CVC3 Generation. Key Verification Code
Var 2 2
h h h
This function derives a unique-per-card, 16-byte, ICC CVC3 Data Key, DKCVC3. Optionally, it also calculates the 2-byte IVCVC3 for Track 1 and Track 2. Processing Steps 1. Derive KDCVC3 using IMKCVC3 and PAN Data. 2. Encrypt KDCVC3 using KTK or derived KKEK 3. Calculate kvc(KDCVC3).
SafeNet, Inc.
424
4. If len(IV Data 1) > 0 calculate IVCVC3TRACK1 If len(IV Data 2) > 0 calculate IVCVC3TRACK2
SafeNet, Inc.
425
CREATE_ADDITIONAL_ICC
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
U D U U U
Length 3 1 Var
Attribute h h K-Spec
Description Function Code = 00 Key Specifier for Issuer Private Key. Key Type = Certificate, Data Signature (Formats: 0 - 3, 82) Output from EE2048 or EE2058. Digital signature for the public key certificate. The field length is equal to the length NI of the modulus of SI A variable-length data element. This field is only present if NIC > N 42 and consists of the NIC NI + 42 least significant bytes of the ICC Public Key. A variable-length data element provided by the issuer. ICC Public Key Exponent equal to 3 or 216 + 1. Static data to be authenticated as specified in Part II of Book 3 of these specifications. Description Function Code Return Code Digital signature for the public key certificate. The field length is equal to the
length NI of the modulus of SI
Var
Var
Var
Static Data to be Authenticated Response Content EE0013 rc Additional ICC Public Key Certificate
Var
Length 3 1 Var
Attribute h h h
This function creates an ICC certificate with different SDA data than the certificate previously created by function EE2048 or EE2058. The function extracts the data from original certificate, adds data provided in the request message and creates the additional certificate incorporating the new SDA data Processing Steps 1. Extract the required certificate data fields from ICC Public Key Certificate (i.e. fields up to and including ICC Public Key or Leftmost Digits of the ICC Public Key. 2. Append ICC Public Key Remainder, ICC Public Key Exponent and Static Data to be Authenticated to form the certificate data (MSG).
SafeNet, Inc.
426
3. Calculate the hash value (H) of resulting certificate data. 4. Concatenate a header byte (B), the left part of certificate data (MSG1), the hash result (H) and the trailer byte (E) to form X = B || MSG1 || H || E. 5. Sign X using the Issuer Private Key provided in SI to give Additional ICC Public Key Certificate.
SafeNet, Inc.
427
SafeNet, Inc.
428
Part 3
______________________________________________________________________
SafeNet, Inc.
429
SafeNet, Inc.
430
Definitions
Customer PIN Customer Selected PIN Customer Entered PIN PINLEN CHKLEN PIN Offset PIN assigned to or selected by the customer. A PIN that is chosen by the customer. The entered PIN that is to be verified. Number of digits in a Customer PIN. Number of PIN digits checked in the PIN verification procedure. Non secret data that is associated with the PIN and used in the PIN verification procedure. Process of creating a PIN that is then issued to a customer. Process of validating a Customer PIN.
A 3624 PIN may either be derived, or randomly generated. Random PINs have an associated Offset.
SafeNet, Inc.
431
Validation data .............. PVK ............................... DT ................................. PINLEN ......................... CHKLEN ....................... Customer PIN ...............
1234 5678 9012 3456 A775 3725 38B0 325E 01223 4567 8901 2345 8 6 6540 6902
1. Form Validation data ................ 1234 5678 9012 3456 2. ePVK(Validation data) ............. 6FEA 6902 AF41 CC43
3. Decimalize encrypted data ....... 6540 6902 0541 2243 4. Derived PIN digits .................... 6540 6902 5. Compare rightmost CHKLEN digits with Customer PIN 40 6902
A Derived PIN may also be verified by this method if an Offset of all zeros is used. Table F.2 contains an example of verifying a Random PIN.
SafeNet, Inc.
432
Validation data .................... PVK .................................... DT ....................................... PINLEN ............................... CHKLEN ............................. Customer PIN ..................... OFFSET ..............................
1234 5678 9012 3456 A775 3725 38B0 325E 0123 4567 8901 2345 8 6 5429 9605 89 3703
1. Form Validation data ............................ 1234 5678 9012 3456 2. ePVK(Validation data) .......................... 6FEA 6902 AF41 CC43 3. Decimalize encrypted data ................... 6540 6902 0541 2243 4. Derived PIN digits ................................. 6540 6902 5. Add Offset, Modulo 10, to the Derived PIN 40 6902 + 89 3703 ------------29 9605 ------------29 9605
For example, if the PINLEN is 9, the Customer PIN is 3614 3624 3, and the Derived PIN is 7613 6574 6, the significant Offset digits are calculated as follows : 1. Subtract Derived PIN from Customer PIN to give Offset digits. 3614 3624 3 7613 6574 6 --------------Offset 6001 7150 7 --------------If CHKLEN equals 4, then the rightmost 4 Offset digits are significant. That is digits 1507. If CHKLEN equals 5, then the rightmost 5 Offset digits are significant. That is digits 71507.
2.
Table F.3 details the significant Customer PIN digits and significant Offset digits for each valid value of CHKLEN using the same data as this example.
SafeNet, Inc.
433
PINLEN ................. 9 Customer PIN ....... 3614 3624 3 Derived PIN .......... 7613 6574 6 Offset .................... 6001 7150 7
Significant PIN CHKLEN Digits 4 5 6 7 8 9 6243 36243 436243 1436243 61436243 361436243 Significant OFFSET Digits 1507 71507 171507 0171507 00171507 600171507
SafeNet, Inc.
434
EE 04 08 00 02
Length of BDK - double length
EE 04 08 0 = successful completion 00 11 0D A0 2C EB FA 20 2F 6D C1 A0 D4 62 50 A6 AE AB 4C
Key Specifier Format 13 (0Dh) - double length CBC
SafeNet, Inc.
435
SafeNet, Inc.
436
13 82 EF 11 55
F2 9D 22 66
E1 CA 22 66
BB 28 33 77
90 97 33 77
07 B0 44 88
CE D3 03 03
00 01 11 22 22 33 33 44 03 55 66 66 77 77 88 03
EE 00 85 AA F5 18 9F B3
20 52 FE BB 73 2C C2 5A 74 23 87 C3 10 8A B9 84 19 E5 9F A3 0B C2 32 E0 3A 4D 68 56 A9 A7 E0 AA FD 72 2E 02 2B 38 B0 AE 49 48 DF 65
SafeNet, Inc.
437
SafeNet, Inc.
438
PIN-FROM-OFF EE0609
Transmitted to HSM
Function code = 00 PVK Spec Validation Data Offset PIN Length PPK-Spec PFo ANB Returned from HSM Function code Return code ePPK(PIN) EE 06 09 00 02 01 61 04 02 01 66 00 01 23 45 67 89 AB CD EF 71 00 00 00 00 00 01 66 66 66 66 66
EE 06 09 00 B2 41 19 C5 13 ED 69 7B
IT-PVK-EXPORT EF0210
Transmitted to HSM
Function code = 00 PVK Spec Mode KTM Spec Returned from HSM Function code Return code (Var) eKTM(PVK) KVC EF 02 10 00 02 00 01 10 02 00 01 EF 02 10 00 08 74 A2 82 4B F5 0C C4 4E AD C6 7D
SafeNet, Inc.
439
SafeNet, Inc.
440
Note that the following examples are host communication independent and do not show the necessary information to wrap the example data into a valid message block. Please refer to your communications guide for details of your specific host communication requirements.
Variable Length Field: The first byte of the field expanded to binary 0010 0000 reveals, the MSB is 0 indicating that the length field is one byte. The 7 LSBs indicate the number of bytes that follow (i.e. 20h = 32 bytes).
00 01 23 45 67 89 01 23 45 5E EF F8 2C E6 76 A8 A0 D4 7C 38 2C 62 26 5C EB 50 58 06 FA A6 62 E0 20 AE F3 8A 2F AB 59 94 6D 4C C2 80
AC-index = 1
EE 20 00 00 89 B6 8C 00 8E 06 2B F3
0 = successful completion
EE 20 01 00h
SafeNet, Inc.
441
01 23 45 67 89 01 23 45 5E EF F8 2C E6 76 A8 F5 23 45 67 89 AB CD EF 01
EE 20 01 00h
EE 20 02 00 81 DE
EE 20 03 00
EE 20 04 00 BA 33
SafeNet, Inc.
442
IDN (2 bytes)
EE 20 05 00
EE 20 06 00 AB 31 8E E1 C3 0D 67 0C
EE 20 07 01 80 02 00 07
Example of the variable Length prefix being 4 bytes in length, and indicating 32 bytes of data.
Offset (Var) Script Data Returned from HSM Function code Return code eSK(Text-Data)
02 01 EF E0 E9 C1 A0 C5 00 00
00 23 5E 00 A0 D4 7C 38 00
05 45 EF 00 2C 62 26 5C
67 F8 20 EB 50 58 06
89 01 23 45 2C E6 76 A8 FA A6 62 E0 20 AE F3 8A 2F AB 59 94 6D 4C C2 80
MAC
EE 00 EF BE 44 C9 00
20 07 07 83 AC 0B 00 EB BF 78 D9 00 41 F9 76 81 00 FA 23 96 42 00 FD 0E 47 C6 00 D9 13 10 AE 00 13 69 37 CB 00
SafeNet, Inc.
443
01 7F CF 54 BB 34 1D FB 00 00 00 00 00 00 00
EF 20 10 00
01 23 45 67 89 01 23 45 01 01 01 01 01 01 01 01 01 01 01 01 01 01
01 36 00 00 00 00 00 00 00 01
EF 20 10 00
EF 20 11 00
SafeNet, Inc.
444
EF 20 11 00
01 00 00 00 00 00 00 00
EF 20 12 00 50 7F CF 54 BB 34 1D FB
SafeNet, Inc.
445
Transmitted To HSM Function code = 00 Select Code (SC) (Var) SMI spec (Var) SMC spec Application PAN Block Initialization Vector Height Branch factor ATC Encryption Mode Var) Text-Data Text-Data Offset (Var) Script Data Data Returned From HSM Function code Return code eSKsmc(Text) MAC
EF 00 03 02 02 01 01 01 10 02 00 00 08 01 00 08 01
20 13
00 00 23 01 01
01 01 45 67 89 01 23 45 01 01 01 01 01 01 01 01 01 01 01 01
01
00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
EF 20 13 00 CA BF 92 07 A3 D4 1A 35 6D 97 2A 4F 24 4B 70 A7
00 00 23 01 00 00 00
01 01 45 67 89 01 23 45 00 08 00 00 00 00 00 00
00 00 00 00 00 00 00
EF 20 14 00 6D 47 F8 BE B4 58 A5 DB 00 00 00 00 00 00 00 00
SafeNet, Inc.
446
Sixteen characters are extracted from the nineteen characters which make up the expiration date and account number. The two fields are combined after stripping the 37 and the check digit from the account number. 9 9 1 2 1 2 3 4 5 6 7 8 9 0 1 2
34 Cards
The CSC algorithm does not include the ISO code (34 or 37) or the check digit. It is possible that a 34 card and a 37 card with the same internal digits could have the same CSC. Thus a 37xxxxxxxxxxxxxC and a 34xxxxxxxxxxxxC with the same expiration date and the same CSCK would have the same CSC. It is recommended that 34 Cards use different CSCKs than their 37 counterpart. This will eliminate any potential sequencing that might otherwise be mathematically possible. In the event that it is impossible to establish a separate key, there is a mechanism to treat 34 Cards differently than 37 Cards. The 37card process should prefix the expiration date to the 12 digits from the account number while the 34 Card process should append the expiration date to the 12 digits from the account number.
SafeNet, Inc.
447
SafeNet, Inc.
448
Test 1
Transmitted to HSM: SOM LENGTH Application Data BCC EOM Received From HSM: SOM LENGHT Application Data BCC EOM
Function Code Key Specifier 3C 0C [A8][02][00 01][98 07 12 34 56 78 90 12] 7E Length 3E Account Block
3C 08 A8 00 12 88 10 90 58 40 7B 3E
Test 2
Transmitted to HSM: SOM LENGTH Application Data BCC EOM Received From SM: SOM LENGTH Application Data BCC EOM 3C 0C A8 02 00 01 99 12 12 34 56 78 90 12 7B 3E 3C 08 A8 00 28 34 11 77 09 54 7C 3E
SafeNet, Inc.
449
Test 3
Transmitted to HSM: SOM LENGTH Application Data BCC EOM Received From HSM: SOM LENGTH Application Data BCC EOM 3C 0C A8 02 00 01 00 01 12 34 56 78 90 12 79 3E 3C 08 A8 00 66 42 84 85 75 23 7D 3E
Test 4
Transmitted to HSM: SOM LENGTH Application Data BCC EOM Received From HSM: SOM LENGTH Application Data BCC EOM 3C 0C A8 02 00 01 99 12 00 00 44 30 10 00 7B 3E 3C 08 A8 00 31 03 21 34 28 80 7E 3E
Test 5
Transmitted to HSM: SOM LENGTH Application Data BCC EOM Received From HSM: SOM LENGTH Application Data BCC EOM 3C 0C A8 02 00 01 99 12 82 57 56 78 90 12 77 3E 3C 08 A8 00 12 71 22 07 64 29 72 3E
Test 6
Transmitted to HSM: SOM LENGTH Application Data BCC EOM Received From HSM: SOM LENGTH Application Data BCC EOM 3C 0C A8 02 00 01 99 12 00 91 31 18 90 12 70 3E 3C 08 A8 00 17 42 45 00 27 57 7F 3E
Test 7
SafeNet, Inc.
450
Transmitted to HSM: SOM LENGTH Application Data BCC EOM Received From HSM: SOM LENGTH Application Data BCC EOM
3C 0C A8 02 00 01 99 12 00 10 80 88 90 12 7A 3E 3C 08 A8 00 77 02 86 18 45 55 7D 3E
Test 8
Transmitted to HSM: SOM LENGTH Application Data BCC EOM Received From HSM: SOM LENGTH Application Data BCC EOM 3C 0C A8 02 00 01 12 34 56 78 90 12 99 12 7B 3E 3C 08 A8 00 80 63 23 26 89 00 70 3E
SafeNet, Inc.
451
SafeNet, Inc.
452
Func. Code 01 11 12 13 21 22 41 42 43 44 45 46 47 49 4A 4C 51 52 53 54 55 56 57 58 59 5A 5B 5C
Function Name
SHP
PHW
PSO
PHW CI
Supercedes
Superceded by
HSM_STATUS Establish_KM KM_Migrate Erase_Old_KM Retrieve_Key Store_Key IT-PPK-GEN IT-MPK-GEN IT-DPK-GEN NT-PPK-GEN NT-MPK-GEN NT-DPK-GEN D51-PPK-GEN M-DPK-GEN GEN_SESS_KEYS TERM-VER II-PPK-GEN II-MPK-GEN II-DPK-GEN II-PPK-RCV II-MPK-RCV II-DPK-RCV NI-PPK-GEN NI-MPK-GEN NI-DPK-GEN NI-PPK-RCV NI-MPK-RCV NI-DPK-RCV EE0400 EE0406 EE0402 EE0402 EE0402 EE0403 EE0403 EE0403 EE0404 EE0404 EE0404 EE0405 EE0405 EE0405 EE0400 EE0400 EE0400 EE0401 EE0401 EE0401
SafeNet, Inc.
453
Func. Code 60 61 62 63 64 65 66 67 68 69 6A 6B 70 71 72 73 80 81 82 83 84 85 90 91 92 93 94 95 96 97 98 99 9A 9B 9C A0 A1 A2 A3 A7 A8
Function Name
SHP
PHW
PSO
PHW CI
Supercedes
PIN-TRAN PIN-VER PIN-VER-PP PIN-TRAN-3624 KB-PIN-VER D51-PIN-TRAN D51-PIN-VER VAR-PIN-VER VAR-PIN-VER-PP VAR-KB-PIN-VER PIN-OFF-AS PIN-OFF-PP MAC-GEN MAC-TRAN MAC-VER KB-MAC-GEN ENCIPHER DECIPHER ENCIPHER-ECB DECIPHER-ECB B-ENCIPHER-ECB B-DECIPHER-ECB PVV-GEN-1 PVV-VER-1 PVV-VER-2 PVV-VER-3 PIN-TRAN-1 PIN-TRAN-2 PVV-GEN-2 PVV-VER-4 PVV-VER-5 PVV-VER-6 PVV-CHANGE CVV-GEN CVV_VER MT-KPE-GEN MT-KPE-RCV MT-PIN-TRAN MT-PIN-VER MT_PIN_VER_PVV CALC_CSCK
EE0606 EE0605 EE0605 EE0605 EE0602 EE0602 EE0606 EE0605 EE0605 EE0605 EE0607 EE0802 EE0803
SafeNet, Inc.
454
Func. Code A9 AA AB E2 E3 FFF0 FFF1 EE0002 EE0200 EE0201 EE0202 EE0210 EE0400 EE0401 EE0402 EE0403 EE0404 EE0405 EE0406 EE0408 EE0600 EE0601 EE0602 EE0603 EE0604 EE0605 EE0606 EE0607 EE0609 EE0610 EE0611 EE0612 EE0613 EE0614 EE0615 EE0616 EE0628 EE0640 EE0641 EE0642
Function Name
SHP
PHW
PSO
PHW CI
Supercedes
Superceded by
CREATE_CSCK EXPORT_CSCK IMPORT_CSCK PIN-MAIL Meta Function Support HSM_ERRORLOG_STATUS HSM_GET_ERRORLOG GEN_RANDOM KEY_IMPORT KEY_EXPORT GET_KEY_DETAILS ZKA-IMPORT-MK IT_KEY_GEN NT_KEY_GEN II_KEY_GEN II_KEY_RCV NI_KEY_GEN NI_KEY_RCV TERM_VER_2 BDKGEN CLR-PIN-ENCRYPT MIGRATEPIN PIN-TRAN-2 PIN-VER PIN-OFF PVV-VER PVV-CALC-3624 PVV-CALC PIN-FROM-OFF ZKA-PIN-TRANS ZKA-PIN-VER ZKA-CALC-PVN ZKA-PIN-TRANS-1 DIEBOLD_PIN_VER PIN_TRANS_SEED_DES DIEBOLD_PIN_OFF GEN_TERMINAL_KEY Generate KM-encrypted PIN Print a KM-encrypted PIN Verify a PIN Using KM-encrypted PIN 60,65,94,95 61,62,66,67, 68 6A,6B 91,92,93,97, 98,99 90,96 9A 41,42,43,4A 44,45,46 51,52,53 54,55,56 57,58,59 5A,5B,5C
SafeNet, Inc.
455
Func. Code EE0643 EE0644 EE0700 EE0701 EE0702 EE0710 EE0711 EE0800 EE0801 EE0802 EE0803 EE0804 EE0805 EE0806 EE0E01 EE0E04 EE0E05 EE2000 EE2001 EE2002 EE2003 EE2004 EE2005 EE2006 EE2007 EE2016 EE2017 EE2018 EE3030 EE3031 EE3032 EE3033 EE3034 EE3100 EE3101 EE9001 EE9003 EE9004 EE9005 EE9006 EE9007
Function Name
SHP
PHW
PSO
PHW CI
Supercedes
Superceded by
Translate a PIN from PPK to LMK Migrate PIN MAC_GEN_UPDATE MAC_GEN_FINAL MAC_VER_FINAL ZKA-MAC-GEN ZKA-MAC-GEN-1 ENCIPHER_2 DECIPHER_2 CVV_GENERATE CVV_VERIFY ENCIPHER_3 DECIPHER_3 ENCIPHER_KTM1 Key Mailer PIN-GENERATE PIN-PRINT EMV_AC_GEN EMV_AC_VERIFY EMV_DAC_GEN EMV_DAC_VERIFY EMV_ICC_DN_GEN EMV_ICC_DN_VERIFY EMV_ARPC_GEN EMV_SCRIPT_CRYPTO EMV_PIN_CHANGE_UNBLOCK EMV_PIN_CHANGE_UNBLOCK_E MV_2000 EMV_VERIFY_AC_GEN_ARPC GETPUBLICKEY KIS_SEND KIR_REC NODEPROOF NODERESP LOAD_HSM_SOFTWARE HSM_SOFTWARE_STATUS Generate RSA Key Pair Import Public Key Import Public Key Certificate Sign Data Verify Signed Data Generate MD5 Hash 80,82 81,83 9B 9C 70,71,72
SafeNet, Inc.
456
Func. Code EE9008 EE9101 EE9102 EE9201 EF0210 EF0701 EF0702 EF0703 EF0704 EF0F01 EF2010 EF2011 EF2012 EF2013 EF2014 EF2015 EE2019 EE2020 EE2021 EE0010 EE0011 EE0014 EE0015 EE0608 EE2040 EE2041 EE2042 EE2043 EE2044 EE2045 EE2046 EE2047 EE2048 EE2058 EE2049 EE204A EE204B EE204C
Function Name
SHP
PHW
PSO
PHW CI
Supercedes
Superceded by
Generate SHA Hash Generate Key Diebold Verify ATM Response Diebold Generate KM NCR IT_PVK_EXPORT VCEPS_VER_S1_GEN_S2 VCEPS_VER_SN VCEPS_GEN_SN VCEPS_MAC_VER_LSAM VCEPS_GEN_HASH_CEP EMV_VERIFY_AC_EMV2000 EMV_VERIFY_AC_VISA EMV_GENERATE_ARPC EMV_SCRIPT_CRYPTO_EMV2000 EMV_SCRIPT_CRYPTO_VISA EMV_PIN_CHANGE_UNBLOCK_VI SA EMV_AC_GEN_MULTI EMV_SCRIPT_CRYPTO_MULTI EMV_PIN_CHANGE_UNBLOCK_M ULTI CVC3_GENERATE CVC3_VERIFY dCVV_GENERATE dCVV_VERIFY PIN-TRANSLATEVSDC Personalization AC Generate Issuer Key Pair Self-Certify Issuer Public Key (Europay- MasterCard) Verify CA Public Key (MasterCard) Verify Issuer Public Key Certificate (MasterCard) Self-Sign Issuer Public Key (Visa) Verify CA Public Key (Visa) Verify Issuer Public Key Certificate (Visa) Verify Detached Signature (Visa) Generate ICC Key Pair Generate ICC CRT Key Pair Verify ICC Certificate (EMV2000) Derive ICC Master Key Sign ICC Static Data Verify ICC Static Data
SafeNet, Inc.
457
Func. Code EE204D EE204E EE204F EE2050 EE2051 EE2052 EE2053 EE2054 EE0012 EE0013
Function Name
SHP
PHW
PSO
PHW CI
Supercedes
Superceded by
Verify ICC Dynamic Data Encipher PIN Generate PIN Export PIN Key Export using KTK Derive New ICC Key Set Derive New ICC Key Generate DCV DERIVE_KDCVC3_AND_IVCVC3 CREATE_ADDITIONAL_ICC
SafeNet, Inc.
458
BCD;
bin;
BCD[2];
SafeNet, Inc.
459
typedef struct { UCHAR UCHAR UCHAR UCHAR UCHAR UCHAR UCHAR UCHAR UCHAR UCHAR UCHAR } FORMAT15;
// Represents Key Spec 15 version; keyType; keySubType; KMID; authAlgID; attributeCount; padding; keyFieldLen; keyField[32]; attributes[2]; mac[8];
typedef struct { // Represents Key Spec 50 UCHAR format_KMC; union { FORMAT00 KMC_fmt00; FORMAT01 KMC_fmt01; FORMAT02 KMC_fmt02; FORMAT03 KMC_fmt03; FORMAT13 KMC_fmt13; }; UCHAR Card_Data[16]; UCHAR Card_Method; } FORMAT50;
typedef struct { // Represents Key Spec 51 UCHAR format_KMC; union { FORMAT00 KMC_fmt00; FORMAT01 KMC_fmt01; FORMAT02 KMC_fmt02; FORMAT03 KMC_fmt03; FORMAT13 KMC_fmt13; }; UCHAR Card_Data[16]; UCHAR Card_Method; UCHAR Session_Data[16]; UCHAR Session_Method; } FORMAT51;
SafeNet, Inc.
460
UCHAR } FORMAT80;
typedef struct { USHORT UCHAR USHORT UCHAR UCHAR USHORT UCHAR USHORT UCHAR UCHAR UCHAR } FORMAT81;
// Represents Key Spec 81 modulusLen; modulus[512]; exponentLen; exponent[512]; KMID; keyType; authAlgID; userDataLen; userData[512]; authDataLen; authData[16];
typedef struct { USHORT UCHAR UCHAR USHORT UCHAR USHORT UCHAR USHORT UCHAR UCHAR UCHAR } FORMAT82;
// Represents Key Spec 82 modulusLen; keyFormat; KMID; keyType; authAlgID; userDataLen; userData[512]; SKLen; eKMv20_SK[1024]; authDataLen; authData[32];
typedef struct { // Represents Key Spec 90 UCHAR format; union { FORMAT00 fmt00; FORMAT01 fmt01; FORMAT02 fmt02; FORMAT03 fmt03; FORMAT13 fmt13; FORMAT92 fmt92; }; UCHAR cvIndex; UCHAR eTK_KS[16]; } FORMAT90;
SafeNet, Inc.
461
Appendix I SHP Toolkit FORMAT00 FORMAT01 FORMAT02 FORMAT03 FORMAT13 KGK1_fmt00; KGK1_fmt01; KGK1_fmt02; KGK1_fmt03; KGK1_fmt13;
}; UCHAR format_KGK2; union { FORMAT00 KGK2_fmt00; FORMAT01 KGK2_fmt01; FORMAT02 KGK2_fmt02; FORMAT03 KGK2_fmt03; FORMAT13 KGK2_fmt13; }; UCHAR BLZ[4]; } FORMAT91;
SafeNet, Inc.
462
When an EFTBUFFER is provided by the caller to supply input to a function, the system will expect the length field to indicate the length of valid data. When an EFTBUFFER is provided by the caller to accept returned data from a function: the system will set the length field to be the actual length of the returned data (if the length of the returned data is less than the maximum length originally specified in the length field) alternately, it will truncate the returned data to the length originally specified in the length field.
Void API_SetTraceFile(char *TraceFileName); This function will set trace file name as passed on parameter.
SafeNet, Inc.
463
These keywords represent optional inputs and outputs. Any optional inputs that are not needed can be passed a NULL pointer. Any optional outputs that are not used return a NULL pointer.
extern "C" EXPORT int EFT_FFF0_HSMErrorLogStatus( IN UCHAR *ESMID, IN UCHAR FM, OUT _OUT _OUT _OUT _OUT _OUT _OUT _OUT _OUT _OUT _OUT UCHAR UCHAR UCHAR UCHAR UCHAR UCHAR UCHAR UCHAR UCHAR UCHAR UCHAR *Num_Files, LogFileStatus[31], LogFileStatus1[31], LogFileStatus2[31], LogFileStatus3[31], LogFileStatus4[31], LogFileStatus5[31], LogFileStatus6[31], LogFileStatus7[31], LogFileStatus8[31], LogFileStatus9[31],
SafeNet, Inc.
464
_OUT
The LogFileStatus fields contain the returned data for each Log File in the following format : Byte 0 1 3 11 17 25 Length Data 1 2 8 6 8 6
ErrorLog File Number Total Number of Errors in File (big endian) First Error Date (DDMMYYYY) First Error Time (HHMMSS) Last Error Date (DDMMYYYY) Last Error Time (HHMMSS)
extern "C" EXPORT int EFT_FFF1_HSMGetErrorLog( IN UCHAR *ESMID, IN UCHAR FM, IN UCHAR File_Number, IN UCHAR Error_Index[2], IN UCHAR Error_Date[8], IN UCHAR Error_Time[6], IN UCHAR Get_Error_Flag, OUT _OUT _OUT _OUT _OUT _OUT _OUT _OUT _OUT _OUT _OUT _OUT _OUT _OUT _OUT _OUT _OUT _OUT _OUT _OUT _OUT UCHAR UCHAR EFTBUFFER UCHAR EFTBUFFER UCHAR EFTBUFFER UCHAR EFTBUFFER UCHAR EFTBUFFER UCHAR EFTBUFFER UCHAR EFTBUFFER UCHAR EFTBUFFER UCHAR EFTBUFFER UCHAR EFTBUFFER *Returned_File_Number, Error_Log_Index[2], *Error_Log_Data, Error_Log_Index1[2], *Error_Log_Data1, Error_Log_Index2[2], *Error_Log_Data2, Error_Log_Index3[2], *Error_Log_Data3, Error_Log_Index4[2], *Error_Log_Data4, Error_Log_Index5[2], *Error_Log_Data5, Error_Log_Index6[2], *Error_Log_Data6, Error_Log_Index7[2], *Error_Log_Data7, Error_Log_Index8[2], *Error_Log_Data8, Error_Log_Index9[2], *Error_Log_Data9);
KM Change Functions
extern "C" EXPORT int EFT_11_EstablishKM(void); extern "C" EXPORT int EFT_12_MigrateKey(
SafeNet, Inc.
465
Appendix I SHP Toolkit UCHAR UCHAR KEYSPEC KEYSPEC KEYSPEC KEYSPEC KEYSPEC KEYSPEC KEYSPEC KEYSPEC KEYSPEC KEYSPEC UCHAR KEYSPEC KEYSPEC KEYSPEC KEYSPEC KEYSPEC KEYSPEC KEYSPEC KEYSPEC KEYSPEC KEYSPEC variantNum, NumKeys, *keyToTranslate1, *keyToTranslate2, *keyToTranslate3, *keyToTranslate4, *keyToTranslate5, *keyToTranslate6, *keyToTranslate7, *keyToTranslate8, *keyToTranslate9, *keyToTranslate10, *NumKeysReturned, *translatedKey1, *translatedKey2, *translatedKey3, *translatedKey4, *translatedKey5, *translatedKey6, *translatedKey7, *translatedKey8, *translatedKey9, *translatedKey10);
IN IN IN _IN _IN _IN _IN _IN _IN _IN _IN _IN OUT OUT _OUT _OUT _OUT _OUT _OUT _OUT _OUT _OUT _OUT
extern "C" EXPORT int EFT_13_EraseOldKM(void); extern "C" EXPORT int EFT_21_RetrieveKey( IN UCHAR Reserved[2], IN KEYSPEC *tfrTableIndex, OUT OUT OUT UCHAR KEYSPEC UCHAR *keyType, *retrievedKey, KVC[3]);
extern "C" EXPORT int EFT_22_StoreKey( IN UCHAR IN KEYSPEC IN UCHAR IN KEYSPEC IN UCHAR
extern "C" EXPORT int EFT_EE0200_KeyImport( IN UCHAR FM, IN KEYSPEC *KIR, IN UCHAR KeyType, IN UCHAR EncMode, IN EFTBUFFER *eKIRvK, OUT OUT KEYSPEC UCHAR *eKMvK, KVC[3]);
extern "C" EXPORT int EFT_EE0201_KeyExport( IN UCHAR FM, IN KEYSPEC *KIS, IN UCHAR KeyType, IN UCHAR EncMode, IN KEYSPEC *eKMvK,
SafeNet, Inc.
466
OUT OUT
extern "C" EXPORT int EFT_EE0202_GetKeyDetails( IN UCHAR FM, IN KEYSPEC *K, IN UCHAR KeyType, IN UCHAR KVCType, OUT OUT UCHAR EFTBUFFER *Parity, *KVC);
SafeNet, Inc.
467
Appendix I SHP Toolkit UCHAR UCHAR EFTBUFFER UCHAR UCHAR EFTBUFFER UCHAR UCHAR EFTBUFFER UCHAR UCHAR EFTBUFFER UCHAR UCHAR EFTBUFFER UCHAR UCHAR EFTBUFFER UCHAR UCHAR EFTBUFFER UCHAR UCHAR EFTBUFFER UCHAR UCHAR EFTBUFFER UCHAR UCHAR EFTBUFFER UCHAR UCHAR KEYSPEC EFTBUFFER *LineNo1b, *ColumnNo1b, *Data1b, *LineNo2b, *ColumnNo2b, *Data2b, *LineNo3b, *ColumnNo3b, *Data3b, *LineNo4b, *ColumnNo4b, *Data4b, *LineNo5b, *ColumnNo5b, *Data5b, *LineNo6b, *ColumnNo6b, *Data6b, *LineNo7b, *ColumnNo7b, *Data7b, *LineNo8b, *ColumnNo8b, *Data8b, *LineNo9b, *ColumnNo9b, *Data9b, *LineNo10b, *ColumnNo10b, *Data10b, *KeyType, *KvcType, *eKMv5_KTM, *KVC_Key );
_IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN OUT _OUT
extern "C" EXPORT int EFT_EE0400_InitialSessionKeyGeneration( IN UCHAR FM, IN KEYSPEC *KTM, IN UCHAR KeyFlags[2], OUT OUT OUT OUT _OUT _OUT _OUT UCHAR EFTBUFFER KEYSPEC UCHAR EFTBUFFER KEYSPEC UCHAR *numKeys, *eKTM_KS1, *KS1, KVC1[3], *eKTM_KS2, *KS2, KVC2[3],
SafeNet, Inc.
468
extern "C" EXPORT int EFT_EE0401_RolloverSessionKeyGeneration( IN UCHAR FM, IN UCHAR KeyFlags[2], IN KEYSPEC *KSi1, _IN KEYSPEC *KSi2, _IN KEYSPEC *KSi3, OUT OUT OUT OUT _OUT _OUT _OUT _OUT _OUT _OUT UCHAR EFTBUFFER KEYSPEC UCHAR EFTBUFFER KEYSPEC UCHAR EFTBUFFER KEYSPEC UCHAR *numKeys, *eKS_KS1, *KS1, KVC1[3], *eKS_KS2, *KS2, KVC2[3], *eKS_KS3, *KS3, KVC3[3]);
extern "C" EXPORT int EFT_EE0406_TerminalVerification( IN UCHAR FM, IN KEYSPEC *KTM, IN UCHAR SecurityNumber[8], IN UCHAR LogonData[8]); extern "C" EXPORT int EFT_EE0408_DUKPT_BDK_Generation( IN UCHAR FM, IN UCHAR KeyLength, OUT KEYSPEC *BDK);
extern "C" EXPORT int EFT_EE9003_ImportPublicKey( IN UCHAR FM, IN UCHAR KeyType[2], IN KEYSPEC *PKi, IN EFTBUFFER *UserData,
SafeNet, Inc.
469
OUT
KEYSPEC
*PKo);
extern "C" EXPORT int EFT_EE9004_ImportPublicKeyCertificate( IN UCHAR FM, IN KEYSPEC *PK_CA, IN UCHAR CertFormat, IN UCHAR HashFunction, IN EFTBUFFER *Certificate, IN UCHAR KeyType[2], IN EFTBUFFER *UserData, OUT KEYSPEC *PK);
extern "C" EXPORT int EFT_EE9005_SignData( IN UCHAR FM, IN KEYSPEC *SK, IN UCHAR Algorithm, IN UCHAR HashFunction, IN EFTBUFFER *Data, OUT EFTBUFFER *Signature);
extern "C" EXPORT int EFT_EE9006_VerifySignedData( IN UCHAR FM, IN KEYSPEC *PK, IN UCHAR Algorithm, IN UCHAR HashFunction, IN EFTBUFFER *Data, IN EFTBUFFER *Signature); extern "C" EXPORT int EFT_EE9007_GenerateMD5Hash( IN UCHAR FM, IN UCHAR Mode, IN UCHAR BitCount[8], IN UCHAR HashValue[16], IN EFTBUFFER *Data, OUT OUT UCHAR UCHAR BitCount2[8], HashValue2[16]);
extern "C" EXPORT int EFT_EE9008_GenerateSHAHash( IN UCHAR FM, IN UCHAR Algorithm, IN UCHAR Mode, IN UCHAR BitCount[8], IN EFTBUFFER *HashValue, IN EFTBUFFER *Data, OUT OUT UCHAR EFTBUFFER BitCount2[8], *HashResult);
extern "C" EXPORT int EFT_EE9101_GenerateKey_Diebold( IN UCHAR FM, IN EFTBUFFER *I_HOST, IN EFTBUFFER *I_ATM, IN EFTBUFFER *r_ATM, IN KEYSPEC *e_ATM, IN KEYSPEC *s_HOST, IN UCHAR KeyLen,
SafeNet, Inc.
470
Appendix I SHP Toolkit UCHAR EFTBUFFER EFTBUFFER KEYSPEC KeyType, *KT_B1, *r_HOST, *K_KTM);
extern "C" EXPORT int EFT_EE9102_VerifyATMResponse_Diebold( IN UCHAR FM, IN EFTBUFFER *KT_A2, IN EFTBUFFER *I_HOST, IN EFTBUFFER *r_ATM, IN EFTBUFFER *r_HOST, IN KEYSPEC *P_ATM); extern "C" EXPORT int EFT_EE9201_GenerateKTM_NCR( IN UCHAR FM, IN KEYSPEC *SK_HSM, IN KEYSPEC *PK_EPP, OUT OUT OUT OUT KEYSPEC EFTBUFFER EFTBUFFER UCHAR *KTM, *eKTM_PK_EPP, *sSK_HSM_eKTM_PK_EPP, KVC_KTM[3]);
Interchange Functions
extern "C" EXPORT int EFT_EE0402_InitialSessionKeyGeneration( IN UCHAR FM, IN KEYSPEC *KIS, IN UCHAR KeyFlags[2], OUT OUT OUT OUT _OUT _OUT _OUT _OUT _OUT _OUT _OUT _OUT _OUT UCHAR EFTBUFFER KEYSPEC UCHAR EFTBUFFER KEYSPEC UCHAR EFTBUFFER KEYSPEC UCHAR EFTBUFFER KEYSPEC UCHAR *numKeys, *eKIS_KS1, *KS1, KVC1[3], *eKIS_KS2, *KS2, KVC2[3], *eKIS_KS3, *KS3, KVC3[3], *eKIS_KS4, *KS4, KVC4[3]);
extern "C" EXPORT int EFT_EE0403_ReceiveInitialSessionKey( IN UCHAR FM, IN KEYSPEC *KIR, IN UCHAR KeyFlags[2], IN EFTBUFFER *eKIR_KS1, _IN EFTBUFFER *eKIR_KS2, _IN EFTBUFFER *eKIR_KS3, _IN EFTBUFFER *eKIR_KS4, OUT UCHAR *numKeys,
SafeNet, Inc.
471
Appendix I SHP Toolkit KEYSPEC UCHAR KEYSPEC UCHAR KEYSPEC UCHAR KEYSPEC UCHAR *KS1, KVC1[3], *KS2, KVC2[3], *KS3, KVC3[3], *KS4, KVC4[3]);
extern "C" EXPORT int EFT_EE0404_RolloverSessionKeyGeneration( IN UCHAR FM, IN UCHAR KeyFlags[2], IN KEYSPEC *KSi1, _IN KEYSPEC *KSi2, _IN KEYSPEC *KSi3, OUT OUT OUT OUT _OUT _OUT _OUT _OUT _OUT _OUT UCHAR EFTBUFFER KEYSPEC UCHAR EFTBUFFER KEYSPEC UCHAR EFTBUFFER KEYSPEC UCHAR *numKeys, *eKS_KS1, *KS1, KVC1[3], *eKS_KS2, *KS2, KVC2[3], *eKS_KS3, *KS3, KVC3[3]);
extern "C" EXPORT int EFT_EE0405_ReceiveRolloverSessionKey( IN UCHAR FM, IN UCHAR KeyFlags[2], IN KEYSPEC *KSi1, IN EFTBUFFER *eKS_KSi1, _IN _IN _IN _IN _IN _IN OUT OUT OUT _OUT _OUT _OUT _OUT _OUT KEYSPEC EFTBUFFER KEYSPEC EFTBUFFER KEYSPEC EFTBUFFER UCHAR KEYSPEC UCHAR KEYSPEC UCHAR KEYSPEC UCHAR KEYSPEC *KSi2, *eKS_KSi2, *KSi3, *eKS_KSi3, *KSi4, *eKS_KSi4, *numKeys, *KS1, KVC1[3], *KS2, KVC2[3], *KS3, KVC3[3], *KS4,
SafeNet, Inc.
472
_OUT
extern "C" EXPORT int EFT_EE0601_MigratePin( IN UCHAR FM, IN KEYSPEC *PVK1, IN UCHAR PAN[8], IN UCHAR Offset1[6], IN UCHAR PinLen, IN KEYSPEC *PVK2, OUT UCHAR Offset2[6]);
extern "C" EXPORT int EFT_EE0602_PinTranslate( IN UCHAR FM, IN UCHAR ePPKi_PIN[8], IN KEYSPEC *PPKi, IN UCHAR PFi, IN UCHAR ANB[6], IN UCHAR PFo, IN KEYSPEC *PPKo, OUT UCHAR ePPKo_PIN[8]);
extern "C" EXPORT int EFT_EE0603_PinVerify_IBM( IN UCHAR FM, IN UCHAR ePPK_PIN[8], IN KEYSPEC *PPK, IN UCHAR PF, IN UCHAR ANB[6], IN KEYSPEC *PVK, IN UCHAR pan[8], IN UCHAR Offset[6], IN UCHAR ChkLen); extern "C" EXPORT int EFT_EE0604_CalculateIBMOffset_EncPIN( IN UCHAR FM, IN UCHAR ePPK_PIN[8], IN KEYSPEC *PPK, IN UCHAR PF, IN UCHAR ANB[6], IN KEYSPEC *PVK, IN UCHAR pan[8], OUT OUT UCHAR UCHAR Offset[6], *PinLen);
SafeNet, Inc.
473
Appendix I SHP Toolkit KEYSPEC *PVK, UCHAR Validation_Data[8], UCHAR Offset[6], UCHAR Pin_Length, KEYSPEC *PPK, UCHAR PFo, UCHAR ANB[6], UCHAR ePPK_PIN[8]);
IN IN IN IN IN IN IN OUT
extern "C" int IN IN IN IN IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN
EFT_EE0641_Print_eKMPin( UCHAR FM, KEYSPEC *eKM_PIN, UCHAR ANB[6], UCHAR PAN[8], UCHAR UCHAR UCHAR EFTBUFFER UCHAR UCHAR EFTBUFFER UCHAR UCHAR EFTBUFFER UCHAR UCHAR EFTBUFFER UCHAR UCHAR EFTBUFFER UCHAR UCHAR EFTBUFFER UCHAR UCHAR EFTBUFFER UCHAR UCHAR EFTBUFFER DataSets, *LineNo1, *ColumnNo1, *Data1, *LineNo2, *ColumnNo2, *Data2, *LineNo3, *ColumnNo3, *Data3, *LineNo4, *ColumnNo4, *Data4, *LineNo5, *ColumnNo5, *Data5, *LineNo6, *ColumnNo6, *Data6, *LineNo7, *ColumnNo7, *Data7, *LineNo8, *ColumnNo8, *Data8,
SafeNet, Inc.
474
extern "C" int EFT_EE0642_Verify_eKMPin( IN UCHAR FM, IN UCHAR ePPK_PIN[8], IN KEYSPEC *PPK, IN UCHAR PF, IN UCHAR ANB[6], IN EFTBUFFER *eKM_PIN);
extern "C" int EFT_EE0643_TRANSPIN_PPKTOLMK( IN UCHAR FM, IN UCHAR ePPK_PIN[8], IN KEYSPEC *PPK, IN UCHAR PF, IN UCHAR ANB[6], OUT KEYSPEC *eKM_PIN);
extern "C" int EFT_EE0644_Migrate_eKMPin( IN UCHAR FM, IN KEYSPEC *eKM_PINi, IN UCHAR ANB[6], OUT KEYSPEC *eKM_PINo);
VISA Functions
extern "C" EXPORT int EFT_EE0605_PINVerify_VISA( IN UCHAR FM, IN UCHAR ePPKi_PIN[8], IN KEYSPEC *PPKi, IN UCHAR PFi, IN UCHAR ANB[6], IN KEYSPEC *PVVK, IN UCHAR TSP12[6], IN UCHAR PVV[2]); extern "C" EXPORT int EFT_EE0606_CalculatePVV_IBM( IN UCHAR FM, IN KEYSPEC *PVK, IN UCHAR PAN[8], IN UCHAR Offset[2], IN KEYSPEC *PVVK, IN UCHAR TSP12[6], OUT UCHAR PVV[2]);
SafeNet, Inc.
475
extern "C" EXPORT int EFT_EE0607_CalculatePVV_EncPIN( IN UCHAR FM, IN UCHAR ePPKi_PIN[8], IN KEYSPEC *PPKi, IN UCHAR PFi, IN UCHAR ANB[6], IN KEYSPEC *PVVK, IN UCHAR TSP12[6], OUT UCHAR PVV[2]);
extern "C" EXPORT int EFT_EE0615_SEEDTranslation( IN UCHAR FM, IN EFTBUFFER *ePPK_PIN, IN KEYSPEC *PPKi, IN UCHAR PFi, IN EFTBUFFER *ANB, IN UCHAR PFo, IN KEYSPEC *PPKo, OUT EFTBUFFER *ePPKo_PIN);
extern "C" EXPORT int EFT_EE0802_CVVGenerate( IN UCHAR FM, IN EFTBUFFER *CVK_Spec, IN UCHAR CVV_Data[16], OUT UCHAR CVV[2]);
extern "C" EXPORT int EFT_EE0803_CVVVerify( IN UCHAR FM, IN EFTBUFFER *CVK_Spec, IN UCHAR CVV_Data[16], IN UCHAR CVV[2]);
extern "C" EXPORT int EFT_EE0701_MACGenerate_Final( IN UCHAR FM, IN UCHAR algorithm, IN UCHAR MacLen, IN UCHAR icd[8], IN KEYSPEC *MPK, IN EFTBUFFER *data, OUT EFTBUFFER *mac);
extern "C" EXPORT int EFT_EE0702_MACVerify_Final( IN UCHAR FM, IN UCHAR algorithm, IN UCHAR icd[8],
SafeNet, Inc.
476
IN IN IN
extern "C" EXPORT int EFT_EE0801_Decipher( IN UCHAR FM, IN KEYSPEC *DPK, IN UCHAR CipherMode, IN UCHAR ICV[8], IN EFTBUFFER *enc_data, OUT OUT UCHAR EFTBUFFER OCV[8], *clear_data);
extern "C" EXPORT int EFT_EE0804_Encipher3( IN UCHAR FM, IN KEYSPEC *DPK, IN UCHAR CipherMode, IN EFTBUFFER *ICV, IN EFTBUFFER *clear_data, OUT OUT EFTBUFFER EFTBUFFER *OCV, *enc_data);
extern "C" EXPORT int EFT_EE0805_Decipher3( IN UCHAR FM, IN KEYSPEC *DPK, IN UCHAR CipherMode, IN EFTBUFFER *ICV, IN EFTBUFFER *enc_data, OUT OUT EFTBUFFER EFTBUFFER *OCV, *clear_data);
extern "C" EXPORT int EFT_EE0806_EncipherKTM1( IN UCHAR FM, IN KEYSPEC *DPK, IN UCHAR CipherMode, IN EFTBUFFER *ICV, IN KEYSPEC *KTM, OUT OUT EFTBUFFER EFTBUFFER *OCV, *eDPK_KTM);
MasterCard Functions
extern "C" EXPORT int EFT_A0_MT_KPE_Gen( IN UCHAR MTIndex,
SafeNet, Inc.
477
extern "C" EXPORT int EFT_A1_MT_KPE_Rcv( IN UCHAR MTIndex, IN UCHAR eKEKn_KPE[8], OUT OUT UCHAR UCHAR eKMv1_KPE[8], KCV[2]);
extern "C" EXPORT int EFT_A2_MT_PIN_Tran( IN UCHAR PF, IN UCHAR ePPK_PIN[8], IN UCHAR eKMv1_PPK[8], IN UCHAR MTIndex, IN UCHAR ANB[6], OUT UCHAR eKPE_AS_PIN[8]);
extern "C" EXPORT int EFT_A3_MT_PIN_Ver( IN UCHAR PVKIndex, IN UCHAR eKPE_AS_PIN[8], IN UCHAR MTIndex, IN UCHAR PAN[8], IN UCHAR ANB[6], IN UCHAR Offset[6]); extern "C" EXPORT int EFT_A7_MT_PIN_Ver_PVV( IN UCHAR PVVKIndex, IN UCHAR eKPE_AS_PIN[8], IN UCHAR MTIndex, IN UCHAR ANB[6], IN UCHAR TSP12[6], IN UCHAR PVV[2]);
extern "C" EXPORT int EFT_A9_CreateCSCK ( IN UCHAR CSCK_storage_indicator, OUT OUT KEYSPEC UCHAR *CSCK, KVC[3]);
extern "C" EXPORT int EFT_AA_ExportCSCK ( IN KEYSPEC *CSCK, IN KEYSPEC *KIS, OUT OUT UCHAR UCHAR eKIS_CSCK[16], KVC[3]);
SafeNet, Inc.
478
Appendix I SHP Toolkit KEYSPEC UCHAR KEYSPEC UCHAR *KIR, eKIR_CSCK[16], *CSCK, KVC[3]);
IN IN OUT OUT
SafeNet, Inc.
479
Appendix I SHP Toolkit UCHAR UCHAR KEYSPEC UCHAR PFo, ANB[6], *PPK, ePPK_PIN[8]);
IN IN IN OUT
extern "C" EXPORT int EFT_EE0E05_PrintPIN( IN UCHAR *ESMID, IN UCHAR FM, IN UCHAR ePPK_PIN[8], IN KEYSPEC *PPK, IN UCHAR PFi, IN UCHAR ANB[6], IN UCHAR PAN[8], IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN UCHAR UCHAR UCHAR EFTBUFFER UCHAR UCHAR EFTBUFFER UCHAR UCHAR EFTBUFFER UCHAR UCHAR EFTBUFFER UCHAR UCHAR EFTBUFFER UCHAR UCHAR EFTBUFFER UCHAR UCHAR EFTBUFFER UCHAR UCHAR EFTBUFFER UCHAR UCHAR EFTBUFFER UCHAR UCHAR EFTBUFFER DataSets, *LineNo1, *ColumnNo1, *Data1, *LineNo2, *ColumnNo2, *Data2, *LineNo3, *ColumnNo3, *Data3, *LineNo4, *ColumnNo4, *Data4, *LineNo5, *ColumnNo5, *Data5, *LineNo6, *ColumnNo6, *Data6, *LineNo7, *ColumnNo7, *Data7, *LineNo8, *ColumnNo8, *Data8, *LineNo9, *ColumnNo9, *Data9, *LineNo10, *ColumnNo10, *Data10);
EMV Functions
SafeNet, Inc.
480
extern "C" EXPORT int EFT_EE0002_EMVGenRandomNumber( IN UCHAR FM, IN UCHAR Len, OUT EFTBUFFER *RAND_NUM);
extern "C" EXPORT int EFT_EE2000_EMVAcGen( IN UCHAR FM, IN KEYSPEC *IMK_AC, IN UCHAR APANB[8], IN UCHAR RN[8], IN EFTBUFFER *AC_DATA, OUT UCHAR AC[8]);
extern "C" EXPORT int EFT_EE2001_EMVAcVerify( IN UCHAR FM, IN KEYSPEC *IMK_AC, IN UCHAR APANB[8], IN UCHAR RN[8], IN UCHAR AC[8], IN EFTBUFFER *AC_DATA); extern "C" EXPORT int EFT_EE2002_EMVDacGen( IN UCHAR FM, IN KEYSPEC *IMK_DAC, IN UCHAR APANB[8], OUT UCHAR DAC[2]);
extern "C" EXPORT int EFT_EE2003_EMVDacVerify( IN UCHAR FM, IN KEYSPEC *IMK_DAC, IN UCHAR APANB[8], IN UCHAR DAC[2]); extern "C" EXPORT int EFT_EE2004_EMVIccDnGen( IN UCHAR FM, IN KEYSPEC *IMK_IDN, IN UCHAR APANB[8], IN UCHAR RN[8], OUT UCHAR IDN[2]); extern "C" EXPORT int EFT_EE2005_EMVIccDnVerify( IN UCHAR FM, IN KEYSPEC *IMK_IDN, IN UCHAR APANB[8], IN UCHAR RN[8], IN UCHAR IDN[2]); extern "C" EXPORT int EFT_EE2006_EMVArpcGen( IN UCHAR FM, IN KEYSPEC *IMK_AC, IN UCHAR APANB[8], IN UCHAR ARPC_DATA[8], OUT UCHAR ARPC[8]);
SafeNet, Inc.
481
Appendix I SHP Toolkit UCHAR KEYSPEC KEYSPEC UCHAR UCHAR EFTBUFFER USHORT EFTBUFFER EFTBUFFER UCHAR SC, *IMK_SMI, *IMK_SMC, APANB[8], RN[8], *Text, Offset, *Script_Data, *eSMC_Text, MAC[8]);
IN IN IN IN IN IN IN IN OUT OUT
extern "C" EXPORT int EFT_EF2010_EMVVerifyAc_EMV2000( IN UCHAR FM, IN KEYSPEC *IMK_AC, IN UCHAR PAN_data[8], IN UCHAR IV[16], IN UCHAR H, IN UCHAR b, IN UCHAR ATC[2], IN UCHAR AC[8], IN EFTBUFFER *AC_DATA); extern "C" EXPORT int EFT_EF2010_EMVVerifyAc_EMV2000_2( IN UCHAR FM, IN KEYSPEC *IMK_AC, IN UCHAR PAN_data[8], IN UCHAR IV[16], IN UCHAR H, IN UCHAR b, IN UCHAR ATC[2], IN EFTBUFFER *AC, IN EFTBUFFER *AC_DATA, IN KEYSPEC bitmap); extern "C" EXPORT int EFT_EF2011_EMVVerifyAcVisa( IN UCHAR FM, IN KEYSPEC *IMK_AC, IN UCHAR PAN[8], IN UCHAR AC[8], IN EFTBUFFER *AC_DATA); extern "C" EXPORT int EFT_EF2011_EMVVerifyAcVisa_2( IN UCHAR FM, IN KEYSPEC *IMK_AC, IN UCHAR PAN[8], IN EFTBUFFER *AC, IN EFTBUFFER *AC_DATA, IN KEYSPEC bitmap);
SafeNet, Inc.
482
extern "C" EXPORT int EFT_EF2012_EMVGenerateArpc( IN UCHAR FM, IN KEYSPEC *IMK_AC, IN UCHAR PAN_data[8], IN UCHAR IV[16], IN UCHAR H, IN UCHAR b, IN UCHAR ATC[2], IN UCHAR ARPC_data[8], OUT UCHAR ARPC[8]);
extern "C" EXPORT int EFT_EF2013_EMVScriptCrypto_EMV2000( IN UCHAR FM, IN UCHAR SC, IN KEYSPEC *IMK_SMI, IN KEYSPEC *IMK_SMC, IN UCHAR PAN_data[8], IN UCHAR IV[16], IN UCHAR H, IN UCHAR b, IN UCHAR ATC[2], IN UCHAR encrypt_mode, IN EFTBUFFER *Text, IN USHORT Offset, IN EFTBUFFER *Script_Data, OUT OUT EFTBUFFER UCHAR *eSMC_Text, MAC[8]);
extern "C" EXPORT int EFT_EF2014_EMVScriptCryptoVisa( IN UCHAR FM, IN UCHAR SC, IN KEYSPEC *IMK_SMI, IN KEYSPEC *IMK_SMC, IN UCHAR PAN_data[8], IN UCHAR ATC[2], IN EFTBUFFER *Text, IN USHORT Offset, IN EFTBUFFER *Script_Data, OUT OUT EFTBUFFER *eSMC_Text, UCHAR MAC[8]);
SafeNet, Inc.
483
extern "C" EXPORT int EFT_EF2015_EMVPinChangeUnblockVisa( IN UCHAR FM, IN UCHAR P2, IN KEYSPEC *IMK_SMI, IN KEYSPEC *IMK_SMC, IN UCHAR PAN_data[8], IN UCHAR ATC[2], IN KEYSPEC *PPK, IN UCHAR ePPK_PIN[8], IN UCHAR ANB[6], IN KEYSPEC *PVK, IN UCHAR Validation_data[8], IN UCHAR Offset[6], IN UCHAR PIN_len, IN USHORT Script_Data_Pos, IN EFTBUFFER *Script_Data, OUT OUT EFTBUFFER *New_PIN_Data, UCHAR MAC[8]);
extern "C" EXPORT int EFT_EE2016_EMVPinChangeUnBlock( IN UCHAR FM, IN UCHAR P2, IN UCHAR Scheme, IN KEYSPEC *IMK_SMI, IN KEYSPEC *IMK_SMC, IN KEYSPEC *IMK_AC, IN EFTBUFFER *PAN_data, IN EFTBUFFER *SK_Data, IN UCHAR ePPK_PIN1[8], IN UCHAR ePPK_PIN2[8], IN KEYSPEC *PPK, IN UCHAR PF, IN UCHAR ANB[6], IN USHORT Script_Data_Pos, IN EFTBUFFER *Script_Data, OUT OUT EFTBUFFER *New_PIN_Data, UCHAR MAC[8]);
extern "C" EXPORT int EFT_EE2017_EMVPinChangeUnBlockEMV2000( IN UCHAR FM, IN UCHAR P2, IN UCHAR Scheme, IN KEYSPEC *IMK_SMI, IN KEYSPEC *IMK_SMC, IN KEYSPEC *IMK_AC, IN UCHAR PAN_data[8], IN UCHAR IV[16], IN UCHAR H, IN UCHAR b, IN UCHAR ATC[2], IN UCHAR ePPK_PIN1[8], IN UCHAR ePPK_PIN2[8], IN KEYSPEC *PPK, IN UCHAR PF, IN UCHAR ANB[6], IN USHORT Script_Data_Pos, IN EFTBUFFER *Script_Data,
SafeNet, Inc.
484
OUT OUT
extern "C" EXPORT int EFT_EE2018_EMV_VerifyAC_GenerateARPC( IN UCHAR FM, IN UCHAR Action, IN KEYSPEC *IMK_AC, IN UCHAR MK_Method, IN EFTBUFFER *MK_Data, IN UCHAR AC_Key_Method, IN EFTBUFFER *AC_Key_Data, IN UCHAR AC_Method, IN EFTBUFFER *AC_Data, IN UCHAR AC[8], IN UCHAR ARPC_Key_Method, IN EFTBUFFER *ARPC_Key_Data, IN UCHAR ARPC_Method, IN EFTBUFFER *ARPC_Data, _OUT EFTBUFFER *ARPC);
extern "C" EXPORT int EFT_EE2019_ EMV_AC_Generate_MULTI ( IN UCHAR FM, IN KEYSPEC *IMK_AC, IN UCHAR MK_Method, IN EFTBUFFER *MK_Data, IN UCHAR AC_Key_Method, IN EFTBUFFER *AC_Key_Data, IN UCHAR AC_Method, IN EFTBUFFER *AC_Data _OUT UCHAR AC[8] );
extern "C" EXPORT int EFT_EE2020_EMVScriptCrypto_Multi( IN UCHAR FM, IN UCHAR SC, IN KEYSPEC *IMK_SMI, IN KEYSPEC *IMK_SMC, IN UCHAR MK_Method, IN EFTBUFFER *MK_Data, IN UCHAR SM_Key_Method, IN EFTBUFFER *SM_Key_Data, IN UCHAR SM_method, IN EFTBUFFER *Text, IN USHORT Offset, IN EFTBUFFER *Script_Data, OUT OUT EFTBUFFER UCHAR *eSMC_Text, MAC[8]);
CEPS Functions
extern "C" EXPORT int EFT_EF0701_VcepsVerS1GenS2( IN UCHAR FM, IN KEYSPEC *KMx, IN UCHAR IDcep[6],
SafeNet, Inc.
485
Appendix I SHP Toolkit UCHAR UCHAR EFTBUFFER EFTBUFFER UCHAR NTcep[2], MAC_S1[8], *S1_Data, *S2_Data, MAC_S2[8]);
IN IN IN IN OUT
extern "C" EXPORT int EFT_EF0702_VcepsVerSn( IN UCHAR FM, IN KEYSPEC *KMx, IN EFTBUFFER *Deriv_Data, IN EFTBUFFER *Session_Data, IN UCHAR MAC_Sn[8], IN EFTBUFFER *Sn_Data); extern "C" EXPORT int EFT_EF0703_VcepsGenSn( IN UCHAR FM, IN KEYSPEC *KMx, IN EFTBUFFER *Deriv_Data, IN EFTBUFFER *Session_Data, IN EFTBUFFER *Sn_Data, OUT UCHAR MAC_Sn[8]);
extern "C" EXPORT int EFT_EF0704_VcepsSMacVerLSam( IN UCHAR FM, IN KEYSPEC *LSAMK, IN UCHAR eLSAMK_R1[16], IN UCHAR MAC[4], IN EFTBUFFER *Data); extern "C" EXPORT int EFT_EF0F01_VcepsGenHashCep( IN UCHAR FM, IN KEYSPEC *KMx, IN UCHAR IDcep[6], IN EFTBUFFER *Hash_Data, OUT UCHAR Hcep[10]);
extern "C" EXPORT int EFT_EE3031_KisSend( IN UCHAR FM, IN KEYSPEC *SK, IN KEYSPEC *PKr, OUT OUT OUT OUT KEYSPEC EFTBUFFER EFTBUFFER UCHAR *KIS, *Signed_Hash, *ePKr_KIS, KVC_KIS[3] );
SafeNet, Inc.
486
Appendix I SHP Toolkit UCHAR KEYSPEC EFTBUFFER EFTBUFFER KEYSPEC KEYSPEC UCHAR FM, *SK, *Signed_Hash, *ePKr_KIR, *PK, *KIR, KVC_KIR[3]);
IN IN IN IN IN OUT OUT
extern "C" EXPORT int EFT_EE3033_NodeProof( IN UCHAR FM, IN UCHAR len, IN KEYSPEC *KIS, OUT OUT EFTBUFFER EFTBUFFER *eKISv82_RNs, *eKISv84_RNr);
extern "C" EXPORT int EFT_EE3034_NodeResp( IN UCHAR FM, IN KEYSPEC *KIR, IN EFTBUFFER *eKIRv82_RNs, OUT EFTBUFFER *eKIRv84_RNr);
Key Block
extern "C" EXPORT int EFT_EE0628_ReceiveRolloverSessionKey( IN UCHAR FM, IN KEYSPEC *KTM, IN UCHAR Algorithm, IN UCHAR KeyLen[2], IN UCHAR KeyType, IN UCHAR TerminalKeyFormat, IN UCHAR HostKeyFormat, IN UCHAR KVCFormat, IN UCHAR VerID, IN UCHAR KeyUsage[2], IN UCHAR Mode, IN UCHAR KeyVerNum[2], IN UCHAR Export, IN UCHAR Padding, IN UCHAR NumOptFields, _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN OUT OUT OUT EFTBUFFER EFTBUFFER EFTBUFFER EFTBUFFER EFTBUFFER EFTBUFFER EFTBUFFER EFTBUFFER EFTBUFFER EFTBUFFER EFTBUFFER KEYSPEC EFTBUFFER *OptField1, *OptField2, *OptField3, *OptField4, *OptField5, *OptField6, *OptField7, *OptField8, *OptField9, *OptField10, *TerminalKey, *HostKey, *KVC);
ZKA Functions
SafeNet, Inc.
487
extern "C" EXPORT int EFT_EE0210_ZKA_Import_MK( IN UCHAR FM, IN UCHAR eKTK_K[16], IN KEYSPEC *KTK, IN UCHAR Enc_Mode, IN UCHAR Key_Type, IN UCHAR ICM, IN EFTBUFFER *ICV, OUT KEYSPEC *eKMx_K);
extern "C" EXPORT int EFT_EE0610_ZKA_PIN_Translate( IN UCHAR FM, IN UCHAR ePPKi_PIN[8], IN KEYSPEC *PPKi, IN UCHAR PFi, IN UCHAR ANB[6], IN UCHAR PFo, IN KEYSPEC *MK, OUT OUT UCHAR UCHAR ePPKo_PIN[8], RNDo[16]);
extern "C" EXPORT int EFT_EE0611_ZKA_PIN_Ver_ecVAR( IN UCHAR FM, IN UCHAR ePPK_PIN[8], IN KEYSPEC *PPK, IN UCHAR PF, IN UCHAR ANB[6], IN KEYSPEC *KK_BLZ, IN UCHAR Account_Number[5], IN UCHAR CSN, IN UCHAR Expiration_Year, IN UCHAR PVN_Type, IN UCHAR PVN[2]); extern "C" EXPORT int EFT_EE0612_ZKA_PIN_Ver_enc_PIN( IN UCHAR FM, IN UCHAR ePPK_PIN[8], IN KEYSPEC *PPK, IN UCHAR PF, IN UCHAR ANB[6], IN KEYSPEC *KK_BLZ, IN UCHAR Account_Number[5], IN UCHAR CSN, IN UCHAR Expiration_Year, IN UCHAR PVN_Type, OUT OUT EFTBUFFER UCHAR *PVN, *PIN_Length);
extern "C" EXPORT int EFT_EE0613_ZKA_PIN_Translate( IN UCHAR FM, IN UCHAR ePPKi_PIN[8], IN KEYSPEC *PPKi, IN UCHAR PFi, IN UCHAR ANB[6], IN UCHAR PFo, IN KEYSPEC *MK2_1,
SafeNet, Inc.
488
extern "C" EXPORT int EFT_EE0710_ZKA_MAC_Generate( IN UCHAR FM, IN UCHAR Algorithm, IN UCHAR MacLen, IN UCHAR ICD[8], IN KEYSPEC *MK, IN EFTBUFFER *Data, IN UCHAR C[2], OUT OUT EFTBUFFER UCHAR *MAC, RND[16]);
extern "C" EXPORT int EFT_EE0711_ZKA_MAC_Gen_1( IN UCHAR FM, IN UCHAR Algorithm, IN UCHAR MacLen, IN UCHAR ICD[8], IN KEYSPEC *MK2_1, IN EFTBUFFER *Data, IN UCHAR Offset1[2], IN UCHAR Offset2[2], IN UCHAR Offset3[2], OUT OUT OUT EFTBUFFER UCHAR KEYSPEC *MAC, RND[16], *MK2_2);
SafeNet, Inc.
489
extern "C" EXPORT int EFT_EE3101_ HSMSoftwareStatus( IN UCHAR *ESMID, IN UCHAR FM, OUT OUT OUT UCHAR EFTBUFFER UCHAR *Status, *Version); Data_len [4]);
extern "C" EXPORT int EFT_EE3001_OBM_GenerateRandomNumber( IN UCHAR FM, IN UCHAR Length, OUT EFTBUFFER *RandomNumber);
extern "C" EXPORT int EFT_EE3002_OBM_VerifyPIN_RSAEncrypted_3624Offset( IN UCHAR FM, IN KEYSPEC *SK, IN EFTBUFFER *C, IN EFTBUFFER *P, IN EFTBUFFER *RN, IN KEYSPEC *PVK, IN UCHAR ValidationData[8], IN UCHAR Offset[6]);
extern "C" EXPORT int EFT_EE3003_OBM_ChangePIN_RSAEncrypted_3624Offset( IN UCHAR FM, IN KEYSPEC *SK, IN EFTBUFFER *C, IN EFTBUFFER *P, IN EFTBUFFER *RN, IN KEYSPEC *PVK1, IN UCHAR ValidationData1[8], IN UCHAR Offset1[6], IN KEYSPEC *PVK2, IN UCHAR ValidationData2[8], OUT UCHAR Offset2[6]);
SafeNet, Inc.
490
extern "C" EXPORT int EFT_EE3004_OBM_SetPassword_RSAEncrypted_TPV( IN UCHAR FM, IN KEYSPEC *SK, IN EFTBUFFER *C, IN EFTBUFFER *P, IN EFTBUFFER *RN, IN UCHAR AlgorithmID, IN EFTBUFFER *DataA, IN EFTBUFFER *DataB, IN KEYSPEC *KTPV, OUT EFTBUFFER *ReferenceTPV);
extern "C" EXPORT int EFT_EE3005_OBM_VerifyPassword_RSAEncrypted_TPV( IN UCHAR FM, IN KEYSPEC *SK, IN EFTBUFFER *C, IN EFTBUFFER *P, IN EFTBUFFER *RN, IN UCHAR AlgorithmID, IN EFTBUFFER *DataA, IN EFTBUFFER *DataB, IN KEYSPEC *KTPV, IN EFTBUFFER *ReferenceTPV); extern "C" EXPORT int EFT_EE3006_OBM_ChangePassword_RSAEncrypted_TPV( IN UCHAR FM, IN KEYSPEC *SK, IN EFTBUFFER *C, IN EFTBUFFER *P, IN EFTBUFFER *RN, IN UCHAR AlgorithmID1, IN EFTBUFFER *DataA1, IN EFTBUFFER *DataB1, IN KEYSPEC *KTPV1, IN EFTBUFFER *ReferenceTPV1, IN UCHAR AlgorithmID2, IN EFTBUFFER *DataA2, IN EFTBUFFER *DataB2, IN KEYSPEC *KTPV2, OUT EFTBUFFER *ReferenceTPV2);
extern "C" EXPORT int EFT_EE3008_OBM_Prextern "C" EXPORT intPassword( IN UCHAR *ESMID, IN UCHAR FM, IN UCHAR PasswordType, IN UCHAR PasswordLength, IN UCHAR AlgorithmID, IN EFTBUFFER *DataA, IN EFTBUFFER *DataB, IN KEYSPEC *KTPV, IN UCHAR DataSets, _IN _IN _IN _IN UCHAR *LineNo1, UCHAR *ColumnNo1, EFTBUFFER *Data1, UCHAR *LineNo2,
SafeNet, Inc.
491
Appendix I SHP Toolkit UCHAR *ColumnNo2, EFTBUFFER *Data2, UCHAR *LineNo3, UCHAR *ColumnNo3, EFTBUFFER *Data3, UCHAR *LineNo4, UCHAR *ColumnNo4, EFTBUFFER *Data4, UCHAR *LineNo5, UCHAR *ColumnNo5, EFTBUFFER *Data5, UCHAR *LineNo6, UCHAR *ColumnNo6, EFTBUFFER *Data6, UCHAR *LineNo7, UCHAR *ColumnNo7, EFTBUFFER *Data7, UCHAR *LineNo8, UCHAR *ColumnNo8, EFTBUFFER *Data8, UCHAR *LineNo9, UCHAR *ColumnNo9, EFTBUFFER *Data9, UCHAR *LineNo10, UCHAR *ColumnNo10, EFTBUFFER *Data10, EFTBUFFER *ReferenceTPV);
_IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN OUT
extern "C" EXPORT int EFT_EE3009_OBM_MigratePIN_OffsetToTPV( IN UCHAR FM, IN KEYSPEC *PVK, IN UCHAR ValidationData[8], IN UCHAR Offset[6], IN UCHAR PINLength, IN UCHAR AlgorithmID, IN EFTBUFFER *DataA, IN EFTBUFFER *DataB, IN KEYSPEC *KTPV, OUT EFTBUFFER *ReferenceTPV);
extern "C" EXPORT int EFT_EE3016_OBM_GetPrextern "C" EXPORT intToken( IN UCHAR *ESMID, IN UCHAR FM, OUT UCHAR Prextern "C" EXPORT intToken[8]);
extern "C" EXPORT int EFT_EE3017_OBM_GenerateRandomPIN( IN UCHAR FM, IN UCHAR Pextern "C" EXPORT intype, IN UCHAR PINLength,
SafeNet, Inc.
492
Appendix I SHP Toolkit UCHAR AlgorithmID, EFTBUFFER *DataA, EFTBUFFER *DataB, KEYSPEC *KTPV, UCHAR Prextern "C" EXPORT intToken[8], KEYSPEC *PPK, EFTBUFFER EFTBUFFER *ePPK_PIN, *ReferenceTPV);
IN IN IN IN IN IN OUT OUT
extern "C" EXPORT int EFT_EE3018_OBM_Prextern "C" EXPORT intEncryptedPIN( IN UCHAR *ESMID, IN UCHAR FM, IN UCHAR PINLength, IN KEYSPEC *PPK, IN EFTBUFFER *ePPK_PIN, IN UCHAR DataSets, _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN _IN UCHAR *LineNo1, UCHAR *ColumnNo1, EFTBUFFER *Data1, UCHAR *LineNo2, UCHAR *ColumnNo2, EFTBUFFER *Data2, UCHAR *LineNo3, UCHAR *ColumnNo3, EFTBUFFER *Data3, UCHAR *LineNo4, UCHAR *ColumnNo4, EFTBUFFER *Data4, UCHAR *LineNo5, UCHAR *ColumnNo5, EFTBUFFER *Data5, UCHAR *LineNo6, UCHAR *ColumnNo6, EFTBUFFER *Data6, UCHAR *LineNo7, UCHAR *ColumnNo7, EFTBUFFER *Data7, UCHAR *LineNo8, UCHAR *ColumnNo8, EFTBUFFER *Data8, UCHAR *LineNo9, UCHAR *ColumnNo9, EFTBUFFER *Data9, UCHAR *LineNo10, UCHAR *ColumnNo10, EFTBUFFER *Data10);
SafeNet, Inc.
493
Appendix I SHP Toolkit UCHAR UCHAR KEYSPEC EFTBUFFER EFTBUFFER EFTBUFFER KEYSPEC UCHAR UCHAR EFTBUFFER *ESMID, FM, *SK, *C, *P, *RN, *PPKo, PFo, ANB[6], *ePPKo_PIN);
IN IN IN IN IN IN IN IN IN OUT
extern "C" EXPORT int EFT_EE3020_OBM_SetPIN_PPKencrypted_TPV( IN UCHAR *ESMID, IN UCHAR FM, IN EFTBUFFER *ePPKi_PIN, IN KEYSPEC *PPKi, IN UCHAR PFi, IN UCHAR ANB[6], IN UCHAR AlgorithmID, IN EFTBUFFER *DataA, IN EFTBUFFER *DataB, IN KEYSPEC *KTPV, OUT EFTBUFFER *ReferenceTPV);
SHP Toolkit CI
This appendix provides the list of function definitions for the SHP Toolkit CI application programming interface (API). The functions that make up the C API accept and return data in standard C variable types and / or the set of structures as described in the Mark II Programmers Guide. (The structures are defined in the file eftApiBase.h).
EXPORT int EFT_EE0608_PIN_Translate_VSDC( IN UCHAR FM, IN UCHAR ePPKi_PIN[8], IN KEYSPEC *PPKi, IN UCHAR PFi, IN UCHAR ANB[6], IN UCHAR PFo, IN KEYSPEC *PPKo, IN UCHAR Encryption_Method, IN EFTBUFFER *PIN_Data, OUT EFTBUFFER *ePPKo_PIN);
EXPORT int EFT_EE2040_GenerateIssuerKeyPair( IN UCHAR FM, IN USHORT key_len, IN EFTBUFFER *exponent, IN EFTBUFFER *user_data, OUT OUT KEYSPEC KEYSPEC *PK_spec, *SK_spec);
SafeNet, Inc.
494
EXPORT int EFT_EE2041_SelfCertIssuerPublicKey( IN UCHAR FM, IN KEYSPEC *SK_spec, IN KEYSPEC *PK_spec, IN UCHAR cert_subject_id[4], IN UCHAR cert_exp_date[2], IN UCHAR cert_serial_no[3], IN UCHAR hash_alg_indicator, IN UCHAR Iss_PK_index[3], OUT OUT OUT OUT OUT OUT OUT UCHAR UCHAR EFTBUFFER UCHAR EFTBUFFER EFTBUFFER UCHAR *Iss_PK_len, *Iss_PK_exp_len, *PK_left_digits, PK_remainder[36], *PK_exponent, *PK_certificate, PK_check_sum[20]);
EXPORT int EFT_EE2042_VerifyCAPublicKeyMC( IN UCHAR FM, IN UCHAR ID_cert_subject[5], IN UCHAR PK_index, IN UCHAR PK_alg_indicator, IN EFTBUFFER *PK_left_digits, IN UCHAR PK_remainder[37], IN EFTBUFFER *PK_exp, IN EFTBUFFER *PK_cert, IN EFTBUFFER *PK_checksum, IN UCHAR hash_alg_indicator, IN EFTBUFFER *user_data, OUT OUT OUT UCHAR EFTBUFFER KEYSPEC *validation_result, *cert_data, *PK);
EXPORT int EFT_EE2043_VerifyIssuerPKCertMC( IN UCHAR FM, IN KEYSPEC *CA_PK_spec, IN KEYSPEC *Iss_PK_spec, IN EFTBUFFER *Iss_PK_rem, IN EFTBUFFER *PK_exp, IN EFTBUFFER *PK_cert, OUT OUT UCHAR EFTBUFFER *validation_result, *cert_data);
EXPORT int EFT_EE2044_SelfSignIssuerPKVisa( IN UCHAR FM, IN KEYSPEC *Iss_SK_spec, IN KEYSPEC *Iss_PK_spec, IN UCHAR Gen_PK_Data[15], IN UCHAR hash_alg_indicator, IN UCHAR Iss_PK_ind, OUT OUT EFTBUFFER UCHAR *signature, HashResult[20]);
SafeNet, Inc.
495
Appendix I SHP Toolkit UCHAR UCHAR UCHAR UCHAR EFTBUFFER EFTBUFFER UCHAR EFTBUFFER EFTBUFFER KEYSPEC EFTBUFFER FM, CA_PK_alg_indicator, RID[5], CA_PK_index, *CA_PK_modulus, *CA_PK_exp, hash_data[20], *CA_PK_cert, *user_data, *CA_PK_spec, *cert_data);
IN IN IN IN IN IN IN IN IN OUT OUT
EXPORT int EFT_EE2046_VerifyIssuerPKCertVisa( IN UCHAR FM, IN KEYSPEC *Pca, IN KEYSPEC *Pi, IN EFTBUFFER *IPK_modulus_rem, IN EFTBUFFER *IPK_exp, IN EFTBUFFER *IPK_cert, OUT OUT UCHAR EFTBUFFER *validation_result, *cert_data);
EXPORT int EFT_EE2047_VerifyDetachedCertVisa( IN UCHAR FM, IN KEYSPEC *Pca, IN EFTBUFFER *detached_signature, IN EFTBUFFER *hash_data); EXPORT int EFT_EE2048_GenerateICCKeypair( IN UCHAR FM, IN KEYSPEC *SK, IN EFTBUFFER *cert_data, IN KEYSPEC *KTK, IN UCHAR enc_method, IN UCHAR Pxx_flag, IN EFTBUFFER *user_data, OUT OUT OUT OUT OUT EFTBUFFER EFTBUFFER EFTBUFFER EFTBUFFER KEYSPEC *eKTK_SK_mod, *eKTK_SK_exp, *ICC_PK_cert, *ICC_PK_rem, *PK_spec);
EXPORT int EFT_EE2049_VerifyICCCertificate( IN UCHAR FM, IN KEYSPEC *PK, IN EFTBUFFER *ICC_PK_cert, IN EFTBUFFER *ICC_PK_rem, IN EFTBUFFER *ICC_PK_exp, IN EFTBUFFER *static_data, IN EFTBUFFER *user_data, OUT KEYSPEC *PK_spec);
SafeNet, Inc.
496
Appendix I SHP Toolkit UCHAR KEYSPEC UCHAR UCHAR UCHAR EFTBUFFER PAN[8], *KTK, enc_method, kvc_method, eKTK_MK[24], *kvc_MK);
IN IN IN IN OUT OUT
EXPORT int EFT_EE204B_SignICCStaticData( IN UCHAR FM, IN KEYSPEC *SK, IN UCHAR SDF, IN UCHAR hash_alg_indicator, IN UCHAR data_auth_code[2], IN EFTBUFFER *static_data, OUT EFTBUFFER *signature);
EXPORT int EFT_EE204C_VerifyICCStaticData( IN UCHAR FM, IN KEYSPEC *PK, IN EFTBUFFER *static_data, IN EFTBUFFER *signature, OUT OUT OUT OUT UCHAR UCHAR UCHAR UCHAR *verify_flag, *SDF, *hash_alg_indicator, data_auth_code[2]);
EXPORT int EFT_EE204D_VerifyICCDynamicData( IN UCHAR FM, IN KEYSPEC *PKicc, IN EFTBUFFER *dynamic_data, IN EFTBUFFER *signature, OUT OUT OUT OUT UCHAR UCHAR UCHAR EFTBUFFER *verify_flag, *SDF, *hash_alg_indicator, *ICC_dynamic_data);
EXPORT int EFT_EE204E_RsaEncipherPin( IN UCHAR FM, IN KEYSPEC *PVK, IN UCHAR validation_data[8], IN UCHAR Offset[6], IN UCHAR pin_len, IN UCHAR unpredictable_no[8], IN KEYSPEC *Pic, OUT EFTBUFFER *ePxx_PIN);
EXPORT int EFT_EE204F_GenerateRandomPinEMV( IN UCHAR FM, IN KEYSPEC *PVK, IN UCHAR validation_data[8], IN UCHAR pin_len, IN UCHAR ANB[6], IN EFTBUFFER *PIN_Data, IN UCHAR enc_method, IN KEYSPEC *PTK,
SafeNet, Inc.
497
OUT OUT
UCHAR EFTBUFFER
Offset[6], *ePTK_PIN);
EXPORT int EFT_EE2050_ExportPinEMV( IN UCHAR IN KEYSPEC IN UCHAR IN UCHAR IN UCHAR IN UCHAR IN EFTBUFFER IN UCHAR IN KEYSPEC OUT EFTBUFFER
FM, *PVK, validation_data[8], Offset[6], pin_len, ANB[6], *PIN_Data, enc_method, *PTK, *ePTK_PIN);
EXPORT int EFT_EE2051_KeyExportKTK( IN UCHAR IN KEYSPEC IN UCHAR IN UCHAR IN KEYSPEC OUT OUT EFTBUFFER UCHAR
EXPORT int EFT_EE2052_DeriveNewICCKeySets( IN UCHAR FM, IN KEYSPEC *K1kek, IN KEYSPEC *K2xxx, OUT OUT OUT UCHAR UCHAR UCHAR eK1kek_K2enc[16], eK1kek_K2mac[16], eK1kek_K2kek[16]);
EXPORT int EFT_EE2053_DeriveNewICCKey( IN UCHAR IN KEYSPEC IN KEYSPEC OUT OUT UCHAR eKEK_Key[16], UCHAR KVC[3]);
EXPORT int EFT_EE2054_GenerateDCV( IN UCHAR IN EFTBUFFER IN KEYSPEC IN UCHAR IN UCHAR OUT UCHAR
EXPORT int EFT_EE2058_GENERATE_ICC_CRT_KEYPAIR( IN UCHAR FM, IN KEYSPEC *SK, IN EFTBUFFER *cert_data, IN KEYSPEC *KTK,
SafeNet, Inc.
498
Appendix I SHP Toolkit UCHAR UCHAR EFTBUFFER EFTBUFFER EFTBUFFER EFTBUFFER EFTBUFFER EFTBUFFER EFTBUFFER EFTBUFFER KEYSPEC enc_method, Pxx_flag, *user_data, *P, *Q, *PQ, *DP1, *DQ1, *ICC_PK_cert, *ICC_PK_remainder, *PK );
SafeNet, Inc.
499
SafeNet, Inc.
500
00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0F 10 11 12 13 14 15 16 17 19 1A 20 21 22 23 24 25 27 28 29 30 32 33 34 35 36
No error DES Fault (system disabled) Illegal Function Code. PIN mailing not enabled Incorrect message length Invalid data in message: Character not in range (0-9, A-F) Invalid key index: Index not defined, key with this Index not stored or incorrect key length Invalid PIN format specifier: only AS/ANSI = 1 & PIN/PAD = 3 specified PIN format error: PIN does not comply with the AS2805.3 1985 specification, is in an invalid PIN/PAD format, or is in an invalid Docutel format Verification failure Contents of key memory destroyed: e.g. the SHP (SafeNet HSM Payment) was tampered or all Keys deleted Uninitiated key accessed. Key or decimalization table (DT) is not stored in the SHP (SafeNet HSM Payment). Checklength Error. Customer PIN length is less than the minimum PVK length or less than Checklen in function. Inconsistent Request Fields: inconsistent field size. Invalid VISA Index. Invalid VISA PIN verification key indicator. Internal Error Errlog file does not exist Errlog internal error Errlog request length invalid Errlog file number invalid Errlog index number invalid Errlog date time invalid Errlog before/after flag invalid Unsupported key type Duplicate key or record Invalid key specifier length Unsupported key specifier Invalid key specifier content Invalid key specifier format Function Modifier not equal to 00 Invalid key attributes Hash process failed Invalid Key Type Unsupported Triple Des Index Invalid administrator signature No administration session Invalid file type Invalid signature KKL disabled No PIN pad
SafeNet, Inc.
501
Error Code
Meaning
37 39 3A 3B 40 50 50 51 52 53 54 60 61 62 63 64 65 66 67 70 71 72 73 74 75 76 77 78 79 7F 80 81 82 83 90 F0
Pin pad timeout Public key pair not available Public key pair generating RSA cipher error Unsupported HSM stored SEED key Invalid Variant Scheme Invalid SDF Invalid hash indicator Invalid public key algorithm Public key pair incompatible RSA key length error Software already Loaded Software being loaded from CD ROM Software data segment too large Invalid offset value Software loading not initiated Unsupported file id Unsupported control id Software image is being verified Invalid PIN Block flag Invalid PIN Block random padding Invalid PIN Block delimiter Invalid PIN Block RB Invalid PIN Block. Random number invalid Invalid PIN Block RA Invalid PIN Block PIN Invalid PIN Block PIN length PIN Block format disabled or requested reformatting not allowed Validation data check failed Invalid Print Token OAEP Decode Error OAEP Invalid Header Byte OAEP Invalid PIN Block OAEP Invalid Random Number General Printer Error Zero length PIN
SafeNet, Inc.
502
SafeNet, Inc.
503
[32] Common Personalization Specification,Visa International, Version 1.5, January 2002. [33] Global Platform Card Specification, Global Platform, Version 2.1, June 2001. [34] Schnittstellen Spezifikation fr die ZKA-Chipkarte: Secure Chip Card Operating System (SECCOS), Version 5.0, June 2001. [35] EMV Integrated Circuit Card Specification for Payment Systems: Book 2 Security and Key Management, Version 4.1, May 2004. [36] Specification Update Bulletin No. 46 Replacement of EMV Session Key Derivation Method First Edition October 2005 [37] American Express Global Network Services AEIPS Chip Card Specification 4.0 March 2003 [38] JCB Intl JCB IC Card Specification 2.0 April 2002 [39] Visa Int'l Version 1.3.2 Visa Integrated Circuit Card Card (ICC) Specification July 1999 [40] ZKA Interface Specifications for the SECCOS ICC Version 6.2 18.09.2007 with revisions [41] PayPass M/Chip Technical Specifications [42] VISA Contactless Payment Specification version 2.0.2 Jul 2006
[25]
SafeNet, Inc.
504
RSA Laboratories, PKCS#10: Certification Request Syntax Standard, v1.7, 26 May 00 RSA Laboratories, PKCS#7: Cryptographic Message Syntax Standard, v1.5, 01 Nov 93 X9.24 Part II, Symmetric Key Management, using asymmetric techniques for the distribution of symmetric keys, V1.0., ..03 Visa Int'l Visa Smart Debit Card (VSDC) Technical Guide to Visas Applet for GlobalPlatform Cards. November 2003. ISO 9564-1-2002 Banking - Personal Identification Number - PIN - management and security - Part 1- Basic principles and requirements for online PIN handling in ATM and POS systems. ISO 9564-3-2003 Banking - Personal Identification Number management and security Part 3- Requirements for offline PIN handling in ATM and POS systems. Visa International Common Personalization Specification, V1.5. January 2002. EMV Card Personalisation Specification, V1.1, July 2007.
SafeNet, Inc.
505
SafeNet, Inc.
506
Appendix L Glossary
Appendix L Glossary
51-PIN ANB The Docutel 5100 formatted PIN Block. The 12 digit Account Number Block. Used in the formation of the AS/ANSI PIN Block. Synonymous with PAN2. AS-PIN AWK bks CBC CHKLEN CVK CV CVV DATA DES DPK ECB Func. Code HMAC-SHA-1 HSM IWK KB KBn KB-index KCV KEK KGK KHT KIR KIRn KIRnx KIS KISn KISnx KI-index KK The AS/ANSI formatted PIN Block. Acquirer Working Key (Visa). A 1 byte binary field identifying the number of 8 - byte blocks in a variable length data field which follows. Cypher Block Chaining Number of PIN digits which are checked in the PIN verification procedure. Card Verification Keys (Visa). Control Vector Card Verification Value (Visa). Data to be encrypted etc. Always a multiple of 8 bytes. Data Encryption Standard Data Protect Key. Usually a random generated session key (KS). Electronic Code Book The function code is always the first field in all response and request messages. This code is in the range 01 - FF and determines fields which are expected to follow. Message authentication algorithm using SHA-1 hash. Reference RFC 2104. Hardware Security Module Issuer Working Key (Visa). Base Key for terminals (typically used for passing encrypted keys). Base Key Number n (n = 1 to 99) Refer to XX-index. Key Check Value. Key Exchange Key (MasterCard). Key Generation Key Host Transfer Key Receive Interchange Key (used for passing encrypted keys). KIR Number n (n = 1 to 99). A variant of KIRn (as for KMx below). Send Interchange Key (used for passing encrypted keys). KIS Number n (n = 1 to 99). A variant of KISn (as for KMx below). Refer to XX-index. ecPIN Verification Key
SafeNet, Inc.
507
Appendix L Glossary
KKL KM KMx
Key load key the domain master key (used for encrypting keys for storage on the host). a variant of the key KM, where: KM1 is used for PPK functions, KM2 is used for MPK functions, (KM is used for DPK functions). PIN Encryption Key (MasterCard). Session Key. Used as a PPK, MPK or DPK. The current session key. The new session key. Key Transport Key Terminal Master Key. The result of a terminal encrypting its SEC-NO with its Base Key (KB). Message Authentication Code. Calculated as per AS2805.4 1985/ANSI X9.9. Most significant 32 bits (4 bytes) are returned.
MACi MACo MCS MINPIN MK MPK OFFSET PAC PAN PAN1 PAN2 PFi PFo
The 4 byte input to a MAC translate. The 4 byte output from a MAC translate. MasterCard Switch Centre. The PIN length which is entered with the PVK. It represents the minimum PIN length permissible for the associated PVK. ZKA Master Key MAC Protect Key. 6 bytes (up to 12 digits) of data used to Offset the 'raw' PIN to get a customer PIN. PIN Authentication Code The customer Primary Account Number. The 16 digit (8 byte) PAN encrypted to give the 'raw' PIN in the PIN verification procedure. The 12 digit (6 byte) PAN element used in AS/ANSI formatted PIN Blocks. Synonymous with ANB. Input PIN format to PIN translate function. Output PIN format. Note: PFi,PFo are unusual in that they are 4 bit values and share a byte (i = low 4 bits). The values for both are: 1 = AS/ANSI format 3 = PIN/PAD format.
The Personal Id Number. It may be formatted in several ways depending on the function. Number of digits of a customer PIN. Public Key Refer to XX-index. PIN/PAD formatted PIN Block. PIN Protect Key. Input key to a PIN key translate function. Output key from a PIN key translate function.
SafeNet, Inc.
508
Appendix L Glossary
The PIN Verification Key may be used for PIN protection as well as for PIN Verification. PIN Verification Key Indicator (Visa). PIN Verification Number PIN Verification Service (Visa). PIN Verification Value (Visa). Return Code The second field in all response messages. If this field is non-zero then an error is indicated and none of the fields which normally follow will be sent. Random Number Structured block based on a collaborative industry standard (e.g. TR-31, GISKE) to securely transport keys to terminals and to hosts for storage. Self-describes the embedded encrypted key and contents are verified using embedded MAC. 8 byte Terminal Security Number. A national security standard of Korea (KICS Korean Information Communication Standard) since June 2002. A 128-bit block cipher that has been widely used in Korea for confidential services such as ecommerce, e-mail, financial service, data storage, electronic toll collection, VPN and digital rights management. The left most three bytes of the result of sixteen bytes of hexadecimal zeros encrypted with a key using SEED ECB mode. SafeNet HSM Payment Secret Key Terminal Key Terminal Key Set Index. In the range 1-2. References the required 3624 keys. Transformed Security Parameter (Visa). Verification Constant of '0123456789ABCDEF'for a Docutel 5100 ATM. Visa Member Master Key. References a key of which there are multiple copies stored in the HSM. The index consists of 1 byte containing 2 BCD digits. The valid ranges are: KTM-index 01 to 99 (KTMn) KI-index 01 to 20 (KISn and KIRn) PK-index 01 to 20 (PVKn and Dtn). Zone Control Master Key (Visa).
RND SECURE KEY BLOCK SEC-NO SEED SEED Algorithm SEED KVC Method SHP SK TK TKSI TSP VCon VMMK XX-index
ZCMK
SafeNet, Inc.
509
Appendix L Glossary
SafeNet, Inc.
510
Metafunction................................................................ HSM_STATUS .............................................................. HSM-ERRORLOG-STATUS .......................................... HSM-GET-ERRORLOG ................................................. Establish_KM ............................................................... KM_Migrate ................................................................. Erase_Old_KM.............................................................. Retrieve_Key ................................................................ Store_Key ..................................................................... KEY_IMPORT............................................................... KEY_EXPORT............................................................... Get_Key_Details ........................................................... LOAD_HSM_SOFTWARE ............................................ HSM_SOFTWARE_STATUS ........................................ Key Mailer .................................................................... IT_KEY_GEN ................................................................ NT_KEY_GEN .............................................................. D51-PPK-GEN.............................................................. M-DPK-GEN ................................................................. TERM_VER_2 .............................................................. BDKGEN ....................................................................... Generate RSA Key Pair ................................................ Import Public Key ........................................................ Import public key certificate ........................................ Sign Data...................................................................... Verify Signed Data........................................................ Generate MD5 Hash..................................................... Generate SHA Hash ..................................................... Generate Key Diebold ................................................ Verify ATM Response Diebold ................................... Generate KM NCR ..................................................... II_KEY_GEN ................................................................. II_KEY_RCV ................................................................. NI-KEY-GEN................................................................. NI_KEY_RCV ............................................................... CLR-PIN-ENCRYPT...................................................... MIGRATEPIN............................................................... PIN-TRAN-2 ................................................................ PIN-VER-IBM-MULTI................................................... PIN-TRAN-3624.......................................................... KB-PIN-VER ................................................................. VAR-KB-PIN-VER ........................................................ PIN-OFF........................................................................ PIN-FROM-OFF ............................................................ Generate KM-encrypted PIN........................................ Print a KM-encrypted PIN ........................................... Verify a PIN Using KM-encrypted PIN......................... Translate a PIN from PPK to KM ................................. Migrate PIN.................................................................. IT-PVK-EXPORT .......................................................... OBM GetPublicKey() .................................................... OBM GenerateRandomNumber...................................
E3....................................... 28 01 ...................................... 32 FFF0................................... 34 FFF1................................... 36 11 ...................................... 40 12 ...................................... 41 13 ...................................... 43 21 ...................................... 46 22 ...................................... 48 EE0200.............................. 49 EE0201.............................. 52 EE0202.............................. 54 EE3100.............................. 56 EE3101.............................. 58 EE0E01 .............................. 62 EE0400.............................. 66 EE0401.............................. 69 47 ...................................... 71 49 ...................................... 72 EE0406.............................. 73 EE0408.............................. 74 EE9001.............................. 79 EE9003.............................. 81 EE9004.............................. 82 EE9005.............................. 84 EE9006.............................. 85 EE9007.............................. 86 EE9008.............................. 87 EE9101.............................. 88 EE9102.............................. 90 EE9201.............................. 91 EE0402.............................. 94 EE0403.............................. 97 EE0404.............................. 101 EE0405.............................. 103 EE0600.............................. 107 EE0601.............................. 108 EE0602.............................. 110 EE0603.............................. 112 63 ...................................... 114 64 ...................................... 115 69 ...................................... 116 EE0604.............................. 117 EE0609.............................. 119 EE0640.............................. 121 EE0641.............................. 122 EE0642.............................. 124 EE0643.............................. 125 EE0644.............................. 126 EF0210.............................. 127 EE3000.............................. 133 EE3001.............................. 134
SafeNet, Inc.
511
Function
OBM Verify PIN RSA-encrypted, 3624 Offset ........... OBM Change PIN RSA-encrypted, 3624 Offset ........ OBM SetPassword RSAEncrypted TPV........................ OBM VerifyPassword RSAEncrypted TPV ................... OBM ChangePassword RSAEncrypted TPV ................ OBM PrintPassword..................................................... OBM MigratePIN OffsetToTPV..................................... OBM GetPrintToken..................................................... OBM GenerateRandomPIN.......................................... OBM PrintEncryptedPIN.............................................. OBM Translate PIN RSA-encrypted, PPK ................. OBM Set PIN PPK-encrypted, TPV............................ PVV-VER ...................................................................... PVV- CALC-3624......................................................... PVV-CALC.................................................................... DIEBOLD_PIN_VER ..................................................... DIEBOLD_PIN_OFF...................................................... PIN-TRANS-SEED-DES ................................................ CVV- GENERATE.......................................................... CVV- VERIFY................................................................ MAC_GEN_UPDATE .................................................... MAC_GEN_FINAL........................................................ MAC_VER_FINAL........................................................ KTM-MAC-GEN............................................................ ENCIPHER_2................................................................ DECIPHER_2................................................................ ENCIPHER_3................................................................ DECIPHER_3................................................................ ENCIPHER-KTM1 ........................................................ B-ENCIPHER-ECB......................................................... B-DECIPHER-ECB......................................................... MT-KPE-GEN................................................................ MT-KPE-RCV................................................................ MT-PIN-TRAN ............................................................. MT-PIN-VER ................................................................ MT_PIN_VER_PVV...................................................... CALC_CSCK ................................................................. CREATE_CSCK............................................................. EXPORT_CSCK............................................................. IMPORT_CSCK............................................................. PIN-MAIL..................................................................... PIN-GENERATE ........................................................... PIN-PRINT ................................................................... GEN_RANDOM ............................................................ EMV_AC_GEN.............................................................. EMV_AC_VERIFY ........................................................ EMV_DAC_GEN ........................................................... EMV_DAC_VERIFY...................................................... EMV_ICC_DN_GEN...................................................... EMV_ICC_DN_VERIFY ................................................ EMV_ARPC_GEN ......................................................... EMV_SCRIPT_CRYPTO ............................................... EMV_VERIFY_AC_EMV2000...................................... EMV_VERIFY_AC_VISA.............................................. EMV_GENERATE_ARPC.............................................. EMV_SCRIPT_CRYPTO_EMV2000 ............................ EMV_SCRIPT_CRYPTO_VISA..................................... EMV_PIN_CHANGE_UNBLOCK_VISA........................
EE3002.............................. 135 EE3003.............................. 136 EE3004.............................. 138 EE3005.............................. 139 EE3006.............................. 140 EE3008.............................. 141 EE3009.............................. 143 EE3016.............................. 144 EE3017.............................. 145 EE3018.............................. 146 EE3019.............................. 148 EE3020.............................. 149 EE0605.............................. 158 EE0606.............................. 160 EE0607.............................. 161 EE0614.............................. 163 EE0616.............................. 165 EE0615.............................. 167 EE0802.............................. 169 EE0803.............................. 170 EE0700.............................. 172 EE0701.............................. 174 EE0702.............................. 176 73 ...................................... 178 EE0800.............................. 180 EE0801.............................. 182 EE0804.............................. 184 EE0805.............................. 186 EE0806.............................. 188 84 ...................................... 190 85 ...................................... 191 A0...................................... 196 A1...................................... 197 A2...................................... 198 A3...................................... 199 A7...................................... 200 A8...................................... 203 A9...................................... 204 AA ..................................... 205 AB...................................... 206 E2....................................... 209 EE0E04 .............................. 212 EE0E05 .............................. 213 EE0002.............................. 216 EE2000.............................. 217 EE2001.............................. 218 EE2002.............................. 221 EE2003.............................. 222 EE2004.............................. 223 EE2005.............................. 224 EE2006.............................. 225 EE2007.............................. 226 EF2010.............................. 228 EF2011.............................. 231 EF2012.............................. 233 EF2013.............................. 235 EF2014.............................. 238 EF2015.............................. 240
SafeNet, Inc.
512
Function
EMV_PIN_CHANGE_UNBLOCK .................................. EMV_PIN_CHANGE_UNBLOCK_EMV_2000 ............. EMV_VERIFY_AC_GEN_ARPC ................................... EMV_AC_GEN_MULTI................................................. EMV_SCRIPT_CRYPTO_MULTI .................................. EMV_PIN_CHANGE_UNBLOCK_MULTI..................... VCEPS_VER_S1_GEN_S2 ............................................ VCEPS_VER_SN ........................................................... VCEPS_GEN_SN........................................................... VCEPS_MAC_VER_LSAM............................................ VCEPS_GEN_HASH_CEP............................................. GETPUBLICKEY ........................................................... KIS_SEND..................................................................... KIR_REC....................................................................... NODEPROOF ................................................................ NODERESP ................................................................... GEN_TERMINAL_KEY................................................. ZKA-IMPORT-MK ........................................................ ZKA-PIN-TRANS ......................................................... ZKA-PIN-VER............................................................... ZKA-CALC-PVN ........................................................... ZKA-PIN-TRANS-1...................................................... ZKA-MAC-GEN ............................................................ ZKA-MAC-GEN-1......................................................... GetKVC......................................................................... PIN_Generation ........................................................... Auth_Param_Generate................................................ Random_Key_Generation ........................................... IT-PPK-GEN ................................................................. IT-MPK-GEN ................................................................ IT-DPK-GEN ................................................................. NT-PPK-GEN................................................................ NT-MPK-GEN............................................................... NT-DPK-GEN................................................................ GEN_SESS_KEYS.......................................................... TERM-VER ................................................................... II-PPK-GEN .................................................................. II-MPK-GEN ................................................................. II-DPK-GEN .................................................................. II-PPK-RCV .................................................................. II-MPK-RCV ................................................................. II-DPK-RCV .................................................................. NI-PPK-GEN................................................................. NI-MPK-GEN................................................................ NI-DPK-GEN................................................................. NI-PPK-RCV................................................................. NI-MPK-RCV................................................................ NI-DPK-RCV................................................................. PIN-TRAN.................................................................... PIN-VER-IBM-ANSI ..................................................... PIN-VER-PP ................................................................. D51-PIN-TRAN............................................................ D51-PIN-VER............................................................... VAR-PIN-VER .............................................................. VAR-PIN-VER-PP ........................................................ PIN-OFF-AS.................................................................. PIN-OFF-PP.................................................................. MAC-GEN.....................................................................
EE2016.............................. 243 EE2017.............................. 245 EE2018.............................. 248 EE2019.............................. 253 EE2020.............................. 257 EE2021.............................. 262 EF0701.............................. 268 EF0702.............................. 269 EF0703.............................. 271 EF0704.............................. 272 EF0F01 .............................. 273 EE3030.............................. 276 EE3031.............................. 277 EE3032.............................. 278 EE3033.............................. 279 EE3034.............................. 280 EE0628.............................. 282 EE0210.............................. 288 EE0610.............................. 290 EE0611.............................. 292 EE0612.............................. 294 EE0613.............................. 296 EE0710.............................. 298 EE0711.............................. 300 EEBF29 .............................. 303 EF0616.............................. 305 EF0617.............................. 306 EF0618.............................. 307 41 ...................................... 309 42 ...................................... 310 43 ...................................... 311 44 ...................................... 312 45 ...................................... 313 46 ...................................... 314 4A...................................... 315 4C ...................................... 316 51 ...................................... 317 52 ...................................... 318 53 ...................................... 319 54 ...................................... 320 55 ...................................... 321 56 ...................................... 322 57 ...................................... 323 58 ...................................... 324 59 ...................................... 325 5A...................................... 326 5B ...................................... 327 5C ...................................... 328 60 ...................................... 329 61 ...................................... 330 62 ...................................... 331 65 ...................................... 332 66 ...................................... 333 67 ...................................... 334 68 ...................................... 335 6A...................................... 336 6B ...................................... 337 70 ...................................... 338
SafeNet, Inc.
513
Function
MAC-TRAN.................................................................. MAC-VER ..................................................................... ENCIPHER.................................................................... DECIPHER .................................................................... ENCIPHER-ECB ............................................................ DECIPHER-ECB ............................................................ PVV-GEN-1 .................................................................. PVV-VER-1................................................................... PVV-VER-2................................................................... PVV-VER-3................................................................... PIN-TRAN-1 ................................................................ PIN-TRAN-2 ................................................................ PVV-GEN-2 .................................................................. PVV-VER-4................................................................... PVV-VER-5................................................................... PVV-VER-6................................................................... PVV-CHANGE .............................................................. CVV-GEN...................................................................... CVV-VER ...................................................................... CVC3_GENERATE........................................................ CVC3_VERIFY.............................................................. dCVV_GENERATE........................................................ dCVV_VERIFY.............................................................. Key Package Status...................................................... Export Keys Package .................................................... Import Key Package..................................................... PIN-TRANSLATEVSDC Personalization.................... Generate Issuer Key Pair.............................................. Self-Certify Issuer Public Key (Europay MasterCard)... Verify CA Public Key (MasterCard).............................. Verify Issuer Public Key Certificate (MasterCard)........ Self-Sign Issuer Public Key (Visa) ................................ Verify CA Public Key (Visa).......................................... Verify Issuer Public Key Certificate (Visa).................... Verify Detached Signature (Visa) ................................ Generate ICC Key Pair.................................................. Generate ICC CRT Key Pair.......................................... Verify ICC Certificate (EMV2000)................................ Derive ICC Master Key ................................................. Sign ICC Static Data ..................................................... Verify ICC Static Data................................................... Verify ICC Dynamic Data ............................................. Encipher PIN ................................................................ Generate PIN................................................................ Export PIN.................................................................... Key Export using KTK .................................................. Derive New ICC Key Set ............................................... Derive New ICC Key ..................................................... Generate DCV............................................................... DERIVE_KDCVC3_AND_IVCVC3................................ CREATE_ADDITIONAL_ICC........................................
71 ...................................... 339 72 ...................................... 340 80 ...................................... 341 81 ...................................... 342 82 ...................................... 343 83 ...................................... 344 90 ...................................... 345 91 ...................................... 346 92 ...................................... 347 93 ...................................... 348 94 ...................................... 349 95 ...................................... 350 96 ...................................... 351 97 ...................................... 352 98 ...................................... 353 99 ...................................... 354 9A...................................... 355 9B ...................................... 356 9C ...................................... 357 EE0010.............................. 360 EE0011.............................. 361 EE0014.............................. 362 EE0015.............................. 364 EE3102.............................. 366 EE3103.............................. 367 EE3104.............................. 368 EE0608.............................. 376 EE2040.............................. 380 EE2041.............................. 382 EE2042.............................. 385 EE2043.............................. 387 EE2044.............................. 389 EE2045.............................. 391 EE2046.............................. 393 EE2047.............................. 395 EE2048.............................. 396 EE2058.............................. 399 EE2049.............................. 402 EE204A ............................. 404 EE204B.............................. 406 EE204C.............................. 408 EE204D.............................. 410 EE204E .............................. 412 EE204F .............................. 414 EE2050.............................. 416 EE2051.............................. 418 EE2052.............................. 419 EE2053.............................. 420 EE2054.............................. 421 EE0012.............................. 424 EE0013.............................. 426
SafeNet, Inc.
514