Mark II Programmers Guide
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
Copyright © 2009, SafeNet, Inc. All rights reserved.
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
Q R
S T
© SafeNet, Inc.
Action/Change
Date
This revision was skipped for Document Control reasons. SHP 1.1 Release. MarkII Programmer’s Guide updated for: 1. Card Issuance Integration 2. Host Key rationalization 3. Network Key Transfer Host Functions
June 2009
This revision was skipped for Document Control reasons. Functionality enhanced for FM=2 in function EE2048 and EE2058.
October 2009
This revision was skipped for Document Control reasons. Updated for a few host functions
December 2009
June 2009
October 2009
December 2009
i
Mark II Programmers Guide
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.
FCC Notice to Users These limits are designed to provide reasonable protection against harmful interference in a residential installation. This equipment generates, uses and can radiate radio frequency energy and if not installed and used in accordance with the instructions, may cause harmful interference to radio communications. However, there is no guarantee that interference will not occur in a particular installation. If this equipment does cause harmful interference to radio or television reception, which can be determined by turning the equipment off and on, the user is encouraged to try to correct the interference by one or more of the following measures:
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.
WEEE and RoHS Compliance SafeNet HSM Payment devices comply with Waste Electrical and Electronic Equipment (WEEE) and Restriction of Hazardous Substances (RoHS) standards. When discarding, these devices must be handed over to a designated collection point for the recycling of waste electrical and electronic equipment
© SafeNet, Inc.
ii
Mark II Programmers Guide
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
Mark II Programmers Guide
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
Mark II Programmers Guide
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.
v
Mark II Programmers Guide
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
Mark II Programmers Guide
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.
Where to Find Information ? Information MarkII Function Set Information
Recommended References Chapter 1 -27, under Part 1 of the Guide
Card Issuance Function Set Information
Chapters under Part 2 of the Guide
Appendices
Appendices under Part 3 of the Guide
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
Contacting Technical Support If you encounter a problem while installing, registering or operating this product, please make sure that you have read the documentation. If you cannot resolve the issue, please contact your supplier or SafeNet support. SafeNet support operates 24 hours a day, 7 days a week. Your level of access to this service is governed by the support plan arrangements made between SafeNet and your organization. Please consult this support plan for further information about your entitlements, including the hours when telephone support is available to you. Technical Support Contact Information: Phone: 800-545-6608 Email:
[email protected]
© SafeNet, Inc.
vii
Mark II Programmers Guide
© SafeNet, Inc.
Preface
viii
Mark II Programmers Guide
Part 1 ______________________________________________________________________
MarkII Function Set
© SafeNet, Inc.
1
Mark II Programmers Guide
© SafeNet, Inc.
2
Mark II Programmers Guide
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.
3
Mark II Programmers Guide
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.
Common Terms and Phraseology This or other documentation may refer to a SafeNet HSM security module as an ESM, ESM2000, and HSM/PHeft. The device has been renamed as SafeNet HSM Payment (referred to as SHP, hereafter). The names SafeNet HSM Payment (SHP), PHeft, ESM, HSM and ESM2000 all refer to the same device in the context of this or previous Guides. The Glossary at the back of this Guide explains some of the many terms, abbreviations and acronyms used 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.
4
Mark II Programmers Guide
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.
Host Function Overview Each function involves a host request being sent to the HSM. Each request produces a corresponding response message containing the results of the function or a status code indicating an error. The message content of each function is described in this guide and is independent of the selected communications protocol. Message formatting procedures appropriate to each available protocol are described in the Communications Guide. A host request message starts with a Function Code followed by function-dependent binary data. These data may be fixed or variable length depending on the function. Functions requiring variable length data include the length of the variable field in a one-byte length parameter. Where a function requires multiple fields in a message, there is no delimiter between fields. For example Function NT-PPK-GEN (FN 44) : eKM1(KSn) = 12 34 56 78 90 AB CD EF By adding the function code the complete host request message is 44 12 34 56 78 90 AB CD EF A response message starts with the Function Code from the host request message followed by a one-byte Return Code. Appendix I Error Codes lists the assignments for the Return (Error) Code. If the Error Code returned is non-zero, there is no data following the Error Code. Otherwise, the response data follows the Error Code. For example, function NT-PPK-GEN (FN 44): Return Code : 0A (uninitialized key access) By adding the function code the complete response message is 44 0A
Host Function Specification in this Guide For each Host Function that is specified in this document, the title of the section which details the specification takes the following format. The function name appears at the left side of the page. It is important to note that this is an abbreviated form of the function name that is used in the Console. For a list of Host Function codes and associated function names, refer to the section entitled Appendix H Function Matrix. To the right of the function name, a table lists the products in which the function is supported. SHP refers to the SafeNet HSM Payment product running the Mark II software. PSO/PHW refers to the ProtectServer Orange/HSM product running the Mark II software. SHP Toolkit MK2 refers to the ProtectTookit EFT MK2 application programming interface (API). Card Issuance refers to the
© SafeNet, Inc.
5
Mark II Programmers Guide
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.
Figure 1 Function definition format
© SafeNet, Inc.
6
Mark II Programmers Guide
Chapter 2 Function Construction
Chapter 2 Function Construction Host Function Overview Each function involves a host request being sent to the HSM. Each request produces a corresponding response message containing the results of the function or a status code indicating an error. The message content of each function is described in this guide and is independent of the selected communications protocol. Message formatting procedures appropriate to each available protocol are described in the Communications Guide. A host request message starts with a Function Code followed by function-dependent binary data. These data may be fixed or variable length depending on the function. Functions requiring variable length data include the length of the variable field in a one-byte length parameter. Where a function requires multiple fields in a message, there is no delimiter between fields. For example Function NT-PPK-GEN (FN 44): eKM1(KSn) = 12 34 56 78 90 AB CD EF By adding the function code the complete host request message is 44 12 34 56 78 90 AB CD EF A response message starts with the Function Code from the host request message followed by a one-byte Return Code. Appendix J Error Codes lists the assignments for the Return (Error) Code. If the Error Code returned is non-zero, there is no data following the Error Code. Otherwise, the response data follows the Error Code. For example, function NT-PPK-GEN (FN 44) : Return Code : 0A (uninitialized key access) By adding the function code the complete response message is 44 0A
Function Message Formats Data Item Representation in Request/Response Messages Request and response content may use the following operators and qualifying letters.
© SafeNet, Inc.
Operator
Meaning
d e Qualifier L R r s V
Decrypt in Electronic Code Book (ECB) mode. Encrypt in Electronic Code Book (ECB) mode. Meaning The left part of a key pair The right part of a key pair Used for receiving Used for sending Variant
7
Mark II Programmers Guide
Chapter 2 Function Construction
Each field has an associated attribute and its length in bytes. The attributes are defined as follows: Attribute
Description
b h d x B64 B512 P-key K-Spec
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
S-Block
Common Message Header Formats All functions employ a common format for both request and response messages. Function Request Headers Each function request begins with a header of the form: Description Function Code
Length 1
Attribute h
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.
Transmission of Two-byte Integers For any 2-byte integer values contained in message requests or responses, the function code field should be transmitted with the most significant byte first unless otherwise stated.
Function Modifier Values Selection of host key protection method within host functions can be done using the FM field. The Host Key Protection using Function Modifier can be in the range of x0, where x= 0 , 1 or 2. This impacts the key-types under the Response Content since they are generated based on the chosen operation on console and FM. The following table shows different combinations of FM value and console check box and their impact on behavior of the host function. Notes: FM override is only applicable for those functions that return key specifier in response. For the functions that receive key spec in request, FM (xy) and x>0 will cause an error. Also, Functions not having FM fields will generate keys according to global method.
© SafeNet, Inc.
8
Mark II Programmers Guide
State of FM Override on console Enabled
Disabled
Chapter 2 Function Construction
Global Method Selected
FM xy
Key Protection Method to be used
Legacy Legacy Legacy ECB ECB ECB CBC CBC CBC Legacy Legacy
0000 0000 0001 0000 0010 0000 0000 0000 0001 0000 0010 0000 0000 0000 0001 0000 0010 0000 0000 0000 0001 0000
Legacy
0010 0000
ECB ECB ECB
0000 0000 0001 0000 0010 0000
CBC CBC
0000 0000 0001 0000
CBC
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)
Variable Length Fields in Function Request and Response Messages This section describes the method for specifying the actual length of a variable-length data field in a function request or response. The method utilizes a length prefix that in itself has a variable length. The length prefix forms an essential part of the variable-length data field. Host functions utilize two field constructs, namely the Variable-length field and the Key specifier. The variable-length field construct provides a standard mechanism for incorporating a field of varying length into HSM Request or Response messages. It comprises the variable-length data and a prefix which specifies the length of the data, and which is also of variable-length. This section describes the method for specifying the actual length of a variable-length data field in a function request or response. The actual length of the length prefix is specified by the most significant bits of the most significant byte within the prefix. The remaining bits within the most significant byte form part (or all, in the single-byte case) of the value of the length prefix. Thus: Length of length prefix Length indicator bits in most significant byte (bytes) 1 0… 2 10… 3 110 … 4 1110 … … The encoding defined above results in the following ranges of values for the length prefixes, and ranges of lengths for the corresponding data values:
© SafeNet, Inc.
Length of length prefix
Values in length prefix
(bytes)
(hex)
Bytes in data value (hex)
(dec)
9
Mark II Programmers Guide
Chapter 2 Function Construction
1 2
00 – 7F
3 4
C00000 – DFFFFF E0000000 – EFFFFFFF
8000 – BFFF
00 – 7F 0000 – 3FFF
0 – 127 0 – 16383
000000 – 1FFFFF 00000000 – 0FFFFFFF
0 – 2097151 0– 268435455
… The following points apply to the Mark II implementation of the method.
© SafeNet, Inc.
•
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. X’00’ or X’8000’. A zero-length field is useful where a field is not optional, but is not used.
10
Mark II Programmers Guide
Chapter 2 Function Construction
Example Field Formats The following examples illustrate how a variable-length field containing 27 data bytes could be represented using a length prefix of differing lengths.
One byte length msb 1sb 0 b6 b5 b4 b3 b2 b1 b0 Zero indicates one byte length field Length is 7 bit binary number (b6b5b4b3b2b1b0)
Two byte length First byte transmitted
Second byte transmitted
msb 1 0
1sb msb 1sb b13 b12 b11 b10 b09 b08 b07 b06 b05 b04 b03 b02 b01 b00
1
indicates two byte length field
0
Length is 14 bit binary number (b13b12...b01b00)
Three byte length First byte transmitted
Second byte transmitted
Third byte transmitted
msb 1 1
0
1sb msb 1sb msb 1sb b20 b19 b18 b17 b16 b15 b14 b13 b12 b11 b10 b09 b08 b07 b06 b05 b04 b03 b02 b01 b00
1
0
indicates three byte length field
1
Length is 21 bit binary number (b20b19…b01b00)
© SafeNet Technologies
11
Mark II Programmers Guide
Chapter 2 Function Construction
Four byte length First byte transmitted
Second byte transmitted
Third byte transmitted
Fourth byte transmitted
msb 1 1
1
0
1sb msb 1sb msb 1sb msb 1sb b27 b26 b25 b24 b23 b22 b21 b20 b19 b18 b17 b16 b15 b14 b13 b12 b11 b10 b09 b08 b07 b06 b05 b04 b03 b02 b01 b00
1
1
0
indicates four byte length field - Length is 28 bit binary number (b27b26...b01b00)
1
© SafeNet Technologies
12
Mark II Programmers Guide
Chapter 2 Function Construction
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 X’00’ X’28’ X’24’ X’44’ X’88’ X’22’ X’20’ X’18’ X’14’ X’48’ X’45’ X’4D’ X’5C’ X’0C’ X’0A’ X’1E’ X’2E’ X’4E’ X’72’ X’78’ X’70’ X’74’ X’30’ X’36’ X’3A’ X’3C’ X’50’ X’66’ X’6A’ X’6C’ X’7E’
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 Variant Scheme Variants of KIS/KIR keys are used to provide functional separation as described in AS2805 Part 6.1, 1988. The variant is calculated as described in AS2805 Part 6.1, 1988 using the constants defined in the tables below. The variant constant is formed by repeating the Variant Byte from the following table 8 times (for single length keys) or 16 times (for double length keys). Note that no variant is applied to KIS/KIR keys used to encrypt DPK keys. Support for KTM keys added in SafeNet Variant Scheme.
© SafeNet, Inc.
13
Mark II Programmers Guide
Chapter 2 Function Construction
Variant Byte X'24'
Used to Protect MPK
X'28'
PPK
X'22'
KTM
Atalla Variant Scheme The Atalla key management system separates DPK, PPK and MPK keys by storing and downloading then under different variants of KIS/KIR keys. Single length key variants are formed by exclusive or’ing (XOR) the variant byte with the left most byte of the key. Double length key variants are formed by exclusive or’ing (XOR) the variant byte with the left most byte of each half of the key. The variant bytes used for the Atalla variant scheme are listed in the following table. KIS/KIR variant 1 2
Variant Byte
Used to Protect
X'08'
PPK
X'10'
DPK
3
X'18'
MPK
AS2805.6.1 Variant Scheme Variants of KIS/KIR keys are used to provide functional separation as described in AS2805 Part 6.1, 2002. The variant is calculated as described in AS2805 Part 6.1, 2002 using the constants defined in the table below. This variant scheme is identical to the current APCA variant scheme. In order to provide additional separation between 64-bit, 128-bit and 192-bit DEA keys the standard has been extended as described below. In each case the variant key is obtained by an XOR operation of the base key with the Variant Constant.
Variant Byte
Used to Protect
X'22'
DPK
X'24'
MPK PPK
X'28'
Size of Session Key 64-bit DEA keys 128 bit CBC and DEA keys
192 bit CBC and DEA keys '
© SafeNet, Inc.
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.
14
Mark II Programmers Guide
Chapter 2 Function Construction
Public Key Verification Code The KVC for a public key (PVC) is formed as described in AS2805 part 6.1 as follows: • • •
The modulus and public exponent are each expressed as whole bytes, most significant byte first, with no length field and no leading zero bytes. The modulus and exponent are concatenated in that order. The SHA1 digest of that data is calculated.
The first 64 bits of the SHA1 digest will be the PVC of the key.
The ‘Key Specifier’ Function Field Host functions utilize two field constructs, namely the Variable-length field and the Key specifier. The key specifier construct is a variable-length field that contains a variable-format specification of a key. In general, a key specifier may contain either an index to an HSM-stored key, or an encrypted key from host storage – encrypted by a variant of *KM. The format of a key specifier field is fully described in this section. Formats for key specifiers that accommodate RSA public and private keys are also covered. Most host functions perform transformations using cryptographic keys which are stored either within the secure memory (HSM-stored) or in the host database in encrypted form (Host-stored). Traditionally, the choice of whether a key should be HSM-stored or host-stored has been on a perkey-type basis and has been fixed in the function design. The key specifier introduces the capability for that choice to be at the discretion of the user (or host software provider); it also permits the possibility to HSM-store some keys of a key type and to host-store other keys of that same key type. To support the capability, a ‘key specifier’ is defined which is a variable format field to be built into host function request and (possibly) response messages. The key specifier provides access to a key - either by value (an encrypted key from, or for, host storage) or by reference (an index to a key table). Being variable format, a key specifier field will be variable length. Refer to the section entitled Variable Length Fields in Function Request and Response Messages for details of the variable length field. Although the key specifier introduces extra flexibility for the user, there need be no extra complexity for the host programmer. One simply selects the appropriate key specifier format for the particular key, and then treats that instance of the key specifier as a fixed length, fixed format field. Currently, the (Mark II) functions that access HSM-stored keys, do so via a one-byte index which contains two packed BCD digits. This limits the maximum index to 99. The key specifier includes formats which support two-byte packed BCD indices, and one- and two-byte binary indices, thereby significantly increasing the maximum index supported. The following formats are defined.
© SafeNet, Inc.
15
Mark II Programmers Guide
Chapter 2 Function Construction
Key Specifier Formats for HSM-stored Keys The following key specifier formats provide access to keys stored in tables (or files) within HSM Secure Memory. The formats incorporate an index which identifies the required key in a table; the particular table to access is implicit in the function definition. All the formats support index values from zero to the maximum value which fits in the field. Restrictions in the values are applied by other considerations, such as physical capacity of Secure Memory. All tables are indexed from one, so zero is an invalid value. Index - short / BCD Format 00 Field length: 2
byte 1 2
attribute x d
content 00 00 - 99
Index - short / binary Format 01 byte Field length: 2 1 2
attribute x x
content 01 00 - FF
byte 1 2-3
attribute x d
content 02 0000 - 9999
Index - long / binary Format 03 byte Field length: 3 1 2-3
attribute x x
content 03 0000 - FFFF
Index - long / BCD Format 02 Field length: 3
© SafeNet, Inc.
16
Mark II Programmers Guide
Chapter 2 Function Construction
Key Specifier Formats for Host-stored Keys The following key specifier formats incorporate encrypted key values. Formats for single-, double-, and triple-length keys are specified, and both single and multiple Domain Master Keys (KM) are supported. The field lengths shown for formats 10-14 below assume DES keys appropriate to current functionalities. However, the algorithm and associated key length is not implicit in the key specifier; so these formats could be equally appropriate for other algorithms, and might then have a different field length. Encrypted key - Single-length Format 10 byte Field length: 9 1 2-9
attribute x x
content 10 eKMx(K)
Encrypted key - Double-length - ECB Format 11 byte attribute Field length: 17 1 x 2-17 x
content 11 eKMx(K)
Encrypted key - Triple-length - ECB Format 12 byte attribute Field length: 25 1 x 2-25 x
content 12 eKMx(K)
Encrypted key - Double-length – CBC Format 13 byte attribute Field length: 17 1 x 2-17 x
content 13 eKMx(K)
Encrypted key –Triple-length– CBC Format 14 byte attribute Field length: 25 1 x 2-25 x
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
Mark II Programmers Guide
Chapter 2 Function Construction
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
Attribute
1
h
2
1
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
1
h
Block length
1
h
Mode of operation
1
h
eKMv(K)
Var
h
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
Mark II Programmers Guide
Chapter 2 Function Construction
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.
Host-stored bitmap Field Content Length Format 19 1 Data Specifier 1 Type
© SafeNet, Inc.
Attribute h h
Description 19 = 02 – CAP Bitmap
19
Mark II Programmers Guide
Chapter 2 Function Construction
Host-stored bitmap Field Content Length Encrypted 1 Payload KM-Id 1 Payload Length Pad1 Bitmap Authentication Code
Attribute h h
2 2 8 8
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
h
1
h
Description 50 Key specifier for personalization master key (format 0 –3, 13).
= 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
Mark II Programmers Guide
Chapter 2 Function Construction
Unique-per-card derived session key Field Content Length Attribute Format 51 1 h KMC Var K-Spec
Card-unique derivation data Card method
16
h
1
h
Session data Session method
16 1
h h
Description 51 Key specifier for personalization master key (format 0 –3, 13).
= 01: ECB = 02: CBC = 01: ECB = 02: CBC
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
KM-Id
1
h
Key Type Authentication Algorithm Id. User data Authentication Value
2 1
h h
Var Var
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.
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
Mark II Programmers Guide
Chapter 2 Function Construction
RSA private key – Encrypted Field Content Format Mod Len Key format
Length 1 2 1
Attribute h h h
KM-Id
1
h
Key Type Authentication Algorithm Id. User data eKMv20(SK)
2 1
h h
Var Var
h h
Var
h
Authentication Value
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.
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
Field Content Format
Encrypted session key Length Attribute Description 1 h = 90
MK-spec
Var
K-spec
Key specifier for Master key (formats 0–3, 13, 92).
CV-index
1
h
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
© SafeNet, Inc.
CV1 00 00 4D 00 03 41 00 00
CV2 00 00 4D 00 03 21 00 00
22
Mark II Programmers Guide
PAC
Chapter 2 Function Construction
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
Field Content Format
Length
Description
1
*KGK1-spec
Var
K-spec
Key specifier for *KGK1 (formats 0-3 or 13)
*KGK2-spec
Var
K-spec
Key specifier for *KGK2 (format 0-3 or 13)
BLZ
4
h
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.
Field Content Format
Length 1
MK2 reference Attribute h = 92
Sub-type
1
h
= hex 00 – 63, or FF
Version Number
1
h
= hex 00 – 63, or FF
Generation Number
1
h
= hex 00 – 63, or FF
Expiry Date
2
d
mmyy, where mm = BCD 01 – 31 and yy = BCD 00 – 99;
Description
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
Mark II Programmers Guide
Chapter 2 Function Construction
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 X’74’.
Field Content Format
Length 1
KM-encrypted PIN Attribute h = 1A
Description
Type
1
h
= 01
KM-Id
1
h
For the AMB HSM, identifies the KM used, otherwise must be zero.
eKMv27(PIN)
8
h
Encrypted PIN Block.
Usage Notes for Key Specifiers In Host Functions The key specifier is widely used in newly developed host functions. The type of key being accessed by the key specifier will most likely always be implicit in the function design. For example, in one place a key specifier might be for a terminal master key, in another place it could be for PIN verification key, and in yet another it could be for a PIN encrypting key. This is identical to the current situation with indexes to HSM-stored keys. The function field therefore always identifies the type of key that the key specifier is for. It will not always be appropriate for a given key type to be HSM-stored or host-stored. Nevertheless, a key specifier is still useful, e.g. to provide a choice of formats for specifying an index to a HSM-stored key. When considering key specifier formats, the following guidelines apply: -
Formats 0,1,2 or 3 should be used when specifying an index to a HSM stored key.
-
Format 10 should be used to specify single-length, host stored keys that are encrypted using ECB.
-
Format 11 is provided as legacy function support. Some older functions used ECB instead of CBC to encrypt a double-length key for host storage. Note that this key specifier should only be used to supply host stored keys that are known to have been generated using these legacy functions. New functions use CBC to encrypt doublelength keys and Format 13.
© SafeNet, Inc.
-
Format 13 should be used to specify double-length, host stored keys that are encrypted using CBC.
-
Format 14 should be used to specify triple-length, host stored keys that are encrypted using CBC.
-
HSM-stored (formats 0-3) MPK keys can be stored for use with DES or HMAC-SHA-1 algorithm. HMAC-SHA-1 MPK key valid key lengths are 128, 160 and 192 bits. DES MPK key valid key lengths are single, double and triple length (64, 128 and 192 bits). HMAC-SHA1 MPK keys are only applied for use with HMAC-SHA-1 algorithm.
24
Mark II Programmers Guide
Chapter 2 Function Construction
PIN Block Formats Supported PIN Block Formats The format of a PIN Block is specified in a single-byte field. The valid values for the field and the associated meanings are shown in the following table. Format 01
Name ANSI
02
Docutel 2
03 08
PIN/Pad Docutel
09 10 11 12 13
ZKA ISO 0 ISO 1 ISO 2 ISO 3
Details Identical to existing PIN-TRAN Format 1 – ANSI format; AS2805 Part 3 format 0; ISO 9564-1 Format 0. Contains 1-digit PIN length, 4 to 6-digit PIN and a user-defined padding string of 9 digits. If the PIN has 4 or 5 digits, it is initially padded to the right with 2 or 1 zero digits to total 6 digits. Identical to existing PIN-TRAN Format 3. Identical to existing Docutel 5100 Format 8 (used in D51-PIN-TRAN, etc.) The input PIN Block may be ISO Format 0 or an ISO Format 1 Identical to Format 01 above. ISO 9564-1:2003 Format 1 ISO 9564-3: 2003 Format 2 ISO 9564-1: 2002 Format 3
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.
Enabled and Disabled PIN Blocks The HSM needs to support all PIN blocks formats that are used within the industry. Many users do not require support for some of these formats. Therefore, each PIN block format can be enabled or disabled. The default condition for each PIN block format is as follows. PIN Block Format ISO-0 ISO-1 ISO-2 ISO-3
© SafeNet, Inc.
Enabled x x
Disabled
x x
25
Mark II Programmers Guide
Chapter 2 Function Construction PIN/Pad Docutel
x x
A console operation allows the user to enable support for just those PIN block formats that are required.
Function Identifier Control The Function Identifier Control allows the HSM to operate with a new optional Function Identifier field which is placed into the function request and response messages in order to provide message identity. When enabled, the Function Identifier is a fixed-length field with length as specified by the user, occurring immediately after the function code field in every function request and response message. Field length can be set in a range from 1 to 99 bytes in length. To maintain backwards compatibility, the function identifier can be switched on or off via a console operation. Please refer to the console user guide for details on how to activate or deactivate the function identifier.
Message Meta-function Format The meta-function message format provides a transparent mechanism for implementing extensions to the current host message format. See Chapter 3, The Metafunction for further information.
© SafeNet, Inc.
26
Mark II Programmers Guide
Chapter 3 The Metafunction
Chapter 3 The Metafunction Message Meta-function Format The meta-function message format provides a transparent mechanism for implementing extensions to the current host message format. Note: Currently, only SafeNet’s ProtectToolkit EFT product makes use of the meta-function format. Metafunction support can be enabled or disabled via the console under the Device Administration/Function Control menu. The meta-function is presented as a special function code called the Meta-function Indicator (E3). If the Meta-function Indicator is found in the message, the SHP knows that the message came encapsulated. It then extracts the normal request message frame, processes it in the usual manner and then puts the meta-function back around the response message before sending the reply.
Request Message Comms Header
Metafunction Indicator
Meta-function Type
Version
Type specific data …
Comms trailer
Type specific data …
Comms trailer
Type specific data …
Comms trailer
Response Message Comms Header
Metafunction Indicator
Meta-function Type
Version
Respons e Code (= 00)
Meta-function Error Response Message Comms Header
Metafunction Indicator
Meta-function Type
Version
Response Code (<> 00)
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
Mark II Programmers Guide
Chapter 3 The Metafunction
Metafunction
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
Request Content E3
Length 1
Attribute h
Reserved Byte Meta-function ID Version Message Id Data Field
1 1 1 4 Var
h h h x x
Response Content E3
Length 1
Attribute h
Reserved Byte Meta-function ID Version Return Code
1 1 1 1
h h h h
4 Var
x x
Message Id Data Field
D D U U D
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 SafeNet’s Cryptolink product, it provides a unique message identifier for all messages. Reserved Byte
Currently restricted to 00
eta-function ID
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.
Return Code
(response only) The return code indicates the status of the sent message.
Message ID
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
Mark II Programmers Guide
Data
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
Return Codes: 00 OK 01 Invalid meta-function Id 02 Invalid version number 03 Invalid data field length
NOTE •
© SafeNet, Inc.
If an error occurs in the E3 Function the encapsulated message is not run and no return data will be presented.
29
Mark II Programmers Guide
© SafeNet, Inc.
Chapter 3 The Metafunction
30
Mark II Programmers Guide
Chapter 4 HSM Status Functions
Chapter 4 HSM Status Functions Summary of HSM Status Functions Function Name
Function Code
Page
HSM_STATUS
01
32
HSM-ERRORLOG-STATUS
FFF0
34
HSM-GET-ERRORLOG
FFF1
36
The Error Log The error log consists of one or more text files stored on the hard disk of the HSM. If an error condition is generated by the HSM’s software that error condition is written to the HSM’s error log. The error number, line of code and module being run are the details recorded for each error when it occurs. The error log is not an audit trail and does not record details of functions run, function data, keys saved or key data. The data in the error log is gathered primarily for return to SafeNet to assist with troubleshooting.
Recovering the error log The recommended method for retrieving the error log from a TCP/IP or Async HSM is to use the SafeNet error log retrieval program (lrp.exe) that makes use of the functions documented in this section. This program is distributed separately. To use the error log retrieval program it must first be installed on a PC. The HSM is then taken off line and connected to the PC which then acts as the host. The retrieval program can then be run and the errorlog details displayed using the program’s user friendly interface.
© SafeNet, Inc.
31
Mark II Programmers Guide
Chapter 4 HSM Status Functions
HSM_STATUS
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
Request Content 01
Length 1
Attribute h
Description Function Code
Response Content 01 rc
Length 1 1
Attribute h h
Description Function Code Return Code
1 1 1 1 1 1 1 1 2 4 4 1 n
h h h h h h h h h h h h h
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
D D D D D
This function activates the self-tests and returns the results to the host. * RAM Status * ROM Status DES Status
Host Port Status
Battery Status * Hard Disk Status RSA Accelerator Performance Level Reset Count
© SafeNet, Inc.
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
32
Mark II Programmers Guide
Chapter 4 HSM Status Functions
Calls in last minute Calls in last 10 mins Software ID length Software ID
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
© SafeNet, Inc.
UCHAR UCHAR UCHAR UCHAR UCHAR UCHAR UCHAR UCHAR USHORT ULONG ULONG EFTBUFFER
*RAMStatus, *ROMStatus, *DESStatus, *HostPortStatus, *BatteryStatus, *HardDiskStatus, *RSAAccelerator, *PerformanceLevel, *ResetCount, *CallsInLastMinute, *CallsInLast10Minutes, *SoftwareID);
33
Mark II Programmers Guide
Chapter 4 HSM Status Functions
HSM-ERRORLOG-STATUS
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
Request Content FFF0 FM
Length 3 1
Attribute h h
Description Function Code Function Modifier = 00
Response Content FFF0 rc
Length 3 1
Attribute h h
Description Function Code Return Code
No of Error log Files
1
h
00 if no errorlog file created
Repeat for each errorlog file: Errorlog File Number Total No of Errors logged
1 2
h h
First Errorlog Date First Errorlog Time Last Errorlog Date Last Errorlog Time
8 6 8 6
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
D D U D D
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
© SafeNet, Inc.
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.
34
Mark II Programmers Guide
Chapter 4 HSM Status Functions
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
© SafeNet, Inc.
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] );
35
Mark II Programmers Guide
Chapter 4 HSM Status Functions
HSM-GET-ERRORLOG
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
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
Attribute h h
1 2 8 6 1
h h h h h
Length 3 1
Attribute h h
1
h
00 to 10 max.
2 Var
h h
0 to 65,536, big-endian ASCII formatted log data
D D U D D
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
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
© SafeNet, Inc.
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.
36
Mark II Programmers Guide
Chapter 4 HSM Status Functions
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,
© SafeNet, Inc.
OUT
UCHAR
*Returned_File_Number,
_OUT _OUT
UCHAR EFTBUFFER
Error_Log_Index[2], *Error_Log_Data,
_OUT _OUT
UCHAR EFTBUFFER
Error_Log_Index1[2], *Error_Log_Data1,
_OUT _OUT
UCHAR EFTBUFFER
Error_Log_Index2[2], *Error_Log_Data2,
_OUT _OUT
UCHAR EFTBUFFER
Error_Log_Index3[2], *Error_Log_Data3,
_OUT _OUT
UCHAR EFTBUFFER
Error_Log_Index4[2], *Error_Log_Data4,
_OUT _OUT
UCHAR EFTBUFFER
Error_Log_Index5[2], *Error_Log_Data5,
_OUT _OUT
UCHAR EFTBUFFER
Error_Log_Index6[2], *Error_Log_Data6,
_OUT _OUT
UCHAR EFTBUFFER
Error_Log_Index7[2], *Error_Log_Data7,
_OUT _OUT
UCHAR EFTBUFFER
Error_Log_Index8[2], *Error_Log_Data8,
_OUT _OUT
UCHAR EFTBUFFER
Error_Log_Index9[2], *Error_Log_Data9);
37
Mark II Programmers Guide
© SafeNet, Inc.
Chapter 4 HSM Status Functions
38
Mark II Programmers Guide
Chapter 5 KM Change Functions
Chapter 5 KM Change Functions Summary of KM Change Functions
© SafeNet, Inc.
Function Name
Function Code
Page
Establish_KM
11
40
KM_Migrate
12
41
Erase_Old_KM
13
43
39
Mark II Programmers Guide
Chapter 5 KM Change Functions
Establish_KM
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
Request Content 11
Length 1
Attribute h
Description Function Code
Response Content 11 rc
Length 1 1
Attribute h h
Description Function Code Return Code
D D D D D
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.
SHP Toolkit MK2 int EFT_11_EstablishKM(void);
© SafeNet, Inc.
40
Mark II Programmers Guide
Chapter 5 KM Change Functions
KM_Migrate
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
Request Content 12
Length 1
Attribute h
1 1 Var
h h K-Spec
Length 1 1
Attribute h h
1 Var
h K-Spec
i n 1 Key Spec
Response Content 12 rc 1
1
n Key Spec
D D D D D
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)
This field may be repeated
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
Single or double length key specifier
i
Variant of the Domain Master Key
SHP Toolkit MK2
© SafeNet, Inc.
41
Mark II Programmers Guide
Chapter 5 KM Change Functions
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
© SafeNet, Inc.
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);
42
Mark II Programmers Guide
Chapter 5 KM Change Functions
Erase_Old_KM
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
Request Content 13
Length 1
Attribute h
Description Function Code
Response Content 13 rc
Length 1 1
Attribute h h
Description Function Code Return Code
D D D D D
Used to erase the old KM. This function is enabled/disabled by a console operation.
SHP Toolkit MK2 int EFT_13_EraseOldKM(void);
© SafeNet, Inc.
43
Mark II Programmers Guide
© SafeNet, Inc.
Chapter 5 KM Change Functions
44
Mark II Programmers Guide
Chapter 6 Transfer Functions
Chapter 6 Transfer Functions Summary Of Transfer Functions
© SafeNet, Inc.
Function Name
Function Code
Page
Retrieve_Key
21
46
Store_Key
22
48
KEY_IMPORT
EE0200
49
KEY_EXPORT
EE0201
52
Get_Key_Details
EE0202
54
45
Mark II Programmers Guide
Chapter 6 Transfer Functions
Retrieve_Key
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
Request Content 21 FM
Length 1 1
Attribute h h
Var
K-Spec
Length 1 1
Attribute h h
Key Type
1
h
Key Spec
Var
K-Spec
3
h
KXT Spec Response Content 21 rc
KVC
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
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
Transfer Table Key (1-20)
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.
SHP Toolkit MK2 int EFT_21_RetrieveKey(
© SafeNet, Inc.
46
Mark II Programmers Guide
IN IN
Chapter 6 Transfer Functions UCHAR KEYSPEC
OUT UCHAR OUT KEYSPEC OUT UCHAR
© SafeNet, Inc.
Reserved[2], *tfrTableIndex, *keyType, *retrievedKey, KVC[3] );
47
Mark II Programmers Guide
Chapter 6 Transfer Functions
Store_Key
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
Request Content 22 FM
Length 1 1
Attribute h h
KXT Spec
Var
K-Spec
Key Type
1
h
Key Spec
Var
K-Spec
3 Length 1 1
h Attribute h h
KVC Response Content 22 rc
D D D D D
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
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.
Reserved[2], *tfrTableIndex, keyType, *keyToStore, KVC[3]);
48
Mark II Programmers Guide
Chapter 6 Transfer Functions
KEY_IMPORT
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
Request Content EE0200 FM
Length 3 1
Attribute h h
KIR Spec
Var
K-Spec
Key Type Enc Mode
1 1
d h
eKIRvx(K)
Var
h
Length 3 1
Attribute h h
Var
K-Spec
3
h
Response Content EE0200 Rc Key Spec KVC
D D D D D
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.
© SafeNet, Inc.
FM
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 a HSM-stored or host-stored, single-length or double-length KIR. Accepts key spec formats 0 - 3, 10, 11, 13, and 15.
Key Type
Indicates the type of received encrypted key as follows:
49
Mark II Programmers Guide
Chapter 6 Transfer Functions 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 decrypting the incoming key: 0 1
ECB CBC
eKIRVx(K)
Key encrypted by a variant of the Interchange Receive Key. Accepts key spec formats 10, 11, 13 and 14.
Key Spec
Key Specifier incorporating an encrypted key. Single length ECB and double length CBC encrypted keys (Formats 10, 11, 12, 13, 14).
KVC
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
Mark II Programmers Guide
OUT OUT
© SafeNet, Inc.
Chapter 6 Transfer Functions
KEYSPEC UCHAR
*eKMvK, KVC[3]);
51
Mark II Programmers Guide
Chapter 6 Transfer Functions
KEY_EXPORT
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
Request Content EE0201 FM
Length 3 1
Attribute h h
KIS Spec
Var
K-Spec
Key Type Enc Mode
1 1
d h
Key Spec
Var
K-Spec
Length 3 1
Attribute h h
Var 3
h h
Response Content EE0201 rc eKISvx(K) KVC
D D D D D
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
= 00. Must be set to zero.
KIS Spec
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.
Key Type
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 encrypted by a variant of the Interchange Store Key.
Key Spec
Key Specifier incorporating an encrypted key. Single length ECB and double length CBC encrypted keys (Formats 10, 11, 12, 13 and 14).
KVC
Key Verification Code for the key
Details and Restrictions
© SafeNet, Inc.
52
Mark II Programmers Guide
Chapter 6 Transfer Functions
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
© SafeNet, Inc.
EFTBUFFER UCHAR
*eKISvK, KVC[3]);
53
Mark II Programmers Guide
Chapter 6 Transfer Functions
Get_Key_Details
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
Request Content EE0202 FM
Length 3 1
Attribute h h
Key Spec
Var
K-Spec
Key Type
1
h
1 Length 3 1
h Attribute h h
1
h
Var
h
KVC Type Response Content EE0202 rc Parity KVC
D D D D D
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.
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
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
KVC Type
Specifies the method used to calculate the KVC. Initially only a value of zero is supported, indicating the use of the standard method.
Parity
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
Mark II Programmers Guide
Chapter 7 HSM Software Upgrade Functions
Chapter 7 HSM Software Upgrade Functions Summary of HSM Software Upgrade Functions
© SafeNet, Inc.
Function Name
Function Code
Page
LOAD_HSM_SOFTWARE
EE3100
56
HSM_SOFTWARE_STATUS
EE3101
58
55
Mark II Programmers Guide
Chapter 7 HSM Software Upgrade Functions
LOAD_HSM_SOFTWARE
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
Request Content EE3100 FM
Length 3 1
Attribute h h
File Id
1
h
Control
1
h
4 Var Length 3 1
h h Attribute h h
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
4
h
Length of partial saved file.
File Length / Offset Data Segment Response Content EE3100 rc Cumulative Data Length
D D U D D
Description Function Code Function Modifier = 00
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
Control
This field identifies the name of the file that is being transferred as follows: 01
File ‘eracom.s90’ to be loaded.
02
File ‘eracom.key’ to be loaded.
01
First segment of file to be loaded.
02
File Length / Offset
© SafeNet, Inc.
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).
Data Segment
This field has variable data length and contains the data segment of image file. Usually have constant segment size.
Cumulative Data Length
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
ESMID
Part of the SHP Toolkit MK2 function call. The ESMID is a pointer to a NULL
56
Mark II Programmers Guide
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
© SafeNet, Inc.
UCHAR
Data_len [4]);
57
Mark II Programmers Guide
Chapter 7 HSM Software Upgrade Functions
HSM_SOFTWARE_STATUS
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
Request Content EE3101 FM
Length 3 1
Attribute h h
Description Function Code Function Modifier = 00
Response Content EE3101 rc Status
Length 3 1 1
Attribute h h h
Var
h
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 Software’s version number.
Version
D D U D D
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.
This field represents status of Loaded Software on a HSM box.
58
Mark II Programmers Guide
Chapter 7 HSM Software Upgrade Functions 00
New Software has been loaded from ‘CD ROM’ and available on ‘Loaded Area’ for installation.
01
New Software has been loaded from ‘Host functions’ and available on ‘Loaded Area’ for installation.
02
New Software is being loaded from ‘Host functions’ and currently not available on ‘Loaded Area’ for installation.
03
New Software has been loaded and being verified, currently not available on ‘Loaded Area’ for installation.
04
No Software is loaded into ‘Loaded Area’.
05
New Software is being loaded from ‘CD ROM’ and currently not available on ‘Loaded Area’ for installation.
06
New software being loaded cannot be verified because it is not valid software. New Software loading failed.
07
New software being loaded cannot be verified because it is incompatible or not of allowed variety. New Software loading is failed.
08
SHP package has been loaded from host into host loaded area.
09
SHP package is being transferred from host to host loaded area.
10
No SHP package is loaded from host to host loaded area.
Version
If any software is loaded on the HSM, its version number is returned in this variable length field as string like “M070708”.
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.
SHP Toolkit MK2 int EFT_EE3101_ HSMSoftwareStatus( IN UCHAR *ESMID, IN UCHAR FM, OUT OUT
© SafeNet, Inc.
UCHAR EFTBUFFER
*Status, *Version);
59
Mark II Programmers Guide
© SafeNet, Inc.
Chapter 7 HSM Software Upgrade Functions
60
Mark II Programmers Guide
Chapter 8 EFT Terminal Functions
Chapter 8 EFT Terminal Functions Summary of EFT Terminal Functions Function Name
Function Code
Page
Terminal Master Key Generation Key Mailer
EE0E01
62
EE0400
66
Initial Session Key Generation IT_KEY_GEN
Rollover Session Key Generation NT_KEY_GEN
EE0401
69
47
71
49
72
EE0406
73
EE0408
74
Docutel Key Generation D51-PPK-GEN 3624 Comms Key Generation M-DPK-GEN Terminal Verification TERM_VER_2 DUKPT BDK Generation BDKGEN
© SafeNet, Inc.
61
Mark II Programmers Guide
Chapter 8 EFT Terminal Functions
Key Mailer
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
Request Content EE0E01 FM
Length 3 1
Attribute h h
1 1 1 Var 1 1 1 Var 1
h h h h h h h h h
1 Length 3 1
h Attribute h h
eKMvX(key)
Var
Key-Spec
KVC
Var
h
nA Line No. Column No. Data nB Line No. Column No. Data Key Type KVC Type Response Content EE0E01 rc
D D U D D
Description Function Code Function Modifier = x0, 01, 02 or 03 Number of text fields for env. ‘A’
Number of text fields for env. ‘B’
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
nB in position shown, no additional fields
x1
nB moves below nA, no additional fields
x2
nB in position shown, additional fields present
x3
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
Mark II Programmers Guide
Chapter 8 EFT Terminal Functions
nA
Number of text fields to print on the ‘A’ envelope (max.10).
Line No.
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.
Column No.
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.
Data
This is a variable length field that contains the data to be printed.
nB
Number of text fields to print on the ‘B’ envelope (max.10).
Key Type
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 X’FF’. If key type specified in this field conflicts with that entered at the console, the function will fail with rc = X’28’ 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.
rc
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.
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).
© SafeNet, Inc.
Return code 02
Error condition Illegal Function Code (that is, the Key Mailer facility was not enabled when the Key Mailer request was received).
04
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.
63
Mark II Programmers Guide
0B
Chapter 8 EFT Terminal Functions
Printer is not operable.
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,
© SafeNet, Inc.
_IN _IN _IN
UCHAR *LineNo1a, UCHAR *ColumnNo1a, EFTBUFFER *Data1a,
_IN _IN _IN
UCHAR *LineNo2a, UCHAR *ColumnNo2a, EFTBUFFER *Data2a,
_IN _IN _IN
UCHAR *LineNo3a, UCHAR *ColumnNo3a, EFTBUFFER *Data3a,
_IN _IN _IN
UCHAR *LineNo4a, UCHAR *ColumnNo4a, EFTBUFFER *Data4a,
_IN _IN _IN
UCHAR *LineNo5a, UCHAR *ColumnNo5a, EFTBUFFER *Data5a,
_IN _IN _IN
UCHAR *LineNo6a, UCHAR *ColumnNo6a, EFTBUFFER *Data6a,
_IN _IN _IN
UCHAR *LineNo7a, UCHAR *ColumnNo7a, EFTBUFFER *Data7a,
_IN _IN _IN
UCHAR *LineNo8a, UCHAR *ColumnNo8a, EFTBUFFER *Data8a,
_IN _IN _IN
UCHAR *LineNo9a, UCHAR *ColumnNo9a, EFTBUFFER *Data9a,
_IN _IN _IN
UCHAR *LineNo10a, UCHAR *ColumnNo10a, EFTBUFFER *Data10a,
64
Mark II Programmers Guide
© SafeNet, Inc.
Chapter 8 EFT Terminal Functions
_IN _IN _IN
UCHAR *LineNo1b, UCHAR *ColumnNo1b, EFTBUFFER *Data1b,
_IN _IN _IN
UCHAR *LineNo2b, UCHAR *ColumnNo2b, EFTBUFFER *Data2b,
_IN _IN _IN
UCHAR *LineNo3b, UCHAR *ColumnNo3b, EFTBUFFER *Data3b,
_IN _IN _IN
UCHAR *LineNo4b, UCHAR *ColumnNo4b, EFTBUFFER *Data4b,
_IN _IN _IN
UCHAR *LineNo5b, UCHAR *ColumnNo5b, EFTBUFFER *Data5b,
_IN _IN _IN
UCHAR *LineNo6b, UCHAR *ColumnNo6b, EFTBUFFER *Data6b,
_IN _IN _IN
UCHAR *LineNo7b, UCHAR *ColumnNo7b, EFTBUFFER *Data7b,
_IN _IN _IN
UCHAR *LineNo8b, UCHAR *ColumnNo8b, EFTBUFFER *Data8b,
_IN _IN _IN
UCHAR *LineNo9b, UCHAR *ColumnNo9b, EFTBUFFER *Data9b,
_IN _IN _IN _IN _IN
UCHAR *LineNo10b, UCHAR *ColumnNo10b, EFTBUFFER *Data10b, UCHAR *KeyType, UCHAR *KvcType,
OUT _OUT
KEYSPEC EFTBUFFER
*eKMvX_KEY, *KVC_Key );
65
Mark II Programmers Guide
Chapter 8 EFT Terminal Functions
Initial Session Key Generation IT_KEY_GEN
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
Request Content EE0400 FM
Length 3 1
Attribute h h
Var
K-Spec
2 Length 3 1
h Attribute h h
n eKTM(KS) 1 KS-Spec
1 Var Var
h h K-Spec
1
3
h
KTM-Spec Key Flags Response Content EE0400 rc 1
1
KVC
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
This set of fields will occur ‘n’ 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. 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
Mark II Programmers Guide
Chapter 8 EFT Terminal Functions
KTM-Spec
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.
Key Flags
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
session key type
0 1 2 3 7 8 9 10 11 12
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.
13-15
Bit 0 is the least significant (right most) bit. Examples: To generate a single-length MAC key, this field must be set to X’0004’; • eKTM(KS) KS-Spec KVC
To generate a double-length PIN encrypting key and a singlelength MAC key, the field must be set to X’0204’.
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.
SHP Toolkit MK2
© SafeNet, Inc.
67
Mark II Programmers Guide
Chapter 8 EFT Terminal Functions
int EFT_EE0400_InitialSessionKeyGeneration( IN UCHAR FM, IN KEYSPEC *KTM, IN UCHAR KeyFlags[2],
© SafeNet, Inc.
OUT
UCHAR
*numKeys,
OUT OUT OUT
EFTBUFFER KEYSPEC UCHAR
*eKTM_KS1, *KS1, KVC1[3],
_OUT _OUT _OUT
EFTBUFFER KEYSPEC UCHAR
*eKTM_KS2, *KS2, KVC2[3],
_OUT _OUT _OUT
EFTBUFFER KEYSPEC UCHAR
*eKTM_KS3, *KS3, KVC3[3],
_OUT _OUT _OUT
EFTBUFFER KEYSPEC UCHAR
*eKTM_KS4, *KS4, KVC4[3] );
68
Mark II Programmers Guide
Chapter 8 EFT Terminal Functions
Rollover Session Key Generation NT_KEY_GEN
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
Request Content EE0401 FM Key Flags 1 KSn Spec Response Content EE0401 Rc 1
N eKSn(KSn+1) 1 KSn+1 Spec 1
KVC
Length 3 1
Attribute h h
2 Var
h K-Spec
Length 3 1
Attribute h h
1 Var Var
h h K-Spec
3
h
D D D D U
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
1
This set of fields will occur ‘n’ times.
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.
© SafeNet, Inc.
FM
The Host Key Protection using Function Modifier can be in the range of x0, where x= 0, 1, or 2.
Key Flags
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
session key type
0 1 2 3 7 8 9
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).
69
Mark II Programmers Guide
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 X’0004’; •
To generate a single-length PIN encrypting key and a doublelength MAC key, the field must be set to X’0402’.
KS Spec
A key specifier incorporating a session key, encrypted by a variant of the Domain master key
eKSn(KSn+1)
The new session key encrypted by the supplied session key
KSn+1 Spec
A key specifier to the new session key
KVC
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,
© SafeNet, Inc.
OUT
UCHAR
*numKeys,
OUT OUT OUT
EFTBUFFER KEYSPEC UCHAR
*eKS_KS1, *KS1, KVC1[3],
_OUT _OUT _OUT
EFTBUFFER KEYSPEC UCHAR
*eKS_KS2, *KS2, KVC2[3],
_OUT _OUT _OUT
EFTBUFFER KEYSPEC UCHAR
*eKS_KS3, *KS3, KVC3[3]);
70
Mark II Programmers Guide
Chapter 8 EFT Terminal Functions
Docutel Key Generation D51-PPK-GEN
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
Request Content 47
Length 1
Attribute h
Description Function Code
n Response Content 47 rc
1 Length 1 1
d Attribute h h
KTM Index Description Function Code Return Code
8 8 8
B64 B64 B64
eKTMn(PPK) eKMv1(PPK) ePPK(VCon)
D D U U U
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
Mark II Programmers Guide
Chapter 8 EFT Terminal Functions
3624 Comms Key Generation M-DPK-GEN
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
Request Content 49
Length 1
Attribute h
Description Function Code
TKSI Response Content 49 rc
1 Length 1 1
d Attribute h h
Terminal Key Set Index (1 - 2) Description Function Code Return Code
8 8
B64 B64
eKTM(DPK) eKM(DPK)
D D U U U
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
Mark II Programmers Guide
Chapter 8 EFT Terminal Functions
Terminal Verification TERM_VER_2
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
Request Content EE0406 FM KTM-Spec
SEC-No Logon-Data Response Content EE0406 rc
Length 3 1
Attribute h h
Description Function Code Function Modifier = 00
Var
K-Spec
8 8 Length 3 1
h h Attribute h h
Key specifier for KTM (Formats: 0 - 3, 10, 11, 13) Security Number Logon Data Description Function Code Return Code
D D D D U
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
A key specifier which incorporates an index to an HSM-stored or host-stored single length or double length KTM.
SEC-No
Security Number for the terminal.
Logon-Data
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
Mark II Programmers Guide
Chapter 8 EFT Terminal Functions
DUKPT BDK Generation BDKGEN
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
Request Content EE0408 FM Key Length
Response Content EE0408 rc BDK
Length 3 1
Attribute h h
1
h
Length 3 1
Attribute h h
Var
K-Spec
D D D D U
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)
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.
SHP Toolkit MK2 int EFT_EE0408_DUKPT_BDK_Generation(
© SafeNet, Inc.
74
Mark II Programmers Guide
© SafeNet, Inc.
Chapter 8 EFT Terminal Functions
IN IN
UCHAR UCHAR
FM, KeyLength,
OUT
KEYSPEC
*BDK);
75
Mark II Programmers Guide
© SafeNet, Inc.
Chapter 8 EFT Terminal Functions
76
Mark II Programmers Guide
Chapter 9 Remote ATM Initialization Functions
Chapter 9 Remote ATM Initialization Functions Summary of Remote ATM Initialization Functions Function
Function Code
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
Page
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
Mark II Programmers Guide
•
Chapter 9 Remote ATM Initialization Functions
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
Private key processing
Public key processing
Certificate
Not currently supported
Verify certificate
Data Signature
Sign data
Verify signed data
Key Transport
Decrypt encrypted key
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.
Authentication of public keys The authenticity of a public key is often ensured by its incorporation in a public key certificate. For efficient repeated use by the Mark II, a public key from a certificate is transferred into a key specifier that uses a 3DES MAC to prevent modification. Additionally, a method must be provided that allows an authorized public key that is not in a certificate to be used by the HSM. The mechanism used to transfer the key into a key specifier must minimize the chance of an unauthorized public key being introduced. A host function is provided that inserts a public key into a key specifier. This function should be disabled under normal circumstances, and enabled only for the duration required to import the public key.
Storage of RSA keys Mark II functionality incorporates a table of 16 HSM-stored RSA key pairs which are used in conjunction with AS2805 Part 6.3 key transport using RSA. There is no facility for extracting the private key of a table from the HSM. The Generate RSA key pair function described in this chapter is used to host-store RSA key pairs. While the host functions defined here support host-stored RSA keys only, they may be extended in the future to additionally support HSM-stored key pairs. Key specifier that support host-stored keys are defined in Chapter 2 Function Construction.
© SafeNet, Inc.
78
Mark II Programmers Guide
Chapter 9 Remote ATM Initialization Functions
Generate RSA Key Pair
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
Request Content EE9001 FM
Length 3 1
Attribute h h
2
h
Modulus Length Public Exponent User Data
2 Var Var
h h h
Response Content EE9001 rc
Length 3 1
Attribute h h
PK
Var
K-Spec
SK
Var
K-Spec
Key Type
D D D D U
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
Mark II Programmers Guide
Chapter 9 Remote ATM Initialization Functions
Diebold NCR
PK
SK
vHOST
sHOST
PK-HSM
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.
Diebold
PK
SK
vHOST
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
© SafeNet, Inc.
KEYSPEC KEYSPEC
*PK, *SK);
80
Mark II Programmers Guide
Chapter 9 Remote ATM Initialization Functions
Import Public Key
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
Request Content EE9003 FM
Length 3 1
Attribute h h
2
h
PK
Var
K-Spec
User Data
Var
h
Length 3 1
Attribute h h
Var
K-Spec
Key Type
Response Content EE9003 rc PK
D D D D U
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 NCR’s 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
© SafeNet, Inc.
KEYSPEC
*PKo);
81
Mark II Programmers Guide
Chapter 9 Remote ATM Initialization Functions
Import public key certificate
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
Request Content EE9004 FM
Length 3 1
Attribute h h
Var
K-Spec
Certificate Format
1
h
Hash Function
1
h
Certificate Key Type
Var 2
h h
User Data
Var
h
Length 3 1
Attribute h h
Var
K-Spec
PKCA
Response Content EE9004 rc PK
D D D D U
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)
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 Host’s 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
Mark II Programmers Guide
Chapter 9 Remote ATM Initialization Functions
(The Verify signed data function may be used instead.) 2. Import of EPP’s 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]. If equal to 03 (NCR), the data in the Certificate field takes the format: modulus (256 bytes) concatenated with signature (256 bytes).
Certificate Format
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
preceded by the variable length prefix described in Chapter 2 Function Construction.
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
© SafeNet, Inc.
KEYSPEC
*PK);
83
Mark II Programmers Guide
Chapter 9 Remote ATM Initialization Functions
Sign Data
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
Request Content EE9005 FM
Length 3 1
Attribute h h
Var
K-Spec
1 1
h h
Var Length 3 1
h Attribute h h
Var
h
SK
Signature Algorithm Hash Function
Data Response Content EE9005 rc Signature
D D D D U
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))
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
© SafeNet, Inc.
EFTBUFFER
( FM, *SK, Algorithm, HashFunction, *Data, *Signature);
84
Mark II Programmers Guide
Chapter 9 Remote ATM Initialization Functions
Verify Signed Data
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
Request Content EE9006 FM PK
Signature Algorithm Hash Function
Data sSK(Data) or sSK(h(Data)) Response Content EE9006 rc
Length 3 1
Attribute h h
Var
K-Spec
1 1
h h
Var Var
h h
Length 3 1
Attribute h h
D D D D U
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
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
Mark II Programmers Guide
Chapter 9 Remote ATM Initialization Functions
Generate MD5 Hash
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
Request Content EE9007 FM
Length 3 1
Attribute h h
Mode
1
h
Bit Count
8
h
Hash Value
16
h
Var Length 3 1
h Attribute h h
8 16
h h
Data Response Content EE9007 rc Bit Count Hash Value
D D D D U
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
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
© SafeNet, Inc.
UCHAR UCHAR
BitCount2[8], HashValue2[16] );
86
Mark II Programmers Guide
Chapter 9 Remote ATM Initialization Functions
Generate SHA Hash
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
Request Content EE9008 FM
Length 3 1
Attribute h h
Algorithm Mode
1 1
h h
Bit Count
8
h
Var
h
Var Length 3 1
h Attribute h h
8 Var
h h
Hash Value Data Response Content EE9008 rc Bit Count Hash Result
D D D D U
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
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
© SafeNet, Inc.
UCHAR EFTBUFFER
BitCount2[8], *HashResult );
87
Mark II Programmers Guide
Chapter 9 Remote ATM Initialization Functions
Generate Key – Diebold
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
Request Content EE9101 FM
Length 3 1
Attribute h h
IHOST IATM rATM eATM
Var Var Var Var
h h h K-Spec
sHOST
Var
K-Spec
1
h
1 Length 3 1
h Attribute h h
KTB1
Var
h
Key token B1
rHOST
Var
h
Host random nonce
KKTM
Var
K-Spec
Key Len Key Type Response Content EE9101 Rc
D D D D U
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 specifier for generated key – as determined by Key len (Formats: 10, 11, 13)
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
Mark II Programmers Guide
© SafeNet, Inc.
Chapter 9 Remote ATM Initialization Functions
IN IN IN IN IN
EFTBUFFER KEYSPEC KEYSPEC UCHAR UCHAR
*r_ATM, *e_ATM, *s_HOST, KeyLen, KeyType,
OUT OUT OUT
EFTBUFFER EFTBUFFER KEYSPEC
*KT_B1, *r_HOST, *K_KTM);
89
Mark II Programmers Guide
Chapter 9 Remote ATM Initialization Functions
Verify ATM Response – Diebold
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
Request Content EE9102 FM KTA2 IHOST rATM rHOST PATM Response Content EE9102 rc
Length 3 1
Attribute h h
Var Var Var Var Var
h h h h K-Spec
Length 3 1
Attribute h h
D D D D U
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
This function processes the ATM’s response (KTA2) to the download of the initial key (KTB1). It verifies the signature on the PKCS#7 messages and compares random nonce’s 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
Mark II Programmers Guide
Chapter 9 Remote ATM Initialization Functions
Generate KM – NCR
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
Request Content EE9201 FM
Length 3 1
Attribute h h
SK-HSM
Var
K-Spec
PK-EPP
Var
K-Spec
Length 3 1
Attribute h h
KTM-Spec
Var
K-Spec
[KTM]PK-EPP ([KTM]PK-EPP) *SK-HSM KVC(KTM)
Var Var
h h
Key specifier for generated KTM. (Format: 11, 13) Encrypted key Block Signed encrypted key Block
3
h
NCR Key Verification Value (KVV)
Response Content EE9201 rc
D D D D U
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
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
© SafeNet, Inc.
KEYSPEC EFTBUFFER EFTBUFFER
*KTM, *eKTM_PK_EPP, *sSK_HSM_eKTM_PK_EPP,
91
Mark II Programmers Guide
OUT
© SafeNet, Inc.
Chapter 9 Remote ATM Initialization Functions UCHAR
KVC_KTM[3] );
92
Mark II Programmers Guide
Chapter 10 Interchange Functions
Chapter 10 Interchange Functions The standard Interchange functions use Interchange Send and Receive Keys (KIS/KIR). KIS/KIR can now be stored as either a single or double length keys. The functions listed below will automatically determine the length of the key from the key storage and perform the appropriate encrypt/decrypt operation.
Summary of Interchange Functions Function Name
Function Code
Page
Initial Session Key Generation II_KEY_GEN
EE0402
94
EE0403
97
EE0404
101
EE0405
103
Receive Initial Session Key II_KEY_RCV Rollover Session Key Generation NI-KEY-GEN Receive Rollover Session Key NI_KEY_RCV
© SafeNet, Inc.
93
Mark II Programmers Guide
Chapter 10 Interchange Functions
Initial Session Key Generation II_KEY_GEN
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
Request Content EE0402 FM
Length 3 1
Attribute h h
Description Function Code Function Modifier = 00, 10, 20
KIS-Spec
Var
K-Spec
Key Flags
2
h
Length 3 1
Attribute h h
Key specifier for KIS (Formats: 0 - 3, 10, 11, 13, 15) Key Type indicator / Encryption mode Description Function Code Return Code
1 Var Var
h h Key-Spec
3
h
Response Content EE0402 Rc 1
N eKISnvx(KS) 1 KS-Spec 1
1
KVC
D D D D D
Number of following key sets. Encrypted Session Key Key specifier for Session key (Formats: 10, 11, 13) Key Verification Code
This set of fields will occur ‘n’ times in the response
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
Mark II Programmers Guide
FM
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.
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)
Key encrypted by a variant of the Interchange Receive Key.
KS-Spec
Key Specifier incorporating an encrypted key.
KVC
Key Verification Code for the key
Example values of 'Key Flags' field Value of 'Key Flags' field
Encryption mode
Keys to be generated
X’0004’
ECB
Single-length MPK
X’0402’
ECB
Single-length PPK; double-length MPK
X'1600'
CBC
Double-length PPK; double-length MPK
X'1A00'
CBC
Double-length KIS; double-length PPK
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 KIS-Spec in the request. 2. If a HSM stored KIS is provided in the request, the appropriate variant scheme will be used when encrypting a generated key using that KIS. 3. If a host stored KIS is provided in the request in a key specifier format 10, 11 or 13, the default KIS variants used to encrypt the outgoing 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 KIS or host-stored KIS in a format 15 key specifier), a double-length session key encrypted under KIS is encrypted using CBC. The encryption mode flag bit is ignored; i.e. a value of 0 (ECB) will not cause an error.
© SafeNet, Inc.
95
Mark II Programmers Guide
Chapter 10 Interchange Functions
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.
SHP Toolkit MK2
© SafeNet, Inc.
96
Mark II Programmers Guide
Chapter 10 Interchange Functions
int EFT_EE0402_InitialSessionKeyGeneration( IN UCHAR FM, IN KEYSPEC *KIS, IN UCHAR KeyFlags[2], OUT
UCHAR
*numKeys,
OUT OUT OUT
EFTBUFFER KEYSPEC UCHAR
*eKIS_KS1, *KS1, KVC1[3],
_OUT _OUT _OUT
EFTBUFFER KEYSPEC UCHAR
*eKIS_KS2, *KS2, KVC2[3],
_OUT _OUT _OUT
EFTBUFFER KEYSPEC UCHAR
*eKIS_KS3, *KS3, KVC3[3],
_OUT _OUT _OUT
EFTBUFFER KEYSPEC UCHAR
*eKIS_KS4, *KS4, KVC4[3] );
Receive Initial Session Key II_KEY_RCV
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
Request Content EE0403 FM
Length 3 1
Attribute h h
KIR-Spec
Var
K-Spec
Key Flags
2
h
Var Length 3 1
h Attribute h h
1 Var
h K-Spec
3
h
1
eKIRnvx(KS) Response Content EE0403 Rc 1
N KS-Spec 1
1
KVC
D D D D D
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
This set of fields will occur ‘n’ times.
Notes: The key-types 10, 11 under the Response Content, are generated when using the Legacy option.
© SafeNet, Inc.
97
Mark II Programmers Guide
Chapter 10 Interchange Functions
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.
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)
Key encrypted by a variant of the Interchange Receive Key.
KS-Spec
Key Specifier incorporating an encrypted key.
KVC
Key Verification Code for the key
Example values of 'Key Flags' field Value of 'Key Flags' field
© SafeNet, Inc.
Encryption mode
Keys to be generated
X’0004’
ECB
Single-length MPK
X’0402’
ECB
Single-length PPK; double-length MPK
X'1600'
CBC
Double-length PPK; double-length MPK
98
Mark II Programmers Guide
X'1A00'
Chapter 10 Interchange Functions
CBC
Double-length KIS; double-length PPK
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 • • •
• • • • •
© SafeNet, Inc.
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.
99
Mark II Programmers Guide
Chapter 10 Interchange Functions
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,
© SafeNet, Inc.
OUT
UCHAR
*numKeys,
OUT OUT
KEYSPEC UCHAR
*KS1, KVC1[3],
_OUT _OUT
KEYSPEC UCHAR
*KS2, KVC2[3],
_OUT _OUT
KEYSPEC UCHAR
*KS3, KVC3[3],
_OUT _OUT
KEYSPEC UCHAR
*KS4, KVC4[3]);
(
100
Mark II Programmers Guide
Chapter 10 Interchange Functions
Rollover Session Key Generation NI-KEY-GEN
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
Request Content EE0404 FM Key Flags 1
KSn Spec
Response Content EE0404 rc 1
n eKSn(KSn+1) 1 KSn+1 Spec 1
KVC
Length 3 1
Attribute h h
2
h
Var
K-Spec
Length 3 1
Attribute h h
1 Var Var
h h K-Spec
3
h
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
1
This set of fields will occur ‘n’ times.
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
Mark II Programmers Guide
FM
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.
Key Flags
Indicates the keys to generate and the encryption mode. The bit positions are allocated as follows: Bit:
Indicates:
0 1 2 3 8 9 10 11 12
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.
13-15
Bit 0 is the least significant (right most) bit. KSn-Spec
A key specifier incorporating a session key encrypted by a variant of the Domain master key
EKSn(KSn+1)
The new session key encrypted by the supplied session key
KSn+1-Spec
A key specifier to the new session key
KVC
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,
© SafeNet, Inc.
OUT
UCHAR
*numKeys,
OUT OUT OUT
EFTBUFFER KEYSPEC UCHAR
*eKS_KS1, *KS1, KVC1[3],
_OUT _OUT _OUT
EFTBUFFER KEYSPEC UCHAR
*eKS_KS2, *KS2, KVC2[3],
_OUT _OUT _OUT
EFTBUFFER KEYSPEC UCHAR
*eKS_KS3, *KS3, KVC3 [3] );
102
Mark II Programmers Guide
Chapter 10 Interchange Functions
Receive Rollover Session Key NI_KEY_RCV
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
Request Content EE0405 FM
Length 3 1
Attribute h h
2
h
Var
K-Spec
Var Length 3 1
h Attribute h h
n KSn+1 Spec
1 Var
h K-Spec
1
3
h
Key Flags 1
KSn Spec
1
eKSn(KSn+1) Response Content EE0405 rc 1
KVC
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
1
These fields will occur ‘n’ times.
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
© SafeNet, Inc.
Indicates the keys to generate and the encryption mode. The bit positions are allocated as follows: Bit:
Indicates:
0 1 2 3
Single-length Data Key (DPK). Single-length PIN encrypting key (PPK). Single-length MAC key (MPK). Reserved. Must be zero.
103
Mark II Programmers Guide
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. KS-Specn
Key specifier incorporating an encrypted session key.
eKSn(KSn+1)
A new session key encrypted by the old Session Key.
KVC
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,
© SafeNet, Inc.
_IN _IN
KEYSPEC EFTBUFFER
*KSi2, *eKS_KSi2,
_IN _IN
KEYSPEC EFTBUFFER
*KSi3, *eKS_KSi3,
_IN _IN
KEYSPEC EFTBUFFER
*KSi4, *eKS_KSi4,
OUT
UCHAR
*numKeys,
OUT OUT
KEYSPEC UCHAR
*KS1, KVC1[3],
_OUT _OUT
KEYSPEC UCHAR
*KS2, KVC2[3],
_OUT _OUT
KEYSPEC UCHAR
*KS3, KVC3[3],
_OUT _OUT
KEYSPEC UCHAR
*KS4, KVC4[3]);
104
Mark II Programmers Guide
Chapter 11 PIN Management Functions
Chapter 11 PIN Management Functions Host Stored PVK Management Host Stored PVK’s are represented in functions by PVK-Spec fields that are structured as follows: •
Var field showing length: i.e. 0x11
•
Format:
00x11 for ECB 00x13 for CBC
Followed by 16 bytes of Data i.e. 11111111111111110123456789012345 •
Format: 00x12 and 00x14 for Double length PVK Followed by 24 bytes of Data i.e. 333333333333333311111111111111110123456789012345
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
Mark II Programmers Guide
Chapter 11 PIN Management Functions
Summary of PIN Management Functions
© SafeNet, Inc.
Function Name
Function Code
Page
CLR-PIN-ENCRYPT
EE0600
107
MIGRATEPIN
EE0601
108
PIN-TRAN-2
EE0602
110
PIN-VER-IBM-MULTI
EE0603
112
PIN-TRAN-3624
63
114
KB-PIN-VER
64
115
VAR-KB-PIN-VER
69
116
PIN-OFF
EE0604
117
PIN-FROM-OFF
EE0609
119
Generate KM-encrypted PIN
EE0640
121
Print a KM-encrypted PIN
EE0641
122
Verify a PIN Using KM-encrypted PIN
EE0642
124
Translate a PIN from PPK to KM
EE0643
125
Migrate PIN
EE0644
108
IT-PVK-EXPORT
EF0210
127
106
Mark II Programmers Guide
Chapter 11 PIN Management Functions
PIN Encryption CLR-PIN-ENCRYPT
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
Request Content EE0600 FM PIN-Len PIN ANB PPK-Spec
Response Content EE0600 Rc ePPK(PIN)
Length 3 1
Attribute h h
1 Var 6 Var
h d d K-Spec
Length 3 1
Attribute h h
8
h
D D D D U
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
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
Identifies the number of digits in the PIN, in the range 4 – 12.
PIN
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.
PPK-Spec
Key specifier for the PPK (eKMv1 - Format 0-3, 10, 11, 13, 20 or 90).
ANB
12 PAN digits of the Account Number Block used to format the ANSI PIN Block.
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
© SafeNet, Inc.
UCHAR
ePPK_PIN[8]);
107
Mark II Programmers Guide
Chapter 11 PIN Management Functions
MIGRATEPIN
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
Request Content EE0601 FM
Length 3 1
Attribute h h
PVK1-Spec
Var
K-Spec
PAN Offset1 PINLEN PVK2-Spec
8 6 1 Var
h h h K-Spec
Length 3 1
Attribute h h
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
6
h
Replacement offset for PIN
Response Content EE0601 rc Offset2
D D D D D
Description Function Code Function Modifier = 00
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
= 00. Must be set to zero.
PVK1-Spec PVK2-Spec
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,
PAN
The ‘validation data’ that is used with the PVK and Decimalization table to produce the Offset.
Offset1 Offset2
Existing and replacement PIN offset data. The significant digits are left-justified in the field.
PINLEN
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.
SHP Toolkit MK2
© SafeNet, Inc.
108
Mark II Programmers Guide
Chapter 11 PIN Management Functions
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
Mark II Programmers Guide
Chapter 11 PIN Management Functions
PIN Translation PIN-TRAN-2
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
Request Content EE0602 FM
Length 3 1
Attribute h h
ePPKi(PIN) PPKi-Spec
8 Var
x K-Spec
PFi ANB PFo PPKo-Spec
1 6 1 Var
h h h K-Spec
Length 3 1
Attribute h h
8
h
Response Content EE0602 rc ePPKo(PIN)
D D D D D
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
specifies the format of the input PIN Block format and supports PIN formats, 01, 02, 03, 08, 09, 10, 11, and 13, if enabled.
PFo
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.
ANB
Account Number Block, which is the right most 12 digits of the Primary Account Number (PAN), excluding the check digit.
PPKo and PPKi
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
Mark II Programmers Guide
Chapter 11 PIN Management Functions
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
PFi
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.
ANB
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)
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.
PPKo and PPKi
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.
Session Method
Used when FM = 01. Session Method encrypts ePPKo(PIN + PIN Data) as per selected method. 00 = ECB, 01 = CBC.
ePPKo (PIN+PIN Data) PIN Data
© SafeNet, Inc.
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 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.
111
Mark II Programmers Guide
Chapter 11 PIN Management Functions
PIN Verification PIN-VER-IBM-MULTI
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
Request Content EE0603 FM
Length 3 1
Attribute h h
ePPK(PIN) PPK-Spec
8 Var
x K-Spec
PF ANB PVK-Spec
1 6 Var
h h K-Spec
8 6 1 Length 3 1
h h h Attribute h h
Validation Data Offset Check-Len Response Content EE0603 rc
D D D D D
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.
PF
Supports PIN formats: 01, 02, 03, 08, 09, 10, 11, 13, 20 and 90.
ANB
Account Number Block, which are the right most 12 digits of the Primary Account Number (PAN), excluding the check digit.
Validation Data
Data (usually a part of the PAN) used in the calculation of the reference PIN.
Offset
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.
Check-Len
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.
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
Mark II Programmers Guide
Chapter 11 PIN Management Functions
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
Mark II Programmers Guide
Chapter 11 PIN Management Functions
PINKEY PIN Translation PIN-TRAN-3624
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
Request Content 63
Length 1
Attribute h
ePVK(PP-PIN)
8
B64
1 8 6 Length 1 1
d B64 h Attribute h h
8
B64
PVK-Index eKMv1(PPK) ANB Response Content 63 rc ePPK(AS-PIN)
D D U U U
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
is the PIN/PAD formatted PIN Block. It must be supplied encrypted by a HSM stored PIN Verification KEY (PVK).
PVK-index
identifies the PVKn with which the supplied PIN Block is encrypted.
eKMv1(PPK)
is the host stored encrypted session key with which the resultant AS/ANSI PIN Block is returned encrypted.
ANB
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
Mark II Programmers Guide
Chapter 11 PIN Management Functions
Base Key PIN Verification KB-PIN-VER
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
Request Content 64
Length 1
Attribute h
PVK-Index KTM-Index eKTMn(AS-PIN)
1 1 8
d d B64
PAN ANB Offset Response Content 64 rc
8 6 6 Length 1 1
h h h Attribute h h
D D U U U
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
identifies the PVKn, DTn, and MINPINn appropriate to the PIN verification procedure.
KTM-Index
identifies the Terminal Master Key (KTMn) with which the PIN Block is encrypted.
AS-PIN
is the AS/ANSI formatted PIN Block containing the PIN to be verified.
PAN
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.
ANB
is the 12-digit Account Number Block used in the formation of the clear AS/ANSI PIN Block.
Offset
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
Mark II Programmers Guide
Chapter 11 PIN Management Functions
Base Key PIN Verification - Variable Length VAR-KB-PIN-VER
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
Request Content 69
Length 1
Attribute h
PVK-Index KTM-Index eKTM(AS-PIN)
1 1 8
d d B64
PAN ANB CHKLEN
8 6 1
h h h
6 Length 1 1
h Attribute h h
Offset Response Content 69 rc
D D U U U
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
identifies the PVKn, DTn, and MINPINn appropriate to the PIN verification procedure.
AS-PIN
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).
PAN
the Primary Account Number used in the verification procedure. It must be padded appropriately prior to input to this function.
ANB
is the 12-digit Account Number Block used in the formation of the clear AS/ANSI PIN Block.
CHKLEN
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.
Offset
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 an ISO-0 PIN block is disabled. See Appendix A, for a more detailed overview of the PIN verification procedure.
© SafeNet, Inc.
116
Mark II Programmers Guide
Chapter 11 PIN Management Functions
PIN Offset Generation PIN-OFF
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
Request Content EE0604 FM
Length 3 1
Attribute h h
ePPK(PIN) PPK-Spec
8 Var
x K-Spec
PF ANB PVK-Spec
1 6 Var
h d K-Spec
8 Length 3 1
h Attribute h h
6 1
h h
Validation Data Response Content EE0604 rc Offset PINLEN
D D D D D
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.
PF
Supports PIN formats: 01, 03, 08, 09, 10, 11, and 13.
ANB
Account Number Block, which is the right most 12 digits of the Primary Account Number (PAN), excluding the check digit.
Validation Data
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
Mark II Programmers Guide
Chapter 11 PIN Management Functions
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
Mark II Programmers Guide
Chapter 11 PIN Management Functions
PIN-FROM-OFF
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
Request Content EE0609 FM
Length 3 1
Attribute h h
PVK
Var
K-Spec
Validation Data Offset PIN Len PPK
8 6 1 Var
h h h K-Spec
PFo
1
h
ANB
6
d
Length 3 1
Attribute h h
8
x
Response Content EE0609 rc ePPK(PIN)
D D U D D
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
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.
© SafeNet, Inc.
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
Validation Data, which is usually a part of the Primary Account Number (PAN), and is used in the calculation of the reference PIN.
Offset
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
PIN Length, identifies the number of digits in the PIN, and hence the length of the PIN.
119
Mark II Programmers Guide
Chapter 11 PIN Management Functions
PPK
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
PFo Supports PIN formats: 01, 10, 11 and 13.
ANB
Account Number Block, which is the right-most 12 digits of the Primary Account Number (PAN), excluding the check digit.
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
© SafeNet, Inc.
UCHAR ePPK_PIN[8]);
120
Mark II Programmers Guide
Chapter 11 PIN Management Functions
Generate KM-encrypted PIN
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
Request Content EE0640 FM
Length 3 1
Attribute h h
Description Function Code Function Modifier = 00
PIN Len ANB Response Content EE0640 rc
1 6 Length 3 1
h h Attribute h h
Length of PIN ( 04 - 12) Account Number Block: Description Function Code Return Code
Var
K-Spec
KM-encrypted PIN Block (Format: 1A)
PIN-Spec
D D D D D
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
© SafeNet, Inc.
KEYSPEC
*eKM_PIN);
121
Mark II Programmers Guide
Chapter 11 PIN Management Functions
Print a KM-encrypted PIN
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
Request Content EE0641 FM PIN-Spec ANB PAN
Data Sets Line No Column No Data
Response Content EE0641 rc
Length 3 1
Attribute h h
Var
K-Spec
6 8
h h
1 1 1 Var
h h h h
Length 3 1
Attribute h h
D D U D D
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
This function prints a KM-encrypted PIN.
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],
© SafeNet, Inc.
IN
UCHAR
DataSets,
_IN _IN _IN
UCHAR UCHAR EFTBUFFER
*LineNo1, *ColumnNo1, *Data1,
_IN _IN
UCHAR UCHAR
*LineNo2, *ColumnNo2,
122
Mark II Programmers Guide
© SafeNet, Inc.
Chapter 11 PIN Management Functions
_IN
EFTBUFFER
*Data2,
_IN _IN _IN
UCHAR UCHAR EFTBUFFER
*LineNo3, *ColumnNo3, *Data3,
_IN _IN _IN
UCHAR UCHAR EFTBUFFER
*LineNo4, *ColumnNo4, *Data4,
_IN _IN _IN
UCHAR UCHAR EFTBUFFER
*LineNo5, *ColumnNo5, *Data5,
_IN _IN _IN
UCHAR UCHAR EFTBUFFER
*LineNo6, *ColumnNo6, *Data6,
_IN _IN _IN
UCHAR UCHAR EFTBUFFER
*LineNo7, *ColumnNo7, *Data7,
_IN _IN _IN
UCHAR UCHAR EFTBUFFER
*LineNo8, *ColumnNo8, *Data8,
_IN _IN _IN
UCHAR UCHAR EFTBUFFER
*LineNo9, *ColumnNo9, *Data9,
_IN _IN _IN
UCHAR UCHAR EFTBUFFER
*LineNo10, *ColumnNo10, *Data10);
123
Mark II Programmers Guide
Chapter 11 PIN Management Functions
Verify a PIN Using KM-encrypted PIN
PHW
D
SHP
D
PSO/PSG
D D D
SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
Request Content EE0642 FM ePPK(PIN) PPK-Spec PF ANB PIN-Spec Response Content EE0642 rc
Length 3 1
Attribute h h
8 Var
x K-Spec
1
h
6 Var
h K-Spec
Length 3 1
Attribute h h
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
Mark II Programmers Guide
Chapter 11 PIN Management Functions
Translate a PIN from PPK to KM
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
Request Content EE0643 FM ePPK(PIN) PPK-Spec
Length 3 1
Attribute h h
8 Var
x K-Spec
1
h
6 Length 3 1
h Attribute h h
Var
K-Spec
PF ANB Response Content EE0643 rc PIN-Spec
D D D D D
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
© SafeNet, Inc.
KEYSPEC
*eKM_PIN);
125
Mark II Programmers Guide
Chapter 11 PIN Management Functions
Migrate PIN
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
Request Content EE0644 FM PIN-Spec ANB Response Content EE0644 rc PIN-Spec
Length 3 1
Attribute h h
Var
K-Spec
6 Length 3 1
h Attribute h h
Var
K-Spec
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
© SafeNet, Inc.
KEYSPEC
*eKM_PINo);
126
Mark II Programmers Guide
Chapter 11 PIN Management Functions
IT-PVK-EXPORT
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
Request Content EF0210 FM PVK-Spec Mode
KTM-Spec Response Content EF0210 rc eKTM(PVK) KVC
Length 3 1
Attribute h h
Var
K-Spec
1
h
Var
K-Spec
Length 3 1
Attribute h h
Var 3
h h
U U D D U
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
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
= 00. Must be set to zero or one.
PVK-Spec
Key specifier which provides access to the PVK. Only HSM-stored keys are currently supported, so the key specifier must contain a key index.
KTM-Spec
A key specifier which incorporates an index to an HSM-stored or host stored single-length or double-length KTM.
eKTM(PVK)
Encrypted PVK. The size of this field is 9 bytes as only single length PVKs may be ECB encrypted.
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
Mark II Programmers Guide
© SafeNet, Inc.
Chapter 11 PIN Management Functions
128
Mark II Programmers Guide
Chapter 12 Online Banking Module Functions
Chapter 12 Online Banking Module Functions Summary of Online Banking Module Functions Function Name
Function Code
Page
OBM GetPublicKey()
EE3000
133
OBM GenerateRandomNumber
EE3001
134
OBM Verify PIN – RSA-encrypted, 3624 Offset
EE3002
135
OBM Change PIN – RSA-encrypted, 3624 Offset
EE3003
136
OBM SetPassword RSAEncrypted TPV
EE3004
138
OBM VerifyPassword RSAEncrypted TPV
EE3005
139
OBM ChangePassword RSAEncrypted TPV
EE3006
140
OBM PrintPassword
EE3008
141
OBM MigratePIN OffsetToTPV
EE3009
143
OBM GetPrintToken
EE3016
144
OBM GenerateRandomPIN
EE3017
145
OBM PrintEncryptedPIN
EE3018
146
OBM Translate PIN – RSA-encrypted, PPK
EE3019
148
OBM Set PIN – PPK-encrypted, TPV
EE3020
149
Online Banking Module Password Restrictions Password checking is case-sensitive, i.e. upper- and lower-case letters are distinct. password generation and selection will also be subject to the following restrictions. Password length The password may consist of from 4 to 30 characters. A console operation allows the minimum password length and maximum password length to be altered (within this range). Minimum numeric characters It may be stipulated that a password will contain some numeric characters. This will default to zero, but may be altered (up to the minimum password length) using console operations. Minimum alphabetic characters It may be stipulated that a password will contain some alphabetic characters. This will default to zero, but may be altered (up to the minimum password length) using console operations.
The following functions respect the above described password restrictions: Function Name OBM SetPassword RSAEncrypted TPV
© SafeNet, Inc.
Function Code EE3004
129
Mark II Programmers Guide
Chapter 12 Online Banking Module Functions
OBM ChangePassword RSAEncrypted TPV
EE3006
OBM PrintPassword
EE3008
OBM MigratePIN OffsetToTPV
EE3009
OBM GenerateRandomPIN
EE3017
Function Field Constructs The host functions specified in this section utilize the Variable-length field, Key specifier and Processing Unit field constructs. The variable-length field construct provides a standard mechanism for incorporating a field of varying length into a request or response message. It comprises of the variable-length data and a prefix which specifies the length of the data. The length prefix is in itself also of variable-length. The format of a variable-length field is fully described in Chapter 2 of this guide, in the section entitled Variable length fields in function request and response messages. The key specifier construct is a variable-length field that contains a variable-format specification of a key. In general, a key specifier may contain either an index to a HSM-stored key, or an encrypted key from host storage – encrypted by a variant of KM. The formats of currently-defined key specifiers are fully described in Chapter 2 of this guide, in the section entitled: The ‘key specifier’ function field. The processing unit (PU) is a new construct which is used in function requests. It is a shorthand way of specifying a set of fields and the associated processing just once, rather than repeating the fields and the required processing in each appropriate function.
Data Item Representation in Request/Response Messages Refer to Chapter 2 of this guide for a list of operators and qualifying letters that may be used in request and response content. The following additional qualifier is used in request and response content for the online banking module.
Attribute
Description
Struct
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.
EPB Processing Unit Field Content SK-Spec
Length
Attribute
Var
K-Spec
Description Key specifier for RSA Private Key (HSM-stored) Provides the index into the key table in Secure Memory where the key is stored.
© SafeNet, Inc.
C
Var
h
RSA-encrypted PIN Block.
P
Var
h
PKCS#1 parameter string
RN
Var
h
Random Number
130
Mark II Programmers Guide
Chapter 12 Online Banking Module Functions
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.
CTPV Processing Unit Field Content Algorithm Identifier
Length
Attribute
1
h
Description Format = two nibbles xy, where: x is the encryption algorithm identifier; y is the hash algorithm identifier. Valid values for x: = 0: no encryption; = 1: DES/3DES, CBC. Valid values for y: = 0: no hash; = 1: MD5; = 2: SHA-1. Invalid combinations of x and y: xy = 00.
DataA
Var
h
Data used in the hashing of the PIN, or in the formatting of the PIN Block for encryption. May be zero-length field.
DataB
Var
h
Data used in the hashing of the PIN. May be zero-length field.
KTPV-Spec
Var
K-Spec
KTPV used to encrypt the hashed PIN or formatted PIN Block. Or zero-length field if no encryption Allowed key spec for KTPV are 0-3, 10,11, 13 (Algorithm Identifier = 0x).
Pre-requisites: A plaintext format 2 or 12 PIN Block Process: Calculate a Transformed PIN Value by hashing and/or encrypting the PIN recovered from the supplied plaintext PIN Block. Result: Error Code. Transformed PIN Value. Processing steps
© SafeNet, Inc.
131
Mark II Programmers Guide
Chapter 12 Online Banking Module Functions
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
Mark II Programmers Guide
Chapter 12 Online Banking Module Functions
OBM GetPublicKey()
D D U D U
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
Request Content EE3000 FM PK-Spec1
Response Content EE3000 rc PK-Spec2
PVC
Length 3 1
Attribute h h
Var
K-Spec
Length 3 1
Attribute h h
Var
K-Spec
8
h
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
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
© SafeNet, Inc.
KEYSPEC UCHAR
*PK2, PVC[8]);
133
Mark II Programmers Guide
Chapter 12 Online Banking Module Functions
OBM GenerateRandomNumber
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
Request Content EE3001 FM Random Number Length Response Content EE3001 rc RN
Length 3 1
Attribute h h
1
h
Length 3 1
Attribute h h
Var
h
D D U D U
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
© SafeNet, Inc.
EFTBUFFER
*RandomNumber);
134
Mark II Programmers Guide
Chapter 12 Online Banking Module Functions
OBM Verify PIN – RSA-encrypted, 3624 Offset
D D U
PHW SHP PSO/PSG
Request Content EE3002 FM
Length 3 1
Attribute h h
EPB
Struct
PU
Var
K-Spec
8 6 Length 3 1
h h Attribute h h
PVK-Spec Validation Data Offset Response Content EE3002 Rc
SHP Toolkit MK2
D
Card Issuance (SHP Toolkit EMV)
U
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
Mark II Programmers Guide
Chapter 12 Online Banking Module Functions
OBM Change PIN – RSA-encrypted, 3624 Offset
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
Request Content EE3003 FM
Length 3 1
Attribute h h
EPB
Struct
PU
PVK-Spec1
Var
K-Spec
Validation Data1 Offset1 PVK-Spec2
8 6 Var
h h K-Spec
Validation Data2 Response Content EE3003 Rc
8 Length 3 1
h Attribute h h
6
h
Offset2
D D U D U
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
Mark II Programmers Guide
Chapter 12 Online Banking Module Functions
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
© SafeNet, Inc.
UCHAR
Offset2[6]);
137
Mark II Programmers Guide
Chapter 12 Online Banking Module Functions
OBM SetPassword RSAEncrypted TPV
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
Request Content EE3004 FM
Length 3 1
Attribute h h
Description Function Code Function Modifier = 00
EPB CTPV Response Content EE3004 rc
Struct Struct Length 3 1
PU PU Attribute h h
RSA-encrypted password Block Calculate TPV Description Function Code Return Code
Reference Hash
Var
h
D D U D U
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
© SafeNet, Inc.
EFTBUFFER
*ReferenceTPV);
138
Mark II Programmers Guide
Chapter 12 Online Banking Module Functions
OBM VerifyPassword RSAEncrypted TPV
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
Request Content EE3005 FM
Length 3 1
Attribute h h
Description Function Code Function Modifier = 00
EPB CTPV Reference TPV Response Content EE3005 rc
Struct Struct Var Length 3 1
PU PU h Attribute h h
RSA-encrypted password Block Calculate TPV Transformed Password Value. Description Function Code Return Code
D D U D U
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
Mark II Programmers Guide
Chapter 12 Online Banking Module Functions
OBM ChangePassword RSAEncrypted TPV
PHW SHP PSO/PSG
D D U
SHP Toolkit MK2
D
Card Issuance (SHP Toolkit EMV)
U
Request Content EE3006 FM
Length 3 1
Attribute h h
Description Function Code Function Modifier = 00
EPB CTPV 1 Reference TPV 1 CTPV 2 Response Content EE3006 rc
Struct Struct Var Struct Length 3 1
PU PU h PU Attribute h h
RSA-encrypted password Block Calculate TPV Transformed Password Value Calculate TPV Description Function Code Return Code
Reference TPV 2
Var
h
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
© SafeNet, Inc.
EFTBUFFER
*ReferenceTPV2);
140
Mark II Programmers Guide
Chapter 12 Online Banking Module Functions
OBM PrintPassword
D D U D U
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
Request Content EE3008 FM
Length 3 1
Attribute h h
Password Type
1
h
0 = Numeric
1
h
1 = Alpha-numeric (upper & lower case alpha) 2 = Upper case alpha and numeric 3 = Lower case alpha and numeric In range 04 – 16.
Struct
CTPV Processing Unit
Data Sets
1
h
Repeat count for the following data sets.
Line No
1
h
This set of fields specifies data to be printed at
Column No
1
h
a given line and column.
Var
h
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
Attribute h h
Var
h
Password Length CTPV
Data
Response Content EE3008 rc Reference TPV
Description Function Code Function Modifier = 00
Calculate TPV
Description Function Code Return Code Transformed Password Value.
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
Mark II Programmers Guide
© SafeNet, Inc.
Chapter 12 Online Banking Module Functions
IN IN IN IN IN
UCHAR EFTBUFFER EFTBUFFER KEYSPEC UCHAR
AlgorithmID, *DataA, *DataB, *KTPV, DataSets,
_IN _IN _IN
UCHAR UCHAR EFTBUFFER
*LineNo1, *ColumnNo1, *Data1,
_IN _IN _IN
UCHAR UCHAR EFTBUFFER
*LineNo2, *ColumnNo2, *Data2,
_IN _IN _IN
UCHAR UCHAR EFTBUFFER
*LineNo3, *ColumnNo3, *Data3,
_IN _IN _IN
UCHAR UCHAR EFTBUFFER
*LineNo4, *ColumnNo4, *Data4,
_IN _IN _IN
UCHAR UCHAR EFTBUFFER
*LineNo5, *ColumnNo5, *Data5,
_IN _IN _IN
UCHAR UCHAR EFTBUFFER
*LineNo6, *ColumnNo6, *Data6,
_IN _IN _IN
UCHAR UCHAR EFTBUFFER
*LineNo7, *ColumnNo7, *Data7,
_IN _IN _IN
UCHAR UCHAR EFTBUFFER
*LineNo8, *ColumnNo8, *Data8,
_IN _IN _IN
UCHAR UCHAR EFTBUFFER
*LineNo9, *ColumnNo9, *Data9,
_IN _IN _IN
UCHAR UCHAR EFTBUFFER
*LineNo10, *ColumnNo10, *Data10,
OUT
EFTBUFFER
*ReferenceTPV);
142
Mark II Programmers Guide
Chapter 12 Online Banking Module Functions
OBM MigratePIN OffsetToTPV
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
Request Content EE3009 FM PVK-Spec Validation Data Offset Password Length CTPV Response Content EE3009 rc Reference TPV
Length 3 1
Attribute h h
Var
K-Spec
8
h
6 1 Struct Length 3 1
h h PU Attribute h h
Var
h
D D U D U
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
© SafeNet, Inc.
EFTBUFFER
*ReferenceTPV);
143
Mark II Programmers Guide
Chapter 12 Online Banking Module Functions
OBM GetPrintToken
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
Request Content EE3016 FM
Length 3 1
Attribute h h
Description Function Code Function Modifier = 00
Response Content EE3016 rc
Length 3 1
Attribute h h
Description Function Code Return Code
8
h
Print Token
D D U D U
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)
stores the Print Token in Secure Memory, overwriting any prior Print Tokens
2)
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
Mark II Programmers Guide
Chapter 12 Online Banking Module Functions
OBM GenerateRandomPIN
D D U D U
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
Request Content EE3017 FM
Length 3 1
Attribute h h
1
h
PIN Length CTPV
1 Struct
Print Token
8
h CTPV Processin g Unit h
Var
K-Spec
Length 3 1
Attribute h h
ePPK(OBM Print PIN Block)
Var
h
Encrypted OBM Print PIN Block
Reference TPV
Var
h
Transformed PIN Value
Pin Type
PPK-Spec Response Content EE3017 rc
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
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
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
© SafeNet, Inc.
EFTBUFFER EFTBUFFER
*ePPK_PIN, *ReferenceTPV);
145
Mark II Programmers Guide
Chapter 12 Online Banking Module Functions
OBM PrintEncryptedPIN
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
Request Content EE3018 FM PIN Length PPK-Spec
Length 3 1
Attribute h h
1
h
Var
K-Spec
D D U D U
Description Function Code Function Modifier = 00 In range 04 – 16 Key Specifier for PPK (Formats: 0 - 3)
ePPK(OBM Print PIN Block)
Var
h
Encrypted OBM Print PIN Block
Data Sets
1
h
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.
1
1
h
The line number for the data to be printed at.
1
1
h
The column number for the data to be printed at.
1
Var Length 3 1
h Attribute h h
Line No
Column No
Data Response Content EE3018 rc
The data to be printed. Description Function Code Return Code
1
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
Mark II Programmers Guide
Chapter 12 Online Banking Module Functions
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,
© SafeNet, Inc.
_IN _IN _IN
UCHAR UCHAR EFTBUFFER
*LineNo1, *ColumnNo1, *Data1,
_IN _IN _IN
UCHAR UCHAR EFTBUFFER
*LineNo2, *ColumnNo2, *Data2,
_IN _IN _IN
UCHAR UCHAR EFTBUFFER
*LineNo3, *ColumnNo3, *Data3,
_IN _IN _IN
UCHAR UCHAR EFTBUFFER
*LineNo4, *ColumnNo4, *Data4,
_IN _IN _IN
UCHAR UCHAR EFTBUFFER
*LineNo5, *ColumnNo5, *Data5,
_IN _IN _IN
UCHAR UCHAR EFTBUFFER
*LineNo6, *ColumnNo6, *Data6,
_IN _IN _IN
UCHAR UCHAR EFTBUFFER
*LineNo7, *ColumnNo7, *Data7,
_IN _IN _IN
UCHAR UCHAR EFTBUFFER
*LineNo8, *ColumnNo8, *Data8,
_IN _IN _IN
UCHAR UCHAR EFTBUFFER
*LineNo9, *ColumnNo9, *Data9,
_IN _IN _IN
UCHAR UCHAR EFTBUFFER
*LineNo10, *ColumnNo10, *Data10);
147
Mark II Programmers Guide
Chapter 12 Online Banking Module Functions
OBM Translate PIN – RSA-encrypted, PPK
PHW
D
SHP
D
PSO/PSG
U D
SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
Request Content EE3019 FM
Length 2 1
Attribute h h
EPB
Struct
PU
Var
K-Spec
1
h
6 Length 2 1
h Attribute h h
8
x
PPK-Spec PFo ANB Response Content EE3019 rc ePPKo
U
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
Mark II Programmers Guide
Chapter 12 Online Banking Module Functions
OBM Set PIN – PPK-encrypted, TPV
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
Request Content EE3020 FM ePPK(PIN) PPKi-Spec PFi ANB CTPV Response Content EE3020 rc Reference TPV
Length 2 1
Attribute h h
8 Var
x K-Spec
1
h
6 Struct Length 2 1
h PU Attribute h h
Var
h
D D U D U
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
Mark II Programmers Guide
© SafeNet, Inc.
Chapter 12 Online Banking Module Functions
150
Mark II Programmers Guide
Chapter 13 Visa Functions
Chapter 13 Visa Functions The Visa option specified here is required in a HSM providing support for institutions involved with the Visa network (VisaNet) or which use the Visa method of PIN verification. The specified terms and the facilities used are based on information provided by Visa International (VisaNet, Electronic Value Exchange Standard Manual). These facilities consist of key management and host functions which are in addition to the standard ones. For information regarding related console operations, please refer to the MarkII Console User Guide. Refer to Visa 3DES Support on page 156 for information on how generic functions may be used to provide 3DES Visa functionality.
Summary of Visa Functions Function Name
Function Code
Page
PVV-VER
EE0605
158
PVV- CALC-3624
EE0606
160
PVV-CALC
EE0607
161
DIEBOLD_PIN_VER
EE0614
163
DIEBOLD_PIN_OFF
EE0616
165
PIN-TRANS-SEED-DES
EE0615
167
CVV- GENERATE
EE0802
169
CVV- VERIFY
EE0803
170
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: -
© SafeNet, Inc.
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).
151
Mark II Programmers Guide
-
Chapter 13 Visa Functions
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.
The PVV Method of PIN Verification The Visa PIN Verification Service (PVS) uses a non-secret PIN Verification Value (PVV) to verify a PIN. The PVV is a 4-digit cryptographic transformation of a Transformed Security Parameter (TSP) using 2 keys, PVK-A and PVK-B. The TSP is formed from the account number, the PIN Verification Key Indicator (PVKI) and the PIN, and so is independent of the PIN Generation method. The PVV may be stored either in an on-line database or on the magnetic stripe of the card. The PVKI is stored on the stripe, with a certain value indicating that the PVS should not be used and so the transaction must be routed through to the Issuer. Each Issuer is free to use the PVV method for PIN Verification in on-us transactions, but may alternatively use the verification method, which complements the PIN Generation method. Visa does not specify any standard for PIN Generation.
CVV Card Verification A CVV prevents counterfeit transactions by validating card information. It is a 3 digit cryptographic transformation of the data using two keys, CVK-A and CVK-B. Card verification requires participation by both Issuers and Acquirers. The Issuer must encode the CVV on the card's magnetic stripe, as well as ensuring that the value can be verified during the authorization process. The Acquirer is not actively involved in verifying the CVV but must ensure that all information on a track is transmitted in the authorization request.
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
Mark II Programmers Guide
Chapter 13 Visa Functions
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.
Key Management Operations The Visa key management operations are performed using the HSM console. The following Keys used in the HSM Key Management Operations are defined by Visa for processing of Visa interchange PINs, CVVs, and Keys. - The Zone Control Master Key (ZCMK) - The Acquirer Working Key (AWK) - The Issuer Working Key (IWK) - The pair of PIN Verification Keys (PVK) - The pair of Card Verification Keys (CVK)
ZCMK Component Generation This operation generates and displays a parity-adjusted random ZCMK component, conforming to the Visa requirement that a pair of hexadecimal characters should not appear more than three times in the component.
© SafeNet, Inc.
153
Mark II Programmers Guide
Chapter 13 Visa Functions
Usage of this operation is optional. The user may elect to generate the ZCMK component using a manual process.
ZCMK Calculation and Storage This operation proceeds as follows: 1.
2. 3.
Entry of the three ZCMK components is prompted. Each character of the component is displayed as it is entered, but on completion of the entry of the component, it is cleared from the screen. Following successful entry of the 3 components, the ZCMK is calculated and its KCV is displayed. The user may elect to store the ZCMK (overwriting any previously stored ZCMK).
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.
Working Key Generation This operation generates a parity-adjusted random Working Key and displays the result of encrypting the key by the stored ZCMK, along with the KCV of the generated key. The generated key may be used for any of the Working Keys, IWK, AWK, PVK-A or PVK-B, CVKA or CVK-B. The value of the displayed encrypted key and KCV may be recorded and mailed to Visa. Usage of this operation is optional. The user may elect to generate each Working Key using a manual process in association with the key encryption operation as described below.
Working Key Encryption This operation allows entry of a clear Working Key, and displays the result of encrypting the entered key by the stored ZCMK. It also displays the KCV of the entered key. The clear key is entered in two parts of eight hexadecimal digits, allowing dual custody of the clear key. The alternative procedure as described in the Working Key Generation section above is recommended, as no individual need know even part of the clear key.
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
Mark II Programmers Guide
Chapter 13 Visa Functions
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.
PVK Pair Storage The HSM provides storage for 99 PVK pairs. It is the responsibility of the Issuer to ensure compliance with the Visa stipulation that no more than two pairs should be in concurrent use for each card base. Storing a PVK pair involves the input of a: - PVK index - PVK-A encrypted by the ZCMK - PVK-B encrypted by the ZCMK The KCV of each key is displayed.
CVK Pair Storage The HSM provides storage for 99 CVK pairs. Storing a CVK pair involves the input of a: - CVK index - CVK-A encrypted by the ZCMK - CVK-B encrypted by the ZCMK - CVK entry as either: - Double Length - Key Pair A/B The KCV of each key is displayed.
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 '------'.
Visa Function Overview The functions support: - PVV Generation. - PIN Verification using the PVV method. - PIN Translation (i.e. PIN Block re-encryption). - CVV Generation - CVV Verification PIN Translation is required as the HSM supports PIN Blocks encrypted by (short-term) session keys known as PIN Protect Keys (PPK). The following re-encryptions are supported:
© SafeNet, Inc.
155
Mark II Programmers Guide
Chapter 13 Visa Functions
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.
Visa Function Return Code The following Return Code is specific to Visa functionality. Return Code 0F
Meaning Invalid Visa PIN Verification Key Indicator (PVKI).
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.
Visa 3DES Support Generic HSM keys and associated console operations and host functions can be used to support doublelength keys on VisaNet. The tables below give the generic keys, console operations and host functions to be used when 3DES functionality is required in place of the Visa specific equivalents that apply when DES is used. The following 3DES functionality is not currently supported: •
Triple-length keys
•
3624 Offset PIN verification using a 3DES PVK
•
Export/import of PVKs using a 3DES key
Equivalent keys Key Type Key encrypting key
Visa key ZCMK
HSM key KIS / KIR
PIN encrypting key
AWK / IWK
PPK
PIN verification key (PVV method)
PVK-A / PVK-B
Card validation key (CVV method)
CVK-A / CVK-B
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
© SafeNet, Inc.
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
156
Mark II Programmers Guide
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.
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.
157
Mark II Programmers Guide
Chapter 13 Visa Functions
PVV-VER
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
Request Content EE0605 FM
Length 3 1
Attribute h h
ePPK(PIN) PPK-Spec
8 Var
x K-Spec
PF ANB PVVK-Spec
1 6 Var
h h K-Spec
6 2 Length 3 1
h x Attribute h h
TSP12 PVV Response Content EE0605 rc
D D D D D
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.
PF
specifies the format of the input PIN Block format.
ANB
Account Number Block, which are the 12 right most digits of the Primary Account Number (PAN), excluding the check digit.
PVVK-Spec
A specifier to a HSM-stored or host-stored PVVK (PVK-A and PVK-B)
TSP12
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 •
© SafeNet, Inc.
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)
158
Mark II Programmers Guide
Chapter 13 Visa Functions
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
Mark II Programmers Guide
Chapter 13 Visa Functions
PVV- CALC-3624
D D D D D
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
Request Content EE0606 FM
Length 3 1
Attribute h h
PVK-Spec
Var
K-Spec
Validation Data Offset4 PVVK-Spec
8 2 Var
h d K-Spec
TSP12 Response Content EE0606 rc
6 Length 3 1
h Attribute h h
2
x
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 PIN’s IBM Offset data. The four leftmost digits of the derived or random PIN are appended to the TSP12 to form the TSP. PVK-Spec
A specifier to the HSM stored PVK
Validation Data
Data which is usually part of the PAN and used in the calculation of the reference PIN.
Offset4
Leftmost 4 digits of the PIN offset. If an offset is not used, the digits must contain zeros.
PVVK-Spec
A specifier to a HSM-stored or host-stored PVVK (PVK-A and PVK-B)
TSP12
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
© SafeNet, Inc.
UCHAR
PVV[2]);
160
Mark II Programmers Guide
Chapter 13 Visa Functions
PVV-CALC
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
Request Content EE0607 FM ePPK(PIN) PPK-Spec PF ANB PVVK-Spec TSP12 Response Content EE0607 rc PVV
Length 3 1
Attribute h h
8 Var
x K-Spec
1
h
6 Var
d K-Spec
6 Length 3 1
h Attribute h h
2
x
D D D D D
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.
ANB
Account Number Block, which are the 12 right most digits of the Primary Account Number (PAN), excluding the check digit.
PVVK-Spec
A specifier to a HSM-stored or host-stored PVVK (PVK-A and PVK-B).
TSP12
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
Mark II Programmers Guide
Chapter 13 Visa Functions
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
© SafeNet, Inc.
UCHAR PVV[2]);
162
Mark II Programmers Guide
Chapter 13 Visa Functions
Diebold Table Support DIEBOLD_PIN_VER
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
Request Content EE0614 FM
Length 1 1
Attribute h h
1
h
ePPK(PIN) PPK-Spec
8 Var
B64 K-Spec
ANB ValidationData Offset AlgID PVK-Spec
6 Var 2 1 Var
h h d h K-Spec
Response Content EE0614 rc
Length 1 1
Attribute h h
PF
U U D D U
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).
© SafeNet, Inc.
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.
ePPK(PIN)
The formatted PIN Block encrypted under the PPK. Pin must have length 4.
PPK-spec
Key specifier for the PPK
ANB
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.
163
Mark II Programmers Guide
Chapter 13 Visa Functions
ValidationData
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
Offset
Four BCD digits that are modulo 10 added to the derived pin to create the actual pin.
AlgID
A number from 0 to 255 that is an input into the pin verification algorithm.
PVK-spec
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.
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
Mark II Programmers Guide
Chapter 13 Visa Functions
DIEBOLD_PIN_OFF
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
Request Content EE0616 FM
Length 1 1
Attribute h h
1
h
ePPK(PIN) PPK-Spec
8 Var
B64 K-Spec
ANB ValidationData AlgID PVK-Spec
6 Var 1 Var
h h h K-Spec
Response Content EE0616 Rc Offset
Length 1 1 2
Attribute h h d
PF
U U D D U
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).
© SafeNet, Inc.
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.
ePPK(PIN)
The formatted PIN Block encrypted under the PPK. Pin must have length 4.
PPK-spec
Key specifier for the PPK
ANB
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.
ValidationData
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
165
Mark II Programmers Guide
Chapter 13 Visa Functions
AlgID
A number from 0 to 255 that is an input into the pin verification algorithm.
PVK-spec
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.
Offset
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
© SafeNet, Inc.
PINOffsetTable[2]);
166
Mark II Programmers Guide
Chapter 13 Visa Functions
SEED Translation PIN-TRANS-SEED-DES
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
Request Content EE0615 FM
Length 3 1
Attribute h h
Var Var
x K-Spec
1
h
ANB PFo
Var 1
h h
PPKo-Spec
Var
K-Spec
Length 3 1
Attribute h h
Var
h
ePPKi(PIN) PPKi-Spec PFi
Response Content EE0615 rc ePPKo(PIN)
D D U D D
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
= 00. Must be set to zero.
PFi and PFo
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.
ANB PPKi
PPKo ePPKi(PIN)
© SafeNet, Inc.
PIN Block encrypted using the SEED algorithm by PPKi. This Var field must be 16 bytes in length.
167
Mark II Programmers Guide
Chapter 13 Visa Functions
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
© SafeNet, Inc.
EFTBUFFER
*ePPKo_PIN);
168
Mark II Programmers Guide
Chapter 13 Visa Functions
CVV- GENERATE
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
Request Content EE0802 FM CVK-Spec CVV-Data Response Content EE0802 rc CVV
Length 3 1
Attribute h h
Var
K-Spec
16 Length 3 1
h Attribute h h
2
h
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
= 00. Must be set to zero.
CVK-Spec
A key specifier which incorporates an index to a HSM-stored double length or key pair CVV or a host-stored double-length CVV.
CVV-Data
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".
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
© SafeNet, Inc.
UCHAR
CVV[2]
);
169
Mark II Programmers Guide
Chapter 13 Visa Functions
CVV- VERIFY
D D D D D
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
Request Content EE0803 FM CVK-Spec CVV-Data CVV Response Content EE0803 rc
Length 3 1
Attribute h h
Var
K-Spec
16 2 Length 3 1
h h Attribute h h
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
= 00. Must be set to zero.
CVK-Spec
A key specifier which incorporates an index to a HSM-stored double length or key pair CVV or a host-stored double-length CVV.
CVV-Data
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".
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
Mark II Programmers Guide
Chapter 14 MAC Management Functions
Chapter 14 MAC Management Functions Summary of MAC Management Functions
© SafeNet, Inc.
Function Name
Function Code
Page
MAC_GEN_UPDATE
EE0700
172
MAC_GEN_FINAL
EE0701
174
MAC_VER_FINAL
EE0702
176
KTM-MAC-GEN
73
178
171
Mark II Programmers Guide
Chapter 14 MAC Management Functions
MAC Generation MAC_GEN_UPDATE
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
Request Content EE0700 FM Alg
Length 3 1
Attribute h h
1
h
D D D D D
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
ICD MPK-Spec
Data Response Content EE0700 rc OCD
8 Var
h K-Spec
Var Length 3 1
h Attribute h h
8
h
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
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.
© SafeNet, Inc.
FM
= 00. Must be set to zero.
Alg
Specifies the MACing algorithm to use.
172
Mark II Programmers Guide
Chapter 14 MAC Management Functions
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
Input Chaining Data, used for long message feedback.
MPK-Spec
A key specifier incorporating an encrypted MAC Protect Key.
OCD
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
© SafeNet, Inc.
UCHAR
ocd[8]);
173
Mark II Programmers Guide
Chapter 14 MAC Management Functions
MAC_GEN_FINAL
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
Request Content EE0701 FM Alg
Length 3 1
Attribute h h
1
h
D D D D D
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
MAClength
1
h
ICD MPK-Spec
8 Var
h K-Spec
Var Length 3 1
h Attribute h h
Var
h
Data Response Content EE0701 rc MAC
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
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
Mark II Programmers Guide
Chapter 14 MAC Management Functions
FM
= 00. Must be set to zero.
Alg
Specifies the MACing algorithm to use. Left nibble: = 0: = 1:
pad with zeroes. 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
eg. Pad with zeroes and double-length MPK using triple-DES CBC method 0x01 MAClength
Specifies the length of the output MAC
ICD
Input Chaining Data, used for long message feedback.
MPK-Spec
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
© SafeNet, Inc.
EFTBUFFER
*mac);
175
Mark II Programmers Guide
Chapter 14 MAC Management Functions
MAC_VER_FINAL
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
Request Content EE0702 FM Alg
Length 3 1
Attribute h h
1
h
D D D D D
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
ICD MPK-Spec
MAC Data Response Content EE0702 rc
8 Var
h K-Spec
Var Var Length 3 1
h h Attribute h h
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
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
Mark II Programmers Guide
Chapter 14 MAC Management Functions
FM
= 00. Must be set to zero.
Alg
Specifies the MACing algorithm to use. Left nibble: = 0: pad with zeroes. = 1: pad with a single one bit and subsequent zeroes
ICD
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.
MPK-Spec
A key specifier incorporating an encrypted MAC Protect Key.
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
Mark II Programmers Guide
Chapter 14 MAC Management Functions
Terminal Master Key MAC Generation KTM-MAC-GEN
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
Request Content 73
Length 1
Attribute h
Description Function Code
Blocks n Data Response Content 73 rc
1 1 bks*8 Length 1 1
h d h Attribute h h
No. of 8 byte Blocks KTM-Index Must be multiple of 8 bytes Description Function Code Return Code
4
h
MAC
D D U U U
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
Mark II Programmers Guide
Chapter 15 Data Ciphering Functions
Chapter 15 Data Ciphering Functions Summary of Data Ciphering Functions
© SafeNet, Inc.
Function Name
Function Code
Page
ENCIPHER_2
EE0800
180
DECIPHER_2
EE0801
182
ENCIPHER_3
EE0804
184
DECIPHER_3
EE0805
186
ENCIPHER-KTM1
EE0806
188
B-ENCIPHER-ECB
84
190
B-DECIPHER-ECB
85
191
179
Mark II Programmers Guide
Chapter 15 Data Ciphering Functions
ENCIPHER_2
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
Request Content EE0800 FM DPK-Spec CM
ICV Data Response Content EE0800 rc OCV eDPK(Data)
Length 3 1
Attribute h h
Var
K-Spec
1
h
8 Var Length 3 1
h h Attribute h h
8 Var
h h
D D D D D
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
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.
© SafeNet, Inc.
DPK-Spec
Key specifier incorporating a single or double length host-stored or HSM-stored DPK.
CM
Specifies the mode of operation for the encipherment: 0 Electronic Code Book (ECB) 1 Cipher Block Chaining (CBC)
ICV
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.
OCV
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.
Data
Plaintext data to be enciphered. Must be a multiple of 8 bytes long.
180
Mark II Programmers Guide
Chapter 15 Data Ciphering Functions
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
© SafeNet, Inc.
UCHAR EFTBUFFER
( FM, *DPK, CipherMode, ICV[8], *clear_data, OCV[8], *enc_data ) ;
181
Mark II Programmers Guide
Chapter 15 Data Ciphering Functions
DECIPHER_2
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
Request Content EE0801 FM DPK-Spec CM
ICV eDPK(Data) Response Content EE0801 rc OCV Data
Length 3 1
Attribute h h
Var
K-Spec
1
h
8 Var Length 3 1
h h Attribute h h
8 Var
h h
D D D D D
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
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.
CM
Specifies the mode of operation for the decipherment: 0 Electronic Code Book (ECB) 1 Cipher Block Chaining (CBC)
ICV
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.
© SafeNet, Inc.
eDPK(Data)
Cipher text to be deciphered. Must be a multiple of 8 bytes long.
OCV
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.
182
Mark II Programmers Guide
Data
Chapter 15 Data Ciphering Functions
Deciphered plaintext 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
© SafeNet, Inc.
UCHAR EFTBUFFER
( FM, *DPK, CipherMode, ICV[8], *enc_data, OCV[8], *clear_data);
183
Mark II Programmers Guide
Chapter 15 Data Ciphering Functions
ENCIPHER_3
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
Request Content EE0804 FM DPK-Spec CM
ICV Data Response Content EE0804 rc OCV eDPK(Data)
Length 3 1
Attribute h h
Var
K-Spec
1
h
Var Var Length 3 1
h h Attribute h h
Var Var
h h
D D U D D
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
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
= 00. Must be set to zero.
DPK-Spec
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
Mark II Programmers Guide
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
© SafeNet, Inc.
EFTBUFFER EFTBUFFER
*OCV, *enc_data );
185
Mark II Programmers Guide
Chapter 15 Data Ciphering Functions
DECIPHER_3
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
Request Content EE0805 FM DPK-Spec CM
ICV eDPK(Data) Response Content EE0805 rc OCV Data
Length 3 1
Attribute h h
Var
K-Spec
1
h
Var Var Length 3 1
h h Attribute h h
Var Var
h h
D D U D D
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
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
= 00. Must be set to zero.
DPK-Spec
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
Mark II Programmers Guide
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
© SafeNet, Inc.
EFTBUFFER EFTBUFFER
*OCV, *clear_data);
187
Mark II Programmers Guide
Chapter 15 Data Ciphering Functions
ENCIPHER-KTM1
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
Request Content
EE0806 FM DPK-Spec CM
ICV KTM-Spec Response Content
EE0806 rc OCV eDPK(KTM)
Length 3
Attribute h
1
h
Var
K-Spec
1
h
Var Var
h K-Spec
Length
Attribute
3 1
h h
Function Code Return Code
Var Var
h h
Output Chaining Value Ciphertext
D D U D D
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 Key specifier for KTM (Formats: 0 - 3, 10, 11, 13, 16) Description
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
CM
ICV
KTM-Spec
OCV
© SafeNet, Inc.
= 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.
188
Mark II Programmers Guide
eDPK(KTM)
Chapter 15 Data Ciphering Functions KTM key encrypted with DPK according to the algorithm specified.
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
© SafeNet, Inc.
EFTBUFFER EFTBUFFER
*OCV, *eDPK_KTM);
189
Mark II Programmers Guide
Chapter 15 Data Ciphering Functions
3624 B-Key Enciphering B-ENCIPHER-ECB
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
Request Content 84
Length 1
Attribute h
Description Function Code
Blocks TKSI Data Response Content 84 rc
1 1 bks*8 Length 1 1
h d h Attribute h h
No. of 8 byte Blocks Terminal Key Set Index Must be multiple of 8 bytes Description Function Code Return Code
eBK(Data)
bks*8
B64
D D U U U
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
Mark II Programmers Guide
Chapter 15 Data Ciphering Functions
3624 B-Key Deciphering B-DECIPHER-ECB
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
Request Content 85
Length 1
Attribute h
Description Function Code
Blocks TKSI eBK(Data) Response Content 85 rc
1 1 bks*8 Length 1 1
h d B64 Attribute h h
No. of 8 byte Blocks Terminal Key Set Index Must be multiple of 8 bytes Description Function Code Return Code
Data
bks*8
h
D D U U U
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
Mark II Programmers Guide
© SafeNet, Inc.
Chapter 15 Data Ciphering Functions
192
Mark II Programmers Guide
Chapter 16 MasterCard Functions
Chapter 16 MasterCard Functions The MasterCard support option provides the additional facilities required in the HSM to provide support for an institution connecting to the MasterCard International network. These facilities consist of console operations and host functions that are in addition to the standard ones. Refer to MasterCard 3DES Support on page 194 for information on how generic functions may be used to provide 3DES MasterCard functionality.
Summary of MasterCard Functions Function Name
Function Code
Page
MT-KPE-GEN
A0
196
MT-KPE-RCV
A1
197
MT-PIN-TRAN
A2
198
MT-PIN-VER
A3
199
MT_PIN_VER_PVV
A7
200
MasterCard Security Requirements It is required that a PIN is never available in a clear form, starting from the entry at the Automatic Teller Machine to the point where the card issuer decryption occurs. To this end, a unique PIN Encryption Key (KPE) is shared between the MasterCard Switch Center (MCS) and each acquirer institution. An acquirer institution routing a transaction to the MCS must pass the PIN encrypted by the shared KPE. Similarly, a unique KPE is shared between the MCS and each member issuer. MCS routing a transaction to an issuer institution will pass the PIN encrypted by the shared KPE. The two available key management methods are: 1.
2.
Manual Key Management With this method the PIN Encryption Key is securely input and stored at the MCS and at the acquirer / issuer. On-line Key Exchange With this method a Key Exchange Key (KEK) is securely input and stored at the MasterCard Switch center (MCS) and at the acquirer / issuer institution. Subsequently, during normal operations, a new PIN Encryption Key encrypted by the KEK is transmitted at frequent intervals from the MCS to the acquirer / issuer institution.
Facilities for MasterCard Support The HSM facilities support both manual key management and online key exchange, and consist of a set of console operations for the key management, and a set of host functions for the transaction processing.
© SafeNet, Inc.
193
Mark II Programmers Guide
Chapter 16 MasterCard Functions
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.
MasterCard 3DES Support Generic HSM keys and associated console operations and host functions can be used to support doublelength keys on the MasterCard International network. The tables below give the generic keys, console operations and host functions to be used when 3DES functionality is required in place of the MasterCard specific equivalents that apply when DES is used. The following 3DES functionality is not currently supported: •
Triple-length keys
•
3624 Offset PIN verification using a 3DES PVK
•
Export/import of PVKs using a 3DES key
Equivalent keys Key Type Key encrypting key
Visa key KEK
HSM key KIS / KIR
PIN encrypting key
KPE
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
© SafeNet, Inc.
Replacement functions II-Key-Gen
194
Mark II Programmers Guide
MT-KPE-RCV MT-PIN-VER MT-PIN-TRAN
© SafeNet, Inc.
Chapter 16 MasterCard Functions
II-Key-Rcv PIN Verify PIN Translate
195
Mark II Programmers Guide
Chapter 16 MasterCard Functions
MT-KPE-GEN
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
Request Content A0
Length 1
Attribute h
Description Function Code
MT-Index Response Content A0 rc
1 Length 1 1
d Attribute h h
Index of KEK Description Function Code Return Code
8 8 2
B64 B64 h
eKEKn(KPE) eKMv1(KPE) KCV
D D U D U
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
This field has the range of 1 to 2 and indexes a KEK. The KEK is used to encrypt the KPE.
eKEKn(KPE)
The random PIN Encryption Key is returned encrypted under the Key Exchange Key indicated by the specified index.
eKMv1(KPE)
The random PIN Encryption Key is returned encrypted under variant 1 of the Domain Master Key for storage within the host.
KCV
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
© SafeNet, Inc.
UCHAR eKEKn_KPE[8], UCHAR eKMv1_KPE[8], UCHAR KCV[2]);
196
Mark II Programmers Guide
Chapter 16 MasterCard Functions
MT-KPE-RCV
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
Request Content A1
Length 1
Attribute h
Description Function Code
MT-Index eKEKn(KPE) Response Content A1 rc
1 8 Length 1 1
d B64 Attribute h h
Index of KEK PIN Encryption Key Description Function Code Return Code
8 2
B64 h
PIN Encryption Key Key Check Value
eKMv1(KPE) KCV
D D U D U
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
This field has the range of 1 to 2 and indexes a KEK. The KEK is used to encrypt the KPE.
eKEKn(KPE)
The PIN Encryption Key is received encrypted under the Key Exchange Key indicated by the supplied index.
eKMv1(KPE)
The PIN Encryption Key is returned encrypted under variant 1 of the Domain Master Key for storage within the host.
KCV
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
© SafeNet, Inc.
UCHAR eKMv1_KPE[8], UCHAR KCV[2]);
197
Mark II Programmers Guide
Chapter 16 MasterCard Functions
MT-PIN-TRAN
D D U D U
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
Request Content A2
Length 1
Attribute h
Description Function Code
PF ePPK(PIN) eKMv1(PPK) MT-Index ANB Response Content A2 rc
1 8 8 1 6 Length 1 1
h B64 B64 d h Attribute h h
PIN Format PIN encrypted under PPK PIN Protect Key Index of KEK Account Number Block Description Function Code Return Code
8
B64
eKPE(AS-PIN)
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)
ePPK(PIN)
The PIN encrypted by a host stored PIN Protect Key.
eKMv1(PPK)
The PIN Protect Key encrypted by a variant 1 of the Domain Master Key.
MT-Index
This field has the range of 1 to 2 and indexes a KPE. The KPE is used to reencrypt the PIN Block.
ANB
The 12-digit Account Number Block used in the formation of the clear AS/ANSI PIN Block.
eKPE(AS-PIN)
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
© SafeNet, Inc.
UCHAR eKPE_AS_PIN[8]);
198
Mark II Programmers Guide
Chapter 16 MasterCard Functions
MT-PIN-VER
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
Request Content A3
Length 1
Attribute h
Description Function Code
PVK-Index eKPE(AS-PIN) MT-Index PAN ANB Offset Response Content A3 rc
1 8 1 8 6 6 Length 1 1
d B64 d h h h Attribute h h
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
D D U D U
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.
eKPE(AS-PIN)
The AS/ANSI formatted PIN Block containing the PIN to be verified is supplied encrypted by an HSM stored PIN Encryption Key.
MT-Index
This field has the range of 1 to 2 and indexes a KPE.
PAN
The Primary Account Number (or other card data) used in the verification procedure.
ANB
The 12-digit Account Number Block used in the formation of the clear AS/ANSI PIN Block.
Offset
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
Mark II Programmers Guide
Chapter 16 MasterCard Functions
MT_PIN_VER_PVV
D D U D U
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
Request Content A7
Length 1
Attribute h
Description Function Code
PVVK-Index eKPE(AS-PIN) MT-Index ANB TSP12 PVV Response Content A7 rc
1 8 1 6 6 2 Length 1 1
d B64 d h h h Attribute h h
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
Identifies the PVK-A/B pair that is to be used in the derivation of the PVV and must be in BCD format.
eKPE(AS-PIN)
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.
MT-Index
This field has the range of 1 to 2 and indexes a KPE.
ANB
The 12-digit Account Number Block used in the formation of the clear AS/ANSI PIN Block.
TSP12
The leftmost 12 digits of the TSP and consists of 11 PAN digits followed by the appropriate one digit PVKI.
PVV
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
Mark II Programmers Guide
Chapter 17 American Express Functions
Chapter 17 American Express Functions This section defines the HSM functionality for generating Card Security Codes as defined by American Express. Note: Refer to Appendix F American Express Account Blocks, for further details on how an American Express Account Block is formed. Also, a series of function examples are given in Appendix G American Express Examples. These can be used to verify correct implementation of the functionality.
Summary of American Express Functions Function Name
Function Code
Page
CALC_CSCK
A8
203
CREATE_CSCK
A9
204
EXPORT_CSCK
AA
205
IMPORT_CSCK
AB
206
Card Security Code Keys (CSCK) The HSM supports a table of 20 CSC double-length DES keys that are used for the generation of CSC values. CSCKs can be stored in HSM secure memory via console operations. Additionally, host functions provide support for the use and storage of CSCKs from a host database.
Distribution of CSC keys in encrypted form The CSC keys are distributed between American Express and the Card Issuer in an encrypted form. These keys are encrypted by a double-length key-encrypting key which is denoted the Zone Master Key (ZMK) in some documents. In the Mark II HSM, the key-encrypting keys which are used to encrypt other keys for distribution between institutions are denoted as Interchange Keys. Uni-directional key management is supported, therefore separate Interchange Sending Keys (KIS) and Interchange Receiving Keys (KIR) are provided. An HSM KIS or KIR is functionally equivalent to a ZMK, with the additional restriction of being used for key distribution in one direction only. For example to send an encrypted key to another institution a KIS is used, e.g. eKIS(CSCK). At the receiving institution an encrypted key is received encrypted by a KIR, e.g. eKIR(CSCK). The Interchange Key functionality supports single and double length keys, with a maximum number of keys set to 99 sending and 99 receiving keys. For mailing or electronic transmission of a CSC key, a double-length KIS is used i.e. eKIS(CSCK). At the receiving institution a double-length KIR would be used, i.e. eKIR(CSCK).
Use of KIS and KIR for distribution of CSCKs
© SafeNet, Inc.
201
Mark II Programmers Guide
Chapter 17 American Express Functions
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
Mark II Programmers Guide
Chapter 17 American Express Functions
CALC_CSCK
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
Request content A8 CSCK-Spec CardData Response content A8 rc CSC
Length 1
Attribute
Var
K-Spec
8 Length 1 1
h Attribute h h
6
h
D D U D D
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
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
© SafeNet, Inc.
UCHAR
CSC[6] );
203
Mark II Programmers Guide
Chapter 17 American Express Functions
CREATE_CSCK
D D U D D
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
Request content A9
Length 1
Attribute h
CSCK-Storage Indicator
1
h
Length 1 1
Attribute h h
Var
K-Spec
3
h
Response content A9 rc CSCK-Spec KVC
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
This function causes a random CSCK to be generated and returned to the host encrypted under the HSM’s 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
© SafeNet, Inc.
KEYSPEC UCHAR
*CSCK, KVC[3]);
204
Mark II Programmers Guide
Chapter 17 American Express Functions
EXPORT_CSCK
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
Request content AA
Length 1
Attribute h
CSCK-Spec
Var
K-Spec
KIS-Spec
Var
K-Spec
Length 1 1
Attribute h h
16 3
h h
Response content AA rc eKIS(CSCK) KVC
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
© SafeNet, Inc.
eKIS_CSCK[16], KVC[3]);
205
Mark II Programmers Guide
Chapter 17 American Express Functions
IMPORT_CSCK
D D U D D
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
Request content AB
Length 1
Attribute h
CSCK-Storage Indicator
1
h
Var
K-Spec
16 Length 1 1
Attribute h h
Var
K-Spec
3
h
KIR-Spec eKIR(CSCK) Response content AB rc CSCK-Spec KVC
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
This function causes a key to be returned encrypted under the HSM’s 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
© SafeNet, Inc.
KEYSPEC UCHAR
*CSCK, KVC[3]);
206
Mark II Programmers Guide
Chapter 18 PIN Issuance Functions
Chapter 18 PIN Issuance Functions Summary of PIN Issuance Functions Function Name
Function Code
Page
PIN-MAIL
E2
209
PIN-GENERATE
EE0E04
212
PIN-PRINT
EE0E05
213
PIN Issuance Overview The HSM’s PIN issuance capabilities allow secure PIN generation and PIN mailer printing without the risk of exposing the Pin Verification Key, as may happen when PIN mailing is processed by a host system. In addition to the host functions covered in this chapter, console operations are provided. The console operations allow access control, envelope design, printer configuration, the printing of alignment test envelopes and the enabling of a PIN mail run. Refer to the Mark II Console User Guide for more detail. An ASCII printer with a serial asynchronous interface is required for printing PIN mailers. Refer to the Communications Guide for more detail on the interface between the PIN mailer printer and the HSM. The PIN-MAIL host function included in this chapter, generates PINs and prints them on PIN mailer envelopes in one operation. PIN generation and printing can also be treated separately (see below). The PIN-MAIL host function allows derived PINs or random PINs to be printed. If random PIN generation is selected, an offset value is returned in the HSM response. The HSM response is delayed until all PIN mail data is transmitted to the printer. The host request may also include any number of data fields which may be printed anywhere on the envelope with the restriction that overprinting is not allowed. Other host functions can still be processed while PIN mailing is enabled.
Separating PIN Generation and Printing Using the functions Generate random PIN and Print PIN the generation and printing of PINs can be separated during the PIN Issuance process. This permits a PIN to be printed at some point in time after its generation, perhaps at a different location. •
The Generate random PIN function generates a random PIN and encrypts it for host storage, transmission and other subsequent use.
•
The Print PIN function prints a PIN supplied in an encrypted form.
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
Mark II Programmers Guide
Chapter 18 PIN Issuance Functions
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).
Host Function Example An example of a host request (using the SafeNet Asynchronous Protocol in ASCII mode) for the PIN Mailer function, with two optional sets of data fields is : 3CE209123456789012345604010101034141410B0104424242420C3E A description of the fields is listed below: Field Name Field Value 3C Start of Message E2 Function Code 09 PK-Index 1234567890123456 PAN 04 number of PIN digits 01 PINTYP 01 line No of 1st data field 01 column No of 1st data field 03 length of 1st data field 414141 contents of 1st data field 0B line No of 2nd data field 01 column No of 2nd data field 04 length of 2nd data field 42424242 contents of 2nd data field 0C BCC 3E End of Message
© SafeNet, Inc.
208
Mark II Programmers Guide
Chapter 18 PIN Issuance Functions
PIN-MAIL
D D U D D
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
Request Content E2
Length 1
Attribute h
Description Function Code
PVK-Index PAN PIN Len PIN Type Line No* Column No* Data Len* Data* Response Content E2 rc
1 8 1 1 1 1 1 Length 1 1
d h h h h h h h Attribute h h
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
6
h
Offset
DATALEN
PIN offset Data
* = optional set of fields. 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.
PAN
This is the Primary Account Number used in the generation of the PIN. It must be padded appropriately prior to input to this function.
PIN Len
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.
PIN Type
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.
© SafeNet, Inc.
Line No
This is the number of the line on which Data is to be printed. It must be in the range 1 to 40.
Column No
This is the number of the column from which Data is to be printed. It must be in the range 1 to 120.
209
Mark II Programmers Guide
Chapter 18 PIN Issuance Functions
Data Len
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.
Data
This field contains the data to be printed.
Offset
This field consists of 12 digits of offset data. The significant digits are leftjustified in the field.
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.
SHP Toolkit MK2 int EFT_E2_PinMailer( IN UCHAR IN UCHAR IN UCHAR IN UCHAR IN UCHAR
© SafeNet, Inc.
*ESMID, PVKIndex, PAN[8], PinLen, PinType,
_IN _IN _IN
UCHAR UCHAR EFTBUFFER
*LineNo1, *ColumnNo1, *Data1,
_IN _IN _IN
UCHAR UCHAR EFTBUFFER
*LineNo2, *ColumnNo2, *Data2,
_IN _IN _IN
UCHAR UCHAR EFTBUFFER
*LineNo3, *ColumnNo3, *Data3,
_IN _IN _IN
UCHAR UCHAR EFTBUFFER
*LineNo4, *ColumnNo4, *Data4,
_IN _IN _IN
UCHAR UCHAR EFTBUFFER
*LineNo5, *ColumnNo5, *Data5,
_IN _IN _IN
UCHAR UCHAR EFTBUFFER
*LineNo6, *ColumnNo6, *Data6,
_IN _IN _IN
UCHAR UCHAR EFTBUFFER
*LineNo7, *ColumnNo7, *Data7,
_IN _IN _IN
UCHAR UCHAR EFTBUFFER
*LineNo8, *ColumnNo8, *Data8,
_IN _IN _IN
UCHAR UCHAR EFTBUFFER
*LineNo9, *ColumnNo9, *Data9,
210
Mark II Programmers Guide
© SafeNet, Inc.
Chapter 18 PIN Issuance Functions
_IN _IN _IN
UCHAR UCHAR EFTBUFFER
*LineNo10, *ColumnNo10, *Data10,
_OUT
UCHAR
offset [6] );
211
Mark II Programmers Guide
Chapter 18 PIN Issuance Functions
PIN-GENERATE
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
Request Content EE0E04 FM PIN Len PFo ANB PPK-Spec Response Content EE0E04 rc ePPK(PIN)
Length 3 1
Attribute h h
1 1
h h
6 Var
h K-Spec
Length 3 1
Attribute h h
8
h
D D U D D
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
© SafeNet, Inc.
UCHAR
ePPK_PIN[8]);
212
Mark II Programmers Guide
Chapter 18 PIN Issuance Functions
PIN-PRINT
D D U D D
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
Request Content EE0E05 FM
Length 3 1
Attribute h h
8 Var
h K-Spec
PFi
1
h
ANB PAN
6 8
h h
1 1 1 Var
h h h h
Length 1 1
Attribute h h
ePPK(PIN) PPK-Spec
Data Sets Line No Column No Data
Response Content EE0E05 rc
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
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
Mark II Programmers Guide
Chapter 18 PIN Issuance Functions
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],
© SafeNet, Inc.
IN
UCHAR
DataSets,
_IN _IN _IN
UCHAR UCHAR EFTBUFFER
*LineNo1, *ColumnNo1, *Data1,
_IN _IN _IN
UCHAR UCHAR EFTBUFFER
*LineNo2, *ColumnNo2, *Data2,
_IN _IN _IN
UCHAR UCHAR EFTBUFFER
*LineNo3, *ColumnNo3, *Data3,
_IN _IN _IN
UCHAR UCHAR EFTBUFFER
*LineNo4, *ColumnNo4, *Data4,
_IN _IN _IN
UCHAR UCHAR EFTBUFFER
*LineNo5, *ColumnNo5, *Data5,
_IN _IN _IN
UCHAR UCHAR EFTBUFFER
*LineNo6, *ColumnNo6, *Data6,
_IN _IN _IN
UCHAR UCHAR EFTBUFFER
*LineNo7, *ColumnNo7, *Data7,
_IN _IN _IN
UCHAR UCHAR EFTBUFFER
*LineNo8, *ColumnNo8, *Data8,
_IN _IN _IN
UCHAR UCHAR EFTBUFFER
*LineNo9, *ColumnNo9, *Data9,
_IN _IN _IN
UCHAR UCHAR EFTBUFFER
*LineNo10, *ColumnNo10, *Data10);
214
Mark II Programmers Guide
Chapter 19 EMV Functions
Chapter 19 EMV Functions The functions define functionality that supports the cryptographic processing defined for EMV ICC payment systems transactions. Note: Appendix E EMV Function Examples documents a series of function examples that can be used to verify correct implementation of EMV functionality.
Summary of EMV functions
© SafeNet, Inc.
Function Name
Function Code
Page
GEN_RANDOM
EE0002
216
EMV_AC_GEN
EE2000
217
EMV_AC_VERIFY
EE2001
218
EMV_DAC_GEN
EE2002
221
EMV_DAC_VERIFY
EE2003
222
EMV_ICC_DN_GEN
EE2004
223
EMV_ICC_DN_VERIFY
EE2005
224
EMV_ARPC_GEN
EE2006
225
EMV_SCRIPT_CRYPTO
EE2007
226
EMV_VERIFY_AC_EMV2000
EF2010
228
EMV_SCRIPT_CRYPTO_VISA
EF2011
238
EMV_GENERATE_ARPC
EF2012
233
EMV_SCRIPT_CRYPTO_EMV2000
EF2013
235
EMV_SCRIPT_CRYPTO_VISA
EF2014
238
EMV_PIN_CHANGE_UNBLOCK_VISA
EF2015
240
EMV_PIN_CHANGE_UNBLOCK
EE2016
243
EMV_PIN_CHANGE_UNBLOCK_EMV_2000
EE2017
245
EMV_VERIFY_AC_GEN_ARPC EMV_AC_GEN_MULTI
EE2018
248
EE2019
253
EMV_SCRIPT_CRYPTO_MULTI
EE2020
257
EMV_PIN_CHANGE_UNBLOCK_MULTI
EE2021
262
215
Mark II Programmers Guide
Chapter 19 EMV Functions
GEN_RANDOM
D D D D D
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
Request Content EE0002 FM
Length 3 1
Attribute h h
Description Function Code Function Modifier = 00
Random No. Len Response Content EE0002 rc
1 Length 3 1
h Attribute h h
= 01 – FF. (1 – 255) Description Function Code Return Code
Var
h
Random No.
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
© SafeNet, Inc.
EFTBUFFER
*RAND_NUM);
216
Mark II Programmers Guide
Chapter 19 EMV Functions
EMV_AC_GEN
D D D D D
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
Request Content EE2000 FM IMKAC –Spec APANB RN AC-Data Response Content EE2000 Rc AC
Length 3 1
Attribute h h
Var
K-Spec
8 8 Var Length 3 1
h h h Attribute h h
8
h
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
= 00. Reserved for possible future use; must be set to zero.
IMKAC –Spec
Key specifier which provides access to the IMKAC. Formats 0 – 3, and 11, 13 accepted.
APANB :
Application PAN Block as defined in [Ref. [1] of MarkII]. The HSM performs no checking on the contents of this field.
RN :
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.
AC Data :
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
Mark II Programmers Guide
Chapter 19 EMV Functions
EMV_AC_VERIFY
D D D D D
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
Request Content EE2001 FM
Length 3 1
Attribute h h
Var
K-Spec
8 8 8/Var
h h h
AC-Data
Var
h
Bitmap
Var
K-Spec
Transaction Data
Var
h
Response Content EE2001 Rc
Length 3 1
Attribute h h
IMKAC-Spec APANB RN AC/CAP Token
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
This function verifies an application cryptogram (TC, AAC or ARQC) as defined in Reference [1] of MarkII.
© SafeNet, Inc.
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.
IMKAC –Spec
Key specifier which provides access to the IMKAC. Formats 0 - 3, and 11, 13 accepted.
APANB
Application PAN Block as defined in Reference [1] of MarkII. The HSM performs no checking on the contents of this field.
RN
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.
AC
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.
218
Mark II Programmers Guide
Chapter 19 EMV Functions
CAP Token
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.
AC-Data
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.
Bitmap
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).
Transaction Data
Data signed to produce CAP Token. Only present when FM = 04. Must be a multiple of eight bytes.
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
UCHAR KEYSPEC UCHAR UCHAR UCHAR EFTBUFFER
FM, *IMK_AC, APANB[8], RN[8], AC[8], *AC_DATA);
For FM=01 or FM=4
© SafeNet, Inc.
219
Mark II Programmers Guide
int EFT_EE2001_EMVAcVerify_2( IN IN IN IN IN IN IN IN
© SafeNet, Inc.
Chapter 19 EMV Functions
UCHAR KEYSPEC UCHAR UCHAR EFTBUFFER EFTBUFFER KEYSPEC EFTBUFFER
FM, *IMK_AC, APANB[8], RN[8], *CAPToken, *AC_DATA, bitmap, *TR_data);
220
Mark II Programmers Guide
Chapter 19 EMV Functions
EMV_DAC_GEN
D D D D D
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
Request Content EE2002 FM IMKDAC –Spec APANB Response Content EE2002 rc DAC
Length 3 1
Attribute h h
Description Function Code Function Modifier = 00
Var
K-Spec
8 Length 3 1
h Attribute h h
Key specifier for IMKDAC (Formats: 0 - 3, 11, 13) Application PAN Block Description Function Code Return Code
2
h
Data Authentication Code
This function generates a Data Authentication Code (DAC) as defined in reference [1] of MarkII. FM
= 00. Reserved for possible future use; must be set to zero.
IMKDAC –Spec
Key specifier which provides access to the IMKDAC. Formats 0 - 3, and 11, 13 accepted.
APANB :
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
© SafeNet, Inc.
UCHAR
DAC[2]);
221
Mark II Programmers Guide
Chapter 19 EMV Functions
EMV_DAC_VERIFY
D D D D D
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
Request Content EE2003 FM IMKDAC –Spec APANB DAC Response Content EE2003 rc
Length 3 1
Attribute h h
Var
K-Spec
8 2 Length 3 1
h h Attribute h h
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
= 00. Reserved for possible future use; must be set to zero.
IMKDAC –Spec
Key specifier which provides access to the IMKDAC. Formats 0 – 3, and 11, 13 accepted.
APANB :
Application PAN Block as defined in reference [1] of MarkII. The HSM performs no checking on the contents of this field.
DAC
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
Mark II Programmers Guide
Chapter 19 EMV Functions
EMV_ICC_DN_GEN
D D D D D
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
Request Content EE2004 FM IMKIDN-Spec APANB IDN Data Response Content EE2004 rc IDN
Length 3 1
Attribute h h
Var
K-Spec
8 8 Length 3 1
h h Attribute h h
2
h
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
= 00. Reserved for possible future use; must be set to zero.
IMKIDN –Spec
Key specifier which provides access to the IMKIDN. Formats 0 - 3, and 11, 13 accepted.
APANB :
Application PAN Block as defined in reference [1] of MarkII. The HSM performs no checking on the contents of this field.
IDN Data :
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
Mark II Programmers Guide
Chapter 19 EMV Functions
EMV_ICC_DN_VERIFY
D D D D D
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
Request Content EE2005 FM IMKIDN-Spec APANB RN IDN Response Content EE2005 rc
Length 3 1
Attribute h h
Description Function Code Function Modifier = 00
Var
K-Spec
8 8 2 Length 3 1
h h h Attribute h h
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
= 00. Reserved for possible future use; must be set to zero.
IMKIDN –Spec
Key specifier which provides access to the IMKIDN Formats 0 – 3, and 11, 13 accepted.
APANB
Application PAN Block as defined in reference [1] of MarkII. The HSM performs no checking on the contents of this field.
RN
Random number for calculating data of IDN as defined in reference [1] of MarkII.
IDN
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
Mark II Programmers Guide
Chapter 19 EMV Functions
EMV_ARPC_GEN
D D D D D
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
Request Content EE2006 FM
Length 3 1
Attribute h h
IMKAC-Spec
Var
K-Spec
APANB ARPC-Data
8 8
h h
Length 3 1
Attribute h h
Key specifier for IMKAC (Formats: 0 - 3, 11, 13) Application PAN Block Authorization Response Cryptogram Data Description Function Code Return Code
8
h
Authorization Response Cryptogram
Response Content EE2006 rc ARPC
Description Function Code Function Modifier = 00
This function generates an Authorization Response Cryptogram as defined in reference [1] of MarkII. FM
= 00. Reserved for possible future use; must be set to zero.
IMKAC –Spec
Key specifier which provides access to the IMKAC. Formats 0 - 3, and 11, 13 accepted.
APANB
Application PAN Block as defined in reference [1] of MarkII. The HSM performs no checking on the contents of this field.
ARPC Data
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.
UCHAR KEYSPEC UCHAR UCHAR
FM, *IMK_AC, APANB[8], ARPC_DATA[8],
UCHAR
ARPC[8]);
225
Mark II Programmers Guide
Chapter 19 EMV Functions
EMV_SCRIPT_CRYPTO
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
Request Content EE2007 FM
Length 3 1
Attribute h h
1
h
IMKSMI-Spec
Var
K-Spec
IMKSMC-Spec
Var
K-Spec
APANB RN Text
8 8 Var
h h h
Offset Script-Data
2 Var
h h
Response Content EE2007 rc
Length 3 1
Attribute h h
eSMC(text)
Variabl e 8
h
Encrypted data.
h
Message Authentication Code
SC
MAC
D D D D D
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
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.
© SafeNet, Inc.
FM
= 00. See eSMC(text) below for further information.
SC
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.
IMKSMI –Spec
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.
226
Mark II Programmers Guide
Chapter 19 EMV Functions
IMKSMC –Spec
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.
APANB
Application PAN Block as defined in reference [1] of MarkII. The HSM performs no checking on the contents of this field.
RN
ARQC/AAC/TC.
Text
Script Command Data that is included in the sent Script to ICC.
Offset
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
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.
eSMC(text)
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.
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
© SafeNet, Inc.
EFTBUFFER UCHAR
*eSMC_Text, MAC[8]);
227
Mark II Programmers Guide
Chapter 19 EMV Functions
EMV_VERIFY_AC_EMV2000
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
Request Content EF2010 FM
Length 3 1
Attribute h h
Var
K-Spec
8 16 1 1 2 8/Var
h h h h h h
AC Data
Var
h
Bitmap
Var
K-Spec
Transaction Data
Var
h
Response Content EF2010 Rc
Length 3 1
Attribute h h
IMKAC-Spec PAN Data IV H B ATC AC/ CAP Token
D D D D D
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
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.
© SafeNet, Inc.
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.
IMKAC –Spec
Key specifier which provides access to the IMKAC. Formats 0 – 3, and 11, 13 accepted.
PAN Data
Formatted PAN and PAN Sequence No.
IV
Initialization Vector
H
Height for tree of keys
b
Branch factor of tree of keys
ATC
Application Transaction Counter (min = 01; max = FFFF)
228
Mark II Programmers Guide
Chapter 19 EMV Functions
AC
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
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.
AC Data
Data used in the calculation of the Application Cryptogram. Must be a multiple of eight bytes).
Bitmap
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).
Transaction Data
Data signed to produce CAP Token. Only present when FM = 04. Must be a multiple of eight bytes.
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
Mark II Programmers Guide
Chapter 19 EMV Functions
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
Mark II Programmers Guide
Chapter 19 EMV Functions
EMV_VERIFY_AC_VISA
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
Request Content EF2011 FM
Length 3 1
Attribute h h
Var
K-Spec
8 8/Var
h h
AC Data
Var
h
Bitmap
Var
K-Spec
Length 3 1
Attribute h h
IMKAC-Spec PAN Data AC/Shortened AC
Response Content EF2011 rc
D D D D D
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
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].
© SafeNet, Inc.
FM
When Function Modifier = 00 the Bitmap field is not included. When Function Modifier = 01 the Bitmap field is included.
IMKAC –Spec
Key specifier which provides access to the IMKAC. Formats 0 - 3, and 11, 13 accepted.
PAN Data
Formatted PAN and PAN Sequence No.
AC
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 AC
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.
231
Mark II Programmers Guide
Chapter 19 EMV Functions
AC Data
Data used in the calculation of the Application Cryptogram (must be a multiple of eight bytes).
Bitmap
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).
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
FM, *IMK_AC, PAN[8], AC[8], *AC_DATA);
For FM = 01 int EFT_EF2011_EMVVerifyAcVisa_2( IN UCHAR IN KEYSPEC IN UCHAR IN EFTBUFFER IN EFTBUFFER IN
© SafeNet, Inc.
KEYSPEC
FM, *IMK_AC, PAN[8], *AC, *AC_DATA, *bitmap);
232
Mark II Programmers Guide
Chapter 19 EMV Functions
EMV_GENERATE_ARPC
D D D D D
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
Request Content EF2012 FM IMKAC-Spec PAN Data IV H b ATC ARPC Data Response Content EF2012 rc ARPC
Length 3 1
Attribute h h
Var
K-Spec
8 16 1 1 2 8 Length 3 1
h h h h h h Attribute h h
8
h
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
= 00. Reserved for possible future use; must be set to zero.
IMKAC –Spec
Key specifier which provides access to the IMKAC. Formats 0 - 3, and 11, 13 accepted.
PAN Data
Formatted PAN and PAN Sequence No.
IV
Initialization Vector
H
Height for tree of keys
b
Branch factor of tree of keys
ATC
Application Transaction Counter (min = 01; max = FFFF)
ARPC Data
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
Mark II Programmers Guide
Chapter 19 EMV Functions
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
© SafeNet, Inc.
UCHAR
ARPC[8]);
234
Mark II Programmers Guide
Chapter 19 EMV Functions
EMV_SCRIPT_CRYPTO_EMV2000
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
Request Content EF2013 FM
Length 3 1
Attribute h h
1
h
IMKSMI –Spec
Var
K-Spec
IMKSMC –Spec
Var
K-Spec
PAN Data IV H b ATC Mode Text Offset Script-Data
8 16 1 1 2 1 Var 2 Var
h h h h h h h h h
Length 3 1
Attribute h h
variable 8
h h
SC
Response Content EF2013 rc eSKSMC(Text) MAC
D D D D D
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
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.
© SafeNet, Inc.
FM
= 00/01. See eSKSMC(Text) below for further information.
SC
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.
235
Mark II Programmers Guide
Chapter 19 EMV Functions
IMKSMI –Spec
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.
IMKSMC –Spec
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.
PAN Data
Formatted PAN and PAN Sequence No.
IV
Initialization Vector
H
Height for tree of keys
b
Branch factor of tree of keys
ATC
Application Transaction Counter (min = 01; max = FFFF)
Mode
Encryption Mode. 00=ECB; 01=CBC
Text
Script Command Data that is included in the sent Script to ICC. (Length must be a multiple of 8.)
Offset
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.
eSKSMC(Text)
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.
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
© SafeNet, Inc.
FM,
236
Mark II Programmers Guide
© SafeNet, Inc.
Chapter 19 EMV Functions IN IN IN IN IN IN IN IN IN IN IN IN
UCHAR KEYSPEC KEYSPEC UCHAR UCHAR UCHAR UCHAR UCHAR UCHAR EFTBUFFER USHORT EFTBUFFER
SC, *IMK_SMI, *IMK_SMC, PAN_data[8], IV[16], H, b, ATC[2], encrypt_mode, *Text, Offset, *Script_Data,
OUT OUT
EFTBUFFER UCHAR
*eSMC_Text, MAC[8]);
237
Mark II Programmers Guide
Chapter 19 EMV Functions
EMV_SCRIPT_CRYPTO_VISA
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
Request Content EF2014 FM
Length 3 1
Attribute H H
1
H
IMKSMI –Spec
Var
K-Spec
IMKSMC –Spec
Var
K-Spec
PAN Data ATC Text
8 2 Var
H H H
Offset Script-Data
2 Var
H H
Length 3 1
Attribute H H
variable 8
H H
SC
Response Content EF2014 rc eSKSMC(Text) MAC
D D D D D
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
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.
© SafeNet, Inc.
FM
= 00/01. See eSKSMC(Text) below for further information.
SC
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.
IMKSMI –Spec
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.
238
Mark II Programmers Guide
Chapter 19 EMV Functions
IMKSMC –Spec
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.
PAN Data
Formatted PAN and PAN Sequence No.
ATC
Application Transaction Counter (min = 01, max = FFFF)
Text
Script Command Data that is included in the sent Script to ICC. (Length must be a multiple of 8.)
Offset
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
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.
eSKSMC(Text)
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.
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
© SafeNet, Inc.
EFTBUFFER UCHAR
FM, SC, *IMK_SMI, *IMK_SMC, PAN_data[8], ATC[2], *Text, Offset, *Script_Data, *eSMC_Text, MAC[8]);
239
Mark II Programmers Guide
Chapter 19 EMV Functions
EMV_PIN_CHANGE_UNBLOCK_VISA
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
Request Content EF2015 FM
Length 3 1
Attribute h h
1
h
IMKSMI –Spec
Var
K-Spec
IMKSMC –Spec
Var
K-Spec
PAN Data ATC PPK-Spec
8 2 Var
h h K-Spec
ePPK(PIN) ANB PVK-Spec
8 6 Var
h d K-Spec
Validation Data Offset PIN Length Script-Data Position Script-Data
8 6 1 2 Var
h d h h h
Response Content EF2015 rc
Length 3 1
Attribute h h
New PIN Data
Variabl e 8
h
Encrypted New PIN Data
h
Message Authentication Code
P2
MAC
D D D D D
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
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.
© SafeNet, Inc.
FM
= 00/01. See New PIN Data below for further information.
P2
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
240
Mark II Programmers Guide
Chapter 19 EMV Functions
IMKSMI –Spec
Issuer Master Key for secure message integrity key specifier. Formats 0 - 3, and 11, 13 accepted.
IMKSMC –Spec
Issuer Master Key for secure message confidentiality key specifier. Formats 0 - 3, and 11, 13 accepted.
PAN Data
Formatted PAN and PAN Sequence No.
ATC
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
Key specifier for PPK. Formats 0 - 3, 10, 11 and 13 accepted.
ePPK(PIN)
Formatted PIN encrypted by the PPK.
ANB
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
Key specifier for PVK. Formats 0 - 3 , 11, 12, 13, 14 accepted.
Validation Data
Validation Data used to calculate the current PIN.
Offset
This field consists of 12 digits of offset data. The significant digits are left justified in the field.
PIN length
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.
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
Mark II Programmers Guide
Chapter 19 EMV Functions
•
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
© SafeNet, Inc.
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]);
242
Mark II Programmers Guide
Chapter 19 EMV Functions
EMV_PIN_CHANGE_UNBLOCK
D D U D D
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
Request Content EE2016 FM
Length 3 1
Attribute h h
P2
1
h
Scheme
1
h
IMKSMI
Var
K-Spec
Key specifier for IMKSMI (Formats 0 - 3, 11, 13)
IMKSMC
Var
K-Spec
Key specifier for IMKSMC (Formats 0 - 3, 11, 13)
IMKAC
Var
K-Spec
Key specifier for IMKAC (Formats 0 - 3, 11, 13)
PAN Data
Var
h
Formatted PAN and PAN Sequence Number
Session Key Data
Var
h
Session Key Data
ePPK(PIN1)
8
h
Encrypted PIN Block (Existing PIN)
ePPK(PIN2)
8
h
Encrypted PIN Block (New PIN)
Var
K-Spec
PF
1
h
PIN Block Format (Formats: 10, 13)
ANB
6
d
Account Number Block
Script-Data Position
2
h
Script-Data Position
Var Length 3 1
h Attribute h h
Var
h
Encrypted New PIN Data
8
h
Message Authentication Code
PPK
Script Data Response Content EE2016 rc New PIN Data MAC
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 PPK (Formats: 0 - 3, 10, 11, 13)
Script Data Description Function Code Return Code
This function provides the cryptographic processing for an issuer script which will unBlock or change the offline reference PIN stored in an EMV’96-based card. It calculates the MAC and, if required, the encrypted new PIN data.
© SafeNet, Inc.
243
Mark II Programmers Guide
Chapter 19 EMV Functions
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.
Session Key Data
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.
ePPK(PIN1)
If the Function Flag (P2) = 01, this field is decrypted to get the existing PIN
ePPK(PIN2)
Decrypted to recover the new PIN
PF
ISO formats 0 and 3. This field is used to get the new PIN and, if appropriate, the existing PIN
ANB
This field is used to get the new PIN and, if appropriate, the existing PIN
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
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.
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.
MAC
Message authentication code.
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
© SafeNet, Inc.
EFTBUFFER UCHAR
*New_PIN_Data, MAC[8]);
244
Mark II Programmers Guide
Chapter 19 EMV Functions
EMV_PIN_CHANGE_UNBLOCK_EMV_2000
D D U
PHW SHP PSO/PSG
Request Content EE2017 FM
D
Card Issuance (SHP Toolkit EMV)
D
Length 3 1
Attribute h h
P2
1
h
Scheme
1
h
IMKSMI
Var
K-Spec
Key specifier for IMKSMI (Formats 0 - 3, 11, 13)
IMKSMC
Var
K-Spec
Key specifier for IMKSMC (Formats 0 - 3, 11, 13)
IMKAC
Var
K-spec
Reserved. (Key specifier for IMKAC)
PAN Data
Var
h
Formatted PAN and PAN Sequence No.
IV
16
h
Initialization Vector
H
1
h
Height of tree of keys
b
1
h
Branch factor of tree of keys
ATC
2
h
Application Transaction Counter
ePPK(PIN1)
8
h
Encrypted PIN Block (Existing PIN)
ePPK(PIN2)
8
h
Encrypted PIN Block (New PIN)
Var
K-Spec
PF
1
h
PIN Block Format (Formats: 10, 13)
ANB
6
d
Account Number Block
Script-Data Position
2
h
Script-Data Position
Var Length 3 1
h Attribute h h
Var
h
Encrypted New PIN data
8
h
Message Authentication Code
PPK
Script-Data Response Content EE2017 rc New PIN data MAC
© SafeNet, Inc.
SHP Toolkit MK2
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 PPK (Formats: 0 – 3, 10, 11. 13)
Script Data Description Function Code Return Code
245
Mark II Programmers Guide
Chapter 19 EMV Functions
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.
ePPK(PIN1)
If the Function Flag (P2) = 01, this field is decrypted to get the existing PIN
ePPK(PIN2)
Decrypted to recover the new PIN
PF
ISO formats 0 and 3. This field is used to get the new PIN and, if appropriate, the existing PIN
ANB
This field is used to get the new PIN and, if appropriate, the existing PIN
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.
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.
MAC
Message authentication code.
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
Mark II Programmers Guide
© SafeNet, Inc.
Chapter 19 EMV Functions
IN
EFTBUFFER
*Script_Data,
OUT OUT
EFTBUFFER UCHAR
*New_PIN_Data, MAC[8]);
247
Mark II Programmers Guide
Chapter 19 EMV Functions
EMV_VERIFY_AC_GEN_ARPC
D D D
PHW SHP PSO/PSG
Request Content EE2018 FM
D
Card Issuance (SHP Toolkit EMV)
D
Length 3 1
Attribute h h
Action
1
h
IMKAC
Var
K-Spec
1
h
00 = Common 01 = SECCOS.
Var
h
Data used with IMKAC to derive MKAC. The contents of this field are dependent on the value of MK Method.
1
h
AC Key Method = 00 - 04, see page 250
Var
h
Data used with MKAC to derive the session key SKAC. The contents of this field are dependent on the value of AC Key Method.
1
h
AC Method = 00 – 03, see page 250
Var
h
Data on which the AC is calculated.
AC
8
h
Application Cryptogram - ARQC, TC or AAC.
ARPC Key Method
1
h
00 = same key as derived for AC. 01 = key = MKAC.
Var
h
Zero-length field.
1
h
01 = Method 1. = Method 2.
Var
h
Length 3 1 Var
Attribute h h h
Data on which the ARPC is calculated. Description Function Code Return Code 4 or 8 byte ARPC. zero-length field.
MK Method MK Data
AC Key Method AC Key Data
AC Method AC Data
ARPC Key Data ARPC Method ARPC-Data Response Content EE2018 Rc ARPC
© SafeNet, Inc.
SHP Toolkit MK2
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)
02
Or
248
Mark II Programmers Guide
Chapter 19 EMV Functions
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
Verify AC only
02
Generate ARPC only
03
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
Reference
00
Common
[1-8]
01
SECCOS
[34]
Field Content
Value 00
PAN Data
Length Attribute Description 6-16
h
PAN || PAN Sequence No.
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:
Value 01
Length
Processing
<16 digits
Left-padded with zeros.
=16 digits
Used as is.
>16 digits
Hashed and decimalized.
Field Content CID
© SafeNet, Inc.
Length Attribute Description 8-32
h
Card Identification Number
249
Mark II Programmers Guide
Chapter 19 EMV Functions
AC Key Method
The following values of AC Key Method are supported:
Value Implementation
Reference
00
SKAC = MKAC
[39] VSDC 1.3.2
01
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
[31], [34] M/Chip 2.1, SECCOS [5] EMV 4.0
02 03 04 Value 00
Field Content
Value 02
Value 03
0
Field Content
Length Attribute Description
ATC
2
h
Application Transaction Counter
UN
4
h
Unpredictable Number
Field Content
Length Attribute Description
ATC
2
h
Application Transaction Counter
IV
16
h
Initialization Vector
H
1
h
Height of tree of keys
B
1
h
Branch factor of tree of keys
Field Content
Length Attribute Description
ATC
Value 04
2
Field Content
h
Application Transaction Counter
Length Attribute Description
ATC
AC Method
[37], [38] AEIPS, J/Smart
Length Attribute Description
Null Value 01
[35] EMV 4.1 CCD
2
h
Application Transaction Counter
The following values of AC Method are supported:
Value ISO/IEC 9797-1 Alternatives
© SafeNet, Inc.
Reference
Algorithm
Pad Method
00
1
1
01
1
2
[5] EMV
02
3
1
[39], [37], [38] VSDC, AEIPS, J/Smart
03
3
2
[5], [31], [34] EMV, M/Chip, SECCOS
250
Mark II Programmers Guide
Chapter 19 EMV Functions
ARPC Key Method
The following values of ARPC Key Method are supported:
ARPC Method
Value Implementation
Reference
00
SKARPC = SKAC
All except M/Chip 2.1
01
SKARPC = MKAC
[31] M/Chip 2.1
The following values of ARPC Method are supported:
Value 00
Value Implementation
Reference
01
Method 1
All
02
Method 2
[35] EMV 4.1
Field Content
Length Attribute Description
ARC
Value 01
2
Field Content
h
Authorization Response Code
Length Attribute Description
CSU
4
h
Application Transaction Counter
PAD
0-8
h
Proprietary Application Data
1.1.1.1 Usage of Methods The following table is a matrix of the common combinations of methods. A call to the function would typically use the methods identified across a single row of the table.
Implementatio n
AC Key
Methods AC
MK
AEIPS
00
ARPC Key
ARPC
04
02
00
01
EMV 4.0
00
02
01, 03
00
01
EMV 4.1
00
02, 03
01, 03
00
01, 02
EMV 4.1 CDD
00
03
01, 03
00
02
J/Smart
00
04
02
00
01
M/Chips 2.1
00
01
03
01
01
SECCOS
01
01
03
00
01
VSDC 1.3.2
00
00
02
00 (or 01)
01
M/Chip 4.0
As M/Chip 2.1 or EMV 4.0
VSC 1.4.0
As VSDC 1.3.2 or EMV 4.0
SHP Toolkit MK2 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
Mark II Programmers Guide
© SafeNet, Inc.
Chapter 19 EMV Functions
IN IN IN IN IN IN IN IN IN
UCHAR EFTBUFFER UCHAR EFTBUFFER UCHAR UCHAR EFTBUFFER UCHAR EFTBUFFER
AC_Key_Method, *AC_Key_Data, AC_Method, *AC_Data, AC[8], ARPC_Key_Method, *ARPC_Key_Data, ARPC_Method, *ARPC_Data,
_OUT
EFTBUFFER
*ARPC);
252
Mark II Programmers Guide
Chapter 19 EMV Functions
EMV_AC_GEN_MULTI
D D U D D
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
Request Content EE2019 FM IMKAC MK Method MK Data
AC Key Method AC Key Data
AC Method AC Data Response Content EE2019 rc AC
Length 3 1
Attribute h h
Description Function Code Function Modifier = 00
Var
K-Spec
Key specifier for IMKAC (Formats: 0 - 3, 11, 13)
1
h
00 = Common = SECCOS.
Var
h
Data used with IMKAC to derive MKAC. The contents of this field are dependent on the value of MK Method.
1
h
AC Key Method = 00 – 04
Var
h
Data used with MKAC to derive the session key SKAC. The contents of this field are dependent on the value of AC Key Method.
1
h
AC Method = 00 – 03, see page 250
Var Length 3 1 8
h Attribute h h h
Data on which the AC is calculated. Description Function Code Return Code Application Cryptogram – ARQC, TC or AAC.
01
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
© SafeNet, Inc.
The following values of MK Method are supported:
Value Implementation
Reference
00
Common
[1-8]
01
SECCOS
[34]
253
Mark II Programmers Guide
Value 00
Chapter 19 EMV Functions
Field Content
Length Attribute Description
PAN Data
6-16
h
PAN || PAN Sequence No.
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:
Value 01
Length
Processing
<16 digits
Left-padded with zeros.
=16 digits
Used as is.
>16 digits
Hashed and decimalized.
Field Content CID
AC Key Method
00
SKAC = MKAC
[39] VSDC 1.3.2
01
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
[31], [34] M/Chip 2.1, SECCOS [5] EMV 4.0
Field Content Null
© SafeNet, Inc.
Card Identification Number
Reference
04
Value 02
h
Value Implementation
03
Value 01
8-32
The following values of AC Key Method are supported:
02
Value 00
Length Attribute Description
Field Content
[35] EMV 4.1 CCD [37], [38] AEIPS, J/Smart
Length Attribute Description 0
Length Attribute Description
ATC
2
h
Application Transaction Counter
UN
4
h
Unpredictable Number
Field Content
Length Attribute Description
ATC
2
h
Application Transaction Counter
IV
16
h
Initialization Vector
H
1
h
Height of tree of keys
254
Mark II Programmers Guide
Chapter 19 EMV Functions
b
Value 03
1
Field Content
2
Field Content
h
Application Transaction Counter
Length Attribute Description
ATC
AC Method
Branch factor of tree of keys
Length Attribute Description
ATC
Value 04
h
2
h
Application Transaction Counter
The following values of AC Method are supported:
Value ISO/IEC 9797-1 Alternatives
Reference
Algorithm
Pad Method
00
1
1
01
1
2
[5], EMV
02
3
1
[39], [37], [38] VSDC, AEIPS, J/Smart
03
3
2
[5], [31], [34] EMV, M/Chip, SECCOS
1.1.1.2 Usage of Methods The following table is a matrix of the common combinations of methods. A call to the function would typically use the methods identified across a single row of the table.
AEIPS
MK 00
Methods AC Key 04
AC 02
EMV 4.0
00
02
01, 03
EMV 4.1
00
02, 03
01, 03
EMV 4.1 CDD
00
03
01, 03
J/Smart
00
04
02
M/Chips 2.1
00
01
03
SECCOS
01
01
03
VSDC 1.3.2
00
00
02
Implementation
SHP Toolkit MK2
© SafeNet, Inc.
255
Mark II Programmers Guide
Chapter 19 EMV Functions
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
© SafeNet, Inc.
AC[8] );
256
Mark II Programmers Guide
Chapter 19 EMV Functions
EMV_SCRIPT_CRYPTO_MULTI
PHW
U
SHP
D
PSO/PSG
U D U
SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
Request Content EE2020 FM
Length 3 1
Attribute h h
1
h
IMKSMI
Var
K-Spec
IMKSMC
Var
K-Spec
1
h
00 = Common 01 = SECCOS.
Var
h
Data used with IMKSMx to derive MKSMx. The contents of this field are dependent on the value of MK Method.
1
h
SM Key Method = 02 – 05
SM Key Data
Var
h
SM Method Text Offset Script-Data
1 Var 2 Var
h h h h
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.
Length 3 1
Attribute h h
Var 8
h h
SC
MK Method MK Data
SM Key Method
Request Content EE2020 rc eSKSMC(Text) MAC
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)
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.
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
Mark II Programmers Guide
Chapter 19 EMV Functions
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
=00.
SC
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.
IMKSMI –Spec
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.
IMKSMC –Spec
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.
MK Method
Methods are Supported for deriving the ICC Master Keys.(MKsmx) 00=Common ; 01=SECCOS.
MK Data
Data used with IMKSMx to derive MKSMx. The contents of this field are dependent on the value of MK Method.
SM Key Method
Methods exist for deriving a Session Key(SKsmx) from the MKsmx.
SM Key Data
Data used with MKSMx to derive the session key SKSMx. The contents of this field are dependent on the value of SM Key Method.
SM Method
Encryption Mode. 00=ECB; 01=CBC.
Text
Script Command Data that is included in the sent Script to ICC. (Length must be a multiple of 8.)
Offset
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 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.
eSKSMC(Text)
Encrypted text in a variable length field. This is the same length as the specified input “Text” field. it is a standard Var field.
MAC
Message authentication code.
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
Mark II Programmers Guide
Chapter 19 EMV Functions
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
encrypt command data only – in ‘Text’ field
02
calculate a MAC for the entire command – ‘ScriptData field.
03
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
Value 00
The following values of MK Method are supported:
Value Implementation
Reference
00
Common
[1-8]
01
SECCOS
[34]
Field Content
Length Attribute Description
PAN Data
6-16
h
PAN || PAN Sequence No.
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:
Value 01
Length
Processing
<16 digits
Left-padded with zeros.
=16 digits
Used as is.
>16 digits
Hashed and decimalized.
Field Content CID
SM Key Method
© SafeNet, Inc.
Length Attribute Description 8-40
h
Card Identification Number
The following values of SM Key Method are supported:
Value Implementation
Reference
02
[5] EMV 4.0
Tree of keys using ATC, IV, H and b
259
Mark II Programmers Guide
Chapter 19 EMV Functions
03 04
Tree of keys using ATC. Fixed IV, H and b. Xor using ATC
05
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
Length Attribute Description
ATC
2
h
Application Transaction Counter
IV
16
h
Initialization Vector
H
1
h
Height of tree of keys
b
1
h
Branch factor of tree of keys
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
Length Attribute Description 2
h
Application Transaction Counter
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
Length Attribute Description 2
h
Application Transaction Counter
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
Length Attribute Description 8
h
Random Number
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
Mark II Programmers Guide
Chapter 19 EMV Functions
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.
1.1.1.3 Usage of Methods The following table is a matrix of the common combinations of methods. A call to the function would typically use the methods identified across a single row of the table.
AEIPS
00
Methods AC Key 04
J/Smart, VSDC
00
04
00
EMV 4.0 / 4.1
00
02
00 or 01
EMV 4.1 CCD
00
03
00 or 01
EMV 4.1 + SU Bulletin 46
00
05
00 or 01
SECCOS
01
05
01
Implementation
MK
AC 01
SHP Toolkit MK2 int EFT_EE2020_EMVScriptCrypto_Multi( IN UCHAR IN UCHAR IN KEYSPEC IN KEYSPEC IN UCHAR IN EFTBUFFER IN UCHAR IN EFTBUFFER IN UCHAR IN EFTBUFFER IN USHORT IN EFTBUFFER OUT OUT
© SafeNet, Inc.
EFTBUFFER UCHAR
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]);
261
Mark II Programmers Guide
Chapter 19 EMV Functions
EMV_PIN_CHANGE_UNBLOCK_MULTI
U D U U
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
Request Content EE2021 FM SC
Length 3 1 1
Attribute h h h
IMKSMI
Var
K-Spec
IMKSMC
Var
K-Spec
1
h
00 = Common 01 = SECCOS.
Var
h
Data used with IMKSMx to derive MKSMx. The contents of this field are dependent on the value of MK Method.
1
h
SM Key Method = 02 – 05
Var
h
Data used with MKSMx to derive the session key SKSMx. The contents of this field are dependent on the value of SM Key Method.
1
h
PIN formatting method = 01, 02, 11, 12.
Var
h
PIN formatting data
MK Method MK Data
SM Key Method SM Key Data
PF Method PF Data
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)
(Formats: 10, 11, 13) PC Method
PC Data PI Method PI Data Response Content EE2021 Rc New PIN data MAC
1
h
PIN confidentiality method 00 = ECB 01 = CBC
Var
h
PIN confidentiality data Zero-length field.
1
h
PIN integrity method 00 = Default
Var
h
PIN integrity data
Length
Attribute
3 1 Var
h h h
Function Code Return Code Encrypted New PIN data
8
h
Message Authentication Code
Description
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.
U
262
Mark II Programmers Guide
Chapter 19 EMV Functions
The subscript SMx is used to denote both SMI and SMC. FM
=00.
SC
Identifies the required processing: 2: PIN Unblock only. 3: PIN Change
IMKSMI –Spec
Key specifier which provides access to the IMKSMI. Formats 0 - 3, and 11, 13 accepted.
IMKSMC –Spec
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.
MK Method
Methods are supported for deriving the ICC Master Keys. (MKsmx) 00=Common; 01=SECCOS.
MK Data
Data used with IMKSMx to derive MKSMx. The contents of this field are dependent on the value of MK Method.
SM Key Method
Methods exist for deriving a Session Key (SKsmx) from the MKsmx.
SM Key Data
Data used with MKSMx to derive the session key SKSMx. The contents of this field are dependent on the value of SM Key Method.
PF Method
Methods exist for creating the cleartext PIN block.
PF Data
it is a variable-length field that contains zero or more fields incorporating the data required by the specific PF Method.
PC 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).
PC Data PI Method
PIN integrity method. Just support one method for calculating MAC using SKSMI. 00 = Default.
PI Data
it is a variable-length field incorporating the data required by the specific PI method.
New PIN Data
Encrypted New PIN Data. It is formatted as a standard Var field. This field is only present when SC = 03.
MAC
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
Mark II Programmers Guide
PF Method
PF Data Value 01 and 02
Chapter 19 EMV Functions
The following values of PF Method are supported:
Value Implementation
Reference
01
ISO-1
[40]
02 11 13
ISO-2 delta PIN with UDK-A ISO-0 with UDK-A
[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
Length Attribute Description
ePPK(PIN)
8
h
Var
K-Spec
PF
1
h
PIN Block Format (Formats: 10, 13)
ANB
6
d
Account Number Block
PPK
Encrypted PIN Block Key specifier for PPK (Formats: 0 - 3, 10, 11, 13)
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
Length Attribute Description
ePPK(PIN1)
8
h
Encrypted PIN Block (Current PIN)
ePPK(PIN2)
8
h
Encrypted PIN Block (New PIN)
Var
K-Spec
PF
1
h
PIN Block Format (Formats: 10, 13)
ANB
6
d
Account Number Block
IMKAC
Var
K-Spec
Key specifier for IMKAC (Formats: 0 - 3, 13)
PPK
Key specifier for PPK (Formats: 0 - 3, 10, 11, 13)
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
Mark II Programmers Guide
Value 12
Chapter 19 EMV Functions
Field Content
Length Attribute Description
ePPK(PIN)
8
h
Var
K-Spec
PF
1
h
PIN Block Format (Formats: 10, 13)
ANB
6
d
Account Number Block
IMKAC
Var
K-Spec
Key specifier for IMKAC (Formats: 0 - 3, 13)
PPK
Encrypted PIN Block Key specifier for PPK (Formats: 0 - 3, 10, 11, 13)
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
The following value of PI Method are supported:
Value Method 00 PI Data
Value 00
Reference
Default
It is a variable-length field that contains zero or more fields incorporating the data required by the specific PI method.
Field Content
Length Attribute Description
Script-Data Position
2
h
Script-Data Position
Script-Data
Var
h
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.
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.
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
Mark II Programmers Guide
2. 3. 4. 5. 6.
7.
Chapter 19 EMV Functions
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)
1.1.1.4 Usage of Methods The following table is a matrix of the common combinations of methods. A call to the function would typically use the methods identified across a single row of the table. Implementation
© SafeNet, Inc.
Methods SM Key PF 04 11, 12
AEIPS
MK 00
PC 01
EMV 4.0
00
02
not specified
00, 01
EMV 4.1
00
02, 03
not specified
00, 01
EMV 4.1 + SUB 46
00
05
not specified
00, 01
EMV 4.1 CCD
00
03
not specified
01
EMV 4.1 CCD + SUB 46
00
05
not specified
01
J/Smart
00
04
11,12
00
M/Chip 2.1
00
05
02
01
SECCOS
01
05
01, 02
01
VSDC 1.3.2
00
04
11, 12
00
266
Mark II Programmers Guide
Chapter 20 CEPS Functions
Chapter 20 CEPS Functions Overview The host functions described in this section are designed to meet the specific needs CEPS transaction processing.
Summary of CEPS Functions
© SafeNet, Inc.
Function Name
Function Code
Page
VCEPS_VER_S1_GEN_S2
EF0701
268
VCEPS_VER_SN
EF0702
269
VCEPS_GEN_SN
EF0703
271
VCEPS_MAC_VER_LSAM
EF0704
272
VCEPS_GEN_HASH_CEP
EF0F01
273
267
Mark II Programmers Guide
Chapter 20 CEPS Functions
VCEPS_VER_S1_GEN_S2
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
Request Content EF0701 FM
Length 3 1
Attribute h h
KMx-Spec
Var
K-Spec
IDCEP NTCEP S1 S1 Data
6 2 8 Var
h h h h
S2 Data
Var
h
Length 3 1
Attribute h h
8
h
Response Content EF0701 rc S2
D D U D D
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
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
© SafeNet, Inc.
UCHAR
MAC_S2[8]);
268
Mark II Programmers Guide
Chapter 20 CEPS Functions
VCEPS_VER_SN
D D U D D
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
Request Content EF0702 FM
Length 3 1
Attribute h h
KMx-Spec
Var
K-Spec
Derivation Data
Var
h
Session Key Data
Var
h
Sn Sn Data
8 Var
h h
Length 3 1
Attribute h h
Response Content EF0702 rc
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
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
Mark II Programmers Guide
Chapter 20 CEPS Functions
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
Mark II Programmers Guide
Chapter 20 CEPS Functions
VCEPS_GEN_SN
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
Request Content EF0703 FM
Length 3 1
Attribute h h
KMx-Spec
Var
K-Spec
Derivation Data
Var
h
Session Key Data
Var
h
Sn Data
Var
h
Length 3 1
Attribute h h
8
h
Response Content EF0703 rc Sn
D D U D D
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
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
© SafeNet, Inc.
UCHAR
MAC_Sn[8]);
271
Mark II Programmers Guide
Chapter 20 CEPS Functions
VCEPS_MAC_VER_LSAM
D D U D D
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
Request Content EF0704 FM
Length 3 1
Attribute h h
LSAMK-Spec
Var
K-Spec
eLSAMK(R1) MACLSAM Data
16 4 Var
h h h
Length 3 1
Attribute h h
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
Mark II Programmers Guide
Chapter 20 CEPS Functions
VCEPS_GEN_HASH_CEP
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
Request Content EF0F01 FM KMx-Spec
IDCEP Hash Data Response Content EF0F01 rc HCEP
Length 3 1
Attribute h h
Var
K-Spec
6 Var Length 3 1
h h Attribute h h
10
h
D D U D D
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.
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
© SafeNet, Inc.
UCHAR
Hcep[10]);
273
Mark II Programmers Guide
© SafeNet, Inc.
Chapter 20 CEPS Functions
274
Mark II Programmers Guide
Chapter 21 AS2805.6.3 Support Functions
Chapter 21 AS2805.6.3 Support Functions Summary of AS2805.6.3 2000 Support Functions This section contains the function descriptions which provide the ability for a Mark II device to encipher and decipher electronic messages using session keys with an AMB device in compliance with the APCA 2000 specification. This means that keys can be exchanged between institutions that have Mark II and AMB devices.
© SafeNet, Inc.
Function Name
Function Code
Page
GETPUBLICKEY
EE3030
276
KIS_SEND
EE3031
277
KIR_REC
EE3032
278
NODEPROOF
EE3033
279
NODERESP
EE3034
280
275
Mark II Programmers Guide
Chapter 21 AS2805.6.3 Support Functions
GETPUBLICKEY
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
Request Content EE3030 FM PK-Spec Response Content EE3030 rc
Length 3 1
Attribute h h
Var
K-Spec
Length 3 1
Attribute h x
1
x
20 Var
x K-Spec
n PVC(PKi HSM) PKi HSM
D D U D D
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
© SafeNet, Inc.
UCHAR UCHAR KEYSPEC
*ModLen, PVC_PKI_HSM[20], *PKI_HSM);
276
Mark II Programmers Guide
Chapter 21 AS2805.6.3 Support Functions
KIS_SEND
D D U D U
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
Request Content EE3031 FM
Length 3 1
Attribute h h
SK-Spec
Var
K-Spec
PKr
Var
K-Spec
Length 3 1
Attribute h x
KIS-Spec
Var
K-Spec
sSKs HSM(hash of key data) ePKr(KIS) KVC(KIS)
Var
S-Block
Key specifier for KIS (Format: 15) Signed hash of KIS
Var 3
S-Block x
Enciphered KIS Key Verification Code of KIS
Response Content EE3031 rc
Description Function Code Function Modifier = 00 Key specifier for Index to SK HSM (Formats: 0 - 3) Receiver’s public Key (Format: 80) Description Function Code Return Code
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
© SafeNet, Inc.
( FM, *SK, *PKr,
OUT OUT OUT
KEYSPEC EFTBUFFER EFTBUFFER
*KIS, *Signed_Hash, *ePKr_KIS,
OUT
UCHAR
KVC_KIS[3] );
277
Mark II Programmers Guide
Chapter 21 AS2805.6.3 Support Functions
KIR_REC
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
Request Content EE3032 FM
Length 3 1
Attribute h h
SK-Spec
Var
K-Spec
sSKs HSM(hash of key data) ePKr HSM(KIR) PKs-Spec
Var
S-Block
Var Var
S-Block K-Spec
Response Content EE3032 rc
Length 3 1
Attribute h x
KIR-Spec
Var
K-Spec
KVC(KIR)
3
x
D D U D U
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 Sender’s 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
© SafeNet, Inc.
KEYSPEC UCHAR
*KIR, KVC_KIR [3] );
278
Mark II Programmers Guide
Chapter 21 AS2805.6.3 Support Functions
NODEPROOF
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
Request Content EE3033 FM Output Len
KIS-Spec Response Content EE3033 rc eKISv82(RNs) eKISv84(RNr)
Length 3 1
Attribute h h
Description Function Code Function Modifier = 00
1
h
Var
K-Spec
Length 3 1
Attribute h x
Output length required 01 = 64 bits 02 = 128 bits Key specifier for KIS (Formats 0 - 3, 15) Description Function Code Return Code
Var Var
h h
D D U D U
Encrypted Random Number Encrypted Inverted Random Number.
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
© SafeNet, Inc.
EFTBUFFER EFTBUFFER
*eKISv82_RNs, *eKISv84_RNr);
279
Mark II Programmers Guide
Chapter 21 AS2805.6.3 Support Functions
NODERESP
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
Request Content EE3034 FM KIR-Spec eKIRv82(RNs) Response Content EE3034 rc eKIRv84(RNr)
Length 3 1
Attribute h h
Var
K-Spec
Var Length 3 1
h Attribute h x
Var
h
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
© SafeNet, Inc.
int EFT_EE3034_NodeResp( IN UCHAR IN KEYSPEC IN EFTBUFFER
FM, *KIR, *eKIRv82_RNs,
OUT
*eKIRv84_RNr);
EFTBUFFER
280
Mark II Programmers Guide
Chapter 22 Key Block
Chapter 22 Key Block Summary of Key Block Functions
© SafeNet, Inc.
Function Name
Function Code
Page
GEN_TERMINAL_KEY
EE0628
282
281
Mark II Programmers Guide
Chapter 22 Key Block
GEN_TERMINAL_KEY
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
Request Content EE0628 FM
Length 3 1
Attribute h h
Var
K-Spec
Crypto Algorithm
1
h
Key Length
2
h
Key Type
1
h
Terminal Key format
1
h
Host Key format
1
h
KVC format
1
h
Version Identifier
1
h
Key Usage
2
h
Mode of use
1
h
Key version number Exportability
2
h
1
h
Padding indicator
1
h
Number of optional fields Optional field 1 … n
1
h
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)
Var
h
Not present
Length 3 1
Attribute h h
KTM
Response Content EE0628 rc
© SafeNet, Inc.
D D U D U
Description Function Code Function Modifier = x0
Description Function Code Return Code
282
Mark II Programmers Guide
Chapter 22 Key Block
Terminal key
Var
h
Host key
Var
K-Spec
KVC
Var
h
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
Key length
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
© SafeNet, Inc.
Key verification code standard format
283
Mark II Programmers Guide
Version identifier
Chapter 22 Key Block ‘2’ - for Verifone key Block 00 (Null) - for binary key Block
Key usage, Mode of use, Key version number
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 type
Key usage
Mode of use
Key version number
MPK
M0
C,M,N,V
00
PPK
P0
N
00
Exportability
‘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
Optional fields
These support the optional fields of key Blocks. Currently not implemented.
SHP Toolkit MK2 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
Mark II Programmers Guide
Chapter 23 ZKA Functions
Chapter 23 ZKA Functions Summary of ZKA Functions Function Name
Function Code
Page
ZKA-IMPORT-MK
EE0210
288
ZKA-PIN-TRANS
EE0610
290
ZKA-PIN-VER
EE0611
292
ZKA-CALC-PVN
EE0612
294
ZKA-PIN-TRANS-1
EE0613
296
ZKA-MAC-GEN
EE0710
298
ZKA-MAC-GEN-1
EF0711
300
Session Key Derivation The following data is entered into the derivation of the Session Key: MK
MKLEFT
MKRIGHT
CV
CVLEFT
CVRIGHT
RND
RNDLEFT
RNDRIGHT
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
Mark II Programmers Guide
Chapter 23 ZKA Functions
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
Length 2 bits
Raw Value 4
Account Number
34 bits
8589939303
10 0000 0000 0000 0000 0001 0010 0110 0111
Card Sequence Number
4 bits
7
0111
© SafeNet, Inc.
Converted Value 10
286
Mark II Programmers Guide
Chapter 23 ZKA Functions
Last digit Expiration Year
4 bits
8
1000
PIN
20 bits
291255
0100 0111 0001 1011 0111
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
Message Authentication Functions The MAC key generation / recovery may be performed within the MAC generation / verification functions. The standard function MAC-VER-FINAL (and MAC-UPDATE if required) can be used with a received RND by utilizing the key specifier format defined above. Function ZKA-MAC-GEN generates RND and uses the associated clear MAC key to generate the MAC.
Key Management Functions This customization assumes that the session key is usually recovered or generated within the PIN or MAC function and therefore no separate key management function need be used. A key management function (ZKA-IMPORT-MK ) is provided though for the import of the ZKA Master Key.
© SafeNet, Inc.
287
Mark II Programmers Guide
Chapter 23 ZKA Functions
ZKA-IMPORT-MK
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
Request Content EE0210 FM
Length 3 1
Attribute h h
16 Var
h K-Spec
Encryption Mode (of e*KTK(K)) Key Type
1 1
h h
ICM
1
h
ICV
Var
H
Length 3 1
Attribute H H
Var
K-Spec
e*KTK(K) *KTK-Spec
Response Content EE0210 rc K-Spec
D D D D U
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)
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.
e*KTK(K)
Is the supplied key encrypted by a Key Transport Key (*KTK).
*KTK-spec
Supports only double-length HSM Mark II-stored keys. (Formats: 0 - 3)
Encryption Mode
Indicates the encryption setting used for the *KTK 00 = ECB Encryption Mode, and 01 = CBC Encryption Mode.
Key Type
© SafeNet, Inc.
Indicates the Key Type and KM variant used to encrypt for Host storage.
288
Mark II Programmers Guide
Chapter 23 ZKA Functions
ICM
The Integrity Check Method - additional integrity check methods will be added later.
ICV
The Integrity Check Value - This value is set to ‘00’ if the ICM is zero.
SHP Toolkit MK2 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
Mark II Programmers Guide
Chapter 23 ZKA Functions
ZKA-PIN-TRANS
D D D D U
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
Request Content EE0610 FM
Length 3 1
Attribute H H
8 Var
X K-Spec
PFi
1
H
ANB PFo
6 1
H H
Var
K-Spec
Length 3 1
Attribute H H
8 16
H H
ePPKi(PIN) PPKi-Spec
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
= 00. Must be set to zero.
ePPKi(PIN)
Is the input formatted PIN Block containing the PIN to be verified. It must be supplied encrypted by a PIN Protect session key (PPK).
PPKi-spec
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
PFi and PFo
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.
© SafeNet, Inc.
ANB
Account Number Block, which is the rightmost 12 digits of the Primary Account Number (PAN), excluding the check digit.
MK-spec
A Host stored (format 13) CBC key specifier incorporating an encrypted ZKA Master Key.
ePPKo(PIN)
Is the output formatted PIN Block containing the PIN to be verified. It must be supplied encrypted by a PIN Protect session key (PPK).
RNDo
Is the encrypted Session Key (Refer Session Key Derivation for details).
290
Mark II Programmers Guide
Chapter 23 ZKA Functions
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
OUT UCHAR OUT UCHAR
© SafeNet, Inc.
FM, ePPKi_PIN[8], *PPKi, PFi, ANB[6], PFo, *MK, ePPKo_PIN[8], RNDo[16]);
291
Mark II Programmers Guide
Chapter 23 ZKA Functions
ZKA-PIN-VER
D D D D U
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
Request Content EE0611 FM ePPK(PIN) PPK-Spec PF ANB *KKBLZ-Spec Account Number CSN Expiration Year PVN Type PVN Response Content EE0611 Rc
Length 3 1
Attribute H H
8 Var
X K-Spec
1
H
6 Var
H K-Spec
5 1 1 1 2 Length 3 1
D D D H D Attribute H H
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).
© SafeNet, Inc.
FM
= 00. Must be set to zero.
ePPK(PIN)
Is the input formatted PIN Block containing the PIN to be verified. It must be supplied encrypted by a PIN Protect session key (PPK).
PPK-spec
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.
PF
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).
ANB
Account Number Block, which is the rightmost 12 digits of the Primary Account Number (PAN), excluding the check digit.
*KKBLZ-spec
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.
Account No.
Is the 10 digit Account Number.
CSN
Is the Card Sequence Number.
Expiration Year
Is the last digit of the expiry year of the card.
PVN Type
0 = Complete value of X (undecimalized) in PVN. 4 = leftmost 4 digits of decimalize(X) packed in 2 bytes in PVN.
292
Mark II Programmers Guide
PVN
Chapter 23 ZKA Functions Is the PIN Verification Number, used to verify the user’s PIN.
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
Mark II Programmers Guide
Chapter 23 ZKA Functions
ZKA-CALC-PVN
D D D D U
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
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
Length 3 1
Attribute H H
8 Var
X K-Spec
1
H
6 Var
D K-Spec
5 1 1 1 Length 3 1
D D D H Attribute H H
Var 1
H H
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.
© SafeNet, Inc.
FM
= 00. Must be set to zero.
ePPK(PIN)
Is the input formatted PIN Block containing the PIN to be verified. It must be supplied encrypted by a PIN Protect session key (PPK).
PPK-spec
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.
PF
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).
ANB
Account Number Block, which is the rightmost 12 digits of the Primary Account Number (PAN), excluding the check digit.
*KKBLZ-spec
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.
Account No.
Is a 10 digit Account Number.
CSN
Is the Card Sequence Number.
294
Mark II Programmers Guide
Chapter 23 ZKA Functions
Expiration Year
Is the last digit of the expiry year of the card.
PVN Type
0 = Complete value of X (undecimalized) in PVN. 4 = leftmost 4 digits of decimalize(X) packed in 2 bytes in PVN.
PVN
Is the returned PIN Verification Number, used to verify the user’s PIN.
PINLEN
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
© SafeNet, Inc.
*PVN, *PIN_Length);
295
Mark II Programmers Guide
Chapter 23 ZKA Functions
ZKA-PIN-TRANS-1
D D D D U
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
Request Content EE0613 FM
Length 3 1
Attribute H H
8 Var
X K-Spec
PFi
1
H
ANB PFo
6 1
H H
Var
K-Spec
Length 3 1
Attribute H H
8 16 Var
H H K-Spec
ePPKi(PIN) PPKi-Spec
MK2-Spec-1
Response Content EE0613 rc ePPKo(PIN) RNDo MK2-Spec-2
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)
* 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
Mark II Programmers Guide
Chapter 23 ZKA Functions
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
© SafeNet, Inc.
ePPKo_PIN[8], RND[16], *MK2_2);
297
Mark II Programmers Guide
Chapter 23 ZKA Functions
ZKA-MAC-GEN
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
Request Content EE0710 FM
D D D D U
Length 3 1
Attribute H H
1
H
MAClen ICD MK-Spec
1 8 Var
H H K-Spec
Data
Var
H
2 Length 3 1
H Attribute H H
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
Var 16
H H
Message Authentication Code Random Number (encrypted session key)
Alg
c Response Content EE0710 rc MAC RND
Description Function Code Function Modifier = 00
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
= 00. Must be set to zero
ALG
Specifies the MACing algorithm to use For single-length MPK – this field must be zero For double-length MPK 00
ISO 9807 method
01
triple-DES CBC method
MAClength
Specifies the length of the output MAC.
ICD
Input Chaining Data, used for long message feedback.
MK-spec
A key Specifier incorporating a ZKA Master Key.
Data
The data to be MACed. Must be a multiple of 8 bytes.
C
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).
Note: ICD will normally be set equal to zero.
© SafeNet, Inc.
298
Mark II Programmers Guide
Chapter 23 ZKA Functions
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
© SafeNet, Inc.
EFTBUFFER UCHAR
*MAC, RND[16]);
299
Mark II Programmers Guide
Chapter 23 ZKA Functions
ZKA-MAC-GEN-1
D D D D U
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
Request Content EE0711 FM
Length 3 1
Attribute H H
Alg MAClen ICD MK2-Spec-1
1 1 8 Var
H H H K-Spec
Data Offset1
Var 2
H H
Offset2
2
H
Offset3
2
H
Length 3 1
Attribute H H
Var 16 Var
H H K-Spec
Response Content EE0711 rc MAC RND MK2-Spec-2
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 MAC’d 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)
* 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
= 00. Must be set to zero.
Alg
Specifies the MACing algorithm to use. 00 01
© SafeNet, Inc.
Retail MAC (ISO 9807) method triple-DES CBC method
MAClength
Specifies the length of the output MAC
MK2-Spec
A key specifier for the Master Key.
Data
The data to be MAC’d. Must be a multiple of 8 bytes.
Offset1
If zero, do not insert RND in Data, else insert RND at specified Offset1 (01 indicates insert at leftmost byte of Data.)
Offset2
If zero, do not insert Version Number in Data, else insert Version Number at specified Offset2 (01 indicates insert at leftmost byte of Data.)
300
Mark II Programmers Guide
Offset3
Chapter 23 ZKA Functions
If zero, do not insert Generation Number in Data, else insert Generation Number at specified Offset3 (1 indicates insert at leftmost byte of Data.)
Note: ICD will normally be set equal to zero.
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
© SafeNet, Inc.
*MAC, RND[16], *MK2_2);
301
Mark II Programmers Guide
© SafeNet, Inc.
Chapter 23 ZKA Functions
302
Mark II Programmers Guide
Chapter 24 Administration Functions
Chapter 24 Administration Functions GetKVC
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
Request Content EEBF29 FM
Key Type
D D U D U
Length
Attribute
3 1
h x
Function Code Function Modifier = 00
h
00 = Get details on specified Key or 01 = Get details on next Key Key Type (decimal)
2
Description
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
© SafeNet, Inc.
303
Mark II Programmers Guide
Chapter 24 Administration Functions
Request Content
KVCType
Index
Length
2
2
Attribute
h
h
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
Response Content EEBF29 rc KeyLen
KeyType
Length
Attribute
2 1 2
h x h
Function Code Return Code Key Length of specified Key
h
8 – single length 16 – double length 24 – triple length Key Table Type
2
01 02 =
Description
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
© SafeNet, Inc.
USHORT *KeyLen, USHORT *KeyType, USHORT *IndexOut, EFTBUFFER *KVC);
304
Mark II Programmers Guide
Chapter 25 ABI Debit Card Functions
Chapter 25 ABI Debit Card Functions PIN_Generation
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
Request Content EF0616 FM ABI PAN Check Digit eKMv7(PVK) DT PF PPK-Spec Response Content EF0616 rc ePPK(PIN)
Length 3 1
Attribute h h
5
d
12 1 Var
d d K-Spec
8 1
d h
Var
K-Spec
Length 3 1
Attribute h h
8
h
D D D D U
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
© SafeNet, Inc.
UCHAR
ePPK[8]);
305
Mark II Programmers Guide
Chapter 25 ABI Debit Card Functions
Auth_Param_Generate
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
Request Content EF0617 FM
D D D D U
Length 3 1
Attribute h h
Var
K-Spec
8 5
h d
Card Secure Code PAN Data DPK-Spec
8 12 Var
d d K-Spec
Response Content EF0617 rc
Length 3 1
Attribute h h
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
8
ASCII Or ePDK(Data)
Encrypted form if AP encryption key identifier specified, otherwise returned in plain text ASCII
PPK ePPK(PIN) Issuer Domestic Code
AP Value
Description Function Code Function Modifier = 00
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
© SafeNet, Inc.
UCHAR
AP_value[8]);
306
Mark II Programmers Guide
Chapter 25 ABI Debit Card Functions
Random_Key_Generation
D D D D U
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
Request Content EF0618 FM KF KMVar Response Content EF0618 rc eKMvX(Key)
Length 3 1
Attribute h h
1
h
1 Length 3 1
h Attribute h h
Var
K-Spec
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(
© SafeNet, Inc.
IN IN IN
UCHAR UCHAR UCHAR
FM, KF, KMVar,
OUT
KEYSPEC
*encypted_Random_Key);
307
Mark II Programmers Guide
© SafeNet, Inc.
Chapter 25 ABI Debit Card Functions
308
Mark II Programmers Guide
Chapter 26 Superceded Functions
Chapter 26 Superceded Functions IT-PPK-GEN
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
Request Content 41
Length 1
Attribute H
Description Function Code
n Response Content 41 rc
1 Length 1 1
D Attribute H H
KTM Index Description Function Code Return Code
8 8
B64 B64
PIN Protect Key PIN Protect Key
eKTMn(PPK) eKMv1(PPK)
D D U U U
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 • •
© SafeNet, Inc.
This function is superceded by function EE0400 This function only supports use of the first 99 KTMs.
309
Mark II Programmers Guide
Chapter 26 Superceded Functions
IT-MPK-GEN
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
Request Content 42
Length 1
Attribute H
Description Function Code
n Response Content 42 rc
1 Length 1 1
D Attribute H H
KTM Index Description Function Code Return Code
8 8
B64 B64
eKTMn(MPK) eKMv2(MPK)
D D U U U
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
Mark II Programmers Guide
Chapter 26 Superceded Functions
IT-DPK-GEN
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
Request Content 43
Length 1
Attribute H
Description Function Code
n Response Content 43 rc
1 Length 1 1
D Attribute H h
KTM Index Description Function Code Return Code
8 8
B64 B64
eKTMn(DPK) eKM(DPK)
D D U U U
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
Mark II Programmers Guide
Chapter 26 Superceded Functions
NT-PPK-GEN
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
Request Content 44
Length 1
Attribute h
Description Function Code
eKMv1(PPKn) Response Content 44 rc
8 Length 1 1
B64 Attribute h h
PIN Protect Key Description Function Code Return Code
ePPKn(PPKn+1) eKMv1(PPKn+1)
8 8
B64 B64
PIN Protect Key PIN Protect Key
D D U U U
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
Mark II Programmers Guide
Chapter 26 Superceded Functions
NT-MPK-GEN
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
Request Content 45
Length 1
Attribute h
Description Function Code
eKMv2(MPKn) Response Content 45 rc
8 Length 1 1
B64 Attribute h h
MAC Protect Key Description Function Code Return Code
eMPKn(MPKn+1) eKMv2(MPKn+1)
8 8
B64 B64
MAC Protect Key MAC Protect Key
D D U U U
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
Mark II Programmers Guide
Chapter 26 Superceded Functions
NT-DPK-GEN
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
Request Content 46
Length 1
Attribute h
Description Function Code
eKM(DPKn) Response Content 46 rc
8 Length 1 1
B64 Attribute h h
Data Protect Key Description Function Code Return Code
8 8
B64 B64
Data Protect Key Data Protect Key
eDPKn(DPKn+1) eKM(DPKn+1)
D D U U U
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
Mark II Programmers Guide
Chapter 26 Superceded Functions
GEN_SESS_KEYS
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
Request Content 4A KTM-Spec Key Flags Response Content 4A rc 1
eKTM(KS) eKMx(KS)
1 1
Length 1
Attribute h
Var
K-Spec
2 Length 1 1
h Attribute h h
8 8
B64 B64
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
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
A key specifier which incorporates an index to an HSM-stored KTM.
Key Flags
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
session key type
0 1 2 3-15
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 X’0004’;
•
To generate a single-length PIN encrypting key and a MAC key, the field must be set to X’0006’.
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
Mark II Programmers Guide
Chapter 26 Superceded Functions
TERM-VER
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
Request Content 4C
Length 1
Attribute h
Description Function Code
n SEC-No Logon-Data Response Content 4C rc
1 8 8 Length 1 1
d h h Attribute h h
KTM Index Security Number Logon Data Description Function Code Return Code
D D U U U
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 •
© SafeNet, Inc.
This function is superceded by function EE0406.
316
Mark II Programmers Guide
Chapter 26 Superceded Functions
II-PPK-GEN
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
Request Content 51
Length 1
Attribute h
Description Function Code
n Response Content 51 rc
1 Length 1 1
d Attribute h h
KIS Index Description Function Code Return Code
8 8
B64 B64
PIN Protect Key PIN Protect Key
eKISnv1(PPK) eKMv1(PPK)
D D U U U
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.
eKMv1(PPK)
is the host stored session key encrypted under variant 1 of the KM.
NOTE • •
© SafeNet, Inc.
This function will check the length of KISn and use the appropriate encryption method. This function is superceded by function EE0402.
317
Mark II Programmers Guide
Chapter 26 Superceded Functions
II-MPK-GEN
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
Request Content 52
Length 1
Attribute h
Description Function Code
n Response Content 52 rc
1 Length 1 1
d Attribute h h
KIS Index Description Function Code Return Code
8 8
B64 B64
eKISnv2(MPK) eKMv2(MPK)
D D U U U
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)
is the session key encrypted under variant 1 of KISn. The variant is determined by the variant scheme associated with KISn.
eKMv2(MPK)
is the host stored session key encrypted under variant 1 of the KM.
NOTE • •
© SafeNet, Inc.
This function will check the length of KISn and use the appropriate encryption method. This function is superceded by function EE0402.
318
Mark II Programmers Guide
Chapter 26 Superceded Functions
II-DPK-GEN
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
Request Content 53
Length 1
Attribute h
Description Function Code
n Response Content 53 rc
1 Length 1 1
d Attribute h h
KIS Index Description Function Code Return Code
8 8
B64 B64
eKISn(DPK) eKM(DPK)
D D U U U
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)
is the session key encrypted under KISn.
eKM(DPK)
is the host stored session key encrypted under the KM.
NOTE • • • •
© SafeNet, Inc.
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.
319
Mark II Programmers Guide
Chapter 26 Superceded Functions
II-PPK-RCV
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
Request Content 54
Length 1
Attribute h
Description Function Code
n eKIRnv1(PPK) Response Content 54 rc
1 8 Length 1 1
d B64 Attribute h h
KIR Index PIN Protect Key Description Function Code Return Code
8
B64
PIN Protect Key
eKMv1(PPK)
D D U U U
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)
is the session key encrypted under variant 1 of KIRn. The variant is determined by the variant scheme associated with KIRn.
eKMv1(PPK)
is the host stored session key encrypted under variant 1 of the KM.
NOTE • •
© SafeNet, Inc.
This function will check the length of KIRn and use the appropriate encryption method. This function is superceded by function EE0403.
320
Mark II Programmers Guide
Chapter 26 Superceded Functions
II-MPK-RCV
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
Request Content 55
Length 1
Attribute h
Description Function Code
n eKIRnv2(MPK) Response Content 55 rc
1 8 Length 1 1
d B64 Attribute h h
KIR Index MAC Protect Key Description Function Code Return Code
8
B64
MAC Protect Key
eKMv2(MPK)
D D U U U
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)
is the session key encrypted under variant 2 of KIRn. The variant is determined by the variant scheme associated with KIRn.
eKMv2(MPK)
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
Mark II Programmers Guide
Chapter 26 Superceded Functions
II-DPK-RCV
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
Request Content 56
Length 1
Attribute h
Description Function Code
n eKIRn(DPK) Response Content 56 rc
1 8 Length 1 1
d B64 Attribute h h
KIR Index Data Protect Key Description Function Code Return Code
8
B64
Data Protect Key
eKM(DPK)
D D U U U
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)
is the session key encrypted under KIRn.
eKM(DPK)
is the host stored session key encrypted under the KM.
NOTE • • • •
© SafeNet, Inc.
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.
322
Mark II Programmers Guide
Chapter 26 Superceded Functions
NI-PPK-GEN
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
Request Content 57
Length 1
Attribute h
Description Function Code
eKMv1(PPKn) Response Content 57 rc
8 Length 1 1
B64 Attribute h h
PIN Protect Key Description Function Code Return Code
ePPKn(PPKn+1) eKMv1(PPKn+1)
8 8
B64 B64
PIN Protect Key PIN Protect Key
D D U U U
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 •
© SafeNet, Inc.
This function is superceded by function EE0404.
323
Mark II Programmers Guide
Chapter 26 Superceded Functions
NI-MPK-GEN
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
Request Content 58
Length 1
Attribute h
Description Function Code
eKMv2(MPKn) Response Content 58 rc
8 Length 1 1
B64 Attribute h h
MAC Protect Key Description Function Code Return Code
eMPKn(MPKn+1) eKMv2(MPKn+1)
8 8
B64 B64
MAC Protect Key MAC Protect Key
D D U U U
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 •
© SafeNet, Inc.
This function is superceded by function EE0404.
324
Mark II Programmers Guide
Chapter 26 Superceded Functions
NI-DPK-GEN
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
Request Content 59
Length 1
Attribute h
Description Function Code
eKM(DPKn) Response Content 59 rc
8 Length 1 1
B64 Attribute h h
Data Protect Key Description Function Code Return Code
8 8
B64 B64
Data Protect Key Data Protect Key
eDPKn(DPKn+1) eKM(DPKn+1)
D D U U U
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 •
© SafeNet, Inc.
This function is superceded by function EE0404.
325
Mark II Programmers Guide
Chapter 26 Superceded Functions
NI-PPK-RCV
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
Request Content 5A
Length 1
Attribute h
Description Function Code
eKMv1(PPKn) ePPKn(PPKn+1) Response Content 5A rc
8 8 Length 1 1
B64 B64 Attribute h h
PIN Protect Key PIN Protect Key Description Function Code Return Code
eKMv1(PPKn+1)
8
B64
PIN Protect Key
D D U U U
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 •
© SafeNet, Inc.
This function is superceded by function EE0405.
326
Mark II Programmers Guide
Chapter 26 Superceded Functions
NI-MPK-RCV
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
Request Content 5B
Length 1
Attribute h
Description Function Code
eKMv2(MPKn) eMPKn(MPKn+1) Response Content 5B rc
8 8 Length 1 1
B64 B64 Attribute h h
MAC Protect Key MAC Protect Key Description Function Code Return Code
eKMv2(MPKn+1)
8
B64
MAC Protect Key
D D U U U
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 •
© SafeNet, Inc.
This function is superceded by function EE0405.
327
Mark II Programmers Guide
Chapter 26 Superceded Functions
NI-DPK-RCV
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
Request Content 5C
Length 1
Attribute h
Description Function Code
eKM(DPKn) eDPKn(DPKn+1) Response Content 5C rc
8 8 Length 1 1
B64 B64 Attribute h h
Data Protect Key Data Protect Key Description Function Code Return Code
8
B64
Data Protect Key
eKM(DPKn+1)
D D U U U
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 •
© SafeNet, Inc.
This function is superceded by function EE0405.
328
Mark II Programmers Guide
Chapter 26 Superceded Functions
PIN-TRAN
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
Request Content 60 PFi, PFo ePPKi(PIN) eKMv1(PPKi) eKMv1(PPKo) ANB Response Content 60 rc ePPKo(PIN)
Length 1
Attribute h
1
h
8 8 8 6 Length 1 1
h B64 B64 h Attribute h h
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
8
B64
PIN encrypted under PPKo
D D U U U
Description Function Code
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.
ANB
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 Pfi or PFo indicates a PIN block format that is disabled or conflicts with the reformatting restrictions.
NOTE •
© SafeNet, Inc.
This function is superceded by function EE0602.
329
Mark II Programmers Guide
Chapter 26 Superceded Functions
PIN-VER-IBM-ANSI
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
Request Content 61
Length 1
Attribute h
Description Function Code
PVK-Index ePPK(AS-PIN) eKMv1(PPK) PAN ANB Offset Response Content 61 rc
1 8 8 8 6 6 Length 1 1
d B64 B64 h h h Attribute h h
Index of PVK PIN Protect Key Encrypted PPK Primary Account Number Account Number Block PIN Offset Data Description Function Code Return Code
D D U U U
This function performs the verification of a PIN in an AS/ANSI formatted PIN Block, using the IBM 3624 method. PVK-Index
identifies the PVKn, DTn, and MINPINn appropriate to the PIN verification procedure.
AS-PIN
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).
PAN
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.
ANB
is the 12-digit Account Number Block used in the formation of the clear AS/ANSI PIN Block.
Offset
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 •
© SafeNet, Inc.
This function is superceded by function EE0603.
330
Mark II Programmers Guide
Chapter 26 Superceded Functions
PIN-VER-PP
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
Request Content 62
Length 1
Attribute h
Description Function Code
PVK-Index ePPK(PP-PIN) eKMv1(PPK) PAN Offset Response Content 62 rc
1 8 8 8 6 Length 1 1
d B64 B64 h h Attribute h h
Index of PVK Encrypted PIN Block Encrypted PPK Primary Account Number PIN Offset Data Description Function Code Return Code
D D U U U
This function verifies a PIN in a PIN/PAD formatted PIN Block using the IBM 3624 method. PVK-Index
identifies the PVKn, DTn, and MINPINn appropriate to the PIN verification procedure.
PP-PIN
is the formatted PIN Block containing the PIN to be verified. It must be supplied encrypted by a PIN Protect session key (PPK).
PAN
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.
Offset
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 •
© SafeNet, Inc.
This function is superceded by function EE0603.
331
Mark II Programmers Guide
Chapter 26 Superceded Functions
D51-PIN-TRAN
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
Request Content 65
Length 1
Attribute h
Description Function Code
ePPKi, PPKo(51-PIN) eKMv1(PPKi) eKMv1(PPKo) ANB Response Content 65 rc
8 8 8 6 Length 1 1
B64 B64 B64 h Attribute h h
Encrypted PIN Block Encrypted Input PPK Encrypted Output PPK Account Number Block Description Function Code Return Code
8
B64
ePPKo(AS-PIN)
D D U U U
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.
PPKi
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.
ANB
is the 12-digit Account Number Block used in the formation of the clear AS/ANSI PIN Block.
AS-PIN
is the resultant AS/ANSI formatted PIN Block.
The function will fail with Error Code 78 if the Docutel or ANSI/ISO 0 PIN block format is disabled.
NOTE •
© SafeNet, Inc.
This function is superceded by function EE0602.
332
Mark II Programmers Guide
Chapter 26 Superceded Functions
D51-PIN-VER
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
Request Content 66
Length 1
Attribute h
Description Function Code
PVK-Index ePPK(D51-PIN) eKMv1(PPK) PAN Offset Response Content 66 rc
1 8 8 8 6 Length 1 1
d B64 B64 h h Attribute h h
Index of PVK Encrypted PIN Block Encrypted PPK Primary Account Number PIN Offset Data Description Function Code Return Code
D D U U U
This function performs the verification of a PIN in a DOCUTEL 5100 formatted PIN Block, using the IBM 3624 method. PVK-Index
identifies the PVKn, DTn, and MINPINn appropriate to the PIN verification procedure.
D51-PIN
is the DOCUTEL 5100 formatted PIN Block containing the PIN to be verified. It must be supplied encrypted by a PIN Protect Key (PPK).
PAN
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.
Offset
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 •
© SafeNet, Inc.
This function is superceded by function EE0603.
333
Mark II Programmers Guide
Chapter 26 Superceded Functions
VAR-PIN-VER
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
Request Content 67
Length 1
Attribute h
Description Function Code
PVK-Index ePPK(AS-PIN) eKMv1(PPK) PAN ANB CHKLEN Offset Response Content 67 rc
1 8 8 8 6 1 6 Length 1 1
d B64 B64 h h h h Attribute h h
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
D D U U U
This function verifies an AS/ANSI formatted PIN. The PIN Block must be supplied encrypted under a PIN Protect Key (PPK). PVK-index
identifies the PVKn, DTn, and MINPINn appropriate to the PIN verification procedure.
AS-PIN
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).
PAN
the Primary Account Number used in the verification procedure. It must be padded appropriately prior to input to this function.
ANB
is the 12-digit Account Number Block used in the formation of the clear AS/ANSI PIN Block.
CHKLEN
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.
Offset
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.
See Appendix A IBM 3624 PIN Verification Method for a more detailed overview of the PIN verification procedure.
NOTE •
© SafeNet, Inc.
This function is superceded by function EE0603.
334
Mark II Programmers Guide
Chapter 26 Superceded Functions
VAR-PIN-VER-PP
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
Request Content 68
Length 1
Attribute h
PVK-Index ePPK(PP-PIN)
1 8
d B64
eKMv1(PPK) PAN CHKLEN
8 8 1
B64 h h
6 Length 1 1
h Attribute h h
Offset Response Content 68 rc
D D U U U
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
identifies the PVKn, DTn, and MINPINn appropriate to the PIN verification procedure.
PAN
the Primary Account Number used in the verification procedure. It must be padded appropriately prior to input to this function.
CHKLEN
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.
Offset
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 PIN/Pad PIN block format is disabled.
See Method for a more detailed overview of the PIN verification procedure.
NOTE •
© SafeNet, Inc.
This function is superceded by function EE0603.
335
Mark II Programmers Guide
Chapter 26 Superceded Functions
PIN-OFF-AS
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
Request Content 6A PVK-Index ePPK(AS-PIN) eKMv1(PPK) PAN ANB Response Content 6A rc Offset PINLEN
Length
Attribute
1
h
1 8 8 8 6 Length 1 1
d B64 B64 h h Attribute h h
6 1
h h
D D U U U
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
identifies the PVKn, DTn, and MINPINn appropriate to the PIN verification procedure.
AS-PIN
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).
PAN
the Primary Account Number used in the verification procedure. It must be padded appropriately prior to input to this function.
ANB
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 •
© SafeNet, Inc.
This function is superceded by function EE0604.
336
Mark II Programmers Guide
Chapter 26 Superceded Functions
PIN-OFF-PP
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
Request Content 6B
Length 1
Attribute h
PVK-Index ePPK(PP-PIN)
1 8
d B64
8 8 Length 1 1
B64 h Attribute h h
Index of PVK PIN/PAD formatted PIN Block Encrypted PPK Primary Account Number Description Function Code Return Code
6 1
h h
Returned PIN Offset Data Returned PIN Length
eKMv1(PPK) PAN Response Content 6B rc Offset PINLEN
D D U U U
Description Function 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). 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
identifies the PVKn, DTn, and MINPINn appropriate to the PIN verification procedure.
PAN
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 •
© SafeNet, Inc.
This function is superceded by function EE0604.
337
Mark II Programmers Guide
Chapter 26 Superceded Functions
MAC-GEN
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
Request Content 70
Length 1
Attribute h
Description Function Code
Blocks eKMv2(MPK) Data Response Content 70 rc
1 8 Bks*8 Length 1 1
h B64 h Attribute h h
No of 8 byte Blocks Encrypted MPK Must be a multiple of 8 Bytes Description Function Code Return Code
4
h
Message Authentication Code
MAC
D D U U U
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 •
© SafeNet, Inc.
This function is superceded by function EE0701.
338
Mark II Programmers Guide
Chapter 26 Superceded Functions
MAC-TRAN
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
Request Content 71
Length 1
Attribute h
Blocks eKMv2(MPKi) eKMv2(MPKo) Data MACi
1 8 8 bks*8 4
h B64 B64 h h
Response Content 71 rc
Length 1 1
Attribute h h
4
h
MACo
D D U U U
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 •
© SafeNet, Inc.
This function is superceded by function EE0701.
339
Mark II Programmers Guide
Chapter 26 Superceded Functions
MAC-VER
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
Request Content 72
Length 1
Attribute h
Blocks eKMv2(MPKi) Data
1 8 bks*8
h B64 h
4
h
Length 1 1
Attribute h h
MAC Response Content 72 rc
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 •
© SafeNet, Inc.
This function is superceded by function EE0701.
340
Mark II Programmers Guide
Chapter 26 Superceded Functions
ENCIPHER
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
Request Content 80
Length 1
Attribute h
Blocks eKM(DPK) Data
1 8 bks*8
h B64 h
Response Content 80 rc
Length 1 1
Attribute h h
eDPK(Data)
bks*8
B64
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 X’555555555555555555.
NOTE •
© SafeNet, Inc.
This function is superceded by function EE0800.
341
Mark II Programmers Guide
Chapter 26 Superceded Functions
DECIPHER
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
Request Content 81
Length 1
Attribute h
Blocks eKM(DPK) eDPK(Data)
1 8 bks*8
h B64 B64
Response Content 81 rc
Length 1 1
Attribute h h
Data
bks*8
h
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 X’555555555555555555.
NOTE •
© SafeNet, Inc.
This function is superceded by function EE0801.
342
Mark II Programmers Guide
Chapter 26 Superceded Functions
ENCIPHER-ECB
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
Request Content 82
Length 1
Attribute h
Description Function Code
Blocks eKM(DPK) Data Response Content 82 rc
1 8 bks*8 Length 1 1
h B64 h Attribute h h
No of 8 byte Blocks Data Protect Key Must be multiple of 8 bytes Description Function Code Return Code
eDPK(Data)
bks*8
B64
Data encrypted under DPK
D D U U U
This function encrypts the supplied DATA under the supplied Data Protect Key (DPK), using the DES in Electronic Code Book mode.
NOTE •
© SafeNet, Inc.
This function is superceded by function EE0800.
343
Mark II Programmers Guide
Chapter 26 Superceded Functions
DECIPHER-ECB
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
Request Content 83
Length 1
Attribute h
Blocks eKM(DPK) eDPK(Data)
1 8 bks*8
h B64 B64
Response Content 83 rc
Length 1 1
Attribute h h
Data
bks*8
h
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 •
© SafeNet, Inc.
This function is superceded by function EE0801.
344
Mark II Programmers Guide
Chapter 26 Superceded Functions
PVV-GEN-1
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
Request Content 90 PVK-Index PAN Offset4 TSP12 Response Content 90 rc PVV
Length 1
Attribute h
1 8 2 6
d h h h
Length 1 1
Attribute h h
2
h
D D U U U
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
is the 16-digit field which is encrypted using PVKn and decimalized using DECTABn to produce the leftmost four digits of the derived PIN.
Offset4
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.
TSP12
is the leftmost 12 digits of the TSP and consists of 11 PAN digits followed by the appropriate one digit PVKI.
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 •
© SafeNet, Inc.
This function is superceded by function EE0606.
345
Mark II Programmers Guide
Chapter 26 Superceded Functions
PVV-VER-1
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
Request Content 91
Length 1
Attribute h
eIWK(AS-PIN) ANB TSP12
8 6 6
B64 h h
2 Length 1 1
h Attribute h h
PVV Response Content 91 rc
D D U U U
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
is the AS 2805.3 1985 formatted PIN Block containing the PIN to be verified.
ANB
is the 12-digit Account Number Block (a PAN element of the clear PIN Block).
TSP12
is the leftmost 12 digits of the TSP and consists of 11 PAN digits followed by the appropriate one digit PVKI.
PVV
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 •
© SafeNet, Inc.
This function is superceded by function EE0605.
346
Mark II Programmers Guide
Chapter 26 Superceded Functions
PVV-VER-2
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
Request Content 92
Length 1
Attribute h
ePPK(AS-PIN) eKMv1(PPK) ANB TSP12
8 8 6 6
B64 B64 h h
2 Length 1 1
h Attribute h h
PVV Response Content 92 rc
D D U U U
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
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).
ANB
is the 12-digit Account Number Block (a PAN element of the clear PIN Block).
TSP12
is the leftmost 12 digits of the TSP and consists of 11 PAN digits followed by the appropriate one digit PVKI.
PVV
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 •
© SafeNet, Inc.
This function is superceded by function EE0605.
347
Mark II Programmers Guide
Chapter 26 Superceded Functions
PVV-VER-3
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
Request Content 93
Length 1
Attribute h
ePPK(PP-PIN) eKMv1(PPK) TSP12
8 8 6
B64 B64 h
2 Length 1 1
h Attribute h h
PVV Response Content 93 rc
D D U U U
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
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).
TSP12
is the leftmost 12 digits of the TSP and consists of 11 PAN digits followed by the appropriate one digit PVKI.
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.
PVV
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 PIN/Pad PIN block format is disabled.
NOTE •
© SafeNet, Inc.
This function is superceded by function EE0605.
348
Mark II Programmers Guide
Chapter 26 Superceded Functions
PIN-TRAN-1
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
Request Content 94
Length 1
Attribute h
Description Function Code
ePPK(PIN) eKMv1(PPK) Response Content 94 rc
8 8 Length 1 1
B64 B64 Attribute h h
Encrypted PIN Block PIN Protect Key Description Function Code Return Code
8
B64
eAWK(PIN)
D D U U U
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 •
© SafeNet, Inc.
This function is superceded by function EE0602.
349
Mark II Programmers Guide
Chapter 26 Superceded Functions
PIN-TRAN-2
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
Request Content 95
Length 1
Attribute h
Description Function Code
eIWK(PIN) eKMv1(PPK) Response Content 95 rc
8 8 Length 1 1
B64 B64 Attribute h h
Encrypted PIN Encrypted PPK Description Function Code Return Code
8
B64
Encrypted PIN
ePPK(PIN)
D D U U U
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 •
© SafeNet, Inc.
This function is superceded by function EE0602.
350
Mark II Programmers Guide
Chapter 26 Superceded Functions
PVV-GEN-2
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
Request Content 96 PVVK-Index PVK-Index PAN Offset 4 TSP12 Response Content 96 rc PVV
Length 1
Attribute h
1 1 8 2 6
d d h h h
Length 1 1
Attribute h h
2
h
D D U U U
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
identifies the PVK-A/B pair that is to be used in the derivation of the PIN and must be in BCD format.
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
is the 16-digit field which is encrypted using PVKn and decimalized using DECTABn to produce the leftmost four digits of the derived PIN.
Offset4
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.
TSP12
is the leftmost 12 digits of the TSP and consists of 11 PAN digits followed by the appropriate one digit PVKI.
NOTE •
© SafeNet, Inc.
This function is superceded by function EE0606.
351
Mark II Programmers Guide
Chapter 26 Superceded Functions
PVV-VER-4
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
Request Content 97
Length 1
Attribute h
PVVK-Index eIWK(AS-PIN) ANB TSP12
1 8 6 6
d B64 h h
2 Length 1 1
h Attribute h h
PVV Response Content 97 rc
D D U U U
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
identifies the PVK-A/B pair, which are to be used in the derivation of the PVV and must be in BCD format.
AS-PIN
is the AS2805.3 1985 formatted PIN Block containing the PIN to be verified.
ANB
is the 12-digit Account Number Block (a PAN element of the clear PIN Block).
TSP12
is the leftmost 12 digits of the TSP and consists of 11 PAN digits followed by the appropriate one digit PVKI.
PVV
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 •
© SafeNet, Inc.
This function is superceded by function EE0605.
352
Mark II Programmers Guide
Chapter 26 Superceded Functions
PVV-VER-5
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
Request Content 98
Length 1
Attribute h
PVVK-Index ePPK(AS-PIN) eKMv1(PPK) ANB TSP12
1 8 8 6 6
d B64 B64 h h
2 Length 1 1
h Attribute h h
PVV Response Content 98 rc
D D U U U
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
identifies the PVK-A/B pair, which are to be used in the derivation of the PVV and must be in BCD format.
AS-PIN
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).
ANB
is the 12-digit Account Number Block (a PAN element of the clear PIN Block).
TSP12
is the leftmost 12 digits of the TSP and consists of 11 PAN digits followed by the appropriate one digit PVKI.
PVV
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 •
© SafeNet, Inc.
This function is superceded by function EE0605.
353
Mark II Programmers Guide
Chapter 26 Superceded Functions
PVV-VER-6
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
Request Content 99
Length 1
Attribute h
PVVK-Index ePPK(PP-PIN) eKMv1(PPK) TSP12
1 8 8 6
d B64 B64 h
2 Length 1 1
h Attribute h h
PVV Response Content 99 rc
D D U U U
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
identifies the PVK-A/B pair that is to be used in the derivation of the PVV and must be in BCD format.
PP-PIN
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).
TSP12
is the leftmost 12 digits of the TSP and consists of 11 PAN digits followed by the appropriate one digit PVKI.
PVV
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 •
© SafeNet, Inc.
This function is superceded by function EE0605.
354
Mark II Programmers Guide
Chapter 26 Superceded Functions
PVV-CHANGE
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
Request Content 9A
Length 1
Attribute h
PVVK-Index ePPK(AS-PIN) eKMv1(PPK) ANB TSP12
1 8 8 6 6
d B64 B64 h h
Length 1 1
Attribute h h
Index of PVVK Encrypted PIN Block Encrypted PPK Account Number Block Transformed Security Parameter Description Function Code Return Code
2
h
PIN Verification Value
Response Content 9A rc PVV
D D U U U
Description Function Code
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
identifies the PVK-A/B pair, which are to be used in the derivation of the PVV and must be in BCD format.
AS-PIN
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).
ANB
is the 12-digit Account Number Block (a PAN element of the clear PIN Block).
TSP12
is the leftmost 12 digits of the TSP and consists of 11 PAN digits followed by the appropriate one digit PVKI.
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 •
© SafeNet, Inc.
This function is superceded by function EE0607.
355
Mark II Programmers Guide
Chapter 26 Superceded Functions
CVV-GEN
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
Request Content 9B CVK-Index CVV-Data Response Content 9B rc CVV
Length 1
Attribute h
1 16
d h
Length 1 1
Attribute h h
Index of CVK Card Verification Value Data Description Function Code Return Code
2
h
Card Verification Value
D D U U U
Description Function Code
This function generates a Card Verification Value (CVV) by the Visa method for card data (CVVdata). CVK-Index
A one byte BCD field that indicates which HSM stored CVK-A/B pair to use in the CVV generation process.
CVV-Data
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.
CVV
The three digit Card Verification Value. The three digits are left aligned and right padded with the hexadecimal digit "F".
NOTE •
© SafeNet, Inc.
This function is superceded by function EE0802.
356
Mark II Programmers Guide
Chapter 26 Superceded Functions
CVV-VER
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
Request Content 9C CVK-Index CVV-Data CVV Response Content 9C rc
Length 1
Attribute h
1 16
d h
2 Length 1 1
h Attribute h h
D D U U U
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
is a one byte BCD field which indicates which HSM stored CVK-A/B pair to use in the CVV generation process.
CVV-Data
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.
CVV
is the digit byte Card Verification Value. The three digits are left aligned and right padded with the hexadecimal digit "F".
NOTE •
© SafeNet, Inc.
This function is superceded by function EE0803.
357
Mark II Programmers Guide
© SafeNet, Inc.
Chapter 26 Superceded Functions
358
Mark II Programmers Guide
Chapter 27 MasterCard PayPass and Visa payWave
Chapter 27 MasterCard PayPass and Visa payWave Summary of MasterCard PayPass and Visa payWave Functions: Function Name
Function Code
Page
CVC3_GENERATE
EE0010
360
CVC3_VERIFY
EE0011
361
dCVV_GENERATE
EE0014
362
dCVV_VERIFY
EE0015
364
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
Mark II Programmers Guide
Chapter 27 MasterCard PayPass and Visa payWave
CVC3_GENERATE
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
Request Content EE0010 FM
Length 3 1
Attribute h h
IMKCVC3
Var
K-Spec
PAN Data IV Mode
Var 1
h h
IV Data
Var
x
4 2 Length 3 1
x x Attribute h h
2
h
UN ATC Response Content EE0010 Rc CVC3
U D U U U
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
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
Mark II Programmers Guide
Chapter 27 MasterCard PayPass and Visa payWave
CVC3_VERIFY
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
Request Content EE0011 FM
Length 3 1
Attribute h h
IMKCVC3
Var
K-Spec
PAN Data IV Mode
Var 1
h h
IV Data
Var
x
UN ATC CVC3 Response Content EE0011 Rc
4 2 2 Length
x x h Attribute
3 1
h h
U D U U U
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
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
Mark II Programmers Guide
Chapter 27 MasterCard PayPass and Visa payWave
dCVV_GENERATE
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
Request Content Length EE0014 3 FM
Attribute h
U D U U U
Description Function Code
1
h
Function Modifier = 00.
IMKCVC-Spec
Var
K-spec
Key specifier for IMKCVC (Formats 0 – 3, 11, 13)
PAN Data
Var
h
16 Length
h Attribute
Description
Function Code
3
h
= EE0014.
Return Code
1
h
CVV
2
h
CVV Data Response Content
PAN || PAN Sequence No.
Card Verification Value
This function generates a CVV for the virtual mag stripe data (CVV Data). FM
Function Modifier. Must be set to zero.
IMKCVC-spec
A key specifier which incorporates an index to a HSM-stored double length key or a host-stored double-length key.
PAN Data
PAN || PAN Sequence No. Length in range 6 -16 bytes, representing 12 -32 digits.
CVV Data
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 of packed BCD are left- aligned and right-padded with the hexadecimal digit ‘F’.
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
Processing
<16 digits
Left-padded with zeros.
=16 digits
Used as is.
>16 digits
Hashed and decimalized.
© SafeNet, Inc.
362
Mark II Programmers Guide
Chapter 27 MasterCard PayPass and Visa payWave
2. Derive MK: MK1 = DES3(IMKCVC)[PAN Data]
MK2= DES3(IMKCVC)[PAN Data XOR (‘FF’||‘FF’||‘FF’||‘FF’||‘FF’||‘FF’||‘FF’||‘FF’)] MK= (MK1 || MK2) 3. Calculate CVV using MK and CVV Data. (The method is identical to that in function EE0802.)
© SafeNet, Inc.
363
Mark II Programmers Guide
Chapter 27 MasterCard PayPass and Visa payWave
dCVV_VERIFY
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
Request Content Length EE0015 3 FM
Attribute h
Description Function Code
1
h
Function Modifier = 00.
IMKCVC-spec
Var
K-spec
Key specifier for IMKCVC (Formats 0 – 3, 11, 13)
PAN Data
Var
h
PAN || PAN Sequence No.
CVV Data
16
h
CVV 2 Response Content Length Function Code 3 Return Code
1
h Attribute h
U D U U U
Card Verification Value Description = EE0015
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
Function Modifier. Must be set to zero.
IMKCVC-spec
A key specifier which incorporates an index to a HSM-stored double length key or a host-stored double-length key.
PAN Data
PAN || PAN Sequence No. Length in range 6 -16 bytes, representing 12 -32 digits.
CVV Data
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 of packed BCD are leftaligned and right-padded with the hexadecimal digit ‘F’.
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
Mark II Programmers Guide
Chapter 28 Network Key Transfer
Chapter 28 Network Key Transfer Summary of Network Key Transfer Functions: Function Name
Function Code
Page
Key Package Status
EE3102
366
Export Keys Package
EE3103
367
Import Key Package
EE3104
368
Network Key Transfer The Network Key Transfer functions provide support for transfer of a set of HSM-stored keys from one HSM, via the host network, to an HSM at a remote location. This new key transfer method provides a solution to the problem of distributed key management on Mark II HSMs. Note: The Network Key transfer functions are disabled by default on HSM.
New Key The Network Key Transfer functionality introduces the Host Tranfer Key (KHT).
© SafeNet, Inc.
365
Mark II Programmers Guide
Chapter 28 Network Key Transfer
Key Package Status
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
U D U U U
Request Content EE3102 FM
Length 1 1
Attribute h h
Description Function Code Function Modifier = 00
Response Content EE3102 rc Status
Length 1 1 1
Attribute h h h
4 Var 4
h h x
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
Length Name checksum
This function returns the status of any Export Key Packages currently stored in the HSM.
rc
return code of zero indicates function completed successfully
Status
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
Length
32 bit Big Endian integer – total length of the Key Package
Name
variable length field, holds printable ASCII characters
checksum
CRC32 checksum of the entire Key Package – Algorithm TBA
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
Mark II Programmers Guide
Chapter 28 Network Key Transfer
Export Keys Package
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
Request Content EE3103 FM
U D U U U
Length 1 1
Attribute h h
Description Function Code Function Modifier = 00
Control
1
H
ReadOffset
4
h
Length
2
h
Response Content EE3103 Rc
Length
Attribute
1 1
h h
Function Code Return Code
Package Segment
Var
H
Next segment of Package or empty (depending on control)
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
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
ReadOffset
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’;
Length
Package Segment
© SafeNet, Inc.
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’
367
Mark II Programmers Guide
Chapter 28 Network Key Transfer
Import Key Package
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
Request Content Length EE3104 1
Attribute h
U D U U U
Description Function Code
FM
1
h
Function Modifier = 00
Control
1
h
Representing segment type = 01: First Segment = 02: Other segments
File Length/Offset
4
h
Dual Variable
Var
h
Length
Attribute
A portion of the Key Package Description
EE3104
1
h
Function Code
rc
1
h
Return Code
Cumulative Data Length
4
h
Length of partial saved package
Data Segment Response Content
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.
FileLength/Offset
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.
DataSegment
Cumulative Data Length
© SafeNet, Inc.
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.
368
Mark II Programmers Guide
Part 2 ______________________________________________________________________
Card Issuance Function Set
© SafeNet, Inc.
369
Mark II Programmers Guide
© SafeNet, Inc.
370
Mark II Programmers Guide
Chapter 29 Card Issuer Key Management and Operational Requirements
Chapter 29 Card Issuer Key Management and Operational Requirements Overview This chapter provides an overview of the key management tasks and cryptographic operations that a card issuer needs to perform when initializing cards. Additionally, it incorporates a summary of the cryptographic keys that are managed by the Card Issuance HSM in support of card issuance processing, with an indication of whether each key is supported by console operations or by host functions. Some of the processes identified may not be required by the issuer – typically being performed by a terminal when a card transaction is initiated – but are included as they might be useful in testing cards prior to issue.
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.
Static Data Authentication Sign ICC static data The issuer must produce a digital signature (using SI) for card static data. Verify ICC static data The issuer does not usually need to verify the ICC static data. Nevertheless, it may be beneficial to perform such verification (using PI) to confirm that an ICC is functioning correctly, prior to issue.
Dynamic Data Authentication Generate ICC key pair / Create ICC public key certificate For each card that is to use Dynamic Data Authentication, the issuer must generate a card key pair (PIC and SIC). A certificate must be produced (using SI), which incorporates PIC and associated data, including the ICC static data.
© SafeNet, Inc.
371
Mark II Programmers Guide
Chapter 29 Card Issuer Key Management and Operational Requirements
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.
Offline PIN Encipherment Generate PIN encipherment key pair / Create PIN encipherment public key certificate For each card that supports an offline enciphered PIN, the issuer must either generate a card key pair (PPE and SPE) or use the key pair generated for DDA for PIN encipherment as well. In the former case, a certificate must be produced (using SI), which incorporates the PIN encipherment public key and associated data. Verify PIN encipherment public key certificate The issuer does not usually need to verify the PIN encipherment public key certificate. Nevertheless, it may be beneficial to perform such verification (using PI) to confirm that an ICC is functioning correctly, prior to issue. Encipher PIN The issuer does not usually need to produce and enciphered PIN – enciphered by the card's public key. Nevertheless, it may be beneficial to perform such encipherment (using PIC or PPE) to confirm that an ICC is functioning correctly, prior to issue.
Reference PIN Management PIN issuance A reference PIN needs to be generated, provided to the cardholder and stored on the card for offline PIN processing. Facilities are provided that can be used to generate and print the PIN, and calculate an Offset or PVV. An Unblock Code (or associated data) may also need to be generated and stored on the card.
Key Management Console Operations
© SafeNet, Inc.
Host Functions
CA Public Key
PCA
input + output
CA Private Key
SCA
Issuer Public Key
PI
generate + store
generate + output
Issuer Private Key
SI
generate + store
generate + output
ICC Public Key
PIC
generate + output
ICC Private Key
SIC
generate +
372
Mark II Programmers Guide
Chapter 29 Card Issuer Key Management and Operational Requirements
Console Operations
Host Functions output
ICC PIN Encipherment Public Key
PPE
generate + output
ICC PIN Encipherment Private Key
SPE
generate + output
Issuer Master Key
IMKAC IMKSMI IMKSMC
enter + store enter + display
IMKcvc
Card Master Key
MKAC MKSMI MKSMC
derive + output
Key Transport Key
KTK
enter + store + display
PIN Transport Key
PTK
enter + store + display
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
Mark II Programmers Guide
© SafeNet, Inc.
Chapter 29 Card Issuer Key Management and Operational Requirements
374
Mark II Programmers Guide
Chapter 30 PIN Management Functions
Chapter 30 PIN Management Functions Host Stored PVK Management Host Stored PVK’s are represented in functions by PVK-Spec that are structured as follows: •
Var field showing length: i.e. 0x11
•
Format: 00x11 for ECB 00x13 for CBC Followed by 16 bytes of Data i.e. 11111111111111110123456789012345
•
Format: 00x14 for Double length PVK Followed by 24 bytes of Data i.e. 333333333333333311111111111111110123456789012345
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
Summary of PIN Management Functions
© SafeNet, Inc.
Function Name
Function Code
Page
PIN-TRANSLATE –VSDC Personalization
EE0608
376
375
Mark II Programmers Guide
Chapter 30 PIN Management Functions
PIN-TRANSLATE–VSDC Personalization Request Content EE0608 FM
Length 3 1
Attribute h h
ePPKi(PIN) PPKi-Spec
8 Var
x K-Spec
PFi ANB Pfo PPKo-Spec
1 6 1 Var
h h h K-Spec
1
h
Var
h
Response Content EE0608 rc
Length 3 1
Attribute h h
ePPKo(PIN + PIN Data)
Var
h
Encryption Method
PIN Data
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
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.
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
PFi
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.
ANB
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
© SafeNet, Inc.
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.
376
Mark II Programmers Guide
Chapter 30 PIN Management Functions
PPKo and PPKi
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
8/16
1
6
0x08 or 0x10
PIN + PIN Data
0x80
00 00 00 00 00 00
SHP Toolkit CI Note: For FM = 0 extern "C" 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 EFTBUFFER *PIN_Data, OUT
EFTBUFFER
*ePPKo_PIN);
For FM=1
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
Mark II Programmers Guide
© SafeNet, Inc.
Chapter 30 PIN Management Functions
378
Mark II Programmers Guide
Chapter 31 Card Issuer Functions
Chapter 31 Card Issuer Functions The functions define functionality that supports the cryptographic processing defined for Card Issuer payment systems transactions.
Key Types The HSM supports multiple RSA key types, as follows: Key Type
Private Key Processing
Certificate
Public Key Processing Verify certificate
Data Signature
Sign data
Verify signed data
Key Transport
Decrypt encrypted key
Encrypt key
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.
Summary of Card Issuer Functions
© SafeNet, Inc.
Function Name
Function Code
Page
AC Generate Issuer Key Pair Self-Certify Issuer Public Key (EuropayMasterCard) 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
EE2040 EE2041
380 382
EE2042 EE2043 EE2044 EE2045 EE2046 EE2047 EE2048 EE2058 EE2049 EE204A EE204B EE204C EE204D EE204E EE204F EE2050 EE2051 EE2052 EE2053 EE2054
385 387 389 391 393 395 396 399 402 404 406 408 410 412 414 416 418 419 420 421
379
Mark II Programmers Guide
Chapter 31 Card Issuer Functions
Issuer Key Management Generate Issuer Key Pair Request Content EE2040 FM
Length 3 1
Attribute h h
Key Length Exponent
2 Var
h h
User Data
Var
h
Length 3 1
Attribute h h
PI-Spec
Var
K-Spec
SI-Spec
Var
K-Spec
Response Content EE2040 rc
Description Function Code Function Modifier = 00 Modulus size in bytes: 64 • m • 248. Exponent of public key. 16 = 3 or 2 + 1. Data to be stored in key specifier for SK (May be a zero length field) Description Function Code Return Code Key specifier containing the public key. Key Type = Certificate, Data Signature (Format: 81) Key specifier containing the private key encrypted by a KM variant. Key Type = Certificate, Data Signature (Format: 82)
This function generates an issuer key pair and returns the keys for host storage. Function modifier
Reserved for possible future use; must be set to zero.
Key Length
Modulus size in bytes for input to the PK/SK generation process.
Exponent
Variable length exponent type for input to the PK/SK generation process. Field length before prefix byte is 1 or 3.
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.
Return Code
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
Key specifier for the Issuer Public Key (format 81). The Key specifier describes the complete Issuer PK.
SI-Spec
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.
Processing steps 4. Generate an RSA key pair of the specified length and with the specified public exponent.
© SafeNet, Inc.
380
Mark II Programmers Guide
Chapter 31 Card Issuer Functions
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
© SafeNet, Inc.
KEYSPEC KEYSPEC
*PK_Spec, *SK_Spec);
381
Mark II Programmers Guide
Chapter 31 Card Issuer Functions
Self-Certify Issuer Public Key (Europay - MasterCard) Request Content EE2041 FM
Length 3 1
Attribute h h
SI-Spec
Var
K-Spec
PI-Spec
Var
K-Spec
4
h
2
h
3
h
1
h
3
h
Length 3 1
Attribute h h
1
h
1
h
Length of the issuer public key modulus (NI). len(e) = 1 or 3.
Var
h
Most significant bytes of modulus.
36
h
Least significant bytes of modulus.
Var
h
= 3 or 2 + 1.
Var
h
20
h
The 'Self-certified Issuer Public Key', of length equal to the length of the Issuer Public Key Modulus (NI) Check Sum Value
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
Description Function Code Function Modifier = 00 Key Specifier for the issuer private key used in the signing operation. Key Type = Certificate, Data Signature (Formats: 0 - 3, 82) Key Specifier for the issuer public key to be signed. Key Type = Certificate, Data Signature (Formats: 0 - 3, 81) Value = 11. MMYY format for when the Certificate expires. 3 bytes chosen by the Issuer. EMV currently specify the Hash Algorithm as SHA-1 value 01. Uniquely identifies the IPK. Description Function Code Return Code
16
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
© SafeNet, Inc.
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
382
Mark II Programmers Guide
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.
ID of Certificate Subject
Specified in Tables 3-1 and 3-2 of [17].
Certificate Expiry Date
Specified in Tables 3-1 and 3-2 of [17].
Certificate Serial Number
Specified in Tables 3-1 and 3-2 of [17].
Hash Algorithm Indicator
Specified in Tables 3-1 and 3-2 of [17].
Issuer Public Key Index
Specified in Tables 7-2 of [17].
Return Code
Contains zero for success.
Issuer Public Key Length
Variable length Issuer PK modulus length.
Issuer Public Key Exponent Length
1 byte, valid length values are 1 and 3.
Leftmost Digits of Issuer Public Key
Variable length field to represent Issuer PK modulus length. As in Tables 3-1 and 3-2 of Ref [17].
Issuer Public Key Remainder
IPK remainder. As in Tables 3-1 and 3-2 of Ref [17].
Issuer Public Key Exponent
Variable length field. Valid values are value=3 (length=1) and 16 value=2 +1 (length=3).
Issuer Public Key Certificate
As in Tables 3-1 and 3-2 of Ref [17].
Issuer Public Key Checksum
As in Tables 3-1 and 3-2 of Ref [17].
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
Mark II Programmers Guide
Chapter 31 Card Issuer Functions
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
© SafeNet, Inc.
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]);
384
Mark II Programmers Guide
Chapter 31 Card Issuer Functions
Verify CA Public Key (MasterCard) Request Content EE2042 FM
Length 3 1
Attribute h h
5
h
Certificate ID
1 1
h h
PK Index = 01: RSA.
Var (NCA – 37) 37
h
CA Public Key (PCA).
h
PK Remainder
Var
h
= 3 or 2 + 1
Var (NCA) Var
h D-Spec
The 'Self-certified Europay-MasterCard Public Key'. PK Checksum
1
h
= 01: SHA-1.
Var
h
Response Content EE2042 rc
Length 3 1
Attribute h h
Data to be stored in key specifier for PK (May be a zero length field) Description Function Code Return Code
Verify Flag Certificate Data
1 Var
h h
PCA-Spec
Var
K-Spec
ID of Certificate Subject CA Public Key Index CA Public Key Algorithm Indicator Leftmost Digits of CA Public Key CA Public Key Remainder CA Public Key Exponent CA Public Key Certificate CA Public Key Checksum Hash Algorithm Indicator User Data
Description Function Code Function Modifier = 00
16
Indicates the result The data recovered from CA Public Key Certificate, of length equal to the length of the CA Public Key Modulus (NCA). Key specifier for the CA public key. Key Type = Certificate (Format: 81)
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.
© SafeNet, Inc.
Function Modifier
Reserved for possible future use; must be set to zero.
ID of Certificate Subject
Specified in Tables 3-1 and 3-2 of [17].
CA Public Key Index
Specified in Tables 4.1 and 7-1 of [17].
CA Public Key Algorithm Indicator
As in Tables 3-1 and 3-2 of Ref [17]. Currently specified as RSA value 01.
Leftmost Digits of CA Public Key
Left-most digits of CA PK modulus. Variable length equal to (C_modLen - 32 - CERT_ID_LEN) or modulus length.
CA Public Key
Only present if CA PK (modulus length > (C_modLen - 32 CERT_ID_LEN). Variable length field, length is (C_modLen - 32 -
385
Mark II Programmers Guide
Chapter 31 Card Issuer Functions
Remainder
CERT_ID_LEN) otherwise is length 1 with value 0. As in Tables 3-1 and 3-2 of Ref [17].
CA Public Key Exponent
As in Tables 3-1 and 3-2 of Ref [17].
CA Public Key Certificate
As in Tables 3-1 and 3-2 of Ref [17].
CA Public Key Checksum
As in Tables 3-1 and 3-2 of Ref [17].
Hash Algorithm Indicator
EMV currently specify the Hash Algorithm as SHA-1 value 01.
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.
Certificate Data
The recovered CA PK data as in Tables3.1/3.2 of Ref [17].
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
© SafeNet, Inc.
UCHAR EFTBUFFER KEYSPEC
*validation_result, *cert_data, *PK);
386
Mark II Programmers Guide
Chapter 31 Card Issuer Functions
Verify Issuer Public Key Certificate (MasterCard) Request Content EE2043 FM
Length 3 1
Attribute h h
PCA-Spec
Var
K-Spec
PI-Spec
Var
K-Spec
Issuer Public Key Remainder Issuer Public Key Exponent Issuer Public Key Certificate
Var
h
Var
h
Var
h
Response Content EE2043 rc
Length 3 1
Attribute h h
1
h
Var
h
Verify Flag Certificate Data
Description Function Code Function Modifier = 00 Key Specifier for the CA public key. Key Type = Certificate (Format: 81) Key Specifier for the Issuer public key. Key Type = Certificate, Data Signature (Formats: 0 - 3, 81) Concatenation of leftmost digits and remainder. 16 = 3 or 2 + 1 The 'Self-certified Europay-MasterCard Public Key', of length equal to the length of the CA Public Key (NCA). Description Function Code Return Code 00 = Verified 01 = Verification Failure The data recovered from Certificate, of length equal to the length of the CA Public Key Modulus (NCA).
This function verifies the signature, form, and content of an Issuer Public Key Certificate.
© SafeNet, Inc.
Function Modifier
Reserved for possible future use; must be set to zero.
PCA-Spec
Key specifier for the CA Public Key (Format 81). The Key specifier describes the complete CA PK.
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.
Issuer Public Key Remainder
Used to validate the recovered certificate data from the CA PK.
Issuer Public Key Exponent
Used to validate the recovered certificate data from the CA PK.
Issuer Public Key Certificate
As in tables Table 3.1/3.2 of Ref [17]
Return Code
Contains zero for success.
Verify Flag
1 byte representing the result of validation tests on the certificate. Value 1 when validation failed, otherwise value 0.
Certificate Data
Variable length certificate data recovered from the CA PK.
387
Mark II Programmers Guide
Chapter 31 Card Issuer Functions
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
© SafeNet, Inc.
UCHAR EFTBUFFER
*validation_result, *cert_data);
388
Mark II Programmers Guide
Chapter 31 Card Issuer Functions
Self-Sign Issuer Public Key (Visa) Request Content EE2044 FM
Length 3 1
Attribute h h
Description Function Code Function Modifier = 00, 01
SI-Spec
Var
K-Spec
PI-Spec
Var
K-Spec
General Public Key Data
15
h
Hash Algorithm Indicator Issuer's Public Key Algorithm Indicator Response Content EE2044 rc
1
h
Key Specifier for the issuer private key used in the signing operation. Key Type = Certificate, Data Signature (Formats: 0 - 3, 82) Key Specifier for the issuer public key to be signed. Key Type = Certificate, Data Signature (Formats: 0 - 3, 81) Data included in the self-signed public key data. The first six fields from Table 3.3 of [18] currently 18 bytes in total. = 01: SHA-1.
1
h
= 01: RSA.
Length 3 1
Attribute h h
Signature
Var
H
The 'Self-Signed Issuer Public Key Data', of length equal to the length of the Issuer Public Key Modulus (NI)
Hash Result
20
h
SHA-1 Hash Result
Description Function Code Return Code
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.
© SafeNet, Inc.
Function Modifier
Reserved for possible future use; must be set to zero.
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.
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.
General Public Key Data
As in Table 3.3 of Ref [[18]
Hash Algorithm Indicator
Currently specified as SHA-1 value 01.
Issuer's Public Key Algorithm Indicator
Currently specified as RSA value 01.
389
Mark II Programmers Guide
Chapter 31 Card Issuer Functions
Return Code
Contains zero for success.
Signature
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
© SafeNet, Inc.
EFTBUFFER UCHAR
*signature, HashResult[20]);
390
Mark II Programmers Guide
Chapter 31 Card Issuer Functions
Verify CA Public Key (Visa) Request Content EE2045 FM
Length 3 1
Attribute h h
Visa CA Public Key Algorithm Indicator RID
1
h
= 01: RSA.
5
h
Visa CA Public Key Index Visa CA Public Key Modulus Visa CA Public Key Exponent Hash Result Certificate
1
h
Registered Application Provider Identifier PK Index
Var (NCA) Var
h
PK Modulus
h
= 3 or 2 + 1
20 Var
h h
Var
h
Length 3 1
Attribute h h
SHA-1 hash of previous four fields. The 'Self-Signed Visa CA Public Key Certificate', of length equal to the length of the CA Public Key Modulus (NCA). Data to be stored in key specifier for PK (May be a zero length field) Description Function Code Return Code
PCA-Spec
Var
K-Spec
Certificate Data
Var
h
User Data Response Content EE2045 rc
Description Function Code Function Modifier = 00
16
Key Specifier for the CA public key. Key Type = Certificate (Format: 81) The data recovered from Certificate, of length equal to the length of the CA Public Key Modulus (NCA).
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.
© SafeNet, Inc.
Function Modifier
Reserved for possible future use; must be set to zero.
Visa CA Public Key Algorithm Indicator
Currently specified as RSA value 01.
Registered Application Provider Identifier (RID)
As in Tables 3-1 and 3-2 of Ref [17].
Visa CA Public Key Index
As in Tables 3-1 and 3-2 of Ref [17].
Visa CA Public Key Modulus
As in Tables 3-1 and 3-2 of Ref [17].
Visa CA Public Key Exponent
As in Tables 3-1 and 3-2 of Ref [17].
Hash Result
As in Tables 3-1 and 3-2 of Ref [17].
Certificate
As in Tables 3-1 and 3-2 of Ref [17].
391
Mark II Programmers Guide
Chapter 31 Card Issuer Functions
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.
Return Code
Contains zero for success.
PCA-Spec
Key specifier for the CA Public Key (format 81). The Key specifier describes the complete CA PK.
Certificate Data
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
© SafeNet, Inc.
KEYSPEC EFTBUFFER
*CA_PK_Spec, *cert_data);
392
Mark II Programmers Guide
Chapter 31 Card Issuer Functions
Verify Issuer Public Key Certificate (Visa) Request Content EE2046 FM
Length 3 1
Attribute h h
PCA-Spec
Var
K-Spec
PI-Spec
Var
K-Spec
IPK Modulus Remainder IPK Exponent CERI
Var
h
Var Var
h h
Length 3 1
Attribute h h
1
h
Var
h
Response Content EE2046 rc Verify Flag Certificate Data
Description Function Code Function Modifier = 00 Key Specifier for CA Public Key Key Type = Certificate (Format: 81). Key Specifier for Issuer Public Key Key Type = Certificate, Data Signature (Formats 0 – 3, 81). Length = max(0, NI-NCA+36) Issuer PK Exponent Issuer Public Key Certificate, of length NCA. Description Function Code Return Code 00 = Verified 01 = Verification Failure Recovered certificate data, of length NCA.
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
Reserved for possible future use; must be set to zero.
PCA-Spec
Key specifier for the CA Public Key (Format 81). The Key specifier describes the complete CA PK.
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.
IPK Modulus Remainder
36 least most significant bytes of the Issuer PK modulus.
IPK Exponent
Variable length field. Valid values are value = 3 (length = 1) and value 16 = 2 +1 (length = 3).
CERI
Variable length field Issuer PK certificate.
Return Code
Contains zero for success.
Verify Flag
1 byte representing the result of validation tests on the certificate. Value 1 when validation failed, otherwise value 0.
Certificate Data
Variable length certificate data recovered from the CA PK.
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
Mark II Programmers Guide
Chapter 31 Card Issuer Functions
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
© SafeNet, Inc.
UCHAR EFTBUFFER
*validation_result, *cert_data);
394
Mark II Programmers Guide
Chapter 31 Card Issuer Functions
Verify Detached Signature (Visa) Request Content EE2047 FM
Length 3 1
Attribute h h
PCA-Spec
Var
K-Spec
Detached Signature
Var
h
Hash Data
Var
h
Length 3 1
Attribute h h
Response Content EE2047 rc
Description Function Code Function Modifier = 00 Key Specifier for the CA public key. Key Type = Certificate (Format: 81) Detached signature for Issuer Public Key, of length NCA. Data that is hashed for inclusion in the detached signature – concatenation of the Output Extension and the resolved IPK Certificate. Description Function Code Return Code
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
Reserved for possible future use; must be set to zero.
PCA-Spec
Key specifier for the CA Public Key (Format 81). The Key specifier describes the complete CA PK.
Detached Signature
Variable length detached signature to be verified.
Hash Data
Variable length hash data (SHA-1) used to verify the detached signature.
Return Code
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
Mark II Programmers Guide
Chapter 31 Card Issuer Functions
ICC Key Management Generate ICC Key Pair Request Content EE2048 FM
Length 3 1
Attribute h h
SI-Spec
Var
K-Spec
Certificate Data
Var
h
KTK-Spec
Var
K-Spec
Encryption Method
1
h
PXX Flag
1
h
Var
h
Response Content EE2048 rc
Length 3 1
Attribute h h
eKKTK(mod of Sxx) or eKKEK(mod of Sxx) or eKKEK(len | mod of Sxx | padding)
Var
h
eKKTK(exp of Sxx) or eKKEK(exp of Sxx) or eKKEK(len | exp of Sxx | padding)
Var
User Data
ICC Public Key Certificate
© SafeNet, Inc.
Description Function Code FM = 00, 01 or 02. Determines which format of eKKEK(mod of Sxx) is returned Key Specifier for Issuer Private Key. Key Type = Certificate, Data Signature (Formats: 0 - 3, 82) ICC Public Key Data, as specified in Table 7 or Table 19 in [5]. (The ICC Public Key modulus will be inserted during function processing.) Key Specifier for Key Transport Key. (Formats:: 0 - 3, 11, 13, 50) 00 = ECB 01 = CBC Indicates whether to provide PXX in a key specifier. 00 = Don't return PXX. 01 = Do return PXX. Data to be stored in key specifier for PK (May be a zero length field) Description Function Code Return Code Encrypted modulus of ICC Private Key. The field length will be the next multiple of eight that is equal to or larger than the length Nxx of the modulus of Sxx + 1. In case of eKKTK(X) and eKKEK(X), the modulus will be right justified and, if necessary, padded to the left with zeroes.
h
Encrypted private exponent of ICC Private Key. The field length will be the next multiple of eight that is equal to or larger than the length Nxx of the exponent of Sxx+ 1.
Var
h
In case of eKKTK(X) and eKKEK(X), the private exponent will be right justified and, if necessary, padded to the left with zeroes. Digital signature for the public key certificate. The field length is equal to the length NI of the modulus of SI
396
Mark II Programmers Guide
ICC Public Key Remainder Pxx
Chapter 31 Card Issuer Functions
Var
h
Var
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
If set to 2, 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]
© SafeNet, Inc.
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.
Certificate Data
Variable length ICC PK certificate data as specified by EMV. Used to build the signature together with the generated SK
KTK-Spec
Key specifier for the Key Transport Key (KTK) (Formats 0 - 3, 13, 50. Encrypted with KMV35).
Encryption Method
ECB and CBC encryption methods represented using 00 or 01 respectively.
PXX Flag
1 byte flag to represent whether to return a built PK Key specifier.
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 a value of zero to represent a zero length variable field.
Return Code
Contains zero for success.
eKTK(mod of Sxx) or eKKEK(mod of Sxx) or eKKEK(len | mod of Sxx | padding)
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.
eKTK(exp of Sxx) or eKKEK(exp of Sxx) or eKKEK(len | exp of Sxx | padding)
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.
ICC Public Key Certificate
Signature for the ICC PK certificate.
ICC Public Key Remainder
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).
PXX
Key specifier for the return Public Key (Format 81). The Key specifier describes the complete PK. The return PK Key specifier is only present
397
Mark II Programmers Guide
Chapter 31 Card Issuer Functions when PXX flag = 1.
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
© SafeNet, Inc.
EFTBUFFER EFTBUFFER EFTBUFFER EFTBUFFER KEYSPEC
*eK_SK_mod, *eKTK_SK_exp, *ICC_PK_cert, *ICC_PK_rem, *PK_Spec);
398
Mark II Programmers Guide
Chapter 31 Card Issuer Functions
Generate ICC CRT Key Pair Request Content EE2058 FM
Length 3 1
Attribute H H
SI-Spec
Var
K-Spec
Certificate Data
Var
H
KTK-Spec
Var
K-Spec
Encryption Method
1
H
PXX Flag
1
H
Var
H
Length 3 1
Attribute H H
Var Var Var Var Var
H H H H H
User Data Response Content EE2058 rc eK(P) eK(Q) eK(PQ) eK(DP1) eK(DQ1)
Description Function Code FM = 00, 01 or 02. Determines which format of eKKEK(mod of Sxx) is returned Key Specifier for Issuer Private Key. Key Type = Certificate, Data Signature (Formats: 0 - 3, 82) ICC Public Key Data, as specified in Table 7 or Table 19 in [5]. (The ICC Public Key modulus will be inserted during function processing.) Key Specifier for Key Transport Key. (Formats:: 0 - 3, 11, 13, 50) 00 = ECB 01 = CBC Indicates whether to provide PXX in a key specifier. 00 = Don't return PXX. 01 = Do return PXX. Data to be stored in key specifier for PK (May be a zero length field) Description Function Code Return Code Encrypted CRT parameters of ICC Private Key. Each field eK(X) is individually encrypted and, dependent on the request fields, comprises: eKKTK(X) or eKKEK(X) or eKKEK(len | X | padding) Each field length will be the next multiple of eight that is equal to or larger than half the length Nxx of the modulus of Sxx + 1. In case of eKKTK(X) and eKKEK(X), the CRT parameter will be right justified and, if necessary, padded to the left with zeroes.
© SafeNet, Inc.
ICC Public Key Certificate
Var
h
ICC Public Key Remainder
Var
h
Digital signature for the public key certificate. The field length is equal to the length NI of the modulus of SI As specified in Table 7 in [5].
399
Mark II Programmers Guide
Chapter 31 Card Issuer Functions
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
If set to 2, 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.
Certificate Data
Variable length ICC PK certificate data as specified by EMV. Used to build the signature together with the generated SK
KTK-Spec
Key specifier for the Key Transport Key (KTK) (Formats 0 - 3, 13, 50. Encrypted with KMV35).
Encryption Method
ECB and CBC encryption methods represented using 00 or 01 respectively.
PXX Flag
1 byte flag to represent whether to return a built PK Key specifier.
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 a value of zero to represent a zero length variable field.
Return Code
Contains zero for success.
eK(P)
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.
eK(Q) eK(PQ)
When FM=2, padding method shall be followed as specified in [33]
eK(DP1) eK(DQ1)
© SafeNet, Inc.
ICC Public Key Certificate
Signature for the ICC PK certificate.
ICC Public Key Remainder
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).
PXX
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.
400
Mark II Programmers Guide
Chapter 31 Card Issuer Functions
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(
© SafeNet, Inc.
IN IN IN IN IN IN IN
UCHAR KEYSPEC EFTBUFFER KEYSPEC UCHAR UCHAR EFTBUFFER
FM, *SK, *cert_data, *KTK, enc_method, Pxx_flag, *user_data,
OUT OUT OUT OUT OUT OUT OUT OUT
EFTBUFFER EFTBUFFER EFTBUFFER EFTBUFFER EFTBUFFER EFTBUFFER EFTBUFFER KEYSPEC
*P, *Q, *PQ, *DP1, *DQ1, *ICC_PK_cert, *ICC_PK_remainder, *PK );
401
Mark II Programmers Guide
Chapter 31 Card Issuer Functions
Verify ICC Certificate (EMV2000) Request Content EE2049 FM
Length 3 1
Attribute h h
PI-Spec
Var
K-Spec
ICC Public Key Certificate
Var
h
ICC Public Key Remainder ICC Public Key Exponent Static Data to be Authenticated Response Content EE2049 rc
Var
h
Var
h
Var
h
Length 3 1
Attribute h h
Var
K-Spec
Pxx-Spec
Description Function Code Function Modifier = 00 Key Specifier for Issuer Public Key. Key Type = Certificate, Data Signature (Formats: 0 - 3, 81) Digital signature for the public key certificate. The field length is equal to the length NI of the modulus of PI As specified in Table 7 in [5]. 16
= 3 or 2 + 1. As specified in Table 7 in [5]. As specified in Table 7 in [5]. Description Function Code Return Code Key Specifier for PIC or PPE. Key Type = Data Signature, PIN Encryption (Format: 81)
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
Reserved for possible future use; must be set to zero.
PI-Spec
Key specifier for the Issuer Public Key (Formats 0 - 3, 81).
ICC Public Key Certificate
Signature for the ICC PK certificate.
ICC Public Key Remainder
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).
ICC Public Key Exponent
Variable length ICC PK exponent Valid values are value = 3 (length = 16 1) and value = 2 +1 (length = 3).
Static Data to be Authenticated
Variable length static data to be authenticated.
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.
Return Code
Contains zero for success.
Pxx-Spec
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
Mark II Programmers Guide
Chapter 31 Card Issuer Functions
2. Build the Pxx-Spec
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
© SafeNet, Inc.
KEYSPEC
*PK_Spec);
403
Mark II Programmers Guide
Chapter 31 Card Issuer Functions
Derive ICC Master Key Request Content EE204A FM
Length 3 1
Attribute h h
IMK-Spec
Var
K-Spec
IMK Type
1
h
PAN Data KTK-Spec
8 Var
h K-Spec
1
h
KVC method Response Content EE204A rc
1 Length 3 1
h Attribute h h
eKTK(MK) or eKKEK(MK) kvc(MK)
16/24
h
Encrypted ICC Master Key.
Var
h
Key Verification Code
Encryption Method
Description Function Code Function Modifier = 00 Key Specifier for Issuer Master Key. (Formats: 0 - 3, 11, 13) 01 = AC 02 = SMI 03 = SMC 04 = IDN. Formatted PAN and PAN Sequence No. Key Specifier for Key Transport Key. (Formats: 0 - 3, 11, 13, 50, 51) 00 = ECB 01 = CBC 11 = Pad+CBC 01 = left 6 digits of eK(0) Description Function Code Return Code
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
Reserved for possible future use; must be set to zero.
IMK-Spec
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.
IMK Type
1 byte flag to represent the Issuer Master Key sub-type.
PAN Data
PAN data, used to derive MK, which is then used with KTK to produce eKTK(MK).
KTK-Spec
Key specifier for the Key Transport Key (KTK) (Formats 0 - 3, 13, 50,51).
Encryption Method
ECB , CBC , CBC with padding encryption methods represented using 00 , 01 or 11 respectively.
Return Code
Contains zero for success.
eKTK(MK)
The return KTK-encrypted MK.
eKKEK(MK)
The return derived KKEK-encrypted MK.
KVC(MK)
The return Key Verification Code (KVC) computed for the MK.
Processing steps
© SafeNet, Inc.
404
Mark II Programmers Guide
Chapter 31 Card Issuer Functions
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
16
1
6
0x10
Derived Master Key
0x80
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
© SafeNet, Inc.
UCHAR EFTBUFFER
eKTK_MK[24], *KVC_MK);
405
Mark II Programmers Guide
Chapter 31 Card Issuer Functions
Sign ICC Static Data Request Content EE204B FM SI-Spec Signed Data Format Hash Algorithm Indicator Data Authentication Code Static Data to be Authenticated Response Content EE204B rc Signed Static Application Data
Length 3 1
Attribute h h
Description Function Code Function Modifier = 00
Var
K-Spec
1 1
h h
2
h
Key Specifier for Issuer Private Key. Key Type = Data Signature (Formats: 0 - 3, 82) = 03. = 01. As specified in Annex B of [5]. Issuer-assigned code
Var
h
Static Data to be authenticated.
Length 3 1
Attribute h h
Var
h
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
Reserved for possible future use; must be set to zero.
SI-Spec
Key specifier for the Issuer Private Key (Formats 0 - 3, 82).
Signed Data Format
EMV currently specify the signed data format value 03.
Hash Algorithm Indicator
EMV currently specify the Hash Algorithm as SHA-1 value 01.
Data Authentication Code
Issuer assigned 2 byte code.
Static Data to be Authenticated
Variable length static data to be authenticated.
Return Code
Contains zero for success.
Signed Static Application Data
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
Mark II Programmers Guide
Chapter 31 Card Issuer Functions
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
© SafeNet, Inc.
EFTBUFFER
*signature);
407
Mark II Programmers Guide
Chapter 31 Card Issuer Functions
Verify ICC Static Data Request Content EE204C FM
Length 3 1
Attribute h h
PI-Spec
Var
K-Spec
Static Data to be Authenticated Signed Static Application Data
Var
h
Var
h
Length 3 1
Attribute h h
Verify Flag
1
h
Signed Data Format Hash Algorithm Indicator Data Authentication Code
1 1
h h
2
h
Response Content EE204C rc
Description Function Code Function Modifier = 00 Key Specifier for Issuer Public Key. Key Type = Data Signature (Formats: 0 - 3, 81) As specified in Table 2 in [5]. Digital signature for the Static Application Data. The field length must be equal to the length NI of the modulus of PI Description Function Code Return Code = 00: Signature verification successful. = 01: Length of Signed Static Application Data • NI. = 02: Invalid Recovered Data Header or Recovered Data Trailer. = 03: Invalid Signed Data Format. = 04: Invalid Hash Algorithm Indicator. = 05: Calculated hash result • recovered Hash Result. = 06: Modulus Match • recovered Modulus Result. = 07: Certificate ID Error = 08: PK Algorithm ID Error = 09: Hash Not Verified Error Data fields recovered from Signed Static Application Data - as specified in Table 5 in [5]. If there is a verification failure these 3 fields are returned zero filled.
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.
© SafeNet, Inc.
Function Modifier
Reserved for possible future use; must be set to zero.
PI-Spec
Key specifier for the Issuer Public Key (Formats 0 - 3, 81).
Static Data to be Authenticated
Variable length static data to be authenticated. Used to build the static application data.
Signed Static Application Data
Variable length signed static application data. Used to validate the recovered signature from the Issuer PK.
Return Code
Contains zero for success.
408
Mark II Programmers Guide
Chapter 31 Card Issuer Functions
Verify Flag
1 byte length to represent result of validation test on the recovered signed application data.
Signed Data Format
Recovered from the signed data and PK values. EMV currently specify the signed data format value 03.
Hash Algorithm Indicator
Recovered from the signed data and PK values. EMV currently specify the Hash Algorithm as SHA-1 value 01.
Data Authentication Code
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
© SafeNet, Inc.
UCHAR UCHAR UCHAR UCHAR
*verify_flag, *SDF, *hash_alg_indicator, data_auth_code[2]);
409
Mark II Programmers Guide
Chapter 31 Card Issuer Functions
Dynamic Data Authentication Verify ICC Dynamic Data Request Content EE204D FM
Length 3 1
Attribute h h
PIC-Spec
Var
K-Spec
Terminal Dynamic Data
Var
h
As specified in Table 11 in [5].
Signed Dynamic Application Data
Var
h
Response Content EE204D rc
Length 3 1
Attribute h h
Digital signature for the Dynamic Application Data. The field length must be equal to the length NIC of the modulus of PIC. Description Function Code Return Code
1
h
Verify Flag
Signed Data Format Hash Algorithm Indicator ICC Dynamic Data Length ICC Dynamic Data
1 1
h h
1
h
LDD
h
Description Function Code Function Modifier = 00 Key Specifier for ICC Public Key. Key Type = Data Signature (Format: 81)
= 00: signature verification passed; = 01: Length of Signed Static Application Data • NI. = 02: Invalid Recovered Data Header or Recovered Data Trailer. = 03: Invalid Signed Data Format. = 04: Invalid Hash Algorithm Indicator. = 05: Calculated hash result • recovered Hash Result. = 06: Modulus Match • recovered Modulus Result. = 07: Certificate ID Error = 08: PK Algorithm ID Error = 09: Hash Not Verified Error Data fields recovered from Signed Dynamic Application Data - as specified in Table 13 in [5].
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.
© SafeNet, Inc.
Function Modifier
Reserved for possible future use; must be set to zero.
PIC-Spec
Key specifier for the ICC Public Key (Format 81). The Key specifier describes the complete ICC PK.
Terminal Dynamic Data
Variable length terminal dynamic data as described in Table 11 in [5].
410
Mark II Programmers Guide
Chapter 31 Card Issuer Functions
Signed Dynamic Application Data
Variable length signed dynamic application data.
Return Code
Contains zero for success.
Verify Flag
1 byte length to represent result of validation test on the recovered signed application data.
Signed Data Format
Recovered from the signed data and PK values. EMV currently specify the signed data format value 05.
Hash Algorithm Indicator
Recovered from the signed data and PK values. EMV currently specify the Hash Algorithm as SHA-1 value 01.
ICC Dynamic Data Length
Length of the built return ICC dynamic data.
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
© SafeNet, Inc.
UCHAR UCHAR UCHAR EFTBUFFER
*verify_flag, *SDF, *hash_alg_indicator, *ICC_dynamic_data);
411
Mark II Programmers Guide
Chapter 31 Card Issuer Functions
PIN Encipherment Encipher PIN Request Content EE204E FM PVK-Spec
Length 3 1
Attribute h h
Var
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
8
h
PIN Length Offset ICC Unpredictable Number PPE-Spec or PIC-Spec
1 6 8
h h h
Var
K-Spec
Length 3 1
Attribute h h
Key Specifier for ICC Public Key. Key Type = PIN Encryption (Formats: 0 - 3, 81) Description Function Code Return Code
Var
h
Enciphered PIN – using PPE or PIC
Response Content EE204E rc ePxx(PIN)
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
Reserved for possible future use; must be set to zero.
PVK-Spec
Key specifier for PIN Verification Key (PVK) (Formats 0 - 3, 11, 12, 13, 14). HSM stored and encrypted with KMv7
Validation Data
8 bytes of PAN data used to recreate the reference PIN.
PIN Length
Valid ISO PIN length.
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.
ICC Unpredictable Number
8 byte number used to form the PIN Block.
PPE-Spec or PIC-Spec
Key specifier for PIN encryption key (Formats 0 - 3, 81).
Return Code
Contains zero for success.
ePxx(PIN)
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
Mark II Programmers Guide
© SafeNet, Inc.
Chapter 31 Card Issuer Functions IN IN IN IN IN IN IN
UCHAR KEYSPEC UCHAR UCHAR UCHAR UCHAR KEYSPEC
FM, *PVK, validation_data[8], Offset[6], pin_len, unpredictable_no[8], *Pic,
OUT
EFTBUFFER
*ePxx_PIN);
413
Mark II Programmers Guide
Chapter 31 Card Issuer Functions
PIN Initialization Generate PIN Request Content EE204F FM
Length 3 1
Attribute h h
Var
K-Spec
8
h
1 6 Var
h h h
1
h
Var
K-Spec
Response Content EE204F Rc
Length 3 1
Attribute h h
Offset ePTK(PIN+PIN data)
6 Var
h h
PVK-Spec Validation Data PIN Length ANB PIN Data Encryption Method PTK-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 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.
© SafeNet, Inc.
Function Modifier
Reserved for possible future use; must be set to zero.
PVK-Spec
Key specifier for PIN Verification Key (PVK) (Formats 0 - 3, 11, 12. 13, 14).
Validation Data
8 bytes of PAN data used to recreate the reference PIN.
PIN Length
Valid ISO PIN length.
ANB
The Account Number Block is used in the formation of the ANSI PIN block.
PIN Data
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).
Encryption Method
ECB and CBC encryption methods represented using 00 or 01 respectively.
PTK-Spec
Key specifier for PIN Transport Key (PTK) (Formats 0 - 3, 11, 13). Encrypted with KMV36
Return Code
Contains zero for success.
414
Mark II Programmers Guide
Chapter 31 Card Issuer Functions
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.
ePTK(PIN+PIN data)
The return PTK-encrypted data block which contains the generated PIN and the appended 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
© SafeNet, Inc.
UCHAR EFTBUFFER
Offset[6], *ePTK_PIN);
415
Mark II Programmers Guide
Chapter 31 Card Issuer Functions
Export PIN Request Content EE2050 FM
Length 3 1
Attribute h h
Var
K-Spec
8
h
6 1 6 Var
h h h h
1
h
Var
K-Spec
Response Content EE2050 Rc
Length 3 1
Attribute h h
ePTK(PIN+PIN data)
Var
h
PVK-Spec Validation Data. Offset PIN Length ANB PIN Data Encryption Method PTK-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.
This function reproduces a previously generated PIN, formats it in an ANSI PIN block and encrypts the block for secure transport.
© SafeNet, Inc.
Function Modifier
Reserved for possible future use; must be set to zero.
PVK-Spec
Key specifier for PIN Verification Key (PVK) (Formats 0 - 3, 11, 12, 13, 14).
Validation Data
8 bytes of PAN data used to recreate the reference PIN.
Offset
6 byte offset that is used to recreate the reference PIN. The offset is in bcd format – big endian.
PIN Length
Valid ISO PIN length.
ANB
The Account Number Block is used in the formation of the ANSI PIN block.
PIN_Data
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).
Encryption Method
ECB and CBC encryption methods represented using 00 or 01 respectively.
PTK-Spec
Key specifier for PIN Transport Key (PTK) (formats 0 - 3, 11, 13). The PTK is used to encrypt the return export PIN.
Return Code
Contains zero for success.
ePTK(PIN+PIN data)
The return PTK-encrypted data block which contains the generated PIN and the appended PIN data.
416
Mark II Programmers Guide
Chapter 31 Card Issuer Functions
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
© SafeNet, Inc.
EFTBUFFER
*ePTK_PIN);
417
Mark II Programmers Guide
Chapter 31 Card Issuer Functions
Key Export using KTK Request Content EE2051 FM
Length 3 1
Attribute h h
KTK-Spec
Var
K-Spec
Key Type Enc Mode
1 1
h h
KX-Spec
Var
K-Spec
Length 3 1
Attribute h h
3
h
Response Content EE2051 rc eKTK(KX)
Description Function Code Function Modifier = 00 Key Specifier for KTK (Formats: 11, 13) 02 = MPK Encryption mode - for encryption of output key: eKTK(K). Key Specifier containing eKMx(KX) (Formats: 11,13) Description Function Code Return Code Key Verification Code
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
© SafeNet, Inc.
EFTBUFFER UCHAR
*eKTK_KX, KVC[3]);
418
Mark II Programmers Guide
Chapter 31 Card Issuer Functions
Derive New ICC Key Set Request Content EE2052 FM
Length 3 1
Attribute h h
K1KEK
Var
K-Spec
K2xxx
Var
K-Spec
Length 3 1
Attribute h h
16 16 16
h h h
Response Content EE2052 rc eK1KEK(K2ENC) eK1KEK(K2MAC) eK1KEK(K2KEK)
Description Function Code Function Modifier = 00 Key Specifier for K1KEK (Format: 50) (derived from KMC1 ) Key Specifier for K2xxx (Format: 50) (derived from KMC2) Description Function Code Return Code New KENC encrypted by old KKEK New KMAC encrypted by old KKEK New KKEK encrypted by old KKEK
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
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.
K2xxx
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
© SafeNet, Inc.
int EFT_EE2052_DeriveNewICCKeySets( UCHAR FM, KEYSPEC *K1kek, KEYSPEC *K2xxx, UCHAR UCHAR UCHAR
eK1kek_K2enc[16], eK1kek_K2mac[16], eK1kek_K2kek[16]);
419
Mark II Programmers Guide
Chapter 31 Card Issuer Functions
Derive New ICC Key Request Content EE2053 FM
Length 3 1
Attribute h h
KEK
Var
K-Spec
Key
Var
K-Spec
Length 3 1
Attribute h h
16 3
h h
Response Content EE2053 rc eKEK(Key) KVC (Key)
Description Function code Function Modifier = 00 Key Specifier for KEK (Format: 50) (derived from KMC) Key Specifier for Key (Format: 50) (derived from KMC) Description Function Code Return Code Key encrypted under KEK KVC for Key.
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
© SafeNet, Inc.
UCHAR eKEK_Key[16], UCHAR KVC[3]);
420
Mark II Programmers Guide
Chapter 31 Card Issuer Functions
Generate DCV Request Content EE2054 FM
Length 3 1
Attribute h h
eDEKi(Data)
Var
h
DEKi-Spec
Var
K-Spec
Key Type
1
BCD
Mode
1
h
Length 3 1
Attribute h h
8
h
Response Content EE2054 rc dcv(Data)
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
© SafeNet, Inc.
UCHAR
FM, *eDEKi_Data, *DEKi, KeyType, EncMode, DCV[8]);
421
Mark II Programmers Guide
© SafeNet, Inc.
Chapter 31 Card Issuer Functions
422
Mark II Programmers Guide
Chapter 32 MasterCard PayPass and Visa payWave
Chapter 32 MasterCard PayPass and Visa payWave Summary of MasterCard PayPass and Visa payWave Functions: Function Name
Function Code
Page
DERIVE_KDCVC3_AND_IVCVC3
EE0012
424
CREATE_ADDITIONAL_ICC
EE0013
426
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
Mark II Programmers Guide
Chapter 32 MasterCard PayPass and Visa payWave
DERIVE_KDCVC3_AND_IVCVC3
U D U U U
PHW SHP PSO/PSG SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
Request Content EE0012 FM
Length 3 1
Attribute h h
IMKCVC3
Var
K-Spec
PAN Data KTK-Spec
8 Var
h K-Spec
1
h
KVC method IV Data 1
1 Var
h h
IV Data 2
Var
h
Length 3
Attribute h
rc
1
h
Return Code
eKTK(KDCVC3) or eKKEK(KDCVC3) Kvc(KDCVC3)
16
h
Encrypted ICC Derived Key for CVC3 Generation.
Var
h
Key Verification Code
IVCVC3TRACK1
2
h
IVCVC3TRACK2
2
h
Encryption Method
Response Content EE0012
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
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
Mark II Programmers Guide
Chapter 32 MasterCard PayPass and Visa payWave
4. If len(IV Data 1) > 0 calculate IVCVC3TRACK1 If len(IV Data 2) > 0 calculate IVCVC3TRACK2
© SafeNet, Inc.
425
Mark II Programmers Guide
Chapter 32 MasterCard PayPass and Visa payWave
CREATE_ADDITIONAL_ICC
PHW
U
SHP
D
PSO/PSG
U U U
SHP Toolkit MK2 Card Issuance (SHP Toolkit EMV)
Request Content EE0013 FM SI
ICC Public Key Certificate
Length 3 1
Attribute h h
Var
K-Spec
Var
h
ICC Public Key Remainder
Var
h
ICC Public Key Exponent
Var
h
Static Data to be Authenticated
Var
h
Length 3 1
Attribute h h
Var
h
Response Content EE0013 rc Additional ICC Public Key Certificate
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
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
Mark II Programmers Guide
Chapter 32 MasterCard PayPass and Visa payWave
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
Mark II Programmers Guide
© SafeNet, Inc.
Chapter 32 MasterCard PayPass and Visa payWave
428
Mark II Programmers Guide
Part 3 ______________________________________________________________________
MarkII & Card Issuance Appendices
© SafeNet, Inc.
429
Mark II Programmers Guide
© SafeNet, Inc.
430
Mark II Programmers Guide
Appendix A IBM 3624 PIN Verification Method
Appendix A IBM 3624 PIN Verification Method This appendix gives an overview of the IBM 3624 PIN Verification method. For a complete description refer to the IBM 3624 Consumer Transaction Facility Programmers Guide (GC66-0008-1 File No. S/370-30).
Definitions Customer PIN
PIN assigned to or selected by the customer.
Customer Selected PIN
A PIN that is chosen by the customer.
Customer Entered PIN
The entered PIN that is to be verified.
PINLEN
Number of digits in a Customer PIN.
CHKLEN
Number of PIN digits checked in the PIN verification procedure.
PIN Offset
Non secret data that is associated with the PIN and used in the PIN verification procedure.
PIN Generation
Process of creating a PIN that is then issued to a customer.
PIN Verification
Process of validating a Customer PIN.
A 3624 PIN may either be derived, or randomly generated. Random PINs have an associated Offset.
Verification of a Derived PIN Five steps are necessary to verify a Derived PIN. 1. Form the validation data. The data must contain 16 digits. Use pad digits if necessary. The digits are normally selected from the Primary Account Number (PAN). 2. Encrypt the validation data with the PIN Verification Key (PVK). 3. Use the Decimalization Table (DT) to decimalize all digits in the encrypted validation data. 4. The leftmost PINLEN digits of the result of step 3 is the Derived PIN. 5. Compare the rightmost CHKLEN digits of the Derived PIN with the rightmost CHKLEN digits of the Customer Entered PIN. Table F.1 contains an example of verifying a Derived PIN.
© SafeNet, Inc.
431
Mark II Programmers Guide
Appendix A IBM 3624 PIN Verification Method
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
Table F.1 Verification of a Derived PIN
Verification of a Random PIN In order to verify a Random PIN an Offset must also be utilized. The Offset is a non-secret value and represents the difference between the Random PIN and the Derived PIN. The following steps are involved: 1. 2. 3. 4. 5. 6.
Form the validation data. The data must contain 16 digits. Use pad digits if necessary. The digits are normally selected from the Primary Account Number (PAN). Encrypt the validation data with the PIN Verification Key (PVK). Use the Decimalization Table (DT) to decimalize all digits in the encrypted validation data. The leftmost PINLEN digits of the result of step 3 is the Derived PIN. Add, modulo 10, the Offset to the Derived PIN to produce the PIN Check Number. The significant Offset digits and the Derived PIN must be right aligned. Compare the rightmost CHKLEN digits of the PIN Check Number with the rightmost CHKLEN digits of the Customer Entered PIN.
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
Mark II Programmers Guide
Appendix A IBM 3624 PIN Verification Method
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
6. Compare rightmost CHKLEN digits with Customer PIN
40 6902 + 89 3703 ------------29 9605 ------------29 9605
Table F.2 Verification of a Random PIN
Selecting Significant Offset Digits There are always CHKLEN significant Offset digits. These digits correspond to the CHKLEN Customer PIN digits which are validated in the PIN verification process. When a PIN is randomly generated, or selected by a customer, the Offset must also be generated. In order to generate the Offset, the Derived PIN for the customer must be calculated. The leftmost PINLEN digits of the Derived PIN must be aligned with the Customer Entered PIN. The significant Offset digits are then calculated as follows : 1 2.
Subtract, modulo 10, each digit of the Derived PIN from each corresponding digit of the randomly generated (or customer selected) PIN. The rightmost CHKLEN digits of the result are the significant Offset digits.
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.
2.
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.
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
Mark II Programmers Guide
Appendix A IBM 3624 PIN Verification Method
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
Table F.3 Selecting Significant PIN and Offset Digits
© SafeNet, Inc.
434
Mark II Programmers Guide
Appendix B EFT Terminal Functions
Appendix B EFT Terminal Functions The following examples demonstrate a sample input and response to each function. These results may be used to verify correct implementation of the EFT Terminal functionality.
DUKPT BDK Generation EE0408 Transmitted to HSM Function code = 00 Key Length
EE 04 08 00
Returned from HSM Function code Return code (Var) BDK Variable Length Field: The first byte of the field expanded to binary 0001 0001 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. 11h = 17 bytes).
© SafeNet, Inc.
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
435
Mark II Programmers Guide
© SafeNet, Inc.
Appendix B EFT Terminal Functions
436
Mark II Programmers Guide
Appendix C Card Issuance Function Examples
Appendix C Card Issuance Function Examples EMV Issuer function EE2052 - Derive New ICC Key Set Transmitted To HSM Function code Function Modifier (Var) K1kek K1kek format (Var) KMC K-spec eKMv37(KMC) Derivation Data Card method (Var) K2xxx K2xxx format (Var) KMC K-spec Derivation Data Card method Returned From HSM Function code Return code eK1kek(K2enc) eK1kek(K2mac) eK1kek(K2kek)
© SafeNet, Inc.
EE 00 24 50 11 2D 76 11 55 01 15 50 02 11 55 01
EE 00 85 AA F5 18 9F B3
20 52
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
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
437
Mark II Programmers Guide
© SafeNet, Inc.
Appendix C Card Issuance Function Examples
438
Mark II Programmers Guide
Appendix D PIN Management Function Examples
Appendix D PIN Management Function Examples The following examples demonstrate sample input and response. These results may be used to verify correct implementation of the PIN Management functionality.
PIN-FROM-OFF EE0609 Transmitted to HSM Function code = 00 PVK Spec Validation Data Offset PIN Length PPK-Spec PFo ANB
EE 06 09 00 02 01 61 04 02 01 66
Returned from HSM Function code Return code ePPK(PIN)
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
© SafeNet, Inc.
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
439
Mark II Programmers Guide
© SafeNet, Inc.
Appendix D PIN Management Function Examples
440
Mark II Programmers Guide
Appendix E EMV Function Examples
Appendix E EMV Function Examples The following examples demonstrate a sample input and response to each function. These results may be used to verify correct implementation of the EMV functionality.
Keys used for the EMV example functions Key *AC
Index 1
*DAC
83
*IDN
22
*SMI
4
*SMC
5
Value 3333 0000 56FE 0000 AAAA 0000 7007 0000 BBBB 0000
3333 0000 19C3 0000 AAAA 0000 C1D5 0000 BBBB 0000
3333 0000 2A3B 0000 AAAA 0000 EA19 0000 BBBB 0000
3333 0000 0ECB 0000 AAAA 0000 0B98 0000 BBBB 0000
3333 0000 123F 0000 1111 0000 BA75 0000 1111 0000
3333 0000 301B 0000 1111 0000 E50B 0000 1111 0000
3333 0000 44FE 0000 1111 0000 89D0 0000 1111 0000
3333 0000 ABCD 0000 1111 0000 2601 0000 1111 0000
KVC ADC67D 4B1BDB C33F45 D12C36 39571E
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).
EMV function EE2000 – AC Gen Transmitted to HSM Function code = 00 00 (Var) AC-index Application PAN Block Random Number (Var) AC-data
Returned from HSM Function code Return code Application Cryptogram
EE 20 00 02 01 EF 20 E9 C1 A0 C5
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
AC-index = 1
6D 4C C2 80
EE 20 00 00 89 B6 8C 00 8E 06 2B F3
0 = successful completion
EMV function EE2001 – AC Verify (FM=00) Transmitted to HSM Function code = 00 00 (Var) AC-index Application PAN Block Random Number Application Cryptogram (Var) AC-data
Returned from HSM Function code Return code
© SafeNet, Inc.
EE 20 01 02 01 EF 89 20 E9 C1 A0 C5
00 23 5E B6
01 45 67 89 01 23 45 EF F8 2C E6 76 A8 8C 00 8E 06 2B F3
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
EE 20 01 00h
441
Mark II Programmers Guide
Appendix E EMV Function Examples
EMV function EE2001 – AC Verify (FM=01) Transmitted to HSM Function code = 00 01 (Var) AC-index Application PAN Block Random Number (Var) CAP Token (Var) AC-data (K-spec) Bitmap
Returned from HSM Function code Return code
EE 20 01 02 00 01 EF 02 85 08 01 02 00
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
EMV function EE2002 – DAC Gen Transmitted to HSM Function code = 00 00 (Var) DAC-index Application PAN Block Returned from HSM Function code Return code Data Authentication Code DAC (2 bytes)
EE 20 02 02 00 83 01 23 45 67 89 01 23 45
EE 20 02 00 81 DE
EMV function EE2003 – DAC Verify Transmitted to HSM Function code = 00 00 (Var) DAC-index Application PAN Block Data Authentication Code DAC (2 bytes) Returned from HSM Function code Return code
EE 20 03 02 00 83 01 23 45 67 89 01 23 45 81 DE
EE 20 03 00
EMV function EE2004 – ICC DN Gen
© SafeNet, Inc.
Transmitted to HSM Function code = 00 00 (Var) IDN-index Application PAN Block Random Number
02 00 22 01 23 45 67 89 01 23 45 EF 5E EF F8 2C E6 76 A8
Returned from HSM Function code Return code ICC Dynamic Number
EE 20 04 00 BA 33
EE 20 04
442
Mark II Programmers Guide
Appendix E EMV Function Examples
IDN (2 bytes)
EMV function EE2005 – ICC DN Verify Transmitted to HSM Function code = 00 00 (Var) IDN-index Application PAN Block Random Number ICC Dynamic Number IDN (2 bytes) Returned from HSM Function code Return code
EE 20 05 02 01 EF BA
00 22 23 45 67 89 01 23 45 5E EF F8 2C E6 76 A8 33
EE 20 05 00
EMV function EE2006 – ARPC Gen Transmitted to HSM Function code = 00 00 (Var) AC-index Application PAN Block ARPC Data
02 00 01 01 23 45 67 89 01 23 45 E9 A0 2C EB FA 20 2F 6D
Returned from HSM Function code Return code Application Response Code
EE 20 06 00 AB 31 8E E1 C3 0D 67 0C
EE 20 06
EMV function EE2007 – Script Crypto Transmitted to HSM Function code = 00 00 SC (Var) SMI-index
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.
(not used because SC=1, see ‘note’ in function description.)
(Var) SMC-index Application PAN Block Random Number (Var) Text-Data
Offset (Var) Script Data Returned from HSM Function code Return code eSK(Text-Data)
MAC
© SafeNet, Inc.
02 01 EF E0 E9 C1 A0 C5 00 00
00 23 5E 00 A0 D4 7C 38 00
EE 00 EF BE 44 C9 00
20 07 07 83 AC 0B 00
05 45 EF 00 2C 62 26 5C
EB BF 78 D9 00
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
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
443
Mark II Programmers Guide
Appendix E EMV Function Examples
EMV function EF2010 - Verify Application Cryptogram-EMV2000 (FM=00) Transmitted To HSM Function code = 00 (Var) AC-index Application PAN Block IV Height Branch factor ATC Application Cryptogram (Var) AC-data Data
EF 00 02 01 01 01 10 02 00 50 08 01
20 10
Returned From HSM Function code Return code
EF 20 10 00
00 23 01 01
01 45 67 89 01 23 45 01 01 01 01 01 01 01 01 01 01 01 01
01 7F CF 54 BB 34 1D FB 00 00 00 00 00 00 00
EMV function EF2010 - Verify Application Cryptogram-EMV2000(FM=01) Transmitted To HSM Function code = 00 (Var) AC-index Application PAN Block IV Height Branch factor ATC (Var CAP Token (Var) AC-data (K-spec) Bitmap
Returned From HSM Function code Return code
EF 01 02 00 01 01 01 10 02 00 02 09 08 01 02 00
20 10
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
EMV function EF2011 - Verify Application Cryptogram-Visa (FM=00)
© SafeNet, Inc.
Transmitted To HSM Function code = 00 (Var) AC-index Application PAN Block Application Cryptogram (Var) AC-data Data
EF 00 02 01 55 08 01
Returned From HSM Function code Return code
EF 20 11 00
20 11 00 01 23 45 67 89 01 23 45 CD 4D 35 9F ED 30 11 00 00 00 00 00 00 00
444
Mark II Programmers Guide
Appendix E EMV Function Examples
EMV function EF2011 - Verify Application Cryptogram-Visa (FM=01) Transmitted To HSM Function code = 00 (Var) AC-index Application PAN Block (Var) CAP Token (Var) AC-data Data Bitmap
Returned From HSM Function code Return code
EF 01 02 01 02 44 08 01 02 00
20 11 00 01 23 45 67 89 01 23 45 28 23 45 67 89 AB CD EF 01
EF 20 11 00
EMV function EF2012 - Generate ARPC – EMV2000 Transmitted To HSM Function code = 00 (Var) AC-index Application PAN Block Initialization Vector Height Branch factor ATC ARPC Data
EF 00 02 01 01 01 10 02 00 01
20 12
Returned From HSM Function code Return code ARPC
EF 20 12 00 50 7F CF 54 BB 34 1D FB
00 23 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
EMV function EF2013 - Script Crypto- EMV2000
© SafeNet, Inc.
445
Mark II Programmers Guide
Transmitted To HSM Function code = 00 Select Code (SC) (Var) SMI spec (Var) SMC spec Application PAN Block Initialization Vector
Appendix E EMV Function Examples
Height Branch factor ATC Encryption Mode Var) Text-Data Text-Data Offset (Var) Script Data Data
EF 00 03 02 02 01 01 01 10 02 00 00 08 01 00 08 01
20 13
Returned From HSM Function code Return code eSKsmc(Text) MAC
EF 20 13 00 CA BF 92 07 A3 D4 1A 35 6D 97 2A 4F 24 4B 70 A7
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
EMV function EF2014 - Script Crypto-Visa
© SafeNet, Inc.
Transmitted To HSM Function code = 00 Select Code (SC) (Var) SMI spec (Var) SMC spec Application PAN Block ATC (Var) Text-Data Text-Data Offset (Var) Script-Data Data
EF 00 01 02 02 01 00 E0 01 00 08 01
Returned from HSM Function code Return code eSKsmc(Text) MAC
EF 20 14 00 6D 47 F8 BE B4 58 A5 DB 00 00 00 00 00 00 00 00
20 14
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
446
Mark II Programmers Guide
Appendix F American Express Account Blocks
Appendix F American Express Account Blocks How To Form An Account Block Expiration (YYMM) 9 9 1
Account Number 2
3
7
1
2
3
4
5
6
7
8
9
0
1
2
3
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
The above result is packed into 8 bytes in Binary Coded Decimal. 99
12
12
34
56
78
90
12
This end result is now the account block
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
Mark II Programmers Guide
© SafeNet, Inc.
Appendix F American Express Account Blocks
448
Mark II Programmers Guide
Appendix G American Express Examples
Appendix G American Express Examples CSC Key in index1= 1234567890ABCDEF1234567890ABCDEF Test
Account
1 2 3 4 5 6 7 8
371234567890123 371234567890124 371234567890123 370000443010001 378257567890123 370091311890123 370010808890123 341234567890123
Expiry Date 9807 9912 0001 9912 9912 9912 9912 9912
Account Block 98 99 00 99 99 99 99 12
07 12 01 12 12 12 12 34
12 12 12 00 82 00 00 56
34 34 34 00 57 91 10 78
56 56 56 44 56 31 80 90
78 78 78 30 78 18 88 12
90 90 90 10 90 90 90 99
12 12 12 00 12 12 12 12
3 Digit 128 283 664 310 127 174 770 806
4 Digit
5 Digit
8109 4117 2848 3213 1220 2450 2861 3232
05840 70954 57523 42880 76429 02757 84555 68900
Test Program Output The following represents the output from tests run by SafeNet using the above examples on the Calculate CSC function. Note: This data is in the format required by the Async. Transparent Protocol.
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
© SafeNet, Inc.
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
449
Mark II Programmers Guide
Appendix G American Express Examples
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
Mark II Programmers Guide
Transmitted to HSM: SOM LENGTH Application Data BCC EOM Received From HSM: SOM LENGTH Application Data BCC EOM
Appendix G American Express Examples
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
© SafeNet, Inc.
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
451
Mark II Programmers Guide
© SafeNet, Inc.
Appendix G American Express Examples
452
Mark II Programmers Guide
Appendix H Function Matrix - MarkII
Appendix H Function Matrix - MarkII The following table provides as list of the function codes that are detailed in this Guide, their associated function name and an indication of which products support the functions. The column headed PHW, lists the functions that are available in the HSM Mark II release. The column headed PSO, lists the functions that are available in the ProtectServer Orange Mark II release. The column headed SHP Toolkit MK2, details the functions included in the SHP Toolkit MK2 API. The column headed PHW CI lists the functions documented in this Guide that are also in the HSM Card Issuance release. If any entry in a particular column is blank, this indicates that the function is not available in the respective product. There are a number of functions which supercede one or more functions. These relationships are detailed in the Supercedes and Superceded by columns.
Func. Code
Function Name
SHP
PHW
PSO
SHP Toolkit MK2
PHW CI
Supercedes
Superceded by
01
HSM_STATUS
11
Establish_KM
12
KM_Migrate
13
Erase_Old_KM
21
Retrieve_Key
22
Store_Key
41
IT-PPK-GEN
EE0400
42
IT-MPK-GEN
EE0400
43
IT-DPK-GEN
EE0400
44
NT-PPK-GEN
EE0401
45
NT-MPK-GEN
EE0401
46
NT-DPK-GEN
EE0401
47
D51-PPK-GEN
49
M-DPK-GEN
4A
GEN_SESS_KEYS
EE0400
4C
TERM-VER
EE0406
51
II-PPK-GEN
EE0402
52
II-MPK-GEN
EE0402
53
II-DPK-GEN
EE0402
54
II-PPK-RCV
EE0403
55
II-MPK-RCV
EE0403
56
II-DPK-RCV
EE0403
57
NI-PPK-GEN
EE0404
58
NI-MPK-GEN
EE0404
59
NI-DPK-GEN
EE0404
5A
NI-PPK-RCV
EE0405
5B
NI-MPK-RCV
EE0405
5C
NI-DPK-RCV
EE0405
© SafeNet, Inc.
453
Mark II Programmers Guide
Func. Code
Function Name
Appendix H Function Matrix - MarkII
SHP
PHW
PSO
SHP Toolkit MK2
PHW CI
Supercedes
Superceded by
60
PIN-TRAN
EE0602
61
PIN-VER
EE0603
62
PIN-VER-PP
EE0603
63
PIN-TRAN-3624
64
KB-PIN-VER
65
D51-PIN-TRAN
EE0602
66
D51-PIN-VER
EE0603
67
VAR-PIN-VER
EE0603
68
VAR-PIN-VER-PP
EE0603
69
VAR-KB-PIN-VER
6A
PIN-OFF-AS
EE0604
6B
PIN-OFF-PP
EE0604
70
MAC-GEN
EE0701
71
MAC-TRAN
EE0701
72
MAC-VER
EE0701
73
KB-MAC-GEN
80
ENCIPHER
EE0800
81
DECIPHER
EE0801
82
ENCIPHER-ECB
EE0800
83
DECIPHER-ECB
EE0801
84
B-ENCIPHER-ECB
85
B-DECIPHER-ECB
90
PVV-GEN-1
EE0606
91
PVV-VER-1
EE0605
92
PVV-VER-2
EE0605
93
PVV-VER-3
EE0605
94
PIN-TRAN-1
EE0602
95
PIN-TRAN-2
EE0602
96
PVV-GEN-2
EE0606
97
PVV-VER-4
EE0605
98
PVV-VER-5
EE0605
99
PVV-VER-6
EE0605
9A
PVV-CHANGE
EE0607
9B
CVV-GEN
EE0802
9C
CVV_VER
EE0803
A0
MT-KPE-GEN
A1
MT-KPE-RCV
A2
MT-PIN-TRAN
A3
MT-PIN-VER
A7
MT_PIN_VER_PVV
A8
CALC_CSCK
© SafeNet, Inc.
454
Mark II Programmers Guide
Func. Code
Function Name
A9
CREATE_CSCK
AA
EXPORT_CSCK
AB
IMPORT_CSCK
E2
PIN-MAIL
E3
Meta Function Support
FFF0
HSM_ERRORLOG_STATUS
FFF1
HSM_GET_ERRORLOG
Appendix H Function Matrix - MarkII
SHP
PHW
PSO
SHP Toolkit MK2
PHW CI
Supercedes
EE0002
GEN_RANDOM
EE0200
KEY_IMPORT
EE0201
KEY_EXPORT
EE0202
GET_KEY_DETAILS
EE0210
ZKA-IMPORT-MK
EE0400
IT_KEY_GEN
EE0401
NT_KEY_GEN
44,45,46
EE0402
II_KEY_GEN
51,52,53
EE0403
II_KEY_RCV
54,55,56
EE0404
NI_KEY_GEN
57,58,59
EE0405
NI_KEY_RCV
5A,5B,5C
EE0406
TERM_VER_2
EE0408
BDKGEN
EE0600
CLR-PIN-ENCRYPT
EE0601
MIGRATEPIN
EE0602
PIN-TRAN-2
60,65,94,95
EE0603
PIN-VER
61,62,66,67, 68
EE0604
PIN-OFF
6A,6B
EE0605
PVV-VER
91,92,93,97, 98,99
EE0606
PVV-CALC-3624
EE0607
PVV-CALC
EE0609
PIN-FROM-OFF
EE0610
ZKA-PIN-TRANS
EE0611
ZKA-PIN-VER
EE0612
ZKA-CALC-PVN
EE0613
ZKA-PIN-TRANS-1
EE0614
DIEBOLD_PIN_VER
EE0615
PIN_TRANS_SEED_DES
EE0616
DIEBOLD_PIN_OFF
EE0628
GEN_TERMINAL_KEY
EE0640
Generate KM-encrypted PIN
EE0641
Print a KM-encrypted PIN
EE0642
Verify a PIN Using KM-encrypted PIN
© SafeNet, Inc.
Superceded by
41,42,43,4A
90,96 9A
455
Mark II Programmers Guide
Func. Code
Function Name
Appendix H Function Matrix - MarkII
SHP
PHW
PSO
SHP Toolkit MK2
PHW CI
Supercedes
EE0643
Translate a PIN from PPK to LMK
EE0644
Migrate PIN
EE0700
MAC_GEN_UPDATE
EE0701
MAC_GEN_FINAL
EE0702
MAC_VER_FINAL
EE0710
ZKA-MAC-GEN
EE0711
ZKA-MAC-GEN-1
EE0800
ENCIPHER_2
80,82
EE0801
DECIPHER_2
81,83
EE0802
CVV_GENERATE
9B
EE0803
CVV_VERIFY
9C
EE0804
ENCIPHER_3
EE0805
DECIPHER_3
EE0806
ENCIPHER_KTM1
EE0E01
Key Mailer
EE0E04
PIN-GENERATE
EE0E05
PIN-PRINT
EE2000
EMV_AC_GEN
EE2001
EMV_AC_VERIFY
EE2002
EMV_DAC_GEN
EE2003
EMV_DAC_VERIFY
EE2004
EMV_ICC_DN_GEN
EE2005
EMV_ICC_DN_VERIFY
EE2006
EMV_ARPC_GEN
EE2007
EMV_SCRIPT_CRYPTO
EE2016
EMV_PIN_CHANGE_UNBLOCK
EE2017
EMV_PIN_CHANGE_UNBLOCK_E MV_2000
EE2018
EMV_VERIFY_AC_GEN_ARPC
EE3030
GETPUBLICKEY
EE3031
KIS_SEND
EE3032
KIR_REC
EE3033
NODEPROOF
EE3034
NODERESP
EE3100
LOAD_HSM_SOFTWARE
EE3101
HSM_SOFTWARE_STATUS
EE9001
Generate RSA Key Pair
EE9003
Import Public Key
EE9004
Import Public Key Certificate
EE9005
Sign Data
EE9006
Verify Signed Data
EE9007
Generate MD5 Hash
© SafeNet, Inc.
Superceded by
70,71,72
456
Mark II Programmers Guide
Func. Code
Function Name
EE9008
Generate SHA Hash
EE9101
Generate Key – Diebold
EE9102
Verify ATM Response – Diebold
EE9201
Generate KM – NCR
EF0210
IT_PVK_EXPORT
EF0701
VCEPS_VER_S1_GEN_S2
EF0702
VCEPS_VER_SN
EF0703
VCEPS_GEN_SN
EF0704
VCEPS_MAC_VER_LSAM
EF0F01
VCEPS_GEN_HASH_CEP
EF2010
EMV_VERIFY_AC_EMV2000
EF2011
EMV_VERIFY_AC_VISA
EF2012
EMV_GENERATE_ARPC
EF2013
EMV_SCRIPT_CRYPTO_EMV2000
EF2014
EMV_SCRIPT_CRYPTO_VISA
EF2015
EMV_PIN_CHANGE_UNBLOCK_VI SA
EE2019
EMV_AC_GEN_MULTI
EE2020
EMV_SCRIPT_CRYPTO_MULTI
EE2021
EMV_PIN_CHANGE_UNBLOCK_M ULTI
EE0010
CVC3_GENERATE
EE0011
CVC3_VERIFY
EE0014
dCVV_GENERATE
EE0015
dCVV_VERIFY
EE0608
PIN-TRANSLATE–VSDC Personalization
EE2040
AC Generate Issuer Key Pair
EE2041
Self-Certify Issuer Public Key (Europay- MasterCard)
EE2042
Verify CA Public Key (MasterCard)
EE2043
Verify Issuer Public Key Certificate (MasterCard)
EE2044
Self-Sign Issuer Public Key (Visa)
EE2045
Verify CA Public Key (Visa)
EE2046
Verify Issuer Public Key Certificate (Visa)
EE2047
Verify Detached Signature (Visa)
EE2048
Generate ICC Key Pair
EE2058
Generate ICC CRT Key Pair
EE2049
Verify ICC Certificate (EMV2000)
EE204A
Derive ICC Master Key
EE204B
Sign ICC Static Data
EE204C
Verify ICC Static Data
© SafeNet, Inc.
Appendix H Function Matrix - MarkII
SHP
PHW
PSO
SHP Toolkit MK2
PHW CI
Supercedes
Superceded by
457
Mark II Programmers Guide
Func. Code
Function Name
EE204D
Verify ICC Dynamic Data
EE204E
Encipher PIN
EE204F
Generate PIN
EE2050
Export PIN
EE2051
Key Export using KTK
EE2052
Derive New ICC Key Set
EE2053
Derive New ICC Key
EE2054
Generate DCV
EE0012
DERIVE_KDCVC3_AND_IVCVC3
EE0013
CREATE_ADDITIONAL_ICC
© SafeNet, Inc.
Appendix H Function Matrix - MarkII
SHP
PHW
PSO
SHP Toolkit MK2
PHW CI
Supercedes
Superceded by
458
Mark II Programmers Guide
Appendix I SHP Toolkit
Appendix I SHP Toolkit SHP Toolkit MK2 This appendix provides information on the use of the SHP Toolkit MK2. The functions that make up the C API accept and return data in standard C variable types and / or the set of structures described here. (The structures are defined in the file eftApiBase.h). Following the structure definitions, the full list of function definitions is provided.
Structures Representing Individual Key Specifiers. (The concept of a Key Specifier is introduced in Chapter 3 of the Programmers Guide) Each defined Key Specifier is represented by a specific C structure:
© SafeNet, Inc.
typedef struct { UCHAR } FORMAT00;
BCD;
// Represents Key Spec 0 // BCD 00 - 99
typedef struct { UCHAR } FORMAT01;
bin;
// Represents Key Spec 1 // binary x00 - xff
typedef struct { UCHAR } FORMAT02;
BCD[2];
// Represents Key Spec 2 // BCD 0000 - 9999
typedef struct { USHORT bin; } FORMAT03;
// Represents Key Spec 03 // binary x0000 - xffff
typedef struct { UCHAR eKM_Key[8]; } FORMAT10;
// Represents Key Spec 10 // eKMvn(key)
typedef struct { UCHAR eKM_Key[16]; } FORMAT11;
// Represents Key Spec 11 // ECB mode eKMvn(*key)
typedef struct { UCHAR eKM_Key[16]; } FORMAT13;
// Represents Key Spec 13 // CBC mode eKMvn(*key)
459
Mark II Programmers Guide
Appendix I SHP Toolkit
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 { UCHAR UCHAR UCHAR UCHAR UCHAR UCHAR } FORMAT16;
// Represents Key Spec 16 algorithm; masterKeyLen; blockLen; mode; keyFieldLen; keyField[32];
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;
typedef struct { USHORT UCHAR USHORT
© SafeNet, Inc.
// Represents Key Spec 80 modulusLen; modulus[512]; exponentLen;
460
Mark II Programmers Guide
Appendix I SHP Toolkit
UCHAR } FORMAT80;
exponent[512];
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 { UCHAR UCHAR UCHAR UCHAR } FORMAT92;
// Represents Format 92 subType; generationNum; versionNumber; expiryDate[2];
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;
typedef struct { UCHAR format_KGK1; union {
© SafeNet, Inc.
// Represents Key Spec 91
461
Mark II Programmers Guide
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;
Structure Representing All Key Specifiers. In general a function that requires a Key Spec as an input parameter will accept any one from a set of allowable Key Specifiers. (The set of acceptable Key Specifiers is listed in the definition of each function) In order to limit the C API to one C function for each ESM function, a single structure (KEYSPEC below) that contains a union of all of the above Key Spec representations is defined. This contains a single unsigned char field (format) that contains the code for the Key Specifier being represented in this instance and a second un-named field that is defined as a union of all the Key Specifier representations defined above. typedef struct { UCHAR format; union { FORMAT00 FORMAT01 FORMAT02 FORMAT03 FORMAT10 FORMAT11 FORMAT13 FORMAT15 FORMAT16 FORMAT50 FORMAT51 FORMAT80 FORMAT81 FORMAT82 FORMAT90 FORMAT91 FORMAT92 }; } KEYSPEC;
© SafeNet, Inc.
// Universal Key Spec // One of..... fmt00; fmt01; fmt02; fmt03; fmt10; fmt11; fmt13; fmt15; fmt16; fmt50; fmt51; fmt80; fmt81; fmt82; fmt90; fmt91; fmt92;
462
Mark II Programmers Guide
Appendix I SHP Toolkit
Structure Representing Variable Length Character Arrays. Some functions accept or return variable length data. The EFTBUFFER structure (below) supports this functionality. typedef struct { ULONG length; UCHAR *data; } EFTBUFFER;
// length of binary data // binary data
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.
API Helper Functions It is recognized that the use of a single Key Specifier structure to represent all possible Key Specifiers will in many case waste storage space, both in memory and in other storage media. Accordingly, two functions have been included to pack and unpack data to / from a KEYSPEC structure and a character array. int EFT_KeySpecToBuffer(UCHAR **p, KEYSPEC *k, int *bufLen); This function will intelligently copy the data from KEYSPEC *k to the buffer at **p, using the information inherent in the format field of the KEYSPEC to compress the data to use the minimum storage space. (During this process internal formatting information is embedded in the packed data that may be subsequently used to recover the data in its original format, see below). If the compressed data would require a larger array than that indicated by the value of *buflen, an error is returned and the contents of the buffer at **p is undefined. The function is intended to be used on data returned by functions in KEYSPEC structures.. int EFT_BufferToKeySpec(KEYSPEC *k, UCHAR **p, int *bufLen); This function will intelligently copy the data from the buffer at **p to KEYSPEC *k, placing the data in the individual fields of the target structure. It is the exact inverse of the above EFT_KeySpecToBuffer function and can only be used to unpack data that was previously packed using that function. EFT_BufferToKeySpec uses internal formatting information to recover the data in its original format. If the internal formatting information indicates that the length of data at **p is different to that indicated by the value of *buflen, an error is returned and the contents of KEYSPEC *k are undefined. int MK2API_SetESM(char *NewESMName); int EMVAPI_SetESM(char *NewESMName); These two function will set ESM name as passed on parameter, defined correspondingly in MK2 and EMV API.
Void API_SetTraceFile(char *TraceFileName); This function will set trace file name as passed on parameter.
© SafeNet, Inc.
463
Mark II Programmers Guide
Appendix I SHP Toolkit
Error Translation Functions int EFTErrToString(int index, char *outString, unsigned int length); This function will return a text string at *outString corresponding to an error number passed in index. The value of length indicates the maximum length of the text to be returned. If the text to be returned is longer than length, the function returns an error and the contents of *outstring is undefined.
Optional IO Fields in Functions _IN _OUT
// optional input field // optional output field
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.
SHP Toolkit MK2 Functions HSM Status Functions extern "C" EXPORT 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);
extern "C" EXPORT int EFT_FFF0_HSMErrorLogStatus( IN UCHAR *ESMID, IN UCHAR FM, OUT _OUT _OUT _OUT _OUT _OUT _OUT _OUT _OUT _OUT _OUT
© SafeNet, Inc.
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],
464
Mark II Programmers Guide
_OUT
Appendix I SHP Toolkit UCHAR
LogFileStatus10[31]);
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
UCHAR
*Returned_File_Number,
_OUT _OUT
UCHAR EFTBUFFER
Error_Log_Index[2], *Error_Log_Data,
_OUT _OUT
UCHAR EFTBUFFER
Error_Log_Index1[2], *Error_Log_Data1,
_OUT _OUT
UCHAR EFTBUFFER
Error_Log_Index2[2], *Error_Log_Data2,
_OUT _OUT
UCHAR EFTBUFFER
Error_Log_Index3[2], *Error_Log_Data3,
_OUT _OUT
UCHAR EFTBUFFER
Error_Log_Index4[2], *Error_Log_Data4,
_OUT _OUT
UCHAR EFTBUFFER
Error_Log_Index5[2], *Error_Log_Data5,
_OUT _OUT
UCHAR EFTBUFFER
Error_Log_Index6[2], *Error_Log_Data6,
_OUT _OUT
UCHAR EFTBUFFER
Error_Log_Index7[2], *Error_Log_Data7,
_OUT _OUT
UCHAR EFTBUFFER
Error_Log_Index8[2], *Error_Log_Data8,
_OUT _OUT
UCHAR EFTBUFFER
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
Mark II Programmers Guide
Appendix I SHP Toolkit
IN IN
UCHAR UCHAR
variantNum, NumKeys,
IN _IN _IN _IN _IN _IN _IN _IN _IN _IN
KEYSPEC KEYSPEC KEYSPEC KEYSPEC KEYSPEC KEYSPEC KEYSPEC KEYSPEC KEYSPEC KEYSPEC
*keyToTranslate1, *keyToTranslate2, *keyToTranslate3, *keyToTranslate4, *keyToTranslate5, *keyToTranslate6, *keyToTranslate7, *keyToTranslate8, *keyToTranslate9, *keyToTranslate10,
OUT OUT _OUT _OUT _OUT _OUT _OUT _OUT _OUT _OUT _OUT
UCHAR KEYSPEC KEYSPEC KEYSPEC KEYSPEC KEYSPEC KEYSPEC KEYSPEC KEYSPEC KEYSPEC KEYSPEC
*NumKeysReturned, *translatedKey1, *translatedKey2, *translatedKey3, *translatedKey4, *translatedKey5, *translatedKey6, *translatedKey7, *translatedKey8, *translatedKey9, *translatedKey10);
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
extern "C" EXPORT int EFT_22_StoreKey( IN UCHAR IN KEYSPEC IN UCHAR IN KEYSPEC IN UCHAR
*keyType, *retrievedKey, KVC[3]);
Reserved[2], *tfrTableIndex, keyType, *keyToStore, KVC[3]);
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
Mark II Programmers Guide
OUT OUT
Appendix I SHP Toolkit EFTBUFFER UCHAR
*eKISvK, KVC[3]);
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);
EFT Terminal Functions extern "C" EXPORT int EFT_EE0E01_KTMMailer( IN UCHAR *ESMID, IN UCHAR FM, IN UCHAR nA, IN UCHAR nB,
© SafeNet, Inc.
_IN _IN _IN
UCHAR UCHAR EFTBUFFER
*LineNo1a, *ColumnNo1a, *Data1a,
_IN _IN _IN
UCHAR UCHAR EFTBUFFER
*LineNo2a, *ColumnNo2a, *Data2a,
_IN _IN _IN
UCHAR UCHAR EFTBUFFER
*LineNo3a, *ColumnNo3a, *Data3a,
_IN _IN _IN
UCHAR UCHAR EFTBUFFER
*LineNo4a, *ColumnNo4a, *Data4a,
_IN _IN _IN
UCHAR UCHAR EFTBUFFER
*LineNo5a, *ColumnNo5a, *Data5a,
_IN _IN _IN
UCHAR UCHAR EFTBUFFER
*LineNo6a, *ColumnNo6a, *Data6a,
_IN _IN _IN
UCHAR UCHAR EFTBUFFER
*LineNo7a, *ColumnNo7a, *Data7a,
_IN _IN _IN
UCHAR UCHAR EFTBUFFER
*LineNo8a, *ColumnNo8a, *Data8a,
_IN _IN _IN
UCHAR UCHAR EFTBUFFER
*LineNo9a, *ColumnNo9a, *Data9a,
_IN _IN _IN
UCHAR UCHAR EFTBUFFER
*LineNo10a, *ColumnNo10a, *Data10a,
467
Mark II Programmers Guide
Appendix I SHP Toolkit
_IN _IN _IN
UCHAR UCHAR EFTBUFFER
*LineNo1b, *ColumnNo1b, *Data1b,
_IN _IN _IN
UCHAR UCHAR EFTBUFFER
*LineNo2b, *ColumnNo2b, *Data2b,
_IN _IN _IN
UCHAR UCHAR EFTBUFFER
*LineNo3b, *ColumnNo3b, *Data3b,
_IN _IN _IN
UCHAR UCHAR EFTBUFFER
*LineNo4b, *ColumnNo4b, *Data4b,
_IN _IN _IN
UCHAR UCHAR EFTBUFFER
*LineNo5b, *ColumnNo5b, *Data5b,
_IN _IN _IN
UCHAR UCHAR EFTBUFFER
*LineNo6b, *ColumnNo6b, *Data6b,
_IN _IN _IN
UCHAR UCHAR EFTBUFFER
*LineNo7b, *ColumnNo7b, *Data7b,
_IN _IN _IN
UCHAR UCHAR EFTBUFFER
*LineNo8b, *ColumnNo8b, *Data8b,
_IN _IN _IN
UCHAR UCHAR EFTBUFFER
*LineNo9b, *ColumnNo9b, *Data9b,
_IN _IN _IN
UCHAR UCHAR EFTBUFFER
*LineNo10b, *ColumnNo10b, *Data10b,
_IN _IN
UCHAR UCHAR
*KeyType, *KvcType,
OUT _OUT
KEYSPEC EFTBUFFER
*eKMv5_KTM, *KVC_Key );
extern "C" EXPORT int EFT_EE0400_InitialSessionKeyGeneration( IN UCHAR FM, IN KEYSPEC *KTM, IN UCHAR KeyFlags[2],
© SafeNet, Inc.
OUT
UCHAR
*numKeys,
OUT OUT OUT
EFTBUFFER KEYSPEC UCHAR
*eKTM_KS1, *KS1, KVC1[3],
_OUT _OUT _OUT
EFTBUFFER KEYSPEC UCHAR
*eKTM_KS2, *KS2, KVC2[3],
468
Mark II Programmers Guide
Appendix I SHP Toolkit
_OUT _OUT _OUT
EFTBUFFER KEYSPEC UCHAR
*eKTM_KS3, *KS3, KVC3[3],
_OUT _OUT _OUT
EFTBUFFER KEYSPEC UCHAR
*eKTM_KS4, *KS4, KVC4[3]);
extern "C" EXPORT int EFT_EE0401_RolloverSessionKeyGeneration( IN UCHAR FM, IN UCHAR KeyFlags[2], IN KEYSPEC *KSi1, _IN KEYSPEC *KSi2, _IN KEYSPEC *KSi3, OUT
UCHAR
*numKeys,
OUT OUT OUT
EFTBUFFER KEYSPEC UCHAR
*eKS_KS1, *KS1, KVC1[3],
_OUT _OUT _OUT
EFTBUFFER KEYSPEC UCHAR
*eKS_KS2, *KS2, KVC2[3],
_OUT _OUT _OUT
EFTBUFFER KEYSPEC UCHAR
*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);
Remote ATM Initialization Functions extern "C" EXPORT 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);
extern "C" EXPORT int EFT_EE9003_ImportPublicKey( IN UCHAR FM, IN UCHAR KeyType[2], IN KEYSPEC *PKi, IN EFTBUFFER *UserData,
© SafeNet, Inc.
469
Mark II Programmers Guide
OUT
Appendix I SHP Toolkit
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
Mark II Programmers Guide
Appendix I SHP Toolkit
IN
UCHAR
KeyType,
OUT OUT OUT
EFTBUFFER EFTBUFFER KEYSPEC
*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
UCHAR
*numKeys,
OUT OUT OUT
EFTBUFFER KEYSPEC UCHAR
*eKIS_KS1, *KS1, KVC1[3],
_OUT _OUT _OUT
EFTBUFFER KEYSPEC UCHAR
*eKIS_KS2, *KS2, KVC2[3],
_OUT _OUT _OUT
EFTBUFFER KEYSPEC UCHAR
*eKIS_KS3, *KS3, KVC3[3],
_OUT _OUT _OUT
EFTBUFFER KEYSPEC UCHAR
*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
© SafeNet, Inc.
UCHAR
*numKeys,
471
Mark II Programmers Guide
Appendix I SHP Toolkit
OUT OUT
KEYSPEC UCHAR
*KS1, KVC1[3],
_OUT _OUT
KEYSPEC UCHAR
*KS2, KVC2[3],
_OUT _OUT
KEYSPEC UCHAR
*KS3, KVC3[3],
_OUT _OUT
KEYSPEC UCHAR
*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
UCHAR
*numKeys,
OUT OUT OUT
EFTBUFFER KEYSPEC UCHAR
*eKS_KS1, *KS1, KVC1[3],
_OUT _OUT _OUT
EFTBUFFER KEYSPEC UCHAR
*eKS_KS2, *KS2, KVC2[3],
_OUT _OUT _OUT
EFTBUFFER KEYSPEC UCHAR
*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,
© SafeNet, Inc.
_IN _IN
KEYSPEC EFTBUFFER
*KSi2, *eKS_KSi2,
_IN _IN
KEYSPEC EFTBUFFER
*KSi3, *eKS_KSi3,
_IN _IN
KEYSPEC EFTBUFFER
*KSi4, *eKS_KSi4,
OUT
UCHAR
*numKeys,
OUT OUT
KEYSPEC UCHAR
*KS1, KVC1[3],
_OUT _OUT
KEYSPEC UCHAR
*KS2, KVC2[3],
_OUT _OUT
KEYSPEC UCHAR
*KS3, KVC3[3],
_OUT
KEYSPEC
*KS4,
472
Mark II Programmers Guide
_OUT
Appendix I SHP Toolkit UCHAR
KVC4[3]);
PIN Management Functions extern "C" EXPORT 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]);
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);
extern "C" int EFT_EE0609_CalculatePINFromOffset( IN UCHAR FM,
© SafeNet, Inc.
473
Mark II Programmers Guide
IN IN IN IN IN IN IN
KEYSPEC *PVK, UCHAR Validation_Data[8], UCHAR Offset[6], UCHAR Pin_Length, KEYSPEC *PPK, UCHAR PFo, UCHAR ANB[6],
OUT
UCHAR ePPK_PIN[8]);
extern "C" int IN IN IN OUT
extern "C" int IN IN IN IN
© SafeNet, Inc.
Appendix I SHP Toolkit
EFT_EE0640_GEN_KM_ENC_PIN( UCHAR FM, UCHAR PINLen, UCHAR ANB[6], KEYSPEC
*eKM_PIN);
EFT_EE0641_Print_eKMPin( UCHAR FM, KEYSPEC *eKM_PIN, UCHAR ANB[6], UCHAR PAN[8],
IN
UCHAR
DataSets,
_IN _IN _IN
UCHAR UCHAR EFTBUFFER
*LineNo1, *ColumnNo1, *Data1,
_IN _IN _IN
UCHAR UCHAR EFTBUFFER
*LineNo2, *ColumnNo2, *Data2,
_IN _IN _IN
UCHAR UCHAR EFTBUFFER
*LineNo3, *ColumnNo3, *Data3,
_IN _IN _IN
UCHAR UCHAR EFTBUFFER
*LineNo4, *ColumnNo4, *Data4,
_IN _IN _IN
UCHAR UCHAR EFTBUFFER
*LineNo5, *ColumnNo5, *Data5,
_IN _IN _IN
UCHAR UCHAR EFTBUFFER
*LineNo6, *ColumnNo6, *Data6,
_IN _IN _IN
UCHAR UCHAR EFTBUFFER
*LineNo7, *ColumnNo7, *Data7,
_IN _IN _IN
UCHAR UCHAR EFTBUFFER
*LineNo8, *ColumnNo8, *Data8,
474
Mark II Programmers Guide
Appendix I SHP Toolkit
_IN _IN _IN
UCHAR UCHAR EFTBUFFER
*LineNo9, *ColumnNo9, *Data9,
_IN _IN _IN
UCHAR UCHAR EFTBUFFER
*LineNo10, *ColumnNo10, *Data10);
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
© SafeNet, Inc.
UCHAR PVV[2]);
475
Mark II Programmers Guide
Appendix I SHP Toolkit
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]);
MAC Management Functions extern "C" EXPORT 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]);
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
Mark II Programmers Guide
IN IN IN
Appendix I SHP Toolkit KEYSPEC EFTBUFFER EFTBUFFER
*MPK, *mac, *data);
Data Ciphering Functions extern "C" EXPORT int EFT_EE0800_Encipher( IN UCHAR FM, IN KEYSPEC *DPK, IN UCHAR CipherMode, IN UCHAR ICV[8], IN EFTBUFFER *clear_data, OUT OUT
UCHAR EFTBUFFER
OCV[8], *enc_data);
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
Mark II Programmers Guide
OUT OUT OUT
Appendix I SHP Toolkit
UCHAR UCHAR UCHAR
eKEKn_KPE[8], eKMv1_KPE[8], KCV[2]);
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]);
American Express Functions extern "C" EXPORT int EFT_A8_CalculateCSCK ( IN KEYSPEC *CSCK, IN UCHAR CardData [8], OUT
UCHAR
CSC[6] );
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]);
extern "C" EXPORT int EFT_AB_ImportCSCK ( IN UCHAR CSCK_storage_indicator,
© SafeNet, Inc.
478
Mark II Programmers Guide
Appendix I SHP Toolkit
IN IN
KEYSPEC UCHAR
*KIR, eKIR_CSCK[16],
OUT OUT
KEYSPEC UCHAR
*CSCK, KVC[3]);
PIN Issuance Functions extern "C" EXPORT int EFT_E2_PinMailer( IN UCHAR IN UCHAR IN UCHAR IN UCHAR IN UCHAR
*ESMID, PVKIndex, PAN[8], PinLen, PinType,
_IN _IN _IN
UCHAR UCHAR EFTBUFFER
*LineNo1, *ColumnNo1, *Data1,
_IN _IN _IN
UCHAR UCHAR EFTBUFFER
*LineNo2, *ColumnNo2, *Data2,
_IN _IN _IN
UCHAR UCHAR EFTBUFFER
*LineNo3, *ColumnNo3, *Data3,
_IN _IN _IN
UCHAR UCHAR EFTBUFFER
*LineNo4, *ColumnNo4, *Data4,
_IN _IN _IN
UCHAR UCHAR EFTBUFFER
*LineNo5, *ColumnNo5, *Data5,
_IN _IN _IN
UCHAR UCHAR EFTBUFFER
*LineNo6, *ColumnNo6, *Data6,
_IN _IN _IN
UCHAR UCHAR EFTBUFFER
*LineNo7, *ColumnNo7, *Data7,
_IN _IN _IN
UCHAR UCHAR EFTBUFFER
*LineNo8, *ColumnNo8, *Data8,
_IN _IN _IN
UCHAR UCHAR EFTBUFFER
*LineNo9, *ColumnNo9, *Data9,
_IN _IN _IN
UCHAR UCHAR EFTBUFFER
*LineNo10, *ColumnNo10, *Data10,
_OUT
UCHAR
Offset[6]);
extern "C" EXPORT int EFT_EE0E04_GenRandomPIN( IN UCHAR FM, IN UCHAR PINLen,
© SafeNet, Inc.
479
Mark II Programmers Guide
Appendix I SHP Toolkit
IN IN IN
UCHAR UCHAR KEYSPEC
PFo, ANB[6], *PPK,
OUT
UCHAR
ePPK_PIN[8]);
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
UCHAR
DataSets,
_IN _IN _IN
UCHAR UCHAR EFTBUFFER
*LineNo1, *ColumnNo1, *Data1,
_IN _IN _IN
UCHAR UCHAR EFTBUFFER
*LineNo2, *ColumnNo2, *Data2,
_IN _IN _IN
UCHAR UCHAR EFTBUFFER
*LineNo3, *ColumnNo3, *Data3,
_IN _IN _IN
UCHAR UCHAR EFTBUFFER
*LineNo4, *ColumnNo4, *Data4,
_IN _IN _IN
UCHAR UCHAR EFTBUFFER
*LineNo5, *ColumnNo5, *Data5,
_IN _IN _IN
UCHAR UCHAR EFTBUFFER
*LineNo6, *ColumnNo6, *Data6,
_IN _IN _IN
UCHAR UCHAR EFTBUFFER
*LineNo7, *ColumnNo7, *Data7,
_IN _IN _IN
UCHAR UCHAR EFTBUFFER
*LineNo8, *ColumnNo8, *Data8,
_IN _IN _IN
UCHAR UCHAR EFTBUFFER
*LineNo9, *ColumnNo9, *Data9,
_IN _IN _IN
UCHAR UCHAR EFTBUFFER
*LineNo10, *ColumnNo10, *Data10);
EMV Functions
© SafeNet, Inc.
480
Mark II Programmers Guide
Appendix I SHP Toolkit
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]);
extern "C" EXPORT int EFT_EE2007_EMVScriptCrypto( IN UCHAR FM,
© SafeNet, Inc.
481
Mark II Programmers Guide
Appendix I SHP Toolkit
IN IN IN IN IN IN IN IN
UCHAR KEYSPEC KEYSPEC UCHAR UCHAR EFTBUFFER USHORT EFTBUFFER
SC, *IMK_SMI, *IMK_SMC, APANB[8], RN[8], *Text, Offset, *Script_Data,
OUT OUT
EFTBUFFER UCHAR
*eSMC_Text, MAC[8]);
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
Mark II Programmers Guide
Appendix I SHP Toolkit
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
© SafeNet, Inc.
EFTBUFFER *eSMC_Text, UCHAR MAC[8]);
483
Mark II Programmers Guide
Appendix I SHP Toolkit
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
Mark II Programmers Guide
OUT OUT
Appendix I SHP Toolkit EFTBUFFER *New_PIN_Data, UCHAR MAC[8]);
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
Mark II Programmers Guide
Appendix I SHP Toolkit
IN IN IN IN
UCHAR UCHAR EFTBUFFER EFTBUFFER
NTcep[2], MAC_S1[8], *S1_Data, *S2_Data,
OUT
UCHAR
MAC_S2[8]);
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]);
AS2805.6.3 Support Functions extern "C" EXPORT int EFT_EE3030_GetPublicKey( IN UCHAR FM, IN KEYSPEC *PK, OUT OUT OUT
UCHAR UCHAR KEYSPEC
*ModLen, PVC_PKI_HSM[20], *PKI_HSM);
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] );
extern "C" EXPORT int EFT_EE3032_KirRec(
© SafeNet, Inc.
486
Mark II Programmers Guide
Appendix I SHP Toolkit
IN IN IN IN IN
UCHAR KEYSPEC EFTBUFFER EFTBUFFER KEYSPEC
FM, *SK, *Signed_Hash, *ePKr_KIR, *PK,
OUT OUT
KEYSPEC UCHAR
*KIR, KVC_KIR[3]);
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
EFTBUFFER EFTBUFFER EFTBUFFER EFTBUFFER EFTBUFFER EFTBUFFER EFTBUFFER EFTBUFFER EFTBUFFER EFTBUFFER
*OptField1, *OptField2, *OptField3, *OptField4, *OptField5, *OptField6, *OptField7, *OptField8, *OptField9, *OptField10,
OUT OUT OUT
EFTBUFFER KEYSPEC EFTBUFFER
*TerminalKey, *HostKey, *KVC);
ZKA Functions
© SafeNet, Inc.
487
Mark II Programmers Guide
Appendix I SHP Toolkit
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
Mark II Programmers Guide
OUT OUT OUT
Appendix I SHP Toolkit UCHAR UCHAR KEYSPEC
ePPKo_PIN[8], RND[16], *MK2_2);
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);
Diebold Table Support extern "C" EXPORT 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); extern "C" EXPORT 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
© SafeNet, Inc.
PINOffsetTable[2]);
489
Mark II Programmers Guide
Appendix I SHP Toolkit
HSM Software Upgrade Functions extern "C" EXPORT 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,
extern "C" EXPORT int EFT_EE3101_ HSMSoftwareStatus( IN UCHAR *ESMID, IN UCHAR FM, OUT OUT OUT
UCHAR EFTBUFFER UCHAR
*Status, *Version); Data_len [4]);
Online Banking Module Functions extern "C" EXPORT int EFT_EE3000_OBM_GetPublicKey( IN UCHAR FM, IN KEYSPEC *PK1, OUT OUT
KEYSPEC *PK2, UCHAR PVC[8]);
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
© SafeNet, Inc.
UCHAR
Offset2[6]);
490
Mark II Programmers Guide
Appendix I SHP Toolkit
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,
© SafeNet, Inc.
_IN _IN _IN
UCHAR *LineNo1, UCHAR *ColumnNo1, EFTBUFFER *Data1,
_IN
UCHAR *LineNo2,
491
Mark II Programmers Guide
Appendix I SHP Toolkit
_IN _IN
UCHAR *ColumnNo2, EFTBUFFER *Data2,
_IN _IN _IN
UCHAR *LineNo3, UCHAR *ColumnNo3, EFTBUFFER *Data3,
_IN _IN _IN
UCHAR *LineNo4, UCHAR *ColumnNo4, EFTBUFFER *Data4,
_IN _IN _IN
UCHAR *LineNo5, UCHAR *ColumnNo5, EFTBUFFER *Data5,
_IN _IN _IN
UCHAR *LineNo6, UCHAR *ColumnNo6, EFTBUFFER *Data6,
_IN _IN _IN
UCHAR *LineNo7, UCHAR *ColumnNo7, EFTBUFFER *Data7,
_IN _IN _IN
UCHAR *LineNo8, UCHAR *ColumnNo8, EFTBUFFER *Data8,
_IN _IN _IN
UCHAR *LineNo9, UCHAR *ColumnNo9, EFTBUFFER *Data9,
_IN _IN _IN
UCHAR *LineNo10, UCHAR *ColumnNo10, EFTBUFFER *Data10,
OUT
EFTBUFFER
*ReferenceTPV);
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
Mark II Programmers Guide
Appendix I SHP Toolkit
IN IN IN IN IN IN
UCHAR AlgorithmID, EFTBUFFER *DataA, EFTBUFFER *DataB, KEYSPEC *KTPV, UCHAR Prextern "C" EXPORT intToken[8], KEYSPEC *PPK,
OUT OUT
EFTBUFFER EFTBUFFER
*ePPK_PIN, *ReferenceTPV);
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
UCHAR *LineNo1, UCHAR *ColumnNo1, EFTBUFFER *Data1,
_IN _IN _IN
UCHAR *LineNo2, UCHAR *ColumnNo2, EFTBUFFER *Data2,
_IN _IN _IN
UCHAR *LineNo3, UCHAR *ColumnNo3, EFTBUFFER *Data3,
_IN _IN _IN
UCHAR *LineNo4, UCHAR *ColumnNo4, EFTBUFFER *Data4,
_IN _IN _IN
UCHAR *LineNo5, UCHAR *ColumnNo5, EFTBUFFER *Data5,
_IN _IN _IN
UCHAR *LineNo6, UCHAR *ColumnNo6, EFTBUFFER *Data6,
_IN _IN _IN
UCHAR *LineNo7, UCHAR *ColumnNo7, EFTBUFFER *Data7,
_IN _IN _IN
UCHAR *LineNo8, UCHAR *ColumnNo8, EFTBUFFER *Data8,
_IN _IN _IN
UCHAR *LineNo9, UCHAR *ColumnNo9, EFTBUFFER *Data9,
_IN _IN _IN
UCHAR *LineNo10, UCHAR *ColumnNo10, EFTBUFFER *Data10);
extern "C" EXPORT int EFT_EE3019_OBM_TranslatePIN_RSAencrypted_PPK(
© SafeNet, Inc.
493
Mark II Programmers Guide
Appendix I SHP Toolkit
IN IN IN IN IN IN IN IN IN
UCHAR UCHAR KEYSPEC EFTBUFFER EFTBUFFER EFTBUFFER KEYSPEC UCHAR UCHAR
*ESMID, FM, *SK, *C, *P, *RN, *PPKo, PFo, ANB[6],
OUT
EFTBUFFER
*ePPKo_PIN);
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
© SafeNet, Inc.
KEYSPEC KEYSPEC
*PK_spec, *SK_spec);
494
Mark II Programmers Guide
Appendix I SHP Toolkit
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]);
EXPORT int EFT_EE2045_VerifyCAPKVisa(
© SafeNet, Inc.
495
Mark II Programmers Guide
Appendix I SHP Toolkit
IN IN IN IN IN IN IN IN IN
UCHAR UCHAR UCHAR UCHAR EFTBUFFER EFTBUFFER UCHAR EFTBUFFER 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,
OUT OUT
KEYSPEC EFTBUFFER
*CA_PK_spec, *cert_data);
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);
EXPORT int EFT_EE204A_DeriveICCMasterKey( IN UCHAR FM, IN KEYSPEC *IMK, IN UCHAR SC,
© SafeNet, Inc.
496
Mark II Programmers Guide
Appendix I SHP Toolkit
IN IN IN IN
UCHAR KEYSPEC UCHAR UCHAR
PAN[8], *KTK, enc_method, kvc_method,
OUT OUT
UCHAR EFTBUFFER
eKTK_MK[24], *kvc_MK);
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
Mark II Programmers Guide
OUT OUT
Appendix I SHP Toolkit
UCHAR EFTBUFFER
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
EXPORT int EFT_EE2051_KeyExportKTK( IN UCHAR IN KEYSPEC IN UCHAR IN UCHAR IN KEYSPEC OUT OUT
EFTBUFFER UCHAR
Offset[6], *ePTK_PIN);
FM, *PVK, validation_data[8], Offset[6], pin_len, ANB[6], *PIN_Data, enc_method, *PTK, *ePTK_PIN);
FM, *KTK, KeyType, EncMode, *KX, *eKTK_KX, KVC[3]);
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
FM, *KEK, *Key,
UCHAR eKEK_Key[16], UCHAR KVC[3]);
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]);
EXPORT int EFT_EE2058_GENERATE_ICC_CRT_KEYPAIR( IN UCHAR FM, IN KEYSPEC *SK, IN EFTBUFFER *cert_data, IN KEYSPEC *KTK,
© SafeNet, Inc.
498
Mark II Programmers Guide
IN IN IN OUT OUT OUT OUT OUT OUT OUT OUT
© SafeNet, Inc.
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 );
499
Mark II Programmers Guide
© SafeNet, Inc.
Appendix I SHP Toolkit
500
Mark II Programmers Guide
Appendix J Error Codes
Appendix J Error Codes Please refer to the Communications Guide for other host connection specific error codes. Error Code
Meaning
00 01 02 03 04 05 06 07
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
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
© SafeNet, Inc.
501
Mark II Programmers Guide
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.
Appendix J Error Codes
502
Mark II Programmers Guide
Appendix K References – MarkII and CI
Appendix K References – MarkII and CI MarkII References [1] [2] [3] [4] [5] [6] [7] [8] [9] [10] [11] [12] [13] [14] [15] [16] [17] [18] [19] [20] [21] [22] [23] [24] [25] [26] [27] [28]
[29] [30] [31]
© SafeNet, Inc.
Integrated Circuit Card Application Specification For Debit and Credit on Chip, Version 2.0, MasterCard International. EMV ’96 Version 3.1.1, May 31, 1998 Integrated Circuit Card Application Specification for Payment Systems EMV ’96 Version 3.1.1, May 31, 1998 Integrated Circuit Card Specification for Payment Systems Part IV – Security Aspects; Annexes E and F. EMV Draft version 0.5 October 31, 2000 Issuer Security Guidelines EMV2000 Version 4.0 December 2000 Integrated Circuit Card Specification for Payment Systems Book 2 – Security and Key Management Europay Int'l Version 2.1 October 1999 Integrated Circuit Card (ICC) Application Specification for Pay Now (Debit) and Pay Later (Credit) cards MasterCard Int'l Version 2.1 November 1999 MasterCard Chip— Recommended Specifications for Debit and Credit Visa Int'l Version 1.4.0 October 2001 Visa Integrated Circuit Card Application Overview Visa Int'l Version 1.4.0 October 2001 Visa Integrated Circuit Card (ICC) Specification Common Electronic Purse Specifications – Technical Specification Version 2.3 March 2001 Joint Specification for Common Electronic Purse Cards Version 2.1.3 February, 2001 Joint Card Interface Specification for Issuers of Common Electronic Purse Cards –Volume 1 – Load, Currency Exchange and POS Transaction Processing Version 1.0 April 2000 Visa Cash Electronic Purse Specifications – Technical Specification – Volume 1 Version 4.1 September 2000 Visa Cash Electronic Purse Specifications – Technical Specification – Volume 2 Version 4.1 January 2001 Visa International CEPS PSAM Creator Version 1.0 PSAM DES Key Card Version 1.10 April 5, 2002 Diebold, Certificate Management, Rev. 1.4, 24 Jun 02 Diebold, Remote Key Management, Rev. 1.4, 24 Jun 02 Diebold, Triple DES Requirements, FIRST Key – 91x Message Formats, Rev. 1.5, 26 Jun 02 NCR, Modifications to NDC+ to support: EPP, RSA Initial Key loading, ISO PIN Block formats, 17 Jul 01 RSA Laboratories, PKCS#1: RSA Cryptography Standard, v2.0, 01 Oct 98 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 ANSI X9, TR-31 2004: Interoperable Secure Key Exchange Key Block Specification for Symmetric Algorithms, Draft, 7 Nov 03 Vendor Group (ACI WorldWide, HP Atalla, Diebold, Thales e-Security, Verifone Inc.), Global Interoperable Secure Key Exchange key Block, V2.3, 6 Dec 02 Verfione, Global Interoperable Secure Key Exchange (GISKE) Key Block Specification, VPN 22986 Rev C, data unknown 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. ANS X9.24-1 Retail Financial Services Symmetric Key Management Part 1 :Using Symmetric Techniques: 2004 MasterCard SecureCode Chip Authentication Program: Functional Architecture: Sept, 2004.
503
Mark II Programmers Guide
Appendix K References – MarkII and CI
[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 für 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 Int’l 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
Card Issuance References [1] [2] [3] [4] [5] [6] [7] [8] [9] [10] [11] [12] [13] [14] [15] [16] [17] [18] [19] [20] [21] [22] [23] [24]
[25]
© SafeNet, Inc.
Integrated Circuit Card Application Specification For Debit and Credit on Chip, Version 2.0, MasterCard International. EMV ’96 Version 3.1.1, May 31, 1998, Integrated Circuit Card Application Specification for Payment Systems. EMV ’96 Version 3.1.1, May 31, 1998, Integrated Circuit Card Specification for Payment Systems Part IV – Security Aspects; Annexes E and F. EMV Draft version 0.5, October 31, 2000, Issuer Security Guidelines. EMV2000 Version 4.0, December 2000, Integrated Circuit Card Specification for Payment Systems Book 2 – Security and Key Management. Europay Int'l Version 2.1, October 1999, Integrated Circuit Card (ICC) Application Specification for Pay Now (Debit) and Pay Later (Credit) cards. MasterCard Int'l Version 2.1, November 1999, MasterCard Chip— Recommended Specifications for Debit and Credit. Visa Int'l Version 1.4.0, October 2001, Visa Integrated Circuit Card Application Overview. Visa Int'l Version 1.4.0, October 2001, Visa Integrated Circuit Card (ICC) Specification. Common Electronic Purse Specifications – Technical Specification, Version 2.3, March 2001. Joint Specification for Common Electronic Purse Cards, Version 2.1.3, February 2001. Joint Card Interface Specification for Issuers of Common Electronic Purse Cards –Volume 1 – Load, Currency Exchange and POS Transaction Processing, Version 1.0, April 2000. Visa Cash Electronic Purse Specifications – Technical Specification – Volume 1, Version 4.1, September 2000. Visa Cash Electronic Purse Specifications – Technical Specification – Volume 2, Version 4.1, January 2001. Visa International CEPS PSAM Creator, Version 1.0. PSAM DES Key Card, Version 1.10, April 5, 2002. Registration Authority (RA) Interface Specification, Europay International, Version 2.1, November 2000. Visa Certificate Authority User's Guide Visa International, Version 1.2, 31 March 2001. Common Personalization Specification, Visa International, Version 1.5, January 2002. Global Platform Card Specification, Global Platform, Version 2.1, June 2001. Diebold, Certificate Management, Rev. 1.4, 24 Jun 02 Diebold, Remote Key Management, Rev. 1.4, 24 Jun 02 Diebold, Triple DES Requirements FIRST Key – 91x Message Formats, Rev. 1.5, 26 Jun 02 NCR, Modifications to NDC+ to support: EPP RSA Initial Key loading ISO PIN block formats, , 17 Jul 01 RSA Laboratories, PKCS#1: RSA Cryptography Standard, v2.0, 01 Oct 98
504
Mark II Programmers Guide
[26] [27] [28] [29] [30]
[31] [32] [33]
© SafeNet, Inc.
Appendix K References – MarkII and CI
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 Visa’s 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.
505
Mark II Programmers Guide
© SafeNet, Inc.
Appendix K References – MarkII and CI
506
Mark II Programmers Guide
Appendix L Glossary
Appendix L Glossary 51-PIN
The Docutel 5100 formatted PIN Block.
ANB
The 12 digit Account Number Block. Used in the formation of the AS/ANSI PIN Block. Synonymous with PAN2.
AS-PIN
The AS/ANSI formatted PIN Block.
AWK
Acquirer Working Key (Visa).
bks
A 1 byte binary field identifying the number of 8 - byte blocks in a variable length data field which follows.
CBC
Cypher Block Chaining
CHKLEN
Number of PIN digits which are checked in the PIN verification procedure.
CVK
Card Verification Keys (Visa).
CV
Control Vector
CVV
Card Verification Value (Visa).
DATA
Data to be encrypted etc. Always a multiple of 8 bytes.
DES
Data Encryption Standard
DPK
Data Protect Key. Usually a random generated session key (KS).
ECB
Electronic Code Book
Func. Code
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.
HMAC-SHA-1
Message authentication algorithm using SHA-1 hash. Reference RFC 2104.
HSM
Hardware Security Module
IWK
Issuer Working Key (Visa).
KB
Base Key for terminals (typically used for passing encrypted keys).
KBn
Base Key Number n (n = 1 to 99)
KB-index
Refer to XX-index.
KCV
Key Check Value.
KEK
Key Exchange Key (MasterCard).
KGK
Key Generation Key
KHT
Host Transfer Key
KIR
Receive Interchange Key (used for passing encrypted keys).
KIRn
KIR Number n (n = 1 to 99).
KIRnx
A variant of KIRn (as for KMx below).
KIS
Send Interchange Key (used for passing encrypted keys).
KISn
KIS Number n (n = 1 to 99).
KISnx
A variant of KISn (as for KMx below).
KI-index
Refer to XX-index.
KK
ecPIN Verification Key
© SafeNet, Inc.
507
Mark II Programmers Guide
KKL
Key load key
KM
the domain master key (used for encrypting keys for storage on the host).
KMx
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).
KPE
PIN Encryption Key (MasterCard).
KS
Session Key. Used as a PPK, MPK or DPK.
KSn
The current session key.
KSn+1
The new session key.
KTK
Key Transport Key
KTM
Terminal Master Key.
LOGON-DATA
The result of a terminal encrypting its SEC-NO with its Base Key (KB).
MAC
Message Authentication Code.
Appendix L Glossary
Calculated as per AS2805.4 1985/ANSI X9.9. Most significant 32 bits (4 bytes) are returned. MACi
The 4 byte input to a MAC translate.
MACo
The 4 byte output from a MAC translate.
MCS
MasterCard Switch Centre.
MINPIN
The PIN length which is entered with the PVK. It represents the minimum PIN length permissible for the associated PVK.
MK
ZKA Master Key
MPK
MAC Protect Key.
OFFSET
6 bytes (up to 12 digits) of data used to Offset the 'raw' PIN to get a customer PIN.
PAC
PIN Authentication Code
PAN
The customer Primary Account Number.
PAN1
The 16 digit (8 byte) PAN encrypted to give the 'raw' PIN in the PIN verification procedure.
PAN2
The 12 digit (6 byte) PAN element used in AS/ANSI formatted PIN Blocks. Synonymous with ANB.
PFi
Input PIN format to PIN translate function.
PFo
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.
PIN
The Personal Id Number. It may be formatted in several ways depending on the function.
PINLEN
Number of digits of a customer PIN.
PK
Public Key
PK-index
Refer to XX-index.
PP-PIN
PIN/PAD formatted PIN Block.
PPK
PIN Protect Key.
PPKi
Input key to a PIN key translate function.
PPKo
Output key from a PIN key translate function.
© SafeNet, Inc.
508
Mark II Programmers Guide
Appendix L Glossary
PVK
The PIN Verification Key may be used for PIN protection as well as for PIN Verification.
PVKI
PIN Verification Key Indicator (Visa).
PVN
PIN Verification Number
PVS
PIN Verification Service (Visa).
PVV
PIN Verification Value (Visa).
RC
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.
RND
Random Number
SECURE KEY BLOCK
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.
SEC-NO
8 byte Terminal Security Number.
SEED
A national security standard of Korea (KICS Korean Information Communication Standard) since June 2002.
SEED Algorithm
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.
SEED KVC Method
The left most three bytes of the result of sixteen bytes of hexadecimal zeros encrypted with a key using SEED ECB mode.
SHP
SafeNet HSM Payment
SK
Secret Key
TK
Terminal Key
TKSI
Terminal Key Set Index. In the range 1-2. References the required 3624 keys.
TSP
Transformed Security Parameter (Visa).
VCon
Verification Constant of '0123456789ABCDEF'for a Docutel 5100 ATM.
VMMK
Visa Member Master Key.
XX-index
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).
ZCMK
Zone Control Master Key (Visa).
© SafeNet, Inc.
509
Mark II Programmers Guide
© SafeNet, Inc.
Appendix L Glossary
510
Mark II Programmers Guide
Appendix M Function List – MarkII and Card Issuance
Appendix M Function List – MarkII and Card Issuance Function
Function Code
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...................................
© SafeNet, Inc.
Page
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
511
Mark II Programmers Guide
Function
Appendix M Function List – MarkII and Card Issuance Function Code
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........................
© SafeNet, Inc.
Page
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
512
Mark II Programmers Guide
Function
Appendix M Function List – MarkII and Card Issuance Function Code
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.....................................................................
© SafeNet, Inc.
Page
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
513
Mark II Programmers Guide
Function
Appendix M Function List – MarkII and Card Issuance Function Code
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-TRANSLATE–VSDC 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........................................
© SafeNet, Inc.
Page
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
514